SEARCH - The BBS Message Searcher Version 1.32 Page -1-
Copyright (C) 1989 by Don Lewis. All rights reserved.
Documentation for
BBS message SEARCHer
Copyright (C) 1989
by
Don Lewis
5207 Mossgrey Ln.
Spring, Tx. 77373
AC 713-353-5295 (after 6:00 P.M.)
*** NOTE ***
This program is SHAREWARE, not FREEWARE! It is Copyrighted and
remains my property. If you try it, and find it useful, please
send $10.00 to me at the above address and I will send you the
latest version on disk. If you do not find SEARCH useful, please
pass the .ARC file on to someone who needs it.
*** Once a registered user, always a registered user. ***
I have a number of ideas to add to SEARCH, and I plan to continue
to release new versions of SEARCH (if enough people find it use-
ful and register). Registered users may update to the latest
version by sending me the original distribution disk and a
stamped, self-addressed floppy disk mailer.
I will gladly provide telephone support to registered users.
Unregistered users who are having problems can take their
chances. Anyone who suggests a useful modification which I use
in a later version receives the latest version on disk and
becomes a registered user.
SEARCH - The BBS Message Searcher Version 1.32 Page -2-
Copyright (C) 1989 by Don Lewis. All rights reserved.
******** NOTICE: ********
The following describes the legal basis under which SEARCH and
its associated files is distributed. If you disagree with these
terms, please destroy all copies of the files, all printed mate-
rial and forget you ever heard of this...
Thanks
/Don Lewis
Now for the legal-eagle detail...
SEARCH is provided on an "as is" basis without warranty of any
kind, express or implied. In no event will Don Lewis (hereafter
referred to as the Author), be liable to you for any damages,
including any lost profits, lost savings or other incidental or
consequential damages arising out of the use of or inability to
use SEARCH, even if the Author has been advised of the possibil-
ity of such damages, or for any claim by any other party.
Your use of SEARCH is at your own risk, and by your use of it,
you agree to indemnify and hold harmless the Author, his heirs
and assigns from any legal action arising from your use of SEARCH
for any purpose whatsoever.
The version of SEARCH referenced in this document supersedes all
previous versions. The Author advises that all previous versions
of SEARCH be destroyed.
Whew! I hope that deflects the hungry lawyers to a more helpless
target (or one with deeper pockets).
SEARCH - The BBS Message Searcher Version 1.32 Page -3-
Copyright (C) 1989 by Don Lewis. All rights reserved.
SEARCH was written to deal with a problem I had as I was doing
Genealogy research. There were so many messages posted on a
local Bulletin Board from the National Genealogy Conference, that
I used all my on-line time each day just reading. I decided to
capture all the new messages and read them offline. That took
much less online time, but then I had to read through
** HUNDREDS ** of messages looking for those few which referred
to something I needed.
SEARCH quickly reads all those messages for me now, compares each
one to a list of words I am looking for, and then makes a file
containing ** ONLY ** those messages which matched.
SEARCH should also be useful to CompuServe(c) users, GEnie(c)
users, members of The Source(c), or anyone who uses a BBS which
handles lots of messages.
Preparing to use SEARCH
-----------------------
Like everything designed to save time, a little effort must be
spent getting ready. To keep SEARCH relatively small and fast, I
have not used elaborate error-checking for files that you will
create. Please carefully follow the steps below, and your trou-
bles will be few...
1) Using your terminal program (I'll not attempt to
instruct on that, as there are a myriad of different
terminal programs), dial up your BBS. Select the BBS
command to read messages without stopping, and have
your terminal program capture the messages in a file
having the following name:
MMMDD.NNN
where:
MMM is the three-letter month name e.g. JAN
DD is the two-number day-of-the-month e.g. 10
NNN is the three-letter BBS name abbreviation
e.g. PST for PasTracks
TRS for TreeShare
Thus, the file I captured from PasTracks on January
10, 1989 is named JAN10.PST
*** Note ***
Avoid EXE, COM or BAT for abbreviations and be con-
sistent once an abbreviation is selected for a spe-
cific bulletin board.
SEARCH - The BBS Message Searcher Version 1.32 Page -4-
Copyright (C) 1989 by Don Lewis. All rights reserved.
2) Create a file named SRCHTITL.NNN, where the NNN is
the BBS name abbreviation used in step 1. This file
must contain three (and ONLY three) words. The first
word will be found at the very beginning of each mes-
sage on the bulletin board, the second begins the
line where message subject is shown and the third
word is found at the beginning of the last line of
each message (see procedure and example messages in
Appendix A).
These words are placed there by the BBS software, not
by the message sender, and ** MUST ** appear in
SRCHTITL.NNN exactly as they do in the downloaded
messages (uppercase, lowercase, and any punctuation).
3) Create a file of search words named SEARCH.LST. A
search word may contain letters, numbers, spaces or
punctuation. Words may be composed of UPPERCASE, low-
ercase or Mixed Case letters; SEARCH doesn't care and
will find the letter sequence without reference to
case.
A word may be any length, but the longer it is, the
slower SEARCH runs, and the less likely it is that a
matching word will be found. Words are searched at
full length, but are shortened to 8 characters for
the screen display.
Use only one word per line, 39 words maximum per
search (more are ignored). Don't get too fancy with
the punctuation and spaces in the word, because
SEARCH looks for an ** EXACT ** match, and it is hard
to predict how someone who sends a message will use
punctuation.
You can create this and the previous file using a
word processor (be sure to use an ASCII format...
some word processing programs call this a non-
document mode), by using EDLIN (supplied with your
DOS disks) or by using COPY CON (see Appendix C for
details).
SEARCH - The BBS Message Searcher Version 1.32 Page -5-
Copyright (C) 1989 by Don Lewis. All rights reserved.
Using SEARCH
------------
Now we are ready to use SEARCH. The simplest arrangement is to
have all the files SEARCH needs to be in the same directory as
SEARCH. Files you will need are:
SEARCH.EXE - the main program
SRCHTITL.NNN - contains the three BBS message marker words
SEARCH.LST - contains the words you are looking for
MMMDD.NNN - the raw message file you captured
Remember: The NNN in SRCHTITL.NNN **MUST** be the same as the
abbreviation used as the extension to the raw message
file, and a different SRCHTITL file must exist for
each BBS you use. Just naming the file SRCHTITL.NNN
will not work!
Identify the file of BBS messages to be searched by entering it
when SEARCH is run. e.g. SEARCH JAN10.PST
Search will display the count of messages it is reading and those
it is finding which include your search words. While it is
searching, it creates 2 new files:
MMMDDSRT.NNN, which contains the selected messages, and
MMMDDSUB.NNN, which contains the subject of all the messages
in the raw message file.
(For JAN10.PST, the selected message file that SEARCH creates is
named JAN10SRT.PST, and the file of subjects is named
JAN10SUB.PST).
JAN10SRT.PST contains all messages found to include any of the
search words you put in SRCHTITL.NNN. Note that if you are
searching for a word which is used as part of another word, mes-
sages containing the longer word will be saved, too (when I
search for my Grandfather Carr, I find messages including the
words carry and Carrolton).
To help you understand what word caused a message to be selected,
SEARCH puts a header, which lists the found word, before each
message, and marks the found word in the selected message file.
You may TYPE the file of selected messages or subjects to the
screen or printer to examine the result of the search. (See
Appendix B for details). If no matching messages were found, the
file will be created with just a header, the list of search words
used, but no messages. In any case, the file of subjects will be
created.
SEARCH - The BBS Message Searcher Version 1.32 Page -6-
Copyright (C) 1989 by Don Lewis. All rights reserved.
*** Note ***
***********************************************************
* The file of selected messages is over-written each time *
* SEARCH is run, so be sure to rename it if you want to *
* keep it for future reference. *
***********************************************************
SEARCH - The BBS Message Searcher Version 1.32 Page -7-
Copyright (C) 1989 by Don Lewis. All rights reserved.
========== APPENDIX A ==========
Here are several example messages to help you determine what
words to use in SRCHTITL.NNN. In the example messages, all the
messages begin with
From:
This is what the BBS software uses to indicate the beginning of a
message. We'll use it too, so the first entry in the file
SRCHTITL.NNN is
From:
The first several letters of the line at the beginning of the
message subject line are the same for all messages, too. That
line begins
Subject:
The second entry in SRCHTITL.NNN is
Subject:
The first several letters of the line at the end of the message
are the same for all messages, too. That line begins
* Origin:
SEARCH will ignore the leading space before the *, and so can we.
The third entry in SRCHTITL.NNN is
* Origin:
This BBS is called OnoxX, so the file will be named SRCHTITL.ONX.
(It could just as well have been named SRCHTITL.OXX, or
SRCHTITL.ONO; your choice.) Create a file for each BBS you use
so each new raw message file will be searched properly.
SRCHTITL.ONX consists of the following words:
From:
Subject:
* Origin:
SEARCH - The BBS Message Searcher Version 1.32 Page -8-
Copyright (C) 1989 by Don Lewis. All rights reserved.
========== APPENDIX A (cont'd) ==========
---------------- example messages -------------------
From: Bill Harris
To: All Concerned Msg #2,
26-Dec-88 12:12am
Subject: Genealogy Search
I am interested in learning more about the HARRIS family of Osh-
kosk. They came to Minnesota in the 1850's. Your assistance is
greatly appreciated. Have a Merry Christmas and Happy New Year!
Thank you.
Bill Harris
---
* Origin: The OnoxX BBS (Opus 9:999/999)
From: Robert Peloppos
To: Frank Hutrado Msg #3,
26-Dec-88 02:20am
Subject: Re: Alto City., IA
Frank, I did get your message. However, I am running about four
weeks late in replying these days. I have the week off between
Christmas and New Years and hope to use some of that time in
catching up. Will get back to you soon. Bob
---
* Origin: The OnoxX BBS (Opus 9:999/999)
*** There is a reply. See #250.
From: Alex Chadwicke Rec'd
To: Jacob Beemer Msg #12,
26-Dec-88 08:25pm
Subject: Virginia Ancestors
Thanks for the feedback Jacob. Glad it can be of use to you.
Alex
--- Opus-CBCS 1.10.v
* Origin: Treasury * Clanton Va * (403) 254-9573 * 9600 HST
(9:999/9999.9)
SEARCH - The BBS Message Searcher Version 1.32 Page -9-
Copyright (C) 1989 by Don Lewis. All rights reserved.
=========== APPENDIX B ============
Displaying the found messages in the search file.
Note:
[ent] means press the Enter key
You can scroll the file on your screen to see what is in it by:
TYPE JAN10SRT.PST[ent]
As the messages start, hold your pinkie finger on the Ctrl key,
and hover your forefinger over the S. When you see something
interesting, press the S and the display will stop scrolling.
Still holding the Ctrl, press the Q key to start the display
again. Some computers will restart the scrolling when the Enter
key or the Spacebar are pressed, also.
You can get more fancy by copying the DOS file MORE.COM to the
same disk (and same directory, if you have a Hard Disk) as
SEARCH. Then, enter the following command:
LOOKAT JAN10SRT.PST[ent]
You will then get the file a screenful at a time, and a chance to
read all of it at your leisure. You can stop reading at any time
by holding the Ctrl key and pressing C.
You can get a more permanent form by sending it to the printer.
Make sure your printer is turned on, is online and has paper.
TYPE JAN10SRT.PST > PRN[ent]
The entire file of found messages will be printed.
Note that the same process can be used on any of the SEARCH docu-
mentation files, as well as those created by SEARCH. SEARCH.DOC,
MMMDDSUB.NNN, NOTES.TXT, and MMMDD.NNN can be read or printed as
described above.
SEARCH - The BBS Message Searcher Version 1.32 Page -10-
Copyright (C) 1989 by Don Lewis. All rights reserved.
============ APPENDIX C ============
Using COPY CON to create SRCHTITL.NNN and SEARCH.LST
This is the slow way, but it works. If you do not have a word
processor that can create a plain ASCII file (no control or for-
matting codes) or a programmer's editor, and do not wish to sub-
mit yourself to the mess that is EDLIN (which I can certainly
understand), do this:
Note:
[ent] means press the Enter key, and
[C-Z] means hold the key marked Ctrl or Control while press-
ing Z
first, from the DOS prompt, enter
COPY CON SRCHTITL.NNN[ent]
From:[ent]
Subject:[ent]
* Origin:[ent]
[C-Z][ent]
-the computer will respond with-
1 File(s) copied.
then, from the DOS prompt, enter:
TYPE SRCHTITL.NNN[ent]
The new file will be listed to the screen. The file should
have ** ONLY ** three words in it and (for this example), they
** MUST ** appear like this:
From:
Subject:
* Origin:
If the file contains the words you wanted it to, and they look
like the example, you're done. Otherwise you will have to
recreate the file again, because with COPY CON, there is no
editing. Remember that the NNN extension used in this example
is for example ** ONLY **. You must use an extension that
matches the extension used on the appropriate BBS raw message
file.
Use the same process to create SEARCH.LST. SEARCH does not
care whether the words you use in SEARCH.LST are UPPERCASE,
lowercase, or Mixed Case, so just type them in, and you're
ready to go!
SEARCH - The BBS Message Searcher Version 1.32 Page -11-
Copyright (C) 1989 by Don Lewis. All rights reserved.
=========== APPENDIX D ============
ADVANCED USER TIPS:
MARKING INTERESTING MESSAGES:
----------------------------
If you use a text editor to read through your
raw message file, any message can be marked
by adding ~ anywhere in the text (Note that
while any character can be used, ~ is fairly
uncommon in messages).
Add ~ to SEARCH.LST to recover marked mes-
sages. This is useful for messages of a gen-
erally interesting nature which do not con-
tain words that you usually search.
While SEARCH can process a file of any size,
some text editors cannot load a **VERY**
large file (like 256 Kbytes, approximately
300 messages). If your message files are
likely to be very large, break up a capture
session into smaller chunks.
USING THE SUBJECT FILE:
-----------------------
The Subject file (MMMDDSUB.NNN) provides a
quick look at some new words to search for.
After running SEARCH through a raw message
file, take a look at the file of subjects;
you may find something new, maybe a name or
word to add permanently to your SEARCH.LST
file.
WORDS TO SEARCH FOR:
--------------------
Sometimes you will get more names if you do
not use the entire name you want to find.
I'm not sure how my wife's G-father spelled
TACKETT (TACKET?). I search for TACKET, and
find both spellings. This is useful for any
name which could have variable spellings in
the last few letters. Note that if you are
looking for SUBLETTE and you just use SUB,
you are going to find ** ALL ** the messages,
since they all have Subject: in the message
heading. In cases like that, it is better to
enter each of the alternative spellings in
SEARCH.LST.
SEARCH - The BBS Message Searcher Version 1.32 Page -12-
Copyright (C) 1989 by Don Lewis. All rights reserved.
=========== APPENDIX D (cont'd) ============
AUTOMATING SEARCH:
-----------------
SEARCH sets a DOS ERRORLEVEL code when it has
completed a run. ERRORLEVEL is set to 0 if
the file of found messages has at least one
message in it; otherwise, ERRORLEVEL is set
to 255. Your batchfile can check the ERROR-
LEVEL to decide whether to rename the file of
found messages or to go on with the next
SEARCH using a renamed list of search words.
See your DOS manual, in the area that
describes batchfiles, for the discussion of
the IF ERRORLEVEL construct. My thanks to
James Davis for this idea.
SEARCH ON A HARD DISK:
----------------------
SEARCH need not be to be in the same subdi-
rectory with these BBS message files in order
to work:
SRCHTITL.NNN
SEARCH.LST
MMMDD.NNN
Make sure that SEARCH.EXE is in a subdirec-
tory on the path, and the three files are
together in the same directory. Change to
the subdirectory containing the three files
and then use the command:
SEARCH MMMDD.NNN
SEARCH - The BBS Message Searcher Version 1.32 Page -13-
Copyright (C) 1989 by Don Lewis. All rights reserved.
=========== APPENDIX D (cont'd) ============
SEARCH ON A DIFFERENT DRIVE:
----------------------------
SEARCH does not have to be on the same drive
as the message files, either. If you have
the three files on drive A: and SEARCH.EXE on
your C: drive in the \UTIL subdirectory,
change to A: and issue the following command:
C:\UTIL\SEARCH MMMDD.NNN
If you use the same floppy disk to search
messages each time, create a batchfile named
SEARCH.BAT on the floppy disk. The batchfile
will contain the following line:
C:\UTIL\SEARCH %1
Also, make sure the three files are on the
floppy disk. Then, you can invoke SEARCH by
typing SEARCH MMMDD.NNN, just as though
SEARCH.EXE was present on the floppy disk.
SEARCH - The BBS Message Searcher Version 1.32 Page -14-
Copyright (C) 1989 by Don Lewis. All rights reserved.
=========== APPENDIX D (cont'd) ============
SEARCH CAN BE RENAMED:
----------------------
SEARCH has no idea what its' name is, nor any
concern about being renamed; in the software
development process, it undergoes a name
change, anyway.
Why do I mention this? Well, apparently
SEARCH.EXE is not an uncommon name among
genealogy program files (and maybe among
other types of utilities, as well).
Feel free to rename it to suit yourself and
to avoid conflicts with existing utilities
having the same name.
SYSOP'S UTILITY:
---------------
Thanks to Edward Hayden, SysOp of PasTracks
BBS for the following tip: SysOps of FIDO
and OPUS BBS systems use a utility called
SAVECHO (there are some other utilities with
the same capability) to automatically save
messages before they are erased due to age.
SAVECHO creates a file which can be searched
with SEARCH, just as though the messages had
been captured while online.
SEARCH - The BBS Message Searcher Version 1.32 Page -15-
Copyright (C) 1989 by Don Lewis. All rights reserved.
=========== APPENDIX E ============
ERROR MESSAGES AND CONDITIONS:
1) Q: Just after the program started, I got a box on the screen
warning that the filename had improper form.
A: The only raw message filename that SEARCH recognizes is in
the form MMMDD.NNN. Pretty picky about that. See section
1 in "Preparing to use SEARCH".
2) Q: Just after the program started, I got a box on the screen
warning that a file was missing.
A: Either SRCHTITL.NNN or SEARCH.LST (or both) is missing from
the current directory, or is garbled. Create or repair
them as necessary. SEARCH must have both files available
and in correct format.
3) Q: SEARCH processes the raw message file, but the message
count doesn't increase from 0 or increases very slowly even
though I know the messages are short and there are lots of
them.
A: SRCHTITL.NNN contains the wrong words to mark the beginning
and end of a message for the raw message file you are
searching.
-- or --
The BBS may not be adding an ending line to all messages;
some BBS software only adds an ending line to messages
received via a network (the origin of local messages is not
given, because presumably, you know where you are...).
Look for a header that the BBS places before the From:
line, and use that for the ending line. CompuServe is an
example of this.
4) Q: As SEARCH processes the raw message file, the message count
stops at 1 and then SEARCH crashes.
A: There is an error in the ending line marker word in
SRCHTITL.NNN. SEARCH is finding the beginning of the mes-
sage, but doesn't see the end, so it just keeps reading
until your computer memory fills.
SEARCH - The BBS Message Searcher Version 1.32 Page -16-
Copyright (C) 1989 by Don Lewis. All rights reserved.
=========== APPENDIX E (cont'd) ============
5) Q: SEARCH finds every message.
A: SEARCH.LST contains a word that appears in every message
(from, to, subject, etc.)
6) Q: When I search for CARR, SEARCH finds carrel, carrot, carry-
ing, Carrolton and Carrie; I don't want to find that
junk... what to do?
A: Nothing. Just use the header word in the sorted message
file to see what caused SEARCH to select that particular
message, and look for the marked word in the body of the
message.
**********
** Note ** Don't try to fool SEARCH into catching only names by
********** putting a space before or after a name in SEARCH.LST.
Many message writers use a / to separate names, as:
CARR/KARR/SMITH/JONES
or some other symbol
CARR, SMITH
Neither of those would be caught by [spc]CARR[spc] in
SEARCH.LST
7) Q: When I run on a floppy disk, SEARCH occasionally crashes
with a message like:
Error 61 in Module SRCH1xx at XXXX:YYYY
Press any key to return to system.
A: Your disk is full, and became full as SEARCH was writing
found message records. Why did I (your obedient program-
mer) let this happen? Well, SEARCH cannot determine how
large a found message record file will be, and thus cannot
anticipate this failure.
Note that when this failure occurs, the file of found mes-
sages ** WILL NOT ** be complete; create some free disk
space and run SEARCH again.
SEARCH - The BBS Message Searcher Version 1.32 Page -17-
Copyright (C) 1989 by Don Lewis. All rights reserved.
=========== APPENDIX E (cont'd) ============
You can create more free space on your work floppy by mov-
ing some un-needed program or raw message files to an
archive disk. Or, reduce the number of search words so
that the found message file will be smaller. Note that
deleting the output files SEARCH produces will not help, as
they are re-created each time SEARCH runs.
SEARCH - The BBS Message Searcher Version 1.32 Page -18-
Copyright (C) 1989 by Don Lewis. All rights reserved.
=========== APPENDIX F ===========
The shareware version of SEARCH must be provided to other users
without charge, except that a reasonable disk duplication and
postage charge may be made (not to exceed $5).
This ARC must contain the following files:
SEARCH.EXE - the main program file
SEARCH.DOC - the document file you are reading
PRINTDOC.BAT - prints SEARCH.DOC
LOOKAT.BAT - displays the found or raw message file
NOTES.TXT - release notes and bug fixes
README.1ST - Urgent updates from earlier versions
If all files are not present, please contact me and tell me what
files are present, and where you got your copy.
Please support SHAREWARE programmers by sending your SHAREWARE
contribution to make more (and better) software available.
Remember that with SHAREWARE, if you don't like what I did in the
program, you have no money invested and thus no hassle getting
your money back.
Just try to get a refund after you have opened the package of a
$300.00 commercial application!
If you feel that this program is useful to you, please send
$10.00 to:
Don Lewis
5207 Mossgrey Ln.
Spring, Texas 77373
Registered users receive the latest version of SEARCH, serialized
and without the SHAREWARE contribution solicitation. Registered
users may update to the latest version by sending me the original
distribution disk and a stamped, self-addressed floppy disk
mailer.
Thank you for using SEARCH
... Don
Copyright (C) 1989
Don Lewis