2Assembly Routines

n	ArrayQuickSort

Sort the given array using a modified quicksort algorithm.

Pass: 	ds:si	Address of the first element in the array.

ax	Size of each element (all of uniform size).

cx	Number of elements in the array.

ss:bp	Address of an inheritable QuickSortParameters structure.

bx	Value to pass to callback routine specified in ss:bp.

Returns: 	Nothing.

Destroyed: 	ax, cx, dx

Library: 	chunkarr.def

n	CellDirty

Mark a cell as dirty.

Pass: 	es	Segment address of block containing the cell.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	cell.def

n	CellGetDBItem

Get the group and item numbers of the database item associated with the 
specified cell.

Pass: 	ds:si	Address of CellFunctionParameters structure.

ax	Row number of cell.

cl	Column number of cell.

Returns: 	CF	Set if the item exists, clear otherwise.

ax	Group number of the cell.

di	Item number of the cell.

Destroyed: 	Nothing.

Library: 	cell.def

n	CellGetExtent

Get the extent (bounds) of the current sheet of spreadsheet cells.

Pass: 	ds:si	Address of CellFunctionParameters structure.

ss:bx	Address of a RangeEnumParams structure. The caller 
does not need to set any values in the structure.

Returns: 	ss:bx	Address of the RangeEnumParams structure; the 
REP_bounds field will be filled in with the extent of the 
spreadsheet. If there is no current spreadsheet, all bounds 
will be set to -1.

Destroyed: 	Nothing.

Library: 	cell.def

n	CellLock

Lock a cell's data to examine or change it. The cell should not be locked while 
also working with other cells; the caller should lock the cell, copy the data, 
then unlock it with CellUnlock.

Pass: 	ds:si	Address of CellFunctionParameters structure.

ax	Row number of cell.

cl	Column number of cell.

Returns: 	CF	Set if the item exists, clear otherwise.

*es:di	Segment:chunk handle of the cell data if cell exists.

Destroyed: 	di, unless it is returned.

Library: 	cell.def

n	CellReplace

Replace a cell's data with new data.

Pass: 	ds:si	Address of CellFunctionParameters structure.

ax	Row number of cell.

cl	Column number of cell.

es:di	Address of new data.

dx	Size of data pointed to, or zero to free the cell.

Returns: 	Nothing.

Destroyed: 	Possibly es, if it pointed to a database item in the same file.

Library: 	cell.def

n	CellUnlock

Unlock a cell previously locked with CellLock.

Pass: 	es	Segment address of block containing cell data.

Returns: 	Nothing.

Destroyed: 	Normally, nothing. If using the error-checking kernel and segment 
error-checking is active, then if either DS or ES is pointing to a block that has 
become unlocked, that register will be set to NULL_SEGMENT.

Library: 	cell.def

n	CheckForDamagedES

When using the error-checking version of the ui, this routine checks the ES 
register to make sure it points to a valid LMem block. This comes in handy 
in code where *es:xx should point to an object.

In a non-error-checking environment, this routine does nothing.

Pass: 	es	Alleged local memory block handle.

Returns: 	Nothing (flags preserved as well).

Destroyed: 	Nothing.

Library: 	ui.def

n	ChunkArrayAppend

Append a new element to the end of a chunk array.

Pass: 	*ds:si	Segment:chunk handle of the chunk array.

ax	Size of new element, if variable-sized.

Returns: 	ds:di	Address of new, locked element.

Destroyed: 	Nothing.

Library: 	chunkarr.def

Warning:	This routine may resize or move the LMem block, invalidating all pointers to 
chunks or elements within it.

n	ChunkArrayCreate

Create a new general chunk array with no elements.

Pass: 	ds	Global handle of block for new array.

bx	Element size (zero for variable-sized elements).

cx	Size for ChunkArrayHeader, or zero for default. Extra 
space is initialized to zeroes.

si 	Chuck to resize and use for chunk array (zero to allocate a 
new chunk).

al	ObjChunkFlags to be passed to LMemAlloc.

Returns: 	*ds:si	Address of the new array, locked.

Destroyed: 	Nothing.

Library: 	chunkarr.def

Warning:	This routine may resize or move the passed block, invalidating all segment 
pointers to it.

n	ChunkArrayDelete

Delete a specified element from the given array.

Pass: 	*ds:si	Segment:chunk handle of the chunk array.

ds:di	Address of locked element.

Returns: 	ds:di	Address of the same element, if it still exists.

Destroyed: 	Nothing.

Library: 	chunkarr.def

n	ChunkArrayDeleteRange

Delete a range of elements from the given chunk array.

Pass: 	*ds:si	Segment:chunk handle of the chunk array.

ax	First element to delete (inclusive).

cx	Total number of elements to delete (-1 to delete to the end of 
the array).

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	chunkarr.def

n	ChunkArrayElementResize

Resize an element in a variable-sized chunk array.

Pass: 	*ds:si	Segment:chunk handle of the chunk array.

ax	Element number of the element to be resized.

cx	New size of the element.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	chunkarr.def

Warning:	If you are resizing the element larger, all pointers you've stored to chunks in 
the block are invalidated. If you are resizing the element smaller, the array 
is guaranteed not to move or cause other chunks to move.

n	ChunkArrayElementToPtr

Return the address of a specified element in a chunk array.

Pass: 	*ds:si	Segment:chunk handle of the chunk array.

ax	Element number of element to find.

Returns: 	CF	Set if element number out of bounds.

cx	Size of the returned element, if variable-sized.

ds:di	Address of element; if ax was out of bounds, ds:di will be 
returned pointing to the last element in the array.

Destroyed: 	Nothing.

Library: 	chunkarr.def

Warning:	The error-checking version fatal-errors if passed CA_NULL_ELEMENT in ax.

n	ChunkArrayEnum

Process all elements in a chunk array, calling a callback routine for each.

Pass: 	*ds:si	Segment:chunk handle of the chunk array.

bx:di	Address of the callback routine.

ax	Initial data passed to callback only if fixed-size elements.

cx, dx, bp, es	Initial data to pass to callback routine.

Returns: 	CF	Set if enumeration aborted by the callback routine.

ax, cx, dx, bp, es
As set by the last call to the callback routine.

Destroyed: 	bx

Callback Routine Specifications:	

Passed: 	*ds:si	Segment:chunk handle of the chunk array.

ds:di	Address of element being processed.

ax	Size of element, if variable-sized; otherwise, 
inherited from ChunkArrayEnum.

cx, dx, bp, es	Inherited from ChunkArrayEnum.

Return: 	CF	Set to abort processing.

cx, dx, bp, es	Data to pass to next enumeration.

May Destroy: 	bx, si, di

Library: 	chunkarr.def

n	ChunkArrayEnumRange

Process the specified elements in a chunk array, calling a callback routine for 
each element.

Pass: 	*ds:si	Segment:chunk handle of the chunk array.

bx:di	Address of the callback routine.

ax	Number of first element to process.

cx	Number of elements to process (-1 to process all including the 
last element).

dx, bp, es	Initial data to pass to the callback routine.

Returns: 	CF	Set if the routine was aborted before all specified elements 
were processed.

ax, cx, dx, bp, es
As returned by the last call to the callback routine.

Destroyed: 	Nothing.

Callback Routine Specifications:	

Passed: 	*ds:si	Segment:chunk handle of the chunk array.

ds:di	Address of element being processed.

ax	Size of element, if variable-sized; otherwise, 
inherited from ChunkArrayEnumRange.

cx, dx, bp, es	Inherited from ChunkArrayEnumRange.

Return: 	CF	Set to abort processing.

cx, dx, bp, es	Data to pass to next enumeration.

May Destroy: 	bx, si, di

Library: 	chunkarr.def

n	ChunkArrayGetCount

Return the number of elements in the given chunk array.

Pass: 	*ds:si	Segment:chunk handle of the chunk array.

Returns: 	cx	Number of elements in the array.

Destroyed: 	Nothing.

Library: 	chunkarr.def

n	ChunkArrayGetElement

Get an element given its element number.

Pass: 	*ds:si	Segment:chunk handle of the chunk array.

ax	Element number of element to be retrieved.

cx:dx	Address of a buffer in which the element will be returned.

Returns: 	ax	Size of element returned.

cx:dx	Address of filled buffer

Destroyed: 	Nothing.

Library: 	chunkarr.def

Warning:	The error-checking version will fatal-error if CA_NULL_ELEMENT is 
passed in ax or if ax is out of bounds.

n	ChunkArrayInsertAt

Insert the specified element at a given position in the array.

Pass: 	*ds:si	Segment:chunk handle of the chunk array.

ds:di	Address of element to insert.

ax	Size of new element, if variable-sized.

Returns: 	ds:di	Address of new element in the array.

Destroyed: 	Nothing.

Library: 	chunkarr.def

Warning:	This routine may resize or move the passed block, invalidating all segment 
pointers to it.

n	ChunkArrayPtrToElement

Return the element number of the element pointed to.

Pass: 	*ds:si	Segment:chunk handle of the chunk array.

ds:di	Address of the element to be checked.

Returns: 	ax	Zero-based element number.

Destroyed: 	Nothing.

Library: 	chunkarr.def

n	ChunkArraySort

Sort the given chunk array in ascending order.

Pass: 	*ds:si	Segment:chunk handle of the chunk array to sort.

bx	Value to pass to callback routine.

cx:dx	Address of callback routine.

Returns: 	Nothing.

Destroyed: 	cx, dx

Callback Routine Specifications:	

Passed: 	bx	Value inherited from ChunkArraySort.

ds:si	Address of first element to compare.

es:di	Address of second element to compare.

Return: 	SF, OF, ZF	These flags should be set in the following 
conditions:

first element less than second element
SF set
OF clear
ZF unrestricted

first element equal to second element
SF unrestricted
OF unrestricted
ZF set

first element larger than second element
SF clear
OF clear
ZF clear

May Destroy: 	ax, bx, cx, dx, si, di

Library: 	chunkarr.def

n	ChunkArrayZero

Free all the elements of the given chunk array and resize it.

Pass: 	*ds:si	Segment:chunk handle of the chunk array.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	chunkarr.def

n	ClipboardAbortQuickTransfer

This routine aborts a quick-transfer. This routine is normally used if the 
quick-transfer source object is about to be destroyed or if an error occurs 
trying to register the quick-transfer item.

Pass: 	Nothing.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardAddToNotificationList

Add the passed OD to the transfer notify list.

Pass: 	cx:dx 	OD to add. If cx is the process handle, then dx must be zero.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardClearQuickTransferNotification

This routine removes the quick-transfer OD notification.

Pass: 	bx:di	Notification OD to remove. 

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardDoneWithItem

This routine must be called when you are finished using the requested 
transfer item.

Pass: 	bx:ax	Transfer item header, as returned by 
ClipboardQueryItem.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardEndQuickTransfer

End a quick-transfer. Reset the mouse pointer image, clear the 
quick-transfer region (if any), and clear the quick-transfer item. Send out 
notification if necessary.

Pass: 	bp 	ClipboardQuickNotifyFlags. If a quick-transfer move 
operation was done, then CQNF_MOVE should be set. If a 
quick-transfer copy operation was done, then CQNF_COPY 
should be set. If the item was not accepted, the 
CQNF_NO_OPERATION should be set.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardEnumItemFormats

This routine returns the list of all available formats 
(ClipboardItemFormatID structures).

Pass: 	bx:ax	Transfer item header, as returned by 
ClipboardQueryItem.

cx 	Maximum number of formats to return.

es:di 	Buffer for formats (should be at least cx * 
sizeof(ClipboardItemFormatID).

Returns: 	cx	Number of formats returned.

es:di 	(unchanged) Buffer now filled.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardFreeItem

Free the passed clipboard item.

Pass: 	bx:ax 	VMFileHandle:VMBlockHandle of item to free.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardFreeItemsNotInUse

Frees normal or quick transfer item if nobody's using it, nukes references to 
it, sends proper GCN messages out.

Pass: 	Nothing.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	clipbrd.def

Warning:	The user should not have called ClipboardRegisterItem with this transfer 
item, as this routine just frees the data without updating any references in 
the map block.

n	ClipboardGetClipboardFile

Return the VM file used to hold clipboard items.

Pass: 	Nothing.

Returns: 	bx	Handle of UI's clipboard VM file.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardGetItemInfo

Get more information about the passed transfer item.

Pass: 	bx:ax	Transfer item header, as returned by 
ClipboardQueryItem.

Returns: 	cx:dx	Handle:chunk of CIH_sourceID from clipboard item header.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardGetNormalItemInfo

Return normal clipboard item information.

Pass: 	Nothing.

Returns: 	bx	Clipboard VM file handle.

ax 	Clipboard VM block handle.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardGetQuickItemInfo

Return quick clipboard item information.

Pass: 	Nothing.

Returns: 	bx	Clipboard VM file handle.

ax 	Clipboard VM block handle.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardGetQuickTransferStatus

Check to see if a quick-transfer is in progress.

Pass: 	Nothing.

Returns: 	ZF 	Clear if quick-transfer is in progress; set otherwise.

ax	If a quick transfer is in progress, this will be 
ClipboardQuckTransferFlags indicating what stage the 
process is in.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardGetUndoItemInfo

Return undo clipboard item information.

Pass: 	Nothing.

Returns: 	bx	Clipboard VM file handle.

ax 	Clipboard VM block handle.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardHandleEndMoveCopy

This routine handles a MSG_META_END_COPY, either preparing to finish the 
quick-transfer and send a MSG_META_END_MOVE_COPY to the object with 
the active grab or ending the quick-transfer and sending a 
MSG_META_END_OTHER to the object with the implied grab.

Pass: 	bx	Zero to send a MSG_META_END_OTHER; non-zero to send a 
MSG_META_END_MOVE_COPY.

bp 	High byte is a UIFunctionsActive structure.

CF 	Should be set clear. Set to check if quick-transfer is in 
progress (this is needed only for internal input handling). 

Returns: 	ax	MSG_META_END_OTHER or MSG_META_END_MOVE_COPY 
(as determined by passed value in bx).

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardQueryItem

This routine registers the passed transfer item.

Pass: 	bp	ClipboardItemFlags (all but CIF_QUICK will be ignored).

Returns: 	bp	Number of formats available (zero if no clipboard item).

cx:dx	Owner of clipboard item.

bx:ax	VMFileHandle:VMBlockHandle to clipboard item header 
(which may then be passed to 
ClipboardRequestItemFormat).

Destroyed: 	Nothing.

Warning:	After calling this routine, ClipboardDoneWithItem must be called.

Library: 	clipbrd.def

n	ClipboardRegisterItem

This routine registers the passed transfer item.

Pass: 	ax	Handle of VM block containing ClipboardItemHeader 
structure or zero to null the clipboard item.

bx 	Handle of VM file containing clipboard item.

bp 	ClipboardItemFlags.

Returns: 	CF	If registering a quick transfer item, this flag's behavior is 
undefined. If registering a normal transfer item, this flag will 
be set on an error, clear otherwise.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardRemoteReceive

Receive clipboard from remotely connected machine.

Pass: 	Nothing.

Returns: 	CF	Set on error, clear on success.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardRemoteSend

Send clipboard to remotely connected machine.

Pass: 	Nothing.

Returns: 	CF	Set on failure, clear on success.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardRemoveFromNotificationList

Remove the passed OD from the transfer notify list.

Pass: 	cx:dx 	OD to remove. If cx is the process handle, then dx must be 
zero.

Returns: 	CF 	Clear if successfully removed, set if was not found.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardRequestItemFormat

This routine requests the given transfer item, as stored in the given format 
type.

Pass: 	bx:ax	Transfer item header, as returned by 
ClipboardQueryItem.

cx:dx	Format manufacturer:format type.

Returns: 	bx	File handle of transfer item.

ax:bp 	VM chain (zero if none).

cx 	First extra data word.

dx 	Second extra data word.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardSetQuickTransferFeedback

Set mouse cursor for quick-transfer.

Pass: 	ax 	ClipboardQuickTransferFeedback value.

bp 	If ax is CQTF_MOVE or CQTF_COPY, then the high byte of this 
register should hold a UIFunctionsActive value. UIFA_MOVE 
signals that you wish to force the cursor to be that associated 
with a quick-move; UIFA_COPY that you wish to force the 
quick-copy cursor.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardStartQuickTransfer

Initiate a quick transfer (normally called from 
MSG_META_START_MOVE_COPY).

Pass: 	si 	ClipboardQuickTransferFlags. The CQTF_COPY_ONLY 
flag should be set if the source only supports copying.
The CQTF_USE_REGION flag should be set if you will be 
passing a region to use as the quick-transfer cursor.
The CQTF_NOTIFICATION flag should be set if the source 
wants notification when the quick-transfer item is accepted 
by the destination.

ax 	Initial cursor to use (CQTF_MOVE or CQTF_COPY). This 
should be -1 if you wish to use the default cursor (i.e. object is 
a quick-transfer source, but not a quick transfer destination).

cx, dx 	If CQTF_USE_REGION set, these registers hold the mouse 
position in screen coordinates. Otherwise they are ignored.

bx:di 	If CQTF_NOTIFICATION set, these registers hold the OD to 
receive MSG_NOTIFY_QUICK_TRANSFER_MOVE, 
MSG_NOTIFY_QUICK_TRANSFER_COPY, and 
MSG_META_CLIPBOARD_NOTIFY_QUICK_TRANSFER_FEED
BACK.

ss:bp 	If CQTF_USE_REGION set, values will be passed on stack.

Pass on stack:	The following structure will only be passed if CQTF_USE_REGION is set:

 ClipboardQuickTransferRegionInfo struct

	 CQTRI_paramAX word

	 CQTRI_paramBX word

	 CQTRI_paramCX word

	 CQTRI_paramDX word

	 CQTRI_regionPos Point

	 CQTRI_strategy dword

	 CQTRI_region dword                                  ; pointer to region

 ClipboardQuickTransferRegionInfo ends

CQTRI_region must be in a block that is in memory already.

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.

Returns: 	CF 	Clear if UI part of new quick-transfer successfully begun; set 
if a quick-transfer was already in progress.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardTestItemFormat

This routine determines whether the clipboard item supports the specified 
format.

Pass: 	bx:ax	Transfer item header, as returned by 
ClipboardQueryItem.

cx:dx 	Format manufacturer:format type.

Returns: 	CF	Clear if format supported; set otherwise.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ClipboardUnregisterItem

This routine unregisters the passed clipboard item, restoring any transfer 
which may have been disturbed by the last normal clipboard item.

Pass: 	cx:dx	Owner output descriptor used when registering previous 
item.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	clipbrd.def

n	ConfigBuildTitledMoniker

Global routine to build a titled moniker based on the passed moniker list

Pass: 	*ds:si	visual moniker list.

Returns: 	Nothing; visMoniker list replaced with visMoniker.

Destroyed: 	Nothing.

Library: 	config.def

n	ConfigBuildTitledMonikerUsingToken

Combine 2 vis monikers-placing the text moniker centered below the 
picture moniker.

Pass: 	ds	Local memory block in which to create the new moniker.

ax:bx:si	Token characters.

Returns: 	CF	Clear if found; set otherwise.

*ds:dx	New moniker.

Destroyed: 	ax, bx, cx, di

Library: 	config.def

n	DBAlloc

Allocate a new database item in a specified group.

Pass: 	bx	File handle of the database file.

ax	Group identifier of the new item (VM block handle).
For an ungrouped item, pass DB_UNGROUPED.

cx	Size of the new item.

ds	Optional segment address of an item-block.

es	Optional segment address of an item-block.

Returns: 	di	Item number of newly allocated item.

ax	Group number of new item.

ds	(If passed) fixed up.

es	(If passed) fixed up.

Destroyed: 	Nothing.

Library: 	dbase.def

n	DBCopyDBItem

Copy an existing database item into a newly-allocated item.

Pass: 	bx	File handle of the source database file.

ax	Group identifier of the source database item.

di	Item number of the source database item.

bp	File handle of the destination database file.

cx	Group identifier of the destination item's group. For and 
ungrouped item, pass DB_UNGROUPED.

Returns: 	di	Item number of the new item.

ax	Group identifier of the new item.

Destroyed: 	Nothing.

Library: 	dbase.def

Warning:	Because a new chunk is allocated, chunks or blocks may be moved. Thus, all 
pointers are invalidated by this routine.

n	DBDeleteAt

Delete a given number of bytes from within the specified database item.

Pass: 	bx	File handle of the database file.

ax	Group identifier of the item.

di	Item number of the item.

dx	Offset of first byte to be deleted.

cx	Total number of bytes to be deleted.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	dbase.def

n	DBDirty

Mark a database item as dirty so it will be written to the database file with 
its changes.

Pass: 	es	Segment of locked block containing the database item.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	dbase.def

n	DBFree

Remove the specified item from the database.

Pass: 	bx	File handle of the database file.

ax	Group identifier of the item.

di	Item number of the item to be freed.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	dbase.def

n	DBGetMap

Return the item that is set to be the database's map.

Pass: 	bx	File handle of the database file.

Returns: 	ax	Group identifier of the map item's group.

di	Item number of the map item.

Destroyed: 	Nothing.

Library: 	dbase.def

n	DBGroupAlloc

Create a new database group.

Pass: 	bx	File handle of the database file.

Returns: 	ax	Group identifier of the new group.

Destroyed: 	Nothing.

Library: 	dbase.def

n	DBGroupFree

Remove all items in the specified group and delete the group.

Pass: 	bx	File handle of the database file.

ax	Group identifier of the group to be deleted.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	dbase.def

n	DBInsertAt

Insert a specified number of bytes within a given database item. The bytes 
may be inserted at any offset, and the new bytes will be zeroed.

Pass: 	bx	File handle of the database file.

ax	Group identifier of the item.

di	Item number of the item.

cx	Total number of bytes to insert.

ds	Optional segment address of an item-block.

es	Optional segment address of an item-block.

Returns: 	ds	(If passed) fixed up.

es	(If passed) fixed up.

si	Old segment address of changed item block.

ax	New segment address of changed item block.

Destroyed: 	Nothing.

Library: 	dbase.def

Warning:	Because the chunk is resized larger, chunks or blocks may be moved. Thus, 
all pointers are invalidated by this routine.

n	DBLock

Lock a database item for exclusive access. When you're done with the item, 
unlock it with DBUnlock.

Pass: 	bx	File handle of the database file.

ax	Item's group number.

di	Item's item number.

Returns: 	*es:di	Segment:chunk handle of database item.

Destroyed: 	Nothing.

Library: 	dbase.def

n	DBLockMap

Lock the map item for the database file. This is a utility that is slightly 
quicker than calling DBGetMap followed by DBLock. When finished with 
the map item, you must call DBUnlock on it.

Pass: 	bx	File handle of the database file.

Returns: 	*es:di	Segment:chunk handle of the locked map item.

di	Zero if there is no map item. In this case, es is not returned.

Destroyed: 	Nothing.

Library: 	dbase.def

n	DBReAlloc

Change the size of an existing database item.

Pass: 	bx	File handle of the database file.

ax	Group identifier of the item (VM block handle).

di	Item number of the item to be reallocated.

cx	New size of the item.

ds	Optional segment address of an item-block.

es	Optional segment address of an item-block.

Returns: 	ds	(If passed) fixed up.

es	(If passed) fixed up.

Destroyed: 	Nothing.

Library: 	dbase.def

n	DBSetMap

Mark a database item as being the map item for the database file.

Pass: 	bx	File handle of the database file.

ax	Group identifier of the item's group.

di	Item number of the item to be made the map.

Returns: 	Nothing.

Destroyed: 	Nothing.

Library: 	dbase.def

n	DBUnlock

Unlocks a database item that had previously been locked with DBLock.

Pass: 	es	Segment address of the item's item-block.

Returns: 	Nothing.

Destroyed: 	Nothing. (Error-checking code may destroy ds or es by writing 
NULL_SEGMENT to it, if it pointed to a block that had become unlocked.)

Library: 	dbase.def

n	DiskCheckInUse

Determine if the passed disk is actively being used, either by an open file or 
by a thread having a directory on the disk in its directory stack.

Pass: 	bx	Disk handle of disk to be checked.

Returns: 	CF	Set if disk is in use, clear if it is not.

Destroyed: 	Nothing.

Library: 	disk.def

n	DiskCheckUnnamed

Check if the passed disk handle refers to an unnamed disk (i.e. a disk that 
has no user-supplied volume name).

Pass: 	bx	Disk handle of disk to be checked.

Returns: 	CF	Set if disk is unnamed, clear if it is named.

Destroyed: 	Nothing.

Library: 	disk.def

n	DiskCheckWritable

See if the passed volume is writable.

Pass: 	bx	Disk handle of volume to be checked.

Returns: 	CF	Set if the volume is writable, clear if it is not.

Destroyed: 	Nothing.

Library: 	disk.def

n	DiskCopy

Copies the contents of the source disk to the destination disk, prompting for 
them as necessary.

Pass: 	dh	source drive number

dl	destination drive number

al	DiskCopyFlags

cx:bp	callback routine

Returns: 	ax	DiskCopyError/FormatError; Zero if successful.

Callback Routine Specifications:	

Passed: 	ax	DiskCopyCallback value signalling what to 
do next.

bx, dx	Additional information based on value of ax:
DCC_GET_SOURCE_DISK
  dl = Zero-based drive number.
DCC_REPORT_NUM_SWAPS
  dx = Number of swaps required.
DCC_GET_DEST_DISK
  dl = Zero-based drive number.
DCC_VERIFY_DEST_DESTRUCTION
  bx = Disk handle of destination disk
  dl = Zero-based drive number
DCC_REPORT_FORMAT_PCT
  dx = Percentage of disk formatted.
DCC_REPORT_READ_PCT
  dx = Percentage of disk read.
DCC_REPORT_WRITE_PCT
  dx = Percentage of disk written.

Return: 	Zero to continue, non-zero to abort.

Destroyed: 	Nothing.

Library: 	disk.def

n	DiskFind

Search the list of registered disks and return the handle of that having the 
passed volume name. An additional search is also made to ensure the match 
is unique.

Pass: 	ds:si	Address of null-terminated volume name to search for.

Returns: 	CF	Set if error.

ax	DiskFindResult:
DFR_UNIQUE if found and unique match.
DFR_NOT_UNIQUE if found but not unique.
DFR_NOT_FOUND if no match found.

bx	If successful, disk handle of first disk found; otherwise, zero.

Destroyed: 	Nothing.

Library: 	disk.def

n	DiskForEach

Call a callback routine for each disk registered with the system, allowing the 
callback to cancel the operation.

Pass: 	ax, cx, dx, bp	Initial data to pass to the callback routine.

di:si	Address of callback routine.

Returns: 	ax, cx, dx, bp	As returned by last callback execution.

CF	Set if callback forced early termination.

bx	If CF set, the disk handle of the last disk processed; otherwise 
will be returned zero.

Destroyed: 	di, si

Callback Routine Specifications:	

Passed: 	bx	Disk handle of current disk.

ax, cx, dx, bp	Data set by caller and callback.

Return: 	ax, cx, dx, bp	May be modified or preserved.

CF	Set if processing should be aborted.

May Destroy: 	ax, cx, dx, bp

Library: 	disk.def

n	DiskFormat

Format the disk in the specified drive.

Pass: 	al	Drive number.

ah	GEOS media descriptor (MediaType).

bx	Handle of the disk to be formatted, or
Zero if disk is known to be unformatted, or
-1 if state of drive is not known.

bp	DiskFormatFlags.

ds:si	New null-terminated ASCII volume name for the disk.

cx:dx	Address of callback routine, initialized only if 
DFF_CALLBACK_PCT_DONE or DFF_CALLBACK_CYL_HEAD 
passed in bp.

Returns: 	CF	Set on error.

ax	Error code if error (FormatError), or FMT_DONE if 
successful.

si:di	If successful, returns number of bytes in good clusters.

dx:cx	If successful, returns number of bytes in bad clusters.

Destroyed: 	ax, bx

Callback Routine Specifications:	

Passed: 	ax	Percentage done or number of cylinder heads 
finished, appropriate to bp parameter.

Return: 	CF	Return set to cancel format.

May Destroy: 	Nothing.

Library: 	disk.def

Warning:	All data on the destination disk is lost.

n	DiskGetDrive

Return the drive number of the drive in which the passed disk was 
registered.

Pass: 	bx	Disk handle of registered disk.

Returns: 	al	Zero-based drive number.

Destroyed: 	ah

Library: 	disk.def

n	DiskGetVolumeFreeSpace

Return the number of bytes free on a volume.

Pass: 	bx	Disk handle of registered volume.

Returns: 	CF	Set if error, clear if successful.

ax	If error, error code: ERROR_INVALID_VOLUME.

dx.ax	If successful, number of bytes free on volume.

Destroyed: 	Nothing.

Library: 	disk.def

n	DiskGetVolumeInfo

Return information about a registered disk.

Pass: 	bx	Disk handle of registered disk.

es:di	Address of DiskInfoStruct to fill in.

Returns: 	CF	Set if error.

ax	Zero if successful, otherwise ERROR_INVALID_VOLUME.

es:di	If successful, the address of the returned DiskInfoStruct 
structure, filled in.

Destroyed: 	ax

Library: 	disk.def

n	DiskGetVolumeName

Return the volume name of the disk specified by the passed handle.

Pass: 	bx	Disk handle of registered disk.

es:di	Pointer to locked or fixed buffer at least 
VOLUME_NAME_LENGTH_ZT bytes long.

Returns: 	es:di	Pointer to null-terminated volume name (with no trailing 
spaces).

Destroyed: 	Nothing.

Library: 	disk.def

n	DiskRegisterDisk

Register a disk with the system.

Pass: 	al	Drive number containing disk to be registered.

Returns: 	CF	Clear if successful, set if error.

bx	Disk handle of registered disk if successful, zero if error.

Destroyed: 	Nothing.

Library: 	disk.def

n	DiskRegisterDiskSilently

Register a disk with the system without informing the user.

Pass: 	al	Drive number containing disk to be registered.

Returns: 	CF	Clear if successful, set if error.

bx	Disk handle of registered disk if successful, zero if error.

Destroyed: 	Nothing.

Library: 	disk.def

n	DiskRestore

Restore a disk handle that had been saved to the state file with DiskSave.

Pass: 	ds:si	Address of locked or fixed buffer originally passed to 
DiskSave.

cx:dx	Address of callback routine to call if the user must be 
prompted for the disk. If cx is zero, no callback will be 
attempted and the routine will fail if the disk is unavailable 
(i.e. the drive no longer exists or the disk is not in the drive).

Returns: 	CF	Set if disk handle could not be restored.

ax	If CF clear, the disk handle of the registered disk.
If CF set, a DiskRestoreError indicating the failure.

Destroyed: 	Nothing.

Callback Routine Specifications:	

Passed: 	ds:dx	Address of null-terminated drive name, with 
":" (colon) as the last character.

ds:di	Address of null-terminated disk name.

ds:si	Address of buffer originally passed to 
DiskSave.

ax	DiskRestoreError to be returned if the 
callback routine was not being called.

bx, bp	As passed to DiskRestore.

Return: 	CF	Clear if disk should be in the drive, set if user 
cancelled the restoration.

ds:si	If CF clear, address of buffer originally passed 
to DiskSave.

ax	If CF set, error code returned (typically 
DRE_USER_CANCELED_RESTORE).

May Destroy: 	Nothing.

Library: 	disk.def

n	DiskSave

Save information that will allow a disk handle to be restored when the caller 
is restoring itself from a state file after a shutdown.

Pass: 	bx	Disk handle to save.

es:di	Address of locked or fixed buffer for opaque data.

cx	Size of buffer in es:di.

Returns: 	CF	Clear if successful, set if error.

cx	If CF clear, actual number of bytes used in the buffer.
If CF set, the number of bytes needed to save the disk; zero if 
the disk can not be saved at all (e.g. it is a network drive that 
no longer exists).

Destroyed: 	Nothing.

Library: 	disk.def

n	DiskSetVolumeName

Set the name of a registered disk.

Pass: 	bx	Disk handle of registered volume.

ds:si	Address of null-terminated ASCII name.

Returns: 	CF	Set if error.

ax	Error code, or zero if no error
ERROR_INVALID_VOLUME
ERROR_ACCESS_DENIED.

Destroyed: 	Nothing.

Library: 	disk.def

n	DosExec

Begin execution of a DOS application, shutting down GEOS to state files or 
creating a new task in the task-switcher for the DOS application.

Pass: 	bx	Optional disk handle for the disk on which the DOS program 
resides. (Pass zero for the disk containing GEOS.)

ds:si	Address of null-terminated path of the DOS application. If 
this is just a null character, the system's command 
interpreter will be run with the given command-line 
arguments.

es:di	If DEF_MEM_REQ is passed, this will contain the 
DosExecArgAndMemReqsStruct containing the memory 
requirements of the program; Otherwise, this is the address 
of a buffer containing the command-line arguments to pass to 
the application.

ax	Optional disk handle for the disk that contains the path or 
directory in which the application should be executed.

dx:bp	Address of a buffer containing the null-terminated path or 
directory name in which the application should be executed.

cx	A record of DosExecFlags.

Returns: 	CF	Set if the program could not be run.

ax	Error code if CF is set:
ERROR_FILE_NOT_FOUND
ERROR_DOS_EXEC_IN_PROGRESS
ERROR_INSUFFICIENT_MEMORY
ERROR_ARGS_TOO_LONG

Destroyed: 	ax, bx, cx, dx, di, si, bp, ds, es

Library: 	system.def

n	DriveGetDefaultMedia

Return the GEOS media descriptor of the highest density format supported 
by the specified drive.

Pass: 	al	Zero-based drive number.

Returns: 	CF	Set if drive does not exist.

ah	GEOS media descriptor (MediaType).

Destroyed: 	Nothing.

Library: 	drive.def

n	DriveGetExtStatus

Return the extended status word for the specified drive.

Pass: 	al	Zero-based drive number.

Returns: 	CF	Set if drive does not exist.

ax	DriveExtendedStatus record if successful.

Destroyed: 	Nothing.

Library: 	drive.def

n	DriveGetName

Return the name of the specified drive.

Pass: 	al	Zero-based drive number.

es:di	Address of locked or fixed buffer into which the 
null-terminated name will be written.

cx	Number of bytes in the buffer.

Returns: 	CF clear:
cx
Number of bytes written to the buffer including the 
terminating null.

	es:di
Address of the terminating null, not the first character.

CF set:

	cx
Zero if the drive does not exist.
Total number of bytes needed if the buffer is too small.

Destroyed: 	Nothing.

Library: 	drive.def

n	DriveGetStatus

Returns status information on the specified drive.

Pass: 	al	Zero-based drive number.

Returns: 	CF	Set if drive does not exist.

ah	DriveStatus record if successful.

Destroyed: 	Nothing.

Library: 	drive.def

n	DriveTestMediaSupport

Test if the specified drive supports the given media type.

Pass: 	al	Zero-based drive number.

ah	MediaType media descriptor.

Returns: 	CF	Clear if media type supported by the drive; set otherwise.

Destroyed: 	Nothing.

Library: 	drive.def
Figure 3-0

Display 3-0

SwatDisplay 3-0

Table 3-0
