Get (HttpRequest function)

<section begin=dpl_desc/><section end=dpl_desc/>

The Get method sends an HTTP request to an HTTP server in the HTTP GET format: the request syntax sent to the server is the same as if a METHOD="GET" HTML form was submitted from a web browser, or as if a URL was simply clicked.

Syntax

%httpresp = %httpreq:Get([[Port=] name] [, [Cancel=] num])

Syntax terms

%httpresp	A reference to the HTTPResponse object instantiated and returned by this Get method.
%httpreq	The previously defined and instantiated HTTPRequest object that contains the request (its methods were used to create the request).
Port=name	A string expression that identifies a previously defined CLSOCK port. The name default is the MASTER port, if any is defined. However, if you omit name and no MASTER port is defined, the request is canceled. This argument is optional, but if you specify a value, the parameter name, Port (case not important), is allowed as a qualifier, as of Sirius Mods version 7.2.
Cancel=num	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 argument is optional, but if you specify a value, the parameter name, Cancel (case not important), is allowed as a qualifier, as of Sirius Mods version 7.2.

Usage notes

• Two classes of non-application errors can occur when Get 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/communication error occurred. Examples of such errors include failure to connect to the server host, and 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 shown below 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.

  For more information about $STATUS and $STATUSD, see the Model 204 User Language Manual.

• Under Sirius Mods versions before 7.1, certain “post-oriented” actions were not allowed with an HTTP GET, and resulted in request cancellation if detected by Get function error checking:
  • An AddXML call added Post data to the request.
  • An AddLongString call added Post data to the request.
  • The MultiPartFormEncoding property set to True enabled multipart form encoding.

  Under Sirius Mods 7.1 and later, these methods are allowed before a Get method call. While unusual, passing content in a Get method is not strictly forbidden by the HTTP specification.

• For HTTP Version 1.1 mode only, the HTTP request header “connection: close” is automatically sent on GETs and POSTs to ensure that the server closes the connection with the client when the HTTP request completes. The HTTP Helper does not support persistent connections.
• For more information about the HTTP GET request format and about the HTTP protocol, refer to http://www.w3.org/Protocols/rfc2616/rfc2616.html.
• You can also send an HTTP GET using the Send method.

Get method return values

Code	Meaning
0	Communications was successful.
100	The format of the response from the server was invalid.
101	A Get operation exceeded its timeout value.
102	The connection was closed before the complete response was received.
-100	No free socket numbers for user.
-101	Remote host name or IP address missing or mismatch with CLSOCK port definition.
-102	Remote port number missing or mismatch with CLSOCK port definition.
-103	CLSOCK port not defined or not started.
-104	All ports on specified CLSOCK port are busy.
-105	Insufficient virtual storage.
-106	Maximum connections exceeded.
-107	Couldn't resolve remote host.
-108	Remote port not responding.
-109	Already have SOCKPMAX sockets open on this CLSOCK port.
-110	SSL/NOSSL setting mismatch.
-111	SSL handshake error.
-112	Access to CLSOCK port not enabled by ALLOW rule.