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 (OpenAPI 2) <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 CSD definition that is required for the Liberty profile WOLA modules is provided on a GitHub website.
   1. In a web browser, open the URL https://github.com/WASdev/sample.wola and click the file CSDUPDAT.jclsamp to open the file.
      Click the Raw to remove the line numbers.
   2. Copy the contents of the file CSDUPDAT.jclsamp into a new file called CSDUPDAT on your workstation.
   3. Upload file CSDUPDAT in ASCII to a PDS (record format FB, record length 80) on your z/OS system.
   4. Customize the CSDUPDAT JCL member STEPLIB and DFHCSD DD cards for your CICS installation.
   5. Review and modify the ADD statement at the end of the file to conform with your CICS installation standards for GROUPs and LISTs.
   6. Run the job and check that it completes with RC=0.
   7. If you want the CSD GROUP(BBOACSD) to be installed when CICS starts, add its LIST to the CICS region startup JCL GRPLIST SIT parameter.
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)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 IBM z/OS Connect server is configured and started.