Legacy Document

Inside Macintosh: Files /

Chapter 2 - File Manager / File Manager Reference

Low-Level Volume Access Routines / Manipulating the Default Volume

PBHSetVol

The PBHSetVol function sets both the default volume and the default directory.

FUNCTION PBHSetVol (paramBlock: WDPBPtr; async: Boolean): OSErr;

paramBlock

A pointer to a working directory parameter block.

async

A Boolean value that specifies asynchronous (TRUE) or synchronous (FALSE) execution.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The result code of the function.
-->	ioNamePtr	StringPtr	A pointer to a pathname.
-->	ioVRefNum	Integer	A volume reference number or a working directory reference number.
-->	ioWDDirID	LongInt	The directory ID.

DESCRIPTION

The PBHSetVol function sets the default volume and directory to the volume and directory specified by the ioNamePtr, ioVRefNum, and ioWDDirID fields.

The PBHSetVol function sets the default volume to the volume specified by the ioVRefNum field, which can contain either a volume reference number or a working directory reference number. If the ioNamePtr field specifies a full pathname, however, the default volume is set to the volume whose name is contained in that pathname. (A full pathname overrides the ioVRefNum field.)

The PBHSetVol function also sets the default directory. If the ioVRefNum field contains a volume reference number, then the default directory is set to the directory on that volume having the partial pathname specified by ioNamePtr in the directory specified by ioWDDirID. If the value of ioNamePtr is NIL, the default directory is simply the directory whose directory ID is contained in ioWDDirID.

If the ioVRefNum field contains a working directory reference number, then ioWDDirID is ignored and the default directory is set to the directory on that volume having the partial pathname specified by ioNamePtr in the directory specified by the working directory reference number. If the value of ioNamePtr is NIL, the default directory is simply the directory specified in ioVRefNum.

WARNING

Use of the PBHSetVol function is discouraged if your application may execute in system software versions prior to version 7.0. Because the specified directory might not itself be a working directory, PBHSetVol records the default volume and directory separately, using the volume reference number of the volume and the actual directory ID of the specified directory. Subsequent calls to GetVol (or PBGetVol) return only the volume reference number, which will cause that volume's root directory (rather than the default directory, as expected) to be accessed.

Note

Both the default volume and the default directory are used in calls made with no volume name, a volume reference number of 0, and a directory ID of 0.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro for PBSGetVol is _HSetVol.

RESULT CODES

noErr	0	No error
nsvErr	-35	No such volume
bdNamErr	-37	Bad volume name
fnfErr	-43	Directory not found
paramErr	-50	No default volume
afpAccessDenied	-5000	User does not have access to the directory