Documentation for
BF-EDIT.EXE
copyright 1990

written by
Douglas K. Brecht


Important: Press F1 for HELP in BF-EDIT


DISCLAIMER

The BF-EDIT program comes "AS-IS", without warranty of any kind, express or
implied.

Under no circumstances shall Douglas K. Brecht be held liable for any damages
whatsoever arising out of the use of, or inability to use this product,
including but not necessarily limited to, damages for loss of business
profits, business interruption, or business information.

All reasonable efforts have been made to ensure the reliability of this
product. If for any reason the accuracy or reliability of this product is
compromised, including reasons of oversight and/or negligence on the
part of Douglas K. Brecht, your sole remedy shall be a refund of any
registration fees paid. In lieu of a refund, Douglas K. Brecht may, at his
option, fix the problem which caused the unreliability.


REGISTRATION

BF-EDIT is distributed as a shareware program. If you find BF-EDIT to be
useful, and use the program, a registration fee of $10 is greatly appreciated.
Registered users will be notified of future releases, and may write for
support at the address below, or on Compuserve (#72701,2263).

ALL users (registered or not) are encouraged to report any problems
encountered in running BF-EDIT, and to suggest additional features or
enhancements. I **hope** to have complete Search & Replace features soon, and
possibly some kind of data conversion, that would output selected fields in
various formats. Let me know what you'd like to see.

Douglas K. Brecht
RR#2 Box 198
Claremont, NH 03743


WHAT BF-EDIT DOES

BF-EDIT allows editing fixed record length files, such as Basic (or QuickBasic) random access files. This includes not only text, but data stored
as integers, single or double precision numbers, and so on. BF-EDIT actually
stands for asic ile or.

BF-EDIT allows searching your files for either text or numeric values.

BF-EDIT is a great debugging aid to quickly see what data is really in your
files, without writing an edit program for every file structure you create.

BF-EDIT is actually quite similar to the BROWSE feature in dBase



WHAT BF-EDIT DOES NOT DO

BF-EDIT does not edit variable length records (such as most sequential files).

BF-EDIT does not edit Btrieve or dBase files.



THE "BF-EDIT" CONCEPT

BF-EDIT arose from the need to view and edit data files containing not only
strings, but integers, long integers, and single and double precision numbers.
Text editors, PATCH, and the like are generally limited in that:

Numeric entries are not displayed in a usable form.

You therefore can't search for numeric values or ranges of numeric values.

While text editors allow you to perform string searches, you generally can't
search for strings found only in particular fields

BF-EDIT does display numeric entries in a usable form, allows searching for
specific values or a range of values, and allows searching for strings in
specific fields. Any information in the file may be edited.

While you could write programs that do this for each file structure you use or
create BF-EDIT provides these features by just specifying the field layout. For
example, if you have a 64 byte record layout that contains both string and
numeric data, you could quickly create a "Type file" that details this record
layout:

Cust Num as integer
Last Name as string * 25
First name as string * 20
Balance as double
Acct. Type as integer
Nil as string * 7

With just this information, you can view your customer file, search for a
specific customer number, view all your customers named "Jones", or those with
a balance over $2,000. Any information can be edited. Records may be appended
to the file.

QuickBasic 4.xx users may recognize that format as similar to a TYPE
declaration. This is intentional, and allows type declarations (such as in an
include file) to be used directly as BF-EDIT type files. For instance, if your
include file actually looked like this:

TYPE CUST
Num AS INTEGER
LName AS STRING * 25
FName AS STRING * 20
Balance AS DOUBLE
AcctType AS INTEGER
Nil AS STRING * 7
END TYPE

you could use it as your BF-EDIT type file with no modifications whatsoever.


RUNNING FROM THE COMMAND LINE

When running BF-EDIT from the command line, the syntax is:

BF-EDIT /T:type file /D:data file /S:start record /MBF /GO

NOTE: ALL of the parameters are optional, and their order is not important.

/T:type file specify the name of the type file, including drive and path

/D:data file specify the name of the data file, including drive and path

/S:start record you may specify the lowest "legal" record number, such as to
avoid accidentally editing header records

/MBF specifies that the single and double precision numbers in your file are
in MBF format. BASICA, GW-BASIC, and QuickBasic (version 1-3) files should use
the /MBF parameter. QuickBasic version 4 and higher uses IEEE format files as
the default, but also support the MBF format.

/GO to indicate that you don't want to view the opening screen, or review
your parameters before starting to edit. If you use the /GO option, you must
have also specified the Type file and Data file. This is most often used as part of a batch file that is specifying all the needed parameters.


ENTERING THE PARAMETERS FROM WITHIN BF-EDIT

If you do not enter the Type file name, Data file name, or starting record
number on the command line, you may enter them when prompted inside BF-EDIT.


CREATING YOUR TYPE FILE


The TYPE file must be pure text, and can be created using whatever text-editor
you generally edit program code with. If you use a word-processor such as
WordStar make sure that you do so in the Non-document mode.

If you enter a non-existing TYPE file name inside BF-EDIT you will be asked if
you want to create that file. If you respond with a Y, you can then create your
TYPE file using BF-EDITs built in editor.


WHAT GOES IN THE TYPE FILE?

You must list the name and type of each field used in your file. An example of
a TYPE file is:

Custnam AS STRING * 30
' last name, then first
Custnum AS INTEGER
Balance AS DOUBLE
PhoneNum AS STRING * 18
Nil AS STRING * 6

Important: the total length of the fields listed in the type file must EQUAL
the actual record length. If you do not use all the characters available, use
"phony" fields (such as the field labeled "Nil" above) to make the total equal
to the record length.


THE RULES: GENERAL

Each line in the Type file can contain an instruction, a comment, or both. Any
line that does not have the word "AS" in it, or any line that starts with an
apostrophe, is treated as a comment. Each line in the type file may be any
length, however lines of 72 characters or less are recommended. Lines longer
than that can not be edited in the BF-EDIT program.

Capitals or lower-case letters are both acceptable.


THE RULES: FIELD NAMES (labels)

Each instruction line should start with the name of the field. These field
names may be up to 12 characters long and may contain spaces. The only
restrictions are that the field name may not be "AS", and should not have a
forward slash "/" in it. The following are all valid field names:

Cust Num
Acct Balance
Account Balance (only 12 characters, "Account Bala", will be used)
Date
Name

The field name MUST be followed with the word "AS"


THE RULES: NUMERIC ENTRIES

The syntax for listing numeric fields is:

fieldname AS [INTEGER, LONG, SINGLE, DOUBLE, CHAR]

Integers are stored as 2-bytes in the file, Long integers as 4-bytes, Single
precision numbers as 4-bytes, and Double precision numbers as 8-bytes.

You will not be allowed to enter any value that is larger or smaller than that
variable type allows.

Quite often files will contain a 1-byte character that stores a value from 0
to 255. The value of those characters can be viewed or edited using the CHAR
type.



THE RULES: STRINGS

The syntax for listing string fields is:

fieldname AS STRING * length

Strings can be from 1 to 65 bytes long. If your file has longer strings, you
must divide them up among several smaller string fields, each no more than 65
bytes. For example, to list a string 80 bytes in length, you could do it like
this:
Descript1 AS STRING * 65
Descript2 AS STRING * 15

or like this:

Descript1 AS STRING * 40
Descript2 AS STRING * 40


THE RULES: MODIFIERS

In addition to specifying the fieldname, and type of variable, there are also
certain modifiers than can be used at the end of a description line in the
TYPE file. The following screens will describe them:


THE /IGNORE MODIFIER

You may tell the BF-EDITor to ignore any field that you do not want to display
or edit from within BF-EDIT. This is commonly used to ignore "nil" fields;
fields used as character placeholders without really containing any data. For
example:

Nil AS STRING * 6 ' /IGNORE

Note that in the example above, the apostrophe is not required. Using the
apostrophe before the modifier does allow you to use the TYPE file as an
INCLUDE file in a QuickBasic program, however.


THE /NUM MODIFIER

Within BF-EDIT, fields that are always numeric (integers, longs, etc.) are
treated differently than strings. Only numbers, decimal points, and plus or
minus signs are allowed. Also, searching numeric fields allows you to look for
a numeric range of values, rather than a specific string pattern. Using the
/NUM modifier imparts those same conditions on string fields.


An example would be if you store invoice totals as a string in your file.
Since you don't want anyone accidentally typing in non-numeric characters, and
you might want to search for an invoice value or range of values, you might
want to include the /NUM modifier to the end of the description line, such as:

InvAmount AS STRING * 10 /NUM

This would restrict entry of that field to numeric characters, and allow you
to search for invoice totals between, say, 1,000 and 2,000 dollars.


THE /MBF MODIFIER

If some of the Single or Double precision numbers in the Data file are in the
MBF format, you can use the /MBF modifier on that line. Otherwise, the number
will be interpreted as being in the IEEE format...and the number displayed
will be wrong. BASICA, GW-BASIC, and QuickBasic before version 4 use only the MBF format.

THE DATA FILE: /D:
The DATA FILE is your file that you wish to edit with BF-EDIT. It must
be a fixed record-length file, such as a Basic random access file. Files with
variable length records (such as most sequential files) can not be edited with
BF-EDIT. Specify here the complete path name to the file, such as:

D:\ACCT\CHECKFIL.DAT


TIPS

*** The most common problem I have encountered myself is in incorrectly
specifying the record length. In other words, I might have a file with a
64-byte record length, but in creating my Type file I only specify, say, 63
bytes. This problem is easy to detect because the first record will generally
look fine, the second record will have its data "shifted" by 1 or more bytes,
and each succeeding record will look a little worse.

*** If the floating point numbers in the file are incorrect, it may mean that
you need to specify the /MBF option when calling BF-EDIT, or use the /MBF
modifier on each line that uses MBF single and double precision numbers.

*** When programming in QuickBasic, I put most of my TYPE declarations in
Include files. I then use those Include files as BF-EDIT Type files as well.
Put any modifiers AFTER apostrophes so that QB will ignore them; BF-EDIT still
uses them. For instance:

InvAmount as string * 10 '/NUM
Nil as string * 4 '/IGNORE

In both these cases the modifier will be seen by BF-EDIT, but ignored by QB.

*** There is On-line help everywhere in BF-EDIT. Simply press F1.