com.WebServiceEngine.HandleRequest
Wait for an HTTP input request to process an operation of one of the registered SOAP or REST Web Services, or return an HttpServiceRequest object to handle a low-level request not registered at all.
Syntax
com.WebServiceEngine.HandleRequest(
timeout INTEGER,
status INTEGER )
RETURNS com.HttpServiceRequest
- timeout defines the timeout in seconds.
- status defines the variable receiving the method execution status. The
variable must be
INTEGER,SMALLINT, orBIGINT; otherwise, a runtime error is thrown.
The method returns a com.HttpServiceRequest object when the request targets a
service that is not registered, and NULL otherwise. For the meaning of each
status value, go to Table 1.
Usage
com.WebServiceEngine.HandleRequest() waits for an incoming HTTP request. Before
using this method, you register the service and start the engine the same as when using ProcessServices(). For example, call
RegisterRestService() or RegisterService() before starting the
engine.
You typically call com.WebServiceEngine.HandleRequest() inside a loop that runs
until the server stops or a fatal error occurs, and handle the status in a
CASE / END CASE block. As long as the int_flag variable is FALSE or
the execution status is valid, the condition within the loop remains
TRUE and requests are executed.
The program must declare DEFER INTERRUPT. Without that declaration, an interrupt stops the program
inside the waiting method, so neither the -4 status nor the int_flag test is
reached.
The method sets the status variable as follows:
| Situation | status | Resolution/Additional notes |
|---|---|---|
| Request for a registered SOAP or REST service | 0 | The engine processed the request, as ProcessServices() does. |
| Request for a service that is not registered | 1 | The method returns a A query-only request to the service root path, such as |
| No request within the timeout | -1 | Not an error: no request arrived in time. Call the method again to go on waiting. With a timeout of -1, the method waits without a time limit and never returns this status. |
| The GAS disconnected the program | -2 | The method raises error
-15575. Trap it with TRY/CATCH and exit the program. |
| Client closed the connection (standalone mode) | -3 | The method raises error
-15575. Trap it with TRY/CATCH. The server stays usable, so you can go on
processing requests. |
| Request that is not valid HTTP | -5 (-8 before FGLGWS 6.00.03) | Starting from FGLGWS 6.00.03, the server responds to the client with an HTTP error status (501 for an unknown method, 505 for an unsupported HTTP version, and 400 for other invalid requests) and keeps running, so the application can process later requests. In earlier versions, such a request puts the GWS HTTP server into an invalid state. Even if the application traps the exception, every later call fails with the same error. The application must then shut down cleanly and exit. |
| An XML service is reached with a method other than GET or POST | -9 | The server sends an HTTP error response to the client and keeps running. |
The web operation called com.WebServiceEngine.Flush() |
-31 | Not an error: the web operation sent its response early. Check the status that Flush() returns inside the web operation function. For details and an example, go to com.WebServiceEngine.Flush. |
No REST operation matches the request path, method, and media type (the
Accept or Content-Type header) |
-35 | Check the URL of the resource, the HTTP method and headers, and the REST web service function parameters. The server sends an HTTP error response to the client and keeps running. |
| Other errors | Other negative values | For the full list, go to Error codes of com.WebServiceEngine. |
The method reports most results in the status variable, with the Web
Services engine codes listed in HandleRequest status
values. It raises only the BDL runtime errors listed in HandleRequest exceptions
as exceptions, which you trap with TRY/CATCH. For both, the
sqlca.sqlerrm register can hold a description of the problem.
In earlier versions, with GAS 6.00.04 or later, this is not an issue in production environments: the Genero Application Server (GAS) and GWSProxy detect the ended DVM, return an HTTP error code to the client app, and any new request starts a new DVM in a clean state through GWSProxy and the pool configuration.
| Error code | Meaning | Notes / Recommendation |
|---|---|---|
| -15552 | URL charset conversion failure | Thrown when the server cannot convert UTF‑8 URLs to the fglrun locale charset. Recommendation: run the Web Services server program in UTF‑8. |
| -15575 | Connection closed | Thrown when the GAS disconnects the WS program, with a status of -2, or, in standalone mode, when the client closes the connection, with a status of -3. For what to do in each case, go to The GAS disconnected the program and Client closed the connection. |
Example: Handle HTTP requests
com.WebServiceEngine.HandleRequest() to process
incoming requests and handle status = 1 by responding to requests for unregistered
services. The TRY/CATCH block traps error -15575. The loop goes on when the client
closes the connection (status -3), and the program exits when the GAS disconnects it (status -2).Use com.WebServiceEngine.ProcessServices() for servers that handle only registered web
services. Use com.WebServiceEngine.HandleRequest() when you need to intercept and
respond to unregistered services or implement custom endpoints.
IMPORT com
IMPORT FGL myservice
MAIN
DEFINE status INTEGER
DEFINE req com.HttpServiceRequest
DEFER INTERRUPT
CALL com.WebServiceEngine.RegisterRestService("myservice", "MyService")
DISPLAY "Server started"
CALL com.WebServiceEngine.Start()
WHILE TRUE
TRY
LET req = com.WebServiceEngine.HandleRequest(-1, status)
CATCH
# Error -15575 is raised when the connection is closed:
# status is -3 when the client closed it, -2 when the GAS did
DISPLAY "Connection closed: ", sqlca.sqlerrm
END TRY
CASE status
WHEN 0
DISPLAY "Request processed."
WHEN 1
DISPLAY "Unregistered service request."
CALL req.sendResponse(400, SFMT("Unknown service (%1)", req.getUrl()))
WHEN -1
DISPLAY "Timeout reached."
WHEN -2
DISPLAY "Disconnected from application server."
EXIT PROGRAM
WHEN -3
DISPLAY "Client connection lost."
WHEN -4
DISPLAY "Server interrupted with Ctrl-C."
WHEN -5
DISPLAY "Invalid HTTP request."
WHEN -8
DISPLAY "HTTP error, the server stops."
EXIT WHILE
WHEN -9
DISPLAY "Unsupported operation."
WHEN -10
DISPLAY "Internal server error."
WHEN -23
DISPLAY "Deserialization error."
WHEN -31
DISPLAY "Flush detected."
WHEN -35
DISPLAY "No such REST operation found."
WHEN -36
DISPLAY "Missing REST parameter."
WHEN -15552
DISPLAY "UTF-8 URL conversion error."
OTHERWISE
DISPLAY "Unexpected server error ", status, " - ", sqlca.sqlerrm
EXIT WHILE
END CASE
IF int_flag <> 0 THEN
LET int_flag = 0
EXIT WHILE
END IF
END WHILE
DISPLAY "Server stopped"
END MAIN