                     dGENERATE Documentation

                   (Version 1.0: August, 1985)
                    (Revised August 15, 1985)

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


dGENERATE is a dBASE III screen and code generator written 
entirely in dBASE III.  The generated code is intended to assist 
rather than replace the application programmer.

dGENERATE produces simple, easy to understand algorithms because 
every programmer's needs are different, and there is no single 
algorithm that will work for everyone.  One of dGENERATE's main 
features is that it is written in dBASE III and can be easily 
modified to generate any algorithm you like.

Due to the variety of algorithms required for applications 
development, we prefer to maintain a library of routines and 
incorporate the generated code with the appropriate routine for 
each application.


RIGHTS:

You are encouraged to freely distribute copies of dGENERATE to 
anyone you choose, as 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 own the generated code just as if you wrote it yourself; use 
it however you like.  You have the right to use portions of 
dGENERATE's source code, either modified or unmodified, in any 
original application of your own that does not directly compete 
with dGENERATE.  We disclaim all liability and make no guarantee.

You are invited to become a registered dGENERATE by sending 
fifteen dollars to us at the above address for which we will send 
you a disk containing the latest version of all the files listed 
below.  Registration also entitles you to full technical support 
by telephone, mail, CompuServe, and the Source.  Only if we have 
you on file can we notify you of updates, bug-fixes, and new 
dBASE-related software.

Registration supports the development and marketing of 
inexpensive software via the "shareware" concept.  Your 
registration makes an important contribution!

We feel that dGENERATE belongs to the entire dBASE community, and 
your feedback is highly valued.  If there is anything you think 
should be changed or added to the next version, please write us 
with your comments.  

The dGENERATE files are:

          Source code: dg_main.prg (7K) and dg_proc.prg (55K)
                         Executes under dBASE III,
                         any version greater than 1.1
      RunTime+ linked: dg.prg (30K)
                         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
                       dg_clip.prg (55K) is the compilable 
                         source code for the Clipper version
             Database: dg.dbf
                         One field 'dg_text', character 254 bytes
        Documentation: dg_doc.txt (20K)
         Announcement: about_us.txt (1K)


INSTALLATION:

"Install" simply means to copy the appropriate files onto your 
working disk.  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, 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 <S>etup 
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.  Your editor's overlay files must be on 
the drive where your editor knows to look for them.

If your system has very little memory, you may get an 
"Insufficient Memory" error message from dBASE when it tries to 
RUN your editor.  To correct this, you can add more memory to 
your system or use the compiled version of dGENERATE which 
requires much less memory than the versions that run under dBASE.


SETUP:

There are thirteen sets of parameters that can be changed in the 
setup module by selecting number six <S>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: Left ':', right ':'
    12.  Marquee line character (ASCII value)
               Default: 61      ('=')
    13.  Filename of editor used to draw screen-forms
               Default: none (uses MODIFY COMMAND)

          dGENERATE relies on the word processing software you 
          assign for all editing tasks.  If you have assigned an 
          editor in <S>etup, dGENERATE will RUN it for all 
          <E>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 
          more versatile editor is highly recommended.

          To use a memory-resident editor such as the one in 
          SideKick, assign "INMEMORY" during <S>etup.  This will 
          prevent the automatic <E>dit after <C>reate.  While at 
          dGENERATE's main menu, call your editor the way you 
          usually do instead of using the <E>dit procedure.  Then 
          save the file, exit the editor, and select <G>enerate 
          to write the code.

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 <S>etup before <C>reating new screen-forms.

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


OPERATION:

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

     1.   <C>reate a new screen-form
     2.   <E>dit an existing screen-form
     3.   <G>enerate code from a screen-form
     4.   <D>O (execute) a command file
     5.   Generate <M>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.

General:

If you are running dGENERATE under regular dBASE III, pressing 
the Escape key will SUSPEND dGENERATE and place you in the 
interactive mode of dBASE III.  Type RESUME to return to 
dGENERATE.  This is useful when you want to create a database 
file or test an expression without exiting and rebooting 
dGENERATE.  If you SUSPEND while in dGENERATE's main menu, you 
must press a key after RESUMing in order to redisplay the menu.

dGENERATE uses only one work area, the current one when dGENERATE 
is entered.  However, because the RUN command is used for 
editing, we recommend that you close all open files before 
executing dGENERATE to avoid the possibility of corrupting them.

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 (around 10K).  The first release of dGENERATE does not 
check for adequate diskspace before creating its temporary files.

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 uses the following names for procedures.  An attempt to 
<D>o 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.

There is a "time-out" feature in dGENERATE.  If you leave 
dGENERATE inactive for three minutes while in the main menu, it 
will clear the screen body and prompt you to press any key to 
re-activate.  If you are in a sub-menu, it will return to the 
main menu.

Option 1: <C>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 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 to assist you in measuring columns 
and placing data.  If the blank-fill flag is on, dGENERATE fills 
the 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: <E>dit a screen-form (or any text) file

If you have specified the form width (columns) in <S>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 all literal prompts 
precisely 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 GET and SAY 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 <S>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: {*--------------------|  State:}S

Memvars may be specified in the definitions table to take the 
place of field names:

     dgDEFINE
     F m_name ~ Name
     9 m_address ~ Address
     * 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
     T TIME()
     D 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 table's example 
syntax:

     dgDEFINE -- Example syntax follows
     <definition symbol> [<memvar> ~] <expression> [PICTURE <phrase>]
     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 <C>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 each 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 <database filename> 
          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, and you specify the characters 
          for each CASE statement on a separate line below the 
          dgMENU declaration.
     dgREPORT
          Writes the algorithm for printed reports.
          Requires use of a database file (can use dgFILE).

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

dgMENU requires allowable characters for each CASE be listed 
without delimiters on a new line directly below the dgMENU 
declaration.  Each line represents the keys that may be pressed 
to select one option from the menu:
     dgMENU
     Aa1
     Bb2
     Cc3
     Qq

dgREPORT writes code that uses the printer.  Be sure your printer 
is on line when using this option or executing the generated 
code.  Maximum form size is 254 columns by 999 rows.  GETs are 
automatically converted to SAYs so that you can re-use screen-
forms originally drawn for data entry.

Option 3: <G>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.  PROW() is used if it is 
declared as a report with dgREPORT.  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: <D>o a command file

"***" appearing in your screen or form means that a variable 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 returning 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 generated screen 
displayed.

If a DO file crashes, select SUSPEND, then type RETURN and 
RESUME.  This 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 or the dBASE interpreter can be called.  None of this is 
automated because the code is likely to be incorporated with 
other code before compiling is desirable.

Option 5: <M>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 field names:

     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 field names.  When CREATing your database 
files, keep significant letters within the first eight letters:

     'Fieldname1' and 'Fieldname2' both generate 'm_fieldnam'
     'Field_1' and 'Field_2' generate 'm_field_1' and 'm_field_2'


TECHNICAL SUPPORT:

Electronic mail on CompuServe or the Source is the best way.  
Regular postal mail is good if your needs are not immediate.  We 
also offer support by telephone, but cannot guarantee that a 
technical person will be available when you call.  However, a 
programmer will return your call the same or following working 
day.  All long distance support calls are returned COLLECT in 
order to keep the price of dGENERATE as low as possible.  
Remember, we only charge fifteen dollars.

Please do NOT call Ashton-Tate or Nantucket for dGENERATE 
support.  They are very busy supporting their own products.


TRADEMARKS:

          Ashton-Tate:  dBASE, dBASE III, RunTime+
              Borland:  SideKick
                  IBM:  PC-DOS
             MicroPro:  WordStar
            Microsoft:  MS-DOS
            Nantucket:  Clipper
Tom Rettig Associates:  dGENERATE


              *** EOF: dGENERATE Documentation ***
