
This is bare bones documentation.  It should be much better in the next
release.

TclIR Documentation -- version 0.9
----------------------------------

TclIR adds one new command to Tcl, the orbRequest command.  It is also
available under several other command names including invokeMethod,
setAttribute, and getAttribute.  These commands are all equivalent and
are provided to make Tcl scripts more readable.

The orbRequest Command
----------------------
orbRequest ObjectRef [Method ?ArgName1 ArgValue1 ...? | Attribute ?Arg?]

ObjectRef -- must contain a string version of an object reference
which has been returned by CORBA's object_to_string() call.  TclIR
converts this string back to an object reference by calling
string_to_object().  It performs no additional checking on the format
of the string, this is left to the ORB.  NOTE: Orbix 1.3 does not
check the validity of these strings, you will receive a segmentation
violation if they are not in a proper format.

Method -- must contain the name of a method (operation) that ObjectRef
implements.  If you specify a method, then you must specify all arguments
to the method, if any.  The arguments are in the form of name-value pairs
where each name corresponds to the method parameter name and the format for
value is specified below.  As an example, the interface below:

interface grid {
        readonly attribute short height;  // height of the grid
        readonly attribute short width;   // width of the grid
 
        // IDL operations
 
        // set the element [n,m] of the grid, to value:
        void set(in short n, in short m, in long value);
 
        // return element [n,m] of the grid:
        long get(in short n, in short m);
};

You could call the set method by issuing the follow Tcl command

orbRequest $objRef set n 2 m 4 value 123

This is equivalent to the C++ call:

	 objRef->set(2, 4, 123);

Attribute -- must contain the name of an attribute that ObjectRef
implements.  If you specify no additional arguments, then TclIR
assumes this is a get operation on the attribute.  If you specify an
additional argument then this is interpreted to be a set operation and
the argument should be in the correct value format as defined below
for that type of attribute.

Values
------

The following formats should be used for values in the name value pairs
for method calls or as a value to set an attribute.  The format varies
depending on the type.

Numeric types (short, long, double, etc.):

The format is the standard Tcl numeric format for such types.  Example
values are:
	
	long - 32, -900, 0
	double - 32, -900.34234, 3.4e-11

String types:

These should be just standard tcl strings, enclosed in quotes or braces
if they contain spaces.  Example value strings:

	hello
	"Hello World"

Boolean types:

These are the standard Tcl boolean types.  Examples for true and false:

	true - 1, true, on, yes
	false - 0, false, off, no

Structures:

Structures are treated as a tcl list of name value pairs.  An Example
IDL struct:

	struct foo {
		int bar;
		float baz;
	}

	could have a value string of:

	{ bar 3 baz 3.14 }

	Structures can be arbitrarily nested...

	struct bar {
		boolean x;
		foo y; // above structure
	};

	could have a value string of:

	{ x true y { bar 4 baz 54.3224 } }

Sequences:

	Sequences are also treated as Tcl lists.  For example a sequence of
	strings would look like:

		{ "String 1" "String 2" Hello "String 4" }

	A sequence of foos (above structure) would look like:

		{ { bar 2 baz 1.0 } { bar 45 baz 3.14 } }

	Sequences can also be nested arbitrarily.

Object References:

	The value of an object reference is just the stringified version of
	the object reference returned from object_to_string().  In orbix
	they look like:

		:host:srv_name:maker:IR_host:IR_server:obj_interface

	This is described in more detail in the Orbix manual.


Suggestions
-----------

I have only released a portion of our complete CORBA-based TCL system,
because it is the only part that would be of general interest.
However, I find that tclIR by itself is not as powerful as when it is
combined with more powerful commands.

Our systems is built upon a distributed computing infrastructure we
call the Distributed Object Messaging Environment (DOME).  One of the
features of DOME is we support generic object factories.  An object
of any type can be created by giving the implementation class name.
We added a new tcl command, createObject, which works something like this:

createObject ImplementationName InstanceName

This will create an object of type ImplementationName and create a new
Tcl command InstanceName.  InstanceName can now be called as a regular
Tcl command and it will automatically invoke the orbRequest command
with an implicit object reference.  An example using the Orbix grid
example is below:

	createObject grid_i grid

	grid set n 1 m 1 value 33

	puts "height is [grid height]"
	puts "width is [grid width]"
	puts [grid get n 1 m 1]

Notice that the user no longer needs to deal with stringified object
references!  You can do this in your system as well by providing
additional commands that use your own object factories or application
specific mechanisms.

This is done through TclIR's C++ interface:

int TclIRorbRequestCmd(ClientData data, Tcl_Interp *interp,
                       int argc, char *argv[]);

Normally, commands such as orbRequest, invokeMethod, etc., call this command
with a value of null for the client data.  If instead, you give it a pointer
to a stringified object reference when you call Tcl_CreateCommand(), then
this function will not look for the object reference in its argument list
and will instead use the value in the client data.  You can use this feature
to build commands like createObject for your own projects.



