DATA-INTO (Parse a Document into a Variable)

The DATA-INTO operation imports the data from a structured document into an RPG variable. DATA-INTO is similar to XML-INTO except that XML-INTO can only work with XML documents, while DATA-INTO can work with any structured document. DATA-INTO also differs from XML-INTO in that DATA-INTO requires a parser that can parse the data in the document.

The DATA-INTO operation passes the document text to the parser, which uses callback functions to gradually pass the names and values of the data in the document to the DATA-INTO operation. The DATA-INTO operation places the information into the target RPG variable.

For information on writing a parser for the DATA-INTO operation, see the Rational Open Access: RPG Edition topic.

The first operand specifies the target of the parsed data. It can contain a variable name or the %HANDLER built-in function.

The second operand must be the %DATA built-in function, identifying the document to be parsed and the options controlling the way the information is used to set the RPG variable. See %DATA (document {:options}) for more information on %DATA.

The third operand must be the %PARSER built-in function, identifying the program or procedure to do the parsing, and the parser-specific options. See %PARSER (parser {: options}) for more information on %PARSER.

See Rules for transferring data to RPG variables for XML-INTO and DATA-INTO.

Subfields of a data structure will be set in the order they appear in the document; the order could be important if subfields overlap within the data structure.

%NULLIND is not updated for any field or subfield during an DATA-INTO operation.

For status 00357, the error code from the parser will be placed in the subfield "External return code" in positions 368-371 of the PSDS. This subfield will be set to zero at the beginning of the operation and set to the value returned by the parser at the end of the operation. The meaning of the error code is determined by the parser.

If an unknown, invalid or unrelated option is found in the options parameter of the %DATA built-in function, the operation will fail with status code 00352 (Error in DATA-INTO options). The External return code subfield in the PSDS will not be updated from the initial value of zero, set when the operation begins.

When the document does not match the RPG variable, for example if the document does not contain the default or specified path, or if it is missing some items to match the subfields of an RPG data structure, the DATA-INTO operation will fail with status 00356. The allowextra, allowmissing, and countprefix options can be used to specify whether an item can have more or less data than is required to fully set the RPG variable.

If the data for an item is not valid for the type of the RPG variable it matches, the operation will fail with status 0356; the specific status code for the assignment error will appear in the replacement text for message RNX0356.

Tip: To avoid the DATA-INTO operation failing because the data cannot be successfully assigned to RPG fields with types such as Date or Numeric, the receiver variable can be defined with subfields that are all of type character or UCS-2. Then the data can be converted to other data types by the RPG program using the conversion built-in functions %DATE, %INT, and so on.

See Examples of DATA-INTO parsers for information about where you can find examples of parsers for the DATA-INTO operation.

   ADDENVVAR QIBM_RPG_DATA_INTO_TRACE_PARSER VALUE('*STDOUT')

**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;

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