PicLan-IP RPC Services

March 8, 2001 - Preliminary Documentation

Overview of Remote Proceedure Calls

The purpose of remote proceedure calls is to provide a mechanism where application software running on one host system can call application software on a remote system bi-directionally passing parameters. With MultiValue DBMS systems this is implemented as the ability for an mv/BASIC application to call an mv/BASIC external subroutine remotely.

Once RPC services are available, the application program can implement nearly any needed functionality including remote file access and update, remote report execution, etc. In addition, because the connection occurs at an application program level, you can easily optimize your proceedure calls to maximize performance.

How are RPC Services licensed

The initial test release of RPC services use existing HTTP server and HTTP client PicLan-IP services. The next release (which should only be a couple of weeks away) will license RPC services seperately and at a lower cost. The end-user price list for RPC services is:

All RPC licenses are bidirectional (or n-directional with more than 2 hosts) so that any system can call subroutines on any other system.

What are included with RPC Services

PicLan-IP RPC Services include the following features:

• Basic functionality
  • RPC functions can be called from any account
    • The called subruotine always executed in the PICLAN-IP account
  • From 1 to 20 parameters can be passed to the called subroutine
• Ease of programming
  • Subroutine templates are called on the local system making remote subroutine calls nearly identical to local subroutine calls
  • Full control over error conditions, timeouts, and retries
• Performance optimizations
  • You can specify which subroutine parameters need to be transferred across the network in which directions
• Reliability features
  • Transparent network retries
    • Server execution is "protected" so that a called subroutine will only be invoked one time even if there is a network error and subsequent retry
  • Multi-homing and multi-path support

A future version of RPC Services will add the following features

• Data compression - LZW compression to optimize network bandwidth
• Data encryption - Tripple DES encryption for secure transactions (single DES for export users)

Setting up a server to accept RPC requests

An RPC server is a computer system running PicLan-IP that can accept inbound requests.

Setting up the PICLAN-IP account

The PicLan-IP server will call your defined subroutines from the PICLAN-IP account. You must compile and catalog your subroutines so that they follow these guidelines:

• Your subroutine will always run from the PICLAN-IP account.
  • You must compile and catalog your subroutine so that it is runable in the PICLAN-IP account.
• Your subroutine cannot use standard COMMON.
  • You can use NAMED COMMON, but remember that PicLan-IP runs a "pool" of processes so your subroutine may run on different processes at different times
  • If you need to store "state" information, you will need to use data files and devise your own "state identifier"
    • We recommend that you let the client call establish a state identifier and pass it as a parameter.
• Your subroutine should open (and close if your system requires this) data files at the beginning and end of every call.
  • It is possible to open files a single time into NAMED COMMON variables. You do this using an "init subroutine" in PicLan-IP.
• All parameters to and from your subroutine must be "storable" strings.
  • You cannot pass file variables or select variables
  • You cannot pass dimensioned arrays (dynamic arrays are fine)
• Your subroutine must be "well behaved"
  • It cannot stop for "input"
  • It must not set locks that it does not release before exiting
  • It must complete within the allowable RPC and Coyote timeout periods

Setting up the PICLAN-IP server

This proceedure wil change in a future release of PicLan-IP RPC support

In the PLIP.CTRL CONFIG file add the following line to the HTTP DIR lines:

HTTP DIR=*:80 /RPC/ FILE PLIP.RPC,PAGES

If your server runs on another IP address or port number, then you can include these in this line instead of "*:80".

If your server is multi-homed, you can include this line multiple time for different IP listen addresses or TCP port numbers.

The RPC functions will not interfere with other Coyote HTTP functions (assuming that you are not currently using a web directory named /rpc).

Creating a subroutine definition record

Before you can call a subroutine, you need to define a subroutine control record. This record is stored in the file PLIP.RPC,SUB. It has the following layout

Setting up a client to make RPC requests

Setting up your user account

This proceedure is still being designed. Suffice it to say that you will need many md items for this.

Creating a callable subroutine

PicLan-IP allows you to build a small local subroutine that has the same interface as the remote subroutine that you are calling. This allows you to write application code that appears to be completely local, even though remote proceedure calls are involved.

Building this local subroutine involves:

• Copying the appropriate template subroutine from the PLIP.RPC,SRC file
  • Templates are included for subroutnes with from 1 to 20 parameters and with and without error parameters
  • You should copy the template to your application source file
  • You should rename the template to a name that makes sense for each subroutine call
  • You will need a seperate subroutine for each system that you wish to call
    • If you want to modify the internals of the template, it is quite easy to use a single template for calling multiple systems.
• Editing the template
  • Fill in the server name and subroutine that is to be called
  • Optinally fill in any size limit, timeout, and retry parameters
• Compile and catalog the subroutine

Defining a server system

Before you can call a server, you need to define a host system in the PLIP.RPC,SERVERS file. This file has the following layout

Actually calling the remote subroutine

You can call the remote subroutine from your application by simply calling the subroutine that you built and compiled from the RPC template.

Tuning for Performance

There is not much to do in terms of tuning for performance except for paying attention to applicaton design.

Only pass the data that you need

If you are running on slow network connections, you should be careful to only pass the actual data needed. Extra data attributes require network transmission time. Also, flag parameters that only need to transfer in one direction as either In or Out instead of both.

On the other hand, if your network is fast, don't worry about this. The internal processing of RPC Services do not really mind large transactions (within reason) and it is only the network layer that is a concern. So, if you are using RPCs across a LAN, just throw the data around.

Minimize the number of transactions

The real area that you can optimize your application is by designing the RPC calls so that you need to make as few calls as practical. For example, if you need to read every item in a file, you should build an RPC that reads more than one item in a single call. Remember that a large part of the overhead of an RPC call is setting up the call, not transferring the data.

Programming tricks

Passing a variable number of dynamic arrays to a routine

One programming technique often needed is the ability to pass a variable number of parameters. With most data, you would just place this in a dynamic array. Things get more complicated if the data is itself a dynamic array. In this case, you can still pass the data in a single parameter using logic like:

Sending side:

DIM PARMS(500)



...


PARM = ''
FOR I = 1 TO 500
   PARM<1,I> = LEN(PARMS(I))
NEXT I


PARM = PARM : CHAR(254)
FOR I = 1 TO 500
   PARM = PARM : PARMS(I)
NEXT I

Receiving side:

DIM PARMS(500)


...


T.CTRL = PARM<1>
T.DATA = PARM[LEN(T.CTRL)+2,999999999]

N = 1
FOR I = 1 TO 500
   PARM(I) = T.DATA[N,T.CTRL<1,I>]

   N = N + T.CTRL<1,I>
NEXT I