GETMAIN

获取 24 位或 31 位主存储器。

GETMAIN

条件: LENGERR 和 NOSTG

此命令是线程安全的。

描述

GETMAIN 获取由 FLENGTH 选项指示的大小的主存储区。区域的地址在 SET 选项中提供的指针引用中返回。

此命令包含 LENGTH 选项，仅用于兼容性目的; 对于使用当前版本的 CICS®运行的程序，请使用 FLENGTH。

CICS 始终在 16 个字节的边界上进行分配，并将请求的长度舍入到最接近的 16 个字节的倍数。没有缺省初始化，因此如果需要将存储器初始化为特定位配置，那么必须使用 INITIMG 选项。

CICS 从下列其中一个动态存储区 (DSA) 分配存储器:

24 位存储器中的 DSA:
- 低于 16 MB (低于界线) 的 CICS 动态存储区 (CDSA)
- 低于 16 MB 的用户动态存储区 (UDSA)
- 低于 16 MB 的共享动态存储区 (SDSA)
31 位存储器中的 DSA; 扩展动态存储区 (EDSA):
- 扩展 CICS 动态存储区 (ECDSA) ，高于 16 MB 但低于 2 GB (高于该行)
- 扩展用户动态存储区 (EUDSA) ，高于 16 MB 但低于 2 GB
- 扩展共享动态存储区 (ESDSA) ，高于 16 MB 但低于 2 GB

有关这些 DSA 的更多信息，请参阅 CICS 动态存储区。

注: 不能使用 GETMAIN 从以下 DSA 获取存储器:

只读 DSA (RDSA)。
扩展只读 DSA (ERDSA)。
扩展可信 DSA (ETDSA)。
以上条形动态存储区 (GDSA) 中的 DSA。要从这些 DSA 获取存储器，请使用 GETMAIN64 命令。

CICS 根据以下选项从 24 位或 31 位存储器分配存储器:

还指定了带有 BELOW 的长度选项。 CICS 从 DSA 获取 24 位存储器中的存储器。
未指定 FLENGTH 选项 BELOW。请求程序的 AMODE 确定获取的存储器的位置。例如，对于 AMODE (31) 程序， CICS 从 EDSA 获取存储器。
LENGTH 选项。 CICS 从 DSA 获取 24 位存储器中的存储器。

CICS 根据以下选项从 CICS-key ， user-key 或 shared DSA 分配存储器:

用户数据键
CICSDATAKEY
共享
如果在 GETMAIN 命令上未指定 data-key 选项，那么在正在其下运行请求程序的 TRANSACTION 资源定义上的 TASKDATAKEY 选项
请参阅 TRANSACTION 属性。

下表概述了数据键选项的效果:

表 1. GETMAIN 命令中的数据键选项
无数据键选项	指定了 USERDATAKEY	指定了 CICSDATAKEY
存储键由事务定义上的 TASKDATAKEY 确定	用户密钥存储器。如果未指定 SHARED 选项，那么从 UDSA 或 EUDSA 获取存储器; 如果指定了 SHARED 选项，那么从 SDSA 或 ESDSA 获取存储器。	CICS键存储器。从 CDSA 或 ECDSA 获取存储器。

GETMAIN 命令上的 data-key 选项将覆盖 TRANSACTION 资源定义上的 TASKDATAKEY 选项。例如，您可以指定 CICSDATAKEY 以确保请求程序从 CICS DSA 获取 CICS-key 存储器，即使在 TRANSACTION 资源定义上指定了 TASKDATAKEY (USER) 也是如此。

在使用 FREEMAIN 或 FREEMAIN64 命令释放任务之前，该任务获取的存储器可用。对于未使用 SHARED 选项获取的区域，只有获取存储器的任务才能释放该存储器，并且在任务结束时， CICS 会自动释放尚未释放的此类存储器。

所有任务 (包括通过事务隔离运行的任务) 都可以访问使用 SHARED 选项获取的任何存储器。但是，在任务结束时不会释放 SHARED 区域，直到显式释放该区域为止; 任何任务都可以发出 FREEMAIN 或 FREEMAIN64 请求。这意味着您可以在任务到任务通信中使用 SHARED 存储器。

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

选项

下面

指定获取 24 位 (低于 16 MB) 存储器; 即，从 CDSA ， UDSA 或 SDSA 获取。

CICSplex 数据键

指定 CICS 从 CICS-key DSA (CDSA 或 ECDSA) 分配存储器，覆盖在事务资源定义上指定的 TASKDATAKEY 选项。如果未指定数据密钥选项，那么存储密钥 (CICS-key 或 user-key) 取决于事务资源定义上的 TASKDATAKEY 选项。

注: 如果程序正在事务资源定义上使用 TASKDATAKEY (USER) 定义的任务下运行，请不要显式使用 FREEMAIN 或 FREEMAIN64，而是允许在任务终止过程中释放存储器。

FLENGTH (data-value)

指定所需的存储字节数 (全字二进制格式)。

您可以指定的最大长度是相应 DSA 的限制值; 即， DSALIMIT 或 EDSALIMIT。这些是系统初始化参数，用于定义 CICS 可以在其中分别分配和管理 24 位和 31 位存储器中的各个 DSA 的总体存储器限制。

如果请求的长度大于相应的 DSALIMIT 或 EDSALIMIT 值，那么会出现 LENGERR 条件。如果请求的长度小于相应的限制，但大于可用存储器，那么将发生 NOSTG 情况。

INITIMG (data-value)

指定可选的 1 字节初始化值。如果指定 INITIMG ，那么 CICS 会将获取的存储器的每个字节设置为您提供的位字符串。否则， CICS 不会初始化存储器。仅在 COBOL 程序中，必须使用数据区而不是数据值来定义初始化位字符串。

LENGTH (data-value)

仅为了与编写为在 CICS的较早发行版下运行的程序兼容，才支持此选项。建议使用 FLENGTH。

LENGTH 指定所需的存储空间的字节数 (无符号半字二进制值)。此选项意味着存储器低于 16 MB 界线，并且具有 65520 字节的上限。对于高于 16 MB 的更大区域或存储器，请使用 FLENGTH。

如果 LENGTH 的值为零，那么将出现 LENGERR 条件。如果请求的长度大于可用存储器，那么将发生 NOSTG 情况。

无暂挂

指定如果没有可用的存储器，那么 CICS 不会暂挂该任务，而是发出 NOSTG 条件。

如果在执行命令时 NOSTG 的 HANDLE CONDITION 处于活动状态，那么控制权将传递到 HANDLE CONDITION 中提供的用户标签。这优先于无暂挂选项，但由 NOHANDLE 或 RESP 取消激活。

SET (ptr-ref)

设置指向获取的主存储器地址的指针引用。指针设置为存储区的第一个字节。

为 FLENGTH 或 LENGTH 指定的零或负值所导致的 LENGERR 条件将 ptr-ref 设置为零。

共享

阻止 GETMAIN 命令在请求存储器的任务结束时自动释放该存储器。这将启用任务到任务通信。直到发出相应的 FREEMAIN (无论是请求任务还是其他任务) 之后，才会释放使用 SHARED 获取的区域。

请注意，如果任务异常终止，那么不会自动释放所获取的任何共享存储器。

用户数据键

指定 CICS 从用户键 DSA (UDSA ， SDSA ， EUDSA 或 ESDSA) 分配存储器，覆盖在事务资源定义上指定的 TASKDATAKEY 选项。如果未指定数据密钥选项，那么存储密钥 (CICS-key 或 user-key) 取决于事务资源定义上的 TASKDATAKEY 选项。

条件

22 LENGERR

RESP2 值：

1: FLENGTH 值小于 1 或大于要满足请求的目标动态存储区的长度。请参阅 CICS 动态存储区中有关 DSA 的信息。

如果 LENGTH 值为零，那么也会发生此情况。

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

42 个 NOSTG

RESP2 值：

2: 请求的存储空间大于目标 DSA 中当前可用的存储空间。请参阅 CICS 动态存储区中有关 DSA 的信息。

缺省操作: 忽略条件。活动的 HANDLE CONDITION NOSTG 也会引发此情况。

示例

以下示例显示如何从低于 16 MB 的用户密钥存储器中获取 1024 字节的区域 (假定在 TRANSACTION 资源定义中指定了 TASKDATAKEY (USER)) ，并将其初始化为空格:

EXEC CICS GETMAIN SET(PTR)
          FLENGTH(1024)
          BELOW
          INITIMG(BLANK)

必须将程序中的 BLANK 定义为表示空格的字符。

以下示例显示如何从高于 16 MB 但低于 2 GB 的 CICS密钥存储器中获取 2048 字节区域 (无论在事务资源定义上指定了 TASKDATAKEY 选项) ，并将其初始化为空格:

EXEC CICS GETMAIN SET(PTR)
          FLENGTH(2048)
          INITIMG(BLANK)
          CICSDATAKEY