IBM MQ service definition properties
We can set properties and attributes for service definitions while creating a new service definition, or when editing an existing service definition.
Some attributes will only be available when the service definition is of a specific binding type or message exchange pattern. Follow these links to view the properties for the individual property pages of a service definition:
- General
- Operation
- Input destination
- Input message schema
- Input message header
- Output destination
- Output message schema
- Output message header
For each attribute, there is a brief description of when you might need to configure the attribute.
General page
The following table lists the attributes we can set on the General page of the Service definition properties dialog.
Attribute Description Namespace Specifies the namespace for the service. There is already a temporary default value assigned. Name A unique name for the new Service Definition. The service definition name is not case sensitive, but a mixed-case service definition name is retained. Message exchange pattern The Message Exchange Pattern describes the direction of messages sent and received during the invocation of a service. There are two possible selections:
- One-Way means that a message is sent one way only.
- Request-Response means that a message is sent and a response is received.
Binding type Specifies the version of the IBM MQ service definition specification. Comment Specify a comment to annotate the service in the WSDL file.
Operation page
The following table lists the attributes we can set on the Operation page of the Service definition properties dialog. Each service definition has only 1 operation.
Attribute Description Operation name Specifies the name of the operation. This property must have a value to create a service definition. Action Used by the service provider to dispatch service requests. For example: Allowing multiple services to be deployed using a single destination, enabling a service provider to dispatch the requests arriving on the destination appropriately. When the binding type is MQ, Action specifies targetAction.
Comment Specify a comment to annotate the operation in the WSDL file.
Input destination page
The following table lists the attributes we can set on the Input Destination page of the Service definition properties dialog. The input pages define the details of the message that the service expects, and the destination where it will be retrieved from.
Attribute Description Input destination name Specifies the name of the destination queue or the destination topic to which the request is sent, for example:The queue-dest or topic-dest particle of a IBM MQ IRI, such as: msg/queue/INS.QUOTE.REPLYDestination queue manager name Specifies the name of the destination queue manager. Connection queue manager Specifies the name of the queue manager to which the requesting service connects to. This corresponds to the QmgrName parameter used on the MQCONN() and MQCONNX() calls. Client connection properties The client connection properties specify detailed bindings which can include information about how a service requester binds to a specific machine or channel. Being able to specify client-bindings and channel names is useful in some circumstances, but over-specifying the service might be restrictive however. A solution to this problem is to minimize the amount of binding information incorporated into a service definition and allow underlying infrastructure or IBM MQ to route messages where possible. Channel table name Specifies the name of the client channel table file which is used to identify the channel connection.
- If Channel table name is not specified, then Channel table library is ignored.
- If either of the MQSERVER or MQCHLTAB environment variables are set in the environment where the client application is running, then Channel table name is ignored.
Channel table library Specifies the path to the client channel table.
- If either MQSERVER or MQCHLLIB environment variables are set in the environment where the client application is running, then Channel table library is ignored.
- If Channel table name is not specified, then Channel table library is ignored.
Client channel connection name Specifies the connection string used when a service requester makes a IBM MQ MQI client-binding connection. For TCP/IP, the connection is in the form of a host name followed by a port number, for example: OS2ROG3(1822)If the port number is not specified, a default value of 1414 is used.
- If the Client channel connection name is specified, then the Client channel name and Client channel transport type must also be specified.
- If either MQSERVER or MQCHLTAB environment variable are set in the environment where the client application is running, then Client channel connection name is ignored.
Client channel name Specifies the channel used when a IBM MQ service requester make a IBM MQ MQI client-binding connection.
- If the Client channel connection name is specified, then the Client channel name and Client channel transport type must also be specified.
- If either MQSERVER or MQCHLTAB environment variable are set in the environment where the client application is running, then Client channel name is ignored.
Client channel transport type Specifies the transport type to be used when a IBM MQ service requester makes a IBM MQ MQI client-binding connection.
- If the Client channel connection name is specified, then the Client channel name and Client channel transport type must also be specified.
- If either MQSERVER or MQCHLTAB environment variable are set in the environment where the client application is running, then Transport type is ignored.
There are two different selectable values:
- TCP. Used to specify the TCP/IP transport protocol. This is the default value.
- LU62. Used to specify the LU6.2 transport protocol.
Input message schema page
The following table lists the attributes we can set on the Input message schema page of the Service definition properties dialog. They allow the schema for the message payload to be defined.
Attribute Description Inbound data type Specifies the expected inbound data type. For simple types, this can be modelled using the built-in XML xsd types such as xsd:string or xsd:int. For more complex types, a data type can be imported from an external file by specifying the Import schema file and Import namespace for the data type. Import schema file Specifies the schema file to be imported. Import namespace Specifies the namespace to be imported.
Input message header page
The following table lists the attributes we can set on the Input message header page of the Service definition properties dialog. The input pages define the details of the message that the service expects, and the destination where it will be retrieved from. Some of the properties only apply to service definitions of an MQ binding type.
Attribute Description CCSID Specifies the Coded Character Set ID which corresponds to the CodedCharSetId field in the MQMD structure. If this value is not specified, then the service requester and service provider uses the value which corresponds to the character set of the message data. Format Specifies the format name of the message data. This property corresponds to the MQRFH2 format field, or the MQMD format field if there is no MQRFH2 is present. The value must be a character string between 0 and 8 characters long consisting of the A-Z and 0-9 characters. The Format can be set to any value according to the guidelines in the Format field.
User properties Specifies the user defined data carried in IBM MQ service messages. Values must be specified in the format allowed for RFH2 folder elements; in a series of triplets encoded using an XML-like syntax such as: <name dt="datatype">value</name>The dt="datatype" element is optional, and if it is omitted, it is treated as a string, allowing elements to be specified as:<name>value</name>For example:<myprop1>value1</myProp1><myprop2>value2</myProp2><myprop3 dt="i4">99</myProp3>For further information on the allowed data types and formatting, see NameValueData ( MQCHARn ). It is not recommended to include security sensitive properties such as UserId or passwords.Message type Specifies the type of message that is sent. This property corresponds to the MsgType in the MQMD structure. The five possible values are:
- Unspecified which means that no value is set, therefore the value is taken from the value of the Message exchange pattern. This is the default value.
- Request which means that the message is one that requires a reply. This value indicate that the service uses a request-response message exchange pattern.
- Reply which means that the message is a reply to a request.
- Report which means that the message is a report.
- Datagram which means that the service is a one-way message exchange and there will not be a reply.
If no value is specifies, the value is set according to the Message Exchange Pattern.
Persistence Specifies whether the message is persistent or not, and it corresponds to the Persistence field in the MQMD structure. The three possible values are:
- Not persistent which means that the messages are not persistent.
- Persistent which means that the messages are persistent.
- Queue default which means that the queue manager determines the message persistence from the definition of the destination that the message is put to. This is the default value.
Message ID Specifies the Message identifier which corresponds to the MsgId field in the MQMD structure. The Message ID allows certain specialized IBM MQ applications to be described as services (for example: applications that share an input queue and select the messages intended for them based on a pre-defined msgId value). Predefined msgIds in service definitions might lead to problems such as when a request-response Message Exchange Pattern return the request's msgId.
The Message Id can be either a character string or a binary value. Binary values must be a string of up to 24 pairs of two-character hexadecimal values.Click Edit to open a dialog and enter a value as text or bytes
Correlation ID Specifies the Correlation ID corresponds to the CorrelId field in the MQMD structure. The Correlation ID can be either a character string or a binary value. Binary values must be a string of up to 24 pairs of two-character hexadecimal values. Click Edit to open a dialog and enter a value as text or bytes
Expiry Specifies the message lifetime. It must be a signed integer, and it is measured in tenths of a second. The Expiry range is from 1 to 2 147 483 647. A special value of Unlimited is used to indicate that the message does not expire. The value of -1 is written to the WSDL file.
A value of Unspecified means that no value is written to the WSDL file. This is the default value.
Priority Specifies the priority associated with the message and corresponds to the priority field in the MQMD structure. It must be specified as an integer between 0 and 9, with 0 as the lowest priority and 9 as the highest priority. A special value of Unlimited is used to indicate that the message priority is taken from the definition of the first queue that the message is put to. The value of -1 is written to the WSDL file.
A value of Unspecified means that no value is written to the WSDL file. This is the default value.
Encoding Specifies the numeric encoding of message data, which corresponds to the Encoding field in the MQMD structure:
- Integer allows you to select Normal or Reversed
- Decimal allows you to select Normal or Reversed
- Float allows you to select Normal, Reversed, or S390
- Mnemonic specifies the 3 character mnemonic based on the other values selected. R = Reversed, N = Normal, and 3 = S390.
- Value specifies the numeric value of the selections and mnemonic.
Report options Specifies how the message and correlation identifiers in the reply message or fault message are set by the service provider. This property corresponds to the Report field in the MQMD structure. There are four possible values:
- New message ID indicates that if a report or reply is generated as a result of this message, a new msgId is generated for the report or reply message.
- Pass Message ID indicates that if a report or reply is generated as a result of this message, then the msgId of this message is copied to the msgId of the report or reply message.
- copy Message ID to Correlation ID indicates that if a report or reply is generated as a result of this message, then the msgId of this message is copied to the correlId of the report or reply message.
- Pass Correlation ID indicates that if a report or reply is generated as a result of this message, then the correlId of this message is copied to the correlId of the report or reply message.
Output destination page
The following table lists the attributes we can set on the Output destination page of the Service definition properties dialog. The output pages define the details of the message that the service will send in response to the input message, and the destination where it will be put. The output destination name must be prefixed with 'msg/queue/' for queues, or 'msg/topic/' for topics.
Attribute Description Output destination name Specifies the name of the destination queue or the destination topic to which the response message is sent, and corresponds to the ReplyToQ and ReplyToQMgr fields of the MQMD structure. The Destination Name must take the form of either the queue-dest or topic-dest particle of a IBM MQ URI, such as: msg/queue/INS.QUOTE.REPLYDestination queue manager name Specifies the name of the destination queue manager. Connection queue manager Specifies the name of the queue manager to which the requesting service connects to. This corresponds to the QmgrName parameter used on the MQCONN() and MQCONNX() calls. Client connection properties The client connection properties specify detailed bindings which can include information about how a service requester binds to a specific machine or channel. Being able to specify client-bindings and channel names is useful in some circumstances, but over-specifying the service might be restrictive however. A solution to this problem is to minimize the amount of binding information incorporated into a service definition and allow underlying infrastructure or IBM MQ to route messages where possible. Channel table name Specifies the name of the client channel table file which is used to identify the channel connection.
- If Channel table name is not specified, then Channel table library is ignored.
- If either of the MQSERVER or MQCHLTAB environment variables are set in the environment where the client application is running, then Channel table name is ignored.
Channel table library Specifies the path to the client channel table.
- If either MQSERVER or MQCHLLIB environment variables are set in the environment where the client application is running, then Channel table library is ignored.
- If Channel table name is not specified, then Channel table library is ignored.
Client channel name Specifies the connection string used when a service requester makes a IBM MQ MQI client-binding connection. For TCP/IP, the connection is in the form of a host name followed by a port number, for example: OS2ROG3(1822)If the port number is not specified, a default value of 1414 is used.
- If the Client channel connection name is specified, then the Client channel name and Client channel transport type must also be specified.
- If either MQSERVER or MQCHLTAB environment variable are set in the environment where the client application is running, then Client channel connection name is ignored.
Client channel connection name Specifies the channel used when a IBM MQ service requester make a IBM MQ MQI client-binding connection.
- If the Client channel connection name is specified, then the Client channel name and Client channel transport type must also be specified.
- If either MQSERVER or MQCHLTAB environment variable are set in the environment where the client application is running, then Client channel name is ignored.
Client channel transport type Specifies the transport type to be used when a IBM MQ service requester makes a IBM MQ MQI client-binding connection.
- If the Client channel connection name is specified, then the Client channel name and Client channel transport type must also be specified.
- If either MQSERVER or MQCHLTAB environment variable are set in the environment where the client application is running, then Transport type is ignored.
There are two different selectable values:
- TCP. Used to specify the TCP/IP transport protocol. This is the default value.
- LU62. Used to specify the LU6.2 transport protocol.
Output message schema page
The following table lists the attributes we can set on the Output message schema page of the Service definition properties dialog. They allow the schema for the message payload to be defined.
Attribute Description Outbound data type Specifies the expected outbound data type Import Schema File Specifies the schema file to be imported Import Namespace Specifies the namespace to be imported
Output message header page
The following table lists the attributes we can set on the Output message header page of the Service definition properties dialog. The output pages define the details of the message that the service will send in response to the input message, and the destination where it will be put. Some of the properties only apply to service definitions of an MQ binding type.
Parent topic: Properties
Attribute Description CCSID Specifies the Coded Character Set ID which corresponds to the CodedCharSetId field in the MQMD structure. If this value is not specified, then the service requester and service provider uses the value which corresponds to the character set of the message data. Format Specifies the format name of the message data. This property corresponds to the MQRFH2 format field, or the MQMD format field if there is no MQRFH2 is present. The value must be a character string between 0 and 8 characters long consisting of the A-Z and 0-9 characters. The Format can be set to any value according to the guidelines in the Format field.
User properties Specifies the user defined data carried in IBM MQ service messages. Values must be specified in the format allowed for RFH2 folder elements; in a series of triplets encoded using an XML-like syntax such as: <name dt="datatype">value</name>The dt="datatype" element is optional, and if it is omitted, it is treated as a string, allowing elements to be specified as:<name>value</name>For example:<myprop1>value1</myProp1><myprop2>value2</myProp2><myprop3 dt="i4">99</myProp3>For further information on the allowed data types and formatting, see NameValueData ( MQCHARn ). It is not recommended to include security sensitive properties such as UserId or passwords.Message type Specifies the type of message that is sent. This property corresponds to the MsgType in the MQMD structure. The five possible values are:
- Unspecified which means that no value is set, therefore the value is taken from the value of the Message exchange pattern. This is the default value.
- Request which means that the message is one that requires a reply. This value indicate that the service uses a request-response message exchange pattern.
- Replay which means that the message is a reply to a request.
- Report which means that the message is a report.
- Datagram which means that the service is a one-way message exchange and there will not be a reply.
If no value is specifies, the value is set according to the Message Exchange Pattern.
Persistence Specifies whether the message is persistent or not, and it corresponds to the Persistence field in the MQMD structure. The three possible values are:
- Not persistent which means that the messages are not persistent.
- Persistent which means that the messages are persistent.
- Queue default which means that the queue manager determines the message persistence from the definition of the destination that the message is put to. This is the default value.
Message ID Specifies the Message identifier which corresponds to the MsgId field in the MQMD structure. The Message ID allows certain specialized IBM MQ applications to be described as services (for example: applications that share an input queue and select the messages intended for them based on a pre-defined msgId value). Predefined msgIds in service definitions might lead to problems such as when a request-response Message Exchange Pattern return the request's msgId.
The Message Id can be either a character string or a binary value. Binary values must be a string of up to 24 pairs of two-character hexadecimal values.Click Edit to open a dialog and enter a value as text or bytes
Correlation ID Specifies the Correlation ID corresponds to the CorrelId field in the MQMD structure. The Correlation ID can be either a character string or a binary value. Binary values must be a string of up to 24 pairs of two-character hexadecimal values. Click Edit to open a dialog and enter a value as text or bytes
Expiry Specifies the message lifetime. It must be a signed integer, and it is measured in tenths of a second. The Expiry range is from 1 to 2 147 483 647. A special value of Unlimited is used to indicate that the message does not expire. The value of -1 is written to the WSDL file.
A value of Unspecified means that no value is written to the WSDL file. This is the default value.
Priority Specifies the priority associated with the message and corresponds to the priority field in the MQMD structure. It must be specified as an integer between 0 and 9, with 0 as the lowest priority and 9 as the highest priority. A special value of Unlimited is used to indicate that the message priority is taken from the definition of the first queue that the message is put to. The value of -1 is written to the WSDL file.
A value of Unspecified means that no value is written to the WSDL file. This is the default value.
Encoding Specifies the numeric encoding of message data, which corresponds to the Encoding field in the MQMD structure:
- Integer allows you to select Normal or Reversed
- Decimal allows you to select Normal or Reversed
- Float allows you to select Normal, Reversed, or S390
- Mnemonic specifies the 3 character mnemonic based on the other values selected. R = Reversed, N = Normal, and 3 = S390.
- Value specifies the numeric value of the selections and mnemonic.
Report options Specifies how the message and correlation identifiers in the reply message or fault message are set by the service provider. This property corresponds to the Report field in the MQMD structure. There are four possible values:
- New message ID indicates that reports or replies generated as a result of this message, a new msgId is generated for the report or reply message.
- Pass Message ID indicates that if a report or reply is generated as a result of this message, then the msgId of this message is copied to the msgId of the report or reply message.
- copy Message ID to Correlation ID indicates that if a report or reply is generated as a result of this message, then the msgId of this message is copied to the correlId of the report or reply message.
- Pass Correlation ID indicates that if a report or reply is generated as a result of this message, then the correlId of this message is copied to the correlId of the report or reply message.
Related tasks
- Create a new service definition
- Adding a service definition repository
- Configure queue managers and objects