How to Call an IBM i API Using newlook Remote Procedure Call (RPC)

Posted by Francisco Hoya on Nov 12, 2015 12:50:28 PM

    

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.

Screen_Shot_2015-11-12_at_4.16.25_PM.png

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.

hoya1.png

 Figure 3: A test form

Create a new form add controls and assign properties using newlook Designer.

hoya2.png

 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.

 

 hoya3.png

 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.

 

 hoya4.png

 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

 

hoya5.png

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.

 Screen_Shot_2015-11-12_at_4.17.47_PM.png

 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 “QWCRSSTSAPI we are calling.

Connection: The connection objectobjConnection 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

 

hoya6.png

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 useApp.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.

 

 

 ThecloseConnection 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.

 

 hoya7.png

Figure 10: Connections

 Summary

hoya8.png

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 [email protected]

 

References

The Retrieve System Status

RPC Calling IBM i Command and Store Procedure

 




 

 

 

 

 

 

 

 

 

 

 

Topics: IBM i, newlook, RPC, ibmi, remote procedure call, IBM i API