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.
WOLA is provided as part of the Liberty profile that is included in the z/OS Connect (OpenAPI 2) installation. To configure CICS to use WOLA, copy the WOLA modules from the z/OS Connect (OpenAPI 2) installation directory to a load library that is referenced in the DFHRPL DD concatenation of the CICS region startup JCL. Next, define WOLA CSD definitions to your CICS region and a SAF profile to control which external user IDs can use WOLA to register to the IBM® z/OS Connect server.
About this task
Note: The Liberty feature that is included in both CICS TS and IBM z/OS Connect , includes the BBOA* WOLA modules, but the versions of these modules are potentially different. Always upload the modules that are included with IBM z/OS Connect as these modules are tested to ensure compatibility.
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
Open a Telnet or ssh session to your z/OS system UNIX System Services:
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.
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'"
- Check the contents of the PDSE to ensure that all the modules were copied successfully.
- Change to the z/OS Connect (OpenAPI 2) <installation_path>/wlp/clients/zos directory that contains the WOLA modules.
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.
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.
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.
- Copy the contents of the file CSDUPDAT.jclsamp into a new file called CSDUPDAT on your workstation.
- Upload file CSDUPDAT in ASCII to a PDS (record format FB, record length 80) on your z/OS system.
- Customize the CSDUPDAT JCL member STEPLIB and DFHCSD DD cards for your CICS installation.
- Review and modify the ADD statement at the end of the file to conform with your CICS installation standards for GROUPs and LISTs.
- Run the job and check that it completes with RC=0.
- 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.
- In a web browser, open the URL https://github.com/WASdev/sample.wola and click the file CSDUPDAT.jclsamp to open the file.
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
Define the SAF CBIND profile to allow remote clients (for example, CICS) to register with WOLA.
In these examples, RACF® commands are used.
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
zosLocalAdapterselement 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
zosLocalAdapterselement because lowercase characters in your three-part name cause a mismatch when the CBIND authority is checked.
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)
SETROPTS RACLIST(CBIND) REFRESH
- Enter the command:
Start the CICS region to ensure that the WOLA
definitions are installed successfully.
- 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).
Confirm that the WOLA support was added, by checking the MSGUSR job log output for the
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.
- Stop the CICS region
You will need to restart CICS after the IBM 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.