RPG Web Services

(click to open)

Quick Page Table of Contents

Scanning…

XMLSERVICE REST Web Services

XMLSERVICE Introduction

XMLSERVICE is Open Source RPG, created for web programming simplicity and deployment flexibility, any language, any transport, avoiding complexities dealing with big package ‘web services’. Internally, XMLSERVICE is designed Plain Old XML (POX), which enables simple REST XML protocol, avoiding complexity of SOAP/WSDL based Web Services. XMLSERVICE is 100% RPG, never requires Java, PHP, or any other front end language to serve your IBM i RPG programs to the web. In fact, XMLSERVICE is so simple, that you can almost run your entire IBM i machine using only simple HTML/XML (demonstrated later section).

XMLSERVICE
XMLSERVICE is a single library of Open Source RPG code that enables XML scripting calls of System i resources

XMLSERVICE RPG source download found at Yips XMLSERVICE.

XMLSERVICE introduction foils and working examples Yips XMLSERVICE Introduction

XMLSERVICE RPG server library does not require other language products to run on your IBM i, however language teams often provide a client toolkit to greatly simplify XML calls to XMLSERVICE.


XMLSERVICE, as name implies, enables XML services on your IBM i machine. XMLSERVICE library is simply a collection of Open Source RPG modules that essentially allow your to access anything on your IBM i machine, assuming proper profile authority. Simply stated, XMLSERVICE accepts XML document containing actions/parameters (<pgm>,<cmd>,<sh>,<sql>,etc.), performs requested operations on IBM i, then sends an XML document of results back to the client. This simple concept has become a powerful tool for scripting language clients on IBM i including Zend Server PHP Toolkit and PowerRuby Toolkit. However, PHP and Ruby are not unique to XMLSERVICE, XML is a universal protocol support by nearly every language, therefore nearly any language can use XMLSERVICE, and most any transport between client/server.

Installation

Installation of XMLSERVICE Open Source is trivial for any IBM i person.

> Unzip xmlservice-rpg.zip to xmlservice.savf 
> crtSAVF FILE(QGPL/XMLSERVICE)
> FTP xmlservice.savf to QGPL/XMLSERVICE (binary FTP)
> RSTLIB SAVLIB(XMLSERVICE) DEV(*SAVF) SAVF(QGPL/XMLSERVICE) MBROPT(*ALL) ALWOBJDIF(*ALL)
> ADDLIBLE XMLSERVICE
XMLSERVICE: test library XMLSERVICE, good for trying new versions
> CRTCLPGM PGM(XMLSERVICE/CRTXML) SRCFILE(XMLSERVICE/QCLSRC)
> call crtxml -- XMLSERVICE library only
> CHGAUT OBJ('/qsys.lib/XMLSERVICE.lib') USER(QTMHHTTP) DTAAUT(*RWX) OBJAUT(*ALL) SUBTREE(*ALL)
Note: Other CLP exist for other team production libraries.
      XMLSERVICE PGM objects are coded to compile library only,
      therefore you cannot SAV/RST PGM, etc. to other libraries. 

IBM PTFs

IBM i traditionalists comfortable with ‘supported software’ as no compile required, may choose IBM i PTFs to avoid download/compile of XMLSERVICE. However, xmlservice source code, tests (ZZCALL), non-production goodies, are not included with IBM i PTFs (size restrictions), therefore, i suggest download matching zip file version for tests and other non-production goodies referenced in this narrative.

V7R1 PTF SI50835 (1.8.1) replaces V7R1 PTF SI48830 (1.7.5)
V6R1 PTF SI50834 (1.8.1) replaces V6R1 PTF SI48831 (1.7.5)
V5R4 PTF SI48440 (1.7.5) no additional PTFs planned

Note: IBM PTF library is QXMLSERV (not XMLSERVICE library).

REST interface

Optional: Set up your Apache to enable XMLSERVICE REST using RPG program XMLCGI.PGM included in XMLSERVICE installation, then restart your Apache instance.

/www/apachedft/conf/httpd.conf:
ScriptAlias /cgi-bin/ /QSYS.LIB/XMLSERVICE.LIB/
<Directory /QSYS.LIB/XMLSERVICE.LIB/>
  AllowOverride None
  order allow,deny
  allow from all
  SetHandler cgi-script
  Options +ExecCGI
</Directory>

stop/start Apache instance:
endTCPSVR SERVER(*HTTP) HTTPSVR(APACHEDFT)
STRTCPSVR SERVER(*HTTP) HTTPSVR(APACHEDFT)

test programs

Optional: To compile XMLSERVICE library test programs.

> CRTCLPGM PGM(XMLSERVICE/CRTTEST) SRCFILE(XMLSERVICE/QCLSRC) 
> call crttest
-- V6+ added tests --
> CRTCLPGM PGM(XMLSERVICE/CRTTEST6) SRCFILE(XMLSERVICE/QCLSRC) 
> call crttest6
> CHGAUT OBJ('/qsys.lib/XMLSERVICE.lib') USER(QTMHHTTP) DTAAUT(*RWX) OBJAUT(*ALL) SUBTREE(*ALL)
  • ZZCALL.PGM - XMLSERVICE language examples in this documentation will be calling this ordinary RPG program included with XMLSERVICE download (ZZCALL.PGM).
         H AlwNull(*UsrCtl)
    
         D Step            s             10i 0 inz(0)
    
         D  INCHARA        S              1a
         D  INCHARB        S              1a
         D  INDEC1         S              7p 4        
         D  INDEC2         S             12p 2
         D  INDS1          DS                  
         D   DSCHARA                      1a
         D   DSCHARB                      1a           
         D   DSDEC1                       7p 4      
         D   DSDEC2                      12p 2            
          *+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
          * main(): Control flow
          *+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
         C     *Entry        PLIST                   
         C                   PARM                    INCHARA
         C                   PARM                    INCHARB
         C                   PARM                    INDEC1
         C                   PARM                    INDEC2
         C                   PARM                    INDS1
          /free
            Step +=1;
            INCHARA = 'C';
            INCHARB = 'D';
            INDEC1 = 321.1234;
            INDEC2 = 1234567890.12;
            DSCHARA = 'E';
            DSCHARB = 'F';
            DSDEC1 = 333.333;
            DSDEC2 = 4444444444.44;
            return;
            // *inlr = *on;
          /end-free
    

Operation and transports

XMLSERVICE XML documents can be transported between IBM i and clients over any connection, any language.

XMLSERVICE

XMLSERVICE APIs (included)

XMLSERVICE library includes language transports for popular REST and DB2 connections, which fulfills needs for most internet services applications.

  • XMLSERVICE/XMLCGI.PGM— RPG CGI HTTP/REST method GET or POST (traditional web service interface)
    • http://myibmi/cgi-bin/xmlcgi.pgm?db2=x@uid=x@pwd=x@ipc=x@ctl=x@xmlin=x@xmlout=x
  • XMLSERVICE/XMLSTOREDP.SRVPGM — RPG DB2 stored procedure (IBM i’s premier DB2 for i)
    • DB2 drivers local/remote with stored procedure IN/OUT capabilities (traditional DB2 interface)
       
      iPLUG4K  (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CHAR(4064),  OUT XMLOUT CHAR(4064))
      iPLUG32K (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(32000), OUT XMLOUT CLOB(32000)) 
      iPLUG65K (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(65K),   OUT XMLOUT CLOB(65K)) 
      iPLUG512K(IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(512K),  OUT XMLOUT CLOB(512K)) 
      iPLUG1M  (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(1M),    OUT XMLOUT CLOB(1M)) 
      iPLUG5M  (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(5M),    OUT XMLOUT CLOB(5M)) 
      iPLUG10M (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(10M),   OUT XMLOUT CLOB(10M)) 
      iPLUG15M (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(15M),   OUT XMLOUT CLOB(15M))
      
    • DB2 drivers local/remote without stored procedure IN/OUT capabilities (loop fetch required)
      iPLUGR4K  (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CHAR(4064))
      iPLUGR32K (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(32000)) 
      iPLUGR65K (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(65K)) 
      iPLUGR512K(IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(512K)) 
      iPLUGR1M  (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(1M)) 
      iPLUGR5M  (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(5M)) 
      iPLUGR10M (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(10M)) 
      iPLUGR15M (IN IPC CHAR(1024), IN CTL CHAR(1024), IN XMLIN CLOB(15M))
      
  • XMLSERVICE/XMLSTOREDP.SRVPGM — optional custom transport (programmers only)
    • if included XMLSERVICE transports do not fill your need, please feel free to create your own (sockets, data queues, ftp, etc.). Multiple entry APIs exist in XMLSERVICE that you may find useful:
      xmlstoredp.srvpgm - *SRVPGM interface for calls
      
        Native stored procedure call target (iPLUG4K - iPLUG15M):
           D iPLUG4K         PR             1N   extproc(*CL:'iPLUG4K')
           D pIPC                        1024A
           D pCtl                        1024A
           D pXmlIn                          *
           D pXmlOut                         *
      
         RPG call target:
           D runClient       PR             1N
           D   pIPCSP                    1024A
           D   pCtl                      1024A
           D   pIClob                        *
           D   szIClob                     10i 0
           D   pOClob                        *
           D   szOClob                     10i 0
      
         PASE call target (also use RPG when CCSID issues):
           D runASCII        PR             1N
           D   pIPCSP2                       *
           D   szIPCSP2                    10i 0
           D   pCtlSP2                       *
           D   szCtlSP2                    10i 0
           D   pIClob2                       *
           D   szIClob2                    10i 0
           D   pOClob2                       *
           D   szOClob2                    10i 0
           D   ccsidPASE2                  10i 0
           D   ccsidILE2                   10i 0
      
      

IBM i CCSID 65535

XMLSERVICE REST and DB2 connections have implicit CCSID conversion between client and server, therefore your XMLIN/XMLOUT XML document will be implicitly CCSID converted by the transport layer, to wit, XMLSERVICE should just work. However, IBM i CCSID 65535 (hex), will destroy the entire XMLSERVICE scheme, and you will witness horrible hangs, junk data, dead processes, etc., so please take action on your IBM i to live with the modern ASCII world (all clients, all new scripting languages, remote/local including PASE).

Check your IBM i for CCSID convert safety.
If you see DSPSYSVAL 65535, you have a big problem with the ASCII world, but you can take corrective IBM i action.

DSPSYSVAL SYSVAL(QCCSID)
 Coded character set
   identifier . . . . . :   65535      1-65535

Here are some corrective IBM i suggestions (CCSID 37 an example), but remember you have to end current running jobs and restart for the CCSID changes to enable (including XTOOLKIT jobs):

  • change system ccsid
    CHGSYSVAL SYSVAL(QCCSID) VALUE(37)
    
  • change Apache instances (/www/instance/httpd.conf)
    # protect FastCGI against bad CCSID (dspsysval qccsid 65535)
    DefaultFsCCSID 37
    CGIJobCCSID 37
    
  • change user profile(s)
    CHGUSRPRF USRPRF(FRED) CCSID(37)
    

Connection public or private

XMLSERVICE parameters CTL and IPC enable two types of connections.

  • public connection — XMLSERVICE stateless, many jobs, every use a fresh start
    • CTL='*here' , IPC="*NA"
      • “public” because any IBM i profile use is a fresh start
      • life scope — life of a single XML IN/OUT request
  • private connection — XMLSERVICE state full, single job, where a given profile is routed to XTOOLKIT job(s)
    • CTL='*sbmjob' , IPC="/tmp/myjob1"
      • CTL='*sbmjob' — if not running, submit a new XTOOLKIT job
      • IPC="/tmp/myjob1" — all requests of IPC route to XTOOLKIT job (*sbmjob)
      • “private” because ONE IBM i profile owns XTOOLKIT job, any other IBM i profile will fail to attach
      • life scope — forever, until ended by operator or user program ends XTOOLKIT job (like a 5250)

When to use XMLSERVICE public or private?
Of course any discussion that presumes to predict usage is likely to have legitimate user exception, but a guideline may be appropriate for use of XMLSERVICE public vs. private connection.

Web programming style (public, stateless)
XMLSERVICE public connections are generally used when IBM i resource can be called once by many different user profiles, current data returned, no lasting persistent data needed by the IBM i resource. The programmer meta description of transient resource services is “stateless programming”.

XMLSERVICE
XMLSERVICE public “stateless”
(CTL=‘*here’, IPC=‘*NA’)
- profile FRED (any public QSQ)
- profile SALLY (any public QSQ)
- profile RITA (any public QSQ)
- profile XAVIER (any public QSQ)

XMLSTOREDP→XMLSERVICE (QSQ)

- QSQ temporary profile use (stateless)
- QSQ return to pool on script end
- XMLSERVICE restart every request (web style)
Although very handy, clean wrkactjob, no hanging locks, etc., public connection is not a high performance use of XMLSERVICE.

  • public connection — XMLSERVICE stateless, many jobs, every use a fresh start
    • CTL='*here' , IPC="*NA" — profile FRED (RPG company stock service)
    • CTL='*here' , IPC="*NA" — profile SALLY (RPG IRS flat tax rate service)
    • CTL='*here' , IPC="*NA" — profile RITA (RPG calculate pound to kilo)
    • CTL='*here' , IPC="*NA" — profile XAVIER (RPG company stock service)

Traditional programming style (private, state full)
XMLSERVICE private connections are generally used when IBM i resource will be called many times by the same user profile, lasting persistent data needed by the IBM i resource (RPG variables, open files, etc.). The programmer meta description of required data services is “state full programming”.

XMLSERVICE
XMLSERVICE private “state full”
(CTL=‘*sbmjob’, IPC=‘/tmp/xxxx’)
- profile FRED XTOOLKIT myjob1,myjob2 (private)
- profile SALLY XTOOLKIT sallyjob1 (private)
- profile RITA XTOOLKIT nursejob (private)
- profile XAVIER XTOOLKIT xjob1 - xjob5 (private)

XMLSTOREDP (QSQ)
- QSQ temporary profile use (stateless)
- QSQ return to pool on script end

XMLSERVICE (XTOOLKIT)
- XTOOLKIT owned by profile (private)
- XTOOLKIT job never ends (until killed)
- XTOOLKIT full state programming (5250 style)


Traditional RPG programs usually need to track local variables, open files, etc., between requests, both for correct functionality and performance. The XTOOLKIT jobs that result from CTL='*sbmjob' , IPC="/tmp/xxxx" are similar to 5250 jobs, where a user profile signs on, then uses 5250 job to run other programs (aka XMLSERVICE design), also, like multiple 5250 sessions (PC emulators), many different XTOOLKIT jobs can be used by the same user profile.

  • private connection — XMLSERVICE state full, single job, where a given profile is routed to same XTOOLKIT job
    • CTL='*sbmjob' , IPC="/tmp/myjob1" — profile FRED XTOOLKIT myjob1 (Fred’s use only RPG payroll application)
    • CTL='*sbmjob' , IPC="/tmp/myjob2" — profile FRED XTOOLKIT myjob2 (Fred’s use only RPG inventory application)
    • CTL='*sbmjob' , IPC="/tmp/sallyjob1" — profile SALLY XTOOLKIT sallyjob1 (Sally’s use only RPG admissions application)
    • CTL='*sbmjob' , IPC="/tmp/nursejob" — profile RITA XTOOLKIT nursejob (Rita’s use only RPG nurse scheduling application)
    • CTL='*sbmjob' , IPC="/tmp/xjob1" — profile XAVIER XTOOLKIT xjob1 (Xavier’s use only RPG payroll application)
    • CTL='*sbmjob' , IPC="/tmp/xjob2" — profile XAVIER XTOOLKIT xjob2 (Xavier’s use only RPG inventory application)
    • CTL='*sbmjob' , IPC="/tmp/xjob3" — profile XAVIER XTOOLKIT xjob3 (Xavier’s use only RPG admissions application)
    • CTL='*sbmjob' , IPC="/tmp/xjob4" — profile XAVIER XTOOLKIT xjob4 (Xavier’s use only RPG nurse scheduling application)
    • CTL='*sbmjob' , IPC="/tmp/xjob5" — profile XAVIER XTOOLKIT xjob5 (Xavier’s use only RPG super hero application)
    • IBM i programmer: Profile Xavier is using many XTOOLKIT jobs (xjob1 - xjob5), many different applications, but Xavier cannot use Fred’s, Sally’s or Rita’s XTOOLKIT jobs (myjob1,myjob2,sallyjob1,nursejob), because Xavier does not own other profile XTOOLKIT jobs. XTOOLKIT jobs should be an easy pattern for RPG programmers familiar with single session 5250 job(s), owned by a profile, one thing at a time (not threaded), long running RPG programs, many IBM i files open, etc.
      • However, XTOOLKIT jobs have an interesting characteristic that 5250 emulator jobs cannot match, profile owned XTOOLKIT jobs can be accessed by many different client devices all at the same time, to wit, Xavier can use a laptop and a smart phone to all jobs at the same time (xjob1 - xjob5), or Xavier can leave his work laptop running (connected), go home, have dinner, and continue working all XTOOLKIT jobs from the family iPAD.
    • IBM i operator: You may wrkactjob and kill *immed XTOOLKIT jobs (same as 5250).
      • However, an ipcs administrative cleaner solution may suggest you write a custom XMLSERVICE program CTL='*immed' , IPC="/tmp/myjob1", to remove “in the way” XTOOLKIT jobs (suggestion only).

Open Source goal

XMLSERVICE is constantly growing Open Source, so new functions are added over time. XMLSERVICE goal is never impact existing applications with new features, to date, XML’s natural ability to add keywords and attributes has been very successful in keeping this goal. XMLSERVICE XML reserved keywords can be found at Yips XMLSERVICE Quick, but here is a summary tour.

XMLSERVICE CMDs

<?xml version='1.0'?>
<script>
<cmd exec='rexx'>RTVJOBA USRLIBL(?) SYSLIBL(?)</cmd>
<cmd>DLTDTAQ DTAQ(MYLIB/MYDATAQ)</cmd>
<cmd>CRTDTAQ DTAQ(MYLIB/MYDATAQ) MAXLEN(100) AUT(*EXCLUDE)</cmd>
</script>

XMLSERVICE PASE

<?xml version='1.0'?>
<script>
<sh rows='on'>/QOpenSys/usr/bin/ls -l /tmp</sh>
<sh rows='on'>/QOpenSys/usr/bin/system -i 'wrkactjob'</sh>
</script>

XMLSERVICE DB2

<?xml version='1.0'?>
<script>
<sql>
<options options='noauto' autocommit='off'/>
<connect conn='myconn' options='noauto'/>
<query conn='myconn' stmt='myupdate'>UPDATE animal SET id = 9 where ID = 3</query>
<query conn='myconn' stmt='myselect'>select count(*) from animal where ID = 9</query>
<fetch stmt='myselect' block='all' desc='off'/>
<free stmt='myselect'/>
<commit conn='myconn' action='rollback'/>
<query conn='myconn' stmt='myselect'>select count(*) from animal where ID = 9</query>
<fetch stmt='myselect' block='all' desc='off'/>
<free/>
</sql>
</script>

XMLSERVICE PGMs, SRVPGMs, APIs

PGM:
<?xml version='1.0'?>
<script>
<pgm name='ZZCALL' lib='XMLSERVICE'>
 <parm  io='both'>
   <data type='1A' var='INCHARA'>a</data>
 </parm>
 <parm  io='both'>
   <data type='1A' var='INCHARB'>b</data>
 </parm>
 <parm  io='both'>
   <data type='7p4' var='INDEC1'>11.1111</data>
 </parm>
 <parm  io='both'>
   <data type='12p2' var='INDEC2'>222.22</data>
 </parm>
 <parm  io='both'>
  <ds>
   <data type='1A' var='INDS1.DSCHARA'>x</data>
   <data type='1A' var='INDS1.DSCHARB'>y</data>
   <data type='7p4' var='INDS1.DSDEC1'>66.6666</data>
   <data type='12p2' var='INDS1.DSDEC2'>77777.77</data>
  </ds>
 </parm>
 <return>
  <data type='10i0'>0</data>
 </return>
</pgm>
</script>

SRVPGM:
<?xml version='1.0'?>
<script>
<pgm name='ZZSRV' lib='XMLSERVICE' func='ZZVARY'>
 <parm comment='search this name' io='in'>
  <data var='myName' type='10A' varying='on'><![CDATA[<Ranger>]]></data>
 </parm>
 <return>
  <data var='myNameis' type='20A' varying='on'><![CDATA[<Mud>]]></data>
 </return>
</pgm>
</script>

System APIs:
<?xml version='1.0'?>
<script>
<pgm name='QSNDDTAQ'>
 <parm io='in'>
   <data type='10A'>MYDATAQ</data>
 </parm>
 <parm  io='in'>
   <data type='10A'>XMLSERVICE</data>
 </parm>
 <parm  io='in'>
   <data type='5p0'>50</data>
 </parm>
 <parm  io='in'>
   <data type='100A'>System i data queues forever</data>
 </parm>
</pgm>
</script>

XMLSERVICE HTML/XML interface

Using your IBM i and XMSERVICE download (see installation), without writing one line of code in any language, we can already check out XMLSERVICE functions using HTML/XML forms. We should note, that by any standard the following trivial XMLSERVICE example is clearly REST web services, but no SOAP, no WSDL, no Java, no PHP, no Ruby, nothing but 2 cents worth of HTML/XML.

XMLSERVICE input - Plain Old XML input to XMLSERVICE for request select * from db2/animals.

XMLSERVICE
> file:///home/adc/Desktop/strsql.html
<myscript>
<sql>
<query>select * from db2/animals</query>
<fetch block=‘all’ desc=‘on’></fetch>
</sql>
</myscript>


XMLSERVICE output - Plain Old XML output from XMLSERVICE with records returned from db2/animals.

XMLSERVICE
> http://lp0364d:10022/cgi-bin/xmlcgi.pgm

<myscript>
<query conn=‘conn1′ stmt=‘stmt1′>
<success><![CDATA[+++ success select * from db2/animals]]></success>
</query>
<fetch block=‘all’ desc=‘on’ stmt=‘stmt1′>
<row>
<data desc=‘ID’><![CDATA[0]]></data>
<data desc=‘BREED’><![CDATA[cat]]></data>
<data desc=‘NAME’><![CDATA[Pook]]></data>
<data desc=‘WEIGHT’><![CDATA[3.20]]></data>
</row>
:

Instructions for your IBM i machine

Step 1) - Add XMLSERVICE to any Apache instance (APACHEDFT)
Set up your Apache to enable XMLSERVICE REST using RPG program XMLCGI.PGM included in XMLSERVICE installation, then restart your Apache instance.

/www/apachedft/conf/httpd.conf:
ScriptAlias /cgi-bin/ /QSYS.LIB/XMLSERVICE.LIB/
<Directory /QSYS.LIB/XMLSERVICE.LIB/>
  AllowOverride None
  order allow,deny
  allow from all
  SetHandler cgi-script
  Options +ExecCGI
</Directory>

start Apache instance:
STRTCPSVR SERVER(*HTTP) HTTPSVR(APACHEDFT)

Step 2) - Ready to use XMLSERVICE for HTML/XML
Cut/Paste following HTML/XML form to your laptop Desktop/strsql.html:

  • change action target to your actual machine action="http://myibmi/cgi-bin/xmlcgi.pgm"
  • point your favorite browser at the HTML file file:///home/adc/Desktop/strsql.html
    • enter database (*LOCAL), user (your profile), password (your password)
    • enter a SQL query in HTML strsql command and press button STRSQL
      desktop/strsql.html:
      <html>
      <head>
      <script>
      function getVal() {
      xml = "<?xml version='1.0'?>";
      xml += "<myscript>";
      xml += "<sql>";
      xml += "<query>";
      xml += document.getElementById('strsql').value;
      xml += "</query>";
      xml += "<fetch block='all' desc='on'>";
      xml += "</fetch>";
      xml += "</sql>";
      xml += "</myscript>";
      document.getElementById('xmlin').value = xml;
      }
      </script>
      </head>
      <body>
      <h3>STRSQL</h3>
      <form onsubmit="getVal();" name="input" action="http://myibmi/cgi-bin/xmlcgi.pgm" method="post">
      <br><input type="text" name="db2" value="*LOCAL" size="40" > database
      <br><input type="text" name="uid" value="MYUID" size="40" > user
      <br><input type="password" name="pwd" value="MYPWD" size="40" > password
      <input type="hidden" name="ipc" value="*NA">
      <input type="hidden" name="ctl" value="*here *cdata">
      <input type="hidden" name="xmlin" id="xmlin" value="na">
      <input type="hidden" name="xmlout" value="500000">
      <br><input type="text" name="strsql" id="strsql" size="40" /> strsql command (select * from db2/animals)
      </table>
      <br><br><input type="submit" value="STRSQL" />
      </form>
      </body>
      </html>
      

desktop/strsql.html example
As strsql.html name implies, this simple html enables STRSQL running from your laptop to your IBM i. Enter any SQL statement you wish in the html form and XMLSERVICE will run just like STRSQL green screen when you press the STRSQL button. XMLSERVICE output returned will be XML (of course), so if your browser has issues displaying XML, you may have to view page source.

HTML form strsql.html uses simple JavaScript function getVal() with document.getElementById('strsql').value, which reads HTML text input <input id='strsql' and adds user SQL request to XML document to HTML text input <input id="xmlin". All XMLSERVICE required REST tag elements can bee seen in the following HTML form http://myibmi/cgi-bin/xmlcgi.pgm?db2=*LOCAL@uid=MYUID@pwd=MYPWD@ipc=*NA@ctl="*here *cdata"@xmlin=(see JavaScript)@xmlout=500000, but we will cover this in later sections.

What is happening?
If we change method="post" to method="get", the fully encoded document will appear on the browser URL line. As you can see, when input arrives from our browser (or REST client), XMLSERVICE/XMLCGI.PGM has much HTTP decoding before actually parsing the XML document and servicing the request.

<form onsubmit="getVal();" name="input" action="http://myibmi/cgi-bin/xmlcgi.pgm" method="post">
-- change --
<form onsubmit="getVal();" name="input" action="http://myibmi/cgi-bin/xmlcgi.pgm" method="get">

The follow cut/paste is one continuous browser line (split for viewing):
http://myibmi/cgi-bin/xmlcgi.pgm?db2=*LOCAL
&uid=MYUID
&pwd=MYPWD
&ipc=*NA
&ctl=*here+*cdata
&xmlin=%3C%3Fxml+version%3D%271.0%27%3F%3E
       %3Cmyscript%3E
       %3Csql%3E
       %3Cquery%3Eselect+*+from+db2%2Fanimals
       %3C%2Fquery%3E
       %3Cfetch+block%3D%27all%27+desc%3D%27on%27%3E
       %3C%2Ffetch%3E
       %3C%2Fsql%3E
       %3C%2Fmyscript%3E
&xmlout=500000
&strsql=select+*+from+db2%2Fanimals

The flow:

  • We point our browser file:///home/adc/Desktop/strsql.html, enter SQL query and press STRSQL button
  • IBM i Apache XMLCGI.PGM receives our encoded HTML/XML form action="http://myibmi/cgi-bin/xmlcgi.pgm"
  • XMLCGI.PGM calls XMLSERVICE.PGM (using DB2 stored procedures iPLUGxxx, but you do not need to know this yet).
  • XMLSERVICE.PGM parses XML input and runs internal DB2 driver <sql><query>...</query></sql>.
  • XMLSERVICE.PGM parses result set from DB2 driver into output XML document <sql><fetch/></sql>
  • browser sees XML return of DB2 data

XMLSERVICE is Open Source, so you can examine internals of XMLCGI.PGM, for now , we simply need to understand XMLCGI.PGM decodes HTML/XML document, passes XML document request to XMLSERVICE.PGM (DB2 request example), and returns XML output to client (browser). If REST client is not a browser, but a scripting language like PHP or Ruby, exact same sequence occurs, except additionally most languages offer an XML parser to parse output XML into variables or structures (PHP Toolkit or Ruby Toolkit).

Quick test functions HTML/XML

XMLSERVICE HTML/XML technique can be used for nearly anything on IBM i machine CMD, PGM, SRVPGM, system APIs, PASE utilities, DB2, etc. Feel free to copy strsql.html form, modify, and try other XMLSERVICE functions <myscript>other functions</myscript>. HTML/XML technique is a very handy testing a potential XMLSERVICE program service without writing a line of code, and, clearly demonstrates elegant simplicity embodied by XMLSERVICE.

XMLSERVICE DB2 interface

DB2 connection is not a web service, but many languages support high speed DB2 local/remote requests, so XMLSERVICE included a stored procedures interface (iPLUG4K - iPLUG15M). The nature of DB2 stored procedures requires a size specified on in/out parameters, therefore XMLSERVICE library includes various iPLUGxx sizes to fit your XML document data needs (4K, 32K, 65K, 512K, 1M, 5M, 10M, up to 15M).

We should note, XMLSERVICE DB2 is much faster over REST interface, so many language toolkits offer DB2 connection as the premier service.

RPG DB2 (no toolkit)

       myIPC = '/tmp/thebears1';       
       myCtl = '*sbmjob';
       // call XMLSERVICE/ZZCALL(...) using XML only
       myXmlIn = 
         '<?xml version="1.0" encoding="ISO-8859-1"?>'         + x'0D'
       + '<script>'                                            + x'0D'
       + '<pgm name="ZZCALL" lib="XMLSERVICE">'                + x'0D'
       + '<parm><data type="1a" v="1">Y</data></parm>'         + x'0D'
       + '<parm><data type="1a" v="2">Z</data></parm>'         + x'0D'
       + '<parm><data type="7p4" v="3">001.0001</data></parm>' + x'0D'
       + '<parm><data type="12p2" v="4">0003.04</data></parm>' + x'0D'
       + '<parm>'                                              + x'0D'
       + ' <ds>'                                               + x'0D'
       + '  <data type="1a" v="5">A</data>'                    + x'0D'
       + '  <data type="1a" v="6">B</data>'                    + x'0D'
       + '  <data type="7p4" v="7">005.0007</data>'            + x'0D'
       + '  <data type="12p2" v="8">0000000006.08</data>'      + x'0D'
       + ' </ds>'                                              + x'0D'
       + '</parm>'                                             + x'0D'
       + '</pgm>'                                              + x'0D'
       + '</script>'                                           + x'00';
       myXmlOut = *BLANKS; 
       // make call to XMLSERVICE provided stored procedure(s)
       // sizes from iPLUG4k to iPLUG15M (see crtsql xmlservice package)
       Exec Sql call XMLSERVICE/iPLUG4K(:myIPC,:myCtl,:myXmlIn,:myXmlOut);

PHP DB2 (toolkit)

require_once("ToolkitService.php");
try { $ToolkitServiceObj = ToolkitService::getInstance($database, $user, $password); }
catch (Exception $e) { die($e->getMessage()); }
$ToolkitServiceObj->setToolkitServiceParams(
array('InternalKey'=>$ipc,         // route to same XMLSERVICE job /tmp/myjob1
'subsystem'=>"QGPL/QDFTJOBD",      // subsystem/jobd to start XMLSERVICE (if not running) 
'plug'=>"32K"));                   // max size data i/o (iPLUG4K,32K,65K, 512K,1M,5M,10M,15M)
$param[] = $ToolkitServiceObj->AddParameterChar   ('both',  1,  'INCHARA', 'var1', 'Y');
$param[] = $ToolkitServiceObj->AddParameterChar   ('both',  1,  'INCHARB', 'var2', 'Z');
$param[] = $ToolkitServiceObj->AddParameterPackDec('both',  7,4,'INDEC1',  'var3', '001.0001');
$param[] = $ToolkitServiceObj->AddParameterPackDec('both', 12,2,'INDEC2',  'var4', '0000000003.04');
   $ds[] = $ToolkitServiceObj->AddParameterChar   ('both',  1,  'DSCHARA', 'ds1',  'A');
   $ds[] = $ToolkitServiceObj->AddParameterChar   ('both',  1,  'DSCHARB', 'ds2',  'B');
   $ds[] = $ToolkitServiceObj->AddParameterPackDec('both',  7,4,'DSDEC1',  'ds3',  '005.0007');
   $ds[] = $ToolkitServiceObj->AddParameterPackDec('both', 12,2,'DSDEC1',  'ds4',  '0000000006.08');
$param[] = $ToolkitServiceObj->AddDataStruct($ds);
$result  = $ToolkitServiceObj->PgmCall('ZZCALL', $testLib, $param, null, null);
echo "good so far ...\n";
var_dump($result);

PHP DB2 (without toolkit)

$fast = false;
$ipc = "*NA";
$ctl = "*here *cdata";
$xmlIn   = "<?xml version='1.0' encoding='ISO-8859-1'?>
<script>
<pgm name='ZZCALL' lib='ZENDSVR'>
<parm><data type='1a'>Y</data></parm>
<parm><data type='1a'>Z</data></parm>
<parm><data type='7p4'>001.0001</data></parm>
<parm><data type='12p2'>0000000003.04</data></parm>
<parm>
 <ds>
  <data type='1a'>A</data>
  <data type='1a'>B</data>
  <data type='7p4'>005.0007</data>
  <data type='12p2'>0000000006.08</data>
 </ds>
</parm>
</pgm>
</script>"; 
$xmlOut = '';
if ($fast) $conn = db2_pconnect($db, $user, $pass);     // persistent/pooled connection
else $conn = db2_connect($db, $user, $pass);            // full open/close connection
if (!$conn) die("Bad connect: $db, $user");
$stmt = db2_prepare($conn, "call $lib.$plug(?,?,?,?)"); // Call XMLSERVICE 
                                                        // stored procedure interface
                                                        // in/out parameter (xmlOut)
                                                        // sizes: iPLUG4K - iPLUG15M
if (!$stmt) die("Bad prepare: ".db2_stmt_errormsg());
$ret=db2_bind_param($stmt, 1, "ipc", DB2_PARAM_IN);     // ? - /tmp/raw_$user (*sbmjob)
$ret=db2_bind_param($stmt, 2, "ctl", DB2_PARAM_IN);     // ? - *here or *sbmjob
$ret=db2_bind_param($stmt, 3, "xmlIn", DB2_PARAM_IN);   // ? - XML input script
$ret=db2_bind_param($stmt, 4, "xmlOut", DB2_PARAM_OUT); // ? - XML output return
$ret=db2_execute($stmt);
if (!$ret) die("Bad execute: ".db2_stmt_errormsg());
var_dump($xmlOut);

PowerRuby DB2 (toolkit)

require 'active_record'
require 'xmlservice'

ActiveRecord::Base.establish_connection(
  :adapter   => 'ibm_db',
  :database => '*LOCAL',
  :username => 'MYUID',
  :password => 'MYPWD'
)
ActiveXMLService::Base.establish_connection(
  :connection => 'ActiveRecord',
  :install => "XMLSERVICE",
  :ctl => "*here *cdata",
  :ipc => "*NA",
  :size => 4096,
  :head => "<?xml version='1.0'?>"
)
zzcall = XMLService::I_PGM.new("zzcall","xmlservice")
zzcall << XMLService::I_a.new('inchara',1,'a')
zzcall << XMLService::I_a.new('incharb',1,'b')
zzcall << XMLService::I_p.new('indec1',7,4,11.1111)
zzcall << XMLService::I_p.new('indec2',12,2,222.22)
zzcall << XMLService::I_DS.new('inds1',1,
          [XMLService::I_a.new('dschara',1,'x'),
           XMLService::I_a.new('dscharb',1,'y'),
           XMLService::I_p.new('dsdec1',7,4,66.6666),
           XMLService::I_p.new('dsdec2',12,2,77777.77)])
zzcall.xmlservice
puts zzcall.out_xml

PowerRuby DB2 (without toolkit)

require 'active_record'

ipc = "*NA"
ctl = "*here *cdata"
xmlin = '<?xml version="1.0"?>
<script>
<pgm name="ZZCALL" lib="XMLSERVICE">
 <parm  io="both">
   <data type="1A">a</data>
 </parm>
 <parm  io="both">
   <data type="1A">b</data>
 </parm>
 <parm  io="both">
   <data type="7p4">11.1111</data>
 </parm>
 <parm  io="both">
   <data type="12p2">222.22</data>
 </parm>
 <parm  io="both">
  <ds>
   <data type="1A">x</data>
   <data type="1A">y</data>
   <data type="7p4">66.6666</data>
   <data type="12p2">77777.77</data>
  </ds>
 </parm>
 <return>
  <data type="10i0">0</data>
 </return>
</pgm>
</script>'
xmlout = ""
ActiveRecord::Base.establish_connection(
  :adapter   => 'ibm_db',
  :database => '*LOCAL',
  :username => 'MYUID',
  :password => 'MYPWD'
)
conn = ActiveRecord::Base.connection.connection
stmt = IBM_DB::prepare(conn, 'CALL XMLSERVICE.iPLUG512K(?,?,?,?)')
ret = IBM_DB::bind_param(stmt, 1, "ipc", IBM_DB::SQL_PARAM_INPUT)
ret = IBM_DB::bind_param(stmt, 2, "ctl", IBM_DB::SQL_PARAM_INPUT)
ret = IBM_DB::bind_param(stmt, 3, "xmlin", IBM_DB::SQL_PARAM_INPUT)
ret = IBM_DB::bind_param(stmt, 4, "xmlout", IBM_DB::SQL_PARAM_OUTPUT)
ret = IBM_DB::execute(stmt)
puts xmlout

Java DB2 (no toolkit)

import java.io.*;
import java.util.*;
import java.sql.*;
import java.math.*;

public class javaXMLserviceDemoJDBC {
public static void main(String[] args)   {
  Connection conn = null;
  Statement stmt=null; 
  CallableStatement cstmt = null ;
  PreparedStatement pstmt = null;
  String url = "jdbc:db2://localhost"; // Set URL for data source
  String user = "MYUID";
  String password = "MYPWD";
  try
  { // Load the DB2(R) Universal JDBC Driver with DriverManager
    Class.forName("com.ibm.db2.jdbc.app.DB2Driver");
    conn = DriverManager.getConnection(url, user, password); 
    String inputClob = 
        "<?xml version='1.0'?>"
      + " <script>"
      + " <pgm name='ZZCALL' lib='XMLSERVICE'>"
      + " <parm><data type='1A'>a</data></parm>"
      + " <parm><data type='1A'>b</data></parm>"
      + " <parm><data type='7p4'>11.1111</data></parm>"
      + " <parm><data type='12p2'>222.22</data></parm>"
      + " <parm>"
      + " <ds>"
      + " <data type='1A'>x</data>"
      + " <data type='1A'>y</data>"
      + " <data type='7p4'>66.6666</data>"
      + " <data type='12p2'>77777.77</data>"
      + " </ds>"
      + " </parm>"
      + " <return><data type='10i0'>0</data></return>"
      + " </pgm>"
      + " </script>";
    String sql="CALL XMLSERVICE.iPLUG512K(?,?,?,?)";
    cstmt = conn.prepareCall(sql);
    System.out.println("Calling with valid name"); 
    cstmt.setString(1,"/tmp/packers01");
    cstmt.setString(2,"*sbmjob");
    cstmt.setString(3,inputClob);
    cstmt.registerOutParameter(4, Types.CLOB);
    cstmt.execute();
    String doc = cstmt.getString(4);
    System.out.println("****** Documento XML: **********");
    System.out.println(doc);
  } 
  catch (Exception e) 
  { System.out.println("******* Eccezione !!! *********");
    e.printStackTrace();
  } 
}
}

perl DB2 (no toolkit)

use DBI;
use DBD::DB2::Constants;
use DBD::DB2;

$dbh = DBI->connect("dbi:DB2:*LOCAL")
            or die $DBI::errstr;

$stmt = 'call XMLSERVICE.iPLUG65K(?,?,?,?)';
$sth = $dbh->prepare($stmt)
  or die "prepare got error " . $dbh->err;
$ipc = "/tmp/perlme";
$sth->bind_param(1, $ipc)
  or die "bind 1 got error " . $dbh->err;
$ctl = "*sbmjob";
$sth->bind_param(2, $ctl)
  or die "bind 2 got error " . $dbh->err;
$xmlin = '<?xml version="1.0"?>
<script>
<pgm name="ZZCALL" lib="XMLSERVICE">
 <parm  io="both">
   <data type="1A">a</data>
 </parm>
 <parm  io="both">
   <data type="1A">b</data>
 </parm>
 <parm  io="both">
   <data type="7p4">11.1111</data>
 </parm>
 <parm  io="both">
   <data type="12p2">222.22</data>
 </parm>
 <parm  io="both">
  <ds>
   <data type="1A">x</data>
   <data type="1A">y</data>
   <data type="7p4">66.6666</data>
   <data type="12p2">77777.77</data>
  </ds>
 </parm>
 <return>
  <data type="10i0">0</data>
 </return>
</pgm>
</script>
';
$sth->bind_param(3, $xmlin)
  or die "bind 3 got error " . $dbh->err;
$xmlout = "";
$xmloutlen = 4096;
$sth->bind_param_inout(4, \$xmlout, $xmloutlen)
  or die "bind 4 got error " . $dbh->err;
$sth->execute()
  or die "execute got error" . $dbh->err;

XMLSERVICE REST interface

XMLSERVICE includes a simple REST interface (XMLCGI.PGM), we demonstrated using the REST service using only HTML/XML in a previous section. Most languages support REST calls, so XMLSERVICE REST interface can be very useful for cloud applications where DB2 drivers are not available. XMLSERVICE has REST production clients in most every scripting language you can imagine (PHP, Ruby, perl, python, etc.).

JavaScript REST (no toolkit)

<html>
<head>
<script src="http://ajax.googleapis.com/ajax/libs/dojo/1.5/dojo/dojo.xd.js" type="text/javascript"></script>
<script language="javascript">
dojo.require("dojox.xml.parser");
// you will need actual uid/pwd
// *NONE not enabled by default
var msgin = "xmlservice input";
var msgout = "xmlservice output";
var xmlhttp = null;
var url = encodeURI("http://"
        + self.location.hostname
        + "/cgi-bin/xmlcgi.pgm?" 
        + "db2=*LOCAL"
        + "&uid=MYUID"
        + "&pwd=MYPWD"
        + "&ipc=/tmp/rangerhtmlonly"
        + "&ctl=*sbmjob"
        + "&xmlin="
        + "<?xml version='1.0'?>"
        + " <myscript>"
        + " <pgm name='ZZCALL' lib='XMLSERVICE'>"
        + " <parm var='p1'><data type='1A' var='d1'>a</data></parm>"
        + " <parm var='p2'><data type='1A' var='d2'>b</data></parm>"
        + " <parm var='p3'><data type='7p4' var='d3'>11.1111</data></parm>"
        + " <parm var='p4'><data type='12p2' var='d4'>222.22</data></parm>"
        + " <parm var='p5'>"
        + " <ds var='myds'>"
        + " <data type='1A' var='ds1'>x</data>"
        + " <data type='1A' var='ds2'>y</data>"
        + " <data type='7p4' var='ds3'>66.6666</data>"
        + " <data type='12p2' var='ds4'>77777.77</data>"
        + " </ds>"
        + " </parm>"
        + " <return var='rc'><data type='10i0' var='d1'>0</data></return>"
        + " </pgm>"
        + " </myscript>"
        + "&xmlout=32768");
function readNode(baseNode,output)
{ // @copy: http://blog.char95.com/post/simple-javascript-xml2array-parser/
  var node = baseNode.firstChild;
  if (output==undefined) var output = {};
  while(node)
  { var nodeData = {};
    if (node.attributes)
    { var nNodes = node.attributes.length;
      while(nNodes--) nodeData['$'+node.attributes[nNodes].nodeName] = node.attributes[nNodes].nodeValue;
    }
    if (output[node.nodeName]==undefined) output[node.nodeName] = new Array(nodeData);
    else output[node.nodeName].push(nodeData);
    var id = output[node.nodeName].length-1;
    output[node.nodeName][id] = readNode(node,output[node.nodeName][id]);
    if (node.firstChild) nodeData['#text'] = node.firstChild.nodeValue;
    node = node.nextSibling;
  }
  return output;
}
function processXMLSERVICE2() 
{ var args = 
  { url:url,
    handleAs:"xml",
    preventCache:true,
    load:function(data) 
    { var xmlArray = readNode(data);
      var table = document.createElement('table');
      var output = 
        "<th>parm</th>"
      + "<th>ds</th>"
      + "<th>var</th>"
      + "<th>value</th>\n";
      parms = xmlArray['myscript'][0]['pgm'][0]['parm'];
      for (var i=0;i<parms.length;i++)
      { if (i<parms.length - 1) 
        { output += "<tr>"
          + "<td>" + parms[i].$var + "</td>\n"
          + "<td>" + "(na)" + "</td>\n"
          + "<td>" + parms[i]['data'][0].$var + "</td>\n"
          + "<td>" + parms[i]['data'][0]['#text'] + "</td>\n"
          + "</tr>";
        }
        else
        { dsvar = parms[i]['ds'][0].$var;
          dsdata = parms[i]['ds'][0]['data'];
          for (var j=0;j<dsdata.length;j++)
          { output += "<tr>"
            + "<td>" + parms[i].$var + "</td>\n"
            + "<td>" + dsvar + "</td>\n"
            + "<td>" + dsdata[j].$var + "</td>\n"
            + "<td>" + dsdata[j]['#text'] + "</td>\n"
            + "</tr>";
          }
        }
      }
      output += "</table>\n";
      table.setAttribute("border","1")
      table.innerHTML = output;
      document.getElementById("addtable").appendChild(table);
    },
    error:function(error) 
    { alert("Error:" + error); 
    }
  };
  var ajaxCall = dojo.xhrGet(args);
}
</script>
</head>
<body>
<p>This page demonstrates calling XMLSERVICE by JavaScript. Display source in your browser to see JavaScript used.</p>
<form>
<ul>
<li><a href="javascript: processXMLSERVICE2();">{XMLSERVICE JavaScript table (click me)}</a> - DoJo REST call RPG build table element</li>
</eul>
<p>
<div id="addtable"></div>
</p>
</form>
</body>
</html>

PHP REST (no toolkit)

<?php
function getxml() {
$clob = <<<ENDPROC
<?xml version='1.0'?>
<script>
<pgm name='ZZCALL' lib='XMLSERVICE'>
 <parm><data type='1A'>a</data></parm>
 <parm><data type='1A'>b</data></parm>
 <parm><data type='7p4'>11.1111</data></parm>
 <parm><data type='12p2'>222.22</data></parm>
 <parm>
  <ds>
   <data type='1A'>x</data>
   <data type='1A'>y</data>
   <data type='7p4'>66.6666</data>
   <data type='12p2'>77777.77</data>
  </ds>
 </parm>
 <return><data type='10i0'>0</data></return>
</pgm>
</script>
ENDPROC;
return $clob;
}
// make the call
$i5persistentconnect = false;
$database = "*LOCAL";
$user = "MYUID";
$password = "MYPWD";
$libxmlservice = "XMLSERVICE";
$ipc = '/tmp/rangerhtmlonly';
$ctl = '*sbmjob';
$clobIn = getxml();
$clobOut = "";
$clobOutMax = "32000";
$i5rest = "http://174.79.32.155/cgi-bin/xmlcgi.pgm";
$postdata = http_build_query(
   array(
     'db2' => $database,
     'uid' => $user,
     'pwd' => $password,
     'ipc' => $ipc,
     'ctl' => $ctl,
     'xmlin' => $clobIn,
     'xmlout' => $clobOutMax    // size expected XML output
   )
  );
$opts = array('http' =>
   array(
     'method'  => 'POST',
     'header'  => 'Content-type: application/x-www-form-urlencoded',
     'content' => $postdata
   )
  );
$context  = stream_context_create($opts);
$clobOut = file_get_contents($i5rest, false, $context);
?>

PowerRuby REST (no toolkit)

require 'adapters/abstract_adapter'
require 'net/http'
require 'uri'

xmlin = '<?xml version="1.0"?>
<script>
<pgm name="ZZCALL" lib="XMLSERVICE">
 <parm  io="both">
   <data type="1A">a</data>
 </parm>
 <parm  io="both">
   <data type="1A">b</data>
 </parm>
 <parm  io="both">
   <data type="7p4">11.1111</data>
 </parm>
 <parm  io="both">
   <data type="12p2">222.22</data>
 </parm>
 <parm  io="both">
  <ds>
   <data type="1A">x</data>
   <data type="1A">y</data>
   <data type="7p4">66.6666</data>
   <data type="12p2">77777.77</data>
  </ds>
 </parm>
 <return>
  <data type="10i0">0</data>
 </return>
</pgm>
</script>'
xmlout = ""

post_args = { 
 :db2 => "*LOCAL",
 :uid => "MYUID",
 :pwd => "MYPWD",
 :ipc => "*NA",
 :ctl => "*here *cdata",
 :xmlin => xmlin,
 :xmlout => 4096
}
uri = URI("http://myibmi/cgi-bin/xmlcgi.pgm")
res = Net::HTTP.post_form(uri, post_args)
xmlout = res.body
puts xmlout

Java REST (no toolkit)

import java.net.*;
import java.io.*;
public class javaXMLserviceDemoREST {
  public static void main(String[] args) 
  { try 
    { // The URL class does not itself encode or decode any URL components according to the escaping mechanism defined in RFC2396. 
      // It is the responsibility of the caller to encode any fields, which need to be escaped prior to calling URL, 
      // and also to decode any escaped fields, that are returned from URL. Furthermore, because URL has no knowledge of URL escaping, 
      // it does not recognise equivalence between the encoded or decoded form of the same URL
      String inputURL = 
          "http://174.79.32.155/cgi-bin/xmlcgi.pgm?" 
        + java.net.URLEncoder.encode(
          "db2=*LOCAL"
        + "&uid=MYUID"
        + "&pwd=MYPWD"
        + "&ipc=/tmp/rangerhtmlonly"
        + "&ctl=*sbmjob"
        + "&xmlin="
        + "<?xml version='1.0'?>"
        + " <script>"
        + " <pgm name='ZZCALL' lib='XMLSERVICE'>"
        + " <parm><data type='1A'>a</data></parm>"
        + " <parm><data type='1A'>b</data></parm>"
        + " <parm><data type='7p4'>11.1111</data></parm>"
        + " <parm><data type='12p2'>222.22</data></parm>"
        + " <parm>"
        + " <ds>"
        + " <data type='1A'>x</data>"
        + " <data type='1A'>y</data>"
        + " <data type='7p4'>66.6666</data>"
        + " <data type='12p2'>77777.77</data>"
        + " </ds>"
        + " </parm>"
        + " <return><data type='10i0'>0</data></return>"
        + " </pgm>"
        + " </script>"
        + "&xmlout=32768", 
          "ISO-8859-1");
      // make REST call to XMLSERVICE
      URL restUrl = new URL(inputURL);
      URLConnection conn = restUrl.openConnection();
      // output processing
      System.out.println("Content type: " + conn.getContentType());
      System.out.println("Content length: " + conn.getContentLength());
      BufferedReader strm = new BufferedReader(new InputStreamReader(conn.getInputStream()));		
      String inputLine;
      String doc = "";
      while ((inputLine = strm.readLine()) != null) {
       doc = doc + inputLine;
      }
      System.out.println("****** Documento XML: **********");
      System.out.println(doc);
    } 
    catch (Exception e) 
    { System.out.println("******* Eccezione !!! *********");
      e.printStackTrace();
    }
  }
}

RPG and XMLSERVICE

RPG is usually considered server side of XMLSERVICE, a called RPG PGM or SRVPGM (web service), but RPG is well versed in DB2, therefore can also be used as RPG client to XMLSERVICE. In fact, client RPG DB2 connection to XMLSERVICE will likely be fastest and easiest choice, especially for your remote IBM i systems (WRKRDBDIRE).

The RPG client examples will demonstrate RPG CGI using XMLSERVICE via Apache configuration, but the techniques also work as batch or green screen application, after using XMLSERVICE for a while, you may realize just how little code you have to write to do a great deal of work.

  • Apache CGI configuration (httpd.conf)
    ScriptAlias /cgi-bin/ /QSYS.LIB/XMLSERVICE.LIB/
    <Directory /QSYS.LIB/XMLSERVICE.LIB/>
      order allow,deny
      allow from all
      SetHandler cgi-script
      Options +ExecCGI
    </Directory>
    

RPG client XMLSERVICE (*PGM)

RPG program ZZRPGSQL.PGM demonstrates client use of XMLSERVICE calling a *PGM (ZZCALL.pgm).

XMLSERVICE/ZZCALL (*PGM)
     D  INCHARA        S              1a
     D  INCHARB        S              1a
     D  INDEC1         S              7p 4        
     D  INDEC2         S             12p 2
     D  INDS1          DS                  
     D   DSCHARA                      1a
     D   DSCHARB                      1a           
     D   DSDEC1                       7p 4      
     D   DSDEC2                      12p 2            
      *+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
      * main(): Control flow
      *+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
     C     *Entry        PLIST                   
     C                   PARM                    INCHARA
     C                   PARM                    INCHARB
     C                   PARM                    INDEC1
     C                   PARM                    INDEC2
     C                   PARM                    INDS1

The simple example is of course a bit contrived, simply extracting strings between <data>output</data> returned XMLSERVICE output, but serves to demonstrate XMLSERVICE call using Exec Sql call XMLSERVICE/iPLUG4K(:myIPC,:myCtl,:myXmlIn,:myXmlOut);.

XMLSERVICE
> http://lp0364d:10022/cgi-bin/zzrpgsql.pgm

  • ZZRPGSQL.PGM calling XMLSERVICE via Exec Sql call XMLSERVICE/iPLUG4K
         H AlwNull(*UsrCtl)
         H BNDDIR('QC2LE')
    
          * vars
         D myIPC           s           1024A   inz(*BLANKS)
         D myCtl           s           1024A   inz(*BLANKS)
         D myXmlIn         s           4096A   inz(*BLANKS)
         D myXmlOut        s           4096A   inz(*BLANKS)
    
         D i               s             10i 0 inz(0)
         D rn              s             10i 0 inz(0)
    
         D data            s          65000A   inz(*BLANKS)
         D xml1            s          65000A   inz(*BLANKS)
         D xml2            s          65000A   inz(*BLANKS)
         D xml3            s          65000A   inz(*BLANKS)
         D xml4            s          65000A   inz(*BLANKS)
    
         D strstr          PR              *   ExtProc('strstr')
         D  pVal1                          *   Value options(*string)
         D  pVal2                          *   Value options(*string)
    
         D strlen          PR            10I 0 ExtProc('strlen')
         D  pVal                           *   Value options(*string)
    
         D writeIFS        PR            20I 0 ExtProc('write')     
         D   fd                          10I 0 value                       
         D   buf                           *   value
         D   size                        10I 0 value      
    
         D xmlfind         PR         65000A
         D  xml                            *   value
         D  nbr                          10i 0 value
         D  xbeg                         32A   value
         D  xbeg1                        32A   value
         D  xend                         32A   value
    
         D Main            PR                  ExtPgm('ZZRPGSQL') 
          *+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
          * main(): Control flow
          *+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
         D Main            PI 
          /free
           Monitor;       
    
           // -----
           // input
    
           myIPC = '*NA';       
           myCtl = '*here';
           myXmlIn = 
             '<?xml version="1.0" encoding="ISO-8859-1"?>'                + x'0D'
           + '<script>'                                                   + x'0D'
           + '<pgm name="ZZCALL" lib="XMLSERVICE">'                       + x'0D'
           + '<parm><data type="1a" var="INCHARA">Y</data></parm>'        + x'0D'
           + '<parm><data type="1a" var="INCHARB">Z</data></parm>'        + x'0D'
           + '<parm><data type="7p4" var="INDEC1">001.0001</data></parm>' + x'0D'
           + '<parm><data type="12p2" var="INDEC2">0003.04</data></parm>' + x'0D'
           + '<parm>'                                                     + x'0D'
           + ' <ds>'                                                      + x'0D'
           + '  <data type="1a" var="DSCHARA">A</data>'                   + x'0D'
           + '  <data type="1a" var="DSCHARB">B</data>'                   + x'0D'
           + '  <data type="7p4" var="DSDEC1">005.0007</data>'            + x'0D'
           + '  <data type="12p2" var="DSDEC2">0000000006.08</data>'      + x'0D'
           + ' </ds>'                                                     + x'0D'
           + '</parm>'                                                    + x'0D'
           + '</pgm>'                                                     + x'0D'
           + '</script>'                                                  + x'00';
           myXmlOut = *BLANKS; 
    
           // -----
           // sql call XMLSERVICE provided stored procedure(iPLUG4k -iPLUG15M)
           Exec Sql call XMLSERVICE/iPLUG4K(:myIPC,:myCtl,:myXmlIn,:myXmlOut);
    
           // -----
           // output (CGI)
    
           // -----
           // send header + end (LFLF)
           data = 'Content-type: text/html' + x'15' + x'15' + x'00';
           rn = writeIFS(1:%addr(data):strlen(%addr(data)));
           // -----
           // send return data       
           // HTML table
           data  = '<h3>RPG call XMLSERVICE</h3>'                 + x'0D';
           data  = %trim(data) + '<table border="1">'             + x'0D';
           data  = %trim(data) + '<th>Parameter name</th>'        + x'0D';
           data  = %trim(data) + '<th>Type value</th>'            + x'0D';
           data  = %trim(data) + '<th>Input value</th>'           + x'0D';
           data  = %trim(data) + '<th>Output value</th>'          + x'0D';
           for i = 1 to 8;
             xml1  = xmlfind(%addr(myXmlIn): i:'var=' :'"':'"');
             xml2  = xmlfind(%addr(myXmlIn): i:'type=':'"':'"');
             xml3  = xmlfind(%addr(myXmlIn): i:'<data':'>':'</data>');
             xml4  = xmlfind(%addr(myXmlOut):i:'<data':'>':'</data>');
             // HTML table row
             data  = %trim(data) + '<tr>'                         + x'0D';
             data  = %trim(data) + '<td>' + %trim(xml1) + '</td>' + x'0D';
             data  = %trim(data) + '<td>' + %trim(xml2) + '</td>' + x'0D';
             data  = %trim(data) + '<td>' + %trim(xml3) + '</td>' + x'0D';
             data  = %trim(data) + '<td>' + %trim(xml4) + '</td>' + x'0D';
             data  = %trim(data) + '</tr>'                        + x'0D';
           endfor;
           data  = %trim(data) + '</table>'                       + x'00';
           rn = writeIFS(1:%addr(data):strlen(%addr(data)));
    
           On-error;
           Endmon;
    
           return;
          /end-free
    
          *****************************************************
          * xmlfind
          *****************************************************
         P xmlfind         B
         D xmlfind         PI         65000A
         D  xml                            *   value
         D  nbr                          10i 0 value
         D  xbeg                         32A   value
         D  xbeg1                        32A   value
         D  xend                         32A   value
          * vars
         D i               s             10i 0 inz(0)
         D cbeg            s             33A   inz(*BLANKS)
         D cbeg1           s             33A   inz(*BLANKS)
         D cend            s             33A   inz(*BLANKS)
         D pbeg            s               *   inz(*NULL)
         D pend            s               *   inz(*NULL)
         D xmlFragment     s          65000A   inz(*BLANKS)
          /free
           cbeg = %trim(xbeg) + x'00';
           cbeg1 = %trim(xbeg1) + x'00';
           cend = %trim(xend) + x'00';
           pbeg = xml;
           for i = 1 to nbr;
             // <item stuff>123</item>
             // x
             if pbeg <> *NULL;
               pbeg = strstr(pbeg + 1:%addr(cbeg));
             endif;
           endfor;
           // <item stuff>123</item>
           //            x
           if pbeg <> *NULL;
             pbeg = strstr(pbeg:%addr(cbeg1));
           endif;
           if pbeg <> *NULL;
             // <item stuff>123</item>
             //             x  x
             pbeg += 1;
             pend = strstr(pbeg:%addr(cend));
             if pend <> *NULL and pend > pbeg;
               xmlFragment = %str(pbeg:pend - pbeg);
             endif;
           endif;
           return xmlFragment;
          /end-free
         P                 E
    

What is happening?

The flow of ZZRPGSQL.PGM is similar to HTML/XML, except we are using the XMLSERVICE provided stored procedure interface to call XMLSERVICE.

  • We point our browser to http://lp0364d:10022/cgi-bin/zzrpgsql.pgm, which is RPG CGI program ZZRPGSQL.PGM.
  • ZZRPGSQL.PGM uses XMLSERVICE DB2 interface Exec Sql call XMLSERVICE/iPLUG4K(:myIPC,:myCtl,:myXmlIn,:myXmlOut);, passing XML input request myXmlIn to XMLSERVICE.
  • XMLSERVICE.PGM parses XML input and dynamically loads/activates/calls target ZZCALL.PGM with included parameters <parm>...</parm>.
  • ZZCALL.PGM runs using normal in/out parameters (memory)
  • XMLSERVICE.PGM parses in/out parameters from ZZCALL.PGM into output XML document
  • ZZRPGSQL.PGM myXmlOut variable contains XML output document
  • ZZRPGSQL.PGM parses myXmlOut into a HTML table output (writeIFS)
  • browser sees the HTML table of ZZCALL data

RPG client XMLSERVICE (*SRVPGM)

RPG program ZZVRYSQL.PGM demonstrates client use of XMLSERVICE calling a *SRVPGM (ZZSRV.ZZVARY). As you read source code for ZZVRYSQL.PGM, you will see it is nearly identical to previous example ZZRPGSQL.PGM.

XMLSERVICE/ZZSRV.ZZVARY (*SRVPGM)
     P zzvary          B                   export
     D zzvary          PI            20A   varying
     D  myName                       10A   varying

XMLSERVICE called ZZSRV.ZZARRY SRVPGM demonstrates advance functions problematic for PCML based web services.

  • difficult — parameter 10A varying - PCML requires multiple XML definitions for length, data
  • impossible — return 20A varying - PCML has no ability to return complex data (only single integer)
XMLSERVICE
> http://lp0364d:10022/cgi-bin/zzvrysql.pgm

  • ZZVRYSQL.PGM calling XMLSERVICE via Exec Sql call XMLSERVICE/iPLUG4K
         H AlwNull(*UsrCtl)
         H BNDDIR('QC2LE')
    
          * vars
         D myIPC           s           1024A   inz(*BLANKS)
         D myCtl           s           1024A   inz(*BLANKS)
         D myXmlIn         s           4096A   inz(*BLANKS)
         D myXmlOut        s           4096A   inz(*BLANKS)
    
         D i               s             10i 0 inz(0)
         D rn              s             10i 0 inz(0)
    
         D data            s          65000A   inz(*BLANKS)
         D xml1            s          65000A   inz(*BLANKS)
         D xml2            s          65000A   inz(*BLANKS)
         D xml3            s          65000A   inz(*BLANKS)
         D xml4            s          65000A   inz(*BLANKS)
    
         D strstr          PR              *   ExtProc('strstr')
         D  pVal1                          *   Value options(*string)
         D  pVal2                          *   Value options(*string)
    
         D strlen          PR            10I 0 ExtProc('strlen')
         D  pVal                           *   Value options(*string)
    
         D writeIFS        PR            20I 0 ExtProc('write')     
         D   fd                          10I 0 value                       
         D   buf                           *   value
         D   size                        10I 0 value      
    
         D xmlfind         PR         65000A
         D  xml                            *   value
         D  nbr                          10i 0 value
         D  xbeg                         32A   value
         D  xbeg1                        32A   value
         D  xend                         32A   value
    
         D Main            PR                  ExtPgm('ZZVRYSQL') 
          *+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
          * main(): Control flow
          *+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
         D Main            PI 
          /free
           Monitor;       
    
           // -----
           // input
           //     P zzvary          B                   export
           //     D zzvary          PI            20A   varying
           //     D  myName                       10A   varying
           myIPC = '*NA';       
           myCtl = '*here';
           myXmlIn = 
             '<?xml version="1.0" encoding="ISO-8859-1"?>'                + x'0D'
           + '<script>'                                                   + x'0D'
           + '<pgm name="ZZSRV" lib="XMLSERVICE" func="ZZVARY">'          + x'0D'
           + '<parm>'                                                     + x'0D'
           + '<data type="10a" var="myName" varying="on">Ranger</data>'   + x'0D'
           + '</parm>'                                                    + x'0D'
           + '<return>'                                                   + x'0D'
           + '<data var="retName" type="20A" varying="on">Mud</data>'     + x'0D'
           + '</return>'                                                  + x'0D'
           + '</pgm>'                                                     + x'0D'
           + '</script>'                                                  + x'00';
           myXmlOut = *BLANKS; 
    
           // -----
           // sql call XMLSERVICE provided stored procedure(iPLUG4k -iPLUG15M)
           Exec Sql call XMLSERVICE/iPLUG4K(:myIPC,:myCtl,:myXmlIn,:myXmlOut);
    
           // -----
           // output (CGI)
    
           // -----
           // send header + end (LFLF)
           data = 'Content-type: text/html' + x'15' + x'15' + x'00';
           rn = writeIFS(1:%addr(data):strlen(%addr(data)));
           // -----
           // send return data       
           // HTML table
           data  = '<h3>RPG call XMLSERVICE</h3>'                 + x'0D';
           data  = %trim(data) + '<table border="1">'             + x'0D';
           data  = %trim(data) + '<th>Parameter name</th>'        + x'0D';
           data  = %trim(data) + '<th>Type value</th>'            + x'0D';
           data  = %trim(data) + '<th>Input value</th>'           + x'0D';
           data  = %trim(data) + '<th>Output value</th>'          + x'0D';
           for i = 1 to 2;
             xml1  = xmlfind(%addr(myXmlIn): i:'var=' :'"':'"');
             xml2  = xmlfind(%addr(myXmlIn): i:'type=':'"':'"');
             xml3  = xmlfind(%addr(myXmlIn): i:'<data':'>':'</data>');
             xml4  = xmlfind(%addr(myXmlOut):i:'<data':'>':'</data>');
             // HTML table row
             data  = %trim(data) + '<tr>'                         + x'0D';
             data  = %trim(data) + '<td>' + %trim(xml1) + '</td>' + x'0D';
             data  = %trim(data) + '<td>' + %trim(xml2) + '</td>' + x'0D';
             data  = %trim(data) + '<td>' + %trim(xml3) + '</td>' + x'0D';
             data  = %trim(data) + '<td>' + %trim(xml4) + '</td>' + x'0D';
             data  = %trim(data) + '</tr>'                        + x'0D';
           endfor;
           data  = %trim(data) + '</table>'                       + x'00';
           rn = writeIFS(1:%addr(data):strlen(%addr(data)));
    
           On-error;
           Endmon;
    
           return;
          /end-free
    
          *****************************************************
          * xmlfind
          *****************************************************
         P xmlfind         B
         D xmlfind         PI         65000A
         D  xml                            *   value
         D  nbr                          10i 0 value
         D  xbeg                         32A   value
         D  xbeg1                        32A   value
         D  xend                         32A   value
          * vars
         D i               s             10i 0 inz(0)
         D cbeg            s             33A   inz(*BLANKS)
         D cbeg1           s             33A   inz(*BLANKS)
         D cend            s             33A   inz(*BLANKS)
         D pbeg            s               *   inz(*NULL)
         D pend            s               *   inz(*NULL)
         D xmlFragment     s          65000A   inz(*BLANKS)
          /free
           cbeg = %trim(xbeg) + x'00';
           cbeg1 = %trim(xbeg1) + x'00';
           cend = %trim(xend) + x'00';
           pbeg = xml;
           for i = 1 to nbr;
             // <item stuff>123</item>
             // x
             if pbeg <> *NULL;
               pbeg = strstr(pbeg + 1:%addr(cbeg));
             endif;
           endfor;
           // <item stuff>123</item>
           //            x
           if pbeg <> *NULL;
             pbeg = strstr(pbeg:%addr(cbeg1));
           endif;
           if pbeg <> *NULL;
             // <item stuff>123</item>
             //             x  x
             pbeg += 1;
             pend = strstr(pbeg:%addr(cend));
             if pend <> *NULL and pend > pbeg;
               xmlFragment = %str(pbeg:pend - pbeg);
             endif;
           endif;
           return xmlFragment;
          /end-free
         P                 E
    

RPG client XMLSERVICE (DataQueue)

RPG program ZZQUESQL.PGM demonstrates client use of XMLSERVICE calling a CMDs and System APIs for Data Queue. As you read source code for ZZQUESQL.PGM, you will see it is nearly identical to previous example ZZRPGSQL.PGM.

DLTDTAQ DTAQ(XMLSERVICE/MYDATAQ)
CRTDTAQ DTAQ(XMLSERVICE/MYDATAQ) MAXLEN(100) 
***************************************
* Send Data Queue (QSNDDTAQ) API
***************************************
* 1 Data queue name     Input Char(10)
* 2 Library name        Input Char(10)
* 3 Length of data      Input Packed(5,0)
* 4 Data Input Char(*)  Input
***************************************
* Receive Data Queue (QRCVDTAQ) API
***************************************
* 1 Data queue name  Input Char(10)
* 2 Library name     Input Char(10)
* 3 Length of data   Input Packed(5,0)
* 4 Data Char(*)     Output
* 5 Wait time        Input Packed(5,0)
XMLSERVICE
> http://lp0364d:10022/cgi-bin/zzquesql.pgm

  • ZZQUESQL.PGM calling XMLSERVICE via Exec Sql call XMLSERVICE/iPLUG4K
         H AlwNull(*UsrCtl)
         H BNDDIR('QC2LE')
    
          * vars
         D myIPC           s           1024A   inz(*BLANKS)
         D myCtl           s           1024A   inz(*BLANKS)
         D myXmlIn         s           4096A   inz(*BLANKS)
         D myXmlOut        s           4096A   inz(*BLANKS)
    
         D i               s             10i 0 inz(0)
         D rn              s             10i 0 inz(0)
    
         D data            s          65000A   inz(*BLANKS)
         D xml1            s          65000A   inz(*BLANKS)
         D xml2            s          65000A   inz(*BLANKS)
         D xml3            s          65000A   inz(*BLANKS)
         D xml4            s          65000A   inz(*BLANKS)
    
         D strstr          PR              *   ExtProc('strstr')
         D  pVal1                          *   Value options(*string)
         D  pVal2                          *   Value options(*string)
    
         D strlen          PR            10I 0 ExtProc('strlen')
         D  pVal                           *   Value options(*string)
    
         D writeIFS        PR            20I 0 ExtProc('write')     
         D   fd                          10I 0 value                       
         D   buf                           *   value
         D   size                        10I 0 value      
    
         D xmlfind         PR         65000A
         D  xml                            *   value
         D  nbr                          10i 0 value
         D  xbeg                         32A   value
         D  xbeg1                        32A   value
         D  xend                         32A   value
    
         D Main            PR                  ExtPgm('ZZVRYSQL') 
          *+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
          * main(): Control flow
          *+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
         D Main            PI 
          /free
           Monitor;       
    
           // -----
           // input
           // ***************************************
           // * Send Data Queue (QSNDDTAQ) API
           // ***************************************
           // * 1 Data queue name     Input Char(10)
           // * 2 Library name        Input Char(10)
           // * 3 Length of data      Input Packed(5,0)
           // * 4 Data Input Char(*)  Input
           // ***************************************
           // * Receive Data Queue (QRCVDTAQ) API
           // ***************************************
           // * 1 Data queue name  Input Char(10)
           // * 2 Library name     Input Char(10)
           // * 3 Length of data   Input Packed(5,0)
           // * 4 Data Char(*)     Output
           // * 5 Wait time        Input Packed(5,0)
           myIPC = '*NA';       
           myCtl = '*here';
           myXmlIn = 
             '<?xml version="1.0" encoding="ISO-8859-1"?>'                + x'0D'
           + '<script>'                                                   + x'0D'
           + '<cmd error="fast">DLTDTAQ DTAQ(XMLSERVICE/MYDATAQ)</cmd>'   + x'0D'
           + '<cmd error="fast">CRTDTAQ DTAQ(XMLSERVICE/MYDATAQ) MAXLEN(100)</cmd>' 
           + x'0D'
           + '<pgm name="QSNDDTAQ">'                                      + x'0D'
           + ' <parm>'                                                    + x'0D'
           + '   <data type="10A" var="sndque">MYDATAQ</data>'            + x'0D'
           + ' </parm>'                                                   + x'0D'
           + ' <parm>'                                                    + x'0D'
           + '   <data type="10A" var="sndlib">XMLSERVICE</data>'         + x'0D'
           + ' </parm>'                                                   + x'0D'
           + ' <parm>'                                                    + x'0D'
           + '   <data type="5p0" var="sndlen">50</data>'                 + x'0D'
           + ' </parm>'                                                   + x'0D'
           + ' <parm>'                                                    + x'0D'
           + '   <data type="100A" var="snddata">i data queues</data>'    + x'0D'
           + ' </parm>'                                                   + x'0D'
           + '</pgm>'                                                     + x'0D'
           + '<pgm name="QRCVDTAQ">'                                      + x'0D'
           + ' <parm>'                                                    + x'0D'
           + '   <data type="10A" var="rcvque">MYDATAQ</data>'            + x'0D'
           + ' </parm>'                                                   + x'0D'
           + ' <parm>'                                                    + x'0D'
           + '   <data type="10A" var="rcvlib">XMLSERVICE</data>'         + x'0D'
           + ' </parm>'                                                   + x'0D'
           + ' <parm>'                                                    + x'0D'
           + '   <data type="5p0" var="rcvlen">50</data>'                 + x'0D'
           + ' </parm>'                                                   + x'0D'
           + ' <parm>'                                                    + x'0D'
           + '   <data type="100A" var="rcvdata">bad stuff</data>'        + x'0D'
           + ' </parm>'                                                   + x'0D'
           + ' <parm>'                                                    + x'0D'
           + '   <data type="5p0" var="rcvwait">0</data>'                 + x'0D'
           + ' </parm>'                                                   + x'0D'
           + '</pgm>'                                                     + x'0D'
           + '<cmd error="fast">DLTDTAQ DTAQ(XMLSERVICE/MYDATAQ)</cmd>'   + x'0D'
           + '</script>'                                                  + x'00';
           myXmlOut = *BLANKS; 
    
           // -----
           // sql call XMLSERVICE provided stored procedure(iPLUG4k -iPLUG15M)
           Exec Sql call XMLSERVICE/iPLUG32K(:myIPC,:myCtl,:myXmlIn,:myXmlOut);
    
           // -----
           // output (CGI)
    
           // -----
           // send header + end (LFLF)
           data = 'Content-type: text/html' + x'15' + x'15' + x'00';
           rn = writeIFS(1:%addr(data):strlen(%addr(data)));
           // -----
           // send return data       
           // HTML table
           data  = '<h3>RPG call XMLSERVICE</h3>'                 + x'0D';
           data  = %trim(data) + '<table border="1">'             + x'0D';
           data  = %trim(data) + '<th>Parameter name</th>'        + x'0D';
           data  = %trim(data) + '<th>Type value</th>'            + x'0D';
           data  = %trim(data) + '<th>Input value</th>'           + x'0D';
           data  = %trim(data) + '<th>Output value</th>'          + x'0D';
           for i = 1 to 9;
             xml1  = xmlfind(%addr(myXmlIn): i:'var=' :'"':'"');
             xml2  = xmlfind(%addr(myXmlIn): i:'type=':'"':'"');
             xml3  = xmlfind(%addr(myXmlIn): i:'<data':'>':'</data>');
             xml4  = xmlfind(%addr(myXmlOut):i:'<data':'>':'</data>');
             // HTML table row
             data  = %trim(data) + '<tr>'                         + x'0D';
             data  = %trim(data) + '<td>' + %trim(xml1) + '</td>' + x'0D';
             data  = %trim(data) + '<td>' + %trim(xml2) + '</td>' + x'0D';
             data  = %trim(data) + '<td>' + %trim(xml3) + '</td>' + x'0D';
             data  = %trim(data) + '<td>' + %trim(xml4) + '</td>' + x'0D';
             data  = %trim(data) + '</tr>'                        + x'0D';
           endfor;
           data  = %trim(data) + '</table>'                       + x'00';
           rn = writeIFS(1:%addr(data):strlen(%addr(data)));
    
           On-error;
           Endmon;
    
           return;
          /end-free
    
          *****************************************************
          * xmlfind
          *****************************************************
         P xmlfind         B
         D xmlfind         PI         65000A
         D  xml                            *   value
         D  nbr                          10i 0 value
         D  xbeg                         32A   value
         D  xbeg1                        32A   value
         D  xend                         32A   value
          * vars
         D i               s             10i 0 inz(0)
         D cbeg            s             33A   inz(*BLANKS)
         D cbeg1           s             33A   inz(*BLANKS)
         D cend            s             33A   inz(*BLANKS)
         D pbeg            s               *   inz(*NULL)
         D pend            s               *   inz(*NULL)
         D xmlFragment     s          65000A   inz(*BLANKS)
          /free
           cbeg = %trim(xbeg) + x'00';
           cbeg1 = %trim(xbeg1) + x'00';
           cend = %trim(xend) + x'00';
           pbeg = xml;
           for i = 1 to nbr;
             // <item stuff>123</item>
             // x
             if pbeg <> *NULL;
               pbeg = strstr(pbeg + 1:%addr(cbeg));
             endif;
           endfor;
           // <item stuff>123</item>
           //            x
           if pbeg <> *NULL;
             pbeg = strstr(pbeg:%addr(cbeg1));
           endif;
           if pbeg <> *NULL;
             // <item stuff>123</item>
             //             x  x
             pbeg += 1;
             pend = strstr(pbeg:%addr(cend));
             if pend <> *NULL and pend > pbeg;
               xmlFragment = %str(pbeg:pend - pbeg);
             endif;
           endif;
           return xmlFragment;
          /end-free
         P                 E