Using TRIMrpc

If you have been struggling with how best to make use of TRIMpl portability, you'll welcome the Remote TRIMpl enhancement to DesignVision functionality, called TRIMrpc.

Now you can access TRIMpl application code (the RPC-- remote procedure call) from any machine on the network. Any programs you created with TRIMpl, including calculations, text manipulation, and access programs, for example, become transparently available to any other TRIMpl "client" on the same network.

Maintaining multiple versions for platform compatibility, moving and updating files are activities of the past. Simply connect through the new driver and call the code. Reuse gets a new meaning for TRIMpl programmers and the systems on which they work.

VTX17.so is a complete TRIM runtime. Because the variables are kept in a static variable space, they remain the same for all calls. You can use persistent stored procedure calls and be confident that they will run the same on all platforms with all development languages.

Creating the TRIMpl Application

To access your useful TRIMpl applications that do not require screen input and output (reading values from a screen or writing to a screen is not currently available through TRIMrpc), you must include the following new #defines in the trim/dv.h file when you create the executable runtime:

#define			db_connect	1 		/* connect to data base*/
#define			db_release	2		/* release database*/
#define			db_commit	3		/* commit work*/
#define			db_rollback	4		/* rollback work*/
#define			db_open 	6		/* open cursor &describe*/
#define			db_exec		11		/* execute SQL statement */

How TRIMrpc Works

(TRIMrpc works like VORTEX drivers in your enterprise. Your client issues a connect, this time to a TRIMpl application on a networked machine, and calls the RPC when it needs the stand-alone application's functionality.)

Client Functions

The client can issue one of five TRIMpl functions (which are completely documented in the TRIMpl Reference Guide) which are translated to one of six new #defines for the RPC. The RPC performs its tasks and returns requested information to the client. In this process, either the client or the RPC application can use any database on the network for which it has access and authority.

Releasing the database is implicit when a client exits or when it reuses an existing connect ID for a new connection. You can pass up to two parameters (depending on the function) in your call.

connect()

Connect to a database using a standard connect string.

connect(0, "net:mypltrim@hawk!VTX17");

The protocol must be "net" since the RPC is on a remote machine. The second element in the connect string is the RPC application name without the .run extension. Following the exclamation mark, put the fully-qualified path to the executable.

exec_sql()

Issue a command to the remote procedure code (RPC).

exec_sql("getdata", LL);

list_open()

Get results from the RPC.

ll = list_open("select results", 10)

commit()

Commit the work.

rollback()

Roll back the work.

Parameters

When you write the TRIMpl stand-alone application, use the #defines according to their purpose. The RPC receives the calls as a series of four parameters.

list_open()

This function translates into the following four parameters:

parm[0]	db_open
parm[1]	A command string that must begin with SELECT.
parm[2]	This (optional) parameter contains a list of parameters.
parm[3]	If the function doesn't return an error, the RPC returns a list to the client. The list must have at least one row. The driver automatically executes a `list_more(list,n,true)` where `n` is twice the number of records that could fit in the fetch buffer. If the columns in the list have names these are used in the describe. Otherwise, the RPC uses "COLn" to describe the columns.

exec_sql()

parm[0] db_exec
parm[1] Command string.
parm[2] This (optional) parameter contains a list (which could be multi-row) of parameters passed from the client's exec_sql() call.
parm[3] If the function doesn't return an error, the RPC returns an integer. You control the integer's meaning in the RPC.

commit()

parm[0] db_commit
parm[1] An integer that indicates if a write transaction should follow a commit/rollback.

rollback()

parm[0]	db_rollback
parm[1]	An integer that indicates if a write transaction should follow a commit/rollback.

For example, for the following TRIMpl client call:

exec_sql("cmd",1958)

The RPC receives:

parm[0] is db_exec
parm[1] is "cmd"
parm[2] is a list with one row and one column with a value of 1958

Error Handling

If the client's TRIMpl generates an error, the TRIMrpc driver traps it and returns a database error. Use error() to explicitly pass back an error message.

Example

TRIMpl client:

{list LL;
  LL = list_open(prompt("Enter list_open parm ==> "),10000);
       list_view(LL,0);
}

Driver:

{list LL;
if (parm[0] == db_connect) connect(0"net:niklas/back");
  else if (parm[0] == db_open)    LL = list_open(parm.1,1000);    
  else                            LL = NULL;
  return(LL);