%HTTP_SERVER_RECEIVE

Receive a request from a client

status = %HTTP_SERVER_RECEIVE(instance_id, uri, method, [timeout], handle, length, error, 
&        [headers], [log_file][, fork])

Return value

status

Returns 0 if successful or an error number if unsuccessful.

Arguments

instance_id

The ID of the created instance of a Synergy HTTP or HTTPS server, returned by %HTTP_SERVER_CREATE. (n)

uri

Returned with the URI (Uniform Resource Indicator) of the requested document. (a)

method

Returned with the HTTP method from the client (for example, GET, POST, or HEAD). (a)

timeout

(optional) The number of seconds to wait for a request from the client before an idle TCP/IP socket time-out occurs. The default is 0, which specifies wait forever. (n)

handle

Returned with the static memory handle of the requested document. (D_HANDLE)

length

Returned with the length of the requested document. (n)

error

Returned with an error message if status is nonzero. Otherwise, it is blank. (a)

headers

(optional) Returned with an array of one or more HTTP header strings. Each string has the form header_name[:value]. ([*]a)

log_file

(optional) The name and location of a log file to log HTTP packet contents. (a)

fork

(optional) One of the following values (UNIX only):

0 = No child is created.

1 = Create a child. The parent continues to accept new requests until the timeout period expires.

2 = Create a child. The parent continues to accept new requests and never returns, regardless of any timeout value.

See the Discussion for additional information.

Discussion

%HTTP_SERVER_RECEIVE waits for a request from an HTTP or HTTPS client and returns the uri, method, handle, and length of the document requested. Call %HTTP_SERVER_RECEIVE in a loop with %HTTP_SERVER_SEND to retrieve and handle client requests. Then format the responses and send them back to the client. If the call fails, an error number is returned, and an error message is returned in the error argument. Otherwise, error is blank.

See Using the HTTP document transport API for details about the uri syntax, including information on the automatic escaping of special characters.

Method can be any valid HTTP method. The two most commonly used methods are GET (which requests a document from a server) and POST (which sends a document to a server).

If handle and length have a value of 0, %HTTP_SERVER_RECEIVE allocates a memory handle for you. It’s your responsibility to free any memory allocated by this routine.

The headers argument enables a Synergy HTTP or HTTPS server to receive HTTP header values. Make sure the array of strings you create is large enough to accept all possible headers. If it’s too small, any received headers that don’t fit will not be put in the array.

Passing a log_file causes the HTTP request packet to be logged to the specified file. This logging feature is available primarily for debugging purposes. Logs of a request packet include the HTTP method (in this case, RECEIVE), the URI, the HTTP version, all HTTP headers, and the body of the HTTP packet. Log entries are always appended to an existing log file. If the log file does not exist, it is created. A log file can only be created on a local drive; remote drives are not supported.

The fork argument is only available on UNIX. You should not use fork if any SQL Connection remote sessions are open or if you have any remote xfServer files.

Using the timeout parameter with a fork value of 1 enables you to shut down the accept capability if necessary. If fork is passed with a value of 1, the parent will go back to accept the next connection request. When the child finishes the request, it should stop. When %HTTP_SERVER_RECEIVE returns, fork is returned with the value of the UNIX fork(2) routine that was used to create the child process. If the returned fork value is 0, the child process is processing the request. If the returned fork value is 1, the accept returned and the parent is running, taking the timeout parameter into account.

If fork is passed with a value of 2, the main accept loop will never time out but will still pass the timeout value to the rest of the HTTP operations. If the returned fork value is 0, the child process is processing the request. Otherwise, the routine never returns (except from an error).

Regardless of the fork value that is passed, a return fork value of -1 means a system error has occurred. You can use %SYSERR to capture the error and then store it in a local variable for later processing. (See %SYSERR for more information.)

%HTTP_SERVER_RECEIVE creates an identical copy of the process, except all channels opened by the original have been closed in the child. Therefore, you must reopen any files needed by the child.

If the Synergy server quits, all of the child processes will quit as well.

For an HTTPS server, client authentication occurs when a request is received by %HTTP_SERVER_RECEIVE if CA_file was passed to %HTTP_SERVER_CREATE. If an authentication error occurs, %HTTP_SERVER_RECEIVE returns the error and terminates the connection.

Examples

See %HTTP_SERVER_CREATE Examples.