[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ARexx interface is only available in the MUIbase version for Amiga.
ARexx is a standard interface for Amiga programs to enable access to functions and data from other programs. MUIbase provides such an ARexx port with a small but well defined set of commands that enable an external program to virtually compute everything a MUIbase program can compute. Furthermore MUIbase' ARexx interface implements a transaction mechanism similar to other relational databases.
16.1 Port name How to address the ARexx port. 16.2 Command syntax How MUIbase ARexx commands look like. 16.3 Return codes Meaning of return values.   Application (MUI)     16.4 Quit Quit MUIbase. 16.5 Hide Iconifying MUIbase windows. 16.6 Show Deiconifying MUIbase windows. 16.7 Info Information about program and author. 16.8 Help Printing available commands.   Programming     16.9 Compile Read & compile external program source.   Database     16.10 Connect Opening a project. 16.11 Disconnect Closing a project. 16.12 Connections Displaying all connections. 16.13 Eval Running a query. 16.14 Transaction Starting a transaction. 16.15 Commit Saving changes of transaction. 16.16 Rollback Ignoring changes of transaction.
Example ARexx scripts for MUIbase can be found in the `rexx' directory.
The port name of the MUIbase ARexx port is `MUIbase.n' where n is a counter starting with 1. Usually, if you start MUIbase only once, the port name is `MUIbase.1'.
You need the port name in the ARexx address
statement before
calling any of MUIbase' ARexx commands. The following program
fragment shows how to check for the presence of a MUIbase ARexx port,
start MUIbase if needed, and address the port.
if ~show(ports, MUIbase.1) then do address command 'run <nil: >nil: MUIbase:MUIbase -n' address command 'waitforport MUIbase.1' end address MUIbase.1 |
After addressing the MUIbase ARexx port you can call any of MUIbase' ARexx commands. The syntax is the same as for most other implementations:
cmd [arg1 ...] |
Since the ARexx interpreter evaluates the command line before
sending it to MUIbase, it is sometimes useful to quote some or all
of the arguments. It is recommended to use single quotes (') around
arguments which should not be further evaluated by the ARexx interpreter.
This way you can still place double quotes ("), e.g. for string constants,
in the arguments. Furthermore you can integrate the value of ARexx variables
by unquoting them. Here is an example using MUIbase' eval
command.
search = `' eval handle 'select Name from Person where (like Name "*'search'*")' |
After calling one of MUIbase' ARexx commands several ARexx variables are updated with the result of the command. For reading all of the results of a command you should enable the ARexx results option by adding the following line at the beginning of your ARexx script.
options results |
For variable rc the following return codes exist:
Return code Meaning
0 Success. Variable result holds the actual result.
-1 Implementation error. Should never happen.
-2 Out of memory.
-3 Unknown ARexx command.
-4 Syntax error.
<= -10 Other error. Error description can be found in lasterror.
-12 Compilation error (only for |
Here is a typical code fragment showing how to examine the result of a MUIbase ARexx command.
eval handle 'select * from Accounts' if (rc == 0) then say result else if (rc == -1) then say "Implementation error" else if (rc == -2) then say "Out of memory" else if (rc == -3) then say "Unknown command" else if (rc == -4) then say "Command syntax error" else if (rc <= -10) then say lasterror else say "Error: " rc |
The quit
command causes MUIbase to exit.
See also the MUI documentation.
Command hide
iconifies all open MUIbase windows.
See also the MUI documentation.
Command show
deiconifies MUIbase and reopens the windows.
See also the MUI documentation.
The info
command provides information about title, author,
copyright, description, version, base and screen of a MUI application.
Command Value of result info title Title of application info author Author of application info copyright Copyright message info description Short description info version Version string info base Name of ARexx port info screen Name of public screen |
The help
command writes a file containing all available
ARexx commands of a MUI application.
|
The compile
command compiles an external program source file.
|
update
has been specified,
re-writes the external source file.
Updating the source file allows to pretty print the MUIbase keywords.
A successfully compiled program is then used as
the project's program and used when executing trigger functions.
If compilation fails, an error code of -12 is returned and lasterror is set to a string containing 4 lines:
Note that a project must have already been opened before sending the
compile
command for compiling its external source.
In case no project whose external source file points to source
is found, an error code <= -10 (but different from -12) is returned
and lasterror is set.
The connect
command opens the communication to a MUIbase project.
|
project-name
has already been opened and loads it if needed. A project is only
opened once and multiple connections to the same project share
the access to the database.
Next a unique communication handle is generated. A communication handle is
an integer value not equal to zero. If the keyword GUI
has been added to the command line then also the graphical user interface
of the MUIbase project is opened. Otherwise no graphical user interface
is generated allowing to process MUIbase ARexx commands in the background
without direct user interaction.
On success, the command returns 0 and sets result to the value of the handle.
Example: `connect "MUIbase:Demos/Movies.mb"' establishes a connection to the sample movie database.
See also Disconnect, Connections, Return codes.
The disconnect
command closes an existing connection.
|
Example: `disconnect 1' closes connection with handle value 1.
See also Connect, Connections, Return codes.
To find out about existing connections, use the connections
command.
|
connections
returns 0 and sets result
to a readable string where each line shows a connection
consisting of handle value and project name.
Example: the result variable after a connections
call could
look like the following:
3 MUIbase:Demos/Accounts.mb 5 MUIbase:Demos/Movies.mb 6 MUIbase:Demos/Movies.mb 7 MUIbase:Demos/Movies.mb |
The main interface of MUIbase' ARexx port for retrieving and updating
data is through the eval
command.
|
eval
command interprets the given command lisp-cmd
(written in MUIbase' lisp language) on the project specified by handle.
A handle can be obtained by the connect
command. The command
lisp-cmd can be any expression of MUIbase' programming language.
Optionally the outmost parenthesis around the expression can be omitted.
It is recommended to surround lisp-cmd by single quotes as
described in Command syntax.
If successful, eval
returns 0 and sets result to a string
representation of the return value of lisp-cmd. The string
representation is done in a way that still allows to find out
what kind of data is returned, e.g. strings are surrounded by double
quotes and lists are surrounded by parenthesis with items separated by
spaces or newline characters. If you want to ensure a certain format,
use your own formatting withing the specified lisp command.
If you did changes to the database within the eval
command
and did not start a transaction first
(see Transaction)
then the changes are automatically made permanent (auto commit).
Otherwise (you did start a transaction before calling eval
)
the changes are kept in memory until a commit
command makes them permanent or a rollback
command
undoes the changes.
Example:
options results address MUIbase.1 connect "MUIbase:Demos/Movie.mb" if (rc == 0) then do handle = result eval handle 'select Title, Director from Movies' end if (rc == 0) then say result |
( ( "Title" "Director" ) ( "Batman" "Tim Burton" ) ( "Batman Returns" "Tim Burton" ) ( "Speechless" "Ron Underwood" ) ( "Tequila Sunrise" "Robert Towne" ) ( "Mad Max" "George Miller (II)" ) ( "Braveheart" "Mel Gibson" ) ( "2010" "Peter Hyams" ) ) |
MUIbase' ARexx port allows to do transactions on a database. A transaction is a set of commands to a database (allowing modifications of data in the database) that is either executed and made permanent completely (commit) or withdrawn at any point within the transaction (rollback). A transaction can be started by issuing the following command:
|
connect
command (see Connect).
After issuing a transaction
command you can put as many
eval
commands as you like without actually changing the database.
At some point, however, you have to decide if you want to make
changes permanent (see Commit) or to go back
to the state before issuing the transaction
command
(see Rollback).
After issuing a transaction
command, access to
the corresponding project is made exclusive to the specified handle.
Thus other programs trying to access the database including the user
accessing MUIbase by its graphical user interface are blocked (or delayed
in case of another ARexx connection) until the exclusive access is released
by calling the commit
or rollback
command.
Usually the transaction
command returns 0. In case another
ARexx connection gained exclusive access to the same project
as handle refers to, the call is blocked until the other
connection finished by committing or rolling back the database.
See also Eval, Commit, Rollback, Return codes.
The commit
command is used at the end of a transaction to make
changes permanent.
|
commit
command ends a transaction
(see Transaction)
by saving the project the argument handle refers to.
On success, commit
returns 0. If you did not start a transaction
before calling commit
or if some other error occurs a value
not equal to 0 is returned.
See also Rollback, Transaction, Return codes.
To cancel changes made in a transaction use the rollback
command.
|
rollback
returns 0.
See also Commit, Transaction, Return codes.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |