WebSphere Application Server 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 that are 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®, WebSphere 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 WebSphere Application Server, 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, that can be used to automatically begin the TRUE program during CICS startup. If you 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.

WebSphere Application Server 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 WebSphere Application Server TRUE, and to set tracing levels for debugging the APIs and WebSphere Application Server-interfacing code. BBOC also sets registrations and unregistrations, and starts and stops WebSphere Application Server 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:

CICS transaction identifier - CTID
The CTID parameter is an optional four character CICS transaction identifier to use for transaction recovery. The Optimized Adapters CICS Control transaction program, BBOACNTL, uses the CICS transaction identifier when it is specified on the CTID= statement. If the CTID= statement is not specified and the CICS transaction identifier is the CPLT value, the BBOC value is used as the CICS transaction identifier instead of the CPLT value.
Daemon group name - DGN
DGN is the eight character daemon group name to register with.
Link Sync-on-return - LSYNC
LSYNC controls whether the SYNCONRETURN option is used when linking to the target program under the link server. When LSYNC=Y, the SYNCONRETURN option is passed to CICS when the target program is linked to, and uses EXEC CICS LINK. This option might be needed when the target program is in another CICS region. The default value is LSYNC=N.
Node short name - NDN
NDN is the eight character node short name to register with.
Register name - RGN
The RGN parameter is the 12 character register name.
Server short name - SVN
SVN is the eight character target server short name.
Service name - SVC
SVC is the service name with a maximum of 8 characters and might be masked with an * (asterisk). This parameter supports *, abc*, *abc, abc*xyz, abc*xy*z, and so on.
Minimum connections - MNC
MNC is the minimum connections. The minimum is 0. This defaults to 1 if a value is not provided.
Maximum connections - MXC
MXC is maximum connections. The maximum is 99999. This defaults to 10 if a value is not provided.
Security propagation - SEC
SEC is the security propagation and is set Y or N for yes or no. SEC=N is the default. For SEC=N, and calling from CICS to WebSphere Application Server, the CICS region user ID is propagated. For SEC=N and calling from WebSphere Application Server to CICS under the Link server (BBO$ task), the Link task runs under the user ID that the Link server was started. For SEC=Y and calling from CICS to WebSphere Application Server, the task level user ID is propagated to WebSphere Application Server. For SEC=Y and calling from WebSphere Application Server to CICS, the Link server attempts to start the Link task (BBO#) with the propagated user ID from WebSphere Application Server. This works only if a valid SURROGAT SAF setup has been completed that permits the user ID that the Link server is running under to issue EXEC CICS START TRAN('BBO#') USERID(<propagated_id>).
TXN
TXN describes the transactional behavior of the registration that is generated by the BBOC transaction.

When BBOC is creates a registration using the REGISTER operation, TXN=Y signifies that any Java™ Platform, Enterprise Edition applications started in the WebSphere Application Server using this registration should join the current CICS unit of work. This creates a global transaction between CICS and WebSphere Application Server, which completes by using the two-phase commit protocol when the CICS application issues an EXEC CICS SYNCPOINT, or when a sync point is implied, such as when the CICS task ends.

When BBOC is used to create a link server by using the START_SRVR function, TXN=Y signifies that the CICS link server task should join the current WebSphere Application Server transaction when a service is invoked. For example, if a Java Platform, Enterprise Edition application starts a resource manager local transaction (RMLT) and invokes a CICS program by using the optimized local adapters JCA connector, the link task joins the local transaction and then invoke the target CICS program. Updates that are made in the CICS program are not committed or backed out until the Java Platform, Enterprise Edition application completes the RMLT by using the commit or rollback API.
Link server CICS transaction ID - STX
STX is the four character name of the Link Server CICS transaction ID to use. The default value for STX is BBO$.
Link task transaction ID - LTX
LTX is the four character name of the Link-to Program CICS transaction ID to be used. The default for LTX is BBO#. If these transaction names are replaced with user-supplied names, they must be defined with the same program name and attributes as BBO$ (for STX) and BBO# (for LTX).
Trace - TRC
Tracing is enabled and set during the processing of any of the commands that are listed in the table. There are three trace levels:
- 0 = none and error messages only
- 1 = basic
- 2 = detailed
Transient data queue - TDQ
Trace data under CICS is written to the extra-partition TDQ that is requested. The TDQ parameter specifies a four character name of the CICS extra-partition TDQ where adapter messages are to be written. If the four character name is not provided, it defaults to BBOQ and DD BBOOUT. If there is a problem writing to the selected TDQ, messages are instead written to the CICS region stdout (tdq CESO dd CEEOUT).
Reuse - REU
If it is determined that the Link server can run with SEC=N, the best performance is achieved by also running with the REU=Y BBOC START_SRVR parameter. REU=Y results in the Link server reusing the program Link invocation tasks (BBO# transactions) between program invocation requests.
Important: If you run the Link server in this configuration, the support in the optimized local adapters JCA for passing a separate LINK transaction ID for individual requests is disabled and a request for this result in a ResourceException thrown back to the application. Also, if you attempt to select REU=Y and SEC=Y, the reuse option is forced to No as the Link server must start a new Program Link task for each request with the identity that was propagated asserted.
Reuse count - REUC
Enter the number of requests that the CICS Link task (BBO#) remains active and is reused. When this count is reached, the Link task terminates. The maximum value is 2147483648.
Important: For a transactional scenario, the Link task terminates after the count is reached and the next commit is received from the application server.
Reuse time - REUT
Enter the number of seconds that the CICS Link task (BBO#) remains active and is reused. When this time interval expires, after the next request is received and processed, the Link task terminates. The maximum value is 2147483648.
Important: For a transactional scenario, the Link task terminates after the requested time is reached and the next commit is received from the application server.
Propagate Transaction ID - RTXP
RTXP=(Y|N) indicates whether the EXEC CICS LINK PROGRAM() command that is run by the Link invocation task (BBO#) includes the TRANSID() parameter. When the RTXP parameter is set to Y, it puts the current value of the EIBTRNID variable in the TRANSID() parameter.
List Link Servers Temporary Storage queue name - LTSQ
LTSQ only applies to the LIST_SRVR operation. LTSQ is the name of a CICS temporary storage queue name where the list of Link Servers and information for each is written. It can be a string up to 8 characters long. A C header file that shows the format of the output records is provided in /<install_root>/AppServer/util/zos/OLASamples/bboaapic.h and described under the tsq_record struct.

Table 1. BBOC . The following table summarizes BBOC operation names, descriptions, and parameters.
Operation name	Abbreviation	Abbreviation, Description	Parameter statements
START_TRUE	STR	Start the WebSphere Application Server TRUE	TRC=0/1/2 TDQ=<`tdqname`> CTID=<`CICS_transaction_ID`>
STOP_TRUE	PTR	Stop the WebSphere Application Server TRUE	TRC=0/1/2 TDQ=<tdqname>
REGISTER	REG	Register with the WebSphere Application Server 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> RTXP=<yes\|no> SEC=<yes\|no> TXN=<yes\|no> TRC=0\|1\|2 TDQ=<tdqname>
UNREGISTER		Unregister with the WebSphere Application Server optimized local adapters	RGN=<name>
START_SRVR	STA	Start the WebSphere Application Server 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> RTXP=<yes\|no>
STOP_SRVR	STP	Stop the WebSphere Application Server 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. You 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

You 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 that is 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 if you want 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 you to issue a BBOC command during CICS start-up by using INITPARM data. You 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 you want to set up a registration with the name WASAPP that consists of 10 minimum connections and 100 maximum during CICS startup, you specify the following:

INITPARM=(BBOACPL2='REG RGN=WASAPP DGN=DAE1 NDN=NODE1 SVN=SERVER1 MNC=10 MXC=100')

With this, you must not use the Register API in your 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, you 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. You can do one of the following to unregister and stop a Link Server before/during CICS shutdown:

Run BBOC STOP_SERVER for all CICS Link servers before CICS shutdown
Add the IBM® provided Program List Table shutdown (PLTSD) program BBOACPLS to your shutdown PLT. This PLTSD executes a BBOC LIST_SRVR to identify all running Link Servers in the region and it will then issue a STOP_SRVR operation for each of them. A sample JCL showing how to add this to your PLT shutdown list is provided in /<install_root>/AppServer/util/zos/OLASamples/DFHPLTO2.jclsamp
Purge the BBO$ tasks
Write your own PLT shutdown program that EXEC CICS LINKs to BBOACNTL for each Link server by passing the STOP_SERVER string
Issue CEMT P SHUT,IMMED

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

You can drive BBOC operations from your programs by 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, you are returned a string that contains 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 documentation 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 documentation 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 documentation 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 documentation 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.

WebSphere Application Server LINK server task for CICS, BB0$

The CICS transaction, BBO$, is used for WebSphere Application Server 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 WebSphere Application Server 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$.

WebSphere Application Server program LINK invocation task for CICS, BBO#

The CICS transaction, BBO#, is used for WebSphere Application Server outbound call support to CICS. It is a non-terminal transaction that represents an instance of a task that was started by the WebSphere Application Server 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 WebSphere Application Server.

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 that is 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 WebSphere Application Server 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 WebSphere Application Server to CICS

This server task supports propagation of the user identity from a WebSphere Application Server 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 you 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.

Start the adapters CICS TRUE program.
bboc start_true
Stop the adapters CICS TRUE program.
bboc stop_true
Register with the name, CICS-HR1, in the daemon group, SY1, with the node, SY1, and with the server BBOS001, with 10 maximum connections and 5 minimum connections. Set the transactional to no and the security propagation to yes.
bboc register rgn=CICS-HR1 svn=bbos001 dgn=sy1 ndn=sy1 mnc=5 mxc=10 txn=n sec=y
Unregister with the name, CICS-HR1.
bboc unregister rgn=CICS-HR1
Start a server transaction as BBO$ for all service and program names under the registration name, CICSPAYR, with a daemon group, node, and server with 10 maximum connections and 5 minimum connections. Set the transactional to no and security propagation to yes.
bboc start_srvr rgn=CICSPAYR svn=bbos001 dgn=sy1 ndn=sy1 mnc=5 mxc=10 sec=y
Stop the BBO$ server transaction running under the registration name, CICSPAYR.
bboc stop_srvr rgn=CICSPAYR
Start a server transaction as BBO$ for the service and program names starting with PAYR under the registration name, CICSPAY1, with a daemon group, node, server with 10 maximum connections and 5 minimum connections. The transaction is no and security propagation is yes.
bboc start_srvr rgn=CICSPAY1 svn=bbos001 dgn=sy1 ndn=sy1 mnc=5 mxc=10 sec=y svc=PAYR*
Start a server transaction under the transaction ID, PAY2, and register with the name, PAYROLL2, for all service and program names in a daemon group, node, and server, with 10 maximum connections and 5 minimum connections. The transactional parameter value is yes, security propagation value is yes, and the tracing set to level 1.
bboc start_srvr rgn=PAYROLL2 svn=bbos001 dgn=sy1 ndn=sy1 mnc=5 mxc=10 sec=y stx=PAY2 trc=1
Start a server transaction under the transaction ID, PAY3, and the link transaction ID of PY3L. Register with the name, PAYROLL3, for service and program names starting with PAYRL3 in a daemon group, node, and server with 10 maximum connections and 5 minimum connections. The transactional parameter value is yes and the security propagation parameter value is yes with tracing set to level 1.
bboc start_srvr rgn=PAYROLL3 svn=bbos001 dgn=sy1 ndn=sy1 mnc=5 mxc=10 sec=y svc=PAYRL3* stx=PAY3 ltx=PY3L trc=1
List all Link Servers running in this CICS region
bboc list_srvr
List all Link Servers running in this CICS region with a Registration name of CICSPAY1
bboc list_srvr rgn=CICSPAY1
List all Link Servers running in this CICS region that start with a Registration name of CICS and copy the list to a Temporary Storage Queue called MYSRVRS
bboc list_srvr rgn=CICS* ltsq=MYSRVRS
List all Link Servers running in this CICS region that start with a Registration name that starts with 'CICS' then any character followed by 'ZZZ' and any other characters after that
bboc list_srvr rgn=CICS?ZZZ*

Support for CICS channels and container objects

For messages larger than 32 K, CICS application programs that are started from WebSphere Application Server are required to receive data and send response data using CICS channels and containers. Applications that are deployed in WebSphere Application Server 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'.

When passing a single container and receiving a single container, the methods setLinkTaskReqContid, setLinkTaskRspContid, setLinkTaskReqContType(bit|char) and setLinkTaskRspContType(bit|char) can be used. For both the request and the response, the channel name, IBM-WAS-ADAPTER, is used. This channel name is fixed.
Alternatively, the JCA MappedRecord interface can be used to send and receive one or more containers from a target CICS program. When using the MappedRecord, use the setLinkTaskChanID() and setLinkTaskChanType() methods of the ConnectionSpecImpl to set the channel name which will be used to hold the request and response containers, as well as the type of containers (bit or char) which will be contained in the channel.
The names of the individual request containers are set by adding data to the MappedRecord, using the put() method.

The keys of the MappedRecord correspond to the CICS container names, and the corresponding value are used to fill the container in CICS. The key must be a String object with a length between 1-16 characters. The value can be either a byte[], or a RecordBytes object generated by tooling such as Rational® Application Developer.

The response container names are extracted from the channel after the CICS request is finished, and populated into a new MappedRecord, which is returned to the client.