Share Gallery 1/share_gal_1.zip/share_gal_1/LA/LA015.ZIP/DG_DOC.TXT

Text File | 1985-08-15 | 21KB | 508 lines

                     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
    [phone] -- 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 ***