aboutsummaryrefslogtreecommitdiffstats
path: root/lib/orber/doc/src/orber.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/orber/doc/src/orber.xml')
-rw-r--r--lib/orber/doc/src/orber.xml689
1 files changed, 689 insertions, 0 deletions
diff --git a/lib/orber/doc/src/orber.xml b/lib/orber/doc/src/orber.xml
new file mode 100644
index 0000000000..da5fd05f98
--- /dev/null
+++ b/lib/orber/doc/src/orber.xml
@@ -0,0 +1,689 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</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>orber</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date>1997-06-10</date>
+ <rev>A</rev>
+ </header>
+ <module>orber</module>
+ <modulesummary>The main module of the Orber application</modulesummary>
+ <description>
+ <p>This module contains the functions for starting and stopping the
+ application. It also has some utility functions to get some of
+ the configuration information from running application.</p>
+ </description>
+ <funcs>
+ <func>
+ <name>start() -> ok</name>
+ <name>start(Type) -> ok</name>
+ <fsummary>Start the Orber application</fsummary>
+ <type>
+ <v>Type = temporary | permanent</v>
+ </type>
+ <desc>
+ <p>Starts the Orber application (it also starts mnesia if it is not running).
+ Which <c>Type</c> parameter is supplied determines the behavior. If not
+ supplied Orber is started as <c>temporary</c>.
+ See the Reference Manual <em>application(3)</em> for further information. </p>
+ </desc>
+ </func>
+ <func>
+ <name>jump_start(Attributes) -> ok | {'EXIT', Reason}</name>
+ <fsummary>Start the Orber application during tests</fsummary>
+ <type>
+ <v>Attributes = Port | Options</v>
+ <v>Port = integer()</v>
+ <v>Options = [{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>Installs and starts the Orber and the Mnesia applications with the configuration
+ parameters <c>domain</c> and <c>iiop_port</c> set to <c>"IP-number:Port"</c>
+ and the supplied Port respectively. Theses settings are in most cases
+ sufficient to ensure that no clash with any other Orber instance occur.
+ If this operation fails, check if the listen port (iiop_port) is already
+ in use. This function <em>MAY ONLY</em> be used during development and
+ tests; how Orber is configured when using this operation may change
+ at any time without warning.</p>
+ </desc>
+ </func>
+ <func>
+ <name>stop() -> ok</name>
+ <fsummary>Stop the Orber application</fsummary>
+ <desc>
+ <p>Stops the Orber application.</p>
+ </desc>
+ </func>
+ <func>
+ <name>info() -> ok</name>
+ <name>info(IoType) -> ok | {'EXIT', Reason} | string()</name>
+ <fsummary>Generate Info Report, which contain Orber's configuration settings</fsummary>
+ <type>
+ <v>IoType = info_msg | string | io | {io, IoDevice}</v>
+ </type>
+ <desc>
+ <p>Generates an Info Report, which contain Orber's configuration settings.
+ If no <c>IoType</c> is supplied, <c>info_msg</c> is used (see the
+ error_logger documentation). When the atom string is supplied this
+ function will return a flat list. For <c>io</c> and <c>{io, IoDevice}</c>,
+ <c>io:format/1</c> and <c>io:format/3</c> is used respectively.</p>
+ </desc>
+ </func>
+ <func>
+ <name>exception_info(Exception) -> {ok, string()} | {error, Reason}</name>
+ <fsummary>Return a printable string, which describes the supplied exception</fsummary>
+ <desc>
+ <p>Returns a printable string, which describes the supplied exception
+ in greater detail. Note, this function is mainly intended for
+ system exceptions.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_system_exception(Exception) -> true | false</name>
+ <fsummary>Return true if the supplied exception is a system defined exception otherwise false</fsummary>
+ <desc>
+ <p>Returns true if the supplied exception is a system defined
+ exception, otherwise false.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_tables() -> [Tables]</name>
+ <fsummary>Get the Mnesia tables Orber uses.</fsummary>
+ <desc>
+ <p>Returns a list of the Orber specific Mnesia tables. This list is
+ required to restore Mnesia if it has been partitioned.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_ORBInitRef() -> string() | undefined</name>
+ <fsummary>Get the initial reference address.</fsummary>
+ <desc>
+ <p>This function returns undefined if we will resolve references locally,
+ otherwise a string describing which host we will contact if the Key given
+ to <c>corba:resolve_initial_references/1</c> matches the Key set
+ in this configuration variable. For more information
+ see the user's guide.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_ORBDefaultInitRef() -> string() | undefined</name>
+ <fsummary>Get the initial reference address.</fsummary>
+ <desc>
+ <p>This function returns undefined if we will resolve references locally,
+ otherwise a string describing which host, or hosts, from which we
+ will try to resolve the Key given to
+ <c>corba:resolve_initial_references/1</c>. For more information
+ see the user's guide.</p>
+ </desc>
+ </func>
+ <func>
+ <name>domain() -> string()</name>
+ <fsummary>Display the Orber domain name</fsummary>
+ <desc>
+ <p>This function returns the domain name of the current Orber domain
+ as a string.</p>
+ </desc>
+ </func>
+ <func>
+ <name>iiop_port() -> int()</name>
+ <fsummary>Display the IIOP port number</fsummary>
+ <desc>
+ <p>This function returns the port-number, which is used by the IIOP
+ protocol. It can be configured by setting the application variable
+ <em>iiop_port</em>, if it is not set it will have the default number
+ 4001.</p>
+ </desc>
+ </func>
+ <func>
+ <name>iiop_out_ports() -> 0 | {Min, Max}</name>
+ <fsummary>Display the ports Orber may use when connecting to another ORB</fsummary>
+ <desc>
+ <p>The return value of this operation is what the configuration
+ parameter <seealso marker="ch_install#config">iiop_out_ports</seealso>
+ have been set to.</p>
+ </desc>
+ </func>
+ <func>
+ <name>iiop_ssl_port() -> int()</name>
+ <fsummary>Display the IIOP port number used for secure connections</fsummary>
+ <desc>
+ <p>This function returns the port-number, which is used by the secure IIOP
+ protocol. It can be configured by setting the application variable
+ <em>iiop_ssl_port</em>, if it is not set it will have the default number
+ 4002 if Orber is to configured to run in secure mode. Otherwise it returns -1.</p>
+ </desc>
+ </func>
+ <func>
+ <name>iiop_timeout() -> int() (milliseconds)</name>
+ <fsummary>Display the IIOP timeout value</fsummary>
+ <desc>
+ <p>This function returns the timeout value after which outgoing IIOP requests terminate.
+ It can be configured by setting the application variable
+ <em>iiop_timeout TimeVal (seconds)</em>, if it is not set it will have the default value
+ <em>infinity</em>. If a request times out a system exception, e.g.
+ <em>TIMEOUT</em>, is raised.</p>
+ <p>Note: the iiop_timeout configuration parameter (TimeVal) may only range between 0 and 1000000 seconds.
+ Otherwise, the default value is used.</p>
+ <p>Note: Earlier IC versions required that the compile option <c>{timeout,"module::interface"}</c>,
+ was used, which allow the user to add an extra timeout parameter, e.g.,
+ <c>module_interface:function(ObjRef, Timeout, ... Arguments ...)</c> or
+ <c>module_interface:function(ObjRef, [{timeout, Timeout}], ... Arguments ...)</c>,
+ instead of <c>module_interface:function(ObjRef, ... Arguments ...)</c>.
+ This is no longer the case and if the extra Timeout is used,
+ argument will override the configuration parameter <c>iiop_timeout</c>.
+ It is, however, not possible
+ to use <c>infinity</c> to override the Timeout parameter. The Timeout
+ option is also valid for objects which resides within the same Orber domain.</p>
+ </desc>
+ </func>
+ <func>
+ <name>iiop_connection_timeout() -> int() (milliseconds)</name>
+ <fsummary>Display the IIOP connection timeout value</fsummary>
+ <desc>
+ <p>This function returns the timeout value after which outgoing IIOP connections terminate.
+ It can be configured by setting the application variable
+ <em>iiop_connection_timeout TimeVal (seconds)</em>, if it is not set it will have the default value
+ <em>infinity</em>. The connection will not be terminated if there are
+ pending requests.</p>
+ <p>Note: the iiop_connection_timeout configuration parameter (TimeVal) may only range between 0 and 1000000 seconds.
+ Otherwise, the default value is used.</p>
+ </desc>
+ </func>
+ <func>
+ <name>iiop_connections() -> Result</name>
+ <name>iiop_connections(Direction) -> Result</name>
+ <fsummary>List all existing connections to/from other ORB's</fsummary>
+ <type>
+ <v>Direction = in | out | inout</v>
+ <v>Result = [{Host, Port}] | [{Host, Port, Interface}] | {'EXIT',Reason}</v>
+ <v>Host = string()</v>
+ <v>Port = integer()</v>
+ <v>Interface = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>The list returned by this operation contain tuples of remote hosts/ports
+ Orber is currently connected to. If no Direction is not supplied, both
+ incoming and outgoing connections are included.</p>
+ <p>If a specific local interface has been defined for the connection,
+ this will be added to the returned tuple.</p>
+ </desc>
+ </func>
+ <func>
+ <name>iiop_connections_pending() -> Result</name>
+ <fsummary>List all connections to another ORB currently being set up</fsummary>
+ <type>
+ <v>Result = [{Host, Port}] | [{Host, Port, Interface}] | {'EXIT',Reason}</v>
+ <v>Host = string()</v>
+ <v>Port = integer()</v>
+ <v>Interface = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>In some cases a connection attempt (i.e. trying to communicate with
+ another ORB) may block due to a number of reasons. This operation
+ allows the user to check if this is the case. The returned list
+ contain tuples of remote hosts/ports. Normally, the list is empty.</p>
+ <p>If a specific local interface has been defined for the connection,
+ this will be added to the returned tuple.</p>
+ </desc>
+ </func>
+ <func>
+ <name>iiop_in_connection_timeout() -> int() (milliseconds)</name>
+ <fsummary>Display the IIOP connection timeout value for incoming connections</fsummary>
+ <desc>
+ <p>This function returns the timeout value after which incoming IIOP
+ connections terminate. It can be configured by setting the application
+ variable <em>iiop_in_connection_timeout TimeVal (seconds)</em>, if it is
+ not set it will have the default value <em>infinity</em>. The connection
+ will not be terminated if there are pending requests.</p>
+ <p>Note: the iiop_in_connection_timeout configuration parameter (TimeVal) may
+ only range between 0 and 1000000 seconds. Otherwise, the default value is
+ used.</p>
+ </desc>
+ </func>
+ <func>
+ <name>iiop_acl() -> Result</name>
+ <fsummary>Return the ACL configuration</fsummary>
+ <type>
+ <v>Result = [{Direction, Filter}] | [{Direction, Filter, [Interface]}]</v>
+ <v>Direction = tcp_in | ssl_in | tcp_out | ssl_out</v>
+ <v>Filter = string()</v>
+ <v>Interface = string()</v>
+ </type>
+ <desc>
+ <p>Returns the ACL configuration. The <c>Filter</c> uses a extended format of
+ Classless Inter Domain Routing (CIDR). For example, <c>"123.123.123.10"</c> limits
+ the connection to that particular host, while <c>"123.123.123.10/17"</c> allows
+ connections to or from any host equal to the 17 most significant bits. Orber
+ also allow the user to specify a certain port or port range, for example,
+ <c>"123.123.123.10/17#4001"</c> and <c>"123.123.123.10/17#4001/5001"</c>
+ respectively. IPv4 or none compressed IPv6 strings are accepted. <br></br>
+
+ The list of <c>Interfaces</c>, IPv4 or IPv6 strings, are currently only used
+ for outgoing connections and may only contain <em>one</em> address. If set and
+ access is granted, Orber will use that local interface when connecting to the
+ other ORB. The module <seealso marker="orber_acl">orber_acl</seealso>
+ provides operations for evaluating the access control for filters and addresses.</p>
+ </desc>
+ </func>
+ <func>
+ <name>activate_audit_trail() -> Result</name>
+ <name>activate_audit_trail(Verbosity) -> Result</name>
+ <fsummary>Activate IIOP audit/trail</fsummary>
+ <type>
+ <v>Verbosity = stealth | normal | verbose</v>
+ <v>Result = ok | {error, Reason}</v>
+ <v>Reason = string()</v>
+ </type>
+ <desc>
+ <p>Activates audit/trail for all existing incoming and outgoing IIOP
+ connections. The <c>Verbosity</c> parameter, <c>stealth</c>,
+ <c>normal</c> or <c>verbose</c>, determines which of the built in
+ interceptors is used (<c>orber_iiop_tracer_stealth</c>,
+ <c>orber_iiop_tracer_silent</c> or <c>orber_iiop_tracer</c> respectively).
+ If no verbosity level is supplied, then the <c>normal</c> will be used.</p>
+ <p>In case Orber is configured to use other interceptors, the audit/trail
+ interceptors will simply be added to that list.</p>
+ </desc>
+ </func>
+ <func>
+ <name>deactivate_audit_trail() -> Result</name>
+ <fsummary>Deactivate IIOP audit/trail</fsummary>
+ <type>
+ <v>Result = ok | {error, Reason}</v>
+ <v>Reason = string()</v>
+ </type>
+ <desc>
+ <p>Deactivates audit/trail for all existing incoming and outgoing IIOP
+ connections. In case Orber is configured to use other interceptors,
+ those will still be used.</p>
+ </desc>
+ </func>
+ <func>
+ <name>add_listen_interface(IP, Type) -> Result</name>
+ <name>add_listen_interface(IP, Type, Port) -> Result</name>
+ <name>add_listen_interface(IP, Type, ConfigurationParameters) -> Result</name>
+ <fsummary>Add a new listen process for incoming connection</fsummary>
+ <type>
+ <v>IP = string</v>
+ <v>Type = normal | ssl</v>
+ <v>Port = integer() > 0</v>
+ <v>ConfigurationParameters = [{Key, Value}]</v>
+ <v>Key = flags | iiop_in_connection_timeout | iiop_max_fragments | iiop_max_in_requests | interceptors | iiop_port | iiop_ssl_port</v>
+ <v>Value = as described in the User's Guide</v>
+ <v>Result = {ok, Ref} | {error, Reason} | {'EXCEPTION', #'BAD_PARAM'{}}</v>
+ <v>Ref = #Ref</v>
+ <v>Reason = string()</v>
+ </type>
+ <desc>
+ <p>Create a new process that handle requests for creating a new incoming
+ IIOP connection via the given interface and port. If the latter is
+ excluded, Orber will use the value of the <c>iiop_port</c> or
+ <c>iiop_ssl_port</c> configuration parameters.
+ The <c>Type</c> parameter determines if it is
+ supposed to be IIOP or IIOP via SSL. If successful, the returned
+ <c>#Ref</c> shall be passed to <c>orber:remove_listen_interface/1</c>
+ when the connection shall be terminated.</p>
+ <p>It is also possible to supply configuration parameters that override
+ the global configuration. The <em>iiop_in_connection_timeout</em>,
+ <em>iiop_max_fragments</em>, <em>iiop_max_in_requests</em> and
+ <em>interceptors</em> parameters simply overrides the global
+ counterparts (See the
+ <seealso marker="ch_install#config">Configuration</seealso> chapter
+ in the User's Guide).
+ But the following parameters there are a few restrictions:</p>
+ <list type="bulleted">
+ <item><em>flags</em> - currently it is only possible to override the global
+ setting for the <c>Use Current Interface in IOR</c> and
+ <c>Exclude CodeSet Component</c> flags.</item>
+ <item><em>iiop_port</em> - requires that <c>Use Current Interface in IOR</c>
+ is activated and the supplied <c>Type</c> is <c>normal</c>. If so,
+ exported IOR:s will contain the IIOP port defined by this configuration
+ parameter. Otherwise, the global setting will be used.</item>
+ <item><em>iiop_ssl_port</em> - almost equivalent to <c>iiop_port</c>.
+ The difference is that <c>Type</c> shall be <c>ssl</c> and that
+ exported IOR:s will contain the IIOP via SSL port defined by this configuration
+ parameter.</item>
+ </list>
+ <p>If it is not possible to add a listener based on the supplied interface
+ and port, the error message is one of the ones described in <c>inet</c>
+ and/or <c>ssl</c> documentation.</p>
+ </desc>
+ </func>
+ <func>
+ <name>remove_listen_interface(Ref) -> ok</name>
+ <fsummary>Terminate listen process for incoming connection</fsummary>
+ <type>
+ <v>Ref = #Ref</v>
+ </type>
+ <desc>
+ <p>Terminates the listen process, associated with the supplied <c>#Ref</c>,
+ for incoming a connection. The Ref parameter is the return value from
+ the <c>orber:add_listen_interface/2/3</c> operation. When terminating
+ the connection, all associated requests will not deliver a reply to
+ the clients.</p>
+ </desc>
+ </func>
+ <func>
+ <name>close_connection(Connection) -> Result</name>
+ <name>close_connection(Connection, Interface) -> Result</name>
+ <fsummary>Terminate outgoing connection(s)</fsummary>
+ <type>
+ <v>Connection = Object | [{Host, Port}]</v>
+ <v>Object = #objref (external)</v>
+ <v>Host = string()</v>
+ <v>Port = string()</v>
+ <v>Interface = string()</v>
+ <v>Result = ok | {'EXCEPTION', #'BAD_PARAM'{}}</v>
+ </type>
+ <desc>
+ <p>Will try to close all outgoing connections to the host/port combinations
+ found in the supplied object reference or the given list of hosts/ports.
+ If a <c>#'IOP_ServiceContext'{}</c> containing a local interface has been
+ used when communicating with the remote object
+ (see also <seealso marker="Module_Interface">Module_Interface</seealso>),
+ that interface shall be passed as the second argument. Otherwise, connections
+ via the default local interface, will be terminated.</p>
+ <p></p>
+ <note>
+ <p>Since several clients maybe communicates via the same connection,
+ they will be affected when invoking this operation. Other clients may
+ re-create the connection by invoking an operation on the target object.</p>
+ </note>
+ </desc>
+ </func>
+ <func>
+ <name>secure() -> no | ssl</name>
+ <fsummary>Display the security mode Orber is running in</fsummary>
+ <desc>
+ <p>This function returns the security mode Orber is running in, which is either no if it is an
+ insecure domain or the type of security mechanism used. For the moment the only security
+ mechanism is ssl. This is configured by setting the application variable
+ <em>secure</em>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>ssl_server_certfile() -> string()</name>
+ <fsummary>Display the path to the server certificate</fsummary>
+ <desc>
+ <p>This function returns a path to a file containing a chain of PEM encoded
+ certificates for the Orber domain as server.
+ This is configured by setting the application variable
+ <em>ssl_server_certfile</em>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>ssl_client_certfile() -> string()</name>
+ <fsummary>Display the path to the client certificate</fsummary>
+ <desc>
+ <p>This function returns a path to a file containing a chain of PEM encoded
+ certificates used in outgoing calls in the current process.
+ The default value is configured by setting the application variable
+ <em>ssl_client_certfile</em>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>set_ssl_client_certfile(Path) -> ok</name>
+ <fsummary>Set the value of the client certificate</fsummary>
+ <type>
+ <v>Path = string()</v>
+ </type>
+ <desc>
+ <p>This function takes a path to a file containing a chain of PEM encoded
+ certificates as parameter and sets it for the current process.</p>
+ </desc>
+ </func>
+ <func>
+ <name>ssl_server_verify() -> 0 | 1 | 2</name>
+ <fsummary>Display the SSL verification type for incoming calls</fsummary>
+ <desc>
+ <p>This function returns the type of verification used by SSL during authentication of the other
+ peer for incoming calls.
+ It is configured by setting the application variable
+ <em>ssl_server_verify</em>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>ssl_client_verify() -> 0 | 1 | 2</name>
+ <fsummary>Display the SSL verification type for outgoing calls</fsummary>
+ <desc>
+ <p>This function returns the type of verification used by SSL during authentication of the other
+ peer for outgoing calls.
+ The default value is configured by setting the application variable
+ <em>ssl_client_verify</em>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>set_ssl_client_verify(Value) -> ok</name>
+ <fsummary>Set the value of the SSL verification type for outgoing calls</fsummary>
+ <type>
+ <v>Value = 0 | 1 | 2</v>
+ </type>
+ <desc>
+ <p>This function sets the SSL verification type for the other peer of outgoing calls.</p>
+ </desc>
+ </func>
+ <func>
+ <name>ssl_server_depth() -> int()</name>
+ <fsummary>Display the SSL verification depth for incoming calls</fsummary>
+ <desc>
+ <p>This function returns the SSL verification depth for incoming calls.
+ It is configured by setting the application variable
+ <em>ssl_server_depth</em>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>ssl_client_depth() -> int()</name>
+ <fsummary>Display the SSL verification depth for outgoing calls</fsummary>
+ <desc>
+ <p>This function returns the SSL verification depth for outgoing calls.
+ The default value is configured by setting the application variable
+ <em>ssl_client_depth</em>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>set_ssl_client_depth(Depth) -> ok</name>
+ <fsummary>Sets the value of the SSL verification depth for outgoing calls</fsummary>
+ <type>
+ <v>Depth = int()</v>
+ </type>
+ <desc>
+ <p>This function sets the SSL verification depth for the other peer of outgoing calls.</p>
+ </desc>
+ </func>
+ <func>
+ <name>objectkeys_gc_time() -> int() (seconds)</name>
+ <fsummary>Display the Object Keys GC time value</fsummary>
+ <desc>
+ <p>This function returns the timeout value after which after which terminated object keys,
+ related to servers started with the configuration parameter <c>{persistent, true}</c>,
+ will be removed.
+ It can be configured by setting the application variable <em>objectkeys_gc_time TimeVal (seconds)</em>,
+ if it is not set it will have the default value <em>infinity</em>. </p>
+ <p>Objects terminating with reason <em>normal</em> or <em>shutdown</em> are removed automatically.</p>
+ <p>Note: the objectkeys_gc_time configuration parameter (TimeVal) may only range between 0 and 1000000 seconds.
+ Otherwise, the default value is used.</p>
+ </desc>
+ </func>
+ <func>
+ <name>orber_nodes() -> RetVal</name>
+ <fsummary>Displays which nodes that this orber domain consist of.</fsummary>
+ <type>
+ <v>RetVal = [node()]</v>
+ </type>
+ <desc>
+ <p>This function returns the list of node names that this orber
+ domain consists of. </p>
+ </desc>
+ </func>
+ <func>
+ <name>install(NodeList) -> ok</name>
+ <name>install(NodeList, Options) -> ok</name>
+ <fsummary>Install the Orber application</fsummary>
+ <type>
+ <v>NodeList = [node()]</v>
+ <v>Options = [Option]</v>
+ <v>Option = {install_timeout, Timeout} | {ifr_storage_type, TableType} | {nameservice_storage_type, TableType} | {initialreferences_storage_type, TableType} | {load_order, Priority}</v>
+ <v>Timeout = infinity | integer()</v>
+ <v>TableType = disc_copies | ram_copies</v>
+ <v>Priority = integer()</v>
+ </type>
+ <desc>
+ <p>This function installs all the necessary mnesia tables and
+ load default data in some of them. If one or more Orber tables
+ already exists the installation fails. The function\011
+ <em>uninstall</em> may be used, if it is safe, i.e., no other
+ application is running Orber.</p>
+ <p>Preconditions:</p>
+ <list type="bulleted">
+ <item>a mnesia schema must exist before the installation</item>
+ <item>mnesia is running on the other nodes if the new installation
+ shall be a multi node domain</item>
+ </list>
+ <p>Mnesia will be started by the function if it is not already running on
+ the installation node and if it was started it will be stopped
+ afterwards.</p>
+ <p>The options that can be sent to the installation program is:</p>
+ <list type="bulleted">
+ <item><c>{install_timeout, Timeout}</c> - this timeout is how long we
+ will wait for the tables to be created. The Timeout value can be
+ <em>infinity</em> or an integer number in milliseconds.
+ Default is infinity.</item>
+ <item><c>{ifr_storage_type, TableType}</c> - this option sets the
+ type of tables used for the interface repository.
+ The TableType can be disc_copies or ram_copies. Default is
+ disc_copies.</item>
+ <item><c>{initialreferences_storage_type, TableType}</c> - this option
+ sets the type of table used for storing initial references.
+ The TableType can be disc_copies or ram_copies. Default is
+ ram_copies.</item>
+ <item><c>{nameservice_storage_type, TableType}</c> - the default
+ behavior of Orber is to install the NameService as ram_copies.
+ This option makes it possible to change this to disc_copies. But
+ the user should be aware of that if a node is restarted, all
+ local object references stored in the NameService is not valid.
+ Hence, you cannot switch to disc_copies and expect exactly the same
+ behavior as before.</item>
+ <item><c>{load_order, Priority}</c> - per default the priority is set to 0.
+ Using this option it will change the priority of in which order
+ Mnesia will load Orber internal tables. For more information,
+ consult the Mnesia documentation.</item>
+ </list>
+ </desc>
+ </func>
+ <func>
+ <name>uninstall() -> ok</name>
+ <fsummary>Uninstall the Orber application</fsummary>
+ <desc>
+ <p>This function stops the Orber application, terminates all server
+ objects and removes all Orber related mnesia tables.</p>
+ <p>Note: Since other applications may be running on the same node
+ using mnesia <em>uninstall</em> will not stop the mnesia application.</p>
+ </desc>
+ </func>
+ <func>
+ <name>add_node(Node, Options) -> RetVal</name>
+ <fsummary>Add a new node to a group of Orber nodes.</fsummary>
+ <type>
+ <v>Node = node()</v>
+ <v>Options = IFRStorageType | [KeyValue] </v>
+ <v>IFRStorageType = StorageType</v>
+ <v>StorageType = disc_copies | ram_copies</v>
+ <v>KeyValue = {ifr_storage_type, StorageType} | {initialreferences_storage_type, StorageType} | {nameservice_storage_type, StorageType} | {type, Type} </v>
+ <v>Type = temporary | permanent</v>
+ <v>RetVal = ok | exit()</v>
+ </type>
+ <desc>
+ <p>This function add given node to a existing Orber node group and starts
+ Orber on the new node. <c>orber:add_node</c> is called from a member in the Orber
+ node group.</p>
+ <p>Preconditions for new node:</p>
+ <list type="bulleted">
+ <item>Erlang started on the new node using the option <c>-mnesia extra_db_nodes</c>, e.g.,
+ <c>erl -sname new_node_name -mnesia extra_db_nodes ConnectToNodes_List</c></item>
+ <item>The new node's <c>domain</c> name is the same for the nodes we want to connect to.</item>
+ <item>Mnesia is running on the new node (no new schema created).</item>
+ <item>If the new node will use <c>disc_copies</c> the schema type must be changed using:
+ <c>mnesia:change_table_copy_type(schema, node(), disc_copies).</c></item>
+ </list>
+ <p>Orber will be started by the function on the new node.</p>
+ <p>Fails if:</p>
+ <list type="bulleted">
+ <item>Orber already installed on given node.</item>
+ <item>Mnesia not started as described above on the new node.</item>
+ <item>Impossible to copy data in Mnesia tables to the new node.</item>
+ <item>Not able to start Orber on the new node, due to, for example, the
+ <c>iiop_port</c> is already in use.</item>
+ </list>
+ <p>The function do not remove already copied tables after a failure.
+ Use <c>orber:remove_node</c> to remove these tables.</p>
+ </desc>
+ </func>
+ <func>
+ <name>remove_node(Node) -> RetVal</name>
+ <fsummary>Removes a node from a group of Orber nodes.</fsummary>
+ <type>
+ <v>Node = node()</v>
+ <v>RetVal = ok | exit()</v>
+ </type>
+ <desc>
+ <p>This function removes given node from a Orber node group. The Mnesia
+ application is not stopped.</p>
+ </desc>
+ </func>
+ <func>
+ <name>configure(Key, Value) -> ok | {'EXIT', Reason}</name>
+ <fsummary>Change Orber configuration.</fsummary>
+ <type>
+ <v>Key = orbDefaultInitRef | orbInitRef | giop_version | iiop_timeout | iiop_connection_timeout | iiop_setup_connection_timeout | iiop_in_connection_timeout | objectkeys_gc_time | orber_debug_level</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. It is possible to invoke <c>configure</c> at any time
+ the keys specified above.</p>
+ <p>Any other key must be set before installing and starting Orber.</p>
+ <p>Trying to change the configuration in any other way is <em>NOT</em>
+ allowed since it may affect the behavior of Orber.</p>
+ <p>For more information regarding allowed values, see
+ <seealso marker="ch_install#config">configuration settings</seealso>
+ in the User's Guide.</p>
+ <p></p>
+ <note>
+ <p>Configuring the IIOP timeout values will not affect already
+ existing connections. If you want a guaranteed uniform behavior, you
+ must set these parameters from the start.</p>
+ </note>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+