The product provides sample files that support optimized
local adapters for z/OS®.
The following sample files are located in the
WebSphere® Application Server product directory,
<Prod_FS_root>/util/zos/OLASamples:
- .jclsamp files
- olarar.py and olararupdate.py files
- Header files, bboaapi.h and bboaapip.include
- EAR sample files
The ola_apis.jar file is located 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. The samples include:
- CSDUPDAT - Customer Information Control System (CICS®) DFHCSDUP utility job that defines all
the resource definitions needed for optimized local adapters under CICS. Group BBOACSD contains CICS definitions for the optimized
local adapters; group BBOASAMP contains definitions for the adapter
samples.
- DFHPLTOL - Job Control Language (JCL) source for assembling a
sample PLT with the optimized local adapters. Enable the Task Related
User Exit (TRUE) program, BBOACPLT, and the optimized local adapters
BBOC command processor PLT, BBOACPL2.
- OLABATCH - JCL to run one of the samples in batch. Ensure that
this runs on the same LPAR that WebSphere Application Server for z/OS is running.
- OLACB01 - JCL source for CICS link
to sample Cobol program that uses a commarea. This is a sample target
program when using the optimized local adapters CICS Link server. It echoes back the sent message.
- OLACB02 - JCL source for CICS link
to sample Cobol program that uses a container. This is a sample target
program when using the optimized local adapters CICS Link server. It echoes back the sent message.
- OLACB03 - JCL source for CICS sample
Cobol program that demonstrates how to make a CICS task into an optimized local adapters server
using the Host Service API.
- OLACB04 - JCL source for CICS sample
Cobol program that demonstrates how to make a CICS task into an optimized local adapters server
using the Receive Request and Get Data APIs
- OLACB05 - JCL source for CICS sample
Cobol program that demonstrates how to use the APIs to Register, Get
a Connection, call an Enterprise JavaBeans (EJB)
with Send Request, get the response with Get Data, and release the
connection with Connection Release and Unregister.
- OLACB06 - JCL source for CICS sample
Cobol program that demonstrates how to use the APIs to Register, call
an EJB application with Invoke and Unregister.
- OLACC01 - JCL source for a C program that does Register, Invoke,
and Unregister. This can be run under batch, UNIX System Services (USS) and CICS.
- OLACC02 - JCL source for a C program that does Host Service,
Send Request, Send Response, and Get Data API calls. This program
invokes itself, calling in to an enterprise bean that then calls back
to this program. This can be run under batch, USS and CICS.
- OLAMAP - JCL source for a CICS BMS
screen map definition. This is a 3270 test driving screen for passing
requests to and from CICS to WebSphere Application Server.
- OLAUTIL - JCL source for Cobol CICS test
application utility. You can test Register, Invoke, Host Service,
Send Response APIs from this panel and update the daemon group (cell
short name), server and node names, as well as the service name, to
run with. This utility can be used for testing calls in both directions.
Code from here can be used as samples for using these APIs.
- OLAPL01 - JCL source for a PL/I program that runs as an IMS™ Fast Path program and is called
by the sample WebSphere Application Server application
using the optimized local adapter over OTMA support. It in turn does
an optimized local adapter Register, Invoke, and Unregister - calling
the target EJB in the OLASample2 application.
- OLAPL02 - .JCL source for a PL/I program that runs as an Information
Management System (IMS) Message
Processing Program (MPP) and is called by the sample WebSphere Application Server application using
optimized local adapters over OTMA support. It in turn does an optimized
local adapter Register, Invoke, and Unregister - calling the target
EJB in the OLASample2 application.
- PSBOLA2 - Sample JCL/source to show how the IMS processor-side
bus (PSB) generates the samples OLAPL01 and OLAPL02.
- OTMAINIT - Sample JCL to show how to start the IMS OTMA callable
interface SVCs on your system.
- STAGE1 - Sample source for IMS STAGE1 for the samples, OLAPL01
and OLAPL02
Samples installation
- 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.
- There is an enterprise archive (EAR) file that can be installed
immediately after you have set up your resource adapter, ola.rar,
and defined a connection factory with the Java Naming and Directory Interface (JNDI) name
of eis/ola.
The EAR file is located in the directory,
<Prod_FS_root>/util/zos/OLASamples.
Attention: If you are using V8.0 use the OLASample2.ear file.
- 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.
- 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.
- Use the following steps to build and run the z/OS batch samples.
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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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, you 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 your system needs to be involved in doing this process.
- 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.
- Submit the OLAMAP job to build the CICS map
set module.
- 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.
- 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.
- Ensure that the sample job CSDUPDAT has run and the steps to install
optimized local adapters under CICS are
complete.
- 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.
- 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.
- 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.
- 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.
- In the Send message data field, enter a message to send to the
service in WebSphere Application Server.
- 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.
- The remaining fields can remain as they are. The service name
displayed above 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.
- Click PF4 to send the message to the EJB,
olasample1_echoHome. The message returns in the Received message data
field.
- 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.
- 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.
- 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.
- 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.
- You now see the message you entered on the browser display on
your CICS 3270 panel in the
Received message data field.
- 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.
- You have now demonstrated a call from a WebSphere Application Server servlet to a CICS Cobol program.
- Use the following steps to demonstrate calling from a WebSphere Application Server application to
a CICS Cobol program using
the optimized local adapters CICS Link
server.
- 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.
- 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.
- Ensure that the sample job CSDUPDAT has run and the steps to install
optimized local adapters under CICS are
complete.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Click Run WAS > External
address space test. You should get a page back with the
input message echoed back.
- You have now demonstrated a call from a servlet in WebSphere Application Server to CICS Cobol program OLACB02 passing data using
a CONTAINER.
- 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
- Use the following steps if you want to set up CICS to automatically start the optimized local
adapters TRUE during CICS start
up.
- You can code BBOC START_TRUE\ in a CICS sequential terminal (TYPE=SDSCI) to start
the optimized local adapters TRUE, or
- 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.