Parameter list for converter program decode function

If the analyzer program, URIMAP definition, or caller of the CICS® business logic interface specified a converter program name for the request, decode is called before the user-written application program that is to provide data for the request.

Summary of parameters

In the following table, the names of the parameters are given in abbreviated form; each name in the table must be prefixed with decode_ to give the name of the parameter.

Table 1. Parameters for decode
Input decode_	Inout decode_	Output decode_
client_address client_ipv6_address client_address_string client_ipv6_address_string eyecatcher entry_count function http_version_length http_version_ptr method_length method_ptr request_header_length request_header_ptr resource_length resource_ptr user_data_length user_data_ptr version volatile	data_ptr input_data_len server_program user_token	output_data_len reason response

Parameters

decode_client_address

(Input only)

A fullword 32-bit field that must be set to the binary IPv4 address of the client, if decode_client_ipv6_address is not specified. decode_client_address does not support IPv6 addresses.

If there is a non-zero value in decode_client_address, this value is used, and any value in decode_client_ipv6_address is ignored. Therefore, if you are using IPv6 addressing you must clear the contents of decode_client_address to allow the value in decode_client_ipv6_address to be used.

decode_client_ipv6_address

(Input only)

A 16-byte field that must be set if you are using IPv6 addressing, or if you are using IPv4 addressing and decode_client_address is not specified. This field supports both IPv4 and IPv6 addresses and is set to the binary IPv6 address of the client, or the IPv4 address of the client in IPv6 format. For more information on IP address format, see IP addresses.

decode_client_address_string

(Input only)

The IPv4 address of the client in dotted decimal format.

decode_client_ipv6_address_string

(Input only)

The IP address of the client in dotted decimal format for IPv4 addresses or in colon hexadecimal format for IPv6 addresses. This field can be up to 39 bytes in length.

decode_data_ptr

(Input and output)

On input, a pointer to the request from the client, which might have been modified by the analyzer program, or, if this call is a loop back from the encode converter function, a pointer to the response data of encode_data_ptr.

On output, pointer to the COMMAREA to be passed to the user-written application program. Do not modify this parameter when decode_volatile has a value of 0.

decode_entry_count

(Input only)

A count to say how many times the decode converter has been entered for the current web request.

decode_eyecatcher

(Input only)

A string of length 8. Its value for decode is >decode .

decode_function

(Input only)

A halfword code set to the constant value URP_DECODE, indicating that decode is being called.

decode_http_version_length

(Input only)

The length in bytes of the string identifying the HTTP version supported by the client. If the request is not an HTTP request, or decode_entry_count is greater than 1, the value is zero.

decode_http_version_ptr

(Input only)

A pointer to the string identifying the HTTP version supported by the client. If the analyzer modified this part of the request, the changes are visible here. If decode_http_version_length is zero, the value is undefined.

decode_input_data_len

(Input and output)

On input, the length in bytes of the request data pointed to by decode_data_ptr.

decode_method_length

(Input only)

The length in bytes of the method specified in the HTTP request. If the request is not an HTTP request, or decode_entry_count is greater than 1, the value is zero.

decode_method_ptr

(Input only)

A pointer to the method specified in the HTTP request. If the analyzer modified this part of the request, the changes are visible here. If decode_method_length is zero, the value is undefined.

decode_output_data_len

(Output only)

The length in bytes of the COMMAREA that is to be passed to the user-written application program, as indicated in the pointer decode_data_ptr. The default value if this output is not set is 32 KB.

decode_reason

(Output only)

A reason code; see Responses and reason codes.

decode_request_header_length

(Input only)

The length of the first HTTP header in the HTTP request. If the request is not an HTTP request, or decode_entry_count is greater than 1, the value is zero.

decode_request_header_ptr

(Input only)

A pointer to the first HTTP header in the HTTP request. If the analyzer program modified this part of the request, the changes are visible here. If decode_request_header_length is zero, the value is undefined.

decode_resource_length

(Input only)

The length in bytes of the path component of the URL in the HTTP request. If the request is not an HTTP request, or decode_entry_count is greater than 1, the value is zero.

decode_resource_ptr

(Input only)

A pointer to the path component of the URL in the HTTP request. If the analyzer program modified this part of the request, the changes are visible here. If decode_resource_length is zero, the value is undefined.

decode_response

(Output only)

A response; see Responses and reason codes.

decode_server_program

(Input and output)

A string of length 8. On input, the value supplied by the analyzer in wbra_server_program, or the value supplied by the caller of the CICS business logic interface. On output, the name of the user-written application program that is to service the request. The application program name must be set here or in the analyzer program; if it is not set, no application program is called.

decode_user_data_length

(Input only)

The length in bytes of the entity body for this HTTP request. If the analyzer program modified this value, the modified value is visible here. If there is no entity body in the request, the length is zero. If the request is not an HTTP request, the value is the length of the request. If decode_entry_count is greater than 1, the value is zero.

decode_user_data_ptr

(Input only)

A pointer to any entity body for this HTTP request. If the analyzer modified this part of the request, the changes are visible here. If the request has no entity body, the pointer is zero. If the request is not an HTTP request, this pointer has the same value as decode_data_ptr. If decode_entry_count is greater than 1, the value is undefined.

decode_user_token

(Input and output)

A 64-bit token. On input, the user token supplied by the analyzer as wbra_user_token, or the user token supplied by the caller of the CICS business logic interface. On output, a token that is passed to Encode as encode_user_token.

decode_version

(Input)

A halfword binary number that indicates which version of the parameter list is currently being used. It is set using the constant value decode_current_version.

decode_volatile

(Input)

A single-character code indicating whether the data area pointed to by decode_data_ptr can be replaced. Possible values are as follows:

0: The area is part of another COMMAREA and cannot be replaced.
1: The storage pointed to by decode_data_ptr can be freed and replaced by a work area of a different size.

Responses and reason codes

You must return one of the following values in decode_response:

Symbolic value	Numeric value	Explanation
URP_OK	0	Processing continues. If a CICS application program is requested, it is run. If not, processing continues with the encode function of the converter program.
URP_EXCEPTION	4	The action taken depends on the reason code: CICS web support 1 (URP_SECURITY_FAILURE). CICS writes an exception trace entry (trace point 455A), and issues a message (DFHWB0121). If the request is an HTTP request, status code 403 is sent to the web client. If the request is not an HTTP request, no response is sent, and the TCP/IP socket is closed. 2 (URP_CORRUPT_CLIENT_DATA). CICS writes an exception trace entry (trace point 4559), and issues a message (DFHWB0121). If the request is an HTTP request, status code 400 is sent to the web client. If the request is not an HTTP request, no response is sent, and the TCP/IP socket is closed. Any other value. CICS writes an exception trace entry (trace point 455B), and issues a message (DFHWB0121). If the request is an HTTP request, status code 501 is sent to the web client. If the request is not an HTTP request, no response is sent, and the TCP/IP socket is closed. CICS business logic interface 2 (URP_CORRUPT_CLIENT_DATA). The CICS business logic interface writes an exception trace entry (trace point 4556), issues a message (DFHWB0120), and returns a response of 400 to its caller. Any other value. CICS writes an exception trace entry (trace point 455B), issues a message (DFHWB0121), and returns a response of 501 to its caller. The CICS application program and the encode function of the converter program do not run.
URP_INVALID	8	The CICS application program and the encode function of the converter program do not run. CICS web support CICS writes an exception trace entry (trace point 455C), and issues a message (DFHWB0121). If the request is an HTTP request, status code 501 is sent to the web client. If the request is not an HTTP request, no response is sent, and the TCP/IP socket is closed. CICS business logic interface CICS writes an exception trace entry (trace point 455C), issues a message (DFHWB0121), and returns a response of 501 to its caller.
URP_DISASTER	12	The CICS application program and the encode function of the decoder do not run. CICS web support CICS writes an exception trace entry (trace point 455D), and issues a message (DFHWB0121). If the request is an HTTP request, status code 501 is sent to the web client. If the request is not an HTTP request, no response is sent, and the TCP/IP socket is closed. CICS business logic interface CICS writes an exception trace entry (trace point 455D), issues a message (DFHWB0121), and returns a response of 501 to its caller.
any other value		The CICS application program and the encode function of the decoder do not run. CICS web support CICS writes an exception trace entry (trace point 455E), and issues a message (DFHWB0121). If the request is an HTTP request, status code 500 is sent to the web client. If the request is not an HTTP request, no response is sent, and the TCP/IP socket is closed. CICS business logic interface CICS writes an exception trace entry (trace point 455E), issues a message (DFHWB0121), and returns a response of 501 to its caller.

You can supply a 32-bit reason code in decode_reason to provide further information in error cases. Neither CICS web support nor the CICS business logic interface takes any action on the reason code returned by decode, except as indicated on URP_EXCEPTION. The reason code is included in any trace entry that results from the invocation of decode.