AccessPointCommit()

void AccessPointCommit();

This routine commits any access point data changes to permanent storage. The AccPnt library normally calls this routine when the device shuts down; applications thus need not call it. If you're trying to track down a bug which is likely to cause the system to crash before the changes can be committed, you may find this routine useful.

Include: accpnt.goh

AccessPointCompareStandardProperty()

void AccessPointCompareStandardProperty(
        AccessPointStandardProperty 					prop,
        char 					*str);

This routine compares the passed string to the name of the passed property.

Include: accpnt.goh

AccessPointCreateEntry()

word AccessPointCreateEntry(
        word 		loc,
        AccessPointType 		apt);

This routine creates a new access point.

After calling this routine, you will probably want to use the AccessPointSet...Property() routines to provide some information about the new access point.

Pass:

loc

The access point before which to insert the new access point. Pass zero to append the new access point to the end of the list.

apt

The AccessPointType of the new access point. APT_INTERNET for an ISP, APT_TERMINAL for a dialup, etc.

Return: ID number of the new access point.

Include: accpnt.goh

See Also: AccessPointSetStringProperty(), AccessPointSetIntegerProperty().

AccessPointDestroyEntry()

Boolean AccessPointDestroyEntry(
        word id);

This routine deletes an access point's information. If it returns non-zero, there was an error. (Perhaps the access point was locked or did not exist.)

Include: accpnt.goh

AccessPointDestroyProperty()

Boolean AccessPointDestroyProperty(
        word id, 
        char *prop);

This routine destroys one of an access point's properties.

Pass:

id

The access point's ID number.

prop

Either an AccessPointStandardProperty value or a pointer to a buffer containing the property's name.

Return: Zero if there was no error, true if there was (no such access point, no such property, access point locked).

Include: accpnt.goh

See Also: AccessPointSetStringProperty(), AccessPointSetIntegerProperty().

AccessPointGetEntries()

ChunkHandle AccessPointGetEntries(
        MemHandle 		mh,
        ChunkHandle 		chunk,
        AccessPointType 		apt);

This routine gets a chunk array of all the access point IDs corresponding to access points of a given AccessPointType . Each element of the arraay is word-sized.

Pass:

mh

The memory block in which the chunk array shall reside.

chunk

Either the ChunkHandle of a chunk array, or zero to request that the library allocate a chunk array.

apt

The AccessPointType we're interested in: APT_INTERNET, APT_TERMINAL, etc.

Return: The ChunkHandle of the chunk array.

Include: accpnt.goh

AccessPointGetIntegerProperty()

Boolean AccessPointGetIntegerProperty(
        word 	id,
        char 	*prop,
        int 	*val);

This routine retrieves the value of one of an access point's property, representing the value as an integer.

Pass:

id

The access point's ID number.

prop

Either an AccessPointStandardProperty value or a pointer to a buffer containing the property's name.

val

Pointer to an integer; the routine will fill in this integer with the value of the property.

Return: Zero if there was no error, true if there was (no such access point, no such property).

Include: accpnt.goh

See Also: AccessPointGetStringPropertyBuffer(), AccessPointGetStringPropertyBlock().

AccessPointGetStringPropertyBlock()

BooleanAccessPointGetStringPropertyBlock(
        word 		id,
        char 		*prop,
        MemHandle 		*data,
        int 		*datalen);

This routine retrieves the value of one of an access point's property, returning the value as a string in a block of memory.

Pass:

id

The access point's ID number.

prop

Either an AccessPointStandardProperty value or a pointer to a buffer containing the property's name.

data

MemHandle of block to fill with value (pass zero to request that the block be allocated).

dataLen

Pointer to integer; the routine will fill in this integer with the length of the value string, excluding the trailing NULL.

Return: Zero if there was no error, true if there was (no such access point, no such property).

Include: accpnt.goh

See Also: AccessPointGetStringPropertyBuffer(), AccessPointGetIntegerProperty().

AccessPointGetStringPropertyBuffer()

Boolean AccessPointGetStringPropertyBuffer(
        word 	id,
        char 	*prop,
        char 	*buf,
        int 	*datalen);

This routine retrieves the value of one of an access point's property, returning the value as a string in a buffer of memory.

Pass:

id

The access point's ID number.

prop

Either an AccessPointStandardProperty value or a pointer to a buffer containing the property's name.

buf

Pointer to buffer to fill with value.

dataLen

Pointer to integer; pass the size of buf. The routine will fill in this integer with the length of the value string.

Return: Zero if there was no error, true if there was (no such access point, no such property).

Include: accpnt.goh

See Also: AccessPointGetStringPropertyBlock(), AccessPointGetIntegerProperty().

AccessPointGetType()

AccessPointType AccessPointCommit(
        word id);

This routine returns the type of an access point: APT_INTERNET, APT_TELNET, etc.

Include: accpnt.goh

AccessPointInUse()

Boolean   AccessPointInUse (word id);

If the access point with the ID id is being used by a connection, then this routine returns TRUE (non-zero); otherwise, it returns FALSE (zero).

Include: accpnt.goh

AccessPointIsEntryValid()

Boolean AccessPointIsEntryValid(
        word id);

This routine returns zero if the passed access point does not exist; it returns non-zero if it does exist.

Include: accpnt.goh

AccessPointLock()

void AccessPointLock(
        word id);

This routine locks an access point, preventing changes to it.

Include: accpnt.goh

See Also: AccessPointUnlock().

AccessPointSetIntegerProperty()

Boolean AccessPointSetIntegerProperty(
        word 	id,
        char+ 	*prop,
        int 	val);

This routine sets the value of one of an access point's properties to an integer.

Pass:

id

The access point's ID number.

prop

Either an AccessPointStandardProperty value or a pointer to a buffer containing the property's name.

val

The new value for the property.

Return: Zero if there was no error, true if there was (no such access point, access point locked).

Include: accpnt.goh

See Also: AccessPointSetStringProperty().

AccessPointSetStringProperty()

Boolean AccessPointSetStringProperty(
        word id,
        char *prop,
        char *val);

This routine sets the value of one of an access point's properties to a string.

Pass:

id

The access point's ID number.

prop

Either an AccessPointStandardProperty value or a pointer to a buffer containing the property's name.

val

The new value for the property.

Return: Zero if there was no error, true if there was (no such access point, access point locked).

Include: accpnt.goh

See Also: AccessPointSetIntegerProperty().

AccessPointUnlock()

void AccessPointUnlock(
        word id);

This routine unlocks an access point that was previously locked.

Include: accpnt.goh

See Also: AccessPointLock().

ArrayQuickSort()

void	ArrayQuickSort(
        void	*array,	/* Pointer to start of array */
        word	count,	/* Number of elements in array */
        word	elementSize,	/* Size of each element (in bytes) */
        word	valueForCallback, 		/* Passed to callback routine */
        QuickSortParameters *parameters);

This routine sorts an array of uniform-sized elements. It uses a modified QuickSort algorithm, using an insertion sort for subarrays below a certain size. The routine calls a callback routine to actually compare elements.

ArrayQuickSort() is passed five arguments: A pointer to the first element of the array, the number of elements in the array, the size of each element in bytes, a word of data (which is passed to all callback routines), and a pointer to a QuickSortParameters structure.

Before ArrayQuickSort() examines or changes any element, it calls a locking routine specified by the QuickSortParameters structure. This routine locks the element, if necessary, and takes any necessary prepatory steps. Similarly, after ArrayQuickSort() is finished with a routine, it calls an unlocking routine in the QuickSortParameters . Each of these routines is passed a pointer to the element and the word of callback data which was passed to ArrayQuickSort() .

The sort routine does not compare elements. Rather, it calls a comparison callback routine specified by the QuickSortParameters . This callback routine should be declared _pascal. Whenever ArrayQuickSort() needs to compare two elements, it calls the callback routine, passing the addresses of the elements and the valueForCallback word which was passed to ChunkArraySort() . The callback routine's return value determines which element will come first in the sorted array:

• If element el1 ought to come before el2 in the sorted array, the callback routine should return a negative integer.
• If element el1 ought to come after el2 in the sorted array, the callback routine should return a positive integer.
• If it doesn't matter whether el1 comes before or after el2 in the array, the callback routine should return zero.

Include: chunkarr.h

Tips and Tricks: You may need to sort an array based on different criteria at different times. The simplest way to do this is to write one general-purpose callback routine and have the valueForCallback word determine how the sort is done. For example, the same callback routine could sort the array in ascending or descending order, depending on the valueForCallback .

Be Sure To: Lock the array on the global heap (unless it is in fixed memory).

Warnings: Do not have the callback routine do anything which might invalidate pointers to the array. For example, if the array is in a chunk, do not resize the chunks or allocate other chunks in the same LMem heap.

See Also: QuickSortParameters, ChunkArraySort().

BlockFromTransferBlockID

VMBlockHandle BlockFromTransferBlockID(id);
        TransferBlockID	 	id;

This macro extracts the VMBlockHandle from a TransferBlockID .

BlockIDFromFileAndBlock

TransferBlockID BlockIDFromFileAndBlock(file, block);
        VMFileHandle 		file;
        VMBlockHandle 		block;

This macro creates the dword type TransferBlockID from a VMFileHandle and a VMBlockHandle.

bsearch()

extern void *_pascal bsearch(
        const void 		*key, 
        const void 		*array,
        word 		count, 
        word 		elementSize,
        PCB(int, compare, (const void *, const void *)));

This is a standard binary search routine. The callback routine must be declared _pascal.

calloc()

void *	calloc(
        word		n,			/* number of structures to allocate */
        size_t		size);			/* size of each structure in bytes */

The malloc() family of routines is provided for Standard C compatibility. If a geode needs a small amount of fixed memory, it can call one of the routines. The kernel will allocate a fixed block to satisfy the geode's malloc() requests; it will allocate memory from this block. When the block is filled, it will allocate another fixed malloc-block. When all the memory in the block is freed, the memory manager will automatically free the block.

When a geode calls calloc() , it will be allocated a contiguous section of memory large enough for the specified number of structures of the specified size. The memory will be allocated out of its malloc-block, and the address of the start of the memory will be returned. The memory will be zero-initialized. If the request cannot be satisfied, calloc() will return a null pointer. The memory is guaranteed not to be moved until it is freed (with free() ) or resized (with realloc() ). When GEOS shuts down, all fixed blocks are freed, and any memory allocated with calloc() is lost.

Tips and Tricks: You can allocate memory in another geode's malloc-block by calling GeoMalloc() . However, that block will be freed when the other geode exits.

Be Sure To: Request a size small enough to fit in a malloc-block; that is, the size of the structure times the number of structures requested must be somewhat smaller than 64K.

Warnings: All memory allocated with calloc() is freed when GEOS shuts down.

See Also: malloc(), free(), GeoMalloc(), realloc().

CCB()

#define CCB(return_type, pointer_name, args) \
        return_type _cdecl (*pointer_name) args

This macro is useful for declaring pointers to functions that use the C calling conventions. For example, to declare a pointer to a function which is passed two strings and returns an integer, one could write

CCB(int, func_ptr, (const char *, const char *));

which would be expanded to

int _cdecl (*func_ptr) (const char *, const char *);

Different compilers have different syntax for the _cdecl keyword. Using this macro makes your callback compiler-independent.

See Also: PCB().

CellDeref()

void *	CellDeref(
        optr		CellRef);

This routine translates an optr to a cell into the cell's address. The routine is simply a synonym for LMemDeref() .

Include: cell.h

CellDirty()

void	CellDirty(
        void *		ptr);		/* pointer to anywhere in locked cell */

This routine marks a cell as "dirty"; i.e., the cell will have to be copied from memory back to the disk.

Include: cell.h

Tips and Tricks: All the cells in an item block are marked dirty at once; thus, you can call this routine just once for several cells in the same item block. Only the segment portion of the pointer is significant; thus, you can pass a pointer to anywhere in the cell. This is useful if you have incremented the pointer to the cell.

CellGetDBItem()

DBGroupAndItem 	CellGetDBItem(
        CellFunctionParameters *			cfp,
        word		row,			/* Get handles of cell in this row */
        byte		column);			/*...and this column */

All cells are stored as ungrouped DB items. If you wish to manipulate the cells with standard DB routines, you will need to know their handles. The routine is passed the address of the CellFunctionParameters and the row and column indices of the desired cell. It returns the DBGroupAndItem value for the specified cell. If there is no cell at the specified coordinates, it returns a null DBGroupAndItem . The routine does not lock the cell or change it in any way.

Include: cell.h

See Also: DBGroupAndItem.

CellGetExtent()

void	CellGetExtent(
        CellFunctionParameters *cfp,
        RangeEnumParams 		*rep); /* write boundaries in REP_bounds field */

This routine returns the boundaries of the utilized portion of the cell file. The routine is passed the address of the cell file's CellFunctionParameters structure.) It writes the results into the REP_bounds field of the passed RangeEnumParams structure. The index of the first row to contain cells is written into REP_bounds.R_top ; the index of the last occupied row is written to REP_bounds.R_bottom ; the index of the first occupied column is written to REP_bounds.R_left ; and the index of the last occupied row is written to REP_bounds.R_right . If the cell file contains no cells, all four fields will be set to -1..

Include: cell.h

CellLock()

void *	CellLock(
        CellFunctionParameters*			cfp,
        word			row,			/* Lock cell in this row... */
        word			column);			/* ... and this column */

This routine is passed the address of the CellFunctionParameters of a cell file, and the row and column indices of a cell. It locks the cell and returns a pointer to it.

Include: cell.h

See Also: CellLockGetRef().

CellLockGetRef()

void *	CellLockGetRef(
        CellFunctionParameters*			cfp,
        word			row,			/* Lock cell in this row... */
        word			column,			/* ... and this column */
        optr *			ref);			/* Write handles here */

This routine is passed the address of the CellFunctionParameters of a cell file, and the row and column indices of a cell. It locks the cell and returns a pointer to it. It also writes the locked cell's item-block and chunk handles to the optr. If the cell moves (e.g. because another cell is allocated), you can translate the optr structure into a pointer by passing it to CellDeref() .

Include: cell.h

Warnings: The optr becomes invalid when the cell is unlocked.

See Also: CellGetDBItem()., CellLock().

CellReplace()

void	CellReplace{
        CellFunctionParameters *			cfp,
        word		row,		/* Insert/replace cell at this row... */
        word		column,			/* ... and this column */
        const void *		cellData,			/* Copy this data into the new cell */
        word		size);			/* Size of new cell (in bytes) */

This routine is used for creating, deleting, and replacing cells in a cell file. To create or replace a cell, set cellData to point to the data to copy into the new cell, and set size to the length of the cell in bytes, and row and column the cell's coordinates. (As usual, cfp is a pointer to the cell file's CellFunctionParameters structure.) Any pre-existing cell at the specified coordinates will automatically be freed, and a new cell will be created.

To delete a cell, pass a size of zero. If there is a cell at the specified coordinates, it will be freed. (The cellData argument is ignored.)

Include: cell.h

Warnings: If a cell is allocated or replaced, pointers to all ungrouped items (including cells) in that VM file may be invalidated. The CellFunctionParameters structure must not move during the call; for this reason, it may not be in an ungrouped DB item. Never replace or free a locked cell; if you do, the cell's item block will not have its lock count decremented, which will prevent the block from being unlocked.

CellUnlock()

void	CellUnlock(
        void *	ptr); /* pointer to anywhere in locked cell */

This routine unlocks the cell pointed to by ptr . Note that a cell may be locked several times. When all locks on all cells in an item-block have been released, the block can be swapped back to the disk.

Include: cell.h

Tips and Tricks: The DB manager does not keep track of locks on individual items; instead, it keeps a count of the total number of locks on all the items in an item-block. For this reason, only the segment address of the cell is significant; thus, you can pass a pointer to somewhere within (or immediately after) a cell to unlock it. This is useful if you have incremented the pointer to the cell.

Be Sure To: If you change the cell, dirty it (with CellDirty() ) before you unlock it.

CFatalError()

void	CFatalError(
        word	code)

This routine generates a fatal error. It stores an error code passed for use by the debugger.

ChunkArrayAppend()

void *	ChunkArrayAppend(
        optr	array,				/* optr to chunk array */
        word	elementSize)				/* Size of new element (ignored if 
						 * elements are uniform-sized) */

This routine adds a new element to the end of a chunk array. It automatically expands the chunk to make room for the element and updates the ChunkArrayHeader . It returns a pointer to the new element.

One of the arguments is the size of the new element. This argument is significant if the array contains variable-sized elements. If the elements are uniform-sized, this argument is ignored. The array is specified with an optr.

Include: chunkarr.h

Be Sure To: Lock the block on the global heap (if it is not fixed).

Warnings: This routine resizes the chunk, which means it can cause heap compaction or resizing. Therefore, all existing pointers to within the LMem heap are invalidated.

See Also: ChunkArrayInsertAt(), ChunkArrayDelete().

ChunkArrayAppendHandles()

void *	ChunkArrayAppendHandles(
        MemHandle		mh,				/* Handle of LMem heap's block */
        ChunkHandle		ch,				/* Handle of chunk array */
        word		size)				/* Size of new element (ignored if 
							 * elements are uniform-sized) */

This routine is exactly like ChunkArrayAppend() , except that the chunk array is specified by its global and local handles instead of by an optr.

Include: chunkarr.h

Be Sure To: Lock the block on the global heap (if it is not fixed).

Warnings: This routine resizes the chunk, which means it can cause heap compaction or resizing. Therefore, all existing pointers to within the LMem heap are invalidated.

See Also: ChunkArrayInsertAt(), ChunkArrayDelete().

ChunkArrayCreate()

ChunkHandle	 ChunkArrayCreate(
        MemHandle 	mh,	/* Handle of LMem heap's block */
        word	elementSize,	/* Size of each element (or zero if elements are
			 * variable-sized) */

        word	headerSize,	/* Amount of chunk to use for header (or zero for
		 	 * default size) */

        ObjChunkFlags ocf);

This routine sets up a chunk array in the specified LMem heap. The heap must have already been initialized normally. The routine allocates a chunk and sets up a chunk array in it. It returns the chunk's handle. If it cannot create the chunk array, it returns a null handle.

If the chunk array will have uniform-size elements, you must specify the element size when you create the chunk array. You will not be able to change this. If the array will have variable-sized elements, pass an element size of zero.

The chunk array always begins with a ChunkArrayHeader . You can specify the total header size; this is useful if you want to begin the chunk array with a special header containing some extra data. However, the header must be large enough to accommodate a ChunkArrayHeader , which will begin the chunk. If you define a header structure, make sure that its first element is a ChunkArrayHeader . Only the chunk array code should access the actual ChunkArrayHeader . If you pass a headerSize of zero, the default header size will be used (namely, sizeof(ChunkArrayHeader) ). If you pass a non-zero headerSize , any space between the ChunkArrayHeader and the heap will be zero-initialized.

To free a chunk array, call LMemFree() as you would for any chunk.

Include: chunkarr.h

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

Warnings: Results are unpredictable if you pass a non-zero headerSize argument which is smaller than sizeof(ChunkArrayHeader) . Since the routine allocates a chunk, it can cause heap compaction or resizing; all pointers to within the block are invalidated.

ChunkArrayCreateAt()

ChunkHandle 	ChunkArrayCreateAt(
        optr	array,	/* Create chunk array in this chunk */
        word	elementSize,	/* Size of each element (or zero if elements are
			 * variable-sized) */

        word	headerSize,	/* Amount of chunk to use for header (or zero for
			 * default size) */

        ObjChunkFlags ocf);

This routine is exactly like ChunkArrayCreate() , except that you specify the chunk which will be made into a chunk array. The chunk is specified with an optr. Note that any data already existing in the chunk will be overwritten.

Warnings: The chunk may be resized, which invalidates all pointers to within the LMem heap.

Include: chunkarr.h

ChunkArrayCreateAtHandles()

ChunkHandle 	ChunkArrayCreateAtHandles(
        MemHandle 		mh,
        ChunkHandle 		ch,
        word		elementSize,
        word		headerSize,
        ObjChunkFlags		ocf);

This routine is exactly like ChunkArrayCreate() , except that the chunk is specified with its global and chunk handles instead of with an optr.

Tips and Tricks: If you pass a null chunk handle, a new chunk will be allocated.

Warnings: The chunk may be resized, which would invalidate all pointers to within the LMem heap.

Include: chunkarr.h

ChunkArrayDelete()

void	ChunkArrayDelete(
        optr	array,				/* optr to chunk array */
        void *	element);				/* Address of element to delete */

This routine deletes an element from a chunk array. It is passed the address of that element, as well as the optr of the array.

Since the chunk is being decreased in size, the routine is guaranteed not to cause heap compaction or resizing.

Include: chunkarr.h

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

Tips and Tricks: Only the chunk handle portion of the optr is significant; the memory block is determined from the pointer to the element.

Warnings: The addresses of all elements after the deleted one will change. No other addresses in the block will be affected. If the address passed is not the address of an element in the array, results are undefined.

See Also: ChunkArrayAppend(), ChunkArrayInsertAt(), ChunkArrayZero().

ChunkArrayDeleteHandle()

void	ChunkArrayDeleteHandle(
        ChunkHandle		ch,				/* Handle of chunk array */
        void *		el);				/* Address of element to delete */

This routine is exactly like ChunkArrayDelete() , except that the chunk array is specified with its chunk handle instead of with an optr. The global memory handle is not needed, as the memory block is implicit in the pointer to the element.

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

Include: chunkarr.h

ChunkArrayDeleteRange()

void	ChunkArrayDeleteRange(
        optr	array,		/* optr to chunk array */
        word	firstElement,		/* index of first element to delete */
        word	count);		/* # of elements to delete (-1 to delete to 
				 * end of array) */

This routine deletes several consecutive elements from a chunk array. The routine is passed the optr of the chunk array, the index of the first element to delete, and the number of elements to delete. The routine is guaranteed not to cause heap compaction or resizing; thus, pointers to other elements in the array will remain valid.

ChunkArrayElementResize()

void	ChunkArrayElementResize(
        optr	array,				/* optr to chunk array */
        word	element,				/* Index of element to resize */
        word	newSize);				/* New size of element, in bytes */

This routine resizes an element in a chunk array. The chunk array must have variable-sized elements. The routine is passed an optr to the chunk array (which must be locked on the global heap), as well as the index of the element to resize and the new size (in bytes). It does not return anything.

If the new size is larger than the old, null bytes will be added to the end of the element. If the new size is smaller than the old, bytes will be removed from the end to truncate the element to the new size.

Warnings: If the element is resized larger, the chunk array may move within the LMem heap, and the heap itself may move on the global heap; thus, all pointers to within the LMem heap will be invalidated.

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

Include: chunkarr.h

ChunkArrayElementResizeHandles()

void	ChunkArrayElementResizeHandles(
        Memhandle		mh,				/* Global handle of LMem heap */
        ChunkHandle		ch,				/* Chunk handle of chunk array */
        word		el,				/* Index of element to resize */
        word		ns);				/* New size of element, in bytes */

This routine is exactly like ChunkArrayElementResize() except that the chunk array is specified with its global and chunk handles, instead of with its optr.

Warnings: If the element is resized to larger than the old, the chunk array may move within the LMem heap, and the heap itself may move on the global heap; thus, all pointers to within the LMem heap will be invalidated.

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

Include: chunkarr.h

ChunkArrayElementToPtr()

void *  ChunkArrayElementToPtr(
        optr           array,                                  /* optr to chunk array */
        word           elementNumber,                                  /* Element to get address of */
        void *         elementSize);                                   /* Write element's size here */

This routine translates the index of an element into the element's address. The routine is passed an optr to the chunk array, the index of the element in question, and a pointer to a word-sized variable. It returns a pointer to the element. If the elements in the array are of variable size, it writes the size of the element to the variable pointed to by the elementSize pointer. If the elements are of uniform size, it does not do this.

If the array index is out of bounds, the routine returns a pointer to the last element in the array. The routine will also do this if you pass the constant CA_LAST_ELEMENT.

Include: chunkarr.h

Tips and Tricks: If you are not interested in the element's size, pass a null pointer as the third argument.

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

Warnings: The error-checking version fatal-errors if passed the index CA_NULL_ELEMENT (i.e. 0xffff, or -1).

ChunkArrayElementToPtrHandles()

void *  ChunkArrayElementToPtrHandles(
        Memhandle              mh,                                     /* Handle of LMem heap's block */
        ChunkHandle            chunk,                                  /* Handle of chunk array */
        word           elementNumber,                                  /* Element to get address of */
        void *         elementSize);                                   /* Write element's size here */

This routine is just like ChunkArrayElementToPtr() , except that the chunk array is specified with its global and chunk handles, instead of with an optr.

Include: chunkarr.h

Tips and Tricks: If you are not interested in the element's size, pass a null pointer as the fourth argument.

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

See Also: ChunkArrayPtrToElement().

Warnings: The error-checking version fatal-errors if passed the index CA_NULL_ELEMENT (i.e. 0xffff, or -1).

ChunkArrayEnum()

Boolean ChunkArrayEnum(
        optr           array,                  /* optr to chunk array */
        void *         enumData,                       /* This is passed to callback routine */
        Boolean _pascal (*callback) (void *element, void *enumData));
        /* callback called for each element; returns TRUE to stop */

This routine lets you apply a procedure to every element in a chunk array. The routine is passed an optr to the chunk array, a pointer (which is passed to the callback routine), and a pointer to a Boolean callback routine. The callback routine, in turn, is called once for each element in the array, and is passed two arguments: a pointer to an element and the pointer which was passed to ChunkArrayEnum() . If the callback routine ever returns true for an element, ChunkArrayEnum() will stop with that element and return true . If it enumerates every element without being aborted, it returns false.

The callback routine can call such routines as ChunkArrayAppend(), ChunkArrayInsertAt(), and ChunkArrayDelete() . ChunkArrayEnum() will see to it that every element is enumerated exactly once. The callback routine can even make a nested call to ChunkArrayEnum() ; the nested call will be completed for every element before the outer call goes to the next element. The callback routine should be declared _pascal.

You can get into trouble if more than one thread of execution is accessing a single ChunkArray and one or both of these threads is using one of the ChunkArrayEnum...() routines. The error-checking version of the kernel detects this situation and generates a CHUNK_ARRAY_ENUM_INSERT_OR_DELETE_RUN_BY_MULTIPLE_THREADS warning if it detects such. If your code is getting this warning, you should add some synchronization between threads. While one thread is enumerating through chunks in the chunk array, the other should do nothing to enumerate the same array, nor alter the array in any way.

Include: chunkarr.h

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

ChunkArrayEnumHandles()

Boolean ChunkArrayEnumHandles(
        MemHandle              mh,                     /* Handle of LMem heap's block */
        ChunkHandle            ch,                     /* Handle of chunk array */
        void *         enumData,                       /* Buffer used by callback routine */
        Boolean _pascal (*callback) (void *element, void *enumData));
        /* callback called for each element; returns TRUE to stop */

This routine is exactly like ChunkArrayEnum() , except that the chunk array is specified by its global and chunk handles (instead of with an optr).

You can get into trouble if more than one thread of execution is accessing a single ChunkArray and one or both of these threads is using one of the ChunkArrayEnum...() routines. The error-checking version of the kernel detects this situation and generates a CHUNK_ARRAY_ENUM_INSERT_OR_DELETE_RUN_BY_MULTIPLE_THREADS warning if it detects such. If your code is getting this warning, you should add some synchronization between threads. While one thread is enumerating through chunks in the chunk array, the other should do nothing to enumerate the same array, nor alter the array in any way.

Include: chunkarr.h

ChunkArrayEnumRange()

Boolean         ChunkArrayEnumRange(
        optr   array,  /* optr to chunk array */
        word   startElement,   /* Start enumeration with this element */
        word   count,  /* Process this many elements */
        void * enumData,       /* This is passed to the callback routine */
        Boolean _pascal (*callback)            /* Return TRUE to halt enumeration */
               (void *element, void *enumData));

This routine is exactly like ChunkArrayEnum() (described above), except that it acts on a limited portion of the array. It is passed two additional arguments: the index of the starting element, and the number of elements to process. It will begin the enumeration with the element specified (remember, the first element in a chunk array has an index of zero). If the count passed would take the enumeration past the end of the array, ChunkArrayEnumRange() will automatically stop with the last element. You can instruct ChunkArrayEnumRange() to process all elements by passing a count of CA_LAST_ELEMENT.

You can get into trouble if more than one thread of execution is accessing a single ChunkArray and one or both of these threads is using one of the ChunkArrayEnum...() routines. The error-checking version of the kernel detects this situation and generates a CHUNK_ARRAY_ENUM_INSERT_OR_DELETE_RUN_BY_MULTIPLE_THREADS warning if it detects such. If your code is getting this warning, you should add some synchronization between threads. While one thread is enumerating through chunks in the chunk array, the other should do nothing to enumerate the same array, nor alter the array in any way.

Include: chunkarr.h

Warnings: The start element must be within the bounds of the array.

See Also: ChunkArrayEnum().

ChunkArrayEnumRangeHandles()

Boolean         ChunkArrayEnumRangeHandles(
        MemHandle      mh,     /* Handle of LMem heap's block */
        ChunkHandle    ch,     /* Handle of chunk array */
        word   startElement,   /* Start enumeration with this element */
        word   count,  /* Process this many elements */
        void * enumData,       /* This is passed to the callback routine */
        Boolean _pascal (*callback)            /* Return TRUE to halt enumeration */
               (void *element, void *enumData));

This routine is exactly like ChunkArrayEnumRange() , except that the chunk array is specified by its global and chunk handles (instead of with an optr).

You can get into trouble if more than one thread of execution is accessing a single ChunkArray and one or both of these threads is using one of the ChunkArrayEnum...() routines. The error-checking version of the kernel detects this situation and generates a CHUNK_ARRAY_ENUM_INSERT_OR_DELETE_RUN_BY_MULTIPLE_THREADS warning if it detects such. If your code is getting this warning, you should add some synchronization between threads. While one thread is enumerating through chunks in the chunk array, the other should do nothing to enumerate the same array, nor alter the array in any way.

ChunkArrayGetCount()

word    ChunkArrayGetCount(
        optr   array);                         /* optr of chunk array */

This routine returns the number of elements in the specified chunk array.

Include: chunkarr.h

Tips and Tricks: It is usually faster to examine the CAH _count field of the ChunkArrayHeader . This field is the first word of the ChunkArrayHeader (and therefore of the chunk). It contains the number of elements in the chunk array.

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

See Also: ChunkArrayHeader.

ChunkArrayGetCountHandles()

word	ChunkArrayGetCountHandles(
        MemHandle		mh,				/* Handle of LMem heap's block */
        ChunkHandle		ch);				/* Handle of chunk array */

This routine is just like ChunkArrayGetCount() , except that the chunk array is specified by its global and local handles (instead of with an optr).

Include: chunkarr.h

ChunkArrayGetElement()

void	ChunkArrayGetElement(
        optr	array,					/* optr to chunk array */
        word	elementNumber,					/* Index of element to copy */
        void *	buffer);					/* Address to copy element to */

This routine copies an element in a chunk array into the passed buffer. It is your responsibility to make sure the buffer is large enough to hold the element.

Include: chunkarr.h

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed). Make sure the buffer is large enough to hold the element.

See Also: ChunkArrayPtrToElement(), ChunkArrayElementToPtr().

ChunkArrayGetElementHandles()

void	ChunkArrayGetElementHandles(
        Memhandle		mh,					/* Handle of LMem heap's block */
        ChunkHandle		array,					/* Handle of chunk array */
        word		elementNumber,					/* Index of element to copy */
        void *		buffer);					/* Address to copy element to */

This routine is just like ChunkArrayGetElement() , except that the chunk array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed). Make sure the buffer is large enough to hold the element.

See Also: ChunkArrayPtrToElement(), ChunkArrayElementToPtr().

ChunkArrayInsertAt()

void *	ChunkArrayInsertAt(
        optr		array,				/* Handle of chunk array */
        void *		insertPointer,				/* Address at which to insert
							 * element */

        word		elementSize);				/* Size of new element (ignored
							 * if elements are uniform-sized) */

This routine inserts a new element in a chunk array. You specify the location by passing a pointer to an element. A new element will be allocated at that location; thus, the element which was pointed to will be shifted, so it ends up immediately after the new element. The new element will be zero-initialized.

The routine is passed three arguments: the optr of the array, the address where the new element should be inserted, and the size of the new element. (If the array is of uniform-size elements, the size argument will be ignored.)

Include: chunkarr.h

Tips and Tricks: Only the chunk-handle portion of the optr is significant; the memory block is implicit in the pointer to the element.

Be Sure To: Lock the block on the global heap (if it is not fixed).

Warnings: If the address passed is not the address of an element already in the chunk array, results are undefined. The routine may cause heap compaction or resizing; all pointers within the block are invalidated.

See Also: ChunkArrayAppend(), ChunkArrayDelete().

ChunkArrayInsertAtHandle()

void *	ChunkArrayInsertAtHandle(
        ChunkHandle		chunk,				/* Handle of chunk array */
        void *		insertPointer,				/* Address at which to insert
							 * element */

        word		elementSize);				/* Size of new element (ignored
							 * if elements are uniform-sized) */

This routine is just like ChunkArrayInsertAt() , except that the chunk array is specified by its chunk handle. (The global block is implicit in the pointer passed.)

Include: chunkarr.h

ChunkArrayPtrToElement()

word	ChunkArrayPtrToElement(
        optr	array,						/* Handle of chunk array */
        void *	element);						/* Address of element */

This routine takes the address of an element in a chunk array, as well as an optr to the array. It returns the element's zero-based index.

Include: chunkarr.h

Tips and Tricks: Only the chunk-handle portion of the optr is significant; the memory block is implicit in the pointer to the element.

Be Sure To: Lock the block on the global heap (unless it is fixed).

Warnings: If the address passed is not the address of the beginning of an element, results are unpredictable.

See Also: ChunkArrayElementToPtr().

ChunkArrayPtrToElementHandle()

word 	ChunkArrayPtrToElementHandle(
        ChunkHandle		array,			/* chunk handle of chunk array */
        void *		element);			/* Pointer to element to delete */

This routine is exactly like ChunkArrayPtrToElement() , except that the chunk array is indicated by its chunk handle. (The global block is implicit in the pointer passed.)

ChunkArraySort()

void	ChunkArraySort(
        optr		array,					/* optr to chunk array */
        word		valueForCallback,					/* Passed to callback routine */
        sword _pascal (*callback)				(void *el1, 
				 void * el2, 
				 word valueForCallback))
	/* Sign of return value decides order of elements */

This is a general-purpose sort routine for chunk arrays. It does a modified Quicksort on the array, using an insertion sort for subarrays below a certain size.

The sort routine does not compare elements. Rather, it calls a comparison callback routine passed in the callback parameter. Whenever it needs to compare two elements, it calls the callback routine, passing the addresses of the elements and the valueForCallback word which was passed to ChunkArraySort() . The callback routine should be declared _pascal. The callback routine's return value determines which element will come first in the sorted array:

• If element el1 ought to come before el2 in the sorted array, the callback routine should return a negative integer.
• If element el1 ought to come after el2 in the sorted array, the callback routine should return a positive integer.
• If it doesn't matter whether el1 comes before or after el2 in the sorted array, the callback routine should return zero.

Include: chunkarr.h

Tips and Tricks: You may need to sort an array based on different criteria at different times. The simplest way to do this is to write one general-purpose callback routine and have the valueForCallback word determine how the sort is done. For example, the same callback routine could sort the array in ascending or descending order, depending on the valueForCallback .

Be Sure To: Lock the block on the global heap (unless it is fixed).

Warnings: Do not have the callback routine do anything which might invalidate pointers to the array (such as allocate a new chunk or element).

See Also: ArrayQuickSort().

ChunkArraySortHandles()

void	ChunkArraySortHandles(
        MemHandle		memHandle,					/* Handle of LMem heap's block */
        ChunkHandle		chunkHandle,					/* Handle chunk array */
        word		valueForCallback,					/* Passed to callback routine */
        sword _pascal(*callback)(void *el1, void * el2, word valueForCallback)
	/* Sign of return value decides order of elements */

This routine is exactly like ChunkArraySort() above, except that the chunk array is specified by its global and chunk handles (instead of by an optr).

Include: chunkarr.h

ChunkArrayZero()

void	ChunkArrayZero(
        optr	array);		/* optr to chunk array */

This routine destroys all the elements in an array. It does not affect the extra-space area between the ChunkArrayHeader and the elements. It is guaranteed not to cause heap compaction or resizing; thus, pointers to other chunks remain valid.

Include: chunkarr.h

Be Sure To: Lock the block on the global heap (unless it is fixed).

See Also: ChunkArrayDelete().

ChunkArrayZeroHandles()

void	ChunkArrayZeroHandles(
        MemHandle		mh		/* Global handle of LMem heap */
        ChunkHandle		ch);		/* Chunk handle of chunk array */

This routine is exactly like ChunkArrayZero() above, except that the chunk array is specified by its global and chunk handles (instead of by an optr).

Include: chunkarr.h

ClipboardAbortQuickTransfer()

void	ClipboardAbortQuickTransfer(void);

This routine cancels a quick-transfer operation in progress. It is typically used when an object involved in a quick-transfer is shutting down or when an error occurs in a quick-transfer. This routine is usually used only by the object or Process which initiated the quick-transfer.

Include: clipbrd.goh

ClipboardAddToNotificationList()

void	ClipboardAddToNotificationList(
        optr	notificationOD);

This routine registers the passed object or process for quick-transfer notification. This routine is typically called from within an object's MSG_META_INITIALIZE handler or within a Process object's MSG_GEN_PROCESS_OPEN_APPLICATION handler. Pass the optr of the object or the geode handle if the Process object should be registered.

Include: clipbrd.goh

See Also: ClipboardRemoveFromNotificationList().

ClipboardClearQuickTransferNotification()

void	ClipboardClearQuickTransferNotification(
        optr	notificationOD);

This routine removes an object or process from quick-transfer notification. It is typically used in the object's MSG_META_DETACH handler or in the Process object's MSG_GEN_PROCESS_CLOSE_APPLICATION to ensure that it is not notified after it has already detached.

Pass the optr of the object specified to receive notification in ClipboardStartQuickTransfer() (or the geode handle if a process).

Note that an object may also want to check if a quick-transfer is in progress when detaching and possibly abort it if there is one.

Include: clipbrd.goh

ClipboardDoneWithItem()

void	ClipboardDoneWithItem(
        TransferBlockID header);

This routine is called when an object or Process is done using a transfer item. It relinquishes exclusive access to the item's transfer VM file after the caller had previously called ClipboardQueryItem() .

Include: clipbrd.goh

ClipboardEndQuickTransfer()

void	ClipboardEndQuickTransfer(
        ClipboardQuickNotifyFlags 				flags);

This routine ends a quick-transfer operation by resetting the pointer image, clearing any quick-transfer region, clearing the quick-transfer item, and sending out any needed notification of the completed transfer.

Pass this routine a record of ClipboardQuickNotifyFlags . Pass the value CQNF_MOVE if the operation was completed and was a move; pass CQNF_COPY if the operation was completed and was a copy. If the operation could not be completed (e.g. incompatible data types), pass CQNF_NO_OPERATION or CQNF_ERROR.

The notification sent out by the UI will be in the form of the message MSG_META_CLIPBOARD_NOTIFY_QUICK_TRANSFER_CONCLUDED . This message notifies the originator of the transfer item of the type of operation; the originator can then respond if necessary.

Include: clipbrd.goh

ClipboardEnumItemFormats()

word	ClipboardEnumItemFormats(
        TransferBlockID 		header,
        word 		maxNumFormats,
        ClipboardFormatID *		buffer);

This routine returns a list of all the formats supported by the current transfer item. To see whether a particular format is supported, you can use ClipboardTestItemFormat() instead.

Pass this routine the following:

header

The transfer item header as returned by ClipboardQueryItem() .

maxNumFormats

The maximum number of formats that should be returned. You should set your return buffer (see below) large enough to support this size.

buffer

A pointer to a locked or fixed buffer into which the formats will be copied. Upon return, the buffer will contain the proper number of ClipboardFormatID structures, one for each format available. This buffer should be at least large enough to support the number of formats requested in maxNumFormats .

The word return value is the total number of formats returned. This number will be equal to or less than the number passed in maxNumFormats . The routine will also return the passed buffer filled with that number of ClipboardFormatID structures.

Include: clipbrd.goh

See Also: ClipboardTestItemFormat().

ClipboardGetClipboardFile()

VMFileHandle ClipboardGetClipboardFile(void);

This routine returns the VM file handle of the current default transfer VM file.

Include: clipbrd.goh

ClipboardGetItemInfo()

optr	ClipboardGetItemInfo(
        TransferBlockID header);

This routine returns the source identifier (CIH _sourceID ) of the current transfer item. Pass the transfer item's header returned by ClipboardQueryItem() .

Include: clipbrd.goh

ClipboardGetNormalItemInfo()

TransferBlockID ClipboardGetNormalItemInfo(void);

This routine returns information about the normal transfer item. It returns a TransferBlockID dword which contains the VM file handle of the transfer file and the VM block handle of the transfer item's header block.

To extract the file handle from the return value, use the macro FileFromTransferBlockID() . To extract the block handle, use the macro BlockFromTransferBlockID() .

Include: clipbrd.goh

ClipboardGetQuickItemInfo()

TransferBlockID ClipboardGetQuickItemInfo(void);

This routine returns information about the quick-transfer transfer item. It returns a TransferBlockID dword which contains the VM file handle of the transfer file and the VM block handle of the transfer item's header block.

To extract the file handle from the return value, use the macro FileFromTransferBlockID() . To extract the block handle, use the macro BlockFromTransferBlockID() .

Include: clipbrd.goh

ClipboardGetQuickTransferStatus()

Boolean	ClipboardGetQuickTransferStatus(void);

This routine returns true if a quick-transfer operation is in progress, false otherwise. It is often called when objects or Processes are shutting down in order to abort any quick-transfers originated by the caller.

Include: clipbrd.goh

ClipboardGetUndoItemInfo()

TransferBlockID ClipboardGetUndoItemInfo(void);

This routine returns information about the undo transfer item. It returns a TransferBlockID dword which contains the VM file handle of the transfer file and the VM block handle of the transfer item's header block.

To extract the file handle from the return value, use the macro FileFromTransferBlockID() . To extract the block handle, use the macro BlockFromTransferBlockID() .

Include: clipbrd.goh

ClipboardQueryItem()

void	ClipboardQueryItem(
        ClipboardItemFlags 			flags,
        ClipboardQueryArgs *			retValues);

This routine locks the transfer item for the caller's exclusive access and returns information about the current transfer item. You should call this routine when beginning any paste or clipboard query operation. For operations in which you will change the clipboard's contents, you should instead use the routine ClipboardRegisterItem() .

Pass the following values:

flags

A record of ClipboardItemFlags indicating the transfer item you want to query. Use CIF_QUICK to get information on the quick transfer item, and pass zero (or TIF_NORMAL) to get information on the normal transfer item.

retValues A pointer to an empty ClipboardQueryArgs structure into which return information about the transfer item will be passed. This structure is defined as follows:

typedef struct {
	word			CQA_numFormats;
	optr			CQA_owner;
	TransferBlockID			CQA_header;
} ClipboardQueryArgs;

The CQA_header field of ClipboardQueryArgs is used as a pass value to several other clipboard routines. It contains the VM file handle of the transfer VM file and the VM block handle of the transfer item's header block. The CQA_owner field is the optr of the object that originated the transfer item. The CQA_numFormats field specifies the total number of formats available for this transfer item. To see if a particular format is supported by the transfer item, call the routine ClipboardTestItemFormat() .

Be Sure To: You must call ClipboardDoneWithItem() when you are done accessing the transfer item. This routine relinquishes your exclusive access to the transfer VM file.

Include: clipbrd.goh

See Also: ClipboardRequestItemFormat(), ClipboardDoneWithItem().

ClipboardRegisterItem()

Boolean	ClipboardRegisterItem(
        TransferBlockID header,
        ClipboardItemFlags flags);

This routine completes a change to the transfer item. You should use this routine whenever copying or cutting something into the clipboard or whenever attaching something as the quick-transfer item.

This routine puts the item specified by header into the transfer VM file. It frees any transfer item that may already be in the file. Pass this routine the following:

header

Header information for the item, consisting of the transfer VM file handle and the VM block handle of the block containing the new transfer item. Create the TransferBlockID structure using the macro BlockIDFromFileAndBlock() .

flags

A record of ClipboardItemFlags indicating whether you're registering a clipboard item or a quick-transfer item. The flag CIF_QUICK indicates the item is a quick-transfer item; zero (or TIF_NORMAL) indicates the item is a normal clipboard item.

Include: clipbrd.goh

See Also: ClipboardRequestItemFormat().

ClipboardRemoveFromNotificationList()

Boolean	ClipboardRemoveFromNotificationList(
        optr	notificationOD);

This routine removes an object or Process from the clipboard's change notification list. It is typically called when the object or Process is being detached or destroyed. Pass it the same optr that was added to the notification list with ClipboardAddToNotificationList ().

This routine returns an error flag: The flag will be true if the object could not be found in the notification list, false if the object was successfully removed from the list.

Include: clipbrd.goh

See Also: ClipboardAddToNotificationList().

ClipboardRequestItemFormat()

void	ClipboardRequestItemFormat(
        ClipboardItemFormatID 			format,
        TransferBlockID 			header,
        ClipboardRequestArgs *			retValue);

This routine returns specific information about a particular transfer item. Because some of the passed information must be retrieved with ClipboardQueryItem() , you must call ClipboardQueryItem() before calling this routine.

Pass this routine the following:

format

The manufacturer ID and format type of the new transfer item being put into the transfer VM file. Create the ClipboardItemFormatID value with the macro FormatIDFromManufacturerAndType() .

header

Header information for the item, consisting of the transfer VM file handle and the VM block handle of the block containing the new transfer item. Create the TransferBlockID structure using the macro BlockIDFromFileAndBlock() using returned information from ClipboardQueryItem() .

retValue A pointer to an empty ClipboardRequestArgs structure that will be filled by the routine. This structure is defined as follows:

typedef struct {
	VMFileHandle		CRA_file;
	VMChain		CRA_data;
	word		CRA_extra1;
	word		CRA_extra2;
} ClipboardRequestArgs;

Upon return, the CRA_file field will contain the transfer VM file's VM file handle and the CRA_data field will contain the VM block handle of the transfer item's header block. If there is no transfer item, CRA_data will be zero.

Include: clipbrd.goh

See Also: ClipboardRegisterItem(), ClipboardQueryItem().

ClipboardSetQuickTransferFeedback()

void	ClipboardSetQuickTransferFeedback(
        ClipboardQuickTransferFeedback 						cursor,
        UIFunctionsActive 						buttonFlags);

This routine sets the image of the mouse pointer during a quick-transfer operation. Use this routine to provide visual feedback to the user during the quick-transfer. For example, an object that could not accept the quick-transfer item would set the "no operation" cursor while the mouse pointer was over its bounds.

Pass the two following values:

cursor

A value of ClipboardQuickTransferFeedback type indicating the type of cursor to set. The possible values are listed below.

buttonFlags

A record of UIFunctionsActive flags. These flags are defined in the Input Manager section and deal with user override of the move/copy behavior.

The cursor parameter contains a value of ClipboardQuickTransferFeedback . This is an enumerated type that defines the cursor to be set, and it has the following values:

CQTF_MOVE

This sets the cursor to the specific UI's move cursor.

CQTF_COPY

This sets the cursor to the specific UI's copy cursor.

CQTF_CLEAR

This clears the cursor and sets it to the specific UI's modal "no operation" cursor.

Include: clipbrd.goh

ClipboardStartQuickTransfer()

Boolean	ClipboardStartQuickTransfer(
        ClipboardQuickTransferFlags 							flags,
        ClipboardQuickTransferFeedback							initialCursor,
        word							mouseXPos,
        word							mouseYPos,
        ClipboardQuickTransferRegionInfo *							regionParams,
        optr							notificationOD);

This routine signals the beginning of a quick-transfer operation. Typically, an object or process will call this routine in its MSG_META_START_MOVE_COPY handler.

Pass it the following parameters:

flags

A record of ClipboardQuickTransferFlags indicating whether an addition graphic region will be attached to the cursor and whether the caller wants notification of transfer completion. The flags allowed are listed below, after the parameter list.

initialCursor

The initial cursor to use for visual feedback to the user. It is a value of ClipboardQuickTransferFeedback , either CQTF_MOVE or CQTF_COPY. If -1 is passed in this parameter, the initial cursor will be the default no-operation cursor (i.e. the transfer source may not also act as the transfer destination).

mouseXPos

This field is used only if CQTF_USE_REGION is passed in flags . It is the horizontal position of the mouse in screen coordinates.

mouseYPos

This field is used only if CQTF_USE_REGION is passed in flags . It is the vertical position of the mouse in screen coordinates.

regionParams

A pointer to a ClipboardQuickTransferRegionInfo structure defining the graphical region to be attached to the cursor during the transfer operation. This structure is only required if CQTF_USE_REGION is passed in flags . It is defined below.

notificationOD

The optr of the object to be notified upon transfer completion. The object specified will receive the notification messages MSG_META_CLIPBOARD_NOTIFY_QUICK_TRANSFER_CONCLUDED and MSG_..._FEEDBACK .

The allowed ClipboardQuickTransferFlags are listed below:

CQTF_COPY_ONLY

Source supports copying only (not cutting).

CQTF_USE_REGION

Source has passed the definition of a graphical region which will be attached to the tail of the quick-transfer cursor.

CQTF_NOTIFICATION

Source requires notification of completion of the transfer in order to cut original data or provide other feedback.

If a graphical region is to be attached to the quick-transfer cursor, you must pass a pointer to a ClipboardQuickTransferRegionInfo in the regionParams parameter. This structure is defined below.

typedef struct {
	word	CQTRI_paramAX;
	word	CQTRI_paramBX;
	word	CQTRI_paramCX;
	word	CQTRI_paramDX;
	Point	CQTRI_regionPos;
	dword	CQTRI_strategy;
	dword	CQTRI_region;
} ClipboardQuickTransferRegionInfo;

This structure is passed on the stack to the routine. The first four fields represent the region's definition parameters. CQTRI_regionPos is a Point structure indicating where (in screen coordinates) the region is to be located. CQTRI_strategy is a pointer to the region strategy routine. CQTRI_strategy should be a video driver strategy. To find out the strategy of the video driver associated with your window, send your object a MSG_VIS_VUP_QUERY with VUQ_VIDEO_DRIVER. Pass the handle thus gained to GeodeInfoDriver() , which will return the strategy.

This routine returns an error flag: If a quick-transfer is already in progress, the return will be true . If the quick-transfer is successfully begun, the error flag will be false .

Include: clipbrd.goh

ClipboardTestItemFormat()

Boolean	ClipboardTestItemFormat(
        TransferBlockID		header,
        ClipboardFormatID 		format);

This routine tests whether the given format is supported by the specified transfer item. It returns true if the format is supported, false if the format is not supported. Pass the following values:

header

A TransferBlockID specifying the VM file handle and VM block handle of the transfer item to be checked. This is returned by the routines ClipboardGetNormalItemInfo() , ClipboardGetQuickItemInfo() , ClipboardGetUndoItemInfo() , and ClipboardQueryItem() . Most often the proper routine to use is ClipboardQueryItem() .

format

A ClipboardFormatID specifying the type and manufacturer ID of the format to be checked. It is most appropriate to create this parameter from its individual parts using the macro FormatIDFromManufacturerAndType() .

Include: clipbrd.goh

ClipboardUnregisterItem()

void	ClipboardUnregisterItem(
        optr	owner);

This routine restores the transfer item to what it was before the last ClipboardRegisterItem() . Pass it the optr of the caller.

Only the object that last registered a transfer item is allowed to unregister it. If the transfer item is owned by a different object, or if there is no transfer item, nothing will be done. If the transfer item is owned by the caller, the transfer item will be unregistered and the clipboard will be restored to its previous state.

Include: clipbrd.goh

ConstructOptr()

optr	ConstructOptr(
        Handle 		han,
        ChunkHandle 		ch);

This macro constructs an optr type from the given handle (typically a MemHandle) and chunk handle.

See Also: HandleToOptr(), OptrToHandle(), OptrToChunk().

ContactCompareNumbers()

Boolean 	ContactCompareNumbers(
        TCHAR *number1, 
        TCHAR *number2);

This function compares two phone number strings for equivalence. It ignores extraneous characters such as spaces. It returns zero if they are the same number, otherwise it returns a non-zero value.

Include: contdb.goh

ContactCreateRecordFromTemplate()

MemHandle	 ContactCreateRecordFromTemplate( void );

This function creates a new Contact record in the Contacts database. It returns the handle of the new record. Make any desired changes to the record and then call ContactSaveRecord() to save the record or FoamDBDiscardRecord() to discard changes.

Include: contdb.goh

See Also: ContactSaveRecord(), ContactSetTemplateRecord().

ContactEnsureEmptyField()

FieldID	ContactEnsureEmptyField( 
        MemHandle 		record,
        optr 		fieldName,
        ContdbFieldType		fieldType);

This function creates a field in a record, and clears the dat from the existing field of that name if one already existed. This function takes the following arguemnts:

record

The handle of the record, as returned by FoamDBGetRecordFromID() or ContactCreateRecordFromTemplate() .

fieldName

optr of a chunk containing the null-terminated name string, or NullOptr to use the default name for the passed ContdbFieldType .

fieldType

The type of field to find. One of CFT_NAME, CFT_COMPANY CFT_TITLE, CFT_ADDRESS, CFT_PHONE, CFT_FAX, CFT_EMAIL, CFT_DTMF, CFT_NOTES.

Include: contdb.goh

See Also: ContactEnsureField(), FoamDBSetFieldData().

ContactEnsureField()

FieldID	ContactEnsureField( 
        MemHandle 		record,
        optr 		fieldName,
        ContdbFieldType		fieldType);

This functionreturns the FieldID of a field within a record, or creates the field if it doesn't find it. This function takes the following arguemnts:

record

The handle of the record, as returned by FoamDBGetRecordFromID() or ContactCreateRecordFromTemplate() .

fieldName

optr of a chunk containing the null-terminated name string, or NullOptr to use the default name for the passed ContdbFieldType .

fieldType

The type of field to find. One of CFT_NAME, CFT_COMPANY CFT_TITLE, CFT_ADDRESS, CFT_PHONE, CFT_FAX, CFT_EMAIL, CFT_DTMF, CFT_NOTES.

Include: contdb.goh

See Also: ContactEnsureEmptyField(), FoamDBSetFieldData().

ContactExportDBToTextFile()

ContactExportStatus 	ContactExportDBToTextFile(
        hptr 	fileExport,
        dword 	startElement,
        dword 	numOfRecords);

This function exports the Contact database's data as an ASCII file. On success, the function returns CES_NO_ERROR, otherwise it returns CES_FILE_ERROR. This function takes the following arguments:

fileExport

The handle of the opened file to hold the exported text.

startElement

The RecordID of the first record to export.

numOfRecords

This argument determines the range of records to export. All records with RecordID at least startElement but less than startElement+numOfRecords will be exported.

To export all the records, pass a startElement of zero and a numOfRecords of CONTACT_EXPORT_ALL_RECORDS.

Include: contdb.goh

See Also: ContactExportDBToTextFile().

ContactGetDBHandle()

VMFileHandle 	ContactGetDBHandle( void );

This function returns the handle of the Contact database, the database that contains all of the "address book" data used by the contdb library. This handle is necessary for various operations with the library. When you're done with the handle, remember to call ContactReleaseDBHandle() .

Include: contdb.goh

See Also: ContactGetDBHandleNoBlock(), ContactReleaseDBHandle().

ContactGetDBHandleNoBlock()

VMFileHandle 	ContactGetDBHandleNoBlock( void );

This function behaves in the same manner as ContactGetDBHandle() , except that if it cannot get the handle, it returns zero instead of waiting until the handleis available.When you're done with the handle, remember to call ContactReleaseDBHandle() .

Include: contdb.goh

See Also: ContactGetDBHandle().

ContactGetName()

Boolean	ContactGetName( 
        MemHandle 		record,
        TCHAR 		*dest);

This function gets the name associated with the record, filling in the dest buffer. If there was no name in the record, this function returns non-zero; otherwise, it returns zero.

Include: contdb.goh

See Also: ContactGetDBHandle().

ContactGetTruncatedName()

Boolean	ContactGetTrunactedName( 
        MemHandle 		record,
        TCHAR 		*dest,
        word		destSize);				/* Size of dest buffer */

This function gets the name associated with the record, filling in the dest buffer. It will truncate the name, as necessary to make it fit inside the buffer. Remember to leave space for the null terminator when determining how big a buffer you'll need. If there was no name in the record, this function returns non-zero; otherwise, it returns zero.

Include: contdb.goh

See Also: ContactGetDBHandle().

ContactGetUserDataID()

RecordID	ContactGetUserDataID( void );

This functionreturns the RecordID of the special Contacts database record containing the user's own contact data.

Include: contdb.goh

See Also: FoamDBGetRecordFromID().

ContactImportDBFromTextFile()

void 	ContactImportDBFromTextFile(
        hptr 		fileImport);					/* file's handle */

This function imports contact database information from an ASCII text file. This file's format is described below. The function will compare imported records to those already in the Contacts database. Any identical records will be merged.

A short sample file is shown below.

[RECORD]
[FIELD]
Name
[FIELD-NAME]
[FIELD-DATA]
Hudson W.
[FIELD-END]
[FIELD]

Company
[FIELD-NAME]
[FIELD-DATA]
Space Marines
[FIELD-END]
[FIELD]
Title
[FIELD-NAME]
[FIELD-DATA]
Private
[FIELD-END]
[RECORD-END]

[RECORD]
[FIELD]
Name
[FIELD-NAME]
[FIELD-DATA]

Adams, John Quincy
[FIELD-END]
[FIELD]
Tel
[FIELD-NAME]
[FIELD-DATA]
1 617 438 1776
[FIELD-END]
[FIELD]
[FIELD-NAME]
Company
[FIELD-DATA]
[FIELD-END]
USA Government
[FIELD]
Notes
[FIELD-NAME]
Note(Birthday)
[FIELD-DATA]
July 11, 1767
Gift ideas: flowers
[FIELD-END]
[RECORD-END]

The ASCII file follows these rules:

• The page is a DOS text file, using the "Latin 1" code page (number 819).
• Each line of text may ends with a newline; the newline may be preceded by an optional carriage return.
• The data corresponding to each record is delimited by a line reading [RECORD] at the start and another line reading [RECORD-END] at the end. Any text that appears outside of these delimiters is lost.
• Each record consists of one or more fields. Each field is delimited by a line reading [FIELD] and a line reading [FIELD-END].
• For each field, the first line after the [FIELD] line will consist of one of the following strings, specifying the field's type:
  Name, Company, Title, Address, Tel, Fax, Mail, DTMF, Note.
• There may be a line of text between the [FIELD-NAME] and [FIELD-DATA] lines. If there is no such line of text, then the field's name is the default name for its data type. If there is such a line of text, then you may form the field name by placing the text of this line between parentheses and preceding it with the default name for the field. In the "Birthday" example, above, the full field name would be "Note(Birthday)".
  The exception to this rule is "GSM/PCN" in phone number fields. If the line of text is "GSM/PCN", treat it as if it were "GSM". The full field name will probably be "Tel(GSM)" or "Fax(GSM)".
• The line(s) of text between the [FIELD-DATA] line and the [FIELD-END] line contain the field's data, if any. If there are no lines of text, that means that the field contains no data. There may be more than one line of text.

Include: contdb.goh

See Also: ContactExportDBToTextFile().

ContactMatchName()

RecordID	ContactMatchName( 
        TCHAR		name,
        ContdbFieldType		type,
        Boolean		stopEarly,
        FieldID		*field,
        word		*numMatches );

This function takes aname, searches all fields of the specified type in all records of the Contact database, returning the RecordID and FieldID of the matching field, if any; if there was no match, it returns -1.

The comparison of names does not consider case.

This function takes the following arguments:

name

String containing the name to match.

type

The type of phone number to match; one of CFT_NAME, CFT_COMPANY CFT_TITLE, CFT_ADDRESS, CFT_PHONE, CFT_FAX, CFT_EMAIL, CFT_DTMF, CFT_NOTES.

stopEarly

Set this flag true to stop searching after finding the first matching name; set it false to find out the number of matching names.

field

Pointer to a FieldID buffer. The function will fill this buffer in with the FieldID of the matching field, if any.

numMatches

Pointer to a word buffer. The function will fill this buffer in with the number of matching records found. This number is only meaningful if the stopEarly flag is false .

Include: contdb.goh

See Also: ContactEnsureEmptyField(), FoamDBSetFieldData().

ContactMatchNumber()

RecordID	ContactMatchNumber( 
        TCHAR		number,
        ContdbCallType		type,
        FieldID		*field,
        word		*numMatches );

This function takes a phone number, searches all fields of the specified type in all records of the Contact database, returning the RecordID and FieldID of the matching field, if any; if there was no match, it returns -1.

This function takes the following arguments:

number

String containing the phone number to match.

type

The type of phone number to match; one of CCT_PHONE, CCT_SMS, CCT_FAX, CCT_EMAIL, CCT_GSM_FAX, CCT_ANY.

field

Pointer to a FieldID buffer. The function will fill this buffer in with the FieldID of the matching field, if any.

numMatches

Pointer to a word buffer. The function will fill this buffer in with the number of matching records found.

Include: contdb.goh

See Also: ContactEnsureEmptyField(), FoamDBSetFieldData().

ContactRecreateFieldLabel()

void ContdbRecreateFieldLabel(
        TCHAR 		*subLabel,
        TCHAR 		*destination,
        int 		fieldType);

This utility function takes a field sub-label (e.g., "GSM/PCN") and field type and creates a label from them (e.g. "Tel(GSM)". It will translate standard labels from English to the user's language. (Some field sublabels are standard, such as the "GSM" in "Tel(GSM)" and will be translated; the user's custom sublabels will not be translated.) This function takes the following arguments:

subLabel

The sublabel string.

destination

String buffer to hold the field name.

fieldType

The ContdbFieldType value of the field.

Include: contdb.goh

See Also: ContactImportDBFromTextFile().

ContactReleaseDBHandle()

void	ContactReleaseDBHandle( void );

This function releases the Contact database's handle, signalling that the application is done with the database for now.

Include: contdb.goh

See Also: ContactGetDBHandle(), ContactReleaseDBHandle().

ContactSaveRecord()

dword	ContactSaveRecord(
        MemHandle 		record);

This functionsaves the passed record in the database, inserting it in the proper sort order. It returns the record's RecordID number.

Include: contdb.goh

See Also: FoamDBDiscardRecord(), FoamDBDeleteRecord().

ContactSetTemplateRecord()

void	ContactSetTemplateRecord( 
        MemHandle 		record);

This functionmakes the passed record the Contact database's template record. It also frees that contact's handle.

Include: contdb.goh

See Also: ContactCreateRecordFromTemplate().

ContdbTranslateSubFieldLabelToEnglish()

void	ContdbTranslateSubFieldLabelToEnglish(
        TCHAR 		*subLabel,
        TCHAR 		*destination);

This function translates a foreign sub-label to its english equivalent. This function only recognizes certain "standard" sublabels; the user's custom labels will not be translated. This function takes two arguments: a buffer containing the string to translate and a string buffer to hold the translation.

See Also: DBAllocUngrouped().

DataStoreAddField()

DataStoreStructureError	DataStoreAddField(
        word		dsToken,
        FieldDescriptor		*fieldDescPtr,
        FieldID		*fieldIDPtr);

Adds a field to the datastore and writes the new field's FieldID to fieldIDPtr. Returns a DataStoreStructureError value (DSSE_NO_ERROR if successful). Takes the following arguments:

dsToken

Session token to the opened datastore.

fieldDescPtr

Pointer to a FieldDescriptor structure. Set FD _flags to FF_PRIMARY_KEY if the field is part of the key.

		typedef struct {
			FieldData		FD_data;
			TCHAR		*FD_name;
		} FieldDescriptor;

		typedef struct {
			FieldType		FD_type;
			FieldCategory		FD_category;
			FieldFlags		FD_flags;
		} FieldData;

fieldIDPtr

Pointer to the FieldID of the added field.

Include: datastor.h

DataStoreBuildIndex()

DataStoreStructureError	DataStoreBuildIndex(
        word					dsToken,
        MemHandle					*indexBlockHan,
        word					dataSize,
        DataStoreIndexCallbackParams					*paramsPtr,
        sword _pascal (*CallbackRoutine) (
        	word	dsToken,
        	DataStoreIndexCallbackParams	*paramsPtr));

Builds an index of RecordNum s (low word only) based on either a specified field or a callback function. Returns a DataStoreStructureError value (DSSE_NO_ERROR if successful). Takes the following arguments:

dsToken

Session token to the opened datastore.

indexBlockHan

Pointer to the handle of the index block.

dataSize

Number of bytes of data to write to the index block.

paramsPtr

Pointer to a DataStoreIndexCallbackParams structure. To build an index on a field, specify the field in DSICP _indexField . Set DSICP _sortOrder to SO_ASCENDING or SO_DESCENDING. If you specify a callback, the caller will pass DSICP _cbData , DSICP _rec1 and DSICP _rec2 to the callback.

		typedef struct {
			FieldID		DSICP_indexField;
			SortOrder		DSICP_sortOrder;
			void		*DSICP_cbData;
			RecordHeader		*DSICP_rec1;
			RecordHeader		*DSICP_rec1;
		} DataStoreIndexCallbackParams;

CallbackRoutine

Subroutine to determine which of two passed records comes before the other. The function should return:

-1 if DSICP_rec1 comes before DSICP_rec2
1 if DSICP_rec1 comes after DSICP_rec2

Warnings: Cannot call this routine on datastores that contain more than 4,000 records (will return DSSE_INDEX_RECORD_NUMBER_LIMIT_EXCEEDED).

Include: datastor.h

DataStoreClose()

DataStoreError	DataStoreClose(
        word		dsToken);	/* session token to opened datastore */

Closes the datastore if no other application has it open; otherwise, closes the "session" associated with dsToken . Returns a DataStoreError value (DSE_NO_ERROR if successful).

Warnings: Returns DSE_CLOSE_WITH_LOCKED_RECORD if the calling session has a record locked.

Include: datastor.h

DataStoreCreate()

DataStoreError	DataStoreCreate(
        DataStoreCreateParams			*paramsPtr,
        word			dsToken);

Creates a new datastore, opens a session to it and writes the session token to dsToken . Returns a DataStoreError value (DSE_NO_ERROR if successful). Takes the following arguments:

paramsPtr

Pointer to a DataStoreCreateParams structure. DSCP_name contains the name of the datastore. You can pass DSF_PRIVATE, DSF_TIMESTAMP and/or DSF_NO_PRIMARY_KEY to DSCP_flags. DSCP_keyList and DSCP_keyCount contain the list and number of key field(s), respectively. Specify the object to receive notification of datastore changes in DSCP_notifObject .

		typedef struct {
			TCHAR			*DSCP_name;
			DataStoreFlags			DSCP_flags;
			FieldDescriptor			*DSCP_keyList;
			word			DSCP_keyCount;
			optr			DSCP_notifObject;
		} DataStoreCreateParams;

dsToken

Session token to the opened datastore.

Include: datastor.h

DataStoreDelete()

DataStoreError	DataStoreDelete(
        TCHAR		*dsNamePtr);

Deletes the named datastore if no other application(s) has(have) it open. Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

DataStoreDeleteField()

DataStoreStructureError	DataStoreDeleteField(
        word		dsToken,	/* session token to opened datastore */
        TCHAR		*fieldNamePtr,
        FieldID		fieldID);

Deletes the passed field from the datastore. Returns a DataStoreStructureError value (DSSE_NO_ERROR if successful).

You can reference a field by its name or FieldID . If referencing by name, pass "0" in fieldID ; if referencing by FieldID , pass NULL in fieldNamePtr .

Warnings: Cannot delete key fields.

Cannot delete a field if an application has locked any record in the datastore (will return DSSE_ACCESS_DENIED).

Include: datastor.h

See Also: DataStoreRemoveFieldFromRecord().

DataStoreDeleteRecord()

DataStoreDataError	DataStoreDeleteRecord(
        word		dsToken,	/* session token to opened datastore */
        RecordID		recordID);

Deletes the passed record (referenced by its RecordID ) and flushes it from the record buffer if it is the current record. Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

Warnings: Cannot delete a record that has been locked or loaded into memory (will return DSDE_RECORD_IN_USE).

Include: datastor.h

See Also: DataStoreDeleteRecordNum().

DataStoreDeleteRecordNum()

DataStoreDataError	DataStoreDeleteRecordNum(
        word		dsToken,	/* session token to opened datastore */
        RecordNum		recordNum);

Deletes the passed record (referenced by its RecordNum ) and flushes it from the record buffer if it is the current record. Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

Warnings: Cannot delete a record that has been locked or loaded into memory (will return DSDE_RECORD_IN_USE).

Include: datastor.h

See Also: DataStoreDeleteRecord().

DataStoreDiscardRecord()

DataStoreDataError	DataStoreDiscardRecord(
        word		dsToken);	/* session token to opened datastore */

Flushes the current record from the record buffer (without saving any changes). Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

Include: datastor.h

See Also: DataStoreSaveRecord().

DataStoreFieldEnum()

DataStoreError	DataStoreFieldEnum(
        word		dsToken,
        RecordHeader		*recordPtr,
        void		*enumDataPtr,
        Boolean _pascal (*CallbackRoutine) (
        	void		*fieldDataPtr,
        	word		fieldDataSize,
        	FieldType		fieldType,
        	FieldCategory		fieldCat,
        	FieldID		fieldID,
        	FieldFlags		flags,
        	void		*enumDataPtr));

Enumerates through the fields in the passed record. When the callback returns TRUE, stops enumeration and returns DSE_NO_ERROR. Takes the following arguments:recordPtr

dsToken

Session token to the opened datastore.

recordPtr

Pointer to a RecordHeader structure.

		typedef struct {
			RecordID		RH_id;
			word		RH_size;
			byte		RH_fieldCount;
		} RecordHeader;

enumDataPtr

Pointer to data that caller passes to the callback.

CallbackRoutine

Boolean subroutine to determine when enumeration should end.

Be Sure To: Lock the record first with DataStoreLockRecord() before calling this routine.

Warnings: Callback can modify data passed in enumDataPtr but cannot modify any actual field data.

Include: datastor.h

See Also: DataStoreRecordEnum().

DataStoreFieldIDToName()

DataStoreStructureError	DataStoreFieldIDToName(
        word		dsToken,	/* session token to opened datastore */
        FieldID		fieldID,
        TCHAR		*fieldNamePtr,
        word		*nameSizePtr);

Writes the field name corresponding to the passed FieldID ( fieldID ) to fieldNamePtr . Copies no more than nameSizePtr bytes and overwrites this same parameter with the number of bytes actually copied. Returns a DataStoreStructureError value (DSSE_NO_ERROR if successful).

Include: datastor.h

See Also: DataStoreFieldNameToID().

DataStoreFieldNameToID()

DataStoreStructureError	DataStoreFieldNameToID(
        word		dsToken,	/* session token to opened datastore */
        TCHAR		*fieldNamePtr,
        FieldID		*fieldIDPtr);

Writes the FieldID corresponding to the passed field name (fieldNamePtr ) to fieldIDPtr . Returns a DataStoreStructureError value (DSSE_NO_ERROR if successful).

Include: datastor.h

See Also: DataStoreFieldIDToName().

DataStoreGetExtraData()

DataStoreError	DataStoreGetExtraData(
        word		dsToken,	/* session token to opened datastore */
        void		*dataPtr, /* data read from file header */
        word		*dataSizePtr);

Writes any extra data for this datastore to dataPtr . Writes the number of bytes copied to dataSizePtr . Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

DataStoreGetField()

DataStoreDataError	DataStoreGetField(
        word		dsToken,	/* session token to opened datastore */
        TCHAR		*fieldNamePtr,
        FieldID		fieldID,
        void		**blockPtrPtr,
        word		*blockSizePtr,
        MemHandle		*blockHanPtr);

Writes contents of the passed field to a block. If blockPtrPtr is NULL, allocates a block and writes its handle to blockHanPtr and its size to blockSizePtr . If blockPtrPtr is not NULL and field data exceeds block size, copies blockSizePtr bytes to the block and returns DSDE_EXCEEDS_BUFFER_SIZE. Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

If referencing field by name, pass "0" in fieldID ; if referencing field by FieldID , pass NULL in fieldNamePtr .

Warnings: If the passed field is not present, writes "0" to blockSizePtr and returns DSDE_NO_ERROR.

Include: datastor.h

See Also: DataStoreGetFieldChunk().

DataStoreGetFieldChunk()

DataStoreDataError	DataStoreGetFieldChunk(
        word		dsToken,	/* session token to opened datastore */
        TCHAR		*fieldNamePtr,
        FieldID		fieldID,
        MemHandle		blockHan,
        ChunkHandle		*chunkHanPtr,
        word		*dataSizePtr);

Writes contents of the passed field to a chunk in the passed block. If chunkHanPtr is NULL, allocates a chunk and writes its handle to chunkHanPtr . If chunkHanPtr is not NULL dataSizePtrand field data exceeds chunk size, resizes the chunk and writes the number of bytes copied to dataSizePtr . Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

If referencing field by name, pass "0" in fieldID ; if referencing field by FieldID , pass NULL in fieldNamePtr .

Warnings: If the passed field is not present, writes "0" to dataSizePtr and returns DSDE_NO_ERROR.

Include: datastor.h

See Also: DataStoreGetField().

DataStoreGetFieldCount()

DataStoreError	DataStoreGetFieldCount(
        word		dsToken,	/* session token to opened datastore */
        word		*fieldCountPtr);

Writes the number of fields defined for this datastore to fieldCountPtr . Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

See Also: DataStoreGetRecordCount().

DataStoreGetFieldInfo()

DataStoreStructureError	DataStoreGetFieldInfo(
        word		dsToken,	/* session token to opened datastore */
        FieldDescriptor		*fieldDescPtr,
        FieldID		fieldID,
        word		fieldNameSize);

Writes FieldDescriptor for passed field to fieldDescPtr. For FD_name , writes fieldNameSize bytes only; pass "0" (and set FD_name to NULL) if you don't need the field name. Returns a DataStoreStructureError value (DSSE_NO_ERROR if successful).

Include: datastor.h

DataStoreGetFieldPtr()

DataStoreDataError	DataStoreGetFieldPtr(
        word		dsToken,	/* session token to opened datastore */
        RecordHeader		*recordPtr,
        FieldID		fieldID,
        void		**fieldContentPtrPtr,
        FieldType		*fieldTypePtr,
        word		*fieldSizePtr);

Gets a pointer to the field specified by fieldID . Writes the field's content to fieldContentPtrPtr , its FieldType to fieldTypePtr , and its size to fieldSizePtr . Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

Include: datastor.h

DataStoreGetFieldSize()

DataStoreDataError	DataStoreGetFieldSize(
        word		dsToken,	/* session token to opened datastore */
        TCHAR		*fieldNamePtr,
        FieldID		fieldID,
        word		*fieldSizePtr);

Writes the number of bytes in the passed field to fieldSizePtr . Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

If referencing field by name, pass "0" in fieldID ; if referencing field by FieldID , pass NULL in fieldNamePtr .

Warnings: If the field is not present, writes "0" to fieldSizePtr and returns DSDE_NO_ERROR.

Include: datastor.h

DataStoreGetFlags()

DataStoreError	DataStoreGetFlags(
        word		dsToken,	/* session token to opened datastore */
        DataStoreFlags		*FlagPtr);

Writes the DataStoreFlags set for this datastore to flagPtr . Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

DataStoreGetNextRecordID()

DataStoreError	DataStoreGetNextRecordID(
        word		dsToken,	/* session token to opened datastore */
        RecordID		*nextIDPtr);

Writes the next RecordID to be assigned to nextIDPtr . Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

DataStoreGetNumFields()

DataStoreDataError	DataStoreGetNumFields(
        word		dsToken,	/* session token to opened datastore */
        word		*fieldCountPtr);

Writes the number of fields in the current record to fieldCountPtr . Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

Include: datastor.h

DataStoreGetOwner()

DataStoreError	DataStoreGetOwner(
        word		dsToken,	/* session token to opened datastore */
        GeodeToken		*tokenPtr);

Writes the GeodeToken of the application that created the datastore to tokenPtr . Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

DataStoreGetRecordCount()

DataStoreError	DataStoreGetRecordCount(
        word		dsToken,	/* session token to opened datastore */
        dword		*RecordCountPtr);

Writes the number of records in the datastore to recordCountPtr . Returns a DataStoreError value (DSE_NO_ERROR if successful).

Warnings: Does not count new records that have not yet been saved.

Include: datastor.h

See Also: DataStoreGetFieldCount().

DataStoreGetRecordID()

DataStoreDataError	DataStoreGetRecordID(
        word		dsToken,	/* session token to opened datastore */
        RecordID		*recordIDPtr);

Writes the RecordID of the current record to recordIDPtr . Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

Warnings: If no record is loaded, returns DSDE_RECORD_BUFFER_EMPTY.

Include: datastor.h

DataStoreGetTimeStamp()

DataStoreError	DataStoreGetTimeStamp(
        word		dsToken,	/* session token to opened datastore */
        FileDateAndTime		*timestampPtr);

Writes the date and time that the datastore was last modified to timestampPtr . Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

DataStoreGetVersion()

DataStoreError	DataStoreGetVersion(
        word		dsToken,	/* session token to opened datastore */
        ProtocolNumber		*versionPtr);

Writes the protocol number of the datastore to versionPtr . (Protocol numbers are useful for keeping track of different versions of a datastore.) Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

DataStoreLoadRecord()

DataStoreDataError	DataStoreLoadRecord(
        word		dsToken,	/* session token to opened datastore */
        RecordID		recordID,
        RecordNum		*recordNumPtr);

Loads the record referenced by recordID into memory and makes it the current record. Writes the RecordNum of the loaded record to recordNumPtr . Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

Warnings: Returns DSDE_RECORD_BUFFER_NOT_EMPTY if there is already a record loaded in the session's record buffer.

Returns DSDE_INVALID_RECORD_NUMBER if there is no such record.

Returns DSDE_RECORD_IN_USE if another session has already locked the record.

Include: datastor.h

See Also: DataStoreLoadRecordNum().

DataStoreLoadRecordNum()

DataStoreDataError	DataStoreLoadRecordNum(
        word		dsToken,	/* session token to opened datastore */
        RecordNum		recordNum,
        RecordID		*recordIDPtr);

Loads the record referenced by recordNum into memory and makes it the current record. Writes the RecordID of the loaded record to recordIDPtr . Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

Warnings: Returns DSDE_RECORD_BUFFER_NOT_EMPTY if there is already a record loaded in the session's record buffer.

Returns DSDE_INVALID_RECORD_NUMBER if there is no such record.

Returns DSDE_RECORD_IN_USE if another session has already locked the record.

Include: datastor.h

See Also: DataStoreLoadRecord().

DataStoreLockRecord()

DataStoreDataError	DataStoreLockRecord(
        word		dsToken,	/* session token to opened datastore */
        RecordHeader		**recordPtrPtr);

Locks the current record. Used primarily when calling DataStoreFieldEnum() . Also used when calling DataStoreGetFieldPtr() . Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

Be Sure To: Unlock the locked record with DataStoreUnlockRecord() when you are through with the record.

Warnings: Returns DSDE_RECORD_BUFFER_EMPTY if there is no record loaded in the buffer.

Include: datastor.h

See Also: DataStoreUnlockRecord().

DataStoreMapRecordNumToID()

DataStoreDataError	DataStoreMapRecordNumToID(
        word		dsToken,	/* session token to opened datastore */
        RecordNum		recordNum,
        RecordID		*recordIDPtr);

Writes the RecordID corresponding to the passed RecordNum to recordIDPtr . Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

Include: datastor.h

DataStoreNewRecord()

DataStoreDataError	DataStoreNewRecord(
        word		dsToken);	/* session token to opened datastore */

Creates a new (empty) record and makes it the current record. Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

Warnings: A new record becomes a permanent part of the datatstore only after it is saved (with DataStoreSaveRecord() ).

Include: datastor.h

DataStoreOpen()

DataStoreError	DataStoreOpen(
        TCHAR		*dsNamePtr,
        optr		notifyObject,
        DataStoreOpenFlags		openFlag,
        word		*dsTokenPtr);

Opens the datastore referenced by dsNamePtr and writes the session token to dsTokenPtr . Passing DSOF_EXCLUSIVE in openFlag opens the datastore with access restricted to the caller; if another application already has the datastore open, returns DSE_ACCESS_DENIED. Passing NullOptr in notifyObject means no object will receive GWNT_DATASTORE_CHANGE notifications. Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

DataStoreRecordEnum()

DataStoreError	DataStoreRecordEnum(
        word				dsToken,
        RecordNum				*startRecordPtr,
        DataStoreRecordEnumFlags				flags,
        void				*enumDataPtr,
        Boolean _pascal (*CallbackRoutine) (
        	RecordHeader				record,
        	void				*enumDataPtr));

Enumerates through the records of a datastore in storage order. When CallbackRoutine returns TRUE, stops enumeration, updates startRecordPtr with the RecordNum of the last record examined, and returns DSE_NO_ERROR. (To continue enumeration, increment startRecordPtr .) Returns DSE_NO_MORE_RECORDS if first or last record is reached.

Takes the following arguments:

dsToken

Session token to the opened datastore.

startRecordPtr

Pointer to the RecordNum at which to start enumeration (unless DSREF_START_AT_END is passed [in flags] in which case this argument is ignored).

flags

DataStoreRecordEnumFlags to pass. Passing DSREF_BACKWARDS causes enumeration to go backwards. Passing DSREF_START_AT_END with DSREF_BACKWARDS causes enumeration to go backwards starting at the last record. (Passing DSREF_START_AT_END without DSREF_BACKWARDS causes enumeration to start at the first record, ignoring whatever value is in startRecordPtr.)

enumDataPtr

Pointer to data that caller passes to the callback routine.

CallbackRoutine

Boolean subroutine. Caller passes in the RecordHeader of the current record and enumDataPtr. Returning TRUE ends enumeration.

Warnings: Callback can modify data passed in enumDataPtr but cannot modify any actual data in the record.

Datastore cannot be modified during enumeration.

Include: datastor.h

See Also: DataStoreFieldEnum(), DataStoreStringSearch().

DataStoreRemoveFieldFromRecord()

DataStoreDataError	DataStoreRemoveFieldFromRecord(
        word		dsToken,	/* session token to opened datastore */
        TCHAR		*fieldNamePtr,
        FieldID		fieldID);

Deletes the passed field from the current record. Returns a DataStoreError value (DSE_NO_ERROR if successful).

If referencing field by name, pass "0" in fieldID ; if referencing field by FieldID , pass NULL in fieldNamePtr .

Include: datastor.h

See Also: DataStoreDeleteField().

DataStoreRename()

DataStoreError	DataStoreRename(
        TCHAR		*oldNamePtr,
        TCHAR		*newNamePtr);

Changes the name of a datastore from oldNamePtr to newNamePtr . Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

DataStoreRenameField()

DataStoreStructureError	DataStoreRenameField(
        word		dsToken,	/* session token to opened datastore */
        TCHAR		*newNamePtr,
        TCHAR		*oldNamePtr,
        FieldID		fieldID);

Changes the name of a field from oldNamePtr to newNamePtr . Returns a DataStoreStructureError value (DSSE_NO_ERROR if successful).

If referencing field by name, pass "0" in fieldID ; if referencing field by FieldID , pass NULL in oldNamePtr .

Warnings: Returns DSSE_FIELD_NAME_TOO_LONG if new name exceeds MAX_FIELD_NAME_LENGTH ( i.e. , 40 * sizeof(TCHAR)).

Include: datastor.h

DataStoreSaveRecord()

DataStoreDataError	DataStoreSaveRecord(
        word		dsToken,
        void		*dataPtr,
        sword _pascal (*CallbackRoutine) (
        	RecordHeader		*Rec1Ptr,
        	RecordHeader		*Rec2Ptr,
        	word		dsToken,
        	void		*dataPtr),
        RecordNum		*recordNumPtr,
        RecordID		*recordIDPtr);

Writes the current record to the datastore (saving any changes made to the record) and flushes the record from the buffer. If CallbackRoutine is "0", inserts saved record to the key (if a key exists) or appends the record to the end of the datastore if no key exists. Writes the RecordNum and RecordID of the saved record to recordNumPtr and recordIDPtr, respectively. Returns a DataStoreDataError value (DSDE_NO_ERROR if successful). Takes the following arguments:

dsToken

Session token to the opened datastore.

dataPtr

Pointer to data that caller passes to the callback.

CallbackRoutine

Subroutine to determine where to insert saved record. Caller passes RecordHeader s of two records to compare. Caller can also pass extra data with dataPtr. The function should return:

-1if Rec1Ptr comes before Rec2Ptr
0 if Rec1Ptr equals Rec2Ptr
1 if Rec1Ptr comes after Rec2Ptr

recordNumPtr

Pointer to RecordNum of saved record.

recordIDPtr

Pointer to RecordID of saved record.

Include: datastor.h

See Also: DataStoreDiscardRecord().

DataStoreSetExtraData()

DataStoreError	DataStoreSetExtraData(
        word		dsToken,	/* session token to opened datastore */
        void		*extraDataPtr, /* data to write to file header */
        word		extraDataSize);

Writes extraDataSize bytes of extra data to the datastore file header, replacing any existing extra data. Passing "0" in extraDataSize deletes any existing extra data. Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

DataStoreSetField()

DataStoreDataError	DataStoreSetField(
        word		dsToken,	/* session token to opened datastore */
        TCHAR		*fieldNamePtr,
        FieldID		fieldID,
        void		*dataPtr,
        word		dataSize);

Writes dataSize bytes of data (dataPtr) to the passed field. Passing "0" in dataSize deletes the field from the record. Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

If referencing field by name, pass "0" in fieldID ; if referencing field by FieldID , pass NULL in fieldNamePtr .

Include: datastor.hblockHan

DataStoreSetNextRecordID()

DataStoreError	DataStoreSetNextRecordID(
        word		dsToken,	/* session token to opened datastore */
        RecordID		nextID);

Sets the next RecordID to be assigned to nextID. Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

See Also: DataStoreSetRecordID().

DataStoreSetRecordID()

DataStoreDataError	DataStoreSetRecordID(
        word		dsToken,	/* session token to opened datastore */
        RecordID		recordID);

Sets the RecordID of the current record to recordID; datastore must be opened for exclusive access. If the passed RecordID is greater than the next RecordID to be assigned, updates the latter with the passed RecordID + 1. Returns a DataStoreDataError value (DSDE_NO_ERROR if successful).

Warnings: Overwrites any existing record with the same RecordID as the passed value.

Include: datastor.h

See Also: DataStoreSetNextRecordID().

DataStoreSetTimeStamp()

DataStoreError	DataStoreSetTimeStamp(
        word		dsToken,	/* session token to opened datastore */
        FileDateAndTime		timestamp);

Sets date and time that datastore was last modified to timestamp. Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

DataStoreSetVersion()

DataStoreError	DataStoreSetVersion(
        word		dsToken,	/* session token to opened datastore */
        ProtocolNumber		version);

Sets the datastore's protocol number; this is useful for keeping track of different versions of a datastore. Returns a DataStoreError value (DSE_NO_ERROR if successful).

Include: datastor.h

DataStoreStringSearch()

DataStoreError	DataStoreStringSearch(
        word		dsToken,	/* session token to opened datastore */
        SearchParams		*paramsPtr);

Performs a string search on the datastore. If it finds a match, updates SP _startRecord with the RecordNum of the matching record and returns DSE_NO_ERROR. If it reaches the first or last record without finding a match, returns DSE_NO_MORE_RECORDS. Takes the following arguments:

dsToken

Session token to the opened datastore.

paramsPtr

Pointer to a SearchParams structure.

		typedef struct {
			SearchType		SP_searchType;
			RecordNum		SP_startRecord;
			dword		SP_maxRecords;
			FieldID		SP_startField;
			FieldCategory	SP_category;
			TCHAR		*SP_searchString;
			SearchFlags		SP_flags;
		} SearchParams;

Warnings: Returns DSSE_INDEX_RECORD_NUMBER_LIMIT_EXCEEDED if you call this routine on a datastore with more than 4,000 records.

Include: datastor.h

See Also: DataStoreRecordEnum(), DataStoreFieldEnum().

DataStoreUnlockRecord()

void	DataStoreUnlockRecord(
        word		dsToken);	/* session token to opened datastore */

Unlocks the current record. If you lock a record with DataStoreLock() , you must unlock it with this routine.

Include: datastor.h

See Also: DataStoreLockRecord().

DBAlloc()

DBItem	DBAlloc(
        VMFileHandle		file,		
        DBGroup		group,
        word		size);

This routine allocates an item in the specified file and group. It is passed the handles for the file and group which will contain the new item. It returns the new item's item-handle.

Warnings: All pointers to items in the group may be invalidated.

Include: dbase.h

See Also: DBAllocUngrouped().

DBAllocUngrouped()

DBGroupAndItem 	DBAllocUngrouped(
        VMFileHandle		file,			
        word		size);

This routine allocates an ungrouped item in the specified file. It is passed the handle of the file which will contain the new item. It returns the item's DBGroupAndItem value.

Warnings: All pointers to ungrouped items may be invalidated.

Include: dbase.h

See Also: DBAlloc().

DBCombineGroupAndItem()

DBGroupAndItem 	DBCombineGroupAndItem(
        DBGroup 		group,
        DBItem 		item);

This macro combines group and item handles into a dword-sized DBGroupAndItem value.

Include: dbase.h

See Also: DBGroupFromGroupAndItem(), DBItemFromGroupAndItem().

DBCopyDBItem()

DBItem 	DBCopyDBItem(
        VMFileHandle		srcFile,				
        DBGroup		srcGroup,
        DBItem		srcItem,
        VMFileHandle		destFile,				
        DBGroup		destGroup);

This routine makes a duplicate of a DB item in the specified DB file and group. It is passed the file handle, group handle, and item handle of the source item, as well as the file handle and group handle of the destination group. It makes a copy of the DB item and returns its DBItem handle.

Warnings: All pointers to items in the destination group may be invalidated.

Include: dbase.h

See Also: VMCopyVMChain().

DBCopyDBItemUngrouped()

DBGroupAndItem 	DBCopyDBItemUngrouped(
        VMFileHandle		srcFile,				
        DBGroupAndItem		srcID,				/* source item */
        VMFileHandle		destFile);				

This routine makes a duplicate of a specified DB item. It is passed the file handle and DBGroupAndItem value specifying the source item, and the file handle of the destination file. It allocates the item as an ungrouped item in the specified file and returns its DBGroupAndItem value.

Tips and Tricks: If the source item is not ungrouped, you can combine the group and item handles into a DBGroupAndItem value by calling the macro DBCombineGroupAndItem() .

Warnings: All pointers to ungrouped items in the destination file may be invalidated.

Include: dbase.h

See Also: VMCopyVMChain().

DBDeleteAt()

void	DBDeleteAt(
        VMFileHandle		file,			
        DBGroup		group,
        DBItem		item,
        word		deleteOffset,
        word		deleteCount);

This routine deletes a sequence of bytes from within an item. It does not invalidate pointers to other items. The routine is passed the file, group, and item handles specifying the item, as well as an offset within the item and a number of bytes to delete. It will delete the specified number of bytes from within the item, starting with the byte at the specified offset.

Include: dbase.h

DBDeleteAtUngrouped()

void	DBDeleteAtUngrouped(
        VMFileHandle		file,				
        DBGroupAndItem		id,
        word		deleteOffset,
        word		deleteCount);

This routine is just like DBDeleteAt() , except it is passed a DBGroupAndItem value instead of separate group and item handles. It does not invalidate pointers to other items.

Include: dbase.h

DBDeref()

void *	DBDeref(
        optr		*ref);

This routine is passed an optr to a locked DB item. The routine returns the address of the item.

Warnings: The optr becomes invalid when the DB item is unlocked.

Include: dbase.h

DBDirty()

void	DBUnlock(
        const void *		ptr);

This routine marks a DB item as dirty; this insures that the VM manager will copy its item-block back to the disk before freeing its memory. The routine is passed a pointer to anywhere within the item.

Tips and Tricks: All the items in an item block are marked dirty at once; thus, you can call this routine just once for several items in the same item block. Only the segment portion of the pointer is significant; thus, you can pass a pointer to anywhere in the item. This is useful if you have incremented the pointer to the item.

Include: dbase.h

DBFree()

void	DBFree(
        VMFileHandle		file,
        DBGroup		group,
        DBItem		item);

This routine frees the specified item. It does not invalidate pointers to other items in the group. It is passed the file, group, and item handles specifying the item; it does not return anything.

Never Use Situations:
Never call DBFree() on a locked item. If you do, the item-block's lock count will not be decremented, which will prevent the item block from ever being properly unlocked.

Include: dbase.h

See Also: DBFreeUngrouped().

DBFreeUngrouped()

void	DBFreeUngrouped(
        VMFileHandle		file,
        DBGroupAndItem		id);

This routine frees the specified item. It does not invalidate pointers to other ungrouped items. It is passed the file handle and DBGroupAndItem value specifying the item; it does not return anything.

Never Use Situations: Never call DBFreeUngrouped() on a locked item. If you do, the item-block's lock count will not be decremented, which will prevent the item block from ever being properly unlocked.

Include: dbase.h

See Also: DBFree().

DBGetMap()

DBGroupAndItem 	DBGetmap(
        VMFileHandle		file);

This routine returns the DBGroupAndItem structure for the passed file's map item. If there is no map item, it returns a null handle.

Include: dbase.h

See Also: DBSetMap(), DBLockMap().

DBGroupAlloc()

DBGroup	DBGroupAlloc(
        VMFileHandle		file);

This routine allocates a new DB group in the specified file and returns its handle. If the group cannot be allocated, DBGroupAlloc() returns a null handle.

Include: dbase.h

DBGroupFree()

void	DBGroupFree(
        VMFileHandle		file,
        DBGroup		group);

This routine frees the specified group. This deletes all items and item-blocks associated with the group. It is passed the file and group handle specifying the group. Note that you can free a group even if some of its items are locked; those locked items will also be freed.

Include: dbase.h

DBGroupFromGroupAndItem()

DBGroup	DBGroupFromGroupAndItem(
        DBGroupAndItem		id);

This macro returns the DBGroup portion of a DBGroupAndItem value.

Include: dbase.h

DBInsertAt()

void	DBInsertAt(
        VMFileHandle		file,			
        DBGroup		group,
        DBItem		item,
        word		insertOffset,
        word		insertCount);

This routine inserts bytes at a specified offset within a DB item. The bytes are zero-initialized. It is passed the file, group, and item handles specifying a DB item, as well as an offset within the cell and a number of bytes to insert. It inserts the specified number of bytes beginning at the specified offset; the data which was at the passed offset will end up immediately after the inserted bytes.

Warnings: This routine invalidates pointers to other items in the same group.

Include: dbase.h

DBInsertAtUngrouped()

void	DBInsertAtUngrouped(
        VMFileHandle		file,			
        DBGroupAndItem		id,
        word		insertOffset,
        word		insertCount);

This routine is just like DBInsertAt() , except it is passed a DBGroupAndItem value instead of separate group and item handles.

Warnings: This routine invalidates pointers to other ungrouped items.

Include: dbase.h

DBItemFromGroupAndItem()

DBItem	DBItemFromGroupAndItem(
        DBGroupAndItem		id);

This macro returns the DBItem portion of a DBGroupAndItem value.

Include: dbase.h

DBLock()

void *	DBLock(
        VMFileHandle		file,
        DBGroup		group,
        DBItem		item);

This routine locks the specified item and returns a pointer to it. It is passed the file, group, and item handles specifying a DB item. If it fails, it returns a null pointer.

Include: dbase.h

See Also: DBLockGetRef(), DBLockUngrouped().

DBLockGetRef()

void *	DBLockGetRef(
        VMFileHandle		file,			
        DBGroup		group,
        DBItem		item,
        optr *		ref);

This routine is just like DBLock() , except that it writes the item's optr to the passed address.

Include: dbase.h

Warnings: The optr is only valid until the DB item is unlocked.

DBLockGetRefUngrouped()

void *	DBLockGetRefUngrouped(
        VMFileHandle		file,			
        DBGroupAndItem		id,
        optr *		ref);

This routine is the same as DBLockGetRef() , except that it is passed a DBGroupAndItem value.

Include: dbase.h

DBLockMap()

void *	DBLockMap(
        VMFileHandle		file);			

This routine locks the specified file's map item and returns its address. To unlock the map item, call DBUnlock() normally.

Include: dbase.h

See Also: DBLockMap().

DBLockUngrouped()

void *	DBLockUngrouped(
        VMFileHandle		file,			
        DBGroupAndItem		id);

This routine is the same as DBLock() , except that it is passed a DBGroupAndItem value.

Include: dbase.h

DBReAlloc()

void	DBReAlloc(
        VMFileHandle		file,			
        DBGroup		group,
        DBItem		item,
        word		size);

This routine changes the size of a DB item. It is passed the file, group, and item handles specifying the DB item, and a new size for the item (in bytes). If the new size is larger than the old, space will be added to the end of the item; if the new size is smaller than the old, the item will be truncated to fit.

Warnings: If the new size is larger than the old, all pointers to items in the group are invalidated. Space added is not zero-initialized.

Include: dbase.h

DBReAllocUngrouped()

void	DBReAllocUngrouped(
        VMFileHandle		file,			
        DBGroupAndItem		id,
        word		size);

This routine is just like DBReAlloc() , except it is passed a DBGroupAndItem value instead of separate group and item handles.

Warnings: If the new size is larger than the old, all pointers to ungrouped items are invalidated. Space added is not zero-initialized.

Include: dbase.h

DBSetMap()

void	DBSetMap(
        VMFileHandle		file,			
        DBGroup		group,
        DBItem		item);

This routine sets the DB map item. You can later retrieve a DBGroupAndItem structure identifying this item by calling DBGetMap() . The routine is passed the file, group, and item handles specifying the new map item; it does not return anything.

Include: dbase.h

DBSetMapUngrouped()

void	DBSetMapUngrouped(
        VMFileHandle		file,			
        DBGroupAndItem		id);

This routine is just like DBSetMap() , except it is passed a DBGroupAndItem value instead of separate group and item handles.

Include: dbase.h

DBUnlock()

void	DBUnlock(
        void *	ptr); /* address of item to unlock */

This routine unlocks the DB item whose address is passed.

Tips and Tricks: Only the segment address of the pointer is significant. Thus, you can pass a pointer to somewhere within an item (or immediately after it) to unlock it.

Be Sure To: If the item has been changed, make sure you call DBDirty() before you unlock it.

Include: dbase.h

DiskCheckInUse()

Boolean	DiskCheckInUse(
        DiskHandle		disk);

This routine checks if a registered disk is being used. If a file on that disk is open, or if a path on that disk is on some thread's directory stack, the routine will return true (i.e. non-zero); otherwise it will return false (i.e. zero). Note that a disk may be "in use" even if it is not currently in any drive.

Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file (which is guaranteed to be in use).

Include: disk.h

DiskCheckUnnamed()

Boolean	DiskCheckUnnamed( /* returns true if disk is unnamed */
        DiskHandle		disk);

This routine checks if a registered disk has a permanent name. If the disk does not have a name, the routine returns true (i.e. non-zero); otherwise it returns false . Note that GEOS assigns a temporary name to unnamed disks when they are registered. To find out a disk's temporary or permanent name, call DiskGetVolumeName() .

Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.

See Also: DiskGetVolumeName().

Include: disk.h

DiskCheckWritable()

Boolean	DiskCheckWritable(
        DiskHandle		disk);

DiskCheckWritable() checks if a disk is currently writable. It returns false (i.e. zero) if the disk is not writable, whether by nature (e.g. a CD-ROM disk) or because the write-protect tab is on; otherwise it returns true (i.e. non-zero).

Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.

Include: disk.h

DiskCopy()

DiskCopyError 	DiskCopy(
        word		source,
        word		dest,
        Boolean _pascal (*callback)
		(DiskCopyCallback					code,
		 DiskHandle					disk,
		 word					param));

This routine copies one disk onto another. The destination disk must be formattable to be the same type as the source disk. The first two arguments specify the source and destination drive. These drives may or may not be the same. If they are different, they must take compatible disks.

A disk copy requires frequent interaction with the user. For example, the copy routine must prompt the user to swap disks when necessary. For this reason, DiskCopy() is passed a pointer to a callback routine. This routine handles all interaction with the user. It must be declared _pascal. Each time it is called, it is passed three arguments. The first is a member of the DiskCopyCallback enumerated type; this argument specifies what the callback routine should do. The second argument is a disk handle; its significance depends on the value of the DiskCopyCallback argument. The third argument is a word-sized piece of data whose significance depends on the value of the DiskCopyCallback argument. Note that either of these arguments may be null values, depending on the value of the DiskCopyCallback argument.

The callback routine can abort the copy by returning true (i.e. non-zero); otherwise, it should return false (i.e. zero). The callback routine is called for several situations, identified by the value of DiskCopyCallback associated with them:

CALLBACK_GET_SOURCE_DISK

The callback routine should prompt the user to insert the source disk into the appropriate drive. The second argument is meaningless for this call. The third argument is the number identifying the drive; use DriveGetName() to find the name for this drive.

CALLBACK_GET_DEST_DISK

The callback routine should prompt the user to insert the destination disk into the appropriate drive. The second argument is meaningless for this call. The third argument is the number identifying the drive.

CALLBACK_REPORT_NUM_SWAPS

The second argument is meaningless for this call. The third argument is the number of disk swaps that will be necessary. The callback routine may wish to report this number to the user and ask for confirmation.

CALLBACK_VERIFY_DEST_DESTRUCTION

If the destination disk has already been formatted, the callback routine will be called with this parameter. The callback routine may wish to remind the user that the destination disk will be erased. The second argument is the handle of the destination disk; this is useful if, for example, you want to report the disk's name. The third argument is the destination drive's number. If the callback routine aborts the copy at this time by returning non-zero, the destination disk will not be harmed.

CALLBACK_REPORT_FORMAT_PCT

If the destination disk needs to be formatted, DiskCopy() will periodically call the callback routine with this parameter. The callback routine may wish to notify the user how the format is progressing. In this case, the second argument will be meaningless; the third parameter will be the percentage of the destination disk which has been formatted. The callback routine may wish to notify the user how the format is progressing.

CALLBACK_REPORT_COPY_PCT

While the copy is taking place, DiskCopy() will periodically call the callback routine with this parameter. The callback routine may wish to notify the user how the copy is progressing. In this case, the second parameter will be meaningless; the third parameter will be the percentage of the copy which has been completed.

If the copy was successful, DiskCopy() returns zero. Otherwise, it returns a member of the DiskCopyError enumerated type. That type has the following members:

ERR_DISKCOPY_INSUFFICIENT_MEM

This is returned if the routine was unable to get adequate memory.

ERR_CANT_COPY_FIXED_DISKS

ERR_CANT_READ_FROM_SOURCE

ERR_CANT_WRITE_TO_DEST

ERR_INCOMPATIBLE_FORMATS

The destination drive must be able to write disks in exactly the same format as the source disk. Note that the source and destination drives may be the same.

ERR_OPERATION_CANCELLED

This is returned if the callback routine ever returned a non-zero value, thus aborting the copy.

ERR_CANT_FORMAT_DEST

Include: disk.h

DiskFind()

DiskHandle 	DiskFind(
        const char *		fname,			/* Null-terminated volume name */
        DiskFindResult *		code);			/* DiskFindResult written here */

This routine returns the handle of the disk with the specified name. If there is no registered disk with the specified name, DiskFind() returns a null handle. Note that while disk handles are unique, volume names are not; therefore, there may be several registered disks with identical volume names. For this reason, DiskFind() writes a member of the DiskFindResults enumerated type (described below) into the space pointed to by the code pointer.

Structures: DiskFind() uses the DiskFindResult enumerated type, which has the following values:

DFR_UNIQUE

There is exactly one registered disk with the specified name; its handle was returned.

DFR_NOT_UNIQUE

There are two or more registered disks with the specified name; the handle of an arbitrary one of these disks was returned.

DFR_NOT_FOUND

There are no registered disks with the specified name; a null disk handle was returned.

Tips and Tricks: If you want to find all the disks with a given volume name, call DiskForEach() and have the callback routine check each disk's name with DiskGetVolumeName() .

See Also: DiskRegisterDisk().

Include: disk.h

DiskForEach()

DiskHandle 	DiskForEach(
        Boolean _pascal (* callback)			(DiskHandle				disk)) 		/* callback returns true
									 * to cancel */

This routine lets you perform an action on every registered disk. It calls the callback routine once for each disk, passing the disk's handle. The callback routine must be declared _pascal. The callback routine can force an early termination by returning true (i.e. non-zero). If the callback routine ever returns true , DiskForEach() terminates and returns the handle of the last disk passed to the callback routine. If the callback routine examines every disk without returning true , DiskForEach() returns a null handle.

Tips and Tricks: DiskForEach() is commonly used to look for a specific disk. The callback routine checks each disk to see if it's the one; if it finds a match, the callback routine simply returns true , and DiskForEach() returns the disk's handle.

Include: disk.h

DiskFormat()

FormatError 	DiskFormat(
        word 		driveNumber,
        MediaType		media,				/* Format to this size */
        DiskFormatFlags		flags,				/* See flags below */
        dword		*goodClusters,					/* These are filled in at the */
        dword		*badClusters,					/* of the format */
        Boolean _pascal (*callback)		
			(word percentDone));						/* Return true to cancel */

This routine formats a disk to the specified size. When it is finished, it fills in the passed pointers to contain the number of good and bad clusters on the disk. (To find out the size of each cluster, call DiskGetVolumeInfo() .) The routine returns a member of the FormatError enumerated type (whose members are described below).

DiskFormat() can be instructed to call a callback routine periodically. This allows the application to keep the user informed about how the format is progressing. The callback routine is passed either the percent of the disk which has been formatted, or the cylinder and head currently being formatted. The callback routine must be declared _pascal. The callback routine can cancel the format by returning true (i.e. non-zero); otherwise, it should return false (i.e. zero).

The third argument passed is a word-length flag field. Currently, only three flags are defined:

DFF_CALLBACK_PERCENT_DONE

A callback routine should be called periodically. The callback routine should be passed a single argument, namely the percentage of the format which has been done.

DFF_CALLBACK_CYL_HEAD

A callback routine should be called periodically. The callback routine should be passed a single argument, namely the cylinder head being formatted. If both DFF_CALLBACK_PERCENT_DONE and DFF_CALLBACK_CYL_HEAD are passed, results are undefined. If neither flag is set, the callback routine will never be called; a null function pointer may be passed.

DFF_FORCE_ERASE

A "hard format" should be done, i.e. the sectors should be rewritten and initialized to zeros. If this flag is not set, DiskFormat() will do a "soft format" if possible; it will check the sectors and write a blank file allocation table, but it will not necessarily erase the data from the disk.

DiskFormat() returns a member of the FormatError enumerated type. If the format was successful, it will return the constant FMT_DONE (which is guaranteed to equal zero). Otherwise, it will return one of the following constants:

FMT_DRIVE_NOT_READY
FMT_ERROR_WRITING_BOOT
FMT_ERROR_WRITING_ROOT_DIR
FMT_ERROR_WRITING_FAT
FMT_ABORTED
FMT_SET_VOLUME_NAME_ERROR
FMT_CANNOT_FORMAT_FIXED_DISKS_IN_CUR_RELEASE
FMT_BAD_PARTITION_TABLE
FMT_ERR_NO_PARTITION_FOUND
FMT_ERR_CANNOT_ALLOC_SECTOR_BUFFER
FMT_ERR_DISK_IS_IN_USE
FMT_ERR_WRITE_PROTECTED
FMT_ERR_DRIVE_CANNOT_SUPPORT_GIVEN_FORMAT
FMT_ERR_INVALID_DRIVE_SPECIFIED
FMT_ERR_DRIVE_CANNOT_BE_FORMATTED
FMT_ERR_DISK_UNAVAILABLE

Include: disk.h

DiskGetDrive()

word	DiskGetDrive(
        DiskHandle		dh);

This routine returns the drive number associated with a registered disk. Note that it will do this even if the drive is no longer usable (e.g. if a network drive has been unmapped).

Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.

See Also: DiskFind(), DiskRegisterDisk().

Include: disk.h

DiskGetVolumeFreeSpace()

dword	DiskGetVolumeFreeSpace( 
        DiskHandle		dh);

This routine returns the amount of free space (measured in bytes) on the specified disk. If the disk is, by nature, not writable (e.g. a CD-ROM disk), DiskGetVolumeFreeSpace() returns zero and clears the thread's error value. If an error condition exists, DiskGetVolumeFreeSpace() returns zero and sets the thread's error value.

Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.

See Also: DiskGetVolumeInfo().

Include: disk.h

DiskGetVolumeInfo()

word	DiskGetVolumeInfo(  /* Returns 0 if successful */
        DiskHandle		dh,
        DiskInfoStruct		*info);			/* Routine fills this structure */

This routine returns general information about a disk. It returns the following four pieces of information:

• The size of each disk block in bytes. When space is allocated, it is rounded up to the nearest whole block.
• The number of free bytes on the disk.
• The total number of bytes on the disk; this is the total of free and used space.
• The disk's volume name. If the volume is unnamed, the current temporary name will be returned.

The information is written to the passed DiskInfoStruct . If an error condition occurs, DiskGetVolumeInfo() will return the error code and set the thread's error value; otherwise, it will return zero.

Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.

Include: disk.h

DiskGetVolumeName()

void	DiskGetVolumeName(
        DiskHandle		dh,
        char *		buffer);			/* Must be VOLUME_NAME_LENGTH_ZT bytes
						 * long */

This routine copies the disk's volume name (as a null-terminated string) to the passed buffer. If an error occurs, it sets the thread's error value. If the volume has no name, the routine returns the current temporary name.

Warnings: DiskGetVolumeName() does not check the size of the buffer passed. If the buffer is not at least VOLUME_NAME_LENGTH_ZT bytes long, the routine may write beyond its boundaries.

Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.

See Also: DiskGetVolumeInfo(), DiskSetVolumeName().

DiskRegisterDisk()

DiskHandle 	DiskRegisterDisk(
        word	driveNumber); 

This routine registers a disk in the specified drive and assigns it a disk handle. (The disk handle persists only to the end of the current session of GEOS.) If the disk already has a handle, DiskRegisterDisk() will return it. If the disk does not have a name, GEOS will assign it a temporary name (such as "UNNAMED1") and display an alert box telling the user what the temporary name is. (This is done only the first time the disk is registered in each session.) Note that the temporary name is not written to the disk; thus, it persists only until the end of the current session of GEOS.

If this routine returns a disk handle, there's a disk in the drive; if it doesn't, there may still be a disk in the drive, but the disk is unformatted.

Tips and Tricks: There is no harm in registering the same disk several times. Thus, if you want to get the disk handle for the disk in a specific drive, you can simply call DiskRegisterDisk() .

See Also: DiskRegisterDiskSilently().

Include: disk.h

DiskRegisterDiskSilently()

DiskHandle 	DiskRegisterDiskSilently(
        word		driveNumber);

This routine is almost identical to DiskRegisterDisk() (described immediately above). There is only one difference: If GEOS assigns a temporary name to the disk, it will not present an alert box to the user.

See Also: DiskRegisterDisk().

Include: disk.h

DiskRestore()

DiskHandle 	DiskRestore(
        void *		buffer,			/* buffer written by DiskSave() */
        DiskRestoreError _pascal (*callback)	
			(const char 						*driveName,
			 const char 						*diskName,
			 void 						**bufferPtr,

        		 DiskRestoreError 						error);

DiskRestore() examines a buffer written by DiskSave() and returns the handle of the disk described by that buffer. If that disk is already registered, DiskRestore() will simply return its handle. If the disk is not registered and is not in the drive, DiskRestore() will call the specified callback routine. The callback routine should be declared _pascal. The callback routine is passed four arguments:

• A null-terminated string containing the name of the drive for the disk.
• A null-terminated string containing the disk's volume label.
• A pointer to a variable in the DiskRestore() routine. This variable is itself a pointer to the opaque data structure provided by DiskSave() . If the callback routine takes any action which causes that structure to move (e.g. if it causes the global or local heap containing the buffer to be shuffled), it should update the pointer in DiskRestore() .
• A member of the DiskRestoreError enumerated type. This is the error which DiskRestore() would have returned if there had not been a callback routine. This is usually DRE_REMOVABLE_DRIVE_DOESNT_HOLD_DISK.

The callback routine should prompt the user to insert a disk. If the callback routine was successful, it should return DRE_DISK_IN_DRIVE (which is guaranteed to be equal to zero). Otherwise, it should return a member of the DiskRestoreError enumerated type; usually it will return DRE_USER_CANCELLED_RESTORE. Note that the callback routine will not generally know if the user has inserted a disk; it generally just displays an alert box and returns when the user clicks "OK." After the callback routine returns, DiskRestore() registers the disk and makes sure that it's the correct one; if it is not, it calls the callback routine again.

You can pass a null function pointer to DiskRestore() instead of providing a callback routine. In this case, DiskRestore() will fail if the disk has not been registered and is not currently in the drive.

DiskRestore() returns the handle of the disk. If it fails for any reason, it returns a null handle and sets the thread's error value to a member of the DiskRestorenError enumerated type. This type has the following members:

DRE_DISK_IN_DRIVE

This is returned by the callback routine. This is guaranteed to equal zero.

DRE_DRIVE_NO_LONGER_EXISTS

The disk is associated with a drive which is no longer attached to the system.

DRE_REMOVABLE_DRIVE_DOESNT_CONTAIN_DISK

The disk is unregistered, and it is not currently in the drive associated with it. If a callback routine was provided, DiskRestore() will call it under these circumstances.

DRE_USER_CANCELLED_RESTORE

This is returned by the callback routine if the user cancels the restore.

DRE_COULDNT_CREATE_NEW_DISK_HANDLE

DiskRestore() was unable to register the disk in the appropriate drive because it couldn't create a new disk handle.

DRE_REMOVABLE_DRIVE_IS_BUSY

The appropriate drive is busy with a time-consuming operation (e.g. a disk format).

DRE_NOT_ATTACHED_TO_SERVER

The disk was from a network server to which we are not logged in.

DRE_PERMISSION_DENIED

The disk was on a network which is now denying access to it.

DRE_ALL_DRIVES_USED

The disk was on a network volume that isn't mounted, but there is no drive left to which it can be mapped.

See Also: DiskSave().

Include: disk.h

DiskSave()

Boolean	DiskSave(
        DiskHandle		disk,
        void *		buffer,				/* data will be written here */
        word *		bufferSize);				/* Size of buffer (in bytes) */

This routine writes information about a disk in the specified buffer. DiskRestore() can use this information to return the disk handle, even in another session of GEOS. The bufferSize argument should point to a word containing the size of the buffer (in bytes). If the buffer is large enough, DiskSave() will write an opaque data structure into the buffer, and change the value of *bufferSize to the actual size of the data structure; any extra buffer space can be freed or otherwise used. In this case, DiskSave() will return true (i.e. non-zero). If the buffer was too small, DiskSave() will return false (i.e. zero) and write the size needed into *bufferSize . Simply call DiskSave() again with a large enough buffer. If DiskSave() failed for some other reason, it will return false and set *bufferSize to zero.

See Also: DiskRestore().

Include: disk.h

DiskSetVolumeName()

word	DiskSetVolumeName(
        DiskHandle		dh,
        const char *		name);			/* Change the name to this */

This routine changes the disk's volume label. If it is successful, it returns zero; otherwise it returns an error code. It also sets or clears the thread's error value appropriately. The following error codes may be returned:

ERROR_INVALID_VOLUME

An invalid disk handle was passed to the routine.

ERROR_ACCESS_DENIED

For some reason, the volume's name could not be changed. For example, the volume might not be writable.

ERROR_DISK_STALE

The drive containing that disk has been deleted. This usually only happens with network drives.

Include: disk.h

DosExec()

word	DosExec(
        const char *		prog,
        DiskHandle 		progDisk,
        const char *		arguments,
        const char *		execDir,
        DiskHandle 		execDisk,
        DosExecFlags 		flags);

This routine shuts down GEOS to run a DOS program. It returns an error code if an error occurs or zero if successful. Its parameters are listed below:

prog

A pointer to a null-terminated character string representing the path of the program to be run. If a null string (not a null pointer), the system's DOS command interpreter will be run. The path string should not contain the drive name.

progDisk

A disk handle indicating the disk on which the program to be executed sits. If zero is passed, the disk on which GEOS resides will be used.

arguments

A pointer to a locked or fixed buffer containing arguments to be passed to the program being run.

execDir

A pointer to a null-terminated character string representing the path in which the program is to be run. The string should not contain the drive name. If a null pointer is passed and execDisk is zero, the program will be run in the directory in which GEOS was first started.

execDisk

The disk handle of the disk containing the directory in execDir .

flags

A record of DosExecFlags indicating whether the DOS program will give a prompt to the user to return to GEOS. The possible flags are DEF_PROMPT, DEF_FORCED_SHUTDOWN, and DEF_INTERACTIVE. For more information, see the entry for DosExecFlags .

If there was no error, DosExec() will return zero. Otherwise it will return one of the following error values: ERROR_FILE_NOT_FOUND, ERROR_DOS_EXEC_IN_PROGRESS, ERROR_INSUFFICIENT_MEMORY, or ERROR_ARGS_TOO_LONG.

Include: system.h

DriveGetDefaultMedia()

MediaType 	DriveGetDefaultMedia(
        word		driveNumber);

This routine returns the default media type for the specified drive. It returns a member of the MediaType enumerated type (described in the Data Structures reference). Note that a drive can be used for media types other than the default. For example, a high-density 3.5-inch drive will have a default media type of MEDIA_1M44, but it can read from, write to, and format 3.5-inch disks with size MEDIA_720K.

See Also: DriveTestMediaSupport().

Include: drive.h

DriveGetExtStatus()

word	DriveGetExtStatus(
        word		driveNumber);

This routine is much like DriveGetStatus() (described immediately below). However, in addition to returning all of the flags set by DriveGetStatus() , it also sets additional flags in the upper byte of the return value. It returns the following additional flags:

DES_LOCAL_ONLY

This flag is set if the device cannot be viewed over a network.

DES_READ_ONLY

This flag is set if the device is read only, i.e. no data can ever be written to a volume mounted on it (e.g., a CD-ROM drive).

DES_FORMATTABLE

This flag is set if disks can be formatted in the drive.

DES_ALIAS

This flag is set if the drive is actually an alias for a path on another drive.

DES_BUSY

This flag is set if the drive will be busy for an extended period of time (e.g., if a disk is being formatted).

If an error condition exists, DriveGetExtStatus() returns zero.

See Also: DriveGetStatus().

Include: drive.h

DriveGetName()

char *	DriveGetName(
        word	driveNumber,	/* Get name of this drive */
        char *	buffer,	/* Write name to this buffer */
        word	bufferSize);	/* Size of buffer (in bytes) */

This routine finds the name of a specified drive. You should use this name when prompting the user to take any action regarding this drive (e.g. to insert a disk). The routine writes the name, as a null terminated string, to the buffer passed. It returns a pointer to the trailing null. If the drive does not exist, or the buffer is too small, DriveGetName() returns a null pointer.

Include: drive.h

DriveGetStatus()

word	DriveGetStatus(
        word	driveNumber);

This routine returns the current status of a drive. The drive is specified by its drive number. The routine returns a word of DriveStatus flags. These flags are listed below:

DS_PRESENT

This flag is set if the physical drive exists, regardless of whether the drive contains a disk.

DS_MEDIA_REMOVABLE

This flag is set if the disk can be removed from the drive.

DS_NETWORK

This flag is set if the drive is accessed over a network (or via network protocols), which means the drive cannot be formatted or copied.

DS_TYPE

This is a mask for the lowest four bits of the field. These bits contain a member of the DriveType enumerated type.

If an error condition exists, DriveGetStatus() returns zero.

See Also: DriveGetExtStatus().

Include: drive.h

DriveTestMediaSupport()

Boolean	DriveTestMediaSupport(
        word		DriveNumber,			
        MediaType		media);				/* Desired disk size */

This routine checks whether the specified drive can support disks in the specified size. It returns true (i.e., non-zero) if the drive supports the size.

See Also: DriveGetDefaultMedia().

Include: drive.h

EC()

void	EC(line);

This macro defines a line of code that will only be compiled into the error-checking version of the geode. The line parameter of the macro is the actual line of code. When the EC version of the program is compiled, the line will be treated as a normal line of code; when the non-EC version is compiled, the line will be ignored.

See Also: NEC().

EC_BOUNDS()

void	EC_BOUNDS(addr);

This macro adds an address check to the error-checking version of a program. When the EC version of the program is compiled, the address check will be included; when the non-EC version is compiled, the address check will be left out. The addr parameter is the address or pointer to be checked.

The macro expands to a call to ECCheckBounds() on the specified address or pointer. If the address is out of bounds, the program will stop with a call to FatalError() .

See Also: ECCheckBounds().

EC_ERROR()

void	EC_ERROR(code);

This macro inserts a call to FatalError() in the error-checking version of the program and does nothing to the non-EC version. When the program gets to this point, it will halt and put up an error message corresponding to the specified error code . If a condition should be checked before calling FatalError() , you can use EC_ERROR_IF() instead.

EC_ERROR_IF()

void	EC_ERROR_IF(test, code);

This macro inserts a conditional call to FatalError() in the error-checking version of a program; it does nothing for the non-EC version. The test parameter is a Boolean value that, if true , will cause the FatalError() call to be made. If test is false , FatalError() will not be called.

EC_WARNING()

EC_WARNING(word warningCode);

This macro generates a warning for the debugger when executed by error-checking code; it has no effect when in non-EC code.

Include: ec.h

EC_WARNING_IF()

EC_WARNING_IF(<expr>, word warningCode)

When this macro is executed in error-checking code, it tests <expr>; if <expr> is non-zero, it generates a warning with code warningCode for the debugger.

In non-EC code, the macro has no effect (and <expr> is not evaluated).

Include: ec.h

ECCheckBounds()

void	ECCheckBounds(
        void	*address);

This routine checks to see if the given pointer is within bounds of the block into which it points. If assertions fail, a fatal error will occur. If the "lmem" EC flag is turned on and the pointer points within an LMem block, then this routine will also check that the pointer points to a valid chunk handle or a chunk within the LMem block.

Include: ec.h

ECCheckChunkArray()

void	ECCheckChunkArray(
        optr	o);

This routine checks the validity of the specified chunk array. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckChunkArrayHandles()

void	ECCheckChunkArrayHandles(
        MemHandle mh,
        ChunkHandle ch);

This routine checks the validity of the specified chunk array. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckClass()

void	ECCheckClass(
        ClassStruct *class);

This routine checks that the given pointer actually references a class definition. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckDriverHandle()

void	ECCheckDriverHandle(
        GeodeHandle gh);

This routine checks that the passed handle actually references a driver. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckEventHandle()

void	ECCheckEventHandle(
        EventHandle eh);

This routine checks that the passed handle actually references a stored message. If the assertions fail, a fatal error will occur.

ECCheckFileHandle()

void	ECCheckFileHandle(
        FileHandle file);

This routine checks that the passed handle actually is a file handle and references a file. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckGeodeHandle()

void	ECCheckGeodeHandle(
        GeodeHandle gh);

This routine checks that the passed handle references a loaded geode. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckGStateHandle()

void	ECCheckGStateHandle(
        GStateHandle gsh);

This routine checks that the passed handle references a GState. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckHugeArray()

void	ECCheckHugeArray(
        VMFileHandle		vmFile,
        VMBlockHandle		vmBlock);

This routine checks the validity of the passed Huge Array. If the block passed is not the directory block of a Huge Array, the routine fails.

Include: ec.h

ECCheckLibraryHandle()

void	ECCheckLibraryHandle(
        GeodeHandle gh);

This routine checks that the passed handle references a library. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckLMemChunk()

void	ECCheckLMemChunk(
        void * chunkPtr);

This routine checks the validity of the chunk pointed to by chunkPtr . If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckLMemHandle()

void	ECCheckLMemHandle(
        MemHandle mh);

This routine checks that the passed handle is a memory handle and actually references a local memory block. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckLMemHandleNS()

void	ECCheckLMemHandleNS(
        MemHandle mh);

This routine checks that the passed handle is a local memory handle; unlike ECCheckLMemHandle() , however, it does not check sharing violations (when threads are illegally using non-sharable memory). If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckLMemObject()

void	ECCheckLMemObject(
        optr	obj); 		/* Object must be locked down. */

This routine checks the validity of an object to ensure that it is an object stored in an object block. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckLMemObjectHandles()

void	ECCheckLMemObjectHandles(
        MemHandle mh,
        ChunkHandle ch);

This routine checks the validity of an object to ensure that it is an object stored in an object block. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckLMemOD()

void	ECCheckLMemOD(
        optr	o);

This routine checks the validity of the given local-memory-based object. If assertions fail, a fatal error will occur.

Include: ec.h

ECCheckLMemODHandles()

void	ECCheckLMemODHandles(
        MemHandle objHan,
        ChunkHandle objCh);

This routine checks the validity of the given local-memory-based object. If assertions fail, a fatal error will occur.

Include: ec.h

ECCheckMemHandle()

void	ECCheckMemHandle(
        MemHandle mh);

This routine checks that the passed handle is a memory handle that references a memory block. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckMemHandleNS()

void	ECCheckMemHandleNS(
        MemHandle mh);

This routine checks that the passed handle references a memory block; unlike ECCheckMemHandle() , however, it will not check for sharing violations (when a thread illegally accesses a non-sharable block). If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckObject()

void	ECCheckObject(
        optr	obj);

This routine checks the validity of the given locked object. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckObjectHandles()

void	ECCheckObjectHandles(
        Memhandle mh,
        ChunkHandle ch);

This routine checks the validity of the given locked object. If the assertions fail, a fatal error will occur.

ECCheckOD()

void	ECCheckOD(
        optr	obj);

This routine checks the validity of the given object. Unlike ECCheckLMemObject() , however, it allows optrs of Process objects to be specified. If assertions fail, a fatal error will occur.

ECCheckODHandles()

void	ECCheckODHandles(
        MemHandle objHan,
        ChunkHandle objCh);

This routine checks the validity of the given object. Unlike ECCheckLMemObjectHandles() , however, it allows processes to be specified. If assertions fail, a fatal error will occur.

Include: ec.h

ECCheckProcessHandle()

void	ECCheckProcessHandle(
        GeodeHandle gh);

This routine checks that the passed handle actually references a process. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckQueueHandle()

void	ECCheckQueueHandle(
        QueueHandle qh);

This routine ensures the passed handle references an event queue. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckResourceHandle()

void	ECCheckResourceHandle(
        MemHandle mh);

This routine ensures that the passed handle references a geode resource. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckStack()

void	ECCheckStack();

This routine checks to make sure the current stack has not overflown (and is not about to). This routine also enforces a 100-byte gap between the stack bottom and the stack pointer. If assertions fail, a fatal error will occur.

Include: ec.h

ECCheckThreadHandle()

void	ECCheckThreadHandle(
        ThreadHandle th);

This routine checks that the passed handle actually references a thread. If the assertions fail, a fatal error will occur.

Include: ec.h

ECCheckWindowHandle()

void	ECCheckWindowHandle(
        WindowHandle wh);

This routine checks that the passed handle actually references a window. If the assertions fail, a fatal error will occur.

Include: ec.h

ECLMemExists()

void	ECLMemExists(
        optr	o);

This routine checks to see if the specified chunk exists. This routine should be called by applications to check the chunk handle's validity. If the assertions fail, a fatal error will occur.

Include: ec.h

ECLMemExistsHandles()

void	ECLMemExistsHandles(
        MemHandle mh,
        ChunkHandle ch);

This routine checks to see if the specified chunk exists. This routine should be called by applications to check the chunk handle's validity. If the assertions fail, a fatal error will occur.

Include: ec.h

ECLMemValidateHandle()

void	ECLMemValidateHandle(
        optr	o);

This routine checks that the passed optr points to a local memory chunk. If the assertions fail, a fatal error will occur.

Include: ec.h

ECLMemValidateHandleHandles()

void	ECLMemValidateHandleHandles(
        MemHandle mh,
        ChunkHandle ch);

This routine checks that the passed memory and chunk handles actually reference a local memory chunk. If the assertions fail, a fatal error will occur.

Include: ec.h

ECLMemValidateHeap()

void	ECLMemValidateHeap(
        MemHandle mh);

This routine does a complete error-check of the LMem heap. It is used internally and should not be needed by application programmers.

Include: ec.h

ECMemVerifyHeap()

void	ECMemVerifyHeap()

This routine makes sure the global heap is in a consistent state. If the assertions fail, a fatal error will occur. This routine should likely not be called by anything other than the EC kernel.

Include: ec.h

ECVMCheckMemHandle()

void	ECVMCheckMemHandle(
        MemHandle han);

This routine checks that the given memory handle is actually linked to a VM block handle. If assertions fail, a fatal error will occur.

Include: ec.h

ECVMCheckVMBlockHandle()

void	ECVMCheckVMBlockHandle(
        VMFileHandle file,
        VMBlockHandle block);

This routine checks the validity of the given VM file and block handles. If assertions fail, a fatal error will occur.

Include: ec.h

ECVMCheckVMFile()

void	ECVMCheckVMFile(
        VMFileHandle file);

This routine checks the validity of the given VM file handle. If assertions fail, a fatal error will occur.

Include: ec.h

ElementArrayAddElement ()

word	ElementArrayAddElement(
        optr	arr,		/* Handle of element array */
        void *	element,		/* Element to add (if necessary) */
        dword	callBackData,		/* This is passed to the Callback routine */
        Boolean _pascal (*callback) (void *elementToAdd, 
			void *elementFromArray, 			dword valueForCallback));

This routine is used to add elements to an array. It is passed the address of a potential element. It compares the element with each member of an element array. If there are no matches, it adds the element to the array and sets the reference count to one. If there is a match, it increments the reference count of the matching element in the array and returns; it does not add the new element. When you pass the address of an element, make sure you pass the address of the data portion of the element (not the reference-count header).

You can pass a callback routine to ElementArrayAddElement() . ElementArrayAddElement() will call the callback routine to compare elements and see if they match. The callback routine should be declared _pascal. ElementArrayAddElement() passes the callback routine the address of the element you passed it, as well as the address of the data-portion of the element in the array (the part after the RefElementHeader structure). If the two elements match (by whatever criteria you use), return true ; otherwise, return false . If you pass a null function pointer, the default comparison routine will be called, which checks to see if every data byte matches.

Include: chunkarr.h

Tips and Tricks: If you know the element is already in the array, you can increment its reference count by calling ElementArrayAddReference() .

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayAddReference().

ElementArrayAddElementHandles()

word	ElementArrayAddElementHandles(
        MemHandle		mh,				/* Global handle of LMem heap */
        ChunkHandle		chunk				/* Chunk handle of element array */
        void *		element,				/* Element to add */
        dword		callBackData,		/* Passed to the Callback routine */
        Boolean _pascal (*callback) (void *elementToAdd, 
			void *elementFromArray, 			dword valueForCallback));

This routine is exactly like ElementArrayAddElement() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

Tips and Tricks: If you know the element is already in the array, you can increment its reference count by calling ElementArrayAddReference() .

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayAddReference().

ElementArrayAddReference()

void	ElementArrayAddReference(
        optr	arr,				/* optr to element array */
        word	token);				/* Index number of element */

This routine increments the reference count of a member of an element array.

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayAddElement().

ElementArrayAddReferenceHandles()

void	ElementArrayAddReferenceHandles(
        MemHandle		mh,				/* Handle of LMem heap's block */
        ChunkHandle		ch,				/* Handle of element array */
        word		token);				/* Index number of element */

This routine is exactly like ElementArrayAddReference() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

ElementArrayCreate()

ChunkHandle ElementArrayCreate(
        MemHandle		mh,				/* Handle of LMem heap's block */
        word		elementSize,				/* Size of each element, or zero
							 * for variable-sized */

        word		headerSize);				/* Header size (zero for default) */

This routine creates an element array in the indicated LMem heap. It creates an ElementArrayHeader structure at the head of the chunk. If you want to leave extra space before the start of the array, you can pass a larger header size; if you want to use the standard header, pass a header size of zero.

You can specify the size of each element. Remember that the first three bytes of every element in an element array are the element's RefElementHeader ; structure, which contains the reference count; leave room for this when you choose a size. For arrays with variable-sized elements, pass a size of zero.

Include: chunkarr.h

Tips and Tricks: You may want to declare a structure for array elements; the first component should be a RefElementHeader . You can pass the size of this structure to ElementArrayCreate() .

If you want extra space after the ElementArrayHeader , you may want to create your own header structure, the first element of which is an ElementArrayHeader . You can pass the size of this header to ElementArrayCreate() , and access the data in your header via the structure.

Be Sure To: Lock the block on the global heap before calling this routine (unless it is fixed). If you pass a header size, make sure it is larger than sizeof(ElementArrayHeader) .

ElementArrayCreateAt()

ChunkHandle 	ElementArrayCreateAt(
        optr	arr,				/* optr of chunk for array */
        word	elementSize,				/* Size of each element, or zero
						 * for variable-sized */

        word	headerSize);				/* Header size (zero for default) */

This routine is just like ElementArrayCreate() above, except that the element array is created in a pre-existing chunk. The contents of that chunk will be overwritten.

Include: chunkarr.h

Warnings: If the chunk isn't large enough, it will be resized. This will invalidate all pointers to chunks in that block.

ElementArrayCreateAtHandles()

ChunkHandle 	ElementArrayCreateAtHandles(
        MemHandle		mh,				/* Handle of LMem heap */
        ChunkHandle		ch				/* Create array in this chunk */
        word		elementSize,				/* Size of each element, or zero
						 * for variable-sized */

        word		headerSize);				/* Header size (zero for default) */

This routine is exactly like ElementArrayCreateAt() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

Warnings: If the chunk isn't large enough, it will be resized. This will invalidate all pointers to chunks in that block.

ElementArrayDelete()

void	ElementArrayDelete(
        optr	arr,					/* optr to element array */
        word	token);					/* index of element to delete */

This routine deletes an element from an element array regardless of its reference count. The routine is passed the element array's optr and the token for the element to delete.

Note that when an element is removed, it is actually resized down to zero size and added to a list of free elements. That way the index numbers of later elements are preserved.

Include: chunkarr.h

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayRemoveReference().

ElementArrayDeleteHandles()

void	ElementArrayDeleteHandles(
        MemHandle		mh,				/* Handle of LMem heap */
        ChunkHandle		ch,				/* Chunk handle of element array */
        word		token);				/* Index of element delete */

This routine is exactly like ElementArrayDelete() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayRemoveReference().

ElementArrayElementChanged()

void	ElementArrayElementChanged(
        optr	arr,				/* optr to element array */
        word	token,				/* Index number of element */
        dword	callbackData,				/* This is passed along to callback */
        Boolean _pascal (*callback)			/* Returns true if elements identical */
        		(void *			elementChanged,
        		 void *			elementToCompare,
        		 dword			valueForCallback));

This routine checks to see if an element is identical to any other elements in the same element array. This is used after an element has changed to see if it now matches another element. If the element matches another, it will be deleted, and the other element will have its reference count incremented.

The routine is passed an optr to the element array, the token of the element which is being checked, a dword of data (which is passed to the callback routine), and a pointer to a callback comparison routine. The callback routine itself is passed pointers to two elements and the callbackData argument passed to ElementArrayElementChanged() . The callback routine should be declared _pascal. If the two elements are identical, the callback should return true (i.e. non-zero); otherwise, it should return false .

If you pass a null function pointer, ElementArrayElementChanged() will do a bytewise comparison of the elements.

Include: chunkarr.h

ElementArrayElementChangedHandles()

void	ElementArrayElementChangedHandles(
        MemHandle		memHandle,				/* Handle of LMem heap's block */
        ChunkHandle		chunkHandle,				/* Chunk handle of element array */
        word		token,				/* Index number of element */
        dword		callbackData,					/* This is passed along to
							 * callback */

        Boolean _pascal (*callback)			/* Returns true if elements identical */
        		(void *			elementChanged,
        		 void *			elementToCompare,
        		 dword			valueForCallback));

This routine is exactly like ElementArrayElementChanged() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

ElementArrayGetUsedCount()

word	ElementArrayGetUsedCount(
        optr	arr,			/* optr to element array */
        dword	callbackData,			/* This is passed to callback routine */
        Boolean _pascal (*callback)				/* return true to count this element */
        		(void * element, dword cbData));

This routine counts the number of active elements in an element array; that is, elements which have a reference count of one or greater. It can be instructed to count every element, or every element which matches certain criteria. The routine is passed three parameters: the optr of the chunk array, a dword which is passed to the callback routine, and a callback routine which determines whether the element should be counted. The callback routine,which should be declared _pascal, is passed the dword an a pointer to an element. It should return true if the element should be counted; otherwise, it should return false . To count every element, pass a null callback pointer.

Include: chunkarr.h

See Also: ElementArrayTokenToUsedIndex(), ElementArrayUsedIndexToToken().

ElementArrayGetUsedCountHandles()

void	ElementArrayGetUsedCountHandles(
        MemHandle 		mh,			/* Handle of LMem heap's block */
        ChunkHandle		ch,			/* Chunk handle of element array */
        dword	callbackData,			/* This is passed to callback routine */
        Boolean _pascal (*callback)				/* return true to count this element */
        		(void * element, dword cbData));

This routine is exactly like ElementArrayGetUsedCount() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

ElementArrayRemoveReference()

void	ElementArrayRemoveReference(
        optr		arr,				/* optr of element array */
        word		token,				/* Index of element to 
						 * unreference */

        dword		callbackData,				/* Passed to callback routine */
        void _pascal (*callback)		(void *element, dword valueForCallback));
/* Routine is called if element is actually removed */

This routine decrements the reference count of the specified element. If the reference count drops to zero, the element will be removed. If an element is to be removed, ElementArrayRemoveReference() calls the callback routine on that element. The callback routine should perform any cleanup necessary; it is passed a pointer to the element and the callbackData argument. If you pass a null function pointer, no callback routine will be called.

Note that when an element is removed, it is actually resized down to zero size and added to a list of free elements. That way the index numbers of later elements are preserved.

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayDelete().

Include: chunkarr.h

ElementArrayRemoveReferenceHandles()

void	ElementArrayRemoveReferenceHandles(
        MemHandle		mh,			/* Handle of LMem heap */
        ChunkHandle		ch,			/* Chunk handle of element array */
        word		token,			/* Index of element to unreference */
        dword		callbackData,				/* Passed to callback routine */
        void _pascal (*callback)		(void *element, dword valueForCallback));
/* Routine is called if element is actually removed */

This routine is exactly like ElementArrayRemoveReference() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

ElementArrayTokenToUsedIndex()

word	ElementArrayTokenToUsedIndex(
        optr	arr,	/* Handle of element array */
        word	token,	/* Index of element to unreference */
        dword	callbackData,	/* Data passed to callback routine */
        Boolean 	_pascal (*callback)	/* Return true to count this element */
        	    (void *element, dword cbData));

This routine is passed the token of an element array. It translates the token into an index from some non-standard indexing scheme. The indexing scheme can either number the elements from zero, counting only those elements in use (i.e. those with a reference count greater than zero); or it can use a more restrictive scheme. If a callback routine is passed, the callback routine will be called for every used element; it should be declared _pascal and return true if the element should be counted. If a null callback pointer is passed, every used element will be counted.

Include: chunkarr.h

ElementArrayTokenToUsedIndexHandles()

word	ElementArrayTokenToUsedIndexHandles(
        MemHandle 		mh,		/* Handle of LMem heap */
        ChunkHandle 		ch,		/* Chunk handle of element array */
        word		token,		/* Index of element to unreference */
        dword		callbackData, /* Data passed to the
						 * callback routine */

        Boolean 	_pascal (*callback)	/* Return true to count this element */
        		(void *element, dword cbData));

This routine is exactly like ElementArrayTokenToUsedIndex() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

ElementArrayUsedIndexToToken()

word	ElementArrayUsedIndexToToken(
        optr	arr,		/* optr to element array */
        word	index,		/* Find token of element with this index */
        dword	callbackData,		/* This is passed to the callback routine */
        Boolean _pascal (*callback)			/* Return true to count this element */
        		(void *element, dword cbData));

This routine takes an index into an element array from some non-standard indexing scheme. The routine finds the element specified and returns the element's token. The indexing scheme can either number the elements from zero, counting only those elements in use (i.e. those with a reference count greater than zero); or it can use a more restrictive scheme. If a callback routine is passed, the callback routine will be called for every used element; it should should be declared _pascal return true if the element should be counted. If a null callback pointer is passed, every used element will be counted.

If no matching element is found, ElementArrayUsedIndexToToken() returns CA_NULL_ELEMENT.

Include: chunkarr.h

ElementArrayUsedIndexToTokenHandles()

word	ElementArrayUsedIndexToTokenHandles(
        MemHandle 		mh,		/* Handle of LMem heap's block */
        ChunkHandle 		ch,		/* Handle of element array */
        word		index,		/* Find token of element with this index */
        dword		callbackData, /* Data passed to the
	 						  * callback routine */

        Boolean 	_pascal (*callback)	/* Return true to count this element */
        	    (void *element, dword cbData));

This routine is exactly like ElementArrayUsedIndexToToken() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

FatalError()

void	FatalError(
        word errorCode);

This routine causes a fatal error, leaving errorCode for the debugger.

FileClose()

word 	FileClose( /* returns error */
        FileHandle		fh,					/* File to close */
        Boolean		noErrorFlag);					/* Set if app. can't handle
								 * errors */

This routine closes an open byte file. If the routine succeeds, it returns zero. If the routine fails and noErrorFlag is false (i.e., zero), FileClose() returns a member of the FileError enumerated type. If the routine fails and noErrorFlag is true (i.e., non-zero), the routine will fatal-error.

Warnings: The noErrorFlag parameter should be true only during debugging.

Include: file.h

FileCommit()

word	FileCommit( /* returns error */
        FileHandle		fh,
        Boolean		noErrorFlag);				/* set if can't handle errors */

FileCommit() forces the file system to write any cached information about a file to the disk immediately. If it is successful, it returns zero. If it fails, it returns an error code. If the routine fails and noErrorFlag is true (i.e. non-zero), the routine will fatal-error.

Warnings: The noErrorFlag parameter should be true only during debugging.

Include: file.h

FileConstructFullPath()

DiskHandle 	FileConstructFullPath(
        char		* * buffer,				/* Path string is written here */
        word		bufSize,			/* Length of buffer (in bytes) */
        DiskHandle		disk,			/* Disk or standard path; null for 
						 * current path */

        const char		* tail,			/* Path relative to handle */
        Boolean		addDriveLetter);					/* Should path begin with drive
								 * name? */

This routine translates a GEOS directory specification into a complete path string. It writes the string into the passed buffer. The directory is specified by two arguments: The first, disk , is the handle of a disk; this may also be a standard path constant. (If a null handle is passed, the current working directory is used.) The second, tail , is a pointer to the character string representing the tail end of the path. FileConstructFullPath() appends this relative path to the location indicated by the disk handle. It then constructs a full path string, beginning with that disk's root directory, and writes it to the buffer passed. If addDriveName is true (i.e. non-zero), the path string will begin with the drive's name and a colon. The pointer pointed to by buffer will be updated to point to the end of the constructed string.

Examples: The following call to FileConstructFullPath() might yield these results:

Sample call to FileConstructFullPath()

/* Here we find out the full path of a subdirectory of the DOCUMENT directory */

	DiskHandle		documentDisk;
	char		pathBuffer[256];			/* long enough for most paths */
	char		*pB = &pathBuffer;

	documentDisk = FileConstructFullPath(&pB,						/* pointer to pointer */
					256, 		/* Length of buffer */
					SP_DOCUMENT,		/* This can be a disk or 
							 * standard path */
					"MEMOS\\JANUARY", /* In C strings, the
							 * backslash must be
							 * doubled */
					TRUE);		/* Prepend drive name */

/* If the standard paths are set up in the default configuration, "documentDisk"
 * would be the handle of the main hard drive, and pathBuffer would contain a
 * string like "C:\GEOWORKS\DOCUMENT\MEMOS\JANUARY" */

See Also: FileParseStandardPath().

Include: file.h

FileCopy()

word	FileCopy( /* returns error */
        const char		* source,				/* Source path and file name */
        const char		* dest,				/* Destination path and file name */
        DiskHandle		sourceDisk,				/* These handles may be Standard */
        DiskHandle		destDisk);				/* Path constants, or null to indi- 
						 * cate current working directory */

This routine makes a copy of a file. The source and destination are specified with path strings. Each string specifies a path relative to the location specified by the corresponding disk handle. If the handle is a disk handle, the path is relative to that disk's root. If the disk handle is a standard path constant, the path string is relative to that standard path. If the disk handle is null, the path is relative to the current working directory.

If FileCopy() is successful, it returns zero. Otherwise, it returns one of the following error codes:

ERROR_FILE_NOT_FOUND

No such source file exists in the specified directory.

ERROR_PATH_NOT_FOUND

An invalid source or destination path string was passed.

ERROR_ACCESS_DENIED

You do not have permission to delete the existing copy of the destination file, or the destination disk or directory is not writable.

ERROR_FILE_IN_USE

Some geode has the existing destination file open.

ERROR_SHORT_READ_WRITE

There was not enough room on the destination disk.

See Also: FileMove().

Include: file.h

FileCreate()

FileHandle 	FileCreate( /* sets thread's error value */
        const char		* name,				/* relative to working directory */
        FileCreateFlags		flags,				/* see below */
        FileAttrs		attributes);				/* FileAttrs of new file */

This routine creates a byte file. The file may be a DOS file or a GEOS byte file. If the file is successfully opened, FileCreate() will return the file's handle; otherwise, it will return a null handle and set the thread's error value.

The second parameter is a word-length FileCreateFlags record. The third parameter, attributes , describes the FileAttrs record to be set for the new file.

If successful, FileCreate() returns the file's handle. If it is unsuccessful, it returns a null handle and sets the thread's error value (accessible via ThreadGetError() ). The following error values are commonly returned:

ERROR_PATH_NOT_FOUND

A relative or absolute path was passed, and the path included a directory which did not exist.

ERROR_TOO_MANY_OPEN_FILES

There is a limit to how many files may be open at once. If this limit is reached, FileCreate() will fail until a file is closed.

ERROR_ACCESS_DENIED

Either the caller requested access which could not be granted (e.g. it requested write access when another geode had already opened the file with FILE_DENY_W), or the caller tried to deny access when that access had already been granted to another geode (e.g. it tried to open the file with FILE_DENY_W when another geode already had it open for write-access).

ERROR_WRITE_PROTECTED

The caller requested write or read-write access to a file in a write-protected volume.

ERROR_FILE_EXISTS

Returned if FileCreate() was called with FILE_CREATE_ONLY and a file with the specified name already exists.

ERROR_FILE_FORMAT_MISMATCH

Returned if FileCreate() was called with FILE_CREATE_TRUNCATE or FILE_CREATE_NO_TRUNCATE and a file exists in a different format than desired; i.e. you passed FCF_NATIVE and the file already exists in the GEOS format, or vice versa.

Examples: An example of usage is shown below.

Example of FileCreate() usage

/* Here we create a DOS file in the current working directory. If the file already
 * exists, we open the existing file and truncate it.
 */

	FileHandle		newFile;

	newFile = 		FileCreate("NEWFILE.TXT",
					( (FILE_CREATE_TRUNCATE | FCF_NATIVE)
					 | (FILE_ACCESS_RW | FILE_DENY_RW)),
					0); /* set no attribute bits */

See Also: FileCreateTempFile(), FileOpen().

Include: file.h

FileCreateDir()

word	FileCreateDir( /* Returns error & sets thread's error value */
        const char * name);				/* Relative path of new directory */

This routine creates a new directory. The parameter is a path string; the path is relative to the current directory. The last element of the path string must be the directory to create.

If FileCreateDir() is successful, it returns zero and clears the thread's error value. Otherwise, it returns an error code and sets the thread's error value (accessible via ThreadGetError() ). The following errors are returned:

ERROR_PATH_TOO_LONG

The path string was longer than is permitted by the file system for that device.

ERROR_FILE_EXISTS

A file or directory with the specified name already exists at the specified location.

ERROR_INVALID_NAME

The name passed was inappropriate for directories on that device.

ERROR_DISK_STALE

The drive that disk was on has been removed.

ERROR_DISK_UNAVAILABLE

The validation of the disk in that drive was aborted by the user.

ERROR_PATH_NOT_FOUND

The path string was in some way invalid; for example, it might have instructed FileCreateDir() to create the directory within a directory which does not exist.

ERROR_ACCESS_DENIED

The thread is not able to create directories in the specified location, or a directory with the specified name already exists.

ERROR_WRITE_PROTECTED

The volume is write-protected.

See Also: FileDeleteDir().

Include: file.h

FileCreateTempFile()

FileHandle FileCreateTempFile( /* Sets thread's error value */
        char		* dir,		/* directory, relative to working dir.;
					 * file name replaces 14 trailing null
					 * characters upon return */

        FileCreateFlags		flags,
        FileAttrs		attributes);

This routine creates and opens a temporary file in the directory specified. The routine automatically selects a name for the temporary file. No creation flags are needed, since the file will definitely be created anew and will be used only by this geode. The directory string must end with fourteen null bytes (enough to be replaced by the new file's name).

If FileCreateTempFile() is successful, it returns the file's handle as well as the string passed in dir , with the trailing null characters replaced by the file name. If it is unsuccessful, it returns a null handle and sets the thread's error value to a member of the FileError enumerated type. (This error value is accessible via ThreadGetError() .)

Tips and Tricks: Temporary files are usually created in a subdirectory of SP_PRIVATE_DATA.

See Also: FileCreate().

Include: file.h

FileDelete()

word	FileDelete( /* returns error */
        const char * name);			/* path relative to working directory */

This routine deletes a file. If it is successful, it returns zero; otherwise, it returns a FileError . Common errors include:

ERROR_FILE_NOT_FOUND

No such file exists in the specified directory.

ERROR_WRITE_PROTECTED

The volume is write-protected.

ERROR_PATH_NOT_FOUND

An invalid path string was passed.

ERROR_ACCESS_DENIED

You do not have permission to delete that file.

ERROR_FILE_IN_USE

Some geode has that file open.

Include: file.h

FileDeleteDir()

word	FileDeleteDir( /* Returns error & sets thread's error value */
        const char * name);			/* Relative path of directory to delete */

This argument deletes an existing directory. The parameter is a string which specifies the directory's position relative to the current working directory. The last element of the path string must be the name of the directory to delete.

If FileDeleteDir() is successful, it returns zero and clears the thread's error value. Otherwise, it returns an error code and sets the thread's error value (accessible via ThreadGetError() ). The following errors are returned:

ERROR_PATH_NOT_FOUND

The directory specified could not be found or does not exist.

ERROR_IS_CURRENT_DIRECTORY

This directory is some thread's current directory, or else it is on some thread's directory stack.

ERROR_ACCESS_DENIED

The thread does not have permission to delete the directory.

ERROR_WRITE_PROTECTED

The volume is write-protected.

ERROR_DIRECTORY_NOT_EMPTY

The directory specified is not empty. A directory must be empty before it can be deleted.

See Also: FileCreateDir().

Include: file.h

FileDuplicateHandle()

FileHandle FileDuplicateHandle( /* Sets thread's error value */
        FileHandle fh);

This routine duplicates the handle of an open file and returns the duplicate handle. The duplicate handle has the same read/write position as the original. Both handles will have to be closed for the file to be closed. If there is an error, FileDuplicateHandle() returns a null handle and sets the thread's error value (accessible via ThreadGetError() ).

Include: file.h

FileEnum()

word	FileEnum( /* returns number of files returned */
        FileEnumParams		* params,			/* described below */
        MemHandle		* bufCreated,			/* FileEnum will allocate a return-
						 * buffer block & write its handle
						 * here */

        word		* numNoFit);				/* Number of files not handled is
						 * written here */

This routine is used to examine all the files in a directory. The routine can filter the files by whether they have certain extended attributes. It creates a buffer and writes information about the files in this buffer. This routine can be called in many different ways; full details are available.

Structures: FileEnum() uses several structures and enumerated types. They are shown below; the detailed description of the structures follows.

        	/* Types, values, and structures passed
 * to the FileEnum() routine: */

        typedef enum /* word */ {
FESRT_COUNT_ONLY,
FESRT_DOS_INFO,
FESRT_NAME,
FESRT_NAME_AND_ATTR

        } FileEnumStandardReturnType;
        typedef enum /* word */ {
FESC_WILDCARD

        } FileEnumStandardCallback;
        	/* Types, values, and structures returned
 * by the FileEnum() routine: */

        typedef struct {
FileAttrs 			DFIS_attributes;
FileDateAndTime 			DFIS_modTimeDate;
dword 			DFIS_fileSize;
FileLongName 			DFIS_name;
DirPathInfo 			DFIS_pathInfo;

        } FEDosInfo;
        typedef struct _FileEnumCallbackData {
FileExtAttrDesc 			FECD_attrs[1];

        } FileEnumCallbackData;
        typedef struct _FileEnumParams {
FileEnumSearchFlags 				FEP_searchFlags;
FileExtAttrDesc *				FEP_returnAttrs;
word 				FEP_returnSize;
FileExtAttrDesc *				FEP_matchAttrs;
word 				FEP_bufSize;
word 				FEP_skipCount;
word _pascal (*FEP_callback) 						(struct _FileEnumParams *params,
						 FileEnumCallbackData *fecd, 
						 word frame);
FileExtAttrDesc *				FEP_callbackAttrs;
dword 			FEP_cbData1;
dword 			FEP_cbData2;
word 			FEP_headerSize;

        } FileEnumParams;

Most of the information passed to FileEnum() is contained in a FileEnumParams structure. The fields of the structure are as follows:

FEP_searchFlags

This is a byte-length flag field. The flags are of type FileEnumSearchFlags (described below). These flags specify which files at the current location will be examined by FileEnum() . They also specify such things as whether a callback routine should be used.

FEP_returnAttrs

This is a pointer to an array of FileExtAttrDesc structures. The last structure should have its FEA_attr field set to FEA_END_OF_LIST. The array specifies what information will be returned by FileEnum() . The FileExtAttrDesc structure is used in a slightly different way than usual. Every file will have an entry in the return buffer; this entry will contain all the extended attribute information requested. Each FileExtAttrDesc structure will specify where in that entry its information should be written. The FEAD_value field should contain only an offset value; the extended attribute will be written at that offset into the entry. (You can specify an offset by casting an integer value to type void * .) The FEAD_size value specifies how long the return value can be. You can also request certain return values by setting FEP_returnAttrs to equal a member of the FileEnumStandardReturnType (again, by casting the FileEnumStandardReturnType value to type void * ). The FileEnumStandardReturnType enumerated type is described later in this section.

FEP_returnSize

This is the size of each entry in the returned buffer. If a standard return type or an array of FileExtAttrDesc structures was passed, each entry in the returned buffer will contain all the extended attribute information requested for that file.

FEP_matchAttrs

This is a pointer to an array of FileExtAttrDesc structures. The last structure should have its FEA_attr field set to FEA_END_OF_LIST. FileEnum() will automatically filter out and ignore all files whose attributes do not match the ones specified by this array. For attributes that are word-sized records, FEAD_value.offset holds the bits that must be set, and FEAD_value.segment holds the bits that must be clear. For byte-sized flags, FEAD_value.offset.low contains the flags that must be set, and FEAD_value.offset.high contains flags that must be clear. Byte- and word-sized non-flag values are stored in FEAD_value.offset . For all other values, FEAD_value holds a pointer to the exact value to match, and FEAD_size specifies the length of that value (in bytes). If you do not want to filter out any files in the working directory, or if you will use the callback routine to filter the files, pass a null pointer in this field.

FEP_bufS

ize
This specifies the maximum number of entries to be returned in the buffer. If you do not want to set a limit, pass the constant FE_BUFSIZE_UNLIMITED. The buffer will be grown as necessary.

FEP_skipCount

This contains the number of matching files to be ignored before the first one is processed. It is often used in conjunction with FEP_bufSize to examine many files a few at a time. For example, if you only wanted to examine ten files at a time, you would set FEP_bufSize to ten and FEP_skipCount to zero. FileEnum() would return the data for the first ten files which match the search criteria. After processing the returned data, if there were any files left over, you could call FileEnum() again, this time with FEP_skipCount set to ten; FileEnum() would handle the next ten matching files and return the data about them. In this way you could walk through all the matching files in the directory. Note that if the FileEnumSearchFlags bit FESF_REAL_SKIP is set (in FEP _searchFlags ), the first files in the directory will be skipped before they are tested to see if they match. This is faster, since the match condition won't have to be checked for the first files in the directory.

FEP_callback

This holds a pointer to a Boolean callback routine. The callback routine can check to see if the file matches some other arbitrary criteria. The callback routine is called for any files which match all the above criteria. It should be declared _pascal. It is passed three arguments: a pointer to the FileEnumParams structure, a pointer to the current stack frame (which is used by some assembly callback routines), and a pointer to an array of FileExtAttrDesc structures. These structures are all the attributes required either for return, matching, or callback (see FEP _callbackAttrs below), with the information for the current file filled in; you can search through them directly for the information you want, or you can call FileEnumLocateAttr() to search through this array. If the file should be accepted by FileEnum() , the callback should return true ; otherwise it should return false . You can also instruct FileEnum() to use one of the standard callback routines by passing a member of the FileEnumStandardCallback enumerated type. In this case, FEP_callbackAttrs is ignored; FileEnum() will automatically pass the appropriate information to the callback routine. (Note that if the FESF_CALLBACK bit of the FEP_searchFlags field is not set, the FEP_callback field is ignored.)

FEP_callbackAttrs

This is a pointer to an array of FileExtAttrDesc structures. The last structure should have its FEA_attr field set to FEA_END_OF_LIST. The array will be filled in with the appropriate information for each file before the callback routine is called. Note that if the FESF_CALLBACK bit of the FEP_searchFlags is not set, the FEP_callbackAttrs is ignored. If you do not need any attributes passed to the callback routine, set this field to be a null pointer.

FEP_cbData1 , FEP_cbData2

These are dword-length fields. Their contents are ignored by FileEnum() ; they are used to pass information to the callback routine. If you do not call a standard callback routine, you may use these fields any way you wish.

FEP_headerSize

If the flag FESF_LEAVE_HEADER is set, FileEnum() will leave an empty header space at the beginning of the return buffer. The size of the header is specified by this field. If FESF_LEAVE_HEADER is clear, this field is ignored.

The first field of the FileEnumParams structure, FEP_searchFlags , is a word-length record containing FileEnumSearchFlags . The following flags are available:

FESF_DIRS

Directories should be examined by FileEnum() .

FESF_NON_GEOS

Non-GEOS files should be examined by FileEnum() .

FESF_GEOS_EXECS

GEOS executable files should be examined by FileEnum() .

FESF_GEOS_NON_EXECS

GEOS non-executable files (e.g., VM files) should be examined by FileEnum() .

FESF_REAL_SKIP

If a skip count of n is specified, the first n files will be skipped regardless of whether they matched the attributes passed. In this case, FileEnum() will return the number of files passed through in order to get enough files to fill the buffer; the return value can thus be the real-skip count for the next pass.

FESF_CALLBACK

FileEnum() should call a callback routine to determine whether a file should be accepted.

FESF_LOCK_CB_DATA

This flag indicates that the FileEnumParams fields FEP_callback1 and FEP_callback2 are far pointers to movable memory that must be locked before FileEnum() is called.

FESF_LEAVE_HEADER

If set, FileEnum() should leave an empty header space at the start of the return buffer. The size of this buffer is specified by the FEP_headerSize field.

The FileEnumStandardReturnType enumerated type has the following values; they are used in conjunction with the FEP_returnAttrs field of the FileEnumParams structure.

FESRT_COUNT_ONLY

FileEnum() will not allocate any memory and will not return data about files; instead, it will simply return the number of files which match the specified criteria.

FESRT_DOS_INFO

FileEnum() will return an array of FEDosInfo structures. These structures contain basic information about the file: its virtual name, size, modification date, DOS attributes, and path information (as a DirPathInfo record).

FESRT_NAME

FileEnum() will return an array of FileLongName strings, each one of which is FILE_LONGNAME_BUFFER_SIZE characters long; every one of these will contain a file's virtual name followed by a null terminator.

FESRT_NAME_AND_ATTR

FileEnum() will return an array of FENameAndAttr structures, each one of which contains a file's DOS attributes and virtual name.

The FEDosInfo structure includes a word-sized record ( DFIS_pathInfo ) which describes the file's position relative to the standard paths. It contains the following fields:

DPI_EXISTS_LOCALLY

This bit is set if the file exists in a directory under the primary tree.

DPI_ENTRY_NUMBER_IN_PATH

This is the mask for a seven-bit field whose offset is DPI_ENTRY_NUMBER_IN_PATH_OFFSET.

DPI_STD_PATH

This is the mask for an eight-bit field whose offset is DPI_STD_PATH_OFFSET. If the file is in a standard path, this field will contain a StandardPath constant for a standard path containing the file. This need not be the "closest" standard path; for example, if the file is in the "World" directory, this constant might nevertheless be SP_TOP.

See Also: FileEnumLocateAttr(), FileEnumWildcard().

Include: fileEnum.h

FileEnumLocateAttr()

void *	FileEnumLocateAttr( /* returns NULL if attr not found */
        FileEnumCallbackData*			fecd,		/* Passed to callback routine */
        FileExtendedAttribute			attr,		/* Search for this attribute */
        const char *			* name);			/* Attribute name (if second
						 * argument is FEA_CUSTOM) */

FileEnum() can be instructed to call a callback routine to decide which files to filter out. This callback routine is passed an array of FileExtAttrDesc structures. To find a particular extended attribute in this array, call FileEnumLocateAttr() . This routine will find the address of the value of the attribute desired, and return that address. If the attribute is not in the array, FileEnumLocateAttr() will return a null pointer.

Include: fileEnum.h

FileEnumWildcard()

Boolean	FileEnumWildcard(
        FileEnumCallbackData			* fecd,			/* Passed to callback routine */
        word			frame);			/* Inherited stack frame */

This routine is a utility used by FileEnum() and is rarely used by applications. It checks to see if the virtual name of the current file (the file currently being evaluated by FileEnum() ) matches the pattern in the FEP_cbData1 field of the FileEnumParams structure.

The fecd parameter is a pointer to the callback data of the FileEnum() routine. The frame parameter is a pointer to the FileEnum() stack frame: The first dword is the FEP_cbData1 field, and the second is the FEP_cbData2 field.

This routine returns true (non-zero) if the file name and pattern match. Otherwise, it returns false .

Include: fileEnum.h

FileFromTransferBlockID()

VMFileHandle	 FileFromTransferBlockID(id);
        TransferBlockID id;

This macro extracts a VMFileHandle from a value of type TransferBlockID .

FileGetAttributes()

FileAttrs 	FileGetAttributes( /* Sets thread's error value */
        const char * path);			/* file's path relative to current
			 * working directory */

This routine returns the standard FileAttrs attributes for a file. The file may be a GEOS file or a plain DOS file. Note that you can also get a file's attributes by getting the file's FEA_FILE_ATTR extended attribute. If an error occurs, this routine sets the thread's error (accessible via ThreadGetError() ).

See Also: FileAttrs, FileSetAttributes().

Include: file.h

FileGetCurrentPath()

DiskHandle FileGetCurrentPath(
        char *	buffer,			/* Path string is written here */
        word	bufferSize);			/* Size of buffer in bytes */

This routine writes the current path string (without drive specifier) to the buffer provided. If the buffer is too small, it truncates the path to fit. It returns the handle of the disk containing the current path. If the current path was declared relative to a standard path, the standard path constant will be returned.

Include: file.h

FileGetDateAndTime()

FileDateAndTime 	FileGetDateAndTime( /* sets thread's error value */
        FileHandle fh);

This routine finds out the time a file was last modified. This routine can be called on GEOS or non-GEOS files. Note that you can also find out the modification time of a file by checking the extended attribute FEA_MODIFICATION. If unsuccessful, it sets the thread's error value (accessible via ThreadGetError() ).

See Also: FileDateAndTime, FileSetDateAndTime().

Include: file.h

FileGetDiskHandle()

DiskHandle FileGetDiskHandle( /* sets thread's error value */
        FileHandle fh);

This routine returns the handle of the disk containing an open file. If unsuccessful, it sets the thread's error value (accessible via ThreadGetError() ).

Include: file.h

FileGetHandleExtAttributes()

word	FileGetHandleExtAttributes(
        FileHandle			fh,				/* open file's handle */
        FileExtendedAttribute			attr,				/* attribute to get */
        void			* buffer,				/* attribute is written here */
        word			bufSize);				/* length of buffer in bytes */

This routine gets one or more extended attributes of an open file. (To get the attributes of a file without opening it, call FileGetPathExtAttributes() .) If a single attribute is requested, the attribute will be written in the buffer passed. If several attributes are requested, attr should be set to FEA_MULTIPLE, and buffer should point to an array of FileExtAttrDesc structures. In this case, bufSize should be the number of structures in the buffer, not the length of the buffer.

If FileGetHandleExtAttributes() is successful, it returns zero. Otherwise, it returns one of the following error codes:

ERROR_ATTR_NOT_SUPPORTED

The file system does not recognize the attribute constant passed.

ERROR_ATTR_SIZE_MISMATCH

The buffer passed was too small for the attribute requested.

ERROR_ATTR_NOT_FOUND

The file does not have a value set for that attribute.

ERROR_ACCESS_DENIED

You do not have read-access to the file.

Tips and Tricks: Note that the only way to recover a custom attribute is by passing FEA_MULTIPLE, and using a FileExtAttrDesc to describe the attribute.

See Also: FileGetPathExtAttributes().

Include: file.h

FileGetPathExtAttributes()

word	FileGetPathExtAttributes(
        const char			* path,				/* path relative to current
							 * working directory */

        FileExtendedAttribute			attr,				/* attribute to get */
        void			* buffer,				/* attribute is written here */
        word			bufSize);				/* length of buffer in bytes */

This routine gets one or more extended attributes of a GEOS file. If a single attribute is requested, the attribute will be written in the buffer passed. If several attributes are requested, attr should be set to FEA_MULTIPLE, and buffer should point to an array of FileExtAttrDesc structures. In this case, bufSize should be the number of structures in the buffer, not the length of the buffer.

If FileGetPathExtAttributes() is successful, it returns zero. Otherwise, it returns one of the following error codes:

ERROR_ATTR_NOT_SUPPORTED

The file system does not recognize the attribute constant passed.

ERROR_ATTR_SIZE_MISMATCH

The buffer passed was too small for the attribute requested.

ERROR_ATTR_NOT_FOUND

The file does not have a value set for that attribute.

ERROR_ACCESS_DENIED

You do not have read-access to the file.

Tips and Tricks: Note that the only way to recover a custom attribute is by passing FEA_MULTIPLE, and using a FileExtAttrDesc to describe the attribute.

See Also: FileGetHandleExtAttributes().

Include: file.h

FileLockRecord()

word	FileLockRecord( /* returns error */
        FileHandle		fh,
        dword		filePos,			/* lock starting at this position... */
        dword		regLength);				/* lock this many bytes */

This routine puts a lock on a part of a byte file. It first checks to make sure that there are no locks that overlap the region specified; if there are, it will fail and return ERROR_ALREADY_LOCKED. If there are no locks, it will place a lock on the region specified and return zero.

Warnings: Locking a region only prevents threads from locking part of the same region; it does not prevent them from reading from or writing to the region. If applications use this mechanism, they have to make sure to call FileLockRecord before trying to access a part of a file.

See Also: FileUnlockRecord(), HandleP().

FileMove()

word	FileMove( /* Returns error */
        const char		* source,				/* source path and file name */
        const char		* dest,				/* destination path and file name */
        DiskHandle		sourceDisk,				/* These handles may be Standard */
        DiskHandle		destDisk);				/* Path constants, or null to indi- 
						 * cate current working directory */

This routine moves a file from one location to another. The source and destination are specified with path strings. Each string specifies a path relative to the location specified by the corresponding disk handle. If the handle is a disk handle, the path is relative to that disk's root. If the disk handle is a standard path constant, the path string is relative to that standard path. If the disk handle is null, the path is relative to the current working directory.

If FileMove() is successful, it returns zero. Otherwise, it returns one of the following error codes and sets the thread's error value.

ERROR_FILE_NOT_FOUND

No such source file exists in the specified directory.

ERROR_PATH_NOT_FOUND

An invalid source or destination path string was passed.

ERROR_ACCESS_DENIED

You do not have permission to delete the source file, or there is already a file with the same name as the destination file (and you do not have permission to delete it), or the destination disk or directory is not writable.

ERROR_FILE_IN_USE

Either the source file is in use, or there is already a file with the same name as the destination file, and it is in use.

ERROR_SHORT_READ_WRITE

There was not enough room on the destination disk.

See Also: FileCopy().

Include: file.h

FileOpen()

FileHandle FileOpen( /* sets thread's error value */
        const char		* name,			/* relative to working dir */
        FileAccessFlags		flags);			/* Permissions/exclusions */

This routine opens a file for bytewise access. The file may be a DOS file or a GEOS byte file. If the file is successfully opened, FileOpen() will return the file's handle; otherwise, it will return a null handle and set the thread's error value (accessible via ThreadGetError() ). Errors typically set by this routine are listed below:

ERROR_FILE_NOT_FOUND

No file with the specified name could be found in the appropriate directory.

ERROR_PATH_NOT_FOUND

A relative or absolute path had been passed, and the path included a directory which did not exist.

ERROR_TOO_MANY_OPEN_FILES

There is a limit to how many files may be open at once. If this limit is reached, FileOpen() will fail until a file is closed.

ERROR_ACCESS_DENIED

Either the caller requested access which could not be granted (e.g. it requested write access when another geode had already opened the file with FILE_DENY_W), or the caller tried to deny access when that access had already been granted to another geode (e.g. it tried to open the file with FILE_DENY_W when another geode already had it open for write-access).

ERROR_WRITE_PROTECTED

The caller requested write or read-write access to a file in a write-protected volume.

See Also: FileCreate(), FileAccessFlags.

Include: file.h

FileParseStandardPath()

StandardPath FileParseStandardPath(
        DiskHandle		disk,
        const char		** path);

This routine is passed a full path (relative to the passed disk or a standard path, if the disk handle is null) and finds the standard path which most closely contains that path. It updates the pointer whose address is passed so that it points to the trailing portion of the path string. For example, if you pass the path string "\GEOWORKS\DOCUMENT\MEMOS\APRIL", the pointer would be updated to point to the "\MEMOS\APRIL" portion, and the StandardPath SP_DOCUMENT would be returned. If the path passed does not belong to a standard path, the constant SP_NOT_STANDARD_PATH will be returned, and the pointer will not be changed.

Include: file.h

FilePopDir()

void	FilePopDir();

FilePopDir() pops the top directory off the thread's directory stack and makes it the current working directory.

See Also: FilePushDir().

Include: file.h

FilePos()

dword	FilePos( /* Sets thread's error value */
        FileHandle		fh,
        dword		posOrOffset,
        FilePosMode		mode);

This routine changes the current file position. The position can be specified in three ways, depending on the value of the mode argument:

FILE_POS_START

The file position is set to a specified number of bytes after the start of the file. Passing this mode with an offset of zero will set the file position to the start of the file.

FILE_POS_RELATIVE

The file position is incremented by a specified number of bytes; this number may be negative.

FILE_POS_END

The file position is set to a specified number of bytes after the end of the file; it is usually passed with a negative number of bytes. Passing this mode with an offset of zero will set the file position to the end of the file.

FilePos() returns a 32-bit integer. This integer specifies the absolute file position after the move (relative to the start of the file). On an error, it sets the thread's error value (accessible via ThreadGetError() ).

Tips and Tricks: To find out the current file position without changing it, call FilePos() with mode FILE_POS_RELATIVE and offset zero.

Include: file.h

FilePushDir()

void	FilePushDir();

FilePushDir() pushes the current working directory onto the thread's directory stack. It does not change the current working directory.

See Also: FilePopDir().

Include: file.h

FileRead()

word	FileRead(
        FileHandle		fh,			/* handle of open file */
        void		* buf,			/* copy data to this buffer */
        word		count,			/* Length of buffer (in bytes) */
        Boolean		noErrorFlag);					/* Set if app can't
							 * handle errors */

This routine copies data from a file into memory. It starts copying from the current position in the file. If possible, it will copy enough data to fill the buffer. If FileRead() is successful, it returns the number of bytes copied. If an error occurs, FileRead() returns -1 and sets the thread's error value (usually to ERROR_ACCESS_DENIED). The current file position will be changed to the first byte after the ones which were read.

In C, there is no way to determine whether an ERROR_SHORT_READ_WRITE error occurs. To check whether all of the data was actually copied into memory, you must compare the number of bytes actually read with the number requested to be read. If your read operation requires multiple FileRead() operations, you may should read until zero bytes are returned.

To retrieve the thread error value, use ThreadGetError() .

If the argument noErrorFlag is set to true (i.e. non-zero), FileRead() will fatal-error if an error occurs (including an ERROR_SHORT_READ_WRITE).

Warnings: Pass noErrorFlag true only during debugging.

Include: file.h

FileRename()

word	FileRename(
        const char * oldName,				/* Relative to working directory */
        const char * newName);				/* Name only, without path */

This routine changes a file's name. It cannot move a file to a different directory; to do that, call FileMove() . If the routine is successful, it returns zero; otherwise, it returns a FileError . Common errors include

ERROR_FILE_NOT_FOUND

No such file exists in the specified directory.

ERROR_PATH_NOT_FOUND

An invalid path string was passed.

ERROR_ACCESS_DENIED

You do not have permission to delete that file, or it exists on a read-only volume.

ERROR_FILE_IN_USE

Some geode has that file open.

ERROR_INVALID_NAME

The name was not a valid GEOS name; or the file is a non-GEOS file, and the name was not an appropriate native name.

See Also: FileMove().

Include: file.h

FileResolveStandardPath()

DiskHandle FileResolveStandardPath(
        char		** buffer,				/* Write path here; update pointer
						 * to point to end of path */

        word		bufSize,				/* Size of buffer (in bytes) */
        const char *		path,				/* Relative path of file */
        FileResolveStandardPathFlags flags,							/* Flags are described below */
        FileAttrs *attrsPtr);							/* Empty buffer, will be filled with attrs of passed file, if any */

This routine finds a file relative to the current location, then writes the full path to the file, starting at the root of the disk ( not at a standard path). It writes the path to the passed buffer, updating the pointer to point to the null at the end of the path string; it also returns the handle of the disk. If it cannot find the file it returns a null path.

Structures: A record of FileResolveStandardPathFlags is passed to FileResolveStandardPath() . The following flags are available:

FRSPF_ADD_DRIVE_NAME

The path string written to the buffer should begin with the drive name (e.g., "C:\GEOWORKS\DOCUMENT\MEMOS").

FRSPF_RETURN_FIRST_DIR

FileResolveStandardPath() should not check whether the passed path actually exists; instead, it should assume that the path exists in the first directory comprising the standard path, and return accordingly.

Include: file.h

FileSetAttributes()

word	FileSetAttributes( /* returns error value */
        const char		* path,			/* file's path relative to current
					 * working directory */

        FileAttrs		attr);			/* new attributes for the file */

This routine changes the standard DOS attributes of a DOS or GEOS file. Note that you can also change the attributes of a file by setting the extended attribute FEA_FILE_ATTR.

See Also: FileAttrs, FileGetAttributes().

Include: file.h

FileSetCurrentPath()

DiskHandle FileSetCurrentPath(
        DiskHandle		disk,			/* May be a standard path constant */
        const char		* path);			/* path string, null-terminated */

This routine changes the current path. It is passed two parameters: The first is the handle of the disk containing the new current path (this may be a standard path constant). The second is a null-terminated path string. It is specified with normal DOS conventions: directories are separated by backslashes; a period (".") indicates the current directory; and a pair of periods ("..") indicates the parent of the current directory. The string may not contain wildcard characters.

If disk is a disk handle, the path is relative to the root directory of that disk; if disk is a standard path constant, the path is relative to the standard path; if it is null, the path is relative to the current working directory. FileSetCurrentPath() returns the disk handle associated with the new current path; this may be a standard path constant. If FileSetCurrentPath() fails, it returns a null handle.

See Also: FileSetStandardPath().

Include: file.h

FileSetDateAndTime()

word	FileSetDateAndTime( /* returns error */
        FileHandle		fh,					/* handle of open file */
        FileDateAndTime		dateAndTime);					/* new modification time */

This routine changes a file's last-modification time-stamp. This routine can be called on GEOS or non-GEOS files. Note that you can also change the modification time of a file by changing the extended attribute FEA_MODIFICATION. If unsuccessful, this routine returns an error and sets the thread's error value (accessible via ThreadGetError() ).

See Also: FileDateAndTime, FileGetDateAndTime().

Include: file.h

FileSetHandleExtAttributes()

word	FileGetPathExtAttributes( /* returns error */
        FileHandle			fh,			/* handle of open file */
        FileExtendedAttribute		 	attr,			/* attribute to get */
        const void			* buffer,			/* attribute is read from here */
        word			bufSize);			/* length of buffer in bytes */

This routine sets one or more extended attributes of an open GEOS file. (To set the attributes of a file without opening it, call FileSetPathExtAttributes() .) If a single attribute is specified, the attribute's new value will be read from the buffer passed. If several attributes are to be changed, attr should be set to FEA_MULTIPLE, and buffer should point to an array of FileExtAttrDesc structures. In this case, bufSize should be the number of structures in the buffer, not the length of the buffer.

If FileSetHandleExtAttributes() is successful, it returns zero. Otherwise, it sets the thread's error value (accessible via ThreadGetError() ) and returns one of the following error codes:

ERROR_ATTR_NOT_SUPPORTED

The file system does not recognize the attribute constant passed.

ERROR_ATTR_SIZE_MISMATCH

The buffer passed was the wrong size for the attribute specified.

ERROR_ACCESS_DENIED

The caller does not have write-access to the file.

ERROR_CANNOT_BE_SET

The extended attribute cannot be changed. Such attributes as FEA_SIZE and FEA_NAME cannot be changed with the FileSet...() routines.

Tips and Tricks: Note that the only way to create or change a custom attribute is by passing FEA_MULTIPLE, and using a FileExtAttrDesc to describe the attribute.

See Also: FileSetPathExtAttributes().

Include: file.h

FileSetPathExtAttributes()

word	FileSetPathExtAttributes(
        const char			* path,			/* path relative to current
						 * working directory */

        FileExtendedAttribute			 attr,			/* attribute to get */
        const void			* buffer,			/* attribute is read from here */
        word			bufSize);			/* length of buffer in bytes */

This routine sets one or more extended attributes of a file. If a single attribute is specified, the attribute will be written in the buffer passed. If several attributes are to be changed, attr should be set to FEA_MULTIPLE and buffer should point to an array of FileExtAttrDesc structures. In this case, bufSize should be the number of structures in the buffer, not the length of the buffer.

If FileSetPathExtAttributes() is successful, it returns zero. Otherwise, it sets the thread's error value (accessible via ThreadGetError() ) and returns one of the following error codes:

ERROR_ATTR_NOT_SUPPORTED

The file system does not recognize the attribute constant passed.

ERROR_ATTR_SIZE_MISMATCH

The buffer passed was the wrong size for the attribute specified.

ERROR_ACCESS_DENIED

FileSetPathExtAttributes() returns this if any geode (including the caller) has the file open with "deny-write" exclusive access, or if the file is not writable.

ERROR_CANNOT_BE_SET

The extended attribute cannot be changed. Such attributes as FEA_SIZE and FEA_NAME cannot be changed with the FileSet...ExtAttributes() routines.

Tips and Tricks: Note that the only way to create or change a custom attribute is by passing FEA_MULTIPLE, and using a FileExtAttrDesc to describe the attribute.

See Also: FileSetHandleExtAttributes().

Include: file.h

FileSetStandardPath()

void	FileSetStandardPath(
        StandardPath path);			/* StandardPath to set */

This routine changes the current working directory to one of the system's StandardPath directories. Pass a standard path.

Include: file.h

FileSize()

dword	FileSize(
        FileHandle fh);		/* handle of open file */

This routine returns the size of the open file specified.

Include: file.h

FileTruncate()

word	FileTruncate(
        FileHandle		fh,			/* handle of open file */
        dword		offset,			/* offset at which to truncate */
        Boolean		noErrorFlag); 

This routine truncates the specified file at the passed offset. The offset parameter can also be thought of as the desired file size. If the high bit of noErrorFlag is one, then no errors will be returned.

Include: file.h

FileUnlockRecord()

word	FileUnlockRecord( /* returns error */
        FileHandle		fh,				/* handle of open file
        dword		filePos,				/* Release lock that starts here */
        dword		regLength);				/* and is this long */

This routine releases a lock on a part of a byte-file. The lock must have been previously placed with FileLockRecord() .

See Also: FileLockRecord(), HandleV().

Include: file.h

FileWrite()

word	FileWrite( /* sets thread's error value */
        FileHandle		fh,				/* handle of open file */
        const void		* buf,				/* Copy from here into file */
        word		count,				/* # of bytes to copy */
        Boolean		noErrorFlag);				/* Set if can't handle errors */

This routine copies a specified number of bytes from a buffer to the file. The bytes are written starting with the current position in the file; any data already at that location will be overwritten. FileWrite() returns the number of bytes written. If FileWrite() could not write all the data (e.g. if the disk ran out of space), it will set the thread's error value (accessible via ThreadGetError() ) to ERROR_SHORT_READ_WRITE and return the number of bytes that were written. If it could not write the data to the file at all (e.g. if you do not have write-access to the file), it will return -1 and set the thread's error value to ERROR_ACCESS_DENIED. In any event, the file position will be changed to the first byte after the ones written.

If the argument noErrorFlag is set to true (i.e. non-zero), FileWrite() will fatal-error if an error occurs.

Warnings: Pass noErrorFlag true only during debugging.

Include: file.h

FloatAsciiToFloat()

Boolean	FloatAsciiToFloat( /* returns FALSE on success */
        word floatAtoFflags, 
        word stringLength,
        void *string, 
        void *resultLocation);

This routine is used to convert an ASCII string to a floating point number. It takes the following arguments:

floatAtoFflags

This FloatAsciiToFloatFlags field determines what will be done with the generated floating point number. At most one flag may be set. If FAF_PUSH_RESULT is set, then the number will be pushed on the floating-point stack. If the FAF_STORE_NUMBER flag is set, the number will be returned at the resultLocation address.

stringLength

This is the length of the buffer passed in string.

string

This buffer contains the ASCII string to convert. The string should be of the format "[|+|-] dddd.dddd [|E|e] [|+|-] dddd". The string is assumed to be legal. There may be at most a single decimal point. Spaces and thousands separators are ignored.

resultLocation

If you pass the FAF_STORE_NUMBER flag, the buffer pointed to by resultLocation will be filled with the floating point number. This buffer should be at least five words long.

FloatFloatToAscii()

word	FloatFloatToAscii( /* returns # of chars in ASCII string */
        FFA_stackFrame 		*stackFrame, 
        char 		*resultString,
        FloatNum 		*number);

This routine converts a floating point number to an ASCII string. It uses a complicated data structure, FFA_stackFrame . To convert floating point numbers to ASCII without filling in this structure, use the FloatFloatToAscii_StdFormat() routine instead. Unless a special flag is passed, this routine will convert the top number of the floating point stack and pop it. FloatFloatToAscii() takes the following arguments:

stackFrame

This is an FFA_stackFrame structure. This structure contains a structure of parameters to FloatFloatToAscii() ; also, the routine will return some information in this structure. The structure is discussed in detail below.

resultString

Pointer to a buffer which will hold the generated ASCII string. This buffer must be either FLOAT_TO_ASCII_NORMAL_BUF_LEN or FLOAT_TO_ASCII_HUGE_BUF_LEN bytes, depending on the type of number (see below).

number

Specifies the format of the floating number. If it is FFAF_DONT_USE_SCIENTIFIC then the buffer resultString must be FLOAT_TO_ASCII_HUGE_BUF_LEN bytes long; otherwise, it must be FLOAT_TO_ASCII_NORMAL_BUF_LEN bytes.

If you pass the FFAF_FROM_ADDR flag, then instead of converting the number at the head of the floating-point stack, the routine will convert this number.

typedef union {
	FloatFloatToAsciiData  	 				FFA_float;
        FloatFloatToDateTimeData				FFA_dateTime;
} FFA_stackFrame; 
        
        typedef struct {
        	FloatFloatToAsciiParams FFA_params;
        	word                    FFA_startNumber;
        	word                    FFA_decimalPoint;
        	word                    FFA_endNumber;
        	word                    FFA_numChars;
        	word                    FFA_startExponent;
        	word                    FFA_bufSize;
        	word                    FFA_saveDI;
        	word                    FFA_numSign;
        	byte                    FFA_startSigCount;
        	byte                    FFA_sigCount;
        	byte                    FFA_noMoreSigInfo;
        	byte                    FFA_startDecCount;
        	byte                    FFA_decCount;
        	word                    FFA_decExponent;
        	word                    FFA_curExponent;
        	byte                    FFA_useCommas;
        	byte                    FFA_charsToComma;
        	char                    FFA_commaChar;
        	char                    FFA_decimalChar;
        } FloatFloatToAsciiData;

        typedef struct {
        	FloatFloatToAsciiFormatFlags 						formatFlags;
        	byte    						decimalOffset;
        	byte    						totalDigits;
        	byte    						decimalLimit;
        	char    						preNegative[SIGN_STR_LEN+1];
        	char    						postNegative[SIGN_STR_LEN+1];
        	char    						prePositive[SIGN_STR_LEN+1];
        	char    						postPositive[SIGN_STR_LEN+1];
        	char    						header[PAD_STR_LEN+1];
        	char    						trailer[PAD_STR_LEN+1];
        	byte    						FFTAP_unused;
        } FloatFloatToAsciiParams;

        typedef WordFlags FloatFloatToAsciiFormatFlags;
        #define FFAF_FLOAT_RESERVED 									0x8000
        #define FFAF_FROM_ADDR 									0x4000
        #define FFAF_DONT_USE_SCIENTIFIC 									0x0200
        #define FFAF_SCIENTIFIC 									0x0100
        #define FFAF_PERCENT 									0x0080
        #define FFAF_USE_COMMAS 									0x0040
        #define FFAF_NO_TRAIL_ZEROS 									0x0020
        #define FFAF_NO_LEAD_ZERO 									0x0010
        #define FFAF_HEADER_PRESENT 									0x0008
        #define FFAF_TRAILER_PRESENT 									0x0004
        #define FFAF_SIGN_CHAR_TO_FOLLOW_HEADER 									0x0002
        #define FFAF_SIGN_CHAR_TO_PRECEDE_TRAILER									0x0001

        typedef struct {
        	FloatFloatToDateTimeParams      FFA_dateTimeParams;
	} FloatFloatToDateTimeData;
        
        typedef struct {
                FloatFloatToDateTimeFlags 							FFA_dateTimeFlags;
                word    							FFA_year;
                byte 							FFA_month;
                byte 							FFA_day;
                byte 							FFA_weekday;
                byte 							FFA_hours;
                byte 							FFA_minutes;
                byte 							FFA_seconds;
        } FloatFloatToDateTimeParams;

        typedef WordFlags FloatFloatToDateTimeFlags;
        #define FFDT_DATE_TIME_OP 				0x8000
        #define FFDT_FROM_ADDR 				0x4000
        #define FFDT_FORMAT 				0x3fff