Shareware Supreme Volume 6 #1/swsii.zip/swsii/126/XHAIR10.ZIP/XHAIR.DOC

Text File | 1993-02-28 | 21KB | 427 lines

                                   CrossHair


                                 Introduction

   CrossHair is a resident file look-up program which will provide information
about files in your collection while viewing a filelist in some other program.
With that information in hand making download, or other decisions, on each
individual file are better informed. For example:

   (1) You might use it while online with a BBS to determine if you already
      have as specific file

   (2) You might use it offline in RoboComm while viewing the "available files"
      screen to determine whether a specific file duplicates something you
      already have, is a later version, or is an entirely new file.

   (3) If you are a PCBoard sysop, you might use it while using PCBfiler in the
      foreground. CrossHair will point out earlier versions on your board, if
      they exist, and will tell you which file directory they are located in.
      The error in which different versions appear in different directories
      should be completely eliminated by using CrossHair.


   To some extent, CrossHair will work with any foreground file-reader or
communication program. The idiosyncrasies of some programs have been
programmically dealt with so that CrossHair will read the screen and
automatically look up the filename under consideration. Programs in this
category include Robocomm, PCBfiler, and List. Other programs, such as Qedit,
work well in the default look-up mode which depends upon the filename starting
on the first screen position and a moving cursor to indicate the file under
consideration. In other programs, such as Telix, it is not possible to tell
what you are looking at from the appearance of the screen. In the latter case,
CrossHair loses some of its automatic nature but can still be used as described
later.

   Before CrossHair can be used, some configuration is required to provide it
with the information to look up. If you are a PCB sysop, the configuration is
done automatically from CNAMES by PCBINDEX which is also a part of this
package. If you are not, you will need to do some setup as described later.


                                 Legal Aspects

LIMIT OF LIABILITY

   CrossHair is distributed as is. The author makes no representation with
respect to the fitness of the software for any particular purpose and disclaims
all warranties, expressed or implied. The author will assume no liability for
damages either from the direct use of this product or as a consequence of the
use of this software.

SUPPORT

   There is no staff employed for support purposes. If you have a problem to
report or features you would like to see implemented, use the comment field on
the registration form. Alternatively, I can be reached with msgs placed on
Computer Connections BBS [phone] in Washington DC or Toad Hall BBS (415)
595-2427 in San Carlos, CA. All suggestions will be evaluated for the next
version.


SHAREWARE

   CrossHair is distributed as shareware. This means you can evaluate the
product before you decide to register it. If you are using it after a couple of
weeks, you should register it. You can copy CrossHair or any shareware program
and distributed to anyone else, provided that neither the program nor the
documentation is altered and that you do not charge a fee. Because there is no
advertising, distribution, or packaging cost, the price of a shareware program
is often less than an equivalent package sold through retail channels. The
registration form is provided in a separate file.


                                     Setup

   To be useful, CrossHair should be able to find the information it displays
in a psychological instant, i.e. what "seems" instantaneously. To achieve that,
all information must be put into a format which permits such rapid access. The
formatting of data is done by PCBINDEX. As a final step, PCBINDEX spawns the
program SORTF which alphabetizes the entire filelist so that CrossHair can
easily find the alphabetic neighbors of the target filename.

   The program SORTF by Vernon Buerg must be on the path for this version, and
probably all future versions, of PCBINDEX to function. SORTF is not included in
this package but it can be found on nearly any BBS, and probably where you
found this package, under the name "sortfnnn.zip" where nnn is the version
number.

   Follow the steps below to setup CrossHair. Setup is slightly different, and
easier, in a PCBoard environment.

1. Put SORTF on the path

2. Set an environmental variable PCBDIR, e.g.

              set pcbdir=c:\pcb

      This statement can be typed from the command line if you are trying
   CrossHair or expect to use it infrequently. Otherwise it should be put into
   your autoexec.bat file. In either case, be sure there are no spaces after
   the equals sign. This is the subdirectory in which both PCBindex and
   CrossHair can expect to find its control files. It need not be on the path
   and it can coexist with other files.

      If you are a PCB sysop, the argument should identify the PCB root
   directory. With that information, CrossHair can find CNAMES (in \pcb\main)
   and from that it can locate all of your file directories and listings (dirn
   files). PCBindex can deal with errors (missing files) listed in CNAMES, you
   will save time in the long run if CNAMES is correct.

       If DOS gives you an error message ("Out of environmental space), your
   environment isn't large enough. If your environment is not large enough, try
   increasing the size a tad. That is done with a shell command in the
   autoexec.bat file, e.g.

                shell=command.com /E=384

      Where the environmental size is specified after /E. If you don't already
      have a shell command, the default environmental size is 250 under DOS5
      and 160 with earlier versions and you will need to increase it from those
      values.


2. Create the control files.

   If you are working in a PCB environment, this step can be skipped since the
control files are created for you automatically by the next step. Otherwise,
the main control file is called pcbxh.dat. You must create it in the following
format:

Text file           Physical Location     Description
R:\DIRS\DIR2        V:\HARDWARE\          Hardware
R:\DIRS\DIR3        Z:\WP\                Word Processing
R:\DIRS\DIR4        Z:\DTP\               Desktop Publishing
R:\DIRS\DIR5        X:\BUSINESS\          Business

   The list of text files which contain filenames must be accurate and
complete. The physical location and description are optional. If they are
included, they are feed back to you with CrossHair "ALT L" command as described
below. This control file must be called PCBXH.DAT and it must be in the
subdirectory pointed by the environmental variable PCBDIR.

   CrossHair works on text files rather than the actual filenames. If you are
the sysop of any kind of BBS, you already have the text files. If you are not
and all you have are files, you can produce text files by writing the
directories which contain files to a file, e.g.

    dir j:\mydir >myfiles1


3. Execute PCBindex without argument.

          c:>pcbindex

   This step will take a few moments and you can watch its progress in the
upper right-hand corner.

   If all goes well, you are now in position to run CrossHair as described
above. There will be a file called xh.xdb in your pcb directory. You will
probably want to put "xh.exe" and "pcbindex.exe" in a util directory on the
path. There is no advantage (or disadvantage) for "pcbxh.dat" or "xh.xdb" to be
pathed or located in the same subdirectory as CrossHair and PCBindex.


                               Running CrossHair

   CrossHair can be executed either in a resident mode or nonresident mode. In
the nonresident mode, all input is taken from the keyboard. In the resident
mode, CrossHair looks at the screen and positions itself in your filelist at
the point it thinks is the targeted filename. If there is a filename which is
an exact match for what it thinks is the targeted filename, the CrossHair
cursor will be positioned on that match. If there is no match, the cursor will
be positioned on the filename which precedes the targeted filename.

   To execute CrossHair in the resident mode:

c:>xh

        This command loads CrossHair. You should see a message telling you how
     to activate CrossHair and how to remove it from memory.

Press the hotkey(ALT .)

        This should cause a screen to come up similar to the one below. An
     escape will remove all CrossHair screens. Because you loaded resident,
     CrossHair will read your screen and what is at the cursor line of the
     screen at the moment is the DOS prompt. If your prompt begins with
     "Monday", for example, the CrossHair cursor will rest on the filename
     which alphabetically precedes Monday (in my list, that is MODEM20).  If
     your prompt begins with the characters "C:", the CrossHair cursor will
     rest on a filename which begins with "C-" or "C2". In any case, a screen
     similar to the following will be displayed.


╔══════════════════════════════════════════════════════════════════════════════╗
║ALFRED12.ZIP    11740  10-31-91  Alfred - The Desktop Butler v1.2:  MS-Windows║
║                               | 3.0 program that sits at the bottom of your  ║
║                               | screen, providing a menu for instant access  ║
╚══════════════════════════════════════════════════════════════════════════════╝

     ╔════════════════════╗
     ║X:\WINDOWS\UTIL\    ║
     ║R:\DIRS\DIR36       ║
     ║Windows: Utilities  ║
     ╚════════════════════╝

                                                  ┌──────────────┐
                                                  │ ADVID105  20 │
                                                  │ AGREP201  46 │
                                                  │ AHEAD     41 │
                                                  │ ALCHMY14  11 │
                                                  │ ALERT14G  42 │
                                                  │ ALFRED12  36 │
                                                  │ ALIB12    47 │
                                                  │ ALINT10   46 │
                                                  │ ALLCC251  41 │
                                                  └──────────────┘

   CrossHair now operates in a obvious way. As you move the bar in the files
box, the description changes to match the operative file. The file box displays
all files in an alphabetic order and the area number in which they are located.
The location box is displayed only if you hit ALT L.

   The area numbers are not meaningful for any conferences. However, the
specifications returned by the ALT L command are correct.

   You can navigate in your files list with the following keys.

   up arrow        Up a file
   down arrow      Down a file
   page up         Up 10 files
   page down       Down 10 file
   home            Go to the first file (alphabetically) in list
   end             Go to last file
   alt L           Display location box
   alpha keys      Go to file whose next letter is the one I hit
   escape          Return to host (DOS)

   To look up a specific file, just start typing in the filename. By the time
you type three or four letters, your bar will be sitting on top of it. In the
example above, by the time you've type MON, you know you have no file called
"MONDAY". To look up a second filename, you have to terminate the first
sequence with a navigational key or a return. In the screen above, if you typed
in the letters A,L,F your bar would be on top of ALFRED12. If you then wanted
to look up PKZIP and did that by typing P, the bar wouldn't move because
CrossHair would think you are looking for a file starting with the letters
"ALFP."  If you hit a return or navigation key first, then the bar would move
to the top of the P's.


Running CrossHair with a host reader:

   With CrossHair resident, load the reader or communication program you
normally use and goto a mode in which you are looking at a listing of files.
Even if you are not using any of the specifically configured file readers (e.g.
Robocomm, PCBfiler) CrossHair will probably still read the screen correctly. If
it doesn't, you can still use CrossHair to look up what is on the screen by
typing the first few letters of the filename. The considerations of look up are
described later.

   These commands apply to the CrossHair:

   xh /n    load CrossHair as a foreground (nonresident) program
   xh /u    unload CrossHair from memory
   ALT .    activate resident CrossHair.


File look-up characteristics

   The manner in which a target file is determined varies from program to
program. The only clue that CrossHair has with respect to what file you are
looking up, is the appearance of the screen. Consequently, CrossHair must
figure out who your host is before it determines what its target is. Since all
possible hosts have not yet been described within CrossHair, it will not always
work automatically. It will work however, in the following circumstances:


Under RoboComm

   RoboComm should work correctly in both the "available files" and
"downloaded" file sections. In robocomm, the cursor location not relevant. The
relevant file is the one under the blue bar. To look up a file, position the
blue bar and hit the hot key. CrossHair with then emerge with its bar on the
nearest match in your files list.


Under PCBfiler

   In PCBfiler, both the cursor location and the bar are irrelevant. The target
file is located in column 10 of the line on which you are located or the
nearest preceding line on which column 10 does not contain a space.

Under List

   List provides no clue about the filename under consideration since the
cursor is always located on the last screen line and CrossHair's pupil-reading
function does not yet work. When List is the host reader, CrossHair will
initiate as if the target filename is the final one displayed. The thinking
here is that it is better to be right some of the time than none of the time.

Under Qedit (default)

   Under Qedit, CrossHair determines the target filename as it does with all
host readers other than those specified above. The target file is determined by
what is located at column 0 on the line on which the cursor is located. If the
first character is a space or tab, then CrossHair examines lines preceding the
cursor line until it finds one in which the first character is not a space.

Under anything else:

   If the environment in which you are operating is not described accurately
above, then you won't get automatic filename lookup with CrossHair. When
CrossHair is brought up, the cursor will probably be at the end of file in
filenames beginning with 'Z'. To find a filename, you will have to type in the
name. Very likely you will be right where you want to be by the time you have
typed 3 or 4 letters.



                                   PCBINDEX

   PCBINDEX must be run before CrossHair. It gets all the information it needs
from the environmental variable PCBDIR and needs no command line arguments.

   PCBINDEX creates two files pcbxh.dat which describes your system and xh.xdb
which is part database and part index file which tells CrossHair in what file a
filename is listed and how many bytes into the file that specific file is
listed. It must be run whenever the file listings have changed. If you are
running under batch file control, you might wish to include it in whatever
night routine you use. However, it is relatively fast and can be run from the
command line without significant time consequent.

   PCBoard can be configured to use an index of file locations which must be
updated when file locations change. That update is performed automatically when
changes are made with PCBfiler via the mechanism of running a batch file named
refresh.bat when changes are made. The CrossHair index can be updated at the
same time by adding the command "pcbindex" to refresh.bat.

   While xh.xdb should not be modified manually, pcbxh.dat is a flat file which
can be modified with any text editor. You can add listings which are not
referenced by CNAMES such as off line directories. However, since pcbxh.dat is
rewritten whenever it becomes obsolete, (and will therefore erase any changes
you've made) what you will want to do is put any additions into a separate file
and run pcbindex from a batch file such as the following:

    pcbindex
    type newstuff >>pcbxh.dat

PCBINDEX command line arguments

   PCBINDEX does have a few command line arguments which are basically
irrelevant to anything discussed heretofore. They do produce some files useful
for other purposes and exist because all the information is available during
the operation of PCBINDEX.

   /g     Creates two batch file called go.bat and 4go.bat. These batch files
          take you to the directory which includes files. E.g. if you gave the
          command, go 43, the batch file would take you to file area 43. The
          batch file "4go.bat" is identical in function, but it is smaller,
          quicker, and works only if you are using 4dos. You will probably want
          to copy one to a pathed subdirectory and delete the other.
   /t     Creates a text file of all filenames. The files are listed in the
          order in which they are found.
   /f     Force a run of pcbindex even though all files are current. This is
          useful only if your system doesn't properly time stamp files or if a
          run is interrupted.


PCBINDEX limits

   There are some limits to the operation which are: 100 conferences and 250
download directories and unlimited filenames. These limits are not logically
necessary but are practically necessary because PCBoard and CNAMES allows
duplicate download directories in different conferences. While that is not
wrong in the operation of PCBoard, it is desirable to weed out the duplicates
for the operation of CrossHair.


WHAT CAN GO WRONG

 1.  When I bring up CrossHair, no filenames are displayed and all I see in the
     files box are zeros.

          You have probably exceeded the maximum number of open files
          particularly if you are running resident under Robocomm. Increase the
          "files=" specification, reboot, and try again.

 2.  The description display is not consistent. Sometimes it does not
     correspond to the filename under the cursor, sometimes it starts in the
     middle of a description.

          Your index (xh.xdb) is not up to date. CrossHair depends on knowing
          how many bytes beyond the beginning of a dir file that the
          description begins. If you change the dir file, that count will be
          wrong at all points after the point at which it was changed.

 3.  The files displayed in the files box are not related to what I am trying
     to look up.

          CrossHair communicates with the display program via what is on the
          screen at the cursor position. But it does some interpretation. It
          checks first to see if the screen display is produced by Robocomm or
          PCBFiler. If it is it knows how to find the active file regardless of
          where the cursor is located. If it isn't, it assumes the filename is
          the first word on the line on which the cursor is located. If that is
          not the filename, it will look up that word anyway. If the listing
          program doesn't work that way, it is not fully compatible with
          CrossHair yet.

          CrossHair should come up and do something, even if it doesn't know
          what to do. If you then type in the filename, you should be sitting
          at the right location by the time you have typed 3 or 4 characters.

 4.  CrossHair seems rather slow on file-description display.

          This is addressed primarily to 286-users. As a point of reference, I
          don't sense any delay on a 486/33. In the most adverse situation
          tested (a 386/20 with four-way clock splitting under DesqView) the
          delay appears to be approximately 0.15 sec which, in my view, is
          borderline acceptable. The tradeoff is between memory consumption and
          speed. The former was chosen because I wanted it to run well under
          RoboComm which wants a great deal of memory. The cost in speed is
          estimated to be about an order of magnitude.