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


NAME
    CxBroker -- create a commodity broker. (V36)

SYNOPSIS
    broker = CxBroker(nb,error);
                      A0 D0

    CxObj *CxBroker(struct NewBroker *,LONG *);

FUNCTION
    This function creates a broker from the specification found in the
    NewBroker structure pointed to by 'nb'. The purpose and meaning of the
    fields of the NewBroker structure are described below. Also see
    <libraries/commodities.h> for more info.

    struct NewBroker
    {
       BYTE            nb_Version;
       BYTE           *nb_Name;
       BYTE           *nb_Title;
       BYTE           *nb_Descr;
       SHORT           nb_Unique;
       BYTE            nb_Pri;
        struct MsgPort *nb_Port;
        WORD            nb_ReservedChannel;
    };

    nb_Version
    This is the way that future versions of commodities.library
    can identify which version of the NewBroker structure you are using.
    This should be set to NB_VERSION, defined in <libraries/commodities.h>

    nb_Name
    This is the name of the broker. This name is used to find the broker
    in the Commodities Object List and is the name shown in the list
    gadget of the Exchange program. The name string is copied in the
    broker object upon creation, so this string can be discarded right
    after CxBroker() returns. The maximum length of the name string is
    defined by a constant in <libraries/commodities.h>.

    nb_Title, nb_Descr
    These are two strings which appear to the user in the Exchange
    program and describe the application the broker is representing.
    Note that these strings are copied into the broker object.
    The maximum length of these strings that will be recognized are
    defined by constants in <libraries/commodities.h>.

    nb_Unique
    This field indicates what should happen if a broker of the same name
    (nb_Name) already exists in the Commodities Object List. Constants
    in <libraries/commodities.h> allow the caller to specify whether
    another broker is to be created, and whether any existing broker of
    the same name should be notified that an attempt at creating a
    duplicate has been made.

    nb_Pri
    This specifies with what priority the new broker is to be inserted
    within the Commodities Object List. Higher priority nodes appear
    earlier in a list. See <libraries/commodities.h> for guidelines for
    priorities of different types of applications. It is strongly
    recommended that the ToolTypes environment of an application be used
    to allow the end-user to set the priority of the broker.

INPUTS
    nb - an initialized NewBroker structure
    error - a pointer to a longword where to store a failure code, this
            may be NULL

RESULTS
    broker - a pointer to the broker object or NULL upon failure. If the
             'error' is not NULL, a further diagnostic code is placed at
             that address. Error codes are in <libraries/commodities.h> and
             include:

                    CBERR_OK
                    No problems; broker created OK.

                    CBERR_SYSERR
                    System problems, not your fault. Sign of low memory or
                    big problems.

                    CBERR_DUP
                    The nb_Unique field specified that only one broker of
                    'nb_Name' should be allowed, and one already exists.

                    CBERR_VERSION
                    The version specified in 'nb_Version' is unknown to the
                    library.

SEE ALSO
    SetCxObjPri(), <libraries/commodities.h>