Programmer 7500/MAX_PROGRAMMERS.iso/PASCAL/DATAGE.ZIP/DG.DOC

Text File | 1989-02-15 | 51.8 KB | 1,976 lines

                                The DataGen Kit
                             USER REFERENCE MANUAL

                           Version 2.02 January 1989
                      (C) Copyright 1989 by Tika Software.
                              All Rights Reserved

                                 Tika Software
                                112 Village Path
                               Lakewood, NJ 08701
























────────────────────────────────────────────────────────────────────────────────

                                   DISCLAIMER

     Tika Software makes no representation or warranties with respect to
     the contents hereof and specifically disclaims any implied warranties
     to the suitability of this program for any particular purpose. You
     must determine that yourself. In addition, you should understand that
     using a program of this type on an IBM PC or compatible has inherent
     risks and that you may inadvertently damage or destroy valuable pro-
     grams or data. Tika Software expressly declines to assume liability
     for any use of this program by you, and your use of this program con-
     stitutes your agreement to hold us blameless. Tika Software reserves
     the right to make changes from time to time in the context hereof
     without obligation to notify any person or persons of such changes.

                                   TRADEMARK

     MS-DOS is a registered trademark of Microsoft Corporation.
     PC-DOS is a registered trademark of IBM Corporation.
     Turbo Pascal and Turbo Database Toolbox are registered trademarks of
     Borland, Intl.
     BTRIEVE is a registered trademark of SoftCraft, Inc.





































────────────────────────────────────────────────────────────────────────────────







                           DataGen Table of Contents

     Introduction.........................................................1
     The DataGen Theory...................................................1
     Why Use DataGen?.....................................................1
     Mastering DataGen....................................................2
     A Recipe for Instant DataGen Applications............................2
     Explanation of Terms.................................................2


     ScreenGen............................................................4
     Command Syntax.......................................................4

     Overview.............................................................5
          Syntax...............................................................5
          Output...............................................................5

     Reference Guide......................................................7
          File Specification...................................................7
          Command Structure....................................................7
          Screen Definition Section............................................7
          Global Definition Section............................................8
          Variable Definition Section.........................................13

     ScreenGen Sample Screens............................................15


     DataGen.............................................................18
     Overview............................................................19
          Syntax..............................................................19
          Output..............................................................19
          Editing Turbo Source................................................20

     DataGen Reference...................................................21
          File Specification..................................................21
          Command Structure...................................................21

     Appendix A) Description of IO.TPU...................................23














────────────────────────────────────────────────────────────────────────────────


     Introduction

     DataGen enables the Turbo Pascal programmer to generate single screen
     -- single datafile database applications quickly, efficiently, and
     with a minimum of programming expertise. Developed with the simple ap-
     plication in mind, DataGen facilitates rapid creation of such programs
     as mailing, client and sales lists.


     The DataGen Theory

     Many database generation systems presume that the datafile is the cen-
     tral component of the database application. While this is often the
     case in relational databases which manipulate several files, it com-
     plicates the process of creating simple list applications.

     DataGen follows the premise that the Data Entry Screen is the pivotal
     component of a database application, effectively mirroring the struc-
     ture of the datafile. From a simple ascii screen definition file,
     DataGen creates a full-function database, storing the items of the
     data entry screen as fields in the database.


     Why Use DataGen?

     DataGen generates accurate and thoroughly documented Turbo Pascal
     source code.

     Once compiled (using Turbo Pascal 4.0 or higher) DataGen applications
     execute independent of runtime modules, and background processes.1

     DataGen generates databases in BTRIEVE or Turbo Toolbox format

     Under BTRIEVE, DataGen applications run on a variety of Multi-user
     Network environments, with full file and record locking.

     Applications which are developed using DataGen are free from royalty
     restrictions.

     The typical DataGen full-function database can be developed in under
     10 minutes.

     DataGen is a Turbo Pascal programming tool; it places no limitations
     on the final database application. The scope of the final process is
     bounded only by the skill of the Turbo Pascal programmer.

     ScreenGen (part of the DataGen Development Kit) generates screens in-
     dependent of DataGen, and may be used in the development of both data-
     base and non-database applications.

     1BTRIEVE format databases require BTRIEVE to be loaded upon execution




              DataWrite Page 1 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────


     Mastering DataGen

     The DataGen Development Kit is made up of two separate processes:

     ScreenGen:         Data Entry Screen generator
     DataGen:           Database generator

     Programmers of DataGen should begin by familiarizing themselves with
     ScreenGen's Screen Development Language (SDL). DataGen utilizes
     ScreenGen SDL source files to build a data storage system for informa-
     tion passed to and from the screen.



     A Recipe For Instant DataGen Applications

     Step 1: Design a screen. I suggest you thoroughly cover the ScreenGen
     section of this manual, however if you're impatient, as I am, flip
     back and forth between the ScreenGen Syntax section of the Reference
     manual, and the ScreenGen Sample Screen section. Good luck.

     Step 2: Follow the instructions listed in the Syntax section of the
     DataGen Overview.

     Step 3: Execute the application. There, instant gratification. Do you
     feel good about yourself? No, you feel cheap and empty inside... I
     suggest that you go back and do it properly.

     Explanation of Terms

     Please refer to this list of definitions when covering the following
     sections.

     <code_list>
     One or more lines of valid (syntax correct) Turbo Pascal source code.

     <conditional>
     A Turbo Pascal conditional clause.

     Example: In the Turbo Pascal statement
     If Color = 'Red' Then Exit
     Color = 'Red' is the conditional clause.

     get_function()
     A get_function() accepts user input, allows the user to edit the in-     put, and returns as the value of the function a specific Turbo Pascal
     data type. The get_function() is the heart of io.tpu, a module of sub-
     routines which form the basis of ScreenGen2. Three get_function()s
     correspond to the three primary Turbo Pascal data types.


     2The get_function()s are detailed in Appendix A, along with all of the
     subroutines of io.tpu.




              DataWrite Page 2 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────

        get_string(default, option_list)
        get_integer(default, option_list)
        get_real(default, option_list);

     The fourth, get_menu(), allows the user to select from a highlighted
     bar of choices, and returns a byte corresponding to the choice
     selected.

        get_menu( menu, menuhelp, default, option_list)

     <menu>
     A string sent as the first parameter in a get_menu() function call.
     See the description of parameters for get_menu() in Appendix A.

     <menuhelp>
     A string sent as the second parameter in a get_menu() function call.
     See the description of parameters for get_menu() in Appendix A.

     #STATEMENT
     A ScreenGen Reserved word, prefixed by the pound sign (#) and followed
     by any number of parameters.




































              DataWrite Page 3 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
     ScreenGen

     ScreenGen assists the Turbo Pascal programmer who is called upon to
     create data entry screens. Executed from the command line, ScreenGen
     accepts a ScreenGen source file as input and generates a Turbo Pascal
     source file capable of executing a full-function data entry screen.

                         SG.EXE                        TPC.EXE
     ScreenGen -->       *----*    -->       Turbo Pascal        *-----* --
     >    Object Code
     Source Code    -->       *----*    -->       Source Code
     *-----*   -->  (.EXE File)
                         SG.EXE                        TPC.EXE
               (ScreenGen Generator)              (Turbo Pascal Compiler)

     Command syntax

     SG <SOURCE_FILE> <OUTPUT_FILE>3




     3Although not required, it is strongly suggested that ScreenWrite
     source files be tagged .SW, that is: <FILENAME>.SW. ScreenWrite output
     files should be tagged .SCR, that is: <FILENAME>.SCR. Thus the command
     syntax becomes:
     SW <SOURCE_FILE>.SW <OUTPUT_FILE>.SCR































              DataWrite Page 4 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
     ScreenGen Overview

     Syntax

     <Screen Definition Section>
     ##
     <Global Definition Section>
     <Variable Definition Section>
     <END OF FILE>

     <Screen Definition Section>
     A Picture of the Screen.

     <Global Definition Section>
     A series of #STATEMENTS which detail characteristics global to the
     screen. The Programmer may specify the format of the generated code,
     as well as defaults for screen functionality.

     <Variable Definition Section>
     A series of #DEFINE statements which assign variable names to the
     fields identified in the <Screen Definition Section>. Additional
     #STATEMENTS assign characteristics to the variables defined and enable
     the user to specify input functionality for a given field.

     Output
     ScreenGen has the ability to generate a screen in two formats.

     1) non_procedural
        A series of get_function() calls, one per field.

     2) procedural
        A complete Turbo Pascal procedure or function.

     [procedure | function] <screen_title>( display_status: string[] )[ :
     byte ];
     <declaration section>
     begin
                with <data_record> do begin

                if \1   Display non-fields (background)
                if \2   Display default field values.
                if \3   repeat
                                Edit Data
                        until <escape_conditional>
                end; {with}
     end; {subroutine}

     Selecting a procedural screen, the programmer generates a fully func-
     tional sub-routine, which can be $Included in a Turbo Pascal Module.
     The procedural screen enables an end-user to view a screen, fill the
     screen and transfer the results to variables defined by the program-
     mer.






              DataWrite Page 5 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
     The screen performs three functions.
     1) Display non-field (background) information.
     2) Display default field values -- those values currently contained in
     the Turbo variables corresponding to the fields.
     3) Allow the user to step through each field adding or changing data.

     The programmer selects the function or functions desired by passing
     '\1', '\2', and/or '\3' in the parameter display_status. For example,
     A call to
                        data_screen('\1\2');
     displays the border information, and field values of a database, while
     a call to:
                        data_screen('\3');
     allows the user to edit database screen fields.












































              DataWrite Page 6 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
     ScreenGen Reference Guide

     Readers of this section should first examine the ScreenGen Overview.

     File Specification

     To run ScreenGen, you need load only the ScreenGen executable file:
     SG.EXE

     Code generated by ScreenGen must be linked to IO.TPU before executing.

     Command Structure and Syntax Detail (SDL)
     <Screen Definition Section>

     The <Screen Definition Section> is made up of up to 24 <Screen Defini-
     tion Line>s each containing:

     1) fields
     2) non-fields (background)

     Fields consist of a combination of @s and non-blank format characters.
     Examples of valid fields are:
                @@@@@@@@@       (field of length 9)
                @@@-@@-@@@@     (formatted field, length 10)

     Formatted fields are useful when storing items such as social security
     numbers, as designated by the example above, dates (@@/@@/@@), and
     telephone numbers ((@@@)-@@@-@@@@). The only restriction placed on a
     formatted field is that it contain no blank characters, otherwise
     ScreenGen will mistakenly interpret it as two separate fields.

     non-fields (background) are made up of any character beside the @ sym-
     bol. Field titles, borders and blank lines are all examples of back-
     ground.

     An example of a <Screen Definition Line> for an employee database
     might be:

     Name: @@@@@@@@@@@@@@@@     Phone: (@@@)-@@@-@@@@   B-Day: @@/@@/@@

     The Phone and Birthday fields are formatted fields and will be stored
     as string[10] and string[6] respectively.

     'Name:', 'Phone:', and 'B-Day:' comprise the background (non-field)
     items on the line.













              DataWrite Page 7 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
     <Global Definition Section>: OPTIONAL

     The <Global Definition Section> defines information pertinent to the
     entire screen.

     #DATABASE, #SCREEN, #PROCEDURE and #FUNCTION are subroutine designa-
     tion statements. They instruct ScreenGen to generate a procedural
     screen. Absence of a subroutine designation #STATEMENT results in the
     generation of a non-procedural screen (a linear series of get_func-
     tion() calls). In the following examples, <file_title> refers to the
     SG source file without the extension.

     #DATABASE <database_title>
     Generates a Turbo Pascal procedure in this format:
     procedure <database_title>_screen( display_status : string[15]);
        begin
                with <database_title>_data do begin
                .
                if \1 then draw screen background
                .
                if \2 then echo default fields
                .
                if \3 then repeat
                        get_function() calls
                until <escape_conditional>
                .
                end; {with}
        end; {procedure}
     This option is generally used in conjunction with DataGen.
     <database_title> default = <file_title>
     <escape_conditional> default = 'in_keycode = k_escape'

     #SCREEN <screen_title>
     Generates a Turbo Pascal procedure in this format:
     procedure <screen_title>( display_status : string[15]);
        begin
                if \1 then draw screen background
                .
                if \2 then echo default fields
                .
                if \3 then repeat
                        get_function() calls
                until <escape_conditional>
        end; {procedure}

     <screen_title> default = <file_title>_screen
     <escape_conditional> default = 'in_keycode = k_escape'

     #PROCEDURE <procedure_title>
     Generates a Turbo Pascal procedure in this format:
     procedure <procedure_title>( display_status : string[15]);
        begin
                if \1 then draw screen background




              DataWrite Page 8 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
                .
                if \2 then echo default fields
                .
                if \3 then repeat
                        get_function() calls
                until <escape_conditional>
        end; {procedure}

     <procedure_title> default = <file_title>_screen
     <escape_conditional> default = 'in_keycode = k_escape'


     #FUNCTION <function_title>
     Generates a Turbo Pascal function in this format:
     function <function_title>( display_status : string[15]) : byte;
        begin
                if \1 then draw screen background
                .
                if \2 then echo default fields
                .
                if \3 then repeat
                        get_function() calls
                until <escape_conditional>
        end; {procedure}

     <function_title> default = <file_title>_screen
     <escape_conditional> default = 'in_keycode = k_escape'
     The return value of the function should be set by the programmer using
     #BEFORE/#AFTER.

     #OVERLAY
     Generates an Overlay Procedure or function. Must be used in conjunc-
     tion with #DATABASE, #SCREEN, #PROCEDURE or #FUNCTION.

     #WITH <record_title>
     Generates a with statement. Must be used in conjunction with #SCREEN,
     #PROCEDURE or #FUNCTION (#DATABASE automatically forces the generation
     of a with statement).
     <record_title> default = <file_title>_data

     #ESCAPE <escape_conditional>
     Default: in_keycode = k_escape
     Sets the <escape_conditional> in the generated procedure/function (see
     above).

     #TYPE [ String | Integer | Real ]
     Default: String
     Sets the default data_type = 'String', 'Integer' or 'Real'.










              DataWrite Page 9 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────

     #BEFORE <code_list>
     #AFTER <code_list>
     Used to insert Turbo Pascal source into the ScreenGen output file.
     Placement of the code depends upon placement of the #BEFORE/#AFTER
     statement. If we consider #SUBROUTINE to be #DATABASE, #SCREEN, #PRO-
     CEDURE, or #FUNCTION, then placement of #BEFORE/#AFTER code in the
     resultant procedure/function follows.


     CASE 1: #BEFORE/#AFTER follows #SUBROUTINE.

     From the source code:

     #SUBROUTINE foo
     #BEFORE <before_code>
        .
        .
     #AFTER <after_code>
        .
        .
     ##

     ScreenGen generates the Turbo Pascal code:

     subroutine foo
     begin
                {with foo_data do begin [if designated])
                <before_code>
                        .
                        .
                body of subroutine...
                        .
                        .
                <after_code>
                        .
                        .
                {end with, if designated}
     end; {subroutine}



















             DataWrite Page 10 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────

     CASE 2: #BEFORE/#AFTER Precedes #SUBROUTINE

     From the source code:

     #BEFORE <before_code>
        .
        .
     #AFTER <after_code>
        .
        .

     #SUBROUTINE foo
     ##

     ScreenGen generates the Turbo Pascal code:

                <before_code>
                        .
                        .
     subroutine foo
     begin
                {with foo_data do begin [if designated])
                body of subroutine...
                        .
                        .
                {end with, if designated}
     end; {subroutine}

                <after_code>
                        .
                        .

     #DECLARE <code_list>
     Used to insert variable declarations into the ScreenGen output file.
     Code is placed in the declaration section of the resultant subroutine.

     From the source code:
     #SUBROUTINE
     #DECLARE <declaration_code_list>
        .
        .
     ##

     ScreenGen generates the Turbo Pascal code:

     subroutine foo
     <declaration code_list>
        .
        .
     begin
                {with foo_data do begin [if designated])
                body of subroutine...





             DataWrite Page 11 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
                        .
                        .
                {end with, if designated}
     end; {subroutine}






















































             DataWrite Page 12 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
     <Variable Definition Section>

     For each field defined in the <Screen Definition Section> ScreenGen
     requires a #DEFINE statement to appear in the <Variable Definition
     Section>. #STATEMENTS which follow the #DEFINE for a given variable
     act as qualifying commands for that variable.

     The following is a list of legal <Variable Definition Section> #STATE-
     MENTS with descriptions:

     #DEFINE <variable>
     Assigns the name <variable> to the next Field as indicated in the
     <Screen Definition Section>. A get_function is generated for the <var-
     iable> unless it is designated #DISPLAY (see #DISPLAY below). Fields
     are assigned in a top down manner from left to right.

     #OPTIONS <option_list>
     Appends <option_list> to the get_function() for the corresponding
     #DEFINEd variable.

     #BEFORE <code_list>
     <code_list> will be executed prior to execution of the get_function()
     for the #DEFINEd variable.
     #AFTER <code_list>
     <code_list> will be executed following execution of the get_function()
     for the #DEFINEd variable.

     #MENU <menu>
     a get_menu() call will be generated for the #DEFINEd variable with
     <menu> as the first parameter.

     #PROMPT <menu>
     a get_menu() call will be generated for the #DEFINEd variable with
     <menu> as the first parameter, and \px and \py set to the field loca-
     tion. As a result the menu selection appears in the field location as
     well as being highlighted on the menu.

     ## <comment_list>
     Allows the user of SG to comment source code. <comment_list> is not
     transferred to the resultant Turbo source. ## also separates the
     <Screen Definition Section> from the <Variable Definition Section>.

     #VIEWORDER <vieworder_spec>
     specifies the

     #VERIFY <turbo_conditional>
     After editing the #DEFINEd field, this <turbo_conditional> is tested,
     before continuing.

     Example:   #DEFINE this_field
                #VERIFY this_field > 17

     #ERROR <error_message>





             DataWrite Page 13 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
     <error_message>  is displayed if the <turbo_conditional> of the
     #VERIFY command is not met.

     Example:   #DEFINE this_field
                #VERIFY this_field > 17
                #ERROR  This field must be at least 18, you twit.

     #DISPLAY
     Sets the #DEFINEd variable to display only. No editing of the field
     will be allowed.

     #HELP <menuhelp>
     If the #DEFINEd field is a menu field, <menuhelp> is offered as the
     second parameter of the get_menu() call.

     #TYPE [ String | Integer | Real ]
     Default: String     parameter = String         : A get_string() call is generated.
     parameter = Integer                : A get_integer() call is genera-
     ted.
     parameter = Real           : A get_real() call is generated.

     To generate a get_menu() call, see #MENU.

     #VIDEO [ bright | dim | reverse | no_color ]
     Default: no_color
     Sets the display intensity for a field.

     #VIEWORDER <view_list>
     Allows the programmer to specify the next field to be edited for each
     exit keystroke (e.g. carriage return, cursor up...). By default, a
     call to vieworder() (part of io.tpu) is generated following each
     get_function(). ScreenGen tries to best guess the intentions of the
     programmer regarding the order of field traversal, based on top-down,
     left-right. Under certain circumstances, it may be necessary to change
     the default order of field traversal. <view_list> is a string contain-
     ing one or more of the following:

        \crn    On carriage return goto field n
        \ucn    On up cursor goto field n
        \dcn    On down cursor goto field n
        \tabn   On tab goto field n
        \btabn  On backtab (Shift+tab) goto field n
        \escn   On escape goto field n

     In all cases, n must be a valid field number. Fields are implicitly
     numbered starting from 1, top-left to bottom-right.












             DataWrite Page 14 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────

     ScreenGen Sample Screens

     Screen 1:  Employee Screen
     Name:      @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
     Street1:   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
     Street2:   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
     City:      @@@@@@@@@@@@@@@@@@@@@@@@  State: @@  Zip: @@@@@@@@@@@
     Phone:     @@@-@@@-@@@@    Social Security:        @@@-@@-@@@@
     ##
     ##         Global Declaration Section
     ##

     #screen employee_screen
     #with employee_data_record

     ##
     ##         Variable Declaration Section
     ##

     #define name
     ## Capitalize the First letter of name
        #option \g
     ## Highlight the Name for easy scanning
        #video bright
     #define street1
     #define street2
     #define city
     #define state
     ## Force the characters of state to uppercase
        #options \u
     #define zip
     #define phone
     #define soc_sec
     ## Although stored as a string, a social security number contains
     ## only numeric digits
        #options \ci





















             DataWrite Page 15 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
     ScreenGen Sample Screens, Continued

     Screen2: Sales Screen              Records on File:        @@@@@     Company:   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
     Contact:   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

     Phone: (w) @@@-@@@-@@@@    (h) @@@-@@@-@@@@

     Date of First Call:        @@/@@/@@ Last:  @@/@@/@@
     Resolution of Call: @@@@@@@@@@@@@@@@

     Notes:     @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
     @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
     @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
     ##
     ## Global Definition Section
     ##
     #procedure sales_screen
     #with sales_data
     ##
     ## Variable Definition Section
     ##
     #define usedrecs( sales_file )
     ##
     ## Sometimes, variables may actually be subroutine calls
     ## which return a specific Turbo type.
     ## usedrecs() is a Turbo Database Toolbox routine.
     ## It is of type integer, and must be set to display only.
     ##
        #type integer
        #display

     #define company
        #options \g
     #define contact
     #define work_phone
     #define home_phone
     #define first_call_date
     #define last_call_date
     #define call_resolution
        #prompt \1Call Again\2No Deal\3Sale
        #help \1When at First you don''t succeed\2Forget it\3Yeah!
     ##
     ## Notice the use of the double '' in the #help call.
     ## When the #help is converted, the parameter becomes a Turbo
     ## Pascal string. Since a single quotation mark signifies
     ## the end of a string, a double mark must be used.
     ##
     #define notes1
     #define notes2
     #define notes3







             DataWrite Page 16 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
     ScreenGen Sample Screens, Continued

     Screen 3: Help Screen

     This is an example of how a ScreenGen programmer might define a Help
     Screen. It contains a useful information about running an application
     that would be brought up under a [HELP] option. In this example, we
     direct that the screen be generated as a function, returning a byte to
     the calling routine which signifies display next (1), or Return to Ap-
     plication (2). The Turbo Pascal variable exit_menu is local to the
     generated function, declared using #DECLARE, initialized in the #BE-
     FORE code and passed to the function in the #AFTER code.

     Turn off VCR                               ----    ALT-F1
     Make pizza                         ----    ALT-F2
     Take my wife, please                       ----    ALT-F3




     @@@@@@@@@@
     ##
     ## Global Definition Section
     ##
     #function help_screen
     #declare var exit_menu : byte;
     #before exit_menu := 1;
     #after help_screen := exit_menu;

     ## Variable Definition Section

     #define exit_menu
        #menu \1Next\2Return
        #help \1Display Next Help Screen\2Return to Application
























             DataWrite Page 17 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────

     DataGen

     DataGen assists Turbo Pascal programmers who wish to create simple
     database applications. Executed from the command line, DataGen accepts
     a DataGen source file as input and generates a Turbo Pascal Source
     file capable of executing a full-function database. Source code may be
     generated in TURBO DATABASE TOOLBOX, or BTRIEVE format.

                         DG.EXE                        TPC.EXE
     DataGen   -->       *----*    -->       Turbo Pascal        *-----* --
     >    Object Code
     Source Code    -->       *----*    -->       Source Code
     *-----*   -->  (.EXE File)
                         DG.EXE                        TPC.EXE
               (DataGen Generator)           (Turbo Pascal Compiler)

     Command syntax

     DG <SOURCE_FILE> [/b]

     The /b parameter indicates generation of a database in BTRIEVE format.




































             DataWrite Page 18 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────

     DataGen Overview

     Syntax

     DataGen syntax is a subset of ScreenGen source syntax. To create a
     database using DataGen, follow these steps:

     1)   Design a screen using ScreenGen SDL
          Tag the file .sg, that is <SOURCE_FILE>.sg

     2)   Make the following changes to the ScreenGen source:
          a)   include the command #DATABASE in the <Global Definition Sec-
     tion>

          b)   using #INDEX, label each variable that you wish to utilize
               as a search key. The #INDEX is a <Variable Definition Sec-
               tion> #STATEMENT and should be included following the
               #DEFINE statement for a given variable. At least one vari-
               able must be #INDEXed per database. #INDEXed variables must
               be of #TYPE string.

     3)   Execute:  DG <SOURCE_FILE>.sg
          Execute:  Make -f<SOURCE_FILE>.mkf

     DataGen creates the executable file <SOURCE_FILE>.exe. Run this file
     to execute the database.

     Output

     DataGen generates database code in two formats.

     TURBO DATABASE TOOLBOX format
     BTRIEVE format

     DataGen creates three files from <SOURCE_FILE>.sg:
     <SOURCE_FILE>.pas   : Turbo Pascal .pas file
     <SOURCE_FILE>.typ   : Record Definition Include file to <SOUR-
     CE_FILE>.pas
     <SOURCE_FILE>.mkf   : Makefile for <SOURCE_FILE>.exe


     For each field #DEFINEd in <SOURCE_FILE>.sg, DataGen generates a Turbo
     Pascal identifier in <SOURCE_FILE>.typ. Each identifier is part of a
     Record called
     <SOURCE_FILE>_structure. For example, the .sg file
     geneva.sg:

     Name: @@@@@@@@@@@@@@@@@@@@@@@@@
     Rank:     @@@@@@@@@@     Serial Number: @@@@@@@@@@@-@@@
     ##
     #database
     #define name





             DataWrite Page 19 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
          #index
     #define rank
     #define serial_number

     yields the .typ file geneva.typ

     type geneva_structure = record
          status : longint;
          name : string[25];
          rank : string[10];
          serial_number : string[14];
     end; {record}

     The status field is generated for TURBO DATABASE TOOLBOX format data-
     bases only, and is used to track deleted records.

     Editing Turbo Source

     Once DataGen generates the source files, they may be edited prior to
     compilation. To do so, one should have a working knowledge of io.tpu,
     as a significant amount of the resultant source calls subroutines
     within the i/o module.




































             DataWrite Page 20 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────

     DataGen Reference

     File Specification

     To execute DataGen, the following files must be loaded:

     DG.EXE:        The DataGen program
     DG.DAT:        DataGen Source Data (Turbo Toolbox)
     IO.TPU:        Input/Output Subroutine Module

     If BTRIEVE format is selected, the files:

     BTRIEVE.DAT:   DataGen BTRIEVE Source Data
     T4BTRV.TPU:    BTRIEVE Link Module for Turbo Pascal

     must also be loaded.


     Command Structure

     DataGen generates code from a modified ScreenGen source file. The     #STATEMENTs utilized by the DataGen generator are listed by section.
     #STATEMENTs not recognized by DataGen, but which appear in the .sg
     file will produce the warning: ** ASSUMED COMMENT ** followed by the
     text of the source line.

     <Global Definition Section>

     #DATABASE - See definition in ScreenGen Reference.

     <Variable Definition Section>

     #DEFINE <variable>
     Generates a Turbo Pascal identifier called <variable> as a member of
     the data record <SOURCE_FILE>_structure. The record field will have
     the Turbo Pascal data type as indicated by #TYPE (or the default for
     the <variable>). If the <variable> is of #TYPE string, it's length is
     calculated as the length of the field defined in the <Screen Defini-
     tion Section>.

     #MENU <menu>
     The #DEFINEd variable will be generated as type byte.

     #PROMPT <menu>
     The #DEFINEd variable will be generated as type byte.

     ## <comment_list>
     Allows the user of DG to comment source code. <comment_list> is not
     transferred to the resultant Turbo source. ## also separates the
     <Screen Definition Section> from the <Variable Definition Section>.

     #INDEX
     Indicates that the #DEFINEd field will be a search key. The field must
     be of #TYPE string.




             DataWrite Page 21 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────

     #TYPE [ String | Integer | Real ]
     Default: String
     parameter = String       : A variable of type string[] is generated
     parameter = Integer : A variable of type integer is generated
     parameter = Real         : A variable of type real is generated

     #NOTDATA
     No identifier is generated for this field.

















































             DataWrite Page 22 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────

     APPENDIX A: Examination of IO.TPU

     function get_string(default, option_list) : string[255];

     Accepts:  default - string[255]
               option_list -  string[80]
     Returns:  string, max length 255, as the value of the function

     Function: get_string() presents the user with an editing buffer con-
     taining the default string. Using Cursor keys, the user may change or
     add characters to the buffer. get_string() returns the altered string
     as the value of the function.

     option_list is a string comprised of any of the following.

     \q   <query>
     The associated <query> is printed as a prompt to the user for entry of
     data into the field.

     \d
     Display only: no data is to be entered into the field.

     \af
     Auto Forward: Exit from the routine occurs when the number of charac-
     ters in the field surpass the allocated size.

     \ab
     Auto Back: Exit from the routine occurs if the user hits a backspace
     when the field is empty.

     \g
     Capitalize: Upon exiting, the first character in the field is Capital-
     ized.

     \u
     Uppercase: Characters are forced to upper-case.

     \xnn
     Goto Xpos: Field location is set to Xpos nn.

     \ynn
     Goto Ypos: Field location is set to Ypos nn.

     \lnn
     Length: The maximum length of the field is set to nn characters.

     \fxxxxxxxx
     Format string: Data is to be entered in a formatted fashion, based on
     the format string xxxxxxxx. xxxxxxxx may contain any non-blank charac-
     ters. At symbols (@) indicate location for character entry.
     \cx
     Valid characters:   Limits the keystrokes accepted for data entry into
     the field.




             DataWrite Page 23 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
                    x = '*' : Any Alphanumeric Character                    x = 'i' : Numeric Character only
                    x = 'r' : Numeric and Period (.) for entry of floating
     point numbers

     \kxxxxxxxxxxxxxxxx
     Return Keystrokes: Sets the keystrokes indicating exit from get_str-
     ing(). xxxxxxxxxxxxxxxx is a concatenation of the following
     'cr'      return on           carriage return
     'uc'           up_cursor
     'dc'           down_cursor
     'tab'          tab
     'btab'         Backtab (Shift+Tab)
     'esc'               Escape key

     \vix
     Video in: Sets the video attribute for field data entry
     x='b'     bright (normal video)
     x='d'     dim (low video)
     x='r'     reverse (reverse video)

     \vox
     Video out: Sets the video attribute for field upon exit.
     x='b','d','r' (see \vi above)

     Examples:
     Chair := get_string( 'Wicker', '\qEnter Chair Type:\x10\y15\l30');

     1. Assign input to the string variable Chair. Default value is the
     character string 'Wicker'. String input is accompanied by the query
     'Enter Chair Type:'. Length of the string should not exceed 30. Input
     takes place at screen position xpos=10, ypos=15.

     Today := get_string( system_date, '\qEnter Date\f@@/@@/@@\x3\y5');

     2. Assign input to the string variable Today. Default value is the 6
     character string variable system_date. String input is accompanied by
     the query 'Enter Date'. The string is to be entered in a formatted
     manner defined by the format string '@@/@@/@@'. Input takes place at
     screen position xpos=3, ypos=5.


















             DataWrite Page 24 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
     function get_menu( menu, menuhelp, default, option_list ) : byte;

     Accepts:  menu - string[255]
               menuhelp - string[255]
               default - byte
               option_list - string[255]

     Returns:  byte as the value of the function

     Function: get_menu() presents the user with a list of menu choices
     passed in the menu, and menuhelp parameters. The user may select the
     desired choice by highlighting it and pressing return, or by pressing
     the first letter of that choice. get_menu() returns a byte correspond-
     ing to the choice number selected by the user.

     The trick to using get_menu() is understanding the format of the menu
     parameter. It must be in the following format.

     '\1First Choice\2Second Choice\3Third Choice... \9Last Choice'

     A maximum of nine (9) choices may appear for each menu. Choices may be
     clarified in the menuhelp parameter which appears directly under the
     highlighted choice.

     '\1This is the First Choice\2And the Second Choice... \9No more
     Choices'

     The default parameter should contain the number corresponding to the
     selection you wish highlighted upon presentation of the menu.

     option_list is a string comprised of any of the following.

     \q   <query>
     The associated <query> is printed as a prompt to the user for entry of
     data into the field.

     \d
     Display only: no data is to be entered into the field.

     \kxxxxxxxxxxxxxxxx
     Return Keystrokes: Sets the keystrokes indicating exit from get_str-
     ing(). xxxxxxxxxxxxxxxx is a concatenation of the following
     'cr'      return on      carriage return
     'uc'                up_cursor
     'dc'                down_cursor
     'tab'                    tab
     'btab'                   Backtab (Shift+Tab)
     'esc'                    Escape key
     \vix
     Video in: Sets the video attribute for field data entry
     x='b'     bright (normal video)
     x='d'     dim (low video)
     x='r'     reverse (reverse video)





             DataWrite Page 25 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────

     \vox
     Video out: Sets the video attribute for field upon exit.
     x='b','d','r' (see \vi above)

     \mxn
     Menu Xposition: n specifies the x screen coordinate at which the menu
     should appear.

     \myn
     Menu Yposition: n specifies the y screen coordinate at which the menu
     should appear.

     \pxn
     Prompt Xposition: If this option is included, get_menu() will echo the
     current menu selection at x screen coordinate n.

     \pyn
     Prompt Yposition: If this option is included, get_menu() will echo the
     current menu selection at y screen coordinate n.

     Example:
     Fruit := get_menu( '\1Apple\2Orange, '\1Big, Red and Juicy\2Sweet,
     slightly tart', 1,  '\qEnter Fruit Type:\mx10\my15');

     1. Assign input to the variable Fruit (type byte). The value of Fruit
     will be set to 1, or 2 based on whether the user selects 'Apple' or
     'Orange' from the menu. It will appear an Xposition 10 and Yposition
     15, preceded by the query 'Enter Fruit Type'. The default menu selec-
     tion is 'Apple', which will be highlighted when the menu appears.




























             DataWrite Page 26 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
     function get_integer( default, option_list ) : integer;

     Accepts:  default - integer
               option_list - string[255]

     Returns:  integer, as the value of the function.

     Function: get_integer() allows the user to enter and change an in-
     teger. It has the same functionality as get_string().

     option_list is a string comprised of all of the options available
     within get_string(), plus the following.

     \lbnnnnnn
     Lower Bound: The integer entered by the user must be at least nnnnnn.

     \ubnnnnnn
     Upper Bound: The integer entered by the user must be at most nnnnnn.



     function get_real( default, option_list ) : real;

     Accepts:  default - real
               option_list - string[255]

     Returns:  real, as the value of the function.

     Function: get_real() allows the user to enter and change a real. It
     has the same functionality as get_string().

     option_list is a string comprised of all of the options available
     within get_string(), plus the following.
     \lbnnnnnn
     Lower Bound: The real entered by the user must be at least nnnnnn.

     \ubnnnnnn
     Upper Bound: The real entered by the user must be at most nnnnnn.


     Note: Both get_integer() and get_real() call get_string().

















             DataWrite Page 27 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
     procedure scan;

     Sets:     in_keycode - keystroke
               in_chr - char

     Function: Accepts a keystroke from the keyboard. Sets the two global
     variables:

     in_keycode: a scaler variable of type keystroke with a value of:

     k_cr, k_escape, k_down_cursor, k_up_cursor, k_left_cursor,
     k_right_cursor, k_bs, k_tab, k_del, k_linefeed, k_ctrl_right,
     k_ctrl_left, k_home, k_end, k_ctrl_K, k_ctrl_Y,
     k_pgup, k_pgdn, k_backtab, k_ascii, k_invalid

     in_chr: char, that accepted by scan; Set to the ascii character when
     in_keycode = k_ascii.


     function format( format_string, format_shell, string_index ) :
     string[];

     Accepts:  format_string - string[255]
               format_shell - string[255]

     Returns:  string_index - byte
               string[255] as the value of the function
     Function: Using format_shell as a guide, format() returns a formatted
     version of the passed string as the value of the function.
     string_index is set to the character location of the last non-format
     character in the returned string.

     format_shell consists of a combination of @s and non-blank format
     characters. Examples of a valid format_shell are:

               @@/@@/@@  (Date)
               @@@-@@-@@@@    (Social Security Number)
               22-@@@@@@@@@   (Federal ID)

     Sample Call:        format('122269', 'H@@@@-@@@DF@@@', s_index );
     Returns 'H1222-69 DF' as the value of the function, and sets
     string_index = 8.

     function atoi( ascii_int ) : integer

     Accepts:  ascii_int - string representation of an integer;
     Returns:  integer, as the value of the function

     Function: Converts a string into the integer which it represents.

     Sample Call:        atoi('12')
     Returns the integer 12 as the value of the function.






             DataWrite Page 28 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
     function itoa( integer ) : string[]

     Accepts:  integer
     Returns:  string[] representation of integer as the value of the func-
     tion

     Function: Converts an integer into a string which represents it.

     Sample Call:        itoa( 966 )
     Returns the string '966' as the value of the function.

     function ator( ascii_real ) : real

     Accepts:  ascii_real - string representation of a real number;
     Returns:  real, as the value of the function

     Function: Converts a string into the real which it represents.

     Sample Call:        ator('16.35')
     Returns the real number 16.35 as the value of the function.
     function rtoa( real_number ) : string[]

     Accepts:  real_number - real
     Returns:  string[] representation of real_number as the value of the
     function

     Function: Converts a real number into a string which represents it.

     Sample Call:        rtoa( 11.44 )
     Returns the string '11.44' as the value of the function.

     function capitalize( in_string ) : string[]

     Accepts:  in_string - string[255]
     Returns:  string[] as the value of the function

     Function: The first letter of each word in string[] (separated by
     blanks) is capitalized.

     Sample Call:        capitalize('it was the best of times');
     Returns:       'It Was The Best Of Times' as the value of the func-
     tion.

     procedure set_cursor( setting )

     Accepts:  setting - byte (0/1)

     Function: setting = 0, cursor is turned off
               setting = 1, cursor is turned on

     procedure message( message, severity )

     Accepts:  message - string[80]





             DataWrite Page 29 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────
               setting - byte (1-4)

     Function: Prints message along the foot of the screen. Set severity
     to:
               1: display the message
               2: display the message and beep
               3: display the message, beep, display Any Key Continues, and
     await user input
               4: display the message, Any Key Continues, no beep

     Sample Call:   message('Your PC is about to explode, please leave the
     room', 3);
     procedure video( attribute )

     Accepts:  attribute - byte

     Function: no_color:      do nothing
               bright:             Normal Video
               dim:           Low Video
               reverse:       Reverse Video

     The four video attributes listed above are defined as global con-
     stants.

     Sample Call:   video( bright );

     procedure writexy( xpos, ypos, attribute, show_string )

     Accepts:  xpos, ypos - byte
               attribute - byte
               show_string - string[80]

     Function: displays show_string at screen(xpos, ypos) using video at-
     tribute.

     Sample Call:   writexy(2, 20, dim, 'Howdy Doody');






















             DataWrite Page 30 -- Copyright (C) Tika Software, Co.
────────────────────────────────────────────────────────────────────────────────