# CHAPTER 4: Script Functions

## empgui_attributes_set
Description | Assign attribute values from objects of the same name.
Syntax | `call empgui_attributes_set (window,|cursor|);` `| null |` where:
`window` | is the name of a window (or bin) for which objects will be referenced
`cursor` | is the name of a cursor for which attributes will be assigned values
Notes | If `cursor` is null (the keyword `NULL` may be used), the cursor name defaults to the window name. The value associated with each object (field, scale, radio box, etc.) in the window specified is assigned to the attributes (if any) which have the same name as the object.
Returns | None.
See Also | `empgui_objects_set()`
Example | Window `win` contains field `name` and scale `salary`. The values of these objects are copied to attributes in cursor `c1`:
    let "win"@"name" = "John";
    let "win"@"salary" = 60000;
    ...
    call empgui_attributes_set ("win", "c1");

## empgui_dialog_error
Description | Display a error message in a dialog box.
Syntax |
    call empgui_dialog_error (title, message, help);
where:
`title` | is a string to be displayed on the title bar of the dialog box
`message` | is a string to be displayed in the dialog box
`help` | is the name of a module
Notes | A dialog box is displayed. It has a title, a message area, an `OK` button, and a `Help` button. The `title` is a string used as the title of the dialog box. The `message` is the text displayed in the dialog box. `help` is the name of a module which is executed when the user clicks on the `Help` button of the dialog box. If `help` is null, the `Help` button is not displayed. The function halts the execution of the script action until the user clicks on the `OK` button to dispose of the dialog box.
Returns | None.
See Also | `empgui_dialog_info()`, `empgui_dialog_warning()`
Example | To check for errors after a database operation: insert into "product_info"; `if (sqlcode != 0)`; `call empgui_dialog_error ("Insert Error", sqlmessage, null);` `exit script;` `end;`

## empgui_dialog_info
Description | Display a message in a dialog box.
Syntax |
    call empgui_dialog_info (title, message);
where:
`title` | is a string to be displayed on the title bar of the dialog box
`message` | is a string to be displayed inside the dialog box
Notes | A dialog box is displayed. It has a title, a message area, and an `OK` button. The `title` is a string used as the title of the dialog box. The `message` is the text displayed in the dialog box. The function does not halt the execution of an script action. To dispose of the dialog box, click on the `OK` button.
Returns | None.
See Also | `empgui_dialog_error()`, `empgui_dialog_warning()`
Example | To inform the user that an invalid value was entered in a field: `if ("win"@"age" < 0)` `call empgui_dialog_info ("Invalid Value", "Age is invalid");` `end;`

## empgui_dialog_prompt
Description | Prompt the user to enter a value in a dialog box.
Syntax | `let str_var = empgui_dialog_prompt (title, message,` `default_value, default_button, help);` where:
`title` | is a string to be displayed on the title bar of the dialog box
`message` | is a string to be displayed in the dialog box
`default_value` | is an expression
`default_button` | is an integer between 1 and 3
`help` | is the name of a module
Notes | A dialog box is displayed. It has a title, a message area, an editable text field, an `OK` button, a `Cancel` button and a `Help` button. The `title` is a string used as the title of the dialog box. The `message` is the text displayed in the dialog box. The `default_value` expression is evaluated and placed in the text field. The user is allowed to change the contents of the field. The `default_button` indicates which button (1: `OK`, 2: `Cancel`, 3: `Help`) is the default. `help` is the name of a module which is executed when the user clicks on the `Help` button of the dialog box. If `help` is null, the `Help` button is not displayed. The function halts the execution of the script action until the user clicks on the `OK` or `Cancel` buttons to dispose of the dialog box. If the user clicks on the `OK` button, the contents of the text field are returned. If the user clicks on the `Cancel` button, the function returns `NULL`.
Returns | String value or `NULL`.
See Also | `empgui_dialog_question()`, `empgui_dialog_warning()`
Example | The following example prompts the user to enter a value, provides the string `"Sales"` as default, and specifies the `OK` button to be the default: `let "win"@"dept" = empgui_dialog_prompt ("Department",` `"Enter a department code:", "Sales", 1, NULL);`

## empgui_dialog_question
Description | Displays a message in a dialog box and allows the user to respond Yes or No:
Syntax |
    if (empgui_dialog_question (title, message, def_button, help)) ...
where:
`title` | is a string to be displayed on the title bar of the dialog box
`message` | is a string to be displayed in the dialog box
`default_button` | is an integer between 1 and 3
`help` | is the name of a module
Notes | A dialog box is displayed. It has a title, a message area, a `Yes` button, a `No` button and a `Help` button. The `title` is a string used as the title of the dialog box. The `message` is the text displayed in the dialog box. The `default_button` indicates which button (1: `Yes`, 2: `No`, 3: `Help`) is the default. `help` is the name of a module which is executed when the user clicks on the `Help` button of the dialog box. If `help` is null, the `Help` button is not displayed. The function halts the execution of the script action until the user clicks on the `Yes` or `No` buttons to dispose of the dialog box. If the user clicks on the `Yes` button, the function returns `TRUE`. If the user clicks on the `No` button, the function returns `FALSE`.
Returns | Boolean value
See Also | `empgui_dialog_prompt()`, `empgui_dialog_warning()`
Example | The following example displays a question in a dialog box, and deletes the current record if the user responds `Yes`: `if(empgui_dialog_question("Delete",` `"Do you really want to delete the current record?", 2, NULL))` `delete from "staff";` `end;`

## empgui_dialog_warning
Description | Displays a message in a dialog box and allows the user to respond Stop or Continue:
Syntax |
    if (empgui_dialog_warning (title, message, def_button, help)) ...
where:
`title` | is a string to be displayed on the title bar of the dialog box
`message` | is a string to be displayed in the dialog box
`default_button` | is an integer between 1 and 3
`help` | is the name of a module
Notes | A dialog box is displayed. It has a title, a message area, a `Continue` button, a `Stop` button and a `Help` button. The `title` is a string used as the title of the dialog box. The `message` is the text displayed in the dialog box. The `default_button` indicates which button (1: `Continue`, 2: `Stop`, 3: `Help`) is the default. `help` is the name of a module which is executed when the user clicks on the `Help` button of the dialog box. If `help` is null, the `Help` button is not displayed. The function halts the execution of the script action until the user clicks on the `Continue` or `Stop` buttons to dispose of the dialog box. If the user clicks on the `Continue` button, the function returns `TRUE`. If the user clicks on the `Stop` button, the function returns `FALSE`.
Returns | Boolean value
See Also | `empgui_dialog_error()`, `empgui_dialog_question()`
Example | The following example displays a message in a dialog box, and stops the execution of the script action if the user responds `Stop`: `if not(empgui_dialog_warning ("Warning",` `"The department code is null", 1, NULL))` `exit script;` `end;`

## empgui_display_refresh
Description | Refresh the contents of the display.
Syntax | `call empgui_display_refresh();`
Notes | All pending X events are processed to ensure that the display is up-to-date.
Returns | None.

## empgui_field_check
Description | Check whether the data in a text field is valid for the definition of the field.
Syntax |
    let variable = empgui_field_check (window, field_name);
or;
    if (empgui_field_check (...) = expr)
where:
`variable` | is an integer variable.
`window` | is the name of the window or bin containing the field. It may be an expression that evaluates to a string.
`field_name` | is the name of the text field to check. It may be an expression that evaluates to a string.
`expr` | is an expression which evaluates to either 1, 0 or -1.
Notes | None.
Returns | `empgui_field_check` returns one of three values in the following table:
Value | Meaning
1 | If the data is valid for the field type.
0 | If the data is not valid for the field type.
-1 | If the field is null.
Example | If the field `tel` in window `names` is defined as an integer data type, you can test if the current value of the field is an integer value with:
    let integerflag = empgui_field_check ("names", "tel");

## empgui_field_focus
Description | Set the keyboard focus to a specific field.
Syntax |
    empgui_field_focus (window, field_name);
where:
`window` | is the name of a window
`field_name` | is the name of a field
Notes | If the field has an enter action specified, the action will be executed. Any keyboard data will be entered in the field until the focus is changed by a mouse click, pressing the <Tab> key or calling this function. This function cannot be used for setting the focus to objects other than text fields.
Returns | None.
Example | To set keyboard focus to field `name` in window `staff`, use:
    call empgui_field_focus ("staff", "name");

## empgui_list_clear
Description | Clear the contents of a list or multilist.
Syntax |
    call empgui_list_clear (window, list);
where:
`window` | is the name of a window or bin
`list` | is the name of a list or multilist
Notes | This function clears all the rows of the list or multilist specified.
Returns | None.
See Also | `empgui_list_display()`
Example | If a push button is used to clear a window, the action for the push button could contain the following: `let "MAINWIN"@"order_number" = null;`; `let "MAINWIN"@"company_name" = null;`; `call empgui_list_clear ("MAINWIN", "item_list");`

## empgui_list_display
Description | Set the contents of a list or multilist.
Syntax |
    call empgui_list_display (window, list, size, array {, array});
where:
`window` | is the name of a window or bin
`list` | is the name of a list or multilist
`size` | is an integer value
`array` | is a character array variable
Notes | This function assigns data in array variables to the list or multilist specified. `size` specifies the number of rows of data to display. If the object is a list, there must be only one array variable. If the object is a multilist, the number of array variables must be equal to the number of columns in the multilist. The first array will be associated with the first column, the second array with the second column, and so on.
Returns | None.
See Also | `empgui_list_clear()`
Example | The following action displays a list of names obtained from a table in the second column of a multilist. `local` `char num[sqlcount];` `char name[sqlcount];` `integer i;` `end;` ; `let i = 0;` ; `while (i < sqlcount)` `let i = i + 1;` `fetch next from cursor1;` `let num[i] = i convert to char;` `let name[i] = "tab"."name";` `end;` `call empgui_list_display ("win", "mlist", i, num, name);`

## empgui_multirecord_define
Description | Associate a cursor to a multilist.
Syntax | `call empgui_multirecord_define (cursor, window, mlist,` `| num_records |, item {, item} );` `| NULL |` where:
`cursor` | is the name of a cursor
`window` | is the name of a window or bin
`mlist` | is the name of a multilist
`num_records` | is an integer value
`item` | is the name of a selected item in the cursor
Notes | The cursor is associated to the multilist specified. The multilist will automatically be updated to reflect the contents of the cursor when the latter is opened. If the cursor was declared with the `count` option, then `num_records` is not needed and can be set to `NULL`. Otherwise, `num_records` provides an estimate of the number of records in the cursor. The number of `item`s must be equal to the number of columns in the multilist. The first `item` will be associated with the first column, the second `item` with the second column, and so on. When a cursor is associated with a list or multilist, there is no current record by default. In effect, the cursor is disabled, and clicking on a row does not make it current. The `enable` statement causes the highlighted row to become current. The `fetch` statement should not be used on a cursor which is associated with a multilist.
Returns | None.
See Also | `empgui_multirecord_undefine()`, `empgui_multirecord_display()`, `enable`, `fetch`
Example | The following action declares a cursor, associates it with a multilist, and displays records in the multilist by opening the cursor: `declare "staff" for` `select "empnum", "name" from "staff_tab" with count;` `call empgui_multirecord_define ("staff", "win", "mlist",` `null, "empnum", "name");` `open "staff";` To delete the highlighted row, the cursor must be enabled to make the row current, before it can be deleted: `enable "staff";` `delete from "staff_tab";`

## empgui_multirecord_display
Description | Refresh a multilist associated to a cursor.
Syntax |
    call empgui_multirecord_display (cursor);
where:
`cursor` | is the name of a cursor
Notes | The multilist associated with the cursor specified is updated to reflect the contents of the cursor. This function is useful after records have been modified.
Returns | None.
See Also | `empgui_multirecord_define()`
Example | To refresh a multilist after a delete operation: `enable "staff";` `delete from "staff_tab";` `call empgui_multirecord_display ("staff");`

## empgui_multirecord_undefine
Description | Remove the association of a cursor to a multilist.
Syntax |
    call empgui_multirecord_undefine (cursor);
where:
`cursor` | is the name of a cursor
Notes | The cursor is dissociated from the multilist to which it was previously associated. This allows the multilist to be associated with another cursor.
Returns | None.
See Also | `empgui_multirecord_define()`
Example | To dissociate the cursor `staff` from a multilist:
    call empgui_multirecord_undefine ("staff");

## empgui_objects_set
Description | Assign objects values from attributes of the same name.
Syntax | `call empgui_objects_set (window,|cursor| [, override] );` `| null |` where:
`window` | is the name of a window (or bin) for which objects will be referenced
`cursor` | is the name of a cursor for which attributes will be assigned values
`override` | is a value to be assigned to the objects, if specified
Notes | If `cursor` is null (the keyword `NULL` may be used), the cursor name defaults to the window name. The value associated with each attribute in the cursor specified is assigned to the objects (if any) which have the same name as the attribute. If the cursor has several attributes with the same name, and they have different values, then the value assigned to the corresponding object cannot be reliably determined. If an `override` is specified, that value is assigned to the objects instead of the attribute values.
Returns | None.
See Also | `empgui_attributes_set()`
Example | To clear the fields in window `win`, an override value of `NULL` can be specified:
    call empgui_objects_set ("win", "c1", NULL);

## empgui_system_command
Description | Execute an operating system command, and return the resulting standard output.
Syntax |
    let str_var = empgui_system_command (command {, argument });
or
    call empgui_system_command (command {, argument } );
where:
`command` | is a string expression
`argument` | is a string expression
`str_var` | is a string variable
Notes | The `command` can be any expression evaluating to a string. The string is passed to the operating system shell specified by the Empress system variable `MSSHELL` (default is `/bin/sh`). The `argument` may be any expression evaluating to a string. The string is placed in double quotes and passed to the operating system. Special characters which cause expansion by the shell are escaped with a backslash (\), to preclude expansion. Execution of the script action is halted until the completion of the `command`. The standard output of the `command` is stored in the string variable `str_var`. If the function is `call`ed, the standard output of the `command` is ignored. If the `command` fails, the standard error output is displayed in a warning dialog box.
Returns | The result of the operating system command.
See Also | `empgui_system_variable()`
Example | To place the contents of a file into a text field:
    let "win"@"field" = empgui_system_command ("cat", "datafile");
To start an `xterm` window with a blue background:
    call empgui_system_command ("xterm -bg blue &");

## empgui_system_variable
Description | Return the value of an environment variable.
Syntax |
    let variable = empgui_system_variable (system_variable);
where:
`system_variable` | is the name of an environment variable.
`variable` | is a string variable.
Notes | The `system_variable` may be an expression that evaluates to a string. The value of the environment variable is assigned to `variable`. Bourne shell variables must have been exported to be accessed by this function. C shell variables must have been set using the `setenv` command. This function will return the value of any of the Empress system variables and administrative variables. Empress system variables are listed in the Empress SQL: User's Guide and administrative variables are listed in the Empress: Database Administrator's Guide.
Returns | Value of the environment variable.
Example | To obtain a the value of the `DISPLAY` environment variable, use:
    let display = empgui_system_variable ("DISPLAY");

## empgui_window_hide
Description | Remove the given window from the screen.
Syntax |
    call empgui_window_hide (window);
where:
`window` | is the name of a window.
Notes | It is not an error to remove a window that is not currently shown. This function does not apply to `MAINWIN`, which is always shown.
Returns | None.
Example | To remove the window `names` from the screen, use:
    call empgui_window_hide ("names");

## empgui_window_show
Description | Show the given window on the screen. The window is guaranteed not to be covered in any way by any other window.
Syntax |
    call empgui_window_show (window);
where:
`window` | is the name of a window.
Notes | It is not an error to show a window that is already shown. If the window was entirely or partially covered by another window, it will be redrawn on top.
Returns | None.
Example | To show the window `names`, use:
    call empgui_window_show ("names");