<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
</legalnotice>
<title>corba</title>
<prepared></prepared>
<responsible></responsible>
<docno></docno>
<approved></approved>
<checked></checked>
<date>1997-06-10</date>
<rev>A</rev>
</header>
<module>corba</module>
<modulesummary>The functions on CORBA module level</modulesummary>
<description>
<p>This module contains functions that are specified on the CORBA module
level. It also contains some functions for creating and disposing
objects.</p>
</description>
<funcs>
<func>
<name>create(Module, TypeID) -> Object</name>
<name>create(Module, TypeID, Env) -> Object</name>
<name>create(Module, TypeID, Env, Optons1) -> Object</name>
<name>create_link(Module, TypeID) -> Object</name>
<name>create_link(Module, TypeID, Env) -> Object</name>
<name>create_link(Module, TypeID, Env, Options2) -> Reply</name>
<fsummary>Create and start a new server object</fsummary>
<type>
<v>Module = atom()</v>
<v>TypeID = string()</v>
<v>Env = term()</v>
<v>Options1 = [{persistent, Bool} | {regname, RegName} | {local_typecheck, Bool}]</v>
<v>Options2 = [{sup_child, Bool} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool}]</v>
<v>RegName = {local, atom()} | {global, term()}</v>
<v>Reply = #objref | {ok, Pid, #objref}</v>
<v>Bool = true | false</v>
<v>Object = #objref</v>
</type>
<desc>
<p>These functions start a new server object. If you start it
without <em>RegName</em> it can only be accessed through the
returned object key. Started with a <em>RegName</em> the name is
registered locally or globally. </p>
<p><em>TypeID</em> is the repository ID of the server object type and
could for example look like "IDL:StackModule/Stack:1.0". </p>
<p><em>Module</em> is the name of the interface API module. </p>
<p><em>Env</em> is the arguments passed which will be passed to the
implementations <em>init</em> call-back function.</p>
<p>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. </p>
<p>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.</p>
<p>If you use the option <c>{sup_child, true}</c> create_link/4 will return
<c>{ok, Pid, #objref}</c>, otherwise <c>#objref</c>, and make it possible
to start a server as a supervisor child (stdlib-1.7 or later).</p>
<p>If you use the option <c>{persistent, true}</c> you also must use the option
<c>{regname, {global, Name}}</c>. This combination makes it possible to tell
the difference between a server permanently terminated or in the process of restarting.</p>
<p>The option <c>{pseudo, true}</c>, allow us to create an object which is not a
server. Using <c>{pseudo, true}</c> overrides all other start options.
For more information see section <c>Module_Interface</c>.</p>
<p>If a server is started using the option <c>{persistent, true}</c> the object key
will not be removed unless it terminates with reason <em>normal</em> or <em>shutdown</em>.
Hence, if persistent servers is used as supervisor children they should be <em>transient</em>
and the <em>objectkeys_gc_time</em> should be modified (default equals <c>infinity</c>).</p>
<p>The option <c>{local_typecheck, boolean()}</c>, which overrides the
<seealso marker="ch_install#flags">Local Typechecking</seealso>
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
<em>MAY ONLY</em> be used during testing and development.</p>
<code type="none">
Example:
corba:create('StackModule_Stack', "IDL:StackModule/Stack:1.0", {10, test})
</code>
</desc>
</func>
<func>
<name>dispose(Object) -> ok</name>
<fsummary>Stop a server object</fsummary>
<type>
<v>Object = #objref</v>
</type>
<desc>
<p>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 <c>corba:create_nil_objref/0</c>, always
return ok. For valid object references, invoking this operation
more than once, will result in a system exception.</p>
</desc>
</func>
<func>
<name>create_nil_objref() -> Object</name>
<fsummary>Stop a server object</fsummary>
<type>
<v>Object = #objref representing NIL.</v>
</type>
<desc>
<p>Creates an object reference that represents the NIL value.
Attempts to invoke operations using the returned object reference
will return a system exception.</p>
</desc>
</func>
<func>
<name>create_subobject_key(Object, Key) -> Result</name>
<fsummary>Add an Erlang term to a private key field</fsummary>
<type>
<v>Object = #objref</v>
<v>Key = term()</v>
<v>Result = #objref</v>
</type>
<desc>
<p>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 <em>Result</em> 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 <em>get_subobject_key/1</em> function to get the private
key value.</p>
<p><em>Key</em> is stored in the object reference <em>Object</em>.
If it is a binary it will be stored as is and otherwise it is
converted to a binary before storage.</p>
</desc>
</func>
<func>
<name>get_subobject_key(Object) -> Result</name>
<fsummary>Fetch the contents of the private key field</fsummary>
<type>
<v>Object = #objref</v>
<v>Result = #binary</v>
</type>
<desc>
<p>This function is used to fetch a subobject key from the object
reference <em>Object</em>. The result is a always a binary, if it
was an Erlang term that was stored with <em>create_subobject_key/2</em>
one can to do <em>binary_to_term/1</em> to get the real value. </p>
</desc>
</func>
<func>
<name>get_pid(Object) -> Result</name>
<fsummary>Get the process id from an object key</fsummary>
<type>
<v>Object = #objref</v>
<v>Result = #pid | {error, Reason} | {'EXCEPTION',E}</v>
</type>
<desc>
<p>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.</p>
</desc>
</func>
<func>
<name>raise(Exception)</name>
<fsummary>Generate an Erlang throw</fsummary>
<type>
<v>Exception = record()</v>
</type>
<desc>
<p>This function is used for raising corba exceptions as an
Erlang user generated exit signal. It will throw the tuple
<c>{'EXCEPTION', </c><em>Exception</em><c>}</c>.</p>
</desc>
</func>
<func>
<name>reply(To, Reply) -> true</name>
<fsummary>Send explicit reply to client</fsummary>
<type>
<v>To = client reference</v>
<v>Reply = IDL type</v>
</type>
<desc>
<p>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 <em>not</em> possible to return a reply in the call-back
module.
<br></br>
<em>To</em> must be the <em>From</em> argument provided to the
callback function, which requires that the IC option <em>from</em>
was used when compiling the IDL-file.</p>
</desc>
</func>
<func>
<name>resolve_initial_references(ObjectId) -> Object</name>
<name>resolve_initial_references(ObjectId, Contexts) -> Object</name>
<fsummary>Return the object reference for the given object id</fsummary>
<type>
<v>ObjectId = string()</v>
<v>Contexts = [Context]</v>
<v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v>
<v>CtxId = ?ORBER_GENERIC_CTX_ID</v>
<v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v>
<v>Interface = string()</v>
<v>Options = [{Key, Value}]</v>
<v>Key = ssl_client_options</v>
<v>Value = allowed value associated with the given key</v>
<v>Object = #objref</v>
</type>
<desc>
<p>This function returns the object reference associated with the given
object id. Initially, only <c>"NameService"</c> is available. To add or remove
services use <c>add_initial_service/2</c> or <c>remove_initial_service/1</c>.</p>
<p>The <em>configuration</em> context is used to override the global
SSL client side
<seealso marker="ch_install#config">configuration</seealso>.</p>
</desc>
</func>
<func>
<name>add_initial_service(ObjectId, Object) -> boolean()</name>
<fsummary>Add a new initial service and associate it with the given id</fsummary>
<type>
<v>ObjectId = string()</v>
<v>Object = #objref</v>
</type>
<desc>
<p>This operation allows us to add initial services, which can be accessed by
using <c>resolve_initial_references/1</c> or the <c>corbaloc</c> schema.
If using an Id defined by the OMG, the given object must be of the
correct type; for more information see the
<seealso marker="ch_naming_service#interop_ns">Interoperable Naming Service</seealso>.
Returns <c>false</c> if the given id already exists.</p>
</desc>
</func>
<func>
<name>remove_initial_service(ObjectId) -> boolean()</name>
<fsummary>Remove association between the given id and service</fsummary>
<type>
<v>ObjectId = string()</v>
</type>
<desc>
<p>If we don not want a certain service to be accessible, invoking this function
will remove the association. Returns <c>true</c> if able to terminate the
binding. If no such binding existed <c>false</c> is returned.</p>
</desc>
</func>
<func>
<name>list_initial_services() -> [ObjectId]</name>
<fsummary>Return a list of supported object id's</fsummary>
<type>
<v>ObjectId = string()</v>
</type>
<desc>
<p>This function returns a list of allowed object id's.</p>
</desc>
</func>
<func>
<name>resolve_initial_references_remote(ObjectId, Address) -> Object</name>
<name>resolve_initial_references_remote(ObjectId, Address, Contexts) -> Object</name>
<fsummary>Return the object reference for the given object id</fsummary>
<type>
<v>ObjectId = string()</v>
<v>Address = [RemoteModifier]</v>
<v>RemoteModifier = string()</v>
<v>Contexts = [Context]</v>
<v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v>
<v>CtxId = ?ORBER_GENERIC_CTX_ID</v>
<v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v>
<v>Interface = string()</v>
<v>Options = [{Key, Value}]</v>
<v>Key = ssl_client_options</v>
<v>Value = allowed value associated with the given key</v>
<v>Object = #objref</v>
</type>
<desc>
<p>This function returns the object reference for the object id asked
for.
The remote modifier string has the following format:
<c>"iiop://host:port"</c>.</p>
<p>The <em>configuration</em> context is used to override the global
SSL client side
<seealso marker="ch_install#config">configuration</seealso>.</p>
<warning>
<p>This operation is not supported by most ORB's. Hence, use
<c>corba:string_to_object/1</c> instead.</p>
</warning>
</desc>
</func>
<func>
<name>list_initial_services_remote(Address) -> [ObjectId]</name>
<name>list_initial_services_remote(Address, Contexts) -> [ObjectId]</name>
<fsummary>Return a list of supported object id's</fsummary>
<type>
<v>Address = [RemoteModifier]</v>
<v>RemoteModifier = string()</v>
<v>Contexts = [Context]</v>
<v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v>
<v>CtxId = ?ORBER_GENERIC_CTX_ID</v>
<v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v>
<v>Interface = string()</v>
<v>Options = [{Key, Value}]</v>
<v>Key = ssl_client_options</v>
<v>Value = allowed value associated with the given key</v>
<v>ObjectId = string()</v>
</type>
<desc>
<p>This function returns a list of allowed object id's. The remote modifier
string has the following format: <c>"iiop://host:port"</c>.</p>
<p>The <em>configuration</em> context is used to override the global
SSL client side
<seealso marker="ch_install#config">configuration</seealso>.</p>
<warning>
<p>This operation is not supported by most ORB's. Hence, avoid
using it.</p>
</warning>
</desc>
</func>
<func>
<name>object_to_string(Object) -> IOR_string</name>
<fsummary>Convert the object reference to the external string representation</fsummary>
<type>
<v>Object = #objref</v>
<v>IOR_string = string()</v>
</type>
<desc>
<p>This function returns the object reference as the external string
representation of an IOR.</p>
</desc>
</func>
<func>
<name>string_to_object(IOR_string) -> Object</name>
<name>string_to_object(IOR_string, Contexts) -> Object</name>
<fsummary>Convert the external string representation to an object reference</fsummary>
<type>
<v>IOR_string = string()</v>
<v>Contexts = [Context]</v>
<v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v>
<v>CtxId = ?ORBER_GENERIC_CTX_ID</v>
<v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v>
<v>Interface = string()</v>
<v>Options = [{Key, Value}]</v>
<v>Key = ssl_client_options</v>
<v>Value = allowed value associated with the given key</v>
<v>Object = #objref</v>
</type>
<desc>
<p>This function takes a <c>corbaname</c>, <c>corbaloc</c> or an IOR on the
external string representation and returns the object reference.</p>
<p>To lookup the NameService reference, simply use
<c>"corbaloc:iiop:[email protected]:4001/NameService"</c></p>
<p>We can also resolve an object from the NameService by using
<c>"corbaname:iiop:[email protected]:4001/NameService#org/Erlang/MyObj"</c></p>
<p>For more information about <c>corbaname</c> and <c>corbaloc</c>, see
the User's Guide (Interoperable Naming Service).</p>
<p>The <em>configuration</em> context is used to override the global
SSL client side
<seealso marker="ch_install#config">configuration</seealso>.</p>
<p>How to handle the interface context is further described in the User's Guide.</p>
</desc>
</func>
<func>
<name>print_object(Data [, Type]) -> ok | {'EXCEPTION', E} | {'EXIT', R} | string()</name>
<fsummary>Print the supplied object</fsummary>
<type>
<v>Data = IOR_string | #objref (local or external) | corbaloc/corbaname string</v>
<v>Type = IoDevice | error_report | {error_report, Reason} | info_msg | {info_msg, Comment} | string</v>
<v>IoDevice = see the io-module</v>
<v>Reason = Comment = string()</v>
</type>
<desc>
<p>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 <c>error_report</c> and <c>info_msg</c>
the <c>error_logger</c> module is used, with or without Reason or Comment.
If the atom <c>string</c> is supplied this function will return a flat
list. The <c>IoDevice</c> is passed to the operation <c>io:format/2</c>.</p>
<p>If the supplied object is a local reference, the output is equivalent
to an object exported from the node this function is invoked on.</p>
</desc>
</func>
<func>
<name>add_alternate_iiop_address(Object, Host, Port) -> NewObject | {'EXCEPTION', E}</name>
<fsummary>Add ALTERNATE_IIOP_ADDRESS component to the supplied local object</fsummary>
<type>
<v>Object = NewObject = local #objref</v>
<v>Host = string()</v>
<v>Port = integer()</v>
</type>
<desc>
<p>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.</p>
<p>The ALTERNATE_IIOP_ADDRESS component requires that IIOP-1.2 is used.
Hence, make sure both Orber and the other ORB is correctly configured.</p>
<p></p>
<note>
<p>Make sure that the given <c>Object</c> is accessible via the
alternate Host/port. For example, if the object is correctly started as
<c>local</c> or <c>pseudo</c>, 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.</p>
</note>
</desc>
</func>
<func>
<name>orb_init(KeyValueList) -> ok | {'EXIT', Reason}</name>
<fsummary>Configure Orber before starting it</fsummary>
<type>
<v>KeyValueList = [{Key, Value}]</v>
<v>Key = any key listed in the configuration chapter</v>
<v>Value = allowed value associated with the given key</v>
</type>
<desc>
<p>This function allows the user to configure Orber in, for example,
an Erlang shell. Orber may <em>NOT</em> be started prior to invoking
this operation. For more information, see
<seealso marker="ch_install#config">configuration settings</seealso>
in the User's Guide.</p>
</desc>
</func>
</funcs>
</erlref>
