# CHAPTER 1: Introduction

## 1.1 Conventions

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

Table 1-1

Typographical Conventions
Examples | Description
`CALL` `THEN` | In the syntax definition of the command, words in upper case are keywords. These are not case-sensitive and may consist of a mixture of upper case and lower case when typed into Empress.
`tabinst` `attr` | Items in lower case italics refer to categories. When typed into Empress, appropriate substitutions of actual names or expressions must be used. For example, `personnel` for `table`. Within text, they appear in `bold` typeface. Note that for user-defined names, case is significant and must be typed exactly as originally defined.
`|item 1|` `|item 2|` | 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.
`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 upper case.

Table 1-2

Typographical Conventions - Keyboard Keys
Examples | Description
<Return> | Keys on your keyboard appear in between angled brackets.
<Ctrl+A> | 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 optional everywhere except in the Parameter, External, Global and Local Variable Definitions. 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.

Note

However, quotes should not be used around names of procedure scripts.

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

## 1.2 System Global Variables

These variables are assigned and some are updated automatically by Empress 4GL. You can obtain information from these variables at anytime and anywhere in their Empress 4GL application script.

Warning

Do not name variables or subscripts after them.

`database` | 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.
`error_string` | is the most recent user trappable error.
`error_number` | is the unique number identifying `error_string`.
`got_records` | is a flag giving the status of the last `next_rec`, `prev_rec`, `next_record` or `prev_record` calls.
The variable has the following values:
1 | successful
0 | unsuccessful; no next or previous record
-1 | record was unattainable
`insert_mode` | determines whether the Field Editor is in `insert` mode. Set it to 0 to put the Field Editor in `replace` mode and any integer value to put it in `insert` mode. Pressing the `Insert mode` key in the Field Editor sets the variable to 1.
`interrupt_number` | is the signal number for most recent user trappable interrupt.
`records_selected` | is the number of records selected in the last `SELECT` statement (with the `COUNT` option in effect).
`record_status` | is a flag giving the status of the last `next_rec`, `prev_rec`, `next_record`, `prev_record`, `next_line`, `prev_line`, `next_group` or `prev_group` calls. The values of `record_status` are as follows:
-2 | Error
-1 | Record is locked
0 | no next/previous record
1 | Got next/previous record
2 | Beginning of group. This value is only set with `next_rec` and `next_record`.
3 | Aggregate Record
`screen_row` | is the number of rows on the terminal screen.
`screen_column` | is the number of columns on the terminal screen.
`mouse_row` | is the current row position of the mouse cursor.
`mouse_column` | is the current column position of the mouse cursor.
`touch_row` | is the row where the touch screen was last touched.
`touch_column` | is the column where the touch screen was last touched.

## 1.3 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.4 Reserved Keywords

The following is a list of Empress 4GL keywords. As keywords they may appear in mixed lower and upper case. For a complete list of all reserved keywords, please refer to our Reserved Keywords document.

Warning

Do not name variables or subscripts after them.

## 1.5 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 `SELECT` or `UPDATE` commands. Expressions may also appear in `WHERE` clauses.

`expr` is:

    | attr                                |

    | string CONSTANT                     |

    | number                              |

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

    | operator expr                       |

    | built_in_function                   |

    | user_defined_function               |

    | user_defined_set_function           |

    | set_function                        |

    | math_library_function               |

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.

## 1.6 Data Types

Empress 4GL data types are Empress 4GL generic data types. Refer to the Empress SQL Reference manual for more information on generic data types.

Table 1-3

Type | Descriptions | Example
`CHAR` | A sequence of characters that may be letters, numbers, or other symbols. | `abcde12345xyz`
`DATE` | A date in one of the formats acceptable to Empress SQL. |
`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. |

## 1.7 Command Summary Groups

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

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

Warning

Do not name variables, subscripts or user-defined functions after them.

### 1.7.1 Variable Declarations

Table 1-4

Name | Description
`parameter` | define variable passed to the script
`external` | define external variable
`global` | define global variable
`local` | define local variable

### 1.7.2 Control Statements

Table 1-5

Name | Description
`call` | call a function or procedure
`call application` | calls an Empress 4GL application
`call emprepwr` | call an Empress Report Writer script
`display` | display field value
`disable interrupt` | disable trapping of system interrupt signals
`enable interrupt` | reactivate trapping of system interrupt signals
`exit` | leave the application
`export` | export Empress 4GL data structure
`if` | branch depending on condition
`import` | import Empress 4GL data structure
`let` | assign a value
`on error` | trap error and respond
`on interrupt` | trap interrupt signal and respond
`return` | leave a function, optionally returning a value
`switch` | branch depending on value
`while` | repeat while a condition is true

### 1.7.3 Database Statements

Table 1-6

Name | Description
`cancel` | cancel or rollback the current transaction
`check` | validate compatibility with attribute
`close` | close a table
`commit` | commit the current transaction
`define select` | define a select without executing
`delete` | delete record from table
`disable` | disable update operations on context
`enable` | enable update operations on context
`end_select` | remove a context
`insert` | insert record into table
`lock` | lock a table
`next_group` | get the next group from context
`next_rec` | get next record from context
`next_record` | get the next record from context
`open` | open a table
`prev_group` | get the previous group from context
`prev_rec` | get previous record from context
`prev_record` | get the previous record from context
`rollback` | rollback a transaction
`savepoint` | set save point in transaction
`select` | select from tables giving a context
`select context` | refresh a predefined context
`start transaction` | start a transaction
`undefine` | cancel a define select
`update` | update record in table

### 1.7.4 System Functions

Table 1-7

Name | Description
`attr_update` | update an attribute with a value
`attr_value` | return the current value of an attribute
`beep` | make the terminal beep
`check_field` | check the validity of data in a field
`clear_fields` | clear the fields in a window
`clear_save_value` | clear saved value
`clear_status` | clear status window
`compare_save_value` | compares saved field with current field value
`current_field` | make a field current
`current_field_name` | return the name of the current field
`current_field_number` | return the number of the current field
`current_field_update` | update the current field with a value
`current_field_value` | return the value of the current field
`current_field_video` | change the video of the current field
`current_window` | make a window current
`current_window_name` | return the name of the current window
`debug_message` | print a message and pause
`define_group_multi` | associate a context with a window for multiple record displays generated by `SELECT` statements with the `GROUP BY` option.
`define_multi` | associate a context with a window
`display_page` | display a page in a multi-record display
`empsql` | invokes the Query Language interface
`error_message` | enter error state and print a message
`error_window` | associate a window and field to display the error messages
`field_help_window` | display field help window through a command
`field_mode` | change the mode of a field
`field_update` | update a field with a value
`field_value` | return the current value of a field
`field_video` | change the video of a field
`get_save_value` | return the saved value of a field
`info_message` | print a message and continue
`info_window` | associate a window and field to display the message
`key_context_name` | return the key context name on the stack
`key_name` | return the key name for a key label
`key_script` | execute a key script
`largest_field_number` | return the size of a multiple field
`mouse_field_name` | return the mouse field name
`mouse_field_number` | return the mouse field number
`mouse_key_down` | return mouse key pressed data
`mouse_location` | return the current mouse location
`mouse_window_name` | return the mouse window name
`move_window` | move a window on the screen
`next_field` | go to next field of the current window
`next_line` | get next line in multi-record display
`next_page` | get next page in multi-record display
`pop_key_context` | pop a key context for a window
`prev_field` | go to previous field of current window
`prev_line` | get previous line in multi-record display
`prev_page` | get previous page in multi-record display
`print_screen` | print the screen
`push_key_context` | push a key context for a window
`remove_window` | remove a window
`reset_fields` | reset fields to default values
`reset_key_context` | reset the key context stack
`restore_field` | sets fields to their saved field values
`save_field` | save current field value
`scroll_page` | scroll a multi-record display
`scroll_window` | scroll a window over a form
`set_attr_values` | copy values from fields to attributes
`set_field_values` | copy values from attributes to fields
`set_key_values` | copy values from key labels to fields
`set_save_value` | copy value to save field value
`show_window` | show a window on the screen
`sys_command` | execute an operating system function and return
`sys_prompt` | display Y/N question in a pop-up window
`sys_value` | execute command returning result
`sys_variable` | return value of an environment variable
`system` | call the operating system
`temporary_window` | display a window and wait for keystroke
`touch_field_name` | return the touch screen field name
`touch_field_number` | return the touch screen field number
`touch_location` | update the touch screen location
`touch_window_name` | return touch window name
`zoom_window` | grow or shrink a window

### 1.7.5 Administrative Functions

Warning

The following function names are used in Empress 4GL Development Environment `sys_main` application (for Empress 4GL internal use only). Do not name user defined functions after them:

Table 1.7

Name | Description
`compile_application` | compile an application
`compile_definition` | compile a definition
`compile_script` | compile a script
`copy_form` | copy a form
`copy_script` | copy an application
`create_application` | create an application
`create_default` | create a default application
`create_menu` | create a menu
`debug_mode` | turn the 4GL debugger on or off
`delete_form` | delete a form
`delete_script` | delete an application
`edit_form` | invoke the form editor
`link_application` | link an application
`load_definition` | load a definition
`rename_form` | rename a form
`rename_script` | rename an application

## 1.8 Script Definition

An Empress 4GL script is:

        [parameter [;]]

        [external [;]]

        [global [;]]

        [local [;]]

        {statement [;]}

A `statement` may be a control statement, a database statement, a system function or an administrative 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 fields. Administrative functions concern actions involving access to scripts, applications, forms and Application Generator definitions. Most of the administrative functions are for Empress 4GL internal use.

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

To access records in a table, a `SELECT` is done on a table instance. This produces a group of records called a context. Once you have a context, you can get the next or previous record in this context, giving you a current record.

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

Note

There is a restriction that applies to database access. Any table instance can support only one context of records at a time.