%GEN (generator {: options})

%GEN is used as the third operand of the DATA-GEN operation code to specify the program or procedure to generate the document, and any options supported by the generator. %GEN does not return a value, and it cannot be specified anywhere other than for the DATA-GEN operation code.

The first operand specifies the program or procedure to generate the document. It can be
  • A procedure pointer expression
  • The %PADDR built-in function
  • A character expression identifying a program. It must be in one of the following forms
    • MYPGM
    • MYLIB/MYPGM
    • *LIBL/MYPGM
  • A character expression identifying a procedure in a service program. It must be in one of the following forms
    • MYSRVPGM(myProcedure)
    • MYLIB/MYSRVPGM(myProcedure)
    • *LIBL/MYSRVPGM(myProcedure)
Note: If a prototype name is specified, it is assumed to be a procedure returning either a procedure pointer value or a character value. If the generator is a prototyped procedure, you use the %PADDR built-in function.

The second operand specifies options that are passed directly to the generator. The generator determines the nature of the options that it supports.

If the second operand is the name of a variable which can be modified, the address of the variable is passed directly to the generator.

If the second operand is a character expression, including the name of a character variable that cannot be modified, a pointer to a null-terminated string containing the content of the expression is passed to the generator.

The generator receives information that indicates whether the pointer the pointer is a null-terminated string.

Examples of %GEN

A program name is specified for the first operand. The second operand is omitted. The generator program 'MYGEN' does not receive any options. 

DATA-GEN myfld %DATA(document) %GEN('MYGEN');
A procedure in a service program is specified for the first operand. A modifiable variable is specified for the second operand. Procedure 'myProcedure' receives a pointer to the "genOptions" data structure. 

DCL-DS genOptions LIKEDS(myGenOpts_T);
DATA-GEN myDs %DATA('myData.txt' : 'doc=file')
              %GEN('MYGENPROCS(myProcedure)' : genOptions);
A procedure pointer is specified for the first operand. A character expression is specified for the second operand. The procedure specified by the procedure pointer receives a pointer to a null-terminated string with the value "sep=comma". 

DCL-S p POINTER(*PROC);
DCL-S sep CHAR(1) INZ(',');
DATA-GEN myds %DATA('myData.txt' : 'doc=file')
              %GEN(p : 'sep=' + sep);
Built-in function %PADDR is specified for the first operand. A non-modifiable character variable "constParm" is specified for the second operand. The value of "constParm" is "boolean=indicator". The procedure specified by prototype "myProc" receives a pointer to a null-terminated string with the value "boolean=indicator". specified as the second operand. 

DCL-PI *N;
   constParm VARCHAR(20) CONST;
END-PI;
DATA-GEN myds %DATA('myData.txt' : 'doc=file')
              %GEN(%PADDR(myProc) : constParm);

For more examples of %GEN, and more information about the DATA-GEN operation, see DATA-GEN (Generate a Document from a Variable).

See the Rational Open Access: RPG Edition topic for information on writing a generator.