Simtel MSDOS 1992 September

home *** CD-ROM | disk | FTP | other *** search

/ Simtel MSDOS 1992 September / Simtel20_Sept92.cdr / msdos / packet / bis_v20.arc / BIS.DOC < prev next >

Wrap

Text File | 1988-09-25 | 32KB | 688 lines

BIS BBS INTERFACE SYSTEM Versions 1.3 and 2.0 For use with WA7MBL BBS versions 3.30 and above Copyright 1988 by Richard K. Helman -1- (*) Indicates changes in documentation with version 2.0. Consult docu- mentation for version 2.0. BBS INTERFACE SYSTEM INTRODUCTION BIS is a User interface designed to be called from the WA7MBL packet BBS program using the OS command. BIS interfaces to yet a third program which is capable of performing file and/or directory searches or may interface to other applications which you may specify. The SEARCH function of BIS accepts additional parameters which the BBS user sends in addition to the command OS, screens and edits this information then passes it on to the search program. If user information is incomplete or in error, BIS will so inform the user, provide useful help information and terminate, returning to the BBS program awaiting to be called again. BIS grew out of my lengthy bout with frustration over keeping index and supplementary lists up to date so that a user desiring to find a particular file contained on the BBS hard disk could easily do so. It was very difficult for a user to use the W command if he expected to get some idea of what was contained in each of the cryptic file names stored in various subdirectories. Originally, I developed an INDEX for each of these subdirectories and faithfully kept them updated each time a new file was added. The process grew old fast. Miraculously, about that time, Jeff's new version 3.3 of the MBL BBS program came out with the new OS feature which allows shelling to DOS to perform some other function. In talking with Jeff, he assures me that he intends to keep the OS function in future MBL BBS updates. THANKS JEFF! Index files and their like are no longer needed thanks to this new command. BIS will allow a user to search any file, series of files or subdirectory for a particular search word using a supplementary searching program such as the one included on this distribution diskette. Although there are other options, normally the result of the search through a particular subdirectory is to return the first line of each file that contains the particular search word. The system can also be configured to return every line in a file that contains the search word making it useful for searching lists such as digipeater or PBBS listings etc. The search program that is used in conjunction with BIS is called FGREP and is included on this distribution diskette. It was chosen because of its small size, speed and features. FGREP was written and copyrighted by Christopher J. Dunford. It comes with its own documentation and distribution allowances. Please take time before attempting to run BIS to become familiar with FGREP and its capabilities. You will find it to be an excellent search program and highly suited to the purpose we are putting it to in conjunction with the BBS program. -2- PRECAUTIONS This program has been tested on an Equity I PC and a Tandy 1000 PC. It has run without problem for approximately six months on the W9LZQ-1 PBBS. It has NOT been tested under multi-tasking environments, with DesqView or DoubleDos. It has NOT been tested with previous versions of the MBL PBBS program. Running this program on any computer not utilizing a hard disk is not practical since file storage is extremely limited on such systems. Internal memory must be sufficient to run both programs in addition to the BBS program. |If you attempt to run BIS and the only thing that happens is the |screen clears and jumps right back to the BBS program without making |an entry in the BIS.LOG file, more than likely the problem is not |enough memory to accomodate all the programs loaded. Some TSR |programs may also present this symptom. As with any new software, you are highly advised to make a complete backup of your hard disk before attempting to run BIS. You should normally be in the habit of doing this before trying any new software on your system. |BIS currently runs on only COM ports 1 and 2. It will not work with |ports 3 and above. If you are running a multi-port system, it will |be necessary for you to reconfigure your system so that the users who |commonly make use of BIS and its functions are on ports 1 and/or 2. In |addition, you will need to have COMBIOS loaded or either COM1BIOS or (*)|COM2BIOS, depending upon your situation. Consult the MBLBBS manual |for more information on these drivers. |It is highly important that your path be set correctly. Both BIS and |its accompanying SEARCH program (FGREP) must be in your current path. |Also, COMMAND.COM must be in your current path. For example, assuming |COMMAND.COM is located in your root directory and the MBLBBS program, |BIS.EXE and FGREP.COM are all in a directory called BBS, your path |would be set as follows: PATH C:\;\BBS |This is absolutely necessary because BIS must know where to find |FGREP.COM and COMMAND.COM. |Finally, if you have previously been using Index files or something |similar to store lists of files in your various subdirectories that |users can download to see where to find files, it is highly recommended |that you retain these files until you are absolutely certain that BIS |is operating properly and you will no longer need them. This is a |normal precaution, but an important reminder. -3- COPYRIGHT, DISTRIBUTION AND DISCLAIMER BIS (BBS Interface System) is copyrighted 1988 by Richard K. Helman. It is provided on an "as is" basis with no guarantees as to its suitability for any particular purpose. The author assumes no responsibility, either consequential or incidental, for damage to equipment or software by using this product. You utilize this software at your own risk. Although it has been tested on certain equipment, the author can make no guarantees that it will work in conjunction with such equipment or any other equipment. The BIS software may be distributed so long as no fee is charged for it, so long as the program is unmodified from its original form and so long as the documentation files are distributed along with the program. You are NOT AUTHORIZED to distribute modified copies of this software without the express written consent of the author. This software may be used only by non-commercial interests and only on a not for profit basis. No fee may be charged to any person accessing information on a computer system through utilizing this program. It may not be utilized on telephone bulletin board systems which charge a fee for usage. FGREP.COM and its associated documentation MUST accompany any distribution of the BIS software. FGREP has its own disclaimer and conditions for distribution included within its documentation file which you must be fully aware of before distributing it. The distribution diskette should contain the following files: BIS.CNF; BIS.DOC; BIS-V20.DOC; BIS-V20.EXE; CHANGES.BIS; DOLOG.BAT; ERRORS.BIS; FGREP.COM; FGREP.DOC; NOTE-512.BIS; O.HLP; OSHELP; READLOG.EXE; README.BIS; REGISTER.BIS. If it does not contain these files, you are NOT AUTHORIZED to distribute it to anyone. -4- FIRST A BIT ABOUT FGREP Before dealing specifically with the BIS functions lets first discuss the search program FGREP and the specific functions which will be used by BIS. Assuming you have now examined the FGREP documentation, you will notice the discussion on FGREP's "switches". The only ones that generally will be needed while run in conjunction with BIS are the following: Useful FGREP Switches -f causes FGREP to show File header lines for only those files which match the search condition. -1 returns only the first line of a file that matches the search condition. -S suppresses the File header output and returns only the search match. You may want to experiment with other switches, however for most uses in BBS database searches, these three are the only ones to be concerned about. For FGREP to function it needs to be passed certain information when called. The syntax is: FGREP [switches] {search word} {file or subdirectory} For example: To find all ARRL Bulletins stored in your ARRL subdirectory which contain the word "antenna" you would call FGREP using the command: FGREP -f1 antenna \arrl\*.* FGREP then would return the name of the file and the first line of text within the file which contained the word "antenna". This is useful for finding particular files when many are stored in the same subdirectory. Another example of usage is when you have a subdirectory devoted to lists of BBS's and Digipeaters. Perhaps you may want to have a subdirectory named "DATA" which contains the following files: BBS.TXT; BBS.DAT; BBS.LOC; DIGI.LST; DIGI.TXT BBS.TXT and BBS.DAT are similar lists which contain a nationwide list of Packet BBS stations. BBS.LOC also contains list of BBS stations in your region. When searching for a particular BBS or location of the BBS, you may wish to include all three BBS lists to be searched. Easy to do using FGREP: FGREP -s milwaukee \data\bbs.* This will return a list of all BBS's in the Milwaukee area from each of the three lists. Or if you wish to obtain a list of all Iowa digipeaters from both digipeater lists: FGREP -s ia \data\digi.* (Note: Iowa is normally abbreviated "IA" in these distributed lists. -5- Are you beginning to see the possibilities for PBBS users? No longer will it be necessary for users to download long listings of BBS's just to find a BBS in a particular city or state. No longer will it be necessary for sysops to maintain an extensive index file of files contained within subdirectories. The user can search them until he finds the information he is seeking using the BIS interface to FGREP. Experiment with FGREP a bit to get used to its conventions and output. THE BIS INTERFACE Although FGREP does the search work for BIS, it is BIS which assures that the information that the user provides is acceptable and is in the proper format in order for FGREP to work. If not, it will return the appropriate error message to the user and return control back to the BBS program. In some instances, it will first send a listing of all of the files and databases that can be searched. It will then terminate and return to the BBS program. It is important to note, as its name implies, BIS has the potential of doing many other things besides interfacing with a search program. Other functions have not (*)been developed yet with two minor exceptions and I am looking forward to hearing from those of you with ideas on implementing other helpful functions. The two minor exceptions are that BIS will return both the time and the date to a user who commands: OS TIME or OS DATE. Meanwhile until further developments, the main function that BIS is concerned with is "SEARCH". Since BIS.EXE is specified in the BBS.CNF file as the MS-DOS program to run using the OS command, it is not necessary for the user to specify which program to run. Using BIS, however, it is necessary to specify which BIS function to use. In this case, SEARCH is the function we are interested in. The user must also supply two other parameters, the file or database to search and the search word. The syntax is: OS SEARCH {DATABASE} {SEARCH WORD} A typical command would be: OS SEARCH DIGI CHICAGO The BBS program would then shell to the BIS program, passing along all of this information along with other necessary data to it. BIS then processes the information passed to it assuring that all is error free and editing it in limited instances. BIS then reads its own configuration file (BIS.CNF) to assure that the data can be processed and to obtain other necessary information to pass on to FGREP. It then calls FGREP and redirects FGREP's output to the (*)particular COM port in use. The end result is easy database searches for packet BBS users. -6- SETTING UP The following files are necessary for BIS.EXE to function. They should all be in the same subdirectory from which you run the BBS program: BIS.EXE BIS.CNF FGREP.COM In addition, BIS will create BIS.LOG which is a log of BIS usage. The log provides a listing of commands sent to BIS and will be helpful to you in tracking usage as well as assisting your BBS users in making use of the function. BIS.LOG may also contain error reports if they occur during BIS execution assuming the program can recover from the error. In the same subdirectory as you place other BBS ".HLP" files, you will want to include the file O.HLP. Users can then obtain a help file by using the BBS command: ?O The help file "OSHELP" should be placed in your FILES subdirectory so that it may be easily downloaded by users by typing: D OSHELP. In order for BIS to be executed as the BBS OS command, you will need to place BIS.EXE on the OS line in your MBL BBS.CNF file. This informs the BBS program of which command or program to execute. -7- THE BIS.CNF FILE 4800,N,8,1, 12 [EXCLUDED CALLS] \BBS XXXXXXXXX ---------- SEARCH DIGI U.S. digipeaters N FGREP -F \BBS\DATA\DIGI.TXT ---------- SEARCH BBS U.S. packet Bulletin Boards N FGREP -F \BBS\DATA\BBS.* ---------- SEARCH ARRL [S] Current year ARRL Bulletins N FGREP -1F \BBS\FILES\ARRL\*.* ---------- SEARCH LIBRARY [S] BBS files of a general nature N FGREP -1F \BBS\FILES\LIBRARY\*.* ---------- The BIS configuration file consists of up to 21 sections, each containing exactly six lines each. The first section contains important information on configuring the BIS program for communication output, etc. The remaining sections are keyed to BIS (*)functions (with this version, only the SEARCH function) and individual "databases" a user can access by using the SEARCH function. They contain database information as well as configuration information for FGREP. -8- Closely examine the first section. This section MUST always be the first section in the configuration file and the first line MUST be the first line in the file. No blank lines are allowed. The first line is the COM port configuration you are using between your computer and the TNC(s). If you are using different configurations with each COM port, BIS will not work with all of them. It will only work with ports configured as in the first line. Each parameter is separated by commas and the line is ended with a comma. The parameters are: baud rate, parity, word length, stop bits, The second line lists the COM ports with which it is acceptable to use BIS. If the COM port the user is currently connected to is not listed, BIS will terminate, returning control back to the BBS program. In this case, ports 1 and 2 are acceptable and each is configured as in line 1. NOTE: Only ports 1 and 2 are allowed. Line three is hopefully unnecessary, but is included as an ounce of prevention. If for some reason it becomes necessary to exclude certain call signs from using the OS functions, the call sign may be placed on this line. All excluded call signs should be placed on line number 3, separated by spaces, with a maximum line length of 255 characters. (*)Line four contains the name of the directory from which you run the MBL BBS program. It is required because during its execution, BIS (*)will change directories and it needs to know where to return when it has finished. (*)Line five of this section is reserved for further expansion. Line six is a series of ten "-" characters required in order to appropriately separate each of the sections. It MUST be the sixth line in EVERY section of the BIS configuration file. The following sections may be in any order but their format must be exactly as shown. Subsequent sections begin with the particular BIS function to be used. Since the current version of BIS has only the (*)SEARCH function implemented, all sections will begin with the word "SEARCH" (TIME and DATE are BIS internal functions and do not require information from the these sections). The first line in all sections MUST BE UPPERCASE. The second line, for lack of a better definition is the name of the database the users is interested in searching. It may be any name up to eight characters in length, MUST BE IN UPPERCASE, and for simplicity sake should probably be given a name consistent with the files that will be searched. Following the database name is a description of that database which must begin in the eleventh (11th) column or beyond of line 2. This information if helpful for the user when BIS sends a listing of databases available and their descriptions. The third line tells BIS whether or not to make the search case sensitive. In most all cases, it is best to use N since case sensitivity can really make it difficult for a user to find anything. If you desire case sensitivity, change the line to Y. The fourth line contains the name of the search program and switches to pass to it. -9- The fifth line tells BIS where to locate the database information including subdirectory and filename. You will note that for filenames, wild cards are acceptable making it easy to search through every file contained in a particular subdirectory. Examine the third section of the configuration file. You will see that the SEARCH in this instance will be of the "BBS" database, not case sensitive, using FGREP -F (switched to return the file name from which it finds the match), and the search will be conducted of all files beginning with "BBS" and with any extension which are contained in the \BBS\DATA subdirectory. Now look at section four. This will cause a SEARCH of the ARRL database which consists of all files in the \BBS\FILES\ARRL subdirectory. FGREP is switched to return the name of the file and the first line within that file that matches the search word. Section five does the same thing for all files in the \BBS\FILES\LIBRARY subdirectory. Finally, looking at section two, you will note that the SEARCH in this instance will be confined to only one file "DIGI.TXT" and will return the name of the file as well as any line in which the search word is found within that file. A word about line two is in order. You will note in the sample BIS configuration file that the description beginning in column 11 may contain "[S]" at the beginning. This is a key for users which indicates that all files contained within that particular database contain a "SUBJECT:" line which describes the contents of that particular file. For example, if the user commands: OS SEARCH LIBRARY SUBJECT: he will receive back a complete list of all files in the "LIBRARY" database along with the first line in the file which matches the "SUBJECT:" search word. If each of your files in that subdirectory contain an "SUBJECT:" line, it makes it easy for a user to get a complete list of files and their topics. It means index files and lengthy lists of subdirectory contents are no longer necessary for you to mess with. All you have to do is be sure that each of the files in the subdirectory contain the subject line. Note that the colon following the word "SUBJECT" is optional. Once you set up your BIS.CNF file, DOUBLE CHECK it for accuracy and format. If you run into problems running BIS, the configuration file is undoubtedly where the problem is. The BIS.CNF file used on the W9LZQ-1 BBS is included in this distribution as an example which you will need to modify to run on your system. -10- BIS EDITING OF USER INPUT BIS in limited instances will do editing on the search word specified by the user and will reject the search word in certain cases. If the search word provided is only two characters in length, BIS will automatically insert a space before the first letter and a space after the second letter, making it effectively 4 characters in length. This provision was included particularly for database searches where users are looking for BBS's or Digipeaters in particular states. Most of the current listings being circulated use the two letter state designator with no period following it... Example: WI for Wisconsin. BIS automatically inserts the necessary spaces. Since the SEARCH program will match any line that contains the search word, you can imagine the result if a two letter search word were allowed. The user could get back matches all the way from "wick" to "wizard". BIS will ignore any leading or trailing spaces in a searchword sent by the user. Example: "[space]TEST[space]" will appear as "TEST" to BIS. BIS will also reject any search word containing an asterisk or question mark since wild card matches are not desirable and are not really necessary on the BBS system. The search word may consist of up to two words separated by a space. If a third word is provided, BIS will reject it and search for only the first two words (one followed by the other). Finally, a note about partial words used as search words. Users may want to specify only a portion of a word as a search word which they may do by only typing a portion of the word. Generally, it is best to include at least 4 or 5 characters of the word just to avoid unwanted matches, but BIS does no editing in such instances. BIS - USER CONSIDERATIONS Although, BIS is relatively easy to use, help messages assist the BBS user who experiences difficulty in utilizing the interface for file and database searches. In addition to including a .HLP file in your BBS HELP subdirectory, it is MANDATORY that you make a duplicate of the file or create your own help file and include it in your "FILES" subdirectory so that a user can use the DOWNLOAD command to get instructions on its use. The file should be named "OSHELP" (no extention) as BIS sends a specific message to users referencing this file for help purposes. The "O.HLP" file, however is not mandatory and the BIS help messages make no reference to it. -11- The syntax of the OS command used to call the SEARCH function of BIS is as follows: OS SEARCH {database or file}{search word} Below are examples of various OS commands given to the BBS and the resultant messages sent back to the user: In the first examples, you will be able to see the help messages sent back to the user if he sends an incomplete or unacceptable command: user command> OS ==BBS INTERFACE SYSTEM== PLEASE PROVIDE FUNCTION ARGUMENT. FOR DATABASE SEARCHES....COMMAND: OS SEARCH [database] [searchword] ...For assistance in using 'OS' command, download file: OSHELP ...Use command: D OSHELP user command> OS SEARCH ==BBS INTERFACE SYSTEM== YOU NEED TO SPECIFY A DATABASE TO SEARCH. VALID DATABASES ARE AS FOLLOWS: DIGI U.S. digipeaters BBS U.S. packet Bulletin Boards ARRL [S] Current year ARRL Bulletins ARRL87 1987 ARRL Bulletins W5YI87 1987 W5YI Newsletters LIBRARY [S] BBS files of a general nature HAMS Call signs, Names, Addresses etc of area amateurs ZIPCODES 5 digit Wisc. zip codes and 3 digit zips for U.S. cities REPEATERS Wisconsin fm voice repeaters TECH [S] Technical files RIVERLAN [S] Files pertaining to the RiverLAN Packet Association GENERAL [S] General files..if not in the LIBRARY, check here! BBSINFO [S] Files relating to the operation of bbs's, digi's, nodes, etc. REPORT [S] NEWSLETTERS: Gateway; ARRL Letter; W5YI Report THE SUBJECT OF ALL FILES IN A DATABASE IDENTIFIED WITH '[S]' MAY BE LISTED BY TYPING "OS SEARCH (DATABASE) SUBJECT:" -12- user command> OS SEARCH REPORT ==BBS INTERFACE SYSTEM== NO SEARCH WORD <OR> SEARCH WORD TOO SHORT. PLEASE TRY AGAIN. user command > OS SEARCH REPORT ANTENNA ==BBS INTERFACE SYSTEM== 05-27-1988 12:47:43 W9XYZ, HERE IS THE RESULT FOR YOUR SEARCH WORD [ANTENNA]: **File AL0212.88 Gale force winds damaged the antenna system at the University of **File GW0219.88 install the antennas, fuel the spacecraft and integrate it with **File AL0408.88 in the path of an oncoming thunderstorm with radio antennas on **File YI0115.88 giving the new Novice operator time to build a station, erect antennas and prepare for THAT'S ALL. The following examples demonstrate other situations: user command> OS SEARCH HAMS W9LZQ ==BBS INTERFACE SYSTEM== 05-27-1988 12:48:21 W9XYZ, HERE IS THE RESULT FOR YOUR SEARCH WORD [W9LZQ]: W9LZQ Kent Helman * (A) 1063 Fairfield St. Onalaska WI 54650 THAT'S ALL. user command> OS SEARCH LIBRARY POTAT (note the partial word) ==BBS INTERFACE SYSTEM== 05-27-1988 12:51:42 W9XYZ, HERE IS THE RESULT FOR YOUR SEARCH WORD [POTAT]: **File RT1LOC87.019 Indian Dinner #2: Potato and Cabbage Vegetable; Mung Dal; Basmati **File WINEMAKE.TXT lack of such an expensive device just squash with a potato masher, **File POTATO.RCP Subject: Blackened potatoes on barbecue grill THAT'S ALL. -13- user command> OS SEARCH DIGI NH ==BBS INTERFACE SYSTEM== 05-27-1988 12:50:53 W9XYZ, HERE IS THE RESULT FOR YOUR SEARCH WORD [ NH ]: **File DIGI.TXT N1AYT 1 DIGI ALTON NH 145.0500 870909 WB2QJA K1BKE 1 DIGI CONCORD NH 145.0500 870909 WB2QJA WA1HZK-1 1 DIGI DEERFIELD NH 145.0500 870909 WB2QJA KA1CDE 1 DIGI DERRY NH 145.0500 870909 WB2QJA N1DYL 1 DIGI HILL NH 145.0500 870909 WB2QJA N1NH 1 DIGI HOLLIS NH 145.0500 870909 WB2QJA W1HJF-1 1 DIGI MT. WASHINGTON NH 145.0100 870503 K1BC W1HJF-4 3 DIGI MT. WASHINGTON NH 445.5500 870905 K1BC K1TR-1 3 DIGI WINDHAM NH 145.0700 870905 K1BC THAT'S ALL. (please note that "NH" has been expanded to " NH " in the example given above, as will any two letter search word) user command> OS SEARCH ARRL SUBJECT: The results of that command are not shown here because of the number of files that would yield, however, it will return the "SUBJECT:" line of every file in the ARRL subdirectory. FINAL COMMENTS (*)Unfortunately, BIS does not provide output of the file searches on your BBS terminal screen while in operation. It does, however, display information about execution of the BIS program. For testing purposes, you will need to call your BBS from another packet station or enlist the assistance of a fellow ham to run tests. Although probably not totally necessary, it might be worthwhile including (*)screen output in a future version. If you have questions about BIS, please write or send a message to me @ W9LZQ-1. Please, no phone calls. Kent Helman W9LZQ 1063 Fairfield St. Onalaska, WI 54650 REGISTRATION You are encouraged to register this program so that you may be notified of updates. Please do not send disks or mailers in antici- pation of updates. Notices of updates will be sent by mail. I cannot guarantee general distribution of future updates, so it is extremely IMPORTANT to register now. A form has been included for your convenience. Future updates will allow for additional (*)interfaces to other functions and will allow you to interface to your own program or DOS commands. In addition, we will be looking for ways to improve the SEARCH interface.