RPG Does XML! New Language Features in V5R4

Transcription

1 RPG Does XML! New Language Features in V5R4 Common Europe Congress 2007 Jon Paris Partner400.com SystemiDeveloper.com Your Partner in System i Education This presentation may contain small code examples that are furnished as simple examples to provide an illustration. These examples have not been thoroughly tested under all conditions. We therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. All code examples contained herein are provided to you "as is". THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED. The authors, Jon Paris and Susan Gantner, are co-founders of Partner400, a firm specializing in customized education and mentoring services for AS/400 and iseries developers. After individual careers with IBM, including workimg at both the Rochester and Toronto laboratories, Jon and Susan are now devoted to educating developers on techniques and technologies to extend and modernize their applications and development environments. Jon and Susan author regular technical articles for the IBM publication, IBM Systems Magazine, i5 edition, and the companion electronic newsletter, iseries Extra. You may view articles in current and past issues and/or subscribe to the free newsletter at: Feel free to contact the authors at: partner400.com or visit the Partner400 web site at Partner400, RPG Does XML - V5R4 Language Features - Page: 1-2

2 Agenda New Op-codes XML-INTO XML-SAX ** New BIFs %XML( ) %HANDLER ( ) ** If we have time Basic Syntax - XML-INTO variable XML-INTO { ( E H ) } variable %XML (... ) E extender allows you to handle errors via testing of %Error H extender controls half-adjust during assignment of numeric values variable is the target for the operation It can be a field, an array, a Data Structure or a Data Structure array If assignment is to a numeric field, the rules of %DEC conversion etc. apply %XML(...) this BIF identifies the XML document It is also used to supply processing options For example when the XML document is contained within a file in the IFS Matching is based on names The hierarchy of the name(s) of the elements and attributes in the XML are matched with that of the variable parameter XML-INTO recordcount %XML(XML_Input1: 'path=customers case=any'); Partner400, RPG Does XML - V5R4 Language Features - Page: 3-4

3 %XML BIF Details The %XML BIF is used with both XML-INTO and XML-SAX Syntax: %XML ( xml_document : options ) xml_document - Identifies the source of the XML By default the XML is contained within the named variable If option 'doc=file' is specified then the variable contains the name of the IFS file which contains the XML document options - Controls the processing of the XML stream Format is optionname1=value1 optionname2=value2 No space allowed between the option name and the equal sign Or between the equal sign and the value Options can be specified in any case. e.g. doc=file or DOC=FILE or Doc=File Can be a literal string, a named constant or a character variable We will look at some of the options as we use them XML Used in Examples 1, 2, and 3 This is the XML data that will be used in our initial examples Although very few of the XML documents you see will be this simple! There is a single instance of the RecordCount element Followed by multiple Company name elements This data is stored in variable XML_Input1 And in the IFS file /partner400/xml_input1.xml <Customers> <RecordCount> 6 </RecordCount> <Company>Phones R Us</Company> <Company>Suchadeal Bank</Company> <Company>Rinky Dinky Toy Co.</Company> <Company>Partner400</Company> <Company>BlackHole Navigation</Company> <Company>Banker's Trust</Company> </Customers> Partner400, RPG Does XML - V5R4 Language Features - Page: 5-6

4 XML-INTO - Example 1 - Fill a Variable Extract the value of a single element Two %XML options are used case=any Deals with the fact that our XML document contains mixed-case names path=customers/recordcount Directs the XML parser to the correct starting point // XML looks like this: // <Customers> // <RecordCount> 6 </RecordCount> D recordcount S 5p 0 /Free dsply ('Record Count before = ' + %Char(recordCount)); XML-INTO recordcount %XML(XML_Input1: 'path=customers/recordcount + case=any'); dsply ('Record Count after = ' + %Char(recordCount)); XML-INTO - Example 2 - Fill an Array Extracting into an array Note that xmlelements is a new field added to the PSDS It contains the number of elements loaded into the array 'path=... ' is not needed as the "shape" of the customers DS matches the XML document i.e. <Customers><Company>...</Company><Company> d customers DS d company 32a Dim(99) D progstatus SDS D xmlelements 20i 0 Overlay(progStatus: 372) d i s 10i 0 /Free XML-INTO company %XML(XML_Input1: 'case=any' ); dsply ( %Char(xmlElements) + ' elements loaded' ); for i = 1 to xmlelements; dsply company(i); endfor; Results 6 elements loaded Phones R Us Suchadeal Bank Rinky Dinky Toy Co. Partner400 BlackHole Navigation Bankers Trust Partner400, RPG Does XML - V5R4 Language Features - Page: 7-8

5 XML-INTO - Example 2A - XML in IFS This is the same basic example as the previous one But it demonstrates how to handle an XML document that is in the IFS The option 'doc=file' informs the compiler that the variable XML_Input contains the name of the XML file Not the actual XML data as it did before d customers DS d company 32a Dim(99) D progstatus SDS D xmlelements 20i 0 Overlay(progStatus: 372) d XML_Input s 256a Varying d Inz('/Partner400/XML_Input1.xml') /Free XML-INTO company %XML(XML_Input: 'case=any doc=file' ); XML-INTO using %HANDLER XML-INTO { ( E H ) } %HANDLER (... ) %XML (... ) Use this version when the XML data exceeds RPG limits Either because the number of elements exceeds RPG's 32,767 Or because the size of the data exceeds the 64K named DS size limit You can also use this approach if you simply want to process the XML "in pieces" For example one order at a time The %HANDLER BIF Identifies the handling procedure It will be called as each "INTO" action is completed. It can then process the data in any way that you like Partner400, RPG Does XML - V5R4 Language Features - Page: 9-10

6 How the %Handler Process Operates This is a "call-back" process C functions such as qsort and bsearch use same approach XML-INTO (or -SAX) starts the process by calling the XML parser The parser notifies the handler when it has data ready to process The handler processes the data and returns control to the parser The parser returns to step 2 unless parsing is completed at which time... The parser returns control to the main-line RPG Main Line Code XML-INTO (or XML-SAX) %HANDLER identifes handling routine 1 RPG Handler Subprocedure Passes communications area Receives data passed to it by the parser Plus the original communications area 4 2 Parser processes XML document 3 %HANDLER BIF - XML-INTO Version %HANDLER ( prototype : communication_area) The first parameter names the prototype of the handling procedure This procedure will be called as each "INTO" action completes Handler's Parameter requirements are shown below Return value can be set non-zero to terminate the processing First parameter is the communications area Second is the area to be filled (i.e. the -INTO area) It must be an array - even if it only contains 1 element Third is the count of the number of array elements filled Highlighted keywords are required The communication area is any variable/array/ds that you would like to be passed to your handler Use it to communicate between your main program and the handler You might want to do this because the handler subprocedure may not be in the same program as the main line code and will be called indirectly d pr 10i 0 d commarea LikeDS(myCommArea) d company Like(companyName) Dim(4) Const d numelements 10u 0 Value Partner400, RPG Does XML - V5R4 Language Features - Page: 11-12

7 XML-INTO - Example 3 - %HANDLER This is similar to Example 2 but uses %Handler This allows us to process documents which exceed RPG's limitations e.g. The Number of array elements or size maximum size of an array or DS Each time the company array is filled the handler routine is called It will also be called to handle the final group of elements We will look at the Handler procedure on the next chart d HandleCompany PR 10i 0 d commarea 10i 0 d company 32a Dim(4) Const d numelements 10i 0 Value d customers DS d company 32a Dim(4) d count S 10i 0 Inz /Free XML-INTO %Handler( HandleCompany: count ) %XML(XML_Input1: 'path=customers/company case=any' ); dsply ('Processed ' + %char(count) + ' total elements'); Partner400, RPG Does XML - V5R4 Language Features - Page: 13-14

8 XML-INTO - Example 3 - The handler numelements contains the count of elements passed It will only be less than the maximum on the final call Comm Area is used to provide a total count of the p HandleCompany b elements processed d pi 10i 0 d count 10i 0 d company 32a Dim(4) Const d numelements 10i 0 Value d i s 10i 0 /Free for i = 1 to numelements; dsply company(i); endfor; // add current count to total in Comm Area and display current count count += numelements; dsply ( %Char(numElements) + ' elements loaded on this call' ); return 0; /End-Free p HandleCompany e Our sample XML contains 6 customer entries and the array we have defined handles 4 at a time. This is the result of running our example program against that XML stream. As you can see the field passed as the communications area has been used to keep a count of the total number of customers processed. DSPLY Phones R Us DSPLY Suchadeal Bank DSPLY Rinky Dinky Toy Co. DSPLY Partner400 DSPLY 4 elements loaded on this call DSPLY BlackHole Navigation DSPLY Bankers Trust DSPLY 2 elements loaded on this call DSPLY Processed 6 total elements Partner400, RPG Does XML - V5R4 Language Features - Page: 15-16

9 XML For Example 4 <Customers> <RecordCount> 25 </RecordCount> <Customer type="wholesale"> <Contact>John Jones</Contact> <Company>Phones R Us</Company> <Address> <Street>5678 High Street</Street> <City>Mytown</City> <State>GA</State> <Zip>30033</Zip> </Address> </Customer> <Customer type="retail"> <Contact>Meanold Miser</Contact> <Company>Suchadeal Bank</Company> <Address> <Street>91011 Important Ave.</Street> <City>Bankville</City> <State>MN</State> <Zip>55901</Zip> </Address> </Customer> </Customers> Example 4 - Compound Structure The nested Data Structures below map the shape of the XML Note that attributes of an element such as "type" are at the same level in the hierarchy as nested elements such as "Company" The recordcount is ignored in the first example More on how this is done in a moment D customers DS Qualified D recordcount 3p 0 D customer LikeDS(customer) Dim(99) D customer DS Qualified D type 10a D company 32a D discountcode 1a D address LikeDS(address) D address DS D street 32a D city 24a D state 2a D zip 5s 0 Partner400, RPG Does XML - V5R4 Language Features - Page: 17-18

10 Example 4 - Program Logic First version uses the "path=... " option This steers the processing to the customer element But it will only process the first customer element in the XML Second does not need a path option - the DS maps the XML i.e. The DS "customers" contains the nested DS "customer" allowextra - XML can contain elements not included in the DS The XML element "Contact" allowmissing - DS can include fields not present in the XML The field "discountcode" in the customer DS XML-INTO customer %XML(XML_Input: 'path=customers/customer case=any + allowextra=yes allowmissing=yes'); XML-INTO customers %XML(XML_Input : 'case=any allowextra=yes + allowmissing=yes'); XML-SAX "SAX" stands for Simple API for XML But there's no such thing as a truly "Simple" example of SAX parsing So we will simply demonstrate the basic process of identifying events With XML-SAX the %HANDLER BIF must always be specified The parameters to the Handler routine are somewhat different though The return value and the Communications are the same The second parameter is a numeric value representing the event It can be compared with RPG IV Special Words such as *XML_ATTR_NAME The third is a pointer to the string containing the current token i.e. The attribute or element name, or data content The fourth is the length of that string Fifth contains an exception Id. when event *XML_EXCEPTION is signaled D myhandler Pr 10I 0 D commarea LikeDS(myCommArea) D event 10I 0 VALUE D pstring * VALUE D stringlen 20I 0 VALUE D exceptionid 10I 0 VALUE Partner400, RPG Does XML - V5R4 Language Features - Page: 19-20

11 XML-SAX Events These inlcude: *XML_START_DOCUMENT Indicates that parsing has begun *XML_START_ELEMENT The name of the XML element that is starting *XML_CHARS The value of the XML element *XML_END_ELEMENT The name of the XML element that is ending *XML_ATTR_NAME The name of the attribute *XML_ATTR_CHARS The value of the attribute *XML_END_ATTR Indicates the end of the attribute *XML_END_DOCUMENT Indicates the end of the document XML-SAX Example As noted a simple SAX example is a contradiction So our example will simply demonstrate the basic mechanism We will use it to simply identify and count the different elements We will be building up an array of element names Plus a count of the number of Start of Element and End of Element events that we encounter. The Communications Area will be used to pass this information back to our main line program // Communications area definition d mycommarea ds d namecount 10i 0 d elementdata Dim(500) d name 64a Overlay(elementData) d startcount 10i 0 Overlay(elementData: *next) d endcount 10i 0 Overlay(elementData: *next) Partner400, RPG Does XML - V5R4 Language Features - Page: 21-22

12 XML-SAX Processing - Data Definition XML-SAX %Handler(MyHandler: mycommarea ) %XML( XML_Input ); for i = 1 to namecount; dsply ('Name = ' + %subst(name(i): 1: 40) ); dsply ('Counts = ' + %char(startcount(i)) + '/' + %char(endcount(i)) endfor;... // Handler procedure begins here P myhandler B D PI 10I 0 D commarea LikeDS(myCommArea) D event 10I 0 VALUE D pstring * VALUE D stringlen 20I 0 VALUE D exceptionid 10I 0 VALUE D string S 65535A Based(pString) D returncode S 10I 0 INZ(0) D name S 256a Varying D element s 10i 0 This is the display produced by the XML-SAX program when processing the sample XML document which contains two complete Customer entries. Note that the names are displayed at the end of the run, but appear in the sequence in which they are first encountered. A quick review of the XML will confirm this if you have any doubts. DSPLY Starting parse DSPLY Name = Customers DSPLY Counts = 1/1 DSPLY Name = RecordCount DSPLY Counts = 1/1 DSPLY Name = Customer DSPLY Name = Contact DSPLY Name = Company DSPLY Name = Address DSPLY Name = Street DSPLY Name = City DSPLY Name = State DSPLY Name = Zip Partner400, RPG Does XML - V5R4 Language Features - Page: 23-24

13 XML-SAX Processing - Handler Logic /free select; // Initialize communications area on start of document when event = *XML_START_DOCUMENT; clear commarea; // If this is an attribute name then add it to the list // if we haven't seen it already when event = *XML_START_ELEMENT or event = *XML_END_ELEMENT; name = %subst(string : 1 : stringlen); element = %lookup( name: commarea.name: 1: commarea.namecount ); if element = 0; commarea.namecount += 1; element = commarea.namecount; commarea.name( element ) = name; endif; if event = *XML_START_ELEMENT; commarea.startcount(element) += 1; else; commarea.endcount(element) += 1; EndIf; endsl; return returncode; Not on V5R4 & Need to Process XML? Write your own parser in RPG Cumbersome, but may be fun! Invoke Java Parser Methods from RPG using V5R1 support Several samples out on the web There are some non-ibm C and C++ based parsers available Scott Klement iseries port of the Expat C parser See ScottKlement.com for more details See Appendix for details of third party options IBM's XML Toolkit for RPG Provides API interfaces to IBM's C++ parser RPG APIs from the RPG-XML Suite V5R3: SAX Parser built into the ILE COBOL compiler V5R4: XML Generation - Coming to RPG in V5R5??? Partner400, RPG Does XML - V5R4 Language Features - Page: 25-26