IBM App Connect Enterprise, Version 11.0.0.2 Operating Systems: Windows, Linux


mqsichangeproperties command

Use the mqsichangeproperties command to modify integration node properties and properties of integration node resources.

Supported platforms

  • Windows systems.
  • Linux and UNIX systems.

Purpose

Use the mqsichangeproperties command to change properties that are associated with an integration node:

  • Properties that affect the whole integration node; for example, an HTTP listener
  • Properties that affect one or more integration servers; for example, the integration node registry
  • Properties that affect a policy; for example, a JMS provider

You can also use web user interface or the IBM® Integration API to change properties.

Use the mqsireportproperties command to view properties that are associated with an integration node.

Usage notes

  • For most parameters of the mqsichangeproperties command, you must ensure that the integration node is running before you run the command. However, you can issue the -f parameter for an integration node that is running or stopped.
  • If you change one or more values, stop and start the integration node again for the change to take effect. This step does not apply to all policies. Check the documentation for the specific policy type. The documentation specifies when restarting the integration node is necessary.
  • When a message flow that includes HTTP nodes is started, the integration node starts the HTTP and HTTPS listeners, unless this listener has been disabled.
  • If you want to change the properties of a resource manager for a policy, and that resource manager requires WebSphere MQ, a queue manager must be associated with the integration node before you run the mqsichangeproperties command. For a list of features that require WebSphere MQ, see Enhanced flexibility in interactions with IBM MQ.

Syntax

Read syntax diagramSkip visual syntax diagram
>>-mqsichangeproperties--integrationNodeName-------------------->

>--+-----------------------------+-- -o --ObjectName------------>
   +- -b --ComponentName---------+                     
   +- -c --policy-type-----------+                     
   '- -e --integrationServerName-'                     

>-- -n --PropertyName--+- -v --PropertyValue-+--+-----+--------><
                       +- -p --Path.FileName-+  '- -f-'   
                       '- -d ----------------'            

Parameters

integrationNodeName
(Required) The name of the integration node to modify. This parameter must be the first parameter.
-b ComponentName
(Optional) The name of the component. Valid values are pubsub, NodeHttpListener, securitycache, cachemanager, webadmin, crlFile, agent. The properties associated with these components affect the whole integration node.
-c policy-type
(Optional) The short name for the type of policy to be changed. Supplied policy types have predefined short names; for example, JMSProviders for the JMS Providers policy type. For a list of supplied policies, and their properties and values, see Policy properties.

You must also specify the name of a policy on the -o parameter.

-e integrationServerName
(Optional) The name of the integration server for which you want to change properties.
-o ObjectName
(Required) The name of the object or policy for which you want to change the properties.

You must also specify -b, -e, or -c with -o, except if you specify the object name BrokerRegistry.

Specify ComIbmJVMManager to update the:
  • JVM settings of the HTTP listener or agent that you have specified with -b, or
  • JVM settings of the integration server that you specified with -e.
If you do not specify -b or -e when you specify ComIbmJVMManager, the JVM settings of all integration servers are updated.

For compatibility with previous versions, you can also specify the value ComIbmXmlParserFactory for the ObjectName.

-n PropertyName
(Required) The name of the property to be changed. The available property names differ according to the component or policy that you have specified. All property names start with a lowercase character. The property name must be a valid XML attribute name; for example, a property name cannot start with a number.

The property names for predefined policies are described in Policy properties.

If you specify a policy of type UserDefined, the PropertyName specified is created if it does not exist.

-v PropertyValue
(Required) The value that is assigned to the property that is specified by the -n parameter.

You can specify more than one property name together with a corresponding value, by using commas as separators, if you use a valid value for the corresponding property; for example, -n Name1,Name2 -v Value1,Value2.

Do not leave a space after each comma in the list of names and corresponding values. Use "" to specify an empty PropertyValue string.

If the property value contains a comma, enclose the value with escaped double quotation marks (\" and \"); for example, -n Name1,Name2 -v Value1,\"Value21,Value22\".

UNIX platformOn UNIX, if the -v parameter contains a semicolon (;), enclose the entire string in quotation marks, as shown in the following example:
mqsichangeproperties INODE -c JDBCProviders -o DB2EXTRA -n connectionUrlFormat
-v "jdbc:db2://[serverName]:[portNumber]/[databaseName]:user=[user];password=[password];"

If you set the -c parameter to EISProviders or JMSProviders, and the -n parameter to jarsURL, the expected value is a URL that specifies the file location of the EIS or JMS provider JAR files, but omits the file:// part of the URL. (On Windows, the file location cannot be a mapped network drive on a remote Windows computer; the directory must be local or on a Storage Area Network (SAN) disk.)

-p Path.FileName
(Optional) The location and name of a file from which the command reads the property value. Use this command as an alternative to -v where the value of the property is complex and is defined in a file, such as an XML or JSON file.
The following conditions apply to the use of this parameter:
  • -p can be used to set a single property only. Therefore, the -n parameter must have a single property name, not a comma-separated list.
  • White space characters (including line feed, carriage return, and end of file characters) read from the file are preserved by the command.

Use this parameter for policy sets and bindings.

Use this parameter for monitoring profiles; the XML file must conform to the monitoring profile schema.

-d
(Optional) This parameter is valid only if you specify a policy of type UserDefined. If the property that you specify on the -n parameter exists, it is deleted.

If you specify this parameter for other policies or components, an error is generated.

-f
(Optional) This parameter is valid only if you specify a property of an integration server level object. If the property that you specify on the -n parameter exists, its value is changed to the PropertyValue specified by the -v parameter.

You can use this parameter only when the integration server is in the stopped state. You can use the -f parameter when the integration node is running or stopped. You are advised to use this parameter only under the direction of IBM support to recover from integration server startup failures.

If you specify this parameter for other policies or components, an error is generated.

Authorization

For information about platform-specific authorizations, see the following topics: If you have enabled integration node administration security, you must also set up the authority that is detailed in Tasks and authorizations for administration security.

Examples

Always enter the command on a single line; in some examples, line breaks have been added to enhance readability.

Changes to integration node components

The following examples specify the -b parameter to identify a particular integration node component.

  • Disable the integration node HTTP listener:
    mqsichangeproperties INODE -b NodeHttpListener -o HTTPListener 
    			-n startListener -v false
  • Enable the integration node HTTP listener:
    mqsichangeproperties INODE -b NodeHttpListener -o HTTPListener 
    			-n startListener -v true
  • Enable the HTTPSConnector for the HTTP nodes deployed to the specified integration nodes that use the integration node listener:
     mqsichangeproperties INODE -b NodeHttpListener -o HTTPListener 
    			-n enableSSLConnector -v true
  • Change the default SSL protocol from TLS to TLSv1.2 for the HTTP nodes that are deployed to the specified integration node:
    mqsichangeproperties INODE  -b NodeHttpListener -o HTTPSConnector 
    			-n sslProtocol -v TLSv1.2 
  • Define CRL processing for HTTP-based input nodes that are deployed to the specified integration node using a CRL file located at file_path:
    mqsichangeproperties INODE -b NodeHttpListener -o HTTPSConnector 
    			-n crlFile -v file_path
  • Change the securitycache timeout to 200 seconds:
    mqsichangeproperties INODE -b securitycache -o SecurityCache 
    			-n cacheTimeout -v 200 
  • Disable the web user interface:
    mqsichangeproperties INODE -b webadmin -o server 
             -n enabled -v false 
  • Change the port number for the web user interface:
    mqsichangeproperties INODE -b webadmin -o HTTPSConnector  
             -n port -v new_port_number 
    You can change this property only when the integration node is running, and the change takes effect when the integration node is restarted.
  • Change the JVM heap size for the integration node:
    mqsichangeproperties INODE -o ComIbmJVMManager 
    -n jvmMaxHeapSize -v size_in_bytes
  • Enable event publication for an event type that belongs to the OperationalEvents event group. This example uses WebSphere MQ for the transport protocol:
    mqsichangeproperties INODE -b pubsub -o OperationalEvents/MQ 
    -n enabled -v true
  • Disable event publication for an event type that belongs to the OperationalEvents event group. This example uses WebSphere MQ as the transport protocol:
    mqsichangeproperties INODE -b pubsub -o OperationalEvents/MQ 
    -n enabled -v false
  • Specify a policy to control event publication, for an event type that belongs to the OperationalEvents event group. This example uses WebSphere MQ as the transport protocol:
    mqsichangeproperties INODE -b pubsub -o OperationalEvents/MQ 
    -n policyUrl -v /apiv1/policy/MQEndpoint/example_mq_policy
  • Set the format of an event publication for WebSphere MQ. This example sets the format of the event message to JMSBytesMessage:
    mqsichangeproperties INODE -b pubsub -o OperationalEvents/MQ 
    -n format -v none

Changes to properties that are associated with integration servers

The following examples include the -e parameter to specify the integration server to change.

  • Configure the integration server so that all deployed HTTP nodes use the embedded listener:
    mqsichangeproperties INODE -e integrationServerName -o ExecutionGroup  
    	-n httpNodesUseEmbeddedListener -v true

    If you disable the integration node listener (as shown in a previous example), you do not have to change the integration server configuration as shown in this command; if the integration node listener is not active, all integration servers use the embedded listener by default for all HTTP message handling.

  • Configure the integration server properties so that deployed HTTP nodes do not use the embedded listener:
    mqsichangeproperties INODE -e integrationServerName -o ExecutionGroup  
    	-n httpNodesUseEmbeddedListener -v false
  • Configure the integration server so that deployed SOAP nodes use the integration node listener rather than the embedded listener:
    mqsichangeproperties INODE -e integrationServerName -o ExecutionGroup  
    	-n soapNodesUseEmbeddedListener -v false
  • Configure the integration server so that deployed SOAP nodes use the embedded listener:
    mqsichangeproperties INODE -e integrationServerName -o ExecutionGroup  
    	-n soapNodesUseEmbeddedListener -v true

    If you disable the integration node listener (as shown in a previous example), you do not have to change the integration server configuration as shown in this command; if the integration node listener is not active, all integration servers use the embedded listener by default for all HTTP message handling.

  • Create and configure a connectivity agent in an integration server where you have deployed a callable flow. If your callable flows are deployed to different integration servers, you must run this command for each integration server:
    mqsichangeproperties integrationNodeName -e integrationServerName -o ComIbmIIBSwitchManager -n agentXConfigFile -p filepath\agentx.json
  • Configure the time to wait before the next message is retrieved from an input node after a message has been rolled back. wait_time is the time to wait in milliseconds.
    mqsichangeproperties INODE -e integrationServerName -o ExecutionGroup 
    -n failedMessageWaitTime -v wait_time
    Note: failedMessageWaitTime applies only to errors that occur downstream of an input node and only if it is set to a non-default value. The default value is 1000 milliseconds.
  • Set the port number when changing properties for integration servers:
    mqsichangeproperties INODE -e integrationServerName -o HTTPSConnector  
    		-n explicitlySetPortNumber -v 7777 
  • Set the list of ciphers allowed by the HTTPS listener of the integration server:
    mqsichangeproperties INODE -e integrationServerName 
    -o HTTPSConnector -n ciphers 
    -v \"SSL_RSA_WITH_RC4_128_MD5,SSL_RSA_WITH_RC4_128_SHA\"
    On distributed systems, if the property value contains a comma, enclose the value with escaped double quotation marks (\" and \"); for example:
    -v \"SSL_RSA_WITH_RC4_128_MD5,SSL_RSA_WITH_RC4_128_SHA\"
    On z/OS®, if the property value contains a comma, enclose the value with double quotation marks (" and "); for example:
    -v "SSL_RSA_WITH_RC4_128_MD5,SSL_RSA_WITH_RC4_128_SHA"
  • Add a certificate revocation list (CRL) file from location file_path for the HTTPS listener of the integration server:
    mqsichangeproperties INODE -e integrationServerName -n crlFile -v file_path
  • Configure the JVM to automatically download any CRL files (from CRL distribution points that are specified in the CA's digital signature):
    mqsichangeproperties INODE -e integrationServerName -o ComIbmJVMManager -n enableCRLDP -v true
  • Set the JVM port number to activate message flow debugging:
    mqsichangeproperties INODE -e integrationServerName -o ComIbmJVMManager 
    	-n jvmDebugPort -v 8018 
  • Change the JVM heap size for the integration server:
    mqsichangeproperties INODE -e integrationServerName -o ComIbmJVMManager 
    -n jvmMaxHeapSize -v size_in_bytes
  • Set the type of server keystore:
    mqsichangeproperties INODE -e AddressSampleProvider 
    	-o ComIbmJVMManager 
    	-n keystoreType -v JKS
  • Set the coordination queue manager to QM2 for integration server integrationServerName in integration node INODE:
    mqsichangeproperties INODE -e integrationServerName
    -o FTEAgent -n coordinationQMgr -v QM2
    Note: After running this command, you must reload the integration server for the change to take effect.
  • Set the way XMLNSC serialization renders characters that do not exist in the target code page:
    mqsichangeproperties INODE -e integrationServerName 
    -o ComIbmGenericXmlParserFactory -n invalidCharacterEscapeType -v character_type
    where character_type specifies how to render the character:
    • unicode renders the character as {U+XXXX}, where XXXX is the Unicode code point associated with the character. For example, the euro character would be rendered as {U+20AC}.
    • hex renders the character as &#xXXXX, where XXXX is the Unicode code point associated with the character. For example, the euro character would be rendered as &#x20AC.
    • decimal renders the character as #DDDD, where DDDD is the Unicode code point associated with the character expressed in decimal. For example, the euro character would be rendered as #8364.
  • Configure the expiry compensation to prevent messages from immediately expiring when put:
    mqsichangeproperties INODE -e default 
    -o ComIbmMQConnectionManager -n expiryCompensation -v option
    where option specifies if the expiry compensation is active or not:
    • false This option is the default value. No adjustment is applied to the expiry
    • true This option causes the expiry to be reduced by the amount of time that the message has spent in the flow at the time that the MQPUT call is made by the MQOutput Node.
  • Enable resource statistics to be reported to IBM Cloud Log Analysis:
    mqsichangeproperties INODE -e integrationServerName 
    -o ComIbmResourceStatsManager -n bluemixReporting -v active
  • Enable resource statistics to be reported to the filesystem:
    mqsichangeproperties INODE -e integrationServerName 
    -o ComIbmResourceStatsManager -n fileReporting -v active

Changes to the BrokerRegistry object

  • Set the HTTPConnector Port Range in the integration node registry:
    mqsichangeproperties INODE -o BrokerRegistry 
    	-n httpConnectorPortRange -v 7777-8888 
  • Configure the path to the CRL files that the JVM uses to check certificates, where file_path is a list of paths to CRL files separated by the path separator character for the host operating system.
    mqsichangeproperties INODE -o BrokerRegistry -n crlFileList -v file_path
  • Configure the file path to a WebSphere MQ CCDT file in the integration node registry:
    mqsichangeproperties INODE -o BrokerRegistry 
    	-n mqCCDT -v "C:\Program Files (x86)\IBM\WebSphere
        MQ\Qmgrs\QM1\@ipcc\AMQCLCHL.TAB"
    When you have set the mqCCDT property, restart the integration node for the changes to take effect.
  • Configure the path to the key repository, when you have specified SSL to be used on an MQInput, MQOutput, MQGet, or MQReply node. This value is specified as the full file path of the SSL key repository minus the .kdb file extension. For example, if the SSL key repository is C:\SSL\key.kdb, set the location of the key repository by using the following command:
    mqsichangeproperties INODE -o BrokerRegistry -n mqKeyRepository -v C:\SSL\key
    The SSL key repository is created using the WebSphere MQ GSKit.

Changes to properties of policies


an09140_.htm | Last updated 2018-11-02 14:45:58