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.
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 |
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:
A string of length 8. (The values of the eyecatchers are defined in the DFHRPUCH header file and the DFHRPUCO copybook.)
A code indicating that Getlengths is being called. The value is URP_GETLENGTHS.
A reason code--see Response and reason codes.
A response code--see Response and reason codes.
On input, that value specified for Server Data Format for the 4-tuple in the connection manager.
On output, the value is to control:
The values you can supply are as follows:
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.
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.
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.
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.
You must return one of the following values in the glength_response field:
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.
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 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.
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.
The client’s UNIX group id.
A pointer to an array of 32-bit integers that are the UNIX group ids of which the client is a member.
The number of elements in the array of UNIX group identifiers pointed to by decode_aup_gids_ptr.
The number of characters in the machine name.
A pointer to a variable length character string representing the name of the machine on which the client is executing.
The time at which the client created the credentials. The time is measured in seconds since 00h00m GMT on 1 January 1970.
The client’s UNIX user ID.
The 32-bit internet address of the client from which the request was received.
A pointer to the data passed from the client. If there is no data, this pointer points to a null string.
A string of length 8. (The values of the eyecatchers are defined in the DFHRPUCH header file and the DFHRPUCO copybook.)
A code indicating that Decode is being called. The value is URP_DECODE.
The procedure number of the 4-tuple to which the client request was made.
The program number of the 4-tuple to which the client request was made.
A reason code--see Response and reason codes.
A response code--see Response and reason codes.
A pointer to an area of storage allocated by the converter that contains:
It may be null if there is no password and if no data is to be passed to the CICS program.
A value that controls:
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.
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.
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.
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.
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.
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.
A fullword that may be used to pass information to the Encode function that is subsequently invoked for the client request.
The version number of the 4-tuple to which the client request was made.
You must return one of the following values in the decode_response field:
An svcerr_decode call is used to send a reply to the client.
An svcerr_auth call with a why-value of AUTH_BADCRED is used to send a reply to the client.
An svcerr_auth call with a why-value of AUTH_TOOWEAK is used to send a reply to the client.
An svcerr_systemerr call is used to send a reply to the client.
An svcerr_systemerr call is used to send a reply to the client.
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.
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 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:
A string of length 8. (The values of the eyecatchers are defined in the DFHRPUCH header file and the DFHRPUCO copybook.)
A code indicating that Encode is being called. The value is URP_ENCODE.
The length in bytes of the data returned from the CICS program. The value is determined as follows:
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.
The length in bytes of the data to be passed to the outbound XDR routine.
A pointer to an area of allocated storage that contains the data that is to be passed to the outbound XDR routine.
A reason code--see Response and reason codes.
A response code--see Response and reason codes.
A fullword containing information which was output from Decode for this client request.
You must return one of the following values in the encode_response field:
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.