SATSHELL Programming/Reference Guide
S@
SATGUI SATSHELL SATFORM SATFILTER SATREPORT SATMYSQL License Download Examples Contact
SATSHELL Programming


SATSHELL Programming Basics/Guidelines

NOTE: The SATSHELL documentation assumes the reader is familiar with shell script programming.


The easiest way to illustrate SATSHELL programming is to use a simple example. In this case a utility to display the contents of the /etc/passwd file for Linux.


Basics

Programming GUI applications tends to be slightly different from the traditional character based approach. The typical GUI application screen may have many items which can be used to trigger an Action (A button press, selecting from a menu, double-clicking an item in a list etc.). These Actions could occur at any time, in any order. To take this into account the recommended Program Structure should be used.

Communication between SATSHELL and the Unix script is through the normal Standard Input/Output mechinism. This is a "natural way" for shell script programming and allows for maximum flexibility.

The Standard Output of the Unix/Linux script is read by SATSHELL, and must be in the form of valid SAT/DL commands. It is the programmers responsibility to ensure that Standard Error is handled or redirected as appropriate for the application. SATSHELL will write script/Unix commands to the Unix/Linux script Standard Input when an Action is triggered.

NOTE: The Unix/Linux system shell interpreter is used to execute the shell script. For example bash under Linux.

Example:

Assume a screen has been displayed which used the following SAT/DL commands:

addEntry {First_Name 1,1 11,25}
addEntry {Last_Name 1,3 11,25}
addButton {Save 1,6 6 {savename first_name last_name}}

If the application user has entered "John" into the First_Name field, and "Smith" into the Last_Name field, SATSHELL will write...

savename "John" "Smith"

...to the Standard Input of the Unix script when the Save button is pressed.

NOTE: For details of the correct format for item names, and their usage: See Name Format.

Program Structure

The simplest, and recommended, method to interface the Unix script with SATSHELL is to structure the script so that each of the possible Actions is defined as a function.

The only code which should not be in a function is the "Initialise" section and the "Main Loop". One of the functions should act as the entry/home screen for the application, and should be executed in the "Initialise" section. The "Main Loop" should be a "Do Forever" (while true) loop. This loop should read and eval anything read from Standard Input.

When the application window is closed for any reason, a null Command is read by the script. It is important to check for this condition and exit from the script. The exit could be defined as a function if a "tidy-up" procedure is required.

#------------------#
# Action Functions #
#------------------#
MyAction1() {
...
...
}

MyAction2() {
...
...
}

#------------#
# Initialise #
#------------#
MyAction1

#-----------#
# Main Loop #
#-----------#
while true
do
   read Command
   [ -z "$Command" ] && exit
   eval "$Command"
done

When to Use the "unlock" SAT/DL Command

When an action is invoked the screen is locked and the clock/hourglass cursor is displayed. This is to ensure that Actions cannot be triggered while the current Action is being processed. It is therefore neccessary to issue an unlock command when the current Action has finished processing.

Positioning Display Items

Display Items (Buttons, entry fields etc) are positioned using an absolute "x,y" coordinate system.

The "x" position is in columns (numbered from zero), where one column is the average width of a character in the default font used for a label. The "y" position is in rows (numbered from zero), where one row is the line spacing in the default font used for a label.

Passing Parameters to Actions

Parameters passed to Actions maybe either value of a SAT/DL item (For example: Data, Entry, Radiobuttons) -or- a literal (Constant) value. Item values are generaly passed by using the name of the item. Checkbuttons also require the button label to be specified (See addCheckbuttons). Literal values are enclosed in single quotes and must not contain spaces.

Examples

{myaction1 first_name last_name}
{myaction2 order_code 'print'}
{myaction2 order_code 'fax'}
{myaction3 customer order:urgent order:customer_collect order:invoice} 

...The first example passes two item (variable) value parameters. The second and third examples show how the same Action can be called in different modes, by passing literal (constant) values in addition to item values. The final example shows how Checkbutton values are passed.


Using File Select/Save Dialogs

File Select and Save dialogs can be invoked by actions associated with Buttons, Hot-Keys, Menus and Toolbars. The File Select dialog will only allow a file that exists to be selected. The File Save dialog displays a file "overwrite" message if a file that exists is specified.

Example:

addButton {Open_Text 1,1 8 {myopenfile open_text} fileselect(.)}

When the button ("Open_Text") created by this command is pressed, a standard file selection dialog is displayed showing all files in the current (working) directory. When a selection is made the filename is assigned to the "name" of the button. The action ("myopenfile") is then invoked with the filename passed as the first parameter.

If the File Select dialog "Cancel" button is pressed the action is aborted.

Path/File Names

The fileselect and filesave options can accept both absolute and relative path/file names.

Examples:

OptionResult
fileselect(.)All files in current directory.
fileselect(*)All files in current directory.
fileselect(./*.txt)All files ending ".txt" in current directory.
fileselect(*.txt)All files ending ".txt" in current directory.
fileselect(/home/mydir)All files in "/home/mydir" directory.
fileselect(/home/mydir/*.txt)All files ending ".txt" in "/home/mydir" directory.

Selected Filename

The name of the data item to which the selected filename is assigned depends on the type of item to which it is associated.

ExampleData Item
addButton {Example 1,1 8 {myaction example} fileselect(.)}example
addHotKey {Control-o {myaction Control-o} fileselect(.)Control-o
addMenu {
   {File
      {Open {myaction file:open} fileselect(.)}
      {Exit exit}
   }
}
file:open
addToolbar {raised {open {myaction toolbar:open} fileselect(.)} {stop exit}}toolbar:open

Application Screen Layout

The "Application Title" is set using the configuration file, setTitle and newScreen.

The "Application Screen" is where the main application appears. The addDisplayItem commands create items (Entry boxes, buttons etc.) in this area.

The "Message Line" is set using setMessage. Some SATSHELL internal facilities (For example: Entry validations) also write to the Message Line.

Tips For Writing And Debugging "SATSHELL" Scripts

SATSHELL assumes that all input it receives is valid, correctly formatted SAT/DL commands. Anything else will either not work at all or, more likely, display an error dialog from the TCL/TK interpreter. This is by far the most common reason for the appearance of an error dialog.In the case of an invalid SAT/DL command, the error information shown is not important and can be ignored.

If you get one of these error dialogs, click the "OK" button, close the application window and any remaining error dialogs...

...then check to make sure your script is generating valid SAT/DL commands.


A simple way to check your script is simply to run it directly from a Linux/Unix command prompt, without using SATSHELL. Enter Action commands manually, using the keyboard, in the format that SATSHELL would generate. Your script should always respond by displaying valid SAT/DL commands.


Although there is no "Visual" development environment for SATSHELL, the SAT/DL Development Tool (SATDLTOOL) provides a very simple method to try out screen layouts by entering SAT/DL commands interactively.

Where Actions have been specified, the command as would be returned to a SATSHELL script are displayed in the "Console" window -or- at the "%" prompt (Depending on whether you are using the executable or source code version).

NOTE: SATSHELL will use double quotes in place of the braces displayed for Actions.

SAT/DL Development Tool

The SAT/DL Development Tool (SATDLTOOL) is a simple interactive tool to assist in designing SATSHELL screen layouts. This is a stand-alone program which allows screen layouts to be tried interactively.

When SATDLTOOL is started using Linux executable, two windows are created (TCL/TK programmers will recognise this!!):-

NOTE: The "Console" window may appear on top of the "Tool" Window.

SAT/DL commands entered into the "Console" will immediately update the "Tool" window. If actions are specified for buttons, entries -or- multi-list items, the action/parameters which would be sent to the shell script are displayed in the "Console" window.

To start SATDLTOOL using the source code

To load/run files containing SAT/DL code

In addition to entering SAT/DL commands at the "Console" prompt, files containing SAT/DL code can be loaded/run using SATGUITOOL.

Or NOTES:

Running SATSHELL Applications

SATSHELL applications are started from the command line using the satshell command.

Examples:

If the locations of both SATSHELL and the script to be run are in the PATH environment variable:-

satshell myprog

If SATSHELL is in the PATH and myprog is in /home/testuser directory:-

satshell /home/testuser/myprog

Passing parameters to myprog from the command line:-

satshell myprog "Test Parameter1" /home/testuser/myfile


Copyright © 2003 Adrian Davis.