SMALLSYS.TEM

This template is the main driver for the SMALLSYS template
system. Based on what's in the editor at generation time,
it will generate system code that may incorporate Pop-up
menus, scrolling pick-list windows, edit, append and search
windows, pop-up confirmation boxes (e.g. for deletions),
and pop-up help.

There's no single shape to the system SMALLSYS generates: it
depends on the boxes present at generation time, and the
way you've linked them together.

Hold on...what's a link? A is link just a few words you
you put in a box slot, or an option action, to tell SMALLSYS
that something should be done at that point in the system.

First, let's backtrack a little. To SMALLSYS, each box in the
editor represents some piece of the system. A Menu box (a
box with Option boxes inside it) represents a menu, surprisingly
enough. A box with fields in it might represent an Edit or
Append operation; a box with the text 'Delete: are you sure?'
and a logical memvar in it might be for confirming a delete.
Links specify how these boxes are used: if you wanted a menu
option to bring up an edit window on the current record within
a database, you'd put a link in the action for that option.

Okay -- so what exactly does 'put a link in' mean? What's the
syntax, what means what, what's legal? 2 answers:

1. the rest of this doc tells you in detail

2. the example design in USER.WW is a full-featured
example. Load it, look around, and generate using
SMALLSYS.TEM. You'll see what the whole thing is
supposed to do for you. Go do that now. And remember,
when you face that huge jumble of boxes that
USER.WW contains, to use the Depth-O-Scope (from F3:Edit)
to make your like easier. I couldn't have done the
example without it, and for it I thank me.

If you're reading this, you've either generated with USER.WW
or you're the kind of person who reads everything first.
Since most of our customer's don't, I'll assume you've
done the example, and [linked and] run the resulting code.
So, here we go with the specs:


In USER.WW (for example), the top node of the system is a
menu. It contains 3 option boxes, each of which has a link
defined in its option action. The link specifies what the
option should do. Here's what one of those links looks like:

<>

What this means is, "When this option is selected, I want
the system to pop up a Picklist based on the box ULNAME.
By the way, generate the picklist code as a procedure."

(We'll go into detail in a minute, but basically the Picklist
could be a procedure or a module, and specifying it in the
link avoids SMALLSYS asking you which you want.)

Because of this link, SMALLSYS will generate code to call the
picklist for when that option is selected, and it'll also
generate the picklist procedure itself.


Here's another example: In the box ULNAME (the box we
specified in the above option to do a Picklist with)
in USER.WW, there are a few links defined in ULNAME's
slots. One of them looks like this:

Help key 28 box ULISTHELP code PROC

This means: "From this box, pop up the box ULISTHELP as help
whenever inkey value 28 (the F1 key) is hit. Generate the
code as a procedure."

Now, before we go any further, here's the exact syntax of links,
and where and how you specify them.

1. In option boxes, links are specified as part of the option's
action. An option may have at most one link. The link is
surrounded by << and >> to distinguish it from literal
option action code, which may also be given in the option's
action, and, as usual, is written directly into the generated
code. AN OPTION LINK DOESN'T NEED TO SPECIFY A KEY. This
is because an option gets selected based on a specific key
anyway (the option's trigger) -- there's no need to define it
twice. In fact, any key specification in an option link is
ignored.

2. In any other boxes, links are given in the box's slots.
They may appear in any slot, and there may be any number of
them. Within one slot you may put several links if you
separate them with semicolons (;). In box slots, the
links are NOT surrounded by << and >>.

3. Links have 4 clauses. One is mandatory, the other three
are optional. They are:


[key ] [box ] [code ]

where

is the action to take,

is the inkey() value of the key that
provokes the action,

is the name of the box that the act uses
as its object, and

is the type of code to generate.

If any but the parts of a link are unspecified, SMALLSYS
will ask you for them at generation time. (Except for the 'key'
clause in an option's link, which is unnecessary as noted above.)

As you may think, and each have a particular
set of legal values, and the sets vary, depending on the
situation you're in. Let's take each clause individually.


1.

Here's the complete set of action words that Smallsys recognizes.
Two other aspects of a link depend on what the link
specifies.

The first is the -- for most s, the
allowable code types are MODULE and PROC -- module and procedure.
For a few, the link may alternately specify the INLINE code type.
(Allowable types for each link action are specified below.)

The second thing that depends on the action word is whether any
further links are collected from the box specified as the link's
object. For instance, when SMALLSYS sees this link:

Menu key 13 box USTMEN

it will look in the box USTMEN for any links defined there, and
add them to the pile of system links. This is because, obviously,
a Menu within a system will almost certainly provoke further
action. On the other hand, when SMALLSYS sees

Help key 28 box URECHELP

it won't look for any more links, since a Help box doesn't
call anything else. Whether any further links will be collected
from within a link object is also noted below, for each link
type.


Display
- just display the box specified in the link.

The Display box may be any box you can draw in UI --
however, only display code for the box's literal text is
generated. Any fields, memvars, etc, within the
box are ignored.

Allowable code types for Display links are INLINE, MODULE
and PROC.

No further links are collected from a Display box.



Help
- Pop the box specified in the link, wait for a key
to be pressed, pop the box down.

As with Display, the Help box may be any box, but only display
code for the literal text will be generated.

Note that there is no particular significance attached to
the word 'Help' -- it simply means 'popup, pause, popdown'.
A Help link could just as well be used as a signon, or warning,
or whatever.

Allowable code types for Help links are MODULE and PROC.
INLINE may also be used ONLY IF THE LINK IS SPECIFIED FROM
A PICKLIST (see below) -- the reason for this is that, within
a Picklist, SMALLSYS will trigger the help from within
the Picklist code itself, and so in-line code is possible.
From any other code, help is done using SET KEY (in Clipper)
or ON KEY, and so a procedure or module must be called.

No further links are collected from a Help box.


Confirm
- Pop the box specified in the link, @..GET the logical
variable contained in the box, then pop the box down,
passing back the logical value input.

A Confirm box must contain 1 logical memvar. SMALLSYS will
generate display code for the box text, and @..GET code for
the first logical memvar it finds within the box; any other
memvars (or fields) in the box are ignored. If no logical
memvar is present, SMALLSYS will report an error.

Allowable code types for Confirm are INLINE, MODULE and PROC.

No further links are collected from a Confirm box.


Delete
- Delete is synonymous with Confirm. The same action is
generated and the same box rules apply.

Allowable code types for Delete are INLINE, MODULE and PROC.
No further links will be collected from a Delete box.

Example: in USER.WW, the link:

Delete key -3 box UDEL code PROC

appears in two places: once in the box UREC, used by several
parts of the system for Editing and Appending, and once
in an option within the box USTMEN, an 'add/edit/delete/search'
kinda menu. UDEL is the delete box.




Menu
- Pop the specified box and its options; take whatever action
is specified within an option box when one is selected.
Unpop the menu box and return when either an option is
selected or escape is hit, passing back a logical
value representing whether an option was ever selected.
NOTE that the Menu action TERMINATES AFTER 1 OPTION SELECTION.
The Loopmenu action (below) repeats until Escape is pressed,
or an option is selected that has the link <> specified.
<> is a special link that only has meaning within
a Loopmenu box.

The box specified in a Menu link must contain at least one
option box within it. Any fields or memvars within the menu
box are ignored. If the box designated in a menu link has no
options, SMALLSYS will error.

Further links are a little trickier with menu boxes. No
further links are collected from the Menu box itself,
however further links ARE collected from the Menu box's
options, as might be assumed.

The legal links within a menu's option boxes are: <>,
<>, <>, <>, <>, <>,
<>, <> and <>.

Example: in USER.WW, the link:

Menu key 13 box USTMEN code PROC

is specified from the box USTLN. Box USTMEN has several
options defined, with further links.


Loopmenu
- Pop the specified box and its options; take whatever
action is specified within an option box when one is
selected; repeat until escape is pressed or an option is
selected which contains the link <>. <> is
a special link which only has meaning within a Loopmenu
box.

The box specified in a Loopmenu link must contain at least
one option box within it. Any fields or memvars within the
box are ignored. If the box designated in a menu link has no
options, SMALLSYS will error.

No further links are collected from the Loopmenu box itself,
however further links ARE collected from the option boxes
within the Loopmenu box.

The legal links within a loopmenu's option boxes are: <>,
<>, <>, <>, <>, <>,
<>, <> and <>.

Example: in USER.WW, the main menu box of the system, called
UMAIN, is a loopmenu. Since it's the main menu, there is
no link specifying it -- nobody calls the main module in
a system -- but SMALLSYS figures out that it's the main
menu because it has the word MAIN in its name (TOP also
works), and decides it's a menu because it has options
in it. Since it's the main menu, SMALLSYS figures it should
repeat rather than exit after one option execution, so
it's a loopmenu. It contains three options, each of which
specifies a different <> link.




Edit
- Pop the specified box; perform an @..GET/READ on all fields
and memvars within the box (using memvar duplicates for
fields); store field values only if something besides Escape
terminates the READ; unpop the edit box.

The box specified in an Edit link must contain at least one
field or memvar. If there are none, SMALLSYS will report an error.

An edit box may contain Help and Display links. NOTE:
there's only one reason you'd ever specify a Display link.
Display code is generated automatically, whether a Display link
is present or not. But if a box is used many times within a system
(say, if it's used for Edit AND Append operations) you
can force SMALLSYS to generate and use a single procedure that
displays the box, instead of generating in-line display
code in all the procs/modules that use the box. The
way to do this is:

Display box code

Note that the 'key' clause is unnecessary here.

Example: in USER.WW, the box UREC is specified in both
Edit and Append links throughout the system; for example
from the box ULNAME.



Append
- Pop the specified box; perform an @..GET/READ on all fields
within the box using memvar duplicates; store field values
to a new record only if something besides Escape
terminates the READ; unpop the append box.

The box specified in an Append link must contain at least one
field. If there are none, SMALLSYS will report an error.

An append box may contain Help and Display links.
NOTE: there's only one reason you'd ever specify a Display link.
Display code is generated automatically, whether a Display
link is present or not. But if a box is used many times within
a system (say, if it's used for Edit AND Append operations) you
can force SMALLSYS to generate and use a single procedure that
displays the box, instead of generating in-line display
code in all the procs/modules that use the box. The
way to do this is:

Display box code

Note that the 'key' clause is unnecessary here.

Example: in USER.WW, the box UREC is specified in both
Edit and Append links throughout the system; for example
from the box ULNAME.



Search
- Pop the specified box; @..GET into memvar duplicates of
all fields within the box; search for a record containing
match values ONLY FOR FIELD IN WHICH VALUES WERE ENTERED
(i.e. the post-READ value differs from the initial value);
use the indexes specified as active in F5:Local data to
do seeks if values were entered for key fields; repeat
this operation until escape is hit.

The box specified in a Search link must contain at least one
field. If there are none, SMALLSYS will report an error.

A search box may contain Help and Display links; see note on
display links in the Append link spec, above.

Example: in USER.WW, the box USEARCH is a search box; it is
specified in several Search links, for example in the
box USTMEN.


Pick/Picklist
- Pop the specified box (which displays a window full of
items; each representing a record in a database); do
navigation with arrow keys, etc., like a menu; unpop
the box when escape is hit. ALSO, call any actions specified
in the box's links, when the keys specified within those
links are hit.

The box specified in a Picklist must contain at least one
field; there should really be a single row of fields --
the picklists generated by SMALLSYS replicate that row
through the box. For an example that's much clearer than
this explanation, check out the three picklist boxes
in USER.WW -- USTCO, ULNAME and UDATE.

A picklist box may contain any kind of link; Display links
are only necessary if you want to force a Display procedure
or module instead of inline code; see note in the Append
link spec.


Well, that's it for the link s. Here are some notes on the
other parts:


2. : this is a number representing the inkey value
of the key you want the action to be provoked by. For example,
the link

Pick key 13 box ULNAME code PROC

specifies that a picklist based on the box ULNAME be popped up
when a carriage return is pressed.

If is not supplied, SMALLSYS will ask you to press
the key that should provoke the action.

(Remember that links in Option boxes don't need the 'key '
clause.)


3. : this is simply the name of the box you want
the link to use. If is not supplied, SMALLSYS
will ask you to indicate the desired box at generation time.


4. : as discussed above, the legal values of
are different for different link actions, but are usually
PROC (which causes SMALLSYS to generate a procedure) and
MODULE (which generates a separate module). Sometimes
INLINE is allowed for simple link actions; see link action list
above.


A few last notes:

1. Once again: consult USER.WW for real-world examples. While you do,
remember that some of the links are completely specified; this is
done to keep the generation process fairly automatic. If you'd
like to vary the generated result a little, try (for instance)
removing the 'code PROC' clause from a few of the links. SMALLSYS
will now ask you whether you'd like a Procedure or Module (and
in some case Inline code) generated for a particular action,
and, based on your response, generate different stuff.

2. Try screwing around with how the existing objects look. After
all, that's the thing UI makes easiest, and with SMALLSYS handling
the management chores, you can have some fun with Gratuitous
Visual Puffery.

3. Check out the System Cross-Reference. Cool, huh?