Figure 9-0

Display 9-0

SwatDisplay 9-0

Table 9-0
3

n	qsort



extern void _pascal qsort(

	void *array, 

	word count, 

	word elementSize,

	PCB(int, compare, (const void *, const void *)));

This is a standard quicksort routine. The callback routine must be decared 
_pascal.

n	QueueGetInfo()



word	QueueGetInfo(

	QueueHandle qh);			/* queue to query */

This routine returns information about a specific event queue. Pass the 
handle of the queue; for information about the current process' queue, pass a 
null handle. This routine returns the number of events (or messages) 
currently in the queue.

Include:	geode.h

n	QueueGetMessage()

EventHandle QueueGetMessage(

	QueueHandle qh);			/* queue to query */

This routine returns the next message on the given queue, blocking if the 
queue is empty. When a new message is added to the empty queue, this 
routine will unblock the thread and return the message. This routine is used 
almost exclusively by the kernel.

Include:	geode.h

n	QueuePostMessage()

void	QueuePostMessage(

	QueueHandle		qh,			/* queue to add event to */

	EventHandle		event,			/* event to be added to queue */

	MessageFlags		flags);			/* MF_INSERT_AT_FRONT or zero */

This routine adds the specified event to the passed queue. The only valid flag 
for this routine is MF_INSERT_AT_FRONT, which will put the event in the 
first spot of the queue.

Include:	geode.h

n	RangeEnum()

Boolean	RangeEnum(

	CellFunctionParameters			* cfp,				/* cell function parameters */

	RangeEnumParams			* params);				/* special other parameters */

This routine calls a callback routine for each cell in a specified range. This 
routine is passed pointers to two structures, both of which are shown below. 
It returns false if all the cells were processed, true if any of the cells caused 
the routine to abort before the end of the range was reached.

Callback Parameters:

The callback routine, which must be declared _pascal, receives a 
RangeEnumCallbackParams structure, which has the following 
definition:

typedef struct {
	RangeEnumParams			*RECP_params;		/* see below */
   /* current row, column, and cell data of cell */
	word			RECP_row;
	word			RECP_column;
	word			RECP_cellData;
} RangeEnumCallbackParams;

The callback routine can do anything with the cell information. It should 
return false after successfully processing the cell; if an error occurs, or if it 
wants to abort the RangeEnum(), it should return true.

Structures:	The CellFunctionParameters structure has the following definition:

typedef struct {
	CellFunctionParameterFlags				CFP_flags;
		/* can have the following flags:
		 * CFPF_DIRTY
		 *	set parameter block dirty
		 * CFPF_NO_FREE_COUNT
		 *	counts the number of calls to
		 *	a non-special RangeEnum() */
	VMFileHandle			CFP_file;
		/* VM file handle of cell file */
	VMBlockHandle			CFP_rowBlocks[N_ROW_BLOCKS];
		/* array of handles to grouped row blocks */
} CellFunctionParameters;

Include:	cell.h

n	RangeExists()



Boolean	RangeExists( /* returns non-zero if there are cells in range */

	CellFunctionParameters			* cfp,				/* see RangeEnum() */

	word			firstRow,				/* range delimiters */

	byte			firstColumn,

	word			lastRow,

	byte			lastColumn);

This routine returns true if there are any cells in the specified range. It is 
passed a pointer to the CellFunctionParameters structure for the cell file, 
as well as the indices of the first and last row, and the first and last column, 
of the range to check.

Include:	cell.h

n	RangeInsert()



void	RangeInsert(

	CellFunctionParameters			* cfp,				/* see RangeEnum() */

	RangeInsertParams			* rep);				/* parameters structure */

This routine shifts existing cells to make room for new ones. (It does not 
actually create new cells.) Which cells are shifted, and in what direction, is 
specified by the RangeInsertParams() structure. This structure has three 
fields:

RIP_bounds	A Rectangle structure which specifies which cells should be 
shifted. The cells currently in this range will be shifted across 
or down, depending on the value of RIP_delta; the shifted cells 
displace more cells, and so on, to the edge of the visible portion 
of the cell file. To insert an entire row (which is much faster 
than inserting a partial row), set RIP_bounds.R_left = 0 and 
RIP_bounds.R_right = LARGEST_COLUMN.

RIP_delta	A Point structure which specifies how far the cells should be 
shifted and in which direction. If the range of cells is to be 
shifted horizontally, RIP_delta.P_x should specify how far the 
cells should be shifted over, and RIP_delta.P_y should be zero. 
If the cells are to be shifted vertically, RIP_delta.P_y should 
specify how far the cells should be shifted over, and 
RIP_delta.P_x should be zero.

RIP_cfp	This is the address of the CellFunctionParameters 
structure. You don't have to initialize this; the routine will do 
so automatically.

Include:	cell.h

Warnings:	If cells are shifted off the "visible" portion of the cell file, you will be unable 
to access them by row or column numbers; but they will not be deleted. For 
this reason, you should free all such cells before calling RangeInsert(). (You 
can find out if there are any cells at the edges by calling RangeExists().) For 
an explanation of the "visible" and "scratch-pad" portions of a cell file, see 
Section 19.4.1 of the Concepts book.

n	realloc()



void *	realloc(

	void *		blockPtr,				/* address of memory to resize */

	size_t		newSize);				/* New size of memory 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.

If a geode needs to change the size of a section of memory assigned to it by 
the malloc() family of routines, it should use realloc(). realloc() resizes the 
piece of memory specified and returns the memory's new base address.

If the new size is smaller then the previous size, bytes will be cut off from the 
end. The request is guaranteed to succeed. Furthermore, the memory will not 
be moved; the address returned will be the same as the address passed.

If the new size is larger than the previous size, realloc() may move the data 
to accommodate the request. If so, it will return the new address. The new 
memory added will not be zero-initialized. If realloc() cannot fulfill the 
request, it will return a null pointer, and the memory will not be altered.

Resizing a stretch of memory down to zero bytes is exactly the same as 
freeing it with free(). If you pass a null address to realloc(), it will allocate 
the memory the same way malloc() does.

The memory must be in a malloc-block assigned to the geode calling 
realloc(). If you want to resize memory in another geode's malloc-block, call 
GeoReAlloc().

Warnings:	Pass exactly the same address as the one returned to you when you allocated 
the memory. If you pass a different address, the results are undefined.

See Also:	calloc(), free(), malloc(), GeoReAlloc()

n	SerialClose()



StreamError SerialClose(

	GeodeHandle 		driver,

	SerialUnit 		unit,

	Boolean 		linger);

Close the stream to a serial port.

n	SerialCloseWithoutReset()



StreamError SerialClose(

	GeodeHandle 		driver,

	SerialUnit 		unit,

	Boolean 		linger);

Close the stream to a serial port, without actually resetting the port.

n	SerialFlush()



StreamError SerialFlush(

	GeodeHandle 		driver,

	SerialUnit		unit,

	StreamRoles 		roles);

Flush all data pending in a serial port's input or output buffer (depending on 
the value of roles).

n	SerialGetFormat()



StreamError SerialGetFormat(

	GeodeHandle 		driver,

	SerialUnit 		unit,

	SerialFormat *		format,

	SerialMode *		mode,

	SerialBaud *		baud);

Get the format of a stream to a specified serial port.



n	SerialGetModem()

StreamError SerialGetModem(

	GeodeHandle 		driver,

	SerialUnit		unit,

	SerialModem *		modem);

Read a modem's hardware flow control bits.

n	SerialOpen()



StreamError SerialOpen(

	GeodeHandle 		driver,

	SerialUnit 		unit,

	StreamOpenFlags 		flags,

	word 		inBuffSize,

	word		outBuffSize,

	word 		timeout);

This routine opens a stream to the specified serial port. It is passed the 
following arguments:

driver	The GeodeToken of the serial driver.

unit	The serial port to open.

flags	This specifies whether the call should fail if the port is busy, or 
wait for a time to see if it will become free.

inBuffSize	The size of the stream buffer used for input from the serial port.

outBuffSize	The size of the stream buffer used for output to the serial port.

timeout	The number of clock ticks to wait for the port to become free. 
(This argument is ignored if flags is not 
STREAM_OPEN_TIMEOUT.)

If the routine is successful, it returns zero. If it is unsuccessful, it returns a 
member of the StreamError enumerated type.

n	SerialQuery()



StreamError SerialQuery(

	GeodeHandle 		driver,

	SerialUnit 		unit,

	StreamRoles role,

	word *		bytesAvailable);

Find out how much space is available in a serial buffer, or how much data is 
waiting to be read.

n	SerialRead()



StreamError SerialRead (

	GeodeHandle 		driver,

	SerialUnit 		unit,

	StreamBlocker 		blocker,

	word 		buffSize,

	byte *		buffer,

	word *		numBytesRead);

Read data from a serial port and write it to a passed buffer.

n	SerialReadByte()



StreamError SerialReadByte (

	GeodeHandle 		driver,

	SerialUnit 		unit,

	StreamBlocker 		blocker,

	word 		buffSize,

	byte *		dataByte);

Read a byte of data from a serial port and write it to a passed variable.

n	SerialSetFormat()



StreamError SerialSetFormat(

	GeodeHandle 		driver,

	SerialUnit 		unit,

	SerialFormat 		format,

	SerialMode		mode,

	SerialBaud 		baud);

Set the format for a stream to a specified serial port.

n	SerialSetModem()



StreamError SerialSetModem(

	GeodeHandle 		driver,

	SerialUnit		unit,

	SerialModem 		modem);

Set a modem's hardware flow control bits.

n	SerialWrite()



StreamError SerialWrite(

	GeodeHandle 		driver,

	SerialUnit 		unit,

	StreamBlocker 		blocker,

	word 		buffSize,

	const byte *		buffer,

	word *		numBytesWritten);

Write data to a serial port.

n	SerialWriteByte()



StreamError SerialWrite(

	GeodeHandle 		driver,

	SerialUnit 		unit,

	StreamBlocker 		blocker,

	word 		buffSize,

	byte		dataByte);

Write one byte of data to a serial port.

n	SGC_MACHINE

byte	SGC_MACHINE(val);

	dword	val;

This macro is used to extract the machine type from a SysGetConfig() 
return value.

Include:	system.goh

n	SGC_PROCESSOR

byte	SGC_PROCESSOR(val);

	dword	val;

This macro is used to extract the processor type from a SysGetConfig() 
return value.

Include:	system.goh

n	SoundAllocMusic()



MemHandle 	SoundAllocMusic(

	const word 		*song, 

	word 		voices );

This routine takes a pointer to a fixed buffer of music and returns a 
MemHandle which may then be passed to SoundPlayMusic() to play the 
music. If the music buffer is in a movable resource, you must initialize it 
using SoundInitMusic() instead of SoundAllocMusic(). To find out how to 
set up one of these buffers of music, see "Sound Library," Chapter 13 of the 
Concepts book. The voices argument is the number of voices in the buffer. 

n	SoundAllocMusicNote()



MemHandle SoundAllocMusicNote(

	word _far 		instrument, 

	word 		frequency, 

	word 		volume,

	word 		DeltaType, 

	word 		duration);

This routine allocates a MemHandle which may be passed to 
SoundPlayMusicNote(). You must provide all information about the note: 
its frequency, volume, and duration. You may specify an instrument, passing 
a value corresponding to a standard instrument (such as IP_PIANO). Specify 
the frequency in Hertz or use one of the constants such as MIDDLE_C_b to 
specify a standard note frequency. Volume ranges from zero to 0xffff-you 
may wish to use a constant value such as DYNAMIC_FFF if you want help 
trying to choose a loudness. The note's duration is determined by its delta 
type, one of SSDTT_MSEC, SSDTT_TICKS, and SSDTT_TEMPO. If you pass 
SSDTT_MSEC or SSDTT_TICKS, the duration is measured in milliseconds or 
ticks (each tick is one sixtieth of a second). If you pass SSDTT_TEMPO, you 
may set the size of your time unit when you call SoundPlayMusicNote(). 
The duration determines how many time units the note should play. If the 
delta type is SSDTT_TICKS and duration is 30, then the note will sound for 
half a second.

n	SoundAllocMusicStream()



MemHandle 	SoundAllocMusicStream(

	word 		streamType,

	word 		priority,

	word 		voices,

	word 		tempo);

This routine returns a token suitable for passing to 
SoundPlayMusicToStream(). It is passed several arguments. The 
SoundStreamType determines how much space to allocate for the stream 
and will determine how much data can be written to the stream at one time. 
If you pass SST_ONE_SHOT, it indicates that the stream will not be explicitly 
destroyed, and that your stream should destroy the stream when the song is 
done. You must specify how many voices there are in the music buffer. You 
must also pass a starting tempo for the music stream.

n	SoundAllocSampleStream()



MemHandle SoundAllocSampleStream(void);

This routine allocates a sample stream handle. If the returned handle is null, 
the library was unavailable (i.e. some other thread has grabbed exclusive 
access).

n	SoundDisableSampleStream()



void 	SoundDisableSampleStream(

	MemHandle 		mh);

This routine disassociates the DAC player from the passed sample handle. 
Before you play more sounds using the handle, you will have to call 
SoundEnableSampleStream() again. 

n	SoundEnableSampleStream()



Boolean 	SoundEnableSampleStream(

	MemHandle 		mh,

	word 		priority,

	word 		rate,

	word 		manufacturerID,

	word 		format);

This routine associates a DAC player with the allocated sample handle. You 
must pass the sound handle, as returned by SoundAllocSampleStream(). 
You must also pass certain pieces of information about the sound you will be 
playing on the DAC device: the priority with which to grab the DAC player 
(e.g. SP_STANDARD), the sampling rate, and the format of the sample (as 
identified by a manufacturerID and a DACSampleFormat value).

n	SoundFreeMusic()



void 	SoundFreeMusic(

	MemHandle 		mh);

This routine frees up a music handle. The music must not be playing; call 
SoundStopMusic() if you are not sure. You may not use the music handle 
after calling this routine on it.

n	SoundFreeMusicNote()



void SoundFreeMusicNote(

	MemHandle 		mh);

This routine frees up the passed note handle. The note must not be playing 
when you call this routine; call SoundStopMusicNote() if you are not sure. 
You should not try to use the note's handle after freeing it.

n	SoundFreeMusicStream()



void SoundFreeMusicStream(

	MemHandle 		mh);

This routine frees up the music stream's token. No music must be playing via 
the stream; call SoundDisableMusicStream() if you are not sure. Do not 
try to use the stream after calling this routine on it.

n	SoundFreeSampleStream()



void 	SoundFreeSampleStream(

	MemHandle 		mh);

This routine frees the passed sampled sound handle. You must not try to use 
this handle after calling this routine on it.

n	SoundGetExclusive()



void	SoundGetExclusive(void);

This routine grabs the exclusive semaphore for the sound library; if another 
thread has already grabbed the exclusive, this routine will wait until the 
exclusive is released. Sounds which are playing now will be permitted to 
finish, but from now on, only the thread calling this routine will be allowed 
to play new sounds. When done with the sound library exclusive, call 
SoundReleaseExclusive().

n	SoundGetExclusiveNB()



Boolean	SoundGetExclusiveNB(void);

This routine grabs the exclusive semaphore for the sound library, doing so 
even if some other thread has already grabbed the exclusive. Sounds which 
are playing now will be permitted to finish, but from now on, only the thread 
calling this routine will be allowed to play new sounds. This routine will 
return true if another thread already has exclusive access.

When done with the sound library exclusive, call 
SoundReleaseExclusive(). 

n	SoundInitMusic()



void SoundInitMusic(

	MemHandle 		mh, 

	byte 		voices);

This routine initializes a pre-defined simple music buffer structure. If the 
music buffer is stored in a fixed block, you can call SoundAllocMusic() 
instead. This allows a music buffer stored in a block referenced by a pointer 
to be playable using SoundPlayMusic().

n	SoundPlayMusic()



Boolean 	SoundPlayMusic(

	MemHandle 		mh, 

	word		priority,

	word 		tempo, 

	char 		flags);

This routine plays a buffer of music previously initialized by 
SoundInitMusic() or allocated by SoundAllocMusic(). The priority value 
will determine whether your sound will play if other sounds are already 
occupying the voices-pass a value such as SP_STANDARD. The tempo value 
will be used to determine the length of a 1/128th note. If your music buffer 
contained any notes whose lengths were measured by SSDTT_TEMPO delta 
type, then you should set this value accordingly. The flags argument 
determines whether the music's handle should be automatically freed when 
the sound is done playing. You may pass either or both of the flags 
UNLOCK_ON_EOS or DESTROY_ON_EOS.

Remember that you must have called SoundInitMusic() on the music 
handle before you may use it to play music.

Include:	sound.h

n	SoundPlayMusicNote()



Boolean 	SoundPlayMusicNote(

	MemHandle 		mh,				/* handle of note */

	word 		priority, 

	word		tempo,				

	word 		flags);			

This routine plays a buffer of music previously allocated by 
SoundAllocMusicNote()-the return value of that function is passed as 
mh. The priority value will determine whether your sound will play if other 
sounds are already occupying the voices-pass a value such as 
SP_STANDARD. The tempo value will be used to determine the length of a 
1/128th note. If your note's delta type is SSDTT_TEMPO, then you should set 
this value accordingly. The flags argument determines whether the notes's 
handle should be automatically freed when the note is done playing. You may 
pass either or both of the flags UNLOCK_ON_EOS or DESTROY_ON_EOS.

This routine returns true if the library was unavailable (i.e. if some other 
thread had grabbed the sound exclusive).

Include:	sound.h

n	SoundPlayToMusicStream()



Boolean 	SoundPlayToMusicStream(

	MemHandle 		mh,

	const word		* sample,

	word 		size,

	SampleFormatDescription 		*format);

This routine plays a music buffer to a stream. Specify which stream to play 
to by means of the token returned by SoundAllocMusicStream(). To play 
music to the buffer, pass the size of the buffer you are playing and a pointer 
to the start of the piece. This piece of buffer must be made up of whole 
events-it should not start or end in the middle of an event (e.g. you can't 
specify that you want to play a note but not give its frequency, even if you 
plan to play another buffer to the stream that might begin with a frequency). 

If you don't know the size of the buffer, it may be all right-any data in the 
buffer after the GE_END_OF_SONG will be ignored.

n	SoundPlayToSampleStream()



Boolean SoundPlayToSampleStream(

	MemHandle 		mh,

	word _far		* sample,

	word 		size,

	SampleFormatDescription 	* format);

This routine passes sampled sound data to a DAC player. You must pass a 
sample sound handle to this routine-to acquire such a handle, call 
SoundAllocSampleStream(). The sample sound handle must be 
associated with a DAC player-to so associate the handle, call 
SoundEnableSampleStream(). You must pass a pointer to the sample 
data, along with the size of the sample as measured in bytes. You may change 
the format information which will determine how the DAC player handles the 
data.

n	SoundReallocMusic()



Boolean 	SoundReallocMusic(

	MemHandle 		mh,

	word _far 		* song);

This routine allows you to associate a new music buffer with an existing 
music handle. The new music buffer must not have more voices than was 
originally requested with SoundAllocMusic(). Do not call this routine with 
the handle of a sound that may be playing; call SoundStopMusic() on the 
handle if you are not sure. See "Sound Library," Chapter 13 of the Concepts 
book to find out how to set up the buffer of music.

n	SoundReallocMusicNote()



Boolean 	SoundReallocMusicNote(

	MemHandle 		mh,

	word 		freq,

	word 		vol,

	word 		timer,

	word 		durat,

	word _far		* instrum);

This routine allows you to associate new note values with an existing note 
handle. Do not call this routine with the handle of a note that may be playing; 
call SoundStopMusicNote() on the handle if you are not sure. 

n	SoundReleaseExclusive()



void	SoundReleaseExclusive(void);

This routine releases the sound library exclusive semaphore. You will not 
need to call this routine unless your code calls SoundGrabExclusive() or 
SoundGrabExclusiveNB(). This routine allows other threads to play 
sounds. If another thread called SoundGrabExclusive() while your thread 
had the exclusive, it will now grab the exclusive.

n	SoundStopMusic()



Boolean 	SoundStopMusic(

	MemHandle 		mh); 		/* Handle of music buffer */

This routine stops the playing of a simple music buffer. It returns true if the 
library was unavailable (i.e. some other thread has grabbed the exclusive).

n	SoundStopMusicNote()



Boolean 	SoundStopMusicNote(

	MemHandle 		mh);

This routine stops a note that is playing. Pass the handle of the note, as was 
returned by SoundAllocMusicNote(). This routine returns true if the 
sound library was unavailable (i.e. some other thread has grabbed the 
exclusive). 

n	SoundStopMusicStream()



Boolean 	SoundStopMusicStream(

	MemHandle 		mh);

This routine stops any music being played to the stream. All sounds are 
flushed from the stream. It takes one argument, the token of the sound 
stream, as returned by SoundAllocMusicStream().

n	SoundStopSampleStream()



void 	SoundStopSampleStream(

	MemHandle 		mh);

This routine stops a sound playing through a previously allocated sampled 
sound stream.

n	SpoolConvertPaperSize()



word 	SpoolConvertPaperSize(

	int 		width,			/* width of paper */

	int 		height,			/* height of paper */

	PageType 		pt);			/* type of page */

This routine converts a width and height into a page size number.

Include:	spool.goh

n	SpoolCreatePaperSize()



Boolean 	SpoolCreatePaperSize( /* Returns true if failed */

	word 	* retValue,		/* returns paper size value */

	char 	* name,		/* name of paper size */

	int 	width,		/* width of paper */

	int 	length,		/* length of paper */

	PageLayout laytout);			/* default page layout */

This routine defines and stores a new paper size for later use by the user.

Include:	spool.goh

n	SpoolCreatePrinter()



Boolean	SpoolCreatePrinter( 	/* Returns true if error 
                (printer already exists) */

	char 		*name,				/* name of printer */

	PrinterDriverType 		type,				/* driver type */

	int 		* retVal); 				/* Will hold printer number */

Adds the printer to the list of currently installed printers and returns the 
new printer number. This routine is normally called from within the 
Preferences manager. Returns true if the printer already exists.

Include:	spool.goh

n	SpoolDeletePaperSize()



Boolean 	SpoolDeletePaperSize(

	word 	size);		/* size number to delete */

This routine deletes a user-defined paper size.

Include:	spool.goh

n	SpoolDeletePrinter()



void 	SpoolDeletePrinter(

	int 	prtrNum);		/* printer number to delete */

Deletes the requested printer from the system.

Include:	spool.goh

n	SpoolGetDefaultPrinter()



int 	SpoolGetDefaultPrinter(); /* Returns printer number */

Returns the system-default printer, which is used (for example) by the 
PrintControlClass as the default printer to print to.

Include:	spool.goh

n	SpoolGetNumPaperSizes()



int 	SpoolGetNumPaperSizes(

	PageType 	type);		/* type of page */

Use this routine to find the number of paper sizes, both pre-defined and 
user-defined, that should appear in a paper size list.

Include:	spool.goh

n	SpoolGetNumPrinters()



int 	SpoolGetNumPrinters(

	PrinterDriverType		type);			/* driver type */

This routine returns the number of installed printers with the given type.

Structures:	

	typedef ByteEnum PrinterDriverType;

	/* The driver type may be one of the following:
PDT_PRINTER,
PDT_PLOTTER,
PDT_FACSIMILE,
PDT_CAMERA,
PDT_OTHER,
PDT_ALL		*/

Include:	spool.goh

n	SpoolGetPaperSize()



XYSizeAsDWord SpoolGetPaperSize(

	int 		size, 			/* This must be between 0 and the return 
					 	 * value of SpoolGetNumPaperSizes() */

	PageType 		pt,	 		/* type of page */

	PageLayout 		*layout);			/* Will hold returned page layout */

Use this routine to determine the dimensions of a paper size.

Include:	spool.goh

n	SpoolGetPaperSizeOrder()



dword 	SpoolGetPaperSizeOrder( /* High byte is number of unused sizes;
	                  * Low byte is # of ordered sizes */

	PageType 		type,

	byte 		*order, 				/* buffer of size MAX_PAPER_SIZES */
						/* On return, this buffer will be 
						 * filled with the page size numbers
						 * arranged in the order 
						 * corresponding to their display */

	byte 		*userSizes); 		/* buffer of size MAX_PAPER_SIZES */
							/* On return, will hold ordered 
							 * array of user paper sizes. */

n	SpoolGetPaperSizeString()



Boolean 	SpoolGetPaperSizeString( /* true if error*/

	char 		* retValue,				/* buffer for returned value */

	int 		size,		/* Must be between 0 and the return
					 * value of SpoolGetNumPaperSizes() */

	PageType		pt);		/* type of page */

Use this routine to determine the string to be displayed for a specific paper 
size. Upon return, retValue will point to a character string and the Boolean 
return value will be false if successful. If any error occurs, or if the page type 
couldn't be found, the returned value will be true.

Include:	spool.goh

n	SpoolGetPrinterString()



Boolean	SpoolGetPrinterString( /* Returns true if error */

	int 	*retValue,	/* On return, will point to length of string */

	char 	*string,	/* returned name string */

	int 	prtrNum);	/* printer number */

This routine fills a buffer with the requested null-terminated printer name 
string. If the printer could not be found, the return value will be true (set for 
error).

Include:	spool.goh

n	SpoolSetDefaultPrinter()



void 	SpoolSetDefaultPrinter(

	int prtrNum);		/* printer number */

Sets the system-default printer, used (for example) by PrintControlClass 
as the default printer. This routine is normally called from within the 
Preferences manager.

Include:	spool.goh

n	SpoolSetDocSize()

void 	SpoolSetDocSize(

	Boolean 		open;			/* false if document is closed */

	PageSizeInfo 		* psr);			/* NULL if document is closed */

This routine tells the application's PageSizeControl object the document's 
size.

Include:	spool.goh

n	SpoolSetPaperSizeOrder()



void 	SpoolSetPaperSizeOrder(

	void 	* ptr, 		/* Array of PageSizeOrder entries */

	word 	number);		/* number of entries in array */

This routine resets the order in which paper sizes are displayed to the user.

Include:	spool.goh

n	SpreadsheetInitFile()



VMBlockHandle SpreadsheetInitFile(

	const SpreadsheetInitFileData					* ifd);

This routine initializes a VM file for use by the spreadsheet object. It allocates 
a spreadsheet map block in the file and initializes this block. The routine 
returns the map block's handle; applications will need to remember this 
handle. It does not change any existing blocks in the VM file.

The ifd parameter is pointer to a SpreadsheetInitFileData structure 
containing the file handle and the number of rows and columns to allocate.

Structures:	The SpreadsheetInitFileData structure is defined as follows:

typedef struct {
	word				SIFD_file;
	word				SIFD_numRows;
	word 				SIFD_numCols;
	SpreadsheetDrawFlags				SIFD_drawFlags;
} SpreadsheetInitFileData;

/* SpreadsheetDrawFlags:
 * SDF_DRAW_GRAPHICS
 * SDF_DRAW_NOTE_BUTTON
 * SDF_DRAW_HEADER_FOOTER_BUTTON
 * SDF_DRAW_GRID				*/

Include:	ssheet.goh

n	StreamClose()



StreamError StreamClose (

	GeodeHandle 		driver,

	StreamToken 		stream,

	Boolean 		linger);

This routine shuts down a stream. It is passed the following arguments:

driver	The GeodeToken of the stream driver.

stream	The StreamToken of the stream.

linger	Set true (i.e., non-zero) if the data currently in the stream 
should be kept until it's read; set false to flush the data 
immediately.

If the routine is successful, it returns zero. If it is unsuccessful, it returns a 
member of the StreamError enumerated type.

n	StreamFlush()



StreamError StreamFlush (

	GeodeHandle 		driver,

	StreamToken 		stream);

This routine flushes all the data pending in a stream. It is passed the 
following arguments:

driver	The GeodeToken of the stream driver.

stream	The StreamToken of the stream.

If the routine is successful, it returns zero. If it is unsuccessful, it returns a 
member of the StreamError enumerated type.

n	StreamOpen()



StreamError	 StreamOpen (

	GeodeHandle 		driver,

	word 		buffSize,

	GeodeHandle		owner,

	HeapFlags 		heapFlags,

	StreamToken *		stream);

This routine opens a stream. It is passed the following:

driver	The GeodeToken of the stream driver.

buffSize	The size of the stream buffer, in bytes.

owner	The geode which will own the stream.

heapFlags	The flags for the creation of the buffer block.

*stream	The stream token will be written here.

If StreamOpen() is successful, it returns zero and writes the stream's token 
to *stream. If it is unsuccessful, it returns a member of the StreamError 
enumerated type.

n	StreamQuery()



StreamError StreamQuery (

	GeodeHandle 		driver,

	StreamToken 		stream,

	StreamRoles 		role,

	word *		bytesAvailable);

This routine finds out either how much free space is available in a stream's 
buffer, or how much data is waiting to be read. It is passed the following 
arguments:

driver	The GeodeToken of the stream driver.

stream	The StreamToken of the stream.

role	If this is STREAM_ROLES_WRITER, the routine will return the 
amount of free space available in the stream buffer. If it is 
STREAM_ROLES_READER, it will return the amount of data 
waiting to be read.

*bytesAvailable
The routine will write the number of bytes available (for 
writing or reading) to this variable.

If the routine is successful, it returns zero. If it is unsuccessful, it returns a 
member of the StreamError enumerated type.

n	StreamRead()



StreamError StreamRead (

	GeodeHandle 		driver,

	StreamToken 		stream,

	StreamBlocker 		blocker,

	word 		buffSize,

	byte *		buffer,

	word *		numBytesRead);

This routine reads data from a stream. The routine takes the following 
arguments:

driver	The GeodeToken of the stream driver.

stream	The StreamToken of the stream.

blocker	Specify whether to block if there is not enough data waiting to 
be read.

buffsize	Size of passed buffer (i.e. amount of data to read from stream).

buffer	Pointer to buffer where data from stream will be written.

*numBytesReadRead
StreamRead() will write to this variable the number of bytes 
actually read from the stream.

If StreamRead() is successful, it returns zero. If it is unsuccessful, or could 
not read all the data requested from the stream, it returns a member of the 
StreamError enumerated type.

n	StreamReadByte()



StreamError StreamWriteByte (

	GeodeHandle 		driver,

	StreamToken 		stream,

	StreamBlocker 		blocker,

	byte *		dataByte);

This routine reads a single byte from a stream. It takes the following 
arguments:

driver	The GeodeToken of the stream driver.

stream	The StreamToken of the stream.

blocker	Specify whether to block if there is not enough room to write 
the data.

*dataByte	Read a byte from the stream, and write it to this variable.

If the routine is successful, it returns zero. If it is unsuccessful, it returns a 
member of the StreamError enumerated type.

n	StreamWrite()



StreamError StreamWrite (

	GeodeHandle 		driver,

	StreamToken 		stream,

	StreamBlocker 		blocker,

	word 		buffSize,

	const byte *		buffer,

	word *		numBytesWritten);

This routine writes data to a stream. The routine takes the following 
arguments:

driver	The GeodeToken of the stream driver.

stream	The StreamToken of the stream.

blocker	Specify whether to block if there is not enough room to write all 
the data.

buffsize	Size of passed data buffer (i.e. amount of data to write to 
stream).

buffer	Pointer to data to write to stream.

*numBytesWritten
StreamWrite() will write to this variable the number of bytes 
actually written to the stream.

If StreamWrite() is successful, it returns zero. If it is unsuccessful, or could 
not write all the data to the stream, it returns a member of the StreamError 
enumerated type.

n	StreamWriteByte()



StreamError StreamWriteByte (

	GeodeHandle 		driver,

	StreamToken 		stream,

	StreamBlocker 		blocker,

	byte 		dataByte);

This routine writes a single byte to a stream. It takes the following 
arguments:

driver	The GeodeToken of the stream driver.

stream	The StreamToken of the stream.

blocker	Specify whether to block if there is not enough room to write 
the data.

dataByte	Write this byte to the stream.

If the routine is successful, it returns zero. If it is unsuccessful, it returns a 
member of the StreamError enumerated type.

n	SysGetConfig()

dword	SysGetConfig();

This routine returns a set of values defining the system configuration. The 
returned dword contains four byte values, listed below from least significant 
byte to most significant byte:

configuration flags
This byte contains a record of SysConfigFlags reflecting the 
system status. This record includes information on how the 
system was started, whether Swat is running it, whether the 
system was restarted, etc.

reserved byte
This byte contains reserved information unusable by 
applications.

processor type
This byte contains a value reflecting the processor type of the 
machine running GEOS. This is of type SysProcessorType 
and is one of SPT_8088, SPT_8086, SPT_80186, SPT_80286, 
SPT_80386, or SPT_80486. Use the macro SGC_PROCESSOR to 
extract this value from the returned dword.

machine type
This byte contains a value of SysMachineType indicating the 
type of the machine running GEOS. It may be one of the 
following values: SMT_UNKNOWN, SMT_PC, SMT_PC_CONV, 
SMT_PC_JR, SMT_PC_XT, SMT_PC_XT_286, SMT_PC_AT, 
SMT_PS2_30, SMT_PS2_50, SMT_PS2_60, SMT_PS2_80, or 
SMT_PS1. Use the macro SGC_MACHINE to extract this value 
from the returned dword.

Include:	system.h

n	SysGetDosEnvironment()

Boolean	SysGetDosEnvironment( /* true if error (not found) */

	const char		* variable,				/* environment variable */

	char		* buffer,				/* buffer for return value */

	word		bufSize);				/* maximum return string length */

This routine looks up a specified DOS environment variable in the 
environment buffer. It takes three parameters:

variable	A pointer to the null-terminated character string representing 
the name of the variable to be searched for.

buffer	A pointer to a locked or fixed buffer in which the variable's 
value will be returned.

bufSize	The size of the passed buffer in bytes (the maximum number of 
characters that can be returned including the terminating null 
character).

If the variable is not found, the error flag returned will be true.

Include:	system.h

n	SysGetECLevel()

ErrorCheckingFlags SysGetECLevel(

	MemHandle * checksumBlock);

This routine checks the current error-checking level of the system. The 
returned record of ErrorCheckingFlags describes which levels of error 
checking are turned on and which are off. If checksum error checking 
(ECF_BLOCK_CHECKSUM) is on, pass a pointer to the handle of a block on 
which the checksum will be done.

Include:	ec.h

n	SysGetInfo()

dword	SysGetInfo(

	SysGetInfoType info);			/* type of information to retrieve */

This routine returns general system information. Pass the type of 
information to be returned; the value returned depends on the type passed in 
info. Note that the largest returned value is a dword; many different return 
values should be cast to the appropriate type when calling SysGetInfo().

The info parameter (of SysGetInfoType) can have one of the following 
values:

SGIT_TOTAL_HANDLES
Returns the total number of handles in the kernel's handle 
table.

SGIT_HEAP_SIZE
Returns the total heap size in bytes.

SGIT_LARGEST_FREE_BLOCK
Returns the size (in bytes) of the largest possible block that 
may be allocated at the moment.

SGIT_TOTAL_COUNT
Returns the total number of clock ticks since the current 
session of GEOS started (subtracts the initial system clock 
value from the current time).

SGIT_NUMBER_OF_VOLUMES
Returns the total number of volumes registered with the 
system.

SGIT_TOTAL_GEODES
Returns the total number of geodes currently loaded.

SGIT_NUMBER_OF_PROCESSES
Returns the total number of processes currently loaded.

SGIT_NUMBER_OF_LIBRARIES
Returns the total number of libraries currently loaded.

SGIT_NUMBER_OF_DRIVERS
Returns the total number of drivers currently loaded.

SGIT_CPU_SPEED
Returns the CPU speed of the processor. The value returned 
will be ten times the ratio of the CPU speed relative to a base 
XT processor.

SGIT_SYSTEM_DISK
Returns the disk handle of the disk on which GEOS (the 
GEOS.INI file) resides.

SGIT_UI_PROCESS

Include:	sysstats.h

n	SysGetPenMode()

Boolean	SysGetPenMode();

This routine returns true if GEOS is running on a pen-based system, false if 
it is not.

Include:	system.h

n	SysLocateFileInDosPath()

DiskHandle SysLocateFileInDosPath( /* sets thread's error value */

	const char		* fname,				/* file name */

	char		* buffer);				/* returned path of file */

This routine searches for a specified file along the search path specified in the 
DOS environment variable PATH. The parameters are

fname	A pointer to the null-terminated file name to search for.

buffer	A pointer to a locked or fixed buffer into which the full path of 
the file will be placed.

This routine returns the disk handle of the disk on which the file resides as 
well as the file's full path (with drive name) in the buffer pointed to by buffer. 
The path returned is a null-terminated character string. If the file could not 
be found, a null disk handle will be returned. The error value can be retrieved 
with ThreadGetError().

Include:	system.h

n	SysNotify()



word	SysNotify(

	SysNotifyFlags		flags,				/* options to offer user */

	const char 		* string1,				/* first string to display */

	const char 		* string2);				/* second string to display */

This routine causes the kernel to put up a standard notification dialog box on 
the screen. This dialog box is white with a black border and is used nearly 
exclusively for error notification by the kernel. Pass this routine the following 
parameters:

flags	A record of SysNotifyFlags indicating the options the dialog 
presents to the user. These flags are shown below.

string1	A pointer to a null-terminated character string put up in the 
dialog box (may be a null pointer).

string2	A pointer to a second null-terminated string presented in the 
dialog box (may be a null pointer).

The returned word is the user's response, based on the SysNotifyFlags 
passed (see below).

Structures:	SysNotifyFlags is a record of several flags; none, any, or all of the flags may 
be set at a time. The five flags are

SNF_RETRY	Allow the user to retry the operation that brought up the 
notification box. If the user selects this option, it will be 
returned by the routine.

SNF_EXIT	Allow the user to exit GEOS entirely. If the user selects this 
option, it will be returned by the routine after an 
SST_CLEAN_FORCED shutdown has been initiated.

SNF_ABORT	Allow the user to abort the operation that brought up the 
notification box. If the user selects this option, it will be 
returned by the routine.

SNF_CONTINUE
Allow the user to continue the operation. If the user selects this 
option, it will be returned by the routine.

SNF_REBOOT
Allow the user to shut down and reboot GEOS directly. If the 
user selects this option, the routine will not return.

Include:	system.h

n	SysRegisterScreen()



void	SysRegisterScreen(

	GeodeHandle		driver,

	WindowHandle		root);

n	SysSetECLevel()

void	SysSetECLevel(

	ErrorCheckingFlags		flags,					/* level of error checking */

	MemHandle		checksumBlock);					/* block to check, if any */	

This routine sets the error-checking level of the software. Pass it a record of 
ErrorCheckingFlags indicating which levels of error checking should be 
employed. If checksum checking (ECF_BLOCK_CHECKSUM) is turned on, 
also pass the handle of a block on which the checksum will be performed.

Include:	ec.h

n	SysSetExitFlags()



word	SysGetExitFlags(

	ExitFlags		bitsToSet,

	ExitFlags		bitsToClear);

n	SysShutdown()



Boolean	SysShutdown(

	SysShutdownType type,

	...);

This routine causes the system to shut down, exiting to the native operating 
system (typically DOS). It takes variable parameters depending on the first 
parameter. The first parameter is the type of shutdown requested, and it 
determines the calling format of the routine. SysShutdown() returns a 
Boolean value dependent on the type of shutdown.

The parameters and calling format for this routine depend on the value in the 
type parameter. The possible values (SysShutdownType) are listed below 
with the associated parameter and return information.

SST_CLEAN	Shut down all applications cleanly, allowing any that wish to to abort the 
shutdown. The routine will return true if a system shutdown is already 
in progress at the time of the call. This type of shutdown will send 
MSG_META_CONFIRM_SHUTDOWN to all objects registered on the 
MANUFACTURER_ID_GEOWORKS:GCNSLT_SHUTDOWN_CONTROL GCN 
list (but only if the shutdown is not cancelled). Each object on that list 
must return an acknowledgment of the shutdown. The parameter format 
and parameters are

Boolean SysShutdown(
	SysShutdownType			type,
	optr			notificationOD,
	Message			msg);

notificationOD
The optr of an object which will receive the message passed in 
msg after the shutdown has been acknowledged. Pass a null 
optr to use the default notification (MSG_META_DETACH sent 
to the UI).

msg	The message to be sent to the object in notificationOD.

SST_CLEAN_FORCED
Shut down all applications cleanly without the possibility of cancellation. 
This type takes no additional parameters and does not allow other geodes 
to abort the shutdown. It will return, but the return value will be 
meaningless.

SST_DIRTY	Attempt to exit device drivers and close all files without shutting down 
applications. Does not return. The parameters of this type are

Boolean SysShutdown{
	SysShutdownType			type,		/* SST_DIRTY */
	const char			* reason);

	The reason parameter is a pointer to a text string presented to the user 
as a reason for the dirty shutdown. The string is null-terminated. Pass -1 
if no reason is to be given.

SST_PANIC	Exit system device drivers (GA_SYSTEM) without exiting applications or 
closing files. This can be bad for the system and should be used only in 
emergency situations. This type of shutdown takes no additional 
parameters and does not return.

SST_REBOOT
This is used by GEOS when the user hits Ctrl-Alt-Del. Applications 
should not call it.

SST_RESTART
This is like SST_CLEAN_FORCED above, but it reloads GEOS after 
shutting down rather than exit completely. It takes no additional 
parameters; it will return TRUE if the system could not be restarted, 
FALSE if the shutdown has been initiated.

SST_FINAL	Perform the final phase of a shutdown. This routine is called only by the 
UI when the SST_CLEAN_FORCED shutdown is complete. This type does 
not return, and it takes one additional parameter. The calling format and 
parameters of this type are

Boolean SysShutdown(
	SysShutdownType			type,
	const char			* reason);

	The reason parameter is a character string explaining the reason 
(typically an error) for the final shutdown.

SST_SUSPEND
Suspend system operation in preparation for task switching, and 
broadcast MSG_META_CONFIRM_SHUTDOWN to all objects on the 
MANUFACTURER_ID_GEOWORKS:GCNSLT_SHUTDOWN_CONTROL GCN 
list (see MetaClass). All notified objects must return acknowledgment of 
the shutdown. This type of SysShutdown() returns true if another 
system shutdown is already in progress. It takes two additional 
parameters:

Boolean SysShutdown(
	SysShutdownType			type,
	optr			notificationOD,
	Message			msg);

notificationOD
The optr of an object which will receive the message passed in 
msg after the shutdown has been acknowledged. Pass a null 
optr to use the default notification (MSG_META_DETACH sent 
to the UI), though this is not usually the intent of the call.

msg	The message to be sent to the object in notificationOD.

SST_CONFIRM_START
Called by the recipient of MSG_META_CONFIRM_SHUTDOWN; this 
allows shutdown confirmation dialog boxes to be presented in order to the 
user. The caller of this type will be blocked until all previous callers have 
finished their confirmation procedure. When SysShutdown() returns, 
the caller may present its confirmation dialog and continue or abort the 
shutdown. If SysShutdown() returns true from a call with this type, the 
caller should not present the confirmation dialog to the user and need not 
call SysShutdown() with SST_CONFIRM_END; another thread has 
already cancelled the shutdown. This type takes no additional 
parameters.

SST_CONFIRM_END
The counterpart of SST_CONFIRM_START, this ends the confirmation 
sequence in an object's MSG_META_CONFIRM_SHUTDOWN handler. It 
takes one additional parameter and returns nothing. The calling format 
is shown below:

void	SysShutdown(
	SysShutdownType			type,
	Boolean			confirm);

	The confirm parameter should be TRUE if the shutdown is to be 
continued, FALSE if the shutdown should be aborted.

Include:	system.h

Warnings:	Most applications should not call SysShutdown(). Any that do should do so 
with extreme care.

n	SysStatistics()

void	SysStatistics(

	SysStats * stats);			/* returned statistics */

This routine returns system performance statistics. Pass it a pointer to an 
empty SysStats structure; the routine will fill in the appropriate fields. 
SysStats has the following structure:

typedef struct {
    dword			SS_idleCount;
    SysSwapInfo			SS_swapOuts;
    SysSwapInfo			SS_swapIns;
    word			SS_contextSwitches;
    word			SS_interrupts;
    word			SS_runQueue;
} SysStats;

Include:	sysstats.h

n	SysUnlockBIOS()



void	SysUnlockBIOS(void);

n	TextSearchInString()



char *	TextSearchInSTring(

	const char		*str1,

	conat char		*startPtr,

	const char		*endPtr,

	word		strSize,

	const char		*str2,

	word		str2Size,

	word		searchOptions,

	word		*matchLen);

TextSearchInString() searches in a single text chunk for a passed text string. 
If a match is found, a pointer to that match (and the length of the match) are 
returned in passed buffers. 

str1 is a pointer to the main string you will be searching in.

startPtr and endPtr are pointers to locations within str1 to begin and end the 
search.

strSize stores the size of str1, or zero if null-terminated.

str2 stores the match string, which may include wildcards (type WildCard).

str2Size stores the size of str2, or zero if null-terminated.

searchOptions stores the SearchOptions to use by the search mechanism. 
The high byte should be zeroed.

matchLen stores a buffer to store the size of the matched word. (The matched 
word itself is returned by the routine.)

Include:	Objects/vTextC.goh

n	TextSearchInHugeArray()



dword	TextSearchInSTring(

	char		*str2,

	word		str2Size,

	dword		str1Size,

	dword		curOffset,

	dword		endOffset,

	FileHandle		hugeArrayFile,

	VMBlockHandle		hugeArrayBlock,

	word		searchOptions,

	word		*matchLen);

TextSearchInHugeArray() searches in a huge array for a passed text string. 
If a match is found, a dword offset to the match (and the length of the match) 
are returned in passed buffers. 

str2 stores the match string, which may include wildcards (type WildCard).

str2Size stores the size of str2, or zero if null-terminated.

str1Size stores the total length of the string being searched.

curOffset stores the offset from the start of str1 to the first character to check.

endOffset stores the offset from the start of str1 to the last character to check.

hugeArrayFile stores the file handle of the huge array.

hugeArrayBlock stores the VM block handle of the huge array.

searchOptions stores the SearchOptions to use by the search mechanism. 
The high byte should be zeroed.

matchLen stores a buffer to store the size of the matched word. (The matched 
word itself is returned by the routine.)

Include:	Objects/vTextC.goh

n	TGI_PRIORITY()

byte	TGI_PRIORITY(val);

	word	val;

This macro extracts the thread priority from the value returned by 
ThreadGetInfo().

n	TGI_RECENT_CPU_USAGE()

byte	TGI_RECENT_CPU_USAGE(val);

	word	val;

This macro extracts the recent CPU usage from the value returned by 
ThreadGetInfo().

n	ThreadAllocSem()



SemaphoreHandle ThreadAllocSem(

	word	value);			/* allowable locks on the semaphore */

This routine allocates and initializes a new semaphore for private use by a 
multithreaded application. Pass the value with which to initialize the 
semaphore; this value represents the number of threads that can grab the 
semaphore before other grab attempts will block. Typically, the passed value 
will be one. The routine returns the handle of the new semaphore.

Include:	sem.h

n	ThreadAllocThreadLock()



ThreadLockHandle ThreadAllocThreadLock();

This routine allocates a special semaphore called a thread lock. With a 
normal semaphore, a thread that grabs the semaphore twice without 
releasing it will deadlock; with a thread lock, a thread can grab it more than 
once in succession. The thread has to release it once for each time it grabs the 
thread lock, however.

In all other aspects, however, the thread lock resembles a normal semaphore. 
ThreadAllocThreadLock() returns the handle of the new thread lock.

Include:	sem.h

n	ThreadAttachToQueue()



void	ThreadAttachToQueue(

	QueueHandle		qh,				/* queue to attach */

	ClassStruct		* class);				/* primary class of thread */

This routine attaches the calling thread to the passed event queue. This is 
used only for event-driven threads. Typically, this routine is called when a 
thread is created; attaching to queues is automatic in nearly all cases, and 
you will rarely need this routine.

Pass the handle of the queue in qh and a class pointer in class. The class will 
be attached to the event queue and will handle all messages sent directly to 
the thread. This class should nearly always be a subclass of ProcessClass.

If a queue handle of zero is passed, the thread wants to "reattach" to the 
current queue. This is used typically during shutdown of event-driven 
threads, and it is nearly always taken care of automatically by 
ProcessClass.

Include:	thread.h

n	ThreadCreate()



ThreadHandle ThreadCreate(

	word	priority,			/* Initial base priority of new thread */

	word	valueToPass,			/* Optional data to pass to new thread */

	word	(*startRoutine)(word valuePassed),
				/* Pointer to entry routine */

	word	stackSize,			/* Size of the stack for the new thread */

	GeodeHandle owner);				/* Geode that will own the new thread */

This routine creates a new procedural thread for a process. If you need a new 
event-driven thread, send MSG_PROCESS_CREATE_EVENT_THREAD to your 
process object instead.

Pass the following parameters to this routine:

priority	The priority of the new thread. Typically this will be one of the 
standard thread priorities (see below).

valueToPass
A word of optional data to be passed to the entry routine of the 
new thread. This can be used, for example, to indicate the 
thread's initial context or for initializing thread variables.

startRoutine
A pointer to the entry routine to be executed immediately for 
the thread. This may be in either fixed or movable memory. The 
segment must be a virtual segment. Note that if the routine is 
in movable memory, it may degrade heap performance for the 
life of the thread (its movable block will remain locked for 
extended stretches of time). The routine may return the 
thread's exit code or may call ThreadDestroy() directly.

stackSize	The stack size allocated for the thread. 512 bytes is typically 
enough for threads doing neither UI nor file system work; 
threads working with the file system will require 1 K. Threads 
working with UI objects will require 3 K.

owner	The geode handle of the geode that will own the thread. If the 
calling thread's geode will own the new thread, it can call 
GeodeGetProcessHandle() prior to calling 
ThreadCreate().

ThreadCreate() returns the thread handle of the new thread. If an error 
occurs, the calling thread's error code will be set and a null handle returned; 
you should likely call ThreadGetError() to retrieve the error code after 
creating the new thread. A return of NO_ERROR_RETURNED from 
ThreadGetError() means no error occurred.

The standard thread priorities that may be passed in the priority parameter 
are listed below:

PRIORITY_TIME_CRITICAL
The highest priority of all; you should not use this in general 
because it will pre-empt nearly all other threads. (It may be 
useful, however, during debugging.)

PRIORITY_HIGH
A high priority; generally only used for highly important 
threads.

PRIORITY_UI
Another high priority; this is used for User Interface threads to 
provide quick response to user actions.

PRIORITY_FOCUS
A medium-level priority; this is used for whatever thread has 
the current input focus (whichever thread the user is currently 
working with).

PRIORITY_STANDARD
The standard application thread priority; you should typically 
use this when creating new threads.

PRIORITY_LOW
A low priority for tasks that can be done in the background.

PRIORITY_LOWEST
The lowest standard priority; it is used for threads that can 
take any amount of time to complete.

Include:	thread.h

n	ThreadDestroy()



void	ThreadDestroy(

	word	errorCode,	/* Error code to indicate cause of destruction */

	optr	ackObject,	/* Object to receive destruction acknowledgment */

	word	ackData);	/* Additional word of data to pass (as the low
			 * word of optr for source of MSG_META_ACK) */

This routine causes the current (calling) thread to exit and then destroy 
itself. The thread is responsible for ensuring that it has no leftover resources 
allocated or semaphores locked.

Pass it an error code or exit code meaningful to the application and the other 
threads in the application. This error code will be used by the debugger to 
determine the cause of the thread's exit; a null error code usually indicates 
successful completion of the thread's task.

Pass also the optr of the object to receive acknowledgement of the thread's 
destruction. The object specified will receive MSG_META_ACK after the 
calling thread is completely destroyed.

Be Sure To:	Always clean up before exiting a thread. Unlock locked resources, free 
allocated memory, etc. You do not have to do these things for the application's 
primary thread; the process object (the primary thread) will automatically 
clean up after itself.

Include:	thread.h

n	ThreadFreeSem()



void	ThreadFreeSem(

	SemaphoreHandle sem);			/* semaphore to be freed */

This routine frees the specified semaphore that had been allocated with 
ThreadAllocSem(). You must be sure that no threads are using the 
semaphore or will use it after it has been freed. Subsequent access attempts 
could cause illegal handle errors or worse.

Include:	sem.h

n	ThreadFreeThreadLock()



void	ThreadFreeThreadLock(

	ThreadLockHandle sem);				/* thread lock to be freed */

This routine frees the specified thread lock that had been allocated with 
ThreadAllocThreadLock(). You must be sure that no threads are using or 
will use the thread lock after it has been freed. Subsequent attempts to grab 
or release the thread lock could cause illegal handle errors.

Include:	sem.h

n	ThreadGetError()



word	ThreadGetError(void)

This routine returns the thread's current error value.

n	ThreadGetInfo()



word	ThreadGetInfo(

	ThreadHandle		th,			/* thread to get information about */

	ThreadGetInfoType 		info);			/* type of information to get */

This routine gets information about the specified thread. The information 
desired is specified in the info parameter; the subject thread is specified in 
the th parameter. If the thread handle passed is zero or a null handle, the 
routine will return information about the calling thread.

The info parameter is one of the following values of ThreadGetInfoType, 
specifying the type of information to be returned by ThreadGetInfo():

TGIT_PRIORITY_AND_USAGE
The returned word will contain both the thread's priority and 
the thread's recent CPU usage. To extract the priority of the 
thread, use the macro TGI_PRIORITY; to extract the recent CPU 
usage, use the macro TGI_RECENT_CPU_USAGE.

TGIT_THREAD_HANDLE
Useful only when the th parameter is zero, this will return the 
thread handle of the subject thread. If th is zero, the handle of 
the calling thread will be returned.

TGIT_QUEUE_HANDLE
The returned word will contain the queue handle of the 
event-driven thread specified in th. If the thread specified is not 
event-driven, a null queue handle will be returned.

Include:	thread.h

n	ThreadGrabThreadLock()



void	ThreadGrabThreadLock(

	ThreadLockHandle sem);				/* thread lock to grab */

This routine attempts to grab the thread lock for the calling thread. If the 
thread lock is currently held by another thread, the caller will block until the 
lock becomes available. If the caller already has the thread lock, it will grab 
the lock again and continue executing.

Be Sure To:	Thread locks must be released with ThreadReleaseThreadLock() once for 
each time they are grabbed.

Warnings:	This routine provides no deadlock protection for multiple threads. If multiple 
threads will be grabbing multiple thread locks, the locks should always be 
grabbed in the same order to minimize the potential for deadlock.

Include:	sem.h

n	ThreadHandleException()



void	ThreadHandleException(

	ThreadHandle		th,				/* thread to handle the exception */

	ThreadExceptions		exception,				/* exception to handle */

	void	(*handler)	());				/* pointer to handler */

This routine allows a thread to set up a handler for a processor exception. 
This can be useful for debugging purposes. Pass the following three 
parameters:

th	The handle of the thread to handle the exception. Pass zero for 
the current thread.

exception	A ThreadException type (see below).

handler	A pointer to a handler in fixed or locked memory. Pass a null 
pointer to use the GEOS default exception handler.

Structures:	The ThreadException type has the following values:

TE_DIVIDE_BY_ZERO
TE_OVERFLOW
TE_BOUND
TE_FPU_EXCEPTION
TE_SINGLE_STEP
TE_BREAKPOINT

Include:	thread.h

n	ThreadModify()



void	ThreadModify(

	ThreadHandle		th,					/* thread to modify */

	word		newBasePriority,					/* thread's new base priority */

	ThreadModifyFlags		flags);					/* flags (see below) */

This routine modifies the priority of the specified thread. Use it to either set 
the base priority of the thread or reset the current CPU usage to zero. The 
parameters should have the following values:

th	The thread handle; pass zero to change the priority of the 
calling thread.

newBasePriority
The new base priority of the thread. Use one of the standard 
priorities-see ThreadCreate()-or use a value between zero 
and 255.

flags	A record of ThreadModifyFlags; pass TMF_BASE_PRIO to 
change the thread's base priority or TMF_ZERO_USAGE to reset 
the thread's recent CPU usage to zero.

Warnings:	Unless the thread is timing-critical, you should not set the base priority to 
zero.

Include:	thread.h

n	ThreadPrivAlloc()



word	ThreadPrivAlloc(

	word		wordsRequested,					/* number of words to allocate */

	GeodeHandle		owner);					/* handle of geode to own data */

This routine allocates a number of contiguous words in the private data of all 
geodes (loaded and yet-to-be loaded). It is exactly the same as 
GeodePrivAlloc(); see the entry for that routine.

Include:	thread.h

See Also:	GeodePrivAlloc()

n	ThreadPrivFree()



void	ThreadPrivFree(

	word	range,			/* offset to first word to be freed */

	word	wordsRequested);			/* number of words to free */

This routine frees a number of contiguous private-data words previously 
allocated with ThreadPrivAlloc(). It is similar to GeodePrivFree(); see 
the entry for that routine for full information.

Include:	thread.h

See Also:	GeodePrivFree()

n	ThreadPSem()

SemaphoreError ThreadPSem(

	SemaphoreHandle sem);				/* semaphore to grab */

This routine attempts to grab the passed semaphore via a "P" operation. If 
the semaphore has already been grabbed, the thread will block until the 
semaphore becomes available, even if it was grabbed by the same thread.

ThreadPSem() returns an error code of type SemaphoreError, described 
in ThreadPTimedSem(), below. The error code is intended to indicate 
abnormal return by the previous thread; if the semaphore never becomes 
available, the thread will block indefinitely and the routine will not return.

Be Sure To:	When the thread no longer needs the semaphore, it should release it with 
ThreadVSem().

Warnings:	This routine provides no deadlock protection. If threads will grab multiple 
common semaphores, they should always grab/release them in the same 
order, minimizing the chances for deadlock.

A thread may not try to grab a particular semaphore twice without releasing 
it in between grabs. The thread will block on itself and will deadlock. If a 
thread may need to grab the semaphore twice in a row, it should use a thread 
lock instead (see ThreadAllocThreadLock() for more information).

Include:	sem.h

n	ThreadPTimedSem()



SemaphoreError ThreadPTimedSem(

	SemaphoreHandle		sem,				/* semaphore to grab */

	word		timeout);				/* ticks before timeout */

This routine attempts to grab the passed semaphore via a "P" operation. If 
the semaphore has already been grabbed, the thread will block for at most 
the number of ticks specified in timeout.

ThreadPTimedSem() returns an error code of type SemaphoreError, 
which has two value:

SE_NO_ERROR
No error occurred and the semaphore was grabbed properly.

SE_TIMEOUT
The time elapsed and the semaphore was not grabbed. If this 
value is returned, the thread should not proceed with whatever 
protected operation was to happen. Instead, it should either 
attempt to grab the semaphore again or should proceed with 
other tasks.

SE_PREVIOUS_OWNER_DIED
The previous owner of the semaphore exited abnormally. If the 
thread currently holding the semaphore exited without 
releasing the semaphore, for example, this would be returned.

Often timeout is passed as zero to indicate that if the semaphore isn't 
available right now, the thread will go on with some other action.

Be Sure To:	When the thread no longer needs the semaphore, it should release it with 
ThreadVSem().

Warnings:	This routine provides no deadlock protection. If threads will grab multiple 
common semaphores, they should always grab/release them in the same 
order, minimizing the chances for deadlock.

A thread may not try to grab a particular semaphore twice without releasing 
it in between grabs. The thread will block on itself and will deadlock. If a 
thread may need to grab the semaphore twice in a row, it should use a thread 
lock instead, though there is no timeout equivalent for thread locks (see 
ThreadAllocThreadLock() for more information).

Include:	sem.h

n	ThreadReleaseThreadLock()



void	ThreadReleaseThreadLock(

	ThreadLockHandle sem);				/* threadlock to release */

This routine releases the specified thread lock previously grabbed with 
ThreadGrabThreadLock(). Pass the handle of the thread lock as returned 
by ThreadAllocThreadLock().

Do not try to release a thread lock that has not previously been grabbed. The 
results are unpredictable.

Include:	sem.h

n	ThreadVSem()



void	ThreadVSem(

	SemaphoreHandle sem);				/* semaphore to release */

This routine releases a semaphore that was grabbed with ThreadPSem() or 
ThreadPTimedSem(). Pass the handle of the semaphore as returned by 
ThreadAllocSem().

Do not try to release a semaphore that has not previously been grabbed with 
one of the above routines. The results are unpredictable.

Include:	sem.h

n	TimerGetCount()

dword	TimerGetCount();

This routine returns the value of the system counter. The returned value is 
the number of ticks since GEOS started.

Include:	timer.h

n	TimerGetDateAndTime()

void	TimerGetDateAndTime(

	TimerDateAndTime * dateAndTime);						/* buffer for returned values */

This routine returns the current time and date. Pass it a pointer to an empty 
TimerDateAndTime structure to be filled in by the routine.

Include:	timedate.h

n	TimerSetDateAndTime()

void	TimerSetDateAndTime(

	word			flags,					/* which item to set */

	const TimerDateAndTime			* dateAndTime);					/* new values */

This routine sets the current date and/or time of the system. Pass it the 
following:

flags	A word of flags. Pass TIME_SET_DATE to set the day, month, 
and year; pass TIME_SET_TIME to set the hour, minute, and 
second. Pass both to set both.

dateAndTime
A pointer to a TimerDateAndTime structure containing the 
information to be set.

Include:	timedate.h

n	TimerSleep()

void	TimerSleep(

	word	ticks);		/* number of ticks the thread should sleep */

This routine invokes a "sleep timer" that will put the calling thread to sleep 
for the given number of ticks. At the end of the time, the thread will continue 
executing with the next instruction.

Warnings:	Do not use sleep timers as a substitute for semaphores for thread 
synchronization.

Include:	timer.h

n	TimerStart()

TimerHandle TimerStart(

	TimerType		timerType,				/* type of timer to start */

	optr		destObject,				/* object to receive notification
						 * message when timer expires */

	word		ticks,				/* amount of time to run */

	Message		msg,				/* notification message */

	word		interval,				/* interval for continual timers */

	word		* id);				/* buffer for returned timer ID */

This routine starts a timer of any type. The timer will run for the specified 
number of ticks and then will send the given message to the destination 
object. The message is sent with the flags MF_FORCE_QUEUE, 
MF_CHECK_DUPLICATE and MF_REPLACE, so it will always be put in the 
recipient's queue and will always replace any duplicates already in the 
queue. Pass this routine the following:

timerType	A value of TimerType indicating the type of timer to start.

destObject	The optr of the object that will be sent the specified message 
when the time is up.

ticks	The number of ticks for the timer to run. (Sixty ticks equals one 
second.) 

msg	The message to be sent to the destination object when time is 
up.

interval	For continual timers, the interval (number of ticks) at which to 
send out the message to the destination object. The timer will 
send the message once at the end of each interval. The first 
message will be sent ticks ticks after the timer is started. The 
second message will be sent interval ticks after that.

id	A pointer to a word in which the timer's ID will be returned. 
You will need this ID for TimerStop().

This routine returns the handle of the timer as well as an ID pointed to by 
the id parameter. You will need the handle and the ID for TimerStop().

TimerType:	The TimerType enumerated type defines what type of timer should be 
initiated. It has the following values:

TIMER_ROUTINE_ONE_SHOT
Start a timer that will call a routine and then free itself when 
the time is expired. This type is supported in assembly but not 
in C.

TIMER_ROUTINE_CONTINUAL
Start a timer that will call a routine once per time interval 
until TimerStop() is called. This type is supported in 
assembly but not in C.

TIMER_EVENT_ONE_SHOT
Start a timer that will send a message to a given object, then 
free itself, when time is expired.

TIMER_EVENT_CONTINUAL
Start a timer that will send a message to a given object once per 
time interval until TimerStop() is called.

TIMER_MS_ROUTINE_ONE_SHOT
Start a timer that has millisecond accuracy. For this timer, the 
number of ticks will actually be the number of milliseconds. 
The timer will call a specified routine and then free itself when 
time is expired. This type is supported in assembly but not in C.

TIMER_EVENT_REAL_TIME
Start a timer that will call a routine at some particular date 
and time. On devices that support such a timer, this event will 
wake a sleeping machine.

Include:	timer.h

n	TimerStop()



Boolean	TimerStop(

	TimerHandle		th,			/* handle of timer to be stopped */

	word		id);			/* timer ID (returned by TimerStart() */

This routine stops a timer that had been started with TimerStart(). Pass it 
the timer handle and the ID as returned by that routine (the ID of a continual 
timer will always be zero).

The returned error flag will be true if the timer could not be found.

Warnings:	If you call TimerStop() to stop a continual timer that sends its message 
across threads, there may be timer events left in the recipient's event queue. 
It is unsafe in this situation to assume that all timer events have been 
handled. To ensure the timer message has been handled, you can send the 
destination an "all-safe" message with the MF_FORCE_QUEUE flag.

Include:	timer.h

n	TocDBLock()



void * TocDBLock(

	DBGroupAndItem 		thing);

Use this routine to lock a name array maintained by a PrefTocList object.

Include:	config.goh

n	TocDBLockGetRef()



void * TocDBLockGetRef(

	DBGroupAndItem 		thing,

	optr		*refPtr);

This routine locks a name array maintained by a PrefTocList object, 
returning the item's pointer and optr.

Include:	config.goh

n	TocFindCategory()



Boolean TocFindCategory(

	TocCategoryStruct 		*cat);

This routine searches a PrefTocList object's name lists for a given token.

Structures:	

	typedef struct {

		TokenChars 		TCS_tokenChars;

		DBGroupAndItem 		TCS_files; 					/* file name array */

		DBGroupAndItem 		TCS_devices; 					/* device name array--only if

									 * TCF_EXTENDED_DEVICE_DRIVERS

									 * is set. */

	} TocCategoryStruct;

Include:	config.goh

n	TocGetFileHandle()



word TocGetFileHandle();

Use this routine to get the handle of the file used by PrefTocLists to store 
their name array data.

Include:	config.goh

n	TocNameArrayAdd()



word TocNameArrayAdd(

	DBGroupAndItem 		array, 

	const char 		*nameToFind,

	const void 		*data);

Use this routine to add a name to a name array maintained by a PrefTocList 
object.

Include:	config.h

n	TocNameArrayFind()



word TocNameArrayGetElement(

	DBGroupAndItem 		array, 

	word 		element,

	void 		*buffer);

Use this routine to find a name in the name list maintained by a PrefTocList 
object.

Include:	config.goh

n	TocNameArrayGetElement()



word TocNameArrayGetElement(

	DBGroupAndItem 		array, 

	word 		element,

	void 		*buffer);

Use this routine to retrieve a given element from a name array maintained 
by a PrefTocList object. 

Include:	config.goh

n	TocSortedNameArrayAdd()



word TocSortedNameArrayAdd(

	word 		arr, 

	const char 		*nameToAdd,

	NameArrayAddFlags 		flags,

	const void 		*data);

This routine adds a name to a sorted name array associated with a 
PrefTocList object. 

Structures:	

	typedef WordFlags NameArrayAddFlags;

	#define NAAF_SET_DATA_ON_REPLACE 0x8000

Include:	config.goh

n	TocSortedNameArrayFind()



Boolean TocSortedNameArrayFind(

	word 				arr, 

	const char 				*nameToFind,

	SortedNameArrayFindFlags 				flags,

	void 				*buffer, 

	word 				*elementNum);

This routine looks up a name in a sorted name array associated with a 
PrefTocList object.

Structures:	

	typedef WordFlags SortedNameArrayFindFlags;

	#define SNAFF_IGNORE_CASE 0x0080

Include:	config.goh

n	TocUpdateCategory()



void TocUpdateCategory(

	TocUpdateCategoryParams *params);

Use this routine to update a PrefTocList object based upon the files in a given 
directory with a given token.

Structures:	

	typedef struct {

		TocUpdateCategoryFlags 				TUCP_flags;

		TokenChars 				TUCP_tokenChars;

		byte 				TUCP_fileArrayElementSize;

	

		TocUpdateAddCallback 				*TUCP_addCallback;

		byte 				TUCP_pad; /* Wants to be word-aligned */

	} TocUpdateCategoryParams;

	

	typedef word _pascal TocUpdateAddCallback(

		const char *filename,

		optr chunkArray);

	/* Return 0 if add aborted, else return offset of new element within

	 * block */

	

Include:	config.goh

n	TOKEN_CHARS()

dword	TOKEN_CHARS(a, b, c, d);

	char	a, b, c, d;

This macro creates a single dword value from four given characters. This is 
useful when creating a token characters value for a specific token.

n	TokenDefineToken()

word	TokenDefineToken(

	dword		tokenChars,					/* four token characters */

	ManufacturerID		manufacturerID,					/* manufacturer ID for token */

	optr		monikerList,					/* optr of moniker list */

	TokenFlags		flags);					/* token flags */

This routine adds a new token and moniker list to the token database. If the 
token already exists in the token DB, the old will be replaced with the new. 
This routine must only be called by a thread that can lock the block in which 
the passed moniker or moniker list resides. This routine must be passed the 
following parameters:

tokenChars	The four token characters that identify this moniker or 
moniker list in the token database. Create this dword value 
from the four characters with the macro TOKEN_CHARS.

manufacturerID
The manufacturer ID number of the manufacturer responsible 
for the token database entry.

monikerList
The optr of the moniker list to be added to the token database.

flags	A record of TokenFlags indicating the relocation status of the 
moniker list.

Warnings:	This routine may legally move locked LMem blocks (token database items), 
thereby invalidating all pointers to token database items.

Include:	token.h

n	TokenGetTokenInfo()

Boolean	TokenGetTokenInfo(

	dword		tokenChars,					/* four characters of token */

	ManufacturerID		manufacturerID,					/* manufacturer ID of token */

	TokenFlags		* flags);					/* returned token flags */

This routine returns information about a specified token. Pass it the 
following:

tokenChars	The four token characters that identify the token database 
entry. Create this dword from the four characters with the 
macro TOKEN_CHARS.

manufacturerID
The manufacturer ID number of the manufacturer responsible 
for the token database entry.

flags	A pointer to an empty flags record; the flags set (if any) for the 
specified token (if it exists) will be returned here.

This routine returns a (non-zero) value of VMStatus if the token was not 
found in the token database. It returns zero if successful.

Include:	token.h

n	TokenListTokens()

dword	TokenListTokens(

	TokenRangeFlags 		tokenRangeFlags,

	word 		headerSize,

	ManufacturerID 		manufacturerID));

This routine lists all the tokens in the token database. It allocates a new 
block on the global heap and writes in it an array of GeodeToken structures. 
This routine returns the actual tokens, not the token groups.

The returned dword consists of two values: The high word represents the 
number of tokens in the returned block and may be extracted with the macro 
TokenListTokensCountFromDWord(). The low word represents the 
handle of the newly-allocated block and can be extracted with the macro 
TokenListTokensHandleFromDWord().

Include:	token.h

n	TokenListTokensCountFromDWord()

word	TokenListTokensCountFromDWord(d);

	dword	d;

This macro extracts the number of tokens from the value returned by 
TokenListTokens().

n	TokenListTokensHandleFromDWord()

word	TokenListTokensHandleFromDWord(d);

	dword	d;

This routine extracts the MemHandle from the value returned by 
TokenListTokens().

n	TokenLoadMonikerBlock()

Boolean	TokenLoadMonikerBlock(

	dword		tokenChars,					/* four characters of token */

	ManufacturerID		manufacturerID,					/* manufacturer ID of token */

	DisplayType		displayType,					/* type of display for token */

	VisMonikerSearchFlags searchFlags,							/* flags for finding token */

	word		* blockSize,					/* returned block size */

	MemHandle		* blockHandle);					/* returned block handle */

This routine loads a specified token's moniker, allocating a new global 
memory block for the moniker. The returned Boolean will be false if the 
moniker was found, true otherwise. Information about the moniker is 
returned in the values pointed to by blockSize (the size of the newly allocated 
block) and blockHandle (the handle of the new block). If the moniker is not 
found, both return pointers will be NULL and no block will be allocated.

Pass this routine the following:

tokenChars	The four token characters that identify the token database 
entry. Create this dword from the four characters with the 
macro TOKEN_CHARS.

manufacturerID
The manufacturer ID number of the manufacturer responsible 
for the token database entry.

displayType
A value of DisplayType indicating the size of the display (used 
to indicate small-screen devices, primarily).

searchFlags
A record of VisMonikerSearchFlags indicating what type of 
moniker is being requested.

blockSize	A pointer to a word in which the new block's size will be 
returned.

blockHandle
A pointer to a handle in which the new block's handle will be 
returned.

Include:	token.h

n	TokenLoadMonikerBuffer()

Boolean	TokenLoadMonikerBuffer(

	dword		tokenChars,					/* four characters of token */

	ManufacturerID		manufacturerID,					/* manufacturer ID of token */

	DisplayType		displayType,					/* type of display for token */

	VisMonikerSearchFlags searchFlags,							/* flags for finding token */

	void		* buffer,					/* pointer to buffer for token */

	word		bufSize,					/* size of passed buffer */

	word		* bytesReturned);						/* number of bytes returned */

This routine loads a specified token's moniker into a provided buffer. The 
return value will be false if the moniker was found, true otherwise. The size 
of the returned moniker will be returned in the word pointed to by the 
bytesReturned parameter.

Pass this routine the following:

tokenChars	The four token characters that identify the token database 
entry. Create this dword from the four characters with the 
macro TOKEN_CHARS.

manufacturerID
The manufacturer ID number of the manufacturer responsible 
for the token database entry.

displayType
A value of DisplayType indicating the size of the display (used 
to indicate small-screen devices, primarily).

searchFlags
A record of VisMonikerSearchFlags indicating what type of 
moniker is being requested.

buffer	A pointer to a locked or fixed buffer into which the moniker will 
be copied.

bufSize	The size of the passed buffer; also the maximum size of the 
moniker that may be returned.

bytesReturned
The size of the moniker actually returned in the buffer.

Include:	token.h

n	TokenLoadMonikerChunk()

Boolean	TokenLoadMonikerChunk(

	dword		tokenChars,					/* four characters of token */

	ManufacturerID		manufacturerID,					/* manufacturer ID of token */

	DisplayType		displayType,					/* type of display for token */

	VisMonikerSearchFlags searchFlags,							/* flags for finding token */

	MemHandle		lmemBlock,					/* locked block for new chunk */

	word		* chunkSize,					/* returned new chunk size */

	ChunkHandle		* chunkHandle);					/* returned new chunk handle */

This routine loads a specified token's moniker, allocating a new chunk in a 
local memory block for the moniker. The returned error flag will be true if the 
moniker was not found, false otherwise.

Pass this routine the following:

tokenChars	The four token characters that identify the token database 
entry. Create this dword from the four characters with the 
macro TOKEN_CHARS.

manufacturerID
The manufacturer ID number of the manufacturer responsible 
for the token database entry.

displayType
A value of DisplayType indicating the size of the display (used 
to indicate small-screen devices, primarily).

searchFlags
A record of VisMonikerSearchFlags indicating what type of 
moniker is being requested.

lmemBlock	The MemHandle of the local memory block in which the new 
chunk will be allocated. If the block is locked, you must 
dereference the global handle after calling this routine.

chunkSize	A pointer to a word in which the size of the allocated chunk will 
be returned.

chunkhandle
A pointer to a chunk handle in which the handle of the newly 
allocated chunk will be returned.

Warnings:	This routine can move chunks in the passed block, thereby invalidating 
pointers to any chunk in the block.

Include:	token.h

n	TokenLoadTokenBlock()

Boolean	TokenLoadTokenBlock(

	dword		tokenChars,					/* four characters of token */

	ManufacturerID		manufacturerID,					/* manufacturer ID of token */

	word		* blockSize,					/* returned size of new block */

	MemHandle		* blockHandle);					/* returned handle of block */

This routine loads the specified token's TokenEntry structure into a 
newly-allocated global memory block. If the token is not found, the returned 
error flag will be true; otherwise, it will be false.

Pass this routine the following:

tokenChars	The four token characters that identify the token database 
entry. Create this dword from the four characters with the 
macro TOKEN_CHARS.

manufacturerID
The manufacturer ID number of the manufacturer responsible 
for the token database entry.

blockSize	A pointer to a word in which the size of the newly-allocated 
block will be returned.

blockHandle
A pointer to a global handle in which the handle of the 
newly-allocated block will be returned.

Include:	token.h

n	TokenLoadTokenBuffer()

Boolean	TokenLoadTokenBuffer(

	dword		tokenChars,					/* four characters of token */

	ManufacturerID		manufacturerID,					/* manufacturer ID of token */

	TokenEntry		* buffer);					/* buffer for returned token */

This routine loads the specified token's TokenEntry structure into a passed 
buffer. The returned error flag will be true if the token was not found, false 
otherwise. Pass this routine the following:

tokenChars	The four token characters that identify the token database 
entry. Create this dword from the four characters with the 
macro TOKEN_CHARS.

manufacturerID
The manufacturer ID number of the manufacturer responsible 
for the token database entry.

buffer	A pointer to a locked or fixed buffer into which the token entry 
will be copied.

Include:	token.h

n	TokenLoadTokenChunk()

Boolean	TokenLoadTokenChunk(

	dword		tokenChars,					/* four characters of token */

	ManufacturerID		manufacturerID,					/* manufacturer ID of token */

	MemHandle		lmemBlock,					/* handle of block for chunk */

	word		* chunkSize,					/* returned size of new chunk */

	ChunkHandle		* chunkHandle);					/* returned chunk handle */

This routine loads the specified token's TokenEntry structure into a 
newly-allocated chunk. The returned error flag will be true if the token could 
not be found, false otherwise.

Pass this routine the following:

tokenChars	The four token characters that identify the token database 
entry. Create this dword from the four characters with the 
macro TOKEN_CHARS.

manufacturerID
The manufacturer ID number of the manufacturer responsible 
for the token database entry.

lmemBlock	The MemHandle of the local memory block in which the new 
chunk will be allocated. If the block is locked, you must 
manually dereference this handle after the routine call.

chunksize	A pointer to a word in which the size of the newly-allocated 
chunk will be returned.

chunkHandle
A pointer to a chunk handle in which the handle of the 
newly-allocated chunk will be returned.

Warnings:	This routine can move chunks in the passed block, thereby invalidating 
pointers to any chunk in the block.

Include:	token.h

n	TokenLockTokenMoniker()

void	* TokenLockTokenMoniker(

	TokenMonikerInfo		tokenMonikerInfo);				/* The DB group and item numbers

					 * as returned by TokenLookupMoniker() */

This routine locks a token's moniker so it may be drawn; it returns a pointer 
to the locked chunk containing the moniker information. Pass it the 
structure returned by TokenLookupMoniker().

Be Sure To:	Unlock the moniker with TokenUnlockMoniker() after you have finished 
drawing it.

Include:	token.h

n	TokenLookupMoniker()

Boolean	TokenLookupMoniker(

	dword		tokenChars,					/* four characters of token */

	ManufacturerID		manufacturerID,					/* manufacturer ID of token */

	DisplayType		displayType,					/* display type of token */

	VisMonikerSearchFlags searchFlags,							/* flags for finding token */

	TokenMonikerInfo *		tokenMonikerInfo);					/* DB group and item of token */

This routine finds and retrieves a pointer to the specific moniker for the 
specified token, given also the token's display type and other attributes. Pass 
the following:

tokenChars	The four token characters that identify this moniker or 
moniker list in the token database. Create this dword value 
from the four characters with the macro TOKEN_CHARS.

manufacturerID
The manufacturer ID number of the manufacturer responsible 
for the token database entry.

displayType
A value of DisplayType indicating the size of the display (used 
to indicate small-screen devices, primarily).

searchFlags
A record of VisMonikerSearchFlags indicating what type of 
moniker is being requested.

tokenDBItem
A pointer to an empty TokenMonikerInfo structure, in which 
the token's group and item numbers will be returned.

The return value is an error flag: it will be true if the item could not be found 
in the token database, false otherwise.

Include:	token.h

n	TokenCloseLocalTokenDB()



void	TokenCloseLocalTokenDB()

This routine closes the local token database.

n	TokenListTokens()



dword TokenListTokens(

	TokenRangeFlags		tokenRangeFlags,

	word		headerSize,

	ManufacturerID		manufacturerID)

This routine locates all the tokens that meet specified criteria, allocates a 
block, and copies the tokens to that block. The upper word of the return value 
is the number of matching tokens found; the lower word is the handle of the 
block which was allocated.

n	TokenOpenLocalTokenDB()



word	TokenOpenLocalTokenDB()

This routine opens the local token database. It returns zero on success, and 
a VMStatus error code on failure.

Include:	token.h

n	TokenRemoveToken

Boolean	TokenRemoveToken(

	dword		tokenChars,					/* four characters of token */

	ManufacturerID		manufacturerID,					/* manufacturer ID of token */

This routine removes the specified token and its moniker list from the token 
database. It returns an error flag: if the token could not be found, the 
returned flag is true; otherwise it is false. Pass the following:

tokenChars	The four token characters that identify this moniker or 
moniker list in the token database. Create this dword value 
from the four characters with the macro TOKEN_CHARS.

manufacturerID
The manufacturer ID number of the manufacturer responsible 
for the token database entry.

Include:	token.h

n	TokenUnlockTokenMoniker()

void	TokenUnlockTokenMoniker(

	void * moniker);

This routine unlocks a moniker that had been locked with 
TokenLockMoniker(). Pass a pointer to the locked moniker, as returned by 
the locking routine.

Include:	token.h

n	TypeFromFormatID()

word	TypeFromFormatID(id);

	ClipboardItemFormatID id;

This macro extracts the word-sized format ID (of type 
ClipboardItemFormat) from a ClipboardFormatID argument.
