Writing the resource checker

Your resource checker program must be called DFHRPRSC. There can be only one resource checker in a CICS® region.

The resource checker allows you to check the credentials of inbound client requests.

The resource checker can check the client address, passed as an input parameter, against a list of known clients for the host on which the request has been received. The password passed to the resource checker is blank.

Reference information for the resource checker

The reference information for the resource checker is presented as follows:

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.

Summary of parameters

The format of the communication area containing the resource checker parameters is in the C header file DFHRPRDH, and the COBOL copybook DFHRPRDO. You will also need values defined in the C header file DFHRPUCH, or in the COBOL copybook DFHRPUCO.

Input Output
res_check_alias_transid
res_check_cics_password_ptr
res_check_cics_userid
res_check_client_ip_address
res_check_eyecatcher
res_check_host_ip_address
res_check_server_program_name

res_check_reason
res_check_response

Function

The resource checker is optionally invoked by the alias before it attempts to link to the CICS program that is to service the client request. It must say whether the client request is allowed to proceed.

Parameters

res_check_alias_transid
(Input only)

The 4-character name of the alias transaction that has linked to the resource checker.

res_check_cics_password_ptr
(Input only)

A pointer to the 8-character password passed from the requesting client or supplied by Decode. The value of this field is blank, and it is provided for compatibility with earlier versions of CICS ONC RPC.

res_check_cics_userid
(Input only)

The 8-character CICS user ID under which the alias is running.

res_check_client_ip_address
(Input only)

The fullword internet address of the client.

res_check_eyecatcher
(Input only)

A string of length 8. (Its value is defined in the header file DFHRPUCH and the copybook DFHRPUCO).

res_check_host_ip_address
(Input only)

The fullword internet address of the TCP/IP for MVS™ host with which the server controller is in communication.

res_check_reason
(Output only)

The reason to be returned to the alias.

res_check response
(Output only)

The response to be returned to the alias.

res_check_server_program_name
(Input only)

The 8-character name of the CICS program that is to be invoked to perform the server function requested by the client.

Response and reason codes

You must return one of the following values in the res_check_response field.

URP_OK
The alias will continue to process the client request.
URP_EXCEPTION
The alias writes an exception trace entry (trace point 9F0E), and issues a message that depends on the reason code:
  • URP_AUTH_BADCRED--message DFHRP0130

    An svcerr_auth call with a why-value of AUTH_BADCRED is used to send a reply to the client.

  • URP_AUTH_TOOWEAK--message DFHRP0184

    An svcerr_auth call with a why-value of AUTH_TOOWEAK is used to send a reply to the client.

  • Any other value--message DFHRP0185

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

URP_INVALID
The alias writes an exception trace entry (trace point 9F0E), and issues a message (DFHRP0186).

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

URP_DISASTER
The alias writes an exception trace entry (trace point 9F0E), and issues a message (DFHRP0187).

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

If you return any other value in res_check_response, the alias writes an exception trace entry (trace point 9F0E), and issues a message (DFHRP0188). 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 the resource checker, except as indicated above under URP_EXCEPTION. The reason code is output in any trace or messages that result from the resource checker, 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.

Related concepts
ONC RPC concepts
CICS ONC RPC security
Related tasks
Security in CICS and its effect on CICS ONC RPC operations
[[ Contents Previous Page | Next Page Index ]]