WebSphere MQ for z/OS
The exits are invoked as if by a z/OS LINK, in:
- Non-authorized problem program state
- Primary address space control mode
- Non-cross-memory mode
- Non-access register mode
- 31-bit addressing mode
The link-edited modules must be placed in the data set specified by the
CSQXLIB DD statement of the channel initiator address space procedure; the
names of the load modules are specified as the exit names in the channel definition.
When writing channel exits for z/OS, the following rules apply:
- Exits must be written in assembler or C; if C is used, it must conform
to the C systems programming environment for system exits, described in the z/OS C/C++ Programming Guide.
- Exits are loaded from the non-authorized libraries defined by a CSQXLIB
DD statement. Providing CSQXLIB has DISP=SHR, exits can be updated while the
channel initiator is running, with the new version used when the channel is
restarted.
- Exits must be reentrant, and capable of running anywhere in virtual storage.
- Exits must reset the environment, on return, to that at entry.
- Exits must free any storage obtained, or ensure that it will be freed
by a subsequent exit invocation.
For storage that is to persist between
invocations, use the z/OS STORAGE service; there is no suitable service in
C.
- All MQI calls except MQCMIT/CSQBCMT and MQBACK/CSQBBAK are allowed. They
must be contained after MQCONN (with a blank queue manager name). If these
calls are used, the exit must be link-edited with the stub CSQXSTUB.
The exception to this rule is that security channel exits may issue commit
and backout MQI calls. To do this, code the verbs CSQXCMT and CSQXBAK in place
of MQCMIT/CSQBCMT and MQBACK/CSQBBAK.
- Exits should not use any system services that could cause a wait, because
this would severely impact the handling of some or all of the other channels.
Many channels are run under a single TCB typically, if you do something in
an exit that causes a wait and you do not use MQXWAIT,
it will cause all these channels to wait. This
will not give any functional problems, but might have an adverse effect on
performance. Most SVCs involve waits, so you should avoid them, except for
the following:
- GETMAIN/FREEMAIN/STORAGE
- LOAD/DELETE
In general, therefore, SVCs, PCs, and I/O should be avoided. Instead,
the MQXWAIT call should be used.
- Exits should not issue ESTAEs or SPIEs, apart from in any subtasks they
attach. This is because their error handling might interfere with the error
handling performed by WebSphere MQ. This means that WebSphere MQ might not be able to recover
from an error, or that your exit program might not receive all the error information.
- The MQXWAIT call (see MQXWAIT - Wait in exit) provides a wait service
that allows waiting for I/O and other events; if this service is used, exits
must not use the linkage stack.
For I/O and other facilities that do not
provide non-blocking facilities or an ECB to wait on, a separate subtask should
be ATTACHed, and its completion waited for by MQXWAIT; because of the overhead
that this technique incurs, it is recommended that this be used only by the
security exit.
- The MQDISC MQI call will not cause an implicit commit to occur within
the exit program. A commit of the channel process is performed only when the
channel protocol dictates.
The following exit samples are provided with WebSphere MQ for z/OS:
- CSQ4BAX0
- This sample is written in assembler, and illustrates the use of MQXWAIT.
- CSQ4BCX1 and CSQ4BCX2
- These samples are written in C and illustrate how to access the parameters.