GET

标识并 (可选) 返回包含所选资源表记录的结果集。

读取语法图跳过可视语法图GETOBJECT(data-value) TESTCOUNT(data-ref)CRITERIA(data-area)LENGTH(data-value)FILTER(cpsm-令牌)PARM(data-area)PARMLEN(data-value)NOWAITTOKEN(data-value)CONTEXT(data-value)SCOPE(data-value)RESULT(cpsm-令牌) THREAD(cpsm-令牌) RESPONSE(data-ref) REASON(data-ref)

描述

此命令标识包含所选资源表记录的结果集。 此命令返回已识别的记录，或已识别的记录的计数，或同时返回记录和计数。
  • 资源表可以是表示 CICS® 资源， CICSPlex ® SM 或 CICS 定义或 CICSPlex SM 运行时对象的表。
  • 执行 GET 命令后，记录指针将定位到结果集的顶部 (即，结果集中的第一个记录)。
  • 如果发出 GET 命令时生效的上下文和作用域包含不支持所请求资源表的 CICS 系统，那么将忽略这些 CICS 系统的请求。
  • 在某些 CICS 环境中， CICSPlex SM 为以下对象返回的资源表属性值:
    资源表 属性值 CICS 环境
    LOCTRAN RESSEC (RESSECEXT) CICS/MVS
    与 CICS返回的 CVDA 值不匹配。 CICS 返回的值与其他 CICS 环境中的 CVDA 值冲突。 为了保留属性的唯一性， CICSPlex SM 将 9000 添加到 CICS返回的值中。 有关转换 CVDA 值的更多信息，请参阅 TRANSLATE 命令。

相关命令

DISCARD ， FETCH ， GETDEF ， QUERY ， RECEIVE ， REFRESH ，指定 FILTER ，指定 VIEW

选项

CONTEXT(数据值)
标识此命令的上下文。 上下文必须是 CMAS 或 CICSplex 的 1-to 8 字符名称。

如果未指定 CONTEXT 选项，那么将采用线程的缺省上下文。

计数(数据引用)
指定一个变量以在此操作完成后接收目标结果集中的资源表记录数。
CRITERIA(数据区)
标识包含要用于此操作的过滤表达式的缓冲区。 CRITERIA 选项仅检索那些符合指定过滤条件的资源表记录。
FILTER(cpsm-token)
标识要用于此操作的过滤器。 FILTER 选项仅检索满足指定过滤条件的那些资源表记录。

用于标识过滤器的 cpsm-token 值由指定 FILTER 命令返回。

LENGTH(数据值)
一个全字值，用于指定 CRITERIA 缓冲区的长度。
注: 您指定的缓冲区长度不应包含除过滤表达式以外的任何数据。
无等待
一旦接受 GET 命令，就会将控制权返回给程序，这将允许异步处理该命令。

如果指定 NOWAIT 选项，那么必须使用后续 RECEIVE 命令来测试此请求是否已完成。 异步请求的结果将作为 ASYNCREQ 资源表记录返回。

注: 如果指定 TOKEN 选项，那么缺省情况下将采用 NOWAIT 选项。
OBJECT(数据值)
标识要检索其记录的资源表。 此值必须是有效资源表或有效视图的 1-to 8 字符名称。 如果您正在使用 TEST 参数，那么必须为 OBJECT指定 CICS 资源表名称。 指定任何其他值 (包括视图名称) 将导致错误。
PARM(数据区)
标识包含要在预选资源表记录中使用的参数表达式的缓冲区。

有关如何将参数表达式与 GET 命令配合使用的详细信息，请参阅 使用 PARM 选项。 有关可以为给定资源表指定的参数的描述，请参阅 CICSPlex SM 资源表。

PARMLEN(数据值)
指定 PARM 缓冲区长度的全字值。
REASON(数据引用)
指定变量以接收此命令返回的全字原因值。
RESPONSE(数据引用)
指定一个变量以接收此命令返回的全字响应值。
RESULT(cpsm-token)
标识此操作要处理的 API 结果集。 结果集可以是由以下任何命令生成的结果集:
  • COPY
  • GET
  • GROUP
  • PERFORM OBJECT。
CICSPlex SM 将现有结果集的内容替换为此 GET 命令请求的资源表记录。
如果此字段为:
  • 设置为二进制零 (在 COBOL ， C ， PL/I 或汇编程序中)
  • 未初始化的变量 (在 REXX 中)。
CICSPlex SM 创建新的结果集，并在同一字段中返回其标识标记。

如果您正在使用 TEST 参数，那么必须为 RESULT指定零值。 指定任何其他值都会导致错误。

SCOPE(数据值)
标识此命令的作用域。
如果当前上下文 (如此命令或先前的 CONNECT 或限定命令所设置) 是 CICSplex ，并且 OBJECT 选项标识 CICS 资源，那么需要有效的作用域。 作用域可以是:
  • CICSplex 本身的 1-to 8 字符名称
  • CICSplex 中的 CICS 系统或 CICS 系统组
  • CICSPlex SM 资源描述 (RESDESC) 中定义的逻辑作用域。
如果 OBJECT 标识 CICS 定义资源，并且 PARM 选项包含 CSDGROUP 参数，那么可以指定有效的作用域。 作用域可以是:
  • CICSplex 中的 CICS 系统。

如果当前上下文是 CMAS 或 OBJECT 选项标识任何其他类型的资源表，那么此选项没有意义，将被忽略。

如果未指定 SCOPE 选项，那么将采用线程的缺省作用域。 如果当前上下文是 CICSplex ，并且未在 CONNECT 或限定命令上设置缺省作用域，那么您将收到 SCOPE 选项的 INVALIDPARM 响应。

测试
仅返回与请求匹配的记录的计数。 如果指定 TEST ，那么请求不会返回任何记录。 如果指定 TEST ，那么必须为 OBJECT 参数指定 CICS 资源名称，并为 RESULT 参数指定零值。
THREAD(cpsm-token)
标识要用于此操作的 API 线程。 用于标识线程的 cpsm-token 值由 CONNECT 命令返回。
TOKEN(数据值)
定义 1-to 4 字符令牌，您选择将异步 GET 请求与后续 RECEIVE 命令的结果关联。 此令牌供程序使用; CICSPlex SM 不使用该值。 当此 GET 请求完成时， RECEIVE 命令将返回该令牌。

条件

以下是 GET 命令可返回的 RESPONSE 值的列表。 每个 RESPONSE 的描述都包含关联的 REASON 值的列表 (如果适用)。
确定
该命令已成功完成处理。
已调度
已调度该命令进行处理。
NODATA
找不到与指定搜索条件匹配的记录。
繁忙
由于以下原因，发生了忙碌状态:
RESULT
RESULT 选项上指定的结果集正由另一个命令处理。
发生了错误
由于下列其中一个原因，发生了环境错误:
无服务
应用程序存根程序无法装入 API 服务模块。
无存储器
应用程序存根程序无法在正在运行处理线程的地址空间中获取必需的存储器。
未处理
请求所指向的其中一个 MAS 无法处理该请求。
请求超时
请求所针对的其中一个或多个 CMAS 未响应。

如果只有部分 CMAS 或 MAS 未响应，那么 GET 命令仍可生成有效结果。 COUNT 可能大于零， RESULT 可能非零。 这样的结果集包含来自那些响应的 CMAS 和 MAS 的数据。

SOCRESOURCE
CMAS 拥有的必需资源不可用。
FAILED
由于下列其中一个原因，该命令失败:
异常终止
命令处理异常结束。
EXCEPTION
命令处理迂到异常情况。
INVALIDATA
检测到无效数据。 包含无效数据的参数将作为原因值返回:
条件
CRITERIA 缓冲区中列出的属性值对于指定的属性无效。
无效命令
由于下列其中一个原因，该命令无效:
FILTER
在操作上传递的过滤表达式过大或复杂。
LENGTH
命令上所有选项的总长度超过最大限制。
INVALIDPARM
检测到无效参数。 将返回无效的参数作为原因值:
  • 上下文
  • 条件
  • FILTER
  • LENGTH
  • OBJECT
  • 参数 (parm)
  • 参数
  • RESULT
  • SCOPE
  • TOKEN
  • 太棒了
请检查命令描述以获取有效的参数语法。
NOTAVAILABLE
由于下列其中一个原因，发生了不可用的情况:
APITASK
API 控制子任务未处于活动状态。
CMAS
请求所定向到的 CMAS 不可用。
CPSMAPI
处理线程所连接的 CMAS 不可用于 API 处理。
MAINTPOINT
当前上下文的维护点不可用。
SCOPE
指定作用域中的任何 MAS 都不可用，或者它们都不支持所请求的资源表。
WORKLOAD
API 请求上标识的工作负载在本地 CMAS 上不可用。
未找到
由于以下原因发生了 "找不到" 情况:
属性
找不到指定资源表的 CRITERIA 缓冲区中指定的属性。
不允许
由于以下原因发生了不允许的情况:
USRID
与处理线程关联的用户标识没有必需的安全权限。
服务器 GONE
处理线程所连接的 CMAS 不再处于活动状态。
表错误
由于以下原因，资源表记录无效:
数据错误
与一个或多个资源表属性关联的值无效。 使用 FEEDBACK 命令可检索有关此错误的其他数据。
版本 INVL
由于下列其中一个原因，发生了版本冲突:
NotSupported
不支持用于此命令的应用程序存根程序的版本。
NOTVSNCONN
用于此命令的应用程序存根程序的版本与用于 CONNECT 命令的版本不同。
警告
由于以下原因，该命令已完成处理，但有警告:
maxRecords
MAS 添加到结果集的记录数将超过该 MAS的 MAXHISTRECS 值。 MAXHISTRECS 限制内的记录已添加到结果集。 修改 FILTER 或 PARM 参数值以增加或减少 MAS 应该添加到结果集的记录数。
注: 如果指定了包含多个 MAS的作用域，那么收集的记录总数可能会超过单个 MAS的 MASHISTRECS 值。