Working with Data Areas
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:
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 need to 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 noname 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:
