+

Search Tips   |   Advanced Search

(ZOS) Optimized local adapters Samples

The product provides sample files that support optimized local adapters for z/OS .

The following sample files are in the WebSphere Application Server product directory, <Prod_FS_root>/util/zos/OLASamples:

The ola_apis.jar file is in the product directory, /lib.


Sample descriptions

A directory of the sample names and what they do is available in a directory in the @@README member of the native set of files. These samples are in <install_root>/util/zos/OLASamples and include:

The OLAUTIL sample does GET CONTAINER INTOCCSID(37) from CCSID(1208)- UTF-8. Before running this sample to demonstrate a WebSphere to CICS flow, ensure that we are running z/OS Unicode services and can support this conversion. Otherwise, an AEZW CICS abend can occur.


Samples installation

  1. Allocate a Partitioned data set (PDS) or Partitioned data set extended (PDSE) to hold the JCL source. In the sample JCL, this data set is named BOSS.OLA.SAMPLES.SRC.

    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.

  2. There is an EAR file that can be installed immediately after we have set up your resource adapter, ola.rar, and defined a connection factory with the JNDI name of eis/ola.

    The EAR file is located in the directory, <Prod_FS_root>/util/zos/OLASamples.

    If we are using V8.0 use the OLASample2.ear file.

  3. Allocate another PDS or PDSE to be used to hold the COBOL COPYBOOK created by the Customer Information Control System (CICS) BMS map build job OLAMAP.

    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.

  4. Allocate or select a load module library to contain the optimized local adapter samples load modules.

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

  5. Use the following steps to build and run the z/OS batch samples.

    For all the members you update during these steps, 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 the 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 change these before compiling, in order for these to function on the system.

    1. Edit member OLACCnn (where nn=test case number) and update the JCL to match your site data set naming conventions for our 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.

      If we 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.

  6. The z/OS batch samples can also be run under CICS. Follow the steps in the topic, Enabling optimized local adapters support in CICS, and add the samples load modules library from step 4 to the CICS DFHRPL DD concatenation.

  7. Use the following steps to build and run the optimized local adapters CICS sample test utility panel. For all the members that you update during this process, we need to change the JCLLIB statement to point at your procedure libraries (for COBOL compilers and for CICS translation in this case). Someone familiar with where this information is located on the system needs to be involved in doing this process.

    1. Edit member OLAMAP and update the JCL to match your site data set name conventions for HLASM applications.

      We need to change the MAPLIB and DSCTLIB parameters to our own data set names. The APLIB 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.

      We can change the default register name on this panel from CICSTEST to something else. We 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 we 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 the 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 our 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. We 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.

      If we 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 we do not get this message, we 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. 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 WAS.

    11. Enter the WAS server short name, WAS node short name, andWAS cell short name (daemon group name) for the server 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.

      If we 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. We have now demonstrated a call from a CICS Cobol program to a WAS 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 we get a return code 8 (RC8) and reason code 8 (RSN8) on Register, this means that we are already registered and do not need to register again. After leaving OLAU and coming back in later, that registration is still active, so we do not need to register again with that name and should set that to the value, N.

    15. To test a call from WAS to CICS, we can use this same panel.

      We must update the service name field to whatever name we 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 our site): http://nn.nn.nn.nn:nnnn/OLA_Sample1_Web/ - change the nnnn port number to your non-SSL WAS 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 to send, register name and service name as we 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 WAS. This should come up on the browser.
    20. We have now demonstrated a call from a WAS servlet to a CICS Cobol program.

  8. Use the following steps to demonstrate calling from a WAS application to a CICS Cobol program using the optimized local adapters CICS Link server.

    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 the 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 the 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 we do not get this message, we 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. 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. We 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. We should get a page back with the same message that was sent to CICS returned. If we look in the CICS CEEMSG DD (in the running CICS job), the message data in UTF-8 displayed.
    8. We have now demonstrated a call from a servlet in WAS 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: We must check the Use Containers check box.

    10. Click Run WAS > External address space test. We should get a page back with the input message echoed back.
    11. We have now demonstrated a call from a servlet in WAS to CICS Cobol program OLACB02 passing data using a CONTAINER.
    12. To track what is happening more closely, we can stop the link server and restart it with tracing set. By setting TRC=2, we 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

  9. Use the following steps if to set up CICS to automatically start the optimized local adapters TRUE during CICS start up.

    1. We can code BBOC START_TRUE\ in a CICS sequential terminal (TYPE=SDSCI) to start the optimized local adapters TRUE, or

    2. 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 we run the PLTPI, we 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.


Related:

  • Optimized local adapters for z/OS usage scenarios
  • Optimized local adapters on WAS for z/OS
  • Optimized local adapters tutorials and reference
  • Planning to use optimized local adapters for z/OS
  • z/OS: Use optimized local adapters for inbound support
  • z/OS: Use optimized local adapters for outbound support