Reference information for the converter functions

This section contains reference material for each of the three functions of a converter. Each function is documented in the same way:

The descriptions give the names of the program elements as they appear in C. In COBOL the names are all in uppercase, and the underscores are replaced by hyphens.

Getlengths

Summary of parameters

The names of the parameters are given in abbreviated form: each name in the table must be prefixed with glength_ 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
glength_
Inout
glength_
Output
glength_
eyecatcher
function

server_data_format
server_input_data_len
server_output_data_len
response
reason

Function

Getlengths is called when the definition of the 4-tuple is being registered, provided that the definition of the 4-tuple specified that Getlengths was to be called. It is not called to process client requests.

Getlengths is responsible for providing CICS ONC RPC with:

Parameters

glength_eyecatcher
(Input only)

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

glength_function
(Input only)

A code indicating that Getlengths is being called. The value is URP_GETLENGTHS.

glength_reason
(Output only)

A reason code--see Response and reason codes.

glength_response
(Output only)

A response code--see Response and reason codes.

glength_server_data_format
(Input and output)

On input, that value specified for Server Data Format for the 4-tuple in the connection manager.

On output, the value is to control:

  • 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

The values you can supply are as follows:

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 glength_server_input_data_len, though Decode can modify this offset.

The connection manager calculates a communication area length by adding the output values of glength_server_input_len and glength_server_output_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 connection manager calculates a communication area length by taking the larger of the output values of glength_server_input_len and glength_server_output_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.

glength_server_input_data_len
(Output only)

For the use of this field, see the description of glength_server_data_format. If you do not set a value in this field, a default value of zero is used.

glength_server_output_data_len
(Output only)

For the use of this field, see the description of glength_server_data_format. If you do not set a value in this field, a default value of zero is used.

Response and reason codes

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

URP_OK
The connection manager checks that the communication area length does not exceed 32 767. If it does not, the information is saved and used to process incoming client requests, and the 4-tuple is registered. If it does, the connection manager writes an exception trace entry (trace point 9EE6), sends a message (DFHRP1991) describing the error to the terminal from which the connection manager was started, and does not register the 4-tuple.
URP_EXCEPTION
The connection manager writes an exception trace entry (trace point 9EE5), sends a message (DFHRP1988) to the terminal from which the connection manager was started, and does not register the 4-tuple.
URP_INVALID
The connection manager writes an exception trace entry (trace point 9EE5), sends a message (DFHRP1989) to the terminal from which the connection manager was started, and does not register the 4-tuple.
URP_DISASTER
The connection manager writes an exception trace entry (trace point 9EE5), sends a message (DFHRP1990) to the terminal from which the connection manager was started, and does not register the 4-tuple.

If you return any other value in glength_response, it is treated as URP_DISASTER.

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 Getlengths. The reason code is output in any trace that results from the invocation of Getlengths, and you may use it as a debugging aid.

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

Decode

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

Function

Decode is invoked by the server controller after the inbound XDR routine. Decode processing must avoid making the server controller wait for resources, as this prevents the server controller from dealing efficiently with other requests. Decode has four main responsibilities:

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

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 Changing the alias and CICS program.

decode_aup_gid
(Input only)

The client’s UNIX group id.

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

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 client’s UNIX user ID.

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 there is no data, this pointer points to a null string.

Note:
The data area pointed to by this pointer must not be changed by Decode, or 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:

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

It may be null if there is no password and if no data is to be passed to the CICS program.

decode_server_data_format
(Input only)

A value that controls:

  • 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 actual 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.

You should 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 may 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 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 Decode, except as indicated above under URP_EXCEPTION. The reason code is output in any trace that results from the invocation of Decode, and you may use it as a debugging aid.

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

Encode

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

Function

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.

Encode must issue EXEC CICS GETMAIN to allocate storage for the data that it returns. Note the following points about GETMAIN options:

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. If neither of the above is the case, 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.

Related concepts
ONC RPC concepts
ONC RPC remote procedures and CICS programs
CICS ONC RPC user-replaceable programs
Related tasks
Write theCICS ONC RPC converter
Related reference
Reference information for the converter functions
[[ Contents Previous Page | Next Page Index ]]