![[z/OS]](../images/ngzos.gif)
优化本地适配器样本
该产品提供了可支持用于 z/OS® 的优化本地适配器的样本文件。
- .jclsamp 文件
- olarar.py 和 olararupdate.py 文件
- 头文件 bboaapi.h 和 bboaapip.include
- EAR 样本文件
ola_apis.jar 文件位于产品目录 /lib 中。
样本描述
在本机文件集的 @@README 成员中的目录内提供了样本名称目录及其用途。这些样本位于 <install_root>/util/zos/OLASamples 中,且包含:
- BBOAAPI - 编译使用 OLA API 的 C/C++ 样本所需的 C 头文件 (bboaapi.h)
- BBOAAPIC - 编译将 OLA API 与 CICS® LINK BBOACNTL 和 COMMAREA 配合使用的 C/C++ 样本所需的 C 头文件 (bboaapic.h)
- BBOAAPIP - 编译使用 OLA API 的 PL/I 应用程序所需的 PL/I 包含文件 (bboaapip.include)
- BBOACPLT - CICS PLT 初始化例程的汇编程序样本源 (BBOACPLT.cicsasm),显示如何在 CICS 启动期间启用 OLA TRUE
- BBOACPL2 - CICS PLT 初始化例程的汇编程序样本源 (BBOACPL2.cicsasm),显示如何在 CICS 启动期间从 CICS 启动参数获取 OLA INITPARMS 和发出 BBOC STRT_SRVR
- BBOACPL3 - CICS PLT 初始化例程的汇编程序样本源 (BBOACPL3.cicsasm),显示如何在 CICS 启动期间将多个 BBOC 命令传递到 BBOACNTL
- BBOACPLS - CICS PLT 关闭例程的汇编程序样本源 (bboacpls.cicsasm),显示如何在 CICS 关闭期间检索运行的 WOLA 链接服务器的列表,以及如何将这些服务器停止
- CSDUPDAT - CICS DFHCSDUP 实用程序作业 (CSDUPDAT.jclsamp),它定义了 CICS 下 OLA 所需的所有资源定义
- DFHPLTOL - 用于将样本 PLT 和支持 OLA 的 TRUE 出口程序 BBOACPLT 以及 OLA BBOC 命令处理器 PLT BBOACPL2 组合在一起的 JCL/源 (dfhpltol.jclsamp)
- OLABATCH - 用于以批处理方式运行其中一个样本的 JCL。请确保它与 WebSphere z/OS 在同一个 LPAR 上运行 (OLABATCH.jclsamp)
- OLACB01 - CICS 链接到使用通信区域的样本 Cobol 程序时使用的 JCL/源。这是使用 OLA CICS 链接服务器时所使用的样本目标程序。它将回传发送的消息 (OLACB01.jclsamp)
- OLACB02 - CICS 链接到使用容器的样本 Cobol 程序时使用的 JCL /源。这是使用 OLA CICS 链接服务器时所使用的样本目标程序。它将回传发送的消息 (OLACB02.jclsamp)
- OLACB03 - CICS 样本 Cobol 程序的 JCL/源,说明了如何使用“主机服务”API 使 CICS 任务进入 OLA 服务器 (OLACB03.jclsamp)
- OLACB04 - CICS 样本 Cobol 程序的 JCL/源,说明了如何使用“接收请求”和“获取数据”API 使 CICS 任务进入 OLA 服务器 (OLACB04.jclsamp)
- OLACB05 - CICS 样本 Cobol 程序的 JCL/源,说明了如何使用 API 来注册、获取连接、使用“发送请求”来调用 EJB、使用“获取数据”来获取响应以及使用“连接释放”和“注销”来释放连接 (OLACB05.jclsamp)
- OLACB06 - CICS 样本 Cobol 程序的 JCL/源,说明了如何使用 API 来注册以及使用“调用”和“注销”来调用 EJB (OLACB06.jclsamp)
- OLACB10 - CICS 样本 Cobol 程序的 JCL/源,此程序使用多个容器将数据从 EJB 传递到 CICS。这是使用 OLA CICS 链接服务器时所使用的样本目标程序 (OLACB10.jclsamp)
- OLACB11 - CICS 样本 Cobol 程序的 JCL/源,此程序使用多个容器将数据从 EJB 传递到 CICS。这是使用 OLA CICS 链接服务器时所使用的样本目标程序。在目标程序中对数据进行修改 (OLACB11.jclsamp)
- OLACB12 - CICS 样本 Cobol 程序的 JCL/源,此程序使用多个容器将数据从 EJB 传递到 CICS。这是使用 OLA CICS 链接服务器时所使用的样本目标程序。在目标程序中删除数据 (OLACB12.jclsamp)
- OLACC01 - 执行注册/调用/注销的 C 程序的 JCL/源。 它可以在批处理/USS/CICS 下运行 (OLACC01.jclsamp)
- OLACC02 - 执行“主机服务”/“发送请求”/“发送响应”/“获取数据”API 调用的 C 程序的 JCL/源。此程序主要调用其本身、调入 EJB,然后 EJB 再回调到此程序。它可以在批处理/USS/CICS 下运行 (OLACC01.jclsamp)
- OLACC10 - CICS 样本 C 程序的 JCL/源,此程序使用多个容器将数据从 EJB 传递到 CICS。这是使用 OLA CICS 链接服务器时所使用的样本目标程序 (OLACC10.jclsamp)
- OLAMAP - CICS BMS 屏幕映射定义的 JCL/源。这是 3270 测试驱动屏幕,用于在 WebSphere 与 CICS 之间传递请求 (OLAMAP.jclsamp)
- OLAPL01 - 作为 IMS™ 快速路径消息事务运行的 PL/I 程序的 JCL/源。 请参阅样本成员 STAGE1 和 PSBOLA2,以获取有关如何在 IMS 环境中生成此项的信息 (OLAPL01.jclsamp)
- OLAPL02 - 作为 IMS 消息处理程序事务运行的 PL/I 程序的 JCL/源。 请参阅样本成员 STAGE1 和 PSBOLA2,以获取有关如何在 IMS 环境中生成此项的信息 (OLAPL02.jclsamp)
- OLAUTIL - Cobol CICS 测试应用程序实用程序的 JCL/源。可以从此面板测试“注册、调用、主机服务和发送响应 API,并更新运行时要使用的守护程序组/服务器/节点名以及服务名。此实用程序可用于以两个方向测试调用。来自此程序的代码可用作使用这些 API 的样本 (OLAUTIL.jclsamp)
- PSBOLA2 - IMS PSB 为 OLAPL01 和 OLAPL02 生成的样本 JCL/源 (PSBOLA2.jclsamp)
- OTMAINIT - 样本 JCL,说明如何在系统上启动 IMS OTMA 可调用接口 SVC。
- STAGE1 - OLAPL01 和 OLAPL02 的 IMS STAGE1 样本源 (STAGE1.jclsamp)
样本安装
- 分配分区数据集 (PDS) 或扩展的分区数据集 (PDSE) 来存放 JCL 源。在样本 JCL 中,此数据集名为 BOSS.OLA.SAMPLES.SRC。
此数据集按 RECFM=FB、DSORG=PO、LRECL=80、BLKSIZE=9040 和 TRKS=40 进行分配。将文件类型为“jclsamp”的文件从 <Prod_FS_root>/util/zos/OLASamples 目录复制(例如,使用 OGET)到此数据集。头文件 bboaapi.h 也与 BBOAAPI 一起放在此数据集中。
- 存在一个企业归档 (EAR) 文件,在您设置资源适配器 ola.rar 并且定义了 Java™ 命名和目录接口 (JNDI) 名称为 eis/ola 的连接工厂之后,可以立即安装此文件。此 EAR 文件位于 <Prod_FS_root>/util/zos/OLASamples 目录中。注意: 如果您正在使用 V8.0,请使用 OLASample2.ear 文件。
- 分配另一个 PDS 或 PDSE 以用于存放客户信息控制系统 (CICS) BMS 映射构建作业 OLAMAP 创建的 COBOL COPYBOOK。
此数据集按 RECFM=FB、DSORG=PO、LRECL=80、BLKSIZE=9040 和 TRKS=15 进行分配。在样本 JCL 中,此数据集名为 BOSS.OLA.SAMPLES.COPYBOOK。
- 分配或选择装入模块库以包含优化本地适配器样本装入模块。
必须将它作为“库”而不是作为 PDS 进行分配。
- 执行下列步骤来构建和运行 z/OS 批处理样本。
对于在执行这些步骤期间更新的所有成员,您必须更改 JCLLIB 语句以指向您的过程库(在此情况下,用于 C 编译)。在执行此过程时,需要熟悉信息在系统上的位置的人员。此外,此测试用例源嵌入了守护程序组(单元短名称)、节点短名称和服务器短名称,您在编译之前必须更改这些名称,以使它们在系统中有效。
- 编辑 OLACCnn 成员(其中 nn 为测试用例编号),更新 JCL 以符合 C 编译器的站点数据集命名约定,并设置输出装入模块所在的 SYSLMOD 数据集。
- 在 OLACCnn 成员中,更新守护程序组名(单元短名称)、节点名和服务器名称并提交作业来构建测试用例装入模块。
- 确保在启动目标应用程序服务器时启用了优化本地适配器支持。通过将 WAS_DAEMON_ONLY_enable_adapter 设置为 true 来启用优化本地适配器支持。 同时,确保已安装 ola.rar 文件并使用 JNDI 名称 eis/ola 创建了连接工厂。
- 请确保目标应用程序服务器中已安装 OLA 样本 EAR 文件。 注意: 如果您正在使用 V8.0,请使用 OLASample2.ear 文件。
- 将 OLABATCH 用作运行 OLACCnn 批处理样本的模板。
某些样本作业涉及到名为 BOSS.OLA90902.SBBOLOAD 的数据集。这表示您使用 copyZOS.sh 脚本将联机适配器模块复制到的数据集。
- z/OS 批处理样本也可以在 CICS 下运行。按照“在 CICS 中启用优化本地适配器支持”主题中的步骤执行操作,并将步骤 4 中的样本装入模块库添加到 CICS DFHRPL DD 并置中。
- 执行下列步骤来构建和运行优化本地适配器 CICS 样本测试实用程序面板。对于在此过程中更新的所有成员,您需要更改 JCLLIB 语句以指向您的过程库(在此情况下,用于 COBOL 编译器和 CICS 转换)。执行此过程时,需要有熟悉此信息在系统上的位置的人员。
- 编辑 OLAMAP 成员并更新 JCL,使其符合 HLASM 应用程序的站点数据集命名约定。您需要将 MAPLIB 和 DSCTLIB 参数更改为您自己的数据集名称。MAPLIB 应指向您在步骤 4 中分配的样本装入模块库。DSCTLIB 应指向您在步骤 3 中分配的 COPYBOOK 数据集。注: 您可以在此面板上将缺省注册名称从 CICSTEST 更改为其他值。您还可以设置缺省的守护程序组名(单元短名称)、节点名和服务器名称。在 CICS 下运行 OLAU 事务时,您在此处输入的值将显示在面板上。
- 提交 OLAMAP 作业以构建 CICS 映射集模板。
- 编辑成员 OLAUTIL 并复审内容。
这是演示来自 Cobol 的许多优化本地适配器 API 的样本 Cobol 应用程序。它发送并接收 CICS BMS 映射 OLAMAP,并且可将消息发送给任何本地连接的应用程序服务器中的任何目标企业 Bean。它还可用于演示如何使用 BBOA1SRV API 将 CICS 任务放入优化本地适配器目标服务。更新 JCL 以符合您的本地数据集名称约定之后,提交作业,OLAUTIL 装入模块保存在 PROGLIB 符号指向的数据集中。
- 请确保优化本地适配器装入模块库和优化本地适配器样本装入模块库位于 CICS 编目过程的 CICS DFHRPL DD 并置中。
- 请确保样本作业 CSDUPDAT 已运行并且在 CICS 下安装优化本地适配器的步骤已完成。
- 确保已启动目标应用程序服务器并且启用了优化本地适配器支持。通过将 WAS_DAEMON_ONLY_enable_adapter 设置为 true 来启用优化本地适配器。 同时,确保已安装 ola.rar 文件并且使用 JNDI 名称 eis/ola 创建了连接工厂。您可以在主题“启用服务器环境以使用优化本地适配器”中读取有关这些过程的更多信息。
- 请确保目标应用程序服务器中已安装 OLA 样本 EAR 文件。 注意: 如果您正在使用 V8.0,请使用 OLASample2.ear 文件。
- 启动 CICS。
请确保已启用优化本地适配器支持,使用有权运行 BBOC 和 OLAU 事务的用户标识登录到 CICS 并清除屏幕。输入 BBOC START_TRUE 以启动与优化本地适配器 CICS 任务相关的用户出口 (TRUE)。将显示一条有关出口已成功启动的消息。如果您未获取此消息,那么应获取指出所发生错误的种类的消息。有关更多详细消息,请参阅 CICS 作业输出并查看文件 BBOOUT。如果在 CICS 启动期间使用优化本地适配器“初始化后程序列表”(PLTPI) 程序来启动优化本地适配器 TRUE,请参阅描述此过程的下一节。
- 再次清除屏幕并输入 OLAU 以启动测试面板。
如果所有程序都正常工作,那么面板将显示标题“* 优化本地适配器 WAS z/OS 测试 *”。面板上将列示运行参数,“首先注册”的值为 Y、“注册名称”的值为 CICSTEST,“服务名称”的值为 ejb/com/ibm/ola/olasample1_echoHome。“要运行的测试数”字段的值为 00001。
- 在“发送消息数据”字段中,输入要发送到 WebSphere Application Server 中的服务的消息。
- 输入要将企业 Bean 调入的服务器的 WebSphere Application Server 服务器短名称、WebSphere Application Server 节点短名称和 WebSphere Application Server 单元短名称(守护程序组名)。
- 其他的字段可保持原样。显示的服务名称是 OLA 样本 EAR 文件中的样本目标企业 Bean 的 JNDI 主名称。 注意: 如果您正在使用 V8.0,请使用 OLASample2.ear 文件。
- 单击 PF4 将消息发送给 EJB olasample1_echoHome。 此消息在“接收的消息数据”字段中返回。
- 您现在演示了从 CICS Cobol 程序调用 WebSphere Application Server EJB 应用程序。
面板显示现在已更改。“首先注册?”字段已从 Y 更改为 N。使用此注册名称重新运行请求不要求先注册调用,所以此值更改为 N。如果您在注册时收到返回码 8 (RC8) 和原因码 8 (RSN8),那么这表示您已经注册,无需再次注册。离开 OLAU,然后又返回来时,此注册仍然处于活动状态,所以您不需要使用该名称再次注册,并且应将值设置为 N。
- 要测试从 WebSphere Application Server 调用 CICS,您也可以使用此面板。
必须将“服务名称”字段更新为您要标识为目标服务名称的任何名称,然后单击 PF5。由于 OLAUTIL 使用您请求的服务名称和注册名称调用 BBOA1SRV API,所以此操作会使屏幕进入 x-wait 状态。此面板显示名为 CICSTEST 的注册和名为 myserv 的服务名称。在面板上显示值的其他参数包括 WAS 服务器短名称、WAS 节点短名称、WAS 单元短名称(守护程序组名)、要运行的测试数以及已完成的测试数。
- 当 OLAU 等待您所请求的服务名称时,请在浏览器中启动样本 Web 应用程序。
使用以下 URL(为您的站点更新 IP/端口号):http://nn.nn.nn.nn:nnnn/OLA_Sample1_Web/ - 将 nnnn 端口号更改为非 SSL WebSphere Application Server 应用程序端口。
- 将显示一个列出了下列字段的 Web 页面:要发送至外部地址空间的数据、从外部地址空间发回的响应、OLA 注册名称、OLA 服务名称、特定于 CICS 链接服务器的数据、CICS 链接请求容器标识、CICS 链接响应容器标识和 CICS 链接事务标识。输入要发送的消息、在 OLAU 面板上使用的注册名和服务名并单击运行 WAS -> 外部地址空间测试。
- 现在您将看到在浏览器中输入的消息显示在 CICS 3270 面板上的“接收到的消息数据”字段中。
- 在“发送消息数据”字段中输入响应消息并单击 PF6 将响应发送回 WebSphere Application Server。这应该出现在浏览器中。
- 您现在已经演示了从 WebSphere Application Server Servlet 调用 CICS Cobol 程序。
- 编辑 OLAMAP 成员并更新 JCL,使其符合 HLASM 应用程序的站点数据集命名约定。
- 通过下列步骤来演示使用优化本地适配器 CICS 链接服务器从 WebSphere Application Server 应用程序调用 CICS Cobol 程序。
- 编辑成员 OLACB01 并复审内容。
这是样本 Cobol 应用程序,此样本程序是具有 COMMAREA 的 EXEC CICS LINK 的目标。它将传递的 COMMAREA 消息数据写入缺省 Cobol 标准输出 (CEEMSG) 并回传消息。将 JCL 更新为指向您的本地数据集并进行提交。保存此模块的装入库必须位于 CICS DFHRPL 并置中。
- 编辑成员 OLACB02 并复审内容。
这是样本 Cobol 应用程序,此样本程序是具有 CONTAINER 的 EXEC CICS LINK 的目标。它读取 CONTAINER 内容并将其写回同一个容器中。将 JCL 更新为指向您的本地数据集并进行提交。保存此模块的装入库必须位于 CICS DFHRPL 并置中。
- 请确保样本作业 CSDUPDAT 已运行并且在 CICS 下安装优化本地适配器的步骤已完成。
- 启动 CICS。
使用有权运行 BBOC、BBO# 和 BBO$ 事务的用户标识登录到 CICS,然后清除此屏幕。
输入 BBOC START_TRUE 以启动优化本地适配器 CICS TRUE。
将显示一条有关出口已成功启动的消息。如果未获取此消息,那么应获取表明出现哪类错误的消息。有关更多详细消息,请参阅 CICS 作业输出并查看文件 BBOOUT。如果您想要使用优化本地适配器 PLTPI 程序在CICS 启动期间启动优化本地适配器 TRUE,请参阅本主题中描述此过程的章节。
- 再次清除屏幕并输入以下内容来启动已优化本地适配器 CICS 链接服务器任务:bboc start_srvr rgn=olaserver svn=<serverName>
dgn=<cellName> ndn=<nodeName>
mnc=1 mxc=5 sec=n svc=*
这会导致 BBO$ 任务使用注册名称 OLASERVER 启动,并连接到指定的应用程序服务器。确保对服务器指定了服务器短名称、单元短名称和节点短名称。
- 您现在已准备好发送请求以链接至现有 CICS 程序。启动测试 Web 页面 (http://nn.nn.nn.nn:nnnn/OLA_Sample1_Web/)。输入 OLASERVER 作为注册名称,OLACB01 作为服务名称。
- 单击运行 WAS > 外部地址空间测试。您应该会看到一个返回的页面,其中具有发送给 CICS 的相同消息。如果在运行的 CICS 作业中查看 CICS CEEMSG DD,将显示使用 UTF-8 的消息数据。
- 您现在已经演示了从 WebSphere Application Server 中的 Servlet 调用 CICS Cobol 程序 OLACB01,其中数据的传递和返回都在 COMMAREA 中进行。
- 再次显示浏览器面板并将服务名称更改为 OLACB02,然后单击“使用容器”复选框。要点: 您必须选中“使用容器”复选框。
- 单击运行 WAS > 外部地址空间测试。您应会看到一个返回的页面,其中具有回传的输入消息。
- 您现在已经演示了从 WebSphere Application Server 中的 Servlet 调用 CICS Cobol 程序 OLACB02,其中使用 CONTAINER 传递数据。
- 如果要更接近地跟踪发生的情况,您可以停止链接服务器并使用跟踪集重新启动该服务器。通过设置 TRC=2,就可在 CICS 作业 BBOOUT 文件中查看跟踪消息。要停止链接服务器,请输入以下内容:bboc stop_srvr rgn=olaserver。要使用跟踪重新启动链接服务器,请输入以下内容:bboc start_srvr rgn=olaServer svn=<serverName> dgn=<cellName> ndn=<nodeName> mnc=1 mxc=5 sec=n svc=* trc=2
- 编辑成员 OLACB01 并复审内容。
- 如果要将 CICS 设置为在 CICS 启动期间自动启动优化本地适配器 TRUE,请执行下列步骤。
- 您可以在 CICS 顺序终端 (TYPE=SDSCI) 中编写代码 BBOC START_TRUE\ 来启动优化本地适配器 TRUE,或
- 可以创建 CICS 区域的“初始化后程序列表”(PLTPI) 并在 CICS 区域启动期间对其进行调用。
样本作业 DFHPLTOL 将创建具有后缀 OL 的 PLTPI。运行此样本,将生成的模块 DFHPLTOL 放入 DFHRPL 并置中的装入模块库,并将 OL 添加到为 CICS 区域指定的 SIT PLTPI,例如,PLTPI=OL。
请参阅样本文件 DFHPLTOL 以获取相关示例。运行 PLTPI 时,如果优化本地适配器 TRUE 正常启动,那么您应在 CICS 作业日志中看到以下消息:+BBOA9920I WAS z/OS OLA CICS PLT init start. +BBOA9921I WAS z/OS OLA CICS TRUE enabled. +BBOA9925I WAS z/OS OLA CICS PLT init ending.