Configuring service properties

Configure the service properties for connection and interaction with the target z/OS® subsystem by clicking the Configuration tab.

zosConnect-2.0 Applies to zosConnect-2.0.

For CICS® services (COMMAREA, or channel), specify the following properties:

Table 1. Properties for CICS services
Property	Importance	Description
Coded character set identifier (CCSID)	Required	Specifies the CCSID that is used at run time to encode character data in COMMAREA and BIT container application data structures. Default is IBM®-037. For more information, see Coded character set identifiers and Considerations for services using the API or build toolkits.
Connection reference	Required	Specifies the ID of the CICS connection.
Transaction ID	Optional	Specifies the CICS transaction name. The transaction ID usage value specifies how the transaction ID value is used. If this parameter is not specified, the transaction ID value in the connection is used.
Transaction ID usage	Optional	Specifies how the transaction ID value is used. Valid values are `EIB_ONLY` and `EIB_AND_MIRROR`. If this value is not specified, the transaction ID usage value in the connection is used.
Use context containers	Optional	Channel services only When enabled, the following context containers are sent to CICS: `DFHWS-URI`, `DFHWS-URI-QUERY`, and `DFHHTTPMETHOD`. The `BAQHTTPHEADERS` container is sent only when headers are configured in the Context containers HTTP headers property. For more information, see Context containers.
Context containers HTTP headers	Optional	Channel services only The HTTP headers to include in the BAQHTTPHEADERS context container if they are present in the HTTP request. This property is enabled only if Use context containers is enabled.
Bidi configuration reference	Optional	CICS bidi services only Specifies the bidi configuration to be used in a CICS service, which performs text transformation according to `server.xml` `zosconnect_bidiConfig` element attributes. For more information, see Configuring bidirectional text support.

For IMS services, specify the following properties:

Table 2. Properties for IMS services
Property	Importance	Description
Connection profile	Required	Specifies the name of the connection profile to use at service invocation.
Interaction profile	Required	Specifies the name of the interaction profile to use at service invocation.
Program name	Optional	Specifies the program name to identify the IMS program that is associated by the service. An IMS program can be triggered by multiple transactions, which define scheduling rules, output limits, and more. The program itself determines how a transaction is processed and how it looks to the user. This optional value is for informational purposes and can be used to identify all services that are associated with a specific program.
IMS destination override	Optional	Specifies a different IMS destination (IMS data store) to use, overriding the one that is defined in the interaction profile. With this option, you can reuse the profiles across multiple z/OS Connect services regardless of the IMS destination that the profile was originally defined for.

For IBM MQ services, specify the following properties. Select the table that matches your configuration.

Table 3. Properties for IBM MQ two-way services
Property	Importance	Description
Connection factory JNDI name	Required	Defines a JNDI name that is used to locate a connection factory that connects to an IBM MQ for 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 Liberty documentation.
Request destination JNDI name	Required	Defines a JNDI name that is used to locate an IBM MQ queue where request messages can be sent. For more information, see JMS Queue (jmsQueue) in the WebSphere Application Server Liberty documentation.
Reply destination JNDI name	Required	Defines a JNDI name that is used to locate an IBM MQ queue that contains reply messages. For more information, see JMS Queue (jmsQueue) in the WebSphere Application Server Liberty documentation.
Wait interval	Required	Specifies how long, in milliseconds the IBM MQ service provider waits for messages to arrive on a queue. Tip: You should set the wait interval to a value less than the `asyncRequestTimeout` value to prevent the HTTP request from timing out in the z/OS Connect Server.
MQMD format	Required	Used in the format field of the MQMD header in messages that are sent by the IBM MQ service provider. For more information, see Considerations for services using the API or build toolkits
Coded character set identifier (CCSID)	Required	Specifies the CCSID that is used at run time to encode character data in application data structures. Default is 37, which is IBM®-037. For the list of CCSIDs supported in z/OS Connect, see Coded character set identifiers.For more information, see Considerations for services using the API or build toolkits
Is message persistent	Required	Describes the persistence of messages that are sent to the IBM MQ queue. The default value is false, indicating that messages are non-persistent. If set to true, messages are persistent. Persistent messages survive queue manager restart; non-persistent messages do not.
Reply selection	Required	Defines how the service locates reply messages on the reply destination. 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.
Expiry	Required	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. For more information, see ibm-mq-md-correlID. 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. Tip: Change `expiry` from the default to a value that is both appropriate for the back-end service and is a relatively small number of seconds. Otherwise, there is the potential for reply messages to build up on the reply destination and not processed by the IBM MQ service provider.

Table 4. Properties for IBM MQ one-way services for sending
Property	Importance	Description
Connection factory JNDI name	Required	Defines a JNDI name that is used to locate a connection factory that connects to an IBM MQ for z/OS queue manager on the same LPAR as the z/OS Connect Server or on a different LPAR. For more information, see JMS connection factory in the WebSphere Application Server Liberty documentation.
Destination JNDI name	Required	Defines a JNDI name that is used to locate an IBM MQ queue or topic where request messages can be sent. For more information, see JMS Queue (jmsQueue) in the WebSphere Application Server Liberty documentation.
Coded character set identifier (CCSID)	Required	Specifies the CCSID that is used at run time to encode character data in application data structures. The default is 37, which is IBM-037. For the list of CCSIDs supported in z/OS Connect, see Coded character set identifiers and Considerations for services using the API or build toolkits.
MQMD format	Required	Used in the format field of the MQMD header in messages that are sent by the IBM MQ service provider. For more information, see Considerations for services using the API or build toolkits.
Is message persistent	Required	Describes the persistence of messages that are sent to the IBM MQ queue. The default value is false, indicating that messages are non-persistent. If set to true, messages are persistent. Persistent messages survive queue manager restart; non-persistent messages do not.
Expiry	Required	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 (MQLONG) 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.

Table 5. Properties for IBM MQ one-way services for receiving
Property	Importance	Description
Connection factory JNDI name	Required	Defines a JNDI name that is used to locate a connection factory that connects to an IBM MQ for z/OS queue manager on the same LPAR as the z/OS Connect Server or on a different LPAR. For more information, see JMS connection factory in the WebSphere Application Server Liberty documentation.
Destination JNDI name	Required	Defines a JNDI name that is used to locate an IBM MQ queue or topic where from which the service receives messages. For more information, see JMS Queue (jmsQueue) in the WebSphere Application Server Liberty documentation.
Coded character set identifier (CCSID)	Required	Specifies the CCSID that is used at run time to encode character data in application data structures. The default is 37, which is IBM-037. For the list of CCSIDs supported in z/OS Connect, see Coded character set identifiers.
Wait interval	Optional	Specifies how long, in milliseconds, the IBM MQ service provider waits for messages to arrive on the queue. If the value is blank or 0, the service provider does not wait for messages. A negative value means that the service provider waits until a message is available. Tip: You should set the wait interval to a value less than 30000 to prevent the HTTP request from timing out in the z/OS Connect Server. The wait interval should be set to a value that is just under, or the same as the value of the expiry property.
Message selector	Optional	Defines a valid JMS message selector that is used to locate messages from the queue. For more information, see Message selectors in JMS in the IBM MQ documentation. REST clients can override `expiry` by specifying an `ibm-mq-md-expiry` HTTP header with a valid 64-bit integer.