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.
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 RGN parameter is the 12 character register name.
DGN is the eight character daemon group name to register with.
NDN is the eight character node short name to register with.
SVN is the eight character target server short name.
SVC is the service name with a maximum of eight characters and might be masked with an * (asterisk). This parameter supports *, abc*, *abc, abc*xyz, abc*xy*z, and so on.
MNC is the minimum connections. The minimum is 0. This defaults to 1 if a value is not provided.
MXC is maximum connections. The maximum is 99999. This defaults to 10 if a value is not provided.
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 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 J2EE 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 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 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 J2EE application starts a resource manager local transaction (RMLT) and invokes a CICS program using the optimized local adapters JCA connector, the link task joins the local transaction and then invoke the target CICS program. Updates made in the CICS program are not committed or backed out until the J2EE application completes the RMLT using the commit or rollback API.
STX is the four character name of the Link Server CICS transaction ID to use. The default value for STX is BBO$.
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 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).
Operation name | Abbreviation | Abbreviation, Description |
Parameters |
---|---|---|---|
START_TRUE | STR | Start the WebSphere Application Server TRUE | TRC=0/1/2 TDQ=<tdqname> |
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> 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> |
STOP_SRVR | STP | Stop the WebSphere Application Server task for Registration name. | RGN=<name> TRC=0/1/2 TDQ=<tdqname> |
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.
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$.
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.
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.
bboc start_true
bboc stop_true
bboc register rgn=CICS-HR1 svn=bbos001 dgn=sy1 ndn=sy1 mnc=5 mxc=10 txn=n sec=y
bboc unregister rgn=CICS-HR1
bboc start_srvr rgn=CICSPAYR svn=bbos001 dgn=sy1 ndn=sy1 mnc=5 mxc=10 sec=y
bboc stop_srvr rgn=CICSPAYR
bboc start_srvr rgn=CICSPAY1 svn=bbos001 dgn=sy1 ndn=sy1 mnc=5 mxc=10 sec=y svc=PAYR*
bboc start_srvr rgn=PAYROLL2 svn=bbos001 dgn=sy1 ndn=sy1 mnc=5 mxc=10 sec=y stx=PAY2 trc=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
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. The methods setLinkTaskReqContid, setLinkTaskRspContid, setLinkTaskReqContType(bit|char) and setLinkTaskRspContType(bit|char) support this. For both cases, the channel name, IBM-WAS-ADAPTER, is used. This channel name is fixed.