Futurebasic/Language/file spec

File Spec Records

CAUTION  (Jan. 2008)
Although the FSSpec structure represents the current FB standard for specifying files and directories, it is outdated since years and should not be considered for serious new FB projects. There are at least two modern alternatives to the FSSpec structure, namely the opaque FSRef structure explicated in:

“Migrating to FSRefs & long Unicode names from FSSpecs” (Apple Technical Note TN2078, May 2003) [1]

and the FileURL outlined in:

“The death of typeFSSpec: moving along to typeFileURL” (Apple Technical Note TN2022, June 2001) [2]

Revised: February 2002 (FB^3 Release 6)

Description

File spec records (FSSpecs) are the modern replacement for FB's time tested volume reference number/file name combinatons. You can create a file spec record as follows:

DIM fs AS FSSpec

A file spec record is defined in the headers as follows:

BEGIN RECORD FSSpec
  DIM vRefNum AS SHORT
  DIM parID AS LONG
  DIM name AS STR63
END RECORD

When the FSspec is used as a parameter in FILES$, or OPEN the information is passed to file handling calls as a single record, but you may extract information from the record as follows:

DIM fs AS FSSPEC
fileName$ = fs.name
parentID& = fs.parID
volRefNum = fs.vRefNum

OS x vs OS 9 volRefNum

OS X does not allow the use of the older vRefNum/fileName combination. In order to insure that your programs work correctly without modification, the FB runtime creates a list of parent IDs and volume reference numbers and substitutes the list element number
for the old volume reference number. Look at the difference between the calls below:

System 9
fileName$ = FILES$(_fOpen,_"PICT", "Open a picture", refNumVar%)
OPEN "I",#1,fileName$,,refNumVar%

OS X
fileName$ = FILES$(_fOpen,_"PICT", "Open a picture", fbElemNum%)
OPEN "I",#1,fileName$,,fbElemNum%

Your program won't require changes to move from the old to the new style calls, but will become OS X savvy without any additional coding.

Extracting Real Information From FB Indexed List Information

A utility function has been provided that extracts the true volume reference number and parent ID from FB's indexed table.

FN GetRealVolAndDir(vRefNum%,parentID&)

Pass the pseudo volume reference number to the routine in the vRefNum% parameter. On return, the true volume reference number is placed in the vRefNum% variable and the correct parent ID is place in the parentID& variable.

FSMAKEFSSPEC -> FBMakeFSSpec

A utility function provided by the runtime lets you build a file spec from individual components. This function has been designed to work with all versions of the system software. It's parameters are identical to those of the toolbox version of the call, but this particular function is smart enough to know when it id dealing with real parameters and when it has encountered the indexed element number from FB's substitute parameters.

DIM fs AS FSSpec
FN FBMakeFSSpec(inVol%,inDir&,name$, fs )

If the name$ parameter is a null string, FB returns information about the parent folder.

/* Not Supported by FBtoC */

Notes

You will not be able to use many of the file utility functions (like FN GetRealVolAndDir) unless you include the proper header file as follows:

INCLUDE "Util_Files.incl"

The function FBMakeFSSpec is unsupported in FBtoC.