Rocket® Enterprise Developer (formerly a product of Micro Focus or formerly a product of Open Text) documentation, created before Rocket Software acquired certain products from OpenText, may include outdated references to "Micro Focus" or "OpenText", both of which are trademarks of OpenText or its affiliates. Rocket Software is not affiliated with Micro Focus or OpenText and has since rebranded these products as Rocket® products. You may also encounter outdated links in this documentation. If you do, please contact Rocket Support (support@rocketsoftware.com) for assistance.
Global and Task-related Exit Programs
You must enable each user exit that an application program needs before it is called, and you can disable it when the application program has finished with it, though you do not have to; user exits are always disabled by default when CICS starts up. You use the CICS command ENABLE PROGRAM to enable a user exit program, and the CICS command DISABLE PROGRAM to disable a user exit program. If you try to enable an invalid exit an EIBRCODE of X'804000' is returned. If you try to enable an exit that is valid but not implemented, an EIBRCODE of X'804010' is returned. The EXTRACT EXIT command is also provided; you use this to gain access to the work area of a user exit program. For details of the level of support provided for these commands see the topic System Programmers Commands.
You must define each user exit program as a program (in the PLT) and the definition must be available on the running system.
For information about global user exits and task-related user exits see the IBM manual CICS/ESA 3.3 Customization Guide. This manual contains a list of valid user exit points.
You need to include the following two copybooks in your user exit program, whether it is for a global user exit or a task-related user exit:
- dfhcbuxi.cpy:
78 78-uxi-TRUE value 1. 78 78-uxi-XZCATT value 2. 78 78-uxi-XZCIN value 3. 78 78-uxi-XZCOUT value 4. 78 78-uxi-XEIIN value 5. 78 78-uxi-XEIOUT value 6. 78 78-uxi-XFCFSHRO value 7. 78 78-uxi-XWBOPEN value 8. 78 78-uxi-XWBSNDO value 9. 78 78-uxi-XWBAUTH value 10. 610668 78 78-uxi-XFAINTU value 11. 78 78-exi-rc-UERCBYP value 4. ***--------------------------------------------------------------* *** Base parameters * ***--------------------------------------------------------------* 01 uxi-user-exit-interface. 02 uxi-operational-flags-ptr pointer. 02 uxi-scheduling-flags-ptr pointer. 02 uxi-global-area-ptr pointer. 02 uxi-global-area-length pic x(4) comp-5. 02 uxi-local-area-ptr pointer. 02 uxi-local-area-length pic x(4) comp-5. 02 uxi-dfheiblk-ptr pointer. 02 uxi-unit-of-recovery-ptr pointer. ***--------------------------------------------------------------* *** Exit specific parameters * ***--------------------------------------------------------------* 02 uxi-exit-specific-ptrs. *> XZCAT In/Ot XEin/ot FSHRO XWB???? 03 uxi-resource-ptr pointer. *> TCTTE TCTTE Arg lst Buffer 03 uxi-resource-data-ptr pointer. *> TIOA TIOA UserID UserID 03 uxi-res-data-len-ptr pointer. *> * * 03 uxi-aux-1-ptr pointer. *> 62TPN program F-Name ParmList 03 uxi-aux-1-length-ptr pointer. *> * * 03 uxi-aux-2-ptr pointer. *> Tran Sys EIB Keys 03 uxi-aux-2-length-ptr pointer. *> 03 uxi-aux-3-ptr pointer. *> TEUA TEUA 03 uxi-aux-3-length-ptr pointer. *> * * 03 uxi-aux-4-ptr pointer. *> ComA ComA 03 uxi-aux-4-length-ptr pointer. *> * * 03 pointer. *> 610668 02 redefines uxi-exit-specific-ptrs. *> XFAINTU 610668 03 uxi-xfaintu-uepfareq-ptr *> UEPFAREQ 610668 pointer. 610668 03 uxi-xfaintu-uepfatut-ptr *> UEPFATUT 610668 pointer. 610668 03 uxi-xfaintu-uepfanam-ptr *> UEPFANAM 610668 pointer. 610668 03 uxi-xfaintu-uepfatyp-ptr *> UEPFATYP 610668 pointer. 610668 03 uxi-xfaintu-uepfauaa-ptr *> UEPFAUAA 610668 pointer. 610668 03 uxi-xfaintu-uepfaual-ptr *> UEPFAUAL 610668 pointer. 610668 03 uxi-xfaintu-uepfatk-ptr *> UEPFATK 610668 pointer. 610668 03 uxi-xfaintu-uepfamch-ptr *> UEPFAMCH 610668 pointer. 610668 03 uxi-xfaintu-uepfareg-ptr *> UEPFAREG 610668 pointer. sc-f74 03 pointer. sc-f74 03 pointer. sc-f74 03 pointer. ***--------------------------------------------------------------* *** System parameters * ***--------------------------------------------------------------* 02 uxi-PCA-ptr pointer. 02 uxi-CSA-ptr pointer. 02 uxi-DCA-ptr pointer. 02 uxi-local-trace-table-ptr pointer. *----------------------------------------------------------------* * dfhcbuxi.cpy end *----------------------------------------------------------------* - dfhcbuxc.cpy:
01 lk-uxc-operation. 03 lk-uxc-exit-id pic x comp-x. 88 lk-uxc-TRUE-88 value 78-uxi-TRUE. 88 lk-uxc-XZCATT-88 value 78-uxi-XZCATT. 88 lk-uxc-XZCIN-88 value 78-uxi-XZCIN. 88 lk-uxc-XZCOUT-88 value 78-uxi-XZCOUT. 88 lk-uxc-XEIIN-88 value 78-uxi-XEIIN. 88 lk-uxc-XEIOUT-88 value 78-uxi-XEIOUT. 88 lk-uxc-XFCFSHRO-88 value 78-uxi-XFCFSHRO. 03 lk-uxc-schedule pic x. 88 lk-uxc-generic-88 value x'80'. 88 lk-uxc-TRUE-on-start-88 value x'80'. 88 lk-uxc-TRUE-on-sync-88 value x'40'. 88 lk-uxc-TRUE-on-prep-88 value x'20'. 88 lk-uxc-TRUE-on-tr-wrap-88 value x'01'. 03 lk-uxc-modifier pic x comp-x. 88 lk-uxc-user-syncpoint-88 value 0. 88 lk-uxc-task-syncpoint-88 value 1. 88 lk-uxc-task-start-88 value 2. Y97157 88 lk-uxc-re-initialization-88 value 253. 88 lk-uxc-initialization-88 value 254. Y97157 88 lk-uxc-initialization-88m value 253 254. 88 lk-uxc-shutdown-88 value 255. 03 lk-uxc-action pic x comp-x. 88 lk-uxc-syncpoint-commit-88 value 0. 88 lk-uxc-syncpoint-rollback-88 value 1. 88 lk-uxc-syncpoint-prepare-88 value 2. 03 lk-uxc-return-code pic x(4) comp-5. a82573 88 ws-uex-max-rc-uercbyp-88 value 4. 01 lk-uxc-schedule-parm. 03 lk-uxc-schedule-byte pic x. 03 lk-uxc-schedule-byte-bin redefines lk-uxc-schedule-byte pic x comp-x. 78 78-lk-uxc-TRUE-on-start value h'80'. 78 78-lk-uxc-TRUE-on-sync value h'40'. 78 78-lk-uxc-TRUE-on-prep value h'20'. 78 78-lk-uxc-TRUE-on-tr-wrap value h'01'. *----------------------------------------------------------------* * dfhcbuxc.cpy end *----------------------------------------------------------------*
Note:
- The user exit parameters are passed to your exit program in structure uxi-user-exit-interface, defined in the copybook dfhcbuxi.cpy. Two fields in this structure, uxi-operational-flags-ptr and uxi-scheduling-flags-ptr, point respectively to two further structures, lk-uxc-operation and lk-uxz-schedule-param, in the other copybook, dfhcbuxc.cpy.
- A CICS application can call a task-related user exit directly, for example, to obtain the address of the task area. Normally, the CICS application would call a task-related user exit program with the DFHRMCAL macro. As this macro is not supported, the application must call the user exit program directly, and must include the copy books dfhcbuxi.cpy and dfhcbuxc.cpy. If a user exit program can be called by an application program, you need to use a mechanism by which the exit program can decide whether it was called by an application program or by MSS. The sample exit program included below shows one approach: the application sets an unused bit in lk-uxc-schedule, which the user exit program tests for.