Encode

Encode is called by the alias after the CICS® program ends. Encode is responsible for taking the data returned from the CICS program and changing its format so that it is suitable to be passed to the outbound XDR routine for return to the client. If no restructuring of outbound data is required, you can specify to the connection manager that Encode is not to be called. The reference to the CICS program data to be returned to the client is passed to Encode in the encode_input_data_ptr input field. This data is in CICS program format, which is a communication area structure in any CICS supported language. The CICS program data may be mapped from this format into the format required by the client, which is likely to be C, and might include pointer references, by allocating an area of storage and mapping the server data into it. Encode must set encode_output_data_ptr to point to the start of the allocated storage.

Summary of parameters

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.

To find the C type of each parameter, consult the header file DFHRPCDH provided with CICS ONC RPC. For COBOL, consult the copybook DFHRPCDO.
Input encode_ Inout encode_ Output encode_

eyecatcher
function
input_data_ptr
input_data_len
user_token
 none

output_data_ptr
output_data_len
response
reason
Encode must issue EXEC CICS GETMAIN to allocate storage for the data that it returns. Note the following points about GETMAIN options:
  • You do not need to use the SHARED option.
  • You must use the FLENGTH option.
  • If your CICS system is using storage protection, you can use the CICSDATAKEY option to prevent overwriting by user-key programs.

Parameters

encode_eyecatcher
(Input only)

A string of length 8. (The values of the eyecatchers are defined in the DFHRPUCH header file and the DFHRPUCO copybook.)

encode_function
(Input only)

A code indicating that Encode is being called. The value is URP_ENCODE.

encode_input_data_len
(Input only)
The length in bytes of the data returned from the CICS program. The value is determined as follows:
  1. It is the output value of decode_server_output_data_len , if Decode set it.
  2. If Decode did not set the value, it is the output value of glength_server_output_data_len , if Getlengths was called when the 4-tuple was registered.
  3. Otherwise, it is the value specified for Server Output Length in the connection manager when the 4-tuple was defined.
encode_input_data_ptr
(Input only)

A pointer to the data returned from the CICS program. The setting of this pointer depends on the definition of the 4-tuple in the connection manager, Getlengths processing when the 4-tuple was registered, and Decode processing for the client request.

encode_output_data_len
(Output only)

The length in bytes of the data to be passed to the outbound XDR routine.

encode_output_data_ptr
(Output only)

A pointer to an area of allocated storage that contains the data that is to be passed to the outbound XDR routine.

encode_reason
(Output only)

A reason code—see Response and reason codes.

encode_response
(Output only)

A response code—see Response and reason codes.

encode_user_token
(Input only)

A fullword containing information which was output from Decode for this client request.

Response and reason codes

You must return one of the following values in the encode_response field:
URP_OK
The alias passes the output data to the outbound XDR routine.
URP_EXCEPTION
The alias writes an exception trace entry (trace point 9F17), and issues a message (DFHRP0161). An svcerr_systemerr call is used to send a reply to the client.
URP_INVALID
The alias writes an exception trace entry (trace point 9F17), and issues a message (DFHRP0162). An svcerr_systemerr call is used to send a reply to the client.
URP_DISASTER
The alias writes an exception trace entry (trace point 9F17), and issues a message (DFHRP0169). An svcerr_systemerr call is used to send a reply to the client.

If you return any other value in encode_response , the alias writes an exception trace entry (trace point 9F17), and issues a message (DFHRP0163). An svcerr_systemerr call is used to send a reply to the client.

You can supply a 32-bit reason code in conjunction with the response value to provide further information in error cases. CICS ONC RPC does not take any action on the reason code returned by Encode . The reason code is output in any trace that results from the invocation of Encode , and you may use it as a debugging aid.

See Numeric values of response and reason codes for the numeric values of the response in trace output.