1orber(3)                   Erlang Module Definition                   orber(3)
2
3
4

NAME

6       orber - The main module of the Orber application
7

DESCRIPTION

9       This module contains the functions for starting and stopping the appli‐
10       cation. It also has some utility functions to get some of the  configu‐
11       ration information from running application.
12

EXPORTS

14       start() -> ok
15       start(Type) -> ok
16
17              Types:
18
19                 Type = temporary | permanent
20
21              Starts the Orber application (it also starts mnesia if it is not
22              running). Which Type parameter is supplied determines the behav‐
23              ior. If not supplied Orber is started as temporary. See the Ref‐
24              erence Manual application(3) for further information.
25
26       jump_start(Attributes) -> ok | {'EXIT', Reason}
27
28              Types:
29
30                 Attributes = Port | Options
31                 Port = integer()
32                 Options = [{Key, Value}]
33                 Key = any key listed in the configuration chapter
34                 Value = allowed value associated with the given key
35
36              Installs and starts the Orber and the Mnesia  applications  with
37              the  configuration  parameters  domain and iiop_port set to "IP-
38              number:Port" and the supplied Port respectively. Theses settings
39              are  in  most  cases sufficient to ensure that no clash with any
40              other Orber instance occur. If this operation  fails,  check  if
41              the listen port (iiop_port) is already in use. This function MAY
42              ONLY be used during development and tests; how Orber is  config‐
43              ured  when  using  this operation may change at any time without
44              warning.
45
46       stop() -> ok
47
48              Stops the Orber application.
49
50       info() -> ok
51       info(IoType) -> ok | {'EXIT', Reason} | string()
52
53              Types:
54
55                 IoType = info_msg | string | io | {io, IoDevice}
56
57              Generates an Info Report, which  contain  Orber's  configuration
58              settings.  If  no  IoType is supplied, info_msg is used (see the
59              error_logger documentation). When the atom  string  is  supplied
60              this  function  will  return  a flat list. For io and {io, IoDe‐
61              vice}, io:format/1 and io:format/3 is used respectively.
62
63       exception_info(Exception) -> {ok, string()} | {error, Reason}
64
65              Returns a printable string, which describes the supplied  excep‐
66              tion  in  greater detail. Note, this function is mainly intended
67              for system exceptions.
68
69       is_system_exception(Exception) -> true | false
70
71              Returns true if the supplied exception is a system  defined  ex‐
72              ception, otherwise false.
73
74       get_tables() -> [Tables]
75
76              Returns a list of the Orber specific Mnesia tables. This list is
77              required to restore Mnesia if it has been partitioned.
78
79       get_ORBInitRef() -> string() | undefined
80
81              This function returns undefined if we  will  resolve  references
82              locally,  otherwise  a string describing which host we will con‐
83              tact if  the  Key  given  to  corba:resolve_initial_references/1
84              matches the Key set in this configuration variable. For more in‐
85              formation see the user's guide.
86
87       get_ORBDefaultInitRef() -> string() | undefined
88
89              This function returns undefined if we  will  resolve  references
90              locally,  otherwise  a  string  describing which host, or hosts,
91              from which we will try to resolve the  Key  given  to  corba:re‐
92              solve_initial_references/1.  For more information see the user's
93              guide.
94
95       domain() -> string()
96
97              This function returns the domain name of the current  Orber  do‐
98              main as a string.
99
100       iiop_port() -> int()
101
102              This function returns the port-number, which is used by the IIOP
103              protocol. It can be configured by setting the application  vari‐
104              able iiop_port, if it is not set it will have the default number
105              4001.
106
107       iiop_out_ports() -> 0 | {Min, Max}
108
109              The return value of this operation is what the configuration pa‐
110              rameter iiop_out_ports has been set to.
111
112       iiop_out_ports_random() -> true | false
113
114              Return    the    value    of    the    configuration   parameter
115              iiop_out_ports_random.
116
117       iiop_out_ports_attempts() -> int()
118
119              Return   the    value    of    the    configuration    parameter
120              iiop_out_ports_attempts.
121
122       iiop_ssl_port() -> int()
123
124              This  function returns the port-number, which is used by the se‐
125              cure IIOP protocol. It can be configured by setting the applica‐
126              tion  variable  iiop_ssl_port, if it is not set it will have the
127              default number 4002 if Orber is to configured to run  in  secure
128              mode. Otherwise it returns -1.
129
130       iiop_timeout() -> int() (milliseconds)
131
132              This  function  returns  the  timeout value after which outgoing
133              IIOP requests terminate. It can be configured by setting the ap‐
134              plication  variable iiop_timeout TimeVal (seconds), if it is not
135              set it will have the default value infinity. If a request  times
136              out a system exception, e.g. TIMEOUT, is raised.
137
138              Note:  the  iiop_timeout  configuration  parameter (TimeVal) may
139              only range between 0 and 1000000 seconds. Otherwise, the default
140              value is used.
141
142              Note:  Earlier  IC  versions  required  that  the compile option
143              {timeout,"module::interface"}, was used, which allow the user to
144              add  an  extra  timeout  parameter, e.g., module_interface:func‐
145              tion(ObjRef,  Timeout,  ...  Arguments  ...)  or   module_inter‐
146              face:function(ObjRef,  [{timeout, Timeout}], ... Arguments ...),
147              instead of module_interface:function(ObjRef, ... Arguments ...).
148              This is no longer the case and if the extra Timeout is used, ar‐
149              gument will override the configuration  parameter  iiop_timeout.
150              It  is,  however,  not  possible to use infinity to override the
151              Timeout parameter. The Timeout option is also valid for  objects
152              which resides within the same Orber domain.
153
154       iiop_connection_timeout() -> int() (milliseconds)
155
156              This  function  returns  the  timeout value after which outgoing
157              IIOP connections terminate. It can be configured by setting  the
158              application  variable iiop_connection_timeout TimeVal (seconds),
159              if it is not set it will have the default  value  infinity.  The
160              connection will not be terminated if there are pending requests.
161
162              Note:   the   iiop_connection_timeout   configuration  parameter
163              (TimeVal) may only range between 0 and 1000000  seconds.  Other‐
164              wise, the default value is used.
165
166       iiop_connections() -> Result
167       iiop_connections(Direction) -> Result
168
169              Types:
170
171                 Direction = in | out | inout
172                 Result  =  [{Host,  Port}]  |  [{Host,  Port,  Interface}]  |
173                 {'EXIT',Reason}
174                 Host = string()
175                 Port = integer()
176                 Interface = string()
177                 Reason = term()
178
179              The list returned by this operation  contain  tuples  of  remote
180              hosts/ports  Orber is currently connected to. If no Direction is
181              not supplied, both incoming and  outgoing  connections  are  in‐
182              cluded.
183
184              If  a  specific local interface has been defined for the connec‐
185              tion, this will be added to the returned tuple.
186
187       iiop_connections_pending() -> Result
188
189              Types:
190
191                 Result  =  [{Host,  Port}]  |  [{Host,  Port,  Interface}]  |
192                 {'EXIT',Reason}
193                 Host = string()
194                 Port = integer()
195                 Interface = string()
196                 Reason = term()
197
198              In  some  cases a connection attempt (i.e. trying to communicate
199              with another ORB) may block due to a number of reasons. This op‐
200              eration  allows  the  user to check if this is the case. The re‐
201              turned list contain tuples of remote hosts/ports. Normally,  the
202              list is empty.
203
204              If  a  specific local interface has been defined for the connec‐
205              tion, this will be added to the returned tuple.
206
207       iiop_in_connection_timeout() -> int() (milliseconds)
208
209              This function returns the timeout  value  after  which  incoming
210              IIOP  connections terminate. It can be configured by setting the
211              application variable  iiop_in_connection_timeout  TimeVal  (sec‐
212              onds), if it is not set it will have the default value infinity.
213              The connection will not be terminated if there are  pending  re‐
214              quests.
215
216              Note:  the  iiop_in_connection_timeout  configuration  parameter
217              (TimeVal) may only range between 0 and 1000000  seconds.  Other‐
218              wise, the default value is used.
219
220       iiop_acl() -> Result
221
222              Types:
223
224                 Result = [{Direction, Filter}] | [{Direction, Filter, [Inter‐
225                 face]}]
226                 Direction = tcp_in | ssl_in | tcp_out | ssl_out
227                 Filter = string()
228                 Interface = string()
229
230              Returns the ACL configuration. The Filter uses a extended format
231              of   Classless   Inter   Domain  Routing  (CIDR).  For  example,
232              "123.123.123.10" limits the connection to that particular  host,
233              while "123.123.123.10/17" allows connections to or from any host
234              equal to the 17 most significant bits. Orber also allow the user
235              to   specify   a  certain  port  or  port  range,  for  example,
236              "123.123.123.10/17#4001" and  "123.123.123.10/17#4001/5001"  re‐
237              spectively. IPv4 or none compressed IPv6 strings are accepted.
238              The list of Interfaces, IPv4 or IPv6 strings, are currently only
239              used for outgoing connections and may only contain one  address.
240              If  set  and access is granted, Orber will use that local inter‐
241              face when connecting to the other ORB. The module orber_acl pro‐
242              vides  operations  for evaluating the access control for filters
243              and addresses.
244
245       activate_audit_trail() -> Result
246       activate_audit_trail(Verbosity) -> Result
247
248              Types:
249
250                 Verbosity = stealth | normal | verbose
251                 Result = ok | {error, Reason}
252                 Reason = string()
253
254              Activates audit/trail for all  existing  incoming  and  outgoing
255              IIOP  connections.  The  Verbosity parameter, stealth, normal or
256              verbose, determines which of the built in interceptors  is  used
257              (orber_iiop_tracer_stealth,   orber_iiop_tracer_silent   or  or‐
258              ber_iiop_tracer respectively). If no  verbosity  level  is  sup‐
259              plied, then the normal will be used.
260
261              In  case  Orber is configured to use other interceptors, the au‐
262              dit/trail interceptors will simply be added to that list.
263
264       deactivate_audit_trail() -> Result
265
266              Types:
267
268                 Result = ok | {error, Reason}
269                 Reason = string()
270
271              Deactivates audit/trail for all existing incoming  and  outgoing
272              IIOP  connections.  In case Orber is configured to use other in‐
273              terceptors, those will still be used.
274
275       add_listen_interface(IP, Type) -> Result
276       add_listen_interface(IP, Type, Port) -> Result
277       add_listen_interface(IP, Type, ConfigurationParameters) -> Result
278
279              Types:
280
281                 IP = string
282                 Type = normal | ssl
283                 Port = integer() > 0
284                 ConfigurationParameters = [{Key, Value}]
285                 Key  =  flags  |  ip_family  |  iiop_in_connection_timeout  |
286                 iiop_max_fragments  |  iiop_max_in_requests  | interceptors |
287                 iiop_port | iiop_ssl_port | ssl_server_options
288                 Value = as described in the User's Guide or below
289                 Result  =  {ok,  Ref}  |  {error,  Reason}  |   {'EXCEPTION',
290                 #'BAD_PARAM'{}}
291                 Ref = #Ref
292                 Reason = string()
293
294              Create a new process that handle requests for creating a new in‐
295              coming IIOP connection via the given interface and port. If  the
296              latter is excluded, Orber will use the value of the iiop_port or
297              iiop_ssl_port configuration parameters. The Type  parameter  de‐
298              termines  if  it is supposed to be IIOP or IIOP via SSL. If suc‐
299              cessful, the returned #Ref shall be passed to  orber:remove_lis‐
300              ten_interface/1 when the connection shall be terminated.
301
302              It  is  also  possible  to  supply configuration parameters that
303              override the global configuration. The  iiop_in_connection_time‐
304              out,  iiop_max_fragments,  iiop_max_in_requests and interceptors
305              parameters simply overrides the  global  counterparts  (See  the
306              Configuration  chapter in the User's Guide). But for the follow‐
307              ing parameters there are a few restrictions:
308
309                * flags - currently it is only possible to override the global
310                  setting  for  the  Use  Current Interface in IOR and Exclude
311                  CodeSet Component flags.
312
313                * ip_family - can be set to inet or inet6 and is used to get a
314                  listen  interface  that uses another IP version than the de‐
315                  fault set with flags at startup.
316
317                * iiop_port - requires that Use Current Interface  in  IOR  is
318                  activated  and  the supplied Type is normal. If so, exported
319                  IOR:s will contain the IIOP port defined by this  configura‐
320                  tion parameter. Otherwise, the global setting will be used.
321
322                * iiop_ssl_port  - almost equivalent to iiop_port. The differ‐
323                  ence is that Type shall be ssl and that exported IOR:s  will
324                  contain  the IIOP via SSL port defined by this configuration
325                  parameter.
326
327              If it is not possible to add a listener based  on  the  supplied
328              interface  and  port,  the  error message is one of the ones de‐
329              scribed in inet and/or ssl documentation.
330
331       remove_listen_interface(Ref) -> ok
332
333              Types:
334
335                 Ref = #Ref
336
337              Terminates the listen  process,  associated  with  the  supplied
338              #Ref, for incoming a connection. The Ref parameter is the return
339              value from the  orber:add_listen_interface/2/3  operation.  When
340              terminating the connection, all associated requests will not de‐
341              liver a reply to the clients.
342
343       close_connection(Connection) -> Result
344       close_connection(Connection, Interface) -> Result
345
346              Types:
347
348                 Connection = Object | [{Host, Port}]
349                 Object = #objref (external)
350                 Host = string()
351                 Port = string()
352                 Interface = string()
353                 Result = ok | {'EXCEPTION', #'BAD_PARAM'{}}
354
355              Will try to close all outgoing connections to the host/port com‐
356              binations  found  in  the supplied object reference or the given
357              list of hosts/ports. If a #'IOP_ServiceContext'{}  containing  a
358              local interface has been used when communicating with the remote
359              object (see also  Module_Interface),  that  interface  shall  be
360              passed  as  the  second argument. Otherwise, connections via the
361              default local interface, will be terminated.
362
363          Note:
364              Since several clients maybe communicates via  the  same  connec‐
365              tion,  they will be affected when invoking this operation. Other
366              clients may re-create the connection by invoking an operation on
367              the target object.
368
369
370       secure() -> no | ssl
371
372              This  function  returns  the  security mode Orber is running in,
373              which is either no if it is an insecure domain or  the  type  of
374              security mechanism used. For the moment the only security mecha‐
375              nism is ssl. This is configured by setting the application vari‐
376              able secure.
377
378       ssl_server_options() -> list()
379
380              This  function returns the list of SSL options set for the Orber
381              domain as server. This is configured by setting the  application
382              variable ssl_server_options.
383
384       ssl_client_options() -> list()
385
386              This  function  returns the list of SSL options used in outgoing
387              calls in the current process. The default value is configured by
388              setting the application variable ssl_client_options.
389
390       set_ssl_client_options(Options) -> ok
391
392              Types:
393
394                 Options = list()
395
396              This  function takes a list of SSL options as parameter and sets
397              it for the current process.
398
399       objectkeys_gc_time() -> int() (seconds)
400
401              This function returns the timeout value after which after  which
402              terminated object keys, related to servers started with the con‐
403              figuration parameter {persistent, true}, will be removed. It can
404              be   configured  by  setting  the  application  variable  objec‐
405              tkeys_gc_time TimeVal (seconds), if it is not set it  will  have
406              the default value infinity.
407
408              Objects  terminating  with reason normal or shutdown are removed
409              automatically.
410
411              Note: the objectkeys_gc_time configuration  parameter  (TimeVal)
412              may only range between 0 and 1000000 seconds. Otherwise, the de‐
413              fault value is used.
414
415       orber_nodes() -> RetVal
416
417              Types:
418
419                 RetVal = [node()]
420
421              This function returns the list of node names that this orber do‐
422              main consists of.
423
424       install(NodeList) -> ok
425       install(NodeList, Options) -> ok
426
427              Types:
428
429                 NodeList = [node()]
430                 Options = [Option]
431                 Option  =  {install_timeout,  Timeout}  |  {ifr_storage_type,
432                 TableType} | {nameservice_storage_type,  TableType}  |  {ini‐
433                 tialreferences_storage_type, TableType} | {load_order, Prior‐
434                 ity}
435                 Timeout = infinity | integer()
436                 TableType = disc_copies | ram_copies
437                 Priority = integer()
438
439              This function installs all the necessary mnesia tables and  load
440              default  data  in  some of them. If one or more Orber tables al‐
441              ready exists the installation fails. The function uninstall  may
442              be  used,  if  it is safe, i.e., no other application is running
443              Orber.
444
445              Preconditions:
446
447                * a mnesia schema must exist before the installation
448
449                * mnesia is running on the other nodes if the new installation
450                  shall be a multi node domain
451
452              Mnesia will be started by the function if it is not already run‐
453              ning on the installation node and if it was started it  will  be
454              stopped afterwards.
455
456              The options that can be sent to the installation program is:
457
458                * {install_timeout,  Timeout}  -  this  timeout is how long we
459                  will wait for the tables to be created.  The  Timeout  value
460                  can  be  infinity  or an integer number in milliseconds. De‐
461                  fault is infinity.
462
463                * {ifr_storage_type, TableType} - this option sets the type of
464                  tables  used for the interface repository. The TableType can
465                  be disc_copies or ram_copies. Default is disc_copies.
466
467                * {initialreferences_storage_type, TableType}  -  this  option
468                  sets  the type of table used for storing initial references.
469                  The TableType can be disc_copies or ram_copies.  Default  is
470                  ram_copies.
471
472                * {nameservice_storage_type, TableType} - the default behavior
473                  of Orber is to install the NameService as  ram_copies.  This
474                  option  makes it possible to change this to disc_copies. But
475                  the user should be aware of that if a node is restarted, all
476                  local  object  references  stored  in the NameService is not
477                  valid. Hence, you cannot switch to  disc_copies  and  expect
478                  exactly the same behavior as before.
479
480                * {load_order,  Priority} - per default the priority is set to
481                  0. Using this option it will change the priority of in which
482                  order  Mnesia  will load Orber internal tables. For more in‐
483                  formation, consult the Mnesia documentation.
484
485       uninstall() -> ok
486
487              This function stops the Orber application, terminates all server
488              objects and removes all Orber related mnesia tables.
489
490              Note:  Since  other applications may be running on the same node
491              using mnesia uninstall will not stop the mnesia application.
492
493       add_node(Node, Options) -> RetVal
494
495              Types:
496
497                 Node = node()
498                 Options = IFRStorageType | [KeyValue]
499                 IFRStorageType = StorageType
500                 StorageType = disc_copies | ram_copies
501                 KeyValue = {ifr_storage_type, StorageType}  |  {initialrefer‐
502                 ences_storage_type, StorageType} | {nameservice_storage_type,
503                 StorageType} | {type, Type}
504                 Type = temporary | permanent
505                 RetVal = ok | exit()
506
507              This function add given node to a existing Orber node group  and
508              starts  Orber  on  the new node. orber:add_node is called from a
509              member in the Orber node group.
510
511              Preconditions for new node:
512
513                * Erlang started on the new node using the option -mnesia  ex‐
514                  tra_db_nodes,  e.g.,  erl  -sname  new_node_name -mnesia ex‐
515                  tra_db_nodes ConnectToNodes_List
516
517                * The new node's domain name is the same for the nodes we want
518                  to connect to.
519
520                * Mnesia is running on the new node (no new schema created).
521
522                * If the new node will use disc_copies the schema type must be
523                  changed using: mnesia:change_table_copy_type(schema, node(),
524                  disc_copies).
525
526              Orber will be started by the function on the new node.
527
528              Fails if:
529
530                * Orber already installed on given node.
531
532                * Mnesia not started as described above on the new node.
533
534                * Impossible to copy data in Mnesia tables to the new node.
535
536                * Not  able  to start Orber on the new node, due to, for exam‐
537                  ple, the iiop_port is already in use.
538
539              The function do not remove already copied tables after  a  fail‐
540              ure. Use orber:remove_node to remove these tables.
541
542       remove_node(Node) -> RetVal
543
544              Types:
545
546                 Node = node()
547                 RetVal = ok | exit()
548
549              This  function  removes  given node from a Orber node group. The
550              Mnesia application is not stopped.
551
552       configure(Key, Value) -> ok | {'EXIT', Reason}
553
554              Types:
555
556                 Key  =  orbDefaultInitRef  |  orbInitRef  |  giop_version   |
557                 iiop_timeout  |  iiop_connection_timeout | iiop_setup_connec‐
558                 tion_timeout   |    iiop_in_connection_timeout    |    objec‐
559                 tkeys_gc_time | orber_debug_level
560                 Value = allowed value associated with the given key
561
562              This  function  allows the user to configure Orber in, for exam‐
563              ple, an Erlang shell. It is possible to invoke configure at  any
564              time the keys specified above.
565
566              Any other key must be set before installing and starting Orber.
567
568              Trying  to  change the configuration in any other way is NOT al‐
569              lowed since it may affect the behavior of Orber.
570
571              For more information regarding allowed values, see configuration
572              settings in the User's Guide.
573
574          Note:
575              Configuring  the IIOP timeout values will not affect already ex‐
576              isting connections. If you want a guaranteed  uniform  behavior,
577              you must set these parameters from the start.
578
579
580
581
582Ericsson AB                       orber 5.0.2                         orber(3)
Impressum