This open source utility for IBM System i features a command - XMLPARSE -
that loads the data from a XML stream file to a database file member.
- At least OS/400 release V7R1.
- Compiler ILE RPG IV, product 57xxWDS, opt. 31, is required during the installation phase and to run command XMLPARSE.
- Minimum knowledge of XML language.
- Download file ez4parse.zip from the Easy400 download page and unzip it.
- Follow the ez4parse.txt instructions to upload and to restore library EZ4PARSE.
- On the IBM System i
- sign on with a class *SECOFR user profile
- run the following procedure:
STRREXPRC SRCMBR(INSTALL) SRCFILE(EZ4PARSE/QREXSRC)
It does the following:
- creates objects in library EZ4PARSE
- restores IFS directory /ez4parse
To know about the latest updates to this tool, press this link.
To know about the release date of the Ez4PARSE version you may have installed, on your IBM i system execute command EZ4PARSE/RELEASED .
This is the core XML conversion command of this utility.
This basic command requires that the names of the XML elements match the field names of the receiving database file.
In the next page you can find other commands to solve more difficult cases:
- Command CRTTODBF creates a receiving data dabatase file with field names the same as the XML element names
- Command RNMXMLFLDS duplicates the XML file while renaming its XML element names
- Command SUPERPARSE automatically drives you through commands of this utility.
Parse a XML stream file (XMLPARSE)
Type choices, press Enter.
XML stream file . . . . . . . . STMF >
Path to the XML elements . . . . XMLPTH *AUTO
Number of segments in XMLPTH . . XMLPTHNBR 2 1-99
Target database file . . . . . . TOFILE Name
library . . . . . . . . . . . *CURLIB Name, *CURLIB
Target member . . . . . . . . . TOMBR *FILE Name, *FILE
Replace or add records . . . . . MBROPT *REPLACE *ADD, *REPLACE
Take default parsing options . . DFTOPTIONS > *NO *YES, *NO
1.CCSID parsing option . . . . CCSID *BEST *BEST, *JOB, *UCS2
2.TRIM parsing option . . . . . TRIM *ALL *ALL, *NONE
3.ALLOWMISSING parsing option ALWMISSING *YES *YES, *NO
4.ALLOWEXTRA parsing option . . ALWEXTRA *YES *YES, *NO
|Figure 1 - Command XMLPARSE|
This command gets data from a XML stream file and adds or replace
records to a given database file member.
- Note: Before running this command, you must make sure that
the data elements in the XML files match the field names in the TOFILE database record format.
For more information and examples about "XML parsing options", see this PDF.
6-How it works
The following describes how program XMLPARSE does its job:
Note. The QTEMP ILE-RPG XML parser program takes advantage of the special statement
XML-INTO available since V6R1.
- Calls program CRTPARSEP to create in library QTEMP a XML parser program accessing the specified database file member.
Program CRTPARSEP does the following:
- Calls system API QUSLRCD to retrieve the name of the target database file record format
- Copies to a QTEMP source file the source of an ILE-RPG template XML parser program, by customizing its output file name and record format name
- Compiles this QTEMP customized XML parser program
- Calls the QTEMP XML customized parser program providing all the parameters received from command XMLPARSE.
Command XMLPARSE does not support XML repeated data fields and data subfields.
For instance, in the following example:
<?xml version="1.0" encoding="UTF-8" ?>
<mpiReference>SKF VKJP 2053</mpiReference>
<description>JEU DE SOUFFLETS DE DIRECTION OPEL, VAUXHALL</description>
|Figure 2- XML with repeated fields and data subfields|
- data field <stock> is a repeated data field (it appears 3 times in "record" structure <product>)
- data field <stock> is made of 3 data subfields
(<country>, <deliveryDate> and <parts>)
When such cases occur, though XMLPARSE may not bump out, the data transfer from those XML data fields does not correctly work.
8-Error codes returned from XML-INTO
||Error in XML parsing|
See "ML parser error message RNX0351, detailed error meanings", below.
||Invalid XML option|
||XML document does not match RPG variable|
XML data element names do not match database record field names.
- Display XML stream file and database record field names, look for mismatches
- ALWMISSING(*YES) or ALWEXTRA(*YES) may help
||Error preparing for XML parsing|
• XML parser error message RNX0351, detailed error meanings:
If the XML parser detects an error in the XML document during parsing, message RNX0351 will be issued.
From the message, you can get the specific error code associated with the error,
as well as the offset in the document where the error was discovered.
The following table shows the meaning of each parser error code:
||The parser found an invalid character while scanning white space outside element content.|
||The parser found an invalid start of a processing instruction, element, comment, or document type declaration outside element content.|
||The parser found a duplicate attribute name.|
||The parser found the markup character '<' in an attribute value.|
||The start and end tag names of an element did not match.|
||The parser found an invalid character in element content.|
||The parser found an invalid start of an element, comment, processing instruction, or CDATA section in element content.|
||- The parser found in element content the CDATA closing character sequence ']]>' without the matching opening character sequence '<![CDATA['.|
- A data element failed to be converted to a numeric value.
||The parser found an invalid character in a comment.|
||The parser found in a comment the character sequence '--' (two hyphens) not followed by '>'.|
||The parser found an invalid character in a processing instruction data segment.|
||A processing instruction target name was 'xml' in lowercase, uppercase or mixed case.|
||The parser found an invalid digit in a hexadecimal character reference (of the form �, for example ັ).|
||The parser found an invalid digit in a decimal character reference (of the form &#dddd;).|
||A character reference did not refer to a legal XML character.|
||The parser found an invalid character in an entity reference name.|
||The parser found an invalid character in an attribute value.|
||The parser found a possible invalid start of a document type declaration.|
||The parser found a second document type declaration.|
||An element name was not specified correctly. The first character was not a letter, '_', or ':', or the parser found an invalid character either in or following the element name.|
||An attribute was not specified correctly. The first character of the attribute name was not a letter, '_', or ':', or a character other than '=' was found following the attribute name, or one of the delimiters of the value was not correct, or an invalid character was found in or following the name.|
||An empty element tag was not terminated by a '>' following the '/'.|
||The element end tag was not specified correctly. The first character was not a letter, '_', or ':', or the tag was not terminated by '>'.|
||The parser found an invalid start of a comment or CDATA section in element content.|
||A processing instruction target name was not specified correctly. The first character of the processing instruction target name was not a letter, '_', or ':', or the parser found an invalid character in or following the processing instruction target name.|
||A processing instruction was not terminated by the closing character sequence '?>'.|
||The parser found an invalid character following '&' in a character reference or entity reference.|
||The version information was not present in the XML declaration.|
||The 'version' in the XML declaration was not specified correctly. 'version' was not followed by '=', or the value was missing or improperly delimited, or the value specified a bad character, or the start and end delimiters did not match, or the parser found an invalid character following the version information value closing delimiter in the XML declaration.|
||The parser found an invalid attribute instead of the optional encoding declaration in the XML declaration.|
||The encoding declaration value in the XML declaration was missing or incorrect. The value did not begin with lowercase or uppercase A through Z, or 'encoding' was not followed by '=', or the value was missing or improperly delimited or it specified a bad character, or the start and end delimiters did not match, or the parser found an invalid character following the closing delimiter.|
||The parser found an invalid attribute instead of the optional standalone declaration in the XML declaration.|
||The 'standalone' attribute in the XML declaration was not specified correctly. 'standalone' was not followed by a '=', or the value was either missing or improperly delimited, or the value was neither 'yes' nor 'no', or the value specified a bad character, or the start and end delimiters did not match, or the parser found an invalid character following the closing delimiter.|
||The XML declaration was not terminated by the proper character sequence '?>', or contained an invalid attribute.|
||The parser found the start of a document type declaration after the end of the root element.|
||The parser found the start of an element after the end of the root element.|
||The parser reached the end of the document before the document was complete.|
||The %HANDLER procedure for XML-INTO or XML-SAX returned a non-zero value, causing the XML parsing to end.|
||The parser does not support the requested CCSID value or the first character of the XML document was not '<'.|
||The document was too large for the parser to handle. The parser attempted to parse the incomplete document, but the data at the end of the document was necessary for the parsing to complete.|
||Internal error in the external parser. Please report the error to your service representative.|
||Internal error in the parser. Please report the error to your service representative.|