.TH corba 3 "orber  3.6.9" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
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
.TP
Types
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
.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 Local Typechecking 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\&.

.nf
Example: 
          
  corba:create(\&'StackModule_Stack\&', "IDL:StackModule/Stack:1\&.0",
               {10, test})
        
.fi
.RE
.LP
.B
dispose(Object) -> ok
.br
.RS
.TP
Types
Object = #objref
.br
.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
.TP
Types
Object = #objref representing NIL\&.
.br
.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
.TP
Types
Object = #objref
.br
Key = term()
.br
Result = #objref
.br
.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
.TP
Types
Object = #objref
.br
Result = #binary
.br
.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
.TP
Types
Object = #objref
.br
Result = #pid | {error, Reason} | {\&'EXCEPTION\&', E}
.br
.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
.TP
Types
Exception = record()
.br
.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
.TP
Types
To = client reference
.br
Reply = IDL type
.br
.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
.TP
Types
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_verify | ssl_client_depth | ssl_client_certfile | ssl_client_cacertfile | ssl_client_password | ssl_client_keyfile | ssl_client_ciphers | ssl_client_cachetimeout
.br
Value = allowed value associated with the given key
.br
Object = #objref
.br
.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 configuration\&.
.RE
.LP
.B
add_initial_service(ObjectId, Object) -> boolean()
.br
.RS
.TP
Types
ObjectId = string()
.br
Object = #objref
.br
.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 Interoperable Naming Service\&. Returns \fIfalse\fR if the given id already exists\&.
.RE
.LP
.B
remove_initial_service(ObjectId) -> boolean()
.br
.RS
.TP
Types
ObjectId = string()
.br
.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
.TP
Types
ObjectId = string()
.br
.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
.TP
Types
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_verify | ssl_client_depth | ssl_client_certfile | ssl_client_cacertfile | ssl_client_password | ssl_client_keyfile | ssl_client_ciphers | ssl_client_cachetimeout
.br
Value = allowed value associated with the given key
.br
Object = #objref
.br
.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 configuration\&.
.SS Warning:
.LP
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
.TP
Types
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_verify | ssl_client_depth | ssl_client_certfile | ssl_client_cacertfile | ssl_client_password | ssl_client_keyfile | ssl_client_ciphers | ssl_client_cachetimeout
.br
Value = allowed value associated with the given key
.br
ObjectId = string()
.br
.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 configuration\&.
.SS Warning:
.LP
This operation is not supported by most ORB\&'s\&. Hence, avoid using it\&.

.RE
.LP
.B
object_to_string(Object) -> IOR_string
.br
.RS
.TP
Types
Object = #objref
.br
IOR_string = string()
.br
.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
.TP
Types
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_verify | ssl_client_depth | ssl_client_certfile | ssl_client_cacertfile | ssl_client_password | ssl_client_keyfile | ssl_client_ciphers | ssl_client_cachetimeout
.br
Value = allowed value associated with the given key
.br
Object = #objref
.br
.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 configuration\&.
.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
.TP
Types
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
.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
.TP
Types
Object = NewObject = local #objref
.br
Host = string()
.br
Port = integer()
.br
.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

.SS Note:
.LP
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
.TP
Types
KeyValueList = [{Key, Value}]
.br
Key = any key listed in the configuration chapter
.br
Value = allowed value associated with the given key
.br
.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 configuration settings in the User\&'s Guide\&.
.RE