MUIbase Support This Project
programmable relational database
with graphical user interface
This page is also available in Deutsch Français

Documentation

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


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

16. Programming MUIbase

This chapter (the largest in this manual) describes the programming language of MUIbase, including all available functions. This chapter, however, is not intended as a general guide about programming. You should be familiar with the basics about programming and should already have written some small (and correctly working :-)) programs.


16.1 Program Editor

To enter a program for a project, open the program editor by selecting menu item `Program - Edit'. If you are using the setting program source internal (see Program source), this will open the `Edit program' window containing:

  • a text editor field where you edit the project program.

  • a button `Compile & close' for compiling the program and, on successful compilation, leaving the program editor.

  • a button `Compile' to compile the program. If your program contains an error somewhere then an error description is put into the window title and the cursor is set on the faulty location.

  • a button `Revert' that reverts all changes since the last successful compilation.

The program editor is a non-modal window. You can leave the window open and still work with the rest of the application. You can close the editor at any time by clicking into its window close button. If you have done changes since the last successful compilation then a dialog pops-up asking for confirmation to close the window.

In case you have set menu item `Program - Source' to `External' the external editor (see External editor) is launched with the filename of the external source file when choosing `Program - Edit'. This allows you to edit the program source using your favorite editor (see External program source).

You can also compile a project's program without opening the program editor by choosing menu item `Program - Compile'. This can be useful if you e.g. do changes to an external include file and want to incorporate these changes in the project's program.


16.2 External program source

By choosing menu item `Program - Source - External' and entering a filename you can make the program source of a project externally available. This allows you to load the program source into your favorite editor for programming.

If compilation is successful, the compiled program is set as the project's program and used when executing trigger functions. When you save a project, the last successfully compiled program is store with the project inside the project file. Thus, after saving and closing a project, the external source is no longer needed actually. You can specify if unneeded external source files should be deleted automatically by checking menu item `Preferences - Cleanup external program source'.

The status of menu item `Program - source' is stored with the project. If you re-open a project that uses the external source feature, the external source file is created after opening the project. If the external source file already exists and is different from the version stored inside the project, a dialog asks for confirmation before overwriting the file.

On the Amiga you can send the compile command to MUIbase' ARexx port from your editor. MUIbase then reads the external program source, compiles it, and returns the compile status with an optional error message containing filename, line and column, and an error description. This allows you to place the cursor at the exact location of where a compile error occurred. See ARexx compile, for details on return values and error format.


16.3 Preprocessing

MUIbase programs are pre-processed similar to a C compiler preprocessing a C source file. This section describes how to use the preprocessing directives.

All directives start with a hash symbol # which should be the first character on a line. Space or tab characters can appear after the initial #.


16.3.1 #define

 
#define name string

Defines a new symbol with the given name and contents. The symbol string can be any text including spaces and ends at the end of line. If string does not fit on one line you can use further lines by using a backslash character \ at the end of each line (except for the last one). If the symbol name does occur in the remaining source code then it will be replaced by the contents of string.

Example: `(PRINTF "X is %i" X)' prints `X is 1' (Occurrences of name in strings are not altered.)

The replacement of defined symbols is done syntactically which means that you can replace symbols with any text, e.g. you can define your own syntax like in the following example:

 
#define BEGIN (
#define END )

BEGIN defun test ()
        ...
END

The replacement string of a definition may contain another symbol that has been defined with the #define directive to allow nested definitions. However there is an upper limit of 16 nested definitions.

See also #undef, #ifdef, #ifndef.


16.3.2 #undef

 
#undef name

Removes the definition of symbol name. If name has not been defined, nothing happens.

See also #define, #ifdef, #ifndef.


16.3.3 #include

 
#include filename

Reads in the contents of filename (a string surrounded with double quotes) at this location. MUIbase searches in the current directory and in the directory specified in the preferences (see Program include directory) for loading the file. The file contents are processed by the compiler as if they were part of the current source code.

An external file may include one or more other external files. However there is an limit of 16 nested #include directives. To protect files from including them more than once, you can use conditional compilation.

Be careful when moving source code to external files! Debugging and tracking down errors is much harder for external files. Move only well tested and project independent code to external files.


16.3.4 #if

 
#if const-expr

If the given constant expression results to non-NIL then the text up to the matching #else, #elif, or #endif is used for compilation, otherwise (the expression results to NIL) the text up to the matching #else, #elif, or #endif is discarded for compilation.

Currently you can only use TRUE and NIL as constant expressions.

See also #ifdef, #ifndef, #elif, #else, #endif.


16.3.5 #ifdef

 
#ifdef name

If the given symbol has been defined with a #define directive then the text up to the matching #else, #elif, or #endif is used for compilation, otherwise it is discarded.

See also #if, #ifndef, #elif, #else, #endif.


16.3.6 #ifndef

 
#ifndef name

If the given symbol has not been defined with a #define directive then the text up to the matching #else, #elif, or #endif is used for compilation, otherwise it is discarded.

See also #if, #ifdef, #elif, #else, #endif.


16.3.7 #elif

 
#elif const-expr

Any number of #elif directives may appear between an #if, #ifdef, or #ifndef directive and a matching #else or #endif directive. The lines following the #elif directive are used for compilation only if all of the following conditions hold:

  • The constant expression in the preceding #if directive evaluated to NIL, the symbol name in the preceding #ifdef is not defined, or the symbol name in the preceding #ifndef directive was defined.
  • The constant expression in all intervening #elif directives evaluated to NIL.
  • The current constant expression evaluates to non-NIL.

If the above conditions hold then subsequent #elif and #else directives are ignored up to the matching #endif.

See also #if, #ifdef, #ifndef, #else, #endif.


16.3.8 #else

 
#else

This inverts the sense of the conditional directive otherwise in effect. If the preceding conditional would indicate that lines are to be included, then lines between the #else and the matching #endif are ignored. If the preceding conditional indicates that lines would be ignored, subsequent lines are included for compilation.

Conditional directives and corresponding #else directives can be nested. However there is a maximum nesting count limit of 16 nested conditional directives

See also #if, #ifdef, #ifndef, #elif, #endif.


16.3.9 #endif

 
#endif

Ends a section of lines begun by one of the conditional directives #if, #ifdef, or #ifndef. Each such directive must have a matching #endif.

See also #if, #ifdef, #ifndef, #elif, #else.


16.4 Programming Language

MUIbase uses a programming language with a lisp-like syntax. Indeed several constructs and functions have been adopted from standard lisp. However, MUIbase is not fully compatible to standard lisp. Many functions are missing (e.g. destructive commands) and the meaning of some commands is different (e.g. the return command).


16.4.1 Why Lisp?

The advantage of a lisp-like language is that you can program in both, a functional and an imperative way. Functional languages are getting quite popular in mathematical applications. The basic concept in functional languages is the use of expressions. Functions are defined in a mathematical way and recursion is used heavily.

Imperative programming languages (e.g. C, Pascal, Modula) use an imperative description on how to compute things. Here, the state is the basic concept (e.g. variables) and a program computes its output by going from one state to another (e.g. by assigning values to variables).

Lisp combines both techniques and therefore you can choose in which way you want to implement things. Use the one which is more appropriate for the specific problem or which you like more.


16.4.2 Lisp Syntax

A lisp expression is either a constant, a variable, or a function application. For calling functions, lisp uses a prefix notation. The function and its arguments are surrounded by parenthesis. For example, to add two values a and b, you write

 
(+ a b)

All expressions return a value, e.g. in the above example the sum of a and b returned. Expressions can be nested, that is, you can place an expression as a sub-expression into another one.

Function evaluation is done by using a call-by-value scheme, this means that the arguments are evaluated first before a function is called.

If not stated otherwise, all functions are strict, that is, all arguments of a function are evaluated before the function is called. Some functions, however, are non-strict, e.g. IF, AND and OR. These functions may not evaluate all arguments.


16.4.3 Kinds of Programs

MUIbase knows three kinds of programs. The first one is the project program kind. In a program of this kind you can define functions and global variables. The functions can be used as trigger functions for attributes. You define a project program in the program editor (see Program editor).

The second kind is the query program kind. For this kind you can enter expressions only. An expression is allowed to contain global variables and calls to functions that are defined in the project program. However, you cannot define new global variables or functions in a query program. Query programs are entered in the query editor (see Query editor).

The third kind of programs are filter expressions. Here you can only enter expressions that contain calls to pre-defined MUIbase functions. Not all pre-defined functions are available, only those that don't have a side effect, e.g. you cannot use a function that writes data to a file. Filter expressions are entered in the change-filter dialog (see Changing filters).


16.4.4 Name Conventions

In a MUIbase program you can define symbols like functions and local or global variables. The names of these symbols must follow the following conventions:

  • the first character of a name must be a lowercase letter. This distinguishes program symbols from table and attribute names.
  • The following characters can be any letters, digits or underscore characters. Other characters like German umlauts are not allowed.


16.4.5 Accessing Record Contents

To access tables and attributes in a MUIbase program, you have to specify a path to them. A path is a dot separated list of components where each component is the name of a table or an attribute.

Paths can either be relative or absolute. Absolute paths are specified with a table name as the first component, followed by a list of attributes that lead to the final attribute you want to access. E.g. the absolute path `Person.Name' accesses the `Name' attribute in the current record of table `Person', or the absolute path `Person.Father.Name' accesses the `Name' attribute in the record referenced by the `Father' field (a reference attribute to table `Person').

Relative paths already have a current table to which they are relative. For example in a filter expression the current table is the table for which you write the filter expression. The relative path for an attribute in the current table is simply the attribute name itself. For attributes that are not directly accessible from the current table but indirectly via a reference attribute, the same rules as for absolute paths apply.

It is not always clear if a specified path is a relative or an absolute one, e.g. suppose you are writing a filter expression for a table `Foo' that has an attribute `Bar' and there also exists a table `Bar'. Now entering `Bar' would be ambiguous, what is meant, the table or the attribute? Therefore all paths are first treated as relative ones. If no attribute is found for the specified path than the path is treated as global. In our example the attribute would be preferred.

But now, what if you want to access the table in the above example? Therefore the path must be given absolute. To indicate that a path is global you have to insert two colons in front of the path. In our example you would have to type `::Bar' for accessing the table.

To give you a better understanding of paths and their semantics, consider in our example that the `Bar' attribute in the `Foo' table is a reference to the `Bar' table, and the `Bar' table has an attribute `Name'. Now you can access the `Name' attribute by typing `Bar.Name' or `::Bar.Name'. Both expressions have a different meaning. `::Bar.Name' means to take the current record of table `Bar' and return the value of the `Name' attribute of this record, whereas `Bar.Name' takes the current record of table `Foo', extracts the record reference of the `Bar' field and uses this record for getting the value of the `Name' attribute.

To make a more complete example, consider that table `Bar' has two records. One that contains `Ralph' and one that contains `Steffen' in the `Name' field. The first record should be the current one. Furthermore table `Foo' has one record (the current one) whose `Bar' field refers to the second record of table `Bar'. Now `::Bar.Name' results to `Ralph' and `Bar.Name' to `Steffen'.


16.4.6 Data Types for Programming

The programming language of MUIbase knows of the following data types:

 
Type        Description

Boolean     all expressions. Non-NIL expressions are treated as TRUE.

Integer     long integer, 32 bit, choice values are automatically
            converted to integers

Real        double, 64 bit

String      strings of arbitrary length

Memo        like strings but line oriented format

Date        date values

Time        time values

Record      pointer to a record

File        file descriptor for reading/writing

List        list of items, NIL is empty list.

All programming types support the NIL value.


16.4.7 Constants

The programming language of MUIbase can handle constant expressions which can be entered depending on the type of the expression:

 
Type        Description

Integer     Integer constants in the range of -2147483648 to
            2147483647 can be specified as usual.  Values
            starting with 0 are interpreted as octal numbers,
            values starting with 0x as hexadecimal numbers.

Real        Floating point constants in the range of -3.59e308
            to 3.59e308 can be specified as usual, in scientific
            or non-scientific format.  If you omit the decimal
            point then the number may not be treated as a real
            number but as an integer instead.

String      String constants are any character strings surrounded
            by double quotes, e.g. "sample string".  Within the
            double quotes you can enter any characters except
            control characters or new lines.  However there are
            special escape codes for entering such characters:

                \n              new line (nl)
                \t              horizontal tabulator (ht)
                \v              vertical tabulator (vt)
                \b              backspace (bs)
                \r              carriage return (cr)
                \f              form feed (ff)
                \\              backslash character itself
                \"              double quote
                \e              escape code 033
                \nnn            character with octal code nnn
                \xnn            character with hex code nn

Memo        Same as string constants.

Date        Constant date values can be specified in one of the
            formats `DD.MM.YYYY', `MM/DD/YYYY', or `YYYY-MM-DD', where
            `DD', `MM' and `YYYY' are standing for two and four digit
            values representing the day, month and year of the
            date respectively.

Time        Constant time values can be entered in the format
            `HH:MM:SS', where `HH' represent the hours, 
            `MM' the minutes, and `SS' the seconds.

For some other pre-defined constant values, see Pre-defined constants.


16.4.8 Command Syntax

In the remainder of this chapter, you will find the description of all commands and functions available for programming MUIbase. The following syntax is used for describing the commands:

  • text written in brackets [] is optional. If you omit the text inside the brackets then a default value is assumed.
  • text separated by a vertical bar | denotes several options, e.g. `a | b' means that you can specify either `a' or `b'.
  • text written in a font like var indicates a place-holder that can be filled with other expressions.
  • dots ... indicate that further expressions can follow.
  • all other text is obligatory.


16.5 Defining Commands

This section lists commands for defining functions and global variables. The commands are only available for project programs.


16.5.1 DEFUN

DEFUN defines a function with the specified name, a list of arguments that are passed to the function, and a list of expressions to evaluate.

 
(DEFUN name (varlist) expr ...)

The name of a function must start with a lowercase character, followed by further characters, digits or underscore characters (see Name conventions).

The parameters varlist specifies the arguments of the function:

 
varlist: var1 ...

where var1 ... are the names for the arguments. The names must follow the same rules as the function name.

It is also possible to add type specifiers to the arguments (see Type specifiers).

The function executes the expressions expr, ... one by one and returns the value of the last expression. The function may call further functions including itself. A self defined function can be called like calling a pre-defined function.

For example to count the number of elements of a list, you can define the following function:

 
(DEFUN len (l)
    (IF (= l NIL)
        0
        (+ 1 (len (REST l)))
    )
)

Functions defined with DEFUN are listed in the pop-up list-views of table and attribute dialogs (see Creating tables and Creating attributes).

This command is only available for project programs.

See also DEFUN*, DEFVAR.


16.5.2 DEFUN*

DEFUN* is the star version of DEFUN and has the same effect as DEFUN (see DEFUN). The only difference is that functions defined with DEFUN* are not listed in the pop-up list-views when creating or changing tables and attributes. However, it is still possible to enter the function name in the corresponding string fields.

This command is only available for project programs.

See also DEFUN, DEFVAR.


16.5.3 DEFVAR

 
(DEFVAR var [expr])

Defines a global variable with initial value of expr or NIL if expr is missing. The name of the variables must start with a lowercase letter followed by further letters, digits or underscore characters (see Name conventions).

You can also add a type specifier to the variable name (see Type specifiers).

DEFVAR is only available for project programs. All DEFVAR commands should be placed on top of all function definitions.

After execution of a trigger function (when MUIbase returns to the user interface), all global variables loose their contents. They are re-initialized with their initial value expr on the next invocation of a trigger function. If this is not desired, use the DEFVAR* (see DEFVAR*) command which allows to store the value of global variables between program calls.

Please use global variables rarely (if at all). All global variables have to be initialized (and expr be evaluated if given) whenever a trigger function is called from outside.

Example: `(DEFVAR x 42)' defines a global variable `x' with value 42.

There are some pre-defined global variables in MUIbase (see Pre-defined variables).

See also DEFVAR*, DEFUN, DEFUN*, LET.


16.5.4 DEFVAR*

 
(DEFVAR* var [expr])

DEFVAR* has the same effect as the DEFVAR command (see DEFVAR) except that a variable defined with DEFVAR* does not loose its value after the program completes.

On the first invocation of the program, var is initialized with expr or NIL if expr is omitted. Subsequent calls of the program do not evaluate expr again but use the value of var from the previous call. This way it is possible to transfer information from one program call to another without storing data in an external file or a database table. Note, however, that all global variables defined with DEFVAR* loose their contents when the project program is re-compiled. If you wish to permanently store information, use a (possibly hidden) attribute in a table.

See also DEFVAR, DEFUN, DEFUN*, LET.


16.6 Program Control Functions

This section lists functions for program control, e.g. functions for defining local variables, loop functions, conditional program execution, loop control functions and more.


16.6.1 PROGN

To evaluate several expressions one by another the PROGN construction can be used.

 
([expr ...])

executes expr ... one by one. Returns the result of the last expression (or NIL if no expression has been specified). In Lisp this construct is known as (PROGN [expr ...]).

Example: `(1 2 3 4)' results to 4.

See also PROG1.


16.6.2 PROG1

Another way, besides the PROGN function, to evaluate several expressions one by another is the PROG1 expression.

 
(PROG1 [expr ...])

executes expr ... and returns the value of the first expression (or NIL if no expression has been specified).

Example: `(PROG1 1 2 3 4)' results to 1.

See also PROGN.


16.6.3 LET

LET defines a new block of local variables. This is useful, e.g., for defining local variables of a function. The syntax is

 
(LET (varlist) expr ...)

where varlist is a list of local variables.

 
varlist: varspec ...

 
varspec: (var expr) | var

Here var is the name of the variable and must start with a lowercase character, followed by further characters, digits or underscore characters (see Name conventions).

In the case of a (var expr) specification, the new variable is initialized with the given expression. In the other case the new variable is set to NIL.

It is also possible to add type specifiers to the variables. (see Type specifiers).

After initializing all variables the list of expressions expr ... are evaluated and the value of the last one is returned.

For example, the following LET expression

 
(LET ((x 0) y (z (+ x 1)))
    (+ x z)
)

results to 1.

See also DOTIMES, DOLIST, DO, DEFVAR.


16.6.4 SETQ

The SETQ function sets values to variables, attributes and tables.

 
(SETQ lvalue1 expr ...)

Sets lvalue1 to the value of expr. The dots indicate assignments for further lvalues. An lvalue is either a variable, an attribute in a table, or a table. In case of a variable, the variable must have been previously defined (e.g. by a LET expression).

Setting the value of a table means setting its program or GUI record pointer: `(SETQ Table expr)' sets the program record pointer of Table to the value of expr, `(SETQ Table* expr)' sets the GUI record pointer of it and updates the display. For more information about program and GUI record pointers, see Tables.

SETQ returns the value of the last expression.

Example: `(SETQ a 1 b 2)' assigns 1 to the variable `a', 2 to the variable `b' and returns 2.

See also SETQ*, LET, DEFVAR, Tables, Semantics of expressions.


16.6.5 SETQ*

SETQ* is the star version of SETQ (see SETQ) and has similar effects. The difference is that when assigning a value to an attribute, SETQ* calls the trigger function of that attribute (see Attribute trigger) instead of directly assigning the value. In case no trigger function has been specified for an attribute, SETQ* behaves like SETQ and simply assigns the value to the attribute.

Example: `(SETQ* Table.Attr 0)' calls the trigger function of `Table.Attr' with an argument of 0.

Warning: With this function it is possible to write endless loops, e.g. if you have defined a trigger function for an attribute and this function calls SETQ* to set a value to itself.

See also SETQ, LET, DEFVAR.


16.6.6 FUNCALL

FUNCALL is used to call a function with arguments.

 
(FUNCALL fun-expr [expr ...])

Calls the function fun-expr with the given arguments. The expression fun-expr can be any expression whose value is a pre-defined or user-defined function, e.g. a variable holding the function to call. If the number of arguments is not correct, an error message is generated.

FUNCALL returns the return value of the function call or NIL if fun-expr is NIL.

For more information about functional expressions, see Functional parameters.

See also APPLY.


16.6.7 APPLY

APPLY is used to apply a function to a list of arguments.

 
(APPLY fun-expr [expr ...] list-expr)

Applies the function fun-expr to a list created by cons'ing the arguments expr ... to list-expr. In other words: calls the function fun-expr with the arguments expr ... and list-expr expanded to its list elements.

The expression fun-expr can be any expression whose value is a pre-defined or user-defined function, e.g. a variable holding the function to call. The last argument list-expr must be a valid list or NIL, otherwise an error message is generated. If the number of arguments is not correct, an error occurs.

APPLY returns the return value of the function call or NIL if fun-expr is NIL.

For more information about functional expressions, see Functional parameters.

Example: `(APPLY + 4 (LIST 1 2 3))' returns 10.

See also FUNCALL.


16.6.8 IF

IF is a conditional operator.

 
(IF expr1 expr2 [expr3])

The expression expr1 is tested. If it results to non-NIL then the value of expr2 is returned else the value of expr3 (or NIL if not present) is returned.

This function is not strict, that is, only one expression of expr2 or expr3 will be evaluated.

See also CASE, COND.


16.6.9 CASE

CASE is similar to the switch statement in the C language.

 
(CASE expr [case ...])

Here expr is the selection expression and case ... are pairs consisting of:

 
case: (value [expr ...])

where value is a single expression or a list of expressions and expr ... are the expressions to be executed if one of the case expression matches.

The CASE expression first evaluates expr. Then each case pair is checked whether it (or one of the expressions in the list) matches the evaluated expression. If a matching case expression is found then the corresponding expressions are executed and the value of the last expression is returned. If no case matches, NIL is returned.

Example: `(CASE 1 ((2 3 4) 1) (1 2))' returns 2.

See also IF, COND.


16.6.10 COND

COND is, like IF, a conditional operator.

 
(COND [(test-expr [expr ...]) ...])

COND test the first expression of each list one by one. For the first one that does not result to NIL, the corresponding expressions expr ... are evaluated and the value of the last expression is returned.

If all tested expressions result to NIL then NIL is returned.

Example

 
(COND ((> 1 2) "1 > 2")
      ((= 1 2) "1 = 2")
      ((< 1 2) "1 < 2")
)

results to "1 < 2".

See also IF, CASE.


16.6.11 DOTIMES

For simple loops the DOTIMES command can be used.

 
(DOTIMES (name int-expr [result-expr ...]) [loop-expr ...])

Here name is the name of a new variable which will be used in the loop. The name must start with a lowercase character, followed by further characters, digits or underscore characters (see Name conventions).

The number of times the loop is executed is given in int-expr. In result-expr ... expressions can be specified that are executed after terminating the loop. In loop-expr you specify the body of the loop, that is, the expressions that are evaluated in each loop run.

Before executing the loop, DOTIMES computes the value of int-expr to determine the number of times the loop gets executed. Here int-expr is evaluated only once at the start of the loop and must result to an integer value. Then DOTIMES sets the loop variable to the values of 0 to int-expr-1 one by one for each loop run. First, the variable is initialized with zero and checked if it is already greater or equal to the value of expr. If int-expr is negative or NIL or if the variable is greater or equal to the value of expr then the loop is terminated and the result expressions are evaluated. Otherwise the loop expressions are evaluated and the variable is incremented by one. Then the execution returns to the termination test and, possibly, does further loop runs.

The DOTIMES expression returns the value of the last result expression or NIL if no result expression has been given.

Example

 
(DOTIMES (i 50 i) (PRINT i))

Prints the numbers from 0 to 49 and returns the value 50.

See also DOLIST, DO, FOR ALL, LET.


16.6.12 DOLIST

For loops through lists the DOLIST expression can be used.

 
(DOLIST (name list-expr [result-expr ...]) [loop-expr ...])

Here name is the name of a new variable which will be used in the loop. The name must start with a lowercase character, followed by further characters, digits or underscore characters (see Name conventions).

In list-expr you specify the list over which the loop should be executed, result-expr ... are expressions which are evaluated after terminating the loop, and loop-expr ... build the body of the loop.

Before executing the loop, DOLIST computes the value of list-expr. This expression is evaluated only once at the start of the loop and must result to a list value. Then DOTIMES sets the loop variable to the nodes of the list one by one for each loop run. First the loop variable is initialized to the first node of the list. If the list is already empty (NIL) then the loop is terminated and the result expressions are evaluated. Otherwise the loop expressions are evaluated and the variable is set to the next node of the list. Then the execution returns to the termination test and, possibly, does further loop runs.

The DOLIST expression returns the value of the last result expression or NIL if no result expression has been given.

Example

 
(DOLIST (i (SELECT * FROM Accounts)) (PRINT i))

Prints all records of table `Accounts' and returns NIL.

See also DOTIMES, DO, FOR ALL, LET.


16.6.13 DO

With the DO expression arbitrary loops can be programmed.

 
(DO ([binding ...]) (term-expr [result-expr ...]) [loop-expr ...])

where binding ... are the variable bindings, each of which is either:

  • a new name for a variable (which is initialized to NIL)
  • a list of the form: (name init [step]) where name is a name for the new variable, init is the initial value of the variable, and step is a step expression.

Furthermore, term-expr is the termination test expression, result-expr ... are the result expressions (the default is nil) and loop-expr ... build the body of the loop.

The DO loop first initializes all local variables with the init expressions, then tests the termination expression. If it results to TRUE, the loop is terminated and the result expressions are evaluated. The value of the last result expression is returned. Otherwise the body of the loop (loop-expr ...) is executed and each variable is updated by the value of its step expression. Then the execution returns to test the terminating expression and so on.

Example

 
(DO ((i 0 (+ i 1))) ((>= i 5) i) (PRINT i))

Prints the values 0, 1, 2, 3 and 4 and returns the value 5. Of course this is a quite complicated way to build a simple FOR loop. Therefore a simpler version exists, the DOTIMES expression.

See also DOTIMES, DOLIST, FOR ALL, LET.


16.6.14 FOR ALL

The FOR ALL expression is used to loop over a list of records.

 
(FOR ALL table-list [WHERE where-expr] [ORDER BY order-list] DO expr ...)

Here table-list is a comma-separated list of tables, where-expr an expression to test each set of records, order-list a comma-separated list of expressions by which the record sets are ordered, and expr ... are the expressions that are executed for each record set.

FOR ALL first generates a list of all record sets for which the loop body should be executed. This is done like in the SELECT expression. Please see SELECT, for more information about how this list is generated. For each element of this list the loop body expr ... is executed.

For example, summing up an attribute of a table can be done in the following way:

 
(SETQ sum 0)
(FOR ALL Accounts DO
    (SETQ sum (+ sum Accounts.Amount))
)

The FOR ALL expression returns NIL.

See also SELECT, DOTIMES, DOLIST, DO.


16.6.15 NEXT

NEXT can be used for controlling DOTIMES, DOLIST, DO and FOR ALL loops.

Calling NEXT in the body of a loop will jump to the next loop iteration. This can be used for skipping non-interesting loop runs, like e.g. in the following example:

 
(FOR ALL Table DO
    (IF not-interested-in-the-current-record (NEXT))
    ...
)

See also EXIT, DOTIMES, DOLIST, DO, FOR ALL.


16.6.16 EXIT

EXIT can be used to terminate a loop.

 
(EXIT [expr ...])

EXIT within a loop body will terminate the loop, execute the optional expressions expr ..., and return the value of the last expression (or NIL in case of no expression) as the return value of the loop. Possible return expressions of the loop as for example in

 
(DOTIMES (x 10 ret-expr ...) ...)

are not executed.

You may use the EXIT function for example to end a FOR ALL loop when you found the record you are interested in:

 
(FOR ALL Table DO
    (IF interested-in-the-current-record (EXIT Table))
    ...
)

See also NEXT, RETURN, HALT, DOTIMES, DOLIST, DO, FOR ALL.


16.6.17 RETURN

Within a function definition you can return to the caller by using the RETURN command.

 
(RETURN [expr ...])

terminates the function, executes the optional expressions expr ..., and returns the value of the last expression (or NIL in case of no expression).

Example

 
(DEFUN find-record (name)
    (FOR ALL Table DO
        (IF (= Name name) (RETURN Table))
    )
)

The example searches a record whose Name attribute matches the given name. The function returns the first record found or NIL in case of no record found.

See also HALT, EXIT.


16.6.18 HALT

HALT can be used to terminate program execution.

 
(HALT)

stops program execution silently.

See also ERROR, EXIT, RETURN.


16.6.19 ERROR

For aborting program execution with an error message the ERROR function can be used.

 
(ERROR fmt [arg ...])

stops program execution and pops up a dialog with an error message. The error message is generated from fmt and the optional arguments arg ... like in the SPRINTF function (see SPRINTF).

See also HALT, SPRINTF.


16.7 Type Predicates

For each type a predicate is defined that returns TRUE if the supplied expression is of the specified type and NIL otherwise. The predicates are:

 
Predicate           Description

(STRP expr)        TRUE if expr is of type string, NIL otherwise.

(MEMOP expr)       TRUE if expr is of type memo, NIL otherwise.

(INTP expr)        TRUE if expr is of type integer, NIL otherwise.

(REALP expr)       TRUE if expr is of type real, NIL otherwise.

(DATEP expr)       TRUE if expr is of type date, NIL otherwise.

(TIMEP expr)       TRUE if expr is of type time, NIL otherwise.

(NULL expr)        TRUE if expr is NIL (an empty list), NIL otherwise.

(CONSP expr)       TRUE if expr is a non-empty list, NIL otherwise.

(LISTP expr)       TRUE if expr is a list (may be NIL), NIL otherwise.

(RECP table expr)  TRUE if expr is a record pointer of the given table.
                    If expr is NIL then TRUE is returned (initial record).
                    If table is NIL then a check is done whether expr
                    is a record pointer of any table.


16.8 Type Conversion Functions

This section lists functions for converting values from one type to another one.


16.8.1 STR

STR can be used to convert an expression into a string representation.

 
(STR expr)

converts expr into a string representation. The type of expr determines the conversion:

 
Type            Return string

String          The string itself.

Memo            The whole memo text in one string.

Integer         String representation of integer value.

Real            String representation of real value.
                If expr is an attribute then the number
                decimals specified for this attribute are used,
                otherwise 2 decimals are used.

Choice          Label string of the choice attribute.

Date            String representation of date value.

Time            String representation of time value.

Boolean         The string "TRUE"

NIL             User defined nil string if expr is an attribute,
                the string "NIL" otherwise.

Record          String representation of record number.

Others          String representation of internal address pointer.

See also MEMO, SPRINTF.


16.8.2 MEMO

MEMO can be used to convert an expression into a memo.

 
(MEMO expr)

converts expr into a memo representation. It treats the expression like the STR function (see STR) but returns a memo text instead of a string.

See also STR.


16.8.3 INT

INT is used to convert an expression into an integer.

 
(INT expr)

converts expr into an integer value. Possible conversions are:

 
Type            Return value

String          If the complete string represents a valid integer value,
                it is converted into an integer.  A string starting
                with 0 is interpreted as an octal number, one starting
                with 0x as hexadecimal number.  Leading and following
                spaces are ignored.
                If the string does not represent an integer value, NIL 
                is returned.

Memo            Same as for string.

Integer         The value itself.

Real            If the value lies within the integer range than the real value
                is rounded and returned, otherwise NIL is returned.

Choice          The internal number (starting with 0) of the current label.

Date            Number of days since 01.01.0000.

Time            Number of seconds since 00:00:00.

Record          Record number.

NIL             NIL

Others          An error message is generated and program execution is aborted.

See also REAL, ASC.


16.8.4 REAL

REAL is used to convert an expression into a value of type real.

 
(REAL expr)

converts expr into a real. It treats the expression like the INT function (see INT) but returns a value of type real instead of an integer.

See also INT.


16.8.5 DATE

DATE is used to convert an expression into a date (with your favorite friend :-).

 
(DATE expr)

converts the given expression into a date value. Possible conversions are:

 
Type            Return value

String          If the whole string represents a date value then the
                string is converted into a date value. Leading and following
                spaces are ignored.
                If it does not represent a date value, NIL is returned.

Memo            Same as for string.

Integer         A date value is generated where the given integer represents
                the number of days since 01.01.0000. If the integer value is
                too great (date value would be greater than 31.12.9999) or
                negative then NIL is returned.

Real            Same as for integer.

Date            The value itself.

NIL             NIL

others          An error message is generated and program execution is aborted.

See also DATEDMY.


16.8.6 TIME

TIME is used to convert an expression into a time value.

 
(TIME expr)

converts the given expression into a time value. Possible conversions are:

 
Type            Return value

String          If the whole string represents a time value then the
                string is converted into a time value. Leading and following
                spaces are ignored.
                If it does not represent a time value, NIL is returned.

Memo            Same as for string.

Integer         A time value is generated where the given integer represents
                the number of seconds since 00:00:00.

Real            Same as for integer.

Time            The value itself.

NIL             NIL

others          An error message is generated and program execution is aborted.


16.9 Boolean Functions

This section lists Boolean operators.


16.9.1 AND

AND checks if all of its arguments are TRUE.

 
(AND [expr ...])

checks expr ... one by another until one expression evaluates to NIL. If all expressions evaluate to non-NIL then the value of the last expression is returned. Otherwise NIL is returned.

This function is non-strict which means that arguments of AND may not be evaluated, e.g. in `(AND NIL (+ 1 2))' the expression `(+ 1 2)' is not evaluated since a NIL value has already been processed, however in `(AND (+ 1 2) NIL)' the expression `(+ 1 2)' gets evaluated.

See also OR, NOT.


16.9.2 OR

OR checks if all of its arguments are NIL.

 
(OR [expr ...])

checks expr ... one by another until one expression evaluates to non-NIL. Returns the value of the first non-NIL expression or NIL if all expressions evaluate to NIL.

This function is non-strict which means that arguments of OR may not be evaluated, e.g. in `(OR TRUE (+ 1 2))' the expression `(+ 1 2)' is not evaluated since a non-NIL value (here `TRUE') has already been processed, however in `(OR (+ 1 2) TRUE)' the expression `(+ 1 2)' gets evaluated.

See also AND, NOT.


16.9.3 NOT

NOT is used to invert the value of a Boolean expression.

 
(NOT expr)

results to TRUE if expr is NIL, NIL otherwise.

See also AND, OR.


16.10 Comparison Functions

In this section you will find functions for comparing values.


16.10.1 Relational Operators

For comparing two values in a MUIbase program, use

 
(op expr1 expr2)

where op is in {=, <>, <, >, >=, <=, =*, <>*, <*, >*, >=*, <=*}. The star is used for special comparison (strings are compared case insensitive, records are compared by using the order defined by the user).

The following table shows all rules for comparing two values in a MUIbase program.

 
Type        Order relation

Integer     NIL < MIN_INT < ... < -1 < 0 < 1 < ... < MAX_INT

Real        NIL < -HUGE_VAL < ... < -1.0 < 0.0 < 1.0 < ... < HUGE_VAL

String:     NIL <  "" <  "Z" <  "a"  <  "aa" <  "b" < ... (case sensitive)
            NIL <* "" <* "a" <* "AA" <* "b" < ...       (case insensitive)

Memo:       same as string

Date        NIL < 1.1.0000 < ... < 31.12.9999

Time        NIL < 00:00:00 < ... < 596523:14:07 

Boolean     NIL < TRUE

Record:     NIL < any_record    (records itself are not comparable with <)
            NIL <* rec1 <* rec2 (order specified by user)

See also CMP, CMP*, LIKE.


16.10.2 CMP

CMP returns an integer representing the order of its arguments.

 
(CMP expr1 expr2)

returns a value less than 0 if expr1 is smaller than expr2, 0 if expr1 is equal to expr2, and a value greater than 0 if expr1 is greater than expr2. For determining the order the simple (non-star) order relation as for relational operators (see Relational operators) is used.

Do not assume that the returned value will always be -1, 0, or 1!

Example: `(CMP "Bike" "bIKE")' results to -1.

See also CMP*, Relational operators.


16.10.3 CMP*

CMP* is the star version of CMP. The difference is that CMP* uses the extended ordering as defined for relational operators (see Relational operators) where strings are compared case insensitive and records are compared using the user defined record order.

Example: `(CMP* "Bike" "bIKE")' results to 0.

See also CMP, Relational operators.


16.10.4 MAX

MAX returns the argument that has the largest value.

 
(MAX [expr ...])

Returns the maximum value of the arguments expr .... If no arguments are given then NIL is returned. For determining the largest element the simple (non-star) order relation as for relational operators (see Relational operators) is used.

See also MAX*, MIN, Relational operators.


16.10.5 MAX*

MAX* is the star version of MAX. The difference is that MAX* uses the extended ordering as defined for relational operators (see Relational operators) where strings are compared case insensitive and records are compared using the user defined record order.

Example: `(MAX* "x" "Y")' results to "Y".

See also MAX, MIN*, Relational operators.


16.10.6 MIN

MIN returns the argument that has the smallest value.

 
(MIN [expr ...)]

Returns the minimum value of the arguments expr .... If no arguments are given then NIL is returned. For determining the smallest element the simple (non-star) order relation as for relational operators (see Relational operators) is used.

See also MIN*, MAX, Relational operators.


16.10.7 MIN*

MIN* is the star version of MIN. The difference is that MIN* uses the extended ordering as defined for relational operators (see Relational operators) where strings are compared case insensitive and records are compared using the user defined record order.

Example: `(MIN* "x" "Y")' results to "x".

See also MIN, MAX*, Relational operators.


16.11 Mathematical Functions

Here, some mathematical functions are listed.


16.11.1 Adding Values

For adding values, use

 
(+ expr ...)

Returns the sum of the arguments expr .... If any argument value is NIL then the result is NIL. If the values are of type real or integer then a real (or integer) value is the result.

You may also add strings or memos. In this case the result is the concatenation of the strings/memos.

If expr is of type date and the rest of the arguments are integers/reals then the sum of integers/reals are interpreted as a number of days and added to expr. If the resulting date is out of range (smaller than 1.1.0000 or greater than 31.12.9999) then NIL is the result.

If expr is of type time and the rest of the arguments are integers/reals or other time values then the sum of integers/reals (interpreted as a number of seconds) and time values are added to expr. If the resulting time is out of range (smaller than 00:00:00 or greater than 596523:14:07) then NIL is the result.

Examples

 
Expression                       Value

(+ 1 2 3)                        6
(+ 5 1.0)                        6.0
(+ "Hello" " " "world!")         "Hello world!"
(+ 28.11.1968 +365 -28 -9)       22.10.1969
(+ 07:30:00 3600)                08:30:00
(+ 03:00:00 23:59:59)            26:59:59

See also -, 1+, *, CONCAT, CONCAT2, ADDMONTH, ADDYEAR.


16.11.2 Subtracting Values

For subtracting values, use

 
(- expr1 expr2 ...)

Subtracts the sum of expr2 ... from expr1. Here the same rules apply as for adding values (see +), except that strings and memos can't be subtracted.

(- expr) has a special meaning, it returns the negative value of expr (integer or real), e.g. `(- (+ 1 2))' results to -3.

See also +, 1-.


16.11.3 1+

1+ increases an integer or real expression by one.

 
(1+ expr)

Returns the value of expr (integer or real) plus one. If expr is NIL then NIL is returned.

See also +, 1-.


16.11.4 1-

1- decreases an integer or real expression by one.

 
(1- expr)

Returns the value of expr (integer or real) minus one. If expr is NIL then NIL is returned.

See also -, 1+.


16.11.5 Multiplying Values

For multiplying integer/real values, use

 
(* expr ...)

Returns the multiplication of the integer/real values expr .... If all arguments are integers then an integer is returned, otherwise the result is a value of type real.

See also +, /.


16.11.6 Dividing Values

For dividing integer/real values, use

 
(/ expr1 [expr2 ...])

Divides expr1 by the multiplication of the rest of the arguments. Returns a real value. On division by zero, NIL is returned.

See also *, DIV, MOD.


16.11.7 DIV

DIV is used for integer division.

 
(DIV int1 int2)

Returns the integer division of int1 with int2. For example, `(DIV 5 3)' results to 1.

See also /, MOD.


16.11.8 MOD

MOD is used for modulo calculation.

 
(MOD int1 int2)

Returns int1 modulo int2. For example, `(MOD 5 3)' results to 2.

See also DIV.


16.11.9 ABS

ABS computes the absolute value of an expression.

 
(ABS expr)

Returns the absolute value of expr (integer or real). If expr is NIL then NIL is returned.


16.11.10 TRUNC

TRUNC truncates decimals of a real value.

 
(TRUNC real)

Returns the largest integer (as a real number) not greater than the specified real number. If real is NIL then NIL is returned.

Examples: `(TRUNC 26.1)' results to 26, `(TRUNC -1.2)' results to -2.

See also ROUND.


16.11.11 ROUND

ROUND rounds a real value.

 
(ROUND real digits)

Returns the specified real number rounded to digits decimal digits. If real or digits are NIL then NIL is returned.

Examples: `(ROUND 70.70859 2)' results to 70.71, `(ROUND 392.36 -1)' results to 390.0.

See also TRUNC.


16.11.12 RANDOM

RANDOM can be used to generate random numbers.

 
(RANDOM expr)

Returns a random number. On the first call the random number generator is initialized with a value generated from the current time. RANDOM generates a random number in the range of 0 ... expr, excluding the value of expr itself. The type of expr (integer or real) is the return type. If expr is NIL then NIL is returned.

Examples:

 
Example                 Meaning

(RANDOM 10)             returns a value from 0 to 9,
(RANDOM 10.0)           returns a value from 0.0 to 9.99999...


16.11.13 POW

POW computes the power of values.

 
(POW x y)

Returns the value of real value x raised to the power of real value y. If either x or y are NIL, or if x is negative and y not an integral number, then NIL is returned.

Example: `(POW 2 3)' results to 8.

See also SQRT, EXP.


16.11.14 SQRT

SQRT computes the square root of a number.

 
(SQRT x)

Returns the square root of real value x. If x is NIL or a negative number then NIL is returned.

See also POW.


16.11.15 EXP

EXP computes the exponential function.

 
(EXP x)

Returns the value of the base of the natural logarithm raised to the power of real value x. If x is NIL then NIL is returned.

See also POW, LOG.


16.11.16 LOG

LOG computes the natural logarithm of a number.

 
(LOG x)

Returns the natural logarithm of real value x. If x is NIL or not a positive number then NIL is returned.

See also EXP.


16.12 String Functions

This section deals with functions useful for strings.


16.12.1 LEN

LEN computes the length of a string.

 
(LEN str)

Returns the length of the given string or NIL if str is NIL.

See also WORDS, LINES, MAXLEN.


16.12.2 LEFTSTR

LEFTSTR extracts a sub string out of a string.

 
(LEFTSTR str len)

Returns the left part of the given string with at most len characters. If str or len are NIL or if len is negative then NIL is returned.

Example: `(LEFTSTR "Hello world!" 5)' results to "Hello".

See also RIGHTSTR, MIDSTR, WORD, LINE.


16.12.3 RIGHTSTR

RIGHTSTR extracts a sub string out of a string.

 
(RIGHTSTR str len)

Returns the right part of the given string with at most len characters. If str or len are NIL or if len is negative then NIL is returned.

Example: `(RIGHTSTR "Hello world!" 6)' results to "world!".

See also LEFTSTR, MIDSTR, WORD, LINE.


16.12.4 MIDSTR

MIDSTR extracts a sub string out of a string.

 
(MIDSTR str pos len)

Returns a part of the given string with at most len characters. The sub string starts at the pos-th position (starting with zero). If len is NIL then the full sub string starting at pos is returned. If str is NIL or if len is negative then NIL is returned. If pos is out of range, that is, negative or greater than the string length, NIL is returned.

Example: `(MIDSTR "Hello world!" 3 5)' results to "lo wo".

See also LEFTSTR, RIGHTSTR, WORD, LINE, SETMIDSTR, INSMIDSTR.


16.12.5 SETMIDSTR

SETMIDSTR replaces a sub string in a string.

 
(SETMIDSTR str index set)

Returns a copy of string str where the sub string starting at index is overwritten with string set. The length of the returned string is greater or equal to the length of str. If one of the arguments is NIL or if index is out of range then NIL is returned.

Example: `(SETMIDSTR "Hello world!" 6 "Melanie!")' results to "Hello Melanie!".

See also INSMIDSTR, REPLACESTR.


16.12.6 INSMIDSTR

INSMIDSTR is used to insert a sub string into a string.

 
(INSMIDSTR str index insert)

Returns a copy of string str where the string insert has been inserted at the given index. If one of the arguments is NIL or if index is out of range then NIL is returned.

Example: `(INSMIDSTR "Hello world!" 6 "MUIbase-")' results to "Hello MUIbase-world!".

See also SETMIDSTR, REPLACESTR.


16.12.7 INDEXSTR

INDEXSTR searches a string for the first occurrence of a sub string.

 
(INDEXSTR str substr)

Searches for the first occurrence of substr in str. String comparison is done case-sensitive. Returns the index (starting with 0) of the sub string in str or NIL if the sub string is not present. If one of the arguments is NIL then NIL is returned.

Example: `(INDEXSTR "Hello world!" "world")' returns 6.

See also INDEXSTR*, RINDEXSTR, RINDEXSTR*, INDEXBRK, INDEXBRK*.


16.12.8 INDEXSTR*

INDEXSTR* has the same effect as INDEXSTR (see INDEXSTR) except that string comparison is done case-insensitive.

See also INDEXSTR, RINDEXSTR, RINDEXSTR*, INDEXBRK, INDEXBRK*.


16.12.9 INDEXBRK

INDEXBRK searches for the first occurrence of a character in a string.

 
(INDEXBRK str brkstr)

Searches for the first occurrence of a character from brkstr in str. String comparison is done case-sensitive. Returns the index (starting with 0) of the first character found in str or NIL if no character is found. If one of the arguments is NIL then NIL is returned.

Example: `(INDEXBRK "Hello world!" "aeiou")' returns 1.

See also INDEXBRK*, RINDEXBRK, RINDEXBRK*, INDEXSTR, INDEXSTR*.


16.12.10 INDEXBRK*

INDEXBRK* has the same effect as INDEXBRK (see INDEXBRK) except that string comparison is done case-insensitive.

See also INDEXBRK, RINDEXBRK, RINDEXBRK*, INDEXSTR, INDEXSTR*.


16.12.11 RINDEXSTR

RINDEXSTR searches a string for the last occurrence of a sub string.

 
(RINDEXSTR str substr)

Searches for the last occurrence of substr in str. String comparison is done case-sensitive. Returns the index (starting with 0) of the sub string in str or NIL if the sub string is not present. If one of the arguments is NIL then NIL is returned.

Example: `(RINDEXSTR "Do itashimashite." "shi")' returns 11.

See also RINDEXSTR*, INDEXSTR, INDEXSTR*, RINDEXBRK, RINDEXBRK*.


16.12.12 RINDEXSTR*

RINDEXSTR* has the same effect as RINDEXSTR (see RINDEXSTR) except that string comparison is done case-insensitive.

See also RINDEXSTR, INDEXSTR, INDEXSTR*, RINDEXBRK, RINDEXBRK*.


16.12.13 RINDEXBRK

RINDEXBRK searches for the last occurrence of a character in a string.

 
(RINDEXBRK str brkstr)

Searches for the last occurrence of a character from brkstr in str. String comparison is done case-sensitive. Returns the index (starting with 0) of the last character found in str or NIL if no character is found. If one of the arguments is NIL then NIL is returned.

Example: `(RINDEXBRK "Konnichiwa" "chk")' returns 6.

See also RINDEXBRK*, INDEXBRK, INDEXBRK*, RINDEXSTR, RINDEXSTR*.


16.12.14 RINDEXBRK*

RINDEXBRK* has the same effect as RINDEXBRK (see RINDEXBRK) except that string comparison is done case-insensitive.

See also RINDEXBRK, INDEXBRK, INDEXBRK*, RINDEXSTR, RINDEXSTR*.


16.12.15 REPLACESTR

REPLACESTR replaces sub strings by other strings.

 
(REPLACESTR str [substr1 replacestr1 ...])

Replaces all occurrences of substr1 in str by replacestr1. Continues replacing further sub strings in the new string using the next pair of search and replacement string until all arguments have been processed. Note that the number of arguments must be odd with arguments at even positions specifying the search strings each followed by the replacement string. Due to the fact that the result of a replacement is used in the next following replacement, multiple replacements can take place. This should be considered when using this function. A different order of the arguments might help resolving conflicts since replacements are done from left to right.

If any of the strings are NIL or any search string is empty then NIL is returned.

Example: `(REPLACESTR "black is white" "black" "white" "white "black")' results to "black is black".

See also REPLACESTR*, SETMIDSTR, INSMIDSTR, REMCHARS.


16.12.16 REPLACESTR*

REPLACESTR* has the same effect as REPLACESTR (see REPLACESTR) except that string comparison is done case-insensitive for searching sub strings.

See also REPLACESTR, SETMIDSTR, INSMIDSTR, REMCHARS.


16.12.17 REMCHARS

REMCHARS removes characters from a string.

 
(REMCHARS str chars-to-remove)

Returns a copy of str where all characters of chars-to-remove are removed from. If str or chars-to-remove are NIL then NIL is returned.

Example: `(REMCHARS your-string " \t\n")' removes all spaces, tabs and newline characters from your-string.

See also REPLACESTR, TRIMSTR.


16.12.18 TRIMSTR

TRIMSTR removes leading and trailing characters from a string.

 
(TRIMSTR str [front back])

Returns a copy of str where leading and trailing characters have been removed. If called with one argument only, spaces, form-feeds, newlines, carriage returns, and horizontal and vertical tabs are removed. When called with three arguments, front specifies the leading and back specifies the trailing characters to be removed. Note that TRIMSTR cannot be called with two arguments.

If any of str, front, or back is NIL then NIL is returned.

Example: (TRIMSTR " I wrecked Selma's bike. ") results to "I wrecked Selma's bike.", (TRIMSTR "007 " "0" " \f\n\r\t\v") results to "7".

See also REMCHARS.


16.12.19 WORD

WORD returns a word of a string.

 
(WORD str num)

Returns the num-th word (starting with zero) of the given string. Words in a string are non-empty sub strings separated by one or more non-breakable space characters (e.g. space, tab or newline characters).

If str or num are NIL, or if num is out of range, that is, less than zero or greater or equal to the number of words, then NIL is returned.

Example: `(WORD "Therefore, I lend Selma my bike." 3)' results to "Selma".

See also WORDS, LINE, FIELD, LEFTSTR, RIGHTSTR, MIDSTR, STRTOLIST.


16.12.20 WORDS

WORDS counts the number of words in a string.

 
(WORDS str)

Returns the number of words of the given string or NIL if str is NIL. Words are sub strings separated by one or more non-breakable space characters (e.g. space, tab, or newline characters).

Example: `(WORDS "Actually, it wasn't really my bike.")' results to 6.

See also WORD, FIELDS, LINES, LEN.


16.12.21 FIELD

FIELD returns a field in a string.

 
(FIELD str num [sep [quotes]])

Returns the num-th field (starting with zero) of the given string. Fields in a string are sub strings separated by exactly one separator character. A field may be an empty string. Argument sep contains the characters that separate fields. If sep is NIL or not provided then non-breakable space characters (e.g. space, tab, or newline characters) are used. If quotes is given and not NIL then fields can be surrounded by double quotes and may contain separator characters. The double quotes are stripped when returning the field.

If str or num are NIL, or if num is out of range, that is, less than zero or greater or equal to the number of fields, then NIL is returned.

Example: `(FIELD "My name is \"Darth Vader\"" 3 " " TRUE)' results to "Darth Vader".

See also FIELDS, WORD, LEFTSTR, RIGHTSTR, MIDSTR, STRTOLIST.


16.12.22 FIELDS

FIELDS counts the number of fields in a string.

 
(FIELDS str [sep [quotes]])

Returns the number of fields in the given string or NIL if str is NIL. Fields in a string are sub strings separated by exactly one separator character. A field may be an empty string. Argument sep contains the characters that separate fields. If sep is NIL or not provided then non-breakable space characters (e.g. space, tab, or newline characters) are used. If quotes is given and not NIL then fields can be surrounded by double quotes and may contain separator characters.

See also FIELD, WORDS, LEN.


16.12.23 STRTOLIST

STRTOLIST converts a string to a list of sub-strings.

 
(STRTOLIST str [sep])

Creates a list of sub-strings by breaking the string str at the occurrences of the separation sequence sep. If sep is not specified then the tab character "\t" is used. If sep is the empty string "" then a list of all characters in the string is returned.

If str or sep are NIL then NIL is returned.

Examples

`(STRTOLIST "I\tlike\tJapan.")' results to ( "I" "like" "Japan." ).

`(STRTOLIST "Name|Street|City" "|")' results to ( "Name" "Street" "City" ).

`(STRTOLIST "abc" "")' results to ( "a" "b" "c" ).

See also MEMOTOLIST, LISTTOSTR, WORD.


16.12.24 LISTTOSTR

LISTTOSTR converts a list of items into a string.

 
(LISTTOSTR list [sep])

Converts the given list of items into a string by concatenation of the string representations of each list element separated by the sequence sep. If sep is not specified then the tab character "\t" is used. If list or sep are NIL then NIL is returned.

Examples

`(LISTTOSTR (LIST "Peter is" 18 "years old"))' results to: "Peter is\t18\tyears old".

`(LISTTOSTR (LIST "Name" "Street" "City") "|")' results to: "Name|Street|City".

See also LISTTOMEMO, CONCAT, CONCAT2, STRTOLIST.


16.12.25 CONCAT

CONCAT concatenates strings.

 
(CONCAT [str ...])

Returns the concatenation of the given list of strings where space characters have been inserted between the strings. If one of the strings is NIL, or the list is empty, then NIL is returned.

Example: `(CONCAT "I" "thought" "it" "was" "an "abandoned" "bike.")' results to "I thought it was an abandoned bike.".

See also CONCAT2, +, LISTTOSTR, COPYSTR, SPRINTF.


16.12.26 CONCAT2

CONCAT2 concatenates strings.

 
(CONCAT2 insert [str ...])

Returns the concatenation of the given list of strings. The strings will be separated with the given insert string. If insert is NIL, one of the strings is NIL, or the list is empty, then NIL is returned.

Example: `(CONCAT2 "! " "But" "it" "wasn't!")' results to "But! it! wasn't!".

See also CONCAT, +, LISTTOSTR, COPYSTR, SPRINTF.


16.12.27 COPYSTR

COPYSTR creates copies of a string.

 
(COPYSTR str num)

Returns a string consisting of num times the string str. If str is NIL, num is NIL or less than zero, NIL is returned.

Example: `(COPYSTR "+-" 5)' results to "+-+-+-+-+-".

See also CONCAT CONCAT2, +, SPRINTF.


16.12.28 SHA1SUM

SHA1SUM computes the SHA1 hash of a string.

 
(SHA1SUM str)

Returns a string containing the SHA1 hash of the given string. If str is NIL then NIL is returned.

Example: `(SHA1SUM "flower, sun and beach")' results to "47b6c496493c512b40e042337c128d85ecf15ba4".

See also ADMINPASSWORD, demo `Users.mb'.


16.12.29 UPPER

UPPER converts a string to upper case.

 
(UPPER str)

Returns a copy of the given string where all characters are converted to upper case. If str is NIL then NIL is returned.

Example: `(UPPER "Selma found a letter attached to my bike.")' results to "SELMA FOUND A LETTER ATTACHED TO MY BIKE.".

See also LOWER.


16.12.30 LOWER

LOWER converts a string to lower case.

 
(LOWER str)

Returns a copy of the given string where all characters are converted to lower case. If str is NIL then NIL is returned.

Example: `(LOWER "The letter was from Silke.")' results to "the letter was from silke.".

See also UPPER.


16.12.31 ASC

ASC converts a character to its internal integer representation.

 
(ASC str)

Returns the internal integer code of the first character of str. On Windows, Mac OS and Linux this is the unicode representation. On Amiga, it is the 8-bit integer code in the default character encoding. If str is empty, 0 is returned. If str is NIL, NIL is returned.

Example: (ASC "A") results to 65.

See also CHR, INT.


16.12.32 CHR

CHR converts an integer code to a character.

 
(CHR int)

Returns a string containing the character with integer code int. On Windows, Mac OS and Linux, int is interpreted as a unicode character. On Amiga, int is the 8-bit integer in the default character encoding. If int is 0, an empty string is returned. If int is NIL or not in the range of valid character values, NIL is returned.

Example: `(CHR 67)' results to "C".

See also ASC, STR.


16.12.33 LIKE

LIKE compares strings.

 
(LIKE str1 str2)

Returns TRUE if str1 matches str2, NIL otherwise. The string str2 may contain the joker characters '?' and '*' where '?' matches exactly one character and '*' matches a string of any length. String comparison is done case insensitive.

Example: `(LIKE "Silke has been in France for one year." "*France*")' results to TRUE.

See also Comparison functions.


16.12.34 SPRINTF

SPRINTF formats a string with various data.

 
(SPRINTF fmt [expr ...])

SPRINTF takes a series of arguments, converts them to strings, and returns the formatted information as one string. The string fmt determines exactly what gets written to the return string and may contain two types of items: ordinary characters which are always copied verbatim and conversion specifiers which direct SPRINTF to take arguments from its argument list and format them. Conversion specifiers always begin with a `%' character.

Conversion specifiers always take the following form:

 
%[flags][width][.precision]type

where

  • The optional flags field controls output justification, sign character on numerical values, decimal points, and trailing blanks.

  • The optional width field specifies the minimum number of characters to print (the field width), with padding done with blanks or zeros.

  • The optional precision field specifies either the maximum number of characters to be printed for types string, Boolean, date and time, or the number of digits after the decimal point to be printed for values of type real.

  • The type field specifies the actual type of the argument that SPRINTF will be converting, such as string, integer, real, etc.

Note that all of the above fields are optional except for type. The following tables list the valid options for these fields.

Flags field

-:
The result is left justified, with padding done on the right using blanks. By default when `-' is not specified, the result is right justified with padding on the left with `0''s or blanks.

+:
The result will always have a `-' or `+' character prepended to it if it is a numeric conversion.

0:
For numbers padding on the left is done using leading zeros instead of spaces.

space:
Positive numbers begin with a space instead of a `+' character, but negative values still have a prepended `-'.

Width field

n:
A minimum of n characters are output. If the conversion has less than n characters, the field is padded with blanks or leading zeros.

*:
The width specifier is supplied in the argument list as an integer or real value, before the actual conversion argument. This value is limited to the range of 0 to 999.

Precision field

.n:
For string, Boolean, date and time values, n is the maximum number of characters written from the converted item. For conversions of real values, n specifies the number of digits after the decimal point (conversions `f' and `e') or the number of significant digits (conversion `g'). For integer conversions this field is ignored.

.*:
The precision is supplied in the argument list as an integer or real value, before the actual conversion argument. This value is limited to the range of 0 to 999.

Type field

b:
Converts a Boolean parameter to "TRUE" or "NIL".
i:
Converts an integer value to a signed decimal notation.
o:
Converts an integer value to an unsigned octal notation.
x:
Converts an integer value to an unsigned hexadecimal notation using lowercase letters `abcdef'.
X:
Converts an integer value to an unsigned hexadecimal notation using uppercase letters `ABCDEF'.
e:
Converts a real number using the format [-]d.ddde+dd. Exactly one digit is before the decimal point, followed by an `e', followed by an exponent. The number of digits after the decimal point is determined by the precision field, or is 2 if precision is not specified. The decimal point will not appear if precision is 0.
f:
Converts a real value using the format [-]ddd.ddd. The number of digits after the decimal point is determined by the precision field, or is 2 if precision is not specified. The decimal point will not appear if precision is 0.
g:
Converts a real value using style `e' or `f' depending on the number of digits for representing the value. If the precision is not specified then 15 significant digits are used. Trailing zeros other than a single zero after the decimal point are removed.
s:
Writes a string value until either the end of string is reached or the number of characters written equals the precision field.
d:
Converts a date value.
t:
Converts a time value.
%:
The character `%' is written, and no argument is converted.

SPRINTF returns the formatted string or NIL in case fmt is NIL.

Examples

 
Call                      Result

(SPRINTF "Hello")                "Hello"
(SPRINTF "%s" "Hello")           "Hello"
(SPRINTF "%10s" "Hello")         "     Hello"
(SPRINTF "%-10.10s" "Hello")     "Hello     "
(SPRINTF "%010.3s" "Hello")      "       Hel"
(SPRINTF "%-5.3b" TRUE)          "TRU  "
(SPRINTF "%i" 3)                 "3"
(SPRINTF "%03i" 3)               "003"
(SPRINTF "%0- 5.3i" 3)           " 3   "
(SPRINTF "%f" 12)                "12.00"
(SPRINTF "%10e" 12.0)            "  1.20e+01"
(SPRINTF "%+-10.4f" 12.0)        "+12.0000  "
(SPRINTF "%10.5t" 12:30:00)      "     12:30"
(SPRINTF "%d" 28.11.1968)        "28.11.1968"
(SPRINTF "He%s %5.5s!"
   "llo"
   "world champion ship")        "Hello world!"

See also PRINTF, FPRINTF, STR, +, CONCAT, CONCAT2, COPYSTR.


16.13 Memo Functions

This section deals with functions useful for memos.


16.13.1 LINE

LINE extracts a line in a memo.

 
(LINE memo num)

Returns the num-th line (starting with zero) of the given memo. The line string will not have a terminating newline character. If memo or num are NIL or if num is out of range, that is, less than zero or greater or equal to the number of lines, then NIL is returned.

See also LINES, WORD.


16.13.2 LINES

LINES returns the number of lines in a memo.

 
(LINES memo)

Returns the number of lines of the given memo or NIL if memo is NIL.

See also LINE, WORDS, LEN.


16.13.3 MEMOTOLIST

MEMOTOLIST converts a memo into a list of strings.

 
(MEMOTOLIST memo [expandstr])

Converts the given memo to a list. If memo is NIL then NIL is returned, otherwise a list is generated where each element contains one line of the memo.

If expandstr is given and is not NIL then resulting list of strings is further processed by applying STRTOLIST to each list element. This results into a list of lists of strings.

Examples

`(MEMOTOLIST "My insurance\npays for\nthe wrecked bike.")' results to ( "My insurance" "pays for" "the wrecked bike." ).

`(MEMOTOLIST "Here is\ta multi-columned\nexample." TRUE)' results to ( ( "Here is" "a multi-columned" ) ( "example" ) ).

See also STRTOLIST, LISTTOMEMO.


16.13.4 LISTTOMEMO

LISTTOMEMO converts a list into a memo.

 
(LISTTOMEMO list)

Converts the given list into a memo. If list is NIL then NIL is returned, otherwise a memo is generated where each line consists of the string representation of the corresponding list element. If a list element is a sub-list then LISTTOSTR (see LISTTOSTR) is applied on it before integrating the resulting string into the memo.

Examples

`(LISTTOMEMO (LIST "Silke" "lends me" "'my' bike" "till" 01.09.1998)' results to: "Silke\nlends me\n'my' bike\ntill\n01.09.1998".

`(LISTTOMEMO (LIST (LIST "Name" "Birthday") (LIST "Steffen" 28.11.1968)' results to: "Name\tBirthday\nSteffen\t28.11.1968".

See also LISTTOSTR, MEMOTOLIST.


16.13.5 FILLMEMO

FILLMEMO fills in a memo with the results of expressions.

 
(FILLMEMO memo)

Creates a copy of the given memo where all substrings of the form `$(expr)' are replaced by their results after evaluation.

Example: `(FILLMEMO "(+ 1 1) is $(+ 1 1).")' results to "(+ 1 1) is 2."

Please use only small expressions in the memo as debugging and tracking down errors is not easy here.

See also FORMATMEMO, INDENTMEMO.


16.13.6 FORMATMEMO

FORMATMEMO formats a memo.

 
(FORMATMEMO memo width [fill [singlelinesec]])

Formats memo to a memo with lines not longer than width characters. If fill is given and non-NIL then spaces are used to pad the lines to exactly width characters. The memo is processed section-wise. A section starts at the first non-white-space character. If singlelinesec is specified and non-NIL then all characters until the end of this line are taken as the section. Otherwise, all characters on this and the following lines are counted as the section until a line starting with a white-space character is reached. The whole section is formated word-wise, that is, as many words are put on one line as there are space for. Remaining words are then put on the next line and so on.

See also FILLMEMO, INDENTMEMO.


16.13.7 INDENTMEMO

INDENTMEMO indents a memo by putting spaces to the left.

 
(INDENTMEMO memo indent)

Returns a copy of the given memo where each line is indented by indent space characters. If memo or indent is NIL then NIL is returned. If indent is negative, a value of 0 is used.

See also FILLMEMO, FORMATMEMO.


16.14 Date and Time Functions

This section deals with functions useful for date and time values.


16.14.1 DAY

DAY extracts the day field of a date.

 
(DAY date)

Returns an integer representing the day of the given date value. If date is NIL then NIL is returned.

See also MONTH, YEAR, DATEDMY.


16.14.2 MONTH

MONTH extracts the month field of a date.

 
(MONTH date)

Returns an integer representing the month of the given date value. If date is NIL then NIL is returned.

See also DAY, YEAR, DATEDMY, MONTHDAYS.


16.14.3 YEAR

YEAR extracts the year field of a date.

 
(YEAR date)

Returns an integer representing the year of the given date value. If date is NIL then NIL is returned.

See also DAY, MONTH, DATEDMY, YEARDAYS.


16.14.4 DATEDMY

DATEDMY creates a date value from day, month, and year.

 
(DATEDMY day month year)

Creates a date value from the given day, month, and year. If any of day, month, or year is NIL or out of the valid range, or if the resulting date is invalid, then NIL is returned.

Example: `(DATEDMY 28 11 1968)' results to the 28th of November, 1968.

See also DATE, TODAY, DAY, MONTH, YEAR.


16.14.5 MONTHDAYS

MONTHDAYS gets the number of days of a month.

 
(MONTHDAYS month year)

Returns the number of days of the given month and year as an integer. If month is NIL or out of the valid range (less than 1 or greater than 12) then NIL is returned. If year is NIL then a non-leap year is considered for computing the number of days. If year is invalid (less than 0 or greater than 9999) then NIL is returned.

Examples: `(MONTHDAYS 2 2004)' results to 29, `(MONTHDAYS 2 NIL)' results to 28.

See also YEARDAYS, MONTH.


16.14.6 YEARDAYS

YEARDAYS gets the number of days of a year.

 
(YEARDAYS year)

Returns the number of days of the given year as an integer. If year is NIL or out of the valid range (less than 0 or greater than 9999) then NIL is returned.

Examples: `(YEARDAYS 2004)' results to 366, `(YEARDAYS 2005)' results to 365.

See also MONTHDAYS, YEAR.


16.14.7 ADDMONTH

ADDMONTH adds a number of months to a date.

 
(ADDMONTH date months)

Returns a date value where the given number of months has been added to the given date value. Negative values for months subtract months. If date or months is NIL, or the resulting date is invalid, then NIL is returned.

ADDMONTH handles over- and underflow of the month field by adjusting the year field accordingly. In case the day field exceeds the maximum number of days of the resulting month, it is decremented to the maximum allowed day.

Examples: `(ADDMONTH 30.01.2004 1)' results to 29.02.2004, `(ADDMONTH 30.01.2004 -1)' results to 30.12.2003.

See also ADDYEAR, +.


16.14.8 ADDYEAR

ADDYEAR adds a number of years to a date.

 
(ADDYEAR date years)

Returns a date value where the given number of years has been added to the given date value. Negative values for years subtract years. If date or years is NIL, or the resulting date is invalid, then NIL is returned.

ADDYEAR decrements the day field by 1 in case date represents February 29th and the resulting year is not a leap year.

Examples: `(ADDYEAR 29.02.2004 1)' results to 28.02.2005, `(ADDMONTH 04.02.2004 -1962)' results to 04.02.0042.

See also ADDMONTH, +.


16.14.9 TODAY

TODAY returns the current date.

 
(TODAY)

Returns the current date as a date value.

See also NOW, DATEDMY.


16.14.10 NOW

NOW returns the current time.

 
(NOW)

Returns the current time as a time value.

See also TODAY.


16.15 List Functions

This section lists functions for processing lists.


16.15.1 CONS

CONS builds a pair of expressions.

 
(CONS elem list)

Constructs a new list. The first element of the new list is elem, the rest are the elements of list (which should be a list or NIL). The list list is not copied, only a pointer is used to reference it!

Example: `(CONS 1 (CONS 2 NIL))' results to ( 1 2 ).

The elements of a list can be of any type, e.g. it's also possible to have a list of lists (e.g. see SELECT). The CONS constructor can also be used to build pairs of elements, e.g. `(CONS 1 2)' is the pair with the two integers 1 and 2.

See also LIST, FIRST, REST.


16.15.2 LIST

LIST generates a list out of its arguments.

 
(LIST [elem ...])

takes the arguments elem ... and generates a list of it. This is equivalent to calling (CONS elem (CONS ... NIL)). Note that NIL alone stands for an empty list.

See also CONS, LENGTH.


16.15.3 LENGTH

LENGTH determines the length of a list.

 
(LENGTH list)

returns the length of the given list.

Example: `(LENGTH (LIST "a" 2 42 3))' results to 4.

See also LIST.


16.15.4 FIRST

FIRST extracts the first element in a list.

 
(FIRST list)

returns the first element of the given list. If list is empty (NIL) then NIL is returned.

See also REST, LAST, NTH, CONS.


16.15.5 REST

REST returns the sub-list after the first element of a list.

 
(REST list)

returns the rest of the given list (the list without the first element). If list is empty (NIL) then NIL is returned.

Example: `(REST (LIST 1 2 3))' results to ( 2 3 ).

See also FIRST, CONS.


16.15.6 LAST

LAST extracts the last element in a list.

 
(LAST list)

Returns the last element of the given list or NIL if list is NIL.

See also FIRST, NTH.


16.15.7 NTH

NTH extracts the n-th element of a list.

 
(NTH n list)

Returns the n-th element of the given list (starting with 0) or NIL if the element doesn't exist.

See also FIRST, LAST.


16.15.8 APPEND

APPEND concatenates lists.

 
(APPEND [list ...])

returns the concatenation of list ....

Example: `(APPEND (list 1 2) (list 3 4) (list 5))' results to ( 1 2 3 4 5 ).

See also LIST.


16.15.9 REVERSE

REVERSE reverses a list.

 
(REVERSE list)

returns the reverse list.

Example: `(REVERSE (list 1 2 3))' results to ( 3 2 1 ).


16.15.10 MAPFIRST

MAPFIRST applies a function to all list elements.

 
(MAPFIRST func list [...])

Builds a list whose elements are the result of the specified function called with the arguments of the given list elements one by one. The length of the returned list is as long as the length of the longest specified list. If one of the specified lists is too short then the list is padded with NIL elements.

Examples

 
Expression                                    Value

(MAPFIRST 1+ (LIST 1 2 3))             ( 2 3 4 )
(MAPFIRST + (LIST 1 2 3) (LIST 2 3))   ( 3 5 NIL )


16.15.11 SORTLIST

SORTLIST sorts the elements of a list.

 
(SORTLIST func list)

Returns a copy of the specified list that has been sorted using the function func for ordering. The order function must take two arguments one for each element and return an integer value less than zero if the first element is smaller than the second one, a value greater then zero if the first element is greater than the second one, and a value of zero if the two elements are equal.

Example for a string comparing function usable for sorting:

 
(DEFUN cmp_str (x y)
    (COND
        ((< x y) -1)
        ((> x y) 1)
        (TRUE 0)
    )
)

Now you can sort a list by calling:

 
(SORTLIST cmp_str (LIST "hi" "fine" "great" "ok"))

which results to ( "fine" "great" "hi" "ok" ).

See also SORTLISTGT, MAPFIRST.


16.15.12 SORTLISTGT

SORTLIST sorts the elements of a list.

 
(SORTLISTGT gtfunc list)

Like SORTLIST but here you specify an order function that returns a value not equal to NIL if the first element is greater then the second one, and NIL otherwise.

Example: `(SORTLISTGT > (LIST "hi" "fine" "great" "ok"))' result to ( "fine" "great" "hi" "ok" ).

See also SORTLIST, MAPFIRST.


16.16 Input Requesting Functions

For requesting information from the user, the following functions can be used.


16.16.1 ASKFILE

ASKFILE prompts the user for entering a filename.

 
(ASKFILE title oktext default savemode)

Pops up a file dialog for entering a filename. The window title can be set in title, the text of the `Ok' button in oktext, and the initial filename in default. You may specify NIL for one of them to use default values. The last argument savemode (Boolean) allows setting the file dialog to a save mode. This mode should be used when asking for a filename to write something to.

ASKFILE returns the entered filename as string or NIL in case the user canceled the dialog.

See also ASKDIR, ASKSTR.


16.16.2 ASKDIR

ASKDIR prompts the user for entering a directory name.

 
(ASKDIR title oktext default savemode)

Pops up a file dialog for entering a directory name. The arguments are used in the same way as in ASKFILE (see ASKFILE).

ASKDIR returns the entered directory name as string or NIL in case the user canceled the dialog.

See also ASKFILE, ASKSTR.


16.16.3 ASKSTR

ASKSTR prompts the user for entering a string.

 
(ASKSTR title oktext default maxlen [secret])

Pops up a dialog asking for a string to enter. The window title, the text of the `Ok' button, and the initial value can be set in title, oktext, and default respectively (strings or NIL for default values), maxlen determines the maximum characters the user can enter. If secret is given and is not NIL then the entered string is made invisible by displaying a bullet sign for each string character.

ASKSTR returns the entered string or NIL in case the user canceled.

See also ASKFILE, ASKDIR, ASKCHOICESTR, ASKINT.


16.16.4 ASKINT

ASKINT prompts the user for entering an integer value.

 
(ASKINT title oktext default min max)

Pops up a dialog asking for an integer to enter. The window title and the text of the `Ok' button can be specified in title and oktext (strings or NIL for default values). In default you pass the initial integer value or NIL to start with an empty editing field. In min and max you can set the integer range. Entered values outside this range are not accepted by the dialog. Use NIL for default min and max values.

ASKINT returns the entered integer or NIL if the user canceled the dialog.

See also ASKSTR.


16.16.5 ASKCHOICE

ASKCHOICE prompts the user to select one item out of many items.

 
(ASKCHOICE title oktext choices default [titles])

Pops up a dialog allowing the user to choose one item out of a list of items. You can set the window title and the text of the `Ok' button in title and oktext (strings or NIL for default values). In choices you specify a list of choices. You can use a multi-column format by providing each choice item as a list of sub-items. The initial choice value can be set in default and is the index in the list of choices (starting with index 0 for the first item). Use NIL for no initial choice. If the optional argument titles is specified and is non-NIL then a list header containing titles is shown. For using a multi-column format, specify titles as a list of column titles.

Both, choices and titles, can also be given as a memo and a string (instead of lists). If so, they are converted to lists automatically by calling (MEMOTOLIST choices TRUE) (see MEMOTOLIST) and (STRTOLIST titles) (see STRTOLIST) respectively.

ASKCHOICE returns the index of the chosen item or NIL if the user canceled the dialog.

Example

 
(LET ((items (LIST "First Entry" 2 3.14 "Last entry")) index)
    (SETQ index (ASKCHOICE "Choose one item" "Ok" items NIL))
    (IF index
        (PRINTF "User chose item num %i with contents <%s>\n"
            index (STR (NTH index items))
        )
    )
)

Consider the case where you would like to ask the user to select a certain record in a table. The table shall be called `Article' with attributes `Name', `Number', and `Prize'. The following code fragment shows how to use ASKCHOICE for asking to select a record with Prize larger than 10 and ordered by Name:

 
(LET ((query (SELECT Article, Name, Number, Prize from Article 
	      WHERE (> Prize 10) ORDER BY Name))
     (recs (MAPFIRST FIRST (REST query)))	; record pointers
     (items (MAPFIRST REST (REST query)))	; choices
     (titles (REST (FIRST query)))		; titles
     (index (ASKCHOICE "Choose" "Ok" items NIL titles))
     (rec (NTH index recs)))
     ; now rec holds the selected record (or NIL on cancel)
)

See also ASKCHOICESTR, ASKOPTIONS.


16.16.6 ASKCHOICESTR

ASKCHOICESTR prompts the user for entering a string value offering several pre-defined ones.

 
(ASKCHOICESTR title oktext strings default [titles])

Pops up a dialog allowing the user to choose one string out of many strings or to enter any other string in a separate string field. You can set the window title and the text of the `Ok' button in title and oktext (strings or NIL for default values). In strings you specify a list of choices. You can use a multi-column format by providing each choice item as a list of sub-items. The initial value of the string field can be set in default (string or NIL for an empty string field). If the optional argument titles is specified and is non-NIL then a list header containing titles is shown. For using a multi-column format, specify titles as a list of column titles.

Both, strings and titles, can also be given as a memo and a string (instead of lists). If so, they are converted to lists automatically by calling (MEMOTOLIST strings TRUE) (see MEMOTOLIST) and (STRTOLIST titles) (see STRTOLIST) respectively.

ASKCHOICESTR returns the chosen string or NIL if the user canceled the dialog.

Example

 
(LET ((strings (LIST "Claudia" "Mats" "Ralphie")) likebest)
    (SETQ likebest
        (ASKCHOICESTR "Who do you like the best?" "Ok" strings 
	    "My collies!"
	)
    )
    (IF likebest (PRINTF "User chose <%s>\n" likebest))
)

See also ASKCHOICE, ASKOPTIONS.


16.16.7 ASKOPTIONS

ASKOPTIONS prompts the user for selecting several items out of a list of items.

 
(ASKOPTIONS title oktext options selected [titles])

Pops up a dialog allowing the user to select several options out of a list of options. You can set the window title and the text of the `Ok' button in title and oktext (strings or NIL for default values). In options you specify a list of options. You can use a multi-column format by providing each option item as a list of sub-items. The initial selection state can be set in selected as a list of integers each specifying an index whose corresponding item in options should initially be selected. Use NIL for all items being unselected. If the optional argument titles is specified and is non-NIL then a list header containing titles is shown. For using a multi-column format, specify titles as a list of column titles.

Both, options and titles, can also be given as a memo and a string (instead of lists). If so, they are converted to lists automatically by calling (MEMOTOLIST options TRUE) (see MEMOTOLIST) and (STRTOLIST titles) (see STRTOLIST) respectively.

ASKOPTIONS returns a list of integers each specifying the index of a selected item, or NIL in case the user canceled or did not choose any item.

Example

 
(LET ((options (LIST "Salva Mea" "Insomnia" "Don't leave" "7 days & 1 week"))
        (selected (LIST 0 1 3))
    )
    (SETQ selected (ASKOPTIONS "Select music titles" "Ok" options selected))
    (IF selected
        (
            (PRINTF "User has selected the following items:\n")
            (DOLIST (i selected)
                (PRINTF "\tnum: %i contents: <%s>\n" i (STR (NTH i options)))
            )
        )
    )
)


16.16.8 ASKBUTTON

ASKBUTTON prompts the user for pressing a button.

 
(ASKBUTTON title text buttons canceltext)

Pops up a dialog with the specified window title (string or NIL for a default title) and specified description text (string or NIL for no text). The function waits until the user presses one of the buttons specified in buttons (list of strings) or the `Cancel' button. The text of the cancel button can be set in canceltext. If you specify NIL here then a default text based on the number of buttons you specified is used.

ASKBUTTON returns the number of the pressed button (starting with 0 for the first (leftmost) button) or NIL if the user pressed the `Cancel' button.

Examples

 
(LET ((buttons (LIST "At home" "In bed" "In front of my computer")) index)
    (SETQ index (ASKBUTTON "Please answer:"
        "Where do you want to be tomorrow?" buttons "Don't know")
    )
    (IF index
        (PRINTF "User chose: <%s>\n" (NTH index buttons))
    )
)

(ASKBUTTON "Info" "MUIbase is great!" NIL NIL)

See also ASKCHOICE.


16.16.9 ASKMULTI

ASKMULTI prompts the user to enter various kinds of information.

 
(ASKMULTI title oktext itemlist)

ASKMULTI is a multi-purpose dialog. It opens a window with the specified title, a set of GUI objects for editing data, and two buttons (`Ok' and `Cancel') for terminating the dialog. The text of the `Ok' button can be set in oktext (string or NIL for default text). The set of GUI objects are specified in itemlist which is a list of items where each item has one of the following forms:

 
    (LIST title "String" initial [help [secret]])  for editing one line of text,
    (LIST title "Memo" initial [help])     for editing multi-line text,
    (LIST title "Integer" initial [help])  for editing an integer,
    (LIST title "Real" initial [help])     for editing a real,
    (LIST title "Date" initial [help])     for editing a date,
    (LIST title "Time" initial [help])     for editing a time,
    (LIST title "Bool" initial [help])     for a Boolean field,
    (LIST title "Choice" initial
        (LIST choice ...) [help]
    )                                      for a choice field.
    (LIST title "ChoiceList" initial
        (LIST choice ...) [help]
    )                                      for selecting one item of a list.
    (LIST title "Options" initial
        (LIST option ...) [help]
    )                                      for selecting several items of a list.
    non-list-expr                          for static text

The title (string or NIL for no title) will be displayed to the left of the GUI object. If the initial value is NIL then a default value is used (e.g. an empty text field). For choice fields the initial value must be the index (starting with 0) for the initial active entry, for choice list fields the initial value may be NIL (no item is activated), and for options fields the initial value must be a list of integers representing the indices (starting with 0) of the items that are initially selected. The optional help field (string) can be used for giving more information to the user about the usage of the field. For string fields an additional parameter `secret' can be specified. If non-NIL then the contents of the string field are made invisible by displaying a bullet sign for each string character.

ASKMULTI returns a list of result values which the user has edited and acknowledged by pressing the `Ok' button. Each result value of a field has the same format as the one for the initial value, e.g. for a choice list field the result value is the index of the selected item (or NIL if no item has been selected), or for an options field the result value is a list of integers representing the indices of the selected items. For static text a value of NIL is returned.

E.g. if you have specified a date field, a static text field, a choice field, an options field, and a string field with initial value "world", and the user has entered 11.11.1999, selected the choice entry with index number 2, selected the 3rd and 4th item in the options field, and left the string field untouched then the function returns the list ( 11.11.1999 NIL 2 ( 3 4 ) "world" ).

If the user cancels the dialog, NIL is returned.

Example

 
(ASKMULTI "Please edit:" NIL (LIST
    (LIST "N_ame" "String" "")
    (LIST "_Birthday" "Date" NIL)
    (LIST "_Sex" "Choice" 0 (LIST "male" "female"))
    (LIST "_Has car?" "Bool" NIL)
    (LIST "_Likes" "Options" (LIST 0 2)
        (LIST "Beer" "Wine" "Whisky" "Wodka" "Schnaps")
    ))
)

Please see also the project `AskDemo.mb' for further examples.


16.17 I/O Functions

This sections lists functions and variables for input and output (e.g. printing) of data.


16.17.1 FOPEN

FOPEN opens a file for reading/writing.

 
(FOPEN filename mode [encoding])

Opens the file specified by filename (string). The mode parameter (string) controls the access mode. Use `"w"' to open a file for writing, `"a"' to append to a file, and `"r"' for reading from a file. You may also use other flags (or combination of flags) like `"r+"' for reading and writing. There is no check done that tests if you have specified a valid flag string. However if the file can't be opened, NIL is returned.

The optional parameter encoding controls the encoding of the file and is one of the following strings:

`"none"':
No interpretation of characters is performed. Use this for binary files.

`"UTF-8"':
Text is encoded in UTF-8. Reading and writing converts from/to UTF-8.

`"locale"':
Text is encoded in your system locale. On Windows this is the system's code page. On Mac OS and Linux it is the setting of the LANG and LC_* environment variables, see man locale. On Amiga it is the default 8 bit encoding.

`"8-bit"':
Text is encoded in the default 8-bit codeset. On Windows, Mac OS and Linux this is the ISO-8859-1 (latin 1) encoding. On Amiga it is the system's default 8 bit encoding (same as `locale').

`"auto"':
The encoding is auto-detected. If the file is readable then the encoding is determined as follows: If all contents conform to UTF-8 then `"UTF-8"' is assumed. Else if the system's locale is not UTF-8 then `"locale"' is assumed. Otherwise `"8-bit"' is assumed. When writing and the encoding has not been determined yet then first the system's locale encoding is tried. If there were no conversion errors then `"locale"', otherwise `"UTF-8"' is used.

If no encoding parameter is given then `"auto"' is used.

FOPEN returns a file handle on success. On failure NIL is returned. If filename, mode or encoding are NIL then NIL is returned.

Examples

`(FOPEN "index.html" "w" "utf-8")' opens and returns a file handle for writing to the file `index.html' and encoding it in UTF-8.

`(FOPEN "output.txt" "a+")' opens file `output.txt' for appending it using the same text encoding as is already present in the file. Note that if you only specify `"a"' as mode then MUIbase might not be able to read the file and decide the existing encoding. In this case the encoding is decided when writing to the file (and might be different from the exising one).

See also FCLOSE, stdout, FFLUSH.


16.17.2 FCLOSE

FCLOSE closes a file.

 
(FCLOSE file)

Closes the given file. Returns 0 on success, NIL if an error has occurred. If file is NIL then 0 is returned (no error). After closing a file accessing the file handle is an illegal operation and results in aborting program execution with an error message.

See also FOPEN, FFLUSH.


16.17.3 stdout

The global variable stdout holds the file handle to MUIbase's standard output file. The output filename can be set in menu item `Program - Output file' (see Program output file).

The output file is opened on the first access of this variable (e.g. when calling `(FPRINTF stdout ...)', or when calling `(PRINTF ...)'). The file is not pre-opened on program execution. This avoids opening the file when no output is generated, e.g. when you simply want to do some calculations and change some record contents.

When opening the output file the mode parameter is either `"w"' or `"a+"' depending on the `Append' setting in menu item `Program - Output file'. The encoding is set to `"auto"'.

If MUIbase can't open the program output file then execution is aborted and an error message is generated.

See also FOPEN, PRINTF.


16.17.4 PRINT

PRINT converts an expression to a string and prints it.

 
(PRINT elem)

Converts the value of elem to a readable string and prints it to stdout. This function mainly exists for debug purposes.

See also PRINTF, stdout.


16.17.5 PRINTF

PRINTF prints a formatted string.

 
(PRINTF format [expr ...])

Formats a string using the given format string and arguments and prints it to stdout. Formatting is done like in SPRINTF (see SPRINTF).

PRINTF returns the number of output characters or NIL on failure. If format is NIL then NIL is returned.

Example: `(PRINTF "%i days and %i week" 7 1)' prints the string "7 days and 1 week" to stdout and returns 17.

See also PRINT, FPRINTF, stdout.


16.17.6 FPRINTF

FPRINTF prints a formatted string to a file.

 
(FPRINTF file format [expr ...])

Formats a string using the given format string and arguments and prints it to the specified file. Formatting is done like in SPRINTF (see SPRINTF).

FPRINTF returns the number of output characters or NIL on failure. If file is NIL then FPRINTF still returns the number of potentially written characters but no output is actually written. If format is NIL then NIL is returned.

See also PRINTF, FOPEN.


16.17.7 FERROR

FERROR checks if an file I/O error has occurred.

 
(FERROR file)

returns TRUE if an error for the given file has occurred, NIL otherwise. If `file' is NIL, NIL is returned.

See also FEOF, FOPEN, FCLOSE.


16.17.8 FEOF

FEOF checks for an end of file status.

 
(FEOF file)

Tests the end-of-file indicator for the given file and returns TRUE if it is set. Otherwise NIL is returned. If `file' is NIL, NIL is returned.

See also FERROR, FTELL, FOPEN, FCLOSE.


16.17.9 FSEEK

FSEEK sets the read/write position in a file.

 
(FSEEK file offset whence)

Sets the read/write position for the given file. The new position, measured in bytes, is obtained by adding offset bytes to the position specified by whence. If whence is set to SEEK_SET, SEEK_CUR, or SEEK_END, the offset is relative to the start of the file, the current position, or end-of-file, respectively.

On success, FSEEK returns 0. Otherwise NIL is returned and the file position stays unchanged. If file, offset, or whence is NIL, or if whence is not one of the constant values SEEK_SET, SEEK_CUR, or SEEK_END then NIL is returned.

Note that after a read operation calling FSEEK with whence as SEEK_CUR is only supported for encoding `"none"'.

See also FTELL, FOPEN, Pre-defined constants.


16.17.10 FTELL

FTELL returns the read/write position of a file.

 
(FTELL file)

Determines the current read/write position of the given file relative to the beginning of the file and returns it as an integer. If an error occurs or if `file' is NIL, then NIL is returned.

Note that after a read operation calling FTELL is only supported for encoding `"none"'.

See also FSEEK, FOPEN, FEOF.


16.17.11 FGETCHAR

FGETCHAR reads a character from a file.

 
(FGETCHAR file)

Returns the next character from the given file as a string or NIL if file is NIL, end of file has been reached, or an error has happened. If the next character is a null character, an empty string is returned.

See also FGETCHARS, FGETSTR, FPUTCHAR.


16.17.12 FGETCHARS

FGETCHARS reads characters from a file.

 
(FGETCHARS num file)

returns a string containing the next num characters from the given file. If end of file has been reached before reading num characters or if a null character has been read then only these characters are returned. If num or file are NIL, num is negative, end of file has been reached before reading the first character, or a read error has happened then NIL is returned.

See also FGETCHAR, FGETSTR.


16.17.13 FGETSTR

FGETSTR reads a string from a file.

 
(FGETSTR file)

returns the next line of the given file as a string or NIL if file is NIL, end of file has been reached, or an error happened. The end of a line is detected if either a newline character or a null character is read, or if end of file is detected. In either case the string does not contain any newline characters.

See also FGETCHAR, FGETCHARS, FGETMEMO, FPUTSTR.


16.17.14 FGETMEMO

FGETMEMO reads a memo from a file.

 
(FGETMEMO file)

returns a memo that contains the contents of the given file up to the next null character or up to the end of file. If file is NIL, end of file has been reached before reading any characters, or an error occurred then NIL is returned.

See also FGETSTR, FPUTMEMO.


16.17.15 FPUTCHAR

FPUTCHAR writes a character to a file.

 
(FPUTCHAR str file)

Writes the first character of str to the given file. If str is empty, a null character is written, if str or file are NIL, nothing happens. Returns str or NIL in case an output error occurred.

See also FPUTSTR, FGETCHAR.


16.17.16 FPUTSTR

FPUTSTR writes a string to a file.

 
(FPUTSTR str file)

Prints str together with a newline character to the given file. If str or file are NIL, nothing happens. Returns str or NIL in case an output error occurred.

See also FPUTCHAR, FPUTMEMO, FGETSTR.


16.17.17 FPUTMEMO

FPUTMEMO writes a memo to a file.

 
(FPUTMEMO memo file)

Prints memo to the given file. If memo or file are NIL, nothing happens. Returns memo or NIL in case an output error occurred.

See also FPUTSTR, FGETMEMO.


16.17.18 FFLUSH

FFLUSH flushes pending data to a file.

 
(FFLUSH file)

Flushes all pending output for the given file. Returns 0 on success, NIL if an error occurred. If file is NIL then 0 is returned (no error).

See also FOPEN, FCLOSE.


16.18 Record Functions

This section lists functions that deal with records.


16.18.1 NEW

NEW allocates a new record for a table.

 
(NEW table init)

Allocates a new record in the given table. The parameter init specifies the record which should be used for initializing the new record. A value of NIL stands for the initial record.

NEW returns a record pointer to the new record.

The NEW function has the side effect of setting the program record pointer of the given table (see Tables) to the new record.

Example: `(NEW table NIL)' allocates a new record in the given table and initializes it with the initial record.

See also NEW*, DELETE, Tables.


16.18.2 NEW*

NEW* is the star version of NEW (see NEW).

 
(NEW* table init)

NEW* checks if you have specified a `New' trigger function for the given table (see New trigger). If so then this trigger function is called for allocating the record and its result is returned. The init parameter can be used to specify a record with which the new record should be initialized (use NIL for the initial record).

If no trigger function has been specified, the function behaves like the NEW function.

Warning: With this function it is possible to write endless loops, e.g. if you have defined a `New' trigger function for a table and this function calls NEW* to allocate the record.

See also NEW, DELETE*.


16.18.3 DELETE

DELETE deletes a record in a table.

 
(DELETE table confirm)

Deletes the current program record of the given table after an optional delete confirmation. The first argument specifies the table for which the current program record should be deleted, the second argument is a Boolean expression. If it is NIL then the record is deleted silently, if it is not NIL then the state of preferences menu item `Confirm delete record' is checked. If it is not set, the record is deleted silently, otherwise the standard delete dialog appears asking for confirmation. If the users cancels the delete operation then the record will not be deleted.

The return code of the DELETE function reflects the selected action. If it returns TRUE then the record has been deleted, otherwise (the user has canceled the operation) NIL is returned.

On deletion, DELETE sets the program record pointer (see Tables) of the specified table to NIL.

Example: `(DELETE table NIL)' deletes the current record in the given table silently.

See also DELETE*, DELETEALL, NEW, Tables.


16.18.4 DELETE*

DELETE* is the star version of DELETE (see DELETE).

 
(DELETE* table confirm)

DELETE* checks if you have specified a `Delete' trigger function for the given table (see Delete trigger). If so then this trigger function is called for deleting the record and its result is returned. The confirm parameter can be used to specify if the trigger function should pop up a confirmation dialog before deleting the record.

If no trigger function has been specified, the function behaves like the DELETE function.

Warning: With this function it is possible to write endless loops, e.g. if you have defined a `Delete' trigger function for a table and this function calls DELETE* to delete the record.

See also DELETE, DELETEALL, NEW*.


16.18.5 DELETEALL

DELETEALL deletes all records of a table.

 
(DELETEALL table[*])

Deletes all records of the specified table. If you add a star behind the table name then only those records that match the current filter of the table are deleted. There is no confirmation dialog before deleting the records.

DELETEALL returns TRUE on successful deletion of all records, otherwise NIL is returned. If table is NIL then NIL is returned.

Example: `(DELETEALL table*)' deletes all records in the given table that match the filter of the table.

See also DELETE, Tables.


16.18.6 GETMATCHFILTER

GETMATCHFILTER returns the match-filter state of a record.

 
(GETMATCHFILTER rec)

Returns TRUE if the specified record matches the filter of its table, NIL otherwise. If the filter of the table is currently not active then TRUE is returned. If rec is NIL (the initial record) then NIL is returned.

See also SETMATCHFILTER, GETISSORTED, GETFILTERSTR, SETFILTERSTR.


16.18.7 SETMATCHFILTER

SETMATCHFILTER sets the match-filter state of a record.

 
(SETMATCHFILTER rec on)

Changes the match-filter state of the specified record to the value of on. SETMATCHFILTER returns the new match-filter state of the given record. The new state may be different from the expected one because setting the match-filter state to NIL does only work when the filter of the corresponding table is currently active, otherwise TRUE is returned. Calling SETMATCHFILTER with a value of NIL for rec (the initial record) will always return NIL.

See also GETMATCHFILTER, SETISSORTED, GETFILTERSTR, SETFILTERSTR.


16.18.8 GETISSORTED

GETISSORTED returns the sorted state of a record.

 
(GETISSORTED rec)

Returns TRUE if the specified record is sorted in the order that has been defined for its table, NIL otherwise. If rec is NIL then NIL is returned.

See also SETISSORTED, GETMATCHFILTER, REORDER, GETORDERSTR, SETORDERSTR, Comparison function.


16.18.9 SETISSORTED

SETISSORTED sets the sorted state of a record.

 
(SETISSORTED rec on)

Changes the sorted state of the specified record to the value of on. Use this function if you think that a certain record is in the right order (on = TRUE), or it it should be reordered (on = NIL). Reordering all unsorted records can be done by calling the REORDER function (see REORDER).

SETISSORTED returns the new sorted state of the given record. Calling SETISSORTED with a value of NIL for rec (the initial record) will return NIL.

For an example on how to use this function, see Comparison function.

See also GETISSORTED, SETMATCHFILTER, REORDER, GETORDERSTR, SETORDERSTR, Comparison function.


16.18.10 RECNUM

RECNUM returns the record number of a record.

 
(RECNUM record)

Returns the record number of the given record. Please note that the numbering for records is different than e.g. for lists. For lists, strings and others the counting begins with zero, however for records it begins with 1 for the first record. The number 0 is reserved for the initial record. This seems to be inconsistent with the rest of the MUIbase programming functions, but it does really makes sense here as the record numbers are also used in the window display.

See also RECORDS, INT.


16.18.11 COPYREC

COPYREC copies records.

 
(COPYREC rec source)

Copies the contents of record source to record rec. If source is NIL then rec is set to the values of the initial record. If rec is NIL then an error message is generated.

COPYREC returns rec.

See also NEW.


16.19 Attribute Functions

This section lists functions that work on attributes of a table.


16.19.1 ATTRNAME

ATTRNAME returns the name of an attribute.

 
(ATTRNAME attr)

Returns a string containing the name of the specified attribute.

See also TABLENAME


16.19.2 MAXLEN

MAXLEN returns the maximum size of a string attribute.

 
(MAXLEN string-attr)

Returns the maximum number of characters that the given string attribute can hold.

See also LEN.


16.19.3 GETLABELS

GETLABELS returns all labels of a choice or string attribute.

 
(GETLABELS attr)

Returns the labels of the given choice or string attribute. In case of a choice attribute, the labels you entered in the attribute dialog (see Type specific settings) are returned, in case of a string attribute, the static labels you entered for the list-view pop-up (see Attribute object editor) are returned (note that this function is only useful for static labels).

The labels are returned in one single string and are separated by newline characters.

For example, consider you have a choice attribute with the labels `Car', `House', and `Oil'. Then calling GETLABELS on that attribute will result to the string "Car\nHouse\nOil".

Note: you can easily convert the result string to a list by calling MEMOTOLIST (see MEMOTOLIST) on the result string.

See also SETLABELS.


16.19.4 SETLABELS

SETLABELS is used to set the labels of a string attribute.

 
(SETLABELS attr str)

Sets the static labels of the string attribute attr to the labels listed in the str argument. The str argument consists of lines each of which holds one label. The labels replace the ones you have entered for the pop-up list-view in the attribute object editor (see Attribute object editor). Note that this function is only useful for static labels.

SETLABELS returns the value of its str argument.

Example: `(SETLABELS Table.String "My house\nis\nyour house")' sets the static list-view labels of the specifies string attribute to `My house', `is', and `your house'.

Note: you can easily convert a list of labels to the required string format by calling LISTTOMEMO on the list.

See also GETLABELS.


16.20 Table Functions


16.20.1 TABLENAME

TABLENAME returns the name of a table.

 
(TABLENAME table)

Returns a string containing the name of the specified table.

See also ATTRNAME


16.20.2 GETORDERSTR

GETORDERSTR returns the record order of a table.

 
(GETORDERSTR table)

Returns the current order expression of the given table. If the table uses an attribute list for ordering then the returned string contains the attribute names separated by spaces. Each attribute name is prepended by a `+' or a `-' sign indicating ascending or descending order.

If the table is ordered by a comparison function then the name of this function is returned.

An empty string means no ordering.

Example

Consider a table `Person' which is ordered by the Attributes `Name' (ascending), `Town' (ascending), and `Birthday' (descending). Then `(ORDERSTR Person)' will result to the string "+Name +Town -Birthday".

See also SETORDERSTR, REORDER, REORDERALL, GETISSORTED, SETISSORTED, Order, Comparison function.


16.20.3 SETORDERSTR

SETORDERSTR sets the record order of a table.

 
(SETORDERSTR table order)

Sets the order of the given table according to the order string. The order string can either hold a list of attribute names or the name of a comparison function.

For sorting using an attribute list, the order string must contain the attribute names separated by any number of spaces, tabs or newlines. Each attribute name may be prepended by a `+' or a `-' sign indicating ascending or descending order. If you omit this sign then ascending ordering is assumed.

For sorting using a comparison function, the order string must hold the name of the function.

SETORDERSTR returns TRUE if it has been able to set the new order, NIL otherwise, e.g. if an unknown attribute has been specified or the type of the attribute is not allowed for ordering. If you specify NIL for the order argument then nothing happens and NIL is returned.

Note: For building the order string you should not directly write the attribute names into the string because when you change an attribute name then the order string will not be updated. Better use the ATTRNAME function (see ATTRNAME) to copy the attribute's name into the order string.

Example

Consider a table `Person' with the attributes `Name', `Town', and `Birthday'. Then `(SETORDERSTR Person (SPRINTF "+%s" (ATTRNAME Person.Name)))' will set the order of table `Person' using `Name' as (ascending) order attribute.

See also GETORDERSTR, REORDER, REORDERALL, GETISSORTED, SETISSORTED, Order, Comparison function.


16.20.4 REORDER

REORDER brings all unsorted records back into the right order.

 
(REORDER table)

Examines all records of the given table for unsorted ones and reinserts them to their right positions. After reinserting an unsorted record, the sorted state of the record is set to TRUE, thus on the return of REORDER the sorted state of all records is TRUE.

REORDER returns NIL.

Usually you only need to call this function, when you are using a comparison function for defining the order of a table. Orders defined by an attribute list are automatic, that is, a record is reordered automatically when needed.

For an example on how to use this function, see Comparison function.

See also REORDERALL, GETORDERSTR, SETORDERSTR, GETISSORTED, SETISSORTED, Order, Comparison function.


16.20.5 REORDERALL

REORDERALL reorders all records of a table.

 
(REORDERALL table)

Reorders all records of the given table by setting the sorted state of all records to NIL and then calling REORDER for reordering everything.

REORDERALL returns NIL.

See also REORDER, GETORDERSTR, SETORDERSTR, GETISSORTED, SETISSORTED, Order, Comparison function.


16.20.6 GETFILTERACTIVE

GETFILTERACTIVE returns the filter state of a table.

 
(GETFILTERACTIVE table)

Returns TRUE if the filter of the specified table is currently activated and NIL otherwise.

See also SETFILTERACTIVE, GETFILTERSTR, GETMATCHFILTER.


16.20.7 SETFILTERACTIVE

SETFILTERACTIVE sets the filter state of a table.

 
(SETFILTERACTIVE table bool)

Sets the filter state of the specified table. If bool is non-NIL then the filter is activated, otherwise it is deactivated.

SETFILTERACTIVE returns the new state of the filter. The new state may not be the expected one in case you activate the filter but an error condition occurs and the filter can't be activated. However deactivating the filter always succeeds.

See also GETFILTERACTIVE, SETFILTERSTR, SETMATCHFILTER.


16.20.8 GETFILTERSTR

GETFILTERSTR returns the record filter expression of a table.

 
(GETFILTERSTR table)

Returns the record filter expression of the specified table as a string. An empty string means that no filter expression has been set for this table.

See also SETFILTERSTR, GETFILTERACTIVE, GETMATCHFILTER.


16.20.9 SETFILTERSTR

SETFILTERSTR sets the record filter expression of a table.

 
(SETFILTERSTR table filter-str)

Sets the record filter expression of the specified table to the expression in the filter-str argument (which must be a string and not the actual expression itself!). If the filter of the given table is currently active then the new filter expression is directly applied to all records and the match-filter state of all records are recomputed.

SETFILTERSTR returns TRUE if it has been able to compile the given filter string expression, otherwise NIL is returned. Note that you only get the result of the compilation. If the filter of the given table is currently active and recomputing all match-filter states of the corresponding records fails then you will not notice that from the result of this function. The recommended way to set a new filter expression is like follows:

 
(SETFILTERACTIVE Table NIL)               ; always succeeds.
(IF (NOT (SETFILTERSTR Table filter-string))
    (ERROR "Can't set filter string for %s!" (TABLENAME Table))
)
(IF (NOT (SETFILTERACTIVE Table TRUE))
    (ERROR "Can't activate filter for %s!" (TABLENAME Table))
)

If SETFILTERSTR is called with a value of NIL for the filter-str argument then nothing happens and NIL is returned.

Example: `(SETFILTERSTR Table "(> Value 0.0)")'.

See also GETFILTERSTR, SETFILTERACTIVE, SETMATCHFILTER.


16.20.10 RECORDS

RECORDS returns the number of records in a table.

 
(RECORDS table)

Returns the number of records in the given table. You may append a star to the table name for counting the number of records that match the filter of the table.

See also RECORD, RECNUM.


16.20.11 RECORD

RECORD returns a record pointer for a given record number.

 
(RECORD table num)

Returns the record pointer to the num-th record in the given table or NIL if a record with this number doesn't exist. You may add a star to the table name to get the num-th record that matches the record filter of the table.

Please note that record numbers start with 1 and record number 0 is used for the initial record.

See also RECORDS, RECNUM.


16.20.12 SELECT

SELECT extracts and returns various data from records.

 
(SELECT [DISTINCT] exprlist FROM tablelist
        [WHERE where-expr] [ORDER BY orderlist])

where exprlist is either a simple star `*' or a list of expressions with optional titles separated by commas:

 
exprlist:     * | expr "title", ...

and tablelist is a list of table names:

 
tablelist:      table[*] [ident], ...

For each table in the table list you can specify an identifier. This can be very useful if a table occurs more than once in the table list (see example of comparing ages below). If you add a star to a table then only the records matching the currently defined filter of that table will be examined.

The orderlist has the following syntax:

 
orderlist:    expr [ASC | DESC], ...

where expr, ... can be arbitrary expressions or field numbers. For example `(SELECT Name FROM ... ORDER BY 1)' will sort the result by the `Name' attribute. You may specify ASC or DESC for an ascending or descending order. If none of them are present then an ascending order is assumed.

How it works

The select-from-where query builds the (mathematical) cross product of all tables in the table list (it examines all sets of records in table, ...) and checks the where-expression (if any). If the where-expression results to TRUE (or there is no where-expression) then a list is build whose elements are calculated by the expression list in the select-part. If you have specified a single star for the expression list then the list contains the values of all attributes belonging to tables in the table list (except virtual attributes and buttons).

The result of the query is a list of lists. The first list entry contains the title strings, the remaining ones contain the values of the from-list in the matching records.

Examples

See Query examples, for some examples using the SELECT function.

See also FOR ALL.


16.21 GUI Functions

This section describes functions for manipulating GUI elements.


16.21.1 SETCURSOR

SETCURSOR sets the cursor on a GUI element.

 
(SETCURSOR attr-or-table)

Sets the cursor on the GUI object of the given attribute or table. The function also opens the window where the attribute/table resides in if the window was not open.

SETCURSOR returns TRUE if everything went ok (window could be opened) or NIL on failure.

See also SETVIRTUALLISTACTIVE.


16.21.2 SETBGPEN

SETBGPEN sets the background pen of a GUI element.

 
(SETBGPEN attr pen)

Sets the pen for drawing the background of the GUI object given by attr. For pen a hexadecimal integer value holding a color in RBG (red, green, blue) format, or one of the PEN_* constants can be used. If pen is NIL then a default background is set.

SETBGPEN returns the value of the new background pen.

Example: `(SETBGPEN Control.Status 0xFF0000)' sets a red background for the GUI element of attribute `Status' in table `Table'. The same effect can be achieved by `(SETBGPEN Control.Status PEN_RED)'.

See also Pre-defined constants.


16.21.3 GETWINDOWOPEN

GETWINDOWOPEN returns the open state of a window.

 
(GETWINDOWOPEN attr-or-table)

Returns the open state of the window where the given attribute/table resides.

See also SETWINDOWOPEN.


16.21.4 SETWINDOWOPEN

SETWINDOWOPEN opens and closes a window.

 
(SETWINDOWOPEN attr-or-table open)

Opens or closes the window in which the given attribute/table resides. If open is non-NIL then the window is opened, otherwise it is closed. You cannot close the main window of a project.

SETWINDOWOPEN returns the new open state of the window.

See also GETWINDOWOPEN.


16.21.5 GETVIRTUALLISTACTIVE

GETVIRTUALLISTACTIVE returns the index of the active line of a virtual attribute that uses the `List' kind for display.

 
(GETVIRTUALLISTACTIVE virtual-attr)

Returns the logical index (starting with 1) of the currently active line in the specified virtual attribute. The logical index is the line number in the original list used when setting the virtual attribute. It can differ from the display order in case the user changed the sorting, e.g. by clicking on a column title. If the GUI element of virtual-attr is not visible, or if it does not use the `List' kind for display, or if no line is active, then NIL is returned.

See also SETVIRTUALLISTACTIVE.


16.21.6 SETVIRTUALLISTACTIVE

SETVIRTUALLISTACTIVE sets the active line of a virtual attribute that uses the `List' kind for display.

 
(SETVIRTUALLISTACTIVE virtual-attr num)

Sets the active line of the given virtual attribute to the num-th logical line (starting with 1). The logical line is the line number in the original list used when setting the virtual attribute and can differ from the display order in case the user changed the sorting, e.g. by clicking on a column title.

Returns num, or NIL if the GUI element of virtual-attr is not visible, does not use the `List' kind for display, or if num is out of range (less than 1 or greater than the number of lines).

SETVIRTUALLISTACTIVE does not set the cursor to the attribute's GUI element, use SETCURSOR (see SETCURSOR) for doing so.

See also GETVIRTUALLISTACTIVE, SETCURSOR.


16.22 Project Functions

This section lists functions dealing with projects.


16.22.1 PROJECTNAME

PROJECTNAME returns the project name.

 
(PROJECTNAME)

PROJECTNAME returns the name of the current project as a string or NIL if no name has been defined yet. The project name is the pathname of the project directory in the file system.

See also CHANGES.


16.22.2 PREPARECHANGE

PREPARECHANGE prepares the project for a change.

 
(PREPARECHANGE)

This command obtains a change lock on the project. This is useful when accessing a project with several MUIbase instances possibly running on different computers. Once a change lock has been obtained, no other MUIbase instance can obtain one until the lock is released. The change lock is released if the project program returns without actually performing a change, or after the project has been saved. For more information on sharing of a project, see File format.

PREPARECHANGE returns NIL on success. If obtaining the change lock fails, the program quits with an appropriate error message.

See also CHANGES.


16.22.3 CHANGES

CHANGES returns the number of changes in the current project.

 
(CHANGES)

Returns an integer containing the number of changes since the last save operation of the current project.

See also PREPARECHANGE, PROJECTNAME.


16.22.4 GETADMINMODE

GETADMINMODE tells whether the current project is in admin mode or user mode.

 
(GETADMINMODE)

Returns TRUE if the current project is in admin mode, NIL otherwise.

See also SETADMINMODE, ADMINPASSWORD, onAdminMode.


16.22.5 SETADMINMODE

SETADMINMODE changes the current project to admin mode or user mode.

 
(SETADMINMODE admin)

If admin is NIL then the current project is set into user mode, otherwise into admin mode. Note that there is no authentification dialog when changing from user to admin mode using this function.

Returns TRUE if the project has been set to admin mode, or NIL if set to user mode.

See also GETADMINMODE, ADMINPASSWORD, onAdminMode, demo `Users.mb'.


16.22.6 ADMINPASSWORD

ADMINPASSWORD obtains the admin password as SHA1 hash string.

 
(ADMINPASSWORD)

Returns a string containing the SHA1 hash of the admin password of the current project. If no admin password has been set, NIL is returned.

See also GETADMINMODE, SETADMINMODE, SHA1SUM, demo `Users.mb'.


16.23 System Functions

This section lists functions accessing the operating system.


16.23.1 EDIT

EDIT launches the external editor.

 
(EDIT filename)

Starts the external editor for editing the specified file. The external editor can be set in menu item `Preferences - External editor' (see External editor). EDIT starts the external editor synchronously, that is, it waits until the user exits the editor.

EDIT returns the return code of the external editor as an integer.

See also EDIT*, VIEW, SYSTEM.


16.23.2 EDIT*

EDIT* is the star version of EDIT and has the same effect as EDIT (see EDIT). The only difference is that EDIT* starts the external editor asynchronously, thus the function returns immediately.

EDIT* returns 0 if it was successful in starting the editor, otherwise it returns a non-zero integer value representing a system specific error code.

See also EDIT, VIEW*, SYSTEM*.


16.23.3 VIEW

VIEW launches the external viewer.

 
(VIEW filename)

Starts the external viewer for displaying the specified file. The external viewer can be set in menu item `Preferences - External viewer' (see External viewer). VIEW starts the external viewer synchronously, that is, it waits until the user exits the viewer. Note that on some systems, the call might return immediately if an instance of the viewer is already running.

VIEW returns the return code of the external viewer as an integer.

See also VIEW*, EDIT, SYSTEM.


16.23.4 VIEW*

VIEW* is the star version of VIEW and has the same effect as VIEW (see VIEW). The only difference is that VIEW* starts the external viewer asynchronously, thus the function returns immediately.

VIEW* returns 0 if it was successful in starting the viewer, otherwise it returns a non-zero integer value representing a system specific error code.

See also VIEW, EDIT*, SYSTEM*.


16.23.5 SYSTEM

SYSTEM calls an external program.

 
(SYSTEM fmt [arg ...])

Calls an external program. The command line to call the program is generated from fmt and the optional arguments like in the SPRINTF function (see SPRINTF). For interpreting the command line, a system specific shell is used (ShellExecute on Windows, /bin/sh on Mac OS and Linux, the user shell on Amiga). SYSTEM waits until the called program exits.

SYSTEM returns the return code of the executed command as an integer.

See also SYSTEM*, EDIT, VIEW.


16.23.6 SYSTEM*

SYSTEM* is the star version of SYSTEM and has the same effect as SYSTEM (see SYSTEM). The only difference is that SYSTEM* executes the command line asynchronously, thus the function returns immediately.

SYSTEM* returns 0 if it was successful in starting execution of the command line, otherwise it returns a non-zero integer value representing a system specific error code.

See also SYSTEM, EDIT*, VIEW*.


16.23.7 STAT

STAT examines a filename.

 
(STAT filename)

Examines if the specified filename exists in the file system. STAT returns NIL if the filename could not be found, 0 if the filename exists and is a directory, and an integer value greater than 0 if the filename exists and is a regular file.


16.23.8 TACKON

TACKON creates a pathname.

 
(TACKON dirname [component ...])

Joins dirname and all components in [component ...] to a pathname. TACKON knows how to deal with special characters used as path separators at the end of each argument. It returns the pathname as a string or NIL if any of the arguments is NIL. Note that TACKON does not perform any check whether the resulting path actually refers to an existing file or directory in the filesystem.

Example: `(TACKON "Sys:System" "CLI")' results to "Sys:System/CLI".

See also FILENAME, DIRNAME.


16.23.9 FILENAME

FILENAME extracts the filename part of a path name.

 
(FILENAME path)

Extracts the last component of the given path name. There is no check whether path actually refers to a file, thus it is also possible to use FILENAME to get the name of a sub-directory. FILENAME returns its result as a string or NIL if path is NIL.

Example: `(FILENAME "Sys:System/CLI")' results to "CLI".

See also DIRNAME, TACKON.


16.23.10 DIRNAME

DIRNAME extracts the directory part of a path name.

 
(DIRNAME path)

Extracts the directory part of the given path name. There is no check whether path actually refers to a file, thus it is also possible to use DIRNAME to get the name of a parent directory. DIRNAME returns its result as a string or NIL if path is NIL.

Example: `(DIRNAME "Sys:System/CLI")' results to "Sys:System".

See also FILENAME, TACKON.


16.23.11 MESSAGE

MESSAGE displays a message to the user.

 
(MESSAGE fmt [arg ...])

Sets the window title of the pause/abort window (if it is open). The title string is generated from fmt and the optional arguments like in the SPRINTF function (see SPRINTF).

MESSAGE returns the formatted title string.

Example: `(MESSAGE "6 * 7 = %i" (* 6 7))'.

See also PRINT, PRINTF.


16.23.12 COMPLETEMAX

COMPLETEMAX sets the maximum number of progress steps.

 
(COMPLETEMAX steps)

Sets the maximum number of steps for showing the progress of your MUIbase program to the user. The default (if you do not call this function) is 100 steps. The argument steps must be an integer value. If steps is NIL or 0 then no progress bar is displayed. The progress bar is part of the pause/abort window that pops up after a short delay when executing a MUIbase program.

COMPLETEMAX returns its argument steps.

See also COMPLETEADD, COMPLETE.


16.23.13 COMPLETEADD

COMPLETEADD increases the progress state.

 
(COMPLETEADD add)

Adds the integer expression add to the current progress value. Initially, the progress value is set to 0. If add is NIL then the progress value is reset to 0 and no progress bar is shown.

COMPLETEADD returns its argument add.

Example:

 
    (SETQ num ...)
    (COMPLETEMAX num)
    (DOTIMES (i num)
        (COMPLETEADD 1)
    )

See also COMPLETEMAX, COMPLETE.


16.23.14 COMPLETE

COMPLETE sets the progress state.

 
(COMPLETE cur)

Sets the current progress value to the integer expression cur. If cur is NIL or 0 then no progress bar is shown.

COMPLETE returns its argument cur.

Example:

 
    (COMPLETE 10)
    ...
    (COMPLETE 50)
    ...
    (COMPLETE 100)

See also COMPLETEMAX, COMPLETEADD.


16.23.15 GC

GC forces garbage collection.

 
(GC)

Forces garbage collection and returns NIL. Normally garbage collection is done automatically from time to time.


16.23.16 PUBSCREEN

PUBSCREEN returns name of public screen.

 
(PUBSCREEN)

On Amiga, PUBSCREEN returns the name of the public screen MUIbase is running on, or NIL in case the screen is not public.

On other systems PUBSCREEN returns NIL.


16.24 Pre-Defined Variables

MUIbase knows some pre-defined global variables.

In the current version there exists only one global variable: stdout (see stdout).


16.25 Pre-Defined Constants

The following pre-defined constants can be used in any expression for programming.

 
Name            Type            Value           Comment
-------------------------------------------------------------------------
NIL             any             NIL
TRUE            Boolean         TRUE
RESET           string          "\33c"
NORMAL          string          "\33[0m"
ITON            string          "\33[3m"
ITOFF           string          "\33[23m"
ULON            string          "\33[4m"
ULOFF           string          "\33[24m"
BFON            string          "\33[1m"
BFOFF           string          "\33[22m"
ELITEON         string          "\33[2w"
ELITEOFF        string          "\33[1w"
CONDON          string          "\33[4w"
CONDOFF         string          "\33[3w"
WIDEON          string          "\33[6w"
WIDEOFF         string          "\33[5w"
NLQON           string          "\33[2\"z"
NLQOFF          string          "\33[1\"z"
INT_MAX         integer         2147483647      Maximum integer value
INT_MIN         integer         -2147483648     Minimum integer value
HUGE_VAL        real            1.797693e+308   Largest absolute real value
PI              real            3.14159265359
OSTYPE          string          <OS type>       "Windows", "MacOSX", "Unix" or "Amiga"
OSVER           integer         <OS version>
OSREV           integer         <OS revision>
MBVER           integer         <MUIbase version>
MBREV           integer         <MUIbase revision>
LANGUAGE        string          depends         Default language
SEEK_SET        integer         see stdio.h     Seek from beg. of file
SEEK_CUR        integer         see stdio.h     Seek from current pos
SEEK_END        integer         see stdio.h     Seek from end of file
TMPDIR          string          Temporary directory depending on system
PEN_WHITE       integer         0xFFFFFF
PEN_BLACK       integer         0x000000
PEN_RED         integer         0xFF0000
PEN_GREEN       integer         0x00FF00
PEN_BLUE        integer         0x0000FF
PEN_CYAN        integer         0x00FFFF
PEN_MAGENTA     integer         0xFF00FF
PEN_YELLOW      integer         0xFFFF00

See Constants, for more information about constants. For defining your own constants, use the #define preprocessing directive (see #define).


16.26 Functional Parameters

You can pass a function as an argument to another function. This is useful for defining functions of higher order, e.g. for sorting or mapping a list.

To call a function that has been passed in an argument you have to use the FUNCALL function (see FUNCALL).

Example:

 
(DEFUN map (l fun)              # arguments: list and function
    (LET (res)                  # local variable res, initialized with NIL
        (DOLIST (i l)           # for all items one by one
            (SETQ res
                (CONS (FUNCALL fun i) res)       # calls function and
            )                                    # build new list
        )
        (REVERSE res)           # we need to reverse the new list
    )
)

You can now use the map function for example to increment all items of a list of integers:

`(map (LIST 1 2 3 4) 1+)' results to ( 2 3 4 5 ).

See also FUNCALL, APPLY, MAPFIRST.


16.27 Type Specifiers

It is possible to specify the type of a variable by adding a type specifier behind the name. The following type specifiers exist:

 
Specifier   Description

:INT        for integers
:REAL       for reals
:STR        for strings
:MEMO       for memos
:DATE       for dates
:TIME       for times
:LIST       for lists
:FILE       for file handles
:FUNC       for functions of any type
:table      for record pointers to table

The type specifier appends the variable name as in the following example:

 
(LET (x:INT (y:REAL 0.0) z) ...)

The example defines three new variables `x', `y' and `z', where `x' is of type integer and initialized with NIL, `y' is of type real and initialized with 0.0, and `z' is an untyped variable initialized with NIL.

The advantage of the type specifiers is that the compiler can detect more type errors, e.g. if you have a function:

 
(DEFUN foo (x:INT) ...)

and call it with `(foo "bar")' then the compiler generates an error message. However, if you call `foo' with an untyped value, e.g. `(foo (FIRST list))' then no error checking can be done at compile time because the type of `(FIRST list)' is unknown.

For reasons of speed no type checking is currently done at run time. It could be implemented but then would add a little overhead which is not really necessary as the wrong type will result in a type error sooner or later anyway.

Type specifiers for record pointers have another useful feature. If you tag a variable as a record pointer to a table then you can access all attributes of this table by using the variable name instead of the table name in the attribute path. E.g. if you have a table `Foo' with an attribute `Bar', and you define a variable `foo' as:

 
(LET (foo:Foo))

then you can print the `Bar' attribute of the third record by using:

 
(SETQ foo (RECORD Foo 3)) (PRINT foo.Bar)

Note that in a select-from-where expression, variables defined in the from list automatically have a type of record pointer to the corresponding table.


16.28 Semantics of Expressions

The semantics of expressions are very important for understanding what a program does. This section lists the semantics depending on syntactical expressions.

(func [expr ...])

Evaluates expr ... and then calls the function func (call by value). Returns the return value of the called function. In MUIbase there exists some non-strict functions, e.g. AND, OR and IF. These functions may not evaluate all expressions. For more information about non-strict functions, see Lisp syntax, AND, OR, and IF.

([expr ...])

Evaluates expr ... and returns the value of the last expression (see PROGN). An empty expression () evaluates to NIL.

Table

Returns the program record pointer of the given table.

Table*

Returns the GUI record pointer of the given table.

AttrPath

Returns the contents of the specified attribute. The attribute path specifies which record is used to extract the attribute value. For example `Table.Attribute' uses the program record of `Table' to extract the value of the attribute, `Table.ReferenceAttribute.Attribute' uses the program record of `Table' to extract the value of the reference attribute (which is a record pointer) and then uses this record to extract the value of `Attribute'.

var

Returns the contents of the global or local variable var. Global variables can be defined with DEFVAR (see DEFVAR), local variables e.g. with LET (see LET).

var.AttrPath
Uses the record pointer of var to determine the value of the specified attribute.


16.29 Function Triggering

For automatic execution of MUIbase programs you can specify trigger functions for projects, tables and attributes which are called in specific cases. This section lists all available trigger possibilities.


16.29.1 onOpen

After opening a project, MUIbase searches the project's program for a function called onOpen. If such a function exists then this function is called without any arguments.

Example

 
(DEFUN onOpen ()
    (ASKBUTTON NIL "Thank you for opening me!" NIL NIL)
)

See also onReload, onClose, onAdminMode, onChange, demo `Trigger.mb'.


16.29.2 onReload

Similar to onOpen (see onOpen) MUIbase calls the function onReload when reloading a project, e.g. by selecting menu item `Project - Reload'. The function is called without any arguments.

However, onReload is only called in case there are no structural changes to the project, i.e. no tables or attributes were changed, added or deleted, no changes to the project program were made, and no other changes are present that qualify as a structural change. In such a case, a reload is considered a re-opening of the project, and the function onOpen is called instead.

See also onOpen, onClose, onAdminMode, onChange.


16.29.3 onClose

Before closing a project, MUIbase searches the project's program for a function called onClose. If such a function exists then this function is called without any arguments. In the current version the result of the trigger function is ignored and the project is closed regardless of its return value.

If you do changes to the project in the onClose function then MUIbase will ask you for saving the project first before it is actually closed. If you use menu item `Project - Save & Close' for closing the project, the trigger function is called before saving the project, thus the changes are saved automatically.

Example

 
(DEFUN onClose ()
    (ASKBUTTON NIL "Good bye!" NIL NIL)
)

See also onOpen, onChange, demo `Trigger.mb'.


16.29.4 onAdminMode

Whenever a project is set into admin mode or user mode and a function called onAdminMode exists in the project's program then this function is called. The function receives one argument admin telling whether the project is in admin mode (admin is non-NIL) or in user mode (admin is NIL).

Example

 
(DEFUN onAdminMode (admin)
    (IF admin
	(ASKBUTTON NIL "Now in admin mode" NIL NIL)
	(ASKBUTTON NIL "Back to user mode" NIL NIL)
    )
)

See also onOpen, onChange, SETADMINMODE, demo `Users.mb'.


16.29.5 onChange

Whenever the user makes changes to a project or after saving a project, MUIbase searches the project's program for a function called onChange. If such a function exists then this function is called without any arguments. This can be used to count the changes a user does to a project.

Example

 
(DEFUN onChange ()
    (SETQ Control.NumChanges (CHANGES))
)

In the above example `Control.NumChanges' could be a virtual attribute somewhere in an `exactly-one-record' table for displaying the project's number of changes.

See also onOpen, onClose, onAdminMode, logLabel, demo `Trigger.mb'.


16.29.6 logLabel

When creating a new entry for the project's log, MUIbase searches the project's program for a function with the name logLabel. If it exists, it calls this function without any arguments. The returned expression is converted to a string and used for the `_Label' field of the new log entry (see Set log label).

Example

 
(DEFUN logLabel ()
    Control.CurrentUser.Name
)

The above example has been taken from the `Users.mb' project. Here the label is the name of the current user who opened the project. This means that all changes by the current user are tagged with his or her name. Thus, it is later possible to identify which user performed which change.

See also onChange, demo `Users.mb'.


16.29.7 mainWindowTitle

If a project's program contains a function with the name mainWindowTitle then the result of this function is used for setting the window title of the project's main window. The function is called without any arguments and should return a string value. The window title is automatically re-computed whenever an attribute used in the function changes.

In case mainWindowTitle does not exist, the window title shows the project's name.

Note that, in any case, MUIbase prepends the title with a `*' character whenever the project has any unsaved changes.

See also demo `Trigger.mb'.


16.29.8 New Trigger

When the user wants to allocate a new record by selecting one of the menu items `New record' or `Duplicate record' and the `New' trigger of that table has been set to a MUIbase program function then this trigger function is executed. The `New' trigger function can be set in the table dialog (see Creating tables).

The trigger function receives NIL or a record pointer as the first and only argument. NIL means that the user wants to allocate a new record, a record pointer means that the user wants to duplicate this record. If the trigger function has more than one argument then these are initialized with NIL. The trigger function should allocate the new record by calling the NEW function (see NEW). The result returned by the trigger function will be examined. If it returns a record pointer then this record will be displayed.

The `New' trigger is also called when a MUIbase program calls the NEW* function (see NEW*).

Sample New trigger function

 
(DEFUN newRecord (init)
    (PROG1                      ; for returning the result of NEW
        (NEW Table init)
        ...
    )
)

See also NEW, NEW*, Delete trigger.


16.29.9 Delete Trigger

When the user wants to delete a record by selecting menu item `Delete record' and the `Delete' trigger of that table has been set to a MUIbase program function then this trigger function is executed. The `Delete' trigger function can be set in the table dialog (see Creating tables).

The trigger function receives a Boolean argument as its only argument. If the argument is non-NIL then the function should ask the user if he really wants to delete the record. If so, the function should call DELETE (see DELETE) for deleting the record.

The `Delete' trigger is also called when a MUIbase program calls the DELETE* function (see DELETE*).

Sample Delete trigger function

 
(DEFUN deleteRecord (confirm)
    (DELETE Table confirm)
)

See also DELETE, DELETE*, New trigger.


16.29.10 Comparison Function

For defining an order on the records of a table you can use a comparison function. See Changing orders, for information on how to specify such a function for a table. The function takes two record pointers as arguments and returns an integer value reflecting the order relation of the two records. The comparison function should return a value smaller than 0 if its first argument is smaller than the second, 0 if they are equal and a value larger than 0 it the first argument is greater then the second one.

For example, if you have a table `Persons' with a string attribute `Name' then you could use the following function for comparing two records:

 
(DEFUN cmpPersons (rec1:Persons rec2:Persons)
    (CMP rec1.Name rec2.Name)
)

This will order all records according to the `Name' field using case sensitive string comparison. Note that by using an attribute list you could not archive the same ordering as string comparison is done case insensitive for attribute lists.

Using a comparison function you can define very complex order relations. Be careful not to create recursive functions that will call itself. MUIbase will stop program execution and prompt you with an error message if you try to do so. Also you should not use commands that cause side effects, e.g. setting a value to an attribute.

When using a comparison function, MUIbase does not always know when it has to reorder its records. E.g. consider in the above example another table `Toys' with a string attribute `Name' and a reference attribute `Owner' referring to `Persons', and the following function for comparing records:

 
(DEFUN cmpToys (rec1:Toys rec2:Toys)
    (CMP* rec1.Owner rec2.Owner)
)

This function is using the order of `Persons' for determining the order of the records, thus the records of `Toys' are sorted according to the order of `Persons'.

Now if the user changes one record in the `Persons' table and this record gets a new position then also records in `Toys' that refer to this record have to be reordered. MUIbase, however, does not know of this dependency.

Besides using menu item `Table - Reorder all records' on the `Toys' table for rearranging the order, you can implement an automatic reordering yourself by specifying the following trigger function for the `Name' attribute of `Persons':

 
(DEFUN setName (newValue)
    (SETQ Persons.Name newValue)
    (FOR ALL Toys WHERE (= Toys.Owner Persons) DO
        (SETISSORTED Toys NIL) 
    )
    (REORDER Toys)
)

The function clears the sorted flag for all records that refer to the current record of table `Persons' and then reorders all unsorted records of table `Toys'.

See also Order, CMP, GETISSORTED, SETISSORTED, REORDER, REORDERALL, GETORDERSTR, SETORDERSTR, demo `Order.mb'.


16.29.11 Attribute Trigger

In the attribute dialog (see Creating attributes) you can define a trigger function that is called whenever the user wants to change the attribute contents.

If you have defined such a trigger function for an attribute and the user changes the value of that attribute then the record contents are not automatically updated with the new value. Instead the value is passed to the trigger function as first argument. The trigger function can now check the value and may refuse it. To store the value in the record you have to use the SETQ function.

The trigger function should return the result of the SETQ call or the old value of the attribute if it decides to refuse the new one.

The trigger function is also called when a MUIbase program calls the SETQ* function (see SETQ*) for setting a value to the attribute.

Sample attribute trigger function

 
(DEFUN setAmount (amount)
    (IF some-expression
        (SETQ Table.Amount amount)
        (ASKBUTTON NIL "Invalid value!" NIL NIL)
    )
    Table.Amount                        ; return current value
)

See also SETQ*


16.29.12 Programming Virtual Attributes

In MUIbase virtual attributes are special attributes that calculate their value on the fly whenever it is needed. E.g. if you go to another record by clicking on one of the arrow buttons in a table's panel bar then a virtual attribute in that table is automatically recomputed and displayed (given appropriate settings for the virtual attribute, see Attribute object editor). For computing the value the attribute's `Compute' trigger function is called. This trigger function can be specified in the attribute dialog (see Type specific settings). The return value of this function defines the value of the virtual attribute. If you don't specify a `Compute' trigger function for a virtual attribute then the attribute's value is NIL.

You can also trigger the calculation of a virtual attribute by simply accessing it in an MUIbase program, so e.g. if you have a button that should compute the value of the virtual attribute, you only need to specify a function for the button like the following one:

 
(DEFUN buttonHook ()
    virtual-attr
)

You can also set a virtual attribute to any value by using the SETQ function:

 
(SETQ virtual-attr expr)

However if you access the virtual attribute after the SETQ call then the value of the virtual attribute is recomputed.

There is no caching of the value of a virtual attribute because it's not easy to know when the value has to be recomputed and when not. Thus you should access virtual attributes rarely and cache the value in local variables for further use by yourself.

For an example on how to use virtual attributes please check the `Movie.mb' demo.

See also Virtual, demo `Movie.mb'.


16.29.13 Compute Enabled Function

For attribute objects and window buttons you can specify a trigger function for computing the enabled state of the object. See Attribute object editor and Window editor, for information on how to specify this trigger function.

The trigger function is called without any arguments. It should return NIL for disabling the object and non-NIL for enabling it.

For example the compute enabled function for an object, that gets enabled when a certain virtual attribute using the `List' kind has an active item, could look like this:

 
(DEFUN enableObject ()
    (GETVIRTUALLISTACTIVE virtual-list-attr)
)

See also Attribute object editor, Window editor, demo `Users.mb'.


16.29.14 Compute Record Description

For table objects and attribute objects of type reference, a tigger function can be entered for computing a record description (see Table object editor and Attribute object editor).

The trigger function is called without any arguments. It should return a single expression or a list of expressions.

For example, in a table `Person' with attributes `Name' and `Birthday', the function could look like this:

 
(DEFUN personDescription ()
    (LIST Person.Name Person.Birthday)
)

See also Table object editor, Attribute object editor.


16.29.15 Double Click Trigger

For virtual attributes that use the list kind for displaying its contents, a trigger function can be specified which gets called whenever the user double clicks on an item in the list. See Attribute object editor, for information on how to specify this trigger function for a virtual attribute object.

The trigger functions is called with three arguments. The first argument holds the row number of the clicked field, starting with 1 for the first line (row 0 refers to the list header). The second argument holds the column number starting with 0. The third argument is a pointer to the record the list field has been generated from, or NIL if the entry has not been generated directly from one. The return code of the function is ignored.

A typical example of a double click trigger is the following.

 
(DEFUN doubleClickTrigger (row col rec:Table)
    ...
)

Here rec is declared as a record pointer to Table. This way attributes of Table can be accessed directly from rec.

In case there is more than one possible table the record argument could belong to, the following construction using type predicates to different tables is useful.

 
(DEFUN doubleClickTrigger (row col rec)
    (COND
	((RECP Table1 rec) (SETQ Table1 rec) ...)
        ((RECP Table2 rec) (SETQ Table2 rec) ...)
	...
    )
)

The list item the user clicked on might not be related to any record. In this case, the third argument can be ignored and the list element be accessed like in the following example.

 
(DEFUN doubleClickTrigger (row col)
    (PRINT (NTH col (NTH row virtual-attr)))
)

See also Attribute object editor, demo `Movie.mb'.


16.29.16 Compute Listview Labels

For string attributes, the GUI object can contain a listview pop-up that when pressed opens a list of label strings the user can choose from. The labels in this list can be static labels or they can be computed by a trigger function. See Attribute object editor, for information on how to select between static and computed labels and how to specify the trigger function.

The trigger function for computing the labels does not have any arguments. It should return a memo text with one label per line or NIL for no labels.

For example the compute function could look like this:

 
(DEFUN computeLabels ()
    "Tokyo\nMunich\nLos Angeles\nRome"
)

See also Compute reference records, Attribute object editor.


16.29.17 Compute Reference Records

For reference attributes, the GUI object usually contains a pop-up button that when pressed opens a list of records the user can choose from. The list of records in this pop-up can be computed by a trigger function. See Attribute object editor, for information on how to specify the trigger function for reference fields.

The function for computing the list of records does not have any arguments. It should return a list that is searched for the occurrence of records of the referenced table. Any such record found is added to the list shown in the reference pop-up. Items that are not records of the referenced table are ignored silently.

A typical compute function for reference records is the following example. Say a project contains a table `Person' with a Boolean attribute `Female'. Then the following compute function only shows the female persons in the reference popup:

 
(DEFUN computeFemaleRecords ()
    (SELECT Person FROM Person WHERE Female)
)

See also Compute list-view labels, Attribute object editor.


16.30 List of Obsolete Functions

The following functions are obsolete starting with MUIbase version 2.7.

  • GETDISABLED
  • SETDISABLED
  • GETWINDOWDISABLED
  • SETWINDOWDISABLED

Obsolete functions are not working as expected any longer and calling any of them is either ignored (resulting in a no-operation), opens a warning dialog, or causes an error, depending on the setting of menu item `Program - Obsolete functions' (see Obsolete functions).

It is recommended to remove these functions from a project program and implement the functionality using the enabled/disabled setting of attribute objects and window buttons (see Compute enabled function).


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on Oktober, 10 2017 using texi2html