		BEA WebLogic Enterprise 4.2 Developer Center
		HOME \| SITE MAP \| SEARCH \| CONTACT \| GLOSSARY \| PDF FILES \| WHAT'S NEW
		C++ REFERENCE \| TABLE OF CONTENTS \| PREVIOUS TOPIC \| NEXT TOPIC

CORBA API

This chapter describes the BEA WLE implementation of the CORBA core member functions in C++ and their extensions. It also describes pseudo-objects and their relationship to C++ classes. Pseudo-objects are object references that cannot be transmitted across the network. Pseudo-objects are similar to other objects; however, because the ORB owns them, they cannot be extended.

Note: Some of the information in this chapter is taken from Chapter 20 of the Common Object Request Broker: Architecture and Specification. Revision 2.2, February 1998, published by the Object Management Group (OMG). Used with permission by OMG.

Global Classes

The following WLE classes are global in scope:

CORBA
Tobj

These classes contain the predefined types, classes, and functions used in WLE development.

The CORBA class contains the classes, data types, and member functions essential to using an Object Request Broker (ORB) as defined by CORBA. The WLE extensions to CORBA are contained in the Tobj C++ class. The Tobj class contains data types, nested classes, and member functions that WLE provides as an extension to CORBA.

Using CORBA data types and member functions in the WLE product requires the CORBA:: prefix. For example, a Long is a CORBA::Long. Likewise, to use Tobj nested classes and member functions in the WLE product, you need the Tobj:: prefix. For example, FactoryFinder is Tobj::FactoryFinder.

Pseudo-objects

Pseudo-objects are represented as local classes, which reside in the CORBA class. A pseudo-object and its corresponding member functions are named using a nested class structure. For example, an ORB object is a CORBA::ORB and a Current object is a CORBA::Current.

Any Class Member Functions

This section describes the member functions of the Any class.

The mapping of these member functions to C++ is as follows:

class CORBA { class Any { public:

}; }; //CORBA

CORBA::Any::Any()

Synopsis

Constructs the Any object.
C++ Binding

CORBA::Any::Any()
Arguments

None.
Description

This is the default constructor for the CORBA::Any class. It creates an Any object with a TypeCode of type tc_null and a value of 0 (zero).
Return Values

None.

CORBA::Any::Any(const CORBA::Any & InitAny)

Synopsis

Constructs the Any object that is a copy of another Any object.
C++ Binding

CORBA::Any::Any(const CORBA::Any & InitAny)
Argument

InitAny
Refers to the CORBA::Any to copy.

Description

This is the copy constructor for the CORBA::Any class. This constructor duplicates the TypeCode reference of the Any that is passed in.
The type of copying to be performed is determined by the release flag of the Any object to be copied. If release evaluates as CORBA_TRUE, the constructor deep-copies the parameter's value; if release evaluates as CORBA_FALSE, the constructor shallow-copies the parameter's value. Using a shallow copy gives you more control to optimize memory allocation, but the caller must ensure the Any does not use memory that has been freed.
Return Values

None.

CORBA::Any::Any(TypeCode_ptr TC, void * Value, Boolean Release)

Synopsis

Creates the Any object using a TypeCode and a value.
C++ Binding

CORBA::Any::Any(TypeCode_ptr TC, void * Value, Boolean Release)
Arguments

A pointer to a TypeCode pseudo-object reference, specifying the type to be created.

Value
A pointer to the data to be used to create the Any object. The data type of this argument must match the TypeCode specified.

Determines whether the Any assumes ownership of the memory specified by the Value argument. If Release is CORBA_TRUE, the Any assumes ownership. If Release is CORBA_FALSE, the Any does not assume ownership; the data pointed to by the Value argument is not released upon assignment or destruction.

Description

This constructor is used with the nontype-safe Any interface. It duplicates the specified TypeCode object reference and then inserts the data pointed to by value inside the
Any object.
Return Values

None.

CORBA::Any::~Any()

Synopsis

Destructor for the Any.
C++ Binding

CORBA::Any::~Any()
Arguments

None.
Description

This destructor frees the memory that the CORBA::Any holds (if the Release flag is specified as CORBA_TRUE), and releases the TypeCode pseudo-object reference contained in the Any.
Return Values

None.

CORBA::Any & CORBA::Any::operator=(const CORBA::Any & InitAny)

Synopsis

Any assignment operator.
C++ Binding

CORBA::Any & CORBA::Any::operator=(const CORBA::Any & InitAny)
Arguments

InitAny
A reference to an Any to use in the assignment. The Any to use in the assignment determines whether the Any assumes ownership of the memory in Value. If Release is CORBA_TRUE, the Any assumes ownership and deep-copies the InitAny argument's value; if Release is CORBA_FALSE, the Any shallow-copies the InitAny argument's value.

Description

This is the assignment operator for the Any class. Memory management of this member function is determined by the current value of the Release flag. The current value of the Release flag determines whether the current memory is released before the assignment. If the current Release flag is CORBA_TRUE, the Any releases any value previously held; if the current Release flag is CORBA_FALSE, the Any does not release any value previously held.
Return Values

Returns the Any, which holds the copy of the InitAny.

void CORBA::any::operator<<=()

Synopsis

Type safe Any insertion operators.
C++ Binding

void CORBA::Any::operator<<=(CORBA::Short Value) void CORBA::Any::operator<<=(CORBA::UShort Value) void CORBA::Any::operator<<=(CORBA::Long Value) void CORBA::Any::operator<<=(CORBA::Ulong Value) void CORBA::Any::operator<<=(CORBA::Float Value) void CORBA::Any::operator<<=(CORBA::Double Value) void CORBA::Any::operator<<=(const CORBA::Any & Value) void CORBA::Any::operator<<=(const char * Value) void CORBA::Any::operator<<=(Object_ptr Value)
Argument

Value
Type specific value to be inserted into the Any.

Description

This insertion member function performs type-safe insertions. If the Any had a previous value, and the release flag is CORBA_TRUE, the memory is deallocated and the previous TypeCode object reference is freed. The new value is inserted into the Any by copying the value passed in using the Value parameter. The appropriate TypeCode reference is duplicated.
Return Values

None.

CORBA::Boolean CORBA::Any::operator>>=()

Synopsis

Type safe Any extraction operators.
C++ Binding

CORBA::Boolean CORBA::Any::operator>>=( CORBA::Short & Value) const CORBA::Boolean CORBA::Any::operator>>=( CORBA::UShort & Value) const CORBA::Boolean CORBA::Any::operator>>=( CORBA::Long & Value) const CORBA::Boolean CORBA::Any::operator>>=( CORBA::Ulong & Value) const CORBA::Boolean CORBA::Any::operator>>=( CORBA::Float & Value) const CORBA::Boolean CORBA::Any::operator>>=( CORBA::Double & Value) const CORBA::Boolean CORBA::Any::operator>>=(CORBA::Any & Value) const CORBA::Boolean CORBA::Any::operator>>=(char * & Value) const CORBA::Boolean CORBA::Any::operator>>=(Object_ptr & Value) const
Argument

The Value argument is a reference to the relevant object that receives the output of the value contained in the Any object.
Description

This extraction member function performs type-safe extractions. If the Any object contains the specified type, this member function assigns the pointer of the Any to the output reference value, Value, and CORBA_TRUE is returned. If the Any does not contain the appropriate type, CORBA_FALSE is returned. The caller must not attempt to release or delete the storage because it is owned and managed by the Any object. The Value argument is a reference to the relevant object that receives the output of the value contained in the Any object. If the Any object does not contain the appropriate type, the value remains unchanged.
Return Values

CORBA_TRUE if the Any contained a value of the specific type. CORBA_FALSE if the Any did not contain a value of the specific type.

CORBA::Any::operator<<=()

Synopsis

Type safe insertion operators for Any.
C++ Binding

void CORBA::Any::operator<<=(from_boolean Value) void CORBA::Any::operator<<=(from_char Value) void CORBA::Any::operator<<=(from_octet Value) void CORBA::Any::operator<<=(from_string Value)
Argument

Value
A relevant object that contains the value to insert into the Any.

Description

These insertion member functions perform a type-safe insertion of a CORBA::Boolean, a CORBA::Char, or a CORBA::Octet reference into an Any. If the Any had a previous value, and its Release flag is CORBA_TRUE, the memory is deallocated and the previous TypeCode object reference is freed. The new value is inserted into the Any object by copying the value passed in using the Value parameter. The appropriate TypeCode reference is duplicated.
Return Values

None.

CORBA::Boolean CORBA::Any::operator>>=()

Synopsis

Type-safe extraction operators for Any.
C++ Binding

CORBA::Boolean CORBA::Any::operator>>=(to_boolean Value) const CORBA::Boolean CORBA::Any::operator>>=(to_char Value) const CORBA::Boolean CORBA::Any::operator>>=(to_octet Value) const CORBA::Boolean CORBA::Any::operator>>=(to_object Value) const CORBA::Boolean CORBA::Any::operator>>=(to_string Value) const
Argument

Value
A reference to the relevant object that receives the output of the value contained in the Any object. If the Any object does not contain the appropriate type, the value remains unchanged.

Description

These extraction member functions perform a type-safe extraction of a CORBA::Boolean, a CORBA::Char, a CORBA::Octet, a CORBA::Object, or a String reference from an Any. These member functions are helpers nested in the Any class. Their purpose is to distinguish extractions of the OMG IDL types: boolean, char, and octet (C++ does not require these to be distinct types).
Return Values

If the Any contains the specified type, this member function assigns the value in the Any object reference to the output variable, Value, and returns CORBA_TRUE. If the Any object does not contain the appropriate type, CORBA_FALSE is returned.

CORBA::TypeCode_ptr CORBA::Any::type() const

Synopsis

TypeCode accessor for Any.
C++ Binding

CORBA::TypeCode_ptr CORBA::Any::type();

Arguments

None.
Description

This function returns the TypeCode_ptr pseudo-object reference of the TypeCode object associated with the Any. The TypeCode_ptr pseudo-object reference must be released by the CORBA::release member function or must be assigned to a TypeCode_var to be automatically released.
Return Values

TypeCode_ptr contained in the Any.

void CORBA::Any::replace()

Synopsis

Non-type safe Any "insertion."
C++ Binding

void CORBA::Any::replace(TypeCode_ptr TC, void * Value, Boolean Release = CORBA_FALSE);
Arguments

TC
A TypeCode pseudo-object reference specifying the TypeCode value for the replaced Any object. This argument is duplicated.
Value
A void pointer specifying the storage pointed to by the Any object.
Release
Determines whether the Any manages the specified Value argument. If Release is CORBA_TRUE, the Any assumes ownership. If Release is CORBA_FALSE, the Any does not assume ownership and the data pointed to by the Value parameter is not released upon assignment or destruction.

Description

These member functions replace the data and TypeCode value currently contained in the Any with the value of the TC and Value arguments passed in. The functions perform a nontype-safe replacement, which means that the caller is responsible for consistency between the TypeCode value and the data type of the storage pointed to by the Value argument.
If the value of Release is CORBA_TRUE, this function releases the existing TypeCode pseudo-object in the Any object and frees the storage pointed to be the Any object reference.
Return Values

None.
Context Member Functions

A Context supplies optional context information associated with a method invocation.
The mapping of these member functions to C++ is as follows:
class CORBA { class Context { public: const char *context_name() const; Context_ptr parent() const; void create_child(const char *, Context_out); void set_one_value(const char *, const Any &); void set_values(NVList_ptr); void delete_values(const char *); void get_values( const char *, Flags, const char *, NVList_out ); }; // Context }// CORBA
Memory Management

Context has the following special memory management rule:

Ownership of the return values of the context_name and parent functions is maintained by the Context; these return values must not be freed by the caller.

This section describes Context member functions.

CORBA::Context::context_name

Synopsis

Returns the name of a given Context object.
C++ Binding

Const char * CORBA::Context::context_name () const;
Arguments

None.

Description

This member function returns the name of a given Context object. The Context object reference owns the memory for the returned char *. Users should not modify this memory.
Return Values

If the member function succeeds, it returns the name of the Context object. The value may be empty if the Context object is not a child Context created by a call to CORBA::Context::create_child.
If the Context object has no name, this is an empty string.

CORBA::Context::create_child

Synopsis

Creates a child of the Context object.
C++ Binding

void CORBA::Context::create_child ( const char * CtxName, CORBA::Context_out CtxObject);
Arguments

CtxName
The name to be associated with the child of the Context reference.
CtxObject
The newly created Context object reference.

Description

This member function creates a child of the Context object. That is, searches on the child Context object will look for matching property names in the parent context (and so on, up the context tree), if necessary.
Return Values

None.
Exception

CORBA::NO_MEMORY
See Also

CORBA::ORB::get_default_context
CORBA::release

CORBA::Context::delete_values

Synopsis

Deletes the values for a specified attribute in the Context object.
C++ Binding

void CORBA::Context::delete_values ( const char * AttrName);
Argument

AttrName
The name of the attribute whose values are to be deleted. If this argument has a trailing wildcard character (*), all names that match the string preceding the wildcard character are deleted.

Description

This member function deletes named values for an attribute in the Context object. Note that it does not do recursively do the same to its parents, if any.
Return Values

None.
Exceptions

CORBA::BAD_PARAM if attribute is an empty string.
CORBA::BAD_CONTEXT if no matching attributes to be deleted were found.
See Also

CORBA::Context::create_child
CORBA::ORB::get_default_context

CORBA::Context::get_values

Synopsis

Retrieves the values for a given attribute in the Context object within the specified scope.
C++ Binding

void CORBA::Context::get_values ( const char * StartScope, CORBA::Flags OpFlags, const char * AttrName, CORBA::NVList_out AttrValues);
Arguments

StartScope
The Context object level at which to initiate the search for specified properties. The level is the name of the context, or parent, at which the search is started. If the value is 0 (zero), the search begins with the current Context object.
OpFlags
The only valid operation flag is CORBA::CTX_RESTRICT_SCOPE. If you specify this flag, the object implementation restricts the property search to the current scope only (that is, the property search is not executed recursively up the chain of the parent context); otherwise, the search continues to a wider scope until a match has been found or until all wider levels have been searched.
AttrName
The name of the attribute whose values are to be returned. If this argument has a trailing wildcard character (*), all names that match the string preceding the wildcard character are returned.
AttrValues
Receives the values for the specified attributes (returns an NVList object) where each item in the list is a NamedValue.

Description

This member function retrieves the values for a specified attribute in the Context object. These values are returned as an NVList object, which must be freed when no longer needed using the CORBA::release member function.
Return Values

None.
Exceptions

CORBA::BAD_PARAM if attribute is an empty string.
CORBA::BAD_CONTEXT if no matching attributes were found.
CORBA::NO_MEMORY if dynamic memory allocation failed.
See Also

CORBA::Context::create_child CORBA::ORB::get_default_context

CORBA::Context::parent

Synopsis

Returns the parent context of the Context object.
C++ Binding

CORBA::Context_ptr CORBA::Context::parent () const;

Arguments

None.
Description

This member function returns the parent context of the Context object. The parent of the Context object is an attribute owned by the Context and should not be modified or freed by the caller. This parent is nil unless the Context object was created using the CORBA::Context::create_child member function.
Return Values

If the member function succeeds, the parent context of the Context object is returned. The parent context may be nil. Use the CORBA::is_nil member function to test for a nil object reference.
If the member function does not succeed, an exception is thrown. Use the CORBA::is_nil member function to test for a nil object reference.

CORBA::Context::set_one_value

Synopsis

Sets the value for a given attribute in the Context object.
C++ Binding

void CORBA::Context::set_one_value ( const char * AttrName, const CORBA::Any & AttrValue);
Arguments

AttrName
The name of the attribute to set.
AttrValue
The value of the attribute. Currently, the WLE system supports only the string type; therefore, this parameter must contain a CORBA::Any object with a string inside.

Description

This member function sets the value for a given attribute in the Context object. Currently, only string values are supported by the Context object. If the Context object already has an attribute with the given name, it is deleted first.
Return Values

None.
Exceptions

CORBA::BAD_PARAM if AttrName is an empty string or AttrValue does not contain a string type.
CORBA::NO_MEMORY if dynamic memory allocation failed.
See Also

CORBA::Context::get_values CORBA::Context::set_values

CORBA::Context::set_values

Synopsis

Sets the values for given attributes in the Context object.
C++ Binding

void CORBA::Context::set_values (
CORBA::NVList_ptr AttrValue);
Argument

AttrValues
The name and value of the attribute. Currently the WLE system supports only the string type; therefore, all NamedValue objects in the list must have CORBA::Any objects with a string inside.

Description

This member function sets the values for given attributes in the Context object. The CORBA::NVList member function contains the property name and value pairs to be set.
Return Values

None.
Exceptions

CORBA::BAD_PARAM if any of the attribute values has a value that is not a string type.
CORBA::NO_MEMORY if dynamic memory allocation failed.
See Also

CORBA::Context::get_values CORBA::Context::set_one_value

ContextList Member Functions

The ContextList allows a client or server application to provide a list of context strings that must be supplied with Request invocation. For a description of the Request member functions, see the section "Request Member Functions" on page 12-112.
The ContextList differs from the Context in that the former supplies only the context strings whose values are to be looked up and sent with the request invocation (if applicable), while the latter is where those values are obtained. For a description of the Context member functions, see the section "Context Member Functions" on page 12-15.
The mapping of these member functions to C++ is as follows:
class CORBA { class ContextList { public: Ulong count (); void add(const char* ctxt); void add_consume(char* ctxt); const char* item(Ulong index); Status remove(Ulong index); }; // ContextList }// CORBA

CORBA::ContextList:: count

Synopsis

Retrieves the current number of items in the list.
C++ Binding

Ulong count ();

Arguments

None.
Description

This member function retrieves the current number of items in the list.
Return Values

If the function succeeds, the returned value is the number of items in the list. If the list has just been created, and no ContextList objects have been added, this function returns 0 (zero).
Exception

If the function does not succeed, an exception is thrown.
See Also

CORBA::ContextList::add
CORBA::ContextList::add_consume
CORBA::ContextList::item
CORBA::ContextList::remove

CORBA::ContextList::add

Synopsis

Constructs a ContextList object with an unnamed item, setting only the flags attribute.
C++ Binding

void add(const char* ctxt);

Argument

ctxt
Defines the memory location referred to by char*.

Description

This member function constructs a ContextList object with an unnamed item, setting only the flags attribute.
The ContextList object grows dynamically; your application does not need to track its size.
Return Values

If the function succeeds, the return value is a pointer to the newly created ContextList object.
Exception

If the member function does not succeed, a CORBA::NO_MEMORY exception is thrown.
See Also

CORBA::ContextList::add_consume
CORBA::ContextList::count
CORBA::ContextList::item
CORBA::ContextList::remove

CORBA::ContextList::add_consume

Synopsis

Constructs a ContextList object.
C++ Binding

void add_consume(const char* ctxt);
Argument

ctxt
Defines the memory location referred to by char*.

Description

This member function constructs a ContextList object.
The ContextList object grows dynamically; your application does not need to track its size.
Return Values

If the function succeeds, the return value is a pointer to the newly created ContextList object.
Exception

If the member function does not succeed, an exception is raised.
See Also

CORBA::ContextList::add
CORBA::ContextList::count
CORBA::ContextList::item
CORBA::ContextList::remove

CORBA::ContextList::item

Synopsis

Retrieves a pointer to the ContextList object, based on the index passed in.
C++ Binding

const char* item(ULong index);
Argument

index
The index into the ContextList object. The indexing is zero-based.

Description

This member function retrieves a pointer to a ContextList object, based on the index passed in. The function uses zero-based indexing.
Return Values

If the function succeeds, the return value is a pointer to the ContextList object.
Exceptions

If this function does not succeed, the BAD_PARAM exception is thrown.
See Also

CORBA::ContextList::add
CORBA::ContextList::add_consume
CORBA::ContextList::count
CORBA::ContextList::remove

CORBA::ContextList::remove

Synopsis

Removes the item at the specified index, frees any associated memory, and reorders the remaining items on the list.
C++ Binding

Status remove(ULong index);
Argument

Index
The index into the ContextList object. The indexing is zero-based.

Description

This member function removes the item at the specified index, frees any associated memory, and reorders the remaining items on the list.
Return Values

None.
Exceptions

If this function does not succeed, the BAD_PARAM exception is thrown.
See Also

CORBA::ContextList::add
CORBA::ContextList::add_consume
CORBA::ContextList::count
CORBA::ContextList::item

NamedValue Member Functions

NamedValue is used only as an element of NVList, especially in the DII. NamedValue maintains an (optional) name, an any value, and labelling flags. Legal flag values are CORBA::ARG_IN, CORBA::ARG_OUT, and CORBA::ARG_INOUT.
The value in a NamedValue may be manipulated via standard operations on any.
The mapping of these member functions to C++ is as follows:
// C++ class NamedValue { public: Flags flags() const; const char * name() const; Any * value() const; };
Memory Management

NamedValue has the following special memory management rule:

Ownership of the return values of the name() and value() functions is maintained by the NamedValue; these return values must not be freed by the caller.

The following sections describe NamedValue member functions.

CORBA::NamedValue::flags

Synopsis

Retrieves the flags attribute of the NamedValue object.
C++ Binding

CORBA::Flags CORBA::NamedValue::flags () const;

Arguments

None.

Description

This member function retrieves the flags attribute of the NamedValue object.
Return Values

If the function succeeds, the return value is the flags attribute of the NamedValue object.
If the function does not succeed, an exception is thrown.

CORBA::NamedValue::name

Synopsis

Retrieves the name attribute of the NamedValue object.
C++ Binding

const char * CORBA::NamedValue::name () const;

Arguments

None.

Description

This member function retrieves the name attribute of the NamedValue object. The name returned by this member function is owned by the NamedValue object and should not be modified or released.
Return Values

If the function succeeds, the value returned is a constant Identifier object representing the name attribute of the NamedValue object.
If the function does not succeed, an exception is thrown.

CORBA::NamedValue::value

Synopsis

Retrieves a pointer to the value attribute of the NamedValue object.
C++ Binding

CORBA::Any * CORBA::NamedValue::value () const;

Arguments

None.

Description

This member function retrieves a pointer to the Any object that represents the value attribute of the NamedValue object. This attribute is owned by the NamedValue object, and should not be modified or released.
Return Values

If the function succeeds, the return value is a pointer to the Any object contained in the NamedValue object.
If the function does not succeed, an exception is thrown.
NVList Member Functions

NVList is a list of NamedValues. A new NVList is constructed using the ORB::create_list operation (see "CORBA::ORB::create_list" on page 12-61). New NamedValues may be constructed as part of an NVList, in any of following ways:

add-creates an unnamed value, initializing only the flags

add_item-initializes name and flags

add_value-initializes name, value, and flags

Each of these operations returns the new item.
Elements may be accessed and deleted via zero-based indexing. The add, add_item, add_value, add_item_consume, and add_value_consume functions lengthen the NVList to hold the new element each time they are called. The item function can be used to access existing elements.
// C++ class NVList { public: ULong count() const; NamedValue_ptr add(Flags); NamedValue_ptr add_item(const char*, Flags); NamedValue_ptr add_value(const char*, const Any&, Flags); NamedValue_ptr item(ULong); void remove(ULong); };
Memory Management

NVList has the following special memory management rules:

Ownership of the return values of the add, add_item, add_value, add_item_consume, add_value_consume, and item functions is maintained by the NVList; these return values must not be freed by the caller.

The char* parameters to the add_item_consume and add_value_consume functions and the Any* parameter to the add_value_consume function are consumed by the NVList. The caller may not access these data after they have been passed to these functions because the NVList may copy them and destroy the originals immediately. The caller should use the NamedValue::value() operation to modify the value attribute of the underlying NamedValue, if desired.

The remove function also calls CORBA::release on the removed NamedValue.

The following sections describe NVList member functions.

CORBA::NVList::add

Synopsis

Constructs a NamedValue object with an unnamed item, setting only the flags attribute.
C++ Binding

CORBA::NamedValue_ptr CORBA::NVList::add (
CORBA::Flags Flags);

Argument
Flags
Flags to determine argument passing. Valid values are:
CORBA::ARG_IN CORBA::ARG_INOUT CORBA::ARG_OUT
Description

This member function constructs a NamedValue object with an unnamed item, setting only the flags attribute. The NamedValue object is added to the NVList object that the call was invoked upon.
The NVList object grows dynamically; your application does not need to track its size.
Return Values

If the function succeeds, the return value is a pointer to the newly created NamedValue object. The returned NamedValue object reference is owned by the NVList and should not be released.
If the member function does not succeed, a CORBA::NO_MEMORY exception is thrown.
See Also

CORBA::NVList::add CORBA::NVList::add_item CORBA::NVList::add_value CORBA::NVList::count CORBA::NVList::remove

CORBA::NVList::add_item

Synopsis

Constructs a NamedValue object, creating an empty value attribute and initializing the name and flags attributes.
C++ Binding

CORBA::NamedValue_ptr CORBA::NVList::add_item (
const char * Name,
CORBA::Flags Flags);

Arguments
Name
The name of the list item.
Flags
Flags to determine argument passing. Valid values are:
CORBA::ARG_IN
CORBA::ARG_INOUT
CORBA::ARG_OUT
Description

This member function constructs a NamedValue object, creating an empty value attribute and initializing the name and flags attributes that pass in as parameters. The NamedValue object is added to the NVList object that the call was invoked upon.
The NVList object grows dynamically; your application does not need to track its size.
Return Values

If the function succeeds, the return value is a pointer to the newly created NamedValue object. The returned NamedValue object reference is owned by the NVList and should not be released.
If the member function does not succeed, an exception is thrown.
See Also

CORBA::NVList::add CORBA::NVList::add_value CORBA::NVList::count CORBA::NVList::item CORBA::NVList::remove

CORBA::NVList::add_value

Synopsis

Constructs a NamedValue object, initializing the name, value, and flags attribute.
C++ Binding

CORBA::NamedValue_ptr CORBA::NVList::add_value (
const char * Name,
const CORBA::Any & Value,
CORBA::Flags Flags);

Arguments
Name
The name of the list item.
Value
The value of the list item.
Flags
Flags to determine argument passing. Valid values are:
CORBA::ARG_IN
CORBA::ARG_INOUT
CORBA::ARG_OUT
Description

This member function constructs a NamedValue object, initializing the name, value, and flags attributes. The NamedValue object is added to the NVList object that the call was invoked upon.
The NVList object grows dynamically; your application does not need to track its size.
Return Values

If the function succeeds, the return value is a pointer to the newly created NamedValue object. The returned NamedValue object reference is owned by the NVList and should not be released.
If the member function does not succeed, an exception is raised.
See Also

CORBA::NVList::add CORBA::NVList::add_item CORBA::NVList::count CORBA::NVList::item CORBA::NVList::remove

CORBA::NVList::count

Synopsis

Retrieves the current number of items in the list.
C++ Binding

CORBA::ULong CORBA::NVList::count () const;

Arguments

None.
Description

This member function retrieves the current number of items in the list.
Return Values

If the function succeeds, the returned value is the number of items in the list. If the list has just been created, and no NamedValue objects have been added, this function returns 0 (zero).
If the function does not succeed, an exception is thrown.
See Also

CORBA::NVList::add CORBA::NVList::add_item CORBA::NVList::add_value CORBA::NVList::item CORBA::NVList::remove

CORBA::NVList::item

Synopsis

Retrieves a pointer to the NamedValue object, based on the index passed in.
C++ Binding

CORBA::NamedValue_ptr CORBA::NVList::item (
CORBA::ULong Index);

Argument

Index
The index into the NVList object. The indexing is zero-based.

Description

This member function retrieves a pointer to a NamedValue object, based on the index passed in. The function uses zero-based indexing.
Return Values

If the function succeeds, the return value is a pointer to the NamedValue object. The returned NamedValue object reference is owned by the NVList and should not be released.
Exception

If this function does not succeed, the BAD_PARAM exception is thrown.
See Also

CORBA::NVList::add CORBA::NVList::add_item CORBA::NVList::add_value CORBA::NVList::count CORBA::NVList::remove

CORBA::NVList::remove

Synopsis

Removes the item at the specified index, frees any associated memory, and reorders the remaining items on the list.
C++ Binding

void CORBA::NVList::remove (
CORBA::ULong Index);

Argument

Index
The index into the NVList object. The indexing is zero-based.

Description

This member function removes the item at the specified index, frees any associated memory, and reorders the remaining items on the list.
Return Values

None.
Exception

If this function does not succeed, the BAD_PARAM exception is thrown.
See Also

CORBA::NVList::add CORBA::NVList::add_item CORBA::NVList::add_value CORBA::NVList::count CORBA::NVList::item

Object Member Functions

The rules in this section apply to the OMG IDL interface Object, which is the base of the OMG IDL interface hierarchy. Interface Object defines a normal CORBA object, not a pseudo-object. However, it is included here because it references other pseudo-objects.
In addition to other rules, all operation names in interface Object have leading underscores in the mapped C++ class. Also, the mapping for create_request is divided into three forms, corresponding to the usage styles described in the section "Request Member Functions" on page 12-112. The is_nil and release functions are provided in the CORBA namespace, as described in "Object Member Functions" on page 12-42.
The WLE software uses object reference operations that are defined by CORBA Revision 2.2. These operations depend only on type Object, so they can be expressed as regular functions within the CORBA namespace.
Note: Because the WLE software uses the POA and not the BOA, the deprecated get_implementation() member function is not visible; you will get a compile error if you attempt to reference it.
The mapping of these member functions to C++ is as follows:
class CORBA { class Object { public: CORBA::Boolean _is_a(const char *) CORBA::Boolean _is_equivalent(); CORBA::Boolean _nonexistent(Object_ptr); static Object_ptr _duplicate(Object_ptr obj); static Object_ptr _nil(); InterfaceDef_ptr _get_interface(); CORBA::ULong _hass(CORBA::ULong); void _create_request( Context_ptr ctx, const char *operation, NVList_ptr arg_list, NamedValue_ptr result, Request_out request, Flags req_flags ); Status _create_request( Context_ptr ctx, const char * operation, NVList_ptr arg_list, NamedValue_ptr result, ExceptionList_ptr Except_list,
ContextList_ptr Context_list,
Request_out request, Flags req_flags ); Request_ptr _request(const char* operation); }; //Object }; // CORBA
The following sections describe the Object member functions.

CORBA::Object::_create_request

Synopsis

Creates a request with user-specified information.
C++ Binding

Void CORBA::Object::_create_request (
CORBA::Context_ptr Ctx,
const char * Operation,
CORBA::NVList_ptr Arg_list,
CORBA::NamedValue_ptr Result,
CORBA::ExceptionList_ptr Except_list,
CORBA::ContextList_ptr Context_list,
CORBA::Request_out Request,
CORBA::Flags Req_flags,);

Arguments

Ctx
The Context to be used for this request.
Operation
The operation name for this request.
Arg_list
The argument list for this request.
Result
The NamedValue reference where the return value of this request is to be stored after a successful invocation.
Except_list
The exception list for this request.
Context_list
The context list for this request.
Request
The newly created request reference.
Req_flags
Reserved for future use; the user must pass a value of zero.

Description

This member function creates a request that provides information on context, operation name, and other values (long form). To create a request with just the operation name supplied at the time of the call (short form), use the CORBA::Object::_request member function. The remainder of the information provided in the long form eventually needs to be supplied.
Return Values

None.
See Also

CORBA::Object::_request

CORBA::Object::_duplicate

Synopsis

Duplicates the Object object reference.
C++ Binding

CORBA::Object_ptr CORBA::Object::_duplicate(
Object_ptr Obj);

Argument

obj
The object reference to be duplicated.

Description

This member function duplicates the specified Object object reference (Obj). If the given object reference is nil, the _duplicate function returns a nil object reference. The object returned by this call should be freed using CORBA::release, or should be assigned to CORBA::Object_var for automatic destruction.
This function can throw CORBA system exceptions.
Return Values

Returns the duplicate object reference. If the specified object reference is nil, a nil object reference is returned.
Example

CORBA::Object_ptr op = TP::create_object_reference(
"IDL:Teller:1.0","MyTeller");
CORBA::Object_ptr dop = CORBA::Object::_duplicate(op);

CORBA::Object::_get_interface

Synopsis

Returns an interface definition for the Repository object.
C++ Binding

CORBA::InterfaceDef_ptr CORBA::Object::_get_interface ();

Arguments

None.
Description

Returns an interface definition for the Repository object.
Note: To use the Repository Interface API, define a macro before CORBA.h is included. For information about how to define a macro, see Creating C++ Server Applications.
Return Values

InterfaceDef_ptr

CORBA::Object::_is_a

Synopsis

Determines whether an object is of a certain interface.
C++ Binding

CORBA::Boolean CORBA::Object::_is_a(const char * interface_id);

Argument

interface_id
A string that denotes the interface repository ID.

Description

This member function is used to determine if an object is an instance of the interface that you specify in the interface_id parameter. It facilitates maintaining type-safety for object references over the scope of an ORB.
Return Values

Returns TRUE if the object is an instance of the specified type, or if the object is an ancestor of the "most derived" type of that object.
Example

CORBA::Object_ptr op = TP::create_object_reference(
"IDL:Teller:1.0", "MyTeller");
CORBA::Boolean b = op->_is_a("IDL:Teller:1.0");

Exceptions

Can throw a standard CORBA exception.

CORBA::Object::_is_equivalent

Synopsis

Determines if two object references are equivalent.
C++ Binding

CORBA::Boolean CORBA::Object::_is_equivalent ( CORBA::Object_ptr other_obj);

Argument

other_obj
The object reference for the other object, which is used for comparison with the target object.

Description

This member function is used to determine if two object references are equivalent, so far as the ORB can easily determine. It returns TRUE if your object reference is equivalent to the object reference you pass as a parameter. If two object references are identical, they are equivalent. Two different object references that refer to the same object are also equivalent.
Return Values

Returns TRUE if the target object reference is known to be equivalent to the other object reference passed as a parameter; otherwise, it returns FALSE.
Example

CORBA::Object_ptr op = TP::create_object_reference(
"IDL:Teller:1.0", "MyTeller");
CORBA::Object_ptr dop = CORBA::Object::_duplicate(op);
CORBA::Boolean b = op->_is_equivalent(dop);

CORBA::Object::_nil

Synopsis

Returns a reference to a nil object.
C++ Binding

CORBA::Object_ptr CORBA::Object::_nil();

Arguments

None.
Description

This member function returns a nil object reference. To test whether a given object is nil, use the appropriate CORBA::is_nil member function (see the section "CORBA::release" on page 12-54). Calling the CORBA:is_nil routine on any _nil member function always yields CORBA_TRUE.
Return Values

Returns a nil object reference.
Example

CORBA::Object_ptr op = CORBA::Object::_nil();

CORBA::Object::_non_existent

Synopsis

May be used to determine if an object has been destroyed.
C++ Binding

CORBA::Boolean CORBA::Object::_non_existent();

Arguments

None.
Description

This member function may be used to determine if an object has been destroyed. It does this without invoking any application-level operation on the object, and so will never affect the object itself.
Return Values

Returns CORBA_TRUE (rather than raising CORBA::OBJECT_NOT_EXIST) if the ORB knows authoritatively that the object does not exist; otherwise, it returns CORBA_FALSE.

CORBA::Object::_request

Synopsis

Creates a request specifying the operation name.
C++ Binding

CORBA::Request_ptr CORBA::Object::_request (
const char * Operation);

Argument

Operation
The name of the operation for this request.

Description

This member function creates a request specifying the operation name. All other information, such as arguments and results, must be populated using CORBA::Request member functions.
Return Values

If the member function succeeds, the return value is a pointer to the newly created request.
If the member function does not succeed, an exception is thrown.
See Also

CORBA::Object::_create_request
CORBA Member Functions

This section describes the Object and Pseudo-Object Reference member functions.
The mapping of these member functions to C++ is as follows:
class CORBA {
   	void release(Object_ptr);
   	void release(Environment_ptr);
   	void release(NamedValue_ptr);
	void release(NVList_ptr);
   	void release(Request_ptr);
   	void release(Context_ptr);
   	void release(TypeCode_ptr);
   	void release(POA_ptr);
   	void release(ORB_ptr);
   	void release(ExceptionList_ptr);
   	void release(ContextList_ptr);

   	Boolean is_nil(Object_ptr);
	Boolean is_nil(Environment_ptr);
   	Boolean is_nil(NamedValue_ptr);
   	Boolean is_nil(NVList_ptr);
   	Boolean is_nil(Request_ptr);
   	Boolean is_nil(Context_ptr);
   	Boolean is_nil(TypeCode_ptr);
   	Boolean is_nil(POA_ptr);
   	Boolean is_nil(ORB_ptr);
   	Boolean is_nil(ExceptionList_ptr);
   	Boolean is_nil(ContextList_ptr);

   	hash(maximum);

	resolve_initial_references(identifier);
   	...
};

CORBA::release

Synopsis

Allows allocated resources to be released for the specified object type.
C++ Binding

void CORBA::release(spec_object_type obj);

Argument

obj
The object reference that the caller will no longer access. The specified object type must be one of the types listed in the section "CORBA Member Functions" on page 12-53.

Description

This member function indicates that the caller will no longer access the reference so that associated resources may be deallocated. If the specified object reference is nil, the release operation does nothing. If the ORB instance release is the last reference to the ORB, then the ORB will be shutdown prior to its destruction. This is the same as calling ORB_shutdown prior to calling CORBA::release. This only applies to the release member function called on the ORB.
This member function may not throw CORBA exceptions.
Return Values

None.
Example

CORBA::Object_ptr op = TP::create_object_reference(
"IDL:Teller:1.0", "MyTeller");
CORBA::release(op);

CORBA::is_nil

Synopsis

Determines if an object exists for the specified object type.
C++ Binding

CORBA::Boolean CORBA::is_nil(spec_object_type obj);
Argument

obj
The object reference. The specified object type must be one of the types listed in the section "CORBA Member Functions" on page 12-53.

Description

This member function is used to determine if a specified object reference is nil. It returns TRUE if the object reference contains the special value for a nil object reference as defined by the ORB.
This operation may not throw CORBA exceptions.
Return Values

Returns TRUE if the specified object is nil; otherwise, returns FALSE.
Example

CORBA::Object_ptr op = TP::create_object_reference(
"IDL:Teller:1.0", "MyTeller");
CORBA::Boolean b = CORBA::is_nil(op);

CORBA::hash

Synopsis

Provides indirect access to object references using identifiers internal to the ORB.
C++ Binding

CORBA::hash(CORBA::ULong maximum);

Argument

maximum
Specifies an upper bound on the hash value returned by the ORB.

Description

Object references are associated with ORB-internal identifiers that may indirectly be accessed by applications using the hash() operation. The value of this identifier does not change during the lifetime of the object reference, and so neither will any hash function of that identifier.
The value of this operation is not guaranteed to be unique; that is, another object reference may return the same hash value. However, if two object references hash differently, applications can determine that the two object references are not identical.
The maximum parameter to the hash operation specifies an upper bound on the hash value returned by the ORB. The lower bound of that value is zero. Since a typical use of this feature is to construct and access a collision-chained hash table of object references, the more randomly distributed the values are within that range, and the less expensive those values are to compute, the better.
Return Values

None.

CORBA::resolve_initial_references

Synopsis

Returns an initial object reference corresponding to an identifier string.
C++ Binding

CORBA::Object_ptr CORBA::resolve_initial_references( const CORBA::char *identifier);

Argument

identifier
String identifying the object whose reference is required.

Description

Returns an initial object reference corresponding to an identifier string. Valid identifiers are "RootPOA" and "POACurrent".
Note: This function is supported only for a joint client/server.
Return Values

Returns a CORBA::Object_ptr.
Exception

InvalidName
Example

CORBA::ORB_ptr orb = CORBA::ORB_init(argc, argv); CORBA::Object_ptr pfobj = orb->resolve_initial_references("RootPOA"); PortableServer::POA_ptr rootPOA; rootPOA = PortableServer::POA::narrow(pfobj);

ORB Member Functions

The ORB member functions constitute the programming interface to the Object Request Broker.
The mapping of the ORB member functions to C++ is as follows:
class CORBA { class ORB { public: char *object_to_string(Object_ptr); Object_ptr string_to_object(const char *); void create_list(Long, NVList_out); void create_operation_list(operationDef_ptr, NVList_out); void create_named_value(NamedValue_out); void create_environment(Environment_out); void create_policy (in PolicyType type, in any val); void destroy () void send_multiple_requests_oneway(const requestSeq&); void send_multiple_requests_deferred(const requestSeq&); void create_exception_list(ExceptionList_out); void create_context_list(ContextList_out); void get_default_context(Context_out); void get_next_response(Request_out); void perform_work(); void run(); void shutdown(in boolean wait_for_completion); Boolean poll_next_response(); Boolean work_pending( ); }; //ORB }; // CORBA
Thread-related Operations:
To support single-threaded ORBs, as well as multithreaded ORBs that run multithread-unaware code, four operations (perform_work, run, shutdown, and work_pending) are included in the ORB interface. These operations can be used by single-threaded and multithreaded applications. An application that is a pure ORB client would not need to use these operations. Both the ORB::run() and ORB::shutdown() are useful in fully multithreaded programs.
The following sections describe the ORB member functions.

CORBA::ORB::create_environment

Synopsis

Creates an environment.
C++ Binding

void CORBA::ORB::create_environment (
CORBA::Environment_out New_env);

Argument

New_env
Receives a reference to the newly created environment.

Description

This member function creates an environment.
Return Values

None.
See Also

CORBA::NVList::add CORBA::NVList::add_item CORBA::NVList::add_value CORBA::release

CORBA::ORB::create_list

Synopsis

Creates and returns an NVList object reference.
C++ Binding

void CORBA::ORB::create_list (
CORBA::Long NumItem,
CORBA::NVList_out List);

Arguments

NumItem
The number of elements to preallocate in the newly created list.
List
Receives the newly created list.

Description

This member function creates a list, preallocating a specified number of items. List items may be sequentially added to the list using the CORBA::NVList_add_item member function. When no longer needed, this list must be freed using the CORBA::release member function.
Return Values

None.
See Also

CORBA::NVList::add CORBA::NVList::add_item CORBA::NVList::add_value CORBA::release

CORBA::ORB::create_named_value

Synopsis

Creates a NamedValue object reference.
C++ Binding

void CORBA::ORB::create_named_value (
NameValue_out NewNamedVal);

Argument

NewNamedVal
A reference to the newly created NamedValue object.

Description

This member function creates a NamedValue object. Its intended use is for the result argument of a request that needs a NamedValue object. The extra steps of creating an NVList object are avoided by calling this member function.
When no longer needed, the NamedValue object must be freed using the CORBA::release member function.
Return Values

None.
See Also

CORBA::NVList::add CORBA::NVList::add_item CORBA::NVList::add_value CORBA::release

CORBA::ORB::create_exception_list

Synopsis

Returns a list of exceptions.
C++ Binding

void CORBA::ORB::create_exception_list( CORBA::ExceptionList_out List);

Argument

List
Receives a reference to the newly created exception list.

Description

This member function creates and returns a list of exceptions in a form that may be used in the Dynamic Invocation Interface (DII). When no longer needed, this list must be freed using the CORBA::release member function.
Return Values

None.

CORBA::ORB::create_context_list

Synopsis

Creates and returns a list of contexts.
C++ Binding

void CORBA::ORB::create_context_list( CORBA::ContextList_out List);

Argument

List
Receives a reference to the newly created context list.

Description

This member function creates and returns a list of context strings that must be supplied with the Request operation in a form that may be used in the Dynamic Invocation Interface (DII). When no longer needed, this list must be freed using the CORBA::release member function.
Return Values

None.

CORBA::ORB::create_policy

Synopsis

Creates new instances of policy objects of a specific type with specified initial state.
C++ Binding

void CORBA::ORB::create_policy (
in PolicyType type,
in any val);

Arguments

type
BiDirPolicy::BIDIRECTIONAL_POLICY_TYPE is the only PolicyType value supported for WLE V4.2 .
val
The only val value supported for WLE V4.2 is BiDirPolicy::BidirectionalPolicyValue.

Description

This operation can be invoked to create new instances of policy objects of a specific type with specified initial state. If create_policy fails to instantiate a new Policy object due to its inability to interpret the requested type and content of the policy, it raises the Policy Error exception with the appropriate reason. (See Exceptions below.)
The BidirectionalPolicy argument is provided for remote clients using callbacks because remote clients use IIOP. It is not used for native clients using callbacks or for WLE servers because machines inside a WLE domain communicate differently.
Before GIOP 1.2, bidirectional policy was not available as a choice in IIOP (which uses TCP/IP). Connections in GIOP 1.0 and 1.1 were one way (that is, a request flowed from a client to a server); only responses flowed from the server back to the client. If the server wanted to make a request back to the client machine (say for a callback), the server machine had to establish another one-way connection. (Be advised that "connections" in this sense mean operating system resources, not physically different wires or communication paths. A connection uses resources, so minimizing connections is desirable.)
Since this release of the WLE C++ software supports GIOP 1.2, it supports re-use of the TCP/IP connection for both incoming and outgoing requests. Re-using connections saves resources when a remote client sends callback references to a WLE domain. The joint client/server uses a connection to send a request to a WLE domain; that connection can be re-used for the callback request. If the connection is not re-used, the callback request must establish another connection.
Allowing re-use of a connection is a choice of the ORB/POA that creates callback object references. The server for those object references (usually the creator of the references, especially in the callback case) might choose not to allow re-use for security considerations (that is, the outgoing connection (a client request from this machine to a remote server) may not need security because the remote server does not require it, but the callback server on this machine might require security). Since security is established partly on a connection basis, the incoming security can be established only if a separate connection is used. If the remote server requires security, and if that security involves a mutual authentication, the local server usually feels safe in allowing re-use of the connection.
Since the choice of connection re-use is at the server end, whenever a process acts as a server-in this case a joint client/server-and creates object references, it must inform the ORB that it is willing to re-use connections. The process does this by setting a policy on the POA that creates the object references. The default policy is to not allow re-use (that is, if you do not supply a policy object for re-use, the POA does not allow re-use).
This default allows for backward compatibility with code written before CORBA version 2.3. Such code did not know that re-use was possible so it did not have to take into consideration the security implications of re-use. Thus, that unchanged code should continue to disallow re-use until the user considers security and explicitly makes a decision to the contrary.
To allow re-use, you use the create_policy operation to create a policy object that allows re-use, and use that policy object as part of the list of policies for POA creation.
Return Values

None.
Exceptions

PolicyError
This exception is raised to indicate problems with the parameter values passed to the ORB::create_policy operation. The specific exception and reasons are as follows:

Exception Reason

BAD_POLICY

The requested Policy is not understood by the ORB.

UNSUPPORTED_POLICY

The requested Policy is understood to be valid by the ORB, but is not currently supported.

BAD_POLICY_TYPE

The type of the value requested for the Policy is not valid for that PolicyType.

BAD_POLICY_VALUE

The value requested for the Policy is of a valid type, but is not within the valid range for that type.

UNSUPPORTED_POLICY_VALUE

The value requested for the Policy is of a valid type and within the valid range for that type, but this valid value is not currently supported.

Example

#include <BiDirPolicy_c.h> BiDirPolicy::BidirectionalPolicy_var bd_policy; CORBA::Any allow_reuse;
allow_reuse <<= BiDirPolicy::BOTH;
CORBA::Policy_var generic_policy = orb->create_policy( BiDirPolicy::BIDIRECTIONAL_POLICY_TYPE, allow_reuse ); bd_policy = BiDirPolicy::BidirectionalPolicy::_narrow( generic_policy );
In the above example, the bd_policy would then be placed in the PolicyList passed to the create_poa operation.

Exception	Reason
`BAD_POLICY`	The requested Policy is not understood by the ORB.
`UNSUPPORTED_POLICY`	The requested Policy is understood to be valid by the ORB, but is not currently supported.
`BAD_POLICY_TYPE`	The type of the value requested for the Policy is not valid for that PolicyType.
`BAD_POLICY_VALUE`	The value requested for the Policy is of a valid type, but is not within the valid range for that type.
`UNSUPPORTED_POLICY_VALUE`	The value requested for the Policy is of a valid type and within the valid range for that type, but this valid value is not currently supported.

CORBA::ORB::create_operation_list

Synopsis

Creates and returns a list of the arguments of a specified operation.
C++ Binding

void CORBA::ORB::create_operation_list (
CORBA::OperationDef_ptr Oper,
CORBA::NVList_out List);

Arguments

Oper
The operation definition for which the list is being created.
List
Receives a reference to the newly created arguments list.

Description

This member function creates and returns a list of the arguments of a specified operation, in a form that may be used with the Dynamic Invocation Interface (DII). When no longer needed, this list must be freed using the CORBA::release member function.
Return Values

None.
See Also

CORBA::OBB::create_list CORBA::NVList::add CORBA::NVList::add_item CORBA::NVList::add_value CORBA::release

CORBA::ORB::get_default_context

Synopsis

Returns a reference to the default context.
C++ Binding

void CORBA::ORB::get_default_context (
CORBA::Context_out ContextObj);

Argument

ContextObj
The reference to the default context.

Description

This member function returns a reference to the default context. When no longer needed, this context reference must be freed using the CORBA::release member function.
Return Values

None.
See Also

CORBA::Context::get_one_value
CORBA::Context::get_values

CORBA::ORB::get_next_response

Synopsis

Determines and reports the next deferred synchronous request that completes.
C++ Binding

void CORBA::ORB::get_next_response (
CORBA::Request_out RequestObj);

Argument

RequestObj
The reference to the next completed request.

Description

This member function returns a reference to the next request that completes. If no requests have completed, the function waits for a request to complete. This member function returns the next request on the queue, in contrast to the CORBA::Request::get_response member function, which waits for a particular request to complete. When no longer needed, this request must be freed using the CORBA::release member function.
Return Values

None.
See Also

CORBA::ORB::poll_next_response CORBA::Request::get_reponse

CORBA::ORB::perform_work

Synopsis

Allows the ORB to perform server-related work.
C++ Binding

void CORBA::ORB::perform_work ();

Arguments

None.

Description

If called by the main thread, this operation allows the ORB to perform server-related work. Otherwise, it does nothing.
The work_pending() and perform_work() operations can be used to write a simple polling loop that multiplexes the main thread among the ORB and other activities. Such a loop would most likely be needed in a single-threaded server. A multithreaded server would need a polling loop only if there were both ORB and other code that required use of the main thread. See the example below for such a polling loop.
Return Values

None.
Exceptions

Once the ORB has shut down, a call to work_pending and perform_work() raises the BAD_INV_ORDER exception. An application can detect this exception to determine when to terminate a polling loop.
See Also

CORBA::ORB::work_pending
Example

Here is an example of a polling loop:
// C++ for (;;) { if (orb->work_pending()) { orb->perform_work(); } // do other things // sleep? }

CORBA::ORB::run

Synopsis

Enables the ORB to perform work using the main thread.
C++ Binding

void CORBA::ORB::run();

Argument

None
Description

This operation provides execution resources to the ORB so that it can perform its internal functions. Since the WLE C++ ORB is single-threaded, this essentially turns the process into a pure server.
This operation blocks until the ORB has completed the shutdown process, initiated when a thread calls CORBA::ORB::shutdown().
Return Values

None.
See Also

CORBA::ORB::perform_work

CORBA::ORB::shutdown

Synopsis

Instructs the ORB to shut down.
C++ Binding

void shutdown( in boolean wait_for_completion );

Argument

wait_for_completion
A value of TRUE blocks until all ORB processing has completed.

Description

This operation instructs the ORB to shut down (that is, to stop processing in preparation for destruction).
Shutting down the ORB causes all POAs to be destroyed, since they cannot exist in the absence of an ORB. Shut down is complete when all ORB processing (including request processing and object deactivation or other operations associated with the POAs) has completed and all POAs have been destroyed.
If the wait_for_completion parameter is TRUE, this operation blocks until the shut down is complete. If an application calls shutdown(TRUE) in a thread that is currently servicing an invocation, the BAD_INV_ORDER system exception will be raised with the OMG minor code 3, since blocking would result in a deadlock.
If the wait_for_completion parameter is FALSE, the shutdown may not have completed upon return. This use of FALSE is not recommended.
While the ORB is in the process of shutting down, the ORB operates as normal, servicing incoming and outgoing requests until all requests have been completed.
Once an ORB has shut down, invoking any operation on that ORB or any object reference obtained from that ORB will raise the BAD_INV_ORDER system exception with the OMG minor code 4, except for the reference management operations duplicate(), release(), and is_nil().
Return Values

None.

CORBA::ORB::object_to_string

Synopsis

Produces a string representation of an object reference.
C++ Binding

char * CORBA::ORB::object_to_string (
CORBA::Object_ptr ObjRef);

Argument

ObjRef
The object reference to represent as a string.

Description

This member function produces a string representation of an object reference. The calling program must use the CORBA::string_free member function to free the string memory after it is no longer needed.
Return Values

The string representing the specified object reference.
Example

CORBA::Object_ptr op = TP::create_object_reference(
"IDL:Teller:1.0", "MyTeller");
char* objstr = TP::orb()->object_to_string(op);

See Also

CORBA::ORB::string_to_object CORBA::string_free

CORBA::ORB::poll_next_response

Synopsis

Determines whether a completed request is outstanding.
C++ Binding

CORBA::Boolean CORBA::ORB::poll_next_response ();

Arguments

None.
Description

This member function reports on whether there is an outstanding (pending) completed request; it does not remove the request. If a completed request is outstanding, the next call to the CORBA::ORB::get_next_response member function is guaranteed to return a request without waiting. If there are no completed requests outstanding, the CORBA::ORB::poll_next_response member function returns without waiting (blocking).
Return Values

If a completed request is outstanding, the function returns CORBA_TRUE.
If no completed request is outstanding, the function returns CORBA_FALSE.
See Also

CORBA::ORB::get_next_response

CORBA::ORB::work_pending

Synopsis

Returns an indication of whether the ORB needs the main thread to perform server-related work.
C++ Binding

CORBA::boolean CORBA::ORB::work_pending ();

Arguments

None.
Description

This operation returns an indication of whether the ORB needs the main thread to perform server-related work.
Return Values

A result of TRUE indicates that the ORB needs the main thread to perform server-related work, and a result of FALSE indicates that the ORB does not need the main thread.
See Also

CORBA::ORB::perform_work

CORBA::ORB::send_multiple_requests_deferred

Synopsis

Sends a sequence of deferred synchronous requests.
C++ Binding

void CORBA::ORB::send_multiple_requests_deferred (
const CORBA::ORB::RequestSeq & Reqs);

Argument

Reqs
The sequence of requests to be sent. For more information about how to populate the sequence with request references, see CORBA::ORB::RequestSeq in the section "Usage" on page 11-23.

Description

This member function sends out a sequence of requests and returns control to the caller without waiting for the operation to complete. The caller uses CORBA::ORB::poll_ next_response, CORBA::ORB::get_next_response, or CORBA::Rquest::get_response or all three to determine if the operation has completed and if the output arguments have been updated.
Return Values

None.
See Also

CORBA::Request::get_response CORBA::ORB::get_next_response CORBA::ORB::send_multiple_requests_oneway

CORBA::ORB::send_multiple_requests_oneway

Synopsis

Sends a sequence of one-way, deferred synchronous requests.
C++ Binding

void CORBA::ORB::send_multiple_requests_oneway (
const CORBA::RequestSeq & Reqs);

Argument

Reqs
The sequence of requests to be sent. For more information about how to populate the sequence with request references, see CORBA::ORB::RequestSeq in the section "Usage" on page 11-23.

Description

This member function sends out a sequence of requests and returns control to the caller without waiting for the operation to complete. The caller neither intends to wait for a response nor expects any output arguments to be updated.
Return Values

None.
See Also

CORBA::ORB::send_multiple_requests_deferred

CORBA::ORB::string_to_object

Synopsis

Creates an object reference, given a specified string.
C++ Binding

CORBA::Object_ptr CORBA::ORB::string_to_object (
const char * ObjRefString);

Argument

ObjRefString
The string to be transformed into an object reference.

Description

This member function creates an object reference, given a specified string. Usually the string has been obtained previously by calling the CORBA::ORB::object_to_string member function. After you are done with the object reference, use the CORBA::release member function to free the associated memory.
Return Values

If the member function succeeds, the object reference represented by the specified string is returned.
If the member function does not succeed, an exception is thrown.
Example

CORBA::Object_ptr op = TP::create_object_reference(
"IDL:Teller:1.0", "MyTeller");
char* objstr = TP::orb()->object_to_string(op);
CORBA::Object_ptr op2 = TP::orb()->string_to_object(objstr);

See Also

CORBA::ORB::object_to_string
ORB Initialization Member Function

The mapping of this member function to C++ is as follows:
class CORBA { typedef char* ORBid; static CORBA::ORB_ptr ORB_init(int& argc, char** argv, const char* orb_identifier = 0, const char* -ORBport nnn); };

CORBA::ORB_init

Synopsis

Initializes operations for an ORB.
C++ Binding

static CORBA::ORB_ptr ORB_init(int& argc, char** argv, const char* orb_identifier = 0);

Arguments

argc
The number of strings in argv.
argv
This argument is defined as an unbound array of strings (char **) and the number of strings in the array is passed in the argc parameter.
orb_identifier
If the orb_identifier parameter is supplied, "BEA_IIOP" explicitly specifies a remote client and "BEA_TOBJ" explicitly specifies a native client, as defined in the section "Tobj_Bootstrap" on page 4-11.

Description

This member function initializes operations for an ORB and returns a pointer to the ORB. When your program is done with the ORB, use the CORBA::release member function to free the resources allocated for the ORB pointer returned from CORBA::ORB_ptr ORB_init.
The ORB returned has been initialized with two pieces of information to determine how it will operate: client type (remote or native) and server port number. The client type can be specified in the orb_identifier argument, in the argv argument, or in the system registry. The server port number can be specified in the argv argument.
The arguments argc and argv are typically the same parameters that were passed to the main program. As specified by C++, these parameters contain string tokens from the command line that started the client. The two ORB options can be specified on the command line, each using a pair of tokens, as shown in examples below.
CLIENT TYPE
The ORB_init function determines the client type of the ORB by the following steps.

If the orb_identifier argument is present, ORB_init determines the client type, either native or remote, if the string is "BEA_IIOP" or "BEA_TOBJ", respectively. If an orb_identifier string is present, all -ORBid parameters in the argv are ignored (removed).

If orb_identifier is not present or is explicitly zero, ORB_init looks at the entries in argc/argv. If argv contains an entry with "-ORBid", the next entry should be either "BEA_IIOP" or "BEA_TOBJ", again specifiying remote or native. This pair of entries occurs if the command line contains either "-ORBid BEA_IIOP" or "-ORBid BEA_TOBJ".

If no client type is specified in argc/argv, ORB_init uses the default client type from the system registry (BEA_IIOP or BEA_TOBJ). The system registry was initialized at the time WLE was installed.

SERVER PORT
In the case of a WLE remote joint client/server, in order to support IIOP, by definition, the object references created for the server part must contain a host and port. For transient object references, any port is sufficient and can be obtained by the ORB dynamically, but this is not sufficient for persistent
object references. Persistent references must be served on the same port after the ORB restarts, that is, the ORB must be prepared to accept requests on the same port with which it created the object reference. Thus, there must be some way to configure the ORB to use a particular port.
Typically, a system administrator assigns the port number for the client from the "user" range of port numbers rather from the dynamic range. This keeps the joint client/servers from using conflicting ports.
To determine port number, ORB_init searches the argv parameter for the token "-ORBport" and a following numeric token. For example, if the client executable is named sherry, the command line might specify that the server port should be 937 as follows:
sherry -ORBport 937
ARGV PARAMETER CONSIDERATIONS
For C++, the order of consumption of argv parameters may be significant to an application. To ensure that applications are not required to handle argv parameters they do not recognize, the ORB initialization function must be called before the remainder of the parameters are consumed. Therefore, after the ORB_init call, the argv and argc parameters have been modified to remove the ORB understood arguments. It is important to note that the ORB_init function can only reorder or remove references to parameters from the argv list. This restriction is made to avoid potential memory management problems caused by trying to free parts of the argv list or extending the argv list of parameters. This is why argv is passed as a char** and not as a char**&.
Note: Use the CORBA::release member function to free the resources allocated for the pointer returned from CORBA::ORB_init.
Return Value

A pointer to a CORBA::ORB.
Exceptions

None.

Policy Member Functions

A policy is an object used to communicate certain choices to an ORB regarding its operation. This information is accessed in a structured manner using interfaces derived from the Policy interface defined in the CORBA module.
Note: These CORBA::Policy operations and structures are not usually needed by programmers. The derived interfaces usually contain the information relevant to specifications. A Policy object can be constructed by a specific factory or by using the CORBA::create_policy operation.
The mapping of this object to C++ is as follows:
class CORBA { class Policy { public: copy(); void destroy(); }; //Policy typedef sequence<Policy>PolicyList; }; // CORBA
PolicyList is used the same as any other C++ sequence mapping. For a discussion of sequence usage, see "Sequences" on page 11-13.
See Also: POA Policy and CORBA::ORB::create_policy.

CORBA:Policy::copy

Synopsis

Copies the policy object.
C++ Binding

CORBA::Policy::copy();

Argument

None.
Description

This operation copies the policy object. The copy does not retain any relationships that the policy had with any domain or object.
Note: This function is supported only for a joint client/server.
Return Values

None.

CORBA::Policy::destroy

Synopsis

Destroys the policy object.
C++ Binding

void CORBA::Policy::destroy();

Argument

None.
Description

This operation destroys the policy object. It is the responsibility of the policy object to determine whether it can be destroyed.
Note: This function is supported only for a joint client/server.
Return Values

None.
Exceptions

If the policy object determines that it cannot be destroyed, the CORBA::NO_PERMISSION exception is raised.
PortableServer Member Functions

The mapping of the PortableServer member functions to C++ is as follows:
// C++
class PortableServer
{
    public:
           class LifespanPolicy;
           class IdAssignmentPolicy;
           class POA::find_POA
           class reference_to_id
           class POAManager;
           class POA;
           class Current;
           class virtual ObjectId
           class ServantBase
};
ObjectId-An ObjectId is a value that is used by the POA and by the user-supplied implementation to identify a particular abstract CORBA object. ObjectId values may be assigned and managed by the POA, or they may be assigned and managed by the implementation. ObjectId values are hidden from clients, encapsulated by references. ObjectIds have no standard form; they are managed by the POA as uninterpreted octet sequences.
The following sections describe the remaining classes.

PortableServer::POA::activate_object

Synopsis

Explicitly activates an individual object.
C++ Binding

ObjectId * activate_object ( Servant p_servant);

Argument

p_servant
An instance of the C++ implementation class for the interface.

Description

This operation explicitly activates an individual object by generating an ObjectId and entering the ObjectId and the specified servant in the Active Object Map.
Note: This function is supported only for a joint client/server.
Return Values

If the function succeeds, the ObjectId is returned.
Exceptions

If the specified servant is already in the Active Object Map, the ServantAlreadyActive exception is raised.
Note: Other exceptions can occur if the POA uses unsupported policies.
Example

In the following example, the first struct creates a servant by a user-defined constructor. The second struct tells the POA that the servant can be used to handle requests on an object. The POA returns the ObjectId it has created for the object. The third statement assumes that the POA has the IMPLICIT_ACTIVATION policy (the only supported policy in version 4.2 of the WLE software) and returns a reference to the object. That reference can then be handed to a client for invocations. When the client invokes on the reference, the request is returned to the servant just created.
MyFooServant* afoo = new MyFooServant(poa,27);
PortableServer::ObjectId_var oid = 
	 poa->activate_object(afoo);
Foo_var foo = afoo->_this();

PortableServer::POA::activate_object_with_id

Synopsis

Activates an individual object with a specified ObjectId.
C++ Binding

void activate_object_with_id ( const ObjectId & id, Servant p_servant);

Argument

id
ObjectId that identifies the object on which that operation was invoked.
p_servant
An instance of the C++ implementation class for the interface.

Description

This operation enters an association between the specified ObjectId and the specified servant in the Active Object Map.
Note: This function is supported only for a joint client/server.
Return Values

None.
Exceptions

The ObjectAlreadyActive exception is raised if the CORBA object denoted by the ObjectId value is already active in this POA.
The ServantAlreadyActive exception is raised if the servant is already in the Active Object Map.
Note: Other exceptions can occur if the POA uses unsupported policies.
The BAD_PARAM system exception may be raised if the POA has the SYSTEM_ID policy and it detects that the ObjectId value was not generated by the system or for this POA. An ORB is not required to detect all such invalid ObjectId values. However, a portable application must not invoke activate_object_with_id on a POA if the POA has the SYSTEM_ID policy with an ObjectId value that was not previously generated by the system for that POA, or, if the POA also has the PERSISTENT policy, for a previous instantiation of the same POA.
Example

MyFooServant* afoo = new MyFooServant(poa, 27);
PortableServer::ObjectId_var oid =
PortableServer::string_to_ObjectId("myLittleFoo");
poa->activate_object_with_id(oid.in(), afoo);
Foo_var foo = afoo->_this();

PortableServer::POA::create_id_assignment_policy

Synopsis

Obtain an object with the IdAssignmentPolicy interface so the user can pass the object to the POA::create_POA operation.
C++ Binding

IdAssignmentPolicy_ptr PortableServer::POA::create_id_assignment_policy (PortableServer::IdAssignmentPolicyValue value)

Argument

value
A value of either PortableServer::USER_ID, indicating ObjectIds are assigned only by the application, or PortableServer::SYSTEM_ID, indicating ObjectIds are assigned only by the system.

Description

The POA::create_id_assignment_policy operation obtains objects with the IdAssignmentPolicy interface. When passed to the POA::create_POA operation, this policy specifies whether ObjectIds in the created POA are generated by the application or by the ORB. The following values can be supplied:

PortableServer::USER_ID-objects created with that POA are assigned ObjectIds only by the application.

PortableServer::SYSTEM_ID-objects created with that POA are assigned ObjectIds only by the POA. If the POA also has the PERSISTENT LifespanPolicy, assigned ObjectIds must be unique across all instantiations of the same POA.

If no IdAssignmentPolicy is specified at POA creation, the default is SYSTEM_ID.
Note: This function is supported only for a joint client/server.
Return Values

Returns an Id Assignment policy.

PortableServer::POA::create_lifespan_policy

Synopsis

Obtain an object with the LifespanPolicy interface so the user can pass the object to the POA::create_POA operation.
C++ Binding

LifespanPolicy_ptr PortableServer::POA::create_lifespan_policy (PortableServer::LifespanPolicyPolicyValue value)

Argument

value
A value of either PortableServer::USER_ID, indicating ObjectIds are assigned only by the application, or PortableServer::SYSTEM_ID, indicating ObjectIds are assigned only by the system.

Description

Objects with the LifespanPolicy interface are obtained using the POA::create_lifespan_policy operation and passed to the POA::create_POA operation to specify the lifespan of the objects implemented in the created POA. The following values can be supplied.

TRANSIENT-The objects implemented in the POA cannot outlive the process in which they are first created. Once the POA is deactivated, use of any object references generated from it will result in an OBJECT_NOT_EXIST exception.

PERSISTENT-The objects implemented in the POA can outlive the process in which they are first created.

Persistent objects have a POA associated with them (the POA which created them). When the ORB receives a request on a persistent object, it first searches for the matching POA, based on the names of the POA and all of its ancestors.

Administrative action beyond the scope of this specification may be necessary to inform the ORB's location service of the creation and eventual termination of existence of this POA, and optionally to arrange for on-demand activation of a process implementing this POA.

POA names must be unique within their enclosing scope (the parent POA). A portable program can assume that POA names used in other processes will not conflict with its own POA names. A conforming CORBA implementation will provide a method for ensuring this property.

If no LifespanPolicy object is passed to POA::create_POA, the lifespan policy defaults to TRANSIENT.
Note: This function is supported only for a joint client/server.
Return Values

Returns a LifespanPolicy.

PortableServer::POA::create_POA

Synopsis

Creates a new POA as a child of the target POA.
C++ Binding

POA_ptr PortableServer::create_POA ( const char * adapter_name, POAManager_ptr a_POAManager, const CORBA::PolicyList & policies)

Arguments

adapter_name
The name of the POA to be created.
a_POAManager
Either a null value, indicating that a new POAManager is to be created and associated with the new POA, or a pointer to an existing POAManager.
policies
Policy objects to be associated with the new POA.

Description

This operation creates a new POA as a child of the target POA. The specified name, which must be unique, identifies the new POA with respect to other POAs with the same parent POA.
If the a_POAManager parameter is null, a new PortableServer::POAManager object is created and associated with the new POA. Otherwise, the specified POAManager object is associated with the new POA. The POAManager object can be obtained using the attribute name the_POAManager.
The specified policy objects are associated with the POA and are used to control its behavior. The policy objects are effectively copied before this operation returns, so the application is free to destroy them while the POA is in use. Policies are not inherited from the parent POA.
Note: This function is supported only for joint client/servers.
Return Values

Returns a pointer to the POA that was created.
Exceptions

AdapterAlreadyExists
Raised if the target POA already has a child POA with the specified name.
InvalidPolicy
Raised if any of the policy objects specified are not valid for the ORB implementation, if conflicting policy objects are specified, or if any of the specified policy objects require prior administrative action that has not been performed. This exception contains the index in the policy parameter value of the first offending policy object.
IMP_LIMIT
Raised if the program tries to create a POA with a LifespanPolicy of PERSISTENT without having set a port, as described in the operation "CORBA::ORB_init" on page 12-81.

Examples

Example 1:
In this example, the child POA would use the same manager as the parent POA; the child POA would then have the same state as the parent (that is, it would be active if the parent is active).
CORBA::PolicyList policies(2);
policies.length (1);
policies[0] = rootPOA->create_lifespan_policy( 
              PortableServer::LifespanPolicy::TRANSIENT);
PortableServer::POA_ptr poa = 
       rootPOA->create_POA("my_little_poa",
              rootPOA->the_POAManager, policies);
Example 2:
In this example, a new POA is created as a child of the root POA.
CORBA::PolicyList policies(2);
policies.length (1);
policies[0] = rootPOA->create_lifespan_policy( 
              PortableServer::LifespanPolicy::TRANSIENT);
PortableServer::POA_ptr poa = 
       rootPOA->create_POA("my_little_poa",
              PortableServer::POAManager::_nil(), policies);

PortableServer::POA::create_reference

Synopsis

Creates an object reference that encapsulates a POA-generated ObjectId value and the specified interface repository ID.
C++ Binding

CORBA::Object_ptr create_reference ( const char * intf)

Argument

intf
The interface repository ID.

Description

This create_reference operation creates an object reference that encapsulates a POA-generated ObjectId value and the specified interface repository ID. This operation collects the necessary information to constitute the reference from information associated with the POA and from parameters to the operation. This operation only creates a reference; it does not associate the reference with an active servant. The resulting reference may be passed to clients, so that subsequent requests on those references return to the POA using the ObjectId generated. The generated ObjectId value may be obtained by invoking POA::reference_to_id with the created reference.
Note: This function is supported only for a joint client/server.
Return Values

Returns a pointer to the object.
Exceptions

This operation requires the LifespanPolicy to have the value SYSTEM_ID; if not present, the PortableServer::WrongPolicy exception is raised.

PortableServer::POA::create_reference_with_id

Synopsis

Creates an object reference that encapsulates the specified ObjectId and interface repository ID values.
C++ Binding

CORBA::Object_ptr create_reference_with_id ( const ObjectId & oid, const char * intf)

Arguments

oid
ObjectId that identifies the object on which that operation was invoked.
intf
The interface repository ID.

Description

The create_reference operation creates an object reference that encapsulates the specified ObjectId and interface repository ID values. This operation collects the necessary information to constitute the reference from information associated with the POA and from parameters to the operation. This operation only creates a reference; it does not associate the reference with an active servant. The resulting reference may be passed to clients, so that subsequent requests on those references cause the invocation to be returned to the same POA with ObjectId specified.
Note: This function is supported only for a joint client/server.
Return Values

Returns Object_ptr.
Exceptions

If the POA has a LifespanPolicy with value SYSTEM_ID and it detects that the ObjectId value was not generated by the system or for this POA, the operation will raise the BAD_PARAM system exception.
Example

PortableServer::ObjectId_var oid =
PortableServer::string_to_ObjectId("myLittleFoo");
CORBA::Object_var obj = poa->create_reference_with_id(
oid.in(), "IDL:Foo:1.0");
Foo_var foo = Foo::_narrow(obj);

PortableServer::POA::deactivate_object

Synopsis

Removes the ObjectId from the Active Object Map.
C++ Binding

void deactivate_object ( const ObjectId & oid)

Argument

oid
ObjectId that identifies the object.

Description

This operation causes the association of the ObjectId specified by the oid parameter and its servant to be removed from the Active Object Map.
Note: This function is supported only for a joint client/server.
Return Values

None.
Exceptions

If there is no active object associated with the specified ObjectId, the operation raises an ObjectNotActive exception.

PortableServer::POA::destroy

Synopsis

Destroys the POA and all descendant POAs.
C++ Binding

void destroy ( CORBA::Boolean etherealize_objects, CORBA::Boolean wait_for_completion)

Arguments

etherealize_objects
This argument should be FALSE for this release of WLE.
wait_for_completion
This argument indicates whether or not the operation should return immediately.

Description

This operation destroys the POA and all descendant POAs. The POA with its name may be re-created later in the same process. (This differs from the POAManager::deactivate operation, which does not allow a re-creation of its associated POA in the same process.)
When a POA is destroyed, any requests that have started execution continue to completion. Any requests that have not started execution are processed as if they were newly arrived and there is no POA; that is, they are rejected and the OBJECT_NON_EXIST exception is raised.
If the wait_for_completion parameter is TRUE, the destroy operation returns only after all requests in process have completed and all invocations of etherealize have completed. Otherwise, the destroy operation returns after destroying the POAs.
Note: This release of WLE does not support multithreading. Hence, wait_for_completion should not be TRUE if the call is made in the context of an object invocation. That is, the POA cannot start destroying itself if it is currently executing.
Note: This function is supported only for a joint client/server.
Return Values

None.

PortableServer::POA::find_POA

Synopsis

Returns a reference to a child POA with a given name.
C++ Binding

void find_POA( in string adapter_name, in boolean activate_it);

Argument

adapter_name
A reference to the target POA.
active_it
In this version of WLE, this parameter must be false.

Description

If the POA has a child POA with the specified name, that child POA is returned. If a child POA with the specified name does not exist and the value of the activate_it parameter is FALSE, the AdapterNonExistent exception is raised.
Return Values

None.
Exception

AdapterNonExistent
This exception is raised if the POA does not exist.

PortableServer::POA::reference_to_id

Synopsis

Returns the ObjectId value encapsulated by the specified reference.
C++ Binding

ObjectId reference_to_id(in Object reference);
Argument

reference
Specifies the reference to the object.

Description

This operation returns the ObjectId value encapsulated by the specified reference. This operation is valid only if the reference was created by the POA on which the operation is being performed. The object denoted by the reference does not have to be active for this operation to succeed.
Note: This function is supported only for a joint client/server.
Return Values

Returns the ObjectId value encapsulated by the specified reference.
Exceptions

WrongAdapter
This exception is raised if the reference was not created by that POA.

PortableServer::POA::the_POAManager

Synopsis

Identifies the POA manager associated with the POA.
C++ Binding

POAManager_ptr the_POAManager ();

Argument

None.

Description

This read-only attribute identifies the POA manager associated with the POA.
Note: This function is supported only for a joint client/server.
Return Values

None.
Example

poa->the_POAManager()->activate();

This statement will set the state of the POAManager for the given POA to active, which is required if the POA is to accept requests. Note that if the POA has a parent, that is, it is not the root POA, all of its parent's POAManagers must also be in the active state for this statement to have any effect.

PortableServer::ServantBase::_default_POA

Synopsis

Returns an object reference to the POA associated with the servant.
C++ Binding

class PortableServer { class ServantBase { public: virtual POA_ptr _default_POA(); }}
Argument

None.

Description

All C++ Servants inherit from PortableServer::ServantBase, so they all inherit the _default_POA function. In this version of WLE there is usually no reason to use _default_POA.
The default implementation of this function returns an object reference to the root POA of the default ORB in this process-the same as the return value of an invocation of ORB::resolve_initial_references("RootPOA"). A C++ Servant can override this definition to return thePOA of its choice, if desired.
Note: This function is supported only for joint client/servers.
Return Values

The default POA associated with the servant.
POA Current Member Functions

The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked.

PortableServer::Current::get_object_id

Synopsis

Returns the ObjectId identifying the object in whose context it is called.
C++ Binding

ObjectId * get_object_id ();

Arguments

None.

Description

This operation returns the PortableServer::ObjectId identifying the object in whose context it is called.
Note: This function is supported only for a joint client/server.
Return Values

This operation returns the ObjectId identifying the object in whose context it is called.
Exception

If called outside the context of a POA-dispatched operation, a PortableServer::NoContext exception is raised.

PortableServer::Current::get_POA

Synopsis

Returns a reference to the POA implementing the object in whose context it is called.
C++ Binding

POA_ptr get_POA ();

Argument

None.

Description

This operation returns a reference to the POA implementing the object in whose context it is called.
Note: This function is supported only for a joint client/server.
Return Values

This operation returns a reference to the POA implementing the object in whose context it is called.
Exceptions

If this operation is called outside the context of a POA-dispatched operation, a PortableServer::NoContext exception is raised.
POAManager Member Functions

Each POA object has an associated POAManager object. A POA manager may be associated with one or more POA objects. A POA manager encapsulates the processing state of the POAs with which it is associated. Using operations on the POA manager, an application can cause requests for those POAs to be queued or discarded, and can cause the POAs to be deactivated.
POA managers are created and destroyed implicitly. Unless an explicit POA manager object is provided at POA creation time, a POA manager is created when a POA is created and is automatically associated with that POA. A POA manager object is implicitly destroyed when all of its associated POAs have been destroyed.
A POA manager has four possible processing states: active, inactive, holding, and discarding. The processing state determines the capabilities of the associated POAs and the disposition of requests received by those POAs.
A POA manager is created in the holding state. In that state, any invocations on its POA are queued until the POA manager enters the active state. This version of WLE supports only the ability to enter active and inactive states. That is, this version does not support the ability to return to holding state or to enter discarding state.

PortableServer::POAManager::activate

Synopsis

Changes the state of the POA manager to active.
C++ Binding

void activate();

Argument

None.

Description

This operation changes the state of the POA manager to active. Entering the active state enables the associated POAs to process requests.
Note: All parent POAs must also have POAManagers in the active state for this POA to process requests.
Note: This function is supported only for a joint client/server.
Return Values

None.
Exceptions

If this operation is issued while the POA manager is in the inactive state, the PortableServer::POAManager::AdapterInactive exception is raised.

PortableServer::POAManager::deactivate

Synopsis

Changes the state of the POA manager to inactive.
C++ Binding

void deactivate ( CORBA::Boolean etherealize_objects, CORBA::Boolean wait_for_completion);

Argument

etherealize_objects
For WLE V4.2 software, this argument should always be set to FALSE.
wait_for_completion
If this argument is TRUE, the deactivate operation returns only after all requests in process have completed. If this argument is FALSE, the deactivate operation returns after changing the state of the associated POAs.

Description

This operation changes the state of the POA manager to inactive. Entering the inactive state causes the associated POAs to reject requests that have not begun to be executed, as well as any new requests.
Note: This release of WLE does not support multithreading. Hence, wait_for_completion should not be TRUE if the call is made in the context of an object invocation. That is, the POAManager cannot be set to inactive state if it is currently executing.
Note: This function is supported only for a joint client/server.
Return Values

None.
Exceptions

If issued while the POA manager is in the inactive state, the PortableServer::POAManager::AdapterInactive exception is raised.
POA Policy Member Objects

Interfaces derived from CORBA::Policy are used with the POA::create_POA operation to specify policies that apply to a POA. Policy objects are created using factory operations on any pre-existing POA, such as the root POA. Policy objects are specified when a POA is created. Policies may not be changed on an existing POA. Policies are not inherited from the parent POA.

PortableServer::LifespanPolicy

Synopsis

Specifies the life span of objects to the create_POA operation.
Description

Objects with the LifespanPolicy interface are obtained using the POA::create_lifespan_policy operation and are passed to the POA::create_POA operation to specify the life span of the objects implemented in the created POA. The following values can be supplied:

TRANSIENT-The objects implemented in the POA cannot outlive the process in which they are first created.

PERSISTENT-The objects implemented in the POA can outlive the process in which they are first created.

Persistent objects have a POA associated with them (the POA that created them). When the ORB receives a request on a persistent object, it searches for the matching POA, based on the names of the POA and all of its ancestors.
POA names must be unique within their enclosing scope (the parent POA). A portable program can assume that POA names used in other processes will not conflict with its own POA names.

If no LifespanPolicy object is passed to create_POA, the lifespan policy defaults to TRANSIENT.
Note: This function is supported only for a joint client/server.
Exceptions

None.

PortableServer::IdAssignmentPolicy

Synopsis

Specifies whether ObjectIds in the created POA are generated by the application or by the ORB.
Description

Objects with the IdAssignmentPolicy interface are obtained using the POA::create_id_assignment_policy operation and are passed to the POA::create_POA operation to specify whether ObjectIds in the created POA are generated by the application or by the ORB. The following values can be supplied:

USER_ID-objects created with that POA are assigned ObjectIds only by the application.

SYSTEM_ID-objects created with that POA are assigned ObjectIds only by the POA. If the POA also has the PERSISTENT policy, assigned ObjectIds must be unique across all instantiations of the same POA.

If no IdAssignmentPolicy is specified at POA creation, the default is SYSTEM_ID.
Note: This function is supported only for a joint client/server.
Request Member Functions

The mapping of these member functions to C++ is as follows:
// C++ class Request { public: Object_ptr target() const; const char *operation() const; NamedValue_ptr result(); NVList_ptr arguments(); Environment_ptr env(); ExceptionList_ptr exceptions(); ContextList_ptr contexts(); void ctx(Context_ptr); Context_ptr ctx() const
// argument manipulation helper functions Any &add_in_arg(); Any &add_in_arg(const char* name); Any &add_inout_arg(): Any &add_inout_arg(const char* name); Any &add_out_arg(): Any &add_out_arg(const char* name); void set_return_type(TypeCode_ptr tc); Any &return_value(); void invoke(); void send_oneway(); void send_deferred(); void get_response(); Boolean poll_response(); };
Note: The add_*_arg, set_return_type, and return_value member functions are added as shortcuts for using the attribute-based accessors.
The following sections describe these member functions.

CORBA::Request::arguments

Synopsis

Retrieves the argument list for the request.
C++ Binding

CORBA::NVList_ptr CORBA::Request::arguments () const;

Arguments

None.

Description

This member function retrieves the argument list for the request. The arguments can be input, output, or both.
Return Values

If the function succeeds, the value returned is a pointer to the list of arguments to the operation for the request. The returned argument list is owned by the Request object reference and should not be released.
If the function does not succeed, an exception is thrown.

CORBA::Request::ctx(Context_ptr)

Synopsis

Sets the Context object for the operation.
C++ Binding

void CORBA::Request::ctx (
CORBA::Context_ptr CtxObject);

Argument

CtxObject
The new value to which to set the Context object.

Description

This member function sets the Context object for the operation.
Return Values

None.
See Also

CORBA::Request::ctx()

CORBA::Request::get_response

Synopsis

Retrieves the response of a specific deferred synchronous request.
C++ Binding

void CORBA::Request::get_response ();

Arguments

None.
Description

This member function retrieves the response of a specific request; it is used after a call to the CORBA::Request::send_deferred function or the CORBA::Request::send_multiple_requests function. If the request has not completed, the CORBA::Request::get_response function blocks until it does complete.
Return Values

None.
See Also

CORBA::Request::send_deferred

CORBA::Request::invoke

Synopsis

Performs an invoke on the operation specified in the request.
C++ Binding

void CORBA::Request::invoke ();

Arguments

None.
Description

This member function calls the Object Request Broker (ORB) to send the request to the appropriate server application.
Return Values

None.

CORBA::Request::operation

Synopsis

Retrieves the operation intended for the request.
C++ Binding

const char * CORBA::Request::operation () const;

Arguments

None.
Description

This member function retrieves the operation intended for the request.
Return Values

If the function succeeds, the value returned is a pointer to the operation intended for the object; the value can be 0 (zero). The memory returned is owned by the Request object and should not be freed.
If the function does not succeed, an exception is thrown.

CORBA::Request::poll_response

Synopsis

Determines whether a deferred synchronous request has completed.
C++ Binding

CORBA::Boolean CORBA::Request::poll_response ();

Arguments

None.
Description

This member function determines whether the request has completed and returns immediately. You can use this call to check the state of the request. This member function can also be used to determine whether a call to CORBA::Request::get_response will block.
Return Values

If the function succeeds, the value returned is CORBA_TRUE if the response has already completed, and CORBA_FALSE if the response has not yet completed.
If the function does not succeed, an exception is thrown.
See Also

CORBA::ORB::get_next_response CORBA::ORB::poll_next_response CORBA::ORB::send_multiple_requests CORBA::Request::get_response CORBA::Request::send_deferred

CORBA::Request::result

Synopsis

Retrieves the result of the request.
C++ Binding

CORBA::NamedValue_ptr CORBA::Request::result ();

Arguments

None.
Description

This member function retrieves the result of the request.
Return Values

If the function succeeds, the value returned is a pointer to the result of the operation. The returned result is owned by the Request object and should not be released.
If the function does not succeed, an exception is thrown.

CORBA::Request::env

Synopsis

Retrieves the environment of the request.
C++ Binding

CORBA::Environment_ptr CORBA::Request::env ();

Arguments

None.
Description

This member function retrieves the environment of the request.
Return Values

If the function succeeds, the value returned is a pointer to the environment of the operation. The returned environment is owned by the Request object and should not be released.
If the function does not succeed, an exception is thrown.

CORBA::Request::ctx

Synopsis

Retrieves the context of the request.
C++ Binding

CORBA::context_ptr CORBA::Request::ctx ();

Arguments

None.
Description

This member function retrieves the context of the request.
Return Values

If the function succeeds, the value returned is a pointer to the context of the operation. The returned context is owned by the Request object and should not be released.
If the function does not succeed, an exception is thrown.

CORBA::Request::contexts

Synopsis

Retrieves the context lists for the request.
C++ Binding

CORBA::ContextList_ptr CORBA::Request::contexts ();

Arguments

None.
Description

This member function retrieves the context lists for the request.
Return Values

If the function succeeds, the value returned is a pointer to the context lists for the operation. The returned context list is owned by the Request object and should not be released.
If the function does not succeed, an exception is thrown.

CORBA::Request::exceptions

Synopsis

Retrieves the exception lists for the request.
C++ Binding

CORBA::ExceptionList_ptr CORBA::Request::exceptions ();

Arguments

None.
Description

This member function retrieves the exception lists for the request.
Return Values

If the function succeeds, the value returned is a pointer to the exception list for the request. The returned exception list is owned by the Request object and should not be released.
If the function does not succeed, an exception is thrown.

CORBA::Request::target

Synopsis

Retrieves the target object reference for the request.
C++ Binding

CORBA::Object_ptr CORBA::Request::target () const;

Arguments

None.
Description

This member function retrieves the target object reference for the request.
Return Values

If the function succeeds, the value returned is a pointer to the target object of the operation. The returned value is owned by the Request object and should not be released.
If the function does not succeed, an exception is thrown.

CORBA::Request::send_deferred

Synopsis

Initiates a deferred synchronous request.
C++ Binding

void CORBA::Request::send_deferred ();

Arguments

None.
Description

This member function initiates a deferred synchronous request. You use this function when a response is expected and in conjunction with the CORBA::Request::get_response function.
Return Values

None.
See Also

CORBA::ORB::get_next_response CORBA::ORB::poll_next_response CORBA::ORB::send_multiple_requests CORBA::Request::get_response CORBA::Request::poll_response CORBA::Request::send_oneway

CORBA::Request::send_oneway

Synopsis

Initiates a one-way request.
C++ Binding

void CORBA::Request::send_oneway ();

Arguments

None.
Description

This member function initiates a one-way request; it does not expect a response.
Return Values

None.
See Also

CORBA::ORB::send_multiple_requests CORBA::Request::send_deferred
Strings

The mapping of these functions to C++ is as follows:
// C++
namespace CORBA {
static char * string_alloc(ULong len);
static char * string_dup (const char *);
static void string_free(char *);
...
}

Note: A static array of char in C++ decays to a char*. Therefore, care must be taken when assigning a static array to a String_var, because the String_var assumes that the pointer points to data allocated via string_alloc, and thus eventually attempts to free it using string_free.

This behavior has changed in ANSI/ISO C++, where string literals are const char*, not char*. However, since most C++ compilers do not yet implement this change, portable programs must heed the advice given here.
The following sections describe the functions that manage memory allocated to strings.

CORBA::string_alloc

Synopsis

Allocates memory for a string.
C++ Binding

char * CORBA::string_alloc(ULong len);

Argument

len
The length of the string for which to allocate memory.

Description

This member function dynamically allocates memory for a string, or returns a Nil pointer if it cannot perform the allocation. It allocates len+1 characters so that the resulting string has enough space to hold a trailing NULL character. Free the memory allocated by this member function by calling the CORBA::string_free member function.
This function does not throw CORBA exceptions.
Return Values

If the function succeeds, the return value is a pointer to the newly allocated memory for the string object; if the function fails, the return value is a Nil pointer.
Example

char* s = CORBA::string_alloc(10);

See Also

CORBA::string_free CORBA::string_dup

CORBA::string_dup

Synopsis

Makes a copy of a string.
C++ Binding

char * CORBA::string_dup (const char * Str);

Argument

Str
The address of the string to be copied.

Description

This function dynamically allocates enough memory to hold a copy of its string argument, including the NULL character, copies the string argument into that memory, and returns a pointer to the new string.
This function does not throw CORBA exceptions.
Return Values

If the function succeeds, the return value is a pointer to the new string; if the function fails, the return value is a Nil pointer.
Example

char* s = CORBA::string_dup("hello world");

See Also

CORBA::string_free CORBA::string_alloc

CORBA::string_free

Synopsis

Frees memory allocated to a string.
C++ Binding

void CORBA::string_free(char * Str);

Argument

Str
The address of the memory to be deallocated.

Description

This member function deallocates memory that was previously allocated to a string using the CORBA::string_alloc() or CORBA::string_dup() member functions. Passing a Nil pointer to this function is acceptable and results in no action being performed.
This function may not throw CORBA exceptions.
Return Values

None.
Example

char* s = CORBA::string_dup("hello world");
CORBA::string_free(s);

See Also

CORBA::string_alloc CORBA::string_dup

TypeCode Member Functions

A TypeCode represents OMG IDL type information.
No constructors for TypeCodes are defined. However, in addition to the mapped interface, for each basic and defined OMG IDL type, an implementation provides access to a TypeCode pseudo-object reference (TypeCode_ptr) of the form _tc_<type> that may be used to set types in Any, as arguments for equal, and so on. In the names of these TypeCode reference constants, <type> refers to the local name of the type within its defining scope. Each C++ _tc_<type> constant is defined at the same scoping level as its matching type.
Like all other serverless objects, the C++ mapping for TypeCode provides a _nil() operation that returns a nil object reference for a TypeCode. This operation can be used to initialize TypeCode references embedded within constructed types. However, a nil TypeCode reference may never be passed as an argument to an operation, since TypeCodes are effectively passed as values, not as object references.
The mapping of these member functions to C++ is as follows:
class CORBA { class TypeCode { public: class Bounds { ... }; class BadKind { ... }; Boolean equal(TypeCode_ptr) const; TCKind kind() const; Long param_count() const; Any *parameter(Long) const; RepositoryId id () const; }; // TypeCode }; // CORBA
Memory Management

TypeCode has the following special memory management rule:

Ownership of the return values of the id function is maintained by the TypeCode; these return values must not be freed by the caller.

The following sections describe these member functions.

CORBA::TypeCode::equal

Synopsis

Determines whether two TypeCode objects are equal.
C++ Binding

CORBA::Boolean CORBA::TypeCode::equal (
CORBA::TypeCode_ptr TypeCodeObj) const;

Argument

TypeCodeObj
A pointer to a TypeCode object with which to make the comparison.

Description

This member function determines whether a TypeCode object is equal to the input parameter, TypeCodeObj.
Return Values

If the TypeCode object is equal to the TypeCodeObj parameter, CORBA_TRUE is returned.
If the TypeCode object is not equal to the TypeCodeObj parameter, CORBA_FALSE is returned.
If the function does not succeed, an exception is thrown.

CORBA::TypeCode::id

Synopsis

Returns the ID for the TypeCode.
C++ Binding

CORBA::RepositoryId CORBA::TypeCode::id () const;

Arguments

None.
Description

This member function returns the ID for the TypeCode.
Return Values

Repository ID for the TypeCode.

CORBA::TypeCode::kind

Synopsis

Retrieves the kind of data contained in the TypeCode object reference.
C++ Binding

CORBA::TCKind CORBA::TypeCode::kind () const;

Arguments

None.
Description

This member function retrieves the kind attribute of the CORBA::TypeCode class, which specifies the kind of data contained in the TypeCode object reference.
Return Values

If the member function succeeds, it returns the kind of data contained in the TypeCode object reference. For a list of the TypeCode kinds and their parameters, see Table 12-1.
If the member function does not succeed, an exception is thrown.

Table 12-1 Legal Typecode Kinds and Parameters

Typecode Kind Parameters List

CORBA::tk_null

*NONE*

CORBA::tk_void

*NONE*

CORBA::tk_short

*NONE*

CORBA::tk_long

*NONE*

CORBA::tk_long

*NONE*

CORBA::tk_ushort

*NONE*

CORBA::tk_ulong

*NONE*

CORBA::tk_float

*NONE*

CORBA::tk_double

*NONE*

CORBA::tk_boolean

*NONE*

CORBA::tk_char

*NONE*

CORBA::tk_octet

*NONE*

CORBA::tk_Typecode

*NONE*

CORBA::tk_Principal

*NONE*

CORBA::tk_objref

{interface_id}

CORBA::tk_struct

{struct-name, member-name, TypeCode, ... (repeat pairs)}

CORBA::tk_union

{union-name, switch-TypeCode, label-value, member-name, enum-id, ...}

CORBA::tk_enum

{enum-name, enum-id, ...}

CORBA::tk_string

{maxlen-integer}

CORBA::tk_sequence

{TypeCode, maxlen-integer}

CORBA::tk_array

{TypeCode, length-integer}

**Table 12-1 Legal Typecode Kinds and Parameters**
Typecode Kind	Parameters List
`CORBA::tk_null`	NONE
`CORBA::tk_void`	NONE
`CORBA::tk_short`	NONE
`CORBA::tk_long`	NONE
`CORBA::tk_long`	NONE
`CORBA::tk_ushort`	NONE
`CORBA::tk_ulong`	NONE
`CORBA::tk_float`	NONE
`CORBA::tk_double`	NONE
`CORBA::tk_boolean`	NONE
`CORBA::tk_char`	NONE
`CORBA::tk_octet`	NONE
`CORBA::tk_Typecode`	NONE
`CORBA::tk_Principal`	NONE
`CORBA::tk_objref`	{interface_id}
`CORBA::tk_struct`	{struct-name, member-name, TypeCode, ... (repeat pairs)}
`CORBA::tk_union`	{union-name, switch-TypeCode, label-value, member-name, enum-id, ...}
`CORBA::tk_enum`	{enum-name, enum-id, ...}
`CORBA::tk_string`	{maxlen-integer}
`CORBA::tk_sequence`	{TypeCode, maxlen-integer}
`CORBA::tk_array`	{TypeCode, length-integer}

CORBA::TypeCode::param_count

Synopsis

Retrieves the number of parameters for the TypeCode object reference.
C++ Binding

CORBA::Long CORBA::TypeCode::param_count () const;

Arguments

None.
Description

This member function retrieves the parameter attribute of the CORBA::TypeCode class, which specifies the number of parameters for the TypeCode object reference. For a list of parameters of each kind, see Table 12-1.
Return Values

If the function succeeds, it returns the number of parameters contained in the TypeCode object reference.
If the function does not succeed, an exception is thrown.

CORBA::TypeCode::parameter

Synopsis

Retrieves a parameter specified by the index input argument.
C++ Binding

CORBA::Any * CORBA::TypeCode::parameter (
CORBA::Long Index) const;

Argument

Index
An index to the parameter list, used to determine which parameter to retrieve.

Description

This member function retrieves a parameter specified by the index input argument. For a list of parameters of each kind, see Table 12-1.
Return Values

If the member function succeeds, the return value is a pointer to the parameter specified by the index input argument.
If the member function does not succeed, an exception is thrown.
Exception Member Functions

The WLE system supports the throwing and catching of exceptions.
Descriptions of exception member functions follow:

CORBA::SystemException::SystemException ()
This is the default constructor for the CORBA::SystemException class. Minor code is initialized to 0 (zero) and the completion status is set to COMPLETED_NO.
CORBA::SystemException::SystemException ( const CORBA::SystemException & Se)
This is the copy constructor for the CORBA::SystemException class.
CORBA::SystemException::SystemException( CORBA::ULong Minor, CORBA::CompletionStatus Status)
This constructor for the CORBA::SystemException class sets the minor code and completion status.
Explanations of the arguments are as follows:

Minor
The minor code for the Exception object. The minor field is an implementation-specific value used by the ORB to identify the exception. The WLE minor field definitions can be found in the file orbminor.h.
Status
The completion status for the Exception object. The values are as follows:
CORBA::COMPLETED_YES
CORBA::COMPLETED_NO
CORBA::COMPLETED_MAYBE

CORBA::SystemException::~SystemException ()
This is the destructor for the CORBA::SystemException class. It frees any memory used for the Exception object.
CORBA::SystemException CORBA::SystemException::operator = const CORBA::SystemException Se)
This assignment operator copies exception information from the source exception. The Se argument specifies the SystemException object that is to be copied by this operator.
CORBA::CompletionStatus CORBA::SystemException::completed()
This member function returns the completion status for this exception.
CORBA::SystemException::completed( CORBA::CompletionStatus Completed)
This member function sets the completion status for this exception. The Completed argument specifies the completion status for this exception.
CORBA::ULong CORBA::SystemException::minor()
This member function returns the minor code for this exception.
CORBA::SystemException::minor (CORBA::ULong Minor)
This member function sets the minor code for this exception. The minor argument specifies the new minor code for this exception. The minor field is an implementation-specific value used by the application to identify the exception.
CORBA::SystemException * CORBA::SystemException::_narrow ( CORBA::Exception_ptr Exc)
This member function determines whether a specified exception can be narrowed to a system exception. The Exc argument specifies the exception to be narrowed.
If the specified exception is a system exception, this member function returns a pointer to the system exception. If the specified exception is not a system exception, the function returns 0 (zero).
CORBA::UserException * CORBA::UserException::_narrow( CORBA::Exception_ptr Exc)
This member function determines whether a specified exception can be narrowed to a user exception. The Exc argument specifies the exception to be narrowed.
If the specified exception is a user exception, this member function returns a pointer to the user exception. If the specified exception is not a user exception, the function returns 0 (zero).

Standard Exceptions

This section presents the standard exceptions defined for the ORB. These exception identifiers may be returned as a result of any operation invocation, regardless of the interface specification. Standard exceptions are not listed in raises expressions.
To bound the complexity in handling the standard exceptions, the set of standard exceptions is kept to a tractable size. This constraint forces the definition of equivalence classes of exceptions, rather than enumerating many similar exceptions.
For example, an operation invocation can fail at many different points due to the inability to allocate dynamic memory. Rather than enumerate several different exceptions that correspond to the different ways that memory allocation failure causes the exception (during marshaling, unmarshaling, in the client, in the object implementation, allocating network packets, and so forth), a single exception corresponding to dynamic memory allocation failure is defined. Each standard exception includes a minor code to designate the subcategory of the exception; the assignment of values to the minor codes is left to each ORB implementation.
Each standard exception also includes a completion_status code, which takes one of the following values:

CORBA::COMPLETED_YES
The object implementation completed processing prior to the exception being raised.
CORBA::COMPLETED_NO
The object implementation was not initiated prior to the exception being raised.
CORBA::COMPLETED_MAYBE
The status of implementation completion is unknown.

Exception Definitions

The standard exceptions are defined below. Clients must be prepared to handle system exceptions that are not on this list, both because future versions of this specification may define additional standard exceptions, and because ORB implementations may raise nonstandard system exceptions. For more information about exceptions, see System Messages.
Table 12-2 defines the exceptions.

Table 12-2 Exception Definitions

Exception Description

CORBA::UNKNOWN

The unknown exception.

CORBA::BAD_PARAM

An invalid parameter was passed.

CORBA::NO_MEMORY

Dynamic memory allocation failure.

CORBA::IMP_LIMIT

Violated implementation limit.

CORBA::COMM_FAILURE

Communication failure.

CORBA::INV_OBJREF

Invalid object reference.

CORBA::NO_PERMISSION

No permission for attempted operation.

CORBA::INTERNAL

ORB internal error.

CORBA::MARSHAL

Error marshalling parameter/result.

CORBA::INITIALIZE

ORB initialization failure.

CORBA::NO_IMPLEMENT

Operation implementation unavailable.

CORBA::BAD_TYPECODE

Bad typecode.

CORBA::BAD_OPERATION

Invalid operation.

CORBA::NO_RESOURCES

Insufficient resources for request.

CORBA::NO_RESPONSE

Response to request not yet available.

CORBA::PERSIST_STORE

Persistent storage failure.

CORBA::BAD_INV_ORDER

Routine invocations out of order.

CORBA::TRANSIENT

Transient failure; reissue request.

CORBA::FREE_MEM

Cannot free memory.

CORBA::INV_IDENT

Invalid identifier syntax.

CORBA::INV_FLAG

Invalid flag was specified.

CORBA::INTF_REPOS

Error accessing interface repository.

CORBA::BAD_CONTEXT

Error processing context object.

CORBA::OBJ_ADAPTER

Failure detected by object adapter.

CORBA::DATA_CONVERSION

Data conversion error.

CORBA::OBJECT_NOT_EXIST

Non-existent object; delete reference.

CORBA::TRANSACTION_REQUIRED

Transaction required.

CORBA::TRANSACTION_ROLLEDBACK

Transaction rolled back.

CORBA::INVALID_TRANSACTION

Invalid transaction.

Object Nonexistence

The CORBA::OBJECT_NOT_EXIST exception is raised whenever an invocation on a deleted object is performed. It is an authoritative "hard" fault report. Anyone receiving it is allowed (even expected) to delete all copies of this object reference and to perform other appropriate "final recovery" style procedures.
Transaction Exceptions

The CORBA::TRANSACTION_REQUIRED exception indicates that the request carried a null transaction context, but an active transaction is required.
The CORBA::TRANSACTION_ROLLEDBACK exception indicates that the transaction associated with the request has already been rolled back or marked to roll back. Thus, the requested operation either could not be performed or was not performed because further computation on behalf of the transaction would be fruitless.
The CORBA::INVALID_TRANSACTION indicates that the request carried an invalid transaction context. For example, this exception could be raised if an error occurred when trying to register a resource.
ExceptionList Member Functions

The ExceptionList member functions allow a client or server application to provide a list of TypeCodes for all user-defined exceptions that may result when the Request is invoked. For a description of the Request member functions, see the section "Request Member Functions" on page 12-112.
The mapping of these member functions to C++ is as follows:
class CORBA { class ExceptionList { public: Ulong count (); void add(TypeCode_ptr tc); void add_consume(TypeCode_ptr tc); TypeCode_ptr item(Ulong index); Status remove(Ulong index); }; // ExceptionList }// CORBA

Table 12-2 **Exception Definitions**
Exception	Description
CORBA::UNKNOWN	The unknown exception.
CORBA::BAD_PARAM	An invalid parameter was passed.
CORBA::NO_MEMORY	Dynamic memory allocation failure.
CORBA::IMP_LIMIT	Violated implementation limit.
CORBA::COMM_FAILURE	Communication failure.
CORBA::INV_OBJREF	Invalid object reference.
CORBA::NO_PERMISSION	No permission for attempted operation.
CORBA::INTERNAL	ORB internal error.
CORBA::MARSHAL	Error marshalling parameter/result.
CORBA::INITIALIZE	ORB initialization failure.
CORBA::NO_IMPLEMENT	Operation implementation unavailable.
CORBA::BAD_TYPECODE	Bad typecode.
CORBA::BAD_OPERATION	Invalid operation.
CORBA::NO_RESOURCES	Insufficient resources for request.
CORBA::NO_RESPONSE	Response to request not yet available.
CORBA::PERSIST_STORE	Persistent storage failure.
CORBA::BAD_INV_ORDER	Routine invocations out of order.
CORBA::TRANSIENT	Transient failure; reissue request.
CORBA::FREE_MEM	Cannot free memory.
CORBA::INV_IDENT	Invalid identifier syntax.
CORBA::INV_FLAG	Invalid flag was specified.
CORBA::INTF_REPOS	Error accessing interface repository.
CORBA::BAD_CONTEXT	Error processing context object.
CORBA::OBJ_ADAPTER	Failure detected by object adapter.
CORBA::DATA_CONVERSION	Data conversion error.
CORBA::OBJECT_NOT_EXIST	Non-existent object; delete reference.
CORBA::TRANSACTION_REQUIRED	Transaction required.
CORBA::TRANSACTION_ROLLEDBACK	Transaction rolled back.
CORBA::INVALID_TRANSACTION	Invalid transaction.

CORBA::ExceptionList::count

Synopsis

Retrieves the current number of items in the list.
C++ Binding

Ulong count ();
Arguments

None.

Description

This member function retrieves the current number of items in the list.
Return Values

If the function succeeds, the returned value is the number of items in the list. If the list has just been created, and no ExceptionList objects have been added, this function returns 0 (zero).
Exception

If the function does not succeed, an exception is thrown.

CORBA::ExceptionList::add

Synopsis

Constructs a ExceptionList object with an unnamed item, setting only the flags attribute.
C++ Binding

void add(TypeCode_ptr tc);
Arguments

tc
Defines the memory location referred to by TypeCode_ptr.

Description

This member function constructs an ExceptionList object with an unnamed item, setting only the flags attribute.
The ExceptionList object grows dynamically; your application does not need to track its size.
Return Values

If the function succeeds, the return value is a pointer to the newly created ExceptionList object.
Exception

If the member function does not succeed, a CORBA::NO_MEMORY exception is thrown.
See Also

CORBA::ExceptionList::add_consume CORBA::ExceptionList::count CORBA::ExceptionList::item CORBA::ExceptionList::remove

CORBA::ExceptionList::add_consume

Synopsis

Constructs an ExceptionList object.
C++ Binding

void add_consume(TypeCode_ptr tc);
Arguments

tc
The memory location to be assumed.

Description

This member function constructs an ExceptionList object.
The ExceptionList object grows dynamically; your application does not need to track its size.
Return Values

If the function succeeds, the return value is a pointer to the newly created ExceptionList object.
Exceptions

If the member function does not succeed, an exception is raised.
See Also

CORBA::ExceptionList::add CORBA::ExceptionList::count CORBA::ExceptionList::item CORBA::ExceptionList::remove

CORBA::ExceptionList::item

Synopsis

Retrieves a pointer to the ExceptionList object, based on the index passed in.
C++ Binding

TypeCode_ptr item(ULong index);
Argument

index
The index into the ExceptionList object. The indexing is zero-based.

Description

This member function retrieves a pointer to an ExceptionList object, based on the index passed in. The function uses zero-based indexing.
Return Values

If the function succeeds, the return value is a pointer to the ExceptionList object.
Exceptions

If the function does not succeed, the BAD_PARAM exception is thrown.
See Also

CORBA::ExceptionList::add CORBA::ExceptionList::add_consume CORBA::ExceptionList::count CORBA::ExceptionList::remove

CORBA::ExceptionList::remove

Synopsis

Removes the item at the specified index, frees any associated memory, and reorders the remaining items on the list.
C++ Binding

Status remove(ULong index);
Argument

Index
The index into the ContextList object. The indexing is zero-based.

Description

This member function removes the item at the specified index, frees any associated memory, and reorders the remaining items on the list.
Return Values

None.
Exceptions

If the function does not succeed, the BAD_PARAM exception is thrown.
See Also

CORBA::ExceptionList::add CORBA::ExceptionList::add_consume CORBA::ExceptionList::count CORBA::ExceptionList::item

Copyright � 1999 BEA Systems, Inc. All Rights Reserved.
Required browser version: Netscape Communicator version 4.0 or higher, or Microsoft Internet Explorer version 4.0 or higher.
Last update: July 06, 1999.