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-XWBOPEN value 7.
78 78-uxi-XWBSNDO value 8.
78 78-uxi-XWBAUTH value 9.
***--------------------------------------------------------------*
*** 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.
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-XWBOPEN-88 value 78-uxi- XWBOPEN.
88 lk-uxc-XWBSNDO-88 value 78-uxi- XWBSNDO.
88 lk-uxc-XWBAUTH-88 value 78-uxi- XWBAUTH.
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'.
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.
01 work-scl.
02 ws-allocate-local.
03 ws-allocate-local-ptr-x.
04 ws-allocate-local-ptr pointer.
03 ws-allocate-local-size pic x(4) comp-5.
03 ws-allocate-local-return pic x(4) comp-5.
88 ws-allocate-local-ok-88 value 0.
88 ws-allocate-local-no-space-88 value 1.
88 ws-deallocate-local-invalid-88 value 2.
88 ws-deallocate-inv-length-88 value 157.
02 ws-allocate-local-type pic x.
02 pic x.
02 ws-mfpm-register-flag pic x(2).
88 ws-mfpm-assign-24-88 value x'0000'.
88 ws-mfpm-absolute-24-88 value x'0200'.
88 ws-mfpm-assign-31-88 value x'0001'.
88 ws-mfpm-absolute-31-88 value x'0201'.
02 ws-mfpm-allocate-size pic x(4) comp-x.
02 ws-mfpm-allocate-ptr-x.
03 ws-mfpm-allocate-ptr pointer value null.
linkage section .
copy 'dfhcbuxi.cpy'.
copy 'dfhcbuxc.cpy'.
01 lk-global-area.
03 lk-ga-byte pic x occurs 0 to 4096
depending on uxi-global-area-length.
01 lk-local-area.
03 lk-la-byte pic x occurs 0 to 4096
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'02'
perform called-by-application
goback
end-if
*> -- Register syncpoint interest
move 78-lk-uxc-TRUE-on-sync to lk-uxc-schedule-byte
*> -- Register start of task interest
call "CBL_OR" using
78-lk-uxc-TRUE-on-start
lk-uxc-schedule-byte
by value 1
end-call
*> -- Register any other interest here by OR'ing bits
*> -- in lk-uxc-schedule-byte as above.
if lk-uxc-exit-id not = 0 *> -- handle only TRUEs
goback
end-if
evaluate true
when lk-uxc-initialization-88
when lk-uxc-shutdown-88
goback
when lk-uxc-task-start-88
perform save-TA-address
when lk-uxc-task-syncpoint-88
perform end-task-process
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
*> -- We haven't registered an interest for this
continue
when lk-uxc-syncpoint-commit-88
perform commit-process
when lk-uxc-syncpoint-rollback-88
perform rollback-process
end-evaluate
end-evaluate
goback
.
called-by-application section.
*> -- Add any code here that you wish to execute when
*> -- called by an application program.
*> -- This sample passes back the address of the local
*> -- task area.
set uxi-local-area-ptr to ws-mfpm-allocate-ptr
exit
.
save-TA-address section.
*> -- Convert local task area address and save in W/S.
exit
.
end-task-process section.
*> -- Insert code here that you wish to perform at
*> -- end of task.
exit
.
commit-process section.
*> -- Insert code here that you wish to perform at
*> -- user syncpoint.
exit
.
rollback-process section.
*> -- Insert code here that you wish to perform at
*> -- user backout.
exit
.