This topic applies only on the z/OS operating system.

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®, 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, refer to 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:
  • Register name - RGN

    The RGN parameter is the 12 character register name.

  • Daemon group name - DGN

    DGN is the eight character daemon group name to register with.

  • Node short name - NDN

    NDN is the eight character node short name to register with.

  • 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 eight characters and might be masked with an * (asterik). 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 the proper SURROGAT SAF set up 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.

    [Fix Pack 12 or later] 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 syncpoint is implied, such as when the CICS task ends.

    [Fix Pack 12 or later] 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.

  • 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 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 results 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 needs to 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#) should remain active and be reused. When this count is reached, the Link task terminates. The maximum value that can be provided 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#) should remain active and be reused. When this time interval expires, after the next request is received and processed, the Link task terminates. The maximum value that can be provided 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.
Table 1. BBOC. The following table summarizes BBOC operation names, descriptions, and parameters.
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>

REUC=< number_of_requests>

REUT=<number_of_seconds>

STOP_SRVR STP Stop the WebSphere Application Server task for Registration name. RGN=<name>

TRC=0/1/2

TDQ=<tdqname>

Running a BBOC command automatically during CICS start-up

You can automatically register an optimized local adapters link when CICS starts. This starts a long running task BBO# which exists until the link is unregistered. There is a need to unregister the link prior to CICS shutdown otherwise the CICS shutdown is held up for some minutes until CICS finally cancels the BBO# transaction. You can do one of the following to unregister a link:
  • Run BBOC STOP_SERVER for all CICS Link servers
  • Purge the BBO$ tasks
  • Write a Program List Table (PLT) shutdown program that EXEC CICS LINKs to BBOACNTL for each Link server passing the STOP_SERVER string
  • Issue CEMT P SHUT,IMMED
There are two CICS Program List Table Post-Initialization (PLTPI) programs provided in the load library that is created by the olaInstall.sh script. This load library can be used to run BBOC commands during CICS startup. Add BBOACPLT to your CICS PLT as phase 2 or phase 3 entries 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 startup 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.

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, as well as 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

Support for CICS channels and container objects

For messages larger than 32K, 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.




Related concepts
Optimized local adapters for z/OS APIs
Optimized local adapters for z/OS usage scenarios
Optimized local adapters on WebSphere Application Server for z/OS
Related tasks
Planning to use optimized local adapters for z/OS
Installing the Websphere BBOC, BBO$ and BBO# transactions in CICS
Reference topic    

Terms of Use | Feedback

Last updated: Oct 21, 2010 10:04:34 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=compass&product=was-nd-mp&topic=rdat_cics
File name: rdat_cics.html