With GI.bench setup, a small tool called “gins-rpcutil.exe” is installed. This tool implements a XML-RPC client and offers the possibility to use/call/communicate with all XML-RPC APIs provided by Gantner Instruments just with command line parameters. So it is not necessary to have a client implemented. This can be used for example to program scripted API calls in batch files, or if you need to interface the APIs in program languages, which were (maybe not yet) provided as client sorce files (as for C++, C# and Pascal).
Usage
If you run the “gins-rpcutil.exe” in your command window, it will give you a list of valid options:
usage: gins-rpcutil OPTIONS
/help display help information on command line arguments
/execute performs a rpc execution (relevant params: port, server, method, file, file1)
/compare compares a rpc value against a reference value (modes: 0 = compatibility, 1 = equal compatible member, 2 = copletely identical, 3 = tbd
/file-read copy files from rpc server (use srcFile and destFile
/file-write copy files to rpc server (use srcFile and destFile
/file-list list files on rpc server (use destFile
/file-delete delete files from rpc server (use destFile
/params performs a rpc params request (relevant params: port, server, method, file)
/list list members of an rpc value
/count get size of an array rpc value
/get-val get a value from an rpc value
/get-string get a value from an rpc value as raw string
/set-val set a value to an rpc value
/version display version information
/port=port port number (default: 1200)
/server=server host name or ip address as string (default: 127.0.0.1)
/method=method rpc method name (including route path if needed or no path if specified with path option)
/rpcpath=rpcpath path for rpc server (default: \"\" (no path))
/value=value rpc value to be sent by rpc execute as string
/srcFile=srcFile specifies a input file path
/refFile=refFile specifies an reference file
/destFile=destFile specifies an output file path
/name=name specifies the name in a rpc value to be handled
/index=index specifies index to be used by commands like rpcvalue-get / rpcvalue-set
/mode=mode specifies a command specific mode value (described per command)
/tagset=tagset specifies tagset for writing an XmlRpc value (0=XML - long, 1=Xml-Short, 2=Json, 3=Json-Pretty)
/timeout=timeout specifies timeout for rpc communication in seconds (default=10)
/permissive be permissive against invalid state responses ( default: exit with error if ReturnState is invalid )
Procedure
Most efficient way to work with the APIs and with the util, is to first inspect the API methods using GI.monitor. There are some step-by-step descriptions in DokuWiki available for common procedures with GI.config or GI.com APIs.
You need to know, that the structs used in the Gantner Instruments XML-RPC APIs are defined in GInsXmlRpcStdAPI. In the example below, the struct of “Interface” is of type “ElementSelectionList”. The “value” of this type is of type “ElementValue”, which again has a unique “value”, that has to be set for execution of the method (the server only evaluates the “value” of an element/struct, not the “description” or other elements in the list)
Get Method Parameters
In general, most of the XML-RPC API-methods are executed with parameters. So the first step to execute a method is to read the parameters of a method, and save them to a file, usually next to the EXE file. Therefore use the command line parameter
-
/params
Example:
gins-rpcutil.exe /params /port=8090 /server=localhost /method=DeviceConfigAPI.StartDeviceScan /rpcpath=GI.com /destFile=paramfile.json /tagset=3
-
Command line parameters
/serverand/portare the connection parameters of the XML-RPC Server. If you are working with GI.bench (GI.service) on your PC, these could be for example “localhost” and “8090” (same as you use in GI.monitor to connect) -
As
/method, please use it like <Api-Name>.<Method-Name>. For example:/method=DeviceConfigAPI.StartDeviceScan -
The
/rpcpathfor this example would be:/rpcpath=GI.com. This is because the method “StartDeviceScan” is part of “GI.com → DeviceConfigAPI”. Since we are connected to GI.service, the method is available through the “route” (path) “GI.com” -
The parameters of the desired method are now saved into a file, specified in
/destFile=paramfile.json(/tagset=3defines the tagset for writing the file, here it is Json-Pretty)
If you run this example in a command line window (GI.bench is running), you will get a result file “paramfile.json” beside your gins-rpcutil.exe.
{
"Filter": [],
"Interface": {
"_id": "0.200",
"List": [{
"_id": "0.1",
"Description": "Network Controller",
"Value": "TyNwCntrl"
},
{
"_id": "0.1",
"Description": "Network Controller IPv6",
"Value": "TyNwCntrl_IPv6"
},
{
"_id": "0.1",
"Description": "Network Controller All",
"Value": "TyNwCntrl_All"
},
{
"_id": "0.1",
"Description": "LocalRPC",
"Value": "TyLoRpc"
},
{
"_id": "0.1",
"Description": "Localbus Transparent Port",
"Value": "TyLbTransPort"
},
{
"_id": "0.1",
"Description": "Localbus UART",
"Value": "TyLbUART"
},
{
"_id": "0.1",
"Description": "Remote Controller",
"Value": "TyRemCntrl"
}],
"PresType": "",
"Value": {
"_id": "0.1",
"Description": "Network Controller",
"Value": "TyNwCntrl"
}
},
"MethodID": "DeviceConfigAPI::StartDeviceScan"
}
You can compare this example by using GI.monitor. You can see the
-
RpcPath (Route)
-
API Name
-
Method
-
Parameters, provided by this method (also called using “GetParams” by GI.monitor)
Set Values
After you got the method parameters in a file as described, you can now use the gins-rpcutil.exe to set your parameter values in the file. To set a value, you always use
-
/set-val- as gins-rpcutil.exe parameter so set a parameter-value -
/name- this is the parameter name in the file -
/value- the new value you want to set for the parameter. Instead of/valueyou can also use/srcFileto set a value out of an existing file (see “Get Values”) -
/destFile- the filename of the parameters (as used in the example here: paramfile.json)
Example:
You can use:
gins-rpcutil.exe /set-val /value="<value>TyRemCntrl</value>" /name=Interface/Value/Value /destFile=paramfile.json /tagset=3
or
gins-rpcutil.exe /set-val /value=\"TyRemCntrl\" /name=Interface/Value/Value /destFile=paramfile.json /tagset=3
→ escape the quotation marks with ' \ '.
This example will set the value for “Interface → Value → Value” to “TyRemCntrl” in the paramfile.json. It looks like (here the list entries are replaced with “…”):
paramfile.json{
"Filter": [],
"Interface": {
"_id": "0.200",
"List": [{
...
}],
"PresType": "",
"Value": {
"_id": "0.1",
"Description": "Network Controller",
"Value": "TyRemCntrl"
}
},
"MethodID": "DeviceConfigAPI::StartDeviceScan"
}
Get Values
Sometimes it is necessary to read values out of a parameter file, and save it into another file. For example some Object IDs, Connection-Tokens, return-states …
To get a value out of a parameter-file, use:
-
/get_val- as gins-rpcutil.exe parameter so get a parameter-value (also/get-stringcan be used to read strings without quotation marks) -
/srcFile- defines the source filename, here paramfile.json -
/destFile- defines the destination filename (in the example: value.json) -
/name- this is the parameter name in the file
Example:
gins-rpcutil.exe /get-val /name=Interface/Value/Value /destFile=value.json /srcFile=paramfile.json /tagset=3
This example reads the actual value of “Interface → Value → Value” and generate a file with the result:
value.json"TyNwCntrl"
Compared this example with using /get-string:
gins-rpcutil.exe /get-string /name=Interface/Value/Value /destFile=value.json /srcFile=paramfile.json /tagset=3
will write the stirng into the file as:
value.jsonTyNwCntrl
It is now possible to use that file to “Set Values” back into a parameter-file using set-val, for example:
gins-rpcutil.exe /set-val /srcFile=value.json /name=Interface/Value/Value /destFile=paramfile.json /tagset=3
Execute Methods
After all values in the parameter-file are prepared using “set” and “get” value, it can be used to execute the method with
-
/execute- command line parameter for gins-rpcutil.exe to execute a method -
/srcFile- defines the filename of the parameter-file (in the example: paramfile.json) -
/destFile- defines the filename for the results of the method (returnstates…) -
other parameters are similar to “Get Method Parameters” function.
Example:
gins-rpcutil.exe /execute /srcFile=paramfile.json /server=localhost /port=8090 /method=DeviceConfigAPI.StartDeviceScan /destFile=startdevicescan_result.json /rpcpath=GI.com /tagset=3
The result file of an execution (here: startdevicescan_result.json) will be generated and can be evaluated again to check if the execution was successful or had some errors. For this example, the result looks like:
{
"MethodID": "DeviceConfigAPI::StartDeviceScan",
"ReturnState": {
"_id": "0.102",
"Description": "",
"Value": 0
}
}
You can again compare this example by using GI.monitor by simply click on “Send” button at the selected method. You will get the same result:
Get Array Size
To get the size of an array, use the parameter
-
/count
on a defined array, available in a parameter-file.
Example:
In the example above, there is an array “List” in the paramfile.json file. To count the available elements in this list, use
gins-rpcutil.exe /count /srcFile=paramfile.json /name=Interface/List
This will return “7” directly as return value of the gins-rpcutil.exe in the command window. If you need to redirect the output to a file (in windows command window), you can do it like this:
gins-rpcutil.exe /count /srcFile=paramfile.json /name=Interface/List > result
→ return value is saved into the file “result”.
Get Array Element
Reading an element out of an array is also done using
-
/get-value
as described in “Get Value” above. The trick is to set a numeration into the “name” parameter using “%”.
Example:
Again using the paramfile.json file from the examples above, we want to read the 2nd element in the List-Array:
gins-rpcutil.exe /get-val /name=Interface/List/%1/Value /destFile=value.json /srcFile=paramfile.json /tagset=3
which will result in a new “value.json” file:
value.json"TyNwCntrl_IPv6"