call attr_update (tabinst, attr, expr);

1. This function updates an attribute in the application, not in the database table. To update a record in a table, use the UPDATE command.

update

call attr_update ("nametable", "tel", "names"@"tel");

let variable = attr_value (tabinst, attr)

if attr_value (tabinst, attr) = expr

let telephone = attr_value ("nametable", "tel");

call beep ();

call beep ();

call funcname ([expr {, expr}]);

1. 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.
2. If expr is given, they are evaluated and the results passed as arguments to the procedure or function.

call menu ();

call application apname ([expr {, expr}]);

1. The apname must be a quoted string or a variable.
2. 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.
3. If a call application statement is encountered in a script, the application is executed immediately. When it is completed, control returns to the script.
4. Executing a series of call application statements causes a stack of applications to be built. If the stack grows large, system performance may suffer.
5. An application returns a value through a return statement in the application exit script.

call application "personnel" ();

check expr for attr;

1. 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.
2. A null field will always be accepted (even if the attribute is defined as not null).
3. 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.

check "names"@"name" for "nametable"."name";

let variable = check_field (window, field_name

      [, field_number]);

if check_field (...) = expr 

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

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

 

let integerflag = check_field ("names", "tel");

call clear_fields ([window]); 

1. If no window is supplied, it defaults to the current window.
2. 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.

call clear_fields ("names");

call clear_save_value (window [, field_name

     [, field_number]]);

1. The keyword NULL may be used in place of window. Empress accepts this as referring to the current window.
2. The keyword NULL may be used in place of field_name.  Empress accepts this as referring to the current field. 
3. The field_name may be omitted. Empress will then clear saved values for every field in the window.
4. The field_number may be omitted. Empress will clear save values for the current field.
5. A saved field value is stored as data type CHAR, regardless of the data type of its associated field.
6. 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.

call clear_save_value ("names", "name");

call clear_status ();

debug_message, error_message, info_message

call clear_status (); 

close tabinst {, tabinst}; 

end_select, undefine

close "nametable";

commit [transaction];

1. 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. 
2. If no transaction is in progress, an error message is printed in a status box on the top right corner of the screen. 
3. To roll back a transaction, see the rollback command.

start transaction, rollback transaction

commit transaction;

let variable = compare_save_value

      (window [, field_name [, field_number]]);

if compare_save_value () = expr

1. The keyword NULL may be used in place of window. The routine will default to the current window.
2. The keyword NULL may be used in place of field_name. The routine will default to the current field.
3. 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.
4. The field_number may be omitted. The operation will be performed on the current field.
5. A saved field value is stored as data type CHAR, regardless of the data type of its associated field.
6. 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.

save_value

let nameflag = compare_save_value ("names", "name"); 

call current_field (field_name [, field_number] ['-x']);

1. 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.
2. 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).
3. The named field is not entered immediately; it is entered after the script containing the statement completes.
4. 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.
5. The option -x instructs the application to execute the exit script of the current field before performing any other action.

call current_field ("name");

let variable = current_field_name ();

if current_field_name () = expr

let field_name = current_field_name ();

let variable = current_field_number ();

if current_field_number () = expr

let fnum = current_field_number ();

call current_field_update (expr);

call current_field_update (goodvalue);

let variable = current_field_value ();

if current_field_value () = expr

let goodvalue = current_field_value ();

call current_field_video (video_name);

1. The attribute normal is always permitted. The range of allowable video attributes is terminal dependent.
2. The list of video_names 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.
3. 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_names you can pass to the current_field_video function.

call current_field_video ("reverse");

call current_window (window [, field_name

      [, field_number]] ['-x']);

1. 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.
2. 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).
3. 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.
4. Making a window current does not make it appear on the screen. That is done with the show_window function.
5. It is not an error to make a window current without having shown it first.
6. Note that control is not passed to the window immediately; control is passed after the script containing the statement completes.
7. The -x option instructs the application to execute the exit script of the current field before performing any other action.

call current_window ("names", "name");

let variable = current_window_name ();

if current_window_name () = expr

let wname = current_window_name (); 

call debug_message (message {, message});

1. The messages are concatenated together when they are displayed. No blanks are inserted between each message.
2. The information message is displayed and execution pauses until a key (any key) is pressed.

let a = b;

call debug_message ("a = ", a);

call debug_mode (mode);

call debug_mode ("on"); 

call define_group_multi (context, window,

     next_line, prev_line, display_script, locked_script,

     fill_script {, field_name}) [;]

1. This function defines window as a multiple record window for displaying records of the context. 
2. The window will normally contain multi-fields (sets of fields sharing the same name) for displaying attribute values. 
3. 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. 
4. 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. 
5. 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). 
6. 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. 
7. 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. 
8. 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. 
9. 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. 
10. It is possible to associate multi-fields in a window with more than one context. 
11. If no field_names are listed, all the fields in the window are included. 
12. 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. 

13. 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.
14. See the Empress 4GL User's Guide for a detailed example of building a multiple record application.

set_field_values, select, define select, display_page,

next_group, prev_group, define_multi

call define_multi (context, window, next_line,

     prev_line, display_script, locked_script,

     fill_script {, field_name});

1. This function defines window as a multiple record window for displaying records of the context.
2. 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.
3. 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. 
4. The functions next_line, prev_line, scroll_page, display_page, next_page, and prev_page are made available for the context.
5. 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).
6. 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).
7. 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.
8. 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. 
9. 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.
10. Each multi-field in the window can be associated with only one context. If no field_names are listed, all the fields in the window are included.

set_field_values, select, display_page

_______ 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]

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"; 

call define_multi ("name_list", "names", 0, 1,

     "display_script" "locked_script", "fill_script");

call set_field_values ("names", "name_list");

The script locked_script may be: 

call set_field_values ("names", "name_list", 0, NULL);

let "names"@"address" = "locked";

The script fill_script may set each field to null: 

call set_field_values ("names", "name_list", 0, NULL);

call show_window ("names");

select context "name_list";

call display_page ("name_list");

define select_statement

1. 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.
2. 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.
3. The context defined with this statement must be removed with the undefine statement.

select context, select

The statement:

define select from "nametable"

     where "nametable"."name" = "names"@"name";

The statement: 

define select from "nametable"

     where "nametable"."name" = "names"@"name"

     becomes context "namesakes";

delete tabinst {, tabinst};

1. The record deleted is the current record of each context generated from the tabinsts. If there is no current record for a tabinst, Empress 4GL will beep and stop executing the script.

delete "nametable";

disable context;

1. 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.
2. The context is disabled until a current record re-establishes with a next_rec, prev_rec, or enable statement.

enable

disable "namesakes";

disable interrupt signal_no. {, signal_no. ...}; 

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

2. If signals are disabled then the Empress 4GL will take its default action. In most cases, this is to ignore the signal.

on interrupt, enable interrupt

disable interrupt 14, 16; 

display [from funcname |()             |]; 

                       |(expr {, expr})|

1. 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. 
2. 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. 

display from display_names ();

display_names is the script: 

let "names"@"address" = "nametable"."address";

let "names"@"tel" = "nametable"."tel";

call display_page ([context]); 

1. If no context is given it defaults to the context associated with the current window. 
2. 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. 
3. 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.
4. 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. 
5. 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.
6. If there are no records to display a status message is printed in the status box on the top right corner of the screen. 

define_multi

call display_page ("name_list"); 

call emprepwr context (script_name, outfile

     [, message {, expr}])

1. A context is a named group of selected records referred to as a context.
2. 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. 

3. The outfile is overwritten if it exists. 
4. If the first character of the outfile is "!", the remainder of theoutfile 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.

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

call emprepwr "namesakes"

    ("printnames", "printfile", "names being printed");

call empsql ([database_name [, query_language_command]]); 

1. 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.
2. 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.
3. If query_language_command is not supplied the Query Language STOP command returns control to Empress 4GL.

call empsql ("mydatabase");

call empsql ();

display mydatabase:mytable;

call empsql ("mydatabase", "display mytable"); 

enable context;

1. enable re-establishes the current record if it still exists or is not locked by another user. 
2. next_rec, next_record, prev_rec and prev_record also enable a context.

disable, next_rec, prev_rec, next_record, prev_record 

enable "namesakes"; 

enable interrupt signal_no {, signal_no. ...};

The signal(s) may have been temporarily disabled within the application with the disable interrupt command

on interrupt, disable interrupt

enable interrupt 14; 

end_select [context] context;

1. It removes contexts initialized with selects but does not remove contexts defined by define_select. 
2. Since a table instance can only support one context, this statement frees the table instance to generate another context.
3. This statement will fail giving an error if the context was never established by the execution of a select. 
4. 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.

select, define_select

end_select "namesakes"; 

call error_message (error_message {, error_message}); 

1. The error messages are concatenated together when they are displayed. Note that no blanks are inserted between each error message.
2. Empress 4GL will beep and exit from the script immediately. Subsequent statements in the script will not be executed.

if a != b

then call error_message ("error: a = ", a, " b = ", b);

end; 

call error_window ([window, field]);

1. The window and field called can be any to which you have access in the current application. The window can be user-defined. 
2. If no window is specified, the application will use the built-in default error window.
3. 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.
4. The field number is always assumed to be 1.

call error_window ("error", "error_message"); 

exit [|empress       |] [confirm];

      |script        |

      |to application| 

1. Whenever you exit an application the application exit script is executed. 
2. If the confirm option is specified, the user will be prompted for exit confirmation with a "Confirm exit? (y/n)" message.

exit;

exit empress; 

exit script;

exit to "menu";

export struct_type struct_name {;

       struct_type struct_name} [;] END;

1. 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.
2. 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. 
3. 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.
4. A shared form is defined in one application and used in another. 
5. 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.
6. A shared script is defined in one application and used in another. 

export script check_value; end; 

external [type] variable {; [type] variable} [;] end;

1. 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". 
2. An external variable may only be declared in the application enter script. 
3. There may be only one external statement in a script. It must follow the parameter statement, if any, and precede all other statements. 

external 

    char name; 

    integer age;

end; 

call field_help_window () 

call field_help_window (); 

call field_mode (window, field_name, field_number, mode);

1. 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.
2. There is no way to query the field mode.

next_field, prev_field

call field_mode ("names", "name", 1, "r"); 

call field_update (window, field_name,

     [field_number, ] expr);

1. 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. 
2. 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).

call field_update ("names", "tel", "nametable"."tel"); 

let variable = field_value (window, field_name

    [, field_number]);

if field_value (window, field_name

    [, field_number]) = expr

1. 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.
2. 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). 

let telephone = field_value ("names", "tel");

call field_video (window, field_name,

    [field_number, ] video_name);

1. 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.
2. 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).
3. 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_names on a given terminal. 

current_field_video

call field_video ("names", "address", "reverse"); 

let variable = get_save_value (window, field_name

    [, field_number]);

if get_save_value (window, field_name

    [, field_number]) = expr 

1. 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. 
2. The keyword NULL can be used in place of window. The routine will default to the current window.
3. The keyword NULL can be used in place of field_name. The routine will default to the current field.
4. The field_number may be omitted. The routine will default to the current field number.
5. A saved field value is stored as data type CHAR, regardless of the data type of its associated field. 
6. 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).

let variable = get_save_value ("names", "name");

global [type] variable {; [type] variable} [;] END;

1. The named variables are declared to be global to the application and of the given types. See Chapter 1.8 - "Data Types".
2. A global variable may only be declared in the application enter script. global variables declared elsewhere are taken as local to the script.
3. 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.
4. A global can be referenced in another application by declaring the same variable as an external in that application.

parameter, external, local 

global 

   char name; 

   integer age;

end; 

if condition [then]

{statement [;]}

[|else {statement [;]}|]

 |elseif_clause       |

end; 

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 |

1. 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.
2. 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.
3. Attempting to compare a string and a number results in an expression failure. An error message will be generated.

if "names"@"name" = "stop" then 

     exit;

end;

1. If the field is empty prompt for a value
2. If the value is stop exit the script
3. If there is a value and it is not stop call the script get_details.

if "names"@"name" = null then

     call error_message ("enter a name");

elseif "names"@"name" = stop then 

     exit;

else

     call get_details ();

end; 

import struct_type struct_name 

     {; struct_type struct_name} [;] end;

1. 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.
2. 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.
3. 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.
4. A shared form is defined in one application and used in another.
5. 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.
6. A shared script is defined in one application and used in another.

export

import script SC1; end

call info_message (information {, information}); 

1. The informations are concatenated together when they are displayed. Note that no blanks are inserted between each information.
2. 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.
3. If any system error messages are caused by the script after the info_message statement, these will cover the information.
4. The info_message also does the equivalent of a display.

display

....

.... (phase 5 statements)

....

call info_window ([window, field]);

1. The window and field called can be any to which you have access in the current application. The window can be user-defined.
2. If no window is specified, the application will use the built-in default information window.
3. 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.
4. The field number is always assumed to be 1.

info_message

call info_window ("info", "info_message");

insert tabinst {, tabinst}

      [from funcname |()             |];

                     |(expr {, expr})|

1. Each record is defined by the current attribute values associated with each tabinst.
2. 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.
3. 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. 

next_rec, prev_rec, enable

insert "nametable" from insert_name ();

let "nametable"."address" = "names"@"address";

let "nametable"."tel" = "names"@"tel"; 

let variable = key_context_name ([[window,] number]);

if key_context_name ([[window,] number]) = expr

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

push_key_context, pop_key_context

let keyname = key_context_name ("names", 3);

let variable = key_name (key_label);

if key_name (key_label) = expr

1. variable often will be a field, since key names are useful to display the physical keys associated with scripted functions.
2. 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. 
3. 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.

call show_window ("menu");

let "menu"@"update" = key_name ("AP_1");

display; 

call key_script ([context,] key_label);

call key_script ("AP_8");

let variable = largest_field_number (window, field_name);

if largest_field_number (window, field_name) = expr

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

define_multi

let largest_number = largest_field_number ("names",

"name"); 

let variable = |expr|;  

               |null| 

1. 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.
2. 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.
3. 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). 

let "names"@"address" = "nametable"."address";

let "names"@"address"[1] = "nametable"."address";

local [type] variable {; [type] variable} [;] end; 

1. The named variables are declared to be local to the script and of the given types. See Chapter 1.8 - "Data Types".
2. 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.
3. 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.

parameter, external, global

local 

   char name; 

   integer age;

end; 

lock table [in] |exclusive| [mode];

                |excl     |

                |share    |

1. The lock statement locks the table known by the table name. It is only effective during a transaction.
2. 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.
3. 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.
4. 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. 

lock "nametable" in exclusive mode; 

let variable = mouse_field_name ();

if mouse_field_name () = expr

let fname = mouse_field_name (); 

let variable = mouse_field_number ();

if mouse_field_number () = expr

let fnumber = mouse_field_number ();

let variable = mouse_key_down (); 

if mouse_key_down () = expr 

1. This command must be repeatedly called until it returns 0.
2. The current mouse location is also returned. This command is used to track mouse cursor movement from within an Empress 4GL script. 
3. The system global variables mouse_row and mouse_column are automatically updated.

if mouse_key_down () = 1 then

   .

   .

   .

end;

call mouse_location (); 

1. The system global variables mouse_row and mouse_column are automatically updated.

call mouse_location () ; 

let variable = mouse_window_name ();

if mouse_window_name () = expr

let wname = mouse_window_name ();

call move_window (window, row_amount, col_amount);

1. This command moves the window by the given amounts relative to its last defined position. 
2. 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. 
3. A window cannot be moved beyond the edges of the screen. 
4. The new position of the window is held until it is moved again, or until you quit the application.

call move_window ("names", 10, -5); 

call next_field (['-x']); 

1. 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. 
2. 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. 
3. If the parameter -x is used, the exit script of the current field is executed before the next field is made the current field. 
4. The following conditions determine which field becomes current in any circumstance. Conditions are listed from highest to lowest priority. 
1. 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.
2. 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. 

3. 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.
4. 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. 
5. The next field is entered only after the script completes.

current_field, prev_field

call next_field ();

next_group context [number]; 

1. 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.
2. 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.
3. 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.
4. 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.
5. The function next_group can be called for any active context.
6. The system variables got_records and record_status can be checked after a call to next_group to determine the result of that call.

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

 

select, define select, next_line, prev_line, prev_group,

define_group_multi

next_group "namesakes" 1;

call next_line (); 

1. 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.
2. 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.
3. 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.
4. 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. 

define_multi, next_page

call next_line ();

call next_page ([context]);

1. If context is not given, the context associated with the current window is assumed. 
2. 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.
3. 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.)
4. 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.
5. 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). 
6. 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.

define_multi, scroll_page

call next_page ("name_list"); 

next_rec context [expr];

1. 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. 
2. 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 n^th record from the current position is to be retrieved.
3. 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

4. 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 n^th record of a total of N in the context.

select, define, prev_rec

next_rec "namesakes" 1;

next_record context [expr];

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.

select, define select, prev_record, next _record,

next_rec, prev_rec, next_group, prev_group

next_record "namesakes" 1;

on error|call script ()|error_number {, error_number...};

        |default       |

        |ignore        |

        |exit          |

1. The parameter list for a script called by on error may not contain any reference to local variables.
2. 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.
3. Errors which occur while another error is being processed are handled in the default manner. 

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.

 

on error call actions () 1014; 

on interrupt |call script ()| signal_no.{, signal_no....}

             |break         |

             |exit          |

1. 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....}

disable interrupt, enable interrupt

on interrupt exit 2; 

1. 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.
2. tabinsts is the only name by which any tables are known in the application.
3. If no tabinst is specified, the value of table is taken as the "instance name".
4. 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.
5. 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.
6. 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).
7. Locking levels are described in the Empress SQL Reference under the "LOCK LEVEL" command.
8. Update type operations on a table via any instance name affect the records accessed through all the instance names.
9. The Empress variables MSIAEXCLRETRY, MSIAEXCLSLEEP, MSIALOCKRETRY and MSIALOCKSLEEP are used when attempting to place locks on a table.
10. The time required to open a large number of tables in the same database can be reduced if the opens are issued consecutively in a script.

open "nametable" update;

open "nametable" update as "exampletable";

parameters [type] variable {; [type] variable} [;] end; 

1. 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".
2. If the type is not specified it is assumed to be CHAR.
3. A variable is a sequence of letters, digits and underscores, starting with a letter.
4. 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.
5. 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. 
6. There can be only one parameter statement in a script and it must precede all other statements.

parameters

   char name;

   integer age;

end;

call ages ("John", 30);

call pop_key_context ([window]);

1. If the window name is not supplied, the current window is assumed.
2. 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.
3. 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.
4. 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. 
5. The effects of pushing and popping key contexts endures through separate invocations of a window as the current window.

push_key_context

call pop_key_context ("names"); 

call prev_field (['-x']); 

1. 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.
2. 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.
3. If the parameter -x is used, the exit script of the current field is executed before the previous field is made the current field. 
4. The following conditions determine which field becomes current in any circumstance. They are listed from highest to lowest priority.
1. 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.
2. 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.
3. 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.
5. The previous field is entered only after the script completes.

next_field, current_field

call prev_field ();

prev_group context [number];

1. 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.
2. 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.
3. 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. 
4. 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. 

5. The function prev_group can be called for any active context.
6. The system variables got_records and record_status can be checked after a call to prev_group to determine the result of that call.

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

 

select, define select, next_line, prev_line, next_group,

define_group_multi

prev_group "namesakes" 1; 

call prev_line (); 

1. 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.
2. 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.
3. 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. 
4. 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.

define_multi, prev_page

call prev_line (); 

call prev_page ([context]);

1. If context is not given, the context associated with the current window is assumed.
2. 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.
3. 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. 
4. 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.
5. 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.) 
6. 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.

define_multi, scroll_page

call prev_page ("name_list");

prev_rec context [expr];

1. 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. 
2. 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 n^th previous record from the current position is to be retrieved. 
3. 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

4. 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 n^th record of a total of N in the context.

select, define, next_rec

prev_rec "namesakes"; 

prev_record context [expr];

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.

select, define select, next_record, next_rec, prev_rec, 

next_group, prev_group

prev_record "namesakes" 1;

call print_screen ([out_file]); 

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

2. If out_file is not specified, the output is directed to a file specified by MS4GLPRINTSCREEN. By default this file is called screen.
3. print_screen output can be generated in either ASCII or Postscript format by assigning a or p respectively to the Empress variable MS4GLPRINTSCREENFORMAT.
4. 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. 
5. If print_screen is called repeatedly in the application, the screen contents will be appended to the out_file. 

call print_screen ("screen")

call push_key_context ([window, ] key_context); 

1. If window is not supplied, the current window is assumed.
2. 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. 
3. 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.
4. This function pushes the key context on top of the stack for the window.
5. To remove the key context on the top of the stack for a window, see the pop_key_context function.
6. The effects of pushing and popping key contexts endures through separate invocations of a window as the current window. 

pop_key_context, push_key_context

call push_key_context ("names", "names_keys");

call remove_window (window);

1. It is not an error to remove a window that is not currently shown. 

call remove_window ("names"); 

call reset_fields ([window [, field_name

     [, field_number]]]);

1. Default values are set by entering the default value in the default value field of the field table.

call reset_fields ("names", "name");

call reset_key_context ([window]);

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

push_key_context, pop_key_context

call reset_key_context ("names"); 

call restore_field (window [, field_name

     [, field_number]]);

1. The keyword NULL may be used in place of window. The routine will assume the current window.
2. The keyword NULL may be used in place of field_name. The routine will assume the current field.
3. The field_name may be omitted. The routine will set every field in the window. 
4. The field_number may be omitted. The routine will assume the current field number. 
5. A saved field value is stored as data type CHAR, regardless of the data type of its associated field.
6. 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. 

call restore_field ("names", "name");

return [expr];

1. Control returns to the script that invoked the script with the return statement.

return result;

let store_result = calculation (argument1, argument2);

|rollback| [transaction] [to savepoint];

|cancel  | 

1. 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.
2. If no savepoint is specified, the entire transaction is rolled back.
3. 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.
4. If no transaction is in progress, an error message is printed in a status box on the top right corner of the screen.
5. To commit a transaction, see commit.

commit, savepoint, start transaction

start transaction;

...

savepoint t1;

...

rollback transaction to t1;

call save_field (window [,field_name [, field_number]])

1. The keyword NULL may be used in place of window. The routine will assume the current window.
2. The keyword NULL may be used in place of field_name. The routine will assume the current field.
3. The field_name may be omitted. The routine will set every field in the window.
4. The field_number may be omitted. The routine will assume the current field number.
5. A saved field value is stored as data type CHAR, regardless of the data type of its associated field.
6. 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.

call save_field ("names", "name"); 

savepoint savepoint;

1. A transaction must be in progress for the statement to succeed. A save point is marked in the transaction, starting a nested transaction.
2. 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.
3. If the application ends before the transaction is explicitly committed or rolled back, it is committed by default.

start transaction, commit, rollback

start transaction;

...

savepoint t1;

...

rollback transaction to t1;

commit transaction; 

call scroll_page ([context, ] number_records);

1. If no context is given it defaults to the context associated with the current window. 
2. 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. 
3. 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. 
4. 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. 
5. 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. 
6. 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. 
7. 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. 
8. If there are no records to display a status message is printed in the status box on the top right corner of the screen.

define_multi, display_page

call scroll_page ("name_list", 5);

call scroll_page ("name_list",

     (largest_field_number ("names", "name") - 1));

call scroll_window (window, row_amount, col_amount); 

1. 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. 
2. It is an error to scroll a window that is not currently shown. 
3. The row_amount and col_amount may be expression that evaluate to integers.

call scroll_window ("names", 1, 0);

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];

1. 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.
2. The select establishes a context but does not establish a current record for the context. This must be done with a next_rec statement. 
3. 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.
4. If sorting is specified, and the variable MSSORTBYPASS is set, locked records will not be included in the select context.
5. 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.
6. 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. 

7. 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 tabinsts 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.
8. 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. 
9. 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. 

10. To define a context without doing a select see define select.
11. Aggregate values and expressions can only be accessed through the context.
12. 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. 
13. The aggregate or expression can be referred to as:

  "context"."print_item"

if the optional PRINT clause has been used with the select item. 
14. 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;

select from "nametable"

     where "nametable"."name" = "names"@"name";

select from "nametable"

where "nametable"."name" = "names"@"name"

becomes context "namesakes";

select context context_name; 

1. The context is generated by initializing or re-initializing it with records.

select, define select

define select from "nametable"

where "nametable"."name" = "names"@"name"

as context "namesakes";

select "namesakes";

call set_attr_values (|window|, |context|, [field_number]);

                      |NULL  |  |NULL   | 

1. If window is null (the keyword NULL may be used) the window defaults to the current window.
2. If context is null (the keyword NULL may be used) the context name defaults to the window name.
3. If field_number is specified then all fields with that field number will be used.
4. 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.
5. 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).
6. 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.

call set_attr_values ("names", "name_list");

let "nametable"."name" = "names"@"name";

let "nametable"."address" = "names"@"address";

let "nametable"."tel" = "names"@"tel";

call set_field_values ( window, context

    [, field_number [, override]]);

1. If window is null (the keyword NULL may be used) the window defaults to the current window.
2. If context is null (the keyword NULL may be used) the context name defaults to the window name.
3. If field_number is specified then only fields with that field number will be assigned.
4. 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.
5. 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).
6. 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.
7. 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.
8. 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.

call set_field_values ("names", "name_list");

let "names"@"name" = "nametable"."name";

let "names"@"address" = "nametable"."address";

let "names"@"tel" = "nametable"."tel";

call set_field_values ("names", "name_list", 0, null); 

call set_key_values (window [, field_number]);

1. If window is null (the keyword NULL may be used) it defaults to the current window.
2. 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.
3. 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).
4. 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.
5. See the description of the function key_name for a discussion of key labels.

call set_key_values ("menu");

let "menu"@"AP_1" = key_name ("AP_1");

let "menu"@"AP_2" = key_name ("AP_2");

let "menu"@"AP_10" = key_name ("AP_10");

call set_save_value (window [, field 

     [, field_number}},value);

1. The keyword NULL may be used in place of window. The routine will assume the current window. 
2. The keyword NULL may be used in place of field_name. The routine will assume the current field.
3. The field_name may be omitted. The routine will set values for every field in the window.
4. The field_number may be omitted. The routine will assume the current field number.
5. A saved field value is stored as data type CHAR, regardless of the data type of its associated field.
6. 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.

call set_save_value ("names", "name", null); 

call show_window (window);

1. Showing a window does not make it current.
2. It is not an error to show a window that is already shown. 

call show_window ("names");

start transaction; 

1. 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.
2. If a transaction is already in progress, a savepoint can be used to roll back to later.
3. To commit a transaction, see commit. To roll back a transaction, see rollback.
4. If the application ends before the transaction is explicitly committed or cancelled, it is committed by default.
5. When one application is called by another, the transaction in the called application can be started and ended without affecting the calling application.

commit, rollback, savepoint

start transaction; 

...

savepoint t1; 

...

rollback transaction to t1;

commit transaction;

switch expr

    { case constant {, constant}: {statement [;]} }

    [ default: {statement [;] }]

end; 

1. The default case is chosen if the expression does not match any constant.

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; 

call sys_command (command {, argument});

1. The command may be any expression that evaluates to a string. The value of the string is passed to the operating system.
2. 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.
3. In addition, special characters that cause expansion by the shell are escaped with a backslash (\) to preclude expansion.

call sys_command ("print", "prtfile");

print "prtfile"

let answer = application sys_prompt (question, row, col); 

1. 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.
2. The window will remain visible until the yes or no response is received.
3. 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.
4. The row and column coordinates must be chosen to allow the entire pop-up window (3 rows, 34 columns) to display. 

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; 

let variable = sys_value (command {, argument});

if sys_value (...) = expr

1. The result of the command will be stored in variable.
2. The command may be any expression that evaluates to a string. The value of the string is passed to the operating system. 
3. 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.
4. In addition, special characters that cause expansion by the shell are escaped with a backslash (\) to preclude expansion. 
5. If the operating system command fails, the statement fails. Empress 4GL will beep and immediately stop executing the script. 

let wordcount = sys_value ("wc", "-w", "ufile"); 

wc "-w" "ufile"

let variable = sys_variable (system_variable);

if sys_variable (system_variable) = expr

1. The system_variable may be an expression that evaluates to a string. The value of the environment variable is assigned to variable.
2. Bourne shell variables must have been exported to be accessed by this function. C shell variables must have been set using the setenv command.
3. 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. 

let screenkey = sys_variable ("MSSCPRINTSCREEN");

call system (command {, argument});