# CHAPTER 1: Introduction

## 1.1 Conventions

This chapter describes the syntax notation used in this manual, the summary of Empress functions and syntax for the Empress script.

Typographical Conventions
Examples | Description
`empgui` `database` | SQL command and script syntax are appeared in courier typeface. Items in lowercase italics refer to categories. When typed into Empress, appropriate substitutions of actual names or expressions must be used. For example, `employees` for `database`. Note that for user-defined names, case is significant and must be typed exactly as originally defined.
`SELECT` command | When a command is referred to in the text (anywhere other than in the syntax) of the manual, it will usually be written in uppercase.
|item1| |item2| | Items stacked between vertical lines "|" are options from which one must be chosen.
[ ] | Square brackets are used to indicate that the items enclosed are optional.
{ } | Braces may contain more than one item or none at all.
MSTERMDB | Empress system variables are in uppercase and must be typed in uppercase. These variables always start with "MS".
Empress GUI Builder: Tools | Italics are used for new terms being introduced or explained and for titles of books, manuals, documents and other publications.
`File`, `New` `Cancel`, `OK` | References to Empress GUI Builder menu bar functions, push buttons, option menus, etc., are in this typeface.
<Enter> <Tab> | Keys on your keyboard appear in between angled brackets.
<Alt+Tab> | Key chords which require pressing more than one key at a time appear with a "+" separating the keys.

All text in a script between "`/*`" and "`*/`" is considered a comment and is ignored. A comment may span multiple lines.

Semicolons are mandatory. Quotes (single or double) are required for literal strings; they may not enclose variables. Quotes should also be used around names of windows, fields, tables and attributes to preclude confusion with keywords.

In general, Empress interprets words without quotes as either keywords, variables, numbers or functions. Words within quotes are interpreted as literals.

## 1.2 Variables

The Empress GUI Builder script language supports variables which may be of various classes and data types. The name of a variable may consist of letters, digits and the underscore character, but it should not begin with a digit. Keywords should not be used as variable names.

Variables must be declared before they are used. The variable declaration block must precede all other statements in a script action:

    variable_class

    data_type variable_name;

    { data_type variable_name; }

    end;

### 1.2.1 Classes of Variables

The class of a variable is one of the following:

`parameters` | The variables are passed values by a calling action.
`global` | The variables are visible in all script actions of the module.
`local` | The variables are visible only in the script action where they are declared.

If a script action has both parameters and local variables, the parameter declaration must come first, and the local variable declaration last. The scope of a parameter is the same as that of a local variable.

Global variables can only be declared in the global script action. This script action is the action whose name is specified in the module's properties as the global action. It can only have a global declaration section. No other statements are allowed in the global action.

### 1.2.2 Data Types

Empress GUI Builder script data types are Empress GUI Builder script generic data types. Refer to the Empress SQL: Reference manual for more information on generic data types.

Type | Descriptions | Example
`BOOLEAN` | Either `TRUE` or `FALSE`. |
`CHAR` | A string of characters that may be letters, numbers, or other symbols. | `abcde12345xyz`
`DATE` | A date in one of the formats acceptable to Empress SQL. | `12` `March` `1994`
`DECIMAL` | A sequence of digits, followed by a decimal place and trailing digits. | `12345.678`
`FLOAT` | Also known as "scientific notation". A digit followed by a decimal point and trailing digits, followed by "e" and an exponent of ten. | `1.2345e2`
`INTEGER` | A generic integer. | `1234`

Conversion of values from one data type to another can be performed using the Empress SQL `convert` `to` operator.

Example

    let string_var = float_var convert to char;

    let boolean_var = int_var convert to generic boolean;

Note that if the keyword `generic` is not specified before the data type, the latter is assumed to be an attribute data type. Since there is no `boolean` data type for attributes, "`convert` `to` `boolean`" is incorrect.

### 1.2.3 Array Variables

The declaration of an array variable is as follows:

    data_type 	variable_name [size]

In a parameter declaration, `size` should not be specified, leaving the square brackets empty.

In a global variable declaration, `size` can be an integer constant or an integer parameter.

In a local variable declaration, `size` must be an integer constant.

Examples

    parameters

        char     data[];

        integer  num;

    end;

    local

        char     list[num];

        float    result[10];

    end;

Entire arrays can be passed as arguments to a function or script action. They are passed by reference. Therefore, if the function changes the contents of the array, the calling script will also see the change.

The first element of an array has index 1.

## 1.3 System Global Variables

These variables are defined and updated automatically by Empress GUI Builder script. You can obtain information from these variables at anytime and anywhere in their Empress GUI Builder script application text.

Warning
Do not use these name for your variables or scripts actions.

`sqldatabase` | is the name of the current default database. This database is searched for any table references where the table name is not preceded by a database name. The values can be changed to make another database the current default database.
`sqlmessage` | is the most recent system message.
`sqlcode` | is the unique number identifying `sqlmessage`.
`sqlresult` | is a flag giving the result of the last `fetch`. The variable has the following values:
1 | Successful
0 | Unsuccessful; no record
-1 | Record was unattainable
`sqlcount` | is the number of records selected by the last `open` `cursor` statement (with the `COUNT` option in effect).
`sqlstatus` | is a flag giving the status of the last `fetch` statement. The values of `sqlstatus` are as follows:
-2 | Error
-1 | Record is locked
0 | No record
1 | Record obtained
2 | Beginning of group
3 | Aggregate record

## 1.4 The NULL Keyword

The keyword `NULL` should be used to refer to null values. Currently, the empty string is accepted as a null value, but use of the keyword `NULL` is recommended.

The `NULL` keyword can be used to check if a variable, attribute or field is null, and to assign a null value to a variable, attribute or field.

A variable is null when it is declared, and a field is null when it is empty. Note that `NULL` means that a variable has no determinable value. In a comparison, if one term is a variable with a null value, the expression will return false, unless the other term is the keyword `NULL.`

For example, the expression "`if variable_1 = variable_2`" returns false even if both `variable_1` and `variable_2` are null.

You have to check for null values explicitly.

## 1.5 Reserved Keywords

For a complete list of all reserved keywords, please refer to our Reserved Keywords document. Keywords may appear in mixed upper- and lowercase characters.

Warning
Do not use these names for your variables or scripts.

## 1.6 Expressions

An expression (`expr`) is not a command. It represents an expression that can appear as part of a command. Expressions may appear, for example, in the `LET` or `SELECT` commands. Expressions may also appear in `WHERE` clauses.

Syntax

`expr` is:
`|variable |`
`|attr |`
`|string constant |`
`|number |`
`|NULL |`
`|TRUE |`
`|FALSE |`
`|(expr) |`
`|CONVERT expr [TO] data_type |`
`|CONVERT expr [TO] GENERIC data_type |`
`|expr CONVERT TO data_type |`
`|expr CONVERT [TO] GENERIC data_type |`
`|expr operator expr |`
`|expr operator |`
`|exprRANGE value[EXCL] TO value[EXCL] |`
`|exprBETWEEN value[EXCL]AND value[EXCL]|`
`|operator expr |`
`|built_in_function |`
`|user-defined_function |`
`|math_library_function |`
`|script_functions |`

Notes

1. Implicit data type conversions occur during the evaluation of expressions whenever possible.
2. Unless the result of an expression is explicitly converted to a data type, the result is generic data (data not governed by data type parameters and not associated with any attribute). Generic data is discussed in the "Data Types" chapter of Empress SQL: Reference manual.
3. Explicit conversion to data types is discussed in the Empress SQL: User's Guide.
4. The use of expressions for date arithmetic is described in the Empress SQL: User's Guide.
5. An error message will be returned if an expression is impossible to evaluate, for example, if it requires division by zero.
6. String constants must be quoted. Either single quotes or double quotes may be used.

## 1.7 Command Summary Groups

The following tables summarize commands grouped by function. These groups include:

- Variable Declarations
- Control Statements
- Database Statements
- System Functions

Warning
Do not use these names for your variables, scripts or user-defined functions.

Variable Declarations
Name | Description
`parameters` | Define variable passed to the script
`global` | Define global variable
`local` | Define local variable

Control Statements
Name | Description
`call` | Call a function or procedure
`call application` | Call an application
`exit` | Leave the application
`if` | Branch depending on condition
`let` | Assign a value
`on` | Trap events
`return` | Leave a function, optionally returning a value
`switch` | Branch depending on value
`while` | Repeat while a condition is true

Database Statements
Name | Description
`cancel` | Cancel or rollback the current transaction
`close` | Close a cursor
`close table` | Close a table
`commit` | Commit the current transaction
`declare` | Declare a cursor
`delete` | Delete record from table
`disable` | Disable operations on cursor
`enable` | Enable operations on cursor
`fetch` | Retrieve records
`insert` | Insert record into table
`lock` | Lock a table
`open` | Open a cursor
`open table` | Open a table
`rollback` | Rollback a transaction
`savepoint` | Set save point in transaction
`start transaction` | Start a transaction
`undeclare` | Remove definition of a cursor
`update` | Update record in table

System Functions
Name | Description
`empgui_attributes_set` | Copy values from objects to attributes.
`empgui_dialog_error` | Display an error message in a dialog window.
`empgui_dialog_info` | Display an information message in a dialog window.
`empgui_dialog_prompt` | Display a dialog window to prompt the user for a value.
`empgui_dialog_question` | Display a dialog window to ask a question to the user.
`empgui_dialog_warning` | Display a warning message in a dialog window.
`empgui_display_refresh` | Process pending events that affect the display.
`empgui_field_check` | Check the validity of the value in a field.
`empgui_field_focus` | Set input focus on field.
`empgui_list_clear` | Clear the contents of a list or multilist.
`empgui_list_display` | Display values in a list or multilist.
`empgui_multirecord_define` | Associate a cursor to a multilist for multiple record display.
`empgui_multirecord_display` | Update multilist to reflect the contents of a cursor.
`empgui_multirecord_undefine` | Dissociate a cursor from a list.
`empgui_objects_set` | Copy values from attributes to objects.
`empgui_system_command` | Execute an operating system command.
`empgui_system_variable` | Obtain the value of an environment variable.
`empgui_window_hide` | Hide a window from the screen.
`empgui_window_show` | Display a window on the screen.

## 1.8 Script Definition

An Empress GUI Builder script is:

    [parameter declaration;]

    [local declaration;]

    {statement;}

A `statement` may be a control statement, a database statement, or a system function. Control statements determine the flow of control within an application. Database statements concern actions involving access to databases. System functions concern actions involving access to windows and objects.

## 1.9 Database Operations

A general view of database operations is introduced here in summary. Technical terms are in italics.

To access Empress tables, the tables must be "opened" in the application. When a table is opened it may be assigned a new name, giving a table instance. There may be several instances of the same table (i.e., the table is "opened" to several names) in an application.

Example

    open table "staff" read as "staff1";

Each table instance has a record buffer. Values can be assigned to attributes in the buffer using the 'table_instance'.'attribute' notation, but these values are not in the table until an `INSERT` or `UPDATE` operation is performed.

To retrieve records in tables, a select must be defined by declaring a cursor. The records are selected by opening the cursor. A record is retrieved and made current by performing a `FETCH`.

Example

    declare "c_staff" cursor for select from "staff1";

    open "c_staff";

    fetch "c_staff";

A record may be created by assigning values to attributes. To update or delete a record you must have a current record in a cursor. A record may be inserted, updated or deleted by referencing the appropriate table instance.

Example

    update "staff1"

Note
There is a restriction that applies to database access. Any table instance can support only one cursor at a time.