| Prev | Next | Start of Chapter | End of Chapter | Contents | Glossary | Index | Comments | (5 out of 11)

Using Remote Procedure Calls

You can use remote procedure calls (RPCs) in any application that requires G2 to execute a procedure in another G2 across an ICP interface object. In particular, you can use RPCs for value- and item-passing, and to build interfaces to external devices and database systems. You can also use RPCs to allow G2 Gateway to call procedures in G2 and receive return values.

The G2 that issues the remote procedure call is the client. The G2 that executes that call is the server. To use RPCs, the client G2 declares that a particular procedure is remote by using a remote procedure declaration. The remote procedure declaration specifies the name, argument types, and return types of the procedure as it exists on the remote G2.

Depending on the arguments of the remote procedure, and thus how you declare the remote procedure on the client G2, you can send or receive:

Variable or parameter values.
A reference to any item.
A copy of any item with any number of its user-defined, and user-accessible system-defined attributes.

The next three sections describe how to create, declare, and call or start a remote procedure. Subsequent sections present the valid arguments for RPCs, and various ways to use RPCs to pass values and items to and from remote systems.

Creating and Declaring a Remote Procedure

To create a remote procedure declaration:

Choose KB Workspace > New Definition > remote-procedure-declaration

G2 invokes the Text Editor immediately so that you can complete the remote procedure. After completing the declaration, you can place the remote procedure onto the workspace and then open its attribute table.

You complete the remote procedure declaration by stating the name of the procedure you will call from the local KB, but which resides on a remote G2 process. The syntax is:

declare remote remote-procedure-name (  [argument] [,...]  )  =  (return [,...])


Element	Description
remote-procedure-name	The name of the procedure on the remote system.
argument	One or more arguments that the procedure accepts. You can specify up to 200 arguments within the parentheses. For a complete description of RPC arguments, see Value and Item Passing Arguments and Return Types for RPCs.
return	Indicates the return value (or values) of the procedure.

Using an Alternative Procedure Name

The name you enter in the declaration statement is duplicated as a string in capital letters in the Name-in-remote-system attribute of the remote procedure declaration's attribute table, as shown in this diagram.

You can use the Name-in-remote-system attribute to declare a remote procedure with a different name so that you do not have two procedures with the same name in your local KB.

Once you edit this attribute, G2 decouples the name from the remote-procedure-name in the remote procedure declaration syntax. This means that further edits to the declaration will not affect the Name-in-remote-system attribute. You will have to edit that attribute directly to change it.

The Name-in-remote-system attribute of the remote procedure declaration is a case-sensitive string. For example, if the name of the remote procedure is my-proc, and you enter MY-PROC, G2 will be unable to locate the appropriate procedure on the remote system. By default, G2 procedure names are uppercase.

Invoking Remote Procedures

You can invoke a remote procedure from the client G2 in one of two ways:

A start action with the across g2-to-g2-interface phrase
A call statement with the across g2-to-g2-interface phrase

You can use the start action for remote procedures in both rules and procedures. When you use start, the client G2 continues to execute the calling rule or procedure.

You can use the call statement only in procedures. When you use call, the client G2 waits until the remote procedure completes before continuing with the calling procedure.

It is possible for a call to a remote procedure to be aborted at the client, for example, when a different branch of a do in parallel statement within a procedure finishes first. In this case, the client procedure continues processing and the remote procedure is aborted.

Starting a Remote Procedure

To use the start statement for a remote procedure, the syntax is:

start remote procedure (argument [,...]) 
    [at priority integer-expression]  [after time-interval] 
    across g2-to-g2 interface


Element	Description
`remote-procedure`	An expression that returns a procedure.
`at priority integer-expression`	Specifies the priority of the procedure. This priority setting overrides the default priority only within the client; within the server, the execution of the remote procedure call begins at that procedure's default priority.
`after time-interval`	Specifies a time interval after which the remote procedure should start in the client.
`across g2-to-g2 interface`	Indicates the ICP interface through which the RPC is being called. If the ICP interface object is not connected, an G2 signals an error in the client process executing the `start` action, but the executing rule or procedure continues processing.

If the remote procedure does not exist in the server, or if an error occurs in starting the remote procedure, G2 signals an error in the client.

If an error occurs during the execution of the remote procedure after it has started, the server G2 handles the error as if the procedure were called locally. The client G2 does not signal an error. If the remote procedure was called from a higher-level procedure, that procedure continues processing.

Calling a Remote Procedure

To use the call statement for a remote procedure, the syntax is:

[return [,...] =] call remote procedure (argument [, ...] ] ) 
    across g2-to-g2 interface


Element	Description
`remote-procedure`	An expression that returns a procedure.
`across g2-to-g2 interface`	Indicates the ICP interface through which the RPC is being called. If the ICP interface object is not connected, an error occurs in the client process and G2 signals an error on the client.

In the client G2, the processing to initiate the call occurs at the same priority as that of the procedure containing the call. This priority does not affect the priority of the call within the server G2, where the execution of the remote procedure call begins at the default priority of the remote procedure.

If an error occurs during the execution of the called remote procedure, the remote procedure is aborted in the server G2 and the error message is propagated back to the client. On the client G2, the procedure that initiated the remote call is aborted and a message is displayed on the client logbook.

| Prev | Next | Start of Chapter | End of Chapter | Contents | Glossary | Index | Comments | (5 out of 11)

Copyright © 1997 Gensym Corporation, Inc.