In this page we are going to deal with a case where
- We want to input to command XMLPARSE a XML stream file fitting its specific requirement:
- data element names ("XML fields") compatible with IBM i database field name rules (10 char max, alphanumeric, etc.)
- We are unluckily missing a database file - with field names the same as the XML stmf - for receiving the XML data via command XMLPARSE.
To create such a receiving database file we will use command CRTTODBF.
In the next example we assume that the XML file is /tmp/mybooks.xml, which looks as follow:
<?xml version="1.0"?>
<catalog>
<book id="bk101">
<bkauthor>Gambardella, Matthew</bkauthor>
<bktitle>XML Developer's Guide</bktitle>
<bkgenre>Computer</bkgenre>
<price>44.95</price>
<bkpubdate>2000-10-01</bkpubdate>
<bkdescr>An in-depth look at creating applications
with XML.</bkdescr>
</book>
<book id="bk102">
<bkauthor>Ralls, Kim</bkauthor>
<bktitle>Midnight Rain</bktitle>
<bkgenre>Fantasy</bkgenre>
<bkprice>5.95</bkprice>
<bkpubdate>2000-12-16</bkpubdate>
<bkdescr>A former architect battles corporate zombies,
an evil sorceress, and her own childhood to become queen
of the world.</bkdescr>
</book>
</catalog>
|
|
Figure 1 - Our sample XML stream file XML field names look like this |
The name of the data base file - to be created with the same field names as the XML stream file - is QGPL/BOOKS.
This is how we use command CRTTODFB:
Create "TO" database file (CRTTODBF)
Type choices, press Enter.
Input XML stream file . . . . . STMFIN > '/tmp/mybooks.xml'
Path to the XML elements . . . . XMLPTH *AUTO
Number of segments in XMLPTH . . XMLPTHNBR 2 1-99
"TO" database file . . . . . . . TODBF > BOOKS Name
library . . . . . . . . . . . > QGPL Name
DDS source file . . . . . . . . DDSSRC QDDSSRC Name
library . . . . . . . . . . . QTEMP Name
Edit the DDS for the "TO" dbf . EDTDDS > *YES *YES, *NO
Display FFD of the "TO" dbf . . DSPFFD > *YES *YES, *NO
|
|
Figure 2 - Command CRTTODBF |
Try it:
CRTTODBF STMFIN('/tmp/mybooks.xml') TODBF(QGPL/BOOKS)
EDTDDS(*YES) DSPFFD(*YES) |
- Input XML stream file (STMFIN):
Path and name of the XML stream file with data element ("field") used to create the "TO" database file.
This is the same XML stream file that will later on used as input to command XMLPARSE.
Restriction: the size of this file cannot exceed 15 Mb.
- Path to the XML elements (XMLPTH):
See the explanations given for this same parameter in command XMLPARSE.
If a path (instead of *AUTO) is specified, some attention should be payed, as the path (example: Roset/Row)
is case sensitive and must perfectly match the corresponding HTML tags.
- Number of segments in XMLPTH (XMLPTHNBR):
See the explanations given for this same parameter in command XMLPARSE.
- "TO" database file (TODBF):
The data base file to be created (this is the database file that later on will be uploaded with the XML data from command XMLPARSE).
- DDS source file (DDSSRC):
whether the DDS generated from the program for creating the "TO" database file should be edited before the database file is created.
- Edit the DDS for the "TO" dbf (EDTDDS):
Whether the DDS for creating the "TO" database file should be edited before it is created.
In this way you could
- Add file level keywords
- Add or change field level keywords
- (Re)define key fields
If you perform one of the following operations:
- Remove some fields
- Add new fields
- Rename field names
then in command XMLPARSE and in command SUPERPARSE you must specify parameters ALWMISSING(*YES) and ALWEXTRA(*YES),
otherwise the parsing would fail with error code 00353 - XML document does not match RPG variable.
If you change some field attribute (such as length, data type or decimal precision), the next time you run command CRTTODBF or SUPERPARSE for the same target database file,
you will get (in Figure 4) the previously saved attributes and you will have to change them for good.
- Display FFD of the "TO" dbf (DSPFFD):
Whether the field descriptions of the database file should be displayed following its generation.
The following screen shows up:
CRTTODBF - Create the "TO" database file
XML stmf . . . /tmp/mybooks.xml
Database file . . QGPL/BOOKS
Rcdfmt name . . . DFTRCD
Complete field definitions and press F13 to create the "TO" database file.
Data Decimal
Field Name Length Type Positions Text Description
BKID 0
BKAUTHOR 0
BKTITLE 0
BKGENRE 0
BKPRICE 0
BKPUBDATE 0
BKDESCR 0
Bottom
F3=End F12=Previous F13=Create database file
|
|
Figure 3 - CRTTODBF screen |
In this screen you should:
- Change, if you wish, the recotf format name of the "TO" database file (a DFTRCD record format name is initially provided.
- For each data base field (their names are in column Field Name) you should specify the following properties:
- data type
- length (if supported; as an example, data type "L" (date) requires no length)
- decimal positions (only for data type S-zoned, P-packed, B-Binary, F-Floating Point)
- text description value (optional).
Help text is available for these columns. Error messages are used to flag wrong properties.
See the following example:
CRTTODBF - Create the "TO" database file
XML stmf . . . /tmp/mybooks.xml
Database file . . QGPL/BOOKS
Rcdfmt name . . . BOOKRCD
Complete field definitions and press F13 to create the "TO" database file.
Data Decimal
Field Name Length Type Positions Text Description
BKID 5 A 0 Identifier
BKAUTHOR 30 A 0 Author
BKTITLE 50 A 0 Title
BKGENRE 15 A 0 Genre
BKPRICE 5 S 2 Price
BKPUBDATE L 0 Date published
BKDESCR 500 A 0 Description
Bottom
F3=End F12=Previous F13=Create database file
|
|
Figure 4 - CRTTODBF screen filled in |
Create the "TO" database file (example: QGPL/BOOKS) by pressing F13.
If requested (though command parameters EDTDDS and DSPFFD) the DDS of the file are browsed before its creation and its fields descriptions are shown after file creation.
See figures 5 and 6.
Columns . . . : 1 80 Edit
SEU==>
FMT PF .....A..........T.Name++++++RLen++TDpB......Functions+++++++++++++++++++++++++++
*************** Beginning of data **********************************************************
0001.00 A R BOOKRCD 000000
0002.00 A BKID 5A 000000
0003.00 A TEXT('Identifier') 000000
0004.00 A BKAUTHOR 30A 000000
0005.00 A TEXT('Author') 000000
0006.00 A BKTITLE 50A 000000
0007.00 A TEXT('Title') 000000
0008.00 A BKGENRE 15A 000000
0009.00 A TEXT('Genre') 000000
0010.00 A BKPRICE 5P 2 000000
0011.00 A TEXT('Price') 000000
0012.00 A BKPUBDATE L 000000
0013.00 A TEXT('Publication date') 000000
0014.00 A BKDESCR 500A 000000
0015.00 A TEXT('Description') 000000
0016.00 A K BKID 000000
****************** End of data *************************************************************
|
|
Figure 5 - DDS for "TO" dbf creation |
You may:
- Add file level keywords
- Add or change field level keywords
- (Re)define key fields
If you perform one of the following operations:
- Remove some fields
- Add new fields
- Rename field names
then in command XMLPARSE and in command SUPERPARSE you must specify parameters ALWMISSING(*YES) and ALWEXTRA(*YES),
otherwise the parsing would fail with error code 00353 - XML document does not match RPG variable.
If you change some field attribute (such as length, data type or decimal precision), the next time you run command CRTTODBF or SUPERPARSE for the same target database file,
you will get (in Figure 4) the previously saved attributes and you will have to change them for good.
Display Spooled File
File . . . . . : QPDSPFFD
Control . . . . .
Find . . . . . .
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+....9
Display File Field Description
Input parameters
File . . . . . . . . . . . . . . . . . . . : BOOKS
Library . . . . . . . . . . . . . . . . . : QGPL
File Information
File . . . . . . . . . . . . . . . . . . . : BOOKS
Library . . . . . . . . . . . . . . . . . : QGPL
File location . . . . . . . . . . . . . . . : *LCL
Externally described . . . . . . . . . . . : Yes
Number of record formats . . . . . . . . . : 1
Type of file . . . . . . . . . . . . . . . : Physical
File creation date . . . . . . . . . . . . : 09/19/16
Text 'description'. . . . . . . . . . . . . : Created by command EZ4PARSE/CRTTODBF
Record Format Information
Record format . . . . . . . . . . . . . . . : BOOKRCD
Format level identifier . . . . . . . . . . : 55C01489B19AE
Number of fields . . . . . . . . . . . . . : 7
Record length . . . . . . . . . . . . . . . : 613
Field Level Information
Data Field Buffer Buffer Field Column
Field Type Length Length Position Usage Heading
BKID CHAR 5 5 1 Both BKID
Field text . . . . . . . . . . . . . . . : Identifier
Coded Character Set Identifier . . . . . : 37
BKAUTHOR CHAR 30 30 6 Both BKAUTHOR
Field text . . . . . . . . . . . . . . . : Author
Coded Character Set Identifier . . . . . : 37
BKTITLE CHAR 50 50 36 Both BKTITLE
Field text . . . . . . . . . . . . . . . : Title
Coded Character Set Identifier . . . . . : 37
BKGENRE CHAR 15 15 86 Both BKGENRE
Field text . . . . . . . . . . . . . . . : Genre
Coded Character Set Identifier . . . . . : 37
BKPRICE PACKED 5 2 3 101 Both BKPRICE
Field text . . . . . . . . . . . . . . . : Price
BKPUBDATE DATE 10 10 104 Both BKPUBDATE
Field text . . . . . . . . . . . . . . . : Publication date
Date Format . . . . . . . . . . . . . . . : *ISO
Coded Character Set Identifier . . . . . : 37
BKDESCR CHAR 500 500 114 Both BKDESCR
Field text . . . . . . . . . . . . . . . : Description
Coded Character Set Identifier . . . . . : 37
|
|
Figure 6 - Field descriptions of "TO" database file |
As you now have database file QGPL/BOOKS with field names matching the field names
of stream file /tmp/mybooks.xml,
you can safely use command XMLPARSE to upload the XML data to the database file:
Parse a XML stream file (XMLPARSE)
Type choices, press Enter.
XML stream file . . . . . . . . STMF > /tmp/mybooks.xml
Path to the XML elements . . . . XMLPTH *AUTO
Number of segments in XMLPTH . . XMLPTHNBR 2 1-99
Target database file . . . . . . TOFILE BOOKS Name
library . . . . . . . . . . . QGPL Name, *LIBL, *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
Bottom |
|
Figure 7 - Running command XMLPARSE |
Press Enter and you get this:
> XMLPARSE STMF('/tmp/books.xml') TOFILE(QGPL/BOOKS)
--- Program XLPARSE started.
XML parser program PARSERPGM created in library QTEMP.
12 records loaded to file QGPL/BOOKS, member BOOKS.
--- Program XLPARSE successfully completed. |
|
Figure 8 - Well done! |
Special note
The utility maintains some memory, for some time, of the field properties entered (Figure 4).
Therefore it should be no surprise if it - in Figure 3 - returns the field properties the user entered the last time the same "TO" database file was created.
|