Futurebasic/Language/files folders

Specifying Files and Directories

There are a number of FB statements and functions in which you must specify a particular file and/or a particular directory. A directory is basically a folder; in addition, every volume (basically, every disk) has a root directory, which has the same name as the volume itself. A directory is a container; when you double-click on a folder icon in the Finder, you see a window which shows that directory's contents. Likewise, when you double-click on a volume's icon, you see a window which shows the contents of that volume's root directory.

As the MacOS has evolved, a number of different schemes have emerged for specifying files and directories. The statements and functions in FB use a system which involves three different pieces of information, which interact in ways that are sometimes subtle. These pieces of information are: the Path Name, the Directory Reference Number, and the Directory ID Number.

The Path Name

In the MacOS, a path name is a string of no more than 255 characters, consisting of colons and/or names of files and directories in a particular format. It's usually identified as path$ in syntax descriptions in the manual.

• A full path name begins with the name of a volume, and ends with the name of a file or directory that is somewhere within that volume. In between is a hierarchical list of the directories leading from the root level to the final item; the names in the list are separated by colons. If the last item in the list is a directory, it may optionally be followed by a final colon. A full path name always contains at least one colon, but never begins with one. A full path name which consists of just the volume's name followed by a colon, indicates the volume's root directory.
• A partial path name either begins with a colon, or consists of just a single item's name with no colons. It indicates a hierarchical directory path relative to some "base directory" (discussed below). A partial path name that contains no colons indicates an item at the base directory's first level. A partial path name that consists only of a colon (with no item names listed) refers to the base directory itself. A partial path name may also begin with multiple colons: a leading double-colon indicates that the path begins at the base directory's parent; a leading triple-colon indicates that the path begins at the base directory's "grandparent," and so forth.

The Directory Reference Number

This is a peculiar concept which, for historical reasons, can be interpreted in a number of different ways depending on its value. It can also be interpreted as indicating either a volume, or a particular directory on a volume, depending on the value of another quantity called the "Directory ID Number" (discussed below). The Directory Reference Number is always stored as a "signed short-integer" number, so it can range in value from -32768 to +32767. It's usually identified as refNum% in syntax descriptions in the manual.

Note: A Drive ID Number is assigned to each disk drive when the system starts up. A Volume Reference Number is assigned to each volume when it's mounted, and is valid until the volume is unmounted. A Working Directory Reference Number is assigned to a particular directory on a particular mounted volume at the request of your application, and is valid until your application "closes" that directory (as with the CLOSE FOLDER statement), or your application quits.

The Directory ID Number

This is a positive number that the MacOS assigns permanently to each directory at the time the directory is created. On any given volume, no two Directory ID Numbers are the same; however, two directories on two different volumes might both have the same Directory ID Number.

In those FB statements that use a Directory ID Number (OPEN, KILL, NAME, RENAME), you can use two different techniques to specify the number:

You can specify it explicitly as a parameter to the statement. It's usually identified as dirID& in syntax descriptions in the manual. If you don't specify it explicitly, FB uses the number that you've specified in the PARENTID statement. If you haven't yet executed the PARENTID statement, FB uses zero. Also, the OPEN, KILL, NAME and RENAME statements always automatically reset the PARENTID value back to zero after the statement executes.

Note: certain other FB statements and functions (such as FOLDER) do not use a Directory ID Number and don't pay attention to the PARENTID value. Another way to put it is: such statements and functions always behave as though the Directory ID Number were zero.

How These Three Things Interact

FB uses the Path Name, the Directory Reference Number and the Directory ID Number in the following ways to identify which file or directory you're indicating:

• If the Path Name is a full path name, then the Directory Reference Number and Directory ID Number are ignored. The item is completely specified by the Path Name. (Note that if there are two mounted volumes which both have the same volume name, then a full path name can be ambiguous.) If the Path Name is a partial path name (or is not specified), then the Directory
• Reference Number and Directory ID Number are used together to identify a base directory. The item, as identified by the partial path name, is then located relative to that base directory (or, if no Path Name is specified, the item is the base directory itself). The base directory is determined as follows:
  • If the Directory ID Number is zero, then the base directory is determined entirely by the Directory Reference Number, according to the "Directory Interpretation" column in the table above.
  • If the Directory ID Number is nonzero, then both the Directory ReferenceNumber and the Directory ID Number are used to identify the base directory. In this case, the base directory's volume is indicated by the Directory Reference Number (according to the "Volume Interpretation" column in the table), and the Directory ID Number identifies a directory within that volume.

Other Ways to Specify Items

When you specify files or folders in calls to MacOS Toolbox routines, you don't always need to use the three data items discussed above. The preferred way to identify a file or folder in many Toolbox calls is by means of a fileSpec, which is a 70-byte record containing a volume reference number, a directory ID number, and the item's name. To track an item which may not be on a currently mounted volume, or which may have been renamed or moved to a different folder, the preferred method is to use an alias record. Refer to Inside Macintosh: Files for a complete discussion of fileSpec's and alias records.

Note that many MacOS Toolbox routines also support the use of Path Names, Directory Reference Numbers (usually called ioVRefNum), and Directory ID Numbers, using exactly the same rules of interaction discussed above.