DesignVision Users Guide

8

Remote TRIMpl Applications

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 DVremote.

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.

vtxhost.trm 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 DVremote), you must include the following new #defines in the trim.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 DVremote Works

DVremote 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.

The client can issue one of five TRIMpl functions (which are completely documented in the TRIMpl Reference Manual) 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.

Client Functions

From the client, you can issue five TRIMpl functions. 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!/usr2/bin/vtxhost.trm");

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 extention. 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 #define s 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 ecords 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 e xec_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.

Example

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 TRIMremote 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);

}