TABLE OF CONTENTS

CALib.headers/WBCLIArgs
CALib.library/DestroyRDA
CALib.library/FreeWBCli
CALib.library/LRand/--background--
CALib.library/LRand/LRand
CALib.library/LRand/LRClose
CALib.library/LRand/LROpen
CALib.library/MakeRDA
CALib.library/MWReadArgs
CALib.library/RXPrintf
CALib.library/StrToDouble
CALib.library/WBCliArgs
CALib.headers/WBCLIArgs                               CALib.headers/WBCLIArgs

    NAME
        WBCLIArgs -- Header for the WBCLIArgs() routine.

    AUTHOR
        Fred Mitchell, Products Assurance, Commodore-Amiga, Inc.


    SEE ALSO
        CALib.library/WBCLIArgs

CALib.library/DestroyRDA                             CALib.library/DestroyRDA

    NAME
        DestroyRDA -- Deallocate memory used by MakeRDA()

    SYNOPSIS
        void DestroyRDA(struct RDArgs *rda)

    FUNCTION
        Frees memory used by MakeRDA(), returning it back to the system.
        DOES NOT do a FreeArgs() - you must do that yourself (see MakeRDA()).

    INPUTS
        rda - The RDArgs structure allocated by MakeRDA().

    RESULTS
        Nothing's returned.

    SEE ALSO
        MakeRDA().

CALib.library/FreeWBCli                               CALib.library/FreeWBCli

    NAME
        FreeWBCli -- Free up the resources used by WBCliArgs()

    AUTHOR
        Fred Mitchell, Products Assurance, Commodore-Amiga, Inc.

    SYNOPSIS
        void FreeWBCli(struct WBCli *wbcli)

    FUNCTION
        Releases all resources associated with WBCliArgs().

    INPUTS
        wbcli   - PRIVATE structure returned by WBCliArgs(). Can be NULL,
                  in which case it will be ignored.

    SEE ALSO
        WBCliArgs()

CALib.library/LRand/--background--         CALib.library/LRand/--background--

    NAME
        LRand -- Long Random number system

    AUTHOR
        Fred Mitchell

    DESCRIPTION
        The LRand system employs a shift-register metaphor to
        create the random sequence. based on the number of
        bits in the shift-register, it is possible to acheive
        a period of (2 ** bits) if done properly. Since this is
        implemented as unsigned longwords, you can get a steady
        train of random values.

        The system is designed to be customizable by the user,
        but does have useful defaults.

CALib.library/LRand/LRand                           CALib.library/LRand/LRand

    NAME
        LRand -- Generate unsigned longword random number

    SYNOPSIS
        ULONG LRand(struct LREnv *lr)

    FUNCTION
        Generates a unsigned longword random number based on the state of
        the hande.

    INPUTS
        lr  - handle created by LROpen().

    RESULTS
        Returns an unsigned longword random number, to the full range
        of the longword (0 to 2**lwbits - 1).

    SEE ALSO
        LROpen().

CALib.library/LRand/LRClose                       CALib.library/LRand/LRClose

    NAME
        LRClose -- Deallocate resources used for LRand

    SYNOPSIS
        void LRClose(struct LREnv *lr)

    FUNCTION
        Frees up and deallocates any resources associated with LR.

    INPUTS
        lr  - The handle returned by LROpen(). NULL handles are allowed.

    RESULTS
        Returns nothing

    SEE ALSO
        LROpen().

CALib.library/LRand/LROpen                         CALib.library/LRand/LROpen

    NAME
        LROpen -- Set up the LR System

    SYNOPSIS
        struct LREnv *LROpen(ULONG Seed, ULONG NumRegs, ULONG Tap)

    FUNCTION
        Creates a LREnv handle for use of random number generation.
        If NumRegs is zero, uses internal defaults for NumRegs and
        Tap. Else both must be specified. NumRegs should be a prime
        number, and Tap should probably be 2 or 3 less than
        NumReg. You will have to experiment for best settings of
        NumRegs and Tap.

    INPUTS
        Seed    - Seed to use for LRand

        NumRegs - Either ZERO (0) for internal defaults, or a number > 1.
                  Note that NumRegs longwords will be allocated for
                  the shift-register.

        Tap     - Place to tap register for feedback. Good taps would
                  probably be around NumRegs - 3. Experimentation is
                  Necessary. Note that this is ignored when NumRegs == 0.

    RESULTS
        Returns a pointer to a private handle, or NULL.

    SEE ALSO
        LRClose().

CALib.library/MakeRDA                                   CALib.library/MakeRDA

    NAME
        MakeRDA -- Make an RDArgs structure for scanning a buffer

    AUTHOR
        Fred Mitchell

    SYNOPSIS
        struct RDArgs *MakeRDA(char *buf)

    FUNCTION
        Sets up an RDArgs structure for parsing a NULL-terminated
        buffer by ReadArgs().

    INPUTS
        buf - pointer to a NULL-terminated buffer to be parsed.
              A copy of buf will be made.

    RESULTS
        Returns a pointer to a RDArgs structure, which must be freed
        by calling DestroyRDA(). Returns a NULL pointer if out of
        memory.

    EXAMPLE
        if (rda = MakeRDA(buf))
        {
            if (ReadArgs(TEMPLATE, &args, rda))
            {
                ...
                FreeArgs(rda);
            }
            DestroyRDA(rda);
        }
        ...

    SEE ALSO
        DestroyRDA()

CALib.library/MWReadArgs                             CALib.library/MWReadArgs

    NAME
        MWReadArgs -- Substitute for ReadArgs

    AUTHOR
        Fred Mitchell

    SYNOPSIS
        struct RDArgs *ReadArgs(UBYTE *template,
                        LONG *array, struct RDArgs *rdargs)

    FUNCTION
        Replacement for the ReadArgs() supplied by dos.library. This
        implementation is a drop-in replacement for ReadArgs() and more.
        The differences are:

            *   /M can appear anywhere in the template and
                behave as as expected.

            *   Multiple synonyms can be specified
                e.g. "W=WHOLE=WHOLE_THING/K"

            *   Can be made keyword case-sensitive, specifiable
                from template.
                i.e. "Del/C"

            *   Options can be delimited a character of your
                choosing.
                e.g. "//D,..." uses slash as a delimiter

            *   Help can be placed in the template.
                e.g. "W=WHOLE(Create The Whole Thing)/K"

        All other rules concerning ReadArgs() should apply.

CALib.library/RXPrintf                                 CALib.library/RXPrintf

    NAME
        RXPrintf -- formats an Argstring.

    AUTHOR
        Fred Mitchell

    SYNOPSIS
        UBYTE *RXPrintf(char *fmt, ULONG p1, ...)

    FUNCTION
        Uses RawDoFmt() to format an Argstring for ARexx. Follows all of the
        conventions of RawDoFmt().

    INPUTS
        fmt     - the format string
        p1, ... - The list of parameters

    RESULTS
        returns a pointer to an ARexx Argstring, which can be passed
        back to ARexx as a result string.

    NOTE
        To use this function, the rexxsyslib.library MUST be opened!!!

    SEE ALSO
        exec/RawDoFmt

CALib.library/StrToDouble                           CALib.library/StrToDouble

    NAME
        StrToDouble -- Convert a string to a double float

    SYNOPSIS
        double StrToDouble(char *s, long *plen)

    FUNCTION
        Converts the given string to a double. Optionally
        supplies the number of characters consumed. Will
        stop on a non-numeric character. Skips over leading
        whitespace.

    INPUTS
        s       - string to convert
        plen    - pointer to long that will receive the length of
                  the string connverted, or NULL. This includes any
                  leading whitespace skipped. If pointer is NULL, will
                  be ignored.

    RESULTS
        Returns the double result. If no number was encountered, will
        return a zero.

    BUGS
        Error checking needs to be improved.

    SEE ALSO

CALib.library/WBCliArgs                               CALib.library/WBCliArgs

    NAME
        WBCliArgs -- Argument processing for WorkBench tooltypes and CLI

    AUTHOR
        Fred Mitchell, Products Assurance, Commodore-Amiga, Inc.

    SYNOPSIS
        struct WBCli *WBCliArgs(struct TagItem *array)
        struct WBCli *WBCliArgsTags(ULONG tag1, (void *) data, ...)

    FUNCTION
        WBCLIArgs processes arguments either from ToolTypes
        or ReadArgs(). It allows a uniformity and therefore
        transparency as how these arguments are to be processed.
        The same labels used for ReadArgs can also be used for
        Workbench ToolTypes without the programmer doing extra
        work. The ToolTypes, if exists, can be used as defaults
        for CLI ReadArgs if the appopriate information is given.

    INPUTS
        array       - Array of TagItems
        tag1, ...   - TagItems
        data, ...   - Data required by Tag

    TAGITEMS
        WC_Template     - (char *) Template of the same format that
                          ReadArgs() wants. Required.

        WC_Args         - (long *) Array of arguments, corresponding to
                          the placement in the template, ReadArgs()-style.
                          Required.

        WC_Startup      - (struct WBStartup *) Startup message to process.
                          Will use first argument's ToolTypes for default
                          (if WC_DiskObject is not specified), and the rest
                          as parameters to the first /M template. Thus, an
                          array of fully qualified pathnames are created.

        WC_TrustStartup - (BOOL) Whether to trust WC_Startup as
                          valid. Default is TRUE. This is useful for
                          using "argv" and "argc" directly. Therefore,
                          this is an indication to WBCliArgs() that
                          the program started from Workbench or CLI.

                          The way one would normally use this with a normal
                          main() startup is as follows:
                            ...
                                WC_Startup, argv,
                                WC_TrustStartup, !argc,
                            ...

                          NOTE that if WC_Startup is not present or
                          NULL that WBCliArgs() will assume CLI startup.

        WC_DiskObject   - (struct DiskObject *) DiskObject to process
                          for ToolTypes. Overrides the object given in
                          WC_Startup. Only reads information from this;
                          you are still responsible for the cleanup.

        WC_DiskObjectName - Synonym for WC_DiskObject, name of the icon
                          to read for ToolTypes. WBCliArgs() in this
                          case acquires and unloads the disk object
                          on its own.

        WC_Help         - (char *) NULL-terminated help string to
                          use if user types second '?' from CLI.

        WC_MToolTypes   - (char *) If non-NULL, use the string as a
                          pattern match to the ToolTypes array to fill
                          in the /M multiple strings, when launched from
                          Workbench. Does not affect ReadArgs()/Cli
                          operation. Mutiple strings are then what was
                          matched in the ToolTypes rather than the
                          full pathnames of a multiple-select.

    RESULT
        Returns a handle, a pointer to a PRIVATE structure if successful,
        or NULL. Handle must be passed to FreeWBCli() to release
        resources ONLY WHEN you are finished using the args array.
        Memory is dynamically allocated by WBCliArgs()
        to fill in some of the arguments in the args array, so do
        not FreeWBCli() until you are finished with using the
        args.

    NOTES
        We may, at a future date, have WBCliArgs() open its own
        libraries. Do not depend on this, however.

    NOTES
        The modifier '/N' has slightly different behavior for ToolTypes
        than for ReadArgs(). '/N' for ToolTypes can be either decimal,
        hexadecimal, or octal following the 'C' convention of denoting
        radix of numbers. Since ReadArgs() does not recognize this
        convention, ReadArgs() will still try to convert them as
        decimal.

    BUGS
        We have made every effort to make this call crash-proof. However,
        there are some low-memory or other error conditions that do
        not properly back out of operations yet. Those areas of
        concern are marked by three ampersands in the source code,
        and will be addressed shortly.

    LIBRARIES
        Requires the following libraries to be opened:
            intuition.library   (IntuitionBase)
            utility.library     (UtilityBase)
            icon.library        (IconBase)
            dos.library         (DOSBase)
            exec.library

    SEE ALSO
        FreeWBCli()
