Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       orber - The main module of the Orber application

DESCRIPTION

       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.

EXPORTS

       start() -> ok
       start(Type) -> ok

              Types:

                 Type = temporary | permanent

              Starts  the  Orber  application (it also starts mnesia if it is not running). Which
              Type parameter is supplied determines  the  behavior.  If  not  supplied  Orber  is
              started  as  temporary.  See  the  Reference  Manual  application(3erl) for further
              information.

       jump_start(Attributes) -> ok | {'EXIT', Reason}

              Types:

                 Attributes = Port | Options
                 Port = integer()
                 Options = [{Key, Value}]
                 Key = any key listed in the configuration chapter
                 Value = allowed value associated with the given key

              Installs and starts the Orber and the Mnesia applications  with  the  configuration
              parameters  domain  and  iiop_port  set  to  "IP-number:Port" 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  MAY  ONLY  be  used  during
              development and tests; how Orber is configured when using this operation may change
              at any time without warning.

       stop() -> ok

              Stops the Orber application.

       info() -> ok
       info(IoType) -> ok | {'EXIT', Reason} | string()

              Types:

                 IoType = info_msg | string | io | {io, IoDevice}

              Generates an Info Report, which  contain  Orber's  configuration  settings.  If  no
              IoType is supplied, info_msg is used (see the error_logger documentation). When the
              atom string is supplied this function will return a flat  list.  For  io  and  {io,
              IoDevice}, io:format/1 and io:format/3 is used respectively.

       exception_info(Exception) -> {ok, string()} | {error, Reason}

              Returns  a  printable  string,  which  describes  the supplied exception in greater
              detail. Note, this function is mainly intended for system exceptions.

       is_system_exception(Exception) -> true | false

              Returns true if the supplied exception is a  system  defined  exception,  otherwise
              false.

       get_tables() -> [Tables]

              Returns  a  list  of  the  Orber  specific  Mnesia tables. This list is required to
              restore Mnesia if it has been partitioned.

       get_ORBInitRef() -> string() | undefined

              This function returns undefined if we will resolve references locally, otherwise  a
              string   describing   which   host   we   will   contact   if   the  Key  given  to
              corba:resolve_initial_references/1  matches  the  Key  set  in  this  configuration
              variable. For more information see the user's guide.

       get_ORBDefaultInitRef() -> string() | undefined

              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  corba:resolve_initial_references/1.  For more information see the user's
              guide.

       domain() -> string()

              This function returns the domain name of the current Orber domain as a string.

       iiop_port() -> int()

              This function returns the port-number, which is used by the IIOP protocol.  It  can
              be  configured  by  setting the application variable iiop_port, if it is not set it
              will have the default number 4001.

       iiop_out_ports() -> 0 | {Min, Max}

              The  return  value  of  this  operation  is  what   the   configuration   parameter
              iiop_out_ports has been set to.

       iiop_out_ports_random() -> true | false

              Return the value of the configuration parameter iiop_out_ports_random.

       iiop_out_ports_attempts() -> int()

              Return the value of the configuration parameter iiop_out_ports_attempts.

       iiop_ssl_port() -> int()

              This  function  returns the port-number, which is used by the secure IIOP protocol.
              It can be configured by setting the application variable iiop_ssl_port,  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.

       iiop_timeout() -> int() (milliseconds)

              This function  returns  the  timeout  value  after  which  outgoing  IIOP  requests
              terminate.  It  can  be configured by setting the application variable iiop_timeout
              TimeVal (seconds), if it is not set it will have the default value infinity.  If  a
              request times out a system exception, e.g. TIMEOUT, is raised.

              Note:  the  iiop_timeout configuration parameter (TimeVal) may only range between 0
              and 1000000 seconds. Otherwise, the default value is used.

              Note:    Earlier    IC    versions    required    that    the    compile     option
              {timeout,"module::interface"},  was  used,  which  allow  the  user to add an extra
              timeout parameter, e.g., module_interface:function(ObjRef, Timeout,  ...  Arguments
              ...) or module_interface:function(ObjRef, [{timeout, Timeout}], ... Arguments ...),
              instead of module_interface:function(ObjRef, ... Arguments ...). This is no  longer
              the case and if the extra Timeout is used, argument will override the configuration
              parameter iiop_timeout. It is, however, not possible to use  infinity  to  override
              the  Timeout  parameter. The Timeout option is also valid for objects which resides
              within the same Orber domain.

       iiop_connection_timeout() -> int() (milliseconds)

              This function returns the timeout  value  after  which  outgoing  IIOP  connections
              terminate.   It   can   be   configured   by   setting   the  application  variable
              iiop_connection_timeout TimeVal (seconds), if it  is  not  set  it  will  have  the
              default  value infinity. The connection will not be terminated if there are pending
              requests.

              Note: the iiop_connection_timeout configuration parameter (TimeVal) may only  range
              between 0 and 1000000 seconds. Otherwise, the default value is used.

       iiop_connections() -> Result
       iiop_connections(Direction) -> Result

              Types:

                 Direction = in | out | inout
                 Result = [{Host, Port}] | [{Host, Port, Interface}] | {'EXIT',Reason}
                 Host = string()
                 Port = integer()
                 Interface = string()
                 Reason = term()

              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.

              If  a  specific  local  interface has been defined for the connection, this will be
              added to the returned tuple.

       iiop_connections_pending() -> Result

              Types:

                 Result = [{Host, Port}] | [{Host, Port, Interface}] | {'EXIT',Reason}
                 Host = string()
                 Port = integer()
                 Interface = string()
                 Reason = term()

              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.

              If  a  specific  local  interface has been defined for the connection, this will be
              added to the returned tuple.

       iiop_in_connection_timeout() -> int() (milliseconds)

              This function returns the timeout  value  after  which  incoming  IIOP  connections
              terminate.   It   can   be   configured   by   setting   the  application  variable
              iiop_in_connection_timeout TimeVal (seconds), if it is not set  it  will  have  the
              default  value infinity. The connection will not be terminated if there are pending
              requests.

              Note: the iiop_in_connection_timeout configuration  parameter  (TimeVal)  may  only
              range between 0 and 1000000 seconds. Otherwise, the default value is used.

       iiop_acl() -> Result

              Types:

                 Result = [{Direction, Filter}] | [{Direction, Filter, [Interface]}]
                 Direction = tcp_in | ssl_in | tcp_out | ssl_out
                 Filter = string()
                 Interface = string()

              Returns the ACL configuration. The Filter uses a extended format of Classless Inter
              Domain Routing (CIDR). For example, "123.123.123.10" limits the connection to  that
              particular  host,  while "123.123.123.10/17" 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,  "123.123.123.10/17#4001"  and
              "123.123.123.10/17#4001/5001" respectively. IPv4 or none  compressed  IPv6  strings
              are accepted.
              The  list of Interfaces, IPv4 or IPv6 strings, are currently only used for outgoing
              connections and may only contain one address. If set and access is  granted,  Orber
              will  use  that  local  interface  when  connecting  to  the  other ORB. The module
              orber_acl provides operations for evaluating the access  control  for  filters  and
              addresses.

       activate_audit_trail() -> Result
       activate_audit_trail(Verbosity) -> Result

              Types:

                 Verbosity = stealth | normal | verbose
                 Result = ok | {error, Reason}
                 Reason = string()

              Activates  audit/trail for all existing incoming and outgoing IIOP connections. The
              Verbosity parameter, stealth, normal or verbose, determines which of the  built  in
              interceptors   is   used  (orber_iiop_tracer_stealth,  orber_iiop_tracer_silent  or
              orber_iiop_tracer respectively). If no verbosity level is supplied, then the normal
              will be used.

              In case Orber is configured to use other interceptors, the audit/trail interceptors
              will simply be added to that list.

       deactivate_audit_trail() -> Result

              Types:

                 Result = ok | {error, Reason}
                 Reason = string()

              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.

       add_listen_interface(IP, Type) -> Result
       add_listen_interface(IP, Type, Port) -> Result
       add_listen_interface(IP, Type, ConfigurationParameters) -> Result

              Types:

                 IP = string
                 Type = normal | ssl
                 Port = integer() > 0
                 ConfigurationParameters = [{Key, Value}]
                 Key    =    flags    |   iiop_in_connection_timeout   |   iiop_max_fragments   |
                 iiop_max_in_requests   |   interceptors   |   iiop_port   |   iiop_ssl_port    |
                 ssl_server_options
                 Value = as described in the User's Guide
                 Result = {ok, Ref} | {error, Reason} | {'EXCEPTION', #'BAD_PARAM'{}}
                 Ref = #Ref
                 Reason = string()

              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 iiop_port or iiop_ssl_port configuration parameters. The Type
              parameter determines if it is supposed to be IIOP or IIOP via SSL.  If  successful,
              the  returned  #Ref  shall  be  passed  to orber:remove_listen_interface/1 when the
              connection shall be terminated.

              It is also possible to supply configuration parameters  that  override  the  global
              configuration.       The       iiop_in_connection_timeout,      iiop_max_fragments,
              iiop_max_in_requests  and  interceptors  parameters  simply  overrides  the  global
              counterparts  (See  the  Configuration  chapter  in  the User's Guide). But for the
              following parameters there are a few restrictions:

                * flags - currently it is only possible to override the global  setting  for  the
                  Use Current Interface in IOR and Exclude CodeSet Component flags.

                * iiop_port  -  requires  that  Use Current Interface in IOR is activated and the
                  supplied Type is normal. If so, exported  IOR:s  will  contain  the  IIOP  port
                  defined  by this configuration parameter. Otherwise, the global setting will be
                  used.

                * iiop_ssl_port - almost equivalent to iiop_port. The  difference  is  that  Type
                  shall be ssl and that exported IOR:s will contain the IIOP via SSL port defined
                  by this configuration parameter.

              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 inet and/or ssl documentation.

       remove_listen_interface(Ref) -> ok

              Types:

                 Ref = #Ref

              Terminates  the  listen  process, associated with the supplied #Ref, for incoming a
              connection.   The   Ref    parameter    is    the    return    value    from    the
              orber:add_listen_interface/2/3  operation.  When  terminating  the  connection, all
              associated requests will not deliver a reply to the clients.

       close_connection(Connection) -> Result
       close_connection(Connection, Interface) -> Result

              Types:

                 Connection = Object | [{Host, Port}]
                 Object = #objref (external)
                 Host = string()
                 Port = string()
                 Interface = string()
                 Result = ok | {'EXCEPTION', #'BAD_PARAM'{}}

              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
              #'IOP_ServiceContext'{}  containing  a  local  interface   has   been   used   when
              communicating  with  the  remote object (see also Module_Interface), that interface
              shall be passed as the second argument.  Otherwise,  connections  via  the  default
              local interface, will be terminated.

          Note:
              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.

       secure() -> no | ssl

              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 secure.

       ssl_server_options() -> list()

              This function returns the list of SSL options set for the Orber domain  as  server.
              This is configured by setting the application variable ssl_server_options.

       ssl_client_options() -> list()

              This function returns the list of SSL options used in outgoing calls in the current
              process. The default value  is  configured  by  setting  the  application  variable
              ssl_client_options.

       set_ssl_client_options(Options) -> ok

              Types:

                 Options = list()

              This  function takes a list of SSL options as parameter and sets it for the current
              process.

       objectkeys_gc_time() -> int() (seconds)

              This function returns the timeout value after which after which  terminated  object
              keys,  related  to  servers  started  with the configuration parameter {persistent,
              true}, will be removed. It can be configured by setting  the  application  variable
              objectkeys_gc_time  TimeVal  (seconds),  if  it is not set it will have the default
              value infinity.

              Objects terminating with reason normal or shutdown are removed automatically.

              Note: the objectkeys_gc_time  configuration  parameter  (TimeVal)  may  only  range
              between 0 and 1000000 seconds. Otherwise, the default value is used.

       orber_nodes() -> RetVal

              Types:

                 RetVal = [node()]

              This function returns the list of node names that this orber domain consists of.

       install(NodeList) -> ok
       install(NodeList, Options) -> ok

              Types:

                 NodeList = [node()]
                 Options = [Option]
                 Option   =   {install_timeout,   Timeout}   |  {ifr_storage_type,  TableType}  |
                 {nameservice_storage_type,   TableType}    |    {initialreferences_storage_type,
                 TableType} | {load_order, Priority}
                 Timeout = infinity | integer()
                 TableType = disc_copies | ram_copies
                 Priority = integer()

              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  uninstall  may be used, if it is safe, i.e., no other application is
              running Orber.

              Preconditions:

                * a mnesia schema must exist before the installation

                * mnesia is running on the other nodes if the new installation shall be  a  multi
                  node domain

              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.

              The options that can be sent to the installation program is:

                * {install_timeout, Timeout} - this timeout is how long  we  will  wait  for  the
                  tables to be created. The Timeout value can be infinity or an integer number in
                  milliseconds. Default is infinity.

                * {ifr_storage_type, TableType} - 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.

                * {initialreferences_storage_type, TableType} - 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.

                * {nameservice_storage_type, TableType} - 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.

                * {load_order,  Priority}  -  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.

       uninstall() -> ok

              This  function  stops  the  Orber  application,  terminates  all server objects and
              removes all Orber related mnesia tables.

              Note: Since other applications may  be  running  on  the  same  node  using  mnesia
              uninstall will not stop the mnesia application.

       add_node(Node, Options) -> RetVal

              Types:

                 Node = node()
                 Options = IFRStorageType | [KeyValue]
                 IFRStorageType = StorageType
                 StorageType = disc_copies | ram_copies
                 KeyValue  =  {ifr_storage_type,  StorageType} | {initialreferences_storage_type,
                 StorageType} | {nameservice_storage_type, StorageType} | {type, Type}
                 Type = temporary | permanent
                 RetVal = ok | exit()

              This function add given node to a existing Orber node group and starts Orber on the
              new node. orber:add_node is called from a member in the Orber node group.

              Preconditions for new node:

                * Erlang  started  on the new node using the option -mnesia extra_db_nodes, e.g.,
                  erl -sname new_node_name -mnesia extra_db_nodes ConnectToNodes_List

                * The new node's domain name is the same for the nodes we want to connect to.

                * Mnesia is running on the new node (no new schema created).

                * If the new node will use disc_copies the schema type  must  be  changed  using:
                  mnesia:change_table_copy_type(schema, node(), disc_copies).

              Orber will be started by the function on the new node.

              Fails if:

                * Orber already installed on given node.

                * Mnesia not started as described above on the new node.

                * Impossible to copy data in Mnesia tables to the new node.

                * Not  able to start Orber on the new node, due to, for example, the iiop_port is
                  already in use.

              The  function  do  not  remove  already  copied  tables  after   a   failure.   Use
              orber:remove_node to remove these tables.

       remove_node(Node) -> RetVal

              Types:

                 Node = node()
                 RetVal = ok | exit()

              This function removes given node from a Orber node group. The Mnesia application is
              not stopped.

       configure(Key, Value) -> ok | {'EXIT', Reason}

              Types:

                 Key  =  orbDefaultInitRef  |  orbInitRef  |  giop_version   |   iiop_timeout   |
                 iiop_connection_timeout         |         iiop_setup_connection_timeout        |
                 iiop_in_connection_timeout | objectkeys_gc_time | orber_debug_level
                 Value = allowed value associated with the given key

              This function allows the user to configure Orber in, for example, an Erlang  shell.
              It is possible to invoke configure at any time the keys specified above.

              Any other key must be set before installing and starting Orber.

              Trying  to  change  the  configuration in any other way is NOT allowed since it may
              affect the behavior of Orber.

              For more information regarding allowed values, see configuration  settings  in  the
              User's Guide.

          Note:
              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.