OS/2 Shareware BBS: 8 Other/08-Other.zip/dbfill-b.zip/db-fill.doc

Text File | 1996-03-24 | 14KB | 379 lines

DB-FILL 1.0 for OS/2 (open beta)

DB-FILL is copyrighted by, and can be obtained from:

Byte Of Software Systems
#75 - 20465 Douglas Crescent
Langley, British Columbia
V3A 4B6

[e-mail]


Terms of Use
~~~~~~~~~~~~
This software is presented as-is. Byte Of Software Systems will not be
liable for any damages arising from the use of DB-FILL. This is a beta
version of DB-FILL. As such it is assumed to have software anomalies.

While Byte Of Software Systems is interested in bug and usage reports, it
is under no obligaton to use the reports, nor pay for the reports.

Introduction
~~~~~~~~~~~~
DB-FILL is a program designed for data base system developers. DB-FILL
creates randomly generated data for filling data bases. This allows the
data base system to be tested under load.

Usually data base developers input a few records to test their reports and
look-up functions. Then, when the system is delivered to the customer,
problems surface when the record count reaches into the thousands.

This beta version of DB-FILL is limited to 10 records per data file. The
production version will created unlimited numbers of records, based on disk
space.

DB-FILL can create data for relational data base systems. Simply link the
data base files using primary and secondary field definitions. DB-FILL will
correctly relate records using the key fields. Records (and fields) can be
conditionally created.

This document is a condensed version of the printed manual. It does not
contain the example descriptions, and only has brief descriptions of the
command set.

Requirements
~~~~~~~~~~~~
DB-FILL will run on OS/2 2.x and greater. You will also require a data
base program that is capable of importing ASCII data in either FIXED LENGTH
format, or COMMA DELIMITED format.

Installation
~~~~~~~~~~~~
Create a directory for DB-FILL and unzip DB-FILL_.ZIP using a directory
expansion option (-d).

Running DB-FILL
~~~~~~~~~~~~~~~
DB-FILL requires a single command line parameter, the name of a script
file. For the contents of the script file see below.

Conventions
~~~~~~~~~~~
Any text within square brackets is optional []. Capitalized text is
MANDATORY. Text with a vertical bar '|' between options means select from
the choices.

File Commands
~~~~~~~~~~~~~
Every file command starts with the ampersand '@' character. Commands can be
continued on successive lines. White space (spaces, tabs) are ignored,
except within double quotes ". To actually insert a double quote, use \".
Text case is ignored except within double quotes.

Names must start with a letter and can contain numbers and underscores '_'.

All files must have the following line as the first non-blank line:
      DB-FILL VERSION 1


@CHOICE, name, value; value [;value]
   Builds a choice list. The name of the list is used within @FIELD
   definitions. Up to 100 choice values can be defined. For greater lists
   use @TABLE.

@*
   Single line comment. Can be placed after a valid command on the same
   line.

@COMMENT
   Starts a comment block. Comment blocks are ended with the @ENDCOMMENT
   command.

@COUNT, name, NUMBER, initial, minimum, maximum
   Defines a counter. The name of the counter is used within @FIELD
   definitions.

@COUNT, name, LIST, initial
   Defines a counter which uses a list. The name of the counter is used
   within @FIELD definitions.

@COUNT SET, name, text | count;param [& text | count;param]
   Defines a count set. Count sets are evaluated right to left, but
   inserted left to right. You can string several counters and literal text
   together. The right most counter is incremented first. If it reaches its
   maximum value, it is set to its minimum, and the next right counter is
   incremented.

@DATA BASE, name, file name, COMMA | FIXED LENGTH, REPLACE | QUIT
   Starts the definition of a data base. Output methods are comma delimited
   or fixed length. If a file with the same name is found, REPLACE will
   over write it, while QUIT will end DB-FILL. A data base definition is
   followed by its @FIELD definitions.

@DATA PATH, ADD | INSERT | REPLACE, path [;path]
   Defines the data path that DB-FILL will search to locate input files.

@DATE, format codes
   Changes the default date format. See DATETIME in FIELD TYPES for valid
   codes.

@DRIVE FREE, drive, mega bytes
   Sets the minimum amount of free space in mega bytes on the indicated drive
   before DB-FILL quits. The default is 2 Mbytes.

@ECHO, text
   Echos the text to the screen. Used for input file indicators.

@ECHO PROCESS, HIDE | SHOW
   Turns on or off @ECHO display.

@ENDCOMMENT
   Ends a comment block started with the @COMMENT command.

@ERROR FILE, file name
   Uses an error file rather than the screen

@FIELD KEY, name, size, type; parms [+type;parms][+"text"]
   A KEY field definition. Every data base must have a key field. Size is
   in characters. For types and their parameters see FIELD TYPES.

@FIELD PF-KEY, name, db; field, min. max, % | field; condition
   A primary foreign field. DB; FIELD is the foreign field name in the data
   base. Somewhere between min and max records will be created. The min and
   max are limited to 10 records in this beta version. Normally DB-FILL can
   create thousands of related records. Percent is the probability that a
   record will be created, or if the field in DB matches the condition,
   the record is created. See CONDITIONS below.

@FIELD SF-KEY, name, db;field
   A secondary key field. The value will be randomly chosen from the DB
   field.

@FIELD DATA, name, %,size, type;parm [+type;parm][,SKIP|DO;fname;condition]
   A data field. Percent is the probability that the field will hold data.
   Size is in characters. For types and their parameters see FIELD TYPES.
   If SKIP or DO and a condition is used, then the percent value is
   ignored. The field will be used (or not) dependant on the conditions in
   the field 'fname'.

@GENERATE, db; records
   Tells DB-FILL how many records to create for the data base. This is
   limited to 10 records in this beta version. Normally DB-FILL can create
   thousands of records.

@INCLUDE FILE, file name
   Inserts the file name. You can have files with stock definitions and
   re-use them.

@MACRO, name, text
   Defines a macro. The macro text will replace the macro name wherever it
   is found. Macro names are placed within angle brackets <>. Built in
   macros are: <file name> the current file being loaded, <line number> the
   current line number of the file being read, <program name> usually
   DB-FILL, <program path> the path where DB-FILL.EXE is, <BASE PATH> the
   path where you started DB-FILL from, and <VERSION> the current DB-FILL
   version.

@MACRO OUT, name
   Removes the macro from use.

@ORDER, db name, field [;field]
   Defines the field output order for the data base. Normally DB-FILL
   writes the fields in the order in which they were defined. You can
   over ride this by using @ORDER. If you use @ORDER, then ALL the fields
   that you want output must be listed.

@PROCESS, RUN | SYNTAX | TEST
   RUN is the default. SYNTAX reads the definition files but does not
   create records. TEST reads the definition files, then allows testing of
   FIELD TYPES.

@PROJECT, text
   Sets up project text. This can be used within @FIELD definitions.

@RANDOM SEED, number
   Seeds the random number generator. This allows for repeatable random
   values. Default is the current date/time.

@STATUS FILE, file name
   Uses a status file rather than the screen for runtime messages.

@STATUS MESSAGE, VALUE LIST | LOAD DATA BASE | FILE NAME | SHOW ALL | SHOW
 SETTING, level [+level]
   Sets run time status message reporting.
     VALUE LIST
        ALL, NONE, TABLE NAME, TABLE VALUE, TABLE LIST, TABLE MEMORY,
        CHOICE NAME, CHOICE VALUE, CHOICE MEMORY, COUNT NAME, COUNT MEMORY
     LOAD DATA BASE
        ALL, NONE, DATA BASE NAME, DATA BASE LOAD, DATA BASE LAYOUT, FIELD
        NAME, FIELD DEFINITION
     FILE NAME
        ALL, NONE, FILE FIND, INCLUDE OPEN, INCLUDE CLOSE, TABLE OPEN,
        TABLE CLOSE, OUTPUT OPEN, FILE LINE, COMMAND LINE, RESULT LINE
     SHOW ALL
        ALL, NONE
     SHOW SETTING
        ALL, NONE, DATA PATH, DATE TIME

@TABLE FILE, file name [, table name]
   Uses a table file for lists. File syntax follows general DB-FILL file
   syntax. If you use a table name, it will over-ride the tabe name in the
   table file. Valid table file commands are:

   @*
   @COMMENT
   @END COMMENT

   @TABLE NAME, name
      This is the name of the table. It can be over-ridden by using a table
      name in the @TABLE command.

   @VALUE, START
      ALL lines after this command will be used as table values. Only the
      single line comment '@*' is not a vlaue.

@TIME
   Changes the default time format. See DATETIME in FIELD TYPES for valid
   codes.


Conditions
~~~~~~~~~~
DB-FILL can conditionally fill data fields, or conditionally create related
records. There are four condition types: CHOICE, DATA, NO DATA, and VALUE.
For data fields, if the condition is true, you can DO or SKIP filling the
field.

CHOICE; name
   Use a CHOICE list. If any of the values in the choice list match the
   value in the condition field, then the condition is true.

DATA
   If the condition field holds a value, then the condition is true.

NO DATA
   If the condition field does not hold a value, then the condition is
   true.

VALUE; data [;data]
   A list of values. For numeric data, you can specify a range by using the
   ampersand (ie: 5&20).


Field Types
~~~~~~~~~~~
This section outlines the various field types that are used to create data.
You can string the field types together by using the '+' sign. In this way
you can tailor the data and create an unlimited number of data types.

Most of the field types have an optional size parameter. If more than one
field type is used, then the size parameter is mandatory. If only one field
type is used, then the size is taken from the field definition size.

"Text  "
   Text can be used simply by placing it within double quotes. Spaces and
   letter case will be left as is.

CHOICE;[size];name
CHOICE;[size];name;C
CHOICE;[size];name;S[;#]
CHOICE;[size];name;R[;#]
   Use a choice list. If no usage parameter is used, the R is used. Using C
   will place the current value into the field. Using S will sequemtially
   use that choice values. If the optional number is given, then each value
   will be used NUMBER times before the next value is used. If R is used,
   then the values are randomly chosen. If the optional number is given,
   then each value will be used up to NUMBER times. After each value is
   used NUMBER times, the list will be re-used.

COUNT;[size];name;type [;[ S | Z ] [;increment amount] ]
   Use a counter. Type refers to numeric types. See below for a list. If
   the letter S is used, then the value is padded on the left with spaces.
   The letter Z will pad with the zero value for the type. If an increment is
   used, then the counter will be incremented by that amount. Negative
   values will decrement the counter.

COUNT SET;[size];name[;I]
   Use the count set. If I is used, then the counters will be incremented.

DATETIME; format [;action]
   Insert a date and/or time, optionally adjusting it. Date and time format
   codes are presented below.


   Format Codes
      " "         literal text
      AM          AM or PM
      D           day number
      D0          day number with leading zero
      DATE        default date format (see @DATE)
      DMY         date in day.month.year format
      H12         hour in 12 hour format
      H24         hour in 24 hour format
      HMS12       time in 12 hour format with AM/PM
      HMS24       time in 24 hour format
      J           julian day
      MIN         minute
      M           month number
      M0          month number with leading zero
      MDY         date in month.day.year format
      ML          long month name
      MS          three letter month name
      PM          AM or PM
      S           seconds
      TIME        default time format (see @TIME)
      W           numeric week day (0 = Sunday)
      WL          long weekday name
      WS          three letter weekday name
      Y2          two digit year
      Y4          four digit year
      YMD         date in year.month.day format

   Action Codes
      Y [-] #     add/subtract from the year
      M [-] #     add/subtract from the month
      D [-] #     add/subtract from the day
      W [-] #     add/subtract number of weeks
      H [-] #     add/subtract from the hour
      N [-] #     add/subtract from the minute
      S [-] #     add/subtract from the second

INTEGER;[size];start;end;type[; S | Z ]
   Insert an integer into the field. The value will be random between start
   and end. Type refers to numeric types. See below for a list. The letter S
   will pad on the left with spaces.  The Z will zero fill the number.

PROJECT [;size]
   Insert the project text. See @PROJECT.

TABLE;[size];name[;#]
   Insert a value from a table. If # is used, then each value will be used
   number times before the next value is used.

TEXT;[size];type;U|L|M[;"Pad Text"]
   Inserts randomly generate text. The number of characters inserted is
   random between 25% and 100% of size. U, L, or M, will change the case to
   Upper, Lower, or leave it Mixed. If Pad is given, then the text will be
   padded to size. Text types are below.

   FREE         free text. No restraints on content
   NAME         names. Starts with a consonent. Vowels or consonents do not
                appear more than twice in a row
   ALPHA        only letters
   ALPHANUM     mixture of numbers and letters
   " Text "     literal text


Number Types
~~~~~~~~~~~~
DB-FILL can output numeric data in several different types. Use the first
letter of the type.

B - BINARY          0 - 1
H - HEXADECIMAL     0 - F
N - NUMBER          0 - 9
O - OCTAL           0 - 7
T - TEXT            A - Z