Simtel MSDOS 1992 September/Simtel20_Sept92.cdr/msdos/packet/bis_v20.arc/BIS-V20.DOC

Text File | 1988-09-25 | 20KB | 402 lines

             ADDITIONAL DOCUMENTATION FOR BIS VERSION 2.0

There have been some major changes in BIS V2.0 and how it performs the
search function.  You will need to change your BIS.CNF file if
you have been running a previous version of the program.  It is best to
completely read this documentation before making the changes as there
are options available to you which were not previously.  As mentioned
in previous documentation, if you have a problem running BIS, it is
MORE THAN LIKELY a problem with the configuration file.  In questions I
have received about BIS, this held true and it probably will in the
future.  In order to understand the configuration file, you should
completely understand the documentation, both for the previous version
and now version 2.0.  So hold onto your seats, here we go!

First, it is important to understand that the new version of BIS now is
capable of calling functions other than SEARCH TIME and DATE.  It is
up to you to develop the other functions you may wish to do which will
take the form of DOS commands or external programs.  The original
intent of BIS, as its name implies, was to act as an interface between
the MBL BBS program and other programs a user can call by using the BBS.
Originally BIS was limited to only the three functions, but now the
type and number of functions is basically unlimited.

Be careful, however, in installing these alternative functions.  Some
may act very unpredictably if conditions are not set properly.  You
need to have a pretty good idea of what you are doing.  Some may not
work at all and some may only partially work.  ANY PROGRAM OR DOS
COMMAND WHICH REQUIRES USER INPUT WHILE RUNNING WILL NOT WORK unless it
is specifically designed to take input from the COM port in use.  More
about preparing for alternate programs and commands later.

CHANGES
Other than the capability mentioned above, there have been some other
changes to BIS which have improved upon previous versions.

EXTRA LINE FEED
Searches now have an extra blank line between files when more than one
"find" is made in the SEARCH function.  This makes output much more
readable on the remote computer.

BIS DISPLAY
BIS activity is now displayed on screen in the SEARCH function.  You
can see what is being sent to the user and the information sent by the
BIS program.  There is a built in delay of approximately five seconds
when BIS completes its functions and returns to the BBS program to
allow the SYSOP time to see the last information passed on by BIS.
Essentially this delay will be unnoticed by the user because the
display is usually ahead of TNC output.

NO LONGER USES DOS REDIRECTION TO COM PORT FOR SEARCHES
Previous versions of BIS called the FGREP search program to complete
the searches by directing FGREP's output to COM 1 or 2.  This is no
longer the case.  Instead, FGREP's output is directed to a disk file
and then BIS reads the disk file and moves it out the COM port.  This
should relieve some of the problems in timing etc. that some sysops
experienced with the original version.

                                    -2-

STRIPS GARBAGE CHARACTERS
Redirecting FGREP's output to a file has the additional advantage of
allowing BIS to do some editing prior to sending it out the COM port.
One of the problems experienced by sysops in previous versions was
FGREP's nasty tendency to insert some garbage characters if the SEARCH
"find" was the first line of a particular file.  The temporary fix was
to edit the file with a blank line at the top or use FGREP's "-w"
option.  Unfortunately, using the "-w" option meant two letter word
searches meant exactly that instead of allowing BIS to insert a space
before and after the two letters and also made two word searches like
for "Kansas City" or "New Orleans" impossible because it strips the
space.  BIS 2.0 instead strips the garbage characters out of the
temporary file before sending them out the COM port.

TWO LETTER WORD SEARCHES
As you know if you have used previous versions of BIS, the program
inserts a space before and after the two letter word before calling
upon FGREP to do the search.  This is to allow for searches in
databases which contain two letter state abbreviations.  Some
encountered the problem that the program then wouldn't find matches in
files where the two letter state abbreviation was at the end of the
line.  Most of the digi and bbs lists that I have seen do not have the
state at the end of the line, but somewhere in the middle, so those
worked fine.  If you have that problem, you have one of two choices.
Either modify the database with a space at the end of each line or use
the "-w" option to call FGREP in that particular section of your
BIS.CNF file.  This will effectively strip the spaces that BIS inserts
but has the disadvantage of matching anything in the file that has
those two letters in it.  Having a user insert a space at the beginning
of the search word will have no effect since FGREP will strip it out.
So the first option is probably the better.  I struggled with this
problem for some time, but there is just no way to do it short of
forcing two or three calls to FGREP...one to search for " NY "; one to
search for "NY<CR>"; and perhaps one to search for "NY."  FGREP does
not accept choices.  It is one way or the other.

BIS CONFIGURATION FILE EXPANDED
The configuration file BIS.CNF is now expanded to essentially as
many sections you wish, depending upon available memory.  Each section
does require some memory, however.  BIS is allocated 64 K for string
storage, so this must be a consideration.  Even without the additional
feature of allowing other external programs to run, folks were asking
for additional sections, so this change should be of help.

RAM DISK OPTION
As mentioned, previously, BIS redirects FGREP's search output to a
temporary file called "BIS_FILE.000.  If all goes well you should never
see this file in your directory because BIS deletes it before returning
control back to the BBS program.  YOU MUST DESIGNATE THE DIRECTORY OR
SUBDIRECTORY TO STORE THIS FILE in your BIS.CNF file in the third line
of the first section.  In previous versions of BIS, this line was used
to tell DOS where to find BIS again after a search but this version of
BIS does not change directories.  So instead, the line designates where
to store BIS_FILE.000.

                                    -3-

You may wish to use a RAM DISK instead of your hard disk to store this
file as it makes the program run much faster and requires no writes to
your hard disk.  If so, keep in mind the amount of space needed by the
program to store search results.  Should the search output exceed the
ram disk allocation, the BIS program will abort and should return back
to the BBS program again giving the usual prompt to the user.  Be
certain to USE A BACK-SLASH "\" as the last character in this line.

CHOICE OF SHOWING FULL PATH OR FILE NAMES ONLY ON SEARCHES

BIS now gives you the option of sending the user the full path name to
the file which contains the "find" or only the file name itself.
Originally only the file name was shown.  If the full path name is
allowed, be certain your users understand they may only have to use a
portion of the path to download a file.  For example, if your BBS ARRL
files are stored in a deeply nested subdirectory but MBL BBS program
only needs the last two subdirectories to find the file, giving the
full path name for a download would result in the BBS program giving a
"Not Found" error to the user.  The PATH OPTION IS SPECIFIED ON LINE
FOUR of the BIS.CNF file and must be either YES for full path names or
NO in caps.

THE CONFIGURATION FILE
Only two changes to the BIS.CNF file are MANDATORY for this version to
run as desired.  Both changes are in the first section of six lines.
The first required change is the directory to store the temporary
BIS_FILE.000 and is on the third line.  The second change is the path
option on line four.  Remember this file must contain sections of six
lines each, the sixth line being a series of ten dashes.  There should
be no leading or trailing spaces on each line other than what is
allowed in the SEARCH sections.  The format should be exactly as shown
in the sample configuration file.

PORT DRIVERS
BIS runs fine with COMBIOS or DVIOCOM.  It does not apparently work
with MBBIOS.  Various reports of success have been heard from users of
the multi-port drivers.  Since I do not use any of those drivers, I am
not able to check those.  Keep in mind with multi-port drivers that BIS
still works only on COM1 and COM2.

RUNNING OTHER PROGRAMS UNDER BIS (OR LET THE FUN BEGIN!)
If you have guts and your computer sufficient memory, you can now use
BIS to run other executable programs, batch files and yes, even BASIC
programs!  Unless the external program has its own method of taking
input from the COM port, these programs cannot expect user input during
execution.  However, BIS provides up to 6 parameters which you may use
in running your program.

Recall for a minute using BIS's SEARCH FUNCTION.  The syntax of the
command is:
FUNCTION; DATABASE OR FILE NAME; SEARCH WORD

In reality, the SEARCH WORD may be two words, yielding in reality two
parameters.  Thus the command might look like this:
SEARCH HAMS KANSAS CITY

                                    -4-

So, effectively there are 4 parameters used in finding the correct
search word specified by the user during a SEARCH.  BIS will supply
these four parameters to your program and in addition, supplies two
others, the COM port in use and the users call sign.

      PARAMETER LABELS

$1  COM port                       For purposes of the BIS.CNF file,
                                   the table at left shows all 6 of
$2  Call sign                      the parameters available to call
                                   your program.  You probably won't
$3  FUNCTION (user supplied)       use the Function parameter as it
                                   is mainly used internally by BIS
$4  First param (user supplied)    to find the function desired in
                                   the BIS.CNF file.
$5  Second param (user supplied)   Label $3 corresponds to the word
                                   "SEARCH" when BIS does the SEARCH
$6  Third param (user supplied)    function; $4 corresponds to the
                                   database; $5 corresponds to the
                                   first search word; and $6 to the
                                   second search word.

In the BIS.CNF file, each external program will have its own unique
FUNCTION name.  BIS will then search the BIS.CNF file for the function
and execute the program named in that section.

If your program has user output, you have your choice of methods in
sending it if the program itself doesn't have a method.  The output can
be redirected to the COM port (specified by "$1") or can be redirected
to BIS_FILE.000.  Although DOS redirection will work in most instances,
you are probably safer redirecting the output to BIS_FILE.000 which BIS
will send out the COM port when the external program has finished
executing.  One of the reasons SEARCH output was changed from COM port
redirection in version 1.x to file redirection in version 2.0 of BIS
was because of some of the problems people encountered with the former
method.

Take a few minutes to look over the sample BIS.CNF file supplied with
this program, in particular, the last few sections which specify
functions other than SEARCH.

As in the SEARCH function sections, these sections have six lines each,
the last line of which must be a series of ten dashes or hyphens (not
the underline character).  Actually six dashes will do it, but ten are
in for good measure.  The fifth line is unused and is present only to
maintain consistency with the SEARCH functions.



DIRECT                                  As in the example at left, the
DIR C:\BBS\FILES > COM$1:               first line is the name of the
ACCEPT ONLY: W9LZQ                      FUNCTION.  When a user types the
REJECT ONLY: NONE                       OS command in the MBL BBS
NOT USED                                program, it is the next word
----------                              after "OS".  It may be any word
                                        you desire, but MUST be different
than any of the other functions in the BIS.CNF file.  Additionally, it

                                    -5-

obviously cannot be "SEARCH"; "VERSION" (undocumented function);
"TIME"; or "DATE", since these are all previously defined BIS
functions.  "TIME" and "DATE" are internal functions of BIS.  The
second line ("command line", for lack of a better name) is the line to
call your program and pass any parameters to it.  The third line allows
you to insert call signs of stations who will have access to this
function IF it is to be limited to only specified stations.  The fourth
line allows you to insert call signs of stations who MAY NOT use the
function.  If there is a call sign entered on either line, the word
"NONE" (in caps) must be deleted.  If the line is to be ignored, the
word "NONE" must be on the line.  If "NONE" is entered on both the
third and fourth lines, all stations will have access to the command.
The two lines are mutually exclusive.  That is, if a call sign is
entered on one of the lines, the other line MUST NOT have call signs on
it and MUST have the word "NONE" entered on it instead.

In the example above, the FUNCTION called is "DIRECT".  The command BIS
calls is in the second line and calls the internal DOS function:
DIR C:\BBS\FILES which is redirected out the COM port in label $1.
Station W9LZQ is the only call sign allowed to use the function.  The
MBL BBS command to call this function would therefore be:

OS DIRECT

Another example:

                                         In this case, the FUNCTION is
                                         called "WHAT" (makes sense,
WHAT                                     doesn't it?).  The command line
DIR $4 > D:\BIS_FILE.000                 calls the DOS function "DIR"
ACCEPT ONLY: W9LZQ                       again, but this time with a
REJECT ONLY: NONE                        twist. Here, the directory must
NOT USED                                 be specified by the user when he
----------                               calls the function.  Also, you
note that this time the output is directed to BIS_FILE.000 which BIS will
read and send out the COM port when the external program finishes.  When
the user requests the WHAT function, he (or she) must supply an
additional parameter ($4) or the function will merely output a listing
of the current directory. Here, the MBL BBS program OS command would
look something like:

OS WHAT C:\JOKES\SICK

which sends to file BIS_FILE.000 for later output, the files in the
"SICK" subdirectory of the "JOKES" directory.

Want to run a program written in BASIC?  Here is how its done:

                                        The function is called "TEST"
                                        which calls BASIC and tells it to
TEST                                    run "TEST.BAS" and send its
BASIC TEST > COM$1:                     output to the COM port specified
ACCEPT ONLY: NONE                       in label $1.  In this case, any
REJECT ONLY: W9LZQ                      user can call the function except
NOT USED                                poor W9LZQ, alas!  The MBL BBS
----------                              command to call the function is:
*NOTE: Use the name of your BASIC       OS TEST.
interpreter.

                                    -6-

You may also call Batch files for execution from BIS.  The next example
in the sample BIS.CNF file demonstrates how to do that with the
FUNCTION, "INFORMATION".

In the next section (FUNCTION "NEW") any user can read a file stored in
the \BBS subdirectory called "WHATSNEW", where the output is first
redirected to D:\BIS_FILE.000 and then read by BIS and sent out the COM
port.

The final example, the LOG FUNCTION demonstrates how to use a batch
file for what may be a very useful function, reading the BBS log for a
given date.  The .BAT file first makes use of FGREP.COM to do the
initial search and then calls the program named READLOG.EXE to
eliminate improper entries found by FGREP, sending its output to the
BIS read file, BIS_FILE.000. The syntax of the OS command is: OS LOG xxdd
Where xx = month and dd = day

  BIS.CNF SECTION

LOG
DOLOG.BAT $4
ACCEPT ONLY: W9LZQ W9HWQ WD9GCR
REJECT ONLY: NONE
NOT USED
----------
* Note: "DOLOG.BAT" is in the current directory


  DOLOG.BAT

ECHO OFF

REM DOLOG.BAT WORKS IN CONJUNCTION WITH BIS.EXE BBS PROGRAM.
REM SEND LOG INFORMATION FOR USER PROVIDED DATE (xxdd).
REM FIRST CALLS FGREP.COM TO DO A QUICK SEARCH OF THE LOG FILE
REM  AND REDIRECTS ITS OUTPUT TO "BIS_FILE.000".

FGREP -sx %1 \BBS\LOG\LOG.BBS > D:\BIS_FILE.000

REM COPY "BIS_FILE.000" TO A DIFFERENTLY NAMED FILE
REM   (you may wish to modify this, depending upon whether
REM   or not you are using a RAM disk and how much space it
REM   has allocated).

COPY D:\BIS_FILE.000 C:\BBS\TEMPFILE.000

REM CALL READLOG.EXE TO ELIMINATE FALSE FINDS FROM FGREP'S OUTPUT
REM   AND REDIRECT OUTPUT TO "BIS_FILE.000".

READLOG.EXE %1 C:\BBS\TEMPFILE.000 > D:\BIS_FILE.000

REM DELETE TEMPFILE.000 THEN
REM EXIT BACK TO BIS WHERE BIS_FILE.000 WILL BE SENT OUT COM PORT.

DEL C:\BBS\TEMPFILE.000

                                    -7-

Using the LOG FUNCTION, I can remotely check the log for entries during
any particular day and so can assistant Sysops.  The READLOG.EXE
program and the DOLOG.BAT file are included on the BIS version 2.0
distribution diskette, however, you will have to edit the .BAT file to
suit your particular system.  It should probably go in the same
subdirectory, along with READLOG.EXE in which your BBS program is
located.  Remember also that the LOG FUNCTION and READLOG.EXE do not
work with earlier versions of the MBLBBS program because the log format
was changed in the last version.

Incidentally, you can run READLOG.EXE as a stand-alone program locally,
although it is extremely slow without using FGREP.COM first.  It also
has one additional optional parameter which will allow its output to
the screen to pause if you use it locally.  Don't include the parameter
when it is being called via the COM port.  The command syntax is:

READLOG.EXE mmdd [/P]

As a final note to the discussion about sections, remember that on line
2 of the functions other than SEARCH, you an mix and match parameters
and labels in any sequence you need to call your external program.


SUMMARY

BIS Version 2.0 provides you the capabilities to do a wide variety of
things at the command of your users.  But it is up to you to develop
the applications!  If you come up with some good ones, let me know.  If
they provide a useful needed function, I will include them on the BIS
distribution diskette if you send a copy to me.  Also, I plan on
distributing applications which can be used in conjunction with BIS on
an individual disk if I receive a few from MBL BBS sysops, so if you send
one, please include necessary documentation.

Finally, I would like to thank those of you who offered suggestions for
improvement of BIS.  Most of them have been incorporated into this
version and should make for a much nicer BBS Interface System.

Definitely remember to register your program.  It is the only way I have
of notifying you of updates.  You will find the registration form as a
separate document on the distribution disk.  Comments and suggestions
made on the registration form will be much appreciated.