DATA-GEN (根据变量生成文档)

自由格式语法

DATA-GEN{(E)} 源 %DATA (文档 {: options1 }) %GEN (生成器 {: options2 });

DATA-GEN{(E)} *START %DATA (文档 ): options1) %GEN (生成器 {: 选项 2 });

DATA-GEN{(E)} *END %DATA (文档 : options1) %GEN (生成器 {: 选项 2 });

代码	因子1	扩充因子2
数据-GEN		source %DATA (文档 {: options1 }) %GEN (生成器 {: options2 })
数据-GEN		*START %DATA (文档 ): options1) %GEN (生成器 {: 选项 2 })
数据-GEN		*END %DATA (文档 : options1) %GEN (生成器 {: 选项 2 })

DATA-GEN 操作从 RPG 变量生成结构化文档。 DATA-GEN 需要生成器程序或过程来生成文档的文本。

DATA-GEN 操作将 source 变量的名称和值传递给生成器，生成器使用回调函数将文档的文本逐渐传递给 DATA-GEN 操作。 DATA-GEN 操作将信息放入由 %DATA 内置函数指定的目标 RPG 变量或目标 Integrated File System 文件中。

有关为 DATA-GEN 操作编写生成器的信息，请参阅 Rational® Open Access: RPG Edition 主题。请参阅 DATA-GEN 生成器示例，以获取有关可在何处找到 DATA-GEN 操作的生成器示例的信息。

第一个操作数指定文档的源变量。如果第一个操作数是数组，那么可以使用 %SUBARR 来限制用于 DATA-GEN 的元素数。如果需要多个 DATA-GEN 操作来生成文档，那么第一个操作数也可以是 *START 或 *END。

第二个操作数必须是 %DATA 内置函数，用于标识文档的输出位置以及用于控制 RPG 变量中的信息生成方式的选项。有多个选项可用于 %DATA 内置函数。请参阅 DATA-GEN 操作码的 %DATA 选项。

请参阅 %DATA (文档 {:options}) ，以获取有关 %DATA 的更多信息。

第三个操作数必须是 %GEN 内置函数，标识生成文档的程序或过程，以及特定于生成器的选项。请参阅 %GEN (生成器 {: options}) 以获取有关 %GEN 的更多信息。

如果第一个操作数是变量名:

将根据变量的名称和值生成文档。传递给生成器的名称的大小写将与用于定义变量或子字段的大小写相同。如果该变量是外部描述的数据结构，那么除非在 EXTFLD 语句上指定了子字段，否则该名称将为大写。请参阅 EXTFLD{(field_name)}。
可以使用名称选项来更改传递给生成器的变量的顶级名称。
例如，如果变量名是 myDs，并指定了选项 "name=info"，那么传递给生成器的文档顶层名称将是 "info"。
如果变量是数据结构，那么在操作因错误而结束时，可能会将某些子字段的信息输出到文档。一旦生成者将信息报告给 DATA-GEN ，就会将其添加到文档中。

数据结构的子字段的名称和值将按照它们在数据结构定义中的显示顺序传递给生成器。

如果第一个操作数是 *START ，那么 DATA-GEN 操作将开始输出到 Integrated File System中同一文件的 DATA-GEN 操作序列。如果第一个操作数是 *END ，那么 DATA-GEN 操作结束 DATA-GEN 操作的序列。请参阅使用多个 DATA-GEN 操作来生成单个文档。

可以指定操作扩展器 E 来处理以下状态码:

00352: DATA-GEN 选项无效。
00355: 生成器程序或过程不可用。
00359: 运行生成器程序或过程时发生错误。
00361: 从 RPG 变量准备数据时发生错误。
00362: 生成器提供的信息出错。
00363: 生成器检测到错误。
00364: 处理输出文件时发生错误。
00365: 执行DATA-GEN操作序列时发生错误。

注: 仅当使用自由格式语法时，才能指定操作扩展器。

对于状态 00363 ，来自生成器的错误代码将放置在 PSDS 的位置 368-371 中的子字段 "外部返回码" 中。此子字段将在操作开始时设置为零，并在操作结束时设置为生成器返回的值。错误代码的含义由生成器确定。

如果在 %DATA 内置函数的 options 参数中找到未知，无效或无关的选项，那么操作将失败，状态码为 00352 (DATA-GEN 选项中的错误)。 PSDS 中的 "外部返回码" 子字段将不会从操作开始时设置的初始值零开始更新。

使用多个 DATA-GEN 操作来生成单个文档

DATA-GEN 操作序列可用于将单个文档生成到 Integrated File System 文件中。该文件将保持打开状态，直到迂到序列结束。

数据-GEN *START: 以 DATA-GEN *START 操作开始序列。必须在 %DATA 内置函数的第二个操作数中指定选项 "doc = file"。
DATA-GEN 变量: 在 *START 和 *END 操作之间，指定带有变量名的 DATA-GEN 操作作为第一个操作数，并使用指定为 DATA-GEN *START 操作的 %DATA 内置函数的第一个操作数的同一文件。必须在 *START 和 *END 操作之间的 DATA-GEN 操作的 %DATA 内置函数的第二个参数中指定 "output = continue"。
数据-GEN *END: 使用 DATA-GEN *END 操作结束序列，该操作与指定为 DATA-GEN *START 操作的 %DATA 内置函数的第一个操作数的文件相同。

序列中的 DATA-GEN 操作可以在不同的过程中完成。但是，它们必须都在同一激活组和同一线程中运行。

如果对具有 DATA-GEN *START 操作的过程的调用在没有针对同一输出文件的 DATA-GEN *END 的情况下结束，那么将关闭输出文件。

获取 DATA-GEN 的跟踪

要获取与生成器之间传递的信息的跟踪，请使用值 "*STDOUT" 设置 QIBM_RPG_DATA_GEN_TRACE 环境变量。


   ADDENVVAR QIBM_RPG_DATA_GEN_TRACE VALUE('*STDOUT')

注: 如果跟踪输出未立即显示，或者如果它闪烁太快而无法查看，那么可以通过调用以下 ILE RPG 程序来查看标准输出。使用 CRTBNDRPG 编译程序。


**FREE
CTL-OPT ACTGRP(*NEW);
DCL-PR printf EXTPROC(*DCLCASE);
  p POINTER VALUE OPTIONS(*STRING : *NOPASS);
END-PR;
DCL-PR getchar INT(10) EXTPROC(*DCLCASE) END-PR;
DCL-C EOL x'15';

printf (EOL);
getchar ();
return;

下面的 C 程序将完成同样的事情。使用 CRTBNDC 编译程序。


#include <stdio.h>
main()
{
   printf("\n");
   getchar();
}