`mqzOSConnectService` element

The MQ Service Provider is provided as a standard Liberty feature and so is configured using server.xml. Each one or two-way service is defined in an mqzOSConnectService element. This element and all of its attributes apply to both z/OS® Connect V1 and z/OS Connect EE.

Important: An mqzOSConnectService element needs to be referenced by a zOSConnectService element before it can be used.

An example mqzOSConnectService element with some attributes specified is shown below.


<mqzOSConnectService id="twoWay "
                        connectionFactory="jms/cf1"
                        destination="jms/requestQueue"
                        replyDestination="jms/replyQueue"
                        expiry="-1"
                        waitInterval="10000"
                        replySelection="msgIDToCorrelID"
                        selector=""
                        persistence="false"/>

Attention: Depending on how the MQ Service Provider has been installed, the mqzOSConnectService element might be prefixed with a string followed by an underscore, for example usr_mqzOSConnectService.

This is described in Installing the MQ Service Provider into WLP for z/OS Connect V1 and Installing the MQ Service Provider into IBM® z/OS Connect EE for z/OS Connect EE.

The format shown in the following example is where the MQ Service Provider has been installed into the WLP kernel (as described in option 1 of Installing the MQ Service Provider into WLP

Table 1. Attributes of an `mqzOSConnectService` element
Attribute name	Type	Default value	Description
id	string		id
connectionFactory	A JNDI name (string).		connectionFactory
destination	A JNDI name (string).		destination
replyDestination	A JNDI name (string).		replyDestination
expiry	integer	-1	expiry
waitInterval	integer		waitInterval
replySelection	string	`msgIDToCorrelID`	replySelection
selector	string		selector
persistence	boolean	false	persistence
mqmdFormat	string		mqmdFormat
userName	string		userName
password	string		password
useCallerPrincipal	boolean	false	useCallerPrincipal
receiveTextCCSID	integer	37	receiveTextCCSID

id

id is a required attribute and must be unique across all elements in server.xml. id is used by the zosConnectService element to refer to a target service provider instance.

connectionFactory

connectionFactory specifies the JNDI name of an IBM MQ messaging provider connection factory. The MQ Service Provider uses the connection factory to connect to IBM MQ.

connectionFactory is a required attribute. For more information on connection factories, see JMS Connection Factory.

You should specify transportType="BINDINGS" for the connection factory.

destination

destination specifies the JNDI name of an IBM MQ messaging provider destination.

destination is a required attribute.

For more information on configuring a:

Queue in WLP, see JMS Queue.
Topic in WLP, see JMS Topic.

For a one-way service, destination is used as the target for HTTP POST, HTTP GET, and HTTP DELETE requests.

Note that queue destinations are supported for all three request types whereas topic destinations are supported only with HTTP POST requests.

For a two-way service, destination must be a queue destination which represents the request queue used by the back end service.

Two-way services support only HTTP POST requests.

replyDestination

replyDestination specifies the JNDI name of an IBM MQ messaging provider queue.

replyDestination is an optional attribute.

For more information on configuring a queue in WLP, see JMS Queue.

If replyDestination is not specified, the service is a one-way service. If replyDestination is specified, the service is a two-way service.

This queue is the reply destination where the back end service sends reply messages to.

expiry

expiry specifies how long messages sent by the MQ Service Provider are valid for, in thousandths of a second, from the time they were sent. The message becomes eligible to be discarded if it has not been removed from the destination queue before this period of time elapses.

expiry is an optional attribute, and is equivalent to setting the MQMD Expiry field.

Negative values means that messages never expire. The default value of expiry is -1.

REST clients can override expiry by specifying an ibm-mq-md-expiry HTTP header with a valid 64-bit integer.

waitInterval

For HTTP DELETE requests to one-way services, waitInterval specifies the number of milliseconds that the service waits for a matching message on the queue, specified by the destination attribute.

For HTTP POST requests to two-way services, waitInterval specifies the number of milliseconds that the service waits for a matching message on the queue, specified by the replydestination attribute.

waitInterval is an optional attribute for one-way services, a required attribute for two-way services, and is equivalent to setting the MQMD WaitInterval field.

waitInterval is not supported with HTTP GET requests.

If waitInterval is:

Zero, the service does not wait.
A waitInterval of zero is not supported with two-way services.
Negative, the service waits for ever until a message is available.

REST clients can override this value by specifying an ibm-mq-gmo-waitInterval HTTP header with a valid 64 bit integer.

Note: Specifying a large, or negative waitInterval, is likely to result in transaction timeouts and asynchronous service request timeouts. If either, or both, of these events occur, increase the timeout, reduce the wait interval, or do both.

replySelection

replySelection describes the mechanism used to match reply messages with request messages.

replySelection is optional and used only used with two-way services. If replySelection is used with a one-way service, it is ignored.

The value is one of the following:

msgIDToCorrelID: Reply messages are assumed to be generated with the correlation ID set to the value of the message ID from the request message. The service generates a suitable message selector based on this information. This is the default value.
none: No mechanism is used to correlate reply messages with request messages. The service gets the first available message on the reply queue.
correlIDToCorrelID: Reply messages are assumed to be generated with the correlation ID set to the value of the correlation ID from the request message. The service generates a suitable message selector based on this information. If the request message does not have a correlation ID specified (see ibm-mq-md-correlID) the service generates a random correlation ID for the request message.

selector

selector must be a valid JMS message selector as described by the JMS specification.

selector is only used with one-way services and is optional. If selector is specified on a two-way service it is ignored. For more information on selectors, see Message selectors in JMS.

selector is used on HTTP GET and HTTP DELETE requests to select which message is returned. If the ibm-mq-md-msgID or ibm-mq-md-correlID headers are specified, selector is ignored.

Some selector characters need to be encoded in order to be embedded in server.xml. You can do this using standard mechanisms as follows:


" becomes &quot;
' becomes &apos;
< becomes &lt;
> becomes &gt;

persistence

persistence specifies the persistence of messages sent by a service.

persistence is optional, and is equivalent to setting the MQMD Persistence field.

The value is one of the following:

false: Means messages are non-persistent. This is the default value.
true: Means messages are persistent.

You can override persistence by using an ibm-mq-md-persistence HTTP header which takes the same values.

mqmdFormat

This attribute is used to set the value of the MQMD format field in messages that are sent by the MQ Service Provider. However, it is only used when the MQ Service Provider has been configured to use z/OS Connect data transformations, otherwise it is ignored.

If you do not specify this attribute, and data transformations are used, messages are sent with the MQMD format field set to blanks. The value of this attribute must be less than, or equal to, eight characters in length.

userName

The user name that the MQ Service Provider presents to IBM MQ for authentication and authorization purposes.

If you do not specify this attribute, the userName attribute in the connection factory referred to by the connectionFactory attribute is used.

If a userName attribute is specified, both on the referenced connection factory and on the MQ Service Provider, the MQ Service Provider value is used.

If you specify this attribute, you must specify the password attribute.

password

The password that the MQ Service Provider presents to IBM MQ for authentication and authorization purposes.

You can specify the password in plain text, although you should not do so. Instead, you should encode the password using the securityUtility tool provided with z/OS Connect, using the encode option. For more information see Liberty: securityUtility command.

If you do not specify this attribute, the password attribute in the connection factory referred to by the connectionFactory attribute is used.

If a password attribute is specified both on the referenced connection factory and on the MQ Service Provider the MQ Service Provider value is used.

If you specify this attribute, you must also specify the userName attribute.

useCallerPrincipal

When a request is made to z/OS Connect the caller authenticates with z/OS Connect. The name of the authenticated principle can be passed onto IBM MQ for authentication and authorization purposes.

To do this, set the value of useCallerPrincipal to true.

The name of the principal, but no password, is used when connecting to IBM MQ. Any values specified in the password and userName attributes are ignored.

receiveTextCCSID

The CCSID that is used when a data transformation is received and a javax.jms.TextMessage is being consumed (that is, an HTTP GET or HTTP DELETE with a one-way service, or on retrieving a response message for a two-way service).

The text in the message is converted into the CCSID specified by receiveTextCCSID.