WEBSVC

WEBSVC

Top  Previous  Next

 

The WEBSVC command listens for incoming simple web services connections.

 

 

Format

 

WEBSVC subr {MAX n}  {POOL name}  {PORT portno}

 

where

 

subrSpecifies the name of the subroutine to be called to process the incoming requests.

 

MAX nSets the maximum number of simultaneous child processes. Defaults to 10 if omitted.

 

POOL nameSpecifies the connection pool name to be used for the child processes.

 

PORT portnoIs the port number on which to listen for incoming connections. Defaults to 80 if omitted. Linux systems only allow processes running as root to listen on port numbers less than 1024.

 

This command is normally only present in the VOC of the QMSYS account but may be copied to other accounts if needed.

 

 

The WEBSVC command, typically used in a phantom process, listens for incoming web services connections on the specified port number. When a connection arrives, a phantom process is started to service this request. If the limit on simultaneous connections has been reached, the listener process pauses briefly until some other connection terminates.

 

The phantom process parses the incoming web request, separating the header from the request body, and calls the catalogued processing subroutine specified in the command line. This subroutine should be declared as

SUBROUTINE name(IP.ADDR,           ;* Origin

               ACTION,            ;* Request type (GET, POST, etc)

               URI,               ;* URI
               RQST.HEADER,       ;* Request header as a data collection...

               RQST.BODY,         ;* ...and associated request body

               RESPONSE.HEADER,   ;* Response header...
               RESPONSE.BODY,     ;* ...and associated response body

               CLOSE.CONNECTION)  ;* Close connection after sending response?

 

As an example of how the incoming request is processed, consider a simple request submitted via a browser:

http://mysite.com/a/b?x&y&z

 

ACTIONis the HTTP request type (GET, POST, etc).

 

URIis the URI string "/a/b?x&y&z"

 

RQST.HEADERis a data collection with an element for each of the name/value pairs in the HTTP request such as

ACCEPT text/html, application/xhtml+xml, */*

ACCEPT-ENCODING gzip, deflate

ACCEPT-LANGUAGE en-GB

CONNECTION Keep-Alive

HOST myservice.com

USER-AGENT Mozilla/5.0

 

RQST.BODY would be a null string in this example.

 

The subroutine processes this data and constructs the response body as a field mark delimited dynamic array. For example,

 

RESPONSE.BODY = '<!DOCTYPE html>'

RESPONSE.BODY<-1> ='<html>'

RESPONSE.BODY<-1> = '<p>Hello ' : IP.ADDR : '</p>'

RESPONSE.BODY<-1> ='</html>'

 

The default values for RESPONSE.HEADER and CLOSE.CONNECTION if not updated by the user supplied subroutine are equivalent to:

 

RESPONSE.HEADER = 'HTTP/1.1 200 OK'

RESPONSE.HEADER<-1> = 'Content-Type: text/html'

RESPONSE.HEADER<-1> = 'Server: QM/':change(system(SYS$VERSION), '-', '.')

RESPONSE.HEADER<-1> = 'Date: ' : OCONV(EPOCH(), 'E4WADMYTSZL[A3,", ",A3]')

RESPONSE.HEADER<-1> = 'Connection: close'

 

CLOSE.CONNECTION = @TRUE

 

If the POOL command line parameter has been used, the phantom process will go into an idle wait state until either a new connection arrives or the pool timeout is reached. Use of connection pools can improve performance as the process can potentially omit initialisation tasks such as opening files.