/rpc URL Handler (In-Process CGI Task)

URL Handler (In-Process CGI routine) that executes GPL functions on the web server controller via a remote procedure call (RPC) technique. The String results of the GPL function are available for use by the invoking web page.

/rpc

Prerequisites

The GPL string function must be loaded and compiled before the web page is displayed.

AJAX Send Request (XMLHttpRequest) Parameters

.Open("POST", "/rpc", false)

A required AJAX method that specifies the type of request, the URL, and if the request should be handled asynchronously or not. For the RPC operation, the method must be "POST", the url must be "/rpc" to invoke the RPC process, and async must be false to synchronize the reading of the RPC results.

.SetRequestHeader("Content-type", "text/plain")

A required AJAX method that defines the format of the reply from the RPC. The type should be set to "text/plain" for general compatibility.

.Send(string)

A required AJAX method that specifies the RPC GPL function to be executed along with any needed function parameters. Since GPL requires double quotes around String constants, the string should contain the following fields surrounded by single quotes as follows:

'Module.Class1...Fname(arg1, ... , argn), Project'

where

"Module." specifies the optional top-level module or class name. If omitted, all modules and top-level classes are searched.
"Class1..." specifies an optional list of public class names nested within the top-level module or class.
"Fname" specifies the public String-valued GPL function to be called remotely.
"arg1, ..., argn" is a list (possibly empty) of arguments to be passed to the function. Empty ( ) must be specified even if there are no arguments. If an argument contains a GPL variable, it must be globally accessible.
", Project" is the optional project name. If omitted, all projects are searched.

Remarks

The server side Javascript procedures provide a very convenient means for reading dynamic data that the controller automatically updates, such as axis positions and digital I/O states. However, for more complicated interactions, such as writing a series of values to the controller and reading a computed response, the Javascript procedures can be laborious to implement and slow to execute. For these more complicated communications, in GPL 3.2 G5 and later, the web interface supports remote procedure calls (RPC's). The RPC method permits a web page to execute a GPL function on the controller, specify its arguments, and obtain a result from the function.

The remote procedures that are invoked by the RPC method can be any user written GPL function that returns a String value. When referenced from within AJAX (Asynchronous JavaScript and XML) on a web page, the remote procedure with its arguments is executed as a separate thread within GPL. The String returned by the function becomes a value accessible to JavaScript for use within the web page.

Creating The Remote Procedure

The GPL function that is executed on the controller as a Remote Procedure must be a Public GPL function that returns a single String value. If it is class member, it must be Shared. Like all GPL functions, you must specify the module or class name path if it is not a top-level function. The function may have an arbitrary argument list that must match the arguments passed by the actual call. The function may call any other procedures within your GPL project. The project containing the Remote Procedure must be loaded and compiled before a remote call will succeed.

While the GPL function is active, the entire web server is blocked so that no other web operations can occur until the function completes. For this reason, the functions should be designed to execute quickly.

Calling The Remote Procedure

Remote procedures are called by using an HTML POST operation to the special URL named "/rpc". The contents of the POST are interpreted by the GPL web server as a function call. The String value returned by the function is returned as the response text of the POST. One convenient way to issue the POST is by using AJAX to issue the POST and read the response. The response text may be copied to a JavaScript variable for display or additional processing on the client.

The maximum RPC String for the POST is about 1200 bytes.

There is no limit to the length of the response String.

A single line-feed character (ASCII byte value 10) is always appended to the response String value returned by the remote procedure.

If an error occurs, the response String is empty, unless the debug flag is set in DataID 464.

Configuration and Debugging Remote Commands

DataID 464 ("Web RPC: debug, timeout, stack") allows configuration of the RPC functionality. It is an array of 3 elements.

Element 1: Debug bit mask. Set to 0 by default for normal operation. If bit 1 is set, any errors are returned as an error message String in the text response. If bit 2 is set, RPC threads do not send events to GDE regarding thread start/stop. If this is set, it prevents RPC-based web pages from frequently interrupting and interfering with normal program debugging.

Element 2: Timeout. The time limit, in seconds, for the Remote Procedure to execute. If set to zero, there is no time limit. If the remote procedure fails to complete within the time limit, the call fails with error -752 "Timeout stopping thread". You will not see the error message unless you are in debug mode. Your web browser may also time out if it does not get a response from GPL within a reasonable time. Defaults to 0.

Element 3: Stack size. The size of the GPL stack to be used by the RPC thread. If zero, the default size for the project (normally 4Kbytes) is used. Defaults to 0.

The web interface is handled entirely by a single GPL thread, so only one Remote Procedure can be active at a time. Each procedure must complete before the next one can be executed. The RPC thread name is hard-coded to "_Web_RPC" so users should not start a thread with that name. Within each project, a hidden program named "_RPC" is created whenever a remote procedure call is received. Users should not create a procedure with this name. This program executes in thread "_Web_RPC" and performs the actual call.

You may insert breakpoints into the Remote Procedure or in any of the procedures called by it. When a breakpoint is hit, GDE allows you to display variables, single-step procedures, or continue as normal. Be sure you have your timeout value set long enough to account for delays due to single-stepping.

Examples

Example GPL remote procedure:

Public Function TestRPC(ByVal header As String, _
        ByVal data As Integer) As String
    Dim ss As String
    ss = header & CStr(data)
    Return ss
End Function

Example AJAX script to call the GPL procedure above:

var xmlHttpOprStt
function ReadTest() {
    xmlHttpOprStt=new XMLHttpRequest();
    xmlHttpOprStt.open("POST","/rpc",false);
    xmlHttpOprStt.setRequestHeader("Content-type","text/plain");
    xmlHttpOprStt.send('TestRPC("The value is: ", 123)');
    return xmlHttpOprStt.responseText
}

After execution, this function returns a string containing:

The value is: 123<lf>

where: <lf> represents the line-feed character.