# CHAPTER 2: Empress 4GL Statements

The following sections contain an alphabetical listing of all Empress 4GL statements and functions. Each entry contains:

- A description of the statement or function
- A syntax diagram
- Relevant notes
- Information returned
- Related functions
- Examples of use

The Empress 4GL statements are:

  attr_update | attr_value |
  beep |  |
  call | call application | check
  check_field | clear_fields | clear_save_value
  clear_status | close | commit
  compare_save_value | current_field | current_field_name
  current_field_number | current_field_update | current_field_value
  current_field_video | current_window | current_window_name
  debug_message | debug_mode | define_group_multi
  define_multi | define select | delete
  disable | disable interrupt | display
  display_page |  |
  emprepwr | empsql | enable
  enable interrupt | end_select | error_message
  error_window | exit | export
  external |  |
  field_help_window | field_mode | field_update
  field_value | field_video |
  get_save_value | global |
  if | import | info_message
  info_window | insert |
  key_context_name | key_name | key_script
  largest_field_number | let | local
  lock |  |
  mouse_field_name | mouse_field_number | mouse_key_down
  mouse_location | mouse_window_name | move_window
  next_field | next_group | next_line
  next_page | next_rec | next_record
  on error | on interrupt | open
  parameter | pop_key_context | prev_field
  prev_group | prev_line | prev_page
  prev_rec | prev_record | print_screen
  push_key_context |  |
  remove_window | reset_fields | reset_key_context
  restore_field | return | rollback
  save_field | savepoint | scroll_page
  scroll_window | select | select context
  set_attr_values | set_field_values | set_key_values
  set_save_value | show_window | start transaction
  switch | sys_command | sys_prompt
  sys_value | sys_variable | system
  temporary_window | touch_field_name | touch_field_number
  touch_location | touch_window_name |
  undefine | update |
  while |  |
  zoom_window |  |

# attr_update

Description | Update an attribute value in the application.
Syntax |
    call attr_update (tabinst, attr, expr);
where:
`tabinst` | is the table instance name of the table. It may be an expression that evaluates to a string.
`attr` | is the name of the attribute in the table. It may be an expression that evaluates to a string.
`expr` | is an expression which evaluates to the value to be assigned to the attribute.
Notes | This function updates an attribute in the application, not in the database table. To update a record in a table, use the `UPDATE` command.
Returns | None.
See Also |
    update
Example | To update the value of the attribute `"nametable"."tel"` from the field `"names"@"tel"`:
    call attr_update ("nametable", "tel", "names"@"tel");

# attr_value

Description | Return the current value of an attribute.
Syntax |
    let variable = attr_value (tabinst, attr)
or
    if attr_value (tabinst, attr) = expr
where:
`variable` | is any character string that begins with a letter.
`tabinst` | is the table instance name of the table. It may be an expression that evaluates to a string.
`attr` | is the name of the attribute in the table. It may be an expression that evaluates to a string.
Returns | Current attribute value or null.
Example | To assign the value of `"nametable"."tel"` to the variable `telephone`, use:
    let telephone = attr_value ("nametable", "tel");

# beep

Description | Cause the terminal to beep when called.
Syntax |
    call beep ();
Returns | None.
Example | To make the terminal beep, use:
    call beep ();

# call

Description | This calls a procedure.
Syntax |
    call funcname ([expr {, expr}]);
where:
`funcname` | is a function name.
`expr` | is an expression.
Notes | The `funcname` may be a built-in function, a subscript, or a user-defined function. Procedures for adding a user-defined function to Empress 4GL are given in the Empress 4GL Administrator's Guide. If `expr` is given, they are evaluated and the results passed as arguments to the procedure or function.
Returns | None.
Example | To call a subscript named `menu` use the command:
    call menu ();

# call application

Description | Invokes the Empress 4GL application.
Syntax |
    call application apname ([expr {, expr}]);
where:
`apname` | is the name of an Empress 4GL application.
`expr` | is an expression which will be evaluated and the result will be passed to the application as arguments.
Notes | The `apname` must be a quoted `string` or a `variable`. The routine will first look for a module of the given name - that is, a sub-application of the current application. If none is found, it will proceed to look for an independent application of the given name. If a `call application` statement is encountered in a script, the application is executed immediately. When it is completed, control returns to the script. Executing a series of call application statements causes a stack of applications to be built. If the stack grows large, system performance may suffer. An application returns a value through a `return` statement in the application exit script.
Returns | None.
Example | To call an application named `personnel` use the command:
    call application "personnel" ();

# check

Description | Check whether the result of an expression is a valid value for the attribute.
Syntax |
    check expr for attr;
where:
`expr` | is an expression which evaluates to the value to be assigned to the attribute.
`attr` | is the name of the attribute in the table. It may be an expression that evaluates to a string.
Notes | The statement is useful in the exit script of a field. If the statement fails, indicating a bad expression, Empress 4GL will beep and refuse to let you out of the field until the error has been corrected. A null field will always be accepted (even if the attribute is defined as not null). If the statement is used in an exit script, it will be executed before any key script for the current window if a key is pressed, unless the key definition disables exit scripts, in which case the key script will execute immediately.
Returns | None.
Example | To ensure that the data keyed into the field `name` in window `names` is a valid entry for the attribute `name` in `nametable`, use:
    check "names"@"name" for "nametable"."name";

# check_field

Description | Check whether the data in a field is valid for the field.
Syntax |
    let variable = check_field (window, field_name
          [, field_number]);
or
    if check_field (...) = expr
where:
`variable` | is any character string that begins with a letter.
`window` | is the name of the window in which the field lies. It may be an expression that evaluates to a string.
`field_name` | is the name of the field to check. It may be an expression that evaluates to a string.
`field_number` | is a field number which is an integer.
`expr` | is an expression.
Notes | If `field_number` is not specified, then if there is only one field of a given name it is used; whereas if there are several fields of the same name, then the field number of the current field is used to determine the field to be used. The default field number is 1.
Returns | `check_field` returns one of three values in the following table:
| Table 2-1
Value | Meaning
1 | if the data is valid for the field type
0 | if the data is not valid for the field type
-1 | if the field is null
Example | If the field `tel` in window `names` is defined as an integer field in the field definition, you can test if the current value of the field is an integer value with:
    let integerflag = check_field ("names", "tel");

# clear_fields

Description | Clears all the fields in the specified window.
Syntax |
    call clear_fields ([window]);
where:
`window` | is an optional window name specifying the window whose fields are to be cleared. It may be an expression that evaluates to a string.
Notes | If no `window` is supplied, it defaults to the current window. Remember that clearing fields only affects the screen display. The current record (if any) is not affected. As you write your scripts, you may wish to use the `disable` statement to protect against accidental data loss as a result of carelessly pressing function keys.
Returns | None.
See Also | `disable`
Example | To clear the fields in the window `names`, use:
    call clear_fields ("names");

# clear_save_value

Description | Set the saved field value to null.
Syntax |
    call clear_save_value (window [, field_name
         [, field_number]]);
where:
`window` | is an optional window name specifying the window whose saved field values are to be cleared. It may be an expression that evaluates to a string.
`field_name` | is the name of the field to check. It may be an expression that evaluates to a string.
`field_number` | is an integer giving the field number.
Notes | The keyword `NULL` may be used in place of `window`. Empress accepts this as referring to the current window. The keyword `NULL` may be used in place of `field_name`. Empress accepts this as referring to the current field. The `field_name` may be omitted. Empress will then clear saved values for every field in the window. The `field_number` may be omitted. Empress will clear save values for the current field. A saved field value is stored as data type `CHAR`, regardless of the data type of its associated field. Null field values and null saved field values are ignored in save field commands. A null field value is neither saved to the associated field name, nor is it restored to the associated field.
Returns | None
Example | To clear the value saved for the field `name` in the window `names` to null, use:
    call clear_save_value ("names", "name");

# clear_status

Description | Clear the buffer containing system messages displayed in the status box on the top right corner of the screen.
Syntax |
    call clear_status ();
Notes | This function clears system information messages such as "`record n of N`", "`no next record`", and so on. It does not clear error messages or messages placed in the status box by `debug_message`, `error_message`, or `info_message` calls.
Returns | None.
See Also |
    debug_message, error_message, info_message
Example | To prevent record count messages from disturbing the screen, use:
    call clear_status ();

# close

Description | Close a table or list of tables.
Syntax |
    close tabinst {, tabinst};
where:
`tabinst` | is the name of the table instance to be closed.
Notes | This command cannot close a table instance currently in use - that is, a table called in an active `select` command. To close such a table, first issue an `end_select` or `undefine` command.
Returns | None.
See Also |
    end_select, undefine
Example | To close the table `nametable`, use:
    close "nametable";

# commit

Description | Commit the current transaction.
Syntax |
    commit [transaction];
Notes | The current transaction is committed. The transaction must have been started with a `start transaction` command. All database operations subsequent to the start of the transaction are committed. If no transaction is in progress, an error message is printed in a status box on the top right corner of the screen. To roll back a transaction, see the rollback command.
Returns | None.
See Also |
    start transaction, rollback transaction
Example | To commit the current transaction, use:
    commit transaction;

# compare_save_value

Description | Compare the saved field value with the current field value.
Syntax |
    let variable = compare_save_value
          (window [, field_name [, field_number]]);
or
    if compare_save_value () = expr
where:
`variable` | is any character string that begins with a letter.
`window` | is the name of the window in which the field lies. It may be an expression that evaluates to a string.
`field_name` | is the name of the field to check. It may be an expression that evaluates to a string.
`field_number` | is an integer giving the field number.
`expr` | is an expression.
Notes | The keyword `NULL` may be used in place of `window`. The routine will default to the current window. The keyword `NULL` may be used in place of `field_name`. The routine will default to the current field. The `field_name` may be omitted. The operation will be performed on every field in the window, with the results of the individual comparisons added together. A zero (0) will be returned if even one value is different. The `field_number` may be omitted. The operation will be performed on the current field. A saved field value is stored as data type `CHAR`, regardless of the data type of its associated field. Null field values and null saved field values are ignored in saved field commands. A null field value is neither saved to the associated field name, nor restored to the associated field.
Returns |
1 | if the value is the same
0 | if the values are different.
See Also |
    save_value
Example | To compare the value saved for the field `name` in the window `names` to the current value for that field, use:
    let nameflag = compare_save_value ("names", "name");

# current_field

Description | Make the given field in the current window the current field.
Syntax |
    call current_field (field_name [, field_number] ['-x']);
where:
`field_name` | is the name of a field. It may be an expression that evaluates to a string.
`field_number` | is an integer giving the field number.
Notes | If the `field_number` is not specified and there is only one field of a given name, then the field number is 1. If there are several fields of the same name, then the field number of the current field in the form is used. If there is no current field in the form or the field number is out of range, then number 1 is used. Note that entering any field in a window once defines a current field in the window. When control leaves the window, the last current field is remembered and is considered the current field for the window (even though the window is no longer current). The named field is not entered immediately; it is entered after the script containing the statement completes. Only one occurrence of this function, the `next_field` function or the `prev_field` function will be effective in a script or series of scripts executed without interruption. The last call to either `prev_field`, `next_field` or `current_field` is the effective call. The option `-x` instructs the application to execute the exit script of the current field before performing any other action.
Returns | None.
Example | To make the field `name` in the current window current, use:
    call current_field ("name");

# current_field_name

Description | Return the name of the current field.
Syntax |
    let variable = current_field_name ();
or
    if current_field_name () = expr
where:
`variable` | is any character string that begins with a letter.
`expr` | may be any expression that evaluates to a string.
Returns | The name of the current field or returns null if there is no current field.
Example | To put the name of the current field into the variable `field_name`, use:
    let field_name = current_field_name ();

# current_field_number

Description | Returns the field number of the current field.
Syntax |
    let variable = current_field_number ();
or
    if current_field_number () = expr
where:
`variable` | is any character string that begins with a letter.
`expr` | may be any expression that evaluates to an integer.
Returns | The field number of the current field or null if no current field.
Example | To put the field number of the current field into the variable `fnum` (to make it look like variable then the function name), use:
    let fnum = current_field_number ();

# current_field_update

Description | Update the value of the current field.
Syntax |
    call current_field_update (expr);
where:
`expr` | may be any expression that evaluates to the appropriate data type for the field.
Returns | None.
Example | To update the value of the current field with the contents of the variable `goodvalue`, use:
    call current_field_update (goodvalue);

# current_field_value

Description | Return the value of the current field.
Syntax |
    let variable = current_field_value ();
or
    if current_field_value () = expr
where:
`variable` | is any character string that begins with a letter.
`expr` | may be any expression that evaluates to the appropriate data type for the field.
Returns | Value of the current field.
Example | To get the value of the current field into the variable `goodvalue`, use:
    let goodvalue = current_field_value ();

# current_field_video

Description | Set the video attribute of the current field.
Syntax |
    call current_field_video (video_name);
where:
`video_name` | is a video name defined in the Empress 4GL terminal definition database.
Notes | The attribute `normal` is always permitted. The range of allowable video attributes is terminal dependent. The list of `video_name`s that can be used on a given terminal can be read from the `video_name` attribute of the `term_video` table found in the terminal database `termdb`. A brief description of how to locate video names follows. The `termdb` database is the terminal definition database used by Empress 4GL. It normally resides in the 4GL directory where Empress is installed. In `termdb`, search the terminal table for the entry where the `term` attribute corresponds to the value of the Empress variable `MSTERM` or the system variable `TERM` if `MSTERM` is not set. Using the value of the `video_set_1` attribute for that entry, search the `term_video` table for the entries where the `video_set` attribute has the same value. The `video_name` attribute of those entries is the list of `video_name`s you can pass to the `current_field_video` function.
Returns | None.
Example | To set the video of the current field to reverse, use:
    call current_field_video ("reverse");

# current_window

Description | This makes the given window the current window. If a field is specified, this makes the field the current field.
Syntax |
    call current_window (window [, field_name
          [, field_number]] ['-x']);
where:
`window` | is the name of a window. It may be an expression that evaluates to a string.
`field_name` | is the name of a field. It may be an expression that evaluates to a string.
`field_number` | is the number of a field. It may be an expression that evaluates to an integer.
Notes | If the `field_number` is not specified and there is only one field of a given name, then the field number is 1. If there are several fields of the same name, then the field number of the current field in the form is used. If there is no current field in the form or the field number is out of range, then number 1 is used. Note that entering any field in a window once is sufficient to define a current field in the window. When control leaves the window the last current field is remembered and is considered the current field for the window (even though the window is no longer current). When a field is made current with a window, the cursor moves directly into the field. If a window is made current without the current field, the cursor moves to the last field in the window that was current. If there is no such field the cursor moves to the top left corner of the screen. Making a window current does not make it appear on the screen. That is done with the `show_window` function. It is not an error to make a window current without having shown it first. Note that control is not passed to the window immediately; control is passed after the script containing the statement completes. The `-x` option instructs the application to execute the exit script of the current field before performing any other action.
Returns | None.
Example | To make a window called `names` current and make the field `name` in the window current, use:
    call current_window ("names", "name");

# current_window_name

Description | Returns the name of the current window.
Syntax |
    let variable = current_window_name ();
or
    if current_window_name () = expr
where:
`variable` | is any character string that begins with a letter.
`expr` | may be any expression that evaluates to a string.
Returns | Current window name.
Example | To get the name of the current window into the variable `wname`, use:
    let wname = current_window_name ();

# debug_message

Description | Print a given message in the top right hand corner of the screen and wait for a key to be pressed before proceeding.
Syntax |
    call debug_message (message {, message});
where:
`message` | is the message to be printed. It may be any expression that evaluates to a string.
Notes | The messages are concatenated together when they are displayed. No blanks are inserted between each message. The information message is displayed and execution pauses until a key (any key) is pressed.
Returns | None.
Example | To view the value of a variable at some stage of execution, use:
    let a = b;
    call debug_message ("a = ", a);
When the `debug_message` function is executed, the string "`a =` " followed by value of `a` is shown on the top right corner of the screen.

# debug_mode

Description | Turns the 4GL Application Debugger on or off.
Syntax |
    call debug_mode (mode);
where:
`mode` | is the value `on` or `off`.
Returns | None.
Example | To turn the 4GL Application Debugger on use:
    call debug_mode ("on");

# define_group_multi

Description | Associate a context with a window for multiple record displays generated by `SELECT` statements with the `GROUP BY` option.
Syntax |
    call define_group_multi (context, window,
         next_line, prev_line, display_script, locked_script,
         fill_script {, field_name}) [;]
where:
`context` | is the select context to be displayed.
`window` | is the window in which the select context is to be displayed.
`next_line` | is the line in the window that will contain the next record if the `next_line` function causes an implicit next page to occur.
`prev_line` | is the line in the window that will contain the previous record if the `prev_line` function causes an implicit previous page to occur.
`display_script` | is the name of the script to be used to assign values to each field when a page of records is displayed.
`locked_script` | is the name of the script to be used to assign values to each field in the event a record is locked.
`fill_script` | is the name of the script to be used to assign values to each field where there is no record to display.
`field_name` | is the name of a field to be included in the multiple record display for this `context`.
Notes | This function defines `window` as a multiple record window for displaying records of the `context`. The `window` will normally contain multi-fields (sets of fields sharing the same name) for displaying attribute values. A multiple record window can be used to display several contexts, provided that different contexts are mapped to different multi-fields, as described for the `field_name` argument below. The functions `next_line`, `prev_line`,`scroll_page`,`display_page`,`next_page`,`prev_page`,`next_group`, and`prev_group` are made available for the context. If `next_line` is 0, the value of the largest field number in the window is used, (i.e., the page will scroll up by one line in the event of an implicit next page). If `prev_line` is 0, the value of the largest field number in the window is used, (i.e., the page will scroll down by the number of lines in the page in the event of an implicit previous page). If there are fewer records remaining at the beginning of the context than lines in the multi-record display, the previous record will be placed on the line number correspond- ing to its actual position in the context. The `display_script` script will normally contain state- ments assigning values to fields. The script is executed by the `next_line`,`prev_line`,`scroll_page`,`display_page`, `next_page` and`prev_page` functions to refresh the display whenever necessary. The script is executed once for each record to be displayed. The `locked_script` script will normally contain statements assigning values to fields. The script is executed by the `next_line`,`prev_line`, `scroll_page`, `display_page`,`next_page`,`prev_page` functions to refresh the display whenever necessary. The script is executed once for each record that is locked. The `fill_script` script will normally contain statements assigning values to fields. The script is executed by the `next_line`,`prev_line`, `scroll_page`, `display_page`,`next_page`,`prev_page` functions to refresh the display whenever necessary. The script is executed once for each field number in the window for which there are no more records in the context. It is possible to associate multi-fields in a window with more than one context. If no `field_name`s are listed, all the fields in the window are included. The `next_group` and `prev_group` functions can be used to access contexts generated by the `define_group_multi` and `define_multi` commands and also for contexts displayed one record at a time. The `define_group_multi` command will allow for the display of only one group of records at a time, if a `GROUP BY` clause is present in the `define select` statement. To access another group of records, either the `next_group` or `prev_group` commands must be used. Within a group, the `next_line` and `prev_line` functions can be used to access records, including the aggregate record for that group. If the `define_multi` command is used in conjunction with a context, the first record in one group will be displayed immediately following the last record of the previous group. To access records in another group the functions `next_line` and `prev_line` can be used, as well as the functions `next_group` and `prev_group`. The `next_group` and `prev_group` functions are generally intended to be used with the `define_group_multi` function. For each group in the context there will be a row that can be used to display the aggregate record for that group. That row can be determined by testing the `record_status` variable for the value 3. See the Empress 4GL User's Guide for a detailed example of building a multiple record application.
Returns | None.
See Also |
    set_field_values, select, define select, display_page,
    next_group, prev_group, define_multi
Example | See example for `define_multi`.

# define_multi

Description | Associate a context with a window for multiple record displays.
Syntax |
    call define_multi (context, window, next_line,
         prev_line, display_script, locked_script,
         fill_script {, field_name});
where:
`context` | is the select context to be displayed.
`window` | is the window in which the select context is to be displayed.
`next_line` | is the line in the window that will contain the next record if the `next_line` function causes an implicit next page to occur.
`prev_line` | is the line in the window that will contain the previous record if the `prev_line` function causes an implicit previous page to occur.
`display_script` | is the name of the script to be used to assign values to each field when a page of records is displayed.
`locked_script` | is the name of the script to be used to assign values to each field in the event a record is locked.
`fill_script` | is the name of the script to be used to assign values to each field where there is no record to display.
`field_name` | is the name of a field to be included in the multiple record display for this `context`.
Notes | This function defines `window` as a multiple record window for displaying records of the `context`. The `window` will normally contain multi-fields (sets of fields sharing the same name) for displaying attribute values. For use with this function, all the multi-fields in the window included in the display must consist of the same number of fields, that is, the largest field number of all the fields must be the same. A multiple record window can be used to display several contexts, provided that different contexts are mapped to different multi-fields, as described for the `field_name` argument below. The functions `next_line`, `prev_line`, `scroll_page`, `display_page`, `next_page`, and `prev_page` are made available for the context. If `next_line` is 0, the value of the largest field number in the window is used, (ie. the page will scroll up by one line in the event of an implicit next page). If `prev_line` is 0, the value of the largest field number in the window is used, (i.e., the page will scroll up by the number of lines in the page in the event of an implicit previous page). The `display_script` script will normally contain statements assigning values to fields. The script is executed by the `next_line`, `prev_line`, `scroll_page`, `display_page`, `next_page` and `prev_page` functions to refresh the display whenever necessary. The script is executed once for each record to be displayed. The `locked_script` script will normally contain statements assigning values to fields. The script is executed by the `next_line`, `prev_line`, `scroll_page`, `display_page`, `next_page` and `prev_page` functions to refresh the display whenever necessary. The script is executed once for each record that is locked. The `fill_script` script will normally contain statements assigning values to fields. The script is executed by the `next_line`, `prev_line`, `scroll_page`, `display_page`, `next_page` and `prev_page` functions to refresh the display whenever necessary. The script is executed once for each field number in the window for which there are no more records in the context. Each multi-field in the window can be associated with only one context. If no `field_name`s are listed, all the fields in the window are included.
Returns | None.
See Also |
    set_field_values, select, display_page
Example | Consider the form `names` shown below. The field names are shown beside the fields represented as lines.
    _______ name [1] ___________ address [1] ________ tel [1]
    _______ name [2] ___________ address [2] ________ tel [2]
    _______ name [3] ___________ address [3] ________ tel [3]
    _______ name [4] ___________ address [4] ________ tel [4]
    _______ name [5] ___________ address [5] ________ tel [5]
Suppose we have defined a window `names` to show this form. We would like to show the records of table `nametable` with the attributes `name`, `address` and `tel` in this window. If we have opened `nametable` using the default table instance name (same as the table name), we can define a context with the `define select` statement:
    define select from "nametable"
           becomes context "name_list";
To associate the context with the window, we use:
    call define_multi ("name_list", "names", 0, 1,
         "display_script" "locked_script", "fill_script");
We can then write the script `display_script` as:
    call set_field_values ("names", "name_list");
The `set_field_values` function will assign field values in the `names` window from attributes of the same name from the `name_list` context. The script `locked_script` may be:
    call set_field_values ("names", "name_list", 0, NULL);
    let "names"@"address" = "locked";
Here the `set_field_values` function is used to assign `null` to each field, then the string `locked` is put in the `address` field. The script `fill_script` may set each field to `null`:
    call set_field_values ("names", "name_list", 0, NULL);
To display the records of the context in the window, we can do:
    call show_window ("names");
    select context "name_list";
    call display_page ("name_list");
If you make the `names` window current and allow tabbing within the fields of that window, it is important to keep the cursor on the same line when moving from field to field, otherwise the cursor will not reliably indicate the current record of the context. Use the previous and next entries of the field definitions to do this. Specifying previous and next field names in the field definition without specifying their field numbers causes the same field number as the current field to be used by default. For instance, in this example we should define the previous of `name` to be `tel` and the next of `tel` to be `name`, without specifying any field number.

# define select

Description | Define a select without executing.
Syntax |
    define select_statement
where:
`select_statement` | is a 4GL `select` statement.
Notes | Except for the leading keyword `define`, the syntax of this statement is the same as for `select`. Details of the syntax are explained under the subsection for the `select` statement. This statement defines a `context` without executing the Query Language `select` from the database(s). The actual `select` may be done separately using a `select context`. The `context` defined with this statement must be removed with the `undefine` statement.
Returns | None.
See Also |
    select context, select
Example |
    The statement:
    define select from "nametable"
         where "nametable"."name" = "names"@"name";
defines a `context` that can be initialized with the `select context` statement. The `context` takes the name `nametable` by default. The statement:
    define select from "nametable"
         where "nametable"."name" = "names"@"name"
         becomes context "namesakes";
defines a similar `context` but with the name `namesakes`.

# delete

Description | Delete a record.
Syntax |
    delete tabinst {, tabinst};
where:
`tabinst` | is a name given to an Empress database table when it is opened for access.
Notes | The record deleted is the current record of each `context` generated from the `tabinst`s. If there is no current record for a `tabinst`, Empress 4GL will beep and stop executing the script.
Returns | None.
Example | To delete a record in `nametable`, use:
    delete "nametable";

# disable

Description | Disable access to the current record within a given `context`.
Syntax |
    disable context;
where:
`context` | is the selected context to be disabled.
Notes | The `disable` command effectively disestablishes the current record without losing its position. Attempting an update or delete operation causes a "`No current record`" message to be displayed. Also, the lock on the record is released. The context is disabled until a current record re-establishes with a `next_rec`, `prev_rec`, or `enable` statement.
Returns | None.
See Also |
    enable
Example | To disable any update or delete operations on `namesakes`, use:
    disable "namesakes";

# disable interrupt

Description | Disable trapping of system interrupt signals.
Syntax |
    disable interrupt signal_no. {, signal_no. ...};
where:
`signal_no.` | is the identifying number of a signal generated by UNIX. The signal(s) should have been trapped with the `on interrupt` command earlier in the application before they are disabled.
Notes | Before using `disable interrupt` the application must have trapped the interrupt with the `on interrupt` command. After the signals are disabled they can be re-enabled again with the `enable interrupt` command. If signals are disabled then the Empress 4GL will take its default action. In most cases, this is to ignore the signal.
Returns | None.
See Also |
    on interrupt, enable interrupt
Example | To disable trapping of the alarm and urgent signals use:
    disable interrupt 14, 16;

# display

Description | This displays visible fields with current values.
Syntax |
    display [from funcname |()             |];
                           |(expr {, expr})|
where:
`funcname` | is a function name. It is usually the name of a script.
`expr` | is an expression.
Notes | Empress 4GL does not refresh the screen with every assignment of a value to a field. A `display` causes every visible field to be updated with its current value. `show_window` commands are not visible until a `DISPLAY` is done. If `funcname` is supplied, the script `funcname` is invoked with the given expressions as arguments, typically to assign values from attributes to fields. The screen is refreshed after the sub-routine completes. The function name must not be enclosed in quotes. The parentheses after the function name are necessary even if no arguments are passed.
Returns | None.
Example | To refresh the screen after executing a script `display_names` that updates field values, use:
    display from display_names ();
where:`` `display_names` is the script:
    let "names"@"address" = "nametable"."address";
    let "names"@"tel" = "nametable"."tel";

# display_page

Description | Display the current page of records in a multiple record window.
Syntax |
    call display_page ([context]);
where:
`context` | is the context whose records are to be displayed.
Notes | If no `context` is given it defaults to the context associated with the current window. The `context` must be associated with a window used for multiple record displays, that is, the context and window must have been associated through a `define_multi` function call. The function retrieves the current page of records from the context and displays it in the appropriate window. If that window is the current window, then the record on which the cursor is resting when the function completes is the current record. This function is equivalent to a `scroll_page (0)` function call. Either this function or the equivalent `scroll_page (0)` should be executed after any insert, update, or delete is done on the context. This guarantees that the display reflects the current state of the context. As the function displays each record on the page it attempts to obtain it in the context. If it succeeds, the function to display the record (the fifth argument to `define_multi`) is executed. If the record is locked the script given as the sixth argument to `define_multi` is executed. When there are no more records in the context the script given as the seventh argument to `define_multi` is executed for each remaining line in the window. If there are no records to display a status message is printed in the status box on the top right corner of the screen.
Returns | None.
See Also |
    define_multi
Example | Referring to the example for the `define_multi` function, to display the current page of records of context `name_list` in the window `names`, use:
    call display_page ("name_list");

# emprepwr

Description | Call Empress Report Writer.
Syntax |
    call emprepwr context (script_name, outfile
         [, message {, expr}])
where:
`context` | is the name associated with a `select` statement or `define select` statement.
`script_name` | is the name of the Report Writer script to be executed.
`outfile` | is the name of the file to which the Report Writer output will be directed.
`message` | is a string or a variable containing a message to appear on the screen when Report Writer starts running.
Notes | A `context` is a named group of selected records referred to as a context. This sends all the records in `context` to the Report Writer for formatting by the Report Writer script `script_name`. Any specified expressions are evaluated and passed to the Report Writer as arguments. Although the records in the Empress 4GL context are passed to the Report Writer, the context name is not passed, so that the group of records is not recognized by the context name in the Report Writer. The Report Writer sees the records in exactly the same way that it sees records in a file when it is invoked with the `-f` option - the Report Writer `FOR` statements will automatically operate on those records by default, as long as they are not within the scope of a `SELECT` or `READ` statement. The `outfile` is overwritten if it exists. If the first character of the `outfile` is "`!`", the remainder of the`outfile` is taken as a UNIX command. So, the `outfile` is commonly "`'!lpr'`" to direct output to the line printer spooler. Other special values are: Table 2-2
outfile Special Values
outfile | Output Directed To
"`-`" | Screen (standard output).
"`pager`" | `MSPAGER`
"`printer`" | `MSPRINTER` (equivalent by default to "`!pr | lpr`")
`MSPAGER` and `MSPRINTER` are Empress variables which specify system paging and printing programs. See the Empress SQL User's Guide. The `message` may be a string or a variable containing a message to appear on the screen when the Report Writer starts running. If you pass arguments to the Report Writer but want no messages, use the keyword `NULL` instead of a string. The call is then silent.
Example | To call the Report Writer script `printnames` to format the records of context `namesakes` and send the output to the file `printfile`, use:
    call emprepwr "namesakes"
        ("printnames", "printfile", "names being printed");
The message "`names being printed`" appears on the screen when the Report Writer is called.

# empsql

Description | Call Empress, invoking the Query Language interface.
Syntax |
    call empsql ([database_name [, query_language_command]]);
where:
`database_name` | is the name of an Empress database. It may be any expression that evaluates to a string.
`query_language_command` | is an Query Language command to be executed when Empress is called.
Notes | If `database_name` is supplied, the Query Language is invoked with that database as the default database. If `database_name` is not supplied, the Query Language is invoked without a default database. If `query_language_command` is supplied then the command is executed; after it completes, a message is printed to "`press any key`" to return to Empress 4GL. If `query_language_command` is not supplied the Query Language `STOP` command returns control to Empress 4GL.
Returns | None.
Example | To call Empress for the database `mydatabase`, use:
    call empsql ("mydatabase");
To call Empress without a default database use:
    call empsql ();
Regardless of whether there is a default database, any table in any database can be referenced by preceding the table name with the database name followed by a colon (:) as in:
    display mydatabase:mytable;
To display the table `mytable` in the database `mydatabase`, use:
    call empsql ("mydatabase", "display mytable");

# enable

Description | Enable a `context` that was previously disabled with `disable`.
Syntax |
    enable context;
where:
`context` | is the selected context to be enabled.
Notes | `enable` re-establishes the current record if it still exists or is not locked by another user. `next_rec`, `next_record`, `prev_rec` and `prev_record` also enable a context.
Returns | None.
See Also |
    disable, next_rec, prev_rec, next_record, prev_record
Example | To enable the context `namesakes`, use:
    enable "namesakes";

# enable interrupt

Description | Reactivate trapping of system interrupt signals.
Syntax |
    enable interrupt signal_no {, signal_no. ...};
where:
`signal_no.` | is the identifying number of a signal generated by UNIX. The signal(s) must have been trapped with the `on interrupt` command and may have been disabled with the `disable interrupt` command before they are enabled again.
Notes | Before using `enable interrupt` the application must have trapped the interrupt with the `on interrupt` command. The signal(s) may have been temporarily disabled within the application with the `disable interrupt` command
Returns | None.
See Also |
    on interrupt, disable interrupt
Example | To reactivate execution of the default action (as given within the application by the `on interrupt 14` command) when the alarm signal is received, use:
    enable interrupt 14;

# end_select

Description | Remove the given `context`.
Syntax |
    end_select [context] context;
where:
`context` | is the selected context on which the `end_select` is performed.
Notes | It removes contexts initialized with `select`s but does not remove contexts defined by `define_select`. Since a table instance can only support one context, this statement frees the table instance to generate another context. This statement will fail giving an error if the context was never established by the execution of a `select`. If a context on a table is established, and another table instance is to be opened on the table, an `end_select` should be done on the context first. This guarantees that any work on the context is written from program buffers for the new table instance to pick up.
Returns | None.
See Also |
    select, define_select
Example | To remove the context `namesakes`, use:
    end_select "namesakes";

# error_message

Description | Force Empress 4GL to enter an error state for the script and to print an error message at the top right corner of the screen.
Syntax |
    call error_message (error_message {, error_message});
where:
`error_message` | may be any expression that evaluates to a string.
Notes | The error messages are concatenated together when they are displayed. Note that no blanks are inserted between each error message. Empress 4GL will beep and exit from the script immediately. Subsequent statements in the script will not be executed.
Returns | None.
Example | To force an error condition when two variables `a` and `b` are not equal, use:
    if a != b
    then call error_message ("error: a = ", a, " b = ", b);
    end;

# error_window

Description | This determines the window and field to be used by an application to display an error message.
Syntax |
    call error_window ([window, field]);
where:
`window` | is the name of the window to be shown in the event of an error.
`field` | is the name of the field to be used for the error message in the event of an error.
Notes | The window and field called can be any to which you have access in the current application. The window can be user-defined. If no window is specified, the application will use the built-in default error window. If the default window is used, it will automatically grow or shrink to match the size of the field displayed. A user-defined error window will not. The field number is always assumed to be 1.
Returns | None.
Example | To call the window `error` and the field `error_message` in the event of an error, use:
    call error_window ("error", "error_message");

# exit

Description | Stop execution of a script and exits to a specified location.
Syntax |
    exit [|empress       |] [confirm];
          |script        |
          |to application|
where:
`application` | is the name of an application in the calling sequence.
Notes | Whenever you exit an application the application exit script is executed. If the `confirm` option is specified, the user will be prompted for exit confirmation with a "`Confirm exit? (y/n)`" message.
Returns | None.
Example | To exit the current application, use:
    exit;
To exit Empress 4GL, use:
    exit empress;
To stop execution in the current script but not exit the current application, use:
    exit script;
To exit to the application `menu` in the calling sequence, use:
    exit to "menu";

# export

Description | Some Empress 4GL data structures can be shared across applications. Sharing data saves space by eliminating redundant form and window definitions and opens and selects. Use `export` to export Empress 4GL data structures across applications.
Syntax |
    export struct_type struct_name {;
           struct_type struct_name} [;] END;
where:
`struct_type` | is one of the keywords `form`, `window`, `select`, `table`, or `script`.
`struct_name` | is the name of the desired form, window, select, table, or script.
Notes | Data can be exported from a calling application to a called application. Data must be declared for export in the enter script of the application. Export declarations must follow any parameter and import declarations, and precede any other declarations. A shared table instance is defined in one application and used in another. A shared table instance can be used for inserts, updates, deletes, and selects. A table instance can be defined only once and can be used in only one select context at a time. A shared select context is executed in one application and used in another. A record may be made current in one application and accessed in the other. The same guidelines on the use of select contexts hold across applications as within applications. A shared form is defined in one application and used in another. A shared window is defined in one application and used in another. A shared window can be shown and removed. The fields of a shared window can be used to display, update, and retrieve data. However, a shared window can only be made current and its key context accessed from the application in which it was defined. A shared script is defined in one application and used in another.
Returns | None.
Example | To export the script `check_value` from the current application, use:
    export script check_value; end;

# external

Description | Declare a variable to be an `external` variable.
Syntax |
    external [type] variable {; [type] variable} [;] end;
where:
`type` | is the data type of the variable.
`variable` | is the variable name.
Notes | The named variables are declared to be external to the application and of the given types. External variables must be declared `global` in an application to be linked with the application. See Chapter 1.8 - "Data Types". An `external` variable may only be declared in the application enter script. There may be only one `external` statement in a script. It must follow the `parameter` statement, if any, and precede all other statements.
Returns | None.
Example | To define `external` `name` and `age` so that they will be identified with a `global` defined in another application:
    external
        char name;
        integer age;
    end;

# field_help_window

Description | Display the Help screen temporarily. The Help screen will disappear on the next key stroke.
Syntax |
    call field_help_window ()
Notes | None.
See Also | `Help` key
Example | To display the Help screen, use:
    call field_help_window ();

# field_mode

Description | Alter the mode of a field while an application is running.
Syntax |
    call field_mode (window, field_name, field_number, mode);
where:
`window` | is the window containing the field to be altered.
`field_name` | is the name of the field to be altered.
`field_number` | is the number of the field to be altered. For a normal (non-multi) field, `field_number` should be set to a value of 1.
`mode` | is the mode to set the field to. It may be one of: `r` (read), `w` (write), or `s` (skip). The mode of a field cannot be changed to `skip` mode while it is the current field.
Notes | There is no way to reset the field to the mode defined in the `Field Table`. Changes to the mode of a field will persist until the mode is changed with `field_mode` or the application is exited. Removing then restoring a window will not reset the mode of fields in the window. There is no way to query the field mode.
Returns | None.
See Also |
    next_field, prev_field
Example | To change the mode of the field `name` in the window `names` to read, use:
    call field_mode ("names", "name", 1, "r");

# field_update

Description | Update a field with a value.
Syntax |
    call field_update (window, field_name,
         [field_number, ] expr);
where:
`window` | is the name of the window with the field. It may be an expression that evaluates to a string.
`field_name` | is the name of the field. It may be an expression that evaluates to a string.
`field_number` | is an optional integer giving the field number of the field. It may be an expression that evaluates to an integer.
`expr` | is an expression which evaluates to the value to be assigned to the field.
Notes | If the `field_number` is not specified and there is only one field of a given name, then this field is updated. If there are several fields of the same name, then the field number of the current field in the form is updated. If there is no current field in the form or the field number is out of range, then the field with field number 1 is updated. Note that entering any field in a window once is sufficient to define a current field in the window. When control leaves, the window the last current field is remembered and is considered the current field for the window (even though the window is no longer current).
Returns | None.
Example | To update the field `"names"@"tel"` with the value of attribute `"nametable"."tel",` use:
    call field_update ("names", "tel", "nametable"."tel");

# field_value

Description | Return the current value of a field.
Syntax |
    let variable = field_value (window, field_name
        [, field_number]);
or
    if field_value (window, field_name
        [, field_number]) = expr
where:
`window` | is the name of the window with the field. It may be an expression that evaluates to a string.
`field_name` | is the name of the field. It may be an expression that evaluates to a string.
`field_number` | is the field number of the field.
Notes | If the `field_number` is not specified and there is only one field of a given name, then the field number is 1. If there are several fields of the same name, then the field number of the current field in the form is used. If there is no current field in the form or the field number is out of range, then number 1 is used. Note that entering any field in a window once is sufficient to define a current field in the window. When control leaves the window, the last current field is remembered and is considered the current field for the window (even though the window is no longer current).
Returns | The current value of the specified field or null.
Example | To assign the current value of the `tel` field in window `names` to the variable `telephone`, use:
    let telephone = field_value ("names", "tel");

# field_video

Description | Set the video attribute of a field.
Syntax |
    call field_video (window, field_name,
        [field_number, ] video_name);
where:
`window` | is the name of the window containing the field.
`field_name` | is the name of the field whose video attribute is to be affected.
`field_number` | is the number of the field.
`video_name` | is a video name defined in the Empress 4GL terminal definition database.
Notes | If the `field_number` is not specified, and there is only one field of a given name, then the field number is 1. If there are several fields of the same name, then the field number of the current field in the form is used. If there is no current field in the form or the field number is out of range, then number 1 is used. Note that entering any field in a window once is sufficient to define a current field in the window. When control leaves the window, the last current field is remembered and is considered the current field for the window (even though the window is no longer current). The attribute `normal` is always permitted. The range of allowable video attributes is terminal dependent. See the entry for the function `current_field_video` for how to find the allowable `video_name`s on a given terminal.
Returns | None.
See Also |
    current_field_video
Example | To set the video of the field `"names"@"address"` to reverse use:
    call field_video ("names", "address", "reverse");

# get_save_value

Description | Return the saved value for a given field.
Syntax |
    let variable = get_save_value (window, field_name
        [, field_number]);
or
    if get_save_value (window, field_name
        [, field_number]) = expr
Notes | A saved field value is a copy of the value in a field. A given field has only one saved value, even if it is a multi-field. The keyword `NULL` can be used in place of `window`. The routine will default to the current window. The keyword `NULL` can be used in place of `field_name`. The routine will default to the current field. The `field_number` may be omitted. The routine will default to the current field number. A saved field value is stored as data type `CHAR`, regardless of the data type of its associated field. Null field values and null saved field values are ignored in saved field commands. A null field value is neither saved to the associated save name, nor restored to the associated field(s).
Returns | Saved value for a given field.
Example | To retrieve the saved value for the field `name` in the window `names`, use:
    let variable = get_save_value ("names", "name");

# global

Description | Declare variable to be `global`.
Syntax |
    global [type] variable {; [type] variable} [;] END;
where:
`type` | is the data type of the variable.
`variable` | is the name of the variable.
Notes | The named variables are declared to be global to the application and of the given types. See Chapter 1.8 - "Data Types". A `global` variable may only be declared in the application enter script. `global` variables declared elsewhere are taken as `local` to the script. There may be only one `global` statement in a script. It must follow the `parameter` and `external` statements, if any, and precede all other statements. A `global` can be referenced in another application by declaring the same variable as an `external` in that application.
Returns | None.
See Also |
    parameter, external, local
Example | To define variables `name` and `age` so that they will be known throughout the application, do the following in the application enter script:
    global
       char name;
       integer age;
    end;

# if

Description | Choose one of two branches of statements based on the evaluation of a condition.
Syntax |
    if condition [then]
    {statement [;]}
    [|else {statement [;]}|]
     |elseif_clause       |
    end;
where `elseif_clause` has the format:
    elseif condition [then]
    {statement [;]}
    [|else {statement [;]|]
     |elseif_clause      |
    and condition may be one of the following:
    (condition)
    condition or condition
    condition and condition
    not condition
    expr[|is      |]range expr[|exclusive|]to expr[|exclusive|]
         |[is] not|            |inclusive|         |inclusive|
    expr[|is      |]between expr[|exclusive|]and expr[|exclusive|]
         |[is] not|              |inclusive|          |inclusive|
    expr[|is      |] [|= |] null
         |[is] not|   |!=|
                      |~=|
    null expr
    expr[|IS      |] |=       | expr
         |[is] not|  |<       |
                     |>       |
                     |<=      |
                     |>=      |
                     |!=      |
                     |<>      |
                     |~=      |
                     |like    |
                     |not like|
                     |match   |
                     |!match  |
                     |smatch  |
                     |!smatch |
where:
(`condition`) | guarantees precedence.
`Or` | is an `or` conjunction which returns true if either condition is true.
`and` | is an `and` conjunction which returns true if both conditions are true.
`range` `between` | is a `range` or `between` condition which returns true if the value falls in the given range. The `exclusive` keyword means that the boundary values are not included in the range. The `inclusive` keyword means that the boundary values are included in the range. The keyword `excl` is a synonym for `exclusive` and `incl` is a synonym for `inclusive`. The default is `inclusive`.
`Patterns` | are operators `like`, `match`, `smatch` (single-case pattern match), `!match` and `!smatch` providing pattern matching. Pattern matching is as for Empress Query Language `WHERE` clauses. The interpretation of patterns is in the following table. Table 2-3
Pattern Matching Characters
Character | Use | Example
? | Matches any character in the position. |
* | Matches 0 or more occurrences of any character. |
[...] | Matches any of a set of characters in the position. | `[abc]` matches "a", "b", "c"
{...} | Matches 0 or more occurrences of a fixed length pattern. | `{[a-z]}` matches any string of lower case letters
[.-.] | Matches any range of characters in the position. | `[a-cf-i]` matches "a", "b", "c", "f", "g", "h", "i"
[^...] | Matches anything but a set or range of characters in the position. | `[^123]` matches everything but 1, 2, and 3; `[^a-d]` matches anything but "a", "b", "c", and "d"
...|... | Requires a match on either side of the bar. | `"ab|cd"` requires a match on "ab" or "cd"
...&... | Requires match on both sides of the ampersand. | `[a-z]&[^x]` matches any letter except "x"
\ | Placed before any of the special characters "?", "*", "|", "&", "{,}", "[,]", and "\", causes the character to be interpreted as an ordinary character. |
Notes | If the `condition` is true, the statements after the `then` are executed. If the condition is false, the statements following the `else` or `elseif` are executed. In a `condition` that compares two expressions, neither expression should evaluate to null, else an error is flagged. To prevent this from occurring, test for null explicitly before using an expression that may have a null value. Attempting to compare a string and a number results in an expression failure. An error message will be generated.
Returns | None.
Example 1 | Suppose you are writing an exit script for the field `name` in the window `names`. If you want to be able to leave the application by typing `stop` in the `name` field, you could use this statement:
    if "names"@"name" = "stop" then
         exit;
    end;
Example 2 | Extending the above example, suppose you wish to take the following actions in the exit script for the `name` field: If the field is empty prompt for a value If the value is `stop` exit the script If there is a value and it is not `stop` call the script `get_details`. You can use the `if` statement as follows:
    if "names"@"name" = null then
         call error_message ("enter a name");
    elseif "names"@"name" = stop then
         exit;
    else
         call get_details ();
    end;

# import

Description | Some Empress 4GL data structures can be shared across applications. Sharing data saves time and space by eliminating redundant form and window definitions and opens and selects. Use `import` to import Empress 4GL data structures across applications.
Syntax |
    import struct_type struct_name
         {; struct_type struct_name} [;] end;
where:
`struct_type` | is one of the keywords `form`, `window`, `select`, `table`, or `script`.
`struct_name` | is the name of the desired form, window, select, table, or script.
Notes | Data can be imported to a called application from a calling application. Data must be declared for import in the enter script of the application. Import declarations must follow any parameter declarations, and precede any other declarations. A shared table instance is defined in one application and used in another. A shared table instance can be used for inserts, updates, deletes, and selects. A table instance can be defined only once and can be used in only one select context at a time. A shared select context is executed in one application and used in another. A record may be made current in one application and accessed in the other. The same guidelines on the use of select contexts hold across applications as within applications. A shared form is defined in one application and used in another. A shared window is defined in one application and used in another. A shared window can be shown and removed. The fields of a shared window can be used to display, update, and retrieve data. However, a shared window can only be made current and its key context accessed from the application in which it was defined. A shared script is defined in one application and used in another.
Returns | None.
See Also |
    export
Example | To import the script `SC1` to the current application, use:
    import script SC1; end

# info_message

Description | Print the given message in the top right hand corner of the screen.
Syntax |
    call info_message (information {, information});
where:
`information` | may be any expression that evaluates to a string.
Notes | The `information`s are concatenated together when they are displayed. Note that no blanks are inserted between each information. If any system information messages are caused by the script, these will cover the `information`. System information messages are displayed after the script is executed, and thus after any `info_message` statement in the script. System information messages may be suppressed by using a return statement in the script. If any system error messages are caused by the script after the `info_message` statement, these will cover the `information`. The `info_message` also does the equivalent of a `display`.
Returns | None.
See Also |
    display
Example | To display a message when a certain phase (for example `phase 5`) of execution begins, use: call info_message ("phase 5 beginning");
    ....
    .... (phase 5 statements)
    ....

# info_window

Description | This determines the window and field to be called by an application in the case of an Empress 4GL information message or call to an `info_message`.
Syntax |
    call info_window ([window, field]);
where:
`window` | is the name of the window to be shown in the event of a call to an information message.
`field` | is the name of the field to be used for the message text in the event of a call to an information message.
Notes | The window and field called can be any to which you have access in the current application. The window can be user-defined. If no window is specified, the application will use the built-in default information window. If the default window is used, it will automatically grow or shrink to match the size of the field displayed. A user-defined information window will not. The field number is always assumed to be 1.
Returns | None.
See Also |
    info_message
Example | To call the window `info` and the field `info_message` in the event of a call to an information message, use:
    call info_window ("info", "info_message");

# insert

Description | Insert a record into a table.
Syntax |
    insert tabinst {, tabinst}
          [from funcname |()             |];
                         |(expr {, expr})|
where:
`tabinst` | is a table instance.
`funcname` | is a function name. It is usually the name of a script.
Notes | Each record is defined by the current attribute values associated with each `tabinst`. If `funcname` is supplied, the script `funcname` is invoked with the given expressions as arguments, typically to assign values from fields to attributes. The insert is done after the function completes. The function name must not be enclosed in quotes. The parentheses after the function name are necessary even if no arguments are passed. Inserting a record does not affect the position of the current record of the context, if any, associated with the table instance; in particular, the record inserted should not be confused with the current record. To prevent inadvertent corruption of the current record, the context is disabled immediately after an `insert`. No update or delete may be applied to the context until a current record is re-established with a `next_rec`, `prev_rec` or `enable` statement.
Returns | None.
See Also |
    next_rec, prev_rec, enable
Example | To insert a record into a table instance named `nametable` after executing a script `insert_name` that updates attribute variables, use:
    insert "nametable" from insert_name ();
where `insert_name` is the script:
    let "nametable"."address" = "names"@"address";
    let "nametable"."tel" = "names"@"tel";

# key_context_name

Description | Return the name of a key context on the key context stack.
Syntax |
    let variable = key_context_name ([[window,] number]);
or
    if key_context_name ([[window,] number]) = expr
where:
`variable` | is an Empress 4GL variable of data type `CHAR`.
`window` | is the name of the window associated with the key context stack. If no window name is given, the routine defaults to the current window.
`number` | is the key context's number on the stack. If no number is given, the routine defaults to the first key context. If the number given does not match any key context, the routine will return a null.
`expr` | is an expression.
Notes | Key context stacks are defined with the Script Editor. Local key context stacks are defined through the window table; global key context stacks are defined through the application table. Stacks are manipulated with the `push_key_context` and `pop_key_context` commands.
Returns | Name of the key context.
See Also |
    push_key_context, pop_key_context
Example | To get the name of a key context that is third on the stack in the window `names`, use:
    let keyname = key_context_name ("names", 3);

# key_name

Description | Return the name of the key on the terminal keyboard associated with the label for the key used in the application.
Syntax |
    let variable = key_name (key_label);
or
    if key_name (key_label) = expr
where:
`variable` | a variable name.
`key_label` | a label that is assigned to a key as defined in `termdb`.
Notes | `variable` often will be a field, since key names are useful to display the physical keys associated with scripted functions. The mapping between key names and key labels is defined in the terminal database `termdb`. Each physical key may be referenced by more than one label, but each label may refer to only one key. In the terminal configuration tables supplied with Empress 4GL, the labels `AP_1` to `AP_10` are always mapped to some key. These labels can always be safely used.
Returns | Name of the key.
See Also |
Example | Suppose you have a field called `update` in a window called `menu`. You have written a script to do the update in the `menu` window. The script is associated with the key `AP_1`. Now you want to display the `menu` window, and the physical key that should be pressed to execute the script. You can type:
    call show_window ("menu");
    let "menu"@"update" = key_name ("AP_1");
    display;

# key_script

Description | Execute a key script.
Syntax |
    call key_script ([context,] key_label);
where:
`context` | is the name of a key context.
`key_label` | a label that is assigned to a key as defined in `termdb`.
Notes | If a key context is not specified then the current key context is used.
Returns | None.
Example | To execute the script associated with the key label `AP_8`, use:
    call key_script ("AP_8");

# largest_field_number

Description | Return the highest field number of a multi-field.
Syntax |
    let variable = largest_field_number (window, field_name);
or
    if largest_field_number (window, field_name) = expr
where:
`window` | is the name of the window containing the field. It may be an expression that evaluates to a string.
`field_name` | is the name of the field. It may be an expression that evaluates to a string.
Notes | A multi-field is a set of fields having the same name. Such fields are always assigned field numbers (1, 2, etc.). Thus, it is possible to have the fields `"names"@"name"[1]`, `"names"@"name"[2]`, `"names"@"name"[3]`, and so on. This function returns the highest number of a given field. This is the same as the number of distinct fields in the multi-field of that name, which is the same as the number of distinct fields sharing the same name.
Returns | The highest field number.
See Also |
    define_multi
Example | To find the largest field number of the field `"names"@"name"`, use:
    let largest_number = largest_field_number ("names",
    "name");

# let

Description | Assign a value to a variable.
Syntax |
    let variable = |expr|;
                   |null|
where:
`variable` | is one of: `attribute`, `field`, `system variable`, or `variable`.
Notes | Remember that a field is usually cited as `window@field_name` optionally followed by a field number enclosed in square brackets (`[]`). A `window` is the name of a window. A `field_name` is the name of a field. If no field number is given and there is only one field of a given name, it is the one referred to; whereas if there are several fields of the same name, the number of the current field (in the appropriate window) determines the field referred to. If the current field (in the appropriate window) is undefined or no field of the given number exists, field 1 is used. Note that entering any field in a window once is sufficient to define a current field in the window. When control leaves the window the last current field is remembered and is considered the current field for the window (even though the window is no longer current).
Returns | None.
Example | To assign the value of the attribute `nametable.address` to the field `names@address`, use:
    let "names"@"address" = "nametable"."address";
This is equivalent to:
    let "names"@"address"[1] = "nametable"."address";

# local

Description | Declare a variable to be `local`.
Syntax |
    local [type] variable {; [type] variable} [;] end;
where:
`type` | is the data type of the variable.
`variable` | is the name of the variable.
Notes | The named variables are declared to be local to the script and of the given types. See Chapter 1.8 - "Data Types". A `local` variable may have the same name as a global variable created elsewhere. Within the script the `local` is recognized, while outside the script the global variable is recognized. There may be only one `local` statement in a script. It must follow the `parameter`, `external` and `global` statements, if any, and precede all other statements.
Returns | None.
See Also |
    parameter, external, global
Example | To define variables `name` and `age` so that they will be known only in the script use:
    local
       char name;
       integer age;
    end;

# lock

Description | Apply locking to the specified table.
Syntax |
    lock table [in] |exclusive| [mode];
                    |excl     |
                    |share    |
where:
`table` | is the name of the table instance to be locked.
Notes | The `lock` statement locks the table known by the table name. It is only effective during a transaction. A table may be locked in exclusive or share modes. An exclusive lock gives exclusive access to the table. No one else may select from or update the table and no other locks may be placed on it concurrently. A share-mode lock guarantees only that you will be able to select from the table and precludes update operations from others. Several share-mode locks can be placed on a table at one time. If there is more than one share-mode lock on a given table it may not be updated. If you have placed the only share-mode lock on a table you may perform updates on that table. Records so updated will not be accessible to others for the remainder of the transaction. The `lock` command will only have effect if some level of locking has been set for the table using the Empress `LOCK LEVEL` Query Language command.
Returns | None.
Example | To lock the table `nametable` in exclusive mode during a transaction, type:
    lock "nametable" in exclusive mode;

# mouse_field_name

Description | Return the field name of the mouse cursor position.
Syntax |
    let variable = mouse_field_name ();
or
    if mouse_field_name () = expr
where:
`variable` | is the name of the variable.
`expr` | is an expression.
Returns | Null or the mouse cursor position's field name.
Example | To assign the field name of the mouse cursor to a variable `fname`, use:
    let fname = mouse_field_name ();

# mouse_field_number

Description | Return the field number of the mouse cursor position.
Syntax |
    let variable = mouse_field_number ();
or
    if mouse_field_number () = expr
where:
`variable` | is the name of the variable.
`expr` | is an expression.
Returns | Null or the mouse cursor position's field number.
Example | To assign the field number of the mouse cursor to a variable `fnumber`, use:
    let fnumber = mouse_field_number ();

# mouse_key_down

Description | Indicate whether a mouse key is being depressed.
Syntax |
    let variable = mouse_key_down ();
or
    if mouse_key_down () = expr
where:
`variable` | is the name of the variable.
`expr` | is an expression.
Notes | This command must be repeatedly called until it returns 0. The current mouse location is also returned. This command is used to track mouse cursor movement from within an Empress 4GL script. The system global variables `mouse_row` and `mouse_column` are automatically updated.
Returns | One if a mouse key is being depressed, otherwise, zero.
See Also |
Example | To check if the mouse key is being depressed, use:
    if mouse_key_down () = 1 then
       .
       .
       .
    end;

# mouse_location

Description | Determine the current location of the mouse cursor.
Syntax |
    call mouse_location ();
Notes | The system global variables `mouse_row` and `mouse_column` are automatically updated.
Returns | None.
Example | To get to the current mouse cursor location, use:
    call mouse_location () ;

# mouse_window_name

Description | Determine the current window of the mouse cursor.
Syntax |
    let variable = mouse_window_name ();
or
    if mouse_window_name () = expr
where:
`variable` | is the name of the variable.
`expr` | is an expression.
Returns | Null or the window name of the mouse cursor.
Example | To get the window name of the mouse cursor and assign to a variable `wname`, use:
    let wname = mouse_window_name ();

# move_window

Description | Move the given window to a new location.
Syntax |
    call move_window (window, row_amount, col_amount);
where:
`window` | is the name of a window.
`row_amount` | is the number of rows to move from the current position. It may be an expression that evaluates to an integer.
`col_amount` | is the number of columns to move from the current position. It may be an expression that evaluates to an integer.
Notes | This command moves the window by the given amounts relative to its last defined position. It is not an error to execute this statement for a window that is not currently shown. The window's defined position will be adjusted. A window cannot be moved beyond the edges of the screen. The new position of the window is held until it is moved again, or until you quit the application.
Returns | None.
Example | To move the window `names` ten rows down and five columns to the left, use:
    call move_window ("names", 10, -5);

# next_field

Description | Make current the next field in the current window.
Syntax |
    call next_field (['-x']);
Notes | The field definition for the current field is consulted to determine the next field. If no `next_field` is specified in the definition, the physical order of fields is used. Fields are read from left to right and top to bottom of the form. Only one occurrence of this function, the `prev_field` function or the `current_field` function will be effective in a script or series of scripts executed without interruption. The last call to either `next_field`, `prev_field` or `current_field` is the effective call. If the parameter `-x` is used, the exit script of the current field is executed before the next field is made the current field. The following conditions determine which field becomes current in any circumstance. Conditions are listed from highest to lowest priority. The execution of the last `current_field`, `next_field` or `prev_field` function in a script or series of scripts that are executed without interruption. The order of execution of scripts can be ambiguous only when a function key is pressed while a field is current. The convention governing this situation is: first the field's exit script is executed, unless the key script definition has set the disable exit script flag; then the key script is executed. If control returns to the same field, the enter script for the field is not executed; if control is passed to another field, the enter script for that field is executed last. The previous and next fields specified in the field definition. If no field number is specified for the previous or next, the field number is taken to be the same as that of the current field; if such a field does not exist then the field with number 1 is used. The physical order of fields on the form. Fields are read from left to right and top to bottom of the form for the next field, and the reverse for the previous field. The next field is entered only after the script completes.
Returns | None.
See Also |
    current_field, prev_field
Example | To make current the next field in the current window, use:
    call next_field ();

# next_group

Description | Get the next group in a select context.
Syntax |
    next_group context [number];
where:
`context` | is the name of a select context
`number` | is an expression that evaluates to a positive integer
Notes | The context is generated (initialized with records) by a `define select` or a `select` statement. The `next_group` statement effectively initializes each attribute of the table instances forming the context with the values of the attributes for the record made current as the result of the `next_group` command. The next group of records in the `context` will be made the current group. If the optional `expr` is given, it must evaluate to an integer `n` greater than 0, and specifies that the nth group from the current group is to be made current. If the context is manipulated using the `define_group_multi` command, and `next_group` retrieves a next group, the record pointer will advance to the aggregate record for the next group. If `display_page` is then called, the cursor will be positioned on the same row of the multi as it was on for the previous group or the last row of the group if placing the cursor on the same row number would place the cursor on a row with no records. If the context is manipulated using the `define_multi` command, or the context is displayed one record at a time, when `next_group` is called, the aggregate record for the group will be made current if the current record is not an aggregate record. If the current record for a group is an aggregate record, the aggregate record for the next group, if there is one, will be made the current record. When the context is re-displayed using the `display_page` function, the current record will still be the aggregate record. The function `next_group` can be called for any active context. The system variables `got_records` and `record_status` can be checked after a call to `next_group` to determine the result of that call. The following table summarizes the values of `record_status`: Table 2-4
Value | Meaning
-2 | Error
-1 | Record is locked
0 | No next/previous record
1 | Got next/previous record
2 | Beginning of Group (only set with `next_rec` and `next_record`)
3 | Aggregate Record
Returns | None.
See Also |
    select, define select, next_line, prev_line, prev_group,
    define_group_multi
Example | To make the next group from the context `namesakes` the current group, use:
    next_group "namesakes" 1;

# next_line

Description | Move the cursor to the next line of a multiple record display.
Syntax |
    call next_line ();
Notes | The current window must be a window used for multiple record displays; that is, it must have been associated with a context through a `define_multi` function call. The function moves the cursor to the next field that is part of the current multi field; that is, it moves the cursor to the field with the same name and the next field number. The function also makes the next record in the context current. When the function completes, the record the cursor is resting on is the current record. If the cursor is at the bottom of the display (i.e., there is no higher field number for that field), an implicit `next_page` is done. The third argument passed to the `define_multi` function then determines the line on which the next record will appear. If the function obtains the next record, the script to display the record (the fifth argument to `define_multi`) is executed. If the next record is locked the script given as the sixth argument to `define_multi` is executed. If there is no next record in the context a status message is printed in a status box on the top right corner of the screen and the cursor remains where it is.
Returns | None.
See Also |
    define_multi, next_page
Example | Referring back to the context `name_list` and window `names` set up for multiple record displays in the `define_multi` example, if the window `names` is the current window you can put the cursor on the next record of the display by executing:
    call next_line ();

# next_page

Description | This displays the next page of records in a multiple record display. It has the format:
Syntax |
    call next_page ([context]);
where:
`context` | is the name of the context for which the next page of records is to be displayed.
Notes | If `context` is not given, the context associated with the current window is assumed. The `context` must be associated with a window used for multiple record displays; that is, the context and window must have been associated through a `define_multi` function call. The function retrieves the next page of records from the context and displays them in the appropriate window. (The next page is considered to begin with the record after the last record currently displayed.) If that window is the current window, then the record on which the cursor is resting when the function completes is the current record. Normally the cursor position in the window is not changed by this function. If, however, the next page does not contain enough records to reach the current cursor position, the cursor will move to the last record. (The exit and enter scripts of the appropriate fields will be executed.) The function will not adjust pages to fill the last page with data. Fields not filled with data are assigned values as specified in the script passed as the seventh argument to `define_multi`. Unless these fields are explicitly assigned values (possibly null) they will not be refreshed. This function is equivalent to a `scroll_page (N)` function call where `n` is the number of fields in each multi-field (they must all have the same number). As the function displays each record on the page it attempts to obtain it in the context. If it succeeds, the function to display the record (the fifth argument to `define_multi`) is executed. If the record is locked the script given as the lock script (sixth argument to `define_multi`) is executed. When there are no more records in the context the script given as the seventh argument to `define_multi` is executed for each remaining line in the window.
Returns | None.
See Also |
    define_multi, scroll_page
Example | Referring back to the context `name_list` and window `names` set up for multiple record displays in the `define_multi` example, you can display the next page of records in window `names` by executing:
    call next_page ("name_list");

# next_rec

Description | Get the next record in a select context.
Syntax |
    next_rec context [expr];
where:
`context` | is the name of a `select context`.
`expr` | is an expression that evaluates to a positive integer.
Notes | The `context` is generated (initialized with records) by a `select`. The `next_rec` statement effectively initializes each attribute of the table instances forming the context with the values of the next record's attributes. The next record from the `context` becomes current. If the optional expression is given, it must evaluate to an integer greater than 0, and specifies that the nth record from the current position is to be retrieved. The system variable `got_records` can be used to test the result of a `next_rec`. The value of `got_records` as follows:
1 | record obtained successfully
0 | no next record, the current record will not be changed
-1 | record is locked
If the `context` was generated using the `display count` option of the `select`, then each time a `next_rec` gets a new record, the message "`record n of N`" is displayed in a status window at the top left corner of the screen. The message means that the new record is the nth record of a total of `N` in the context.
Returns | None.
See Also |
    select, define, prev_rec
Example | To make the next record from `namesakes` the current record, use:
    next_rec "namesakes" 1;
If `namesakes` was generated from the table instance `nametable` which refers to the table `nametable` with attributes `name`, `address` and `tel`, then the attributes `nametable.name`, `nametable.address`, and `nametable.tel` are initialized.

# next_record

Description | Get the next record in a select context.
Syntax |
    next_record context [expr];
where:
`context` | is the name of a select context.
`expr` | is an expression that evaluates to a positive integer.
Notes | The context is generated (initialized with records) by a `select`. The `next_record` statement effectively initializes each attribute of the table instances forming the context with the values of the next record's attributes. The next record from the `context` becomes current. If the optional `expr` is given, it must evaluate to an integer `n` greater than 0, and specifies that the nth record from the current position is to be retrieved. The system variable `got_records` can be used to test the result of a `next_record`. If the next record was obtained, `got_records` has the value 1. If there was no next record, `got_records` has the value 0; the current record will have changed to the position at the end of the context (i.e., beyond the last record). If the record was locked, `got_records` has the value -1. The system variable `record_status` can also be used to test the result of a `next_record`. It is similar to `got_records` but has different values to provide more information about the position in the context. If the next record was obtained, `record_status` has the value 1. If there was no next record, `record_status` has the value 0; the current record will have changed to the position at the end of the context. If the record was locked, `record_status` has the value -1. If the record retrieved is the first record in a new group, `record_status` has the value 2. This value is only set when a new group becomes current. For example, if the current position in the group is the second record, and `prev_record` is called, `record_status` has the value 1 even though the record is at the beginning of a group. If the record retrieved is an aggregate record, `record_status` has the value 3. If an error is encountered, `record_status` has the value -2. If the `context` was generated using the `display count` option of the `select`, then each time `next_record` gets a new record, the message "`record n of N`" is displayed in a status window at the top right corner of the screen. The message means that the new record is the nth record of a total of N in the context. The functions `next_record` and `next_rec` differ in that when the last record in the context is reached, `next_record` moves the position in the context to the point beyond the end of the context. `next_rec` does not change the position in the context from the last record.
Returns | None.
See Also |
    select, define select, prev_record, next _record,
    next_rec, prev_rec, next_group, prev_group
Example | To make the next record from the context `namesakes` the current record, use:
    next_record "namesakes" 1;
If `namesakes` was generated from the table instance `nametable` which refers to the table `nametable` with attributes `name`, `address`, and `tel`, then the attributes `nametable.name`, `nametable.address`, and `nametable.tel` are initialized.

# on error

Description | Trap errors and determine how the system responds to them.
Syntax |
    on error|call script ()|error_number {, error_number...};
            |default       |
            |ignore        |
            |exit          |
where:
`script` | is the name of a user-defined script containing instructions for handling errors.
`error_numbers` | are numbers Empress uses to identify common error conditions. The notes following give the conditions and their numbers.
`default` | invokes the default action for that error. Generally, Empress will terminate the call sequence and display an error message in the status window.
`ignore` | ignores the error; no action is taken.
`exit` | is the exit command.
Notes | The parameter list for a script called by `on error` may not contain any reference to local variables. The `on error` command will remain in force for any given error until superseded by the next `on error` command. `on error` commands do not, however, carry over from application to application. Errors which occur while another error is being processed are handled in the default manner. `on error` can handle the following conditions: Table 2-4
Error Messages
1001 | no current record
1002 | field value not in range
1003 | table instance `%s' already exists
1004 | table instance `%s' being used
1005 | table instance `%s' does not exist
1006 | select context `%s' already exists
1007 | select context `%s' does not exist
1008 | call application error
1009 | window `%s' cannot be placed at coordinates (%d, %d, %d, %d)
1010 | key label `%s' does not exist
1011 | application `%s' already exists
1012 | application `%s' does not exist
1013 | form `%s' already exists
1014 | form `%s' does not exist
1015 | application `%s' does not exist or has not been compiled
1016 | null value for attribute `%s'
1017 | call `sys_value` error
1018 | field not accessible
1019 | delete invalid on aggregate
1020 | update invalid on aggregate
Table 2-5
Status Messages
2001 | `Insert` Mode
2002 | `Replace` Mode
2003 | record inserted
2004 | record updated
2005 | record deleted
2006 | record%d of %d
2007 | null record - ignored
2008 | null record - deleted
2009 | some records are locked
2010 | no next record
2011 | no previous record
2012 | no records selected
2013 | record unattainable
2014 | aggregate record
2015 | no next group
2016 | no previous group
Table 2-6
Beeps
3001 | no current field
3002 | no next or previous field
3003 | key not defined
Table 2-7
mr Errors
1-n | Any `mr` error can be trapped. See the manual Empress C<+>Language Kernel Level Interface - mr Routines, the header file `mscc.h`, for a list of errors and their identification numbers.
Returns | None.
Example | If form does not exist then execute the `actions` script.
    on error call actions () 1014;

# on interrupt

Description | Trap system interrupt signals.
Syntax |
    on interrupt |call script ()| signal_no.{, signal_no....}
                 |break         |
                 |exit          |
where:
`script` | is the name of a user-defined script containing instructions for handling interrupts.
`signal_no.` | is the identifying number of a signal generated by UNIX. See The UNIX Programmer's Manual for a list of possible signals and their numbers.
`break` | generates a breakpoint, if the debugger is active.
`exit` | is the exit command.
Notes | `on interrupt` can be disabled for a signal or range of signals with the command:
       disable interrupt signal_no.{, signal_no....}
It may then be reactivated by
       enable interrupt signal_no.{, signal_no....}
Returns | None.
See Also |
    disable interrupt, enable interrupt
Example | To exit Empress 4GL when the interrupt signal is generated from the keyboard, use:
    on interrupt exit 2;

# open

Description | Open database tables for access.
Syntax |
`OPEN table_name` | `|READ |UPDATE |DEFERRED |BYPASS_LOCK` | `| [AS tabinst {, tabinst}] | | |`
where:
`table` | is the name of an Empress table.
`tabinst` | are the "instance names" by which the `table` is to be known and referenced.
Notes | The `table` may be specified using `database:table` where `database` is the database containing the table and `table` is the name of the table in the database. The `database` may be other than the current user database. `tabinst`s is the only name by which any tables are known in the application. If no `tabinst` is specified, the value of `table` is taken as the "instance name". Tables may be opened in one of several modes. If a table is opened in `read` mode no update type operations can be done on it. With record level locking defined for the table, a read lock is in effect for each record while it is current. If a table is opened in `update` mode records may be inserted, updated and deleted from it. With record level locking defined for the table an update lock (i.e., exclusive access lock) is in effect for each record while it is current. If a table is opened in `deferred` mode records may also be inserted, updated and deleted from it. However, if locking for the table is set at the record level only a read lock is placed on each record when it becomes current. The read lock is exchanged for an update lock only when an update type operation occurs. The update lock lasts for the duration of the update type operation, then it is replaced with a read lock again. The read lock is removed when the record is no longer current. Opening a table in `deferred` mode thus keeps the table in a shareable state more of the time (given record level locking on the table). Locking levels are described in the Empress SQL Reference under the "LOCK LEVEL" command. Update type operations on a table via any instance name affect the records accessed through all the instance names. The Empress variables `MSIAEXCLRETRY`, `MSIAEXCLSLEEP`, `MSIALOCKRETRY` and `MSIALOCKSLEEP` are used when attempting to place locks on a table. The time required to open a large number of tables in the same database can be reduced if the `open`s are issued consecutively in a script.
Returns | None.
Example | To open the table `nametable` in update mode, use:
    open "nametable" update;
The table instance name becomes `nametable` by default since no `tabinst` was specified. On the other hand:
    open "nametable" update as "exampletable";
opens the table to the name `exampletable`. Any references to this table will then be to `exampletable`. For instance, the attribute `name` of the Empress table `nametable` would be known in the application as `"exampletable"."name"`.

# parameter

Description | Declare variables to pass to a script.
Syntax |
    parameters [type] variable {; [type] variable} [;] end;
where:
`type` | is the data type of the variable.
`variable` | is the name of the variable.
Notes | Parameters are values that are passed to a script when that script is run. The values are stored in the named `variable` and must be of the given `types`. See Chapter 1.8 - "Data Types". If the `type` is not specified it is assumed to be `CHAR`. A `variable` is a sequence of letters, digits and underscores, starting with a letter. A `variable` defined as a `parameter` is known only in the script where it is so defined, except `parameters` defined in the application enter script. Application enter script `parameters` are `global`. Parameters are initialized when the script is invoked with arguments. The parameters assume the values of the arguments. Empress 4GL reports an error if a script is invoked with a different number of arguments than the number of parameters defined in it. There can be only one `parameter` statement in a script and it must precede all other statements.
Returns | None.
Example | Suppose you have a script `ages` which begins by defining parameters `name` and `age`:
    parameters
       char name;
       integer age;
    end;
You could then execute the statement:
    call ages ("John", 30);
The `ages` script would be invoked, the `name` parameter would have the value `john`, and the `age` parameter the value "30".

# pop_key_context

Description | Remove the key context on the top of the key context stack for a window.
Syntax |
    call pop_key_context ([window]);
where:
`window` | is the name of a window. It may be an expression that evaluates to a string.
Notes | If the window name is not supplied, the current window is assumed. Each window has a stack of key contexts associated with it. A key context becomes associated with a window either through the window definition (refer to the chapter on "The Application Manager" in the Empress 4GL Tools Reference) or through the `push_key_context` function. The key contexts associated with a window determine the key labels and scripts that are active when the window is current. Key contexts higher in the stack override key contexts lower in the stack. The key context on the top of the stack is guaranteed to define active keys in the window. Key contexts below the top of the stack may define active keys in the window, depending on the key labels used; key labels not used in key contexts higher in the stack will define active keys in the window. This function removes the key context on the top of the stack for the window. Key contexts cannot be removed from the middle of the stack. The effects of pushing and popping key contexts endures through separate invocations of a window as the current window.
Returns | None.
See Also |
    push_key_context
Example | To remove the key context on the top of the stack for the `names` window, type:
    call pop_key_context ("names");

# prev_field

Description | Make the previous field current in the current window.
Syntax |
    call prev_field (['-x']);
Notes | The definition for the current field is consulted to determine the previous field. If no previous field is specified in the definition, the physical order of fields is used. Fields are read from right to left and bottom to top of the form. Only one occurrence of this function, the `next_field` function or the `current_field` function will be effective in a script or series of scripts executed without interruption. The last call to either `prev_field`, `next_field` or `current_field` is the effective call. If the parameter `-x` is used, the exit script of the current field is executed before the previous field is made the current field. The following conditions determine which field becomes current in any circumstance. They are listed from highest to lowest priority. The execution of the last `current_field`, `next_field` or `prev_field` function in a script or series of scripts that are executed without interruption. The order of execution of scripts can be ambiguous only when a function key is pressed while a field is current. The convention governing this situation is: first the field's exit script is executed, unless the key script definition has set the disable exit script flag; then the key script is executed. If control returns to the same field, the enter script for the field is not executed; if control is passed to another field, the enter script for that field is executed last. The previous and next fields specified in the field definition. If no field number is specified for the previous or next, the field number is taken to be the same as that of the current field; if such a field does not exist then the field with number 1 is used. The physical order of fields on the form. Fields are read from left to right and top to bottom of the form for the next field, and the reverse for the previous field. The previous field is entered only after the script completes.
Returns | None.
See Also |
    next_field, current_field
Example | To make the previous field current in the current window, use:
    call prev_field ();

# prev_group

Description | Get the previous group in a select context.
Syntax |
    prev_group context [number];
where:
`context` | is the name of a select context.
`number` | is an expression that evaluates to a positive integer.
Notes | The context is generated (initialized with records) by a `define select` or a `select` statement. The `prev_group` statement effectively initializes each attribute of the table instances forming the context with the values of the attributes for the record made current as the result of the `prev_group` command. The previous group of records in the `context` will be made the current group. If the optional `expr` is given, it must evaluate to an integer `n` greater than 0, and specifies that the nth previous group from the current group is to be made current. If the context is manipulated using the `define_group_multi` command, and `prev_group` retrieves a previous group, the record pointer will move back to the aggregate record for the previous group. If `display_page` is then called, the cursor will be positioned on the same row of the multi as it was on for the previous group or the last row of the group if placing the cursor on the same row number would place the cursor on a row with no records. If the context is manipulated using the `define_multi` command, or the context is displayed one record at a time, when `prev_group` is called, the aggregate record for the group will be made current if the current record is not an aggregate record. If the current record for a group is an aggregate record, the aggregate record for the previous group, if there is one, will be made the current record. When the context is re-displayed using the `display_page` function, the current record will still be the aggregate record. The function `prev_group` can be called for any active context. The system variables `got_records` and `record_status` can be checked after a call to `prev_group` to determine the result of that call. The following table summarizes the values of `record_status`: Table 2-8
Value | Meaning
-2 | Error
-1 | Record is locked
0 | No next/previous record
1 | Got next/previous record
2 | Beginning of Group (only set with `next_rec` and `next_record`)
3 | Aggregate Record
Returns | None.
See Also |
    select, define select, next_line, prev_line, next_group,
    define_group_multi
Example | To make the previous group from the context `namesakes` the current group, use:
    prev_group "namesakes" 1;

# prev_line

Description | Move the cursor to the previous line of a multiple record display.
Syntax |
    call prev_line ();
Notes | The current window must be a window used for multiple record displays; that is, it must have been associated with a context through a `define_multi` function call. The function moves the cursor to the previous field that is part of the current multi-field; that is, it moves the cursor to the field with the same name and the previous field number. The function also makes the previous record in the context current. When the function completes, the record the cursor is resting on is the current record. If the cursor is at the top of the display (i.e., there is no lower field number for that field), an implicit `prev_page` is done. The fourth argument passed to the `define_multi` function then determines the line on which the previous record will appear. If the function obtains the previous record the script to display the record (the fifth argument to `define_multi`) is executed. If the previous record is locked the script given as the sixth argument to `define_multi` is executed. If there is no previous record in the context a status message is printed in a status box on the top right corner of the screen and the cursor remains where it is.
Returns | None.
See Also |
    define_multi, prev_page
Example | Referring back to the context `name_list` and window `names` set up for multiple record displays in the `define_multi` example, if the window `names` is the current window you can put the cursor on the previous record of the display by executing:
    call prev_line ();

# prev_page

Description | Display the previous page of records in a multiple record display.
Syntax |
    call prev_page ([context]);
where:
`context` | is the name of the context for which the previous page of records is to be displayed.
Notes | If `context` is not given, the context associated with the current window is assumed. The `context` must be associated with a window used for multiple record displays; that is, the context and window must have been associated through a `define_multi` function call. The function retrieves the previous page of records from the context and displays them in the appropriate window. (The previous page is considered to end with the record before the first record currently displayed.) If that window is the current window, then the record on which the cursor is resting when the function completes is the current record. The cursor position in the window is not changed by this function. The function will adjust the first page to start on the first line of the display. Fields not filled with data are assigned values as specified in the script passed as the seventh argument to `define_multi`. Unless these fields are assigned values (possibly null) they will not be refreshed. This function is equivalent to a `scroll_page (-n)` function call where `n` is the number of fields in each multi-field. (They must all have the same number.) As the function displays each record on the page, it attempts to obtain it in the context. If it succeeds, the function to display the record (the fifth argument to `define_multi`) is executed. If the record is locked the script given as the sixth argument to `define_multi` is executed. When there are no more records in the context the script given as the seventh argument to `define_multi` is executed for each remaining line in the window.
Returns | 0 if there is no previous page and 1 otherwise.
See Also |
    define_multi, scroll_page
Example | Referring back to the context `name_list` and window `names` set up for multiple record displays in the `define_multi` example, you can display the previous page of records in window `names` by executing:
    call prev_page ("name_list");

# prev_rec

Description | Get the previous record in a select context.
Syntax |
    prev_rec context [expr];
where:
`context` | is the name of a select context.
`expr` | is an expression that evaluates to a positive integer.
Notes | The context may have been generated (initialized with records) by a `select` statement. The `prev_rec` statement effectively initializes each attribute of the table instance forming the context with the values of the previous record's attributes. The previous record from the `context` becomes current. Each attribute associated with the `context` is initialized. If the optional expression is given, it must evaluate to an integer n greater than 0, specifying that the nth previous record from the current position is to be retrieved. The system variable `got_records` can be used to test the result of a `prev_rec` statement. The value of `got_records` is as follows:
1 | record obtained successfully
0 | no next record, the current record will not be changed
-1 | record is locked
If the `context` was generated using the `display count` option of the `select` statement, then each time a `next_rec` statement gets a new record, the message `record n of N` is displayed in a status window at the top left corner of the screen. The message means that the new record is the nth record of a total of `N` in the context.
Returns | None.
See Also |
    select, define, next_rec
Example | To make the previous record from `namesakes` the current record, use:
    prev_rec "namesakes";

# prev_record

Description | Get the previous record in a select context.
Syntax |
    prev_record context [expr];
where:
`context` | is the name of a select context.
`expr` | is an expression that evaluates to a positive integer.
Notes | The context is generated (initialized with records) by a `select`. The `prev_record` statement effectively initializes each attribute of the table instances forming the context with the values of the previous record's attributes. The previous record from the `context` becomes current. If the optional `expr` is given, it must evaluate to an integer `n` greater than 0, and specifies that the nth previous record from the current position is to be retrieved. The system variable `got_records` can be used to test the result of a `prev_record`. If the previous record was obtained, `got_records` has the value 1. If there was no previous record, `got_records` has the value 0; the current record will have changed to the position at the beginning of the context (i.e., before the first record). If the record was locked, `got_records` has the value -1. The system variable `record_status` can also be used to test the result of a `prev_record`. It is similar to `got_records` but has different values to provide more information about the position in the context. If the previous record was obtained, `record_status` has the value 1. If there was no previous record, `record_status` has the value 0; the current record will have changed to the position at the beginning of the context. If the record was locked, `record_status` has the value -1. If the current position in the group is the second record, and `prev_record` is called, the value of `record_status` will not change to 2 to indicate the beginning of a group; `record_status` will only be set to 2 to indicate the beginning of a group if `next_record` makes the first record of a group the current record. If the record retrieved is an aggregate record, `record_status` has the value 3. If an error is encountered, `record_status` has the value -2. If the `context` was generated using the `display count` option of the `select`, then each time `prev_record` gets a new record, the message "`record n of N`" is displayed in a status window at the top right corner of the screen. The message means that the new record is the nth record of a total of `N` in the context. The functions `prev_record` and `prev_rec` differ in that when the first record in the context is reached, `prev_record` moves the position in the context to the point before the start of the context. `prev_rec` does not change the position in the context from the first record.
Returns | None.
See Also |
    select, define select, next_record, next_rec, prev_rec,
    next_group, prev_group
Example | To make the previous record from the context `namesakes` the current record, use:
    prev_record "namesakes" 1;
If `namesakes` was generated from the table instance `nametable` which refers to the table `nametable` with attributes `name`, `address`, and `tel`, then the attributes `nametable.name`, `nametable.address`, and `nametable.tel` are initialized.

# print_screen

Description | Print the current screen.
Syntax |
    call print_screen ([out_file]);
where:
`out_file` | is the file to which the screen contents will be printed.
Notes | If the first character of `out_file` is `!`, the remainder of `out_file` is taken as a UNIX command. So, `out_file` is commonly `'!lpr'` to direct output to the line printer spooler. Special values are: Table 2-10
out_file | Output Directed To
"`!`" | UNIX command
"`printer`" | `MSPRINTER`
If `out_file` is not specified, the output is directed to a file specified by `MS4GLPRINTSCREEN`. By default this file is called `screen`. `print_screen` output can be generated in either ASCII or Postscript format by assigning `a` or `p` respectively to the Empress variable `MS4GLPRINTSCREENFORMAT`. If Postscript output is selected then the Empress variables `MS4GLPSWIDTH` and `MS4GLPSHEIGHT` are used to set the width and height of the characters. The Empress variable `MS4GLHEADER` is used to specify a file containing Postscript header information. If `print_screen` is called repeatedly in the application, the screen contents will be appended to the `out_file`.
Returns | None.
Example | To print the current screen into a file named `screen`, use:
    call print_screen ("screen")

# push_key_context

Description | Push a key context onto the top of the key context stack for a window.
Syntax |
    call push_key_context ([window, ] key_context);
where:
`window` | is the name of a window. It may be an expression that evaluates to a string.
`key_context` | is the name of the key context.
Notes | If `window` is not supplied, the current window is assumed. Each window has a stack of key contexts associated with it. A key context becomes associated with a window either through the window definition or through the `push_key_context` function. The key contexts associated with a window determine the key labels and scripts that are active when the window is current. Key contexts higher in the stack override key contexts lower in the stack. The key context on the top of the stack is guaranteed to define active keys in the window. Key contexts below the top of the stack may define active keys in the window, depending on the key labels used; key labels not used in key contexts higher in the stack will define active keys in the window. This function pushes the key context on top of the stack for the window. To remove the key context on the top of the stack for a window, see the `pop_key_context` function. The effects of pushing and popping key contexts endures through separate invocations of a window as the current window.
Returns | None.
See Also |
    pop_key_context, push_key_context
Example | To push key context `names_keys` onto the stack for window `names`:
    call push_key_context ("names", "names_keys");

# remove_window

Description | Remove the given window from the screen.
Syntax |
    call remove_window (window);
where:
`window` | is the name of a window.
Notes | It is not an error to remove a window that is not currently shown.
Returns | None.
Example | To remove the window `names` from the screen, use:
    call remove_window ("names");

# reset_fields

Description | Reset fields to their default values.
Syntax |
    call reset_fields ([window [, field_name
         [, field_number]]]);
where:
`window` | is the name of the window containing the field or fields to be reset. The routine defaults to the current window.
`field_name` | is the name of the field to be reset. The routine resets all fields in the given window by default.
`field_number` | is the number of the field to be reset. The routine resets all fields with the given name by default.
Notes | Default values are set by entering the default value in the `default value` field of the `field` table.
Returns | None.
Example | To reset the field `name` in the window `names` to the default, use:
    call reset_fields ("names", "name");

# reset_key_context

Description | Reset the key context stack.
Syntax |
    call reset_key_context ([window]);
where:
`window` | is the name of the window associated with the key context stack. The routine defaults to the current window.
Notes | Key context stacks are defined in the Script Editor. Local key context stacks are defined through the window table. Global key context stacks, which cannot be modified, are defined through the application table.
Returns | None.
See Also |
    push_key_context, pop_key_context
Example | To reset the key context stack for the window `names`, use:
    call reset_key_context ("names");

# restore_field

Description | This sets fields to their saved field values.
Syntax |
    call restore_field (window [, field_name
         [, field_number]]);
where:
`window` | is the name of the window containing the field or fields to be reset. The routine defaults to the current window.
`field_name` | is the name of the field to be reset. The routine resets all fields in the given window by default.
`field_number` | is the number of the field to be reset. The routine resets all fields with the given name by default.
Notes | The keyword `NULL` may be used in place of `window`. The routine will assume the current window. The keyword `NULL` may be used in place of field_name. The routine will assume the current field. The `field_name` may be omitted. The routine will set every field in the window. The `field_number` may be omitted. The routine will assume the current field number. A saved field value is stored as data type `CHAR`, regardless of the data type of its associated field. Null field values and null saved field values are ignored in saved field commands. A null field value is neither saved to the save name nor restored to the field.
Returns | None.
Example | To set the field `name` in the window `names` to the saved value, use:
    call restore_field ("names", "name");

# return

Description | Cause an immediate return from a script.
Syntax |
    return [expr];
where:
`expr` | is a value to be returned.
Notes | Control returns to the script that invoked the script with the `return` statement.
Returns | None.
Example | A script that computes a value called `result` could return the result with the statement:
    return result;
If the script is named `calculation`, and accepts two arguments, then it would be invoked as in:
    let store_result = calculation (argument1, argument2);
Here, the arguments are the contents of `argument1` and `argument2`, and the returned result is stored in the variable `store_result`.

# rollback

Description | Roll back a transaction.
Syntax |
    |rollback| [transaction] [to savepoint];
    |cancel  |
Notes | This rolls back a transaction. A `savepoint` (given as a string starting with a letter) may be specified to roll back to the start of that nested transaction. If no `savepoint` is specified, the entire transaction is rolled back. A transaction is started with a `start transaction`. A save point is set with a `savepoint` statement. All database operations subsequent to the start of the transaction (or the save point) are rolled back. If no transaction is in progress, an error message is printed in a status box on the top right corner of the screen. To commit a transaction, see `commit`.
Returns | None.
See Also |
    commit, savepoint, start transaction
Example | The following group of statements rolls back the transaction to the save point `t1`.
    start transaction;
    ...
    savepoint t1;
    ...
    rollback transaction to t1;
This returns the database(s) to the state immediately following the setting of the save point.

# save_field

Description | Set the saved field value to the current value of the field.
Syntax |
    call save_field (window [,field_name [, field_number]])
where:
`window` | is the name of the window containing the field or fields to be reset. The routine defaults to the current window.
`field_name` | is the name of the field to be reset. The routine resets all fields in the given window by default.
`field_number` | is the number of the field to be reset. The routine resets all fields with the given name by default.
Notes | The keyword `NULL` may be used in place of `window`. The routine will assume the current window. The keyword `NULL` may be used in place of `field_name`. The routine will assume the current field. The `field_name` may be omitted. The routine will set every field in the window. The `field_number` may be omitted. The routine will assume the current field number. A saved field value is stored as data type `CHAR`, regardless of the data type of its associated field. Null field values and null saved field values are ignored in saved field commands. A null field value is neither saved to the associated save name, nor restored to the associated field.
Returns | None.
Example | To save the current value of the field `name` in the `names` window, use:
    call save_field ("names", "name");

# savepoint

Description | Set a save point in a transaction.
Syntax |
    savepoint savepoint;
where:
`savepoint` | is a name of savepoint given by user, it is a string starting with a letter.
Notes | A transaction must be in progress for the statement to succeed. A save point is marked in the transaction, starting a nested transaction. A `rollback transaction to savepoint` statement can be used to rollback the transaction to any defined save point. A commit transaction statement will commit the entire transaction. If the application ends before the transaction is explicitly committed or rolled back, it is committed by default.
Returns | None.
See Also |
    start transaction, commit, rollback
Example | The following sequence starts a transaction, sets a save point, then rolls back. The operations up to the save point are then committed.
    start transaction;
    ...
    savepoint t1;
    ...
    rollback transaction to t1;
    commit transaction;

# scroll_page

Description | Scroll the records in a multiple record window and display a new page.
Syntax |
    call scroll_page ([context, ] number_records);
where:
`context` | is the context whose records are to be displayed.
`number_records` | is the number of records to scroll before displaying the page.
Notes | If no `context` is given it defaults to the context associated with the current window. The `number_records` may be an expression that evaluates to an integer and cannot be larger than the number of lines on the page. A positive number scrolls the page forward in the context and a negative number scrolls the page backward in the context. If `number_records` is zero this function is equivalent to a `display_page`. The `context` must be associated with a window used for multiple record displays; that is, the context and window must have been associated through a `define_multi` function call. The function scrolls the current page of records in the context and displays a new page in the appropriate window. If that window is the current window, then the record on which the cursor is resting when the function completes is the current record. Normally the cursor position in the window is not changed by this function. If, however, the new page does not contain enough records to reach the current cursor position, the cursor will move to the last record. (The exit and enter scripts for the appropriate fields will be executed.) The function will adjust the first page to begin on the first line of the display, but it will not adjust the last page to fill it with data. Either this function or the `display_page` function should be executed after any insert, update, or delete is done on the context. This guarantees that the display reflects the current state of the context. As the function displays each record on the page it attempts to obtain it in the context. If it succeeds, the function to display the record (the fifth argument to `define_multi`) is executed. If the record is locked the script given as the sixth argument to `define_multi` is executed. When there are no more records in the context the script given as the seventh argument to `define_multi` is executed for each remaining line in the window. If there are no records to display a status message is printed in the status box on the top right corner of the screen.
Returns | 0 if it fails (because there are not enough records in the context for the scroll) and 1 if it succeeds.
See Also |
    define_multi, display_page
Example | Referring to the example for the `define_multi` function, to scroll the current page of records of context `name_list` in the window `names` by five records, use:
    call scroll_page ("name_list", 5);
To scroll the same context by the number of `lines` on the display less one, use:
    call scroll_page ("name_list",
         (largest_field_number ("names", "name") - 1));

# scroll_window

Description | Scroll the window over its associated form to the new location specified by the given relative amounts (which may be positive or negative).
Syntax |
    call scroll_window (window, row_amount, col_amount);
where:
`window` | is the name of a window.
`row_amount` | is the number of rows to move with respect to the current row.
`col_amount` | is the number of columns to move with respect to the current column.
Notes | The window does not move relative to the screen. It moves relative to the form. The effect is one of scrolling the form under the window. It is an error to scroll a window that is not currently shown. The `row_amount` and `col_amount` may be expression that evaluate to integers.
Returns | None.
Example | To scroll the window `names` over its form, use:
    call scroll_window ("names", 1, 0);

# select

Description | Select a group of records.
Syntax |
    select[|distinct|][|*                          |]
           |all     |  |select_item {, select_item}|
    from tabinst[[alias]aliasname]{,tabinst[[alias]aliasname]}
    [where_bool]
    [group by attr {, attr}]
    [having_clause]
    [sort_clause]
    [with[display]count]
    [becomes[context]context];
where:
`context` | is the context name by which the `select context` will be known.
Notes | The `select` statement defines and generates a group of selected records called a context. Operations on the group of records can then be done by referring to the context. If no `context` is specified in the `select` statement, the "table instance" name refers to the context. A `context` must be specified for a multi-table selection. The `select` establishes a `context` but does not establish a current record for the `context`. This must be done with a `next_rec` statement. If sorting is specified, sorting is done with the given attributes in ascending order as the default. For a descending sort, place `descending` after the appropriate attributes. Remember that attribute is of the form `tabinst.attr` where `attr` is the attribute name exactly as it is in the table. The keywords `asc` and `desc` can be used in place of `ascending` and `descending` respectively. If sorting is specified, and the variable `MSSORTBYPASS` is set, locked records will not be included in the `select context`. A "table instance" can only support one `context`. If a different `select` is required from a table, either the existing `context` must be removed with the `end_select` statement, or the table must be opened to another instance name. The `where_bool` conditions evaluate in the same way that Empress `WHERE` clauses do (as described in the Empress SQL Reference). An expression will be eliminated from the `WHERE` clause only if a null variable or a null field appears alone on the right side of a comparison operator opposite an attribute. Pattern matching as in the Query Language is supported. A table of matched patterns is presented under the `if` statement earlier in this chapter. The `where_bool` conditions specifying ranges (using `range` or `between`) get inclusive ranges by default, i.e., the range boundary is included in the range. Specifying the optional `excl` excludes the range boundary from the range. An expression in a `where_bool` condition may not refer to a `tabinst` unless that `tabinst` is part of a join in the `select` statement. This restriction preserves consistency with the Query Language `select` command: if `tabinst`s external to the `select` were allowed to represent constants within the `select`, syntax would have to be introduced to distinguish the use of constants from a join condition this would result in syntax different from that of the Query Language `select` command. To use an attribute value in a comparison, assign the `tabinst.attr` value to a `variable` and use the `variable`. Where the `where_bool` is of the form:
      expr field expr
the field must contain one of the comparison operators (`match`, etc.) Note that though a `field` is acceptable, no other kind of `variable` may be used. If the `count` option is used, the system variable `records_selected` is set to the number of records selected by the `select`. If it is not used the variable is not set. If the number of records is indeterminate (due to some records being locked), the variable is set to -1. Use of the count option exacts a performance penalty. Selects using `count` will be slower than selects that do not use `count`. If the `display` option is used with `count`, the message `record n of N` shows the position of the current record in the context every time a new record is made current with the `next_rec` or `prev_rec` statements. The message is displayed in a window in the top right corner of the screen. If, however, the context is used in a multiple record display (i.e., named in a `define_multi` function), the record count display is disabled for the context. To define a `context` without doing a `select` see `define select`. Aggregate values and expressions can only be accessed through the context. The aggregate or expression can be referred to as:
      "context"."expression_#"
where "`#`" is the number of the expression in the select list. The first aggregate or expression will be `expression_1`, and subsequent aggregates/expressions can be referred to as `expression_2`, `expression_3`, etc. The aggregate or expression can be referred to as:
      "context"."print_item"
if the optional `PRINT` clause has been used with the select item. The aggregate or expression can be referred to as:
      "context"."integer_variable"
where the `integer_variable` is the item number or positional indicator in the select list. For the example given above:
      select a, b, sum (c) print 'TOTAL'
      from TABLE_1 alias T1
      group by a
      becomes context t1_cont
      with display count;
The aggregate `sum(c)` can therefore be referenced as:
a) | "`t1_cont".expression_1` or "`t1_cont`"."`expression_1`"
b) | "`t1_cont`".`total` or "`t1_cont`"."`total`"
c) | "`t1_cont`".`i` | The integer variable "`i`" must first be declared, and it must be assigned the number of the select item to be referenced.
The following is an example of the 4GL code to access an expression or aggregate with a positional indicator.
      local
        integer i;
      end;
      let i = 3;
      let "window"@"field" = "t1_cont".i;
Returns | None.
Example | The statement:
    select from "nametable"
         where "nametable"."name" = "names"@"name";
establishes a `context` of selected records. The `context` takes the name `nametable` by default. On the other hand:
    select from "nametable"
    where "nametable"."name" = "names"@"name"
    becomes context "namesakes";
establishes a `context` containing exactly the same records, but with the name `namesakes`.

# select context

Description | Select a group of records from a previously defined select.
Syntax |
    select context context_name;
where:
`context_name` | is the name of a context established by a `select` statement or defined by `define select`.
Notes | The `context` is generated by initializing or re-initializing it with records.
Returns | None.
See Also |
    select, define select
Example | Given the `define` command:
    define select from "nametable"
    where "nametable"."name" = "names"@"name"
    as context "namesakes";
You can initialize the context with records with:
    select "namesakes";

# set_attr_values

Description | Assign attribute values from fields of the same name.
Syntax |
    call set_attr_values (|window|, |context|, [field_number]);
                          |NULL  |  |NULL   |
where:
`window` | is the name of the window for which fields will be referenced.
`context` | is the name of the context for which attributes will be assigned values.
`field_number` | is an optional specification for the field number of the fields to be used.
Notes | If `window` is null (the keyword `NULL` may be used) the window defaults to the current window. If `context` is null (the keyword `NULL` may be used) the context name defaults to the window name. If `field_number` is specified then all fields with that field number will be used. If `field_number` is not specified, and there is only one field of a given name, its value is used; whereas if there are several fields of the same name, then the field number of the current field (in that window) is used for all fields. If the current field is undefined or a field using the current field's number does not exist, the field with field number 1 is used. Note that entering any field in a window once is sufficient to define a current field in the window. When control leaves the window, the last current field is remembered and is considered the current field for the window (even though the window is no longer current). This function takes a value associated with each field name and assigns it to the attribute(s), if any, with the same name. All attributes of the same name are assigned the same value. It provides a compact way of transferring values from fields to attributes with the same name.
Returns | None.
Example | Referring to the example given for the `define_multi` function, suppose we wished to update the record represented by the current line of the multiple record display. We could call a script to assign the field values of the current line of the multiple record display to the attributes of the `name_list` context. The script could contain the single statement:
    call set_attr_values ("names", "name_list");
This statement is effective because each field has the same name as the attribute whose values it is intended to display. It is equivalent to, yet more compact than, the series:
    let "nametable"."name" = "names"@"name";
    let "nametable"."address" = "names"@"address";
    let "nametable"."tel" = "names"@"tel";

# set_field_values

Description | Assign field values from attributes of the same name.
Syntax |
    call set_field_values ( window, context
        [, field_number [, override]]);
where:
`window` | is the name of the window whose fields will be assigned values.
`context` | is the name of the context whose attributes will be referenced.
`field_number` | is an optional specification for the field number of the fields to be assigned values.
`override` | is a value that will be assigned to the fields if it is specified.
Notes | If `window` is null (the keyword `NULL` may be used) the window defaults to the current window. If `context` is null (the keyword `NULL` may be used) the context name defaults to the window name. If `field_number` is specified then only fields with that field number will be assigned. If `field_number` is not specified, and there is only one field of a given name, then it is assigned to that field. If there are several fields of the same name, then the field number of the current field in that window is used to determine the fields to be assigned. If the current field is undefined or a field using the current field's number does not exist, then the field with field number 1 is used. Note that entering any field in a window once is sufficient to define a current field in the window. When control leaves the window, the last current field is remembered and is considered the current field for the window (even though the window is no longer current). The `override` overrides the assignment from attribute values. A `field_number` must be specified to use `override`. To `override` fields with the same number as the current field, specify a `field_number` of 0. This function takes the value associated with each attribute name in the current record and assigns it to the appropriate field, if any, with the same name. It provides a compact way of transferring values from attributes to fields with the same name. If there is more than one attribute of the same name and they have different values, then the value assigned to the corresponding field cannot be reliably determined.
Returns | None.
Example | Referring to the example given for `define_multi`, the script `display_script` is used to assign field values to each line of the multiple record display. The script is executed for each line in the window. During each execution each line of fields is assigned values from the corresponding record. The script `display_script` is:
    call set_field_values ("names", "name_list");
This script is effective because each field has the same name as the attribute whose values it is intended to display. `set_field_values` is equivalent to, yet more compact than, the series of `let` statements shown next:
    let "names"@"name" = "nametable"."name";
    let "names"@"address" = "nametable"."address";
    let "names"@"tel" = "nametable"."tel";
Similarly, the script `fill_script`, used to fill lines that display no record, can clear each line with:
    call set_field_values ("names", "name_list", 0, null);

# set_key_values

Description | Assign values to fields named after key labels. The value assigned to each field is the result of applying the `key_name` function to the name of the field.
Syntax |
    call set_key_values (window [, field_number]);
where:
`window` | is the name of the window whose fields are to be assigned values.
`field_number` | the field number of the fields to be assigned values.
Notes | If `window` is null (the keyword `NULL` may be used) it defaults to the current window. If the `field_number` is specified, then only fields with that field number will be assigned. If the `field_number` is not specified and there is only one field of a given name, the field number is 1 and it is assigned. If there are several fields of the same name, then the field number of the current field in the form is used to determine the field number to be used. If there is no current field in the form or the field number is out of range, then number 1 is used. Note that entering any field in a window once is sufficient to define a current field in the window. When control leaves the window the last current field is remembered and is considered the current field for the window (even though the window is no longer current). This function applies the `key_name` function to the name of each field in the window, and assigns the result to the field. It provides an easy way of filling function key menus. See the description of the function `key_name` for a discussion of key labels.
Returns | None.
Example | Suppose we have a window `menu` used to display a function menu, and that the fields in the window are named after key labels (by default `AP_1`, `AP_2`, ..., `AP_10`). To display the keys on the keyboard that correspond to these labels, we can use:
    call set_key_values ("menu");
This is equivalent to, yet more compact than, the series:
    let "menu"@"AP_1" = key_name ("AP_1");
    let "menu"@"AP_2" = key_name ("AP_2");
    let "menu"@"AP_10" = key_name ("AP_10");

# set_save_value

Description | Set the saved field value to the specified value.
Syntax |
    call set_save_value (window [, field
         [, field_number}},value);
where:
`window` | is the name of the window containing the field or fields to be used. The routine defaults to the current window.
`field` | is the name of the field to be used. The routine resets all fields in the given window by default.
`field_number` | is the number of the field to be operated upon. The routine resets all fields with the given name by default.
`value` | is the value to be saved for the field.
Notes | The keyword `NULL` may be used in place of `window`. The routine will assume the current window. The keyword `NULL` may be used in place of `field_name`. The routine will assume the current field. The `field_name` may be omitted. The routine will set values for every field in the window. The `field_number` may be omitted. The routine will assume the current field number. A saved field value is stored as data type `CHAR`, regardless of the data type of its associated field. Null field values and null saved field values are ignored in saved field commands. A null field value is neither saved to the associated save name, nor restored to the associated field.
Returns | None.
Example | To save the current value of the field `name` in the `names` window, use:
    call set_save_value ("names", "name", null);

# show_window

Description | Show the given window on the screen. The window is guaranteed not to be covered in any way by any other window.
Syntax |
    call show_window (window);
where:
`window` | is the name of a window.
Notes | Showing a window does not make it current. It is not an error to show a window that is already shown.
Returns | None.
Example | To show the window `names`, use:
    call show_window ("names");

# start transaction

Description | Start a transaction.
Syntax |
    start transaction;
Notes | A transaction is started. Any database operation on any database subsequent to this statement is part of the transaction until the transaction is either committed or rolled back. If a transaction is already in progress, a `savepoint` can be used to roll back to later. To commit a transaction, see `commit`. To roll back a transaction, see `rollback`. If the application ends before the transaction is explicitly committed or cancelled, it is committed by default. When one application is called by another, the transaction in the called application can be started and ended without affecting the calling application.
Returns | None.
See Also |
    commit, rollback, savepoint
Example | The following sequence starts a transaction, then sets a savepoint which is later rolled back. The operations up to the save point are then committed.
    start transaction;
    ...
    savepoint t1;
    ...
    rollback transaction to t1;
    commit transaction;

# switch

Description | Test whether an expression matches one of a number of constants and branch accordingly.
Syntax |
    switch expr
        { case constant {, constant}: {statement [;]} }
        [ default: {statement [;] }]
    end;
where:
`expr` | is an expression that evaluates to a string, an integer, or a decimal.
`constant` | is a constant of the same data type as `expr`.
`statement` | is the statement to be executed on a match.
Notes | The default case is chosen if the expression does not match any constant.
Returns | None.
Example | In this example, the variable `name` is matched by the string "`joe`", so the message "`It's Joe`" will be printed. After printing the message, control leaves the `case` statement.
    let name = "Joe";
    switch name case "Jim":
       call info_message ("It's Jim"); case "Joe":
       call info_message ("It's Joe"); case "Ann":
       call info_message ("It's Ann");
       default: call error_message ("Neither Jim, Joe nor Ann");
    end;

# sys_command

Description | Execute an operating system command and returns immediately.
Syntax |
    call sys_command (command {, argument});
where:
`command` | is an operating system command.
`argument` | is an argument for the operating system command.
Notes | The `command` may be any expression that evaluates to a string. The value of the `string` is passed to the operating system. The `argument` may be any expression that evaluates to a string. The value of the `string` is placed in double quotes and passed to the operating system. In addition, special characters that cause expansion by the shell are escaped with a backslash (`\`) to preclude expansion.
Returns | None.
Example | To send a file `prtfile` to the printer use:
    call sys_command ("print", "prtfile");
which is passed to the operating system as:
    print "prtfile"

# sys_prompt

Description | 4GL application which can be called to display a question in a pop-up window, wait for a yes or no single character response and then remove the pop-up window.
Syntax |
    let answer = application sys_prompt (question, row, col);
where:
`sys_prompt` | is a standard application available in the `apfmdb` which provides a pop-up window that displays a question on the screen until a single character `Y`, `y`, `N`, or `n` response is given. Then the window disappears. The response to the question can be captured.
`question` | is the question to display in the pop-up window.
`row` | is the row coordinate for placement of the upper right corner of the window.
`col` | is the column coordinate for placement of the upper right corner of the window.
Notes | It is necessary to link the application `sys_prompt` with the user application. This is done by including the entry `sys_prompt` in the `Other Page/Link Application` list of the application. The window will remain visible until the yes or no response is received. The `sys_prompt` will concatenate ? (y/n) to the question before display in the pop-up window. The window can display only 30 characters. The question itself therefore should not be longer than 23 characters. However, user can copy this application and modify it to their own liking. The row and column coordinates must be chosen to allow the entire pop-up window (3 rows, 34 columns) to display.
Returns | `CHAR` containing `y` or `n`.
Example |
    local
       char ans;
    end;
    let ans = application sys_prompt ("Are you sure", 1, 1);
    switch ans
       case y: call delete_script();
       case n: exit;
    end;

# sys_value

Description | Execute the given operating system command and return the resulting standard output of the command.
Syntax |
    let variable = sys_value (command {, argument});
or
    if sys_value (...) = expr
where:
`command` | is an operating system command.
`argument` | is an argument for the operating system command.
`expr` | is an expression.
Notes | The result of the command will be stored in `variable`. The `command` may be any expression that evaluates to a string. The value of the `string` is passed to the operating system. The argument may be any expression that evaluates to a string. The value of the `string` is placed in double quotes and passed to the operating system. In addition, special characters that cause expansion by the shell are escaped with a backslash (\) to preclude expansion. If the operating system command fails, the statement fails. Empress 4GL will beep and immediately stop executing the script.
Returns | The result of the operating system command.
Example | To count the number of words in a file `ufile` and place the value in `wordcount`, use:
    let wordcount = sys_value ("wc", "-w", "ufile");
which places the result of the command:
    wc "-w" "ufile"
into the variable `wordcount`.

# sys_variable

Description | Return the value of an environment variable.
Syntax |
    let variable = sys_variable (system_variable);
or
    if sys_variable (system_variable) = expr
where:
`system_variable` | is the name of an environment variable.
`expr` | is an expression.
Notes | The `system_variable` may be an expression that evaluates to a string. The value of the environment variable is assigned to `variable`. Bourne shell variables must have been exported to be accessed by this function. C shell variables must have been set using the `setenv` command. This function will return the value of any of the Empress system variables and administrative variables. Empress system variables are listed in the Empress SQL User's Guide and administrative variables are listed in the Empress Database Administrator's Guide.
Returns | Value of the environment variable.
Example | To place the value of the Empress variable `MSSCPRINTSCREEN` into a variable `screenkey`, use:
    let screenkey = sys_variable ("MSSCPRINTSCREEN");
This particular Empress variable defines the file where an Empress 4GL screen will be sent to when the <Print Screen> key is pressed. If the value returned is `screens` then pressing the <Print Screen> key will print the screen and send the output to the file `screens`.

# system

Description | Causes Empress 4GL to call the operating system. If arguments are given, they are expected to form an operating system command and its arguments, and the command is executed.
Syntax |
    call system (command {, argument});
where:
`command` | is an operating system command.
`argument` | is an argument for the operating system command.
Notes | The `command` may be any expression that evaluates to a string. The value of the `string` is passed to the operating system. The `argument` may be any expression that evaluates to a string. The `string` is placed in double quotes and passed to the operating system. In addition, special characters that cause expansion by the shell are escaped with a backslash (\) to preclude expansion. If the operating system is called without running a command, the normal logout procedure returns control to Empress 4GL. If the operating system is called to run a command, pressing any key after the command has completed returns control to Empress 4GL.
Returns | None.
Example | To escape to the operating system and obtain a directory listing, use:
       call system ("ls", "-al");

# temporary_window

Description | Display a window that is removed automatically by the next keystroke.
Syntax |
    call temporary_window (window [, field_name, message
         {, message...}]);
where:
`window` | is the name of a window. It may be an expression that evaluates to a string.
`field_name` | is the name of a field. It may be an expression that evaluates to a string.
`message` | is the message to be printed. It may be an expression that evaluates to a string.
Notes | If a field and a message are specified, that message is displayed in that field. If the field specified is a multi-field, and more than one message is given, messages are displayed in succeeding fields in turn. If there are more messages that fields, the extra messages are ignored; if there are more fields than messages, the extra fields are ignored. If the field is not a multi-field, multiple messages are concatenated and displayed in that field.
Returns | None.
Example | To create a temporary window for the field `name` in the window `names`, use:
    call temporary_window ("names", "name", "The rain in
    Spain falls mostly on the plain.");

# touch_field_name

Description | Returns the field name of position where the screen was touched.
Syntax |
    let variable = touch_field_name ();
or
    if touch_field_name () = expr
where:
`variable` | is the name of the variable.
Returns | Null or the touch screen position's field name.
See Also |
    touch_field_number, touch_location, touch_window_name
Example | To get the field name of the touch screen position and store the name in the variable `fname`, use:
    let fname = touch_field_name ();

# touch_field_number

Description | Return the field number of the touch screen position.
Syntax |
    let variable = touch_field_number ();
or
    if touch_field_number () = expr
where:
`variable` | is the name of the variable.
Returns | Null or the touch screen position's field number.
See Also |
    touch_field_name, touch_location, touch_window_name
Example | To get the field number of the touch screen position and store in the variable `fnumber`, use:
    let fnumber = touch_field_number ();

# touch_location

Description | Determine the location where the screen was touched.
Syntax |
    call touch_location ();
Notes | The system global variables `touch_row` and `touch_column` are automatically updated.
Returns | None.
See Also |
    touch_field_name, touch_field_number, touch_window_name
Example | To locate the touch screen position, use:
    call touch_location ();

# touch_window_name

Description | This determines the current window of the touch screen position.
Syntax |
    let variable = touch_window_name ();
or
    if touch_window_name () = expr
where:
`variable` | is the name of the variable.
Returns | Null or the window name of the touch screen position.
See Also |
    touch_field_name, touch_field_number, touch_window_name
Example | To determine which window is at the screen touch position and store the name of the window in the variable `wname`, use:
    let wname = touch_window_name ();

# undefine

Description | Remove a select context created by either `select` or by `define select`.
Syntax |
    undefine context context;
where:
`context` | is the name of a selected context.
Notes | This statement will fail giving an error if the context was never established by the execution of a `define select` or a `select`.
Returns | None.
See Also |
    end_select, define select, select
Example | To disable the context `namesakes`, use: undefine context "namesakes";

# update

Description | Description Update the current record in a table.
Syntax |
    update tabinst {, tabinst} [from funcname |()             |];
                                              |(expr {, expr})|
where:
`tabinst` | is the name of a table instance.
`funcname` | is a function name. It is usually the name of a script.
`expr` | is an expression.
Notes | The current record is the current record of the context generated from each table instance. If `funcname` is supplied, the script `funcname` is invoked with the given expressions as arguments, typically to assign values from fields to attributes. The update is done after the function completes. The function name must not be enclosed in quotes. The parentheses after the function name are necessary even if no arguments are passed.
Returns | None.
Example | To update the current record in `nametable` after executing a script `update_name`, use:
    update "nametable" from update_name ();
where `update_name` is the script:
    let "nametable"."address" = "names"@"address";
    let "nametable"."tel" = "names"@"tel";

# while

Description | Repeatedly execute one or more statements while a condition is true.
Syntax |
    while condition {statement [;]} end;
where:
`condition` | is a condition to be evaluated.
`statement` | is an Empress 4GL statement to be executed.
Notes | The `statement`s are performed as long as the `condition` is true. See the `if` statement for the list of allowable conditions.
Returns | None.
Example | A script that counts from one to a hundred is:
    let number = 1;
    while number < 100
        let number = number + 1;
    end;

# zoom_window

Description | Change the size of the window as specified by the given relative amounts (which may be positive or negative).
Syntax |
    call zoom_window (window, row_amount, col_amount
         [, row_amount, col_amount]);
where:
`window` | is the name of a window. It may be any expression that evaluates to a string.
`row_amount` | is the number of rows to move with respect to the current row.
`col_amount` | is the number of rows to move with respect to the current column.
Notes | The `row_amount` and `col_amount` may be expressions that evaluate to integers. If only one set of row and column values is passed, the `row_amount` is applied to both the top and bottom of the window, and the `col_amount` is applied to both the left and right sides of the window. If both sets are passed to the function, the first set of values is applied to the top left corner and the second set is applied to the bottom right corner. The effect of the command is as if the coordinates for the window as defined in the `Window Table` were changed for the current execution of the application. This command does not affect the home position of the form in the window. That is, the part of the form that appears in the top left corner of the window will move with that corner of the window. A window cannot be zoomed so that the current field is obscured. The current field will always remain visible. The window may not be zoomed past any edge of the screen. It may not be shrunk beyond a minimum of one line and one column. It is not an error to zoom a window that is not currently shown. The defined size of the window will be altered. The size of a window remains as it was until you change it again or `exit` the application. The `row_amount` and `col_amount` can be negative.
Returns | None.
Example | To grow the window `names`, use:
    call zoom_window ("names", 1, 1);