xaWebHelp

Method WEngine :Listen
Parameters

nSecsTimeout

Timeout seconds for the CGI to exit the dormant state. By default WEngine:nSessionTTL.

nPort

TCP/IP port to use. If the port is busy, xaWeb will suggest an alternative. Default is 0. A value of 0 indicates automatic port assignment. The return value indicates the exact port assigned.

lDebug

If true, a complete log of all operations is created in a file named xaWeb.log, which will be located in the application directory. By default false.
Return value
nPort
Returns the port that has actually been allocated. This port will remain unchanged for all CGIs executed within the same session. Values less than or equal to zero indicate an assignment error.

This method allows you to put the CGI in listening mode through a specific TCP/IP port so that it doesn't actually exit execution until the timeout specified as the first parameter occurs. This method can be very useful if you want to use the CGI as an ultra-fast Web service, maintaining connections, for example, with a SQL server.

Every time a request is made to the CGI via sockets, the timeout counter is reset to zero. Therefore, if there is activity, the CGI will remain active until it stops requesting. By default, the timeout is set to the same time as the WEngine:nSessionTTL.

Socket queries must be made with the SocketRequest function. The code for this function can be extracted from xaWeb and incorporated directly into your own Harbour projects. However, you will need to link Harbour's socket libraries.

Text sent through the SocketRequest() function will be received by the CGI and sent to the WDoc:SocketRequest method. This method will need to be overloaded by your application to process it correctly for your needs.

Each active session supports its own socket, so it's highly recommended that port assignment be automatic. To do this, you should avoid passing the port parameter or give it a value of zero. The method returns the chosen port. Each time you run this method, xaWeb will check if a port already exists for the active session and if it's working correctly. If so, it will simply return the port number. Otherwise, the method code will be fully processed, and a new connection port will be requested for that session.

Before putting the CGI into listening mode, you should check if there is already a CGI listening for the active session. This is done by using the nListening property.

Note that when you put the CGI into dormant mode, you actually launch a new CGI that only performs that operation, and therefore none of the current CGI that fired it remains in scope.

This method requires using Harbour's multithreading libraries. To do this, you'll need to replace the hbvm library with the hbvmmt library.

Previous Next