[z/OS]

WebSphere Application Server 事务 BBOC、BBO$ 和 BBO#

本主题描述客户信息控制系统 (CICS®) 产品中如何支持优化的本地适配器,包括已介绍的 WebSphere® Application Server 事务 BBOC、BBO$ 和 BBO#。

适配器作为资源管理器在 CICS 区域中运行。在 CICS 中,资源提供程序的主要工具是任务相关用户出口 (TRUE)。TRUE 支持界定了 CICS 应用程序线程与外部资源管理器线程之间的界限。借助 TRUE 支持,目前在 CICS 中使用 DB2®、WebSphere MQ 和 TCP/IP 套接字。优化的本地适配器支持 TRUE。

在 CICS 中运行且采用优化的本地适配器 API 的应用程序通过调用提供的存根例程实现此支持。这些存根例程启动 CICS 资源管理器接口模块,向其传递优化的本地适配器 TRUE 例程名称以及特定于每个 API 的参数。CICS 在 CICS 所维护的其中一 个 OPENAPI TCB 上分派 TRUE,并运行直到 API 调用完成。然后调用携带输出参数返回 CICS。CICS TRUE 支持还能够跨事务边界(例如,在应用程序结束、异常中止或者对 CICS 发出显式 SYNCPOINT 调用时)提供通知。有关此支持如何用于将事务上下文传播到 WebSphere Application Server 以及有关两阶段落实的详细信息,请参阅本主题中关于“传播事务”的章节。另外,对于 CICS,还提供了初始化后程序列表 (PLTPI) 程序,此程序可用于在 CICS 启动期间自动开始 TRUE 程序。如果您不使用 PLTPI,那么系统将提供 CICS 事务 BBOC。此事务可用来开始、停止、启用和禁用对 TRUE 模块的跟踪。

WebSphere Application Server 的 CICS 控制事务 BBOC

BBOC 事务是用于在 CICS 中提供适配器支持的 WebSphere 控制或操作事务。此事务用于启用和启动 WebSphere Application Server TRUE,并且用于设置跟踪级别以调试与 API 和 WebSphere Application Server 交互的代码。另外,BBOC 还设置注册和注销,并且启动和停止 CICS 中的 WebSphere Application Server 链接服务器任务。这些服务器任务支持启动现有的 CICS 程序,并支持通过适配器传递数据(通过使用 COMMAREA)或容器(通过使用输入参数)。这是一个基于 CICS 终端的事务,可以在 3270 终端上或者从 SDSCI 类型的顺序终端发出此事务。BBOC 语法描述如下所示:

BBOC<operation_name><parameters_separated_by_one_or_more_spaces>.

参数如下所示:
  • 注册名称 - RGN

    RGN 参数是 12 个字符的注册名称。

  • 守护程序组名 - DGN

    DGN 是要注册的 8 字符守护程序组名。

  • Link Sync-on-return - LSYNC

    LSYNC 控制在链接到链接服务器上的目标程序时是否使用 SYNCONRETURN 选项。当 LSYNC=Y 时,在链接至目标程序且目标程序使用 EXEC CICS LINK 时会将 SYNCONRETURN 选项传递至 CICS。当目标程序位于另一个 CICS 区域中时,可能需要此选项。缺省值为 LSYNC=N。

  • 节点短名称 - NDN

    NDN 是要注册的 8 字符节点短名称。

  • 服务器短名称 - SVN

    SVN 是 8 个字符的目标服务器短名称。

  • 服务名称 - SVC

    SVC 是服务名称,最大为 8 个字符,可以使用 *(星号)作为掩码。此参数支持 *、abc*、*abc、abc*xyz、abc*xy*z,等。

  • 最小连接数 - MNC

    MNC 是最小连接数。最小值为 0。如果未提供任何值,那么缺省为 1。

  • 最大连接数 - MXC

    MXC 是最大连接数。最大值为 99999。如果未提供任何值,那么缺省为 10。

  • 安全传播 - SEC

    SEC 是安全传播,它设置为 Y(是)或 N(否)。缺省值为 SEC=N。SEC=N 且从 CICS 调用 WebSphere Application Server 时,将传播 CICS 区域用户标识。SEC=N 且从 WebSphere Application Server 调用链接服务器(BBO$ 任务)上的 CICS 时,链接任务将以启动链接服务器的用户标识运行。SEC=Y 且从 CICS 调用 WebSphere Application Server 时,任务级别用户标识将传播至 WebSphere Application Server。SEC=Y 且从 WebSphere Application Server 调用 CICS 时,链接服务器将尝试使用传播自 WebSphere Application Server 的用户标识启动链接任务 (BBO#)。只有在完成了有效的 SURROGAT SAF 设置的情况下,此操作才会成功。SURROGAT SAF 设置允许正在运行链接服务 器的用户标识发出 EXEC CICS START TRAN('BBO#') USERID(<propagated_id>)。

  • TXN

    TXN 描述 BBOC 事务所生成的注册的事务性行为。

    如果 BBOC 使用 REGISTER 操作创建了一个注册,那么 TXN=Y 表示使用此注册在 WebSphere Application Server 中启动的任何 Java Platform Enterprise Edition 应用程序都应该加入当前 CICS 工作单元。这将在 CICS 与 WebSphere Application Server 之间创建一个全局事务,此事务在下列情况下使用两阶段落实协议完成:CICS 应用程序发出 EXEC CICS SYNCPOINT 时,或者暗示某个同步点时(例如 CICS 任务结束时)。

    当 BBOC 用于使用 START_SRVR 函数创建链接服务器时,TXN=Y 表示在调用服务时 CICS 链接服务器任务应该加入当前 WebSphere Application Server 事务。例如,如果 Java Platform, Enterprise Edition 应用程序启动资源管理器局部事务 (RMLT) 并使用已优化本地适配器 JCA 连接器调用 CICS 程序,那么链接任务将加入该局部事务,然后调用目标 CICS 程序。在 Java Platform Enterprise Edition 应用程序使用落实或回滚 API 完成 RMLT 后,在 CICS 程序中进行的更新才会落实或回退。

  • 链接服务器 CICS 事务标识 - STX

    STX 是要使用的链接服务器 CICS 事务标识的四字符名称。STX 的缺省值为 BBO$。

  • 链接任务事务标识 - LTX

    LTX 是要使用的链接目标程序 CICS 事务标识的四字符名称。LTX 的缺省值为 BBO#。如果使用用户提供的名称替换这些事务名称,那么必须使用与 BBO$(用于 STX)和 BBO#(用于 LTX)相同的程序名称和属性对其进行定义。

  • 跟踪 - TRC
    处理表中列出的任何命令期间启用和设置跟踪。有三种跟踪级别:
    • 0 = 无,仅错误消息
    • 1 = 基本信息
    • 2 = 详细信息
  • 瞬时数据队列 - TDQ

    CICS 中的跟踪数据将写入所请求的额外分区 TDQ。TDQ 参数指定 CICS 额外分区 TDQ 的四字符名称,适配器消息将写入此额外分区 TDQ。如果未提供四字符名称,那么缺省值为 BBOQ 和 DD BBOOUT。如果在写入选定 TDQ 时出现问题,那么改为将消息写入 CICS 区域标准输出 (tdq CESO dd CEEOUT)。

  • 复用 - REU
    如果确定在 SEC=N 时链接服务器可以运行,那么使用 REU=Y BBOC START_SRVR 参数运行同样可获得最佳性能。REU=Y 将导致链接服务器在程序调用请求之间复用程序链接调用任务(BBO# 事务)。
    要点: 如果在此配置中运行链接服务器,那么不支持在优化的本地适配器 JCA 中为各个请求传递单独的 LINK 事务标识,并且发出此请求会导致将 ResourceException 异常抛回给应用程序。另外,如果您尝试选择 REU=Y 和 SEC=Y,那么复用选项将强制为 No,这是因为对于每个声明了所传播的身份的请求,链接服务器必须启动一个新的程序链接任务。
  • 复用计数 - REUC
    输入 CICS 链接任务 (BBO#) 保持活动状态并复用的请求数。达到此计数时,链接任务会终止。最大值为 2147483648。
    要点: 针对事务情境,链接任务在达到此计数后终止,且会从应用程序服务器收到下一个落实。
  • 复用时间 - REUT
    输入 CICS 链接任务 (BBO#) 保持活动状态并复用的秒数。此时间间隔到期时,在收到和处理下一个请求后,链接任务会终止。最大值为 2147483648。
    要点: 针对事务情境,链接任务在达到请求的时间后终止,且会从应用程序服务器收到下一个落实。
  • 列示链接服务器临时存储器队列名称 - LTSQ

    LTSQ 仅适用于 LIST_SRVR 操作。LTSQ 是 CICS 临时存储器队列的名称,在此队列中,会写入链接服务器列表和每个链接服务器的信息。它可以是最长为 8 个字符的字符串。显示输出记录格式的 C 头文件在 /<install_root>/AppServer/util/zos/OLASamples/bboaapic.h 中提供,在 tsq_record 结构下描述。

表 1. BBOC. 下表总结了 BBOC 操作名称、描述和参数。
操作名称 缩写 缩写,

描述

参数
START_TRUE STR 启动 WebSphere Application Server TRUE TRC=0/1/2

TDQ=<tdqname>

STOP_TRUE PTR 停止 WebSphere Application Server TRUE TRC=0/1/2

TDQ=<tdqname>

REGISTER REG 向 WebSphere Application 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   向 WebSphere Application Server 优化的本地适配器注销 RGN=<name>
START_SRVR STA 对传递的注册名称启动 WebSphere Application Server 任务。 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 对注册名称停止 WebSphere Application Server 任务。 RGN=<name>

TRC=0/1/2

TDQ=<tdqname>

LIST_SRVR LST 列示与传入注册名称匹配的所有链接服务器。此处的所有参数都是可选的,包括注册名称。当发出不带参数的命令时,会返回所有链接服务器的列表。您还可以传递带有通配符的 RGN 参数。星号 (*) 指示此点后的所有字符都有效,问号 (?) 表示单个字符可为任何字符。LIST_SRVR 操作的输出写入 BBOQ 或 TDQ 参数上的指定瞬时数据队列。如果传递 LTSQ 参数,那么活动链接服务器的列表会写入指定 CICS 临时存储器队列。 RGN=<name>

LTSQ=<tsqname>

TRC=<0/1/2>

TDQ=<tdqname>

在 CICS 启动和关闭期间自动运行 BBOC 命令

您可以在 CICS 启动时自动启动已优化本地适配器链接服务器。这将启动一个长时间运行的任务 BBO$,此任务一直存在,直到链接服务器停止。要在 CICS 启动期间运行 BBOC 命令,copyZOS.sh 脚本所创建的装入库中提供了两种 CICS 初始化后程序列表 (PLTPI) 程序。此装入库可用于在 CICS 启动期间运行 BBOC 命令。如果要在 CICS 启动期间启用与优化本地适配器任务相关的用户出口 (TRUE),请将 BBOACPLT 添加到 CICS PLT 中作为阶段 2 或阶段 3 条目。

提供了第二种 PLTPI 程序 BBOACPL2,如果将其添加到 PLT(同样添加在阶段 2 或阶段 3 中),那么可以在 CICS 启动期间使用 INITPARM 数据发出 BBOC 命令。您可以在 INITPARM 内传递一系列命令(CICS 限制最长为 60 个字符)。以下 INITPARM 字符串样本将调用 BBOACPL2,并传递一个请求以在注册名称“PAYROLL”(其守护程序组名为“DAE1”,节点名为“NODE1”,服务器名为“SERVER1”)下启动链接服务器。此链接服务器接收所有服务名称 (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.
要点: 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;
   };
 };

当大于或等于 268 个字节的通信区域作为输入传递到 BBOACNTL 时,它会收到从 BBOC/BBOACNTL 执行的操作产生的消息响应,此消息响应以前 256 个字节表示,后跟先前显示的带版本、返回码和原因码的区域。以下是来自针对 BBOACNTL 的 EXEC CICS LINK 的支持返回码和原因码:

RC 0 RSN 0
	成功处理请求。前 256 个字节表示的响应消息提供了更多信息。使用返回的消息标识搜索信息中心以获取有关响应的更多信息。
RC 4 RSN 0
   没有链接服务器与请求的注册名称匹配,或没有链接服务器在此区域中运行。前 256 个字节表示的响应消息提供了更多信息。使用返回的消息标识搜索信息中心以获取有关响应的更多信息。
RC 8 RSN 0 或更高版本
   处理请求时发生错误。前 256 个字节表示的响应消息提供了更多信息。使用返回的消息标识搜索信息中心以获取有关响应的更多信息。
RC 12 RSN 0 或更高版本
   处理请求时发生严重错误。前 256 个字节表示的响应消息提供了更多信息。使用返回的消息标识搜索信息中心以获取有关响应的更多信息。

在对 BBOACNTL 的 EXEC CICS LINK 调用的命令字符串中传递 LTSQ 参数会将匹配的活动链接服务器列表写入 LTSQ 参数中传递的 CICS 临时存储器队列。列表中每个链接服务器的输出记录格式在位于 /<install_root>/AppServer/util/zos/OLASamples/bboaapic.h 中的头中进行记录,在 tsq_record 结构下进行描述。

WebSphere Application Server 的 CICS 链接服务器任务 BB0$

CICS 事务 BBO$ 用于提供对 CICS 的 WebSphere Application Server 出站调用支持。它在后台作为非终端事务运行,代表用户指定的注册名称和服务名称的服务器任务实例(使用操作 BBOC START_SRVR 开始该任务)。此服务器任务提供程序 LINK 调用功能,或者提供通过优化的本地适配器 API 启动 WebSphere Application Server 中的现有 CICS 程序的功能。此事务的名称可以被 BBOC START_SRVR 命令 (STX=xxxx) 中提供的用户提供名称覆盖。如果被覆盖,那么必须使用与 BBO$ 相同的程序名和属性将提供的事务名称定义到 CICS。

WebSphere Application Server 的 CICS 程序 LINK 调用任务 BBO#

CICS 事务 BBO# 用于提供对 CICS 的 WebSphere Application Server 出站调用支持。它是一个非终端事务,表示 WebSphere Application Server 适配器服务器任务 BBO$ 为了执行程序 LINK 调用而启动的任务的实例。对部署在 WebSphere Application Server 上的应用程序所发出的每个 CICS 程序链接请求,BBO$ 事务都会启动一个 BBO# 事务。

此事务的名称可能被 BBOC START_SRVR 命令上用户提供的名称(例如,LTX=xxxx)覆盖。 如果被覆盖,那么必须使用与 BBO# 事务相同的程序名和属性将提供的事务名称定义到 CICS。或者,通过使用 JCA 的应用程序,可以从 WebSphere Application Server 传递 4 个字符的链接事务名称。在此案例中,使用适配器的应用程序使用 setLinkTaskTransid 方法。

声明从 WebSphere Application Server 传播到 CICS 的用户身份

此服务器任务支持将用户身份从 WebSphere Application Server 调用传播到 CICS 中,并且支持声明该身份。只有在安全参数设置为 SEC=Y 的情况下执行注册任务时,才会作出此断言。 这是使用 EXEC CICS START TRANSACTION(‘BBO#') USERID(<user_id>) 实现的。

必须定义 SAF SURROGAT 类定义,以确保运行 BBO$ 事务的用户标识有权代表所传递的用户标识启动事务。

如果您在 SEC=N 时运行 BBOC STRT_SRVR,那么与 CICS 的入站请求关联的用户标识是执行 BBOC 事务的用户标识。

BBOC 调用样本

下面是一些 BBOC 调用样本,这些样本说明使用 CICS 适配器程序链接支持可以如何完成各种任务和配置。
  • 启动适配器 CICS TRUE 程序。

    bboc start_true

  • 停止适配器 CICS TRUE 程序。

    bboc stop_true

  • 在守护程序组 SY1 中注册名称 CICS-HR1,节点 SY1 和服务器 BBOS001(包含最大 10 个连接和最小 5 个连接)。设置事务为 no,安全传播为 yes

    bboc register rgn=CICS-HR1 svn=bbos001 dgn=sy1 ndn=sy1 mnc=5 mxc=10 txn=n sec=y

  • 注销名称 CICS-HR1。

    bboc unregister rgn=CICS-HR1

  • 对注册名称 CICSPAYR 下的所有服务和程序名称启动服务器事务 BBO$,该注册名称的守护程序组、节点、服务器的最大连接数为 10,最小连接数为5。设置事务为 no,安全传播为 yes

    bboc start_srvr rgn=CICSPAYR svn=bbos001 dgn=sy1 ndn=sy1 mnc=5 mxc=10 sec=y

  • 停止运行在注册名称为 CICSPAYR 下的 BBO$ 服务器事务。

    bboc stop_srvr rgn=CICSPAYR

  • 开始注册名称 CICSPAY1 下以 PAYR 开头的服务器和程序名称的服务器事务为 BBO$,该注册名称的守护程序组、节点、服务器的最大连接数为 10,最小连接数为5.事务为 no,安全传播为 yes

    bboc start_srvr rgn=CICSPAY1 svn=bbos001 dgn=sy1 ndn=sy1 mnc=5 mxc=10 sec=y svc=PAYR*

  • 开始事务标识 PAY2 下的服务器事务,并注册守护程序组、节点和服务器上所有服务和程序名称为 PAYROLL2,最大连接数为10,最小连接数为 5。事务参数值为 yes,安全传播值为 yes,跟踪设置为级别 1.

    bboc start_srvr rgn=PAYROLL2 svn=bbos001 dgn=sy1 ndn=sy1 mnc=5 mxc=10 sec=y stx=PAY2 trc=1

  • 开始事务标识 PAY3,链接事务标识为 PY3L 下的服务器事务。使用名称 PAYROLL3 注册以 PAYRL3 开头的守护程序组、节点和服务器中的服务和程序名称,最大连接数为 10,最小连接数为 5。 事务参数值为 yes,安全传播参数值为 yes,跟踪设置为级别 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

  • 列示在此 CICS 区域中运行的所有链接服务器

    bboc list_srvr

  • 列示在此 CICS 区域中运行的注册名称为 CICSPAY1 的所有链接服务器

    bboc list_srvr rgn=CICSPAY1

  • 列示在此 CICS 区域中运行的以注册名称 CICS 开头的所有链接服务器,并将列表复制到名为 MYSRVRS 的临时存储器队列

    bboc list_srvr rgn=CICS* ltsq=MYSRVRS

  • 列示在此 CICS 区域中运行的以注册名称开头的所有链接服务器,此注册名称以“CICS”开头后跟任意一个字符,接着是“ZZZ”和任何其他字符

    bboc list_srvr rgn=CICS?ZZZ*

支持 CICS 通道和容器对象

对于大于 32 K 的消息,需要从 WebSphere Application Server 启动的 CICS 应用程序,以使用 CICS 通道和容器接收数据和发送响应数据。部署在 WebSphere Application Server 中的应用程序可以使用提供的 JCA 编程接口来提供将数据传递至目标程序的 CICS 容器的名称和类型 (BIT|CHAR) 以及接收来自应用程序的响应的容器的名称和类型。

具有两种方式来将通道和容器传递到 CICS。在这两种情况下,都必须将 ConnectionSpecImpl 上的 setUseCICSContainer() 方法设置为“1”。
  • 传递单个容器并接收单个容器时,可以使用 setLinkTaskReqContid、setLinkTaskRspContid、setLinkTaskReqContType(bit|char) 和 setLinkTaskRspContType(bit|char) 方法。对于请求和响应,都使用通道名称 IBM-WAS-ADAPTER。此通道名称是固定的。
  • 或者,可使用 JCA MappedRecord 接口从目标 CICS 程序发送和接收一个或多个容器。使用 MappedRecord 时,请使用 ConnectionSpecImpl 的 setLinkTaskChanID() 和 setLinkTaskChanType() 方法来设置将用于存放请求和响应容器的通道名称,以及该通道中将包含的容器的类型(bit 或 char)。

    通过使用 put() 方法向 MappedRecord 添加数据,可以设置各个请求容器的名称。

    MappedRecord 的密钥对应 CICS 容器名称,对应值用于在 CICS 中填充容器。该关键字必须是长度介于 1 到 16 个字符之间的 String 对象。此值可为由诸如 Rational® Application Developer 的工具生成的 byte[] 或 RecordBytes 对象。

    响应容器名称在 CICS 请求完成后会从通道截取,且会填充到返回至客户机的新 MappedRecord。


指示主题类型的图标 参考主题



时间戳记图标 最近一次更新时间: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=rdat_cics
文件名:rdat_cics.html