Registering an external address space with a local Liberty server using optimized local adapters

For WebSphere optimized local adapters (WOLA) to make an outbound call to your local optimized local adapter group or an inbound call to a Liberty server, you must bind the current address space to the Liberty server and establish connection attributes using the Register API.

Before you begin

Enable the Liberty server environment to use WOLA. For more information, see Enabling the Liberty server environment to use optimized local adapters.

The Liberty server must be active on the same z/OS image that the register request originates from.

If you are using the Customer Information Control System (CICS®), enable optimized local adapters support in CICS. For more information, see Enabling support for Liberty optimized local adapters in CICS. Activate the task-related user exit (TRUE) program before you make a connection between CICS and the Liberty server.

Procedure

  1. Decide which parameters to use when you register the address space using the Register API, BBOA1REG.
    The API accepts parameters for the following items:
    • The three parts of the WOLA group name that you specified when you added the feature to the server.xml file
    • The register name
    • The minimum number of initial connections
    • The maximum number of connections
    • Registration flag words to specify tracing behavior

    For inbound calls to the Liberty server, a security context that contains the user ID of the address space that makes the request is always propagated to the Liberty server. For CICS, the reg_flag_C2Wprop registration flag propagates the user ID of the CICS task rather than the user ID from the address space.

    For outbound calls from the Liberty server, the reg_flag_W2Cprop registration flag tells the Liberty server to propagate the user ID to CICS. CICS then attempts to start the target program with that user ID.

    For more information about API parameters, see Optimized local adapters APIs on Liberty for z/OS and Securing optimized local adapters on Liberty for z/OS.

  2. Verify that another optimized local adapter group that this address space is connected to is not already using the selected register name.
    If the register name is used by another optimized local adapter group, an error return code is passed back, and the register request fails.
  3. Call the Register API for your caller from the native-language application in the client address space using the parameters that you selected.

    A 0 return and reason code indicates that the client address space is now bound to the Liberty server.

Results

The passed register name string is reserved in the current address space. No other register calls can be made with this token until an Unregister API call is received for it.
Important: If you use the minimum connections setting on this call, the result is a pool of connections that are pre-established with the target server and wait for requests.
A registration entry context or control block is also created and associated with the register name string. Each unique register name has a register context. Multiple register names with the same address space and thread can bind with one or more Liberty optimized local adapter groups.

What to do next

You can use the registration to make inbound and outbound calls between the Liberty environment and the external address space. For more information, see Developing applications that use optimized local adapters on Liberty.