mqsichangeflowuserexits command

Supported operating systems

Purpose

Use the mqsichangeflowuserexits command to set the list of active or inactive user exits. There is a list of active and a list of inactive user exits for each execution group and message flow. The effective state of user exits for a given flow is decided when the flow starts. It is decided by taking into account the list of active and inactive user exits for the flow and its execution group.

The order of precedence is message flow, execution group, and then broker default. The active list takes precedence over the inactive list in the message flow and execution group settings.

If the state for a given user exit is not set for the message flow, then its state is taken from the execution group setting. If its state is not set for the message flow or execution group, then it takes the default state which is implicitly inactive, or can be explicitly defined as active by the broker property activeUserExits, through the mqsichangebroker command.

If a particular user exit name is present in both the active and inactive lists for a message flow or execution group, then the active list takes precedence and the user exit is active for that level. Therefore, if you want to change a user exit from active to inactive you must specify it as part of the inactive list, by using the -i flag and also remove it from the active list by re-specifying the new active list by using the -a flag.

When multiple exits are active for a given flow, they are invoked in a defined order. Those exits in the message flow’s active list are invoked first in the order that they were specified on the -a flag.

After those have been invoked, the exits in the execution group’s active list (which were in neither the message flow’s active nor inactive list) are invoked. These are invoked in the order that they were specified on the -a flag.

All user exits that are not mentioned in the execution group’s or message flow’s active or inactive list, but are in the broker’s active list, are invoked in the order that they were specified when the broker property activeUserExits was set.

If any of the user exits specified in either the active or inactive list are not registered for the target execution group, the command fails with a BIP8858 error.

After successful command completion, if any user exits specified become invalid then, depending on which list the user exit appeared in, the following action is taken:
  • If the user exit was specified in the message flow’s active or inactive list, then the flow fails to start and a BIP2315 message is written to system log.
  • If the user exit was specified in the execution group’s active or inactive list, then the execution group fails to start and a BIP2314 message is written to system log.
This could happen for one of the following 3 reasons:
  • The broker or execution group is re-started after you change the MQSI_USER_EXIT_PATH variable by removing the directory containing the user exit library.
  • The broker or execution group is re-started after you change the userExitPath broker property by removing the directory containing the user exit library.
  • The user exit library (or one of its dependencies) is removed or broker is unable to load it.

Syntax

Parameters

brokername
(Required). The name of the broker.
-e egName
(Required). The name of the execution group.
-f messageflow
(Optional). The name of the message flow. If supplied, the user exit is changed for that message flow. If not supplied, the user exit is set at the execution group level.
-a activeUserExitNames
(Optional). A list of the names, separated by colons, of the active user exits. These are the names registered by the user exits when they were loaded. If any of the user exits listed are not registered for the target execution group, then the command fails with a BIP8858 error.
-i inactiveUserExitNames
(Optional).

A list of the names, separated by colons, of the inactive user exits. These are the names registered by the user exits when they were loaded. If any of the user exits listed are not registered for the target execution group, then the command fails with a BIP8858 error.

Authorization

The user ID that is used to invoke this command must have mqbrkrs group authority.

Responses

This command returns the following responses:
  • BIP8852 Usage statement
  • BIP80711 Successful command completion.
  • BIP8858 User exit names &1 not valid (where &1 is the name of the user exits that were specified on this command but are not valid because they have not been registered in the target execution group).

Examples

Setting active exits at flow level
mqsichangeflowuserexits WBRK_BROKER -e default -f myFlow -a exit2
BIP8071I: Successful command completion.
Setting inactive exits at flow level
mqsichangeflowuserexits WBRK_BROKER -e default -f myFlow -i exit1
BIP8071I: Successful command completion.
Setting active exits at execution group level
mqsichangeflowuserexits WBRK_BROKER -e default -a exit3,exit1
BIP8071I: Successful command completion.
Setting inactive exits at execution group level
mqsichangeflowuserexits WBRK_BROKER -e default -1 exit2
BIP8071I: Successful command completion.
Changing exit1 to inactive and leaving exit2 active at flow level (A command had previously been issued with "-a exit1:exit2" to set them both active)
mqsichangeflowuserexits WBRK_BROKER -e default -f myFlow -i exit1 -a exit2
BIP8071I: Successful command completion.
Related concepts
Developing user exits