Writing exits and installable services on UNIX, Linux and Windows

We can write and compile exits without linking to any IBM MQ libraries on UNIX, Linux and Windows.

About this task

This topic applies to UNIX, Linux, and Windows systems only. For details on writing exits and installable services for other platforms, see the relevant platform specific topics.

If IBM MQ is installed in a non-default location you must write and compile your exits without linking to any IBM MQ libraries.

We can write and compile exits on UNIX, Linux, and Windows systems without linking any of these IBM MQ libraries:

• mqmzf
• mqm
• mqmvx
• mqmvxd
• mqic
• mqutl

Existing exits that are linked to these libraries continue to work, providing that on UNIX and Linux systems IBM MQ is installed in the default location.

Procedure

1. Include the cmqec.h header file. Including this header file automatically includes the cmqc.h, cmqxc.h and cmqzc.h header files.
2. Write the exit so that MQI and DCI calls are made through the MQIEP structure. For more information about the MQIEP structure, see MQIEP structure.
   • Installable services
     • Use the Hconfig parameter to point to the MQZEP call.
     • We must check that the first 4 bytes of Hconfig match the StrucId of the MQIEP structure before using the Hconfig parameter.
     • For more information about writing installable service components, see MQIEP.

   • API exits
     • Use the Hconfig parameter to point to the MQXEP call.
     • We must check that the first 4 bytes of Hconfig match the StrucId of the MQIEP structure before using the Hconfig parameter.
     • For more information about writing API exits, see Writing API exits.

   • Channel exits
     • Use the pEntryPoints parameter of the MQCXP structure to point to MQI and DCI calls.
     • We must check that the MQCXP version number is at version 8 or higher before using pEntryPoints.
     • For more information about writing channel exits, see Writing channel-exit programs.

   • Data conversion exits
     • Use the pEntryPoints parameter of the MQDXP structure to point to MQI and DCI calls.
     • We must check that the MQDXP version number is at version 2 or higher before using pEntryPoints.
     • We can use the crtmqcvx command and the amqsvfc0.c source file to create data conversion code that uses the pEntryPoints parameter. See Writing a data-conversion exit for IBM MQ for Windows and Writing a data-conversion exit for IBM MQ on UNIX and Linux systems.
     • If we have existing data conversion exits that were generated using the crtmqcvx command, we must regenerate the exit using the updated command.
     • For more information about writing data conversion exits, see Writing data-conversion exits.

   • Pre-connect exits
     • Use the pEntryPoints parameter of the MQNXP structure to point to MQI and DCI calls.
     • We must check that the MQNXP version number is at version 2 or higher before using pEntryPoints.
     • For more information about writing pre-connect exits, see Referencing connection definitions using a pre-connect exit from a repository.

   • Publish exits
     • Use the pEntryPoints parameter of the MQPSXP structure to point to MQI and DCI calls.
     • We must check that the MQPSXP version number is at version 2 or higher before using pEntryPoints.
     • For more information about writing publish exits, see Writing and compiling publish exits.

   • Cluster workload exits
     • Use the pEntryPoints parameter of the MQWXP structure to point to MQXCLWLN calls.
     • We must check that the MQWXP version number is at version 4 or higher before using pEntryPoints.
     • For more information about writing cluster workload exits, see Writing and compiling cluster workload exits.

   For example, in a channel exit calling MQPUT:

   pChannelExitParms -> pEntryPoints -> MQPUT_Call(pChannelExitParms -> Hconn,
                                                   Hobj,
                                                   &md,
                                                   &pmo, 
                                                   messlen,
                                                   buffer,
                                                   &CompCode,
                                                   &Reason);
   

   Further examples can be seen in the Use the IBM MQ sample procedural programs.
3. Compile the exit:
   • Do not link to the IBM MQ libraries.
   • Do not include an embedded RPath to any IBM MQ libraries in your exit.
   • For more information about compiling your exit, see one of the following topics:
     • API exits: Compiling API exits.
     • Channel exits, publish exits, Cluster workload exits: Compiling channel exit programs on Windows, UNIX and Linux systems.
     • Data conversion exits: Writing data-conversion exits.

4. Put the exit in one of the following places:
   • A path of our choosing that you fully qualify when configuring the exit
   • The default exit path, in a specific installation directory. For example, MQ_DATA_PATH/exits/installation2.
   • The default exit path The default exit path is MQ_DATA_PATH/exits for 32 bit exits, and MQ_DATA_PATH/exits64 for 64 bit exits. We can change these paths in the qm.ini or mqclient.ini file. For more information, see Exit path. On Windows and Linux, we can use the IBM MQ Explorer to change the path:
     1. Right click the queue manager name
     2. Click Properties...
     3. Click Exits
     4. In the exits default path field, specify the path name of the directory that holds the exit program.

   If an exit is placed in both a specific installation directory and in the default path directory, the specific installation directory exit is used by the installation of IBM MQ named in the path. For example, the exit is placed in /exits/installation2 and in /exits, but not in /exits/installation1. The IBM MQ installation installation2 uses the exit from /exits/installation2. The IBM MQ installation installation1 uses the exit from the /exits directory.

5. If necessary, configure the exit:
   • Installable services: Configure services and components.
   • API exits: Configure API exits.
   • Channel exits: Configure channel exits.
   • Publish exits: Configure publish exits.
   • Pre-connect exits: PreConnect stanza of the client configuration file.

• API exits not linked with an MQI library
  Under certain circumstances, we should link your existing API exit, that cannot be re-coded to use the MQIEP function pointers, with an IBM MQ API library.

Parent topic: User exits, API exits, and IBM MQ installable services