PathMan Version 1.02 Copyright © 1988 by William S. Hawes All Rights Reserved PathMan is a trick DOS handler that simulates a concatenation of directories, allowing you to combine several different directories into one "path" directory. The internal logic of the handler implements a linear search of the directories and thus provides a transparent search facility for any software application. Since the concatenation is done at the DOS level, any software that makes use of normal DOS calls will work with the path handler. In particular, system directories like LIBS: or FONTS: can be spread over several directories or volumes. Paths may refer to any other devices, directories, or volumes, including other path directories. Devices need not be mounted or created at the time a path is defined, but will be requested when actually needed for a search. Directories included in a path can be redefined at any time, and the path will use the definition in effect when the search takes place. Path directories are automatically created by an attempt to lock an object relative to PATH:, as with the ASSIGN command. By default a path is transient and disappears as soon as the lock is released, though permanent path directories can be created with an ACTION_CREATE_DIR packet. -- Defining a Path -- The PathHandler defines a path as a list of directories separated by the delimiters comma (,), semicolon (;), vertical bar (|), or white space. Each directory name must include a device specification, as there is no "current directory" for the handler itself. A path can include nested references to other paths up to 10 levels deep. The following are all valid path specifications: path:df1:c,df0:devs/printers,jd0: path:vols:,vols:c When a path is referenced by a call to DOS, any nested definitions are fully expanded into their component directories. Within a path definition a directory name following a device name is distributed to all of the components. For example, if "vols:" had been assigned to "path:df0:,df1:", then referring to "vols:c" inside a path would expand to "df0:c,df1:c". Before adding a new directory to the expanded list, the PathHandler checks whether the exact specification already occurs earlier in the list to avoid duplicating the search. A path can be either transient or permanent. Transient paths come into existence by requesting a lock on an object relative to the PATH: device, most conveniently using the ASSIGN command. The transient path persists until all locks on it are released. Permanent paths can be created using the AmigaDOS ACTION_CREATE_DIR packet; the MAKEDIR command doesn't work directly, since it first attempts to lock the directory and concludes that it already exists. Once created, a permanent path can be removed using the DELETE command, provided that there are no outstanding locks on it. -- Path Aliases -- Since the full specification of a path name involves multiple device names with their attendant colons, the path may confuse software that expects to see only a single colon in a file name. In addition, the path name may get quite long, which can create problems for some "file requestor" routines. To avoid these problems, the PathHandler supports a concept of "alias names" for paths. A path alias (not to be confused with the aliases used by a command shell) is an alternative name for a path that obeys the normal naming rules for a file or directory. Whenever an alias name relative to PATH: is found, it is expanded into its full path before being processed by the PathHandler. For example, suppose that "path1" was an alias for the path "DF0:,DF1:". Then a reference to "PATH:path1" would expand into "PATH:DF0:,DF1:". The PathHandler can always tell the difference between a path name and an alias name, since the former must contain at least one colon and the latter will never contain a colon. Path aliases can be created explicitly by using the FileNote command to assign the desired alias name as a "comment". Once this is done, the PathHandler inverts the normal usage of "name" and "comment" and thereafter reports the alias name as the "name", and the full path as the "comment". Path aliases can also be recognized as implicit references to a device or assigned directory, and this gives the PathHandler the ability to refer to any device or volume even if a path to it hasn't been previously created. Whenever a name relative to PATH: doesn't include a colon and so can't be a full path name, the relative part is taken as an implicit alias name. For example, in the name PATH:include/exec, the relative part "include/exec" is assumed to be a path alias. If an alias name "include" has been defined, its full path is substituted. Otherwise, the name is checked against the DOS device list, and if it exists there is tranformed to be relative to that name. In the above example, if INCLUDE: existed as an assigned directory, then PATH:include/exec would be transformed to INCLUDE:exec. -- Protection Attributes -- Path directories can be assigned protection attributes using the PROTECT command, and these attributes are obeyed by the PathHandler when searching a path. If the action to be performed requires a specific permission, the search skips over any candidate directories lacking the necessary attributes. For example, suppose that the following paths are created: 1> ASSIGN p1: path:dh0:,df0: 1> PROTECT p1: r 1> ASSIGN p2: path:p1:c,df1: Then a search of P2: requiring only read permission -- like a LIST command -- will search the P1: directories, but a search requiring delete permission will go directly to the DF1: node. -- Installation -- To install PathMan, just copy the PathHandler file to your L: directory, append the mountlist entry to your DEVS:mountlist file, and mount path:. You're now ready to start building paths using the ASSIGN command. The "setup" script shows a couple of examples. You may also want to use "pathwack", a debugging aid that shows how the path search is being conducted. To run pathwack, open a separate CLI and issue the command "pathwack". The expanded paths being searched by PATH: will then be listed in the pathwack window. Issue a Control-C to exit. -- Technical Details -- The PathHandler employs a number of tricks in attempting to provide a consistent implementation of the DOS packets it supports. Two packet types, ACTION_FINDOUTPUT and ACTION_RENAME, presented special problems in implementation, and are therefore explained in greater detail here. An ACTION_FINDOUTPUT packet is generated whenever a program attempts to open a new file for writing. For example, an editor writing a file out to disk will usually open a file in this mode. The simple implementation of this packet in the PathHandler would have been to walk the path directories until one succeeded in opening the file, and then terminating here. However, often the file being opened for writing has been previously read from an existing file, and in most cases the new file should be written back over the old file. The simple implementation would instead always place the file in the first writable directory in the path. The "write-back" feature is supported by having the PathHandler walk the path list first attempting an ACTION_FINDINPUT packet (the "read file" equivalent). If this operation succeeds, the packet is transformed to an ACTION_END to close the opened filehandle, and then changed back to an ACTION_FINDOUTPUT with the path index set at the point where the file was found. If the ACTION_FINDINPUT or second ACTION_FINDOUTPUT attempt fails, then the path index is reset and the entire operation repeated from the beginning as an ACTION_FINDOUTPUT. Supporting the ACTION_RENAME packet similarly requires several steps, but is even more complex because two separate paths are involved -- one for the old name of the file, and one for the new. The rename operation begins by walking the old name path with an ACTION_LOCATE_OBJECT (lock) packet to attempt to find the named file. If this succeeds, the packet is transformed back into an ACTION_RENAME, and the PathHandler then walks the second (new name) path until this packet succeeds or the path is exhausted. Two possible failures can occur: if the ACTION_LOCATE_OBJECT packet fails, the operation terminates with an error code of 205 ("object not found). If the ACTION_RENAME packet fails, the final error is reported as an error 215 ("rename across devices"). -- Problems? Questions? -- PathMan is still somewhat experimental in its design, though it should operate reliably. Please report any bugs, quirks, and misfeatures promptly so that they can be corrected, and don't hesitate to offer suggestions! Bill Hawes (508) 568-8695 September, 1989