Writing a callback program

The callback program creates and manages the life cycle of a user resource that has been included in a deployed bundle. The deployed bundle is defined in the CICS® region using a BUNDLE resource.

1. CICS links to your callback program. CICS passes the following containers on the channel to create a user resource:
   • DFHRL-CONTROL, containing the tokens for the resource and the request to create or manage the user resource.
   • DFHRL-DATA, containing the metadata from the bundle about the resource.
   • DFHRL-NAME, containing the name of the resource.
   • DFHRL-ROOT, containing the location where the bundle is deployed in the file system.
   • DFHRL-TYPE, containing the URI of the resource type.

   When inquiring on a user resource, changing the status of a user resource, or discarding a user resource, CICS puts the DFHRL-CONTROL container on the channel only.

   The constants for the containers are described in the DFHRLUCx copybooks, where x represents the programming language. These copybooks are in the CICSTSnn.CICS.SDFHSAMP library, where CICSTSnn is your CICS release. For example, the library is CICSTS64.CICS.SDFHSAMP for CICS TS beta.
2. Your program must use these containers to create, enable, disable, or discard the user resource.
   The DFHRL-CONTROL container has two fields that describe the action being performed by a system programmer and the state of the BUNDLE resource:

   rl_function field	rl_state field	Program behavior
   Create bundle	Enabled	The program must create and enable the user resource using the information in the containers on the channel.
   	Disabled	The program must create a user resource in a disabled state using the information in the containers on the channel
   Set bundle	Enabled	The program must enable the user resource, either using the rl_client_token value or the bundle and resource token that CICS also provides in the DFHRL-CONTROL container.
   	Disabled	The program must disable the user resource, either using the rl_client_token value or the bundle and resource token that CICS also provides in the DFHRL-CONTROL container.
   Inquire bundle	Enabled	The program must return the state of the user resource in the DFHRL-CONTROL container.
   	Disabled
   Discard bundle	Discarding	The program must discard the user resource.

3. When the program has completed its processing, it must update the rl_state field in the DFHRL-CONTROL container to indicate if the program was successful in either creating, enabling, disabling, or discarding the user resource:
   • If the program creates a user resource successfully, update the rl_state field with an enabled state and put a unique value in the rl_client_token field. This token is used by CICS on all subsequent calls to the program to manage the resource.
   • If the program disables a user resource successfully, update the rl_state field with a disabled state.
   • If the program discards a user resource successfully, update the rl_state field with a discarded state.
   • If the program is returning the state of a user resource, update the rl_state field with an enabled or disabled state as appropriate.
   • If the program fails to create, disable, or discard a user resource, update the rl_state field with a failed state.