This page is also available in

Documentation

Below documentation is part of the BeeBase dictribution and is also available in PDF.

17. ARexx Interface

The ARexx interface is only available in the BeeBase version for Amiga.

ARexx is a standard interface for Amiga programs to enable access to functions and data from other programs. BeeBase provides such an ARexx port with a small but well defined set of commands that enable an external program to virtually compute everything a BeeBase program can compute. Furthermore BeeBase' ARexx interface implements a transaction mechanism similar to other relational databases.

Example ARexx scripts for BeeBase can be found in the `rexx' directory.

17.1 Port Name

The port name of the BeeBase ARexx port is `BeeBase.n' where n is a counter starting with 1. Usually, if you start BeeBase only once, the port name is `BeeBase.1'.

You need the port name in the ARexx address statement before calling any of BeeBase' ARexx commands. The following program fragment shows how to check for the presence of a BeeBase ARexx port, start BeeBase if needed, and address the port.

if ~show(ports, BeeBase.1) then
do
    address command 'run <nil: >nil: BeeBase:BeeBase -n'
    address command 'waitforport BeeBase.1'
end
    
address BeeBase.1                  

See also sample ARexx script `address.rexx'.

17.2 Command Syntax

After addressing the BeeBase ARexx port you can call any of BeeBase' ARexx commands. The syntax is the same as for most other implementations:

cmd [arg1 ...]

where cmd is one of the commands described further down in this chapter, and arg1 ... are optional arguments to the command.

Since the ARexx interpreter evaluates the command line before sending it to BeeBase, 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 BeeBase' eval command.

search = `'
eval handle 'select Name from Person where (like Name "*'search'*")'

See also Eval.

17.3 Return Codes

After calling one of BeeBase' 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

There are 3 ARexx variables that can be set by the BeeBase ARexx interface: rc, results, and lasterror. Variable rc is always set and reflects the success or failure of a command. If a command was successful, results holds the actual result of the command, whereas in the case of an unsuccessful command, lasterror can hold additional information describing the error.

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.
 -11         Internal error.  Should never happen.
 -12         Compilation error (only for compile command).

Note that only for rc <= -10 variable lasterror holds a valid error description. In the future more error codes might be added to enable a more detailed error handling.

Here is a typical code fragment showing how to examine the result of a BeeBase 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

17.4 Quit

The quit command causes BeeBase to exit. See also the MUI documentation.

17.5 Hide

Command hide iconifies all open BeeBase windows. See also the MUI documentation.

17.6 Show

Command show deiconifies BeeBase and reopens the windows. See also the MUI documentation.

17.7 Info

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

See also the MUI documentation.

17.8 Help

The help command writes a file containing all available ARexx commands of a MUI application.

help filename

ARexx commands are listed using the AmigaDos command line syntax. See the MUI documentation for more information and your AmigaDos manual for the command line syntax.

17.9 Compile

The compile command compiles an external program source file.

compile source [update]

The command compiles the external program source of the project whose external source filename points to the same file as source. On success, the command returns 0 and, if update has been specified, re-writes the external source file. Updating the source file allows to pretty print the BeeBase 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:

• The first line holds the name of the file the error occurred.

• The second line holds the error line number starting with 1.

• The third line holds the error column starting with 1.

• The fourth line describe the error in readable text.

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.

17.10 Connect

The connect command opens the communication to a BeeBase project.

connect project-name [GUI]

The command first checks if the project specified by 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 BeeBase project is opened. Otherwise no graphical user interface is generated allowing to process BeeBase 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 "BeeBase:Demos/Movies.bbs"' establishes a connection to the sample movie database.

See also Disconnect, Connections, Return codes.

17.11 Disconnect

The disconnect command closes an existing connection.

disconnect handle

Closes the database connection given in handle. If this was the only connection to the project handle refers to and there is no graphical user interface for the project then the project is closed and removed from memory. Otherwise the project stays open.

Example: `disconnect 1' closes connection with handle value 1.

See also Connect, Connections, Return codes.

17.12 Connections

To find out about existing connections, use the connections command.

connections

On success, 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 BeeBase:Demos/Accounts.bbs
   5 BeeBase:Demos/Movies.bbs
   6 BeeBase:Demos/Movies.bbs
   7 BeeBase:Demos/Movies.bbs

See also Connect, Disconnect, Return codes.

17.13 Eval

The main interface of BeeBase' ARexx port for retrieving and updating data is through the eval command.

eval handle lisp-cmd

The eval command interprets the given command lisp-cmd (written in BeeBase' 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 BeeBase' programming language. Optionally the outermost 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 within 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 BeeBase.1
connect "BeeBase:Demos/Movie.bbs"
if rc = 0 then
do
    handle = result
    eval handle 'select Title, Director from Movies'
end
if rc = 0 then
    say result	    

The output of the above example could look like this:

( ( "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" ) )

See also Connect, Command syntax, Return codes, Transaction, Commit, sample ARexx script `movies.rexx'.

17.14 Transaction

BeeBase' 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:

transaction handle

where handle refers to a project as obtained by the 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 BeeBase 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.

17.15 Commit

The commit command is used at the end of a transaction to make changes permanent.

commit handle

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

17.16 Rollback

To cancel changes made in a transaction use the rollback command.

rollback handle

All changes made in the project referred to by handle since the beginning of the current transaction (see Transaction) are withdrawn and the state of the project before the transaction is restored. If successful rollback returns 0.

See also Commit, Transaction, Return codes.

This document was generated on September, 30 2024 using texi2html