• Personal tools
  • Log in
• • Main Page
• documentation
  • RPG-XML Suite
  • Krengel Ship for UPS
  • DB2 Web Service Enabler
  • All Products
• Toolbox
  • What links here
  • Related changes
  • Special pages

Included RXS Example Programs

From Wiki

User Guide

The install of RPG-XML Suite (RXS) includes examples using the various subprocedures in the RXSSV service program object. Look for them in the source physical file EXAMPLE in the library specified on the install program. If you used the suggestion in the readme.txt file instructions, that library is MYRXS.

The examples start demonstrating portions of the RPG-XML Suite’s set of APIs with smaller tasks like creating an XML file and placing it in the IFS. They move on to more complex tasks like offering a web service on your IBM i that parses XML, composes XML, transmits XML, and so forth.

The sample programs in MYRXS/EXAMPLE include more than just code snippets. The source comments explain the reasons for using the RXS functions in certain ways. If you have examined and tried out the MYRXS/EXAMPLE programs, you will have a better idea of the capabilities that RPG-XML Suite offers. In RXS v2.00, the DOM-based parser was introduced and a number of new examples have been added for that purpose (i.e. source members PARSE1 through PARSE4).

The other program in the EXAMPLE source physical file named DOORWAY is more complicated than its companions. It does not receive the request, parse the document, compose the response or send it from all within one program. Instead it shows how those functions might be farmed out to different subprocedures. DOORWAY has hard coded service program and subprocedure names. It could retrieve those names from a database instead. Calling a program based on a database value is common practice when using *PGM objects. It is not so common when invoking entry points to *SRVPGM objects because activating subprocedures with soft coded names requires more steps. The RXS_handOff subprocedure can handle that complexity for the programmer. HANDSOFFSV is the name of the program that DOORWAY calls. The interface (parameter list) is quite simple. It merely passes the name of the incoming XML file and the name of the file where the output should be sent. For simplicity’s sake, the code in HANDOFFFN uses static data to compose a file in the IFS. Normally the program would also contain data access and business logic or invoke other resources to provide them.

Example Programs

RXS1

This RPG Web Service program is very simple in nature. It is meant to show how to output information stored in the template file rxs1.tpl. You can find find the template file located at /www/rxs/templates/rxs1.tpl.

RXS2

Read in a URL variable and return it in the response XML. Passing variables on the URL is not a recommended approach, but is used in some cases and thus is included as an example here. Use the Web Service Tester (PC App) to invoke the web service.

RXS3

Read in XML and parse the PostAdr document. Store the values locally and respond with whether or not the processing was successful. Use the Web Service Tester (PC App) to invoke the web service.

RXS3B

This program is similar to RXS3 except that it writes the received XML values to a data base file. It will then build a response based on all of the current postal addresses in PF PSTADR. The purpose is to show how to write parsed data to a DB file and then compose XML by reading from a DB file. Use the Web Service Tester (PC App) to invoke the web service.

RXS3C

Performs the same functions as RXS3 but overrides the Template Engine's section and variable delimiter declarations. Also overrides the parser event handler types (i.e. element begin, element content, element end and attribute). This is useful if you are in a country other than the United States and thus have sensitivities to certain character translations. Use the Web Service Tester (PC App) to invoke the web service.

RXS4

Basic input/output XML web service complete with parsing and serializing. Call this web service with any XML document and it will parse it and compose a response XML document detailing the events that took place during the parsing. This web service doesn't really serve a business purpose and is more academic in nature so that you can learn about parser events. It is a useful generic way to determine what events are being triggered in a particular XML document obtained from another developer. Use the Web Service Tester (PC App) to invoke the web service.

RXS5

Returns XML document detailing how long processing takes along with the amount of data passed in. This is good to test how long some documents will take to read in, parse, and process. There is a 16MB limit of data that can be received with RXS_readToFile. This program doesn't really serve a business purpose and is more academic in nature to show some of the different things you can do to determine performance of a given XML document. Use the Web Service Tester (PC App) to invoke the web service.

TPLENG1

Compose an XML file based on template tpleng1.tpl and place it in the IFS. The tpleng1.tpl file doesn't need to be fully qualified because it is located in the default template directory. By default the template directory is set to /www/myrxs/templates. Defaults are stored in DB2 table MYRXS/RXSCFG.

TPLENG2

Similar to example TPLENG1 except the results aren't being written to the IFS and are instead being held in memory until RXS_getBuffData is used to obtain the XML. Use this approach when you are dealing with small amounts of XML (i.e. less than 65535 bytes). This approach is most often used in conjunction with RXS_getUri to send XML to a remote web service. See example GETURI2 to see this in action. The other difference is this program is obtaining the data from a DB2 PF to plug into the XML.

TPLENG3

Shows how to use multiple template files to build a single XML document. This is helpful if you have sections of repeated XML that you only want to keep in one place (i.e. SOAP envelopes).

GETURI1

Retrieve the contents of a webpage and display it in the job log. Note that this example is purely to show how to connect to another HTTP server and retrieve the contents of an index page. No composing of XML or parsing XML is taking place.

GETURI2

Compose a SOAP XML document to send to a web serivce hosted on http://www.w3schools.com. Use RXS_getUri to send the document to the web service making sure to specify all of the appropriate headers. Lastly, receive the response back from the web service and parse the document to obtain the end result data.

The web service is simple in concept in that it is passing in a Fahrenheit temperature and converting it to Celsius and returning that value to this program. This program also shows how to make use of RXS_ignElemNamSpc which is very useful when parsing SOAP XML documents.

GETURI3

Compose a simple XML stream for a non-SOAP web service transaction. It will call web service http://[yourIBMiIP]:8181/myrxs/rxs3 which is included in the base install of the RPG-XML Suite. Note the [yourIBMiIP] address will need to be changed to that of the machine where RPG-XML Suite was installed.

GETURI4

Compose a simple xml file for a non-SOAP web service transaction. It will call web service http://[yourIBMiIP]:8181/myrxs/rxs6 which is included in the base install of the RPG-XML Suite. Note the [yourIBMiIP] address will need to be changed to that of the machine where RPG-XML Suite was installed.

This program is the same as GETURI3 except it uses different values for the templating engine sections/variables and different event handler type values for the parser. It also uses IFS files to hold the XML vs. RPG variables/memory.

ERR1

This program shows how error handling API's in RPG-XML Suite operate - RXS_throwError and RXS_catchError.

The objective of this code is to call a local subprocedure named subproc1 and use RXS_throwError to generate an error on the program call stack. When RXS_throwError is called in subproc1 then control is immediately passed to the on-error clause in the mainline of the program. Once control is passed to on-error we can retrieve the error that occurred by calling RXS_catchError and placing the result in the RPG-XML Suite predefined data structure (i.e. the likeds(RXS_Error) D-spec). Once the error has been obtained and is placed in gErr you can display the error to the job log by accessing the subfields (i.e. gErr.code, gErr.severity, gErr.pgm, gErr.text)

PARSE1

Parse document <PostAdr> using the DOM-Based parser added in RXS v2.00, and place the results into gPostAdr data structure.

PARSE2

This program shows how to parse an XML structure that has multiple repeating sections (i.e. <component> and <lineItem> repeat). Pay close attention to how RXS_DOMGetData is used and how every other input parameter is an integer allowing you to specify which iteration of an element you are going after within a parents element. Uses the DOM-Based parser added in RXS v2.00.

PARSE3

This program shows how to make parsing long winded XML documents (i.e. XML with many parent-child relationships and/or long tag names) much easier. This is done using the using RXS_setXPath. Uses the DOM-Based parser added in RXS v2.00.

PARSE4

This program shows how to parse an XML document and focuses on how to ignore the namespace prefixes. Uses the DOM-Based parser added in RXS v2.00.

PARSE5

Process the XML using the event-based parser and place it into RPG variables. The event based parser is more performance minded because it incrementally streams/processes a document and issues events to your locally defined sub procedure (i.e. allHandler) vs. loading the entire document into memory.

PARSE6

Process an XML document using the event-based parser and place it into a DB2 phyical file.

PARSE7

Same as PARSE5 except a file in the IFS is going to be parsed vs. an RPG variables content. Before the file is parsed it is going to have the contents of the SOAP envelope decoded using RXS_soapDecode.

MIRROR

This application is useful when you want to return to the requester exactly what was sent. Sometimes this is a good tool for debugging purposes. The basic concept is to first make sure an existing mirror.xml file is deleted, then read the request to the mirror.xml (it will be created if it doesn't exist) and then respond with the contents of the XML that was originally read in.

DOORWAY

Think of this program as being a web service router. It allows you to dynamically call a service program's exported sub procedure. Normally this can only be done out of the box with *PGM objects. Note that the sub procedure being invoked must comply with the RXS_handOff prototype which can be found in RXSCp. This program takes care of reading in XML and pushing it back out. No parsing, no business logic, etc.