2.6 Routines R-U

RangeEnum

Enumerate all cells in a range of cells, calling a callback routine on each.

Pass:
ds:si - Address of a CellFunctionParameters structure.
ss:bp - Address (on stack) of local variables for callback.
ss:bx - Address (on stack) of RangeEnumParams structure.
dl - RangeEnumFlags record with any or all of the following:
REF_ALL_CELLS - Use callback routine for all cells.
REF_NO_LOCK - Callback routine will lock and unlock cells.
REF_COLUMN_FLAGS - Get the ColumnFlags for this cell (passed in the RangeEnumParams structure).
REF_MATCH_COLUMN_FLAGS - Use callback routine only for cells having matching ColumnFlags as those passed.

Pass on stack:
NOTE: - These parameters are not to be popped; they are to be referenced by their pointers as specified. The stack frame will be passed to the callback, which also should not pop them.
ss:bp - Local variables for callback routine.
ss:bx - RangeEnumParams structure, with the following fields:
REP_callback - Address of the callback routine to process the enumerated cells.
REP_bounds - Rectangle structure giving the bounds of the range of cells to enumerate.
REP_columnFlags - ColumnFlags record for the passed cell.
REP_columnFlagsArray - Address of a ColumnArrayHeader structure.
REP_cfp - Address of a CellFunctionParameters structure.
REP_matchFlags - ColumnFlags record to indicate which flags must be set in a cell for it to be processed. Only valid if REF_MATCH_COLUMN_FLAGS set in dl.

Returns:
CF - Set if callback routine forced an early abortion of the routine.

Destroyed:
Nothing.

Callback Routine Specifications:
Passed:
ds:si - Address of CellFunctionParameters as passed to RangeEnum.
ax - Current cell row.
cx - Current cell column.
dl - RangeEnumFlags passed to RangeEnum.
ss:bp - Address (on stack) of local variables for callback routine. See notes above for values passed on the stack.
ss:bx - Address (on stack) of RangeEnumParams structure passed to RangeEnum. See notes above for values passed on the stack. If REF_COLUMN_FLAGS set in dl, REP_columnFlagsArray is a pointer to a ColumnArrayHeader structure, and REP_columnFlags is the ColumnFlags record for the cell.
CF - Set if the cell has data, clear otherwise.
*es:di - Segment:Chunk handle of cell’s data, if any.
Return:
CF - Set to abort RangeEnum, clear to continue.
es - Updated segment address of the cell.
dl - Modified RangeEnumFlags to potentially include the following flags:
REF_CELL_ALLOCATED - Set if the callback routine allocated the cell for which the callback occurred.
REF_CELL_FREED - Set if the callback routine freed the cell for which the callback occurred.
REF_OTHER_ALLOC_OR_FREE - Set if the callback routine may have allocated or freed a cell other than the one for which the callback occurred.
REF_COLUMN_FLAGS_MODIFIED - Set if the callback routine changed the ColumnFlags for the cell.
May Destroy:
Nothing.

Library: cell.def

Warning:
If the caller passes REF_ALL_CELLS and REF_NO_LOCK, then the callback routine will not know if the cell being called back actually exists or not. In this case, the callback parameters *es:di and CF are undefined.

If the callback routine allocates the cell which was called back, it should not unlock the cell; RangeEnum will take care of this.

If the callback routine allocates a different cell, it must unlock the cell and return REF_OTHER_ALLOC_OR_FREE.

If the callback routine frees the cell called back, it must unlock the cell before freeing it. Otherwise, the block containing the freed cell can not be removed (the cell will always be locked). Also, the callback routine must return REF_CELL_FREED.

If the callback routine frees a different cell, it must unlock the cell before freeing the cell, as outlined above. Also, the callback must return REF_OTHER_ALLOC_OR_FREE.

If the callback routine changes the ColumnFlags of the cell, it must also change the data pointed at by REP_columnFlagsArray and return the flag REF_COLUMN_FLAGS_MODIFIED.

Allocate a handle to play FM sounds from fixed memory

Pass:
bx:si - Buffer to play from in fixed memory
cx - Number of voices used in buffer

Destroyed:
See above.

Library: sound.def

Stop a simple frequency-modulated sound from playing. This is similar in usage to SoundStopNote.

Pass:
bx - Handle of the simple sound.

Returns:
CF - Set if the library was unavailable, clear otherwise.
ax - On error, a SoundErrors value; otherwise destroyed.

Library: sound.def

SoundSynthDriverInfo

Get information on the synthesizer driver.

Pass:
Nothing.

Returns:
ax - Number of Voices
bx - SupportedInstrumentFormat
cx - SoundDriverCapability

Destroyed:
Nothing.

Library: sound.def

SpoolAddJob

Add the passed job (a GString file) to the print queue. If the spooler thread has not started, or if there is no queue for the desired device and port, this routine will start them.

Pass:
dx:si - Address of a JobParameters structure. This structure includes information on the document, the paper, the print mode, the number of copies, the port, the device, and the printer.

Returns:
cx - ID of the print job. This ID may be used to track or modify jobs with other spooler routines.

Destroyed:
Nothing.

Library: spool.def

SpoolConvertPaperSize

Convert a width and height pair to a paper size index. This is the complement to SpoolGetPaperSize.

SysNotify

Put the SysNotify dialog box (the white box with black borders) on the screen. The dialog may have two strings printed in it, which are passed with this routine. This box is typically used for unrecoverable errors, but it may be used for other notifications. Most often an application will use a standard dialog rather than a SysNotify for notification messages.

Pass:
ax - SysNotifyFlags record with zero or more of these flags:
SNF_RETRY - Provide “Retry” option to the user.
SNF_EXIT - Provide “Exit Cleanly” option to the user.
SNF_ABORT - Provide “Abort” option to the user.
SNF_CONTINUE - Provide “Continue” option to the user. This implies the notification dialog is not a real error but simply a notification.
SNF_REBOOT - Provide “Reboot” option to the user, executing a dirty shutdown followed by a restart of GEOS. This option will not return.
SNF_BIZARRE - Indicates the notification is unexpected and that the user should be directed to the trouble-shooting guide.
ds:si - Address of the first string. Must be null-terminated and either locked or fixed. If no string, pass si = zero.
ds:di - Address of the second string. Must be null-terminated and either locked or fixed. If no string, pass di = zero.

Returns:
ax - Selected option if SNF_RETRY, SNF_ABORT, SNF_CONTINUE, or SNF_EXIT is passed and selected by the user. If SNF_REBOOT passed and selected, this routine does not return.

Destroyed:
Nothing (except SNF_REBOOT).

Library: system.def

SysRegisterScreen

Register a new screen with the error mechanism, creating a new window and GState. Use of this routine is strongly discouraged.

Pass:
cx - WindowHandle of the new screen’s root window.
dx - DriverHandle of the video driver for the new screen.

Returns:
Nothing.

Destroyed:
Nothing.

Library: system.def

SysSetECLevel

Set the current error-checking flags.

Pass:
ax - ErrorCheckingFlags record containing the flags to set. Flags not set will be cleared. See the reference entry for ErrorCheckingFlags for full details.

bx - Handle of the error-checking block for ECF_BLOCK_CHECKSUM (if any).

Returns:
Nothing.

Destroyed:
Nothing.

Library: ec.def

SysSetExitFlags

Set the record of exit flags for use with task-switching drivers. The exit flags are also used for other purposes. Use of this routine is strongly discouraged. For full information on the flags, see the reference entry for ExitFlags.

Pass:
bh - ExitFlags to clear.
bl - ExitFlags to set. Flags in both bh and bl will be cleared.

Returns:
bl - ExitFlags record as set by the routine. The flags are
EF_PANIC - Exit is a panic, so the GEOS.INI file should not be written to disk.
EF_RUN_DOS - Exit is to run a DOS program.
EF_OLD_EXIT - Exit is old-style DOS exit (if GEOS was accidentally run under DOS 1.X).
EF_RESET - Exit should reset the machine.
EF_RESTART - Exit should immediately restart GEOS.

Destroyed:
bh is destroyed.

Library: system.def

Warning:
This is a dangerous routine.

This routine returns the system character attribute run for this object’s specific UI.

Pass:
*ds:si - Object to get character attributes for.
al - Flags to allocate LMem chunk with (if any) (type ObjChunkFlags).

Returns:
CF - Clear if we needed to allocate a chunk, set if a default character attribute run returned.
ax - New chunk or constant (allocated in passed ds block).
ds - Updated to point at segment of same block as on entry. Chunk handles in this segment may have moved; be sure to dereference them.

Destroyed:
Nothing.

Library: vTextC.def

Warning:
This routine may resize LMem or object blocks, moving them on the heap and invalidating stored segment pointers to them.

TextSearchInHugeArray

This routine finds an occurrence of a string within another string.

Pass:
ss:bp - Pointer to TextSearchInHugeArrayFrame. TextSearchInHugeArrayFrame struct:
TSIHAF_str1Size dword (?) Total length of string to search in (str1). TSIHAF_curOffset dword (?) Offset (from start of str1) to first char to check TSIHAF_endOffset dword (?) Offset (from start of str1) to last char to check. Will only match words that start <= TSIHAF_endOffset. To check to start of string (backward searches only) pass zero To check to end of string (forward searches only) pass TSIHAF_str1Size-1
TSIHAF_searchFlags SearchOptions
ds:si - Pointer to string to search for. This string may contain C_WILDCARD or C_SINGLE_WILDCARD.
cx - Number of characters in string to search for (or zero if null-terminated).

Returns:
CF - Set if string not found, clear if found.
dx:ax - Offset to match found.
bp:cx - Number of characters in match.

Destroyed:
Nothing.

Library: vTextC.def

TextSearchInString

This routine finds an occurrence of a string within another string (both strings must be less than 64K in size.

As an example of how to set up the registers for a search, consider the case where you want to search for the string “foo” in “I want some food”, but wish to start your search from the “w”.
es:bp should point to the “I”.
es:di should point to the “w”.
es:bx should point to the “d”.

Pass:
es:bp - Pointer to first character in string we are searching in.
es:di - Pointer to character at which to start searching. This is a position within the string to search in, allowing you to find multiple instances.
es:bx - Pointer to last character to include in search. This is a character within the string to search in. For forward searches, this routine will not match any word that begins after this character, but will match words that start before or at this character and extend beyond it.
dx - Number of characters pointed to by es:bp (zero if string is null-terminated).
ds:si - Pointer to string to search for. This string may contain C_WILDCARD or C_SINGLE_WILDCARD.
cx - Number of characters in string to search for (or zero if null-terminated).
al - SearchOptions.

Returns:
CF - Set if string not found, clear if found.
es:di - If found, pointer to start of string found; if not found, pointer to last character checked.
cx - Number of characters matched.

Destroyed:
Nothing.

Library: vTextC.def

TextSetSpellLibrary

This routine sets the handle of the spell library to make calls to.

Pass:
bx - Handle of spell library.

Returns:
Nothing.

Destroyed:
Nothing.

Library: vTextC.def

ThreadAllocSem

Allocate a semaphore with the initial passed value. The initial value is the number of locks the semaphore can legally have before it causes users to block. This number is nearly always one.

Pass:
bx - Initial value.

Returns:
bx - Handle of the semaphore.

Destroyed:
Nothing.

Library: sem.def

ThreadAllocThreadLock

Allocate a thread lock semaphore; this type of semaphore allows a single thread to lock it multiple times without hitting deadlock.

Pass:
Nothing.

Returns:
bx - Handle of the thread lock semaphore.

Destroyed:
Nothing.

Library: sem.def

ThreadAttachToQueue

Attach a thread to an event queue, blocking on the queue until an event is received by it.

Pass:
bx - Handle of the event queue to attach to. If null handle passed (zero), the caller wants to “re-attach” to the thread’s current queue. This is used when a function will not return but still needs to field events so its application object can detach properly.
cx:dx - Address of the class that will be bound to the thread. This argument is only used if a null handle is passed in bx.

Returns:
Does not return.

Destroyed:
Does not return.

Library: thread.def

ThreadCreate

Create a new procedural thread. When the thread is started, it begins execution at the routine specified. If you really want to create an event thread (one that runs objects), send MSG_PROCESS_CREATE_EVENT_THREAD to your process object instead.

You can call the C stub for this routine, THREADCREATE, directly if you like; this allows passing a virtual segment pointer to the thread’s execution routine. The routine may also return an exit code in ax. When calling THREADCREATE, however, you must pass the arguments on the stack. The kernel will take care of everything else, including calling ThreadDestroy with the proper exit code.

Pass:
di - Size of stack for new thread. For most threads, 1024 is a good stack size. Threads that do no file-related work can probably use 512 bytes. If the thread will run objects that use keyboard navigation (e.g. dialog boxes), you may need to make it 3072.
bp - Geode handle of the owner of the thread. If you’re in the application’s process thread, you can call GeodeGetProcessHandle to get the right owner value. If you’re in a UI thread and have ds or es pointing to a non-shared LMem block owned by the application, you can mov bx, ds:[LMBH_handle] and call MemOwner.
al - Priority number for the new thread. Usually one of PRIORITY_TIME_CRITICAL
PRIORITY_HIGH
PRIORITY_UI
PRIORITY_FOCUS
PRIORITY_STANDARD
PRIORITY_LOW
PRIORITY_LOWEST
bx - Value to pass to the new thread (the startup routine, defined below) in the cx register.
cx:dx - Address of the thread’s startup routine. This routine will be executed by the thread; it may send messages and call other routines, but when it is done executing, it jumps to ThreadDestroy and kills the thread. The routine’s parameters are listed below:

ds = es - Owning geode’s dgroup segment.
cx - Value passed in bx to ThreadCreate.
dx, y - Zero.
si - Handle of the owning geode.
di - LCT_NEW_CLIENT_THREAD.
flags, ax, bp - Undefined.

Returns:
Nothing.

Destroyed:
Nothing.

Library: timer.def

TimerStart

Start an event or routine timer, either continual or one-shot. A routine timer calls a specified routine when time is up; an event timer sends a specified message. A one-shot timer counts only once; a continual timer counts until stopped (with TimerStop), sending the message or calling the routine each time the specified interval has passed. You can also start a millisecond timer.

For routine timers, the routine called must have the following specifications:
Passed:
ax - The word passed in dx to TimerStart.
cx:dx - The tick count as returned by TimerGetCount.
Return:
Nothing.
May Destroy: ax, bx, cx, dx, si, di, bp, ds, es

For event timers, the message sent will carry the following parameters and may return nothing:
Passed:
ax - Message number sent.
cx:dx - The tick count as returned by TimerGetCount.
bp - The Timer ID for one-shot timers, or The timer interval, for continual timers.

For timers of type TIMER_MS_ROUTINE_ONE_SHOT, the routine must have the following specifications:
Passed:
ax - The word passed in dx to TimerStart.

Interrupts will be off.
Return:
Nothing.
May Destroy:
ax, bx, si, ds

Pass:
ax, bx, si - Six bytes of token. The ax and bx registers contain the four characters of the token and si contains the manufacturer ID.
cx:dx - Handle:chunk of moniker list

bp - TokenFlags.

Returns:
Nothing.

Destroyed:
Nothing.This routine may legally move locked LMem blocks (token database items), invalidating any stored segment pointers to them.

Library: token.def

TokenExitTokenDB

Close the token database file.

Pass:
Nothing.

Returns:
Nothing.

Destroyed:
Nothing

Library: token.def

TokenGetTokenInfo

Get information about a token.

Pass:
ax, bx, si - Six bytes of token.

Returns:
CF - Clear if token exists in database, set otherwise.
bp - TokenFlags for the token (if found).

Destroyed:
Nothing.

Library: token.def

TokenInitTokenDB

Open the local token database file read/write and, if the path for a globally shared token database appears in the .INI file, open that file shared-multiple read-only.

Pass:
Nothing.

Returns:
CF - Set on error; clear on success.
dx - On error, this will be a TokenError value, one of ERROR_OPENING_SHARED_TOKEN_DATABASE_FILE, ERROR_OPENING_LOCAL_TOKEN_DATABASE_FILE, and BAD_PROTOCOL_IN_SHARED_TOKEN_DATABASE_FILE

Destroyed:
Nothing.

Library: token.def

TokenListTokens

Make a list of the tokens in the token.db file and return it in a memory block as an array of GeodeToken structures. Along with the list, the number of items in the list is returned. Because groups are mixed in with tokens, we have to do a preliminary pass to count the tokens, then allocate space and run through again grabbing tokens.

Pass:
ax - Zero if only tokens with GString monikers are requested. Non zero to request all monikers.
bx - Number of bytes to reserve for header in created block. If zero, token list will begin at top of returned block.
cx - ManufacturerID of tokens for list, if the TRF_ONLY_PASSED_MANUFID is set in ax

Returns:
bx - Handle of global memory block containing the list.
ax - Number of items in list.

Destroyed:
Nothing.

Library: token.def

TokenLoadMoniker

This routine loads a specified token’s moniker.

If you ask that this routine create an LMem block for you, and ds or es is pointing to that LMem block, you must fix ds or es yourself. E.g.:

push ds:[LMBH_handle] ; save LMem block handle  
(set up params)  
call TokenLoadMoniker  
pop bx  
call MemDerefDS

Pass:
ax, bx, si - Six bytes of token.
dh - DisplayType.
cx:di - Moniker destination.
If cx is zero, then a new global memory chunk will be allocated for the moniker.
If di is zero, then cx is interpreted as the handle of the LMem block in which to allocate an LMem chunk for the moniker.
Otherwise, cx:di is interpreted as the address to copy the moniker to.
ss:bp - Search flags and buffer size. Note that these arguments will be removed from the stack by this routine.

Pass on stack:
(Pushed in this order):
(word) VisMonikerSearchFlags.
(word) Size of buffer

Returns:
CF - Clear if token exists in database, set otherwise.
cx - Number of bytes in moniker.
di - Global memory block handle, or LMem chunk handle.

Destroyed:
Nothing.

Library: token.def

TokenLoadToken

Load TokenEntry structure for a token into a buffer.

If you ask that this routine create an LMem block for you, and ds or es is pointing to that LMem block, you must fix ds or es yourself. E.g.:

push ds:[0] ; save LMem block handle
call TokenLoadToken
pop bx
call MemDerefDS

Pass:
ds:bp - Pointer to source chunk.
cx - Zero to request that a global memory block be allocated, and that the chunk’s contents be copied to this block; Otherwise, meaning of cx depends on dx.
dx - Zero to specify that cx should be treated as the handle of an LMem block to copy to; Otherwise, cx:dx will be treated as the address to copy to.
ax - Offset specifying where in chunk to start copying. Use zero to start at the beginning.
bx - Flag specifying whether a null terminator should be appended at the end of the copy. One to request a null terminator, zero to omit it.
di - Offset specifying where to stop copying. This is an offset in chunk past the end. Use zero to copy to the end.

Returns:
ax - Chunk handle, if one created. Note that if created, the copied chunk is marked as dirty. The caller must clear the flags to set it otherwise.
cx - Number of characters copied (not including added null terminator, if any).
ds - Updated to point at segment of same block as on entry (only relevant if copying to lmem chunk).

Destroyed:
bx, dx, di, bp.

Library: ui.def

UserCreateDialog

Duplicates a template dialog block, attaches the dialog to an application object, and sets it fully usable. The dialog at this point may be used with UserDoDialog(). The dialog should be removed and destroyed by the caller when no longer needed.

Pass:
bx:si - Template object block, chunk offset of GenInteractionClass within it to invoke. The block must be sharable, read-only, and the top GenInteraction must not be linked into any generic tree.

Returns:
bx:si - Created, fully usable dialog (or zero if unable to create).

Destroyed:
Nothing.

Warning:
This routine may resize LMem and/or object blocks, moving them on the heap and invalidating stored segment pointers to them.

Library: ui.def

UserCreateInkDestinationInfo

This routine creates an InkDestinationInfo structure to be returned with MSG_META_QUERY_IF_PRESS_IS_INK.

Pass:
cx, dx - optr
bp - gstate for ink to be drawn through (or zero)
ax - width/height of ink (or zero for default)
bx:di - virtual fptr of callback routine (to be passed to ProcCallFixedOrMovable) to determine whether a stroke is a gesture or not (BX:DI=0 if none)

Returns:
bp - handle of an InkDestinationInfo structure (or zero if couldn’t allocate).

Destroyed:
Nothing

Library: ui.def

UserCreateItem

Create a GenItem for a given string.

Pass:
es:di - ptr to font string (NULL terminated)
*ds:si - parent
bx - block of parent
ds - pointing to a “fixupable” block
dx - mask OCF_IGNORE_DIRTY if created entry should be marked ignore dirty, 0 if not

Returns:
dx - lmem handle of new list entry
ds - updated to point at segment of same block as on entry

Destroyed:
Nothing.

Library: ui.def

Get the UI moniker font, size for the passed object.

Pass:
ds:si - Object to get the display type for (for future expansion possibilities).

Returns:
cx - FontID.

dx - Point size.

Destroyed:
Nothing.

Library: ui.def

UserGetDisplayType

Get the display type for the passed object. Currently reads the global variable uiDisplayType, set by GenScreen in MSG_GEN_SCREEN_SET_VIDEO_DRIVER.

Loads a GEOS application. Changes to standard application directory before attempting GeodeLoad on filename passed. Stores the filename being launched into the AppLaunchBlock, so that information needed to restore this application instance will be around later if needed.

Ownership of the launch block is transferred to the new geode and will be freed by it. If the application cannot be loaded, the block will be freed here. On no account should a passed AppLaunchBlock be referred to after this function returns.

Pass:
ah - AppLaunchFlags (zero for default). The ALF_SEND_LAUNCH_REQUEST_TO_UI_TO_HANDLE should be set if the actual launch should be done later by the UI, in a safe memory situation (no error code will be returned in this case). If this flag is clear, then the caller should be calling from a fixed memory space, such that none of their movable code segments are locked. This is to provide the most favorable conditions for the new application to be loaded in.
cx - Application attach mode message. This may be one of the following:
Zero: - Use ALB_appMode in AppLaunchBlock passed, or if there is none, use the default mode. If this is non-zero, any ALB_appMode in the launch block is overridden.
MSG_GEN_PROCESS_RESTORE_FROM_STATE: - State file must be passed, no data should be passed.
MSG_GEN_PROCESS_OPEN_APPLICATION: - State file should normally not be passed, although one could be to accomplish UI templates. A data file may be passed into the application as well.
MSG_GEN_PROCESS_OPEN_ENGINE: - State file normally should not be passed. The data file on which the engine will operate must be passed. If zero, the default data file should be used (this is enforced by the application, not GenProcessClass).
dx - Block handle of structure AppLaunchBlock (must be sharable) or zero for default case. This default case results in a mode of MSG_GEN_PROCESS_OPEN_APPLICATION, no data file, no template state file, launch to take place in the current default field, current directory is the data directory passed to the application.
ds:si - If the pathname is not in the AppLaunchBlock, then this may be a pointer to the absolute path of the file to load, or the file name of a file in either SP_APPLICATION or SP_SYS_APPLICATION.
si - If the fill pathname, filename, and diskhandle are stored in the AppLaunchBlock, then si is -1.
bx - If the path is specified in ds:si, then bx contains the disk handle, or a standard path (SP_APPLICATION or SP_SYS_APPLICATION). Otherwise, this register is ignored.

Returns:
bx - Geode process handle.
CF - Clear if no error; set if error.
ax - If no error, segment of geode’s core block. If there was an error, this register will hold the error code, of type GeodeLoadError.

Destroyed:
Nothing.

Library: ui.def

UserLoadExtendedDriver

Load an extended driver given the category of the .INI file in which to find the “device” and “driver” keys for the thing.

Pass:
ax - StandardPath enum for directory to look in
bx - Value to pass in bx to DRE_TEST_DEVICE and DRE_SET_DEVICE; may be garbage if driver being loaded doesn’t expect anything.
cx.dx - Protocol number expected
ds:si - Category

Returns:
CF - Clear if successful; set on error.
bx - On success, handle of loaded and initialized driver.
ax - On error, GeodeLoadError.

Destroyed:
cx, dx, di, si.

Library: ui.def

UserMessageIM

Send a message to the input manager.

Pass:
ax - Message to send.
di - Flags as in ObjMessage().
cx, dx, bp - Data to pass with message.

Returns:
CF - Returned as set by message handler.
di, cx, dx, bp - Data returned by message handler.
ds, es - Updated segments (depending on flags passed in di).

Destroyed:
Nothing.

Library: ui.def

UserRegisterForTextContext

Registers the passed object to receive context data.

Pass:
^lcx:dx - Object to register

Returns:
Nothing.

Destroyed:
Nothing.

Library: ui.def

UserRemoveAutoExec

Remove an application from the list of those to be launched on start-up.

Pass:
ds:si - Name of application to remove.

Returns:
Nothing.

Destroyed:
Nothing.

Library: ui.def

Play a standard sound.

Pass:
di - StandardSoundType.

cx - If playing a stream, this is the stream handle.
If playing a buffer, this is the segment of the buffer.
If playing a note, this is the frequency.
dx - If playing a buffer, this is the offset of the buffer.
If playing a note, this is its duration.
ds - DGroup.

Returns:
Nothing.

Destroyed:
di.

Library: ui.def

UserUnregisterForTextContext

Unregisters the passed object to receive context data.

Pass:
^lcx:dx - Object to unregister.

Returns:
Nothing.

Destroyed:
Nothing.

Library: ui.def

UtilAsciiToHex32

Converts a null-terminated ASCII string into a dword. The string may be signed or unsigned.

Pass:
ds:si - String to convert.

Returns:
CF - Set if error, clear if no error.
dx:ax - DWord value if no error. The ax register will hold a UtilAsciiToHexError value otherwise.

Destroyed:
Nothing.

Library: ui.def

UtilHex32ToAscii

Converts 32-bit unsigned number to its ASCII representation. The number may be signed or unsigned.

Pass:
dx:ax - String to convert.
cx - UtilHexToAsciiFlags, allowing the placement of leading zeros and/or a null terminator.
es:di - Buffer in which to place string. Should be of minimum size UHTA_NO_NULL_TERM_BUFFER_SIZE or UHTA_NULL_TERM_BUFFER_SIZE.

Returns:
CF - Set if error, clear if no error.
dx:ax - DWord value if no error. The ax register will hold a UtilAsciiToHexError value otherwise.
cx - Length of the string, not including null.

Destroyed:
Nothing.

Library: ui.def

Routines M-Q <– Table of Contents –> Routines V-Z