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.
| Input encode_ | Inout encode_ | Output encode_ |
|---|---|---|
eyecatcher |
data_ptr |
reason |
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
| 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 business logic interface
|
| 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 business logic interface
|
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.