ata ase

version s0.5



INTRODUCTION
This is a limited version of MUSIC Db, v1.0, and replaces the previous
beta version originally released as shareware in November of 1991.
Many features were added to the program as a result of suggestions made by
the now-registered users of that beta version who felt it was a program with
potential, worth registering and supporting. As more viable
suggestions come in, and more ideas are implemented, even better future
additions of MDB will become available for registered users.

Those of you who decide to register this version will be getting a good
bargain in comparison with other shareware products currently available.
Not only will you get the new v1.0 for your $25 fee - you will also get
the next two major updates free of charge, and all other benefits outlined
near the end of this document! (Many other packages cost more, and only
offer updates at reduced cost.) YOU SHOULD TAKE NOTE, HOWEVER, THAT THIS
OFFER WILL ONLY APPLY TO THOSE REGISTERING FROM THIS RELEASE. FUTURE
OFFERINGS WILL BE MORE EXPENSIVE AS COSTS INCREASE, AND LESS GENEROUS
IN REGARDS TO UPDATES. (For example, postage costs in this country rose
by almost 10% in one jump at the beginning of this year!)

I have done a great deal more testing on this version of the program, but
there may still be little bugs that didn't show up for me. Reports of such
glitches would be much appreciated. Methods of contacting me are outlined
at the end of this document. (Please note that the Towerview Drive address
will be changing as of the first of April, 1992. At that time, I will
replace existing copies of the package with ones including the new address,
which at this time is unknown. However, mail will still be forwarded from
that address for a three month period, so there should be no problems.)

In this version of the documentation, I have included information on each
of the updates and fixes made to the program to date. I have also noted
where these features are disabled, or limited in functionality. In the
TeX version of the documentation, information on updates and disabled features
will appear in bold type, to set it apart visually from the original text.

WHAT DOES MUSIC Db DO?

Primarily, it stores information about your music collection, generates
printed reports of the information you have stored, and displays listings
of a set of albums specified by a user-selected search key. (I will use
the term 'album' generically throughout the remainder of the document.) For
each album, it stores artist, title, musical classification, media, and up
to 30 songs, or 15 song/artist pairs (for various-artist compilations).

You can select a subset of the albums stored, based on any one of these
qualities, and display/edit/delete them on-screen. You may also print the
selected subset in short or long listings, or print the entire database in
short listing form. As well, you can generate an ASCII delimited text file
of all records in the database, suitable for importing into other
commercial packages, such as Lotus or dBase. (The database file itself is
in dBase III+ format, and can be opened directly by any package which
recognizes that format.)

The program will display in colour on a screen with a colour monitor, and

in monochrome on a monochrome monitor. It tests the system configuration to
see if a colour adapter is installed. If it is, colour is added to the
display. (Please note that this system can be fooled by certain system
configurations. I have only had the opportunity to test it on a VGA colour
system, and a Hercules Mono system.)

SETTING UP THE PROGRAM

The registered version of the program comes on a single installation disk,
in ZIP format. It includes the following files:

> MDBDOC.TXT - This file in ASCII format
> MDB.EXE - The program itself
> MUSIC.DBF - The database structure file
> MDBLOGO.GIF - A GIF picture of the new MUSICDb logo for v1.0

The program may be run from any directory, as long as the file MUSIC.DBF is
in the current directory when the program is run. If it isn't, an error
message will appear on screen, and program operation will be halted.


RUNNING THE PROGRAM

While in the same directory as the database file MUSIC.DBF, type MDB at the
DOS prompt to run the program. The introductory screen should then appear,
prompting you to press any key to start using the database. A menu then
appears offering the following choices:

> Select/Create a database file
> Enter new album information
> View/edit/delete album information
> Report Printing
> Perform a Song Search
> Quit and exit

Select one of these by using the UP and DOWN arrow keys on your numeric
keypad to highlight your choice, then press ENTER. Note that menu wrapping
has now been included, so that at the top or bottom of the item list, both
arrow keys are still valid. For instance, while at the top item, pressing
the Up arrow key will wrap around to select the bottom item (quit and
exit). This feature has been added to all menus in the program. As well,
you may now press the first letter of the menu item in most menus to select
that item. (This will not work well with menus where two or more items
start with the same character; I've tried to avoid this happening, but have
not been totally successful. The Class menu, for example, is unchanged to
maintain compatibility with records created by the beta release of the
program.)

An important new feature to note is the inclusion of help screens at each
of the main levels of the program (six, in total). Each one gives a few
important pieces of information about any special or unique features
available at that level, and is called by pressing the F1 key at any time.
After you finish reading the screen, press any other key and continue at
the point in the program from which you called the help screen. The help
facility might be expanded in future editions, as dictated by user response
and new features.

1) Select/Create New Database File

When MDB starts, it automatically loads the file MUSIC.DBF (if it finds
it). However, this option allows you to switch the database file in use,
or create another empty database file. A menu first appears listing these
options, and you are prompted to select the one you require. Selecting
either option clears the screen and calls a directory listing of all
existing .DBF files in the current directory. If you are opening one, you
are prompted to enter a filename from the list; enter the name only,
without the .DBF extension. If you are creating a new file, you are
prompted to type in a name (no extension) that does NOT appear on the list.
If you enter incorrectly, the input slot clears and you prompted to try
again, this time referring to the list in the top half of the screen.

Note that the new file (when one is created) has exactly the same file
format as MUSIC.DBF, except that it contains no records. Note that you may
also switch back to MUSIC.DBF from another file using this option. (From a
suggestion by Ari Kahan).

[ IN THIS LIMITED VERSION, YOU ARE ONLY PERMITTED TO WORK WITH THE DATABASE
FILE MUSIC.DBF. THE SCREENS FOR THIS FEATURE HAVE BEEN LEFT INTACT FOR
DEMONSTRATION PURPOSES ONLY. YOU WILL NOT BE ALLOWED TO OPEN OR CREATE
ANY OTHER DATABASE. ]


2) Enter new album information:

Select this option to catalog a new album. When selected, a new screen
appears, with a prompt near the top left corner of the screen asking you to
enter the artist's name. When finished, press ENTER. You are then
prompted for the title of the album just below that. Again, type in the
title and press ENTER.

[ IN THIS LIMITED VERSION, ONLY 50 RECORDS MAY BE STORED IN THE DATABASE
AT ONCE. ATTEMPTS TO ENTER ANY MORE WILL BE MET WITH AN ERROR MESSAGE. ]

Next you are prompted for the MEDIA. A small menu will appear, offering a
number of possible choices. (The only choices not offered here are Cassette
singles and 45RPM vinyl singles. I hope to do a similar program for these
in the near future.) Use the up and down arrow keys to highlight your
choice and press ENTER. The next prompt to appear, CLASS, also brings up a
menu of possible musical classifications into which you may place the
album. (Note here that the choice is a little limited. In future
editions, I may attempt to expand the list a bit, but with the diverse
genres of music today, I decided to stick to these few basic ones.) As
with the MEDIA menu, highlight your choice and press ENTER.

After this, the rest of the screen fills with positions for song titles. As
you will note, this portion of the screen is divided into two columns,
labelled SONGS and ARTISTS (IF DIFFERENT). These labels are by no means
restricting. You actually have a number of entry options.

> For tapes of LP's, you can put A-side selections in the first column,
and B-side selections in the second column.
> You can put all album selections (up to 15) in the first column and
leave the second column blank.
> For compilations, follow the labels.
> For albums with more than 15 songs, put titles in both columns.

The thirty spaces are there to be used as you require...different albums
may require different layouts. For box sets, for example, I sometimes add

(part1), etc., to the title, and list the songs over a couple of entries.
It should likely be noted here that no entry in any of the fields needs to
be unique for searching purposes. Also to note is that you may now
selectively perform a song search on either or both of these two columns.
This will be discussed in more detail later.

When you have finished each entry, press ENTER. If you need to back up to
correct a previous entry, use the up arrow key. When finished, press PAGE
DOWN on the numeric keypad, which will store the entry. By the way, if you
need to go back and correct an entry after pressing PAGEDOWN, you may use
the EDIT mode in option 2 from the main menu (to be discussed shortly).


3) Edit/View/Delete album information

When you select this option, the screen will clear, and a small menu will
appear asking you for the search key to be used in selecting the subset of
records you want to work with. This subset may contain from one to all
existing records. Highlight your search criteria, and press ENTER. If
ARTIST or ALBUM is selected, type in all or part of the name to search for.
For example, entering CHRIS for artists would select all entries by artists
such as CHRIS REA, LUTHERAN CHRISTMAS CHORUS, and so on. If MEDIA or CLASS
are selected, you will be presented with the same menus used in the Album
Entry portion of the program, and the selection is made is the same manner.
For example, selecting HOME from the MEDIA menu will set up your subset as
all home recordings.

Once the choice is made and the subset established, the first record in
that subset appears on the screen, in a format similar to that used for the
data entry screen. One feature of this screen has been altered. Now,
below the information, the counters tell you how many matching records were
found, and which of these you are now viewing. (Thanks again, Ari!)} Below
the display is a set of valid command choices, instructing you as to which
keys will perform which actions. Pressing the F5 key will begin editing the
current record, F6 will delete the current record, F7 will display the next
record in the subset, F8 displays the preceding record, F9 prints the
displayed record, and F10 quits and returns to the main menu.

If you select to print or delete the current record, you will be prompted
for confirmation before any action is taken. Answer with one of the valid
options listed in the prompt. If the record you are deleting is the only
one in the currently selected subset, the screen will clear and you will be
returned to the main menu level. Printed output from the PRINT option (F9)
outputs a complete record to the printer, including all song and artist
fields. Starting at the top of the page, it outputs the complete record,
followed by a form-feed to eject the page. [ IN THIS VERSION, A SHORT
COPYRIGHT NOTICE WILL ALSO BE PRINTED ON THE PAGE. ]

For editing, you may move between fields with the up and down arrows. The
field currently being edited will be highlighted. Note that you are able
to change the MEDIA and CLASS field information while editing here. It is
highly recommended that you do not, however, since searches and reports
only recognize a small subset of values for these fields. Any other value
will always cause the record to be omitted from any subset generated for
these purposes.

When viewing records using the NEXT and PREVIOUS keys (F7 and F8), when you
try to go beyond the last record in the selected set, the screen will blank
momentarily, then restore the last valid record displayed. At the start of
the file, the same record will stay on screen while you press the F7 key.
Note that if there are no records matching the specifications you request,
an error message will appear on screen until you press ENTER. This will
return you to the main menu level.

4) Generate Reports

In version 1.0 of MDB, you have the option of three printed report
formats, or output to a delimited ASCII text file. The first includes
every record in the database, and prints only the album title, artist, and
media type. Each album in the database is listed on a single line. The
second option outputs to the printer in the same format, but allows you to
select a subset of records to include in the report. The third option was
designed for outputting reports containing smaller numbers of records. It
outputs complete records, three listings per page. It also provides the
means to select your subset for inclusion. The last item in this submenu
quits and returns to the main menu level.

When you select the first option, you are prompted before the report is
printed. This allows you to make sure your printer is turned on and the
top of the page is properly set. When you are ready to print, type 'Y' and
press ENTER. The second and third options allow you to select a subset of
records using the same menus and prompts as were used in the second main
menu option for selecting records to view. You select the search field,
and provide a value to be used to filter the records into your subset. When
your selection is complete, and a valid subset containing one or more
records is selected, you will be prompted to press 'Y' when you are ready
to begin printing. Here again, you are given the chance to abort the print
job and start over, or get the printer set up and instruct printing to
begin.

The text file outputs a single line for each record in the database to a
text file called ALBUMS.TXT. The line contains the ARTIST, TITLE and MEDIA
for the record. These three fields are comma-delimited with the contents
of the field contained within quote marks. This style is recognizable by a
number of spreadsheet and database programs. I personally use QUATTRO
(Borland) on the IBM and MS-Excel on the Macintosh. It works with both.
Note that the output is indexed alphabetically on the ARTIST field.
[ THIS ITEM IS TOTALLY DISABLED IN THIS VERSION OF THE PROGRAM. ]

Just after you are asked to confirm printing of the report, another small
menu appears, asking where to direct output to. This will permit output to
a second printer, or to a text file. The program defaults to the port
normally accessed by the DOS PRINT command (PRN:). This selection can be
used to over-ride this setting. If you choose to output the report to a
text file (the last option on the menu), you will be prompted to enter an
eight-letter filename (no extension --- PRN is appended automatically).
[ OUTPUT TO A TEXT FILE IS DISABLED IN THE LIMITED VERSION. YOU MAY
ONLY DIRECT THE SELECTED REPORT TO A PRINTER PORT. AS WELL, ALL
PRINTOUTS WILL INCLUDE A COPYRIGHT LINE IN THE HEADER OF EACH PAGE
OF THE REPORT. THIS LINE DOES NOT APPEAR WHEN USING VERSION 1.0. ]

When you select an alternate port, make sure your printer is set up for
that port. Remember that the program expects the printer it finds to be a
regular dot matrix printer, and will not generate special codes (such as
postscript) for fonts and formatting required by some types of printers. A
rule-of-thumb is that, if you can print a text file on the printer using
the DOS Print command from the DOS prompt, it should work here.


5) Song Search

The fourth item on the main menu allows you to search the database for a
specific song title, or part of the title. When selected, the screen is
cleared and you are prompted for a string to search for. This can be a
complete or partial song title. The search is not case-sensitive, meaning
that an `s' will match an `S' in the song title.

Another menu appears after this, prompting you for which columns to search
in. As you will recall, the song titles can be stored in either of the two
columns in each record, on the option of the user. If your data is stored
in the first column only, you may elect to search only that column, thus
cutting the search time in half. (The time saving is based on a worse-case
scenario; when the first match is found in a record, the remaining fields
are skipped. Thus, only one or two fields of the possible thirty may be
searched in some records, thus cutting the time even further.) (From a
suggestion by Ari Kahan.)

Once this selection is made, the program will then begin the search.

Keeping in mind that song titles may appear in any of the 30 provided
spots, each of those fields is searched in every record in the database
until a match is located, and the matching record numbers (if any) are
stored to be recalled by the program. If no matching strings are located,
the program will report this. Otherwise, it will begin displaying them.
Below the record display appears the number of matches located, and which
of the matches you are viewing. It should be noted that because of the
nature of the search, it can be quite slow for large databases.

During displaying of these records, you have only 3 valid input options: F8
to view the next record, F9 to print the current record, and F10 to exit.
Exiting returns you to the main menu level. When you press F8 at the last
record selected, you are returned automatically to the main menu level.

5) Quit/Exit the program

This option does exactly what it says. It stops program operation, and
returns to the DOS prompt.


COPYRIGHT AND LICENSE INFORMATION --- SINGLE USER

Now for the boring, but necessary portion of the documentation. Please do
not be put off by any of the material below. It is placed there for
personal protection, after hearing many horror stories about the plight of
some shareware authors. While I have done my best to see that the program
is bug-free, and the material I've included in this documentation is as
complete and accurate as possible, it is entirely conceivable that I have
missed something or done something incorrectly. If so, I apologize up
front. This is the first general-usage program I have released, having
programmed exclusively for personal or private uses in the past. Plus, not
even commercial packages are all bug-free (look at PCTools 7.0!). Be only
assured that I have done my best to test and debug the package, considering
that this is done as a spare-time project only. Had I prepared this
program solely for personal use, much of the approximately 60 hours of
effort I put into it would not have transpired. For this reason alone, I
place the following restrictions on the use of this software program.

> Holders of the shareware version of the program, v0.5s, may copy and
distribute that version freely, as long as no financial consideration
is involved in the exchange. Any copies made of the program for
such distribution MUST include all files discussed in this document,
in their original, unaltered form, as created by the author of the
program.

> Users of the shareware version of the program, v0.5s, may use the
program for a period of 10 consecutive days after obtaining the
program. After that period, the user must submit a
payment of $25 (US or Canadian dollars) to the author of the program,
as outlined later in this document, to obtain a fully licensed and
registered version of the software. If the user does not choose to
register the software in this manner, he/she must erase all existing
copies of the software (including all files and documentation) in their
possession after the 10 day period previously mentioned.

> The expected use of this program is for personal storage of
information about the user's music collection, as described in the
documentation, and it is intended for personal pleasure use only. The
author assumes no responsibility for any losses incurred as a result
of the use of the program for commercial or other purposes.

> The author of this software will assure that registered users receive
upgraded versions of the program as they are made available by the author.
By prior arrangement with the purchaser of the program, the method of
shipment will either be by Internet electronic mail, or by Canada Post.
This, and all other warranties described herein, are extended ONLY to the
original registered owner of the software. The registered user is
entitled to receive their original registered copy, plus two additional
updates in the agreed-upon manner.

> The author warrants that the software will perform its intended task,
as described in the accompanying documentation, and that the author will
correct, at no additional cost to registered users, any variances in MDB's
operation caused by errors in the program code (incompatibility with the
users' particular hardware, or with other software packages, are not
acceptable criteria for this warranty). A corrected version of the MDB
software will then be supplied to the registered user. The liability of
the author, and your sole remedy will be restricted to this action.
Because of the low volume of licenses, each copy of the software issued
by the author will be checked for media damage (where applicable) and
data corruption. Replacement of software damaged in transit or after
arrival will be done via Internet electronic mail if at all possible. If
not possible, a new installation disk will be mailed via Canada Post to
the licensed user. No such warranty or recourse is offered users of an
unregistered copy of the software.

> The author offers no warranty as to the compatibility of this program
with other software or hardware, and accepts no responsibility for the loss
or damage to hardware, software, or data related to the use of this program
or its interaction with other software/hardware/data.

> The original software was checked as thoroughly as possible by the
author before release to guard against computer viruses and other Trojan
programs, and was, to the best of his knowledge, free of such things. The
user is encouraged to run their own tests, however, on a regular basis.

> The software and its documentation is owned by David Brown (JDB Software),
and protected by Canadian and International Copyright laws and treaty
provisions. Neither the software or documentation may be altered without
express consent of the author.

> You may not lease, rent, or sub-license the software. You may not
decompile or otherwise disassemble the software, nor make derivative works
from it. You may not sell or transfer any copies of the software, and
retain use of a later copy which has been issued as an update to the version
being transferred. This does not apply to newer copies for which a new
license is purchased.

CONTACTING THE AUTHOR

If you wish to contact the author of the program for any reason (such as
with a bug report, suggestions, or for technical assistance), you may do so
by mail to the following address:

David Brown
39 Towerview Drive, Apt. 104
Halifax, Nova Scotia, Canada
B3P 2J4

PLEASE ADDRESS YOUR REGISTRATION FEES TO THAT, OR THE FOLLOWING, ADDRESS.
REMEMBER TO ENCLOSE A CHEQUE OR MONEY ORDER FOR $25, ALONG WITH YOUR
RETURN ADDRESS, PREFERRED MODE OF RECEIVING UPDATES (E-mail or postal),
AND THE SIZE MEDIA ON WHICH YOU WOULD PREFER THE INSTALLATION PACKAGE.
CANADIANS MAY SUBMIT THEIR REGISTRATION IN CANADIAN FUNDS. AMERICAN AND
INTERNATIONAL ORDERS ARE ASKED TO SUBMIT PAYMENT IN US DOLLARS. (Orders
submitted in other currencies will be accepted; the total, however, must
be equivalent to $25 in US funds, plus an additional $1.50 US for bank
exchange fees.)

(Please note that this address will be changing as of the 1st of April,
1992. After March 1, 1992, please address mail to

David Brown
Dept. of Mathematics and Computing Science
Saint Mary's University
Halifax, Nova Scotia, Canada
B3H 3C3

[DISCLAIMER] Saint Mary's University is in no way associated with this
project, or JDB Software.

(c) 1992 by JDB SoftWare (David Brown)
39 Towerview Drive Apt. 104
Halifax, Nova Scotia
Canada B3P 2J4

Phone: (902)420-5893 (days AST), (902)479-0910 (evenings AST)
E-mail: [email protected], [email protected]