3.3.6 RPG Data Structure
RPG data structure support allows RPG programs to send and receive the single or multiple occurrence data structures between the RPG program and the current JSM service.
RPG programs can pass data structures to the JSM services these data structures appear as list or field list objects.
The RPG program can only pass a field list object or a list object with each command, a LANSA function can pass both a field list object and list object at the same time.
The JSMCMDX call is used to pass the data structure as a byte array.
If the command keyword SERVICE_STRUCTURE is present the byte array is converted into a JSMList or JSMFieldList object depending on other command keywords.
These objects are available from the JSMCMD object.
JSMList list = command.getList () ;
JSMFieldList fieldList = command.getFieldList () ;
If no SERVICE_STRUCTURE keyword is present then the data structure can be accessed by the getByteArray method.
byte[] data = command.getByteArray () ;
Reserved keywords
- SERVICE_STRUCTURE ( xxx ) - mandatory if a structure needs to be used.
- OCCURS ( nnn ) - mandatory for list
- SIZE ( nnn ) - mandatory for list
- COUNT ( nnn ) – optional for list, specifies the number of valid entries in the list.
Data structure as a list
To send a multiple occurrence data structure across to the JSM service as a list object, the programmer needs to include the keyword OCCURS.
- OCCURS keyword specifies the maximum number of entries in the list.
- COUNT keyword specifies the current number of entries in the list. Default is zero.
- SIZE keyword is required when an OCCURS keyword is used. This is used as a check against the calculated entry size.
- The byte array length must be equal to SIZE value times the OCCURS value.
Data structure as a field list
To send a data structure across to the JSM service as a field list object the programmer does not need to use the COUNT, OCCURS or SIZE keywords.
- COUNT keyword value defaults to one.
- OCCURS keyword value defaults to one.
- The byte array length must be equal to the calculated structure size.
Determining the layout of the structure
The value of the SERVICE_STRUCTURE keyword is used as a keyed lookup of the structure.properties file in the system sub-directory.
The value component of this property entry is the location of the XML file defining the structure layout.
#
# Java Service Manager structures
#
structure.demoxml.orderhead=structure/demoxml-orderhead.xml
structure.demoxml.orderline=structure/demoxml-orderline.xml
Example structure XML
<?xml version="1.0" encoding="UTF-8"?>
<rdml:structure xmlns:rdml="http://www.lansa.com/2000/XML/Function">
<rdml:field name="ORDER" type="S" length="10" />
<rdml:field name="NAME" type="A" length="50" />
<rdml:field name="STREET" type="A" length="50" />
<rdml:field name="CITY" type="A" length="50" />
<rdml:field name="STATE" type="A" length="5" />
<rdml:field name="ZIP" type="A" length="5" />
</rdml:structure>
Example RPG program
* Order head
D ORDERHEAD DS
D ORDER 10S 0 INZ(0)
D NAME 50 INZ(' ')
D STREET 50 INZ(' ')
D CITY 50 INZ(' ')
D STATE 5 INZ(' ')
D ZIP 5 INZ(' ')
D HEADSIZE C %SIZE(ORDERHEAD)
* Order lines, up to 10 lines
D ORDERLINE DS OCCURS(10)
D LINENUM 3S 0 INZ(0)
D PARTNUM 3S 0 INZ(0)
D PARTDSC 50 INZ(' ')
D PARTAMT 10P 2 INZ(0)
D PARTQTY 3P 0 INZ(0)
D LINEELEM C %ELEM(ORDERLINE)
D LINESIZE C %SIZE(ORDERLINE)
This command will receive the single field values into the ORDERHEAD structure:
RECEIVE HANDLER(IXML) XSL(RECEIVEORDER) SERVICE_STRUCTURE(DEMOXML.ORDERHEAD)
This command will receive the multiple order lines into the ORDERLINE structure:
RECEIVE HANDLER(IXML) XSL(RECEIVEORDER) SERVICE_STRUCTURE(DEMOXML.ORDERLINE) SIZE(64) OCCURS(10)
The data structure names do not need to match the names in the structure XML file, it is only the data type and position that are used.
The structure XML names need to match the field names in the XSL file.
The shipped RPG example QRPGLESRC/DEMOXML illustrates how to send and receive data structures.