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.