%PARSER (parser {: options})

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

The first operand specifies the program or procedure to do the parsing. 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 parser is a prototyped procedure, you use the %PADDR built-in function.

The second operand specifies options that are passed directly to the parser. The parser 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 parser.

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 parser.

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

Examples of %PARSER

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

DATA-INTO myfld %DATA(document) %PARSER('MYPARSER');
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 "parserOptions" data structure. 

DCL-DS parserOptions LIKEDS(myParserOpts_T);
DATA-INTO myDs %DATA('myData.txt' : 'doc=file')
               %PARSER('MYPARSERS(myProcedure)' : parserOptions);
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-INTO myds %DATA('myData.txt' : 'doc=file')
               %PARSER(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-INTO myds %DATA('myData.txt' : 'doc=file')
               %PARSER(%PADDR(myProc) : constParm);

For more examples of %PARSER, and more information about the DATA-INTO operation, see DATA-INTO (Parse a Document into a Variable).

See the Rational Open Access: RPG Edition topic for information on writing an parser.