POST Command

Description:

This command issues an HTTP POST request for a specified resource. It is only valid within a script which has been defined as MODE HTTP.

The optional PRIMARY keyword denotes primary HTTP requests such as those referred to by the "referer" header in secondary requests. For example:

A request pulling back an HTML page from a Web server can be followed by requests pulling back some GIF images whose URLs are contained in the specified page.

The request field headers to be used in the request are obtained from the HEADER clause, appropriately modified by the WITH and WITHOUT clauses, if specified.

The HTTP POST request is asynchronous. Immediately after the request is issued, the next command in the script is processed - it does not wait for a response message to be received.

A client certificate may be specified in a request either by file or by name using the "CERTIFICATE FILE" and "CERTIFICATE NAME" clauses.

There is an optional "RESPONSE TIMER" clause, which can be used to specify that a pair of response timer records are to be written to the statistics log. The first record will be written when the request message is sent, and the second written on receipt of the response request message from the server.

The status code in the response message may be retrieved by using the optional "RETURNING CODE response_code" clause to specify the integer variable to hold the response code. The variable is loaded when the response message is received from the server. In addition, the optional "RETURNING STATUS response_status" clause may be used to return one of two values indicating whether the request succeeded or failed. There is an SCL include file "response_codes.inc" supplied with OpenSTA, that defines SCL integer constants for both the response code and response status values.

The TCP connection used for the request depends upon whether a connection has already been established for the specified Connection ID using the CONNECT command. If it has, the request uses that connection. If it has not, a TCP connection will be established to the host identified by the uri-httpversion, on port 80.

By default, if an error occurs while establishing the TCP connection or issuing the request, an error message is written in the audit log and the thread is aborted. However, if error trapping is enabled, control will be transferred to the error-handling code.

Format:

 {PRIMARY}	 	 POST [ URI | URL ] uri-httpversion {&}
 	 	 ON conid {&}
 	 	 	 HEADER http_header {&}
 	 	 {,{BINARY} BODY http_body} {&}
 	 	 {,WITH header_value} {&}
 	 	 {,WITHOUT header_field} {&}
 	 	 	 	 {,CERTIFICATE FILE cert_filename} {&}
 	 	 {,CERTIFICATE NAME cert_name} {&}
 	 	 {,RESPONSE TIMER timer_name} {&}
 	 	 {,RETURNING STATUS response_status} {&}
 	 	 {,RETURNING CODE response_code}

Parameters:

uri-httpversion

A character variable, quoted character string or character expression, containing the URI (Uniform Resource Identifier) of the resource upon which to apply the request, and the HTTP Version, separated by a single space character. The HTTP Version indicates the format of the message and the sender's capacity for understanding further HTTP communication.

conid

An integer variable, integer value or integer expression identifying the connection ID of the TCP connection on which to issue the request.

http_header

A character variable, quoted character string, character expression or character value list containing the request header fields.

http_body

A character variable, quoted character string or character expression containing the request body.

header_value

A character variable, quoted character string, character expression or character value list containing zero or more request header fields. These request header fields are added to those specified in "http_header". If a request header field appears in both "http_header" and "http_value", the field specified here overrides that specified in "http_header".

header_field

A character variable, quoted character string, character expression or character value list containing the request header field names of fields to be excluded from the request.

cert_filename

A character variable, quoted character string, character expression, containing the name of a file. The file contains a client certificate.

cert_name

A character variable, quoted character string, character expression, containing a client certificate name.

timer_name

The name of a timer declared in the Definitions section of the script.

response_status

An integer variable into which the response status of the HTTP response message is loaded when the HTTP response message is received.

response_code

An integer variable into which the response code of the HTTP response message is loaded when the HTTP response message is received.

Examples:

 POST URL "http://abc.com/~~pascal/don.gif HTTP/1.0" &
 	 ON conid &
 	 HEADER sub_header &
 	 ,WITH (" Host: abc.com", "Referer: http://abc.com/") 
 
 POST URL "http://dogbert.abebooks.com/abe/IList HTTP/1.0" on 
SEARCH_PAGE &
 	 HEADER post_header &
 	 ,WITH ("Host: dogbert.abebooks.com", &
 	 	 "Referer: http://dogbert.abebooks.com/abe/IList") &
 	 ,BODY "bu=New+Search"
 
 POST URI "http://abc.com/~pascal/don.gif HTTP/1.0" ON 2 &
 	 HEADER sub_header &
 	 ,WITH  " Host: abc.com" &
 	 ,WITHOUT "Referer Accept-Language"

See also:

Input Stream Entry Commands