createWMQConnectionFactory command

Use the createWMQConnectionFactory command to create a connection factory for the WebSphere MQ messaging provider at a specific scope.

To run the command, use the AdminTask object of the wsadmin scripting client.

The wsadmin scripting client is run from Qshell. For more information, see the topic "Configure Qshell to run WebSphere Application Server scripts".

This command is valid only when it is used with WebSphere Application Server Version 7 and later application servers. Do not use it with earlier versions.

For a list of the available WebSphere MQ messaging provider administrative commands, plus a brief description of each command, enter the following command at the wsadmin prompt:

print AdminTask.help('WMQAdminCommands')

For overview help on a given command, enter the following command at the wsadmin prompt:

print AdminTask.help('command_name')

After using the command, save the changes to the master configuration. For example, use the following command:

AdminConfig.save()

Purpose

Use the createWMQConnectionFactory command to create a WebSphere MQ messaging provider connection factory at a specific scope.

We cannot create a WebSphere MQ messaging provider connection factory under either of the following conditions:

• A WebSphere MQ messaging provider connection factory already exists with the same name, at the same scope.

• The JNDI name clashes with another entry in WebSphere Application Server JNDI.

Target object

The scope of the WebSphere MQ messaging provider at which the WebSphere MQ messaging provider connection factory is to be created.

Required parameters

-name

The administrative name assigned to this WebSphere MQ messaging provider connection factory.

-jndiName

The name and location used to bind this object into WebSphere Application Server JNDI.

-type

Determine whether a unified connection factory, a queue connection factory or a topic connection factory is to be created.

Enter one of the following values:

• CF

• QCF

• TCF

CF is the default value.

If we specify QCF, we cannot specify any of the following parameters:

• brokerCtrlQueue

• brokerSubQueue

• brokerCCSubQueue

• brokerVersion

• brokerPubQueue

• tempTopicPrefix

• pubAckWindow

• subStore

• stateRefreshInt

• cleanupLevel

• sparesSubs

• wildcardFormat

• brokerQmgr

• clonedSubs

• msgSelection

If we specify TCF, we cannot specify any of the following parameters:

• msgRetention

• rescanInterval

• tempQueuePrefix

• modelQueue

• replyWithRFH2

Optional parameters

-description

An administrative description assigned to the connection factory.

-ccdtUrl

A URL to a client channel definition table to use, for this connection factory, when contacting WebSphere MQ.

Use this parameter to create a ccdtURL connection factory

Do not specify this parameter in conjunction with the following parameters: -qmgrName, -qmgrHostname, -qmgrPortNumber, -qmgrSvrconnChannel, wmqTransportType or -localAddress.

-ccdtQmgrName

A queue manager name, used to select one or more entries from a client channel definition table.

Do not specify this parameter in conjunction with the following parameters: -qmgrName, -qmgrHostname, -qmgrPortNumber, -qmgrSvrconnChannel, wmqTransportType, or -localAddress.

-qmgrName

The name of the queue manager to use, for this connection factory, when connecting with WebSphere MQ.

Use this parameter to create a generic connection factory.

Do not specify this parameter in conjunction with the following parameters: -ccdtUrl or -ccdtQmgrName.

-wmqTransportType

This parameter determines the way in which a connection is established to WebSphere MQ for this connection factory.

Use this parameter to create a generic connection factory.

Enter one of the following values:

• BINDINGS

• BINDINGS_THEN_CLIENT

• CLIENT

The default value is BINDINGS_THEN_CLIENT.

Do not specify this parameter in conjunction with the following parameters: -ccdtUrl or -ccdtQmgrName.

For more information about configuring a transport type of BINDINGS_THEN_CLIENT or BINDINGS, refer to Configure the WebSphere MQ messaging provider with native libraries information.

-qmgrHostname

The host name to use, for this connection factory, when attempting a client mode connection to WebSphere MQ. It must be a valid TCP/IP host name or IPv4 or IPv6 address.

The default value is the local host.

Do not specify this parameter in conjunction with the following parameters: -ccdtUrl or -ccdtQmgrName.

For information on setting the -qmgrHostname parameter in conjunction with the -connectionNameList parameter, see the description of the -connectionNameList parameter.

-qmgrPortNumber

The port number to use, for this connection factory, when attempting a client mode connection to WebSphere MQ.

Enter an integer value in the range 1 - 65536 (inclusive).

The default value is 1414.

Do not specify this parameter in conjunction with the following parameters: -ccdtUrl or -ccdtQmgrName.

For information on setting the -qmgrPortNumber parameter in conjunction with the -connectionNameList parameter, see the description of the -connectionNameList parameter.

-connectionNameList

The connection name list specifying the host name and port details to use when we want the connection factory to connect to a multi-instance queue manager.

We must only use the -connectionNameList parameter to allow a connection to a multi-instance queue manager. Using the -connectionNameList parameter to connect to a non-multi-instance queue manager can jeopardize transaction integrity.

The -connectionNameList parameter must be entered as a comma separated list of host names and ports in the following format:

host(port),host(port)

For host enter a valid TCP/IP host name, IPv4 or IPv6 address.

For port enter an integer value between 1 and 65536 (inclusive). Specifying a value for port is optional. When we do not specify a value, port defaults to 1414.

For example: localhost(1234),remotehost1(1234),remotehost2

When specified the -connectionNameList parameter, the -qmgrHostname and -qmgrPortNumber parameters are automatically set to the host name and port number of the first entry in the connection name list. This overrides any values that you previously specified in the -qmgrHostname and -qmgrPortNumber parameters.

In the preceding example this would mean that -qmgrHostname would be localhost and -qmgrPortNumber would be 1234.

The -connectionNameList parameter is only valid for use in WAS v8.0 or later. Attempting to specify the -connectionNameList parameter on a WebSphere MQ messaging provider connection factory which is defined at a server or node scope running on a version of WAS earlier than Version 8.0 results in an error message when you run the following commands:

• createWMQConnectionFactory

• modifyWMQConnectionFactory

If a WebSphere MQ messaging provider connection factory based on a connection name list is used by an application client or server running a version of WAS earlier than Version 8.0, the -connectionNameList information is not used. Instead, the values specified in the -qmgrHostname and qmgrPortNumber are used, and are set to the relevant values from the first entry in the connectionNameList parameter.

We must not specify the connectionNameList parameter in conjunction with the -ccdtUrl or -ccdtQmgrName parameters.

If we use the-connectionNameList parameter with a centrally managed SSL configuration, the host name and port number information used to select the appropriate SSL configuration is based on the first entry in the connection name list, regardless of which entry in the list is actually used to connect to the queue manager. This is because each instance of a multi-instance queue manager should be using the same SSL configuration, for a given server connection channel, regardless of which instance is actually running.

For more information on using multi-instance queue managers see the WebSphere MQ information center.

-containerAuthAlias

The container-managed authentication alias, defined to the cell, from which security credentials are used to establish a connection to WebSphere MQ.

-componentAuthAlias

The component-managed authentication alias, defined to the cell, from which security credentials are used to establish a connection to WebSphere MQ.

-clientId

The client identifier used for connections started by using this connection factory.

-providerVersion

This parameter determines the minimum version, and capabilities of the queue manager.

Enter values in one of the following formats:

• n

• n.n

• n.n.n

• n.n.n.n

where n is an integer greater than or equal to zero.

For example 6.0.0.0

-sslCrl

This parameter specifies a list of LDAP servers used to provide certificate revocation information if this connection factory establishes an SSL based connection to WebSphere MQ.

-sslResetCount

This parameter is used when the connection factory establishes an SSL connection to the queue manager. This parameter determines how many bytes to transfer before resetting the symmetric encryption key used for the SSL session.

Enter a value in the range 0 through 999,999,999.

The default value is 0.

-sslPeerName

This parameter is used when the connection factory establishes an SSL connection to the queue manager. The value is compared with the distinguished name present in the peer's certificate.

-rcvExit

A comma-separated list of receive exit class names.

-rcvExitInitData

Initialization data to pass to the receive exit.

Do not specify this parameter unless specified the -rcvExit parameter.

-sendExit

A comma-separated list of send exit class names.

-sendExitInitData

Initialization data to pass to the send exit.

Do not specify this parameter unless specified the -sendExit parameter.

-secExit

A security exit class name.

-secExitInitData

Initialization data to pass to the security exit.

Do not specify this parameter unless specified the -secExit parameter.

-compressHeaders

This parameter determines if message headers are compressed.

Enter one of the following values:

• NONE

• SYSTEM

The default value is NONE.

-compressPayload

This parameter determines if message payloads are compressed.

Enter one of the following values:

• NONE

• RLE

• ZLIBFAST

• ZLIBHIGH

The default value is NONE.

-msgRetention

This parameter determines if the connection consumer keeps unwanted messages on the input queue.

Enter one of the following values:

• YES

• NO

where YES specifies that the connection consumer keeps unwanted messages on the input queue, and NO specifies that the messages are disposed of according to their disposition options.

The default value is YES.

-pollingInterval

This property is applicable in the client container only.

If each message listener within a session has no suitable message on its queue, this parameter is the maximum interval, in milliseconds, that elapses before each message listener tries again to get a message from its queue. If it frequently happens that no suitable message is available for any of the message listeners in a session, consider increasing the value of this parameter.

The default value is 5000.

-rescanInterval

When a message consumer in the point-to-point domain uses a message selector to select which messages it is to receive, the JMS client searches the WebSphere MQ queue for suitable messages in the sequence determined by the MsgDeliverySequence attribute of the queue. When the client finds a suitable message and delivers it to the consumer, the client resumes the search for the next suitable message from its current position in the queue. The client continues to search the queue in this way until it reaches the end of the queue, or until the interval of time in milliseconds, as determined by the value of this -rescanInterval parameter has expired. In each case, the client returns to the beginning of the queue to continue its search, and a new time interval commences

This parameter must be a positive integer value.

The default value is 5000.

-ccsid

The coded character set identifier (CCSID) to be used on connections.

Value must be a positive integer. See the WebSphere MQ messaging provider connection factory advanced properties for more details.

The default value is 819.

-failIfQuiescing

This parameter determines the behavior of certain calls to the queue manager when the queue manager is put into quiescing state.

Value must be true or false.

true specifies that calls to certain methods fail if the queue manager is in a quiescing state. If an application detects that the queue manager is quiescing, the application can complete its immediate task and close the connection, allowing the queue manager to stop.

false specifies that no methods fail if the queue manager is in a quiescing state. If we specify this value, an application cannot detect that the queue manager is quiescing. The application might continue to perform operations against the queue manager, and therefore prevent the queue manager from stopping.

The default value is true.

-brokerCtrlQueue

The name of the broker control queue to use if this connection factory is to subscribe to a topic.

The default value is SYSTEM.BROKER.CONTROL.QUEUE.

-brokerSubQueue

The name of the queue to use for obtaining subscription messages if this connection factory is to subscribe to a topic.

The default value is SYSTEM.JMS.ND.SUBSCRIBER.QUEUE.

-brokerCCSubQueue

The name of the queue from which non-durable subscription messages are retrieved for a ConnectionConsumer.

The default value is SYSTEM.JMS.ND.CC.SUBSCRIBER.QUEUE.

-brokerVersion

The value of this parameter determines the level of functionality required for publish/subscribe operations.

Valid values are 1 and 2.

The default value is 1.

-msgSelection

This parameter determines where message selection occurs.

Valid values are CLIENT and BROKER.

The default value is CLIENT.

-subStore

This parameter determines where WebSphere MQ messaging provider stores persistent data relating to active subscriptions.

Valid values are MIGRATE, QUEUE and BROKER.

The default value is MIGRATE.

-stateRefreshInt

The interval, in milliseconds, between refreshes of the long running transaction that detects when a subscriber loses its connection to the queue manager. This parameter is relevant only if -subStore parameter has the value QUEUE.

Value must be a positive integer.

The default value is 60,000.

-cleanupLevel

The cleanup level for BROKER or MIGRATE subscription stores

Valid values are SAFE, NONE, ASPROP, and STRONG.

The default value is SAFE.

-cleanupInterval

The interval between background executions of the publish/subscribe cleanup utility.

Value must be a positive integer.

The default value is 3,600,000.

-wildcardFormat

This parameter determines which sets of characters are interpreted as topic wildcards.

Valid values are Topic or Char.

The default value is Topic.

-sparseSubs

This parameter controls the message retrieval policy of a TopicSubscriber object.

Value must be true or false

The default value is false.

-brokerQmgr

The name of the queue manager running the broker, if it is not the same as the queue manager to which the connection factory connects.

There is no default value.

-clonedSubs

This parameter determines whether two or more instances of the same durable topic subscriber can run simultaneously

Value must be ENABLED or DISABLED

The default value is DISABLED.

-customProperties

This parameter specifies custom properties to be passed to the WebSphere MQ messaging provider connection factory implementation. Typically, custom properties are used to set attributes of the connection factory that are not directly supported through the WebSphere administration interfaces.

Each custom property is specified using name and value table step parameters. Since these are table steps, the order of the two parameters is fixed, so you must always specify the name first and the value second:

• In Jython: [name value]

• In Jacl: {name value}

-qmgrSvrconnChannel

The SVRCONN channel to use when connecting to WebSphere MQ.

Use this parameter to create an explicitly defined connection factory.

The default value is SYSTEM.DEF.SVRCONN.

Do not specify this parameter in conjunction with the following parameters: -ccdtUrl or -ccdtQmgrName.

-support2PCProtocol

This parameter determines if the connection factory acts as a resource that is capable of participation in distributed two-phase commit processing.

Value must be True or False.

The default value True specifies that the connection factory acts as a resource that is capable of participation in distributed two-phase commit processing.

-modelQueue

The name of the WebSphere MQ model queue whose definition is used as a basis when creating JMS temporary destinations.

The default value is SYSTEM.DEFAULT.MODEL.QUEUE.

-tempQueuePrefix

The prefix to apply to WebSphere MQ temporary queues used to represent JMS temporary queue type destinations.

There is no default value.

-tempTopicPrefix

The prefix to apply to the names generated for temporary topics. This parameter is only valid for connection factories or topic connection factories.

There is no default value.

-replyWithRFH2

This parameter determines whether, when sending a reply message to the reply-to queue obtained from a message that does not include an RFH version 2 header, a RFH version 2 header is included in the reply message.

Value must be ALWAYS or AS_REPLY_DEST

The default value is AS_REPLY_DEST.

-brokerPubQueue

The name of the queue to which to send publication messages when using queue based brokering.

The default value is SYSTEM.BROKER.DEFAULT.STREAM.

-pubAckInterval

The number of publications to send to a queue based broker before sending a publication that solicits an acknowledgment.

Value must be a positive integer greater than zero.

The default value is 25.

-sslType

This parameter determines the configuration, if any, to use when applying SSL encryption to the network connection to the queue manager.

Value must be CENTRAL, SPECIFIC or NONE

The default value is NONE.

The sslConfiguration parameter is not valid unless this parameter is set to the value SPECIFIC.

-sslConfiguration

The name of the SSL configuration to use when using SSL to secure network connections to the queue manager.

Value must correspond to an SSL configuration.

Do not specify this parameter unless the parameter -sslType is assigned the value SPECIFIC.

-localAddress

This parameter specifies either or both of the following:

• the local network interface

• the local port, or range of local ports

Do not specify this parameter in conjunction with the following parameters: -ccdtUrl or -ccdtQmgrName.

-mappingAlias

The JAAS mapping alias used when determining which security credentials to use when establishing a connection to WebSphere MQ.

The default value is DefaultPrincipleMapping.

-xaRecoveryAuthAlias

The authentication alias from which credentials are taken and used to connect to WebSphere MQ for XA recovery.

There is no default value.

Minimal connection factory definition

In the following examples, code blocks beginning with wsadmin> show code that is entered by the user. Lines that do not begin with wsadmin> show code that has been returned by the console.

The following example creates an connection factory, specifying the minimum number of parameters. Due to the default values assumed for the unspecified parameters, applications using this connection factory expect to be co-located with a queue manager installed on the same node.

• Jython:
  wsadmin>AdminConfig.getid("/Node:9994GKCNode01")
  9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)

  wsadmin>AdminTask.createWMQConnectionFactory("9994GKCNode01(cells/
  9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)", ["-name cf1
   -jndiName 'jms/cf/cf2' -type CF"])  

  cf1(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml#
  MQConnectionFactory_1205322636000)

• Jacl:
  wsadmin>$AdminConfig getid /Node:9994GKCNode01
  9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)
  wsadmin>$AdminTask createWMQConnectionFactory 9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1) {-name cf1 -jndiName "jms/cf/cf1" -type CF}

  cf1(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml#
  MQConnectionFactory_1205322636000)

Explicitly defined connection factory

The following example creates an connection factory for which the user must specify and maintain all the parameters used for establishing a connection to WebSphere MQ.

• Jython:
  wsadmin>AdminConfig.getid("/Node:9994GKCNode01")
  9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)

  wsadmin>AdminTask.createWMQConnectionFactory("9994GKCNode01(cells/
  9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)", ["-name cf2
   -jndiName 'jms/cf/cf2' -type CF -description 'Must remember to keep each  of these connection factories in sync with the WebSphere MQ queue manager  to which they refer' -qmgrName QM1 -qmgrHostname 192.168.0.22 -qmgrPortNumber 1415
   -qmgrSvrconnChannel QM1.SVRCONN"])  

  cf2(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml#
  MQConnectionFactory_120532263601)

• Jacl:
  wsadmin>$AdminConfig getid /Node:9994GKCNode01
  9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)
  wsadmin>$AdminTask createWMQConnectionFactory 9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1) {-name cf2 -jndiName "jms/cf/cf2" -type CF -description "Must remember to keep each of these connection factories in sync with the WebSphere MQ queue manager to which they refer" -qmgrName QM1 -qmgrHostname 192.168.0.22 -qmgrPortNumber 1415 -qmgrSvrconnChannel QM1.SVRCONN}

  cf2(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml#
  MQConnectionFactory_120532263601)

Connection factory definition specifying a CCDT

The following example creates an connection factory that uses a CCDT to locate the queue manager to connect to.

• Jython:
  wsadmin>AdminConfig.getid("/Node:9994GKCNode01")
  9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)

  wsadmin>AdminTask.createWMQConnectionFactory("9994GKCNode01(cells/
  9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)", ["-name cf3 -jndiName
   'jms/cf/cf3' -type CF -ccdtUrl 'http://myccdt:9080/ccdt/amqclchl.tab'
   -ccdtQmgrName QM3"])  

  cf3(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml#
  MQConnectionFactory_120532263606)

• Jacl:
  wsadmin>$AdminConfig getid /Node:9994GKCNode01
  9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)
  wsadmin>$AdminTask createWMQConnectionFactory 9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1) {-name cf3 -jndiName "jms/cf/cf3" -type CF -ccdtUrl "http://myccdt:9080/ccdt/amqclchl.tab" -ccdtQmgrName QM3}

  cf3(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml#
  MQConnectionFactory_120532263606)

Related tasks

Use the wsadmin scripting AdminTask object for scripted administration

Start the wsadmin scripting client

Configure the WebSphere MQ messaging provider with native libraries information

deleteWMQConnectionFactory command

listWMQConnectionFactories command

modifyWMQConnectionFactory command

showWMQConnectionFactory command

WebSphere MQ messaging provider connection factory advanced properties

Mapping of administrative console panel names to command names and WebSphere MQ names Reference topic