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.
- --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.
- -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.
- -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
mqsichangeflowuserexits INODE -x C:\UserExitDirectory --offline
mqsichangeflowuserexits INODE -e default -k myApplication -f myFlow -a ""
mqsichangeflowuserexits INODE -e default -k myApplication -f myFlow -a exit1:exit2
mqsichangeflowuserexits INODE -e default -k myApplication -f myFlow -i exit3:exit4
mqsichangeflowuserexits INODE -e default -a exit1:exit3
mqsichangeflowuserexits INODE -e default -i exit2:exit4
mqsichangeflowuserexits INODE -e default -k myApplication -f myFlow -i exit1 -a exit2
mqsichangeflowuserexits --admin-host localhost --admin-port 7600 -k myApplication -f myFlow -a exit1:exit2
mqsichangeflowuserexits --admin-host localhost --admin-port 7600 -k myApplication -f myFlow -i exit3:exit4
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.