Liberty for z/OS 上的优化本地适配器 API

Liberty 上 WebSphere® 优化本地适配器 (WOLA) 受到一组 z/OS® 本机语言可调用服务应用程序编程接口 (API) 和 Java™ EE 连接器体系结构 (JCA) 的支持。

可以从下列本机编程语言来使用这些可调用服务:
  • Cobol
  • C/C++
  • PL/I
  • 高级汇编语言

本地连接术语是指为 z/OS 系统上的外部地址空间与同一 z/OS 系统上的 Liberty 服务器之间的通信而创建的跨内存链接。客户机地址空间必须在同一 z/OS 映像上运行。适配器 API 管理那些位于池中的与每个唯一注册的调用者相关联的本地连接。12 个字符的注册名称只能用于每个地址空间的一组连接池。单个地址空间中的唯一注册数仅受可用存储空间量的限制。

注册

使用 BBOA1REG API,您可向本地 Liberty 服务器注册。BBOA1REG API 请求使用所指定的注册名称来分配和注册与本地 Liberty 服务器的一组优化连接。

表 1. BBOA1REG API 语法
API 语法
BBOA1REG BBOA1REG (wolagroupnamepart1, wolagroupnamepart2, wolagroupnamepart3, registername, minconn, maxconn, registerflags, rc, rsn)
BBOA1REGAPI 接受以下输入参数:
wolagroupnamepart1
包含要连接的优化本地适配器组的名称的第一部分的入口变量或入口常量。它必须是正好由 8 个字符组成且以 null 结束的字符串,它必须由引用进行传递。
wolagroupnamepart2
包含要连接的优化本地适配器组的名称的第二部分的入口变量或入口常量。它必须是正好由 8 个字符组成且用空格填充的字符串,它必须由引用进行传递。
wolagroupnamepart3
包含要连接的优化本地适配器组的名称的第三部分的入口变量或入口常量。它必须是正好由 8 个字符组成且用空格填充的字符串,它必须由引用进行传递。
registername(输入)
一个入口变量或入口常量,它包含要用于注册一组本地连接的名称。以后的调用需要此名称以标识要使用的连接池。该参数必须是正好由 12 个字符组成的用空格填充的字符串,并且不能由守护程序组中的另一个客户机使用。如果此客户机连接到多个守护程序组,那么 registername 在此客户机中只能使用一次。
minconn
一个包含要为此注册分配的初始最小连接数的整数。适配器尝试保留注册期间与相关服务器的此连接数。
要点: 即使 minconn 参数指定为 0,至少也分配了一个要与目标服务器绑定的连接,因此,指定 0 与指定 1 的结果相同。
maxconn
一个包含要为此注册分配的最大连接数的整数。如果最小数量的连接全在使用中,那么在“连接获取”API 请求期间,适配器会尝试将本地连接池扩展到此数目。
registerflags
包含注册标志的 32 位标志词语。
  • reg_flag_W2Cprop - 31 位

    reg_flag_W2Cprop 标志控制将出站事务安全性从 Liberty 服务器传播到 CICS®。

  • reg_flag_C2Wprop - 29 位

    reg_flat_C2Wprop 标志将调用任务使用的身份从 CICS 传播到 Liberty 服务器。对于来自 CICS 的入站事务,该标志控制如何确定身份。当启用此位时,在 Liberty 服务器授权过程中使用 CICS 应用程序任务身份。当关闭此位时,将使用 CICS 区域身份。

  • reg_flag_trcmod - 0 位

    如果您想要为所请求的注册修改优化本地适配器跟踪设置,请设置 reg_flag_trcmod 标志。如果您不设置此标志,那么不会对跟踪设置进行更改,而是使用系统缺省值或者使用预定义的适用于注册名称或作业名的跟踪设置。

  • reg_flag_trcmore - 1 位以及 reg_flag_trcsome - 2 位

    如果您将 reg_flag_trcmod 标志设置为 1,那么还必须通过对详细跟踪设置 reg_flag_trcmore 标志或者对粗糙跟踪设置 reg_flag_trcsome 标志,来指定注册的跟踪级别。如果 reg_flag_trcmod 设置为 1,那么将 reg_flag_trcmore 标志和 reg_flag_trcsome 标志同时设置为 0 会强制不对注册进行跟踪,无论预定义或缺省值是如何设置的都是如此。

BBOA1REG API 接受以下输出参数:
rc
表明此调用是成功还是失败的整数返回码。
rsn
用于描述此调用失败的原因的整数原因码。
使用说明:
  • 请确保您在此调用中指定的 Liberty 服务器已启动,并且已启用对本地适配器的支持。
  • 针对服务器最大连接数来验证所请求的最小连接数。最小连接数 (minconn) 值 3 意味着在注册调用期间将保留 3 个连接。如果在给定的时间请求了三个以上的连接,那么连接池可增加到最大连接数 (maxconn) 值。如果服务器的所有连接数达到了允许的最大值,那么即使尚未达到 maxconn 值,也将拒绝此服务器所有后续的“连接获取 API”请求。
    要点: 设置最小连接数值时须谨慎。 除了特定实例之外,请勿设置非常大的值,因为将对每个连接保留 Liberty 服务器中的资源。
  • 可在同一地址空间、线程或客户信息控制系统 (CICS) 任务中向注册 API 发出多个调用;但是它们无法共享注册名称。注册名称必须是唯一名称。
  • 使用“注销 API”调用来移除此注册,并释放与它相关联的连接池。
  • 发出注册调用的地址空间终止时,注册也会自动终止并且释放连接。
返回码和原因码:
表 2. BBOA1REG API 返回码和原因码
返回码 原因码 描述 操作
0 - 成功  
4 4 在适配器不支持全局事务的环境中,设置事务注册标志为 1。 将忽略此设置并继续进行处理。
8 - 错误 - 请查看原因码  
  8 注册名称令牌已存在。 调用“注册”API 之前注销此名称。
  12 指定的最小连接数参数大于最大连接数参数。 确保最小连接数设置小于或等于最大设置。
  14 尝试创建注册时,共享内存不足。 增加为优化本地适配器分配的共享内存或发出注销调用以减少资源的使用。
  74 输入注册名称包含空值。 在调用“注册”API 之前,请使用空格来填充注册名称,以使注册名称的长度刚好为 12 个字符。
 

236

WOLA 名称部分 2 或 3 为空或丢失。 确保针对 BBOA1REG 调用指定了 WOLA 名称部分 2 和 3。
 

480

客户机无法进行授权以调用注册功能。 这是意外情况。确保目标服务器正在运行,且在服务器实例中配置了 zosLocalAdapters 服务。
 

481

客户机找不到 zosLocalAdapters 服务的授权功能表。 确保在目标服务器实例上配置了 zosLocalAdapters 功能。
12 10 该 API 找不到所选择的优化本地适配器组。 请确保已启动 Liberty 服务器和目标服务器,确认优化本地适配器支持处于活动状态,然后重试。
  14 未授权用户标识访问所请求的 Liberty 服务器。 请确保已授权用户标识使用所请求的 Liberty 服务器的 CBIND SAF 类。
  16 找不到优化本地适配器组名的第 2 部分或第 3 部分。 请确保所传递的优化本地适配器组名参数有效且服务器处于活动状态。
  23 对标记进行命名时发生错误。 请参阅 WebSphere Application Server Support 站点上的问题确定信息。
  24 建立初始 Liberty 服务器本地通信连接时发生错误。 请参阅 Liberty 服务器区域日志以获取有关本地通信连接调用的详细信息。
  28 使用此名称标识的注册无效。 所指定的注册名称已注册,但是缺少注册。作为一种变通方法,请调用“注销”API,然后再次尝试调用“注册”API。如果问题仍然存在,请参阅 WebSphere Application Server Support 站点上的问题确定信息。
  68 与共享内存的连接失败。 请参阅 WebSphere Application Server Support 站点上的问题确定信息。
  86 找不到 Liberty 服务器主 BGVT。 在当前 z/OS 操作系统映像上未启动 Liberty 服务器。在启动任何优化本地适配器客户机进程之前,请确保服务器已启动。
  88 找不到 Liberty 服务器主客户机存根表。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
  90 找不到 Liberty 服务器优化本地适配器的主客户机存根表插槽。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
 

232

执行注册调用期间发生内存不足情况。 确保内存可供子池 0 中的客户机使用。再次尝试执行 BBOA1REG 调用。
 

234

客户机无法绑定到 Liberty 服务器实例。 确保已启动 Liberty 服务器实例,且在服务器实例中配置了 zosLocalAdapters 服务。
 

238

客户机找不到目标服务器的注册。 这是意外情况。确保已启动目标服务器实例,且配置了 zosLocalAdapters 功能。如果服务器已停止,请将其启动并再次尝试执行 BBOA1REG 调用。

注销

使用 BBOA1URG API 从本地优化本地适配器组和 Liberty 服务器注销。
表 3. BBOA1URG API 语法. 此 API 请求使用所指定的注册名称来释放与本地优化本地适配器组和 Liberty 服务器建立的一组优化连接。
API 语法
BBOA1URG BBOA1URG (registername, unregflags, rc, rsn)
BBOA1URG API 接受以下输入参数:
registername
一个入口变量或入口常量,它包含要用来注销一组本地连接的名称。值必须刚好 12 个字符,不足 12 个字符则用空格填充,并且是在“注册”API 调用中使用的同一名称。
unregisterflags
包含注销标志的 32 位标志词语。
  • 保留 - 0 - 30 位
  • 强制 (0|1) - 31 位

    指定 1 以强制发出注销请求。缺省情况下,如果所有连接都返回到连接池,那么已完成注销请求。如果所有的连接未返回到该池,那么将有一条警告消息返回给调用者。当最后一个连接返回到池时,便完成了注销过程。发出另一个注册请求并将强制位设置为 1,以强制完成注销过程,并使该注册的所有其余连接句柄都失效。

BBOA1URG API 接受下列输出参数:
rc
表明此调用是成功还是失败的整数返回码。
rsn
用于描述此调用失败的原因的整数原因码。
使用说明:
  • 请确保您在此调用中指定的 Liberty 服务器已启动,并且已启用对本地适配器的支持。
  • 如果未调用“注销”API,但是执行注册调用的地址空间终止,那么自动执行注销调用,并释放连接。
  • 进行注销调用时,只有当此次注册中处于活动状态的所有连接句柄都返回到使用“连接释放”API 的连接池时,这些句柄才无效。要强制清除连接句柄,必须发出另一个注销调用并指定强制标志。这将使所有仍有效的连接句柄失效。
返回码和原因码:
表 4. BBOA1URG API 返回码和原因码
返回码 原因码 描述 操作
0 - 成功  
4 - 警告 - 请参阅原因码  
  66 将延迟注销调用,直到所有的连接都返回到池为止。 当最后一个连接返回到空闲池时,注销完成。
8 - 错误 - 请查看原因码  
  8 注册标记名称不存在。 您必须注册此名称,然后才能对其调用“注销”API。
  64 在发出正常注销之前,无法指定强制选项。 在不指定强制选项的情况下调用注销 API。
  82 已尝试注销此注册。 等待完成前一个注销请求,或者附带 force 选项重新发出此注销请求。
 

228

由于已复用注册,因此取消注册调用无法完成。 不需要任何操作。
 

230

无法在执行取消注册强制调用时清除连接池。 不需要任何操作。要避免使用取消注册强制调用,请确保应用程序将所有连接句柄返回到池,再执行取消注册调用。
 

480

客户机无法进行授权以调用取消注册功能。 这是意外情况。确保目标服务器正在运行,且在服务器实例中配置了 zosLocalAdapters 服务。
12 86 找不到 Liberty 服务器主 BGVT。 在当前 z/OS 操作系统映像上未启动 Liberty 服务器。在启动任何优化本地适配器客户机进程之前,请确保服务器已启动。
  88 找不到 Liberty 服务器主客户机存根表。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
  90 找不到 Liberty 服务器优化本地适配器的主客户机存根表插槽。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。

连接获取

此 API 请求返回来自使用所选择的注册名称创建的池的可用连接。
表 5. BBOA1CNG API 语法
API 语法
BBOA1CNG BBOA1CNG (registername, connectionhandle, waittime, rc, rsn)
BBOA1CNG API 接受以下输入参数:
registername
一个入口变量或入口常量,它包含要用于查找从中检索连接的连接池的名称。该参数必须是正好由 12 个字符组成的用空格填充的字符串。
connectionhandle
在以后请求此连接上的操作时必须传递的 12 个字节的连接句柄。
waittime
包含在返回连接不可用的原因码之前等待连接完成的秒数的整数。值 0 意味着没有等待时间,API 将无限期等待。waittime 参数仅适用于从连接池获取 WOLA 连接的过程。获取该连接后,它将用于接收来自服务器的请求,且等待时间不受限制。
BBOA1CNG API 接受以下输出参数:
rc
表明此调用是成功还是失败的整数返回码。
rsn
用于描述此调用失败的原因的整数原因码。
使用说明:
  • 请确保您在此调用中指定的 Liberty 服务器已启动,并且已启用对本地适配器的支持。
  • 在您使用“连接获取”API 之前,请确保使用相匹配的名称在当前地址空间中成功完成了“注册”API 调用。
返回码和原因码:
表 6. BBOA1CNG API 返回码和原因码
返回码 原因码 描述 操作
0 - 成功  
4 - 警告 - 请参阅原因码  
8 - 错误 - 请查看原因码  
  8 注册名称标记不存在。 在使用“连接获取”API 调用此名称之前注册此名称。
  10 连接不可用。等待时间超时,无法获取连接请求。 应用程序行为改变。请等待,然后重试,或者发出异常终止宏以终止调用了“连接获取”API 的任务。您还可以增大“注册”API 调用上的最大连接数设置。
  24 注册调用成功后,从池中获取连接时发生错误。 验证服务器是否已启动。如果服务器未运行,请重新启动服务器,然后再次尝试该 API 请求。
  28 找到了注册,但是它处于不活动状态。  
 

224

找到不完整的注册。 这是意外情况。使用 BBOA1URG 服务取消注册,使用 BBOA1REG 服务再次注册。
 

480

客户机无法进行授权以调用获取连接功能。 这是意外情况。确保目标服务器正在运行,且在服务器实例中配置了 zosLocalAdapters 服务。
 

482

重新启动目标服务器后,客户机无法重新连接到目标服务器实例。 这是意外情况。使用 BBOA1URG 服务移除注册,使用 BBOA1REG 服务创建一个新的注册。
 

483

重新启动目标服务器后,客户机无法重新连接到目标服务器实例。 这是意外情况。使用 BBOA1URG 服务移除注册,使用 BBOA1REG 服务创建一个新的注册。
12 10 该 API 找不到所选择的优化本地适配器组。 请确保已启动 Liberty 服务器和目标服务器,确认优化本地适配器支持处于活动状态,然后重试。
 

14

未授权用户标识访问所请求的 Liberty 服务器。 请确保已授权用户标识使用所请求的 Liberty 服务器的 CBIND SAF 类。
  86 找不到 Liberty 服务器主 BGVT。 在当前 z/OS 操作系统映像上未启动 Liberty 服务器。在启动任何优化本地适配器客户机进程之前,请确保服务器已启动。
  88 找不到 Liberty 服务器主客户机存根表。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
  90 找不到 Liberty 服务器优化本地适配器的主客户机存根表插槽。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。

连接释放

“连接释放”API 请求将连接返回到从其中检索到该连接的池,并使其可供另一个请求者使用。
表 7. BBOA1CNR API 语法
API 语法
BBOA1CNR BBOA1CNR ( connectionhandle, rc, rsn )
BBOA1CNR API 接受以下输入参数:
connectionhandle
12 个字节的连接句柄,指示先前已获得、但是要释放回连接池的连接。
BBOA1CNR API 接受以下输出参数:
rc
表明此调用是成功还是失败的整数返回码。
rsn
用于描述此调用失败的原因的整数原因码。
使用说明
  • 请确保您在此调用中指定的 Liberty 服务器已启动,并且已启用对本地适配器的支持。
  • 在使用“连接释放”API 之前,请确保使用相匹配的名称在当前地址空间中成功完成了“注册”API 调用,并且成功完成了“连接获取”API 调用以获取现在要释放的连接。
表 8. BBOA1CNR API 返回码和原因码
返回码 原因码 描述 操作
0 - 成功  
4 - 找不到优化本地适配器组和 Liberty 服务器。已清除与此连接相关的任何资源。
8 - 错误 - 请查看原因码  
  36 连接状态无效。 用于此请求的连接句柄处于错误状态。请参阅 API 文档以获取有关连接状态的规则。
  38 客户机连接句柄无效。 用于此请求的客户机连接句柄无效。请参阅 API 文档以获取有关客户机连接句柄的信息。
12 86 找不到 Liberty 服务器主 BGVT。 在当前 z/OS 操作系统映像上未启动 Liberty 服务器。在启动任何优化本地适配器客户机进程之前,请确保服务器已启动。
  88 找不到 Liberty 服务器主客户机存根表。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
  90 找不到 Liberty 服务器优化本地适配器的主客户机存根表插槽。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。

发送请求

这些 API 将请求发送到本地 Liberty 服务器进行处理。
表 9. BBOA1SRQ API 语法
API 语法
BBOA1SRQ BBOA1SRQ (connectionhandle, requesttype, requestservicename, requestservicenamel, requestdata, requestdatalen, async(0|1), responsedatalen, rc, rsn)
BBOA1SRQ API 接受以下输入参数:
connectionhandle
要用于此请求的 12 个字节的连接句柄。
requesttype
一个整数,其中包含请求类型,用于指示要处理的工作请求的类型。对于本地 EJB 工作请求,唯一受支持的值为 1
requestservicename
其中包含要调用的服务名称的最长可为 256 个字节的 EBCDIC 字符串。此参数指定本地业务接口的 JNDI 名称。
requestservicenamel
一个整数,其中包含要启动的服务名称的长度;如果服务名称以 null 结束,那么此整数为 0(零)。
requestdata
指向要发送的请求数据开始处的地址的 31 位指针。
requestdatalen
其中包含要发送数据的长度的 32 位无符号值。
async(0|1)
async 设置为 1,表明即使可能尚不知道响应的长度,调用者也想要立即返回控制。如果您将 async 设置为 0,那么当前线程将等待 Liberty 服务器返回响应,该 API 将在 responsedatalen 输出参数中返回响应长度。
BBOA1SRQ API 接受以下输出参数:
responsedatalen
其中包含响应的长度的 32 位无符号值。 在您调用“获取数据”API 以复制存储器中的数据之前,调用者可以使用此长度来获取存储器。当您将 async 设置为 1 时,表明调用者想要立即返回控制;如果尚未接收到响应,那么该参数的值设置为 0xFFFFFFFF
rc
表明此调用是成功还是失败的整数返回码。
rsn
用于描述此调用失败的原因的整数原因码。
使用说明:
  • 请确保您在此调用中指定的 Liberty 服务器已启动,并且已启用对本地适配器的支持。
  • 在您使用“发送请求”API 之前,请确保使用相匹配的名称在当前地址空间中成功完成了“注册”API 调用。
返回码和原因码:
表 10. BBOA1SRQ API 返回码和原因码
返回码 原因码 描述 操作
0 - 成功  
4 - 警告 - 请参阅原因码  
8 - 错误 - 请查看原因码  
  8 注册名称令牌已存在。 确保传递的注册名称有效。
  16 请求服务名称长度无效。 更正程序,然后重试。
  18 请求长度超出了系统限制。 消息大小大于 Liberty 服务器大小可以支持的大小。请验证该大小是否有效。如果大小有效,请确保 Liberty 服务器的大小足够容纳消息。
  32 API 呼叫请求类型无效。 请求类型无效。请更正程序,然后重试该调用。
  34 找不到目标服务。 请确保在 Liberty 服务器的目标服务器中已安装并启动其中包含目标企业 Bean 的应用程序。
  36 连接状态无效。 用于此请求的连接句柄处于错误状态。请参阅 API 文档以获取有关连接状态的规则。
  38 客户机连接句柄无效。 用于请求的客户机连接句柄无效。请参阅 API 文档以获取有关客户机连接句柄的信息。
  40 发生本地通信错误。 请检查 Liberty 服务器日志以获取所有的本地通信错误消息。
  44 在目标企业 Bean 中发生异常或意外情况。 请参阅 Liberty 服务器日志以查看异常数据。
  46 在本地通信发送请求调用中发生错误。 请查看 Liberty 服务器日志以确定错误。
  98 无法访问所提供的请求缓冲区的开头。 请确保所提供请求缓冲区的地址和长度正确。
  100 无法访问所提供的请求缓冲区的结尾。 请确保所提供请求缓冲区的地址和长度正确。
12 10 该 API 找不到所选择的优化本地适配器组。 请确保已启动 Liberty 服务器和目标服务器,确认优化本地适配器支持处于活动状态,然后重试。
  86 找不到 Liberty 服务器主 BGVT。 在当前 z/OS 操作系统映像上未启动 Liberty 服务器。在启动任何优化本地适配器客户机进程之前,请确保服务器已启动。
  88 找不到 Liberty 服务器主客户机存根表。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
  90 找不到 Liberty 服务器优化本地适配器的主客户机存根表插槽。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。

发送响应

此 API 将对请求的响应发送回本地 Liberty 服务器。
表 11. BBOA1SRP API 语法
API 语法
BBOA1SRP BBOA1SRP (connectionhandle, responsedata, responsedatalen, rc, rsn)
BBOA1SRP API 接受以下输入参数:
connectionhandle
将用于此响应的 12 个字节的连接句柄。
responsedata
指向要发送的响应数据开始处的地址的 31 位指针。
requestdatalen
其中包含要发送数据的长度的 32 位无符号值。
BBOA1SRP API 接受以下输出参数:
rc
表明此调用是成功还是失败的整数返回码。
rsn
用于描述此调用失败的原因的整数原因码。
使用说明:
  • 请确保您在此调用中指定的 Liberty 服务器已启动,并且已启用对本地适配器的支持。
  • 在您使用“发送响应”API 之前,请确保使用相匹配的名称在当前地址空间中成功完成了“注册”API 调用。
  • 请确保已成功完成“连接获取”API 调用,并且将句柄作为此调用的输入来提供。
  • 请确保已成功发出“接收任何请求”、“接收特定请求”或“主机 API”调用,并且返回了连接句柄的请求数据。连接必须处于“发送响应”API 有效的状态。
返回码和原因码:
表 12. BBOA1SRP API 返回码和原因码
返回码 原因码 描述 操作
0 - 成功  
4 - 警告 - 请参阅原因码  
8 - 错误 - 请查看原因码  
  8 注册名称令牌已存在。 确保传递的注册名称有效。
  18 请求长度超出了系统限制。 消息大小大于 Liberty 服务器大小可以支持的大小。请验证该大小是否有效。如果大小有效,请确保 Liberty 服务器的大小足够容纳消息。
  34 找不到目标服务。 请确保在 Liberty 服务器的目标服务器中已安装并启动其中包含目标企业 Bean 的应用程序。
  36 连接状态无效。 用于此请求的连接句柄处于错误状态。请参阅 API 文档以获取有关连接状态的规则。
  38 客户机连接句柄无效。 用于请求的客户机连接句柄无效。请参阅 API 文档以获取有关客户机连接句柄的信息。
  40 发生本地通信错误。 请检查 Liberty 服务器日志以获取所有的本地通信错误消息。
  46 在本地通信发送请求调用中发生错误。 请查看 Liberty 服务器日志以确定错误。
  102 无法访问所提供的响应缓冲区的开头。 请确保所提供响应缓冲区的地址和长度正确。
  104 无法访问所提供的响应缓冲区的结尾。 请确保所提供响应缓冲区的地址和长度正确。
 

480

客户机无法进行授权以调用发送响应功能。 这是意外情况。确保目标服务器正在运行,且在服务器实例中配置了 zosLocalAdapters 服务。
12 10 该 API 找不到所选择的优化本地适配器组。 请确保已启动 Liberty 服务器和目标服务器,确认优化本地适配器支持处于活动状态,然后重试。
  86 找不到 Liberty 服务器主 BGVT。 在当前 z/OS 操作系统映像上未启动 Liberty 服务器。在启动任何优化本地适配器客户机进程之前,请确保服务器已启动。
  88 找不到 Liberty 服务器主客户机存根表。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
  90 找不到 Liberty 服务器优化本地适配器的主客户机存根表插槽。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。

发送响应异常

此 API 将其中包含响应数据的 ResourceException 异常发送回本地 Liberty 服务器中的 JCA 调用者。

表 13. BBOA1SRX API 语法
API 语法
BBOA1SRX

BBOA1SRX (connectionhandle, excresponsedata, exresponsedatalen, rc, rsn)

BBOA1SRX API 接受以下输入参数:
connectionhandle
将用于此响应的 12 个字节的连接句柄。
excresponsedata
指向要发送的异常响应数据开始处的地址的 31 位指针。
excresponsedatalen
其中包含要发送的异常响应数据的长度的 32 位无符号值。异常响应数据是用于描述错误的 EBCDIC 字符串。
BBOA1SRX API 接受以下输出参数:
rc
表明此调用是成功还是失败的整数返回码。
rsn
用于描述此调用失败的原因的整数原因码。
使用说明:
  • 请确保您在此调用中指定的 Liberty 服务器已启动,并且已启用对本地适配器的支持。
  • 在您使用“发送响应”调用之前,请确保使用相匹配的名称在当前地址空间中成功完成了“注册”API 调用。
  • 请确保已成功完成“连接获取”API 调用,并将句柄作为此 API 调用的输入来提供。
  • 请确保已成功发出“接收任何请求”、“接收特定请求”或“主机服务”API 调用,并且返回了连接句柄的请求数据。连接必须处于“发送响应”API 和“发送响应异常”API 都有效的状态。
返回码和原因码:
表 14. BBOA1SRX API 返回码和原因码
返回码 原因码 描述 操作
0 - 成功  
4 - 警告 - 请参阅原因码  
8 - 错误 - 请查看原因码  
  8 注册名称令牌已存在。 确保传递的注册名称有效。
  10 连接句柄处于已释放或无效状态。 请确保传递了有效的连接句柄。
  16 一个或多个参数无效。 请确认所有参数都有效,然后重试该调用。
  18 请求长度超出了系统限制。 消息大小大于 Liberty 服务器大小可以支持的大小。请验证该大小是否有效。如果大小有效,请确保 Liberty 服务器的大小足够容纳消息。
  36 连接状态无效。 用于此请求的连接句柄处于错误状态。请参阅 API 文档以获取有关连接状态的规则。
  38 客户机连接句柄无效。 用于此请求的客户机连接句柄无效。请参阅 API 文档以获取有关客户机连接句柄的信息。
  40 发生本地通信错误。 请检查 Liberty 服务器日志以获取所有的本地通信错误消息。
  46 在本地通信发送请求调用中发生错误。 请查看 Liberty 服务器日志以确定错误。
  102 无法访问所提供的响应缓冲区的开头。 请确保所提供响应缓冲区的地址和长度正确。
  104 无法访问所提供的响应缓冲区的结尾。 请确保所提供响应缓冲区的地址和长度正确。
 

480

客户机无法进行授权以调用发送异常功能。 这是意外情况。确保目标服务器正在运行,且在服务器实例中配置了 zosLocalAdapters 服务。
12 10 该 API 找不到所选择的优化本地适配器组。 请确保已启动 Liberty 服务器和目标服务器,确认优化本地适配器支持处于活动状态,然后重试。
  86 找不到 Liberty 服务器主 BGVT。 在当前 z/OS 操作系统映像上未启动 Liberty 服务器。在启动任何优化本地适配器客户机进程之前,请确保服务器已启动。
  88 找不到 Liberty 服务器主客户机存根表。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
  90 找不到 Liberty 服务器优化本地适配器的主客户机存根表插槽。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。

接收任何请求

此 API 通过所传递的注册名称的池中的任何连接,从本地 Liberty 服务器中接收请求和相关数据。该 API 将请求数据长度和连接句柄作为输出参数返回。使用所返回的连接句柄调用“获取数据”API 将返回接收到的消息数据。

表 15. BBOA1RCA API 语法
API 语法
BBOA1RCA BBOA1RCA (registername, connectionhandle, requestservicename, requestservicenamel, requestdatalen, waittime, rc, rsn)
BBOA1RCA API 接受以下输入参数:
registername
一个入口变量或入口常量,它包含要用于查找从中检索连接的连接池的名称。值必须是刚好由 12 个字符组成的用空格填充的字符串。
waittime
一个整数,它包含在返回“连接不可用”原因码之前等待完成连接的秒数。值 0 表明没有等待时间,API 将无限期等待。waittime 参数仅适用于从连接池获取 WOLA 连接的过程。获取该连接后,它将用于接收来自服务器的请求,且等待时间不受限制。
BBOA1RCA API 接受以下输入或输出参数:
requestservicename
其中包含服务名称的最长可为 256 个字节的 EBCDIC 字符串。此参数是由 Liberty 服务器应用程序在 InteractionSpec 接口上指定的目标服务的名称。值 * 表明当前注册名称下具有的所有服务名称的接收请求。
requestservicenamel
一个整数,其中包含要启动的服务名称的长度;如果服务名称以 null 结束,那么此整数为 0
BBOA1RCA API 接受以下输出参数:
connectionhandle
已返回且在以后请求此连接上的操作时必须传递的 12 个字节的连接句柄。
requestdatalen
将返回包含要接收的数据长度的 32 位无符号值。
rc
表明此调用是成功还是失败的整数返回码。
rsn
用于描述此调用失败的原因的整数原因码。
使用说明:
  • 请确保您在此调用中指定的 Liberty 服务器已启动,并且已启用对本地适配器的支持。
  • 在您使用此 API 之前,请确保使用相匹配的名称在当前地址空间中成功完成了“注册”API 调用。
返回码和原因码:
表 16. BBOA1RCA API 返回码和原因码
返回码 原因码 描述 操作
0 - 成功  
4 - 警告 - 请参阅原因码  
8 - 错误 - 请查看原因码  
  8 注册名称令牌已存在。 确保传递的注册名称有效。
  10 连接不可用。等待时间超时,无法获取连接请求。 应用程序行为改变。请等待,然后重试,或者发出异常终止宏以终止调用了“连接获取”API 的任务。您还可以增大“注册”API 调用上的最大连接数设置。
  16 请求服务名称长度无效。 请更正程序,然后重试该调用。
  19 调用本地通信服务时接收到非零返回码。  
  21 调用本地通信服务时接收到非零返回码。  
  38 客户机连接句柄无效。 用于此请求的客户机连接句柄确定无效。请参阅 API 文档以获取有关客户机连接句柄的信息。
  40 发生本地通信错误。 请检查 Liberty 服务器日志以获取所有的本地通信错误消息。
  46 在本地通信发送请求调用中发生错误。 请查看 Liberty 服务器日志以确定错误。
 

224

找到不完整的注册。 这是意外情况。使用 BBOA1URG 服务取消注册,使用 BBOA1REG 服务再次注册。
 

226

找到不完整的连接句柄。 这是意外情况。使用 BBOA1RCA 服务,再次尝试执行请求。
 

480

客户机无法进行授权以调用接收请求功能。 这是意外情况。确保目标服务器正在运行,且在服务器实例中配置了 zosLocalAdapters 服务。
 

482

重新启动目标服务器后,客户机无法重新连接到目标服务器实例。 这是意外情况。使用 BBOA1URG 服务移除注册,使用 BBOA1REG 服务创建一个新的注册。
 

483

重新启动目标服务器后,客户机无法重新连接到目标服务器实例。 这是意外情况。使用 BBOA1URG 服务移除注册,使用 BBOA1REG 服务创建一个新的注册。
12 10 该 API 找不到所选择的优化本地适配器组。 请确保已启动 Liberty 服务器和目标服务器,确认优化本地适配器支持处于活动状态,然后重试。
 

14

未授权用户标识访问所请求的 Liberty 服务器。 请确保已授权用户标识使用所请求的 Liberty 服务器的 CBIND SAF 类。
  24 注册调用成功后,从池中获取连接时发生错误。 验证服务器是否已启动。如果服务器尚未启动,请重新启动服务器,然后再次尝试该 API 请求。
  86 找不到 Liberty 服务器主 BGVT。 在当前 z/OS 操作系统映像上未启动 Liberty 服务器。在启动任何优化本地适配器客户机进程之前,请确保服务器已启动。
  88 找不到 Liberty 服务器主客户机存根表。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
  90 找不到 Liberty 服务器优化本地适配器的主客户机存根表插槽。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。

接收特定请求

此 API 从本地 Liberty 服务器中接收所指定连接句柄的请求和相关数据。该 API 将请求数据长度作为输出参数返回。使用所指定的连接句柄调用“获取数据”API 将返回接收到的消息数据。
表 17. BBOA1RCS API 语法
API 语法
BBOA1RCS BBOA1RCS (connectionhandle, requestservicename, requestservicenamel, requestdatalen, async(0|1), rc, rsn)
BBOA1RCS API 接受以下输入参数:
connectionhandle
将用于接收请求的 12 个字节的连接句柄。
async(0|1)
async 设置为 1,表明即使可能尚不知道响应的长度,调用者也想要立即返回控制。如果您将 async 设置为 0,那么此调用将等待接收来自 Liberty 服务器的请求。
BBOA1RCS API 接受以下输入或输出参数:
requestservicename
其中包含服务名称的最长可为 256 个字节的 EBCDIC 字符串。此参数是由 Liberty 服务器应用程序在 InteractionSpec 接口上指定的目标服务的名称。值 * 表明设置为当前注册名称下具有的所有服务名称的服务器。
requestservicenamel
一个整数,其中包含要启动的服务名称的长度;如果服务名称以 null 结束,那么此整数为 0
BBOA1RCS API 接受以下输出参数:
requestdatalen
将返回其中包含所接收到的请求数据长度的 32 位无符号值。在您调用“获取数据”API 以复制存储器中的数据之前,调用者可以使用此长度来获取存储器。当 async 设置为 1 时,表明调用者想要立即返回控制;如果尚未接收到请求数据,那么该参数的值设置为 0xFFFFFFFF。在这种情况下,您必须再次调用该 API 以检索入站请求。
rc
表明此调用是成功还是失败的整数返回码。
rsn
用于描述此调用失败的原因的整数原因码。
使用说明:
  • 请确保您在此调用中指定的 Liberty 服务器已启动,并且已启用对本地适配器的支持。
  • 在您使用此 API 之前,请确保使用相匹配的名称在当前地址空间中成功完成了“注册”API 调用。
返回码和原因码:
表 18. BBOA1RCS API 返回码和原因码
返回码 原因码 描述 操作
0 - 成功  
4 - 警告 - 请参阅原因码  
8 - 错误 - 请查看原因码  
  8 注册名称令牌已存在。 确保传递的注册名称有效。
  10 连接句柄处于已释放状态或不正确的状态。 请确保传递了有效的连接句柄。
  16 请求服务名称长度无效。 请更正程序,然后重试该调用。
  19 调用本地通信服务时接收到非零返回码。  
  21 调用本地通信服务时接收到非零返回码。  
  36 连接状态无效。 用于此请求的连接句柄处于错误状态。请参阅 API 文档以获取有关连接状态的规则。
  38 客户机连接句柄无效。 用于此请求的客户机连接句柄无效。请参阅 API 文档以获取有关客户机连接句柄的信息。
  40 发生本地通信错误。 请检查 Liberty 服务器日志以获取所有的本地通信错误消息。
  46 在本地通信发送请求调用中发生错误。 请查看 Liberty 服务器日志以确定错误。
  76 由于服务器不再运行,所以与服务器通信的尝试失败。 启动服务器,然后再次尝试进行通信。
  78 发生了内部错误,导致该连接选择一个不是此连接所处理事务的一部分的请求。 请将此连接返回到连接池。如果问题仍然存在,请参阅 WebSphere Application Server Support 站点上的问题确定信息。
  80 此连接上处于活动状态的事务已超时,然而无法恢复连接状态以便处理另一个请求。 请将此连接返回到连接池。如果问题仍然存在,请参阅 WebSphere Application Server Support 站点上的问题确定信息。
 

226

找到不完整的连接句柄。 这是意外情况。使用 BBOA1CNR 服务发布连接,使用 BBOA1CNG 服务获取新连接。
 

480

客户机无法进行授权以调用接收请求功能。 这是意外情况。确保目标服务器正在运行,且在服务器实例中配置了 zosLocalAdapters 服务。
12 10 该 API 找不到所选择的优化本地适配器组。 请确保已启动 Liberty 服务器和目标服务器,确认优化本地适配器支持处于活动状态,然后重试。
  86 找不到 Liberty 服务器主 BGVT。 在当前 z/OS 操作系统映像上未启动 Liberty 服务器。在启动任何优化本地适配器客户机进程之前,请确保服务器已启动。
  88 找不到 Liberty 服务器主客户机存根表。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
  90 找不到 Liberty 服务器优化本地适配器的主客户机存根表插槽。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。

接收响应长度

“接收响应长度”API 将检索先前发送的请求调用中的响应数据的长度。
表 19. BBOA1RCL API 语法
API 语法
BBOA1RCL BBOA1RCL ( connectionhandle, async(0|1), responsedatalen, rc, rsn )
BBOA1RCL API 接受以下输入参数:
connectionhandle
要用于此请求的 12 个字节的连接句柄。
async(0|1)
async 设置为 1,表明即使可能不知道响应的长度,调用者也想要立即返回控制。如果您将 async 设置为 0,那么此调用将等待 Liberty 服务器返回响应,该 API 将在 responsedatalen 参数中返回响应长度。
BBOA1RCL API 接受以下输出参数:
requestdatalen
将返回包含所接收数据的长度的 32 位无符号值。在您调用“获取数据”API 以复制存储器中的数据之前,调用者可以使用此长度来获取存储器。如果您将 async 设置为 1,并且尚未接收到响应数据,那么该参数的值设置为 0xFFFFFFFF
rc
表明此调用是成功还是失败的整数返回码。
rsn
用于描述此调用失败的原因的整数原因码。
使用说明:
  • 请确保您在此调用中指定的 Liberty 服务器已启动,并且已启用对本地适配器的支持。
  • 在您使用此 API 之前,请确保使用相匹配的名称在当前地址空间中成功完成了“注册”API 调用。
  • 请确保已成功完成“连接获取”API 调用,并且将句柄作为此调用的输入来提供。
  • 在进行此调用之前,请确保已成功完成“发送请求”API 调用。
返回码和原因码:
表 20. BBOA1RCL API 返回码和原因码
返回码 原因码 描述 操作
0 - 成功  
4 - 警告 - 请参阅原因码  
8 - 错误 - 请查看原因码  
  8 注册名称令牌已存在。 确保传递的注册名称有效。
  19 调用本地通信服务时接收到非零返回码。  
  21 调用本地通信服务时接收到非零返回码。  
  36 连接状态无效。 已确定用于此请求的连接句柄处于错误状态。请参阅 API 文档以获取有关连接状态的规则。
  38 客户机连接句柄无效。 用于此请求的客户机连接句柄确定无效。请参阅 API 文档以获取有关客户机连接句柄的信息。
  40 发生本地通信错误。 请检查 Liberty 服务器日志以获取所有的本地通信错误消息。
 

226

找到不完整的连接句柄。 这是意外情况。使用 BBOA1CNR 服务发布连接,使用 BBOA1CNG 服务获取新连接。
 

480

客户机无法进行授权以调用接收长度功能。 这是意外情况。确保目标服务器正在运行,且在服务器实例中配置了 zosLocalAdapters 服务。
12 10 该 API 找不到所选择的优化本地适配器组。 请确保已启动 Liberty 服务器和目标服务器,确认优化本地适配器支持处于活动状态,然后重试。
  86 找不到 Liberty 服务器主 BGVT。 在当前 z/OS 操作系统映像上未启动 Liberty 服务器。在启动任何优化本地适配器客户机进程之前,请确保服务器已启动。
  88 找不到 Liberty 服务器主客户机存根表。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
  90 找不到 Liberty 服务器优化本地适配器的主客户机存根表插槽。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。

获取消息数据

此 API 将复制所接收到的消息数据。当此 API 调用返回时,将从适配器消息高速缓存中移除此消息。
表 21. BBOA1GET API 语法
API 语法
BBOA1GET BBOA1GET ( connectionhandle, msgdata, msgdatalen, rc, rsn, rv )
BBOA1GET API 接受以下输入参数:
connectionhandle
要用于此请求的 12 个字节的连接句柄。
msgdata
指向要复制到的数据区域开始处的地址的 31 位指针。此参数指向的存储器必须位于调用者可写入的键中。
msgdatalen
其中包含要复制数据的长度的 32 位无符号值。
BBOA1GET API 接受以下输出参数:
rc
表明此调用是成功还是失败的整数返回码。
rsn
用于描述此调用失败的原因的整数原因码。
rv
其中包含此请求的上下文缓冲区大小的 32 位整数返回值。
使用说明:
  • 请确保您在此调用中指定的 Liberty 服务器已启动,并且已启用对本地适配器的支持。
  • 在您使用“发送请求”API 之前,请确保使用相匹配的名称在当前地址空间中成功完成了“注册”API 调用。
  • 请确保已成功完成“连接获取”API 调用,并且将句柄作为此调用的输入来提供。
  • 如果 API 调用者输入 msgdatalen 参数大于实际的消息响应,那么返回码将包含 0,并且会将实际的消息长度提供给返回值。
  • 要点: 在“获取消息数据”调用返回到调用者之后,消息数据不再存在,连接将返回到可用于其他发送或接收请求调用的状态。返回出错的获取消息数据或接收响应长度的后续调用。
返回码和原因码:
表 22. BBOA1GET API 返回码和原因码
返回码 原因码 描述 操作
0 - 成功  
4 - 警告 - 请参阅原因码  
8 - 错误 - 请查看原因码  
  8 注册名称令牌已存在。 确保传递的注册名称有效。
  36 连接状态无效。 已确定用于此请求的连接句柄处于错误状态。请参阅 API 文档以获取有关连接状态的规则。
  38 客户机连接句柄无效。 用于此请求的客户机连接句柄确定无效。请参阅 API 文档以获取有关客户机连接句柄的信息。
  40 发生本地通信错误。 请检查 Liberty 服务器日志以获取所有的本地通信错误消息。
  48 在本地通信读请求中发生错误。 请查看 Liberty 服务器日志以确定错误。
  72 响应长度输入参数的大小不足以包含响应消息。 只能返回部分消息。消息的其余部分都被废弃。请参考返回值以获取消息响应的大小。
  98 无法访问所提供的请求缓冲区的开头。 请确保所提供请求缓冲区的地址和长度正确。
  100 无法访问所提供的请求缓冲区的结尾。 请确保所提供请求缓冲区的地址和长度正确。
  102 无法访问所提供的响应缓冲区的开头。 请确保所提供响应缓冲区的地址和长度正确。
  104 无法访问所提供的响应缓冲区的结尾。 请确保所提供响应缓冲区的地址和长度正确。
 

226

找到不完整的连接句柄。 这是意外情况。使用 BBOA1CNR 服务发布连接,使用 BBOA1CNG 服务获取新连接。
 

480

客户机无法进行授权以调用获取数据功能。 这是意外情况。确保目标服务器正在运行,且在服务器实例中配置了 zosLocalAdapters 服务。
12 10 该 API 找不到所选择的优化本地适配器组。 请确保已启动 Liberty 服务器和目标服务器,确认优化本地适配器支持处于活动状态,然后重试。
  86 找不到 Liberty 服务器主 BGVT。 在当前 z/OS 操作系统映像上未启动 Liberty 服务器。在启动任何优化本地适配器客户机进程之前,请确保服务器已启动。
  88 找不到 Liberty 服务器主客户机存根表。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
  90 找不到 Liberty 服务器优化本地适配器的主客户机存根表插槽。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。

调用

此 API 使用其他底层的原语 API 函数来调用本地 Liberty 服务器中的方法。它旨在用于预先知道响应输出区最大大小的情况中。
表 23. BBOA1INV API 语法
API 语法
BBOA1INV BBOA1INV ( registername, requesttype, requestservicename, requestservicenamel, requestdata, requestdatalen, responsedata, responsedatalen, waittime, rc, rsn, rv )
BBOA1INV API 接受以下输入参数:
registername
一个入口变量或入口常量,它包含要用于查找从中检索此调用连接的连接池的名称。值必须是刚好由 12 个字符组成的用空格填充的字符串。
requesttype
一个整数,其中包含请求类型,用于指示要处理的工作请求的类型。对于本地 EJB 工作请求,唯一受支持的值为 1
requestservicename
其中包含要调用的服务名称的最长可为 256 个字节的 EBCDIC 字符串。此参数指定本地业务接口的 JNDI 名称。
requestservicenamel
一个整数,其中包含要启动的服务名称的长度;如果服务名称以 null 结束,那么此整数为 0
requestdata
指向要发送的请求数据开始处的地址的 31 位指针。
requestdatalen
其中包含要发送请求数据的长度的 32 位无符号值。
responsedata
指向要复制到的响应数据区域开始处的地址的 31 位指针。此参数指向的存储器必须位于调用者可写入的键中。
responsedatalen
其中包含要发送的响应数据的长度的 32 位无符号值。
waittime
一个整数,它包含在返回“连接不可用”原因码之前等待完成连接的秒数。值 0(零)表明没有超时,此 API 将无限期等待。waittime 参数仅适用于从连接池获取 WOLA 连接的过程。获取该连接后,它将用于接收来自服务器的请求,且等待时间不受限制。
BBOA1INV API 接受以下输出参数:
rc
表明此调用是成功还是失败的整数返回码。
rsn
用于描述此调用失败的原因的整数原因码。
rv
其中包含已接收到并且已复制到调用者响应区域的消息数据大小的 32 位整数返回值。
使用说明:
  • 请确保您在此调用中指定的 Liberty 服务器已启动,并且已启用对本地适配器的支持。
  • 在您使用“发送请求”API 之前,请确保使用相匹配的名称在当前地址空间中成功完成了“注册”API 调用。
  • 如果 API 调用者输入 responsedatalen 参数大于实际的消息响应,那么返回码将包含 0(零),并且将在返回值中提供实际的消息长度。
返回码和原因码:
表 24. BBOA1INV API 返回码和原因码
返回码 原因码 描述 操作
0 - 成功  
4 - 警告 - 请参阅原因码  
8 - 错误 - 请查看原因码  
  8 注册名称令牌不存在。 确保传递的注册名称有效。
  10 连接不可用。等待时间已到期,未能获得连接请求。 应用程序行为改变。等待并重试或接受此失败的“调用 API”调用。另一选择是增加注册 API 调用上的最大连接数设置。
  16 请求服务名称长度无效。 请更正程序,然后重试该调用。
  18 响应长度超出了系统限制。 消息大小大于 Liberty 服务器大小可以支持的大小。请验证该大小是否有效。如果大小有效,请确保 Liberty 服务器的大小足够容纳消息。
  19 调用本地通信服务时接收到非零返回码。  
  21 调用本地通信服务时接收到非零返回码。  
24 注册调用成功后,从池中获取连接时发生错误。 验证服务器是否已启动。如果服务器未运行,请重新启动服务器,然后再次尝试该 API 请求。
  26 全局事务无法开始。  
  28 找到了注册,但是它处于不活动状态。  
  32 API 调用上的请求类型无效。 请求类型参数无效。请更正程序,然后重试该调用。
  34 找不到目标服务。 请确保在目标 Liberty 服务器中已安装并启动其中包含目标企业 Bean 的应用程序。
  36 连接状态无效。 已确定用于此请求的连接句柄处于错误状态。请参阅 API 文档以获取有关连接状态的规则。
  38 客户机连接句柄无效。 用于此请求的客户机连接句柄确定无效。请参阅 API 文档以获取有关客户机连接句柄的信息。
  40 发生本地通信错误。 请检查 Liberty 服务器日志以获取所有的本地通信错误消息。
  44 在目标企业 Bean 中发生异常或意外情况。 请参阅 Liberty 服务器日志以查看异常数据。
  46 在本地通信发送请求中发生错误。 请参阅 Liberty 服务器日志以确定错误。
  48 在本地通信读请求中发生错误。 请查看 Liberty 服务器日志以确定错误。
  72 响应长度输入参数的大小不足以包含响应消息。 只能返回部分消息。消息的其余部分都被废弃。请参考返回值以获取消息响应的大小。
  98 无法访问提供的请求缓冲区的开头部分。 请确保所提供请求缓冲区的地址和长度正确。
  100 无法访问提供的请求缓冲区的结束部分。 请确保所提供请求缓冲区的地址和长度正确。
  102 无法访问提供的响应缓冲区的开头部分。 请确保所提供响应缓冲区的地址和长度正确。
  104 无法访问提供的响应缓冲区的结束部分。 请确保所提供响应缓冲区的地址和长度正确。
 

224

找到不完整的注册。 这是意外情况。使用 BBOA1URG 服务取消注册,使用 BBOA1REG 服务再次注册。
 

226

找到不完整的连接句柄。 这是意外情况。使用 BBOA1INV 服务,再次尝试执行请求。
 

480

客户机无法进行授权以对调用功能进行调用。 这是意外情况。确保目标服务器正在运行,且在服务器实例中配置了 zosLocalAdapters 服务。
 

482

重新启动目标服务器后,客户机无法重新连接到目标服务器实例。 这是意外情况。使用 BBOA1URG 服务移除注册,使用 BBOA1REG 服务创建一个新的注册。
 

483

重新启动目标服务器后,客户机无法重新连接到目标服务器实例。 这是意外情况。使用 BBOA1URG 服务移除注册,使用 BBOA1REG 服务创建一个新的注册。
12 10 该 API 找不到所选择的优化本地适配器组。 请确保已启动 Liberty 服务器和目标服务器,确认优化本地适配器支持处于活动状态,然后重试。
 

14

未授权用户标识访问所请求的 Liberty 服务器。 请确保已授权用户标识使用所请求的 Liberty 服务器的 CBIND SAF 类。
  24 注册调用成功后,从连接池中获取连接时发生错误。 验证服务器是否已启动。如果服务器未启动,请重新启动服务器,然后再次尝试该 API 请求。
  86 找不到 Liberty 服务器主 BGVT。 在当前 z/OS 操作系统映像上未启动 Liberty 服务器。在启动任何优化本地适配器客户机进程之前,请确保服务器已启动。
  88 找不到 Liberty 服务器主客户机存根表。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
  90 找不到 Liberty 服务器优化本地适配器的主客户机存根表插槽。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。

主机服务

“主机服务”API 使用其他底层原语 API 函数来设置本机语言 z/OS 程序,以作为从本地 Liberty 服务器进行优化本地适配器调用的服务器和目标。当您在调用该 API 之前知道请求区域最大大小时,请使用该 API。
表 25. BBOA1SRV API 语法
API 语法
BBOA1SRV BBOA1SRV ( registername, requestservicename, requestservicenamel, requestdata, requestdatalen, connectionhandle, waittime, rc, rsn, rv )
BBOA1SRV API 接受以下输入参数:
registername
一个入口变量或入口常量,它包含要用于查找从其中检索此调用连接的连接池的名称。值必须是刚好由 12 个字符组成的用空格填充的字符串。
requestdata
指向所接收到的请求数据开始处的地址的 31 位指针。此参数指向的存储器必须位于调用者可写入的键中。
requestdatalen
其中包含要将消息接收到的数据区域的长度的 32 位无符号值。
connectionhandle
返回到调用者并用于发送此请求的响应的 12 个字节的连接句柄。
waittime
一个整数,它包含在返回“连接不可用”原因码之前等待完成连接的秒数。如果值为 0(零),那么意味着不存在超时,此 API 将无限期等待。waittime 参数仅适用于从连接池获取 WOLA 连接的过程。获取该连接后,它将用于接收来自服务器的请求,且等待时间不受限制。
BBOA1SRV API 接受以下输入或输出参数:
requestservicename
其中包含服务名称的最长可为 256 个字节的 EBCDIC 字符串。此参数是由 Liberty 服务器应用程序在 InteractionSpec 接口上指定的目标服务的名称。值 * 表明设置为当前注册名称下具有的所有服务名称的服务器。
requestservicenamel
一个整数,其中包含要启动的服务名称的长度;如果服务名称以 null 结束,那么此整数为 0
BBOA1SRV API 接受以下输出参数:
rc
表明此调用是成功还是失败的整数返回码。
rsn
用于描述此调用失败的原因的整数原因码。
rv
其中包含已接收到并且已复制到调用者响应区域的消息数据大小的 32 位整数返回值。
使用说明:
  • 请确保您在此调用中指定的 Liberty 服务器已启动,并且已启用对本地适配器的支持。
  • 在您使用此 API 之前,请确保使用相匹配的名称在当前地址空间中成功完成了“注册”API 调用。
  • 如果 API 调用者输入 requestdatalen 参数大于实际的消息响应,那么返回码将包含 0(零),并且将在返回值中提供实际的消息长度。
  • 对于使用“发送响应”API 的此“主机服务”调用,必须在所有响应上提供返回的连接句柄。
返回码和原因码:
表 26. BBOA1SRV API 返回码和原因码
返回码 原因码 描述 操作
0 - 成功  
4 - 警告 - 请参阅原因码  
8 - 错误 - 请查看原因码  
  8 注册名称令牌已存在。 确保传递的注册名称有效。
  10 连接句柄处于已释放状态。 请确保传递了正确的连接句柄。
  12 连接句柄不在注册名称中的连接内。 请更正程序,然后重试该调用。
  16 请求服务名称长度无效。 请更正程序,然后重试该调用。
  18 响应长度超出了系统限制。 消息大小大于 Liberty 服务器大小可以支持的大小。请验证该大小是否有效。如果大小有效,请确保 Liberty 服务器的大小足够容纳消息。
  40 发生本地通信错误。 请检查 Liberty 服务器日志以获取所有的本地通信错误消息。
  46 在本地通信发送请求中发生错误。 请查看 Liberty 服务器日志以确定错误。
  48 在本地通信读请求中发生错误。 请查看 Liberty 服务器日志以确定错误。
  72 响应长度输入参数的大小不足以包含响应消息。 只能返回部分消息。消息的其余部分都被废弃。请参考返回值以获取消息响应的大小。
  98 无法访问所提供的请求缓冲区的开头。 请确保所提供请求缓冲区的地址和长度正确。
  100 无法访问所提供的请求缓冲区的结尾。 请确保所提供请求缓冲区的地址和长度正确。
 

224

找到不完整的注册。 这是意外情况。使用 BBOA1URG 服务取消注册,使用 BBOA1REG 服务再次注册。
 

226

找到不完整的连接句柄。 这是意外情况。使用 BBOA1SRV 服务,再次尝试执行请求。
 

480

客户机无法进行授权以调用主机功能。 这是意外情况。确保目标服务器正在运行,且在服务器实例中配置了 zosLocalAdapters 服务。
 

482

重新启动目标服务器后,客户机无法重新连接到目标服务器实例。 这是意外情况。使用 BBOA1URG 服务移除注册,使用 BBOA1REG 服务创建一个新的注册。
 

483

重新启动目标服务器后,客户机无法重新连接到目标服务器实例。 这是意外情况。使用 BBOA1URG 服务移除注册,使用 BBOA1REG 服务创建一个新的注册。
12 10 该 API 找不到所选择的优化本地适配器组。 请确保已启动 Liberty 服务器和目标服务器,确认优化本地适配器支持处于活动状态,然后重试。
 

14

未授权用户标识访问所请求的 Liberty 服务器。 请确保已授权用户标识使用所请求的 Liberty 服务器的 CBIND SAF 类。
  86 找不到 Liberty 服务器主 BGVT。 在当前 z/OS 操作系统映像上未启动 Liberty 服务器。在启动任何优化本地适配器客户机进程之前,请确保服务器已启动。
  88 找不到 Liberty 服务器主客户机存根表。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。
  90 找不到 Liberty 服务器优化本地适配器的主客户机存根表插槽。 在当前 z/OS 操作系统映像上已启动 Liberty 服务器,但服务器未在支持优化本地适配器客户机存根表的级别运行。请确保应用程序正在优化本地适配器存根级别运行,这些存根与此 z/OS 系统上的 Liberty 服务器兼容。

Java EE 连接器体系结构 (JCA) 适配器 API

对于从 Liberty 服务器到批处理程序或子系统的调用,Liberty 服务器应用程序使用标准 JCA API。对下列接口进行了定制以与优化本地适配器配合使用:
  • ConnectionSpec
  • InteractionSpec
  • 记录 I/O

ConnectionSpec

当您获取源自连接工厂的连接时,使用 ConnectionSpec 接口来传递特定于连接的参数。这些参数可能会覆盖连接工厂中定义的相同名称的参数。对于优化本地适配器,作为 com.ibm.websphere.ola.ConnectionSpecImpl 类来实现此接口。ConnectionSpecImpl 类使您能够指定要与其进行通信的优化本地适配器注册名称。

当您与 CICS 链接服务器进行通信时,ConnectionSpecImpl 类提供了一些方法,可以使用这些方法来覆盖链接服务器使用的值。例如,您可以指定链接服务器调用事务的四字符事务标识 BBO#。您还可以指定是将请求数据存储在 CICS COMMAREA 还是 CONTAINER 对象中。

有关 ConnectionSpecImpl 类中的方法的信息,请参阅所生成的 API 文档

InteractionSpec

使用 InteractionSpec 接口来指定您连接到的资源适配器实例的特定于请求的参数。对于优化本地适配器,作为 com.ibm.websphere.ola.InteractionSpecImpl 类来实现此接口。可以使用 InteractionSpecImpl 类来设置要其进行通信的应用程序的服务名称。由获取连接时所指定的注册名称来主管服务名称。

有关 InteractionSpecImpl 类中的方法的信息,请参阅所生成的 API 文档

记录 I/O

使用 Record 接口将请求和响应数据传递到您连接到的资源适配器实例。优化本地适配器提供了 Record 接口的两个实现,IndexedRecord 和 MappedRecord。您可以通过从应用程序使用的 JCA 连接实例获取对 RecordFactory 的引用来创建这两个实现。

如果您要将数据传递给批处理或 UNIX 系统服务程序,或者您要使用 COMMAREA 或单个 CONTAINER 对象与 CICS 进行通信,请使用 IndexedRecord 对象。将一个字节阵列 (byte[]) 添加至 IndexRecord 对象,以表示程序在请求中发送的数据。还会将响应接收到 IndexedRecord 对象中。您可以通过从 IndexedRecord 对象中检索第一个条目并将其强制转换为字节阵列来获取响应数据。

如果您要将数据传递到 CICS 中的多个 CONTAINER 对象,请使用 MappedRecord 对象。MappedRecord 对象包含名称/值对,与映射对象库相似。在名称/值对中,名称是将数据传输到的容器的名称,值是指定为字节阵列 (byte[]) 的实际数据。当您使用 MappedRecord 对象来发送请求时,也将使用 MappedRecord 对象发送回响应。响应包含每个包含响应数据和相关联数据的容器的名称。


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

文件名:rwlp_dat_olaapis.html