STAGE
Copyright (c) Luis Castro 1989-90.
STAGE is a trademark of Software Tools Development Corp.


STAGE FEATURES:

STAGE is the most powerful Screen Design Tool and Application
Generator available for dBASE IV and its clones. It blows away
UI2, Genifer, dBASE IV's dGEN, FoxPro's FoxView, and all the
rest. The current version supports:

o Clipper, Summer '87
o FoxPro, version 1.0

It will support dBASE IV when version 1.1 is released, Clipper
5.0 when its released, and dBXL and QuickSilver when dBASE
IV-compatible versions are released.


Three Most Significant Features:

Three significant features in STAGE deserve to be mentioned from
the very start:

1. APPLICATION SIMULATION. You can link STAGE fields, windows,
pages, and tables in various arrangements--a field can be
linked to a window or page or table, a window can be linked to
another window or page or table, etc. Once the desired
linkages are set, you can navigate through this custom
application tree in STAGE. Thus, the entire application can be
simulated or prototyped, without entering one line of dBASE
code.

One benefit to this feature is that you can DEMO the
application to your client before entering any custom code.
Any major adjustments recommended by the client can be done
easily, since no custom code is involved. Also, you can have
the client sign-off on the DEMO, and pay you for the prototype
(possibly, one-third of the total job estimate).

2. APPLICATION BUILDING BLOCKS. The most common database
operations, such as ADD, EDIT, DEL, SEEK, etc., are now part
of a set of library primitives or code segments. These code
segments can be assigned to menu options in any mix-and-match
arrangement. This allows very custom screens to be designed
with a minimum of effort. Simply declare menu item objects
inside a MENU window and give them formula names, such as ADD,
EDIT, etc.

Also, custom code can be embedded before or after these code
segments to control the type of behavior these routines will
perform.

3. CUSTOM MODIFICATIONS. Custom code can be inserted in string
attributes and embedded in the application at generation time.
The insertions are made by use of the STAGE full-screen
editor, and can be as large as 64K per string. These
insertions are made in strategic places in the STAGE table.

The significance of being able to embed custom code right in
the form definition should not be overlooked. It means that
all DESIGN work and custom CODING can be done entirely within
STAGE. The only time you need to leave STAGE is to generate
the code and run it in dBASE IV or one of the clones.

When a BUG is encountered in the generated program, it will
most likely be in your custom modifications. But, since the
custom modifications are saved as separate text files by
STAGE, you simply load the text files in your favorite program
editor and make the changes there. Finally, you regenerate the
affected program modules. You never modify the final generated
code.

IMPORTANT: STAGE has a built-in MAKE feature, so you don't
have to remember which modules to regenerate; STAGE
determines, based on what you have modified, what modules to
regenerate for you. It's that easy.

The point is this, you maintain the flexibility and dynamic
nature of application development when the application is
defined entirely within STAGE:

(a) If the customer needs the screens to be changed,
the custom code insertions do not have to be
reinserted, because they are part of the design.

(b) Since the bulk of database operations are defined
as standard library code segments, such as ADD, EDIT,
DEL, etc., the only code you have to be concerned with
are the code insertions you specified in STAGE.

(c) Since these code insertions are saved in separate
text files, they can be modified in a program editor
without involving the bulky, standard code that
usually surrounds custom insertions.

Thus, STAGE involves fewer steps, less code exposure, easier
maintenance, and faster debugging.


STAGE blows away the competition:

FoxView UI2 STAGE FEATURES
======= === ===== ========================================

SCREEN PAINTER:
yes YES YES Color support
no YES YES Window support
no yes YES Application Simulation
no yes YES Virtual screen (255x255)
no yes YES Custom code insertions
no no YES String editor (64K per string)
YES no YES Multiple pages
YES no YES Table and Shell Views

APPLICATION GENERATOR:

YES YES YES File maintenance (Add,Edit,etc.)
no YES YES Pull-down menus
no YES YES Pick-list windows
no YES YES Multiple product support
no YES YES Multi-file RELATIONAL support
no YES YES Table/Screen documentation
no yes YES Multi-user support
no no YES Browse windows
no no YES LIST windows (*)
no no YES SHOW windows (**)
no no YES MEMO windows (***)
no no YES Explode/Implode/Shadow windows
no no YES Error trapping
no no YES Sound effects
no no YES Expression builder
no no YES Variable cross-reference
no no YES "DO prgfile" tree structure
no no YES OVERLAY .LNK file builder
no no YES Built-in MAKE and MAKEFILE generator
no no YES R&R (Relational Report Writer) support

TEMPLATE LANGUAGE:
value value BOTH Parameters: pass by Value or Reference
YES YES YES INCLUDE file support
no yes YES LIBRARY support (pre-compiled)
no no YES Read/write/process TEXT files
2048 155 2048 User-defined functions (UDF's)
21 20 60 Field attributes
14 23 34 Datafile/index/relation attributes
7 12 32 INPUT/OUTPUT/SYSTEM functions
18 26 26 String functions
10 ? 16 Datafiles per form
10 8 16 Indexes per datafile
10 8 16 Relations per datafile
0 0 8 Array support: achoice,acopy,adel,etc.

(*) SHOW windows can be defined in either EDIT or BROWSE screens.
They can contain any information, but usually they are used to
display field data from related datafiles.

(**) LIST windows can be defined in EDIT screens. They display
field data from related datafiles in a BROWSE format.

(***) MEMO windows display memo field information in a window.


STAGE TEMPLATES:

The STAGE screen painter is supplied with a template system
designed to generate complete, custom applications with the use
of STAGE tables. This template system is called "AM" for
Application Modules. To run the template system on a STAGE table,
use the BATCH file AM.BAT and from DOS type:

AM /* to generate application

NOTE: We recommend that you set a PATH to the STAGE sub-directory
containing the AM files. See your DOS manual for a more detailed
description of PATH. In general, the DOS PATH command is entered
in the AUTOEXEC.BAT file in your root directory. Assuming STAGE
is in drive C, in the sub-directory called STAGE, and Clipper is
also in drive C, an example line to enter in AUTOEXEC.BAT would
be:

PATH=C:\CLIPPER;C:\STAGE

Thus, you are able to run STAGE and the AM template system from
any sub-directory in your computer.


THE FIRST RUN:
==============
Since we are learning a new way of writing programs, let's begin
with a simple application. Consider the following:

CUSTOMER NEEDS:
1. Customer has a datafile called NAMES.DBF.
2. He needs a File Maintenance application for NAMES.DBF,
which must include: Add, Edit, Del, Goto, etc.

ASSUMPTIONS:
1. You have installed STAGE in STAGE sub-directory.
2. You have Clipper, Summer '87 (or FoxPro 1.0)
3. You have set a PATH to the STAGE sub-directory.
4. You have created a working sub-directory, such as APPS,
and have copied the datafile NAMES.DBF to it.
5. You are now in the APPS sub-directory.

YOU DO:
1. type: STAGE (from the APPS sub-directory).
2. type: USE NAMES (from the Shell in STAGE).
3. type: LOAD MENUS WINDOW 1
4. type: (Hold CTRL key and press ENTER once).
5. type: (Hold ALT key and press the letter "Q").
6. type: AM NAMES (from DOS)
7. type: (press ENTER twice, one after each prompt).
8. type: START
(this will compile NAMES.PRG using CL.BAT)
(or with FoxPro, runs the generated application)

YOU DELIVER:
1. NAMES.DBF
2. NAMES.EXE (or NA*.PRG if they have FoxPro)

YOU RECEIVE:
1. Praise.
2. Money.

Of course, this example says nothing about all the many
enhancements that can be made to the screen design, including:
PICTURE clauses, color, boxes, index files, etc. And, it says
nothing about all the available options at code generation, such
as exploding windows, sound, multi-user code, etc.


Beginning User:
===============
At this point, you have already generated a simple application in
the steps shown above, and have become familiar with getting in
and out of STAGE and the AM template system. Let's now proceed to
the beginner level.

We classify the beginning user as being able to do the following:

Beginning User's Abilities in STAGE:

o Thoroughly familiar with STAGE navigation
o Design EDIT screens with text, color, and boxes
o Design multi-page EDIT screens
o Can DRAG fields and SIZE boxes
o Can add PICTURE, RANGE, etc. clause information
o Can setup simple database information, including index
names, and key expressions.


Intermediate User:
==================
At the Intermediate User Level, you have already generated EDIT
applications using STAGE and the AM template system. You are
thoroughly familiar with STAGE navigation, entering PICTURE
clauses, and entering datafile and index information.

Intermediate User's Abilities in STAGE:

o Design BROWSE and MENU screens
o Can create and manipulate window objects
o Can change STAGE/AM configuration parameters
o Can add Validation and PICKLIST information
o Can setup database information containing indexes and
relations.
o Can link various tables and perform application simulation.


ADVANCED USER:
==============
At the Advanced User Level, you have generated at least one
BROWSE, EDIT, and MENU application using STAGE and the AM
template system. You are thoroughly familiar with STAGE
navigation, entering any and all available Table View attributes,
and entering datafile, index, and relation information.

Advanced User's Abilities in STAGE:

o Familiar with the format of generated programs.
o Can insert custom code inside a STAGE table using the
F2=EDIT feature.
o Has learned the STAGE template language.
o Can modify existing AM template system, to include
permanent custom modifications.


STAGE navigation:

In STAGE, you should first learn to navigation through the
different screens. The following chart describes the navigation
keys:

Keystroke Description
--------- -----------
Anywhere:
Esc Menu system
Alt-Q Quit STAGE
F1 Context-sensitive Help
F2 Full-screen edit on string attributes
F9 File View (Database, Index, Relation files)
F10 toggle between Forms and Table Views
ScrollLock DOS Shell View; Table attributes.

Forms View (F10):
Navigate around fields
Navigate around virtual screen, when page
width is greater than 80 and page length
(decimal) is greater than 25.
Ctrl-N New field object
Ctrl-U Delete object
Alt-B Box create
Alt-C Center object
Alt-K Keypad mapping
Alt-O Open/close window
Alt-P Palette of colors
Alt-T Toggle label around field
Alt-W Window create
Alt-F1 Transfer to previous object
Alt-F2 Transfer to next object
F1 Help
F3 Drag objects
F4 Size objects (fields, boxes, windows)
F5 Resequence by row or column
F6 Extend select
F7 Move fields to another window
F8 Copy fields
GrayPlus Forward to window
GrayMinus Backward to window

Table View (F10):
Ctrl-Home Table "control" panel selector
Tab Right panel (or Ctrl-Rightarrow)
BackTab Left panel (or Ctrl-Leftarrow)
Ctrl-N New field object
Ctrl-U Delete object
F1 Help
F2 Full-screen edit on string attributes
F5 Resequence by row or column
F6 Extend select
F7 Move fields to another window
F8 Copy fields
GrayPlus Forward to window
GrayMinus Backward to window

File View (F9):
Move among file attributes
Ctrl-U Delete object
F1 Help
F2 Full-screen edit on string attributes
F7 Move objects around
F8 Copy objects
Tab Move forward to Indexes and Relations
BackTab Move backward

Shell View (ScrollLock):
F1 Help
Uparrow Previous commands and edit
PgUp Display previous Shell pages


The F2=EDIT feature:
--------------------
The F2=EDIT feature deserves special discussion. When the F2
function key is pressed on a blank string attribute, STAGE will
insert in the attribute, a text filename with the filename
format:

.FILENAME.EXT

Immediately after this, STAGE will load the editor, specified in
the STAGE.CFG file, and perform a full-screen edit on the text
file. Once inside the editor, you will typically enter dBASE
commands. Anytime after this, F2 can be pressed on this
attribute, and the editor will be invoked on this text file.

The dot (.) in front of the filename is very important. It is a
signal to STAGE that this is a reference to a text file. You can
also enter your own text file reference in any string attribute,
and take advantage of this feature.


Required TABLE filename format:
-------------------------------
AM requires that each STAGE table have the following filename
format:

TTXXXX.sw

Where, TT are any two characters identifying the application or
system, and XXXX is the unique four character name of a table in
the system.

Begin all STAGE tables with the first two characters of the
application name, and follow with four descriptive characters.
For example, if you are designing a CHIROPRACTIC SYSTEM, you
might use the characters, "CS," as the first two characters for
each table. Thus, you might have tables:

CSMENU
CSINFO
CSPATS
...etc...

AM will generate the programs based on the table names. It
separates the first two characters from the trailing characters
and inserts an underscore. Thus, the programs generated will be:

CS_MENU.PRG
CS_INFO.PRG
CS_PATS.PRG
...etc...


MOVING fields to windows:

In STAGE, there are two ways of moving fields into windows, one
in Forms View and one in Table View.

(a) Moving fields to windows in Forms View:

1. Assume you already have fields in Forms View.
2. Create a window with Alt-W, drag and F4=SIZE to your liking.
3. Move to the fields on the screen, and extend SELECT=F6 the
ones you want to appear into the window.
4. Press the F7=MOVE key, but do NOT press the ENTER key yet.
5. Press the GrayPlus key until the cursor is positioned to the
window you want to move the fields to.
6. Now, press the ENTER key.

(b) Moving fields to windows in Table View:

1. Assume you already have fields in Forms View.
2. Assume you already created a window in Forms View.
3. Go to the Table View (press F10).
4. Pan to the Display panel in Table View.
5. Go to the WIN column.
6. Change the values of each field from zero to the window
number of the window you want the fields to move to.


Creating MENU screens:

You are able to design custom menus with STAGE. At this time, you
may want to enter STAGE and load the table, EZMENU.SW. From the
Shell View, type:

LOAD ezmenu /* simple main menu
or LOAD oemenu /* pull-down menu

Then, press F10 to view the menu. A minimum of the following
conditions must exist for the AM template system to generate a
complete menu program:

MENU screen requirements:
-------------------------
1. The STAGE table FORMULA attribute must contain the word,
"MENU". To do this, press ScrollLock twice and enter in the
FORMULA attribute the word, "MENU".

2. There must be a WINDOW that has the word "MENU" in its FORMULA
attribute in the Table View.

Optionally, the type of menu can be specified in the window's
FLAG attribute. The available menu types are: SIMPLE, HILITE,
BRIGHT, and LITEBAR. If no menu type is specified, the menu
type LITEBAR is assumed.

3. Menu items must exist inside the MENU window. These are text
objects declared as menu items by entering the letter "I" in
the field SUBTYPE attribute in the Table View.

Optionally, menu items can point to windows that become POPUPs
in a pull-down menu screen. To point to these POPUP windows
set TTY (transfer type attribute) to "WIN" and TRANSFER
(transfer name attribute) to the FIELD name of the window.

4. (Optional). If menu items reference POPUP windows, each of the
POPUP windows must also contain menu items. However, the POPUP
windows do not need to have formulas.

Additionally, menu items can contain the following attribute
information:

5. A FORMULA can be entered for each menu item. These were listed
earlier under the FORMULA column in the Table View attributes.
Such formulas as: ADD, EDIT, SEEK, etc.

6. INITIAL and FINISH dBASE commands can be entered for each menu
item. These commands are executed before (Initial) the FORMULA
routine is executed, and after (Finish) the FORMULA has ended.

For example, if the menu option transfers to another table,
such as CSINFO, you may wish to initialize a memory variable,
such as:

isprinter=.F.

A list of dBASE commands can be entered in each attribute by
separating the commands with semicolons (;). For example:

isprinter=.F.;isdata=.F.;CLEAR

Alternatively, you can enter an entire section of code by
using the F2=EDIT feature on a blank string attribute in
STAGE's Table View.

7. Transfer information for each menu item. In the Table View,
enter the transfer type and name of lower-level tables to
transfer to. For example,

Field SUB FORMULA ... TTY TRANSFER
----- --- ------- --- --- --------
Edit I [do ] ... TBL [csinfo]
Browse I [do ] ... TBL [csbrow]
Reports I [do ] ... TBL [csrepo]

Thus, in the generated program, when the menu item called
REPORTS is selected, transfer will be made to the module
generated for CSREPO.SW.

In STAGE, application simulation is achieved with the use of
this transfer information. To activate, in Forms View position
the cursor to a menu item that has transfer information and
press Alt-F2 to transfer forward. This will cause STAGE to
load and display the next table specified in the TRANSFER
column. To transfer back, press Alt-F1. Any changes made to
the original table is saved before the transfer is made to the
new table.

8. (Optional). Enter the TRIGGER character or key constant that
must be pressed to activate the menu option when the generated
program is running. For example, if the menu option is QUIT,
the trigger character may be the letter "Q" or the key
constant ESC. If no trigger character is specified, AM will
use the first character from the Label string as the trigger
character.

The available key constants are declared in the AMGLOBS.GEN
template, and include: UParrow, DOWNarrow, LEFTarrow,
RIGHTarrow, HOME, ENDkey, PgUp, PgDn, CtrlLeft, CtrlRight,
CtrlPgDn, CtrlPgUp, CtrlHome, CtrlEnd, Esc, Enter, Del, and
CtrlEnter.

9. (Optional). When using Clipper, you can enter HELP window
information for each menu item. To do this, create a window
and give it a formula name of "HELP". Then, for each menu item
enter help information under the HELP attribute in the Table
View (Enhancer Attributes panel). This help information can be
a single line, or multiple lines by separating the lines with
semicolons or by using the F2=EDIT feature.


Creating BROWSE screens:

You are able to design custom BROWSE screens with STAGE. At this
time, you may want to enter STAGE and from the Shell View, type
the following:

LOAD oebrow

Then, press F10 to view the BROWSE screen. A minimum of the
following conditions must exist for the AM template system to
generate a complete BROWSE program:

BROWSE screen requirements:
---------------------------
1. The STAGE table FORMULA attribute must contain the word,
"BROWSE". Press ScrollLock twice and enter the word "BROWSE"
in the Formula column.

2. There must be a WINDOW that has the word "BROWSE" in its
FORMULA attribute in the Table View (F10).

The browse window must contain at least one field of the
declared datafile from workarea "A" in File View. Fields from
other workareas may be included, but the driving datafile must
always come from the "A" datafile in File View.

These fields may be placed in any order in the window. (It is
assumed you already know how to MOVE fields into a window in
either Forms or Table View.)

AM determines the width of the column for each field by
selecting the larger of the field LABEL or field DISPLAY
WIDTH. A PICTURE clause is used for each field if specified in
the PICTURE attribute; otherwise, a default picture clause is
used.

If a calculated expression is specified in the CALC field
attribute, the calculation is used in the display instead of
the FIELD value.

3. A MENU must be declared. Usually, it is placed at the bottom
of the screen.

The MENU is a window declared as a MENU by entering the word,
"MENU," in the FORMULA attribute in Table View. The TYPE of
menu for a BROWSE program always defaults to BRIGHT.


ORDER ENTRY SYSTEM:
-------------------
Now, for a simple "real-world" example to illustrate how the AM
template system works.

Assume you need to develop an ORDER ENTRY application that begins
with a main menu, and from this main menu the user can branch to
an invoice screen which contains header information for an
invoice. Then, from this invoice header screen, the user branches
to a line item screen in which he can enter invoice line items.

The STAGE tables involved are: OEMENU.SW, OEORDR.SW, and
OELINE.SW. OEMENU is the main menu, OEORDR is the invoice header
screen (defined as an EDIT screen), and OELINE is the invoice
line items screen (defined as a BROWSE window). Thus,

OEMENU (main menu)

> OEORDR (edit screen)

> OELINE (browse screen)

For your convenience, the above STAGE tables are included in your
STAGE sub-directory. To view these tables, simply type:

STAGE oemenu /* view the OEMENU.SW table

To navigate to the lower-level tables, in Forms View move the
cursor to the appropriate menu or submenu item, and press Alt-F2.
To navigate back to the previous table, press Alt-F1.

To generate the application, type:

AM oemenu /* to generate application