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:
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
*----------------------------------------------------------------*
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
*----------------------------------------------------------------*
Here is a skeleton example of a task-related user exit program:
id division.
program-id. SAMPTRUE.
environment division.
configuration section.
input-output section.
data division.
file section.
working-storage section.
linkage section .
copy 'dfhcbuxi.cpy'.
copy 'dfhcbuxc.cpy'.
01 lk-global-area.
03 lk-ga-byte pic x occurs 0 to 32767
depending on uxi-global-area-length.
01 lk-local-area.
03 lk-la-byte pic x occurs 0 to 32767
depending on uxi-local-area-length.
procedure division using
uxi-user-exit-interface.
module-entry-point.
move 0 to return-code
set address of lk-uxc-operation
to uxi-operational-flags-ptr
set address of lk-uxc-schedule-parm
to uxi-scheduling-flags-ptr
move 0 to lk-uxc-return-code
*> -- Are we being called by an application?
*> -- (User application sets unused value in lk-uxc-schedule.)
if lk-uxc-schedule = x'00'
perform called-by-application
goback
end-if
evaluate true
when lk-uxc-initialization-88
perform initialization
when lk-uxc-shutdown-88
goback
when lk-uxc-task-start-88
perform task-start-process
when lk-uxc-task-syncpoint-88
evaluate true
when lk-uxc-syncpoint-prepare-88
perform syncpoint-prepare
when lk-uxc-syncpoint-commit-88
perform syncpoint-commit
when lk-uxc-syncpoint-rollback-88
perform syncpoint-rollback
end-evaluate
when lk-uxc-user-syncpoint-88
set address of lk-global-area
to uxi-global-area-ptr
set address of lk-local-area
to uxi-local-area-ptr
evaluate true
when lk-uxc-syncpoint-prepare-88
continue
when lk-uxc-syncpoint-commit-88
perform syncpoint-commit
when lk-uxc-syncpoint-rollback-88
perform syncpoint-rollback
end-evaluate
end-evaluate
goback
.
called-by-application section.
*> -- Add any code here that you wish to execute when
*> -- called by an application program.
exit
.
initialization section.
$if 78-break-on-error defined
call 'CBL_DEBUGBREAK'
$end
perform set-schedule-bits
exit
.
task-start-process section.
*> -- Insert code here that you wish to perform at
*> -- start of task.
perform set-schedule-bits
exit
.
end-task-process section.
*> -- Insert code here that you wish to perform at
*> -- end of task.
exit
.
syncpoint-prepare section.
*> -- Insert code here that you wish to perform at
*> -- syncpoint prepare.
exit
.
syncpoint-commit section.
*> -- Insert code here that you wish to perform at
*> -- syncpoint commit.
exit
.
syncpoint-rollback section.
*> -- Insert code here that you wish to perform at
*> -- syncpoint rollback.
exit
.
set-schedule-bits section.
initialize lk-uxc-schedule-byte
*> -- Register start of task interest
compute lk-uxc-schedule-byte-bin =
lk-uxc-schedule-byte-bin B-OR 78-lk-uxc-TRUE-on-start
*> -- Register syncpoint interest
compute lk-uxc-schedule-byte-bin =
lk-uxc-schedule-byte-bin B-OR 78-lk-uxc-TRUE-on-sync
*> -- Register prepare interest
compute lk-uxc-schedule-byte-bin =
lk-uxc-schedule-byte-bin B-OR 78-lk-uxc-TRUE-on-prep
exit
.