| |
Using 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 TRIM/DesignVision functionality.
Now you can access TRIMpl application code (the RPC-- remote procedure code) from any machine on the network. No more maintaining multiple versions for platform compatibility, no more moving and updating. 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 RPC
To access your useful TRIMpl applications that do not require screen I/O (which generate errors), you must include the following new
#defines
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 TRIMremote works
TRIMremote 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, 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 three 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 appliation name without the .
run
extention. Following the exclamation mark, put the fully-qualified path to the TRIM 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 following table shows the parameters as received by the RPC for the four calls that allow them:
|
1st Param
|
2nd Parameter
|
3rd Parameter
|
Returns
|
|
db_open
|
A command string that must begin with SELECT.
|
This (optional) parameter contains a list of parameters.
|
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.
|
|
db_exec
|
Command string.
|
This (optional) parameter contains a list (which could be multi-row) of parameters passed from the client's e
xec_sql()
call.
|
If the function doesn't return an error, the RPC returns an integer. You control the integer's meaning in the RPC.
|
|
db_
commit
|
An integer that indicates if a write transaction should follow a commit/rollback.
|
N/A
|
N/A
|
|
db_
rollback
|
An integer that indicates if a write transaction should follow a commit/rollback.
|
N/A
|
N/A
|
For example in the following TRIMpl client call the following elements are:
exec_sql("cmd",1958)
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.
Working 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);
}
|
