[futurebasic] Re: File Management Date: Thu, 19 Nov 1998 00:16:49 -0500 To: futurebasic@associate.com, allmedia@microtec.net From: "Eric M. Bennett" Subject: working directories, vrefs, and paramblocks explained [long] (was Re: [FB] C to FB) Message-Id: Sylvain wrote: >Thank you Eric, but i can't use the FOLDER statement coz >i'm in the mini-runtime. > >That would have been easy. Well, dang. Now we'll have to do it the hard way. But that's what you get for using the mini-runtime. :-) >Also, i know that 2 volumes can have the same name, but i have code >to deal with it. > >Things like '.ioNamePtr&' and 'GETVOLUMEINFO' is like >reading a japanese newspaper to me. In theory, the following function will do what you want (it's modified from some other code of mine, and I haven't tested my modifications). If you want to understand how it works (and a good programmer always understands how the code he's using works :-), then you'll have to read the rest of this rather long message. 'this function converts a path name to a 'working directory number ' 'Note the total lack of error checking. ' CLEAR LOCAL DIM 255 paramblock$,pbPtr&,oserr%,workingDirectoryNumber% LOCAL FN NameToID (fold$,myAppCreatorCode&) 'fold$ holds a full pathname pbPtr&=@paramblock$ 'Get address of this block of memory... pbPtr&.ioCompletion&=0 '...and access it as a record. pbPtr&.ioNamePtr&=@fold$ 'A pointer to the pathname of a directory. pbPtr&.ioVRefNum%=0 'A volume reference number. oserr%=FN GETCATINFO (pbPtr&) pbPtr&.ioWDProcID& = myAppCreatorCode& oserr%=FN OPENWD (pbPtr&) workingDirectoryNumber%=pbPtr&.ioVRefNum% 'you could call CLOSEWD when you're done using this directory, but 'as I explained previously, that can be dangerous END FN=workingDirectoryNumber% Now for the explanation of how this works. First let me start with an aside on where working directory numbers came from and why FB confuses them with volume reference numbers. On the original Macintosh, the filesystem was called MFS (Macintosh File System). It did *not* support directories at all. Every file on the disk was stored in the same directory. The system software created the illusion of directories, but in fact there weren't any (one consequence was that no files on the same volume could have the same name--even if they were in different "fake" directories). Then Apple introduced HFS, which allowed real directories. And there was a very big problem. All the existing software was used to identifying files by two pieces of data: the volume reference number and the file's name. But that information wasn't sufficient any more, because on an HFS volume two files can share the same name if they are in different directories. Uh-oh! So Apple hacked around the problem. Apple made it appear to old applications as if *every folder* on an HFS drive were a separate volume! It did that by assigning volume reference numbers to folders. Since these weren't *really* volume reference numbers (they refer to folders rather than disk partitions), Apple gave them a new name: working directory numbers. The File Manager keeps track of the difference between the two, but old applications are fooled into thinking they have received a volume reference number when in fact they have received a working directory number. At this point it is probably clear why the confusion exists. But this solution creates another problem. Volume reference numbers are short integers, and directory ID numbers are long integers. So the File Manager can't just assign a working directory number to every folder. It might run out of numbers. Instead, it assigns them on an as-needed basis. This is why you must "open" and "close" working directory numbers. When your application quits, modern versions of Mac OS will automatically close working directory numbers that your application used as long as no other programs have been using them. In summary, working directory numbers are a hack to allow old software programs to access HFS volumes. There is NO GOOD REASON why any application written since the introduction of HFS (a loooong time ago) should use them. Shame on whoever decided to use them heavily in FB's file routines. Now let's talk about what's going on in the above function. In theory you can get a working directory number with the OpenWD toolbox call (you'd have to convert your path name into a volume reference number and directory ID first): FUNCTION OpenWD (vrefnum: Integer; dirID: LongInt; procID: LongInt; VAR wdRefNum: Integer): OSerr; This is the Pascal toolbox info. procID& is (quoting IM:Files) "a working directory user identifier. You should use your application's signature as the user identifier." You can use this info to write an assembly language routine in FB that calls OpenWD. See page 239 of the handbook. In FB, the assembly language function would be called like this: oserr% = myOpenWD (vref%, dirID&, procID&, @workingDirID%) It happens that FutureBASIC does implement a function called OpenWD, but it does *NOT* implement it as described in IM:Files. (This sort of thing is a very big pain. I really hate FB's file management.) In FB's implementation of OpenWD, you need to pass a parameter block, which includes things like ".ioNamePtr&". If .ioNamePtr& really is Japanese to you, you'd better learn a new language (don't worry, it's not hard). :-) The toolbox has more friendly routines--such as the version of OpenWD I described above--that do not use parameter blocks, but FutureBasic implements approximately ZERO of them (another reason its file management drives me crazy). The File Manager calls that FB implements use parameter blocks. When you hit a wall with the built-in FutureBasic file routines, you can either learn parameter blocks or you can write assembly routines to call the friendlier file manager calls that FB doesn't support. The former is less of a pain, which is why I used FB's version of OpenWD in the sample function at the top of this message. A parameter block is just a chunk of memory... in FB, you end up treating it as if it were a record. The record definitions are available in Inside Mac, and FB gives partial definitions in the appropriate places (like the docs for GET VOLUME INFO in the reference manual). When you create a record in FB, FB creates constants that let you access the data in the record. If you're not familiar with records, you should probably read the appropriate section in the FB manuals before continuing. Here is a sample record definition from one of my own programs (with a lot of entries snipped): DIM RECORD myXVolumeParam DIM myQElemPtr& DIM myQType% DIM myioTrap% DIM myioCmdAddr& DIM myioCompletion& [snip] DIM END RECORD _myXVolumeParam Now, when you want to create a record of type myXVolumeParam, you do the following in FB: DIM myRecord.myXVolumeParam And then you read or assign values as follows: myRecord.myQElemPtr& = 0 otherVariable& = myRecord.myQElemPtr& To understand a parameter block, you need to understand how FutureBasic accesses records. In this example, let's say that FB knows that the data for myRecord starts at memory location 100. Since long integers are four bytes long, bytes 100-103 hold the value for myQElemPtr& and 104-105 hold the value for myQType% (two-byte short integer). FB associates the value zero with .myQElemPtr& and the value 4 with .myQType%. When you access myRecord.myQType%, it adds the value of .myQType% to the starting location of myRecord. That's 100+4, so FB knows that the data for myRecord.myQType% starts at memory location 104. If you access myRecord.myioTrap%, FB adds 100 to 6, and knows that the data for myioTrap% starts at memory location 106. Now, if you're familiar with how FutureBasic treats pointers, you know that you can treat any long integer variable as a pointer. Here's the important part: ***FB treats a DIMmed record name just like a pointer!*** And if that's true, then you might suspect that you can use a pointer as if it were a record. And, in fact, you can. Therefore, the following two pieces of code accomplish exactly the same thing: Local FN MyRoutineA DIM myRecord.myXVolumeParam myRecord.myQElemPtr& = 0 FN CallSomeOtherFunction (myRecord) END FN Local FN MyRoutineB DIM myRecord.myXVolumeParam,recordPtr& recordPtr& = @myRecord recordPtr&.myQElemPtr& = 0 FN CallSomeOtherFunction (recordPtr&) END FN This also means that you can access any block of memory as any particular type of record! If I have a pointer at memory location 2000, then writing myVariable% = myPointer&.myQType% will copy memory locations 2004 and 2005 into myVariable%. FB does not care whether or not there is a DIMmed record sitting at location 2000. If I have a pointer to a string (such as myPtr& = @myString$), then myVariable% = myPtr&.myQType% will copy two bytes from the fifth and sixth bytes of the string. (If the string is "Apple", the first byte is the string length byte with value five. The fifth and six bytes are the "le" from Apple.) When you are dealing with low-level file manager routines, the file manager usually expects you to pass it a pointer to a big record. The record has entries for things like volume reference numbers, directory ID numbers, pointers to file or directory names, file sizes, file types, etc. This is the mysterious "parameter block"--a block of memory with lots of parameters in it. In other words, it's a record. When dealing with this data in FutureBasic, you don't usually bother to DIM a record. You just clear out a large block of memory and then access it through its pointer *as if it were a DIMmed record*. FutureBasic already has most of the entries in the record (such as .ioNamePtr&) defined for you. So now let's look at the function I'm proposing to you: 'this function converts a path name to a 'working directory number ' 'Note the total lack of error checking. ' CLEAR LOCAL DIM 255 paramblock$,pbPtr&,oserr%,workingDirectoryNumber% LOCAL FN NameToID (fold$,myAppCreatorCode&) 'fold$ holds a full pathname pbPtr&=@paramblock$ 'Get address of this block of memory... pbPtr&.ioCompletion&=0 '...and access it as a record. pbPtr&.ioNamePtr&=@fold$ 'A pointer to the pathname of a directory. pbPtr&.ioVRefNum%=0 'A volume reference number. oserr%=FN GETCATINFO (pbPtr&) pbPtr&.ioWDProcID& = myAppCreatorCode& oserr%=FN OPENWD (pbPtr&) workingDirectoryNumber%=pbPtr&.ioVRefNum% 'you could call CLOSEWD when you're done using this directory, but 'as I explained previously, that can be dangerous END FN=workingDirectoryNumber% This code uses a 256 byte string called paramblock$ as the parameter block. Because the function includes the CLEAR LOCAL line, the parameter block will be zeroed. The parameter block contains a lot of entries whose values we won't be concerned with. However, passing random junk in these entries is a very bad thing, so using CLEAR LOCAL (or otherwise zeroing the parablock) is important. GETCATINFO is a file manager call that will look up the item whose pathname is given and fill in various other parts of the parameter block. If you're getting info on a file, for example, it will fill in pbPtr&.ioFlCrDat&, which is the creation date of the file. If you are getting information on a directory, it fills in the directory ID number (pbPtr&.ioDrDirID&) and volume reference number (pbPtr&.ioVRefNum%) for the directory. [An aside: GetCatInfo doesn't *require* a path name. You can feed it an empty path name along with other information that uniquely specifies a file and it will fill in the file's name--but not the complete path name--for you. You can get info on a directory with GetCatInfo too. It's a very useful function.] Next my function calls OPENWD, which takes the information in the paramblock, tries to find the directory it describes, and tries to create a working directory number for that directory. OPENWD overwrites the volume reference number stored in pbPtr&.ioVRefNum% and puts a working directory number there instead. Why does it do that? As I explained at the beginning of this message, working directory numbers were originally a hack designed to fool old programs into thinking that every folder on a drive was actually an independent volume. That meant that the File Manager returned working directory numbers in variables that were originally supposed to hold volume reference numbers. And since the applications thought they have a vref%, they would keep passing this value back to the file manager as a vref%. So whenever you see a variable that's supposed to hold a volume reference number, you can *probably* stick a working directory number in it instead and the File Manager will sort things out. And when dealing with functions that manipulate working directory numbers, the File Manager just uses the variable that's supposed to hold a volume reference number. This is--in a twisted sort of way--just being consistent with how working directory numbers are used elsewhere. Another important thing to know about parameter blocks is that the file manager uses various memory locations in them for more than one type of entry. For example, pbPtr&.ioVolIndex% and pbPtr&.ioFDirIndex% actually refer to the SAME memory location in the paramblock! The former entry only applies to volumes, so when you are dealing with a volume, the file manager puts a volume index number (ioVolIndex%) there. When you are dealing with files, the file manager doesn't need a volume index number. Instead, it reuses this space for a directory index number (ioFDirIndex%). If you are having mysterious problems with a paramblock and can't figure out why, there may be junk left over from a previous file manager call sitting in some of these multi-purpose places in the paramblock. Try re-clearing the entire paramblock and see if the problems go away. -- Eric Bennett (http://www.pobox.com/~ericb/), Cornell Biochemistry Department First law of computer trade journalism: "No technology exists until Microsoft invents it." -Nicholas Petreley

Message: < previous - next > : Reply : Subscribe : Cleanse
Home   : November 1998 : Group Archive : Group : All Groups

From: stewart harris <stharris@...>
Date: Thu, 19 Nov 1998 23:07:01 -0500
Date: Thu, 19 Nov 1998 00:16:49 -0500
To: futurebasic@..., allmedia@...
From: "Eric M. Bennett" <ericb@...>
Subject: working directories, vrefs, and paramblocks explained [long]
(was
 Re: [FB] C to FB)
Message-Id: <v04003000b2793da069a2@[128.253.200.125]>

Sylvain wrote:

snip
In theory, the following function will do what you want (it's modified
from
some other code of mine, and I haven't tested my modifications).  If you

want to understand how it works (and a good programmer always
understands
how the code he's using works :-), then you'll have to read the rest of
this rather long message.

'this function converts a path name to a
'working directory number
'
'Note the total lack of error checking.
'
CLEAR LOCAL
DIM 255 paramblock$,pbPtr&,oserr%,workingDirectoryNumber%
LOCAL FN NameToID (fold$,myAppCreatorCode&)                        
'fold$
holds a full pathname

  pbPtr&=@paramblock$           'Get address of this block of memory...
  pbPtr&.ioCompletion&=0        '...and access it as a record.
  pbPtr&.ioNamePtr&=@fold$      'A pointer to the pathname of a
directory.
  pbPtr&.ioVRefNum%=0           'A volume reference number.

  oserr%=FN GETCATINFO (pbPtr&)

  pbPtr&.ioWDProcID& = myAppCreatorCode&
  oserr%=FN OPENWD (pbPtr&)

  workingDirectoryNumber%=pbPtr&.ioVRefNum%

  'you could call CLOSEWD when you're done using this directory, but
  'as I explained previously, that can be dangerous

END FN=workingDirectoryNumber%

Now for the explanation of how this works.

snip

Thank yoou, Eric, for a very enlightning dissertation. I will spend a
lot of time studying it.

Stewart

FreeGroups.net: Group Email without advertisements.  Is your group here?