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

NAME

       corba - The functions on CORBA module level

DESCRIPTION

       This  module  contains  functions  that  are  specified on the CORBA module level. It also
       contains some functions for creating and disposing objects.

EXPORTS

       create(Module, TypeID) -> Object
       create(Module, TypeID, Env) -> Object
       create(Module, TypeID, Env, Optons1) -> Object
       create_link(Module, TypeID) -> Object
       create_link(Module, TypeID, Env) -> Object
       create_link(Module, TypeID, Env, Options2) -> Reply

              Types:

                 Module = atom()
                 TypeID = string()
                 Env = term()
                 Options1 = [{persistent, Bool} | {regname, RegName} | {local_typecheck, Bool}]
                 Options2 = [{sup_child, Bool}  |  {persistent,  Bool}  |  {regname,  RegName}  |
                 {pseudo, Bool} | {local_typecheck, Bool}]
                 RegName = {local, atom()} | {global, term()}
                 Reply = #objref | {ok, Pid, #objref}
                 Bool = true | false
                 Object = #objref

              These  functions  start a new server object. If you start it without RegName it can
              only be accessed through the returned object key. Started with a RegName  the  name
              is registered locally or globally.

              TypeID  is  the  repository ID of the server object type and could for example look
              like "IDL:StackModule/Stack:1.0".

              Module is the name of the interface API module.

              Env is the arguments passed which will be passed to the implementations init  call-
              back function.

              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.

              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.

              If you use the  option  {sup_child,  true}  create_link/4  will  return  {ok,  Pid,
              #objref}, otherwise #objref, and make it possible to start a server as a supervisor
              child (stdlib-1.7 or later).

              If you use the option {persistent, true} you also must  use  the  option  {regname,
              {global,  Name}}. This combination makes it possible to tell the difference between
              a server permanently terminated or in the process of restarting.

              The option {pseudo, true}, allow us to create an object  which  is  not  a  server.
              Using  {pseudo,  true}  overrides all other start options. For more information see
              section Module_Interface.

              If a server is started using the option {persistent, true} the object key will  not
              be  removed  unless  it  terminates  with  reason  normal  or  shutdown.  Hence, if
              persistent servers is used as supervisor children they should be transient and  the
              objectkeys_gc_time should be modified (default equals infinity).

              The  option  {local_typecheck,  boolean()},  which overrides the Local Typechecking
              environment flag, turns on or off typechecking. If activated,  parameters,  replies
              and  raised  exceptions  will  be  checked to ensure that the data is correct, when
              invoking operations on CORBA Objects within the same Orber domain. Due to the extra
              overhead, this option MAY ONLY be used during testing and development.

              Example:

                corba:create('StackModule_Stack', "IDL:StackModule/Stack:1.0", {10, test})

       dispose(Object) -> ok

              Types:

                 Object = #objref

              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
              corba:create_nil_objref/0,  always return ok. For valid object references, invoking
              this operation more than once, will result in a system exception.

       create_nil_objref() -> Object

              Types:

                 Object = #objref representing NIL.

              Creates an object reference that represents  the  NIL  value.  Attempts  to  invoke
              operations using the returned object reference will return a system exception.

       create_subobject_key(Object, Key) -> Result

              Types:

                 Object = #objref
                 Key = term()
                 Result = #objref

              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 Result 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
              get_subobject_key/1 function to get the private key value.

              Key  is  stored in the object reference Object. If it is a binary it will be stored
              as is and otherwise it is converted to a binary before storage.

       get_subobject_key(Object) -> Result

              Types:

                 Object = #objref
                 Result = #binary

              This function is used to fetch a subobject key from the  object  reference  Object.
              The  result  is  a  always  a binary, if it was an Erlang term that was stored with
              create_subobject_key/2 one can to do binary_to_term/1 to get the real value.

       get_pid(Object) -> Result

              Types:

                 Object = #objref
                 Result = #pid | {error, Reason} | {'EXCEPTION',E}

              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.

       raise(Exception)

              Types:

                 Exception = record()

              This function is used for raising corba exceptions as an Erlang user generated exit
              signal. It will throw the tuple {'EXCEPTION', Exception}.

       reply(To, Reply) -> true

              Types:

                 To = client reference
                 Reply = IDL type

              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 not possible  to
              return a reply in the call-back module.
              To must be the From argument provided to the callback function, which requires that
              the IC option from was used when compiling the IDL-file.

       resolve_initial_references(ObjectId) -> Object
       resolve_initial_references(ObjectId, Contexts) -> Object

              Types:

                 ObjectId = string()
                 Contexts = [Context]
                 Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}
                 CtxId = ?ORBER_GENERIC_CTX_ID
                 CtxData = {interface, Interface}  |  {userspecific,  term()}  |  {configuration,
                 Options}
                 Interface = string()
                 Options = [{Key, Value}]
                 Key = ssl_client_options
                 Value = allowed value associated with the given key
                 Object = #objref

              This  function  returns  the  object reference associated with the given object id.
              Initially,  only  "NameService"  is  available.  To  add  or  remove  services  use
              add_initial_service/2 or remove_initial_service/1.

              The  configuration  context  is  used  to  override  the  global  SSL  client  side
              configuration.

       add_initial_service(ObjectId, Object) -> boolean()

              Types:

                 ObjectId = string()
                 Object = #objref

              This operation allows us to add initial services, which can be  accessed  by  using
              resolve_initial_references/1  or the corbaloc schema. If using an Id defined by the
              OMG, the given object must be of the correct type; for  more  information  see  the
              Interoperable Naming Service. Returns false if the given id already exists.

       remove_initial_service(ObjectId) -> boolean()

              Types:

                 ObjectId = string()

              If  we don not want a certain service to be accessible, invoking this function will
              remove the association. Returns true if able to terminate the binding. If  no  such
              binding existed false is returned.

       list_initial_services() -> [ObjectId]

              Types:

                 ObjectId = string()

              This function returns a list of allowed object id's.

       resolve_initial_references_remote(ObjectId, Address) -> Object
       resolve_initial_references_remote(ObjectId, Address, Contexts) -> Object

              Types:

                 ObjectId = string()
                 Address = [RemoteModifier]
                 RemoteModifier = string()
                 Contexts = [Context]
                 Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}
                 CtxId = ?ORBER_GENERIC_CTX_ID
                 CtxData  =  {interface,  Interface}  |  {userspecific, term()} | {configuration,
                 Options}
                 Interface = string()
                 Options = [{Key, Value}]
                 Key = ssl_client_options
                 Value = allowed value associated with the given key
                 Object = #objref

              This function returns the object reference for the object id asked for. The  remote
              modifier string has the following format: "iiop://host:port".

              The  configuration  context  is  used  to  override  the  global  SSL  client  side
              configuration.

          Warning:
              This operation is not supported by most ORB's. Hence, use  corba:string_to_object/1
              instead.

       list_initial_services_remote(Address) -> [ObjectId]
       list_initial_services_remote(Address, Contexts) -> [ObjectId]

              Types:

                 Address = [RemoteModifier]
                 RemoteModifier = string()
                 Contexts = [Context]
                 Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}
                 CtxId = ?ORBER_GENERIC_CTX_ID
                 CtxData  =  {interface,  Interface}  |  {userspecific, term()} | {configuration,
                 Options}
                 Interface = string()
                 Options = [{Key, Value}]
                 Key = ssl_client_options
                 Value = allowed value associated with the given key
                 ObjectId = string()

              This function returns a list of allowed object id's. The remote modifier string has
              the following format: "iiop://host:port".

              The  configuration  context  is  used  to  override  the  global  SSL  client  side
              configuration.

          Warning:
              This operation is not supported by most ORB's. Hence, avoid using it.

       object_to_string(Object) -> IOR_string

              Types:

                 Object = #objref
                 IOR_string = string()

              This function returns the object reference as the external string representation of
              an IOR.

       string_to_object(IOR_string) -> Object
       string_to_object(IOR_string, Contexts) -> Object

              Types:

                 IOR_string = string()
                 Contexts = [Context]
                 Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}
                 CtxId = ?ORBER_GENERIC_CTX_ID
                 CtxData  =  {interface,  Interface}  |  {userspecific, term()} | {configuration,
                 Options}
                 Interface = string()
                 Options = [{Key, Value}]
                 Key = ssl_client_options
                 Value = allowed value associated with the given key
                 Object = #objref

              This function takes a  corbaname,  corbaloc  or  an  IOR  on  the  external  string
              representation and returns the object reference.

              To       lookup       the       NameService       reference,       simply       use
              "corbaloc:iiop:1.2@123.0.0.012:4001/NameService"

              We   can   also   resolve   an   object   from    the    NameService    by    using
              "corbaname:iiop:1.2@123.0.0.012:4001/NameService#org/Erlang/MyObj"

              For   more   information  about  corbaname  and  corbaloc,  see  the  User's  Guide
              (Interoperable Naming Service).

              The  configuration  context  is  used  to  override  the  global  SSL  client  side
              configuration.

              How to handle the interface context is further described in the User's Guide.

       print_object(Data [, Type]) -> ok | {'EXCEPTION', E} | {'EXIT', R} | string()

              Types:

                 Data = IOR_string | #objref (local or external) | corbaloc/corbaname string
                 Type  = IoDevice | error_report | {error_report, Reason} | info_msg | {info_msg,
                 Comment} | string
                 IoDevice = see the io-module
                 Reason = Comment = string()

              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 error_report and info_msg  the  error_logger  module  is  used,  with  or
              without Reason or Comment. If the atom string is supplied this function will return
              a flat list. The IoDevice is passed to the operation io:format/2.

              If the supplied object is a local reference, the output is equivalent to an  object
              exported from the node this function is invoked on.

       add_alternate_iiop_address(Object, Host, Port) -> NewObject | {'EXCEPTION', E}

              Types:

                 Object = NewObject = local #objref
                 Host = string()
                 Port = integer()

              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.

              The  ALTERNATE_IIOP_ADDRESS  component  requires that IIOP-1.2 is used. Hence, make
              sure both Orber and the other ORB is correctly configured.

          Note:
              Make sure that the given Object is accessible  via  the  alternate  Host/port.  For
              example,  if  the object is correctly started as local or pseudo, 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.

       orb_init(KeyValueList) -> ok | {'EXIT', Reason}

              Types:

                 KeyValueList = [{Key, Value}]
                 Key = any key listed in the configuration chapter
                 Value = allowed value associated with the given key

              This function allows the user to configure Orber in, for example, an Erlang  shell.
              Orber  may  NOT  be started prior to invoking this operation. For more information,
              see configuration settings in the User's Guide.