Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/164.lha/ARexx/VariableInterface/RVI.doc

Text File | 1988-04-28 | 6KB | 135 lines

                        REXX Variables Interface

The REXX Variables Interface (RVI) is a set of functions to allow an ARexx
host to manipulate a macro program's symbol table.  Using these functions
the host can retrieve values for existing variables and install new values.
There is no limit (except for available memory) to the number of variables
that can be created, so the variables interface is a very convenient way to
pass information to a macro program.

The RVI functions can be called whenever the ARexx host holds a pending
command message from an ARexx program.  While the command message is
outstanding, the macro program is waiting for the reply and the program's
symbol table is in a consistent state.  All calls to the interface functions
must be completed before the message is replied.

In a typical application, a macro program issues a command to the host to
perform some specific action, and may pass the name of a stem variable as
an argument.  The host performs the command and fills in the appropriate
variables before replying to the message.  When the macro program resumes
operation, it can check the values of the variables set by the host.


Variable Names.
Variable names are specified by a pointer to a null-terminated string and
must follow the REXX language symbol conventions.  Alphabetic characters
must be in uppercase.  The variable name is treated as a literal string,
and no substitution for compound symbols is performed.

The host application should document the variables affected by each command
so that the macro programmer knows where to find the information, and to
avoid accidental conflicts in variable names.  If a large number of values
must be passed, the host should define them as compound variables and let
the macro program pass the stem name as an argument.


Calling Conventions.
The RVI functions are in the form of linkable functions callable from either
C or assembly language.  The C language entry points have an underscore
prepended to the function name to match the external name generated by the
compiler.

For the C language calls the following declarations apply:
   struct RexxMsg *message;
   char *variable;
   char *value;
   long length;
   long boolean;

To use the RVI functions, include the file "rexxvars.o" when you link your
application code.  It is not necessary to define the ARexx library base
(RexxSysBase), as the ARexx library is opened on the fly when required.


CheckRexxMsg()
Usage: boolean = CheckRexxMsg(message);

This function verifies that the message pointer is a valid RexxMsg and
that it came from an ARexx macro program.  The validation test is more
stringent than that performed by the ARexx library function IsRexx().
The latter verifies that the message is tagged as a RexxMsg structure,
but not that it necessarily came from an ARexx macro program.  Each macro
program installs a pointer to its global data structure in the command
message, and this pointer is necessary to gain access to the symbol table.

The return from the function will be non-zero (TRUE) if the message is
valid, and 0 (FALSE) otherwise.


GetRexxVar()
Usage: error = GetRexxVar(message,variable,&value);

This function retrieves the current value for the specified variable name.
It first validates the message using CheckRexxMsg() and then, if the
message pointer is valid, retrieves the value string and passes it in the
supplied return pointer.  The return pointer is actually an argstring (an
offset pointer to a RexxArg structure), but can be treated as a pointer
to a null-terminated string.  The value must not be disturbed by the host.

The function return will be zero if the value was successfully retrieved
and non-zero otherwise.  An error code of 10 indicates an invalid message.


SetRexxVar()
Usage: error = SetRexxVar(message,variable,value,length);

This function installs a value in the specified variable.  It validates the
message pointer using CheckRexxMsg() and then installs the value, creating
a symbol table entry if required.  The value is supplied as a pointer to
a data area along with the total length; the data may contain arbitrary
values and need not be null-terminated.

The function return will be zero if the call was successful and non-zero
otherwise.  The possible error codes are given in the table below.

   Error Code  Reason for Failure
       3       Insufficient storage
       9       String too long
      10       Invalid message


Assembly Language Calling Convention.
The assembly language entry points are identical to their similarly-named
C counterparts, but of course don't have an underscore prepended.  The
register usages are as follows:

boolean = CheckRexxMsg(message)
  D0                     A0

error, value = GetRexxVar(message,variable)
  D0     A1                 A0       A1

error = SetRexxVar(message,variable,value,length)
  D0                 A0       A1      D0     D1

Note that the value returned by GetRexxVar() is an argstring (pointer),
and the value passed to SetRexxVar() is just a pointer to a data area.


Code Examples and Test Program.
A sample C program to exercise the RVI functions is included.  VarTestC.c
opens a public port named "VarTest" and waits for messages to arrive from
ARexx.  Each message is validated with a call to CheckRexMsg(), after which
the value for A.1 is retrieved using GetRexxVar().  The program then installs
the value "A-OK" in the variable STATUS and replies the message.  VarTestC
exits when it receives a "CLOSE" command.

The ARexx program TestRVI.rexx will demonstrate the VarTestC host.  If run
from WShell, TestRVI will start VarTestC (if it doesn't already exist) and
wait for it to initialize its message port.  If you don't have WShell,
issue a "run Vartest" command first and then issue "rx TestRVI".  TestRVI
executes with tracing on so that you can see the results of each statement.

VarTestC.c should compile under either Lattice or Manx, and a sample link
script for Lattice is included.