I2Rest Server CookBook DataArea - Revision history

Pavel.lobko at 11:42, 28 July 2020

2020-07-28T11:42:15Z

Alexei.baranov: /* How to use authorized access to Data Area */

2020-07-25T11:04:40Z

‎How to use authorized access to Data Area

Alexei.baranov: /* How to create API to access specific DTAARA object /

2020-07-25T11:02:52Z

‎How to create API to access specific *DTAARA object

Alexei.baranov at 10:51, 25 July 2020

2020-07-25T10:51:58Z

Alexei.baranov: Created page with "{{DISPLAYTITLE:Working with Data Areas}} Data areas on IBMi are typically used to store application settings, counter values, and other commonly used parameters. There are sev..."

2020-07-25T10:45:23Z

Created page with "{{DISPLAYTITLE:Working with Data Areas}} Data areas on IBMi are typically used to store application settings, counter values, and other commonly used parameters. There are sev..."

New page

{{DISPLAYTITLE: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:
* [https://www.ibm.com/support/knowledgecenter/en/ssw_ibm_i_71/apis/qwcrdtaa.htm QWCRDTAA - Retrieve Data Area]
* [https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_71/rtref/qxxchgd.htm QXXCHGDA - Change Data Area]

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

__TOC__

=Basic scenario=
We will use [[I2Rest_quick_config|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:
<nowiki><pcml version="1.0"></nowiki>

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

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

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

<nowiki></pcml></nowiki>
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 [[I2Rest_Basic_Test|here]]. We'll show Soap UI screen as an example:
[[File:QWCRDTAA.PNG]]

=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:
<nowiki><pcml version="1.0"></nowiki>

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

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

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

<nowiki></pcml></nowiki>
Test in SoapUI looks as follows:<br/>
[[File:QWCRDTAA noname.PNG]]

[[Category:API CookBook|Data Area API]]

@@ Line 91: / Line 91: @@
 =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 need to configure OAuth2 parameters. See [[Configuring_OAuth2_authorization|here]] how to do it
+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 [[Configuring_OAuth2_authorization|here how to do it]]
 [[Category:API CookBook|Data Area API]]

← Older revision		Revision as of 10:51, 25 July 2020
Line 90:		Line 90:
	[[File:QWCRDTAA noname.PNG]]		[[File:QWCRDTAA noname.PNG]]

		+	=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 need to configure OAuth2 parameters. See [[Configuring_OAuth2_authorization\|here]] how to do it
	[[Category:API CookBook\|Data Area API]]		[[Category:API CookBook\|Data Area API]]

@@ Line 55: / Line 55: @@
 . Restart i2Rest Server instance
-. Time to test! You can use any test client, some examples described [[I2Rest_Basic_Test|here]]. We'll show Soap UI screen as an example:
+. Time to test! You can use any test client, some examples described [[I2Rest_Basic_Test|here]]. We'll show Soap UI screen as an example:<br>
 [[File:QWCRDTAA.PNG]]