The following topics contain important information that must be kept in mind when passing objects, arrays and variables between IDL and an external programming environment:
Object Reference Use
It is possible to pass an object reference to another wrapper object as a method parameter, with the following restrictions.
- The object reference must be a reference to another Export Bridge wrapper object instance of the same wrapper language type (COM or Java). That is, COM to COM or Java to Java
- You cannot pass in object references to non-Export Bridge wrapper objects
- The object reference is “in-only,” meaning that methods and properties cannot return or modify a reference to an object
- Both objects (the object being referred to and the object using the reference) must have their underlying IDL objects contained within the same IDL process.
For example, using the diagram in IDL Access, wrapper object A can have a method that takes an object reference. But the only valid object reference that can be specified is to an instance of wrapper object B, since both have their underlying IDL objects living in the same process, X.
If you attempt to pass in an object reference to an IDL object contained in different processes, the method call returns an error. An error is also returned if you attempt to pass in an object reference that does not reference an instance of an Export Bridge wrapper object.
Arrays of Object References
You can also create an array of object references as long as all the objects being referenced are in the same IDL process as the object using the array.
When creating an array of object references for COM, it must be defined as a SAFEARRAY of variants, with each variant containing the IUknown or IDispatch pointer to a COM wrapper object instance.
When creating an array of object references for Java, it must be defined as a JIDLArray containing an array of JIDLObjectI references.
Array Order Conversion
A method parameter or property value can be an array. When working with multidimensional arrays, it is best to know the array ordering. See Multidimensional Array Storage and Access for details.
However, you must take into account the array ordering of the client-side array and the array order expected by IDL. The wrapper objects will convert array ordering when designated to do so in the Export Bridge Assistant. During wrapper object construction, the Export Bridge Assistant lets you designate a method parameter as an array and then indicate if the array needs to be converted (see Converting Array Majority for details). If the array parameter is marked for conversion, the client array is converted during the method call before being sent to the underlying IDL object. If the parameter is also marked with In/Out mutability (meaning that the parameter is not constant and can be set by the caller and pass the value back to the caller), the array is also converted on the way back to the client. For more information on mutability, see Parameter Information.
However, there are certain cases where arrays are automatically converted and the user does not have the option to designate conversion. When calling the GetIdlVariable and SetIdlVariable methods on a wrapper object, or when an IDL function returns an array value, the array is always converted into the order expected by COM. (For Java, the user has the option to designate conversion.)
IDL is a dynamically typed language that lets variables change type after creation. Java and COM are strongly typed languages, which require a variable to be given a fixed type when it is created. This difference can lead to type-conversion errors during method calls because the IDL object can redefine the data type of a parameter. When a method parameter is marked In/Out, the updated parameter value is returned to the client upon return of the method. During the method return, the wrapper compares the data type of the input value against the data type of the output value.
The wrapper will perform a loose type conversion in which:
- Any scalar type can be converted to any other scalar type (e.g., a short integer to a long integer)
- A scalar string to a scalar string (e.g., a string of one length to a different length)
- An array to an array (e.g., any dimensionality and type to any other dimensionality and type)
Loose type conversion attempts to convert the variables returned by the wrapped IDL object to the types expected by the wrapper object.
A data conversion error is returned when the above rules are not met. For example:
- A scalar changes to a string
- A scalar changes to an array
- A string changes to a scalar
- A string changes to an array
- An array changes to a scalar
- An array changes to a string
See Supported Data Types for data types supported by COM and Java.
IDL Error State and Successful Method Return
If your client creates an instance of a COM/Java Export Bridge wrapper object, and calls an object method whose code throws an error, the wrapped method will return an error unless the referenced code resets the internal IDL error state.
In this circumstance, it is best if the wrapped code catches its own error, handles it, and resets the IDL error state. You can reset the IDL error state in the error handling catch block by calling the MESSAGE procedure:
This procedure call sets the !ERROR_STATE system variable back to the “success” state.