!CALLHTTP()

!CALLHTTP()

Top  Previous  Next

 

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:

HOSTThe server name or IP address.
PORTThe server port number. Defaults to 80 if not specified.
PARAMSFor 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.HDRAdditional 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.
AUTHAuthentication 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:

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:

HEADERThe HTTP response header as a data collection with each item as a name/value pair.
BODYFor 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.

 

 

See also:

Data collections, Simple Web Services