SATFORM Reference
S@
Home SATGUI SATSHELL SATFORM SATFILTER SATREPORT SATMYSQL License Download Examples Contact
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 directories required for SATFORM should be created:-

$SATHOME bin
form
overlay
Executable files for external tags and programs (*).
Form template files.
Overlay files (*).

(*) Optional, depending on application.


bin

This directory is only required if external or <run> tags are used.

Note: Only required if external or <run> tags are used.


form

This directory contains the form templates.

These files must contain executable code, and have execute permissons for the application user.

Note: This directory must exist.


overlay

This directory contains the overlay bitmap/macro files.

This directory is only required if overlays are used.

Note: Only required if overlays are used.

Usage

Syntax:satform form data=value data=value ...
formName of form file in $SATHOME/form directory.
data=valueSet 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 ItemReplaced withConversion
${name}john SMITHNone
%{name}John SmithMixed case
+{name}JOHN SMITHUpper case
-{name}john smithLower case

Predefined Data

Data ItemValue
DATECurrent date in format defined by dateformat.

Example:

Assume todays date is 23rd March 2001 and the dateformat is the default (us):

Data ItemReplaced 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:

  1. Command line variables set.
  2. dateformat, include, overlay and label tags.
  3. Variable/predefined/command-line data substitution.
  4. Macros.
  5. All other tags.

NOTE: From step 5, only text between <body> and </body> is processed.


Copyright © 2003
Adrian Davis.