GET CONTAINER (CHANNEL)

描述

GET CONTAINER (CHANNEL) 读取与指定通道容器关联的数据。

保存数据的容器由名称和作为其容器的通道标识; 由 拥有 该数据的通道标识。

可以通过指定 CHANNEL 选项来显式标识拥有容器的通道，也可以通过省略 CHANNEL 选项来隐式标识该通道。 省略此选项时，将隐含当前通道。 如果没有当前通道，那么假定该命令是 EXEC CICS GET CONTAINER (BTS) 命令。 有关更多信息，请参阅 GET CONTAINER (BTS)。

选项

BYTEOFFSET (data-value)

指定作为全字二进制值的偏移量 (以字节为单位) ，返回的数据将从该偏移量开始。 对于 CHAR 容器， BYTEOFFSET 值用作所请求代码页中数据的偏移量。 如果使用具有多字节字符的代码页，那么根据您指定的 BYTEOFFSET 值，返回的数据可能在开头和/或结尾具有部分字符。 在这种情况下，应用程序必须能够处理和解释返回的数据。 如果指定的值小于零，那么假定为零。

CCSID (data-area)

返回包含 CONVERTST (NOCONVERT) 选项返回的数据的编码字符集标识 (CCSID) 的全字。 可以使用此选项来检索 DATATYPE 为 CHAR 的容器，而不转换数据。 如果为容器指定了 DATATYPE BIT ，那么此值为零。

CHANNEL (data-value)

指定拥有容器的通道的名称 (1-16 个字符)。 您可以指定通道名称 DFHTRANSACTION 以使用事务通道。

CONTAINER (data-value)

指定保存要检索的数据的容器的名称 (1-16 个字符)。

CONVERTST (cvda)

指定所需的数据转换状态。

无转换

将检索容器数据而不进行转换。 如果您使用WEB RECEIVE HTTP存储在容器中，并且需要从该容器中检索未转换的主体，则必须使用NOCONVERT选项。

FLENGTH (data-area)

作为输入字段， FLENGTH 以全字二进制值的形式指定要读取的数据的长度。 作为输出字段， FLENGTH 返回容器中数据的长度。 FLENGTH 是输入或输出字段，具体取决于您指定的 BYTEOFFSET ， INTO ， SET 或 NODATA 选项。

指定了 BYTEOFFSET 选项

FLENGTH 既是输入字段又是输出字段。

在 输入上， FLENGTH 指定程序接受的数据的最大长度。 返回的数据从 BYTEOFFSET 值指定的偏移量开始。 如果指定的值小于零，那么假定为零。

在 输出 (即，完成检索操作时) 上， CICS® 将数据区设置为返回的数据长度。 返回的最大长度等于容器中数据的长度减去 BYTEOFFSET 值。

指定了 INTO 选项

FLENGTH 既是输入字段又是输出字段。

在 输入上， FLENGTH 指定程序接受的数据的最大长度。 如果指定的值小于零，那么假定为零。 如果数据的长度超过指定的值，那么会将数据截断为该值，并且会出现 LENGERR 条件。 如果数据长度小于指定值，那么将复制数据，但不会执行任何填充。

如果长度可以由编译器从 INTO 变量生成，那么不需要指定 FLENGTH。 如果同时指定 INTO 和 FLENGTH ，那么 FLENGTH 指定程序接受的数据的最大长度。

在 输出 (即，完成检索操作时) 上， CICS 会将数据区 (如果指定) 设置为容器中数据的实际长度。 如果容器包含已从一个 CCSID 转换为另一个 CCSID 的字符数据，那么这是转换后数据的长度。

指定了 SET 或 NODATA 选项

FLENGTH 是仅输出字段。 它必须存在并且必须指定为数据区。

完成检索操作后，会将数据区设置为容器中数据的实际长度。 如果容器包含已从一个 CCSID 转换为另一个 CCSID 的字符数据，那么这是转换后数据的长度。

INTO (data-area)

指定要将检索到的数据放入的数据区。

INTOCCSID (data-value)

指定将容器中的字符数据转换为全字二进制数的编码字符集标识 (CCSID)。 如果您希望为代码页指定 IANA 名称，或者如果您希望将 CCSID 指定为字母数字字符，请改为使用 INTOCODEPAGE 选项。

对于 CICS Transaction Server for z/OS® 应用程序， CCSID 通常是 EBCDIC CCSID。 但是，如果您希望检索 ASCII 数据而不将其自动转换为 EBCDIC ，那么可以指定 ASCII CCSID。

如果未指定 INTOCCSID 和 INTOCODEPAGE ，那么转换的值缺省为区域的 CCSID。 在 LOCALCCSID 系统初始化参数上指定区域的缺省 CCSID。

只能转换字符数据，仅当在用于将数据放在容器中的 PUT CONTAINER 或 PUT64 CONTAINER 命令上指定了 CHAR 的 DATATYPE 时，才可以转换字符数据。 如果在 PUT CONTAINER 或 PUT64 CONTAINER 命令上指定了 FROMCCSID 或 FROMCODEPAGE ，那么表示 DATATYPE 为 CHAR。

有关使用通道进行数据转换的更多信息，请参阅 使用通道进行数据转换。

有关 CCSID 的说明，请参阅 准备使用通道进行代码页转换。

INTOCODEPAGE (data-value)

指定要将容器中的字符数据转换为的代码页的 IANA 注册的字母数字字符集名称或编码字符集标识 (CCSID) ，最多使用 40 个字母数字字符，包括相应的标点符号。 如果您希望使用 IANA 注册的字符集名称，请使用此选项代替 CCSID 选项，如 HTTP Content-Type 标头中所述。 CICS 将IANA名称转换为CCSID，后续的数据转换过程完全相同。 如果您更希望以字母数字字符 (而不是全字二进制数) 指定 CCSID ，那么也请使用此选项。

如果存在代码页的 IANA 名称，并且 CICS 支持使用该名称，那么该名称将与 CCSID 一起列出。 有关更多信息，请参阅 准备使用通道进行代码页转换。

NODATA

指定不检索任何数据。 使用此选项可发现容器中数据的长度 (以 FLENGTH 格式返回)。

如果进行数据转换，字符数据的长度可能会更改。 因此，如果要将字符数据转换为任何 CCSID 而不是此区域的 CCSID，那么当您指定 NODATA 时，还应该指定 INTOCCSID。 这将确保在 FLENGTH 中返回正确的已转换数据长度。

SET (ptr-ref)

指定在其中返回所检索数据的地址的数据区。

如果使用 DATALOCATION (ANY) 定义了发出 GET CONTAINER 命令的应用程序，那么数据的地址可以高于或低于 16 MB 界线。 如果应用程序是使用 DATALOCATION (BELOW) 定义的，那么数据的地址低于 16 MB 线。 如果为正在执行的事务指定了 TASKDATAKEY (USER) ，那么返回的数据在用户键中; 否则在 CICS 键中。

CICS 将维护数据区，直到发生以下任何情况为止:

• 对于同一通道中的同一容器，可访问此存储器的任何程序都会发出带有 SET 选项的后续 GET CONTAINER 或 GET64 CONTAINER 命令。
• 容器由 DELETE CONTAINER 命令删除。
• 容器由 MOVE CONTAINER 命令移动。
• 通道超出程序作用域。
• 通道以及其中的容器将由 DELETE CHANNEL 命令删除。

请谨防链接到可能发出其中一个命令的其他程序。

请勿发出 FREEMAIN 命令以释放此存储器。

如果应用程序需要保留数据，那么应将其移动到自己的存储器中。

条件

123 CCSIDERR

RESP2 值：

1

在 INTOCCSID 选项上指定的 CCSID 超出有效 CCSID 值的范围。

2

在 INTOCCSID 选项上指定的 CCSID 和容器的 CCSID 是不受支持的组合。 (容器的 CCSID 是在构建容器时使用 FROMCODEPAGE 或 FROMCCSID 或缺省值指定的值。)

3

已创建数据类型为 BIT 的数据。 无法进行代码页转换。 返回数据时未进行任何代码页转换。

4

无法转换一个或多个字符。 在转换后的数据中，字符已被空格替换。

5

在容器的代码页转换中发生内部错误。

122 CHANNELERR

RESP2 值：

2

找不到在 CHANNEL 选项上指定的通道。

125 CODEPAGEERR

RESP2 值：

1

不支持在 INTOCODEPAGE 选项上指定的代码页。

2

在 INTOCODEPAGE 选项上指定的代码页与通道的代码页是不受支持的组合。

3

已创建数据类型为 BIT 的数据。 无法进行代码页转换。 返回数据时未进行任何代码页转换。

4

无法转换一个或多个字符。 在转换后的数据中，字符已被空格替换。

5

在容器的代码页转换中发生内部错误。

110 CONTAINERERR

RESP2 值：

10

找不到 CONTAINER 选项上指定的容器。

16 INVREQ

RESP2 值：

2

指定了不带 CHANNEL 选项的 INTOCCSID 选项，并且没有当前通道 (因为发出该命令的程序没有传递一个)。 INTOCCSID 仅在指定 (显式或隐式) 通道的 GET CONTAINER 命令上有效。

4

未指定 CHANNEL 选项，没有当前通道 (因为发出该命令的程序未传递一个) ，并且在当前活动的 BTS 活动范围之外发出了该命令。

5

CONVERTST cvda 值无效。

22 LENGERR

RESP2 值：

11

程序区域的长度比容器中数据的长度短。 当面积较小时，数据将被截断以适应其中。

12

偏移量大于或等于容器的长度。