[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

TABLE OF CONTENTS

utility.library/AllocateTagItems
utility.library/Amiga2Date
utility.library/CallHookPkt
utility.library/CheckDate
utility.library/CloneTagItems
utility.library/Date2Amiga
utility.library/FilterTagChanges
utility.library/FilterTagItems
utility.library/FindTagItem
utility.library/FreeTagItems
utility.library/GetTagData
utility.library/MapTags
utility.library/NextTagItem
utility.library/PackBoolTags
utility.library/RefreshTagItemClones
utility.library/SDivMod32
utility.library/SMult32
utility.library/Stricmp
utility.library/Strnicmp
utility.library/TagInArray
utility.library/ToLower
utility.library/ToUpper
utility.library/UDivMod32
utility.library/UMult32
utility.library/AllocateTagItems             utility.library/AllocateTagItems

    NAME
	AllocateTagItems --  Allocate a TagItem array (or chain). (V36)

    SYNOPSIS
	tagList = AllocateTagItems( numItems )
	D0		            D0

	struct TagItem *AllocateTagItems( ULONG numItems);

    FUNCTION
	Allocates the specified number of usable TagItems slots, and does
	so in a format that the function FreeTagItems can handle.

	Note that to access the TagItems in 'tagList', you should use
	the function NextTagItem().  This will insure you respect any
	chaining (TAG_MORE) that the list uses, and will skip any
	TAG_IGNORE items that AllocateTagItems() might use to stash
	size and other information.

    INPUTS
	numItems	- the number of TagItem slots you want to allocate.

    RESULT
	tagList		- the allocated chain of TagItem structures.  Will
	    		  return NULL if unsuccessful.

    BUGS

    SEE ALSO
	FreeTagItems(), CloneTagItems()

utility.library/Amiga2Date                         utility.library/Amiga2Date

   NAME
	Amiga2Date -- Calculate the date from a timestamp.  (V36)

   SYNOPSIS
	Amiga2Date( AmigaTime, Date )
	            D0         A0

	void Amiga2Date( ULONG, struct ClockData * );

   FUNCTION
	Fills in a ClockData structure with the date and time calculated
	from a ULONG containing the number of seconds from 01-Jan-1978
	to the date.

   INPUTS
	AmigaTime 	- the number of seconds from 01-Jan-1978.

   RESULTS
	Date		- filled in with the date/time specified by
			  AmigaTime.

   NOTES

   SEE ALSO
	CheckDate(), Date2Amiga()

   BUGS

utility.library/CallHookPkt                       utility.library/CallHookPkt

    NAME
	CallHookPkt -- Invoke a Hook function callback. (V36)

    SYNOPSIS
	return = CallHookPkt( hook, object, paramPkt )
	D0		      A0    A2	    A1

	ULONG CallHookPkt( struct Hook *hook, VOID *object, VOID *paramPkt );

    FUNCTION
	Performs the callback standard defined by a Hook structure.
	This function is really very simple; it effectively performs
	a JMP to Hook->h_Entry.

	It is probably just as well to do this operation in an
	assembly language function linked in to your program, possibly
	from a compiler supplied library or a builtin function.

	It is anticipated that C programs will often call a 'varargs'
	variant of this function which will be named CallHook.  This
	function must be provided in a compiler specific library, but
	an example of use would be:

	returnval = CallHook( hook, dataobject, COMMAND_ID, param1, param2 );

	This function CallHook can be implemented in many C compilers
	like this:
	CallHook( hook, object, command, ... )
	struct Hook	*hook;
	VOID		*object;
	ULONG		command;
	{
		return ( CallHookPkt( hook, object, (VOID *) &command ) );
	}

    INPUTS
	Hook		- pointer to Hook structure as defined in
			  utility/hooks.h
	Object		- useful data structure in the particular context the
			  hook is being used for.
	ParamPkt	- pointer to a parameter packet (often built on the
			  stack); by convention this packet should start off
			  with a longword command code, and the remaining
			  data in the packet depends on that command.

    RESULT
	return		- The meaning of the value returned in D0 depends on
			  the context in which the Hook is being used.

    NOTES
	The functions called through this function should follow normal
	register conventions unless EXPLICITLY documented otherwise (and
	they have a good reason too).

    BUGS

    SEE ALSO
	utility/hooks.h

utility.library/CheckDate                           utility.library/CheckDate

   NAME
	CheckDate -- Checks ClockData struct for legal date. (V36)

   SYNOPSIS
	AmigaTime = CheckDate( Date )
	D0                     A0

	ULONG CheckDate( struct ClockData * );

   FUNCTION
	Determines if the Date is a legal date and returns the number
	of seconds to Date from 01-Jan-1978 if it is.

   INPUTS
	Date 		- pointer to a ClockData structure.

   RESULTS
	AmigaTime 	- 0 if Date invalid; otherwise, the number of
			  seconds to Date from 01-Jan-1978.

   NOTES

   BUGS
	The wday field of the ClockData structure is not checked.

   SEE ALSO
	Amiga2Date(), Date2Amiga()

utility.library/CloneTagItems                   utility.library/CloneTagItems

    NAME
	CloneTagItems -- Copies a TagItem list.  (V36)

    SYNOPSIS
	newTagList = CloneTagItems( tagList )
	D0			    A0

	struct TagItem *CloneTagItems( struct TagItem *tagList );

    FUNCTION
	Copies the essential contents of a tagItem list.  Internally,
	it uses AllocateTagItems() so that you can use FreeTagItems().

    INPUTS
	tagList		- TagItem list to clone.

    RESULT
	newTagList	- resultant copy.

    BUGS

    SEE ALSO
	AllocateTagItems(), FreeTagItems(), RefreshTagItemClones()

utility.library/Date2Amiga                         utility.library/Date2Amiga

   NAME
	Date2Amiga -- Calculate seconds from 01-Jan-1978.  (V36)

   SYNOPSIS
	AmigaTime = Date2Amiga( Date )
	D0                      A0

	ULONG Date2Amiga( struct ClockData * );

   FUNCTION
	Calculates the number of seconds from 01-Jan-1978 to the date
	specified in the ClockData structure.

   INPUTS
	Date 		- pointer to a ClockData structure containing the
			  date of interest.

   RESULTS
	AmigaTime 	- the number of seconds from 01-Jan-1978 to the
			  date specified in Date.

   NOTES
	This function does no sanity checking of the data in Date.

   SEE ALSO
	Amiga2Date(), CheckDate()

   BUGS

utility.library/FilterTagChanges             utility.library/FilterTagChanges

    NAME
	FilterTagChanges -- Eliminate TagItems which specify no change. (V36)

    SYNOPSIS
	FilterTagChanges( changeList, oldValues, apply)
			  A0	      A1	 D0

	void FilterTagChanges( struct TagItem *changeList,
			       struct TagItem *oldValues, LONG apply );

    FUNCTION
	Eliminate items from a "change list" that specify values already
	in effect in existing list.  Optionally update the existing list
	if the Boolean 'Apply' is true.

	The elimination is done by changing the ti_Tag field to TAG_IGNORE.
	So, this function may change the input tag list(s).

    INPUTS
	changeList 	- specification of new tag-value pairs.
	oldValues	- a list of existing tag item pairs.
	apply		- Boolean specification as to whether the values in
			  oldValues are to be updated to the values in
			  changeList.

    RESULT
	None.

    EXAMPLE
	Assume you have an attribute list for an object (oldValues)
	which looks like this:

		ATTR_Size,  "large",
		ATTR_Color, "orange",
		ATTR_Shape, "square",

	If you receive a new TagList containing some changes (changeList),
	which looks like this:

		ATTR_Size,  "large",
		ATTR_Shape, "triangle"

	If you call FilterTagChanges(), changeList will be modified to
	contain only those attributes which are different from the
	oldValues.  All other tagitems will have their tag-values set to
	TAG_IGNORE.  The resulting changeList will become:

		TAG_IGNORE, "large",
		ATTR_Shape, "triangle"

	If apply was set to TRUE, oldValues would be:

		ATTR_Size,  "large"
		ATTR_Color, "orange"
		ATTR_Shape, "triangle"

    BUGS

    SEE ALSO

utility.library/FilterTagItems                 utility.library/FilterTagItems

    NAME
	FilterTagItems - Remove selected items from a TagItem list. (V36)

    SYNOPSIS
	nvalid = FilterTagItems(tagList, tagArray, logic)
	D0		       A0	A1	  D0

	ULONG FilterTagItems(struct TagItem *tagList, Tag *tagArray,
			     LONG logic);

    FUNCTION
	Removes TagItems from a TagItem list (by changing ti_Tag to
	TAG_IGNORE) depending on whether its ti_Tag value is
	found in an array of TagValues.

	If the 'logic' parameter is TAGFILTER_AND, then all items
	not appearing in the list are excluded.

	If 'logic' is TAGFILTER_NOT, then items not found in the
	array are preserved, and the ones in the array are cast out.

    INPUTS
	tagList		- input list of tag items which is to be filtered
			  by having selected items changed to TAG_IGNORE.
	tagArray	- an array of Tag values, terminated by TAG_END,
			  as specified in the notes on TagInArray().
	logic		- specification whether items in TagArray are to
			  be included or excluded in the filtered result.

    RESULT
	nvalid		- number of valid items left in resulting filtered
			  list.

    BUGS

    SEE ALSO
	TagInArray()

utility.library/FindTagItem                       utility.library/FindTagItem

    NAME
	FindTagItem -- Scans TagItem list for a Tag. (V36)

    SYNOPSIS
	tag = FindTagItem( tagVal, tagList)
	D0		   D0	   A0

	struct TagItem *FindTagItem( Tag tagVal, struct TagItem *tagList );

    FUNCTION
	Scans a TagItem "List", which is in fact a chain of arrays
	of TagItem structures as defined in utility/tagitem.h.
	Returns a pointer to the FIRST item with ti_Tag matching the
	'TagVal' parameter.

    INPUTS
	tagVal 		- Tag value to search for.
	tagList		- beginning of TagItem list to scan.

    RESULT
	Returns a pointer to the item with ti_Tag matching 'TagVal'.
	Returns NULL if there is no match or if TagList is NULL.

    BUGS

    SEE ALSO
	utility/tagitem.h, GetTagData(), PackBoolTags(), NextTagItem()

utility.library/FreeTagItems                     utility.library/FreeTagItems

    NAME
	FreeTagItems --  Frees allocated TagItem lists. (V36)

    SYNOPSIS
	FreeTagItems( tagList )
			A0

	void FreeTagItems( struct TagItem *tagList );

    FUNCTION
	Frees the memory of a TagItem list allocated either by
	AllocateTagItems() or CloneTagItems().

    INPUTS
	TagList		- list to free.  Must be created by functions
			  specified. A value of NULL for 'tagList' is safe.

    RESULT
	None.

    BUGS

    SEE ALSO
	AllocateTagItems(), CloneTagItems()

utility.library/GetTagData                         utility.library/GetTagData

    NAME
	GetTagData -- Obtain data corresponding to Tag. (V36)

    SYNOPSIS
	value = GetTagData(tagVal, default, tagList)
	D0		   D0	   D1	    A0

	ULONG GetTagData(Tag TagVal, ULONG Default, struct TagItem *TagList)

    FUNCTION
	Searches a TagItem list for a matching Tag value, and returns the
	corresponding ti_Data value for the TagItem found.  If none
	found, will return the value passed it as 'default'.

    INPUTS
	tagVal 		- Tag value to search for.
	default		- value to be returned if tagVal is not found.
	tagList 	- the TagItem list to search.

    RESULT
	value		- The ti_Data value for first matching TagItem, or
			  'default' if a ti_Tag matching 'Tag' is not found.

    BUGS

    SEE ALSO
	utility/tagitem.h, FindTagItem(), PackBoolTags(), NextTagItem()

utility.library/MapTags                               utility.library/MapTags

    NAME
	MapTags	-- Convert ti_Tag values in a list via map pairing. (V36)

    SYNOPSIS
	MapTags(tagList, mapList, includeMiss)
		A0	 A1       D0

	void MapTags(struct TagItem *tagList, struct TagItem mapList,
		     LONG includeMiss);

    FUNCTION
	Apply a "mapping list" mapList to tagList:

	If the ti_Tag field of an item in tagList appears as ti_Tag in some
	item in mapList, overwrite ti_Tag with the corresponding ti_Data
	from the map list.

	If a tag in tagList does not appear in the mapList, you can choose
	to have it removed by changing it to TAG_IGNORE. Do this by setting
	includeMiss to FALSE.

	If you want to have items which do not appear in the mapList
	survive the mapping as-is, set includeMiss to 1.

	This is central to gadget interconnections where you want
	to convert the tag values from one space (the sender) to
	another (the receiver).

    INPUTS
	tagList		- Input list of tag items which is to be mapped
			  to Tag values as specified in mapList.
	mapList 	- a "mapping list" tagItem list which pairs Tag
			  values expected to appear in tagList with new
			  values to be substituted in the ti_Tag fields of
			  tagList.  May be NULL, which means that all items
			  in tagList will be eliminated.
	includeMiss	- 0 to remove tags from tagList not in mapList,
			  1 to remove

    RESULT
	None.

    EXAMPLE
	/* Consider this source list: */
	    struct TagItem list[] = {
		{ MY_SIZE, 	71 },
		{ MY_WEIGHT, 	200 },
		{ TAG_END,	} };

	/* And the mapping list: */
	    struct TagItem map[] = {
		{ MY_SIZE, 	HIS_TALL },
		{ TAG_END,	} };

	/* Then after MapTags( list, map, 0 ), 'list' will become: */
		{ HIS_TALL, 71 },
		{ TAG_IGNORE, },
		{ TAG_END, }

	/* Then after MapTags( list, map, 1 ), 'list' will become: */
		{ HIS_TALL, 71 },
		{ MY_WEIGHT, 200 },
		{ TAG_END, }

    NOTES
	The procedure will change the values of the input tag list
	tagList (but not mapList).

	You can "filter" a list by passing includeMiss as 0, and having the
	data items in the map list equal the corresponding tags.

	You can perform the inverse filter ("everything but") by passing
	includeMiss equal to 1, and creating a map item for every tag you
	want to filter out, pairing it with a mapped data value of
	TAG_IGNORE.

	For safety and "order independence" of tag item arrays, if you
	attempt to map some tag to the value TAG_END, the value TAG_IGNORE
	will be substituted instead.

    BUGS

    SEE ALSO

utility.library/NextTagItem                       utility.library/NextTagItem

    NAME
	NextTagItem -- Iterate TagItem lists. (V36)

    SYNOPSIS
	next_tag = NextTagItem( tagItemPtr )
	D0			A0

	struct TagItem *NextTagItem( struct TagItem **tagItemPtr );

    FUNCTION
	Iterates through a (chained) array of TagItem structures,
	skipping and chaining as dictated by system tags.  TAG_SKIP
	will cause it to skip the entry and the next, TAG_IGNORE ignores
	that single entry, and TAG_MORE has a pointer to another array
	of tags (and terminates the current array!)  TAG_DONE also
	terminates the current array.  Each call returns either the next
	tagitem you should examine, or NULL at the end.

    INPUTS
	tagItemPtr 	- doubly-indirect reference to a TagItem structure.
			  The pointer will be changed to keep track of the
			  iteration.

    RESULT
	next_tag	- Each TagItem in the array or chain of arrays that
			  should be processed according to system Tag values
			  (in utility/tagitem.h) is returned in turn with
			  successive calls.

    EXAMPLE
	Iterate( struct TagItem *tags );
	{
		struct TagItem *tstate;
		struct TagItem *tag;

		tstate = tags;
		while ( tag = NextTagItem( &tstate ) )
		{
			switch ( tag->ti_Tag )
			{
 			case TAG1:
			    ...
			    break;
 			case TAG2:
			    ...
			    break;
			...
			}
		}
   	}

    NOTES
	Do NOT use the value of *tagItemPtr, but rather use the pointer
	returned by NextTagItem().


    BUGS

    SEE ALSO
	utility/tagitem.h, GetTagData(), PackBoolTags(), FindTagItem()

utility.library/PackBoolTags                     utility.library/PackBoolTags

    NAME
	PackBoolTags --  Builds a "Flag" word from a TagList. (V36)

    SYNOPSIS
	boolflags = PackBoolTags( initialFlags, tagList, boolMap )
	D0			  D0	        A0       A1

	ULONG PackBoolTags( ULONG initialFlags, struct TagItem *tagList,
			    struct TagItem *boolMap );

    FUNCTION
	Picks out the Boolean TagItems in a TagItem list and converts
	them into bit-flag representations according to a correspondence
	defined by the TagItem list 'BoolMap.'

	A Boolean TagItem is one where only the logical value of
	the ti_Data is relevant.  If this field is 0, the value is
	FALSE, otherwise TRUE.


    INPUTS
	initialFlags 	- a starting set of bit-flags which will be changed
			  by the processing of TRUE and FALSE Boolean tags
			  in tagList.
	tagList		- a TagItem list which may contain several TagItems
			  defined to be "Boolean" by their presence in
			  boolMap.  The logical value of ti_Data determines
			  whether a TagItem causes the bit-flag value related
			  by boolMap to set or cleared in the returned flag
			  longword.
	boolMap		- a TagItem list defining the Boolean Tags to be
			  recognized, and the bit (or bits) in the returned
			  longword that are to be set or cleared when a
			  Boolean Tag is found to be TRUE or FALSE in
			  tagList.

    RESULT
	boolflags	- the accumulated longword of bit-flags, starting
			  with InitialFlags and modified by each Boolean
			  TagItem encountered.

    EXAMPLE

	/* define some nice user tag values ... */
	enum mytags { tag1 = TAG_USER+1, tag2, tag3, tag4, tag5 };

	/* this TagItem list defines the correspondence between Boolean tags
	 * and bit-flag values.
	 */
	struct TagItem	boolmap[] = {
	    { tag1,  0x0001 },
	    { tag2,  0x0002 },
	    { tag3,  0x0004 },
	    { tag4,  0x0008 },
	    { TAG_DONE }
	};

	/* You are probably passed these by some client, and you want
	 * to "collapse" the Boolean content into a single longword.
	 */

	struct TagItem	boolexample[] = {
	    { tag1,  TRUE },
	    { tag2,  FALSE },
	    { tag5, Irrelevant },
	    { tag3,  TRUE },
	    { TAG_DONE }
	};

	/* Perhaps 'boolflags' already has a current value of 0x800002. */
	boolflags = PackBoolTags( boolflags, boolexample, boolmap );

	/* The resulting new value of 'boolflags' will be 0x80005. /*

    BUGS
	There are some undefined cases if there is duplication of
	a given Tag in either list.  It is probably safe to say that
	the *last* of identical Tags in TagList will hold sway.

    SEE ALSO
	utility/tagitem.h, GetTagData(), FindTagItem(), NextTagItem()

utility.library/RefreshTagItemClones     utility.library/RefreshTagItemClones

    NAME
	RefreshTagItemClones -- Rejuvenates a clone from the original. (V36)

    SYNOPSIS
	RefreshTagItemClones( cloneTagItems, originalTagItems )
			      A0	     A1

	void RefreshTagItemClones( struct TagItem *cloneTagItems,
				  struct TagItem *originalTagItems );

    FUNCTION
	If (and only if) the tag items 'cloneTagItems' were created
	from 'originalTagItems' by CloneTagItems(), and if originalTagItems
	has not been changed in any way, you can reset the clone list
	to its original state by using this function.

    INPUTS
	CloneTagItems	- return value from CloneTagItems(originalTagItems).
	OriginalTagItems- a tag list that hasn't changed.

    RESULT
	None.

    EXAMPLE

    BUGS

    SEE ALSO
	CloneTagItems(), AllocateTagItems(), FreeTagItems()

utility.library/SDivMod32                           utility.library/SDivMod32

   NAME
	SDivMod32 -- Signed 32 by 32 bit division and modulus. (V36)

   SYNOPSIS
	Quotient:Remainder = SDivMod32( Dividend, Divisor )
	D0       D1                     D0        D1

	LONG SDivMod32( LONG, LONG );

   FUNCTION
	Divides the signed 32 bit dividend by the signed 32 bit divisor
	   and returns a signed 32 bit quotient and remainder.

   INPUTS
	Dividend 	- signed 32 bit dividend.
	Divisor 	- signed 32 bit divisor.

   RESULTS
	Quotient 	- signed 32 quotient of the division.
	Remainder 	- signed 32 remainder of the division.

   NOTES

   SEE ALSO
	SMult32(), UDivMod32(), UMult32()

   BUGS

utility.library/SMult32                               utility.library/SMult32

   NAME
	SMult32 -- Signed 32 by 32 bit multiply with 32 bit result. (V36)

   SYNOPSIS
	Result = SMult32( Arg1, Arg2 )
	D0                D0    D1

	LONG SMult32( LONG, LONG );

   FUNCTION
	Returns the signed 32 bit result of multiplying Arg1 by Arg2.

   INPUTS
	Arg1, Arg2	- signed multiplicands.

   RESULTS
	Result		- the signed 32 bit result of multiplying
			  Arg1 by Arg2.

   NOTES

   SEE ALSO
	SDivMod32(), UDivMod32(), UMult32()

   BUGS

utility.library/Stricmp                               utility.library/Stricmp

    NAME
	Stricmp	--  Case-insensitive string compare. (V37)

    SYNOPSIS
	res = Stricmp(string1, string2)
	D0		A0       A1

	LONG Stricmp(char *, char *);

    FUNCTION
	Stricmp compares two strings, ignoring case.  It handles all
	internationalization issues.  If the strings have different lengths,
	the shorter is treated as if it were extended with zeros.

    INPUTS
	string1, string2 - strings to be compared

    RESULT
	res - negative if string1 is below string2, 0 if they're the same, and
	      positive if string1 is above string2.

    NOTES
	Commodore is planning a localization library which will take care
	of most details pertaining to system integration into different
	cultures, locales, and territories.

	This function will automatically be replaced by a localized version
	whenever the locale.library is loaded in memory. As such, the
	collating order may change depending on the locale currently
	defined by the user. Take this fact into consideration when using
	this function, and do not rely on obtaining specific collating
	sequences.

    BUGS

    SEE ALSO
	Strnicmp()

utility.library/Strnicmp                             utility.library/Strnicmp

    NAME
	Strnicmp--  Case-insensitive string compare, length-limited. (V37)

    SYNOPSIS
	res = Strnicmp(string1, string2, length)
	D0		A0       A1	   D0

	LONG Strnicmp(char *, char *, LONG length);

    FUNCTION

	Strnicmp compares two strings, ignoring case.  It handles all
	internationalization issues.  If the strings have different lengths,
	the shorter is treated as if it were extended with zeros.  It never
	compares more than <length> characters.

    INPUTS
	string1, string2 - strings to be compared
	length		 - maximum number of characters to examine

    RESULT
	res - negative if string1 is below string2, 0 if they're the same, and
	      positive if string1 is above string2.

    NOTES
	Commodore is planning a localization library which will take care
	of most details pertaining to system integration into different
	cultures, locales, and territories.

	This function will automatically be replaced by a localized version
	whenever the locale.library is loaded in memory. As such, the
	collating order may change depending on the locale currently
	defined by the user. Take this fact into consideration when using
	this function, and do not rely on obtaining specific collating
	sequences.

    BUGS

    SEE ALSO
	Stricmp()

utility.library/TagInArray                         utility.library/TagInArray

    NAME
	TagInArray  -- Check if a Tag value appears in a Tag array. (V36)

    SYNOPSIS
	BOOL TagInArray( tag, tagArray )
	D0	         D0   A0

	BOOL TagInArray( Tag tag, Tag *tagArray);

    FUNCTION
	Perform a quick scan to see if a tag value appears in
	an array terminated with TAG_END.  Returns TRUE if
	the value is found.

	The 'tagArray' must be terminated by TAG_END.  It should
	NOT contain other system tag values, such as TAG_MORE
	or TAG_IGNORE.  Note that this is an array of Tag values, NOT
	an array of TagItems.

	This is sort of a "one shot" version of FilterTagItems().

    INPUTS
	tag 		- Tag value to search array for.
	tagArray	- a simple array terminated by TAG_END.

    RESULT
	Boolean success of search.

    BUGS

    SEE ALSO
	FilterTagItems()

utility.library/ToLower                               utility.library/ToLower

    NAME
	ToLower - Convert a character to lowercase. (V37)

    SYNOPSIS
	char = ToLower(char)
	D0		D0

	char ToLower(char);

    FUNCTION
	Converts a character to lowercase, handling international character
	sets.

    INPUTS
	char - character to be converted.

    RESULT
	char - lowercase version of input character.

    NOTES
	Commodore is planning a localization library which will take care
	of most details pertaining to system integration into different
	cultures, locales, and territories.

	This function will automatically be replaced by a localized version
	whenever the locale.library is loaded in memory. As such, the
	resulting converted character may change depending on the locale
	currently defined by the user. Take this fact into consideration when
	using this function, and do not rely on obtaining specific
	conversions.

    BUGS

    SEE ALSO

utility.library/ToUpper                               utility.library/ToUpper

    NAME
	ToUpper - Convert a character to uppercase. (V37)

    SYNOPSIS
	char = ToUpper(char)
	D0		D0

	char ToUpper(char);

    FUNCTION
	Converts a character to uppercase, handling international character
	sets.

    INPUTS
	char - character to be converted.

    RESULT
	char - uppercase version of input character.

    NOTES
	Commodore is planning a localization library which will take care
	of most details pertaining to system integration into different
	cultures, locales, and territories.

	This function will automatically be replaced by a localized version
	whenever the locale.library is loaded in memory. As such, the
	resulting converted character may change depending on the locale
	currently defined by the user. Take this fact into consideration when
	using this function, and do not rely on obtaining specific
	conversions.

    BUGS

    SEE ALSO

utility.library/UDivMod32                           utility.library/UDivMod32

   NAME
	UDivMod32 -- Unsigned 32 by 32 bit division and modulus. (V36)

   SYNOPSIS
	Quotient:Remainder = UDivMod32( Dividend, Divisor )
	D0       D1                     D0        D1

	ULONG UDivMod32( ULONG, ULONG );

   FUNCTION
	Divides the unsigned 32 bit dividend by the unsigned 32 bit divisor
	and returns a unsigned 32 bit quotient and remainder.

   INPUTS
	Dividend 	- unsigned 32 bit dividend.
	Divisor 	- unsigned 32 bit divisor.

   RESULTS
	Quotient 	- unsigned 32 quotient of the division.
	Remainder 	- unsigned 32 remainder of the division.

   NOTES

   SEE ALSO
	SDivMod32(), SMult32(), UMult32()

   BUGS

utility.library/UMult32                               utility.library/UMult32

   NAME
	UMult32 -- Unsigned 32 by 32 bit multiply with 32 bit result. (V36)

   SYNOPSIS
	Result = UMult32( Arg1, Arg2 )
	D0                D0    D1

	ULONG UMult32( ULONG, ULONG );

   FUNCTION
	Returns the unsigned 32 bit result of multiplying Arg1 by Arg2.

   INPUTS
	Arg1, Arg2		- unsigned multiplicands.

   RESULTS
	Result			- the unsigned 32 bit result of
				  multiplying Arg1 by Arg2.

   NOTES

   SEE ALSO
	SDivMod32(), SMult32(), UDivMod32()

   BUGS