READQ TS

从临时存储器队列中读取数据。

语法

READQ TS

条件: INVREQ ， IOERR ， ISCINVREQ ， ITEMERR ， REGERR ， NOTAUTH ， QIDERR 和 SYSIDERR

当此命令与主存储器或辅助存储器 (在本地 CICS® 区域中) 中的队列一起使用时，或者与通过 IPIC 连接提供给远程 CICS 区域的函数一起使用时，此命令是线程安全的。当它与由临时存储器数据共享服务器 (TS 服务器) 管理的 z/OS® 耦合设施中的共享临时存储池中的队列一起使用时，它也是线程安全的。当通过 IPIC 以外的其他连接类型将命令交付到远程 CICS 区域时，该命令是非线程安全的。

NOHANDLE、RESP 和 RESP2是常用选项，可添加到所有 EXEC CICS 命令中以处理错误条件。命令语法图和选项说明中没有明确包含这些选项。有关这些常用选项和 EXEC CICS 命令语法的信息，请参阅 EXEC CICS 命令格式和编程注意事项.

动态事务路由的注意事项: 使用此命令可能会创建对动态事务路由的使用产生负面影响的事务间亲缘关系。有关事务亲缘关系的更多信息，请参阅亲缘关系。

描述

READQ TS 从主存储器或辅助存储器中的临时存储器队列检索数据。

选项

INTO (data-area)

指定要将数据写入的数据区。数据区可以是任何变量，数组或结构。

ITEM (data-value)

提供半字二进制值，用于指定要从队列中检索的逻辑记录的项号。

LENGTH (数据区)

指定要读取的记录的长度 (作为半字二进制值)。

如果指定 INTO 选项，那么如果可由编译器从 INTO 变量生成长度，那么无需指定 LENGTH。

如果指定 INTO ， LENGTH 将定义程序接受的数据的最大长度。如果指定的值小于零，那么假定为零。如果数据的长度超过指定的值，那么会将数据截断为该值，并出现 LENGERR 条件。

完成检索操作后，数据区将设置为从队列中读取的数据记录的原始长度。

如果指定 SET 选项，那么必须指定 LENGTH。

有关何时必须指定 LENGTH 的详细信息，请参阅翻译注意事项：EXEC CICS 命令中的 LENGTH 选项。

下一步

指定在任何任务检索到的最后一条记录之后的下一条顺序逻辑记录的检索，或者如果未检索到先前的记录，那么指定第一条记录的检索。

注意: 如果两个任务在浏览操作期间失去控制，那么可能会中断两个任务。例如，任务 1 可能检索项 1 ， 3 和 6 ，而任务 2 检索项 2 ， 4 和 5。将 READQ TS 命令与来自线程安全程序的 NEXT 配合使用会增加任务交错的可能性，因为它们在自己的 TCB 上并行运行。如果检索项目的顺序很重要，请在应用程序中添加序列化逻辑，以便单线程浏览队列，尤其是当应用程序定义为 CONCURRENCY(THREADSAFE) 或 CONCURRENCY(REQUIRED) 时。

NUMITEMS (数据区)

指定一个半字二进制字段， CICS 将一个数字存储到该字段中，该数字指示队列中有多少项。仅当命令正常完成时才会发生此情况。

QNAME (名称)

作为 QUEUE的替代方法， QNAME 指定要从中读取的队列的符号名称 (1-16 个字符)。如果名称少于 16 个字符，那么仍必须使用 16 个字符的字段，必要时用空格填充。

QUEUE (名称)

指定要从中读取的队列的符号名称 (1-8 个字符)。如果名称少于 8 个字符，那么仍必须使用 8 字符字段，必要时使用空白填充。

SET (ptr-ref)

指定设置为所检索数据的地址的指针引用。除非被其他命令或语句更改，否则指针引用在下一个 READQ TS 命令或任务结束之前有效。

如果应用程序是使用 DATALOCATION (ANY) 定义的，那么数据的地址可以高于或低于 16 MB 界线。如果应用程序是使用 DATALOCATION (BELOW) 定义的，那么数据的地址低于 16 MB 线。

如果为正在运行的任务指定了 TASKDATAKEY (USER) ，并且存储器保护处于活动状态，那么返回的数据在用户密钥中。如果指定了 TASKDATAKEY (CICS) 并且存储器保护处于活动状态，那么返回的数据位于 CICS键中。

SYSID (systemname)

(仅限远程和共享队列) 指定系统名称 (1-4 个字符) ，用于标识请求所定向到的远程系统或共享队列池。 TSMODEL 资源定义不支持为驻留在临时存储器数据共享池中的队列指定 SYSID。请改为使用 QUEUE 或 QNAME 选项。对共享队列池使用显式 SYSID 需要临时存储器表 (TST) 的支持。

条件

16 INVREQ

在以下任一情况下发生:

队列是由 CICS 内码创建的。
指定的队列名称仅由二进制零组成。

缺省操作: 异常终止任务。

17 IOERR

RESP2 值：

5: 共享队列存在不可恢复的输入/输出错误。

缺省操作: 异常终止任务。

54 ISCINVREQ

当远程系统指示不符合已知条件的故障时发生。

缺省操作: 异常终止任务。

26 ITEMERR

在以下任一情况下发生:

指定的项编号无效 (即，超出写入队列的项编号范围)。
尝试使用 NEXT (缺省值) 选项来读取超出队列末尾的内容。

缺省操作: 异常终止任务。

22 LENGERR

当存储的数据的长度大于 LENGTH 选项指定的值时发生。

此条件仅适用于 INTO 选项，并且不能与 SET 一起出现。

缺省操作: 异常终止任务。

70 NOTAUTH

RESP2 值：

101: 对 QUEUE (名称) 的资源安全性检查失败。

缺省操作: 异常终止任务。

44 QIDERR

在主存储器或辅助存储器中找不到指定的队列时发生。

缺省操作: 异常终止任务。

53 个 SYSIDERR

RESP2 值：

4

在下列任何情况下发生:

SYSID 选项指定的名称不是本地系统或远程系统 (通过定义 CONNECTION 或 IPCONN使 CICS 知道)。
使用 IPIC 连接时，本地系统和/或远程系统不是 CICS TS 4.2 或更高版本的区域。
与远程系统的链接已关闭。
执行临时存储器命令的 CICS 区域无法连接到管理支持所引用临时存储器队列的 TS 池的 TS 服务器。例如，如果未授权 CICS 区域访问临时存储服务器，那么可能会发生此情况。
如果临时存储服务器未启动，或者由于服务器在 CICS 继续运行时发生了故障 (或已停止) ，那么也会发生此情况。

缺省操作: 异常终止任务。

示例

以下示例显示如何将第一个 (或唯一) 记录从临时存储器队列读取到请求中指定的数据区中。 LENGTH 数据区被赋予记录长度的值。

EXEC CICS READQ TS
     ITEM(1)
     QUEUE(UNIQNAME)
     INTO(DATA)
     LENGTH(LDATA)

以下示例显示如何将下一条记录从临时存储器队列读取到 CICS提供的数据区中。将 SET 选项指定的指针引用设置为保留给数据记录的存储区的地址，并为 LENGTH 数据区提供记录长度的值。

EXEC CICS READQ TS
     QUEUE(DESCRQ  )
     SET(PREF)
     LENGTH(LENG)
     NEXT