You can use the sample API-crossing exit program (CSQCAPX)
that is supplied with
CICS®
as
a framework for your own program. You must write your exit program
to be threadsafe and declare your exit program as threadsafe.
About this task
For performance reasons, write your program in assembler
language. If you write it in any of the other languages supported
by
CICS
, you must provide your
own data definition file. Link edit your program as AMODE(31) and
RMODE(ANY). The layout of the MQXP parameter list that is passed to
the crossing exit program is defined in the program.
Procedure
- Exits are written as extensions to the CICS-
WebSphere®
MQ code. Ensure that your exit
does not disrupt any
WebSphere
MQ
for
z/OS®
programs or transactions
that use the MQI.
They are indicated with a prefix of
CSQ, DFH, or CK.
- Your program can use all the APIs (for example,
IMS™
,
DB2®
,
and
CICS
) that a
CICS
task-related user exit program can use.
You must use only threadsafe
CICS
commands
in your exit program and in any programs that your exit program
calls.
- Your program can use any of the MQI calls except MQCONN,
MQCONNX, and MQDISC. However, any MQI calls in the exit
program do not call the exit program a second time.
- When it is called after an MQI call, your program can inspect
and modify the completion and reason codes set by the call.
- To find the name of an MQI call issued by an application,
examine the
ExitCommand
field of the MQXP structure.
To find the number of parameters on the call, examine the
ExitParmCount
field.
You can use the 16 byte
ExitUserArea
field
to store the address of any dynamic storage that the application
obtains.
This field is retained across uses of the exit and has the same
lifetime
as a
CICS
task.
- Your program can suppress the execution of an MQI call
by returning MQXCC_SUPPRESS_FUNCTION or MQXCC_SKIP_FUNCTION in the
ExitResponse
field.
For the call to run (and the exit program to be called again
after the call has completed), your exit program must return
MQXCC_OK.
- Your program can issue
EXEC CICS SYNCPOINT
or
EXEC
CICS SYNCPOINT ROLLBACK
commands. These commands commit
or rollback all the updates done by the task up to the point that
the exit was used.
- Parameter MQXP_EXITCALLPROG is included in the parmlist
which is passed to the module through the commarea, and contains the
name of the program that called the module. Because CSQCAPX is
called
as a User Replaceable Module (URM), an EXEC CICS ASSIGN INVOKINGPROG
command returns blanks. The parameter MQXP_EXITCALLPROG can be used
instead, as it contains the name of the calling program, identical
in format to the output received from an EXEC CICS ASSIGN
INVOKINGPROG
command. This parameter is available if the parameter MXQP_VERISON
has a value of 2.
- Your program must end by issuing an
EXEC CICS
RETURN
command. It must not transfer control with an XCTL
command.
- Create PROGRAM resource definitions for your exit program
and any programs that your exit program calls. You must
call your exit program CSQCAPX.
Specify the following
settings in your PROGRAM resource definitions:
- Specify CONCURRENCY(THREADSAFE) or CONCURRENCY(REQUIRED)
for your exit program and any programs that your exit program calls.
You must use only threadsafe
CICS
commands
in your exit program and in any programs that your exit program
calls.
- If you are using the
CICS
Transaction Server storage
protection feature, specify EXECKEY(CICS) for your exit program and any
programs to which it passes
control, so that they run in
CICS
execution key.
For more information, see
Exit programs and the CICS storage protection facility.
- The parameters in the communication area are addresses
so you must define the exit program as local to the
CICS
system, not as a remote program.
CICS
supplies a sample
program definition for CSQCAPX in group DFHMQ. This program definition
specifies CONCURRENCY(THREADSAFE) and EXECKEY(CICS). You can use
this
sample as a basis for the program definition for your exit program.
Results
The
CICS
system tries
to load the exit program when
CICS
connects
to
WebSphere
MQ for
z/OS
. If this attempt is successful,
message DFHMQ0301I is sent to the CKQC panel or to the system console.
If the load is unsuccessful, for example if the load module does not
exist in any of the libraries in the DFHRPL concatenation, message
DFHMQ0315E is sent to the CKQC panel or to the system console.