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
  1. If cursor is null (the keyword NULL may be used), the cursor name defaults to the window name.
  2. 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
  1. A dialog box is displayed. It has a title, a message area, an OK button, and a Help button.
  2. The title is a string used as the title of the dialog box.
  3. The message is the text displayed in the dialog box.
  4. 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.
  5. 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
  1. A dialog box is displayed. It has a title, a message area, and an OK button.
  2. The title is a string used as the title of the dialog box.
  3. The message is the text displayed in the dialog box.
  4. The function does not halt the execution of an script action.
  5. 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
  1. 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.
  2. The title is a string used as the title of the dialog box.
  3. The message is the text displayed in the dialog box.
  4. The default_value expression is evaluated and placed in the text field. The user is allowed to change the contents of the field.
  5. The default_button indicates which button (1: OK, 2: Cancel, 3: Help) is the default.
  6. 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.
  7. 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.
  8. If the user clicks on the OK button, the contents of the text field are returned.
  9. 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
  1. A dialog box is displayed. It has a title, a message area, a Yes button, a No button and a Help button.
  2. The title is a string used as the title of the dialog box.
  3. The message is the text displayed in the dialog box.
  4. The default_button indicates which button (1: Yes, 2: No, 3: Help) is the default.
  5. 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.
  6. 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.
  7. If the user clicks on the Yes button, the function returns TRUE.
  8. 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
  1. A dialog box is displayed. It has a title, a message area, a Continue button, a Stop button and a Help button.
  2. The title is a string used as the title of the dialog box.
  3. The message is the text displayed in the dialog box.
  4. The default_button indicates which button (1: Continue, 2: Stop, 3: Help) is the default.
  5. 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.
  6. 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.
  7. If the user clicks on the Continue button, the function returns TRUE.
  8. 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
  1. 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
  1. If the field has an enter action specified, the action will be executed.
  2. 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.
  3. 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
  1. 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
  1. This function assigns data in array variables to the list or multilist specified.
  2. size specifies the number of rows of data to display.
  3. If the object is a list, there must be only one array variable.
  4. 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
  1. 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.
  2. 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.
  3. The number of items 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.
  4. 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.
  5. 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
  1. The multilist associated with the cursor specified is updated to reflect the contents of the cursor.
  2. 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
  1. The cursor is dissociated from the multilist to which it was previously associated.
  2. 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
  1. If cursor is null (the keyword NULL may be used), the cursor name defaults to the window name.
  2. 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.
  3. 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.
  4. 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
  1. 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).
  2. The argument may be any expression evaluating to a string. The string is placed in double quotes and passed to the operating system.
  3. Special characters which cause expansion by the shell are escaped with a backslash (\), to preclude expansion.
  4. Execution of the script action is halted until the completion of the command.
  5. The standard output of the command is stored in the string variable str_var. If the function is called, the standard output of the command is ignored.
  6. 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
  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.
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
  1. It is not an error to remove a window that is not currently shown.
  2. 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
  1. It is not an error to show a window that is already shown.
  2. 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");