Reference Class

A Reference object simply holds a reference to another object. Its use is primarily to inform a COM method to pass the contents of the reference by reference rather than by value.

When passing a Reference as argument to a function using COM, the contents of the Reference may be changed by the function call. However, it is only the contents of the Reference which is changed and not the item which was originally held within the Reference.

For instance, suppose we have a COM object with a single method double. The action of double is to double its integer argument, where this argument is supplied by reference. The following Carapace script function test shows that the Reference passed into double is modified, but that the original variable being referenced is unchanged.

    (defun NIL test ( (obj Dispatch) )
    
        (local  (a Integer)
                (r Reference)
        )
        
        (set a 100)
        (set r (create Reference a)) 

        (printAux "Before: a=" a ", r holds " r.contents "\n")

        # double the value
        (obj.double r)

        (printAux "After:  a=" a ", r holds " r.contents "\n")
    )

   Before: a=100, r holds 100
   After:  a=100, r holds 200

Reference Creation

The create function can be used to create a reference:

    (create Reference obj)

Reference Properties

Reference Methods

contentType

Return the type of the object within the reference.

Arguments: none

Return type: a String holding the type name.