Decode

Stabilized feature: CICS® support for Open Network Computing Remote Procedure Call (ONC RPC) is stabilized. Consider exposing and orchestrating applications as API services by using z/OS Connect Enterprise Edition or CICS web services, or by writing web applications in Java or Node.js. See also Stabilization notices and discontinued functions.

Decode is invoked by the server controller after the inbound XDR routine. Decode processing must avoid making the server controller wait for resources, because waiting prevents the server controller from dealing efficiently with other requests.

Decode has four main responsibilities:

To set data lengths for the CICS program when the lengths are not the same for all requests.
To map the input data passed from the inbound XDR routine to the input data format required by the CICS program.
To set the user ID and password that are used to control subsequent processing.
To set the name of the alias and CICS program for the request if those specified for the 4-tuple need to be changed.

Summary of parameters

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.

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 decode_	Inout decode_	Output decode_
eyecatcher function client_address client_data_ptr server_data_format program_number version_number procedure_number aup_time aup_machname_ptr aup_machlen aup_uid aup_gid aup_len aup_gids_ptr	server_program alias_transid server_input_data_len server_output_data_len	returned_data_ptr userid user_token response reason

Decode must issue an EXEC CICS GETMAIN command to allocate storage for the communication area to be passed to the CICS program. Note the following points about GETMAIN options:

You must use the SHARED option, because the storage is acquired under the server controller, but is used under the alias.
You must use the FLENGTH option.
You must use the NOSUSPEND option to prevent the server controller from being made to wait for storage, because waiting prevents the server controller from attending to incoming requests.
To prevent overwriting by user-key programs, consider using the CICSDATAKEY option in the following circumstances:
- The CICS program to be called by the alias is in another CICS system.
- The CICS program to be called by the alias is defined as EXECKEY( CICS).
- The CICS program to be called by the alias is defined as EXECKEY(USER), but the amount of data to be copied is small.

If an overlaid data format is specified, the requested length must be the greater of the output values of decode_server_input_data_len and decode_server_output_data_len plus 8 for DECODE-PASSWORD . If the data format is not overlaid, this length must be the sum of the output values of decode_server_input_data_len and decode_server_output_data_len plus 8 for DECODE-PASSWORD.

Because Decode specifies the SHARED option, the data remains available to CICS ONC RPC modules and to CICS programs. CICS ONC RPC frees the storage when it is no longer required.

Parameters

decode_alias_transid

(Input and output)

On input, the name of the alias associated with the 4-tuple for the client request.

On output, the name of the transaction to be started by the server controller to process this client request.

See How to change the alias and CICS program.

decode_aup_gid

(Input only)

The UNIX group id of the client.

decode_aup_gids_ptr

(Input only)

A pointer to an array of 32-bit integers that are the UNIX group IDs of which the client is a member.

decode_aup_len

(Input only)

The number of elements in the array of UNIX group identifiers pointed to by decode_aup_gids_ptr.

decode_aup_machlen

(Input only)

The number of characters in the machine name.

decode_aup_machname_ptr

(Input only)

A pointer to a variable-length character string representing the name of the machine on which the client is running.

decode_aup_time

(Input only)

The time at which the client created the credentials. The time is measured in seconds since 00h00m GMT on 1 January 1970.

decode_aup_uid

(Input only)

The UNIX user ID of the client.

decode_client_address

(Input only)

The 32-bit internet address of the client from which the request was received.

decode_client_data_ptr

(Input only)

A pointer to the data passed from the client. If no data exists, this pointer points to a null string.

Note: The data area pointed to by this pointer must not be changed by Decode , because CICS storage management errors are likely to occur.

decode_eyecatcher

(Input only)

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

decode_function

(Input only)

A code indicating that Decode is being called. The value is URP_DECODE.

decode_procedure_number

(Input only)

The procedure number of the 4-tuple to which the client request was made.

decode_program_number

(Input only)

The program number of the 4-tuple to which the client request was made.

decode_reason

(Output only)

A reason code; see Response and reason codes.

decode_response

(Output only)

A response code; see Response and reason codes.

decode_returned_data_ptr

(Output only)

A pointer to an area of storage allocated by the converter that contains these fields:

decode_password : the password to be used for user authentication
decode_server_input_data : the data that is to be passed to the CICS program as input.

The pointer might be null if no password exists and if no data is to be passed to the CICS program.

decode_server_data_format

(Input only)

A value that controls these operations:

How the input data pointer for Encode will be set up
How the communication area length to be checked by the connection manager is calculated

URP_CONTIGUOUS: The value of the data pointer that will be passed to Encode , or to the outbound XDR routine if Encode is not used for this 4-tuple, is the address of the CICS program communication area plus the output value of decode_server_input_data_len.
The server controller calculates a communication area length by adding the output values of decode_server_input_data_len and decode_server_output_data_len. If this length is different from the actual length of the communication area passed to the CICS program, errors might occur in the processing of client requests.
URP_OVERLAID: The value of the data pointer that will be passed to Encode , or to the outbound XDR routine if Encode is not used for this 4-tuple, is the address of the CICS program communication area.
The server controller calculates a communication area length by taking the larger of the output values specified of decode_server_input_data_len and decode_server_output_data_len. If this length is different from the length of the communication area passed to the CICS program, errors might occur in the processing of client requests.

decode_server_input_data_len

(Input and output)

On input, the output value of glength_server_input_data_len , or the value specified for Server Input Length for this 4-tuple in the connection manager.

On output, see the description of decode_server_data_format.

decode_server_output_data_len

(Input and output)

On input, the output value of glength_server_output_data_len , or the value specified for Server Output Length for this 4-tuple in the connection manager.

On output, see the description of decode_server_data_format.

decode_server_program

(Input and output)

On input, the name of the CICS program associated with the 4-tuple for the client request.

On output, the name of the CICS program to be linked to by the alias.

Use this field if you want to direct the client call to a different CICS program.

decode_userid

(Output only)

An 8-character field, the user ID known to CICS that correlates to the requesting client ID. If you store no value in this field, the user ID used in subsequent processing is the default CICS user ID.

decode_user_token

(Output only)

A fullword that can be used to pass information to the Encode function that is subsequently invoked for the client request.

decode_version_number

(Input only)

The version number of the 4-tuple to which the client request was made.

Response and reason codes

You must return one of the following values in the decode_response field:

URP_OK

The server controller checks that the communication area length does not exceed 32 767. If it does not, the alias is started using the information supplied as output. If it does, the server controller writes an exception trace entry (trace point 9FC2) and issues a message (DFHRP0516) describing the error. The alias is not started, and an svcerr_systemerr call is used to send a reply to the client.

URP_EXCEPTION

The server controller writes an exception trace entry (trace point 9FAA), and issues a message that depends on the reason code:

URP_CORRUPT_CLIENT_DATA: message DFHRP0626
An svcerr_decode call is used to send a reply to the client.
URP_AUTH_BADCRED: message DFHRP0628
An svcerr_auth call with a why-value of AUTH_BADCRED is used to send a reply to the client.
URP_AUTH_TOOWEAK: message DFHRP0629
An svcerr_auth call with a why-value of AUTH_TOOWEAK is used to send a reply to the client.
Any other value: message DFHRP0631
An svcerr_systemerr call is used to send a reply to the client.

URP_INVALID

The server controller writes an exception trace entry (trace point 9FAA) and issues a message (DFHRP0632).

An svcerr_systemerr call is used to send a reply to the client.

URP_DISASTER

The server controller writes an exception trace entry (trace point 9FAA) and issues a message (DFHRP0635).

An svcerr_systemerr call is used to send a reply to the client.

If you return any other value in decode_response , the server controller writes an exception trace entry (trace point 9FAA) and issues a message (DFHRP0625). An svcerr_systemerr call is used to send a reply to the client.

You can supply a 32-bit reason code 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 Decode , except as indicated for URP_EXCEPTION. The reason code is included in any trace that results from the invocation of Decode , and you can use it as a debugging aid.

See Numeric values of response and reason codes in CICS ONC RPC trace for the numeric values of the response and CICS-defined reason codes in trace output.