How to Call an IBM i API Using newlook Remote Procedure Call (RPC)
The API we use in this example is The Retrieve System Status (QWCRSSTS) API which allows you to retrieve various groups of statistics that represents the current status of the system. We will start by looking at the API parameter list. Figure1, below, shows the parameters to be passed with QWCRSSTS API.
Figure 1 (above): Parameters of Retrieve System Status (QWCRSSTS) API
When the QWCRSSTS API is called with the format name value “SSTS0200”, it will return the system status which is similar to the command DSPSYSSTS. See the Required Parameter Group item 3 (Format name) in Figure1.
SSTS0200 Format
The Receive Variable has the following data structure when the API is called with “SSTS0200” format.
Figure 2: SSTS0200 Format
Step 1 – Design a Form
Design the form with a button to call the API and a grid to show the result from the API.
Figure 3: A test form
Create a new form add controls and assign properties using newlook Designer.
Figure 4: Retrieve System Status Command Button
The button’s OnClick event is used to call the function “retrieveSystemStatus” in the script module “Rpc”. You can find more details of this function later.
Figure 5: Retrieve System Status Grid Control
The grid contains two columns – “System Statistics” and “Value”. Click the button in the Columns Collection property () to define the columns. See Figure 6.
Figure 6: DataGrid Column Editor
Step 2 – Macro and Script
This example uses a Macro module for declaring the API with the SSTS0200 data format type and a Script module for consuming the API. The source code for these modules are given below you can simply do a copy / paste to newlook Macro Editor and Script Editor. When creating the script module please select JScript for the Language.
Macro - DeclareApiFormatName
Figure 6: DeclareApiFormatName – Macro Module
This macro is simply defining the SSTS0200 data Format using newlook TYPE Action and the parameters of the QWCRSSTS API which can be found in Figure 1 and Figure 2.
Line #1:
Label |
QWCRSSTS_SSTS0200 |
The label name “QWCRSSTS_SSTS0200” is defined to group the actions from line 1 to 5 in the macro module.
Line #2 Arguments:
Action |
Type |
Name |
typeSystemStatus |
Elements |
BytesAvailable as Long, BytesReturned as Long, CurrentDateTime as String * 8, SystemName as String * 8, ElapsedTime as String * 6, StateFlag as String * 1, Reserved as String * 1, ProcessingUnitUsed as Long, JobsInSystem as Long, PermanentAddress as Long, TempAddress as Long, SystemASP as Long, ASPUsed as Long, AuxStorage as Long, CurrentUnprotectedStorage as Long, MaxUnprotectedStorage as Long, DBCapability as Long, MainStorageSize as Long, Partitions as Long, PartitionID as Long, Reserved2 as Long, ProcessingCapacity as Long, SharingAtt as String * 1, Reserved3 as String * 3, NumProcessors as Long, ActiveJobs as Long, ActiveThreads as Long, MaxJobs as Long, Temp256Seg as Long, Temp4GSeg as Long, Perm256Seg as Long, Perm4GSed as Long, CurrentInteractivePer as Long, UncappedCPUUsed as Long, SharedProcPoolUsed as Long, MainStorageSizeLong as Long |
TYPE action is similar to RPG DS (Data Structure). The variable “typeSystemStatus” will break the received output value of the parameter “Receiver Variable” from the API into subfields of the format “SSTS0200” – See Figure 1. The Figure 7 shows variables used in the macro against fields of “SSTS0200” Format.
Figure 7: newlook variables
Line #3 Arguments:
|
Action |
Dim |
|
Variable |
varReceiverVariable |
|
Type |
typeSystemStatus |
DIM declares a variable for the output parameter “Receiver Variable” with “typeSystemStatus” which is a user defined data type for the format “SSTS0200”.
Line #4 Arguments:
|
Action |
RPCDeclare |
|
Connection |
objConnection |
|
Library |
*LIBL |
|
Procedure |
QWCRSSTS |
|
Alias |
RetrieveSystemStatus |
|
Returns |
|
|
Arguments |
Output SystemStatus as typeSystemStatus, Input prmReceiverLength as Long, Input prmFormat as String * 8, Input prmResetStatusStat as String * 10, InputOutput prmErrorCode as String * 8 |
RPCDeclare Action describes the “QWCRSSTS” API we are calling.
Connection: The connection object “objConnection” will be used to call the API.
Library & Procedure: Procedure is the name of the “QWCRSSTS” API and we use the library list (*LIBL) of the user profile which is defined on the connection.
Alias: We will use this alias name in the script as this is easier to read.
Returns: The API is not using the Return variable. It will retrieve the result from the Receiver variable parameter of the API which is defined in the macro arguments as the “SystemStatus” output field.
Arguments: You can think of the last parameter “Arguments” for RPCDecalre Action as RPG PR (Proto Type) which describes the parameters required by the API. It is similar to an RPG PR statement only the filed data type and length are important. See Figure 8.
|
Type |
Field |
newlook |
|
Output Char(*) |
Receiver variable |
Output SystemStatus as typeSystemStatus |
|
Input Binary(4) |
Length of receiver variable |
Input prmReceiverLength as Long |
|
Input Char(8) |
Format name |
Input prmFormat as String * 8 |
|
Input Char(10) |
Reset status statistics |
Input prmResetStatusStat as String * 10 |
|
I/O Char(*) |
Error Code |
InputOutput prmErrorCode as String * 8 |
Figure 8: RPCDeclare Arguments parameter
Line #5:
Action |
StopMacro |
This stops the current macro.
In the name field call the macro “DeclareApiFormatName” and save the changes.
Script – Rpc
Figure 9: Rpc - Script Module
Copy all functions below into the Rpc JScript module to test. The Jscript is case-sensitive, so be careful of the case.
The function “alert” is created to use “App.Message” method as a JavaScript alert.
The function “retriveSystemStatus” will be called when the button “Retrieve System Status” is clicked. See Figure 4. This function acts like a mainline in RPG.
The “closeConnection” function will close the connection used for RPC call.
The “openConnection” function will create “objConnection,” the connection object for RPC call.
The “callRpcRetrieveSystemStatus” function calls the “DeclareApiFormatName.QWCRSSTS_SSTS0200” Macro which defines the return data structure and the API parameters. After calling the API it will retrieve API’s return data and insert them into the Form’s Grid (gridSystemStatus).
Connections
This example uses a predefined connection. Create a “connRpc” connection to access your IBM i. See Figure 10.
Figure 10: Connections
Summary
We recommend creating newlook RPC modules instead of RPG programs when you want to call API’s from newlook solution. This example specifically shows how to deal with API parameters. Calling the API is quite easy once the API parameters are defined properly.
If you would like a sample of the above RPC modules, simply send a request to support@freschelegacy.com
References
RPC Calling IBM i Command and Store Procedure
