Creating an IBM MQ service by using a properties file

You can create an IBM® MQ service by using either the API toolkit or passing a properties file to the build toolkit.

The preferred method is to use the API Toolkit as described in Creating a CICS, IMS or IBM MQ service.

Alternatively, a service can be created by specifying a set of properties in a file and passing that file to the build toolkit. The supported set of properties are listed in Table 1.

Note: MQ services which have been created by using properties files support data transformation, but the maximum transformed payload for both request and reply messages must be less than, or equal to, 32 KB. If larger message sizes are needed, use the API toolkit.

When an IBM MQ service provider service archive file is generated and deployed to the IBM z/OS Connect runtime, more properties can be specified in the server.xml configuration file to take effect at run time. Some of these properties can override the properties that were provided to the build toolkit. See IBM MQ override properties.

For more information about running the build toolkit, see Generating service archives for DevOps.

The following properties are supported by the build toolkit:

Table 1. Supported properties for creating a service with the build toolkit.
Property name	Importance	Property description
`provider`	Mandatory	Used to select the plug-in. Must be the value `mq`.
`name`	Mandatory	The name of the service. Can be any string value. For example, `service1`.
`version`	Mandatory	The version of the service. Can be any string value. For example, `1.0`.
`description`	Optional	A description of the service.
`language`	Optional	If data transformation is required, this property defines the type of language structure that is used. If this property is specified, the following conditions apply: The value must be one of either COBOL or PLI. One or both of the `requestStructure` and `responseStructure` properties must be specified. The `operationName` property must be specified. When data transformations are used, the maximum supported length of the COBOL or PL/I data structure is 32 KB.
`languageStructureCodePage`	Optional	Specifies the Java™ character set name for the source language structures that are specified by `requestStructure` or `responseStructure`. For example, for IBM Latin-1 EBCDIC, the value is IBM037. This property is only applicable if the `requestStructure` and `responseStructure` are members of a partitioned data set. When this property is used, both the `requestStructure` and `responseStructure` must name members in the same partitioned data set.
`requestStructure`	Optional	A path to a language structure to be used as the request payload. This attribute must be specified when the `language` property is specified with `messagingAction` set to mqput, or the `replyDestination` property is specified. The language structure must use the syntax of the language property. For example, if language=COBOL it must be a valid COBOL copybook. See Note.
`responseStructure`	Optional	A path to a language structure to be used as the response payload. This attribute must be specified when the `language` property is specified with `messagingAction` set to mqput, or the `replyDestination` property is specified. The language structure must use the syntax of the language property. For example, if language=COBOL it must be a valid COBOL copybook. See Note.
`operationName`	Optional	This property must be specified when the `language` property is specified. It defines the operation name that is used in the generated JSON schema. This property can be up to 8 characters long.
`ccsid`	Optional	This property is only supported if the `language` property is specified. It defines the integer code page of the data structures that are generated by the IBM z/OS Connect data transformation code. The default value is 37.
`connectionFactory`	Mandatory	Defines a JNDI name that is used to locate a connection factory that connects to a z/OS queue manager on the same LPAR as the IBM z/OS Connect server or on a different LPAR. For more information, see JMS connection factory in the WebSphere® Application Server for z/OS Liberty documentation.
`destination`	Mandatory	Defines a JNDI name that is used to locate an IBM MQ queue or topic. For one-way services, if `messagingAction=mqput`, then `destination` is the queue or topic that messages are sent to. If `messagingAction=mqget`, then `destination` is the queue that messages are destructively got from. For two-way services, request messages are sent to this queue. For more information, see the following topics in the WebSphere Application Server for z/OS Liberty documentation: JMS Queue (jmsQueue) if the destination is a queue or JMS Topic (jmsTopic) if the destination is a topic.
`replyDestination`	Optional	Defines a JNDI name that is used to locate a queue that contains response messages for two-way services. If specified, the service is a two-way service. This property is configured in the same way as the destination property.
`expiry`	Optional	Specifies the expiry time of messages that are sent by the IBM MQ service provider. If set, the value is an integer that describes how long the message is available in milliseconds before it expires. By default messages do not expire. Setting `expiry` is equivalent to setting the MQMD Expiry field. Negative values mean that messages never expire. The default value is -1. REST clients can override `expiry` by specifying an `ibm-mq-md-expiry` HTTP header with a valid 64-bit integer.
`waitInterval`	Optional	Specifies how long, in milliseconds the IBM MQ service provider waits for messages to arrive on a queue. This property is only valid if `messagingAction=mqget` or `replyDestination` is set. If `replyDestination` is set, it must be a positive number. If `messagingAction=mqget`, `waitInterval` can be negative, which means that the IBM MQ service provider waits for ever until a message is available. If `waitInterval` is 0, the IBM MQ service provider does not wait.
`replySelection`	Optional	Defines how a two-way service locates reply messages on the queue that is referenced by the `replyDestination` property. If `replySelection` is used with a one-way service, it is ignored. The following values are valid: 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 option 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 specify a correlation ID, the service generates a random correlation ID for the request message. For more information, see ibm-mq-md-correlID.
`selector`	Optional	Defines a valid JMS message selector that is used to locate messages from the queue referenced by the destination attribute. Only valid with one-way services that have `messagingAction=mqget` defined. For more information, see Message selectors in JMS in the IBM MQ documentation.
`persistence`	Optional	Describes the persistence of messages that are sent to the queue referenced by the destination property. The default value is false, indicating that messages are non-persistent. If set to true, messages are sent as persistent.
`mqmdFormat`	Optional	Completes the format field of the MQMD header in messages that are sent by the IBM MQ service provider. Only supported when the `language` property is specified. If not specified, then messages are sent with a blank format.
`messagingAction`	Optional	If the service is used to send messages, the value must be mqput. If the service is used to receive messages, the value must be mqget. If this property is set, the service is a one-way service.

Note: If you use the build toolkit on z/OS to generate a service archive, the values requestStructure and responseStructure can be a UNIX System Services file or a member of a partitioned data set. To specify a member of a partitioned data set, use the syntax //'partitionDatasetName(member)'. See the languageStructureCodePage property to indicate the code page of the z/OS partitioned data set member.