IBM TXSeriesฎ for Multiplatforms V6 IBM TXSeriesฎ for Multiplatforms V6 CICSฎ customization: Introduction to user exits This presentation covers the CICS customization technique called User Exits. Goals Goals Define user exits and their semantics Understand user exit points provided by TXSeries Guidance or rules to write user exit programs Typical advantages of user exit programs The goal of this presentation is to provide an overview of user exits and their semantics, an understanding of user exit points provided by TXSeries, and an overview of the rules for writing user exit programs. You will also see some typical advantages of user exit programs. Agenda Agenda User exits What are user exits? User exit semantics User exit points provided by TXSeries User exits principle Guidance or rules for writing user exit program Typical uses of user exits The agenda for this presentation is to first define user exits, then describe the user exits provided by TXSeries, and then describe the rules for using and typical uses of user exits. User exits User exits Section This section covers the concept of user exits, semantics and how to define user exit programs to the CICS region. What are user exits ? What are user exits ? A user exit (also referred as an user exit point) is a place in a CICS runtime at which CICS transfers control to a user program, and resumes control when your exit program has finished its work. Used to extend and customize the function of your CICS system in accordance with your own environment ….. .. {cics runtime code} …. .. .. {user exit code} ……… ….. .. {cics runtime code} …… …. cics_UE_entry(….) { …….. …… ….. return (UE_Normal); } User Exit Program TXSeries runtime A user exit, also referred to as an user exit point, is the point in a CICS program at which CICS can transfer control to a program that you have written (a user exit program), and can then resume control when your program has finished its work. You do not have to use any of the user exits, but they are useful if you want to extend and customize the function of your CICS system to meet your specific requirements. User exit semantics User exit semantics User exits are referred by an unique: User exit number and User exit Name, of 8-character string: UEcccnnn where ccc is the CICS internal module identifier where nnn is an unique user exit number Description of the user exit point Example: User exit number: 15 User exit name: UE014015 User exit description: Task Termination User Exit Every user exit point in TXSeries has a unique name and a number associated with it. The unique names and the numbers for user exit points are defined by TXSeries and cannot be modified. User Exits are generally named based on the CICS internal module identifier of the CICS component that invokes the user exit program, along with a unique user exit number. As an example, TXSeries defines a user exit point called Task Termination User Exit which has a User Exit Number of 15 and User Exit Name of UE014015. Defining user exit programs A user exit program must be registered in the CICS region by adding a PD definition BHGDTR: GroupName="" ActivateOnStartup=yes ResourceDescription="Program Definition" AmendCounter=0 Permanent=no EnableStatus=enabled RemoteSysId="" RemoteName="" TransId="" RSLKey=private PathName="/usr/lpp/cicssm/bin/bhgdtr" ProgType=program UserExitNumber=25 TemplateDefined=no Resident=no Defining user exit programs User exit number User exit program A CICS region invokes a particular user exit if you define the user exit in the region. The user exit programs can be defined by adding a PD entry and specifying the UserExitNumber. CICS would automatically recognize the PD entry as a user exit entry, and would invoke the program as mentioned in the PathName during the user exit point. User exit points User exit points Section This section provides a list of user exit points provided by TXSeries, and describes some of the advantages offered by these user exit points. User exit points provided by TXSeries User exit points provided by TXSeries User exit number User exit name Description 13 UE015013 Program autoinstall 15 UE014015 Task termination 17 UE052017 Dump request 25 UE014025 Dynamic transaction routing 31 UEI09031 FEPI data conversion 33 UE046033 Dynamic resource definition 50 UE015050 Dynamic distributed program link 51 UE016051 Syncpoint 52 UE115052 IIOP security exit 53 UE115053 IIOP certificate exit At a glance, the table in the slide shows the list of user exit points provided by TXSeries. Every user exit point has a unique name and number associated with it. User exit points – In brief User exit points – In brief Program autoinstall user exit (UE015013) Allows the program definition to be installed dynamically when a program or map that is being run does not have a PD entry. Task termination user exit Invoked at normal and abnormal task termination. Dump request user exit Invoked immediately before a system or transaction dump is taken. The Program autoinstall user exit allows the program definition to be installed dynamically when a program or map that is being run does not have a PD entry. This user exit is invoked when any of the following conditions exists: LINK, LOAD, XCTL, SEND MAP and RECEIVE MAP. This user exit is called also for maps and programs. The Task termination user exit is invoked at normal and abnormal task termination (after any syncpoint has been taken). Ensure that no recoverable work is done in the user exit program. The Dump request user exit is invoked immediately before a system or transaction dump is taken. User exit points – In brief (cont.) User exit points – In brief (cont.) Dynamic transaction routing exit Invoked for the following four different cases: Immediately before a transaction that is defined as dynamic in its Transaction Definition is run either locally or remotely. After a failed attempt to route a dynamic transaction to a remote system. After a successful invocation of a dynamic transaction (remotely or locally) but transaction failure is detected. After successful execution of a dynamic transaction. The dynamic transaction routing user exit is invoked in the four different cases listed in the slide. User exit points – In brief (cont.) User exit points – In brief (cont.) Dynamic resource definition user exit Invoked whenever the region runtime database is changed by: Addition of new entries Deletion of old entries Update or modification of existing entries Syncpoint user exit Invoked following an EXEC CICS SYNCPOINT command. The Dynamic resource definition user exit is invoked whenever the region runtime database is changed. The changes can be addition, deletion or updates to the existing resource entries. The Syncpoint user exit is invoked following an EXEC CICS SYNCPOINT command. The result of the EXEC CICS SYNCPOINT command is made available in this user exit program. It is not possible to change the outcome of the EXEC CICS SYNCPOINT command in this user exit program. User exit points – In brief (cont.) User exit points – In brief (cont.) Dynamic distributed program link user exit Invoked for the following four different cases: When CICS is about to link to a program. When CICS is about to link to a program that does not have a Program Definition (PD). After a successful attempt to link to a program and the initial user exit program invocation requests reinvocation. After a failed attempt to link to a program, if the initial user exit program invocation requests reinvocation. The distributed program link user exit is invoked in the four different cases listed in the slide. Rules for writing user exit programs Rules for writing user exit programs Section This section covers certain guidance or rules to be followed when writing user exit programs. User exit programs – Rules User exit programs – Rules The entry point for all user exit programs is cics_UE_entry All user exits are called with two parameters A pointer to the cics_UE_Header parameter list A pointer to the exit-specific parameter list for the user exit that has been invoked User exits must set a return code that is defined as being supported for the user exit. User exit programs should include cicsue.h header file Contains constants, data definitions, exit specific structure, and interface definitions A task work area is provided for sharing data between user exits within an application server Maximum of 128 bytes Writing User exit programs is different from writing a CICS server application. User exit programs should not be run as normal CICS transactions. Every program running under TXSeries must have an entry point. Thus for user exit programs the entry point is defined as cics_UE_entry. CICS supplies parameters to the entry point – a header parameter list and a user exit specific parameter list, with which user exit programs can know which user exit point has been invoked and also to get relevant user exit specific information. As with any program, user exit programs must return a return code specifying certain action to be taken by CICS. The return code value depends on the user exit point. Every user exit program must include TXSeries provided cicsue.h header file, which consists of constants, data definition, exit specific structures, return codes and interface definitions. If you want to share user data across user exits within the same application server process, you can use the task work area provided with every exit point. The task work area is a common buffer passed to all the user exit programs and can be shared among user exits. A maximum of 128 bytes can be stored in the task work area. User exit programs – Rules (cont.) User exit programs – Rules (cont.) Must be written in C language only Must be reentrant Must not switch threads Must return control to CICS Must not damage integrity of CICS Must not use CICS API commands Cannot access CICS resources Signal handlers must not be included in user exit programs Listed here are some of the important guidelines for writing User exit programs. User exit points – Typical uses User exit points – Typical uses User exit point 17 Suppress system or transaction dumps based on certain application condition. User exit point 25 and 50 Perform intelligent routing when a DPL or DTR request is received. User exit 15 Perform application cleanups during abnormal or normal termination of tasks. Samples provided /samples/userexit Some of the advantages offered by the user exit programs in a practical scenario are listed here. User exit point 17 can be used to suppress system or transaction dumps to possibly avoid numerous dumps in the file system, especially when you are developing new applications and expecting failures. User exit point 25 and 50 can be used to intelligently route when a Distributed Program Link or Distributed Transaction Request is received. The user exit program can modify the SYSID which on return will be used by CICS to route the requests. Before modifying the SYSID the user exit program can devise logic to identify which system is most appropriate for the requests to be routed to. User exit point 15 (Task Termination User Exit Point) can be used to perform cleanups such as closing file descriptors, logging messages to application specific log files during abnormal or normal termination of tasks. A sample user exit program is supplied with the product and can be found in the product samples/userexit directory. Summary Summary Section This section will provide a summary of the topics covered in this presentation. Summary Summary User exits definition and semantics User exit points provided by TXSeries Rules for writing a user exit program Typical advantages of user exit programs In summary, this presentation has covered user exits, including the exit points provided by TXSeries, rules for using user exit programs, and advantages provided by them. Trademarks