mqsichangeflowuserexits command - Windows, Linux, and AIX systems

Use the mqsichangeflowuserexits command on Windows, Linux®, and AIX® systems to set the list of active or inactive user exits. A list of active and a list of inactive user exits is maintained for each integration node, each integration server, and each message flow. The effective state of user exits for a specified flow is decided when the flow starts.

Syntax

Some parameters have alternative names; for example, -e and --integration-server are alternative parameter names of the integration server. The long names and short names available are listed in the Parameters section.

Syntax for use with integration nodes (local integration nodes only)

Syntax for use with an integration server under an integration node

Syntax for use with an independent integration server

Parameters

integrationNodeName

This parameter identifies the name of a specific integration node. To connect to a remote integration node by name, you must also specify --admin-host and (optionally) --admin-port.

-n integrationNodeFileName | --integration-node-file integrationNodeFileName

This parameter identifies the name of a .broker file that contains the connection details for an integration node or independent integration server. Include the location (path) and file name when you specify this parameter. You must ensure that the location is accessible when you run this command.

The file can be used to connect to an independent integration server if:

The connection details do not include a node name (integrationNodeName)
The host and port are for an independent integration server.

Use this option if multiple users want to connect to the same integration node or integration server, or if you are using advanced connection parameters such as SSL. For more information, see Connecting to an integration node by creating a .broker file.

You can run a command that uses SSL to administer a remote integration node or integration server over a secured channel. You must specify the keystore and truststore password for the connection that is using the IBM_JAVA_OPTIONS environment variable. For more information, see Resolving problems when running commands.

--admin-host ipAddress, --admin-port port

These parameters identify a host and port for an integration node or independent integration server, for connections that do not require advanced connection parameters.

To connect to a specific remote integration node by name, you can add the prefix integrationNodeName. You cannot use -n integrationNodeFileName in the same command.

For an integration node, any parameters that you omit assume default values.

--admin-host ipAddress: The hostname or IP address of the computer on which the integration node or server is running. If you do not specify this parameter, a value that represents the local computer is used.
To connect to an independent integration server, the value is the host that you specified in the adminRestApiHost property in the server.conf.yaml configuration file for the integration server.

If you want to connect to a secured integration node or server as a specific user, provide the security credentials as a URI in the following format: tcp://user:password@hostname. If your password contains URI Reserved characters, you must convert these characters to the percent-encoded format. For more information, see A correct URL and password returns error BIP1939 when you attempt to connect to a remote host name in Resolving problems when running commands.
--admin-port port: The port on which the web user interface HTTP connection listener is listening. If you do not specify this parameter, the value 4414 is used.
To connect to an independent integration server, the value is the port that you set for the adminRestApiPort property in the server.conf.yaml configuration file. The default value is 7600.

-a | --active-user-exit-list activeUserExitNames

(Optional). A list of the names, which are separated by colons, of the active user exits. These names were registered when the user exits were loaded. If any of the user exits listed are not registered for the target integration node or the target integration server, then the command fails with a BIP8858 error. This parameter can be applied only to an integration node or an integration server. You can clear the list of active user exits by supplying a blank list ("") as the value for activeUserExitNames.

-e | --integration-server integrationServerName

(Required for an integration server that is managed by an integration node). The name of the integration server.

-f | --flow MessageFlow

(Optional). The name of the message flow.

When you set this parameter, you must also set the -k (application name) parameter.

If you supply this value, the user exit is changed for that message flow; if you do not, the user exit is set at the integration server level.

-i | --inactive-user-exit-list inactiveUserExitNames

(Optional). A list of the names, which are separated by colons, of the inactive user exits. These names were registered when the user exits were loaded. If any of the user exits listed are not registered for the target integration node or the target integration server, then the command fails with a BIP8858 error. This parameter can be applied only to an integration node or an integration server. You can clear the list of inactive user exits by supplying a blank list ("") as the value for inactiveUserExitNames.

-k | --application applicationName

(Optional) This parameter specifies the name of the application that contains the message flow for which the user exit is changed.

When you set this parameter, you must also set the -f (message flow) parameter. To change the user exit for a named message flow in a specific application, set the -k and -f parameters.

You can use this parameter with the -y (library name) parameter to specify that the message flow is contained in a library that is referenced by the application.

--non-persist

(Optional) By default, changes are preserved after a server restart. This parameter ensures that changes will not be preserved after a server restart. It cannot be used for integration nodes, and it cannot be used with the --offline parameter.

-o | --offline

(Optional) This parameter enables the command to run when the integration node is stopped. It cannot be used for an independent integration server or an integration server that is supported by an integration node.

-v | --trace traceFileName

(Optional) Sends internal debug trace information to the specified file.

-x | --user-exit-path userExitPath

(Optional) This parameter specifies the full path name of the directory from which the integration node searches for all user exits. This path is added to the system library search path (PATH,LIBPATH,LD_LIBRARY_PATH,SHLIBPATH) for the integration node process only. If you use this parameter, you must also specify the --offline parameter. This parameter cannot be used for an integration server that is supported by an integration node or an independent integration server.

Note: You must set the user exit path for an independent integration server by completing the following steps:

Stop the independent integration server. For more information, see Stopping an integration server.
Edit the server.conf.yaml file to show the full path name of the directory from which the independent integration server searches for all user exits:
```
UserExits:
            userExitPath: 'C:\Program Files\IBM\ACE\11.0.0.x\server\sample\extensions\userexits\transport'
```
Start the integration server. For more information, see Starting an integration server.

-y | --library libraryName

(Optional) This parameter specifies the name of the library that contains the message flow for which the user exit is changed.

When you set this parameter, you must also set the -k (application name) and -f (message flow) parameters. To set the active or inactive user exits for a named message flow in a specific library, set the -y, -k, and -f parameters.

Examples

Setting the user exit path for an integration node. You must stop the integration node before you set the user exit path:

mqsichangeflowuserexits INODE -x C:\UserExitDirectory --offline

Clear active exits at flow level:

mqsichangeflowuserexits INODE -e default -k myApplication -f myFlow -a ""

Setting active exits at flow level:

mqsichangeflowuserexits INODE -e default -k myApplication -f myFlow -a exit1:exit2

Setting inactive exits at flow level:

mqsichangeflowuserexits INODE -e default -k myApplication -f myFlow -i exit3:exit4

Setting active exits at integration server level:

mqsichangeflowuserexits INODE -e default -a exit1:exit3

Setting inactive exits at integration server level:

mqsichangeflowuserexits INODE -e default -i exit2:exit4

Changing exit1 to inactive and leaving exit2 active at flow level (A command was previously run with "-a exit1:exit2" to set them both active):

mqsichangeflowuserexits INODE -e default -k myApplication -f myFlow -i exit1 -a exit2

Setting active exits at flow level for an independent integration server:

mqsichangeflowuserexits --admin-host localhost --admin-port 7600 -k myApplication -f myFlow -a exit1:exit2

Setting inactive exits at flow level for an independent integration server:

mqsichangeflowuserexits --admin-host localhost --admin-port 7600 -k myApplication -f myFlow -i exit3:exit4

Setting active exits for an independent integration server, capturing trace and making the changes non-persistent.

mqsichangeflowuserexits --admin-host localhost --admin-port 7600 -a exit5:exit6 --trace C:\myTraceFile.txt --non-persist

To run this example, you must first set the user exit path for the independent integration server. For more information, see the advice in the Parameters section.