BLACKBOOK
by Brian Meier







BLCKBOOK.EXE
BLCKBOOK.DOC



January 15, 1988



Brian Meier
P.O. Box 111146
Arlington, TX 76007











































Program Specifications and Disclaimer




Source Code Language: Turbo Pascal 3.0 &
Turbo Pascal 4.0

(Products of Borland International)

Sorce Code Size :

Compiled Size :

Minimum System Configuration
----------------------------
o MS-Dos 2.0 or greater
o IBM PC, XT, AT, PS/2 or compatible system
o EGA or CGA color monitor
o 128 K memory (More for large number of BLCKBOOK entries)
o Keyboard with function keys F1 - F10 (F11,F12 unused)
o Printer (optional, required only to print reports)



DISCLAIMER : This program is classified as Public Domain.
The user assumes all risk for the use of the BLCKBOOK
program. In no event will Brian Meier, the author of this
program, or distributor be liable for any incidental or
consequential damages arising from the use or inability
to use this program. If you agree to these terms then
your are free to use this program and authorized to
distributed the program freely under the following
conditions:

1) You must distribute the following files as a set
and may not modify any file:

BLCKBOOK.EXE
BLCKBOOK.DOC
BLCKBOOK.DTA

2) If distributed through Computer Clubs or other
organizations, this program may not be sold for
profit, and said organization may not charge more
than $7.00 to cover charges including cost of
media, copying, and shipping without the expressed
written consent of the author, Brian Meier.




















Introduction to BLCKBOOK




Program History:

BLCKBOOK.EXE was written on my own time, on my home
computer, a PC-AT compatible. I wanted a simple program
to keep track of a growing number of personal and business
contacts, including phone numbers, names, addresses, and
an area to place uncategorized information. At the same
time I wanted something a bit nicer than lines scrolling
off my screen. I needed to be able to both view large
portions of a list at a time, or instantly access all the
information on a specific person. There are already a
number of nice programs in the public domain area, but none
did quite what I needed, so I undertook the writing of my
own blackbook program. Turbo pascal has a number of great
features such as textcolor, windows, etc. and I couldn't
resist adding them. After my first 1000 lines of code, I
knew this would be a larger project than I had originally
intended, offering form input and editing, extensive help
screens and error handling, options to search and retreive
forms by name or to page thru the list one form at a time.
Of course the data had to be sorted, and to make the program
complete I added a report feature which allows the user to
visibly mark and unmark form so that selected forms could
be printed in one of several formats. For faster insertion,
deletion, and paging of forms I used a double linked list
to store program data. All data is loaded into memory which
may result in a 2 to 3 second delay to initialize the program
with a large dataset but allows faster overall execution.
I wrote the majority of this program in Turbo Pascal 3.0. I
had ordered and intended to write it in Turbo Pascal 4.0 but
the response to the upgrade offer was overwhelming and I was
further delayed by ordering 3.5 inch diskettes. I received
Turbo 4.0 a few days ago and converted a number if instructions
and datatypes where it would optimize performance. Now I am
just glad to have completed this program which took much of
my spare time for a week and a half. I have always been
supportive of the Public Domain idea (as opposed to the
shareware idea) and for that reason am making this program
public domain. The routines for the display of forms, the
editing of data on the forms, the methods of input from the
form, as well as the routines to diplay, mark, scroll, and
print reports are 100% my own routines, tailored to the
needs of this program. The source code for this program will
be made available by written request -- details are at end
of the documentation. I hope you enjoy BLCKBOOK as much
as I do.
Brian Meier














Using BLCKBOOK.EXE





BLCKBOOK is very easy to use and includes an on-screen display
of the function key uses. In this version the functions keys
are arranged in two vertical rows on left of screen, just like
the keyboard. As this may be troublesome for users with the
enhanced keyboard with function keys in one horizontal row across
the top, I will shortly be uploading a version with the function
keys displayed for an enhanced keyboard. From the main
program you have 10 features available through the function keys
and two more available as control key sequences:

F1 : Move cursor to previous field on the displayed form

F2 : Move cursor to next field on the displayed form

F3 : Display the previous form

F4 : Display the next form

F5 : Search for a specific form

F6 : Save changes to a form

F7 : Add a new form (insert in alphabetical order)

F8 : Delete the currently displayed form

F9 : Enter help facility

F10 : Leave BLCKBOOK and save changes if any were made.

Ctrl-R : Enter Reports facility

Ctrl-X : Exit BLCKBOOK and do not save any changes


The following keys may also be used to perform same action as
some of the function keys:

PG UP : same as F3, move to previous form
PG DN : same as F4, move to next form
Up Arrow, Shift-Tab : same as F1, move to previous form field
Dn Arrow, Tab, Return : same as F2, move to next form field
BckSpc, Left Arrow, Right Arrow : move cursor within a field
but does not erase letters passed over
Insert, Delete : the insert and delete keys are disabled














The following functions are available within the Reports
facility. The function key display will update accordingly.

F1 : Move cursor up 1 line to previous entry. If at top
of window data will scroll down. (also Up Arrow)

F2 : Move cursor down 1 line to next entry. If at bottom
of window data will scroll up. (also Down Arrow)

F3 : Move cursor up 18 lines, thus making top line the
bottom line and adding 17 new entries to screen unless
top entry reached first. (also PG UP)

F4 : Move cursor down 18 lines, thus making bottom line the
top line, and moving 17 new entries to screen unless
last entry reached first. (also PG DN)

F5 : Mark current entry, the highlighted line will be marked
for printing. Marked entries are easily visible as color
of text changed from yellow to red.

F6 : Unmark current entry; highlighted line will be unmarked.
This will change color of line from red back to yellow.

F7 : Select print styles and options. There are 3 output
styles available: Verbose, Address, Phone. These are
illustrated during selection. Two print options are
also available: 1) print all forms, 2) print selected
(marked) forms. Default is to print selected forms.

F8 : Prints all marked files according to options set with F7.
Note that printing does not unmark forms.

F9 : Help facility for Reports facility. When in a help
facility, just push the Fkey or Ctrl-key of the function
you need help with.

F10: exits Reports facility and returns user to place in
main BLCKBOOK program.

Ctrl-X : exits both Reports and BLCKBOOK without saving
changes.
























Usage Examples




This is a sample run of the program using example data set
provided. Following these steps will illustrate the major
features of the program.

1. Put all BLCKBOOK.EXE and BLCKBOOK.DTA on a diskette and
run program from diskette drive. This is in case your
system is not 100% compatible, you would not want disk
writes to your hard disk till the program is tested. I
had the misfortune of getting a Trojan Horse last year,
disguised as a game program, it destroyed much of the
contents of my harddisk before I could stop it.

2. Type BLCKBOOK to start program.

3. You should now see a screen with pfkeys displayed on left
and the current form on the right. The .DTA sample file
includes 4 forms, the form displayed on the screen should
be for John Smith, the last alphabetical entry in datafile.

4. Now hit the F3 key or PG UP key to move to previous form.
Use the F3, F4, PGUP, and PGDN keys to move between forms.

5. Now move to the form for John Doe. Use the F1, F2, Up Arrow
and Down Arrow keys to move cursor to different fields.
Next try Tab, Shift-Tab, and Return to move between fields.

6. Now you will edit the form. Using keys in step 5 to move
between fields and Left and Right Arrow keys to move within
a field, begin typing data on a few lines. Notice that if
you reach end of line, cursor automatically goes to start of
next field. You are also only allowed to type within the
fields, not in other places on screen. Also notice how the
cursor skips over parenthesis and dashes in phone numbers,
these are protected fields that cannot be changed.

7. Now use the keys from step 4 to jump to another form then
return to John Doe. Is the information you typed gone?
If so, then the F6 key was not hit to save changes. If
you edit a form, you must hit F6 to save those changes
before moving to another form or the changes will be lost.

8. Try it again and this time hit F6 before you change forms.
The information you typed will now be on the John Doe form
when you return. Notice that the disk did not update when
you typed save. These changes are saved to memory. Only
when you exit using F10 will the changes be written to the
.DTA file on disk.











9. Now lets try the Search function. Go to any form in the
directory except John Doe. Now hit F5 to search. You
should now see the cursor in a box on lower left of screen.
enter 'Doe' here (don't enter quote marks), and press
return. The current form on Screen should now be John Doe
unless you changed the last name when editing.

10. Select F5 again and this time only enter 'Smi' and hit
enter. The current form is now John Smith. The search
option will thus find partial matches which helps on long
names or names difficult to spell. The case of search
name does not matter; search for 'SMI' is same as 'smi'.
caution: only letter prior to first blank or underscore
are searched on. Also if you have more than one entry
with same last name you may need to PGDN one or two forms
for the one you want.

11. Let's try adding a form. hit F8 to add. You should now
see the same box as is used in search. Enter last name
of person you want to add and hit return. Notice that
you can move cursor withing the box to edit. You should
now have a blank form on the screen with the last name
filled in. Use F3,F4,or page keys to move throught forms
and see that the new form has been added in alphabetical
order. You may now edit the form just as you did with
John Doe earlier. Remember to hit F6 to save after you
edit new form.

12. Now hit F8 to delete the current form which should be the
one you just added. You should enter 'yes' or just 'y' if
if you really want to delete the form or enter nothing and
hit return if you want to keep it.

13. Now let's use the help facility. Hit F9 for help. You
should now have the main help screen. Hitting any Fkey
or active Ctrl-key will give you the help info for that
key. Hitting any key will return you to main help screen.
Hitting F10 from main help screen will exit help facility.

14. Now type Ctrl-X. This sound alarm and give you screen that
you are about to exit and any changes made in the session
will not be saved, nor will additions and deletions. Enter
'yes' or just 'y' to exit or hit enter to return to program.

15. That for the report feature which is almost a program of
its own. Type Ctrl-R to enter Reports features. On the
left notice that the PFkey definitions have changed. On the
right you should see the last name, first name, and phone of
the first 19 people in your directory. Using F1, F2, the Up
Arrow, and Down arrow, move the highlighted bar to various
names. Notice if you reach the top or bottom of window, new
data will scroll into the window.














16. Now hit F3, F4, PGUP, and PGDN to move up or down the list
a page at a time.

17. F5 and F6 are used to mark and unmark entries for later
printing. Hit F5. Notice that the text on the highlighted
line changes from yellow to red. This is how you can tell
that an entry has been selected. Move to different names
and hit F5 to mark them.

18. (optional) now turn on your printer and making sure it is
ready and online. Hit F8 and you will see the lines you
selected printed. The default version of data is printed,
unless you have changed the print styles and options in
the current session. You may also select style to print
address and name, or style to print all info.

19. Now move cursor back over marked entries and hit F6 to
unmark them, changing their color back to yellow. If you
are leaving report facility there is no need to unmark the
names, it will be done for you.

20. Print styles and options. Hit key F7 to select the desired
printing styles and options. Hitting key 1, 2, or 3 (these
are the number keys, not function keys) will display style
1, 2, or 3 on the screen. When you hit return, the style
currently displayed on screen will be used for printing
until you select another style or restart the program.
Style 3, full name and phones, is the default style.
You may then select either option 1 to print all forms or
option 2 to print selected forms. Default is option 2 to
print selected forms.

21. Hit F9 for help. The help facility functions in the same
way as the help facility for BLCKBOOK.

22. Hit F10 to leave reports and return to BLCKBOOK.

23. Now hit F10 to exit BLCKBOOK and save you changes or hit
Ctrl-X to exit without changing datafile.

24. You have now finished the BLCKBOOK tutorial. Please read
the following warning.


NOTE: Data is only sorted when a new form is entered. Last
names rarely change except for marriage. Should you
need to change a last name, do not just edit the form
to show the new last name, because you would then have
a different last name in the alphabetical position of
the first. This will cause further problems when you
add other entries and pass this entry which is out of
order. If a last name changes you need to delete the
old form and add a form with the new name. Version 2
of BLCKBOOK will definitely contain an option to resort
the directory. In the meantime, you may wish to request
the source code as indicated at end of this document and
add your own sort routine.
















Comming Attractions





Though I have only just finished Version 1.0 I am an industrious
person who enjoys writing programs and will probably have
Version 2 complete in February or early March. Perhaps longer
if I take time to alter BLCKBOOK 1.0 for the enhanced keyboard,
or if I decide to write a checkbook program first which could
delay version 2 till June.
Here are some of the features you can expect:

o Ctrl-S to resort directory after last names have been
changed.

o Ctrl-P to print info on current form without having to
enter Reports utility.

o Variant Records : this will allow 2 or 3 different formats
for bussiness, personal, etc. You can choose which form
is best for the entry you are using.

o Allow search on any field, not just last name.

o Allow configuration file to set colors of menus, some
text, and to set defaults for printing Styles and options.

o Implementation of subdatabase chains, allowing user to
assign forms to specific subdirectory and then to work
and search in given subdirectory or the whole directory.
(maybe, I haven't decided for certain yet. This would be
good for separating business and personal addresses)

o Allow user define print styles for Reports functions.

o Any other useful features which you may suggest to me
will be taken into consideration.


--------> I would welcome any suggestions, comments, praise
constructive criticism, or reports of bugs. You may contact
me at the address given later in this documentation, or at my
new Email address on GEnie: 'B.MEIER'
























Obtaining Source Code for Customization



As indicated earlier, you may request source code for this
program by writing to me at:

Brian Meier
P.O. Box 111146
Arlington, TX 76007


The charge for this is $6.00. This will cover cost of disk,
packaging, and first class postage, and help defray the cost
of the time it will take to prepare extra documentation for
this. In addition to the actual source code, there will be
documentation explaining each procedure and how I accomplished
each task such as forward and reverse text scrolling, and form
input. A knowledge of data structures such as double linked
lists and pointers is assumed. This code may be compiled
using turbo pascal 4.0, or using turbo pascal 3.0 after changing
a few lines. You may also make changes to customize this
program to your needs. However NOTE: while your are permitted
to customize the program to your needs and to use the ideas
given in my procedures, you may not distribute any altered form
of the program. This program may only be distributed in its
unaltered form and with all three original files. The source
code will be available after the February 14, 1988. No checks
please. I would welcome any suggestions, comments, praise
constructive criticism, or reports of bugs. You may contact
me at the above address, or at my Email address on GEnie :
'B.MEIER'



Late Update : in the final testing of this program, another user
reported that after printing all forms, and returning to the
report list, the data would scroll but the highlight bar was
stuck at the bottom of screen. Hitting F10 to return to main
program and then Ctrl-R to reenter reports cleared problem. I
am currently investigating this.