:bk=0

	Commodities Exchange Function Reference
		v0.3 March 19, 1987
		Jim Mackraz, San Jose, California

NOTE: Starting with Version 0.3, new functions are added to the
end of this file (and appended to the file "funcsummary").


NAME	CreateCxObj()

	CxObj	*co = CreateCxObj(type, arg1, arg2);

	LONG	type;
	LONG	arg1;
	LONG	arg2;

DESCRIPTION
	Creates a Commodities Object of type 'type.'  It is not proper
	to call this function directly.  Each object creation routine
	except CxBroker() is defined as a macro in "cxusr.h."  The
	routines are independently documented.

	Note that the handle returned is a pointer to an abstract type
	named 'CxObj.'  This type is defined as a LONG in "cxusr.h" but
	internally has more content.  The specific size and contents of
	internal data structures are 'private.'

	All functions which operate on a Commodities object are made with
	a reference to the thirty-two bit value returned by this function
	(or CxBroker()).

DIAGNOSTICS
	A NULL returned value indicates that the requested object could not
	be created, typically for lack of system memory.  Minor problems in
	creating an object, such as providing a bad filter description to
	CxFilter(), typically don't cause failure, but are recorded in
	an internal error field in the new object.

SEE ALSO
	CxObjError(), CxFilter(), CxTypeFilter(), CxSender(), CxSignal(),
	CxTranslate(), CxDebug(), CxCustom(), CxBroker()


NAME	CxBroker()

	CxObj	*broker	=	CxBroker(nb, error);

	struct NewBroker	*nb;
	LONG				*error;

DESCRIPTION
	Creates a broker from the specification found in the NewBroker
	structure pointed to by 'nb.'  

	The purposes and meaning of the fields are described below.
	See also the include file "broker.h."

	struct NewBroker {
		BYTE	nb_Version;
		BYTE	*nb_Name;
		BYTE	*nb_Title;
		BYTE	*nb_Descr;
		SHORT	nb_Unique;
		BYTE	nb_Pri;
	};

	'nb_Version' is the way that future versions of the Commodities
	library can identify which version of the NewBroker structure
	you are using.  This should be set to NB_VERSION, defined in
	"broker.h."

	'nb_Name' is a string which is to be the name of the broker
	Node which is created.  This name is application internal,
	and is used only to find the broker Node in the Commodities
	Object List.

	'nb_Title' and 'nb_Descr' are two strings which appear to the
	user and describe the application the broker is representing.
	Note that all strings above are copied into the broker object.
	The maximum length of these strings that will be recognized are
	defined by constants in "broker.h."

	'nb_Unique' is a field that indicates what should happen if
	a broker of the same name (nb_Name) already exists in the
	Commodities Object List.  Constants in "broker.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' specifies with what priority in the Commodities
	Object List that the new broker is to be inserted.  Higher
	priority nodes appear earlier in a list.  See "broker.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.

DIAGNOSTICS
	Returns NULL in the event of failure.  If the pointer 'error'
	is non-null, a further diagnostic code will be placed at
	that address.  Error codes are in "broker.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 field 'nb_Version' is unknown to the running version
		of "commodities.library."

SEE ALSO
	FindBroker()
	Brokers and Application Sub-Trees (in Reference Manual)


NAME	CxFilter()	--	MACRO

	CxObj *filter = CxFilter(description);

	BYTE	*description;

DESCRIPTION
	Creates an input event filter object which matches Commodities
	Input Messages fitting the 'description' string.  If
	'description' is NULL, the filter will not match any messages.

	A filter may be modified by the functions SetFilter(), using
	a description string, and SetFilterIX(), which takes a 
	binary Input Expression as a parameter.

	This function is a C-language macro for CreateCxObj(), defined
	in "cxfunctions.h."

DIAGNOSTICS
	Returns NULL if the function fails, which only occurs
	if there is no memory for the new filter object.  If there
	is a problem in the description string, the internal error
	code of the filter object will be set to so indicate.  This
	error code may be interrogated using the function CxObjError().

SEE ALSO
	CreateCxObj()
	SetFilter(), SetFilterIX(), CxObjError()
	Objects and Message (in Reference Manual)
	Input Expressions and Description Strings
	Objects and Messages (in Reference Manual)
	Error Handling	(in Reference Manual)


NAME	CxTypeFilter()	--	MACRO

	CxObj *typef = CxTypeFilter(typemask);

	LONG	typemask;

DESCRIPTION
	Creates a Commodities Object similar to CxFilter(), but one
	that diverts all Commodities messages whose type, which is
	always a power of two, matches a bit set in 'typemask.'

	Values of message types are given in "cxusr.h."

	This function is a C-language macro for CreateCxObj(), defined
	in "cxfunctions.h."

DIAGNOSTICS
	Returns NULL if the function fails, which only occurs
	if there is no memory for the new filter object.  If there
	is a problem in the description string, the internal error
	code of the filter object will be set to so indicate.  This
	error code may be interrogated using the function CxObjError().

SEE ALSO
	CreateCxObj()
	SetFilter(), SetFilterIX(), CxObjError()
	Object and Messages (in Reference Manual)
	Input Expressions and Description Strings
	Error Handling


NAME	CxSignal()	--	MACRO

	CxObj	*signaler = CxSignal(task, signal);

	struct Task	*task;
	LONG		signal;

DESCRIPTION
	This function creates a Commodities signal object.  The action
	of this object on receiving a Commodities message is to
	send the 'signal' to the 'task.'  The caller is responsible
	for allocating the signal and determining the proper task ID.

	Note that 'signal' is the signal value as returned by
	AllocSignal() (example: 3) , not the mask made from
	that value (i.e., not binary 0000000000001000).

	This function is a C-language macro for CreateCxObj(), defined
	in "cxfunctions.h."

DIAGNOSTICS
	Returns NULL if the object could not be created.

SEE ALSO
	CreateCxObj()
	Objects and Messages (in Reference Manual)
	exec.library/Signal(), exec.library/AllocSignal(),
	exec.library/FindTask()


NAME	CxSender()	--	MACRO

	CxObj	*sender = CxSender(port, id)

	struct MsgPort	*port;
	LONG			id;

DESCRIPTION
	This function creates a Commodities sender object.  The action
	of this object on receiving a Commodities message is to
	copy the Commodities message into a standard Exec Message,
	to put the value 'id' in the message as well, and to send the
	message off to the Message Port 'port.'

	The value 'id' is used so that an application can monitor
	messages from several senders at a single port.  It can
	be retrieved from the Exec message by using the function
	CxMsgID(). The value can be a simple integer ID, or a pointer
	to some application data structure, for example.

	Note that Exec messages sent by sender objects arrive
	asynchronously at the destination port.  Do not assume 
	anything about the status of the Commodities message which
	was copied into the Exec message you received.

	All Exec messages sent to your ports must be replied.
	Messages may be replied after the sender object has been
	deleted.

	This function is a C-language macro for CreateCxObj(), defined
	in "cxfunctions.h."

DIAGNOSTICS
	Returns NULL if the sender object cannot be created.

SEE ALSO
	CreateCxObj()
	exec.library/PutMsg(), exec.library/ReplyMsg()
	CxMsgID()


NAME	CxTranslate()	--	MACRO

	CxObj	*translator = CxTranslate(ie);

	struct InputEvent	*ie;

DESCRIPTION
	This function creates a Commodities 'translate' object. 
	The action of this object on receiving a Commodities
	message is to replace that message in the commodities network
	with a chain of Commodities input messages.

	One new Commodities input message for each input event
	in the linked list starting at 'ie' (and NULL terminated).
	The routing information of the new input messages will be
	copied from the input message they replace.

	The linked list of input events associated with a translate
	object can be changed using the SetTranslate() function.

	If 'ie' is NULL, the null translation occurs: that is, the
	original commodities input message is disposed, and no
	others are created to take its place.

	This function is a C-language macro for CreateCxObj(), defined
	in "cxfunctions.h."

DIAGNOSTICS
	Returns NULL if the translate object cannot be created.

SEE ALSO
	CreateCxObj()
	SetTranslate()
	Commodities Input Messages and Filters


NAME	CxCustom()	--	MACRO

	CxObj	*custom = CxCustom(action, id);

	LONG	(*action)();
	LONG	id;

DESCRIPTION
	This function creates a custom Commodities object.  The action
	of this object on receiving a Commodities message is to
	call a function of the application programmer's choice.

	The function provided ('action') will be passed a pointer to
	the actual commodities message (in commodities private data
	space), and will actually execute as part of the input handler
	system task.  Among other things, the value of 'id' can be
	recovered the message by using the function CxMsgID().

	The purpose of this function is two-fold.  First, it allows
	programmers to create Commodities Exchange objects with
	functionality that was not imagined or chosen for inclusion
	by the designers.  Secondly, this is the only way to act
	synchronously with Commodities. 

	For further explanation and examples, consult the Reference
	Manual.

	This function is a C-language macro for CreateCxObj(), defined
	in "cxfunctions.h."

DIAGNOSTICS
	Returns NULL if the custom object cannot be created.

SEE ALSO
	CreateCxObj()
	Custom Objects (in Reference Manual)
	CxMsgID()


NAME	CxDebug()	--	MACRO

	CxObj	*debugger = CxDebug(id);

	LONG	id;

DESCRIPTION
	This function creates a Commodities debug object.  The action
	of this object on receiving a Commodities message is to
	print out information about the Commodities message through
	the Serial port (using the kprintf() routine).  The value
	'id' will also be displayed.

	Note that this is a synchronous occurence (the printing
	is done by the input device task).  If screen or file
	output is desired, using a sender object instead of
	debug object is necessary, since such output is best
	done by your application process.

	This function is a C-language macro for CreateCxObj(), defined
	in "cxfunctions.h."

DIAGNOSTICS
	Returns NULL if the debug object cannot be created.

SEE ALSO
	CreateCxObj()
	CxSender()
	exec_support/kprintf()


NAME	DeleteCxObj()

	void	DeleteCxObj(co);

	CxObj	*co;

DESCRIPTION
	Deletes a Commodities object of any type.  If the object
	is linked into a list, will first be removed.  Note that
	the handle 'co' is invalid after this function is called.

	Note also that deleting an object which has other objects attached
	to it may be undesirable.  Use the function DeleteCxObjAll()
	to delete an entire sub-tree of objects.

DIAGNOSTICS
	None.  Possible system crash if fed fiction.

SEE ALSO
	exec.library/Remove()
	DeleteCxObjAll()


NAME	DeleteCxObjAll()

	void	DeleteCxObjAll(co);

	CxObj	*co;

DESCRIPTION
	This function deletes the Commodities object 'co,' and also
	recursively deletes all objects attached to 'co,' and the
	objects attached to them.

	If 'co' is linked into a list, it is removed first.  Note
	that the handle 'co' is invalid after this function is called.

	This function is useful when an application exits: most
	applications can clean up completely by deleting the
	entire sub-tree of objects starting at their broker.

DIAGNOSTICS
	None.  Definite system crash if fed fiction.

SEE ALSO
	exec.library/Remove()
	DeleteCxObj()


NAME	CxObjType()

	LONG	type = CxObjType(co);

	CxObj	*co;

DESCRIPTION
	This function should not really be necessary.  It returns
	the type of a Commodities object, which you should already
	know, since you created it in the first place.

	Values for 'type' are given in "cxusr.h."

DIAGNOSTICS
	The value of 'type' will be CX_INVALID if you pass in a value of
	NULL for 'co.'  If you pass a random value for 'co,' you
	will get a random answer.

SEE ALSO
	All Commodities object creation routines.


NAME	ActivateCxObj()

	LONG	previous = ActivateCxObj(co, true);

	CxObj		*co;
	LONG		true;	/* Aztec user's take note	*/

DESCRIPTION
	Commodities objects of all types maintain an "activation state."
	If an object is "active," then it performs its particular action
	whenever a Commodities message arrives.  If the object is
	"inactive," no action is taken, and the message goes on to its
	next destination.

	All objects are created in the "active" state except brokers,
	which are created "inactive."  Thus, after you create your
	broker and hang a tree of objects off of it, you must remember
	to use this function to activate your broker.  This causes it
	it to divert all messages to your tree of objects.

	This function activates 'co' if 'true,' and deactivates it
	otherwise.  The previous value of activation is returned:
	zero for inactive, non-zero for active.

DIAGNOSTICS
	None.

SEE ALSO
	CxBroker()
	Brokers and Application Sub-Trees (in Reference Manual)


NAME	SetTranslate()

	LONG	error = SetTranslate(translator, ie);

	CxObj				*translator;
	struct InputEvent	*ie;

DESCRIPTION
	This function replaces the translation list of a Commodities
	translate object 'translator' with the linked list starting at 'ie.'

	A null value for 'ie' indicates that the object 'translator'
	should swallow all Commodities messages that are sent its way.

	Note that the input events are not copied into Commodities private
	memory, but the value of ie is used--asynchronously to the
	application program--to find a chain of InputEvents in the
	application's data space.

	At the time of translation, though, each input event is copied
	into its own new Commodities message.

	This means that no other Commodities user, nor Commodities itself
	will be modifying your list of InputEvents.  On the other
	hand, your program must not corrupt the input event chain
	that has been presented to a translator. 

DIAGNOSTICS
	Returns zero if there is no problem, otherwise an error code
	with values found in "cxusr.h."  The only forseeable error
	could occur if 'translator' was not in fact a translate object.

SEE ALSO
	include:devices/inputevent.h
	CxTranslate()


NAME	SetFilter()

	void	SetFilter(filter, text);

	CxObj	*filter;
	char	*text;

DESCRIPTION
	Changes the matching condition of a Commodities input filter to
	that described by the input description string 'text.'

DIAGNOSTICS
	The internal error of 'filter' will have the COERR_BADFILTER
	bit set or cleared depending on the failure or success (resp.)
	of SetFilter().

SEE ALSO
	SetFilter(), SetFilterIX(), CxObjError()
	Commodities Input Messages and Filters
	Input Expressions and Description Strings


NAME	SetFilterIX()


	LONG	error = SetFilterIX(filter, ix);

	CxObj	*filter;
	IX		*ix;

DESCRIPTION
	Changes the matching condition of a Commodities input filter to
	that described by the binary input expression pointed by 'ix.'

	Input expressions are defined in the file "ix.h."  It is important
	to remember that the first field of the input expression structure
	must indicate which type of version of the input expression structure
	is being used.  See "ix.h."

DIAGNOSTICS
	If 'error' returned is non-zero, it contains an error code from
	"cxusr.h."

SEE ALSO
	SetFilter(), SetFilterIX(), CxObjError()
	Commodities Input Messages and Filters
	Input Expressions and Description Strings


NAME	ParseIX()

	LONG	failurecode = ParseIX(string, ix);

	char	*string;
	IX		*ix;

DESCRIPTION
	Given an input description string and an allocated, valid input
	expression, sets the fields of the input expression to 
	correspond to the description string.

DIAGNOSTICS
	CHANGED FOR v0.3!!!
	Returns zero if the string WAS successfully parsed.
	Error codes will be formalized later.

SEE ALSO
	Input Expressions and Description Strings


NAME	CxObjError()

	LONG	error = CxObjError(co);

	CxObj	*co;

DESCRIPTION
	When a function acting on an object fails, it records the failure
	in the object's internal data.  This function returns the
	accumulated error value.  The values are represented by flag
	bits defined in "cxusr.h."  Several errors may be recorded
	by multiple bits in 'error.'

	The possible errors (at current writing) are:

	COERR_ISNULL
		The value of parameter 'co' was in fact NULL.  This error
		means "the problem with the object you inquire about is
		that it failed to be created."

	COERR_NULLATTACH
		Using the Commodities list manipulation functions, an
		attempt was made to add a NULL object to the list belonging
		to 'co.'  This allows a line of code as follows to exist
		in an error-tolerant program:

			AttachCxObj(filter, CxSender(myport, MY_ID));

	COERR_BADFILTER
		The most recent filter specification for a Filter object
		was faulty.  This happens if no sense can be made out
		of a description string, or if an Input Expression (IX)
		has in invalid format or version byte.  (See "ix.h.")

		When this bit is set in a filter's error field, the
		filter will match nothing, but this is not the proper
		way to "turn off" a filter.  Use ActivateCxObj().

	COERR_BADTYPE
		A type specific operation, such as SetFilterIX(), was called
		for object 'co,' but 'co' isn't of the proper type.

DIAGNOSTICS
	Nothing but.

SEE ALSO
	SetFilter(), SetFilterIX(), AttachCxObj(), ActivateCxObj(),
	ClearCxObjError()


NAME	ClearCxObjError()

	void	ClearCxObjError(co);

	CxObj	*co;

DESCRIPTION
	Clears the accumulated error value of Commodities object 'co.'

	It is unwise to do this to a filter if COERR_BADFILTER is set.
	This will fool the Commodities Exchange into thinking the
	filter is OK.  Set another, valid, filter, or leave it alone.

DIAGNOSTICS
	None.

SEE ALSO
	CxObjError()


NAME	CxMsgID()

	LONG	id = CxMsgID(cxm);

	CxMsg	*cxm;

DESCRIPTION
	Returns the value associated with the cause or source of the
	Commodities message 'cxm.'  Values are provided by the application
	when a Sender or Custom object is created.

DIAGNOSTICS
	If not specified by the application, the ID value of a Commodities
	message will be null.  It is suggested that using non-null
	values in your program as a rule may identify some possible errors.

SEE ALSO
	CxSender()
	CxCustom()


NAME	AttachCxObj()

	void	AttachCxObj(headobj, co);

	CxObj	*headobj;
	CxObj	*co;

DESCRIPTION
	Appends object 'co' to the list of object 'headobj,' using the
	Exec function AddTail().  Returns 'headobj.'

DIAGNOSTICS
	If 'co' is null, this function will record that fact in the
	internal accumulated error of 'headobj.'  This error record
	can be retrieved using CxObjError() and cleared using
	ClearCxObjError().

SEE ALSO
	exec.library/AddTail()
	Objects and Messages (in Reference Manual)
	CxObjError(), ClearCxObjError()


NAME	EnqueueCxObj()

	void	EnqueueCxObj(headobj, co);

	CxObj	*headobj;
	CxObj	*co;

DESCRIPTION
	Puts object 'co' into the list of object 'headobj,' using the
	Exec function Enqueue().  Returns 'headobj.'

	This function uses the priority of the Commodities object as a node.
	This priority can be set using SetCxObjPri().

DIAGNOSTICS
	If 'co' is null, will record that fact in the internal accumulated
	error of 'headobj.'  This error record can be retrieved using
	CxObjError() and cleared using ClearCxObjError().

SEE ALSO
	exec.library/Enqueue()
	SetCxObjPri()
	Objects and Messages (in Reference Manual)
	CxObjError(), ClearCxObjError()


NAME	InsertCxObj()

	void	InsertCxObj(headobj, co, pred);

	CxObj	*headobj;
	CxObj	*co;
	CxObj	*pred;

DESCRIPTION
	Adds object 'co' to the list of object 'headobj,' using the
	Exec function Insert().  Returns 'headobj.'

	As described in the autodocs for exec.library/Insert(), 'co' will
	be inserted in the list of 'headobj' prior to 'pred.'  Even though
	Insert() doesn't use the list header unless 'pred' is null, calling
	InsertCxObj() you should always pass a valid 'headobj' and a possibly
	null 'pred.'

DIAGNOSTICS
	If 'co' is null, this will be recorded in the internal accumulated
	error of 'headobj.'  This error record can be retrieved using
	CxObjError() and cleared using ClearCxObjError().

SEE ALSO
	exec.library/Insert()
	Objects and Messages (in Reference Manual)
	CxObjError(), ClearCxObjError()


NAME	RemoveCxObj()

	void	RemoveCxObj(co);

	CxObj	*co;

DESCRIPTION
	Removes Commodities object 'co' from any list he is be a part of.
	Will not crash if 'co' is null, or if it has not been inserted
	in a list (and is not corrupted).

	It is not recommended to remove a broker from the master list.

DIAGNOSTICS
	None.

SEE ALSO
	Objects and Messages (in Reference Manual)


NAME	SetCxObjPri()

	void	SetCxObjPri(co, pri)

	CxObj	*co;
	LONG	pri;

DESCRIPTION
	This function sets the priority of a Commodities object for the
	purposes of EnqueueCxObj().  Note that the Commodities list
	mechanisms are based on Amiga Exec lists, so the priority is
	recorded as a signed byte.  Please keep values in range.  A
	value of zero is usually fine.

	It is strongly recommended that the ToolTypes environment be
	utilized to provide end-user control over the priority of
	brokers, but application specific ordering of other objects
	within their lists is not dictated.

DIAGNOSTICS
	None.

SEE ALSO
	ToolTypes and the Commodities Environment (in Reference Manual)
	EnqueueCxObj()


NAME	FindBroker()

	CxObj	*broker = FindBroker(name);

	char	*name;

DESCRIPTION
	Looks for a Commodities broker whose node name is 'name' in the
	Commodities Object List.

	All uses of this function by applications are highly suspect.

DIAGNOSTICS
	Returns NULL if 'name' not found.

SEE ALSO
	Objects and Messages (in Reference Manual)


NAME	CxMsgType()

	ULONG	type = CxMsgType(cxm);

	CxMsg	*cxm;

DESCRIPTION
	Returns the type of a Commodities message.  Possible values of
	'type' are found in "cxusr.h."  Most Commodities messages 
	are Input Event messages.

DIAGNOSTICS
	The value NULL should never be returned, if 'cxm' points to
	a valid message.

SEE ALSO


NAME	CxMsgData()

	char	*contents = CxMsgData(cxm);

	CxMsg	*cxm;

DESCRIPTION
	Most Commodities messages contain meaningful data, such as an
	InputEvent structure.  A pointer to this data may be obtained by
	using this function.  A valid, non-null pointer will always
	be returned if 'cxm' is valid.

	You may get a Commodities message from a synchronous (custom
	object) or asynchronous (sender object) source.  In the second
	case, 'contents' is not valid after you have replied to the message.

DIAGNOSTICS
	If 'cxm' is null, returns NULL.

SEE ALSO
	CxSender()
	CxCustom()


NAME	DisposeCxMsg()

	void	DisposeCxMsg(cxm);

	CxMsg	*cxm;

DESCRIPTION
	Eliminates the Commodities message pointed to by 'cxm.'
	Can be used to 'swallow' InputEvents by disposing of
	every Commodities message of type CXM_IEVENT.

DIAGNOSTICS
	None.

SEE ALSO


NAME	RouteCxMsg()

	void	RouteCxMsg(cxm, co);

	CxMsg	*cxm;
	CxObj	*co;

DESCRIPTION
	Establishes the next destination of a Commodities message
	to be 'co,' which must be a valid Commodities object, and
	must be linked in ultimately to the Commodities Object List.

	Such a routing of an object is analogous to a 'goto' in a 
	program.  There is no effect on the message's routing stack.

DIAGNOSTICS
	None.

SEE ALSO
	DivertCxMsg()


NAME	DivertCxMsg()

	void	DivertCxMsg(cxm, headobj, returnobj);

	CxMsg	*cxm;
	CxObj	*headobj;
	CxObj	*returnobj;

DESCRIPTION
	Sends Commodities message 'cxm' down the list of objects attached to
	'headobj.'  The pointer 'returnobj' is first pushed onto the
	routing stack of 'cxm' so that when the end of the list of 'headobj'
	is reached the SUCCESSOR of 'returnobj' is the next destination.

	For example, when a filter finds a match with a message, the
	message is diverted down the filter's list like this:

		DivertCxMsg(cxm, filter, filter);.

DIAGNOSTICS
	None.

SEE ALSO
	Reference Manual


NAME	HotKey()  --	SCANNED LIBRARY

	CxObj	*filter = Hotkey(descr, port, ID);

	char			*descr;
	struct MsgPort	*port;
	LONG			ID;

DESCRIPTION
	This function is not part of "commodities.library," but
	is in the scanned library cx_support.lib.  It creates
	a triad of Commodities objects to accomplish a high-level
	function.

	The three objects are a filter, which is created to match
	by the call CxFilter(descr), a sender created by the call
	CxSender(port, ID), and a translator which is created by
	CxTranslate(NULL), so that it swallows any Commodities
	input event messages that are passed down by the filter.

	This is the simple way to get a message sent to your program
	when the user performs a particular input action.

	It is strongly recommended that the ToolTypes environment
	be used to allow the user to specify the input descriptions
	for your application's hotkeys.

DIAGNOSTICS
	Returns NULL and cleans up after itself if any problems occur
	creating the objects.  It may be wise to test filter using
	CxObjError() to insure that 'descr' was a valid description.

SEE ALSO
	ToolTypes and the Commodities Environment (in Reference Manual)
	CxFilter(), CxSender(), CxTranslate(), CxObjError()


NAME	ArgArray	--	SCANNED LIBRARY

	char	**ttypes = ArgArrayInit(argc, argv);

	int		argc;
	char	**argv;

DESCRIPTION
	This function is not part of "commodities.library," but is
	in "cx_support.lib."

	ArgArrayInit() returns a null-terminated array
	of strings suitable for sending to the icon.library function
	FindToolType().  This array will be the ToolTypes array of the
	program's icon, if it was started from the workbench.  It will
	be just 'argv' if the program was started from the CLI.

	NOTE WELL: Your C compiler must null terminate '*argv[]' for this
	scheme to work.  Aztec does, in the version Commodities was
	developed with.

	Pass ArgArrayInit() your startup arguments passed to main().

	ArgArrayInit() opens the icon.library (even if the caller was
	started from a CLI, so that the function FindToolType() can 
	be used) and may call GetDiskObject(), so clean up is necessary
	when the strings are no longer needed.  The function ArgArrayDone()
	does just that.

	Use of these routines facilitates the use of ToolTypes or command
	line arguments to control end-user parameters in Commodities 
	applications.  For example, a filter used to trap a keystroke for
	popping up a window might be created by something like this:

	char	*ttypes = ArgArrayInit(argc, argv);
	CxObj	*filter	= UserFilter(ttypes, "POPWINDOW", "alt f1");

	... with ...

	CxObj	*
	UserFilter(tt, action_name, default_descr)
	char	**tt;			/* null-terminated (char *(*)[])	*/
	char	*action_name;	/* name of your semantic action		*/
	char	*default_descr;	/* used if user doesn't provide		*/
	{
		char	*desc;

		desc = FindToolType(tt, action_name);

		return ( CxFilter(desc? desc: default_descr) );
	}

	In this way the user can assign "alt f2" to the action by
	entering a tooltype in the programs icon of the form:

		POPWINDOW=alt f2

	or by starting the program from the CLI with like so:

		myprogram "POPWINDOW=alt f2"

DIAGNOSTICS
	ArgArrayInit() would return NULL if any problems occured.

SEE ALSO
	ArgArrayDone()
	ArgString()
	ArgInt()
	icon.library/FindToolType()
	cx_support.lib probably will have UserFilter().

NAME	ArgArrayDone()		---	SCANNED LIBRARY

	void	ArgArrayDone();

DESCRIPTION
	This function closes the disk object and Icon Library opened
	by ArgArrayInit().  Don't call this until you are done using
	the ToolTypes argument strings.

DIAGNOSTICS
	None.

SEE ALSO
	ArgArrayInit()

NAME	ArgString()		---	SCANNED LIBRARY

	char	*string = ArgString(tt, string, defaultstring)

	char	**tt;
	char	*t;
	char	*defaultstring;

DESCRIPTION
	This function looks in the ToolTypes array 'tt' returned
	by ArgArrayInit() for the entry for 'string' and returns
	the "value" for 'string.'  The entry and value have the
	standard ToolTypes format such as:

		ENTRY=Value

	If an entry for 'string' is not found, the defaultstring
	will be returned.

DIAGNOSTICS
	None.

SEE ALSO
	ArgArrayInit()

NAME	ArgInt()		---	SCANNED LIBRARY

	int	value = ArgInt(tt, string, defaultval)

	char	**tt;
	char	*t;
	int		defaultval;

DESCRIPTION
	This function looks in the ToolTypes array 'tt' returned
	by ArgArrayInit() for the entry for 'string' and returns
	the "value" for 'string.'  The entry and value have the
	standard ToolTypes format such as:

		ENTRY=Value

	In the case of this function, value will be passed through
	'atoi()' before returning.

	If an entry for 'string' is not found, the integer 'defaultval'
	will be returned.

DIAGNOSTICS
	None.

SEE ALSO
	ArgArrayInit()

NAME	InvertKeyMap()

	ULONG	retval = InvertKeyMap(ansicode, ie, km)

	ULONG				ansicode;
	struct InputEvent	*ie;
	struct KeyMap		*km;

DESCRIPTION
	Figures out what InputEvent translates to an ANSI character code
	'ansicode.'  The InputEvent pointed to by 'ie' is filled in
	with that information.  The KeyMap 'km' is used, unless it
	is NULL, in which case the system standard keymap (as defined
	when commodities.library is initialized) is used.

	This function currently handles one-deep dead keys (such as
	<alt f>o).  It does not look up the high key map (keystrokes
	with scan codes greater than 0x40), and misses system changes to
	the default key map.

DIAGNOSTICS
	Returns non-negative value if it worked, less than zero, with
	error values to be defined in the future.

SEE ALSO
	InvertString()

NAME	InvertString()	--	SCANNED LIBRARY

	struct InputEvent	*InvertString(str, km)

	char			*str;
	struct KeyMap	*km;

DESCRIPTION
	This function returns a linked list of input events which would
	translate into the string using the keymap 'km' (of the system
	default keymap if 'km' is NULL).

	The null-terminated 'str' may contain:
	-ANSI character codes
	-backslash escaped characters: 
		\n	-	return
		\r	-	return
		\t	-	tab
		\0	-	don't use this, ok?
		\\	-	backslash
	-a text description of an input event as used by ParseIX(),
	 enclosed in angle brackets.

	An example is:
		abc<alt f1>\nhi there.

	NOTE: you are responsible for freeing the InputEvents that this
	function allocates.  You may use FreeIEvents().

DIAGNOSTICS
	Returns NULL if there is a problem, most often an illegal description
	enclosed in angles.

SEE ALSO
	ParseIX()
	FreeIEvents()

NAME	AddIEvents()

	void	AddIEvents(ie)

	struct InputEvent	*ie;

DESCRIPTION
	This function adds a null-terminated linked list to the input
	stream of Commodities.  It is a touch easier than using the
	input device directly.

	The contents of the input events are copied into Commodities internal
	messages, so they may be disposed of as soon as this call returns.

	The messages are initially routed to the first Broker in the
	Commodities Object List.

DIAGNOSTICS
	None.

SEE ALSO
	FreeIEvents()
