4/9/2012

1

Brian MayBrian MayyyIBM IBM ii Modernization SpecialistModernization Specialist

Profound Logic SoftwareProfound Logic Software

Webmaster  and Coordinator Webmaster  and Coordinator Young Young ii ProfessionalsProfessionals

Overview What is XMLSERVICE?What is XMLSERVICE?

Use cases

Access Methods

Overview of XML syntax used

Simple Examples

4/9/2012

2

And why do I care?

What is it? Created as part of a partnership with ZendCreated as part of a partnership with Zend

Part of Zend’s new PHP Toolkit for IBM i

Allows any program or utility on your IBM i to be utilized using simple XML

Once configured, any program or service program can be accessed without any additional set up.y p

Allows access to programs, service programs, PASE shell, or CL commands.

4/9/2012

3

What is it?

Why is it different? Written in 100% RPGLE codeWritten in 100% RPGLE code

Open Source – BSD licensed to be completely free to use

All communication, in and out, is done using XML documents

Can be used in 1 tier and 2 tier environments

1 tier – All code running on single IBM i

2 tier – Applications on other systems, and even different platforms, accessing IBM i programs

4/9/2012

4

Why is it different? RPG programs can maintain statep g

XML string conversion to parameters in/out and ASCII/EBCDIC conversions handled automatically

Support for complex parameters Arrays

Data Structures

Data Structure Arrays Data Structure Arrays

Complex Data Structures

Commands and program calls can be scripted to run in order within the XML string

That all sounds cool, but when would I want to use it?

4/9/2012

5

Use Cases

Zend Toolkit

The new toolkit from Zend will rely on XMLSERVICE for access to IBM i resources

Still in Beta

Will allow access from web servers outside your IBM i

Also open source

Use Cases Subprocedures with return valuesSubprocedures with return values

Virtually all interfaces from other non‐ILE languages do not support return values of any type but integer

This meant writing wrappers for these procedures to be used by other languages or avoiding return values altogether, thus missing out on a powerful feature

XMLSERVICE allo s return  alues to be retrie ed using  XMLSERVICE allows return values to be retrieved using the <return> tag

4/9/2012

6

Use Cases Languages with no existing interface to IBM iLanguages with no existing interface to IBM i

Most modern programming languages have some mechanism to connect to an SQL database

Most modern programming languages have some mechanism to consume a web service

XMLSERVICE supports both of these scenarios

h b l d b ll This opens up your IBM i to be utilized by virtually any application

Use Cases Secured Web ServicesSecured Web Services

XMLSERVICE, no matter which protocol is used to access it, requires a valid IBM i user name and password

This allows you to control access to your system using object authorities, just like you would for local access

This also allows your applications to have a user profile for internal permissions and auditingfor internal permissions and auditing

4/9/2012

7

How does an application hook into XMLSERVICE?

DB2 Stored Procedures When available, the DB2 stored procedures included When available, the DB2 stored procedures included in XMLSERVICE are the preferred access method

These stored procedures can be accessed via ODBC, JDBC, DB2 Connect, etc

Eliminate the need to create separate stored procedures for every program needed

4/9/2012

8

DB2 Stored Procedures

DB2 Stored Procedures These stored procedures accept four standard These stored procedures accept four standard parameters

IPC Key – This is a path to a folder in the /tmp IFS directory that will be used to route XML input and output to the correct XMLSERVICE job

Commonly used value would be /tmp/UserName

Must be fully qualified IFS path Must be fully qualified IFS path

Max length of 1024 characters

4/9/2012

9

DB2 Stored Procedures CTL – This parameter allows the calling program to pass p g p g pin special codes to control the XMLSERVICE job’s behavior

*debug – stops the server with a message to QSYSOPR to allow the developer to debug the job

*immed – ends the XMLSERVICE job immediately

*fly/*nofly – enables/disables XMLSERVICE’s “flight recorder”.  This feature logs performance information for review

DB2 Stored Procedures CLOB In – This parameter is the XML input documentp p

More on the XML syntax later

CLOB Out – This parameter will receive the XML output containing the parameters returned from your program or status messages for command line commands

4/9/2012

10

REST (Web Service) Interface When accessing DB2 directly is not possible or undesirable, g y p ,XMLSERVICE supports a simple REST interface

REST allows any application to access IBM i using simple HTTP GET or POST requests

Requires a small modification to the httpd.conf file of your IBM i HTTP server, typically as follows

S i tAli / i bi / /QSYS LIB/XMLSERVICE LIB/ScriptAlias /cgi-bin/ /QSYS.LIB/XMLSERVICE.LIB/ <Directory /QSYS.LIB/XMLSERVICE.LIB/> AllowOverride None order allow,denyallow from all SetHandler cgi-script Options +ExecCGI

</Directory>

REST (Web Service) Interface

4/9/2012

11

REST (Web Service) Interface The XMLSERVICE REST interface requires seven qparameters

db2 – this parameter is the database name to be accessed (*LOCAL or name of SQL database)

uid – this parameter should contain the IBM i user id

pwd – this parameter should contain the password for user id

ipc – same as DB2 stored procedureipc same as DB2 stored procedure

ctl – same as DB2 stored procedure

xmlin – XML input document

xmlout – maximum expected size of XML document returned in bytes

How to talk to IBM i using just XML

4/9/2012

12

XML Syntax Calling programs or running commands via Calling programs or running commands via XMLSERVICE is all done via XML

One XML input document can contain multiple commands, program calls, subprocedure calls, etc.

This allows you to use your XML document like a script

Easily set your library list or run a data loading program before calling the program that will return output

XML Syntax XML tags and attributes not used by XMLSERVICE are XML tags and attributes not used by XMLSERVICE are passed along and included in the XML output 

This allows you to add any extra markup needed for parsing returned XML

Also allows addition of comments that will flow with the XML data for debugging purposes

4/9/2012

13

XML Definitions Call an IBM i command

<cmd> Any IBM i command here </cmd>

Example:  <cmd>ADDLIBLE LIB(XMLSERVICE)</cmd>

Your command will have the same format as if you typed them on a command line

Call a PASE utility <sh [rows=‘on|off’]> PASE command </sh> <sh [rows= on|off ]> PASE command </sh>

Example: <sh>mysqldump –u root ‐‐alldatabases > /folder/backup.sql</sh>

Slower than <cmd> because a new PASE job is spawned (this is standard Unix behavior)

XML Definitions Call Program or SubprocedureCall Program or Subprocedure

<pgm name=‘ProgName’ [lib=‘LibName’ func=‘SubProc’]> Parameter Details </pgm>

“lib” and “func” attributes are optional

Parameters

<parm [io=‘in|out|both’ by=‘val|ref’]> Define Data </parm>

Used to mark standard program parameters

“io” and “by” attributes are optional

4/9/2012

14

XML Definitions Return ValueReturn Value

<return> Define Data </return>

Used to mark a return value from a subprocedure

Data Structures

<ds [dim=‘elements’ dou=‘label’> Define Subfields </ds>

“dim” attribute used to create a data structure array

“dou” attribute used to point to a parameter that contains the number of elements actually returned.  This helps when parsing results later.

XML Definitions Data ElementsData Elements

<data type=‘data type’ [dim=‘elements’ varying=‘on|off’]> Value </data>

“dim” attribute used to denote an array

“varying” attribute used to denote a varying length character field

Data Types

Character

type=‘Na’ – Example <data type=‘32a’>

4/9/2012

15

XML Definitions Data Typesyp

Packed Decimal

type=‘NpN’ – Example <data type=‘12p2’>

Zoned Decimal

type=‘NsN’ – Example <data type=’12s2’>

Signed Integer

type=‘NiN’ – Example <data type=’10i0’>yp p yp

Unsigned Integer

type=‘NuN’ – Example <data type=’10u0’>

Floating Point

type=‘Nf’ – Example <data type=‘8f’>

Example – Simple Program Call Program Entry List

D INCHARA S 1aD INCHARB S 1aD INDEC1 S 7p 4 D INDEC2 S 12p 2*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++* main(): Control flow*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++C *E t PLISTC *Entry PLIST C PARM INCHARAC PARM INCHARBC PARM INDEC1C PARM INDEC2

4/9/2012

16

Example – Simple Program Call XML In

<?xml version='1.0'?><script><cmd comment='addlible'>ADDLIBLE LIB(XMLSERVICE) POSITION(*FIRST)</cmd><pgm name=‘MYPGM'><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'>0</data>

</parm><parm io='both'><data type='12p2' var='INDEC2'>0</data>

</parm></pgm></script>

Example – Simple Program Call XML Out

<?xml version='1.0'?><script><cmd comment='addlible'>+++ success ADDLIBLE LIB(XMLSERVICE) POSITIO</cmd><pgm name=‘MYPGM'><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></pgm></script>

4/9/2012

17

Example – Something Complex Subprocedure Prototype

D name_t ds qualified based(Template)D dsMyFirst 32A varyingD dsMyMid 32A varyingD dsMyLast 32A varying

D job_t ds qualified based(Template)D dsMyHire D datfmt(*iso)D dsMyLeav D datfmt(*iso)D dsMyJob 64A varyingD dsMyPay 12p 2D dsMyPay 12p 2

D JOBSMAX c const(3)

D emp_t ds qualified based(Template)D myName likeds(name_t)D myJob likeds(job_t) dim(JOBSMAX)

D get_employee PR likeds(emp_t)D emp_ID 32A

Example – Something Complex XML In

<?xml version="1.0"?><script><pgm name=‘HRSRVPGM' func=‘GET_EMPLOYEE'><parm var=‘emp_id'><data type='32A‘>A12345</data>

</parm><return><ds var=‘emp_t'><ds var=‘name_t'><data type='32A' varying='on' var='first'>na</data><data type='32A' varying='on' var='middle'>na</data><data type='32A' varying='on' var='last'>na</data>

</ds><ds dim='3' var='job_t'><data type='10a' var='begin'>na</data><data type='10a' var='end'>na</data><data type='64a' varying='on' var='job'>na</data><data type='12p2' var='salary'>0.0</data>

</ds></ds>

</return></pgm>

</script>

4/9/2012

18

Example – Something Complex XML Out

<?xml version="1.0"?><script>

<pgm name=‘HRSRVPGM' func=‘GET_EMPLOYEE'><parm var=‘emp_id'><data type='32A‘>A12345</data>

</parm><return><ds var=‘emp_t'>

<ds var=‘name_t'><data type='32A' varying='on' var='first'>John</data>yp y g /<data type='32A' varying='on' var='middle'>Q</data><data type='32A' varying='on' var='last'>Doe</data>

</ds><ds dim='3' var='job_t'>

<data type='10a' var='begin‘>1990-05-07</data><data type='10a' var='end'>1994-07-04</data><data type='64a' varying='on' var='job'>Custodian</data><data type='12p2' var='salary'>12000.00</data>

</ds>

Example – Something Complex XML Out (Continued)

<ds dim='3' var='job_t'><data type='10a' var='begin‘>1994-07-05</data><data type='10a' var='end‘>2002-10-31</data><data type='64a' varying='on' var='job‘>Plant Manager</data><data type='12p2' var='salary‘>35890.25</data>

</ds> <ds dim='3' var='job_t'><data type='10a' var='begin‘>2002-11-01</data><data type='10a' var='end‘>2011-07-22</data><d t t '64 ' i ' ' 'j b‘>Chi f Fi i l Offi </d t ><data type= 64a varying= on var= job‘>Chief Financial Officer</data><data type='12p2' var='salary‘>1000000.00</data>

</ds> </ds>

</return></pgm>

</script>

4/9/2012

19

It’s time for a demo

RPG ProgramH AlwNull(*UsrCtl)

D Step s 10i 0 inz(0)D INCHARA S 1aD INCHARB S 1aD INDEC1 S 7p 4D INDEC2 S 12p 2

D INDS1 DSD DSCHARA 1aD DSCHARB 1aD DSDEC1 7p 4D DSDEC2 12p 2*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++* i (): C t l fl* main(): Control flow*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++C *Entry PLISTC PARM INCHARAC PARM INCHARBC PARM INDEC1C PARM INDEC2C PARM INDS1

4/9/2012

20

RPG Program/free

Step +=1;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

HTTP Source This is an extremely simple web page that calls a This is an extremely simple web page that calls a program using XMLSERVICE’s REST interface

The page consists of a form with hidden parameters and a submit button

This page calls program ZZCALL in the XMLSERVICE library.  This program is included when you install XMLSERVICE, so this example can be used on your system as a simple test

4/9/2012

21

HTTP Source<html>

<body><body>

<form name="input" action="/cgi-bin/xmlcgi.pgm" method="post">

<input type="hidden" name="db2" value="*LOCAL">

<input type="hidden" name="uid" value="MYUID">

<input type="hidden" name="pwd" value="MYPASSWO">

<input type="hidden" name="ipc" value="/tmp/rangerhtml">

<input type="hidden" name="ctl" value="*none">

<input type="hidden" name="xmlin"

value="<?xml version='1 0'?>value= <?xml version= 1.0 ?>

<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>

HTTP Source<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>">

<input type="hidden" name="xmlout" value="32768">

<input type="submit" value="Submit" />

</form>

</body>

</html>

4/9/2012

22

XML Data Returned<?xml version='1.0'?><pgm name='ZZCALL' lib='XMLSERVICE'><pgm name= ZZCALL lib= XMLSERVICE >

<parm><data type=‘1A’>C</data></parm> <parm><data type=‘1A’>D</data></parm> <parm><data type=‘7p4’>321.1234</data></parm> <parm><data type=‘12p2’>1234567890.12</data></parm> <parm> <ds>

<data type=‘1A’>E</data> <data type=‘1A’>F</data> <data type=‘7p4’>333.3330</data><data type 7p4 >333.3330</data> <data type=‘12p2’>4444444444.44</data>

</ds> </parm> <return><data type=‘10i0’>0</data></return>

</pgm>

4/9/2012

23

About the PresenterAbout the PresenterBrian May is an IBM Brian May is an IBM ii Modernization Specialist for Profound Modernization Specialist for Profound Logic Software.  He is also webmaster and coordinator for the Logic Software.  He is also webmaster and coordinator for the Young Young ii Professionals (Professionals (http://www.youngiprofessionals.comhttp://www.youngiprofessionals.com).  ).  He is a husband and father of two beautiful girls.  Brian can be He is a husband and father of two beautiful girls.  Brian can be ggreached at bmay@profoundlogic.com.reached at bmay@profoundlogic.com.