Getlengths

Getlengths is called when the definition of the 4-tuple is being registered.

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:

The size of the data that is passed to and from the CICS program
The data format (contiguous or overlaid) of the CICS program data

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

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.