dGENERATE Documentation

(Version 1.0: August, 1985)

Copyright 1985, Tom Rettig Associates, All Rights Reserved
9300 Wilshire Boulevard, Suite 470, Beverly Hills, CA 90212
(213)272-3784 -- CompuServe: BCR480 -- Source: 75066,352


RIGHTS:

You are encouraged to freely distribute copies of dGENERATE to
anyone you choose,Es long as you do not charge for it and the
original copyright notice and registration information remain
intact in both the code and documentation.

You have the right to use portions of this code, either modified
or unmodified, in any original application of your own that does
not directly compete with dGENERATE.

You are invited to become a registered dGENERATE by sending
fifteen dollars to us at the above address. Registration
supports the development and marketing of inexpensive software
via the shareware concept. Your registration matters!


INSTALLATION:

The dGENERATE files are:
Source code: dg_main.prg (55K) and dg_proc.prg (7K),
executes under dBASE III,
any version greater than 1.1
RunTime+ linked: dg.prg (25K)
Executes under dBASE III,
any version greater than 1.1 or dBRUN
Clipper compiled: dg.exe (160K)
Executes under MS- or PC-DOS,
version 2.0 or higher
Database: dg.dbf
One field 'dg_text', character, 254 bytes
Documentation: dg_doc.txt (16K)

You only need to install the file or files that you will use. If
you want to run source code, install both the main and procedure
files. If you want to run the linked file, only install dg.prg.
If you do not have a copy of dBASE III later than version 1.1, or
want to run the fastest version and do not care to execute the
generated code, install only dg.exe. All versions of dGENERATE
use the dg.dbf system database file. Once you have printed a
copy of this documentation file, you do not need it on your disk.

Hard Disk:

This is the easiest way to use dGENERATE. Set your operating
system "path" to the directory where dBASE III is installed (see
your operating system manual). Now you can call dBASE from
anywhere. Once in dBASE III, SET PATH TO the directory where
dGENERATE is installed. Now you can use dGENERATE from anywhere
that you can call dBASE. The files created by dGENERATE are
always in the local directory.

The editor (word processing software) you specify during setup
must be accessible from the current directory from which you
entered dBASE III. Your editor must be able to find its overlay
files when called from this directory. If it works from the
operating system prompt where you enter dBASE, it should work in
dGENERATE.

Floppy Disk:

One method is to place a copy of both dGENERATE and your editor
on a separate disk which is placed in drive B and used as your
development disk during the application's implementation.

The other method is to create a new dBASE III System Disk Two.
If enough of the optional files are removed from System Disk Two,
both your editor and dGENERATE can be placed on it in drive A.

In either of these floppy schemes, both the DOS file
"Command.com" and the dBASE III overlay file "Dbase.ovl" must be
on the disk in drive A, and your editor's overlay files must be
on the drive where your editor will look for them.


SETUP:

There are thirteen sets of parameters that can be changed in the
setup module by selecting number six etup on the main menu.

1. Characters that denote SAYs and GETs in a screen-form.
Default: SAY '}', GET '{'
2. Character that denotes memory variable in a screen-form.
Default: '~' (the tilde)
3. Size of screen-form in rows and columns.
Default: 24 rows, 80 columns
4. Relative or literal addressing in @ coordinates.
Default: Literal
5. Add the ruler line in screen-form or omit.
Default: Add
6. Set delimiters on or off.
Default: Off
7. Fill new screen form with blanks or omit.
Default: Omit
8. Display help screens or omit.
Default: Display
9. File extensions created by dGENERATE.
Default: Screen-form '.dgS' (Screen-form file),
generated code '.dgP' (Program file),
generated memvars '.dgM' (Memvar file)
10. Ruler line characters.
Default: Column zero '0',
every ten columns thereafter '123456789.'
11. Delimiter characters.
Default: L.t ':', right ':'
12. Marquee line character (ASCII value)
Default: 61 ('=')
13. Filename of editor used to draw screen-forms.
Default: none (uses MODIFY COMMAND)
Note: You can also specify WP in Config.db to
assign an editor.

The "parameters line" is made up of these values and can be saved
in the system database file. Part of the parameters line is
stored in each newly created screen-form file to tell dGENERATE
what parameters to use in generating code from each screen-form.

Change parameters in etup before reating new screen-forms.

Change parameters in existing screen-forms by diting the
parameters line in the screen-form itself.


OPERATION:

dGENERATE performs five distinct operations, each of which ca{ be
called from the main menu.

1. reate a new screen-form
2. dit an existing screen-form
3. enerate code from a screen-form
4. O (execute) a command file
5. Generate emory variable code from a database file

Some operations are called automatically from other operations.
For example, if you create a new screen-form, you are
automatically placed in it for editing. Code is automatically
generated after editing a screen-form, and newly generated
command files are automatically executed by Do.

General:

If you are running dGENERATE under regular dBASE III, pressing
the Escape key will automatically SUSPEND dGENERATE and present
you with the dot prompt for interactive use of dBASE III. Type
RESUME to resume execution of dGENERATE. This is useful when you
want to create a database file or test an expression without
exiting and rebooting dGENERATE.

dGENERATE uses only the current work area. dGENERATE variables
all begin with 'dg_' or dl_' to avoid confusion with other
variables on which you might use dGENERATE. Avoid naming memvars
or fields beginning with 'dg_' or 'dl_' to prevent any conflict
with dGENERATE.

dGENERATE creates temporary files during code generation, but
erases them when finished or if aborted properly. These are not
big, using one 255 byte record for each line in a screen-form,
but there must be room on the default disk for this file and its
index file. The first release of dGENERATE does not check for
adequate diskspace before creating its temporary files.

dGENERATE uses the following names for procedures. An attempt to
DO a command file of the same name will have unpredictable
results. Avoid the use of these names for screen-forms: abort,
alt_file, config, crea_new, doer, editor, file_msg, fileprmt,
generate, gen_entr, gen_menu, gen_rprt, helper, hlp_crea,
hlp_doer, hlp_edit, hlp_gene, hlp_mgen, hlp_setu, hlp_togl,
key_time, line_inc, marquee, mem_gen, pars_lit, pars_var, setup,
set_if1, set_if2, set_if3, wait_msg, and write.

Option 1: reate a new screen-form

dGENERATE places several items in a new screen form to set it up
for your use. To understand these, we must first define the
{parts of a screen-form. Every screen-form has three parts, the
header, the body, and the footer. The body or "screen" is where
you draw your screen or form. The header contains the ruler
line, and the footer contains the variable definitions, code
generating options, and parameters line.

If the ruler-line flag is on, dGENERATE places a ruler on the
first line in the screen-form for ease in measuring columns and
placing data. If the blank-fill flag is on, dGENERATE fills the
screen part (body) of the screen-form with blank spaces. If you
reply that you want to add memvars from a database file when
prompted, dGENERATE places the appropriate names in the
definition table in the footer.

Option 2: dit a screen-form (or any text) file

If you have assigned an editor in etup, dGENERATE will RUN it
for all diting operations. If not, dGENERATE will call MODIFY
COMMAND which will run either the built-in dBASE III word
processor or the editor that has been assigned to WP in
Config.db. Because the built in dBASE III word processor wraps
all lines at the 67th column and provides no way to disable this
feature, it is most inconvenient for drawing screen-forms. The
use of a fully-featured editor is highly recommended.

If you have specified the form width (columns) in etup, the
ruler line will be that exact width. Because it is the first
line in the file, most editors will be positioned to it upon
entering. Many editors allow you to set the working margins from
any line on which the cursor appears. In WordStar, for example,
you can set your working margins to the proper screen-form width
by pressing Ctrl-OF (^OF) when the cursor is on the ruler line.

You draw your screen form by writing out all literal prompts
where you want them to appear. Variables to be displayed with
either a SAY or a GET are identified by the SAY or GET symbol
immediately followed by a single character definition symbol of
your choice. For example:

Name: }a
Address: {b
City: {c

The SAY and GET symbols '{' and '}' cannot be used for anything
else. If you need to use them in the screen-form for something
else, change the symbols first in etup. The definition
symbols 'a', 'b', and 'c' are defined in the definitions table
below the screen body:

dgDEFINE
a Name
b Address
c City

If you want to have a better idea of what your screen or form
will look like while you are drawing it, you can follow the
definition symbol with any combination of characters. All
characters immediately following a definition symbol are ignored
until a space is encountered. For example:

Name: }Full_name_goes_here--------------
Address: }9300_Wilshire_Boulevard,Suite_470
City: }B--------------------| State:}S

And memvars may be specified in the definitions table to take the
place of fieldnames:

dgDEFINE
F m_name ~ Name
9 m_address ~ Address
B m_city ~ City
S m_state ~ State

The definitions table may simply contain expressions instead of
variables unless a GET is being used on that symbol:

dgDEFINE
* TIME()
& DATE()
$ SPACE(20)

PICTURE and FUNCTION phrases may be added and there are no
restrictions about spacing other than beginning with the
definition symbol in the first column and placing all definitions
in the "definition table." {The definition table begins with the
word 'dgDEFINE' on a line in the first column. The next line is
an example syntax of a definition. All definitions are placed
one per line immediately following the definition syntax:

dgDEFINE -- Example syntax follows
[ ~] [PICTURE ]
1 "All definitions go here"
2 m_var ~ "and here" PICTURE "AAAXAAAA"
3 "and so on..." FUNCTION "!"
a "Note that lowercase and"
A "uppercase are different symbols."

If you answered that you want memvars added from a database file
during the reate a screen-form process, the definition table
will look like this:

dgDEFINE
m_name ~ Name
m_address ~ Address
m_city ~ City

You simply add the definition symbol that you use in the screen
body to the first column of each definition. You can also add
PICTURE or FUNCTION clauses and && comments if desired:

dgDEFINE
1 m_name ~ Name FUNCTION "!" && uppercase key expression
2 m_address ~ Address
3 m_city ~ City

All definitions must fit on one line, and cannot be continued
with a semicolon. Leave a blank line after your definitions are
completed.

dGENERATE options are dgFILE, dgENTRY, dgMENU, and dgREPORT.
Options can be declared anywhere in a screen-form as long as they
begin a line in the first column. Only one dgFILE may be
declared in a screen-form. If more than one is declared, only
the first will be used. Only one of the dgENTRY, dgMENU, or
dgREPORT options may be declared. If more are declared, only the
first in this order of precedence will be used: dgENTRY, dgMENU,
dgREPORT.

dgFILE
Writes the code for opening and closing a database file.
dgENTRY
Writes the algorithm for data entry or edit.
dgMENU
Writes the algorithm for menu driven user selections.
Uses INKEY() algorithm, specify characters for each
CASE statement on a separate line below dgMENU.
dgREPORT
Writes the algorithm for printed reports.
Requires use of a database file (can uoge dgFILE).

dgFILE requires only the filename, not the DBF extension:
dgFILE Names

dgMENU requires acceptable characters for each CASE be listed
without delimiters on a new line directly below the dgMENU
declaration:
dgMENU
Aa1
Bb2
Cc3
Qq9

dgREPORT writes code that uses the printer. Be sure your printer
is on line when using this option. Maximum form size is 254
columns by 999 rows. GETs are automatically converted to SAYs.

Option 3: enerate code from screen-form

Sit back and relax while dGENERATE does the work. Part of the
code written is to initialize a variable called 'undefined' with
three asterisks. This prevents a generated program from crashing
when a memvar initialization is overlooked.

If the relative addressing flag is on, dGENERATE will write the @
coordinates using the ROW() function. If it is declared as a
report with dgREPORT, PROW() will be used. Only ROW() and PROW()
are generated as functions, and literal addresses are used in
place of COL() and PCOL() regardless of the flag status.

Option 4: o a command file

"***" appearing in your screen or form means that you are using a
variable that has not been properly defined or initialized.

When DOing a newly generated command file, dGENERATE displays the
screen and then does an invisible WAIT before {eturning to the
Main Menu. This is necessary in order to see the results of your
screen-form, but provides no prompt to press a key unless you
have included one in your screen. Remember to press a key to
return to the menu after you have seen your screen displayed.

If a DO file crashes, SUSPEND, RETURN, and RESUME will place you
back in dGENERATE's Main Menu.

This option is not available in the compiled version of dGENERATE
because the generated dBASE code needs a dBASE interpreter to
run, or it must be compiled first. The compiled dGENERATE offers
access to DOS in this place where the generated code can be
compiled if desired or the dBASE interpreter called. None of
this is automated because the code is likely to be incorporated
with other code before compiling is desirable.

Option 5: ake memvars from fields

Just give dGENERATE the name of a database file, and it will
create memvar names from the field names and write initialization
and REPLACE commands.

Two kinds of initialization statements are generated. One from
the fieldnames:

m_name = Name
m_start_da = Start_date
m_amount = Amount

The other from expressions:

m_name = SPACE( 35)
m_start_da = CTOD(" / / ")
m_amount = 0000.00

The REPLACE statements:

REPLACE Name WITH m_name
REPLACE Start_date WITH m_start_da
REPLACE Amount WITH m_amount

This code is not intended to run as it stands. It is meant to be
incorporated into the code that you write for each application.

Note that the memory variable names only use the first eight
characters of the fieldnames. When CREATing your database files,
keep significant letters within the first eight letters:

'Character1' and 'Character2' both generate 'm_characte'
'Char_1' and 'Char_2' generate 'm_char_1' and 'm_char_2'


*** EOF: dGENERATE Documentation ***