Optimized local adapters performance considerations for Liberty
The WebSphere® optimized local adapter (WOLA) APIs are designed to provide optimal performance for calling between an external address space and applications on Liberty for z/OS®. The APIs establish new kinds of application patterns by supporting fine-grained interactions between applications in these environments. By choosing the best configuration options for your system, you can maximize the performance benefits of using the optimized local adapters.
Selecting minimum and maximum connection values for the Register API call
Selecting a minimum connections value for the Register API call that is too large can degrade performance. Because each established connection remains until the Unregister API is called, a minimum connection value that is too large consumes more memory and increases the time that is needed to complete each Register and Unregister API call. Select the smallest minimum connections value that suits your needs; for example, if hundreds of simultaneous threads can potentially share a registration, then it might make sense to dedicate more memory and time to registration with a large minimum connections value. If you expect fewer concurrent threads, set a smaller minimum connections value.
Selecting a value that is too small for the maximum number of connections can also degrade performance if the client must wait for a connection when it requests one. When the maximum connections value is exceeded, the calling thread waits the number of seconds specified on the wait time parameter for Connection Get, Invoke, Receive Request Any, or Host Service APIs for a connection to become available. When this time expires, return and reason codes are passed back that indicate that a connection handle could not be acquired for the request before the wait time expired. Select a maximum connections value that best fits the anticipated needs of your environment.
Selecting maximum connection values when you start a CICS link server
When you start a link server task under Customer Information Control System (CICS®) without specifying the minimum connections (MNC) and maximum connections (MXC) parameters, MNC defaults to 1 and MXC defaults to 10. The value of the MXC parameter specifies the number of link invocation tasks (BBO#) that can be started and concurrently run by the link server task (BBO$). As a result, the value also limits the number of concurrent threads on the Liberty server that can run and start CICS target programs.
Select an MXC value that reflects the expected duration of the typical target CICS programs that are started under this instance of the link server. For example, if the target CICS programs are mostly long-running, a larger MXC value is appropriate to keep requests flowing efficiently from the Liberty server into CICS. If the target programs are short-lived, a smaller MXC value is more efficient.
Shared 64-bit memory
When the optimized local adapters feature is enabled in a Liberty server, the server obtains 32 MB of shared memory that is located above the 2 GB bar in z/OS. This memory is shared by all Liberty servers with the same wolaGroup name and stores the shared optimized local adapter control structures.
Additional shared memory that is located above the 2 GB bar is allocated to store messages passed between a client and a Liberty server. The amount of storage that is required to pass messages depends on the average size of the messages that are passed, and there must be enough shared memory to hold all of the message data that exists at any one time. Additional memory is allocated as required.
If an application continues to call the Register API and loop without calling the Unregister API and without terminating, which automatically cleans up these registrations, it can overflow the optimized local adapters shared memory buffer for the WOLA group. If this occurs, API calls are returned with out-of-memory reason codes.
You can calculate a rough estimate of the amount of WOLA shared memory that your application needs. Each client registration consumes 384 bytes of shared memory plus 192 bytes of shared memory for each connection. A registration with a maximum of 100 connections consumes about 20 KB of shared memory. Each client thread, which must wait for a connection to become available if all connections are in use, consumes an additional 80 bytes. Each service that the registration hosts consumes an additional 384 bytes.
200 Registrations x 384 bytes = 76,800 bytes 200 Registrations x 200 connections x 192 bytes = 7,680,000 bytes 200 Registrations x 1000 waiters x 80 bytes = 16,000,000 bytes ----------------------------------------------------------------- 23,756,800 bytes 33,554,432 bytes – 23,756,800 bytes = 9,797,632 bytes remaining / 384 bytes per service ----------------------------------------------------------------- 25,514 services
Optimized local adapters CICS link server performance considerations
You can use optimized local adapters for a CICS link server as a simple way to invoke existing CICS application programs from applications that are running on the Liberty server. When you start the link server, the optimized local adapters link server task (BBO$) starts and receives program link requests from the Liberty server. When a link request is received, the link server task (BBO$) initiates the program link task (BBO#), which in turn issues an EXEC CICS LINK command to the target program, receives a response, and sends it to the Liberty server caller. To perform these actions, the thread-level identity of the application on the Liberty server is propagated and asserted onto the target CICS task by setting the SEC=Y parameter on the BBOC START_SRVR command.
If you run a link server with REU=Y, program link tasks (BBO#) remain active until a BBOC STOP_SRVR or UNREGISTER command is entered for the registration. If you are also running with a large maximum connections (MXC) value and a large number of requests arrive concurrently, the number of active program link tasks (BBO#) might reach the CICS maximum concurrent task threshold. For more information about setting the CICS maximum concurrent task threshold, see the documentation for your version of CICS.
To achieve the fastest performance when you call into an application under CICS from the Liberty server, code the Host Service, Receive Request Any, or Receive Request Specific APIs directly in your application program. However, coding the APIs directly does not provide the built-in support for identity propagation that the link server provides.
Considerations for using the JCA resource adapter
When you use the optimized local adapter JCA resource adapter, each connection that is obtained from the ConnectionFactory object requires additional memory overhead. If your application makes several calls to an external address space or CICS in the same application method, you can achieve better performance by using the same connection for each interaction and using the same JCA interaction object within an application method.
When you create the JCA ConnectionFactory object for optimized local adapters, you can modify the minimum and maximum size of the JCA connection pool for that ConnectionFactory. The connection pool represents logical connections that are bound to physical connections that are specified when you call the Register API during an interaction. For optimal performance, set the size of the JCA connection pool to be the same size of the physical connection pool that you set during the Register API call. If your JCA connection pool is too small, your application might have to wait for a JCA connection object, even though there are physical connections available.