Amiga ISO Collection/AmigaUtilCD2.iso/Programming/Misc/TRSICAT.LZX/CATS_CD2_TRSI/Inc&AD2.0/Text_Autodocs/utility.doc

Text File | 1992-09-02 | 25.8 KB | 1,000 lines

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