GEMini Atari/GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso/files/bbs/pfindr13/pfind130.doc

Text File | 1985-11-19 | 30KB | 597 lines

************************ THE PATHFINDER ************************

                       Copyright 1992
                   by Daniel M. Wallin jr.

             This document last edited on 05/16/92

 All rights reserved. All program code, documents, and menus
 are copyrighted but may be freely copied and used according
 to the following conditions :

 1. This document and all program files MUST be included in
    an unmodified form.
 2. This program may only be distributed FREE OF CHARGE. This
    program may not be sold without the written permission of the
    author, and the only charges that may be requested for a copy
    of Pathfinder are those for the cost of a blank disk.
 3. The responsability for the use or misuse of this program rests
    soley with the user, and no responsability is assumed by the
    author as to the performance or applicability of the program.





***************** Pathfinder version 1.2 ****************

    1.0  What is Pathfinder???
    2.0  How do I get started?
    3.0  Things you must know to use The Pathfinder
    4.0  Ordering Information
    5.0  About Pathfinder
    6.0  Planned Updates

*****************************************************





  1.0 : What is Pathfinder?

        Pathfinder is a utility that remains resident in memory, and
        will locate files for the operating system that are
        misplaced or missing.  It's secondary purpose is it's
        ability as a diagnostics tool for determining why programs
        fail to work.  It is especially useful for SYSOP's using
        FOREM or TURBO or other BBS's who run doors games on their
        systems.

        When a program tries to open a file that isn't
        where it's supposed to be, often it simply crashes,
        giving no indication of what went wrong.  With Pathfinder,
        you can get information about exactly what file
        it was looking for, and where it was looking for it.
        Pathfinder can also locate the file automatically for the
        program so that the program thinks it is where it is supposed
        to be. For example, suppose you are running a doors game
        and it is looking for GAME.DAT on drive F.  If you only have
        drives A,B,C and D, it will normally crash or quit when
        it tries to load GAME.DAT.  With Pathfinder active, the program
        will automatically find it on drive A,B,C,D or wherever
        else you have instructed it to look for files.

        You can also relocate all of your data files to one folder,
        and have Pathfinder locate them for you.  In this way you don't
        need duplicate folders on all of your active drives.

        Another useful feature of Pathfinder is it's ability to display
        error information.  Suppose you download a file, UNARC it,
        only to find that when you run it, it doesn't work.  You can
        load Pathfinder with the DISPLAY ON, and then run the program.
        If any files are missing, Pathfinder will display what files
        are missing and where they should be located.

        Another useful feature of Pathfinder is it's ability to run
        programs from a Hard Drive that normally will only run
        on a floppy disk.  A program may look for it's files only
        on Drives A or B, but with Pathfinder active, the program will
        load it's files from any drives and paths that you specify.

        Best of all, Pathfinder is intelligent. Once it finds the files
        a program needs to run, it remembers where they were located,
        and finds them instantly the next time... For instance, FOREM
        looks for an HOURLY.BAT file that can exist on any drive.
        FOREM will look for it on ALL active drives.  With Pathfinder
        active, it remebers where it is, and will cause FOREM to only
        look for it where it is, which can actually speed things up.
        Pathfinder also remembers files that don't exist.  That way
        Pathfinder won't keep searching your disk for files that it
        already knows aren't there.

        Pathfinder is very helpful when you want to know which files
        a program is looking for that are optional. With FOREM,
        for example, it looks for MANY files that are optional.
        Some of them are not documented.  Pathfinder saves a list
        on the disk that describes all of the files that were
        not found, and all the files that were relocated.  This
        way you can print out the list and see exactly which
        batch files you aren't using, but are searched for.

    There are MANY more things that can be done with Pathfinder
        and it has many features that are useful in certain
        applications. The amount of possibilities for Pathfinder are
        virtually endless.

        Note that throughout this manual, you will notice the term,
        PATHNAMES.  This refers to a complete drive and folder
        specification, such as C:\FOREM\DOORS\CONQUEST\ or
        just A:\  (in this case we are referring to the ROOT directory)

        Simply stated, a pathname is an area on a storage device
        where files may be located.



  2.0 : How do I get started?

    Pathfinder should have included the following files :

         PFIND130.ACC - The Pathfinder accessory program
         PFIND130.RSC - The resource file for Pathfinder
         PATHFIND.PAT - A sample list of paths for Pathfinder to work with
           CREATE.PAT - Contains pathname to create 'uncreatable' files in
         PFIND130.DOC - This document

        Optionally, there might be :

        NOTFOUND.PAT - A list of files that don't exist
           FOUND.PAT - A list of files already located by Pathfinder

    ** NOTE ** When installed with the KEY, the additional file
    may appear in the directory.

      CONFIG.PAT - Contains info about how to configure Pathfinder


    The first 4 files are essential for the operation of Pathfinder.
        When you boot the system with Pathfinder in the root directory,
        it loads PATHFIND.PAT.  This file MUST be in the root
        directory with FIND110.ACC and FIND110.RSC BEFORE you boot
        the system with Pathfinder.  The PATHFIND.PAT file is a list of
        pathnames for Pathfinder to search for files in the event that a
        program requests a file that isn't where it's supposed to be.

        An example of a typical PATHFIND.PAT file is :

C:\
C:\FOREM\
C:\FOREM\DOORS\
C:\FOREM\DOORS\LOST\
D:\
D:\SYSTEM\
D:\SYSTEM\DATA\
E:\MISC\
A:\
B:\
@

    (Note the '@' MUST be located at the end of the file)

    When Pathfinder intercepts a failed file request, it will
    look for it in the pathnames listed above. First it
    will search the root directory of C, then in the
    FOREM folder, then inside the DOORS folder, etc..
    It will sequentially search all of the pathnames until
    it finds the file. If it is found, it will load it
    as if nothing was wrong, and add the name of the file
    to the FOUND.PAT list.  If it was not found, it will
    return to the program. (and optionally display an error
    message describing what went wrong.) Note in this example,
    A:\ and B:\ were listed last, that way Pathfinder will only
    look on the Floppy Drives for the file if it isn't found
    in the other places first.. This is faster since searching
    on the Floppies is much slower than on the Hard Drive.

        Before installing the Pathfinder accessory on your root directory,
        you should edit or create the PATHFIND.PAT file for your system.
        Be sure not to have any pathnames in the file that do not
        exist on your system, as this can cause erroneous information
        to be included in the FOUND.PAT file.  A sample PATHFIND.PAT
        file has been included so that the program will not crash
        for anxious users who try the program before reading the
        documentation.  However, for correct operation of Pathfinder, you
        must configure it for the pathnames you wish it to search
        on your system.  You do not need to include ALL of the folders
        on your system, only those that you wish Pathfinder to search.
        It is always a good idea to include the root directory of
        each active drive, and to enter the most commonly used
        directories first, and the least used, or the slowest
        (like the floppies) last.

        *** NOTE : *** You must use a text editor that allows you
        to save text without control codes.  Some editors have
        an option to SAVE AS ASCII, while others do not use control
        characters at all.  If control characters get saved into
        the file, strange things may happen, including a system
        error which may lockup the machine.  That is why it is
        very important that you allow no control characters or
        extra blank lines in any of the *.PAT files.


  2.1 : CREATE.PAT description :

        This file contains one pathname.  Here is a sample CREATE.PAT
        file.

D:\MISC


    ** NOTE ** there must be at least one blank line AFTER the
    pathname or else strange things may happen.

    This pathname tells Pathfinder where to create a file in the
    event that it is uncreatable.  Suppose a program tried
    to create Z:\TEST.DAT  If you don't have a drive Z, then
    the program will usually crash or fail to work.  Pathfinder
    will recognize this, and create D:\MISC\TEST.DAT  The next
    time the program tries to load Z:\TEST.DAT, Pathfinder will
    redirect it to D:\MISC\TEST.DAT  In this way, Pathfinder will
    allow the program to work, which normally would be impossible.



  2.2 :    FOUND.PAT description :

    The FOUND.PAT file contains a list of the files that have
    been searched for by Pathfinder previously, and were located.
    Each entry contains actually contains two PATHNAMES.
    The first is WHAT was being looked for. The second is
    where it actually resides. For instance a typical FOUND.PAT
    file might look like this :

A:\DATA\TEST.DAT
C:\PROGRAMS\DATA\TEST.DAT

A:\FONT.DAT
D:\FOREM\GRAPHICS\FONT.DAT

@

    (Note, the '@' must be located at the end of the file!)

    The first line, A:\DATA\TEST.DAT describes where a program
    was expecting TEST.DAT to reside.  The next line,
    C:\PROGRAMS\DATA\TEST.DAT describes exactly where it was
    located at. Note that the listing is double spaced between
    entry pairs, and that after the first blank line, there
    is a '@'. This is an end of file marker, and must be
    included for Pathfinder to work properly.

  2.3    NOTFOUND.PAT description :

      The NOTFOUND.PAT file is essentially the same as the
      FOUND.PAT file, except that each entry is only ONE pathname,
      which contains the location where the program was expecting
      the file to reside.  A typical NOTFOUND.PAT file looks like
      this :

A:\DATA\QUICK.HLP

C:\FOREM\HOURLY.BAT

D:\TEST.INF

@

    Each entry in this file describes a file that does not
    exist.  Note, if you add a file to the system that isn't
    exactly where it's supposed to be, AND it's name is in
    the NOTFOUND.PAT file, then Pathfinder will not locate it
    for you. To remedy this, simply delete the entry in
    the NOTFOUND.PAT file, being sure to keep the spacing
    between entries the same, and a '@' after the last
    blank line in the file.


  3.0 : Things you must know to use Pathfinder

    Pathfinder will lose all of it's accumulated knowledge when you
    turn the computer off.  When installed with the KEY, Pathfinder
    will automatically configure itself upon reset, and load
    in the saved lists, which will reload all of the information
    it learned about where your files are, or aren't located.

    In order for Pathfinder to be able to load in it's list, it has
    to be saved first.  You must save any lists or setup info from
    the desktop.  (trying to do so from inside of some gem programs
    can cause strange things to happen)

        For BBS owners, the best way to do this is to let the BBS run
        for a while, and then take the board down, and from the desktop,
        select the save list option.  All of Pathfinder's data will be
        transferred into two files in the root directory.  The next time
        Pathfinder is restarted, it will retain all of the information it has
        compiled.  Generally, the best time to save the lists is
        when the program has run long enough to not have any messages
        flash upon the screen.  If messages occasionally flash on
        the screen that means that Pathfinder has not learned the status
        of every file that the BBS might search for.  Eventually, no
        error messages will be displayed unless new programs are
        installed (like doors games).

        *** NOTE ***  On an unregistered version of Pathfinder, saving the
        lists is only valuable for seeing what files were relocated, and
        which files do not exist that are being searched for.  The list
        may be printed out.  With the KEY installed, saving the lists
        is how Pathfinder stores what it has learned.  That way when
        you reboot the system, Pathfinder does not have to relearn
        anything.  This version of Pathfinder works fine, until you turn
        the machine off.  After that, Pathfinder will have to relearn all
        of the information that was lost by turning off the power.
        The main advantage of being able to reload all of it's information
        upon system reboot, is that no time is wasted relocating
        misplace files.  The first time Pathfinder has to locate a file,
        it will cause the system to slow down a little while it searches
        the pathnames for the file.  After it has learned where
        everything is, and where it isn't, then Pathfinder will not slow
        a BBS down at all.

        This version of Pathfinder is intended to show the way it works,
        and how useful it can be, but does not include some of the
        important features of the registered version.  Since this version
        of Pathfinder is free, I only get support for the registered
        version.  This way users who like the program and are serious
        about using it, can see how useful the program is, and instead
        of paying for something that is already 'free', you can pay
        for additional features that make it even more useful.  You do
        this by ordering a KEY that turns this unregistered version
        into a registered, updated version.  See the chapter on
        Ordering for more information.

    When used properly, Pathfinder makes BBS's run more smoothly, and
        allows many programs to run that might otherwise cause problems.
        Pathfinder is an 'intelligent' program that remembers where files
        are, and where they aren't.  However, there are limits to
        what Pathfinder can do with the information it is given by the
        operating system.

        One specific problem deals with using the desktop.
        Pathfinder MUST be disabled while doing file copies or creating
        folders.  Generally, you will want to disable Pathfinder
        while using the desktop, and some command shells, to be sure
        that Pathfinder does not try to locate files that are not supposed
        to exist.  For example, suppose you are copying TEST.DAT from
        drive A onto drive D.  With Pathfinder active, an error message will
        appear saying, TRYING TO OPEN > D:\TEST.DAT.  The desktop always
        tries to open the destination file before creating it, so there
        is no way for Pathfinder to know that the operating system is merely
        checking to see if the file exists.  This can cause one of two
        things to happen.  Either the system will crash, or it will copy
        the file over itself.  Hopefully, a future version of Pathfinder
        will automatically disable itself when the desktop is active.

  3.1 : About the PATHFIND.PAT file

    NOTE: You MUST have a PATHFIND.PAT file in the same directory
        as the Pathfinder accessory, or else the program may fail or crash.
    One other thing you might notice is that you cannot change the
        PATHFIND.PAT file if the Pathfinder accessory is loaded into memory.
        I am not sure exactly which versions of TOS this happens with.
        I can only assume it happens with all versions 1.62 or higher.
        Apparently when the operating system loads a file before the
        desktop is started, it remains in a protected mode, and the
        operating system will not allow it to be modified or deleted.
        To avoid this, you must rename FIND110.ACC to FIND110.ACX
        and reboot the system.  Then you can modify the PATHFIND.PAT
        file. Be sure to rename the Pathfinder accessory to it's original
        name, and then reboot the system. Pathfinder will not work if you
        change it's name, so be sure to restore the name exactly to
        what it was before you changed it.  Normally, the PATHFIND.PAT
        file does not need to be changed very often, so it does not
        normally present a problem.

        ** NOTE **  This problem may be corrected in this version
        of Pathfinder, however, since I do not have access to ALL versions
        of the operating system, I have included the above for those
        who have experienced problems modifying the PATHFIND.PAT file.

  3.2 : Error Messages

    Error messages will only appear if the display mode is set to
        on.  There are 2 error messages. One is for opening files,
        the other for creating files.  The open files error display
        will allow you to insert another disk into the drive to search
        for the file.  It will only work if you have the floppy drive
        specified in the PATHFIND.PAT file.  It just retries
        the entire FIND routine, so if drive A was never specified,
        inserting a new disk will have no effect.  The create files
        message display simply shows what file the operating system
        was unable to create.  (** NOTE **, after displaying the
        create error message, the file will be created in the pathname
        specified in the CREATE.PAT file...  If the display OFF
        option has been selected, then no error messages will appear.)

  3.3 : Pathfinder Options

        From the main menu, you will notice several options, two of
        which should be highlighted in blue.  These are the default
        settings.  On the left side, you will see the display options.
        The ON option will cause error messages to be displayed if
        something goes wrong.  I strongly recommend using this option
        until you get the hang of how Pathfinder works, and what it is
        doing.  It however requires the user to be present to inform
        the Pathfinder program to continue.  That is why the Display OFF
        option was included.  It will not request any input from the
        user if errors occur.  For instance, suppose you run the Pathfinder
        program with the Display ON option.  While running Forem, the
        operating system will eventually try to run a DAILY.BAT file.
        It is not necessary for the operation of Forem.  With the error
        display ON, you will have to enter a keypress the first time
        it tries to load the DAILY.BAT file.  With the Display OFF,
        the program will act as if nothing out of the ordinary occurred,
        and the Pathfinder program will simply update the NOTFOUND.PAT list.
        The other display option is very important.  It is the INACTIVE
        mode. This simply turns off Pathfinder, and makes sure that no
        file redirection takes place.  You will want to use this feature
        whenever you are moving files around with the desktop, or
        creating or deleting files or folders.

        On the right side of the menu, you will see the search options.
        The List mode, will cause Pathfinder only to act upon files that
        are in one of it's lists.  This means that Pathfinder will not learn
        where any new files are, and will only respond to requests to
        locate files that it already knows where they exist.  Normal
        file requests are not modified in any way with this option, so
        as long as a file is where it is supposed to be, it doesn't
        matter which search option Pathfinder is in.  The Search mode causes
        Pathfinder to ignore it's lists, and to search for each file, no
        matter whether or not it knows if it exists, or if it isn't
        supposed to exist.  This mode is the slowest, since it will
        search each path listed in the PATHFIND.PAT file everytime
        a file is requested that is not where it is supposed to be.
        The final option, List and Search, is the normal option.
        It will check it's lists first to see if it knows anything
        about the whereabouts, or nonexistance of the file, and if
        nothing is known about it, then Pathfinder will search for it.
        This is the option that will be used the most often, as it
        employes all of Pathfinder's knowledge to locate a file.

        The other options are self explanatory, or not available in
        this version of Pathfinder.  The info option simply displays the
        program credits, and ordering information.

        The other options are for configuring Pathfinder.  The list size
        option allows you to change the amount of memory reserved by
        Pathfinder. The Save Options button will save all options into a
        configuration file which will be read upon system reboot. This
        way BBS owners in particular can have their system automatically
        reboot upon power failure with Pathfinder already installed.  This
        is particulary important, since some doors programs may not run
        at all without Pathfinder active, and a reboot without automatically
        loading Pathfinder could cause those programs to lock up the computer
        when they are run.

  3.4 : Memory Management

      This version of Pathfinder has it's memory requirements already
      determined.  This means that each of it's 3 lists has 10k of
      memory allocated.  An additional 32k of memory is used for
      saving screen data, and another 20k or so is used by the program.
      This means that Pathfinder can use around 100k, which is no big
      deal on a 4 megabyte system, but on a 512k system, it could
      cause problems with some programs that use all of the available
      memory.  With a KEY installed version, you can configure the
      amount of memory reserved for each of Pathfinder's lists.  In this
      version, you can have upto 10k of data in each file, which is
      actually quite a lot.  However, should you start to approach or
      exceed this amount of memory, which is very unlikely, then strange
      things might begin to happen, so be sure to occasionally check
      on the size of the files. (NOTFOUND.PAT, FOUND.PAT, PATHFIND.PAT)




  4.0 : Ordering Information

      Pathfinder is a shareware program. That means you can use it as much
      as you like, but if you like it, you should become a registered
      user.  This has two effects.  First, you get a KEY which installs
      additional options into the Pathfinder program, and Second, you help
      to fund additional updates.

      With the KEY installed, you also have the following features :

      It will automatically install itself on reset or power up with
      whatever options active that you choose.  It remebers whatever
      it has previously learned, so once you have let Pathfinder figure
      out where everything is, you will not even notice that it is
      installed.  It will quitely redirect file input/output without
      any speed decrease at all.

      It includes the ability to control how much memory
      is assigned to Pathfinder.

      A KEY for Pathfinder is available for only $15 !!!
      To order a KEY for Pathfinder version 1.2, send $15, or more,
      cash or money orders only, to :

                          P A T H F I N D E R

                 P.O. Box 5011, Aloha Oregon 97006-0011

        *** NOTE : ***  Money orders MUST be made payable to
        Daniel M. Wallin jr.   Also, please be sure to clearly
        PRINT your name and address on a seperate piece of paper.

        NOTE : Those users who send in $20 or more, will be placed
        first upon the mailing list.  This means that they will be
        the first ones to receive their key, and future updates.

        ***** YOU MUST INCLUDE THE NODE NUMBER, OR NAME OF THE BBS
        THAT YOU WANT THE KEY FILE TO BE EMAILED TO *****

        This is the fastest, and easiest way to get a registered
        version, as you can receive the KEY over the CROSSNET
        network within a week, sometimes only a couple of days!!!

        Feel free to include any comments or suggestions about what
        features you would like to see in the future.

        Also, while not necessary, it would be nice if you could
        include the system type you are using (ST, STE, Mega STE, TT)
        and the version of the operating system you are using.

        IF you need to contact me, for update information, suggestions,
        or whatever, you can reach me at Puddle City, 503-289-9429.
        Puddle City is NODE # 670.  Please address mail to Dan Wallin.


  5.0 : About Pathfinder

      Pathfinder was originally developed because of the problems
      created by many doors programs which refuse to run
      correctly or cause various problems on some BBS systems.
      With Pathfinder active, the installation and use of many
      doors programs is greatly simplified. Some doors programs
      simply would not run without Pathfinder active.  Developing
      Pathfinder was slow and tedious and required many months of
      debugging, testing, optimization and modifications.  It
      was written entirely in assembly language for the maximum
      amount of speed in the least amount of memory.  Pathfinder
      was designed to increase the ability of the operating system
      without any sacrifice in speed.  Later, an option was added
      for floppy based systems that allowed disk changes for files
      that are not found. That way programs that are so big they
      normally only run on Hard Drives will run on floppies,
      as long as there are no files that are larger than can
      be stored on a floppy.

      While Pathfinder may seem like a small program, it took months
      of research and testing, and is an incredibly complicated
      extension of the operating system.  Pathfinder causes all TOS
      commands to be channeled through Pathfinder, where they are
      examined, and processed accordingly.  Pathfinder should work
      fine with all programs, with the following two exceptions.
      Pathfinder can eat upto 100k, in an unregistered version.
      Programs that require most of the available memory may not
      work with Pathfinder in memory.  This is particulary bothersome
      for 520ST users with only half a megabyte of memory. This
      is why the free memory display was included in the menu.
      This should give you a rough idea of how much memory is
      available to the operating system.  The only other conflict
      might be with programs that use the TRAP #00 vector.  This
      should not be a problem, since it is not used by the operating
      system, and I have not found any programs that use it.

      I hope you find this program useful, and if so, please order
      the updated version, since I only get financial support for
      KEY files which are sent to registered users.

      Also when ordering, please include any comments
      or suggestions on features you would like to see.

  6.0  Planned Updates :

       MANY more things are planned for the future of Pathfinder.
       In the works right now is VIRUS PROTECTION!  This will work
       in the background all the time.  It will keep files on
       your harddisk from being corrupted, and it also will allow
       you to install anti-viruses to keep things from being
       infected.  Unlike other programs which only check to see
       if you have already been infected, this virus protection
       keeps viruses, trojans, and worms from modifying any of
       your files!  Also, online editing of the lists seems like
       the next logical step.  The amount of things that can be
       added to Pathfinder are limitless, since it is an extension
       of the operating system, and causes all TOS commands to
       be channeled through itself.  If you have an idea for
       an update or modification to Pathfinder, please include it in
       your order for a KEY, or send email to me at Puddle City.