3 Routines
All routines in the kernel and the supplied libraries are listed alphabetically in the following sections. In many cases, data structures are listed with certain routines. Global data structures and data types are listed in the following chapter.
3.1 Routines A-D
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; this gives performance of ‘O(‘nlog’n). 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 preparatory 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 *);
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()**.
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.
See Also: Section 19.4.2.2 of the Concepts book
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, Section 19.4.2.2 of the Concepts book
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
See Also: Section 19.4.2.2 of the Concepts book
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(), Section 19.4.2.2 of the Concepts book
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(), Section 19.4.2.2 of the Concepts book
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(), ChunkArrayResize()
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(), ChunkArrayResize()
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(), ChunkArrayResize(), 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 callback routine, 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.
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).
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) (void *element, void *enumData));
/* Return TRUE to halt enumeration */ 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.
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) (void *element, void *enumData));
/* Return TRUE to halt enumeration */ This routine is exactly like **ChunkArrayEnumRange()**, except that the chunk array is specified by its global and chunk handles (instead of with an optr).
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(), ChunkArrayResize()
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; this gives performance of 'O('nlog'n)
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.
See Also: 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_CONCL UDED 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()
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: DBUnlock()
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_PERCT
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_PERCT
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 DiskCopyErrors 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 DiskFindResults 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)) 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. (See Section 17.3.2.2 of the Concepts book)
Include: disk.h
DiskFormat()
FormatError DiskFormat(
word driveNumber,
MediaType media, /* Format to this size */
word flags, /* See flags below */
dword *goodClusters, /* These are filled in at the */
dword *badClusters, /* end 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 FormatErrors 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.
Structures: The routine writes the information to a DiskInfoStruct:
typedef struct {
word DIS_blockSize;
sdword DIS_freeSpace;
sdword DIS_totalSpace;
VolumeName DIS_name;
} DiskInfoStruct;
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 DiskReturnError 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_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).
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 in the Data Structures reference.
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
Parameters File Keywords <– Table of Contents –> Routines E-F