Parameter list for converter program encode function

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 program, or the caller of the CICS® business logic interface, specified a converter program name for the request, Encode is called after the user-written application program has ended. It constructs the response using the data in the COMMAREA returned by the application program.

Parameters

encode_data_ptr
(Input and output)

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

On output, if the converter program has constructed the HTTP response manually in a buffer of storage for CICS to send to the web client, this is a pointer to the buffer containing the response. 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.

If the converter program has used EXEC CICS WEB API commands to send the response instead, CICS ignores and discards any block of storage indicated by this pointer. In this situation, the pointer can be left as a pointer to the COMMAREA returned by the CICS application program; its setting does not matter.

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 function of the converter program 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 the Decode function 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 or later version parameter list.

encode_volatile
(Input)
A single-character code indicating whether the data area pointed to by 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, unless the EXEC CICS WEB API commands have already been used to send a response.
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 TCP/IP 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 CICS 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 TCP/IP 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 the Encode function. The reason code is output in any trace entry that results from the invocation of the Encode function.



dfhtlb0017.html | Timestamp icon Last updated: Monday, 5 June 2017