Decode

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_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
volatile

data_ptr
input_data_len
server_program
user_token

output_data_len
reason
response

Function

If the analyzer, or the caller of the CICS® business logic interface, specified a converter name for the request, Decode is called before the CICS application program that is to service the request.

Parameters

decode_client_address
(Input only)

The 32-bit IP address of the client.

decode_client_address_string
(Input only)

The IP address of the client in dotted decimal format.

decode_data_ptr
(Input and output)

On input, a pointer to the request from the client (as modified by the analyzer) 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 CICS 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, this is the length in bytes of the request data pointed to by decode_data_ptr.

The value to be used for the DATALENGTH option of a LINK command for the CICS application program. The default value if this output is not set is 32K.

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 value to be used for the LENGTH option of the LINK command for the CICS application program. The default value if this output is not set is 32K.

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 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 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 CICS application program that is to service the request. The application program name must be set here or in the analyzer, or no application program will be called.

decode_user_data_length
(Input only)

The length in bytes of the entity body for this HTTP request. If the analyzer modified this value, it 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 there is no entity body in the request, 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 single-character parameter list version identifier, which changes whenever the layout of the parameter list changes. Its value can be either binary zero (X'00'), indicating a pre-CICS TS 1.3 version parameter list, or a character zero (X'F0'), indicating a CICS TS 1.3 version parameter list.

decode_volatile
(Input)
A single-character code indicating whether the data area pointed to be decode_data_ptr can be replaced. Possible values are:
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 different size work area.

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 executed. If not, processing continues with the decoder's encode function.
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 Communications Server 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 for MVS™ 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 Communications Server 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 is not executed, nor is the encode function of the decoder.
URP_INVALID 8 The CICS application program is not executed, nor is the encode function of the decoder.
  • 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 Communications Server 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 is not executed, nor is the encode function of the decoder.
  • 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 Communications Server 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 is not executed, nor is the encode function of the decoder.
  • 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 Communications Server 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 may 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 above under URP_EXCEPTION. The reason code is output in any trace entry that results from the invocation of Decode.