Deploying a user exit

Deploy your user exit to the integration node.

Before you begin

  • Write and compile the user exit code. See Developing a user exit.
  • Ensure that the exit:
    1. Is in a library that has the extension .lel
    2. Exports the functions bipInitializeUserExits and bipTerminateUserExits

About this task

You can set the state of the user exit dynamically to active, or inactive, on a per-message flow basis without restarting the integration node.

You can set the state of the user exit dynamically to active, or inactive, for an independent integration server or an integration server that is managed by an integration node. You do not have to restart the integration node.

You can set the state of the user exit dynamically to active, or inactive, for an integration node. You must start the integration node.

To deploy the user exit:

Procedure

  1. Install the user exit code on an integration node.

    The library that contains the user exit code must be installed on a file system that can be accessed by the integration node. For example, the file must have read and execute authority for the user ID under which the integration node runs. The integration node looks in the following places for libraries that contain user exits:

    • The userExitPath property of the integration node.
      The integration node property userExitPath defines a list of directories that are separated by colons (semicolons on Windows). You can set this property by using one of the following methods:
      • Set the userExitPath property when you create a new integration node, use the -x flag on the mqsicreatebroker command.
      • Set the userExitPath property for an existing integration node, use the -x flag on the mqsichangeflowuserexits command.
      • Set the userExitPath property for an existing integration node by modifying the entry in the node.conf.yaml file for the integration node.
    • The environment variable MQSI_USER_EXIT_PATH.

      Append the directory that contains extension files to the environment variable MQSI_USER_EXIT_PATH associated with the environment in which the integration node is running.

    If the userExitPath property and the environment variable MQSI_USER_EXIT_PATH are both set, the environment variable takes precedence. All the directories in the environment variable are searched in the order in which they appear in the variable. Then, all the directories in the integration node property are searched in the order in which they appear in the property.

  2. Load the user exit library into the integration node's processes.
    When the user exit library is installed on the integration node, you must load it in one of the following ways:
    • Stop and restart the integration node.
    • Run the mqsireload command to restart the integration server processes.
  3. Activate the user exit.

    User exits can be active or inactive, and are inactive by default. You can change the state of a user exit dynamically by updating the node.conf.yaml file, or by using the mqsichangeflowuserexits command. You must restart the integration node.

    To set the default user exit state for an integration node:

    1. Stop the integration node.
    2. Set the --active-user-exit-list property of the integration node by using one of the following methods:
      • Modify the activeUserExitList property in the node.conf.yaml file.
      • Use the -x flag on the mqsichangeflowuserexits command.
    3. Start the integration node and check the system log to ensure that all integration servers start without error.
      If you specify any user exit names that are not provided by any library that is loaded by the integration server, a BIP2314 message is written to the system log. All flows that are in the integration servers fail to start.
    4. Optional: If a BIP2314 message is written to the system log and the flows in the integration servers fail to start, take one of the following actions:
      • Provide a library in the user exit path that implements the exit. Then, run the mqsireload command, or restart the integration node, to load an exit from the library.
      • Run the mqsichangeflowuserexits command to remove the exit from both the active and inactive lists.

    You can also override the default user exit state for an integration node. You can use the mqsichangeflowuserexits command to activate, or deactivate, user exits on a per-integration node, per-integration server, or per-message flow basis. The order of precedence is message flow then integration server, then integration node. When multiple exits are active for a flow, the integration node starts them in the order that is defined by the mqsichangeflowuserexits command.