Configuring CICS to use WebSphere optimized local adapters (WOLA)

z/OS® Connect (OpenAPI 2) includes a WOLA service provider, which uses WOLA to communicate with CICS® programs.

1. Allocate a PDSE, for example called LIBERTY.WOLA.LOAD, with the following values: Space units = TRACK; Primary quantity = 30; Secondary quantity = 2; Directory blocks = 15; Record format = U; Record length = 0; Block size = 32760 and Data set name type = LIBRARY
   
2. Open a Telnet or ssh session to your z/OS system UNIX System Services:
   1. Change to the z/OS Connect <installation_path>/wlp/clients/zos directory that contains the WOLA modules.
      For example, /usr/lpp/IBM/zosconnect/v3r0/wlp/clients/zos.
   2. Enter the following command to copy the modules from the UNIX System Services file system to the PDSE you allocated in previous step:
      cp -Xv ./* "//'data.set'"

      Where "//'data.set'" is the location of the target PDSE. For example,

      cp -Xv ./* "//'LIBERTY.WOLA.LOAD'"
   3. Check the contents of the PDSE to ensure that all the modules were copied successfully.
3. Edit your CICS region JCL start procedure to add the PDSE containing the WOLA modules.
   For example, add LIBERTY.WOLA.LOAD, to the DFHRPL DD concatenation.
4. Define the WOLA resources, transactions, and TD queue to the CICS region DFHCSD.

   The CICS CSD definitions are documented in Optimized local adapter definitions for CICS. Update your CICS CSD to add these definitions.

5. Set up the Liberty message catalog in the CICS region.

   The optimized local adapter programs issue messages from a message catalog that is provided with Liberty. For the programs to issue messages, the NLSPATH environment variable in the CICS region must point to the directory that contains the message catalog. This directory is wlp/lib/native/zos/s390x/nls/%N.cat, where wlp is the directory in which the Liberty server is installed.

   To set the environment variable, use the Language Environment® ENVAR option, which you can set by editing the CEEROPT CSECT that the CICS region uses. After you edit the CSECT, you can build, compile, link, and copy the CSECT into the DFHRPL data set. For more information about other ways to set Language Environment options, see the documentation for your version of CICS.

   Note: Methods for setting Language Environment options that involve editing the application source code or relinking the application are not supported because the optimized local adapter programs cannot be recompiled or relinked.

   The following example shows a CEEROPT CSECT that defines the NLSPATH environment variable for a Liberty server that is installed in /u/MSTONE1/wlp. The definition spans two lines and includes a continuation character, X, in column 72.

   CEEROPT CSECT
   CEEROPT AMODE ANY
   CEEROPT RMODE ANY
   *****************************************************************
   *
   * Utility: CEEROPT
   * Purpose: Set default LE runtime options for CICS region.
   *
   *****************************************************************
           CEEXOPT ENVAR=(('NLSPATH=/u/MSTONE1/wlp/lib/native/zos/s390x/nlX 
                  s/%N.cat'),OVR)
           END

6. Define the SAF CBIND profile to allow remote clients (for example, CICS) to register with WOLA.
   In these examples, RACF® commands are used.
   1. Enter the command:

      RDEF CBIND BBG.WOLA.group.name2.name3 UACC(NONE)

      Where group, name2, and name3 match the values that are specified on the zosLocalAdapters element in the server.xml configuration file to create the three-part name for WOLA. For example,

      RDEF CBIND BBG.WOLA.LIBERTY1.LIBERTY2.LIBERTY3 UACC(NONE)

      Note:

      • You can use a wildcard in the profile to make it more generic. For example, the CBIND profile BBG.WOLA.* would apply to any three-part name you use in Liberty.
      • CBIND profiles are stored in uppercase. Specify uppercase values in your server.xml zosLocalAdapters element because lowercase characters in your three-part name cause a mismatch when the CBIND authority is checked.
   2. Grant the CICS region user ID (for example, cics_id) READ access to the CBIND profile.

      PERMIT BBG.WOLA.group.name2.name3 CLASS(CBIND) ACCESS(READ) ID(cics_id)

      For example,

      PERMIT BBG.WOLA.LIBERTY1.LIBERTY2.LIBERTY3  CLASS(CBIND) ACCESS(READ) ID(CICSID)

      SETROPTS RACLIST(CBIND) REFRESH

7. Start the CICS region to ensure that the WOLA definitions are installed successfully.
   1. Ensure that CSD GROUP(BBOACSD) defined in step 4 is installed.
      Install manually now if it is not included in a List in the GRPLIST SIT parameter.
   2. Confirm that the WOLA support was added, by checking the MSGUSR job log output for the following messages:

      Resource definition for BBOACLNK has been added.     
      Resource definition for BBOACNTL has been added.     
      Resource definition for BBOACSRV has been added.     
      Resource definition for BBOATRUE has been added.     
      TRANSACTION definition entry for BBO$ has been added.
      TRANSACTION definition entry for BBO# has been added.
      TRANSACTION definition entry for BBOC has been added.
      

8. Stop the CICS region.

   You will need to restart CICS after the z/OS Connect Server is configured and started.

What to do next

More advanced configuration options are also available, such as:

• Enabling the WOLA Task Related User Exit (TRUE) to start during CICS region startup.
• Configuring the Link Server Task to start by using either INITPARM or a sequential terminal.

These options are similar to the actions required when WOLA is used in WebSphere® Application Server for z/OS. For more information, see the Full Function WebSphere Application Server z/OS WOLA Quick Start Guide also available from Techdoc WP101490 - WebSphere z/OS Optimized Local Adapters.