| Previous | Table of Contents | Next |
When creating type definition objects in an Interface Repository, types are specified in terms of object references, and the
TypeCodes describing them are generated automatically.
In some situations, such as bridges between ORBs, TypeCodes need to be constructed outside of any Interface Repository. This
can be done using operations on the ORB pseudo-object.
module CORBA {interface ORB {// other operations ...
TypeCode create_struct_tc ( in RepositoryId id; in Identifier name, in StructMemberSeq members
);
TypeCode create_union_tc ( in RepositoryId id, in Identifier name, in TypeCode discriminator_type, in UnionMemberSeq members
);
TypeCode create_enum_tc ( in RepositoryId id, in Identifier name, in EnumMemberSeq members
);
TypeCode create_alias_tc ( in RepositoryId id, in Identifier name, in TypeCode original_type
);
TypeCode create_exception_tc ( in RepositoryId id, in Identifier name, in StructMemberSeq members
);
TypeCode create_interface_tc (
| in RepositoryId | id, | ||||
| in Identifier | name | ||||
| ); |
TypeCode create_string_tc (
in unsigned long bound );
TypeCode create_wstring_tc (
in unsigned long bound );
TypeCode create_fixed_tc (
in unsigned short digits,
in unsigned short scale );
TypeCode create_sequence_tc (
in unsigned long bound,
in TypeCode element_type );
TypeCode create_recursive_sequence_tc (// deprecated
in unsigned long bound,
in unsigned long offset );
TypeCode create_array_tc (
in unsigned long length,
in TypeCode element_type );
TypeCode create_value_tc (
in RepositoryId id,
in Identifier name,
in ValueModifier type_modifier,
in TypeCode concrete_base,
in ValueMemberSeq members );
TypeCode create_value_box_tc (
in RepositoryId id,
in Identifier name,
in TypeCode boxed_type );
TypeCode create_native_tc (
in RepositoryId id,
in Identifier name );
TypeCode create_recursive_tc( in RepositoryId id );
TypeCode create_abstract_interface_tc( in RepositoryId id, in Identifier name
);
TypeCode create_local_interface_tc( in RepositoryId id, in Identifier name
);
TypeCode create_component_tc ( in RepositoryId id, in Identifier name
);
TypeCode create_home_tc ( in RepositoryId id, in Identifier name
);
TypeCode create_event_tc (
| in RepositoryId | id, | ||||
| in Identifier | name, | ||||
| in ValueModifier | type_modifier, | ||||
| in TypeCode | concrete_base, | ||||
| in ValueMemberSeq | members | ||||
| ); | |||||
| }; | |||||
| }; |
Most of these operations are similar to corresponding IR operations for creating type definitions. TypeCodes are used here
instead of IDLType object references to refer to other types. In the StructMember, UnionMember and ValueMember structures,
only the type is used, and the type_def should be set to nil.
Typecode creation operations that take name as an argument shall check that the name is a valid IDL name or is a empty string.
If not, they shall raise the BAD_PARAM exception with standard minor code 15. Operations that take a RepositoryId argument
shall check that the argument passed in is a string of the form <format>:<string> and if not, then raise a BAD_PARAM exception
with standard minor code 16. Operations that take content or member types as arguments shall check that they are legitimate
(i.e., that they don’t have kinds tk_null, tk_void or tk_exception). If not, they shall raise the BAD_TYPECODE exception with
standard minor code 2. Operations that take members shall check that the member names are valid IDL names and that they are
unique within the member list, and if the name is found to be incorrect, they shall raise a BAD_PARAM with standard minor
code 17.
The create_union_tc operation shall check that there are no duplicate label values. It shall also check that each label TypeCode
compares equivalent to the discriminator TypeCode. If a duplicate label is found, raise BAD_PARAM with standard minor code
18. If the TypeCode of a label is not equivalent to the TypeCode of the discriminator (other than the octet TypeCode to indicate
the default label), the operation shall raise BAD_PARAM with standard minor code 19. The create_union_tc operation shall also
check that the supplied discriminator type is legitimate, and if the check fails, raise BAD_PARAM with standard minor code
20.
Note: The create_recursive_sequence_tc operation is deprecated. No new code should make use of this operation. Its functionality
is subsumed by the new operation create_recursive_tc. The create_recursive_sequence_tc operation will be removed from a future
revision of the standard.
The create_recursive_sequence_tc operation is used to create TypeCodes describing recursive sequences that are members of
structs or unions. The result of this operation should be used as the typecode in the StructMemberSeq or UnionMemberSeq arguments
of the create_struct_tc or create_union_tc operations. The offset parameter specifies which enclosing struct or union is the
target of the recursion, with the value 1 indicating the most immediate enclosing struct or union, and larger values indicating
successive enclosing struct or unions. For example, the offset would be 1 for the following IDL structure:
struct foo {
long value;
sequence <foo> chain;
};
Once the recursive sequence TypeCode has been properly embedded in its enclosing TypeCodes, it will function as a normal sequence
TypeCode. Invoking operations on the recursive sequence TypeCode before it has been embedded in the required number of enclosing
TypeCodes will result in undefined behavior. Attempt to marshal incomplete typecodes shall raise the BAD_TYPECODE exception
with standard minor code 1. Attempt to use an incomplete TypeCode as a parameter of any operation when detected shall cause
the BAD_PARAM exception to be raised with standard minor code 13.
For create_value_tc operation, the concrete_base parameter is a TypeCode for the immediate concrete valuetype base of the
valuetype for which the TypeCode is being created. If the valuetype does not have a concrete base, the concrete_base parameter
is a nil TypeCode reference.
The create_recursive_tc operation is used to create a recursive TypeCode, which serves as a place holder for a concrete TypeCode
during the process of creating TypeCodes that contain recursion. The id parameter specifies the repository id of the type
for which the recursive TypeCode is serving as a place holder. Once the recursive TypeCode has been properly embedded in the
enclosing TypeCode, which corresponds to the specified repository id, it will function as a normal TypeCode.
Invoking operations on the recursive TypeCode before it has been embedded in the enclosing TypeCode will result in undefined
behavior. For example, the following IDL type declarations contain recursion:
struct foo { long value; sequence<foo> chain;
};
valuetype V { public V member; };
To create a TypeCode for valuetype V, you would invoke the TypeCode creation operations as shown below:
// C++ TypeCode_var recursive_tc = orb->create_recursive_tc(“IDL:V:1.0?);
ValueMemberSeq v_seq; v_seq.length(1); v_seq[0].name = string_dup(“member?); v_seq[0].type = recursive_tc; v_seq[0].access = PUBLIC_MEMBER; TypeCode_var v_val_tc
= orb->create_value_tc(“IDL:V:1.0?, “V?, VM_NONE, TypeCode::_nil(), v_seq);
For create_event_tc operation, the concrete_base parameter is a TypeCode for the immediate concrete base of the eventtype
for which the TypeCode is being created. If the eventtype does not have a concrete base, the concrete_base parameter is a
nil TypeCode reference.
4.12 Exceptions
The terms “system? and “user? exception are defined in this section. Further the terms “standard system exception? and “standard
user exception? are defined, and then a list of “standard system exceptions? is provided.
4.12.1 Definition of Terms
In general the following terms should be used consistently in all OMG standards documents to refer to exceptions:
Standard Exception: Any exception that is defined in an OMG Standard.
System Exception: Clients must be prepared to handle these exceptions even though they are not declared in a raises clause.
These exceptions cannot appear in a raises clause. These have the structure defined in section 3.17.2 “System Exception,?
and they are of type SYSTEM_EXCEPTION (see PIDL below).
Standard System Exception: A System Exception that is part of the CORBA Standard as enumerated in section 3.17. (e.g., BAD_PARAM).
These are enumerated in Section 3.17.2 “Standard System Exceptions.?
Non-Standard System Exceptions: System exceptions that are proprietary to a particular vendor/implementation.
User Exception: Exceptions that can be raised only by those operations that explicitly declare them in the raises clause of
their signature. These exceptions are of type USER_EXCEPTION (see IDL below).
Standard User Exception: Any User Exception that is defined in a published OMG standard (e.g., WrongTransaction). These are
documented in the documentation of individual interfaces.
Non-standard User Exception: User exceptions that are not defined in any published OMG specification.
4.12.2 System Exceptions
In order to bound the complexity in handling the standard exceptions, the set of standard exceptions should be 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 corresponding to the different ways that memory allocation failure causes the
exception (during marshaling, unmarshaling, in the client, in the object implementation, allocating network packets), a single
exception corresponding to dynamic memory allocation failure is defined.
module CORBA { const unsigned long OMGVMCID = 0x4f4d0000;
#define ex_body {unsigned long minor; completion_status completed;}
enum completion_status { COMPLETED_YES, COMPLETED_NO, COMPLETED_MAYBE
};
enum exception_type {NO_EXCEPTION,USER_EXCEPTION, SYSTEM_EXCEPTION
}; };
Each system exception includes a minor code to designate the subcategory of the exception.
Minor exception codes are of type unsigned long and consist of a 20-bit “Vendor Minor Codeset ID?(VMCID), which occupies the
high order 20 bits, and the minor code which occupies the low order 12 bits.
The standard minor codes for the standard system exceptions are prefaced by the VMCID assigned to OMG, defined as the unsigned
long constant CORBA::OMGVMCID, which has the VMCID allocated to OMG occupying the high order 20 bits. The minor exception
codes associated with the standard exceptions that
are found in Appendix A, Section A.5, “Exception Codes? are or-ed with
OMGVMCID to get the minor code value that is returned in the ex_body
structure (see Section
4.12.3, “Standard System Exception Definitions? on page 4-66 and Section 4.12.4,
“Standard Minor Exception Codes? on page 4-73).
Within a vendor assigned space, the assignment of values to minor codes is left to the vendor. Vendors may request allocation
of VMCIDs by sending email to tag-request@omg.org.
The VMCID 0 and 0xfffff are reserved for experimental use. The VMCID OMGVMCID (
Section 4.12.3, “Standard System Exception Definitions? on page 4-66) and
1 through 0xf are reserved for OMG use.
Each standard system exception also includes a completion_status code that takes one of the values {COMPLETED_YES, COMPLETED_NO,
COMPLETED_MAYBE}. These have the following meanings:
COMPLETED_YESCOMPLETED_NOCOMPLETED_MAYBE |
The object implementation has completed processing prior to the exception being raised. |
||||
| The object implementation was never initiated prior to the exception being raised. | |||||
| The status of implementation completion is indeterminate. |
Client applications must be prepared to handle system exceptions other than the
standard system exception defined below in Section 4.12.3, “Standard System
Exception Definitions? on page 4-66, both because future versions of this specification
may define additional standard system exceptions, and because ORB implementations may raise non-standard system exceptions.
Vendors may define non-standard system exceptions, but these exceptions are discouraged because they are non-portable. A non-standard
system exception, when passed to an ORB that does not recognize it, shall be presented by that ORB as an UNKNOWN standard
system exception. The completion status shall be preserved in the UNKNOWN exception, and the minor code shall be set to standard
value 2 for system exception and standard value 1 for user exception.
Non-standard system exceptions shall have the same structure as of standard standard
system exceptions as specified in section Section 4.12.3, “Standard System Exception
Definitions? on page 4-66 (i.e., they have
the same ex_body). They also shall follow the same language mappings as standard system exceptions. Although they are PIDL,
vendors should ensure that their names do not clash with any other names following the normal naming and scoping rules as
they apply to regular IDL exceptions.
4.12.3 Standard System Exception Definitions
The standard system exceptions are defined in this section.
module CORBA { // PIDL
exception UNKNOWN ex_body; // the unknown exception exception BAD_PARAM ex_body; // an invalid parameter was passed exception
NO_MEMORY ex_body; // dynamic memory allocation failure exception IMP_LIMIT ex_body; // violated implementation limit exception
COMM_FAILURE ex_body; // communication failure exception INV_OBJREF ex_body;
// invalid object reference exception NO_PERMISSION ex_body; // no permission for attempted op. exception INTERNAL ex_body;
// ORB internal error exception MARSHAL ex_body; // error marshaling param/result exception INITIALIZE ex_body; // ORB initialization
failure exception NO_IMPLEMENT ex_body; // operation implementation unavailable exception BAD_TYPECODE ex_body; // bad typecode
exception BAD_OPERATION ex_body; // invalid operation exception NO_RESOURCES ex_body; // insufficient resources for req. exception
NO_RESPONSE ex_body; // response to req. not yet available exception PERSIST_STORE ex_body; // persistent storage failure
exception BAD_INV_ORDER ex_body; // routine invocations out of order exception TRANSIENT ex_body; // transient failure - reissue
request exception FREE_MEM ex_body; // cannot free memory exception INV_IDENT ex_body; // invalid identifier syntax exception
INV_FLAG ex_body; // invalid flag was specified exception INTF_REPOS ex_body; // error accessing interface repository exception
BAD_CONTEXT ex_body; // error processing context object exception OBJ_ADAPTER ex_body; // failure detected by object adapter
exception DATA_CONVERSION ex_body; // data conversion error exception OBJECT_NOT_EXIST ex_body; // non-existent object, delete
reference exception TRANSACTION_REQUIRED ex_body; // transaction required exception TRANSACTION_ROLLEDBACK x_body; // transaction
rolled back exception INVALID_TRANSACTION ex_body; // invalid transaction exception INV_POLICY ex_body; // invalid policy
exception CODESET_INCOMPATIBLE ex_body; // incompatible code set
exception REBIND ex_body; // rebind needed exception TIMEOUT ex_body; // operation timed out exception TRANSACTION_UNAVAILABLE
ex_body; // no transaction exception TRANSACTION_MODE ex_body; // invalid transaction mode exception BAD_QOS ex_body; // bad
quality of service exception INVALID_ACTIVITY ex_body; // bad quality of service exception ACTIVITY_COMPLETED ex_body; //
bad quality of service exception ACTIVITY_REQUIRED ex_body; // bad quality of service };
4.12.3.1 UNKNOWN
This exception is raised if an operation implementation throws a non-CORBA exception (such as an exception specific to the
implementation's programming language), or if an operation raises a user exception that does not appear in the operation's
raises expression. UNKNOWN is also raised if the server returns a system exception that is unknown to the client. (This can
happen if the server uses a later version of CORBA than the client and new system exceptions have been added to the later
version.)
4.12.3.2 BAD_PARAM
A parameter passed to a call is out of range or otherwise considered illegal. An ORB may raise this exception if null values
or null pointers are passed to an operation (for language mappings where the concept of a null pointers or null values applies).
BAD_PARAM can also be raised as a result of client generating requests with incorrect parameters using the DII.
4.12.3.3 NO_MEMORY
The ORB run time has run out of memory.
4.12.3.4 IMP_LIMIT
This exception indicates that an implementation limit was exceeded in the ORB run time. For example, an ORB may reach the
maximum number of references it can hold simultaneously in an address space, the size of a parameter may have exceeded the
allowed maximum, or an ORB may impose a maximum on the number of clients or servers that can run simultaneously.
4.12.3.5 COMM_FAILURE
This exception is raised if communication is lost while an operation is in progress, after the request was sent by the client,
but before the reply from the server has been returned to the client.
4.12.3.6 INV_OBJREF
This exception indicates that an object reference is internally malformed. For example, the repository ID may have incorrect
syntax or the addressing information may be invalid.
An ORB may choose to detect calls via nil references (but is not obliged to detect them). INV_OBJREF is used to indicate this.
If the client invokes an operation that results in an attempt by the client ORB to marshal wchar or wstring data for an in
parameter (or to unmarshal wchar or wstring data for an in/out parameter, out parameter or the return value), and the associated
object reference does not contain a codeset component, the INV_OBJREF standard system exception is raised.
4.12.3.7 NO_PERMISSION
An invocation failed because the caller has insufficient privileges.
4.12.3.8 INTERNAL
This exception indicates an internal failure in an ORB, for example, if an ORB has detected corruption of its internal data
structures.
4.12.3.9 MARSHAL
A request or reply from the network is structurally invalid. This error typically indicates a bug in either the client-side
or server-side run time. For example, if a reply from the server indicates that the message contains 1000 bytes, but the actual
message is shorter or longer than 1000 bytes, the ORB raises this exception. MARSHAL can also be caused by using the DII or
DSI incorrectly, for example, if the type of the actual parameters sent does not agree with IDL signature of an operation.
4.12.3.10 INITIALIZE
An ORB has encountered a failure during its initialization, such as failure to acquire networking resources or detecting a
configuration error.
4.12.3.11 NO_IMPLEMENT
This exception indicates that even though the operation that was invoked exists (it has an IDL definition), no implementation
for that operation exists. NO_IMPLEMENT can, for example, be raised by an ORB if a client asks for an object's type definition
from the interface repository, but no interface repository is provided by the ORB.
4.12.3.12 BAD_TYPECODE
The ORB has encountered a malformed type code (for example, a type code with an invalid TCKind value).
4.12.3.13 BAD_OPERATION
This indicates that an object reference denotes an existing object, but that the object does not support the operation that
was invoked.
4.12.3.14 NO_RESOURCES
The ORB has encountered some general resource limitation. For example, the run time may have reached the maximum permissible
number of open connections.
4.12.3.15 NO_RESPONSE
This exception is raised if a client attempts to retrieve the result of a deferred synchronous call, but the response for
the request is not yet available.
4.12.3.16 PERSIST_STORE
This exception indicates a persistent storage failure, for example, failure to establish a database connection or corruption
of a database.
4.12.3.17 BAD_INV_ORDER
This exception indicates that the caller has invoked operations in the wrong order. For example, it can be raised by an ORB
if an application makes an ORB-related call without having correctly initialized the ORB first.
4.12.3.18 TRANSIENT
TRANSIENT indicates that the ORB attempted to reach an object and failed. It is not an indication that an object does not
exist. Instead, it simply means that no further determination of an object's status was possible because it could not be reached.
This exception is raised if an attempt to establish a connection fails, for example, because the server or the implementation
repository is down.
4.12.3.19 FREE_MEM
The ORB failed in an attempt to free dynamic memory, for example because of heap corruption or memory segments being locked.
4.12.3.20 INV_IDENT
This exception indicates that an IDL identifier is syntactically invalid. It may be raised if, for example, an identifier
passed to the interface repository does not conform to IDL identifier syntax, or if an illegal operation name is used with
the DII.
4.12.3.21 INV_FLAG
An invalid flag was passed to an operation (for example, when creating a DII request).
4.12.3.22 INTF_REPOS
An ORB raises this exception if it cannot reach the interface repository, or some other failure relating to the interface
repository is detected.
4.12.3.23 BAD_CONTEXT
An operation may raise this exception if a client invokes the operation but the passed context does not contain the context
values required by the operation.
4.12.3.24 OBJ_ADAPTER
This exception typically indicates an administrative mismatch. For example, a server may have made an attempt to register
itself with an implementation repository under a name that is already in use, or is unknown to the repository. OBJ_ADAPTER
is also raised by the POA to indicate problems with application-supplied servant managers.
4.12.3.25 DATA_CONVERSION
This exception is raised if an ORB cannot convert the representation of data as marshaled into its native representation or
vice-versa. For example, DATA_CONVERSION can be raised if wide character codeset conversion fails, or if an ORB cannot convert
floating point values between different representations.
4.12.3.26 OBJECT_NOT_EXIST
The OBJECT_NOT_EXIST exception is raised whenever an invocation on a deleted object was 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.
Bridges forward this exception to clients, also destroying any records they may hold (for example, proxy objects used in reference
translation). The clients could in turn purge any of their own data structures.
4.12.3.27 TRANSACTION_REQUIRED
The TRANSACTION_REQUIRED exception indicates that the request carried a null transaction context, but an active transaction
is required.
4.12.3.28 TRANSACTION_ROLLEDBACK
The 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.
4.12.3.29 INVALID_TRANSACTION
The 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.
4.12.3.30 INV_POLICY
INV_POLICY is raised when an invocation cannot be made due to an incompatibility between Policy overrides that apply to the
particular invocation.
4.12.3.31 CODESET_INCOMPATIBLE
This exception is raised whenever meaningful communication is not possible between client and server native code sets. See
Section 13.7.2.6, “Code Set Negotiation,? on page 13-34.
4.12.3.32 REBIND
REBIND is raised when there is a problem in carrying out a requested or implied
attempt to rebind an object reference (Section 22.2.1.2, “interface RebindPolicy? on
page 22-5).
4.12.3.33 TIMEOUT
TIMEOUT is raised when no delivery has been made and the specified time-to-live period has been exceeded. It is a standard
system exception because time-to-live QoS can be applied to any invocation.
4.12.3.34 TRANSACTION_UNAVAILABLE
TRANSACTION_UNAVAILABLE exception is raised by the ORB when it cannot process a transaction service context because its connection
to the Transaction Service has been abnormally terminated.
4.12.3.35 TRANSACTION_MODE
TRANSACTION_MODE exception is raised by the ORB when it detects a mismatch between the TransactionPolicy in the IOR and the
current transaction mode.
4.12.3.36 BAD_QOS
The BAD_QOS exception is raised whenever an object cannot support the quality of service required by an invocation parameter
that has a quality of service semantics associated with it.
4.12.3.37 INVALID_ACTIVITY
The INVALID_ACTIVITY system exception may be raised on the Activity or Transaction services’ resume methods if a transaction
or Activity is resumed in a context different to that from which it was suspended. It is also raised when an attempted invocation
is made that is incompatible with the Activity’s current state.
4.12.3.38 ACTIVITY_COMPLETED
The ACTIVITY_COMPLETED system exception may be raised on any method for which Activity context is accessed. It indicates that
the Activity context in which the method call was made has been completed due to a timeout of either the Activity itself or
a transaction that encompasses the Activity, or that the Activity completed in a manner other than that originally requested.
4.12.3.39 ACTIVITY_REQUIRED
The ACTIVITY_REQUIRED system exception may be raised on any method for which an Activity context is required. It indicates
that an Activity context was necessary to perform the invoked operation, but one was not found associated with the calling
thread.
4.12.4 Standard Minor Exception Codes
Please refer to Appendix A for a table that specifies standard minor exception codes that have been assigned for the standard
system exceptions.