Configuring connections to IMS

The IMS.xml server configuration file contains information about the IMS hostname, port number, and other security-related properties for connection to the specified IMS host system.

IMS connections are specified using the zosconnect_imsConnection element within the IMS.xml connections configuration file within the Liberty configuration directory. In a typical installation, the directory location is <workspaceDir>/<apiDir>/src/main/liberty/config.

Each zosconnect_imsConnection consists of a pair of <zosconnect_imsConnection> </zosconnect_imsConnection> elements. Each zosconnect_imsConnection element references the ID of a connection factory that is defined with a connectionFactory element. This connection factory must reference the ID of an authData element to provide a user and password using a containerAuthDataRef attribute. The connection factory definition must also specify a properties.gmoa element to provide the target IMS host and port.

Note:
  1. A connection factory (connectionFactory) cannot be shared by multiple zosconnect_imsConnection elements. An authorization data object (authData) cannot be shared by multiple connection factories.
  2. IMS connection pools can be created by referencing a top level connectionManager element with the connectionFactory attribute connectionManagerRef. To learn more about the attributes used to define connection pools, see Configuring connection pooling in the WebSphere Application Server Liberty Documentation.
Table 1. Attributes in the zosconnect_imsConnection element
Attribute Description
id Specify a unique ID for this IMS connection. This ID is the IMS connection selected within the z/OS® Connect Designer.
connectionFactoryRef Set this value to the ID of the connectionFactory element.
pingIMSConnectOnInvoke Ping IMS Connect before the transaction is invoked to ensure that the connection that is retrieved from the connection pool is not stale. Throw an exception if z/OS Connect is unable to ping IMS before the service is invoked.
commitMode Specify the commit mode. A value of 0 means commit-then-send (CM0); 1 means send-then-commit (CM1).
imsConnectTimeout Specify the time in milliseconds to wait for a reply after sending a message to IMS Connect. The default value is 30000, which means to wait for 30 seconds.
Tip: General guidelines for setting the imsConnectTimeout value:
  • This value should be equal or larger than the value for interactionTimeout.
  • This value should be at least 5 seconds shorter than the value for the asyncRequestTimeout attribute of the zosconnect_zosConnectManager element in server.xml. This ensures that a successful transaction invocation won’t be erroneously reported to the API client as a IBM® z/OS Connect asyncRequestTimeout failure. For more information, see Configuration elements.
imsDatastoreName Specify the name of the IMS data store (IMS Connect).
interactionTimeout Specify the time in milliseconds for the transaction to be processed by IMS. After sending a message to IMS, IMS Connect waits for a reply from IMS until this timeout value is reached.
  • Valid values are -1, 0, or between 1 and 3600000 (one hour), inclusively.
  • A value of 0 means the timeout value is determined by IMS Connect.
  • A value of -1 (the default) means to wait indefinitely.
tranExpiration Sets the TMRA IMSInteractionSpec property transExpiration. Accepted values for this attribute are “true” or “false”.

To learn what these properties control, see the TMRA section of the IMS documentation.
propagateNetworkSecurityCred Specify whether to propagate the network security credential if the IMS Connect is V15 or later. The default is true.

The credential consists of the user ID and the network session ID (the realm) that are registered in the basic registry or SAF registry. For more information, see Configuring distributed identity propagation to IMS.
syncLevel Specify the sync level. A value of 0 means None; 1 means Confirm. A commitMode value of 0 (CM0, Commit-then-send) is invalid with sync level 0 (None).
imsConnectCodepage Specify the code page to use for character string conversion with IMS Connect. The default is Cp1047.
ltermOverrideName Optional. Specify a LTERM name to override the value in the LTERM field of the IMS application program's I/O PCB.
Table 2. Attributes in the connectionFactory element
Attribute Description
id Specify an ID for the connection factory.
containerAuthDataRef Set this value to the ID of the authData element.

If the user ID from the originating client is to be sent to IMS Connect, remove this attribute, and remove or comment out the authData element. Use this attribute and the corresponding authData element only if you want the user ID and password specified in the zosconnect_imsConnection to be sent to IMS Connect.

Table 3. Attributes of the properties.gmoa element that is nested within the connectionFactory element
Attribute Description
hostName Specify the hostname or IP address of the data store server (IMS Connect).
portNumber Specify the port number that is used to connect to IMS Connect.
SSLEnabled Indicates whether SSL is enabled for this connection factory.
SSLEncryptionType Specifies the type of cipher suite to be used for encryption. For more information, see SSL encryption type (SSLEncryptionType) in the IMS documentation.
SSLProtocol The SSL protocol to be used for encryption.
SSLKeyStoreName Name (full path) of SSL keystore for client certificates and private keys. For more information, see SSL keystore name (SSLKeyStoreName) in the IMS documentation.
SSLKeyStorePassword Password of SSL keystore for client certificates and private keys.
SSLTrustStoreName Name (full path) of SSL keystore for trusted certificates.
SSLTrustStorePassword Password of SSL keystore for trusted certificates.
Table 4. Attributes in the authData element
Attribute Description
id Specify an ID for this authData element.
user Specify the username to use to connect to IMS Connect.
password Specify the encrypted password for the specified user. Use a tool such as securityUtility in Liberty to encrypt plain text.

The following sample shows two zosconnect_imsConnection server configurations, each referencing a connection factory. Each connection factory references an authData object for authorization with IMS Connect.

<server>
    <zosconnect_imsConnection id="myConnectionID1"
    connectionFactoryRef="myConnection1_CF"
    imsDatastoreName="IM4A"             
    comment=""         
    />

    <connectionFactory id="myConnection1_CF" containerAuthDataRef="myConnection1_Auth">
        <properties.gmoa hostName="192.0.2.19" portNumber="5555"/>
    </connectionFactory>

    <authData id="myConnection1_Auth" user="<username_CF>" password="<password>"/>
     
    <zosconnect_imsConnection id="myConnectionID2"
    connectionFactoryRef="myConnection2_CF"
    imsDatastoreName="IM4B"                
    comment=""         
    "/>

    <connectionFactory id="myConnection2_CF" containerAuthDataRef="myConnection2_Auth">
        <properties.gmoa hostName="192.0.2.22" portNumber="1111"/>
    </connectionFactory>

   <authData id="myConnection2_Auth" user="<username_CF2>" password="<password>"/>
  
</server>