Registering CICS with the WebSphere® optimized local adapter (WOLA)

To use the z/OS® Connect (OpenAPI 2) WOLA service provider to connect to CICS®, you must first configure both your IBM® z/OS Connect server and your CICS region. You must then use a CICS transaction to register the CICS region as a client of the WOLA running in the IBM z/OS Connect server.

Before you begin

The following tasks must be completed:
  1. Configure the SAF definitions required to permit your IBM z/OS Connect server the authority to access the z/OS authorized services required by WOLA. Instructions for RACF® are documented in Configuring the Liberty Angel process and z/OS authorized services.
  2. Configure your IBM z/OS Connect server to use the WOLA service provider. Follow the instructions in Using the WOLA service provider.
  3. Configure your CICS region to use WOLA. Follow the instructions in Configuring CICS to use WebSphere optimized local adapters (WOLA).

About this task

In this task, you run a CICS transaction to start the WOLA Task Related User Exit (TRUE) and the Link Server task. This registers the CICS region as a client of the WOLA running in the IBM z/OS Connect server.

Procedure

  1. Ensure that the Angel process is running.
    If it is not running, start it by issuing the following command on the z/OS operator console:
    S BAQZANGL
    Note: The Angel process must be running before a IBM z/OS Connect Server that is configured to use WOLA is started, because the server connects to the Angel process to access the z/OS authorized services.
  2. Start the IBM z/OS Connect server.
    Check the server's message log file in <WLP_USER_DIR>/servers/<serverName>/logs/messages.log. The following messages indicate that the server was started successfully: 
    CWWKB0103I: Authorized service group LOCALCOM is available.
CWWKB0103I: Authorized service group WOLA is available
....
CWWKB0501I: The WebSphere Optimized Local Adapter channel registered with the Liberty profile server using the following name: <GROUP> <NAME2> <NAME3>
J2CA7001I: Resource adapter wola installed in 0.327 seconds.
    where:
    • <GROUP>, <NAME2>, and <NAME3> must match the wolaGroup, wolaName2 and wolaName3 attribute values specified on the zosLocalAdapters element in server.xml.
    • The availability of the LOCALCOM service group is a key indicator that the Angel process is running and your Liberty Server ID has READ access to that server profile.
    • The availability of the WOLA service group is another key indicator that the configuration was completed successfully.
    • Message CWWKB0501I shows the successful use of the WOLA three-part name values you provided in the server.xml file. This message indicates that an external address space might register into the Liberty Profile server, in this instance the IBM z/OS Connect server, by using this three-part name on the BBOA1REG API.
    • The J2CA7001I message indicates that the WOLA JCA resource adapter is available.
  3. Ensure that the CICS region is started.
  4. Start the WOLA TRUE and Link Server task from CICS, and register with WOLA.
    1. Enter the following command on the command line of the CICS region:
      BBOC START_TRUE
      The following message indicates success: 
      WOLA TRACE 1: Exit enabled successfully.
    2. Enter the following command to start the link server task and register to your server:
      BBOC START_SRVR RGN=<registerName> DGN=<GROUP>
      NDN=<NAME2> SVN=<NAME3> SVC=* SEC=N REU=Y
      The following message indicates success: 
      WOLA TRACE 0: Start server completed successfully.
      Messages are also written to the CICS region job log BBOOUT.

      If you get a non-zero return code and reason code, go to the topic Optimized local adapters APIs on Liberty for z/OS in the WebSphere Application Server z/OS Liberty documentation. Search on the string cdat_olaapis. Open the link and go to the Register section, also known as the BBOA1REG section and look for the RC and RSN codes.

Results

You can now send requests from the IBM z/OS Connect server via WOLA to CICS.

What to do next

To unregister the CICS region from WOLA and stop the Link Server task, open a terminal session with the CICS region and issue the following command:
BBOC STOP_SRVR RGN=<registerName>
where:
  • <registerName> must match the registerName attribute value specified on the localAdaptersConnectService element in server.xml.
The following message indicates that the server was stopped: 
WOLA TRACE 0: Stop server completed successfully.
To stop the WOLA TRUE, issue the following command:
BBOC STOP_TRUE
The following message indicates that the exit was stopped:
WOLA TRACE 0: Exit disabled Successfully