+

Search Tips   |   Advanced Search

(ZOS) WAS transactions BBOC, BBO$, BBO#

This topic describes how the optimized local adapters are supported in the Customer Information Control System (CICS ) product, including the WebSphere Application Server transactions introduced, BBOC, BBO$ and BBO#.

The adapter is designed to run in a CICS region as a resource manager. In CICS, the Task Related User Exit (TRUE) is the primary vehicle for resource providers. TRUE support provides the boundary between the CICS application threads and the external resource manager threads. Currently, DB2, IBM MQ, and TCP/IP sockets are used in CICS with the TRUE support. The optimized local adapters support TRUE.

Applications that run under CICS and exploit the optimized local adapter APIs do so by calling the provided stub routines. The stub routines start the CICS resource manager interface module, passing it the name of the optimized local adapter TRUE routine and the parameters specific to each API. CICS dispatches the TRUE on one of the CICS-maintained OPENAPI TCBs and runs until the API call is completed. The call then goes back to CICS with the output parameters. The CICS TRUE support also provides notification over transaction boundaries, like when the application ends normally, abends, or issues an explicit SYNCPOINT call to CICS. For details on how this support is used for propagation of transaction context to WAS, and two-phase commit, see the section in this topic on "Propagating Transactions". Additionally, for CICS, a Program List Table Post-Initialization (PLTPI) program is provided, used to automatically begin the TRUE program during CICS startup. If we do not use the PLTPI, a CICS transaction, BBOC, is provided. This transaction can be used to start, stop, enable, and disable tracing for the TRUE module.


WAS control transaction for CICS, BBOC

The BBOC transaction is the WebSphere control, or operations transaction, for the adapters support under CICS. It is used to enable and start the WAS TRUE, and to set tracing levels for debugging the APIs and WAS-interfacing code. BBOC also sets registrations and unregistrations, and starts and stops WAS Link server tasks in CICS. These server tasks provide support for starting existing CICS programs and passing data with COMMAREAs or containers with the input parameters over the adapters. This is a CICS terminal-based transaction that can be issued on a 3270 terminal or from a sequential, SDSCI-type, terminal. The syntax for BBOC is described as follows:

BBOC<operation_name><parameters_separated_by_one_or_more_spaces>.

The parameters are described as follows:

Operation name Abbreviation Abbreviation,

Description

Parameters
START_TRUE STR Start the WAS appservers TRUE TRC=0/1/2

TDQ=<tdqname>

STOP_TRUE PTR Stop the WAS TRUE TRC=0/1/2

TDQ=<tdqname>

REGISTER REG Register with the WAS optimized local adapters daemon group, node, and server RGN=<name>

DGN=<name>

NDN=<name>

SVN=<name>

MNC=<minimum_number_ of_connections>

MXC=<maximum_number_ of_connections>

SEC=<yes|no>

TXN=<yes|no>

TRC=0|1|2

TDQ=<tdqname>

UNREGISTER
Unregister with the WAS optimized local adapters RGN=<name>
START_SRVR STA Start the WAS appservers task for the passed Registration name. RGN=<name>

DGN=<name>

NDN=<name>

SVC=<name>

SVN=<name>

MNC=<minimum_number_ of_connections>

MXC=<maximum_number_ of_connections>

SEC=<yes|no>

STX=<CICS_link_server_ transaction_ID>

LTX=<CICS_link_server_ transaction_ID>

TRC=0|1|2

TDQ=<tdqname>

REU=<yes|no>

REUC=<number_of_requests>

REUT=<number_of_seconds>

STOP_SRVR STP Stop the WAS task for Registration name. RGN=<name>

TRC=0/1/2

TDQ=<tdqname>

LIST_SRVR LST List all the Link Servers matching the passed in Registration name. The parameters here are all optional, including Registration name. When issued with no parameters, it returns a list of all Link Servers. We can also pass the RGN parameter with wildcards. An asterisk (*) indicates all characters after that point are valid and a question mark (?) means that single character can be any character. The output from the LIST_SRVR operation is written to the BBOQ or the named transient data queue on the TDQ parameter. If the LTSQ parameter is passed, the list of active Link Servers are written to the named CICS temporary storage queue. RGN=<name>

LTSQ=<tsqname>

TRC=<0/1/2>

TDQ=<tdqname>


Running a BBOC command automatically during CICS start-up and shut-down

We can automatically start an optimized local adapters Link Server when CICS starts. This starts a long running task BBO$ which exists until the Link Server is stopped. To run BBOC commands during CICS start-up, there are two CICS Program List Table Post-Initialization (PLTPI) programs that are provided in the load library created by the copyZOS.sh script. This load library can be used to run BBOC commands during CICS startup. Add BBOACPLT to your CICS PLT as a phase 2 or phase 3 entry to enable the optimized local adapters task-related user exit (TRUE) during CICS startup.

A second PLTPI program is provided, BBOACPL2, which when added to your PLT (also in phase 2 or 3) allows us to issue a BBOC command during CICS start-up using INITPARM data. We can pass a string of commands inside the INITPARM (up to the CICS limit of 60 characters). The following sample INITPARM string calls BBOACPL2 and passes in a request to start a Link server under the registration name 'PAYROLL' with daemon group name 'DAE1', node name 'NODE1', and server name 'SERVER1'. This Link server receives requests for all service names (SVC=*): 

INITPARM=(BBOACPL2='STA RGN=PAYROLL DGN=DAE1 NDN=NODE1 SVN=SERVER1 SVC=*')
The command string can be any BBOC command. If to set up a registration with the name WASAPP that consists of 10 minimum connections and 100 maximum during CICS startup, we specify the following: 
INITPARM=(BBOACPL2='REG RGN=WASAPP DGN=DAE1 NDN=NODE1 SVN=SERVER1 MNC=10 MXC=100')
With this, we must not use the Register API in the applications and instead use the other APIs immediately, for example Invoke, Connection Get, and Send Request and so on.

Important: There is a CICS limitation in that there can only be one INITPARM per program (BBOACPL2). Therefore, we can do this once in the CICS startup parameters.

The source and JCL for the BBOACPLT and BBOACPL2 provided PLTPI programs is provided in /<install_root>/AppServer/util/zos/OLASamples as files bboacplt.jclsamp and bboacpl2.jclsamp. There is another sample PLTPI program also provided. /<install_root>/AppServer/util/zos/OLASamples/bboacpl3.jclsamp provides an example that shows how to issue multiple BBOC commands during CICS start-up.

There is also sample JCL showing how to assemble your PLT with these programs included in /<install_root>/AppServer/util/zos/OLASamples/DFHPLTOL.jclsamp.

Stopping Link Servers during CICS Shut-down

There is a need to unregister and stop any running Link Servers before CICS shutdown, otherwise normal shutdown may be unable to proceed. We can do one of the following to unregister and stop a Link Server before/during CICS shutdown:


Running a BBOC command from a program using EXEC CICS LINK PROGRAM('BBOACNTL')

We can drive BBOC operations from your programs using EXEC CICS LINK PROGRAM('BBOACNTL') and passing the command string in the COMMAREA. If the length of the command string in the passed COMMAREA is fewer than 268 characters, we are returned a string containing the result of the execution of the command only. If the length is equal or greater than 268 characters, BBOC/BBOACNTL provides an integer version, integer return code, and integer reason code in the bytes 256 - 268. Here is the structure of the Version 1 returned area:

/* Version 1 DFHCOMMAREA - for EXEC CICS LINK to BBOACNTL */

 struct inputCommarea {
   char command[256];
 };

 struct outputCommarea_v1 {
   char message[256];
   int version;
   int returnCode;
   int reasonCode;
 };

 struct BBOACNTL_Commarea {
   union {
     struct inputCommarea input;
     struct outputCommarea_v1 output;
   };
 };

When a COMMAREA greater than or equal to 268 bytes is passed as input to BBOACNTL, it gets back a message response in the first 256 bytes followed by the area shown previously with the Version, Return Code, and Reason Code from the operation executed by BBOC/BBOACNTL. The following are the supported return and reason codes from the EXEC CICS LINK to BBOACNTL:

RC 0 RSN 0
	Request process successfully. The response message in the first 256 bytes provides more information. Search the Information Center with the returned message id for further information about the response.
RC 4 RSN 0
   No Link Servers match the requested registration name or no Link Servers are running in this region. The response message in the first 256 bytes provides more information. Search the Information Center with the returned message id for further information about the response.
RC 8 RSN 0 or higher
   An error occurred in processing the request. The response message in the first 256 bytes provides more information. Search the Information Center with the returned message id for further information about the response.
RC 12 RSN 0 or higher
   An severe error occurred in processing the request. The response message in the first 256 bytes provides more information. Search the Information Center with the returned message id for further information about the response.

Passing the LTSQ parameter in the command string for the EXEC CICS LINK call to BBOACNTL writes a list of the matching active Link Servers to the CICS temporary storage queue passed in the LTSQ parameter. The output record format for each Link Server in the list is documented in the header that is in: /<install_root>/AppServer/util/zos/OLASamples/bboaapic.h and described under the tsq_record struct.


WAS LINK server task for CICS, BB0$

The CICS transaction, BBO$, is used for WAS outbound call support to CICS. It runs in the background as a non-terminal transaction and represents an instance of a server task that is started using operation, BBOC START_SRVR, for a user-specified register name and service name. This server task provides a program LINK invocation capability, or the ability to start an existing CICS program from WAS over the optimized local adapter APIs. The name of this transaction can be overridden by a user-supplied name that can be provided on the BBOC START_SRVR command (STX=xxxx). If this is done, the provided transaction name must be defined to CICS with the same program name and attributes as BBO$.


WAS program LINK invocation task for CICS, BBO#

The CICS transaction, BBO#, is used for WAS outbound call support to CICS. It is a non-terminal transaction that represents an instance of a task that was started by the WAS adapters server task, BBO$, in order to do a program LINK invocation. The BBO$ transaction initiates a BBO# transaction for each CICS program link request from an application that is deployed on WAS.

The name of this transaction can be overridden by a user-supplied name that can be provided on the BBOC START_SRVR command, for example LTX=xxxx. If this is done, the transaction name provided must be defined to CICS with the same program name and attributes as the BBO# transaction. Alternatively, the 4 character name of the link transaction can be passed from WAS by the application that is using the JCA. In this scenario, the application that is using the adapter is using the setLinkTaskTransid method.


Asserting User Identity from WAS to CICS

This server task supports propagation of the user identity from a WAS call into CICS, and the assertion of that identity. The assertion is done only if the Register task was done with the security parameter set to SEC=Y. This is implemented using an EXEC CICS START TRANSACTION(‘BBO#') USERID(<user_id>).

A SAF SURROGAT class definition must be defined to ensure that the user ID that the BBO$ transaction is running under has the authority to start a transaction on behalf of the passed in user ID.

If we run BBOC STRT_SRVR with SEC=N the user ID associated with inbound requests to CICS is the user ID that executed the BBOC transaction.


Sample BBOC invocations

The following are samples of BBOC invocations that demonstrate how various tasks and configurations can be accomplished with the CICS adapters program link support.


Support for CICS channels and container objects

For messages larger than 32 K, CICS application programs that are started from WAS are required to receive data and send response data using CICS channels and containers. Applications deployed in WAS can use the supplied JCA programming interface to provide the name and type (BIT|CHAR) of the CICS container that passes the data to the target program, and the name and type of container that receives the response from the application.

There are two ways to pass channels and containers to CICS. In both cases, the setUseCICSContainer() method on the ConnectionSpecImpl must be set to '1'.


Related:

  • Optimized local adapters for z/OS APIs
  • Optimized local adapters for z/OS usage scenarios
  • Optimized local adapters on WAS for z/OS
  • Planning to use optimized local adapters for z/OS
  • Install the WebSphere BBOC, BBO$ and BBO# transactions in CICS