Writing channel exit programs on z/OS

We can use the following information to help you write and compile channel-exit programs for z/OS .

The exits are started 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. The new version is 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 is freed by a subsequent exit invocation.

    For storage that is to persist between invocations, use the z/OS STORAGE service, or the 4kmalc library function for System Programming C.

    For more information about this function, see 4kmalc() -- Allocate Page-Aligned Storage.

  • All IBM MQ MQI calls except MQCMIT or CSQBCMT and MQBACK or CSQBBAK can be used. 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 can issue commit and backout MQI calls. To issue such calls, code the verbs CSQXCMT and CSQXBAK in place of MQCMIT or CSQBCMT and MQBACK or CSQBBAK.

  • All exits that use stub CSQXSTUB from IBM WebSphere MQ Version 7.0 or later must be link-edited in a CSQXLIB load library with format PDS-E.
  • Exits must not use any system services that cause a wait, because using system services would severely affect the handling of some or all the other channels. Many channels are run under a single TCB typically. If you do something in an exit that causes a wait and we do not use MQXWAIT, it causes all these channels to wait. Causing channels to wait does not give any functional problems, but might have an adverse effect on performance. Most SVCs involve waits, so we must avoid them, except for the following SVCs:

    • GETMAIN/FREEMAIN/STORAGE
    • LOAD/DELETE

    In general, therefore, avoid SVCs, PCs, and I/O. Instead, use the MQXWAIT call.

  • Exits do not issue ESTAEs or SPIEs, apart from in any subtasks they attach, because their error handling might interfere with the error handling performed by IBM MQ. This means that IBM 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 ) provides a wait service that waits 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 must be ATTACHed, and its completion waited for by MQXWAIT; because of the processing that this technique incurs, this facility must be used only by the security exit.

  • The MQDISC MQI call does 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 IBM 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.

    CSQ4BCX3 and CSQ4BAX3
    These samples are written in C and assembler respectively.

    The CSQ4BCX3 sample (which is pre-compiled into the SCSQAUTH LOADLIB, should function with no changes necessary on the exit itself. We can create a LOADLIB (for example, called MY.TEST.LOADLIB) and copy the SCSQAUTH(CSQ4BCX3) member to it.

    To set up a security exit on a client connection, carry out the following procedure:
    1. Establish a valid OMVS segment for the user ID that the channel initiator uses.

      This allows the IBM MQ for z/OS channel initiator to use TCP/IP with the UNIX System Services (USS) socket interface, in order to facilitate exit processing. Note that it is unnecessary to define an OMVS segment for the user ID of any connecting client.

    2. Ensure that the exit code itself runs only in a program controlled environment. This means everything loaded into the CHINIT address space must be loaded from a program controlled library (meaning all libraries in the STEPLIB), and any libraries named on CSQXLIB and 
      ++hlq++.SCSQANLx 
++hlq++.SCSQMVR1 
++hlq++.SCSQAUTH
      To set a load library as program controlled, use a command similar to this example: 
      RALTER PROGRAM * ADDMEM('MY.TEST.LOADLIB'//NOPADCHK)
      Then we can activate or refresh the program controlled environment by issuing the command: 
      SETROPTS WHEN(PROGRAM) REFRESH
    3. Add the exit LOADLIB to the CSQXLIB DD (in the CHINIT started procedure), by issuing the following command: 
      ALTER CHANNEL(xxxx) CHLTYPE(SVRCONN)SCYEXIT(CSQ4BCX3)
      This activates the exit for the named channel.
    4. Your external security manager (ESM) lists any other libraries to be program controlled, but note that none of the ESM or C libraries needs to be under program control.

    See IBM MQ for z/OS server connection channel for further information on setting up a security exit using the sample CSQ4BCX3.

    CSQ4BCX4
    This sample is written in C and demonstrates using the RemoteProduct and RemoteVersion fields in MQCXP.

Parent topic: Writing channel-exit programs


Related concepts


Related information