!CALLHTTP()

The !CALLHTTP class module allows an application to initiate HTTP style requests to a remote server.

The object is instantiated with a statement of the form

SESSION = OBJECT('!CALLHTTP')

Five HTTP request message types are supported; GET, POST, HEAD, PUT and DELETE. Each has a corresponding public function in the class that takes the request message as its only argument and returns a Boolean value indicating whether the action was successful.

The connection details are set using the following properties prior to calling the request function:

HOST	The server name or IP address.

PORT	The server port number. Defaults to 80 if not specified.

PARAMS

For a GET or HEAD action, if the request message does not contain a "?" character and the PARAMS property is not a null string, a "?" and the PARAMS property value are appended to the request message. For a POST message, if the PARAMS property is not a null string, it is sent as the message body. The PARAMS property is reset to a null string after all request messages.

EXT.HDR

Additional message header items for GET or HEAD as a dynamic array with a field for each item containing a name/value pair in the form "name: value". The header items will be transmitted in the order in which they appear in the dynamic array. Alternatively, the additional items may be set as a single level data collection in which case the order of transmission is the collating sequence of the names in the collection.

AUTH	Authentication details in the form "user:password" for a request requiring authentication.

The server and port can alternatively be specified as part of instantiating the object though actual connection does not occur until a request is submitted.

SESSION = OBJECT('!CALLHTTP', host, port)

The parameters to a GET, HEAD, POST or PUT message can be provided in three mutually exclusive manners using public functions that return a true/false status:

•As part of the request message argument

SESSION->GET('/?t0=h&t1=openqm')

•As the second argument to the GET message

SESSION->GET('/', '?t0=h&t1=openqm')

•By use of the PARAMS property

SESSION->PARAMS = 't0=h&t1=openqm'

SESSION->GET('/')

On return from a GET, HEAD or POST request, the following properties contain information returned from the server:

HEADER

The HTTP response header as a data collection with each item as a name/value pair.

HTTP.STATUS

The HTTP status code (e.g. 404 for item not found), zero if no HTTP error.

BODY	For a GET or POST request, this is the response body.

If the request returns False, the error message is available via the ERROR property.

Examples

SESSION = OBJECT('!CALLHTTP')

SESSION->HOST = 'www.openqm.com'

IF SESSION->GET('/downloads.htm') THEN

DISPLAY SESSION->BODY

END ELSE

DISPLAY SESSION->ERROR

END

The above program fragment uses the !CALLHTTP class to retrieve an item from the OpenQM web site (actually just a redirection link). If successful, the page body is displayed. If an error occurs, the error message is displayed.

SESSION = OBJECT('!CALLHTTP', 'www.openqm.com')

IF SESSION->GET('/?t0=h&t1=openqm') THEN

DISPLAY SESSION->BODY

END ELSE

DISPLAY SESSION->ERROR

END

The above program fragment uses a GET message that includes parameters. It also shows how the host name can be passed in the object instantiation rather than by explicitly setting the HOST property.

SESSION = OBJECT('!CALLHTTP', 'www.openqm.com')

SESSION->PARAMS = 't0=h&t1=openqm'

IF SESSION->GET('/') THEN

DISPLAY SESSION->BODY

END ELSE

DISPLAY SESSION->ERROR

END

The above program fragment is a variation on the preceding example, using the PARAMS property to define the parameters to be appended to the request message. Substituting POST for GET as the session method on the third line of this example would send the request as a POST message.