createWMQActivationSpec command
Use the createWMQActivationSpec command to create an activation specification 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 createWMQActivationSpec command to create a WebSphere MQ messaging provider activation specification at a specific scope.
We cannot create a WebSphere MQ messaging provider activation specification under either of the following conditions:
- A WebSphere MQ messaging provider activation
specification already exists with the same name, at the same scope.
- The JNDI name clashes with another entry in WebSphere Application Server JNDI.
We create a CCDT based activation specification by specifying any of the following parameters:
- ccdtUrl
- ccdtQmgrName
If we do not specify any of the following parameters, we create a generic activation specification :
- ccdtUrl
- ccdtQmgrName
Target object
The scope of the WebSphere MQ messaging provider at which the WebSphere MQ messaging provider activation specification is to be created.
Required parameters
- -name
- The administrative name assigned to this WebSphere MQ messaging provider activation specification.
- -jndiName
- The name and location used to bind this object into WebSphere Application Server JNDI.
- -destinationJndiName
- The JNDI name of a WebSphere MQ messaging provider queue or topic type destination. When an MDB is deployed with this activation specification, messages for the MDB are consumed from this destination.
- -destinationType
- The type of the destination specified using the -destinationJndiName parameter.
Enter one of the following values:
- javax.jms.Queue
- javax.jms.Topic
There is no default value.
- javax.jms.Queue
Optional parameters
- -description
- An administrative description assigned to the activation specification.
- -ccdtUrl
- A URL to a client channel definition table to use, for this activation
specification, when contacting WebSphere MQ.
Use this parameter to create ccdtURL activation specifications
Do not specify this parameter in conjunction with the following parameters: -qmgrName, -qmgrType, -qmgrHostname, -qmgrPortNumber, -qmgrSvrconnChannel, or -localAddress.
- -ccdtQmgrName
- A queue manager name, used to select one or more entries from a client channel definition table.
Specify this parameter if the -transportType has been specified as client or bindingsThenClient.
Do not specify this parameter in conjunction with the following parameters: -qmgrName, -qmgrType, -qmgrHostname, -qmgrPortNumber, -qmgrSvrconnChannel, or -localAddress.
- -qmgrName
- The name of the queue manager to use, for this activation specification, when connecting with WebSphere MQ.
Use this parameter to create generic activation specifications.
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 activation specification.
Use this parameter to create generic activation specifications.
Enter one of the following case-sensitive values:
- BINDINGS
- BINDINGS_THEN_CLIENT
- CLIENT
BINDINGS_THEN_CLIENT is the default value.
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.
- BINDINGS
- -qmgrHostname
- The host name to use, for this activation specification, 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 activation specification, 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 activation specification 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),remotehost(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 activation specification 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:
- createWMQActivationSpec
- modifyWMQActivationSpec
If we specify the -connectionNameList parameter on a cell or cluster-scoped WebSphere MQ activation specification, we can use it for nodes that are running WAS v7. The exact behaviour is determined by the fix pack level of the node:
- For nodes running at WAS v7 Fix
Pack 7 or later, the activation specification uses the -connectionNameList parameter to connect to a multi-instance queue manager.
- For nodes running at a fix pack level earlier than WAS v7 Fix
Pack 7, a warning message similar to the one in the following example is output:
- [29/09/10 12:15:27:468 BST] 00000018 J2CUtilityCla W J2CA0008W: Class com.ibm.mq.connector.inbound.ActivationSpecImpl used by resource cells/L3A3316Node01Cell/resources.xml#J2CResourceAdapter_1284547647859 did not contain method setConnectionNameList. Processing continued.
We can ignore this message.
We must not specify the -connectionNameList parameter in conjunction with the -ccdtUrl or -ccdtQmgrName parameters.
If you 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 -connectionNameList, 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.
- createWMQActivationSpec
- -authAlias
- The authentication alias used to obtain the credentials specified when this activation specification needs to establish a connection to WebSphere MQ.
- -clientId
- The client identifier used for connections started by using this activation specification.
- -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
- n
- -sslCrl
- This parameter specifies a list of LDAP servers used to provide certificate revocation information if this activation specification establishes an SSL based connection to WebSphere MQ.
- -sslResetCount
- This parameter is used when the activation specification 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 activation specification 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.
- 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.
- 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.
- YES
- -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 and must be one of the CCSIDs supported by WebSphere MQ. See the WebSphere MQ messaging provider activation specification 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 activation
specification 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 activation specification 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 Char.
- -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 on which the broker is running.
- -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.
- -qmgrSvrconnChannel
- The SVRCONN channel
to use when connecting to WebSphere MQ.
Use this parameter to create explicitly defined activation specifications.
The default value is SYSTEM.DEF.SVRCONN.
Do not specify this parameter in conjunction with the following parameters: -ccdtUrl or -ccdtQmgrName.
- -brokerCCDurSubQueue
- The name of the queue from which a connection consumer receives durable subscription messages.
The default value is SYSTEM.JMS.D.CC.SUBSCRIBER.QUEUE.
- -maxPoolSize
- The maximum number of server sessions in the server session pool used by the connection consumer.
Value must be a positive integer.
The default value is 10.
- -messageSelector
- A message selector expression specifying which messages are to be delivered.
Value must be either the empty string or a valid SQL 92 statement.
- -poolTimeout
- The period of time, in milliseconds, that an unused server session is held open in the server session pool before being closed due to inactivity.
Value must be a positive integer.
The default value is 300,000.
- -startTimeout
- The period of time, in milliseconds, within which delivery of a message to an MDB must start after the work to deliver the message
has been scheduled. If this period of time elapses, the message is rolled back onto the queue.
Value must be a positive integer.
The default value is 10,000.
- -subscriptionDurability
- This parameter determines whether a durable or nondurable subscription
is used to deliver messages to an MDB that is subscribing to the topic.
Value must be Durable or Nondurable
The default value is Nondurable.
- -subscriptionName
- The name of the durable subscription.
- -customProperties
- This parameter specifies custom properties to be passed to the WebSphere MQ messaging provider activation
specification implementation. Typically, custom properties are used to set attributes of the activation specification which 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}
For example, -WAS_EndpointInitialState is a custom property that can be used with the -customProperties parameter. The value of -WAS_EndpointInitialState must be ACTIVE or INACTIVE. -WAS_EndpointInitialState determines whether the endpoint is activated when the endpoint is registered. If the parameter is set to active, message consumption begins from the JMS destination as soon as the activation specification is used for a message-driven bean to connect with the destination.
This parameter should be ignored for subsequent activation or deactivation via the J2CMessageEndpoint MBean.
- In Jython: [name value]
- -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.
- the
local network interface
- -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 -sslConfiguration parameter is not valid unless this parameter is set to SPECIFIC.
The default value is NONE.
- -sslConfiguration
- The name of the SSL configuration to use when using SSL to secure network connections to the queue manager.
Do not specify this parameter unless the parameter -sslType is assigned the value SPECIFIC.
Value must correspond to an SSL configuration.
There is no default value.
- -stopEndpointIfDeliveryFails
- This parameter indicates whether the endpoint should be stopped
if message delivery fails the number of times specified by the failureDeliveryCount property.
Value must be true or false.
The default value is true.
- -failureDeliveryCount
- This parameter specifies the number of sequential delivery failures
allowed before the endpoint is suspended. This value is only used if stopEndpointIfDeliveryFails is true.
Value must be a non-negative integer.
The default value is 0, which means that the endpoint is stopped the first time it fails.
Minimal activation specification 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 activation specification, specifying the minimum number of parameters. Due to the default values assumed for the unspecified parameters, MDBs deployed by using this activation specification are co-located with a generic queue manager installed on the same node.
- Jython:
- wsadmin>AdminConfig.getid("/Node:9994GKCNode01")
9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)
wsadmin>AdminTask.createWMQActivationSpec("9994GKCNode01(cells/9994GKCNode01Cell/ nodes/9994GKCNode01|node.xml#Node_1)", ["-name spec1 -jndiName jms/as/spec1 -destinationJndiName jms/queues/q1 -destinationType javax.jms.Queue"])spec1(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml# J2CActivationSpec_1098737234986)
- Jacl:
- wsadmin>$AdminConfig getid /Node:9994GKCNode01
9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)
- wsadmin>$AdminTask createWMQActivationSpec 9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1) {-name spec1 -jndiName jms/as/spec1 -destinationJndiName jms/queues/q1 -destinationType javax.jms.Queue}
spec1(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml# J2CActivationSpec_1098737234986)
- The following example creates an activation specification with the WAS_EndpointInitialState optional parameter activated, using Jython:
- wsadmin>attrs = '[[name "WAS_EndpointInitialState"] [ required "false"] [type "java.lang.String"] [value "ACTIVE"]]'
- wsadmin>AdminConfig.getid("/Node:myNode01")
- myNode01(cells/myCell01/nodes/myNode01|node.xml#Node_1)'
- wsadmin>theActSpec = AdminTask.createWMQActivationSpec("myNode01(cells/myCell01/nodes/myNode01|node.xml#Node_1)", '-name testas -jndiName testas -destinationJndiName testq -destinationType javax.jms.Queue -customProperties [[WAS_EndpointInitialState Active]]')
Explicit activation specification definition
The following example creates an activation specification 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.createWMQActivationSpec("9994GKCNode01(cells/9994GKCNode01Cell/ nodes/9994GKCNode01|node.xml#Node_1)", ["-name spec2 -jndiName 'jms/as/spec2' -destinationJndiName 'jms/topics/t2' -destinationType javax.jms.Topic -description 'Must remember to keep each of these activation specifications in sync with the WebSphere MQ queue manager to which they refer' -qmgrName QM1 -qmgrHostname 192.168.0.22 -qmgrPort 1415 -qmgrSvrconnChannel QM1.SVRCONN"])spec2(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml# J2CActivationSpec_1098737234987)
- Jacl:
- wsadmin>$AdminConfig getid /Node:9994GKCNode01
- 9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)
- wsadmin>$AdminTask createWMQActivationSpec 9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1) {-name spec2 -jndiName "jms/as/spec2" -destinationJndiName "jms/topics/t2" -destinationType javax.jms.Topic -description "Must remember to keep each of these activation specifications in sync with the WebSphere MQ queue manager to which they refer" -qmgrName QM1 -qmgrHostname 192.168.0.22 -qmgrPort 1415 -qmgrSvrconnChannel QM1.SVRCONN}
spec2(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml# J2CActivationSpec_1098737234987)
Activation specification definition specifying a CCDT
The following example creates an activation specification that uses a CCDT to locate the queue manager to connect to.
- Jython:
- wsadmin>AdminConfig.getid("/Node:9994GKCNode01/")
- Node01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)")
wsadmin>AdminTask.createWMQActivationSpec("9994GKCNode01(cells/9994GKCNode01Cell/ nodes/9994GKCNode01|node.xml#Node_1)", ["-name spec3 -jndiName 'jms/as/spec3' -destinationJndiName 'jms/queue/q3' -destinationType javax.jms.Queue -ccdtUrl 'http://myccdt:9080/ccdt/amqclchl.tab' -ccdtQmgrName QM3"])spec3(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml# J2CActivationSpec_1098737234988)
- Jacl:
- wsadmin>$AdminConfig getid /Node:9994GKCNode01
- 9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)
wsadmin>$AdminTask createWMQActivationSpec 9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1) {-name spec3 -jndiName "jms/as/spec3" -destinationJndiName "jms/queue/q3" -destinationType javax.jms.Queue -ccdtUrl "http://myccdt:9080/ccdt/ amqclchl.tab" -ccdtQmgrName QM3}spec3(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml# J2CActivationSpec_1098737234988)
Create an activation specification with the -WAS_EndpointInitialState custom property set to Active
- The following example creates an activation specification with the WAS_EndpointInitialState custom property activated, using Jython:
- wsadmin>attrs = '[[name "WAS_EndpointInitialState"] [ required "false"] [type "java.lang.String"] [value "Active"]]'
- wsadmin>AdminConfig.getid("/Node:myNode01")
- myNode01(cells/myCell01/nodes/myNode01|node.xml#Node_1)'
- wsadmin>theActSpec = AdminTask.createWMQActivationSpec("myNode01(cells/myCell01/nodes/myNode01|node.xml#Node_1)", '-name testas -jndiName testas -destinationJndiName testq -destinationType javax.jms.Queue -customProperties [[WAS_EndpointInitialState Active]]')
Related tasks
Reference topic