Options for requests

Options can be set, one at a time, by using the HWTHSET service. (See HWTHSET — Set HTTP connection or request options).

HWTH_OPT_URI

The Uniform Resource Identifier (URI). This supplied buffer is the target location of the target resource of the request. This option is optional for a request.

The name or resource (URN path portion) of the URI. The query and fragment portions of a URI may also be present.

Examples:

/systems/z/
/over/here?name=abc#frag1

HWTH_OPT_REQUESTMETHOD

A required 4-byte integer specifying the wanted HTTP create, read, update, and delete (CRUD) request methods. Valid values are:

HWTH_HTTP_REQUEST_POST: Use the POST method.
HWTH_HTTP_REQUEST_GET: Use the GET method.
HWTH_HTTP_REQUEST_PUT: Use the PUT method.
HWTH_HTTP_REQUEST_DELETE: Use the DELETE method.
HWTH_HTTP_REQUEST_HEAD: Use the HEAD method.
HWTH_HTTP_REQUEST_PATCH: Use the PATCH method.
HWTH_HTTP_REQUEST_OPTIONS: Use the OPTIONS method.

HWTH_OPT_HTTP_VERSION

An optional 4-byte integer specifying the wanted HTTP version. Valid values are:

HWTH_HTTP_VERSION_NONE: The toolkit chooses the default value (currently, HTTP/1.1).
HWTH_HTTP_VERSION_1_0: Use HTTP/1.0.
HWTH_HTTP_VERSION_1_1: Use HTTP/1.1.

HWTH_OPT_HTTPHEADERS

An optional 4-byte sList handle, as returned by the HWTHSLST service, which contains a linked list of HTTP request headers. These headers are sent as-is, without any modification by the toolkit. If a header is specified that the toolkit might add by default (for instance, Host or Cookie), these headers take precedence.

Note: The HTTP headers specified in the sList must not be terminated by a carriage return, line feed (CRLF), as the toolkit automatically terminates each of the headers with a CRLF.

HWTH_OPT_REQUESTBODY

This is useful mainly on an HTTP PUT, PATCH, or POST operation.

This option is mutually-exclusive with the HWTH_OPT_STREAM_SEND_EXIT option. If this option is set to a non-zero value, HWTH_OPT_STREAM_SEND_EXIT must be zero.

Non-REXX:

An optional 4-byte pointer to a single request body data buffer.

REXX:

A REXX variable name that contains the request body.

Notes:

Because the size of a request body could be substantial, the toolkit does not copy the buffer contents into the toolkit’s work area. Therefore, any manipulation of the buffer data pointed to by this address after this option has been set and before the HWTHRQST service is called could yield undesired results.
If the data to be sent on the HTTP request cannot be contained in a single contiguous buffer, consider setting the HWTH_OPT_STREAM_SEND_EXIT option and write code in this exit to stream the data to the server piece by piece.

HWTH_OPT_STREAM_SEND_EXIT

An optional 4-byte address of a program to receive control when the HWTHRQST service is invoked to identify the data to be sent to the server. This exit will be called repeatedly until the exit has indicated that all data has been sent. This option is useful when the request body size is not known or is substantial. See Streaming send exit for more information about how this (exit) routine operates.

This option is mutually-exclusive with the HWTH_OPT_REQUESTBODY option. If this option is set to a non-zero value, the HWTH_OPT_REQUESTBODY option must be set to zero.

HWTH_OPT_REQUESTBODY_USERDATA

An optional 4-byte address of a user buffer to be passed into the streaming send exit. This can serve as a communication mechanism for the application to specify that the streaming send exit is to behave in a certain manner when it receives control for this particular request. For instance, it may be used for maintaining timing information to track the efficiency of the ongoing send request.

The exit will receive this value as part of the input parameters (the progress descriptor’s user data field) the first time the streaming send exit receives control.

HWTH_OPT_TRANSLATE_REQBODY

An optional 4-byte integer value that specifies the codepage translation behavior to be performed on a request body. Valid values are:

HWTH_XLATE_REQBODY_NONE: The toolkit will not translate the request body and send it as-is to the server.
HWTH_XLATE_REQBODY_E2A: The toolkit attempts to translate the application-provided request body from EBCDIC (code page 1047) to ASCII (code page ISO8859-1).

HTTP authorization options

HWTH_OPT_HTTPAUTH

An optional 4-byte integer value that specifies the HTTP authentication level to be used on this request. Valid values are:

HWTH_HTTPAUTH_NONE: No HTTP authorization is to be built by the toolkit.
HWTH_HTTPAUTH_BASIC: Use HTTP basic client authentication. The user and password, as specified by the HWTH_OPT_USERNAME and HWTH_OPT_PASSWORD options, is sent in the clear in the prescribed basic client authentication format.
Note: This option is only recommended for an HTTPS connection.

HWTH_OPT_USERNAME

An optional buffer which contains the user name to be used as part of various authentication protocols (such as basic client authentication), used with the HWTH_OPT_HTTPAUTH and HWTH_OPT_PASSWORD options. This option is required when HWTH_OPT_HTTPAUTH is set to HWTH_HTTPAUTH_BASIC.

HWTH_OPT_PASSWORD

An optional buffer which contains the password to be used as part of various authentication protocols (such as basic client authentication), used with the HWTH_OPT_HTTPAUTH and HWTH_OPT_USERNAME options. This option is required when HWTH_OPT_HTTPAUTH is set to HWTH_HTTPAUTH_BASIC.

Response options

HWTH_OPT_RESPONSEHDR_EXIT (non-REXX)

An optional 4-byte address of a program to receive control once for each response header received by the application. See Receiving data from a server (non-REXX) for more information about how these callback (exit) routines operate.

HWTH_OPT_RESPONSEHDR_USERDATA

Non-REXX:

An optional buffer of user data to be passed into the response header exit when it receives control. This can serve as a communication mechanism for the application to specify that the response header exit is to behave in a certain manner when it receives control for the response that is associated with this request.

REXX:

An optional buffer of a REXX API variable where response headers are returned. If the variable is not a stem, the variable name is appended with the values similar to: var0, var1, var1.1,… If the variable is the name of the stem:

stem.0 contains the number of the returned headers.
stem.n, where n is a number from 1-stem.0, contains the header name.
stem.n.1 contains the header value.

HWTH_OPT_RESPONSEBODY_EXIT (non-REXX)

An optional 4-byte address of a program to receive control when the response body is received. See Receiving data from a server (non-REXX) for more information about how these callback (exit) routines operate.

This option is mutually-exclusive with the HWTH_OPT_STREAM_RECEIVE_EXIT option. If this option is set to a non-zero value, the HWTH_OPT_STREAM_RECEIVE_EXIT option must be set to zero.

HWTH_OPT_STREAM_RECEIVE_EXIT

An optional 4-byte address of a program to receive control when the HWTHRQST service is invoked to accept the response body data returned from the server. This exit will be called repeatedly until the exit is notified that all data has been received. See Response body processing options for more information about how this (exit) routine operates.

This option is mutually-exclusive with the HWTH_OPT_RESPONSEBODY_EXIT option. If this option is set to a non-zero value, the HWTH_OPT_RESPONSEBODY_EXIT option must be set to zero. For more information, see Large data body considerations.

HWTH_OPT_RESPONSEBODY_USERDATA

Non-REXX:

An optional buffer of user data to be passed into the response body exit or streaming receive exit when it receives control. This can serve as a communication mechanism for the application to specify that the exit is to behave in a certain manner when it receives control for the response associated with this request.

REXX:

The name of the REXX variable to contain the response body.

HWTH_OPT_TRANSLATE_RESPBODY

An optional 4-byte integer value that specifies the codepage translation behavior to perform on a response body. Valid values are:

HWTH_XLATE_RESPBODY_NONE: The toolkit will not translate the response body received from the server.
HWTH_XLATE_RESPBODY_A2E: The toolkit attempts to translate the response body received from the server from ASCII (code page ISO8859-1) to EBCDIC (code page 1047).

Cookie options

HWTH_OPT_COOKIE

An optional buffer containing one or more cookies to be explicitly specified in an HTTP request. The format of the value string should be name=contents, where name is the cookie name and contents is the value of the cookie. You can specify more than one cookie by separating each with a semicolon (;).

This option can work in conjunction with the cookie engine enabled (that is, with HWTH_OPT_COOKIETYPE set to HWTH_COOKIETYPE_SESSION or HWTH_COOKIETYPE_PERSIST). If enabled, any cookies specified by this option appear first in the list of cookies to be sent to the server, followed by any eligible cookies found by the cookie engine.

This option is ignored if the application has provided an explicit Cookie header as part of the HWTH_OPT_HTTPHEADERS option.