SATFORM Reference |
Layout of SATFORM Applications |
The base directory for a SAT application must be defined in an exported environment variable called SATHOME. Under this directory the following directories must exist:-
$SATHOME |
bin form overlay |
Executable files for external tags and programs. Form template files. Overlay files. |
This directory is only required if external or <run> tags are used.
This directory contains the form templates.
These files must contain executable code, and have execute permissons for the application user.
This directory contains the overlay bitmap/macro files.
This directory is only required if overlays are used.
Usage |
satform form data=value data=value ...
form | Name of form file in $SATHOME/form directory. |
data=value | Set a data item called DATA to value. |
The data item name will always be converted to uppercase. Therefore the command line data item myvariable="some value" will be referred to as ${MYVARIABLE} in a SAT/ML form.
SATFORM reads the variable data from standard input in the following format:
form1-data-name1\034data-value1
form1-data-name2\034data-value2
...
...
\f
form2-data-name1\034data-value1
form2-data-name2\034data-value2
...
...
\f
...
...
The data-names must not contain spaces. Although upper and lower case characters may be used, it is recommended that lower case only be used for data names, as upper case is used to identify data items specified in the command line.
The data-name must be separated from the data-value by the octal 034 character.
The data for each form must end with a form-feed character. This applies even if there is only one form to be printed.
Variable Data |
As described above, SATFORM reads variable data in name/value pairs. Within a SAT/ML form variable data is refered to by its name. The variable data may also, optionally, have its case converted in one of three ways.
Examples:
Assume the value of the data item name is "john SMITH"
Data Item | Replaced with | Conversion |
${name} | john SMITH | None |
%{name} | John Smith | Mixed case |
+{name} | JOHN SMITH | Upper case |
-{name} | john smith | Lower case |
Predefined Data |
Data Item | Value |
DATE | Current date in format defined by dateformat. |
Example:
Assume todays date is 23rd March 2001 and the dateformat is the default (us):
Data Item | Replaced with |
${DATE} | 03/23/2001 |
External Tags |
External tags are a method of extending SAT/ML without modifying the core code. Whenever a tag is referred to that is not known to SATFORM, a program with the tag name is run form the $SATHOME/bin directory. If parameters are specified they are passed to the program. The standard output from the program then replaces the tag.
In this way new (application specific) tags can be added.
For example: Assume there is a data item called date, which has an mm/dd/yyyy format, but you only want to print the year part of the date.
Create a script in the $SATHOME/bin directory called year, something like:
echo ${1} | cut -f3 -d"/"This new tag can now be used thus:
<year ${date}>
Overlays |
Overlays must be created as PCL macros. A package which can convert the output from most Windows applications into suitable overlay files is Forms Electric.
SAT/ML Form Layout |
SAT/ML forms must have the following general layout:
<dateformat format>
<include form>
<overlay overlay>
<label label> </label>
<body>
All other tags and macros. The include tag is also valid in a form body provided the
included form does not contain tags not valid in a form body.
</body>
<label label> </label>
Above it is shown that labeled blocks can appear before or after the body. In fact all tags which are not valid in the form body can appear after the body. However, for clarity it is suggested that they appear at the begining.
SAT/ML Form Processing |
In order to understand how tags, data and macros interact it is necessary to know the order in which they are processed:
NOTE: From step 5, only text between <body> and </body> is processed.