Liberty server transactions for CICS: BBOC, BBO$, and BBO#

WebSphere® optimized local adapters (WOLA) are supported in the CICS® product through the BBOC, BBO$, and BBO# transactions.

The optimized local adapters run in a CICS region as a resource manager. In CICS, the Task Related User Exit (TRUE) is the primary vehicle that is used by resource providers. TRUE support provides the boundary between the CICS application threads and the external resource manager threads. Currently, DB2®, WebSphere MQ, and TCPIP sockets run in CICS using the TRUE support.

Applications that run under CICS use the optimized local adapter APIs according to the following workflow:
  1. The application runs the provided stub routines.
  2. The stub routines start the CICS resource manager interface module, passing it the name of the optimized local adapter TRUE routine, BBOATRUE, and the parameters specific to each API.
  3. CICS dispatches the TRUE on one of the OPENAPI task control blocks (TCBs) and runs until the API call is completed.
  4. The call goes back to CICS with the output parameters.
See the following sections for more information about the Liberty server transactions for CICS:

Control transaction for CICS: BBOC

The BBOC transaction is the WebSphere control, or operations transaction, for the adapters support under CICS. You can use the transaction to enable and start the Liberty server TRUE and to set tracing levels for debugging the APIs and code that interfaces with the Liberty server. BBOC also sets registrations and unregistrations, and starts and stops link server tasks in CICS. These server tasks provide support for starting existing CICS programs and passing data with COMMAREA objects or containers with the input parameters over the adapters. BBOC is a CICS workstation-based transaction that you can run on a 3270 workstation or from a sequential, or SDSCI-type, workstation.

The syntax for the BBOC transaction is BBOC operation_name parameters, where multiple parameters are separated by one or more spaces. The following parameters are available for the BBOC transaction:

RGN
The 12-character register name
DGN
The first eight-character name of the WOLA group to join
NDN
The second eight-character name of the WOLA group to join
SVN
The third eight-character name of the WOLA group to join
LSYNC
LSYNC controls whether CICS passes the SYNCONRETURN option when it links to the target program. If you specify LSYNC=Y, the CICS link server passes the SYNCONRETURN option on the EXEC CICS LINK command. You might need to specify this option when the target program is in another CICS region. The default value is LSYNC=N.
SVC
The service name of a maximum of 8 characters. The parameter supports masking with asterisks (*); for example, you can specify *, abc*, *abc, abc*xyz, abc*xy*z, and so on.
MNC
The number of minimum connections. The minimum value is 0, and the default value is 1.
MXC
The maximum number of connections. The maximum value is 9999, and the default value is 10.
SEC
The SEC parameter controls which user ID is propagated. The default value is SEC=N.

If you specify SEC=N and are calling from CICS to the Liberty server, the CICS region user ID is propagated. If you specify SEC=N and are calling from the Liberty server to CICS under the link server task (BBO$), the link task runs under the user ID of the started link server.

If you specify SEC=Y and are calling from CICS to the Liberty server, the task-level user ID is propagated to the Liberty server. If you specify SEC=Y and are calling from the Liberty server to CICS, the link server attempts to start the link task (BBO#) with the propagated user ID from the Liberty server. The propagation works only if you created a System Authorization Facility (SAF) SURROGAT class definition to permit the user ID of the link server to issue the EXEC CICS START TRAN('BBO#') USERID(<propagated_id>) command.

STX
The four-character name of the link server CICS transaction ID to use. The default value is BBO$.
Note: If you define a transaction name that is different from the default, you must also define the transaction in the primary CICS system definition (CSD) file, DFHCSD, with the same program name and attributes as BBO$.
LTX
The four-character name of the link-to-program CICS transaction ID to use. The default value is BBO#.
Note: If you define a transaction name that is different from the default, you must also define the transaction in the primary CICS system definition (CSD) file, DFHCSD, with the same program name and attributes as BBO#.
TRC
Defining a value for this parameter enables tracing at the following levels:
  • When set to 0: No tracing; error messages only
  • When set to 1: Basic tracing
  • When set to 2: Detailed tracing
TDQ
The four-character name of the CICS extra-partition transient data queue (TDQ) where adapter messages are written. If you do not specify this parameter, the default is BBOQ and DD BBOUT. If messages cannot be written to the specified TDQ, they are written to the CICS region stdout, tdq CESO dd CEEOUT.
REU
REU controls whether the link server reuses the program link invocation tasks (BBO# transactions) between program invocation requests. The default value is N.
Important: If you run the link server with SEC=N and REU=Y, the optimized local adapter JCA no longer supports passing a separate link transaction ID. Requests for a separate transaction ID result in a ResourceException in the application. If you attempt to run the link server with SEC=Y and REU=Y, the reuse option is forced to No because the link server must start a new program link task for each request and assert the propagated identity.
REUC
The number of requests for which the CICS link task (BBO#) remains active and is reused. When this count is reached, the link task ends. The maximum value is 2147483648.
Important: For a transactional scenario, the link task ends after the count is reached and the next commit is received from the Liberty server.
REUT
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 ends. The maximum value is 2147483648.
Important: For a transactional scenario, the link task ends after the requested time is reached and the next commit is received from the Liberty server.
RETRY

Indicates that a start server or register request should be retried if it is unable to connect with the requested target server. When RETCNT and RETINT are not specified, the default number of times to retry is 10 and the default time between retries is 30 seconds.

RETCNT

When RETRY=Y is provided, RETCNT indicates the number of times the command will be retried after failing before the request is no longer attempted. The minimum value is 1 and the maximum value is 99999999. A value of 0 implies the maximum value. If the value is not supplied and the RETRY=Y option is provided, the default number of retries is 10.

RETINT

When RETRY=Y is provided, RETINT indicates the number of seconds in the time interval between retries. The minimum value is 1 and the maximum is 359000. A value of 0 implies the maximum value. If the value is not supplied and the RETRY=Y option is provided, the default number of seconds between retries is 30.

RTXP

RTXP=(Y|N) indicates that the EXEC CICS LINK PROGRAM() performed by the Link invocation task (BBO#) should have the TRANSID() option included. When this is provided without the RTX (remote transaction) parameter, it will put the current EIBTRNID value in the TRANSID() parameter.

RTX

RTX, when used with the RTXP parameter, indicates that the EXEC CICS LINK PROGRAM() performed by the Link invocation task (BBO#) should have the TRANSID() option included. The value for this option comes from the RTX parameter. When this is not passed and RTXP=Y is supplied the current EIBTRNID value is used in the TRANSID() parameter.

TXN
TXN describes the transactional behavior of the registration that is generated by the BBOC transaction. This option is only supported by registrations to WebSphere Traditional server instances.

When BBOC creates a WOLA registration by using the REGISTER operation, TXN=Y signifies that any Java Platform, Enterprise Edition applications started in the WebSphere Application Server that use this registration joins the current CICS unit of work. When TXN=Y, a global transaction is created 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 joins the current WebSphere Application Server transaction when a service is started. For example, if a Java Platform, Enterprise Edition application starts a resource manager local transaction (RMLT) and starts a CICS program by using the optimized local adapters JCA connector, the link task joins the local transaction and then starts 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.

CTID

The optional CTID parameter specifies a four character CICS transaction identifier that is used for transaction recovery. BBOACNTL, the Optimized Adapters CICS Control transaction program, uses the CICS transaction identifier that is specified by the CTID parameter. If the CTID parameter is not specified and the CICS transaction identifier is CPLT, the BBOC value is used as the CICS transaction identifier instead of the CPLT value.

LTSQ

LTSQ identifies the list of link servers temporary storage queue name. LTSQ only applies to the LIST_SRVR operation. LTSQ specifies 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 Description Parameters, with value descriptions
START_TRUE STR Start the Liberty server TRUE TRC=<0|1|2>

TDQ=<tdqname>

CTID=<CICS_transaction_ID>
STOP_TRUE PTR Stop the Liberty server TRUE TRC=<0|1|2>

TDQ=<tdqname>
REGISTER REG Register with the Liberty server WOLA group RGN=<name>

DGN=<name>

NDN=<name>

SVN=<name>

MNC=<minimum_number_ of_connections>

MXC=<maximum_number_ of_connections>

SEC=<Y|N>

TRC=<0|1|2>

TDQ=<tdqname>

RTXP=<Y|N>

RTX=<remote_transaction_ID>

RETRY=<Y|N>

RETCNT=<number_of_requests>

RETINT=<number_of_seconds>

TXN=<Y|N>
UNREGISTER   Unregister with the Liberty server optimized local adapters RGN=<name>
START_SRVR STA Start the Liberty server task for the passed register name. RGN=<name>

DGN=<name>

NDN=<name>

SVC=<name>

SVN=<name>

MNC=<minimum_number_ of_connections>

MXC=<maximum_number_ of_connections>

SEC=<Y|N>

STX=<CICS_link_server_ transaction_ID>

LTX=<CICS_link_server_ transaction_ID>

TRC=<0|1|2>

TDQ=<tdqname>

REU=<Y|N>

REUC=<number_of_requests>

REUT=<number_of_seconds>

RTXP=<Y|N>

RTX=<remote_transaction_ID>

RETRY=<Y|N>

RETCNT=<number_of_requests>

RETINT=<number_of_seconds>

TXN=<Y|N>
STOP_SRVR STP Stop the Liberty server task for the register name. RGN=<name>

TRC=<0|1|2>

TDQ=<tdqname>
DOCTEMPLATE DOC DOCTEMPLATE (DOC) indicates that the command string (BBOC command and all arguments) should be read from a CICS document template source. Specifying BBOC DOC NAME=<template_name> indicates that the entire request is located in a single line of a document template with the provided name. Refer to the CICS documentation for information on defining document templates. This provides the ability to have long command strings (up to 500 characters maximum) read from datasets, dataset members, and files in the file system of the CICS region. Specifying a BBOC DOC NAME=<> request inside a document template source file is not supported. NAME=<CICS_document_template_name>TRC=<0|1|2>
LIST_SRVR LST List all the link servers matching the supplied registration name. The parameters here are all optional, including registration name. When issued with no parameters, a list of all link servers is returned. 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=<temporary storage queue>

TRC=<0|1|2>

TDQ=<tdqname>

Sample BBOC commands

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 WOLA group with names LIB1, LIB2, and LIB3, with 10 maximum connections, 5 minimum connections, and security propagation.

    bboc register rgn=CICS-HR1 dgn=LIB1 ndn=LIB2 svn=LIB3 mnc=5 mxc=10 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 WOLA group with 10 maximum connections, 5 minimum connections, and security propagation.

    bboc start_srvr rgn=CICSPAYR dgn=LIB1 ndn=LIB2 svn=LIB3 mnc=5 mxc=10 sec=y

  • Stop the BBO$ server transaction that is running under the registration name, CICSPAYR.

    bboc stop_srvr rgn=CICSPAYR

  • Start a server transaction as BBO$ for the service and program names that start with PAYR under the register name, CICSPAY1, with a WOLA group with 10 maximum connections, 5 minimum connections, and security propagation.

    bboc start_srvr rgn=CICSPAY1 dgn=LIB1 ndn=LIB2 svn=LIB3 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 WOLA group with 10 maximum connections, 5 minimum connections, basic tracing, and security propagation.

    bboc start_srvr rgn=PAYROLL2 dgn=LIB1 ndn=LIB2 svn=LIB3 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 that start with PAYRL3 in a WOLA group with 10 maximum connections, 5 minimum connections, basic tracing, and security propagation.

    bboc start_srvr rgn=PAYROLL3 dgn=LIB1 ndn=LIB2 svn=LIB3 mnc=5 mxc=10 sec=y svc=PAYRL3* stx=PAY3 ltx=PY3L trc=1

  • Start a link server transaction where the parameters are all read from a CICS Document Template source called LONGCMD

    bboc doc name=LONGCMD

  • 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*

Automatically running a BBOC command during CICS startup

Two CICS Program List Table Post-Initialization (PLTPI) programs, BBOACPLT and BBOACPL2, are provided as samples on GitHub. For more information, see Optimized local adapters samples for Liberty.
  • To start the optimized local adapters TRUE when CICS starts, add BBOACLPT as phase 2 or phase 3 entries in your CICS PLT.
  • To issue a BBOC command using INITPARM data when CICS starts, add BBOACLP2 as phase 2 or phase 3 entries in your CICS PLT.
You can pass a string of commands up to the CICS limit of 60 characters inside the INITPARM. The following sample INITPARM string calls BBOACPL2 and passes a request to start a link server under the register name PAYROLL, with WOLA group names of LIB1, LIB2, and LIB3. By specifying SVC=*, this link server receives requests for all service names.
INITPARM=(BBOACPL2='STA RGN=PAYROLL DGN=LIB1 NDN=LIB2 SVN=LIB3 SVC=*')
The command string can be any BBOC command, such as REG in the following sample INITPARM string. When CICS starts, the string creates a registration under the name LIBAPP that consists of 10 minimum connections and 100 maximum connections.
INITPARM=(BBOACPL2='REG RGN=LIBAPP DGN=LIB1 NDN=LIB2 SVN=LIB3 MNC=10 MXC=100')

If you create a registration when CICS starts, do not use the Register API in your applications. Instead, immediately use the other APIs, such as Invoke or Connection Get.

Important: You can use only one INITPARM string per BBOACPL2 program.
If you use the PLT programs to automatically create a registration or a link server, be sure to unregister or stop the server before you shut down CICS to avoid a delay while CICS cancels any remaining optimized local adapters transactions. You can remove the optimized local adapters resources in the following ways:
  • Run BBOC STOP_SERVER for all CICS link servers or run BBOC URG for all registrations.
  • Purge the BBO$ tasks.
  • Write a Program List Table (PLT) shutdown program that runs the EXEC CICS LINK command to BBOACNTL for each link server that passes the STOP_SERVER string. The LIST_SRVR operation may be used to identify all running link servers in the region.
  • Issue the following command: CEMT P SHUT,IMMED

Link server transaction for CICS: BBO$

The BBO$ CICS transaction supports calls from the Liberty server to CICS. The BBO$ transaction is a non-workstation transaction that represents an instance of a server task that is started with the BBOC START_SRVR operation for a certain register name and service name. This server task provides program link invocation capability, which is the ability to start an existing CICS program from the Liberty server over the optimized local adapter APIs.

You can override the name of the transaction, BBO$, by specifying STX=name on the BBOC START_SRVR command. The new transaction name must be defined to CICS with the same program name and attributes as BBO$. For more information, see Optimized local adapter definitions for CICS.

Program link invocation transaction for CICS: BBO#

The BBO# CICS transaction supports calls from the Liberty server to CICS. The BBO# transaction is a non-workstation transaction that represents an instance of a task that the link server task, BBO$, starts to invoke a program link. The BBO$ transaction initiates a BBO# for each CICS program link request from a Liberty server application.

You can override the name of the transaction, BBO#, by specifying LTX=name on the BBOC START_SRVR command. The new transaction name must be defined to CICS with the same program name and attributes as BBO#. For more information, see Optimized local adapter definitions for CICS. Alternatively, the Liberty server application can pass the new transaction name to CICS using the JCA setLinkTaskTransid method.