HTTP

9.4D

 

The HTTP instruction provides direct access to web servers using HTTP communications. The instruction uses the following format:

 

 

[label]

HTTP

{HostName},{ResourcePath}[,{options}]

 

Where:

label

Optional. A Program Execution Label.

HostName

Required. A previously defined Character String Variable or literal that contains the host name or IP address of a web server that is being accessed.

ResourcePath

Required. A previously defined Character String Variable or literal that contains the resource path and Optional query string data that is appended to the {HostName} to formulate a HTTP command that is sent to a web server.

options

Optional. One or more of the options described below.

Flags Affected: EOS, OVER, ZERO

Note the following:

  1. The default HTTP command is sent as a 'GET' using the {HostName} plus the {ResourcePath} string.

  2. If the *POSTMESSAGE option is used, the HTTP command is sent as a 'POST' with the *POSTMESSAGE data appended to the {ResourcePath} string.

  3. The {options} that may follow the required operands are:

    4.  

    Option

    Direction

    Specifies...

    *ERROR={svar}

    Output

    a Character String Variable that receives any error information returned by the HTTP instruction. If this parameter is not specified, error information is stored in the S$ERROR$ variable. The EOS flag is set if the error information has to be truncated when it is stored into the {svar} variable.

    *FILENAME={svarlit}

    Input

    a Character String Variable or a string literal that specifies a fully qualified path and file name of a file where the result data is to be stored. If the $HTTP_FLAG_RAW_RESULT is used in the *FLAGS= options, the entire response is stored into the file specified. If the $HTTP_FLAG_RAW_RESULT is not used, the header is stored in the *RESULT= field and the body is stored in the specified file. If the SUNDM keyword is used, the fully qualified path and file name must exist as the system where the Data Manager is executing. (9.5B)

    *FLAGS={dnumnvar}

    Input

    a numeric value that is a bitmask to control specialized behaviors for the execution of the HTTP instruction. The following bitmask definitions can be used:

    Generate/bullet1.gif    0x1 - $HTTP_FLAG_RAWCOMMAND - The HTTP instruction executes in a raw command mode. In this case, the application must specify the {ResourcePath} with the appropriate GET, HEAD, or POST command plus the appropriate ResourcePath data required to access a web server.

    If this flag state is not used, the default action by the HTTP instruction is to prepend the appropriate HTTP command as GET, HEAD, or POST to the ResourcePath data.

    If this bitmask state is used and the end-user specifying the HTTP/1.1 protocol, the HTTP command should specify the "Connection: close" request-header field in the request message. This is needed because the HTTP instruction does not support a persistent socket connection.

    The $HTTP_FLAG_RAWCOMMAND mode is ignored/not used in a HTTP instruction the includes either one of the following:

    1) The *POSTMESSAGE keyword is used.

    2) The $HTTP_FLAG_JUSTHEADER flags option is being used. 

    Generate/bullet1.gif    0x2 - $HTTP_FLAG_NOHEADER - When this bit is set, the HTTP instruction does not return any HTTP header information for the data retrieved from a web server.

    Generate/bullet1.gif    0x4 - $HTTP_FLAG_JUSTHEADER - When this bit is set, the HTTP instruction uses the HTTP HEAD command to only retrieve the HTTP header information from a web server.

    If HTTP *FLAGS options include both the $HTTP_FLAG_RAWCOMMAND and $HTTP_FLAG_JUSTHEADER, the $HTTP_FLAG_JUSTHEADER takes precedence and the $HTTP_FLAG_RAWCOMMAND bit mask option is ignored and not used. 

    Generate/bullet1.gif    0x8 - $HTTP_FLAG_SSL - When this bit is set, the HTTP instruction executes using the SSL (Secure Sockets Layer) to access a web server using a secured communications connection. See information for OpenSSL libraries using this link: (http://www.openssl.org/)

    Generate/bullet1.gif    0x10 - $HTTP_FLAG_HTTP11 - When this bit is set, the HTTP instruction includes the host request-header and the connection request-header fields in the HTTP request message. The host request-header field must be included in all HTTP/1.1 request messages. The connection request-header field is included because the HTTP instruction does not support a persistent socket connection. This bit is only used when the 0x1 bit mask (i.e., Raw data mode bit) is not used.

    Generate/bullet1.gif    0x20 - $HTTP_FLAG_RAW_RESULT -The entire unedited response received for a HTTP request is returned in the result. In this case, the PL/B runtime does not process nor interpret any of the Web Server response. (9.5B)

    Generate/bullet1.gif    0x40 - $HTTP_FLAG_RAWBINARY - If both the $HTTP_FLAG_RAWCOMMAND and the $HTTP_FLAG_RAWBINARY bit values are set for the *FLAGS bit mask value, all of the data found in the {resourcePath} parameter is sent to the Web Server as binary data. This means that any NULL (binary zero) characters are also sent. This bit value allows binary data to be sent to a Web Server.

    Generate/bullet1.gif    0x80 - $HTTP_FLAG_FIRST_RAW_RESULT - The first received unedited response for a HTTP request is returned in the result. In this case, the PL/B runtime does not process nor interpret any of the Server response. Note, this bit mask value should only be used if the user application knows that the response contains all of the raw data in one receive operation with a size less than 1024 bytes. (9.7C)

    Generate/bullet1.gif    0x100 - $HTTP_FLAG_NO_U66 - When this *FLAGS bit mask value is set, the HTTP instruction does not generate a U66 error. In this case, the HTTP instruction sets an error value of '23' that indicates a problem has occurred loading SSL libraries. (10.3)

    Generate/bullet1.gif    0x200 - $HTTP_FLAG_USESUNSSL ( Windows PL/B runtimes ONLY ) - Setting the $HTTP_FLAG_USESUNSSL bit mask value causes the HTTP instruction to first attempt to load the OpenSSL DLLs ( ssleay32.dll and libeay32.dll ) if they exist in the 'openssl' sub-directory located in the directory specified by the PLB_SYSTEM keyword found in the PL/B runtime INI file. Note, this flag option is obsolete for release 10.7 and newer releases.

     

    Example:

     

    PLB_SYSTEM=c:\Sunbelt\plbwin.103A\code

     

    The OpenSSL DLLs ( ssleay32.dll and libeay32.dll ) must exist in the following directory to be used.

     

    c:\Sunbelt\plbwin.10?\code\openssl

     

    Generate/bullet1.gif    0x400 - $HTTP_FLAG_TLSV1 - Use the SSL TLSv1.0 protocol which is an upgraded version of SSLv3.

    Generate/bullet1.gif    0x800 - $HTTP_FLAG_TLSV11 - Use the SSL TLSv1.1 protocol .

    Generate/bullet1.gif    0x1000 - $HTTP_FLAG_TLSV12 - Use the SSL TLSv1.2 protocol.

    Generate/bullet1.gif    0x2000 - $HTTP_FLAG_USESSLDEFS - Use SSL defaults as determined from the OPENSSL command.

    Generate/bullet1.gif    0x4000 - $HTTP_FLAG_USE_IPV6 (10.7) - This flags value is only used for Windows PL/B runtimes. Setting this flag causes the HTTP instruction to expect an address or host name to be processed for an IPV6 format. In this case, the following are valid IPV6 addresses:

     

    Examples of possible IPV6 {hostname} string values:

     

    "::1"

    "fe80::1cab:8479:b8ee:4d1"

    "localipv6-test.home"

    *PORT={dnumnvar}

    Input

    the port number used when logging on to the web server. If this parameter is not specified, the default port number of eighty (80) is used when the SSL mode is not specified and the port number of (443) is used when the SSL mode is specified.

    *POSTMESSAGE={svarlit}

    Input

    a Character String Variable or a string literal that contains data that is sent using a HTTP POST command.

    If the *POSTMESSAGE is used in a HTTP instruction with the $HTTP_FLAG_JUSTHEADER and/or $HTTP_FLAG_RAWCOMMAND bit mask {options} set, the *POSTMESSAGE operation takes precedence and these bit mask values are ignored. 

    *HTTPAUTH={svarlit}

    input

    the 'username' and 'password' packed into the {svarlit} with a colon (:) delimiter as 'username:password'. The HTTPAUTH data is put into the HTTP message as input provided as a HTTP Basic Authentication record. Note that the HTTPAUTH keyword ONLY takes affect and sends an authorization header field when the {flags} bit definition specifies the HTTP/1.1 protocol type and raw mode is not being used. (9.6)

    *HTTPLENGTH={nvar}

    Output

    a Numeric Variable that returns the value as specified by the 'Content-Length:' field that is returned in the HTTP header.

      If the value to be stored in the {nvar} is too large and must be truncated, the OVER flag is set. This option is ignored when the *FLAGS $HTTP_FLAG_RAW_RESULT is used.

    *HTTPRESULT={svar}

    Output

    a Character String Variable that only receives the result that was sent by the web server as a response to the HTTP command. A normal expected result may be a string '200 OK'. The EOS flag is set if the data stored into the {svar} is too large and it has to be truncated. This option is ignored when the *FLAGS $HTTP_FLAG_RAW_RESULT is used.

    *HTTPTYPE={svar}

    Output

    a Character String Variable that returns the 'Content-Type:' field that is returned in the HTTP header that was received from the Web Server. As an example, the 'Content-Type:' field may return the string as 'text/html'. The EOS flag is set if the data stored into the {svar} is too large and it has to be truncated.

    *MAXDATASIZE={dnumnvar}

    Input

    The value specified by this keyword identifies the maximum amount of data to be received before terminating the HTTP transaction. If this keyword option is not used, the default has no maximum when the *FILENAME= is used. If the *FILENAME= is not being used, the default is the physical size of the variable specified by the *RESULT= option. (9.5B)

    *MAXTIMEOUT={dnumnvar}

    Input

    a value that identifies the maximum time to spend processing the HTTP request. This keyword allows a user to put an absolute time limit to process a complete HTTP request. If this keyword is not used, there is no time limit on completing a HTTP request. This timeout value only starts and takes affect after the socket connection has been established. (9.5B)

    *RESULT={svar}

    Output

    a Character String Variable that returns data received from the web server that is being accessed. The data put into this variable may be filtered as controlled by the *FLAGS bitmask value. The EOS flag is set if the data stored into the {svar} is too large and it has to be truncated.

    *RESULTLENGTH={nvar}

    Output

    a Numeric Variable that returns the total number of characters that have been returned from the web server that is being accessed. This value includes all of the characters received including the header data as well as the data count for the body. If the value to be stored in the {nvar} is too large and must be truncated, the OVER flag is set.

    *SUNDM={svarlit}

    Input

    a Character String Variable or a string literal that specifies the DNS host name or IP address and port number for a Sunbelt Data Manager. When this keyword is specified, the HTTP instruction logs onto a Data Manager and the HTTP command is executed by the Data Manager.

    Examples:

    "127.0.0.1"

    "127.0.0.1:3934"

    *TIMEOUT={dnumnvar}

    Input

    the timeout value used when communicating with the web server. If this parameter is not specified, the default timeout of five (5) seconds is used. There are no restrictions placed on the value specified. This timeout value only starts and takes affect after the socket connection has been established.

    *TRACE={svarlit}

    Output

    the file name created to store the HTTP data sent and the first data buffer received as a response from the connected server. The trace logs a maximum size of 1024 for each data buffer processed (i.e., a data buffer sent and a separate data buffer received). Note that a trace file is overwritten for a each HTTP instruction.

    *TRACEAPPEND={svarlit}

    Output

    that trace data is to be appended to an existing trace log file. If the trace log file does not exist, it is created. The TRACE and TRACEAPPEND options cannot be specified in the same HTTP instruction. The same data processing as described by the *TRACE are applied to the *TRACEAPPEND keyword.

     

     

  4. When the *SUNDM keyword is being used, parameters for the HTTP instruction support two tags specified as '<e>' or '<f>'. The '<e>' and '<f>' data for a tag replaces the data of a HostName, ResourcePath, or *PostMessage parameter in the HTTP instruction. The '<e>' tag is specifies an environment variable name that exists in the SUNDM CFG file. The data string for the specified environment variable is substituted into a HTTP instruction parameter that contains the tag. The '<f>' tag specifies the name for a file located at the Data Manager that contains the data string to be substituted into the parameter that contains this tag. The support for these embedded tags have been implemented to maximize the ability to configure the HTTP operations when using the Data Manager. When the '<e>' or '<f>' tags are used, they must be specified as the first data in keyword data string.

  5. The '<e>' tag must be followed by a keyname that is appended to a prefix named 'HTTP_'. A full keyword named 'HTTP_keyname' finds the keyword in the SUNDM CFG file. The data specified by the 'HTTP_keyname' keyword is retrieved and used for the given HTTP parameter that includes the '<e>keyname' tag. The 'HTTP_keyname' keywords must be placed in the 'environment' section of the SUNDM CFG file.

  6. The '<f>' tag must be followed by a name that identifies a file whose data is to be read and substituted for the HTTP parameter that includes the '<f>filename' tag. The filename supports the normal PLB $Macro and Datapoint style name formats the same as a PLB OPEN instruction. The file identified by the filename must be located at the Data Manager server.

  7. The '<e>' or '<f>' tag substitution can only be used for the HostName, ResourcePath, and the *PostMessage parameters in the HTTP instruction.

    8. Example of '<e>' and '<f>' tag substitution for HTTP:

     

    [Environment] ( SUNDM CFG file )

    HTTP_Movies=movies.yahoo.com

    HTTP_All=GET /showtimes-tickets/all/?location=Tyler+TX

     

    Sample HTTP using <e> tag substitution:

     

    HTTP "<e>Movies":

    "<e>All":

    *Result=D1000

     

    In this example, the '<e>' tags are being used to retrieve the HostName and ResourcePath parameters from the SUNDM CFG file.

     

  8. The ZERO flag is set when the HTTP instruction has successfully been completed.

  9. The OVER flag is set if any of the options that returns a numeric value has truncated the numeric data value because a numeric variable was too small.

  10. When the ZERO flag is cleared to indicate an error for the execution of the HTTP instruction, an error code is stored in the variable specified by the *ERROR keyword. Otherwise, the error code is stored in the S$ERROR$ runtime variable. The following error codes can occur:

    11.  

    Code

    Error

    1

    Insufficient memory to execute HTTP instruction.

    2

    Unable to perform initialization required for socket operations

    3

    Unable to open a socket.

    6

    Unable to resolve hostname into an IP address. Bad host name specified.

    7

    Unable to create a socket connection.

    8

    Unable to logon to a SunDM Data Manager.

    9

    The Data Manager that is being accessed does not provide HTTP support.

    10

    There was a timeout that exceeded 180 seconds when the HTTP instruction was being executed Data Manager.

    11

    An invalid message was received from the Data manager as a response when the HTTP instruction was being executed a the Data Manager.

    12

    The <e> or <f> parameter substitution failed for the HTTP HostName parameter.

    13

    The <e> or <f> parameter substitution failed for the HTTP ResourcePath parameter.

    14

    The <e> or <f> parameter substitution failed for the HTTP *PostMessage parameter.

    15

    A socket error occurred while sending a HTTP request to a web server.

    16

    A socket error occurred in a select operation while waiting to receive a response from a web server.

    17

    A timeout occurred while waiting to receive a response from a web server.

    18

    A receive error was detected when executing a select operation while waiting to receive a response from a web server.

    19

    A socket error occurred when a receive operation as executed as a response from a web server was being processed.

    20

    A socket operation was lost while receiving a response from a web server.

    21

    A selection operation failed while waiting to receive a response from a web server. This error was not a socket error.

    22

    It is invalid to execute a HTTP instruction with a HostName parameter that has a zero length.

    23

    Unable to locate/open the 'OpenSSL library required to provide SSL support. By default, this error causes a U66 error to occur when this error value is generated. However, if the $HTTP_FLAG_NO_U66 ( 0x100 ) is set in the *FLAGS bit mask, the U166 is not generated and the error value of '23' is returned in S$ERROR$. In either case, the user must install the SSL support libraries to prevent SSL library load/usage error.

    24

    Unable to connect a SSL socket.

    25

    Unable to create the file specified by the *FILENAME parameter.

    26

    The <e> or <f> parameter substitution failed for the HTTP *FILENAME parameter.

    27

    The <e> or <f> parameter substitution failed for the HTTP *HTTPAUTH parameter.

    28

    The web server response does not contain a HTTP header. All responses from a web server must contain a HTTP header when the *FLAGS $HTTP_FLAG_RAW_RESULT bit is not being used. If the *FLAGS $HTTP_FLAG_RAW_RESULT is being used, this error does not occur and the HTTP instruction returns the response data exactly as received from the web server.

    29

    Unable to create or open the trace file.

    30

    Invalid trace file usage.

    31

    The receive buffer for the HTTP result being received using 'chunked' blocks has overflowed. Report this error to Sunbelt Support and send any trace logs and\or other information regarding this error event for evaluation.

 

 

See Also: Example Code, COMWRITE List Controls, COMREAD, Communication I/O Instructions

 


PL/B Language Reference COMWRITE