.TH corba 3erl "orber 3.6.24" "Ericsson AB" "Erlang Module Definition"
.SH NAME
corba \- The functions on CORBA module level
.SH DESCRIPTION
.LP
This module contains functions that are specified on the CORBA module level\&. It also contains some functions for creating and disposing objects\&.
.SH EXPORTS
.LP
.B
create(Module, TypeID) -> Object
.br
.B
create(Module, TypeID, Env) -> Object
.br
.B
create(Module, TypeID, Env, Optons1) -> Object
.br
.B
create_link(Module, TypeID) -> Object
.br
.B
create_link(Module, TypeID, Env) -> Object
.br
.B
create_link(Module, TypeID, Env, Options2) -> Reply
.br
.RS
.LP
Types:

.RS 3
Module = atom()
.br
TypeID = string()
.br
Env = term()
.br
Options1 = [{persistent, Bool} | {regname, RegName} | {local_typecheck, Bool}]
.br
Options2 = [{sup_child, Bool} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool}]
.br
RegName = {local, atom()} | {global, term()}
.br
Reply = #objref | {ok, Pid, #objref}
.br
Bool = true | false
.br
Object = #objref
.br
.RE
.RE
.RS
.LP
These functions start a new server object\&. If you start it without \fIRegName\fR\& it can only be accessed through the returned object key\&. Started with a \fIRegName\fR\& the name is registered locally or globally\&.
.LP
\fITypeID\fR\& is the repository ID of the server object type and could for example look like "IDL:StackModule/Stack:1\&.0"\&.
.LP
\fIModule\fR\& is the name of the interface API module\&.
.LP
\fIEnv\fR\& is the arguments passed which will be passed to the implementations \fIinit\fR\& call-back function\&.
.LP
A server started with create/2, create/3 or create/4 does not care about the parent, which means that the parent is not handled explicitly in the generic process part\&.
.LP
A server started with create_link2, create_link/3 or create_link/4 is initially linked to the caller, the parent, and it will terminate whenever the parent process terminates, and with the same reason as the parent\&. If the server traps exits, the terminate/2 call-back function is called in order to clean up before the termination\&. These functions should be used if the server is a worker in a supervision tree\&.
.LP
If you use the option \fI{sup_child, true}\fR\& create_link/4 will return \fI{ok, Pid, #objref}\fR\&, otherwise \fI#objref\fR\&, and make it possible to start a server as a supervisor child (stdlib-1\&.7 or later)\&.
.LP
If you use the option \fI{persistent, true}\fR\& you also must use the option \fI{regname, {global, Name}}\fR\&\&. This combination makes it possible to tell the difference between a server permanently terminated or in the process of restarting\&.
.LP
The option \fI{pseudo, true}\fR\&, allow us to create an object which is not a server\&. Using \fI{pseudo, true}\fR\& overrides all other start options\&. For more information see section \fIModule_Interface\fR\&\&.
.LP
If a server is started using the option \fI{persistent, true}\fR\& the object key will not be removed unless it terminates with reason \fInormal\fR\& or \fIshutdown\fR\&\&. Hence, if persistent servers is used as supervisor children they should be \fItransient\fR\& and the \fIobjectkeys_gc_time\fR\& should be modified (default equals \fIinfinity\fR\&)\&.
.LP
The option \fI{local_typecheck, boolean()}\fR\&, which overrides the \fBLocal Typechecking\fR\& environment flag, turns on or off typechecking\&. If activated, parameters, replies and raised exceptions will be checked to ensure that the data is correct, when invoking operations on CORBA Objects within the same Orber domain\&. Due to the extra overhead, this option \fIMAY ONLY\fR\& be used during testing and development\&.
.LP
.nf

Example: 

  corba:create('StackModule_Stack', "IDL:StackModule/Stack:1.0", {10, test})
        
.fi
.RE

.LP
.B
dispose(Object) -> ok
.br
.RS
.LP
Types:

.RS 3
Object = #objref
.br
.RE
.RE
.RS
.LP
This function is used for terminating the execution of a server object\&. Invoking this operation on a NIL object reference, e\&.g\&., the return value of \fIcorba:create_nil_objref/0\fR\&, always return ok\&. For valid object references, invoking this operation more than once, will result in a system exception\&.
.RE

.LP
.B
create_nil_objref() -> Object
.br
.RS
.LP
Types:

.RS 3
Object = #objref representing NIL\&.
.br
.RE
.RE
.RS
.LP
Creates an object reference that represents the NIL value\&. Attempts to invoke operations using the returned object reference will return a system exception\&.
.RE

.LP
.B
create_subobject_key(Object, Key) -> Result
.br
.RS
.LP
Types:

.RS 3
Object = #objref
.br
Key = term()
.br
Result = #objref
.br
.RE
.RE
.RS
.LP
This function is used to create a subobject in a server object\&. It can for example be useful when one wants unique access to separate rows in a mnesia or an ETS table\&. The \fIResult\fR\& is an object reference that will be seen as a unique reference to the outside world but will access the same server object where one can use the \fIget_subobject_key/1\fR\& function to get the private key value\&.
.LP
\fIKey\fR\& is stored in the object reference \fIObject\fR\&\&. If it is a binary it will be stored as is and otherwise it is converted to a binary before storage\&.
.RE

.LP
.B
get_subobject_key(Object) -> Result
.br
.RS
.LP
Types:

.RS 3
Object = #objref
.br
Result = #binary
.br
.RE
.RE
.RS
.LP
This function is used to fetch a subobject key from the object reference \fIObject\fR\&\&. The result is a always a binary, if it was an Erlang term that was stored with \fIcreate_subobject_key/2\fR\& one can to do \fIbinary_to_term/1\fR\& to get the real value\&.
.RE

.LP
.B
get_pid(Object) -> Result
.br
.RS
.LP
Types:

.RS 3
Object = #objref
.br
Result = #pid | {error, Reason} | {\&'EXCEPTION\&',E}
.br
.RE
.RE
.RS
.LP
This function is to get the process id from an object, which is a must when CORBA objects is started/handled in a supervisor tree\&. The function will throw exceptions if the key is not found or some other error occurs\&.
.RE

.LP
.B
raise(Exception)
.br
.RS
.LP
Types:

.RS 3
Exception = record()
.br
.RE
.RE
.RS
.LP
This function is used for raising corba exceptions as an Erlang user generated exit signal\&. It will throw the tuple \fI{\&'EXCEPTION\&', \fR\&\fIException\fR\&\fI}\fR\&\&.
.RE

.LP
.B
reply(To, Reply) -> true
.br
.RS
.LP
Types:

.RS 3
To = client reference
.br
Reply = IDL type
.br
.RE
.RE
.RS
.LP
This function can be used by a CORBA object to explicitly send a reply to a client that invoked a two-way operation\&. If this operation is used, it is \fInot\fR\& possible to return a reply in the call-back module\&. 
.br
\fITo\fR\& must be the \fIFrom\fR\& argument provided to the callback function, which requires that the IC option \fIfrom\fR\& was used when compiling the IDL-file\&.
.RE

.LP
.B
resolve_initial_references(ObjectId) -> Object
.br
.B
resolve_initial_references(ObjectId, Contexts) -> Object
.br
.RS
.LP
Types:

.RS 3
ObjectId = string()
.br
Contexts = [Context]
.br
Context = #\&'IOP_ServiceContext\&'{context_id = CtxId, context_data = CtxData}
.br
CtxId = ?ORBER_GENERIC_CTX_ID
.br
CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}
.br
Interface = string()
.br
Options = [{Key, Value}]
.br
Key = ssl_client_options
.br
Value = allowed value associated with the given key
.br
Object = #objref
.br
.RE
.RE
.RS
.LP
This function returns the object reference associated with the given object id\&. Initially, only \fI"NameService"\fR\& is available\&. To add or remove services use \fIadd_initial_service/2\fR\& or \fIremove_initial_service/1\fR\&\&.
.LP
The \fIconfiguration\fR\& context is used to override the global SSL client side \fBconfiguration\fR\&\&.
.RE

.LP
.B
add_initial_service(ObjectId, Object) -> boolean()
.br
.RS
.LP
Types:

.RS 3
ObjectId = string()
.br
Object = #objref
.br
.RE
.RE
.RS
.LP
This operation allows us to add initial services, which can be accessed by using \fIresolve_initial_references/1\fR\& or the \fIcorbaloc\fR\& schema\&. If using an Id defined by the OMG, the given object must be of the correct type; for more information see the \fBInteroperable Naming Service\fR\&\&. Returns \fIfalse\fR\& if the given id already exists\&.
.RE

.LP
.B
remove_initial_service(ObjectId) -> boolean()
.br
.RS
.LP
Types:

.RS 3
ObjectId = string()
.br
.RE
.RE
.RS
.LP
If we don not want a certain service to be accessible, invoking this function will remove the association\&. Returns \fItrue\fR\& if able to terminate the binding\&. If no such binding existed \fIfalse\fR\& is returned\&.
.RE

.LP
.B
list_initial_services() -> [ObjectId]
.br
.RS
.LP
Types:

.RS 3
ObjectId = string()
.br
.RE
.RE
.RS
.LP
This function returns a list of allowed object id\&'s\&.
.RE

.LP
.B
resolve_initial_references_remote(ObjectId, Address) -> Object
.br
.B
resolve_initial_references_remote(ObjectId, Address, Contexts) -> Object
.br
.RS
.LP
Types:

.RS 3
ObjectId = string()
.br
Address = [RemoteModifier]
.br
RemoteModifier = string()
.br
Contexts = [Context]
.br
Context = #\&'IOP_ServiceContext\&'{context_id = CtxId, context_data = CtxData}
.br
CtxId = ?ORBER_GENERIC_CTX_ID
.br
CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}
.br
Interface = string()
.br
Options = [{Key, Value}]
.br
Key = ssl_client_options
.br
Value = allowed value associated with the given key
.br
Object = #objref
.br
.RE
.RE
.RS
.LP
This function returns the object reference for the object id asked for\&. The remote modifier string has the following format: \fI"iiop://host:port"\fR\&\&.
.LP
The \fIconfiguration\fR\& context is used to override the global SSL client side \fBconfiguration\fR\&\&.
.LP

.RS -4
.B
Warning:
.RE
This operation is not supported by most ORB\&'s\&. Hence, use \fIcorba:string_to_object/1\fR\& instead\&.

.RE

.LP
.B
list_initial_services_remote(Address) -> [ObjectId]
.br
.B
list_initial_services_remote(Address, Contexts) -> [ObjectId]
.br
.RS
.LP
Types:

.RS 3
Address = [RemoteModifier]
.br
RemoteModifier = string()
.br
Contexts = [Context]
.br
Context = #\&'IOP_ServiceContext\&'{context_id = CtxId, context_data = CtxData}
.br
CtxId = ?ORBER_GENERIC_CTX_ID
.br
CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}
.br
Interface = string()
.br
Options = [{Key, Value}]
.br
Key = ssl_client_options
.br
Value = allowed value associated with the given key
.br
ObjectId = string()
.br
.RE
.RE
.RS
.LP
This function returns a list of allowed object id\&'s\&. The remote modifier string has the following format: \fI"iiop://host:port"\fR\&\&.
.LP
The \fIconfiguration\fR\& context is used to override the global SSL client side \fBconfiguration\fR\&\&.
.LP

.RS -4
.B
Warning:
.RE
This operation is not supported by most ORB\&'s\&. Hence, avoid using it\&.

.RE

.LP
.B
object_to_string(Object) -> IOR_string
.br
.RS
.LP
Types:

.RS 3
Object = #objref
.br
IOR_string = string()
.br
.RE
.RE
.RS
.LP
This function returns the object reference as the external string representation of an IOR\&.
.RE

.LP
.B
string_to_object(IOR_string) -> Object
.br
.B
string_to_object(IOR_string, Contexts) -> Object
.br
.RS
.LP
Types:

.RS 3
IOR_string = string()
.br
Contexts = [Context]
.br
Context = #\&'IOP_ServiceContext\&'{context_id = CtxId, context_data = CtxData}
.br
CtxId = ?ORBER_GENERIC_CTX_ID
.br
CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}
.br
Interface = string()
.br
Options = [{Key, Value}]
.br
Key = ssl_client_options
.br
Value = allowed value associated with the given key
.br
Object = #objref
.br
.RE
.RE
.RS
.LP
This function takes a \fIcorbaname\fR\&, \fIcorbaloc\fR\& or an IOR on the external string representation and returns the object reference\&.
.LP
To lookup the NameService reference, simply use \fI"corbaloc:iiop:1\&.2@123\&.0\&.0\&.012:4001/NameService"\fR\&
.LP
We can also resolve an object from the NameService by using \fI"corbaname:iiop:1\&.2@123\&.0\&.0\&.012:4001/NameService#org/Erlang/MyObj"\fR\&
.LP
For more information about \fIcorbaname\fR\& and \fIcorbaloc\fR\&, see the User\&'s Guide (Interoperable Naming Service)\&.
.LP
The \fIconfiguration\fR\& context is used to override the global SSL client side \fBconfiguration\fR\&\&.
.LP
How to handle the interface context is further described in the User\&'s Guide\&.
.RE

.LP
.B
print_object(Data [, Type]) -> ok | {\&'EXCEPTION\&', E} | {\&'EXIT\&', R} | string()
.br
.RS
.LP
Types:

.RS 3
Data = IOR_string | #objref (local or external) | corbaloc/corbaname string
.br
Type = IoDevice | error_report | {error_report, Reason} | info_msg | {info_msg, Comment} | string
.br
IoDevice = see the io-module
.br
Reason = Comment = string()
.br
.RE
.RE
.RS
.LP
The object represented by the supplied data is dissected and presented in a more readable form\&. The Type parameter is optional; if not supplied standard output is used\&. For \fIerror_report\fR\& and \fIinfo_msg\fR\& the \fIerror_logger\fR\& module is used, with or without Reason or Comment\&. If the atom \fIstring\fR\& is supplied this function will return a flat list\&. The \fIIoDevice\fR\& is passed to the operation \fIio:format/2\fR\&\&.
.LP
If the supplied object is a local reference, the output is equivalent to an object exported from the node this function is invoked on\&.
.RE

.LP
.B
add_alternate_iiop_address(Object, Host, Port) -> NewObject | {\&'EXCEPTION\&', E}
.br
.RS
.LP
Types:

.RS 3
Object = NewObject = local #objref
.br
Host = string()
.br
Port = integer()
.br
.RE
.RE
.RS
.LP
This operation creates a new instance of the supplied object containing an ALTERNATE_IIOP_ADDRESS component\&. Only the new instance contains the new component\&. When this object is passed to another ORB, which supports the ALTERNATE_IIOP_ADDRESS, requests will be routed to the alternate address if it is not possible to communicate with the main address\&.
.LP
The ALTERNATE_IIOP_ADDRESS component requires that IIOP-1\&.2 is used\&. Hence, make sure both Orber and the other ORB is correctly configured\&.
.LP

.LP

.RS -4
.B
Note:
.RE
Make sure that the given \fIObject\fR\& is accessible via the alternate Host/port\&. For example, if the object is correctly started as \fIlocal\fR\& or \fIpseudo\fR\&, the object should be available on all nodes within a multi-node Orber installation\&. Since only one instance exists for other object types, it will not be possible to access it if the node it was started on terminates\&.

.RE

.LP
.B
orb_init(KeyValueList) -> ok | {\&'EXIT\&', Reason}
.br
.RS
.LP
Types:

.RS 3
KeyValueList = [{Key, Value}]
.br
Key = any key listed in the configuration chapter
.br
Value = allowed value associated with the given key
.br
.RE
.RE
.RS
.LP
This function allows the user to configure Orber in, for example, an Erlang shell\&. Orber may \fINOT\fR\& be started prior to invoking this operation\&. For more information, see \fBconfiguration settings\fR\& in the User\&'s Guide\&.
.RE