Customizing the DB2 thread management exit

Customizing the DB2® thread management exit enables you to validate clients and control the duration of CAF connections.

If your installation has special processing requirements that can be addressed by a DB2 thread management exit, you can update the exit IBM® delivers or create a custom exit of your own. The following table describes the DB2 thread management parameter list and processing options for developing your own custom DB2 thread management exit.

The DB2 thread management exit is called to perform the following functions:
  • Initialization: Each time a new DB2 CAF service is started from the region controller, an initialization call is made to perform any one-time initialization processing for the started task. If your exit must allocate any storage for use throughout the life of the task, your exit can allocate the storage in this call and place the address of that storage in the user field DB2TUSRW supplied in the exit parameter structure.
  • Client Connection: Called each time a new client has acquired a CAF subtask. Typically, this call is made immediately before connecting to DB2 on behalf of the client. The one exception is when the exit is set to leave connections to DB2 active even when clients disconnect.
  • After Connection to DB2: Called after each attempt is made to connect to DB2. This call is made regardless of whether the connect was successful. The parameters field DB2STAT indicates whether the connection attempt was successful.
  • Client Disconnection: Called each time a client has released its connection to the CAF subtask.
  • Termination: Called once at subtask termination. If you allocated any exit memory at initialization, this is when it needs to be freed.
The parameters listed in the following table are located in the PDS member CACSXPL7 of the SCACMAC library:
Table 1. DB2 thread management exit parameters
Field Description
DB2TUSRW Initialized to binary zeros prior to the initialization call and left unchanged after that point in processing. Use of this field is determined by the user exit.
DB2TUSRP Points to a NULL terminated user parameter as defined on the service definition for the DB2 CAF task. This parameter includes any text included after the exit name itself in the task data field. For example, to pass the string USERPARM to the exit from the service definition, the task data for the exit is:

CACPLAN,CACSX07 USERPARM
DB2TSSN Points to the four-character subsystem name as defined in the Service Name field of the service definition the task. In most cases, this field is for informational purposes only. However, the exit can change this field on client connection calls to designate a new subsystem to connect to, if necessary. If this field is updated, it will remain updated until the thread disconnects from DB2. At that point, it will be changed back to its original service information entry value.
DB2TPLAN Points to the 8-character DB2 PLAN name as defined in the Task Data field of the service definition for the task. In most cases, this field is for informational purposes only. However, the exit can change this field on client connection calls to designate a new DB2 PLAN to open a DB2 connection. If this field is updated, it remains updated until the thread disconnects from DB2. At that point, it is changed back to its original service definition value.
DB2TUID Points to the user ID provided by the client when the client connected to the data server. This field is binary zeros on initialization and termination calls, as no user is available when these calls are issued. This field is for reference purposes only and must not be changed by the exit.
DB2UPWD The DB2UPWD field points to the user password provided by the client when it connected to the data server. This field is binary zeros on initialization and termination calls, as no user is available when these calls are issued. This field is used for reference purposes only and must not be changed by the exit.
DB2TSTAT The DB2TSTAT field identifies whether a current CAF connection exists to DB2. This field is used for reference purposes only.
DB2TFUNC The DB2TFUNC field identifies the function of the call as described previously. Defined values for this field are:
  • DB2TINIT: Initialization function
  • DB2TCCON: Client Connection function
  • DB2TDB2C: DB2 Post Connection/Plan Open function
  • DB2TCDIS: Client Disconnect function
  • DB2TTERM: Termination function
DB2TRFNC The DB2TRFNC field can be used by the exit to:
  • Explicitly request connection or reconnection to the DB2 subsystem.
  • Explicitly request disconnection from the DB2 subsystem.
  • Notify the system that a user ID or password validation error has occurred.

    The field is used to alter the default DB2 subsystem connection and disconnection behavior in the DB2 CAF service. The default behavior is to connect to DB2 when the first user requests DB2 access and disconnect from DB2 at data server shutdown. The exit should set this field on each call to one of the following values:

  • DB2TRDFL: Do default connection processing
  • DB2TRCON: Connect to DB2. If a connection already exists, terminate that connection and create a new connection using the subsystem and plan name in the fields DB2TSSN and DB2TPLAN. This value is valid for Initialization and Client Connection functions.
  • DB2TRDIS: Disconnect from DB2 if a connection exists. This value is valid for the Client Disconnect function.
  • DB2TRUER: User or password information is invalid. This value can be returned on the Client Connection function to return an Access Denied error to the requesting client.

The return code (register 15 value) for successful completion of the user exit should always be set to 0. Any other value causes an error message to be returned to the requesting client.

Activating a customized exit

You can follow the instructions for activating the DB2 thread management exit to activate your customized exit with the following modifications:

  • Replace the system default exit name CACSX07 with the name of your customized exit.
  • If your exit does not create a TCB level ACEE for the DB2 primary authorization ID setting, skip the instructions for updating and reassembling DSN3SATH.