Chapter 3: Developing Exit Programs

CICS Option supports CICS global exit programs and task related exit programs. As part of this support, you can use the following system programming CICS API commands:

• ENABLE PROGRAM (Parameters FORMATEDF and LINKEDITMODE are not supported)
• DISABLE PROGRAM (Parameter FORMATEDF is not supported)
• EXTRACT EXIT

A global user exit is a point in a Transaction System module at which control can be transferred to a global exit program (user written) and at which Transaction System can resume control after it has finished.

A task-related user exit lets you write a program to access a non-CICS resource such as a database. Programs written for Transaction System user exits must not use EXEC CICS commands. These programs must use native addressing for pointers so can not be compiled with the AMODE directive. For more information about global user exits and task-related user exits see the IBM manual CICS/ESA 3.3 Customization Guide. This book also contains a list of valid user exit points. The Transaction System interface to these user exits is in the copybook dfhcbuxi.cpy and is as follows:

        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.
      ***--------------------------------------------------------------*
      ***  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.         *> XZCATT In/Out XEin/out
            03 uxi-resource-ptr      pointer. *> TCTTE  TCTTE  Arg list
            03 uxi-resource-data-ptr pointer. *> TIOA   TIOA   user-id
            03 uxi-res-data-len-ptr  pointer. *>  *      *
            03 uxi-aux-1-ptr         pointer. *> APPC          program
            03 uxi-aux-1-length-ptr  pointer. *>  *
            03 uxi-aux-2-ptr         pointer. *> Tran          Sys EIB
            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. *>
      ***--------------------------------------------------------------*
      ***  System parameters                                           *
      ***--------------------------------------------------------------*
           02 uxi-PCA-ptr                       pointer.
           02 uxi-CSA-ptr                       pointer.
           02 uxi-DCA-ptr                       pointer.
           02 uxi-local-trace-table-ptr         pointer.

The supported global user exit points and the scheduling of task-related user exits are contained in copybook dfhcbuxc.cpy, which is as follows:

        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.
           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.
              88 lk-uxc-initialization-88      value 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.

        01 lk-uxc-schedule-parm.
           03 lk-uxc-schedule-byte             pic x.
           78 78-lk-uxc-TRUE-on-start          value x'80'.
           78 78-lk-uxc-TRUE-on-sync           value x'40'.
           78 78-lk-uxc-TRUE-on-prep           value x'20'.
           78 78-lk-uxc-TRUE-on-tr-wrap        value x'01'.

Global and task-related user exit programs are enabled and disabled using the EXEC CICS ENABLE and EXEC CICS DISABLE commands. Each module containing user exit programs must be defined to Transaction System as a program and the definition must be available on the running system. 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.