Implicit Arguments

Explicit Arguments

Primitive Data Types

Complex Data Types

T_var Data Types

Implicit Arguments

Explicit Arguments

Table 11.1 Argument types.

Mode	Description
in	Parameter used as input only.
out	Parameter used to hold an output result.
inout	Parameter used both as input and to hold an output result.
return	Result of an operation on an interface.

Primitive Data Types

Table 11.2 Parameter passing modes for primitive data types.

Data type	In	Inout	out	Return
short	Short	Short&	Short&	Short
unsigned short	UShort	UShort&	UShort&	UShort
long	Long	Long&	Long&	Long
unsigned long	ULong	ULong&	ULong&	ULong
float	Float	Float&	Float&	Float
double	Double	Double&	Double&	Double
boolean	Boolean	Boolean&	Boolean&	Boolean
char	Char	Char&	Char&	Char
octet	Octet	Octet&	Octet&	Octet
enum	enum	enum&	enum&	enum

Memory Management

Table 11.3 Memory management rules for primitive data types.

Mode	Description
in	The caller allocates the necessary storage and initializes it. The callee uses the value.
out	The caller allocates the necessary storage, but need not initialize it. The callee must set the value.
inout	The caller allocates the necessary storage and initializes it. The callee may change the value.
return	The callee initializes and returns the data by value. The caller receives the value.

Complex Data Types

Table 11.4 Parameter passing modes for complex data types.

Data Type	In	Inout	out	Return
object reference pointer	objref_ptr	objref_ptr &	objref_ptr &	objref_ptr
struct, fixed length	const struct &	struct &	struct &	struct
struct, variable length	const struct &	struct &	struct *&	struct *
union, fixed length	const union &	union &	union &	union
union, variable length	const union &	union &	union *&	union *
string	const char *	char *&	char *&	char *
sequence	const sequence &	sequence &	sequence *&	sequence *
array, fixed length	const array	array	array	array slice *
array, variable length	const array	array	array slice *&	array slice *
any	const any &	any &	any *&	any *

Memory Management

Object Reference Pointers

Table 11.5 Memory management rules for object reference pointers.

Mode	Description
in	The caller allocates the necessary storage for the object reference and is responsible for freeing it when finished. The caller receives the parameter from the ORB and cannot modify it. The memory associated with the parameter is freed by the ORB upon returning. The callee can preserve the object reference by invoking the _duplicate method.
out	The caller allocates the necessary storage, but need not initialize it. Once the method returns, the storage will hold an object reference and the caller is responsible for releasing it when finished. On the server side, the ORB allocates the memory and the callee must provide the object reference. Once the data has been sent to the client, the ORB invokes the _release method on the reference to decrement its reference count.
inout	The caller allocates the necessary storage and initializes it. If the callee modifies the object reference, the ORB will release the old object and assign it a new value. If the caller wants to continue to use the object reference, it must invoke the _duplicate method prior to passing it to the callee. On the server side, the ORB will allocate memory for the reference. If the callee wishes to assign a new value to the object reference, it must first invoke the _release method.
return	On the server side, the callee initializes and returns the object reference. The ORB will invoke _release on the object reference once it has been returned to the caller. The caller receives the object reference and is responsible for releasing it.

Fixed Structures and Unions

Table 11.6 Memory management rules for fixed-length structures and unions.

Mode	Description
in	The caller allocates the necessary storage for the structure and is responsible for freeing it when finished. The callee receives the parameter from the ORB and cannot modify it. The memory associated with the parameter is freed by the ORB upon returning. The callee can preserve the structure by copying it.
out	The caller allocates the necessary storage, but need not initialize it. Once the method returns, the storage will hold the structure and the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates the memory and the callee must set the value. Once the data has been sent to the client, the ORB releases the memory.
inout	The caller allocates the necessary storage and initializes it. Upon return, the caller must release the memory. On the server side, the ORB will allocate memory for the structure. The callee may assign a new value to the structure. Once the structure is returned to the client, the ORB releases the memory.
return	On the server side, the callee initializes and returns the data by value. The caller receives the structure by value.

Variable Structures and Unions

Table 11.7 Memory management rules for variable-length structures and unions.

Mode	Description
in	The caller allocates the necessary storage for the structure and is responsible for freeing it when finished. The callee receives the parameter from the ORB and cannot modify it. The memory associated with the parameter is freed by the ORB upon returning. The callee can preserve the structure by copying it.
out	The caller allocates a pointer and passes it by reference to the ORB. Once the method returns, the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates a pointer and passes it by reference to the callee. The callee sets the pointer to a valid instance of the parameter's type. If the callee wishes to keep the data buffer, it is must make a copy.
inout	The caller allocates the necessary storage and initializes it. Upon return, the caller must release the memory. On the server side, the ORB will allocate memory for the structure. If the callee wishes to change the value, it must first release the old data prior to assigning it a new value. Once the data is returned to the client, the ORB releases the memory.
return	On the server side, the callee returns to the ORB a pointer to the data buffer. The ORB will free the memory upon returning. The client cannot return a NULL pointer. The caller receives a pointer to the structure or union. If the caller wishes to modify any of the values, it must make a copy of the structure or union and modify the copy. The caller is responsible for releasing the memory.

Strings

Table 11.8 Memory management rules for strings.

Mode	Description
in	The caller allocates the necessary storage for the string and is responsible for freeing it when finished. The callee receives the parameter from the ORB and cannot modify it. The memory associated with the parameter is freed by the ORB upon returning. The callee can preserve the string by copying it.
out	The caller allocates a pointer and passes it by reference to the ORB. Once the method returns, the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates a pointer and passes it by reference to the callee. The callee sets the pointer to a valid instance of the parameter's type. If the callee wishes to keep the data buffer, it is must make a copy. The callee is not allowed to return a NULL pointer.
inout	The caller allocates the necessary storage for both input string the char * pointing to it. Upon return, the caller must release the memory using the string_free method. The ORB will delete the old buffer and allocate a new buffer for the out parameter. The size of the output string may be larger that the input string. On the server side, the ORB will allocate memory for the string. To return a new string, the callee must free the old memory using string_free and allocate new storage using the string_alloc method. Once the data is returned to the client, the ORB releases the memory. The callee may not return a NULL pointer.
return	On the server side, the callee returns to the ORB a pointer to the data buffer. The buffer must have been allocated using string_alloc. The ORB will free the memory upon returning. The client cannot return a NULL pointer. The caller receives a char * pointer to the string. If the caller wishes to modify any of the values, it must make a copy of the string and modify the copy. The caller is responsible for releasing the memory using string_free.

Sequences and Type-safe Arrays

Table 11.9 Memory management rules for sequences and any arrays.

Mode	Description
in	The caller allocates the necessary storage for the structure and is responsible for freeing it when finished. The callee receives the parameter from the ORB and cannot modify it. The memory associated with the parameter is freed by the ORB upon returning. The callee can preserve the data buffer by copying it or increasing the object's reference count.
out	The caller allocates a pointer and passes it by reference to the ORB. Once the method returns, the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates a pointer and passes it by reference to the callee. The callee sets the pointer to a valid instance of the parameter's type. If the callee wishes to keep the data buffer, it is must make a copy or increase the object's reference count.
inout	The caller allocates the sequence or any and initializes it. The ORB may free the old buffer and allocate a new buffer for the output parameter., depending on the state of the boolean release parameter used to construct the object. Upon return, the caller must release the memory. On the server side, the ORB will allocate memory for the structure. The callee may free the old buffer and allocate a new buffer, depending on the state of the boolean release parameter used to construct the object. Once the data is returned to the client, the ORB releases the memory.
return	On the server side, the callee returns to the ORB a pointer to the sequence or any. The ORB will free the memory upon returning. The client cannot return a NULL pointer. The caller receives a pointer to the sequence or any. If the caller wishes to modify any of the values, it must make a copy of the object and modify the copy. The caller is responsible for releasing the returned object's memory.

Fixed Arrays

Table 11.10 Memory management rules for fixed-length arrays.

Mode	Description
in	The caller allocates the necessary storage for the array and is responsible for freeing it when finished. The callee receives the array from the ORB and cannot modify it. The memory associated with the array is freed by the ORB upon returning. The callee can preserve the array by copying it.
out	The caller allocates the necessary storage, but need not initialize it. Once the method returns, the storage will hold the array and the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates the memory and the callee initializes the array. Once the array has been sent to the client, the ORB releases the memory.
inout	The caller allocates the necessary storage and initializes it. Upon return, the caller must release the memory. On the server side, the ORB will allocate memory for the array. The callee may the elements in the array. Once the array has been returned to the client, the ORB releases the memory.
return	On the server side, the callee returns a pointer to the array slice. The callee may not return a NULL pointer. The caller receives a pointer to the array slice, but may not modify it. If the caller wishes to modify any of the elements, it must make a copy of the array slice and modify the copy. The caller is responsible for releasing the returned array slice's memory.

Variable-Length Arrays

Table 11.11 Memory management rules for variable-length arrays.

Mode	Description
in	The caller allocates the necessary storage for the array and initializes it. The caller is responsible for freeing the memory when finished. The callee receives the parameter from the ORB and cannot modify it. The memory associated with the parameter is freed by the ORB upon returning. The callee can preserve the array by copying it.
out	The caller allocates a pointer to an array slice and passes it by reference to the ORB. Once the method returns, the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates a pointer to an array slice and passes it by reference to the callee. The callee sets the pointer to a valid instance of an array. Once the data is returned, the ORB will free the storage. The callee is not allowed to return a NULL pointer.
inout	The caller allocates the array and initializes it. Upon return, the caller must release the memory. On the server side, the ORB will allocate memory for the array. The callee may modify elements of the array. Once the data is returned to the client, the ORB releases the memory.
return	On the server side, the callee returns to the ORB a pointer to an array slice. The ORB will free the memory upon returning. The client cannot return a NULL pointer. The caller receives a pointer to the array slice. If the caller wishes to modify any of the elements, it must make a copy of the array and modify the copy. The caller is responsible for releasing the memory.

T_var Data Types

Table 11.12 Parameter passing modes for T_var types.

Data type	In	Inout	out	Return
object ref var	const objref_var&	objref_var&	objref_var&\Q	objref_var
struct_var	const struct_var&	struct_var&	struct_var&	struct_var
union_var	const union_var&	union_var&	union_var&	union_var
string_var	const string_var&	string_var&	string_var&	string_var
sequence_var	const sequence_var&	sequence_var&	sequence_var&	sequence_var
array_var	const array_var&	array_var&	array_var&	array_var
any_var	const any_var&	any_var&	any_var&	any_var

Memory Management for T_var Types

Table 11.13 Memory management rules for T_var Types.

Mode	Description
in	The caller allocates the necessary storage for the object and is responsible for freeing it when finished. The callee receives the object from the ORB and cannot modify it. The memory associated with the object is freed by the ORB upon returning. The callee can preserve the object by copying it or increasing the object's reference count.
out	The caller allocates a pointer and passes it by reference to the ORB. Once the method returns, the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates a pointer and passes it by reference to the callee. The callee sets the pointer to a valid instance of the parameter's type. If the callee wishes to preserve the object, it is must make a copy or increase the object's reference count.
inout	The caller allocates the sequence or any and initializes it. Upon return, the caller must release the memory. On the server side, the ORB will allocate memory for the object. Once the data is returned to the client, the ORB releases the memory. If the callee wishes to preserve the object, it is must make a copy or increase the object's reference count.
return	On the server side, the callee returns to the ORB a pointer to the object. The ORB will free the memory upon returning. The client cannot return a NULL pointer. The caller receives a pointer to the object. The caller is responsible for releasing the returned object's memory.

Last Updated: 02/03/98 15:34:31