Optimized local adapters Samples

This data set is allocated as RECFM=FB, DSORG=PO, LRECL=80, BLKSIZE=9040, TRKS=40. Copy, for example OGET, the files with file type "jclsamp" from the <Prod_FS_root>/util/zos/OLASamples directory to this data set. The header file bboaapi.h is also put in this data set as BBOAAPI.

This data set is allocated as RECFM=FB, DSORG=PO, LRECL=80, BLKSIZE=9040, TRKS=15. In the sample JCL, this data set is named BOSS.OLA.SAMPLES.COPYBOOK.

It must be allocated as a LIBRARY rather than a PDS.

For all the members you update during these steps, you must change the JCLLIB statement to point at your procedure libraries (for C compiles in this case). Someone familiar with where this information is located on your system should be involved in doing this. Also, the test case source has the daemon group (cell short name), the node short name, and the server short name embedded and you must change these before compiling, in order for these to function on your system.

1. Edit member OLACCnn (where nn=test case number) and update the JCL to match your site data set naming conventions for your C compiler and set the SYSLMOD data set where the output load module is placed.
2. In member OLACCnn, update the daemon group name (cell short name), the node name and the server name and submit the job to build the test case load module.
3. Ensure that the target application server is started with optimized local adapters support enabled. You enable the optimized local adapters support by setting the WAS_DAEMON_ONLY_enable_adapter to true. Also, make sure that the ola.rar file is installed and a connection factory is created with the JNDI name, eis/ola.
4. Ensure that the OLA sample EAR file is installed in the target application server.
   Attention: If you are using V8.0, use the OLASample2.ear file.
5. Use OLABATCH as a template for running the OLACCnn batch samples.

Some sample jobs refer to a data set named BOSS.OLA90902.SBBOLOAD. This represents the data set into which you copied the online adapter modules using the copyZOS.sh script.

1. Edit member OLAMAP and update the JCL to match your site data set name conventions for HLASM applications.
   You need to change the MAPLIB and DSCTLIB parameters to your own data set names. The MAPLIB should point to the samples load module library that you allocated in step 4. The DSCTLIB should point to the COPYBOOK data set that you allocated in step 3.

   Note: You can change the default register name on this panel from CICSTEST to something else. You can also set the default daemon group name (cell short name), node name and server name. The values you enter here display on the panel when you run the OLAU transaction under CICS.
2. Submit the OLAMAP job to build the CICS map set module.
3. Edit member OLAUTIL and review the content.

   This is a sample Cobol application that demonstrates a number of the optimized local adapters APIs from Cobol. It sends and receives the CICS BMS map, OLAMAP, and can send a message to any target enterprise bean in any locally attached application server. It can also be used to demonstrate how to make your CICS task into an optimized local adapters target service using the BBOA1SRV API. After updating the JCL to conform to your local data set name conventions, submit the job and the OLAUTIL load module is saved in the data set pointed to by the PROGLIB symbol.

4. Ensure that the optimized local adapters load module library, and the optimized local adapters samples load module library, are in the CICS DFHRPL DD concatenation of your CICS cataloged procedure.
5. Ensure that the sample job CSDUPDAT has run and the steps to install optimized local adapters under CICS are complete.
6. Ensure that the target application server is started with the optimized local adapters support enabled. You enable optimized local adapters by setting the WAS_DAEMON_ONLY_enable_adapter to true. Also, make sure that the ola.rar file is installed and a connection factory is created with the JNDI name eis/ola. You can read more about these procedures in the topic, Enabling the server environment to use optimized local adapters.
7. Ensure that the OLA sample EAR file is installed in the target application server.
   Attention: If you are using V8.0, use the OLASample2.ear file.
8. Start CICS.

   Make sure that optimized local adapters support is enabled, logon to CICS with a user ID that is authorized to run the BBOC and OLAU transactions, and clear the screen. Enter BBOC START_TRUE to start the optimized local adapters CICS task-related user exit (TRUE). A message displays about the exit starting successfully. If you do not get this message, you should get a message indicating the kind of error that occurred. For more detailed messages, refer to the CICS job output and look in file BBOOUT. If you want to use the optimized local adapters Program List Table for Post Initialization (PLTPI) program to start the optimized local adapters TRUE during CICS startup, refer to the following section that describes this process.

9. Clear the screen again and enter OLAU to start the test panel.

   If everything is working properly, the panel displays with the heading, * Optimized Local Adapters WAS z/OS Testing *. The Run parameters are listed on the panel, with Register first with a value of Y, Register name with a value of CICSTEST and Service name with a value of ejb/com/ibm/ola/olasample1_echoHome. The Number of Tests to run field has a value of 00001.

10. In the Send message data field, enter a message to send to the service in WebSphere Application Server.
11. Enter the WebSphere Application Server server short name, WebSphere Application Server node short name, andWebSphere Application Server cell short name (daemon group name) for the server that you want to call an enterprise bean into.
12. The remaining fields can remain as they are. The service name displayed is the JNDI home name of a sample target enterprise bean in the OLA sample EAR file.
    Attention: If you are using V8.0, use the OLASample2.ear file.
13. Click PF4 to send the message to the EJB, olasample1_echoHome. The message returns in the Received message data field.
14. You have now demonstrated a call from a CICS Cobol program to a WebSphere Application Server EJB application.

    The panel display has now changed. The Register First? field changed from Y to N. Rerunning requests with this Register name does not require a register call first, so this changes to the value, N. If you get a return code 8 (RC8) and reason code 8 (RSN8) on Register, this means that you are already registered and do not need to register again. After leaving OLAU and coming back in later, that registration is still active, so you do not need to register again with that name and should set that to the value, N.

15. To test a call from WebSphere Application Server to CICS, you can use this same panel.

    You must update the service name field to whatever name you want to identify as your target service name and click PF5. This puts the screen into an x-wait since OLAUTIL calls the BBOA1SRV API with the service name and registration name that you requested. The panel shows a registration called CICSTEST and service name called myserv. Other parameters that show values on the panel are WAS server short name, WAS node short name, WAS cell short name (daemon group name), Number of Tests to run, and Number of Tests Completed.

16. When OLAU is in the wait for the service name that you requested, start the sample Web application in your browser.

    Use the following URL (updating the IP/port# for your site): http://nn.nn.nn.nn:nnnn/OLA_Sample1_Web/ - change the nnnn port number to your non-SSL WebSphere Application Server application port.

17. A web page displays with the following fields listed: Data to send to external address space, Response back from external address space, OLA Register Name, OLA Service Name, CICS Link server-specific data, CICS Link Request Container ID, CICS Link Response Container ID, and CICS Link Transaction ID. Enter the message that you want to send, register name and service name as you did on the OLAU panel and click Run WAS->External address space test.
18. You now see the message you entered on the browser display on your CICS 3270 panel in the Received message data field.
19. Type in a response message in the Send message data field and click PF6 to send the response back to WebSphere Application Server. This should come up on the browser.
20. You have now demonstrated a call from a WebSphere Application Server servlet to a CICS Cobol program.

1. Edit member OLACB01 and review the contents.

   This is a sample Cobol application that is the target of an EXEC CICS LINK with a COMMAREA. It writes the passed COMMAREA message data to the default Cobol standard out (CEEMSG) and echoes back the message. Update the JCL to point to your local data sets and submit it. The load library that this module is saved in must be in the CICS DFHRPL concatenation.

2. Edit member OLACB02 and review the contents.

   This is a sample Cobol application that is the target of an EXEC CICS LINK with a CONTAINER. It reads the CONTAINER contents and writes it back to the same container. Update the JCL to point to your local data sets and submit it. The load library that this module is saved in must be in the CICS DFHRPL concatenation.

3. Ensure that the sample job CSDUPDAT has run and the steps to install optimized local adapters under CICS are complete.
4. Start CICS.

   Logon to CICS with a user ID that is authorized to run the BBOC, BBO# and BBO$ transactions, and clear the screen.

   Enter BBOC START_TRUE to start the optimized local adapters CICS TRUE.

   A message displays about the exit starting successfully. If you do not get this message, you should get a message indicating what kind of error occurred. For more detailed messages, refer to the CICS job output and look in file BBOOUT. If you want to use the optimized local adapters PLTPI program to start the optimized local adapters TRUE during CICS startup, refer to the section in this topic that describes this process.

5. Clear the screen again and enter the following to start an optimized local adapters CICS Link server task: bboc start_srvr rgn=olaserver svn=<serverName> dgn=<cellName> ndn=<nodeName> mnc=1 mxc=5 sec=n svc=*

   This results in a BBO$ task starting with the register name OLASERVER, connecting the specified application server. Make sure to specify the server short name, cell short name and node short name for the server.

6. You are now ready to send a request to link to an existing CICS program. Start the test web page (http://nn.nn.nn.nn:nnnn/OLA_Sample1_Web/ ). Enter OLASERVER as the register name and OLACB01 as the service name.
7. Click Run WAS > External address space test. You should get a page back with the same message that was sent to CICS returned. If you look in the CICS CEEMSG DD (in the running CICS job), the message data in UTF-8 displayed.
8. You have now demonstrated a call from a servlet in WebSphere Application Server to a CICS Cobol program OLACB01 passing and returning data in a COMMAREA.
9. Display the browser panel again and change the service name to OLACB02 and click the Use Containers check box.
   Important: You must check the Use Containers check box.
10. Click Run WAS > External address space test. You should get a page back with the input message echoed back.
11. You have now demonstrated a call from a servlet in WebSphere Application Server to CICS Cobol program OLACB02 passing data using a CONTAINER.
12. If you want to track what is happening more closely, you can stop the link server and restart it with tracing set. By setting TRC=2, you can view the trace messages in the CICS job BBOOUT file. To stop the link server type the following: bboc stop_srvr rgn=olaserver. To restart the link server with tracing, type the following: bboc start_srvr rgn=olaServer svn=<serverName> dgn=<cellName> ndn=<nodeName> mnc=1 mxc=5 sec=n svc=* trc=2

1. You can code BBOC START_TRUE\ in a CICS sequential terminal (TYPE=SDSCI) to start the optimized local adapters TRUE, or
2. You can create a CICS region Program List Table for Post Initialization (PLTPI) and have it invoked during CICS region startup.

   The sample job DFHPLTOL creates a PLTPI with suffix OL. Run this sample, placing the resulting module DFHPLTOL in a load modules library in the DFHRPL concatenation, and add OL to the SIT PLTPI specified for the CICS region, for example, PLTPI=OL.

   Refer to the samples file DFHPLTOL for an example of this. When you run the PLTPI, you should see the following messages on your CICS job log if the optimized local adapters TRUE started properly:

   +BBOA9920I WAS z/OS OLA CICS PLT init start.     
   +BBOA9921I WAS z/OS OLA CICS TRUE enabled.       
   +BBOA9925I WAS z/OS OLA CICS PLT init ending.