Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 9 - Desktop Manager / Desktop Manager Reference

Routines / Adding to the Desktop Database

PBDTSetComment

To add a user comment for a file or a directory to the desktop database, use the PBDTSetComment function.

FUNCTION PBDTSetComment (paramBlock: DTPBPtr; 
                         async: Boolean): OSErr;

paramBlock

A pointer to a desktop parameter block.

async

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

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
\xAE	ioResult	OSErr	The result code of the function.
-->	ioNamePtr	StringPtr	A pointer to a file or directory name.
-->	ioDTRefNum	Integer	The desktop database reference number.
-->	ioDTBuffer	Ptr	A pointer to the comment text.
-->	ioDTReqCount	LongInt	The comment length.
-->	ioDirID	LongInt	The parent directory of the file or directory.

DESCRIPTION

The PBDTSetComment function establishes the user comment associated with a file or directory in the database specified in ioDTRefNum. You specify the object name through ioNamePtr and the parent directory ID in ioDirID. You put the comment as a plain text string in a buffer pointed to by ioDTBuffer, and you specify the length of the buffer (in bytes) in ioDTReqCount. The maximum length of a comment is 200 bytes; longer comments are truncated. Since the comment is a plain text string and not a Pascal string, the Desktop Manager relies on the value in ioDTReqCount for determining the length of the buffer.

If the specified object already has a comment in the database, the new comment replaces the old.

RESULT CODES

noErr	0	No error
ioErr	-36	I/O error
fnfErr	-43	File or directory doesn't exist
wPrErr	-44	Volume is locked through hardware
vLckdErr	-46	Volume is locked through software
rfNumErr	-51	Reference number invalid
extFSErr	-58	External file system--file system identifier is nonzero