Post (HttpRequest function)

Send an HTTP POST request to the server (HttpRequest class)

The Post method sends an HTTP request to an HTTP server in the HTTP Post format: the request syntax sent to the server is the same as if a METHOD="POST" HTML form was submitted from a web browser.

For more information about the HTTP POST request format, and for information about the HTTP protocol, refer to http://www.w3.org/Protocols/rfc2616/rfc2616.html.

Syntax

%httpResponse = httpRequest:Post[( [[Port=] string], [[Cancel=] number], - [CertificateCheck= certificateChecker], - [CheckKeepAliveCertificate= boolean])]

Syntax terms

%httpResponse	A reference to the HTTPResponse object instantiated and returned by this Post method.
httpRequest	An instantiated HttpRequest object that contains the request (its methods were used to create the request).
Port	A string expression that identifies a previously defined CLSOCK port. The string default is the MASTER port, if any is defined. However, if you omit string and no MASTER port is defined, the request is canceled. This is an optional and name-allowed parameter. If you specify a value, you may (but don't have to) specify the parameter name, Port (case not important).
Cancel	A numeric expression that controls whether the request is cancelled if a communication/socket error occurs. If zero, the request is not cancelled on these errors. If non-zero, the request is cancelled (though a message is still issued). If not specified, it defaults to 1 (cancel). See "Usage notes," below, for further discussion of error handling. This is an optional and name-allowed parameter. If you specify a value, you may (but don't have to) specify the parameter name, Cancel (case not important) if you want.
CertificateCheck	This optional (name required) argument invokes an SSL certificate request from the server at the time of the method call. The argument value (certificateChecker) must be a function, presumably local, with this method template: Function (String):methname Is Boolean When a connection is established, the passed function is called with the certificate (binary, ASN.1 encoded, content copied to a Longstring) as its method object. If the function returns a True, the request is completed. If the function returns a False, the connection is closed and HttpRequest returns a null. In this case, the request is canceled unless the Cancel argument setting prevents it. For a CertificateCheck function example, see Examples for the Get method.
CheckKeepAliveCertificate	This optional, name required, argument controls how frequently a specified CertificateCheck function is invoked for a an HTTP keep-alive connection. If False, the default, the certificateChecker function is called only when the physical connection is first established and not for every HTTP request on that connection. If set to True, the CertificateCheck method is called for every request, keep-alive or not.

Usage notes

• Two classes of errors can occur when Post is invoked:
  • The HTTP request completed, but the server indicated a failure of the request (an HTTP return code of 400 or greater). An example of this is the "404 not found" message issued by a web server when a non-existent document is referenced. In this class of error there was no TCP/IP communication error. For these errors, the request is never cancelled, and an HttpResponse object is always returned. The application handles these errors by checking the HTTPResponse Code, StatusLine, Message, and Success methods.
  • While attempting the HTTP request, a socket or communication error occurred. Examples of such errors include failure to connect to the server host, and a communication failure on a TCP/IP send or receive. For this class of errors, no instance of HTTPResponse is created, and a Null object is returned. In addition, $Status is set to 1, and $StatusD is set to one of these:
    • A negative return code that indicates an error in connecting to the target HTTP server. These codes are the same as those in Get method return values.
    • A positive return code indicating a communications error after the connection was made.

    The request may or may not be cancelled based on the setting of the Cancel parameter.

    Some of these errors are relatively benign (for example, inability to connect because remote partner down, timeout value exceeded), so they produce information-only messages, and they are treated as non-counting. These errors can still be detected and handled by the application (by checking for a Null result object, checking $Status and $StatusD, or both).

    Note: The distinctions between some of the return codes might or might not be meaningful, depending on the situation. For example, network problems can cause a 101 return code (indicating a timeout) or a 102 (indicating a connection closed). Connecting to a server that is using a non-HTTP protocol can result in a 100 (invalid format data received from the server) or a 101 or 102, depending on the protocol used by the server to which the request is sent: a request sent to a telnet port usually results in a timeout (return code 101), while a request sent to an SSL port without using https to indicate SSL usually results in the target server breaking the connection (return code 102).

    In general, it is risky to take action based on the distinction between the various non-zero error codes returned by this method.

  For more information about an error, you may want to issue a JANUS TRACE command with a value of 8 or 15 for the CLSOCK port that is handling your HTTP request.

• If form fields are defined with AddField, no explicit content type is set with AddHeader, and multipart form encoding is not enabled with MultiPartFormEncoding, the HTTP Helper automatically sends the following request header on Post calls:

  content-type: application/x-www-form-urlencoded

• For HTTP Version 1.1 mode only, the HTTP request header "connection: close" is automatically sent on HTTP requests to ensure that the server closes the connection with the client when the HTTP request completes. The HTTP Helper does not support persistent connections.
• The HTTP request header "Content-Length" is automatically sent on POSTs, accompanied by the value of the number of bytes in the non-header posted data.
• If the ports associated with the sockets in the HTTP request are not using SSL, and the CertificateCheck argument is specified, the certificateChecker function does not get called.

See also

• You can also send an HTTP POST using the Send method.

HttpRequest class HttpResponse class	List of HttpRequest methods List of HttpResponse methods List of HTTP Helper methods	HttpRequest methods syntax HttpResponse methods syntax
Notation conventions for methods