(ZOS) Connection factory considerations for optimized local adapters

This topic reviews considerations for connection factories when using optimized local adapters.

A connection factory must be configured to enable the optimized local adapters on z/OS for inbound and outbound support, even though it is only used directly for outbound. Multiple connection factories are supported. The connection factory can have any name.

Each configured connection factory can have different settings associated with it. Configurable settings include connection pool sizes and custom properties.

The following are settings that can be made on an optimized local adapter managed connection factory. Each of these settings can also be set using an optimized local adapter setter method:

• Register name

  1-12 alphanumeric characters.

  Set this value to the target registration name

• IMS™ OTMA group ID

  1-8 alphanumeric characters.

  Set this value to the target Information Management System (IMS) Open Transaction Manager Access (OTMA) name.

  This setting must match the criteria defined for a valid OTMA XCF group name as documented in the IMS information center.

• IMS OTMA server name

  1-16 alphanumeric characters.

  Set this value to the target IMS OTMA server name.

  This setting must match the criteria defined for a valid OTMA server name as documented in the IMS information center.

• IMS OTMA SyncLevel

  1 character - 0|1

  Set this value to 0 (zero) for SyncLevel NONE and 1 for SyncLevel CONFIRM. If we want IMS to commit work for a processed transaction after sending the response to the application server without receiving a positive acknowledgment that the response was accepted, select None as the sync level. If we want IMS to commit the transaction only after receiving a positive acknowledgement, select Confirm as the sync level. If the acknowledgement is negative, the inflight work is rolled back. Note that all calls to IMS transactions with OLA over OTMA run as SEND_THEN_COMMIT (CM1).Refer to the IMS Information Center for more information about these OTMA Sync Levels and CM1 SEND_THEN_COMMIT processing.

• IMS OTMA Maximum Segments

  Integer - 1

  Set this value to the maximum number of IMS message segments supported for sending to IMS or receiving from IMS.

• IMS OTMA Maximum Message Receive Size

  Integer - 32768

  Set this value to the maximum number size for any received message, including all message segments.

• RemoteHostname

  String

  When running on a non-z/OS platform, specifies the host name where the JNDI lookup of the OLA proxy EJB is directed.

• RemotePort

  Integer

  When running on a non-z/OS platform, specifies the port number on the remote host where the JNDI lookup of the OLA proxy EJB is directed.

• RemoteJNDIName

  String

  When running on a non-z/OS platform, specifies the JNDI name on the remote host where the OLA proxy EJB is bound. The remote host is specified by the RemoteHostname and RemotePort properties.

• Username

  String

  User used to send requests to a registration which is running with security enabled. The MVS™ user ID associated with the user name is used. If there is no MVS user ID associated with the username, no identity is sent on the request. If no username is specified, the user ID of the calling component is used to obtain an MVS user ID.

• Password

  String

  Password for the username.

• RemoteJNDIUsername

  String

  When running on a non-z/OS platform, specifies the username used to obtain the JNDI initial context on the remote system. The JNDI context is used to look up the OLA proxy EJB.

• RemoteJNDIPassword

  String

  When running on a non-z/OS platform, specifies the password to be used with the RemoteJNDIUsername.

• RemoteJNDIRealm

  String

  When running on a non-z/OS platform, specifies the security realm to use with the RemoteJNDIUsername.

• UseCICSContainer

  Integer - 0

  When using the CICS Link Server, specifies that the request and response data are to be in containers.

• LinkTaskTranID

  String

  When using the CICS Link Server, specifies the Link task transaction ID.

• LinkTaskReqContID

  String

  When using the CICS Link Server, specifies the name of the request, or input container.

• LinkTaskReqContType

  Integer - 1

  When using the CICS Link Server, specifies the type of the request container (CHAR=0|BIT=1).

• LinkTaskRspContID

  String

  When using the CICS Link Server, specifies the name of the response, or output container.

• LinkTaskRspContType

  Integer - 1

  When using the CICS Link Server, specifies the type of the response container (CHAR=0|BIT=1).

• ConnectionWaitTimeout

  Integer - 30

  Length of time, specified in seconds, to wait for a matching client connection for the current Register name. The external address space must have already been registered. This timeout applies to the time to wait for an available service with the matching register name to become available.

The IMS OTMA client name, which is automatically generated, is 16 characters and cannot be set with the optimized local adapters resource adapter. For more information about using the optimized local adapters over IMS OTMA, see the topic, Enabling optimized local adapters over OTMA/IMS support.

The connection pool settings for the adapter define the number of logical connections defined in the WebSphere Application Server connection pool. This is not the same as the number of physical connections between WAS and an external address space. A logical connection is essentially the Java EE Connector Architecture (JCA) view of a physical connection, in this case. Logical connections are used by WebSphere applications calling outbound to an external address space.

The connection pool settings for the adapter define the number of logical connections defined in the WAS connection pool. This is not the same as the number of physical connections between WAS and an external address space. A logical connection is essentially the JCA view of a physical connection, in this case.

The balance between physical and logical connections depends on how many concurrent WebSphere application threads should be able to get a connection (logical), and how many requests should be able to be sent or received at any given time to and from an external address space (physical). The maximum number of physical connections can be set to make sure an external address space does not flood the Application Server with requests, as these are used for both inbound and outbound communication with the external address space. If an external address space attempts to register with WAS and specifies a number of connections that are the maximum physical connections supported for a server in this node, the register request rejects the register with a reason code that indicates the failure. The register can also fail if the maximum connections for the daemon group are exceeded. Remember that physical connections are requested by the client and are not the same as the logical connections handed out by the JCA adapter. When an outbound request is issued, the JCA logical connection is paired with a physical connection for the duration of the interaction.

After creating and save the connection factories, we can modify the resource references defined in various modules of the application and specify the JNDI names of the connection factories wherever appropriate.

When setting the value for the Maximum Message Receive size, be careful not to set the value too high. This size value is used to pre-obtain an area of memory to receive the IMS message. Each thread that calls to IMS over OTMA has a separate message receive area of this size. The application can also set this value dynamically using the setOTMAMaxRecvSize(nnn) method on the Connection Specification..

The Maximum Segments connection level value can also be set using the setOTMAMaxSegments(nnn) method on the Connection Specification.

To use the resource adapter high availability feature, configure additional connection pool properties on each connection factory. Refer to the topic, Enabling resource adapter high availability support, for more information on how to set up and use this feature.

Enable the server environment to use optimized local adapters

Enable optimized local adapters over OTMA/IMS support

Enable optimized local adapter high availability support