Encode

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 encode_ to give the name of the parameter.

Table 1. Parameters for Encode
Input encode_ Inout encode_ Output encode_

eyecatcher
entry_count
function
input_data_len
user_token

data_ptr

reason
response

Function

If the analyzer, or the caller of the CICS® business logic interface, specified a converter program name for the request, Encode is called after the CICS application program has ended. It constructs the response from the contents of the COMMAREA.

Parameters

encode_data_ptr
(Input and output)

On input, a pointer to the COMMAREA returned by the CICS application program. If no application program was called, it is a pointer to the COMMAREA created by Decode.

On output, a pointer to the buffer containing the response to be sent to the client. You must ensure that the pointer points to a valid location, or results can be unpredictable. The buffer must be doubleword aligned. The first four bytes must be a 32-bit unsigned number specifying the length of the buffer. (In COBOL, specify this as PIC 9(8) COMP.) The rest of the buffer is the response. Do not use this field as output when the converter was called from a CICS business logic interface that was called in offset mode.

encode_entry_count
(Input only)

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

encode_eyecatcher
(Input only)

A string of length 8. Its value for Encode is ">encode ".

encode_function
(Input only)

A halfword code set to the constant value URP_ENCODE, indicating that Encode is being called.

encode_input_data_len
(Input only)

The length of the COMMAREA as specified by Decode in decode_output_data_len.

encode_reason
(Output only)

A reason code—see Responses and reason codes.

encode_response
(Output only)

A response—see Responses and reason codes.

encode_user_token
(Input only)

The 64-bit token output by Decode as decode_user_token.

encode_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.

encode_volatile
(Input)
A single-character code indicating whether the data area pointed to be encode_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 encode_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 encode_response:
Symbolic value Numeric value Explanation
URP_OK 0 The response in the buffer pointed to by encode_data_ptr is sent to the client.
URP_DISASTER 12 CICS Web support
  • CICS writes an exception trace entry (trace point 455D), and issues a message (DFHWB0122). 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 (DFHWB0122), and returns a response of 501 to its caller.
URP_OK_LOOP 16 The CICS Web interface loops back to the start of the Decode function. The value stored in encode_user_token is copied to decode_user_token for the Decode converter function to use.
any other value   CICS Web support
  • CICS writes an exception trace entry (trace point 455E), and issues a message (DFHWB0122). 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 455E), issues a message (DFHWB0122), and returns a response of 501 to its caller.

You can supply a 32-bit reason code in encode_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 Encode. The reason code is output in any trace entry that results from the invocation of Encode.