I2Rest Server CookBook DataArea

Data areas on IBMi are typically used to store application settings, counter values, and other commonly used parameters. There are several IBM i API for working with data areas:

• QWCRDTAA - Retrieve Data Area
• QXXCHGDA - Change Data Area

We'll demonstrate here how to wrap Retrieve Data Area API to OpenAPI.

Basic scenario

We will use basic setup as a starting point of this scenario.

1. Create demo *DTAARA object:

CRTDTAARA DTAARA(QGPL/DEMODATA) TYPE(*CHAR) LEN(100) VALUE('Demo data')

2. Create text file on IFS file system, for example /usr/PCML/DataArea.pcml and enter following text:

<pcml version="1.0">

  <struct name="qualifiedName">
     <data name="name"            type="char" length="10" />
     <data name="library"         type="char" length="10" />
  </struct>

  <struct name="dataReturned">
     <data name="bytesAvailable"          type="int"  length="4" />
     <data name="bytesReturned"           type="int"  length="4" />
     <data name="typeValueReturned"       type="char" length="10" />
     <data name="libraryName"             type="char" length="10" />
     <data name="lengthValueReturned"     type="int"  length="4" />
     <data name="numberDecimalPositions"  type="int"  length="4" />
     <data name="data"                    type="char" length="lengthValueReturned" />
  </struct>

  <program name="QWCRDTAA" path="/QSYS.LIB/%LIBL%.LIB/QWCRDTAA.PGM">
     <data name="outputData"        usage="output"   type="struct" struct="dataReturned" outputsize="9999"/>
     <data name="outputDataLength"  usage="input"    type="int"    length="4"  init="9999"/>
     <data name="dataArea"          usage="input"    type="struct" struct="qualifiedName"/>
     <data name="startingPosition"  usage="input"    type="int"    length="4"/>
     <data name="dataLength"        usage="input"    type="int"    length="4"/>
     <data                          usage="input"    type="int"    length="4" init="0"/>
  </program>
  
</pcml>

3. Add following setting to your i2Rest Server configuration json:

   "pcmls":
   [
      ...,
      {
         "pcml_mount"         : "dataarea",
         "pcml_file"          : "/usr/PCML/DataArea.pcml", 
         "valid_in_anonymous" : true
      }
   ]

4. Restart i2Rest Server instance

5. Time to test! You can use any test client, some examples described here. We'll show Soap UI screen as an example:

How to create API to access specific *DTAARA object

The above example allows you to access any data area - just specify the object name. This scenario is not always valid from a security reasons. It is often necessary to get data from a specific data area, without the possibility of specifying its name in the request. To do this, you need to make small changes in the PCML file - you must specify the name of the data area and remove this parameter from the input parameters. Look at the example, pay attention to initial values in qualifiedName structure and to anonymous parameter at third position in the parameter list:

<pcml version="1.0">

  <struct name="qualifiedName">
     <data name="name"            type="char" length="10" init="DEMODATA"/>
     <data name="library"         type="char" length="10" init="QGPL"/>
  </struct>

  <struct name="dataReturned">
     <data name="bytesAvailable"          type="int"  length="4" />
     <data name="bytesReturned"           type="int"  length="4" />
     <data name="typeValueReturned"       type="char" length="10" />
     <data name="libraryName"             type="char" length="10" />
     <data name="lengthValueReturned"     type="int"  length="4" />
     <data name="numberDecimalPositions"  type="int"  length="4" />
     <data name="data"                    type="char" length="lengthValueReturned" />
  </struct>

  <program name="QWCRDTAA" path="/QSYS.LIB/%LIBL%.LIB/QWCRDTAA.PGM">
     <data name="outputData"        usage="output"   type="struct" struct="dataReturned" outputsize="9999"/>
     <data name="outputDataLength"  usage="input"    type="int"    length="4"  init="9999"/>
     <data                          usage="input"    type="struct" struct="qualifiedName"/>
     <data name="startingPosition"  usage="input"    type="int"    length="4"/>
     <data name="dataLength"        usage="input"    type="int"    length="4"/>
     <data                          usage="input"    type="int"    length="4" init="0"/>
  </program>
  
</pcml>

Test in SoapUI looks as follows:

How to use authorized access to Data Area

The above scenario describes an anonymous access to data area. If you need authorized access to data, you must configure OAuth2 parameters of your i2Rest Server instance. Look here how to do it