<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2001</year><year>2013</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>Debugging</title>
    <prepared></prepared>
    <docno></docno>
    <date>2001-11-29</date>
    <rev></rev>
    <file>ch_debugging.xml</file>
  </header>

  <section>
    <title>Tools and FAQ</title>
    <p>Persons who use Orber for the first time may find it hard to tell what goes
      wrong when trying to setup communication between an Orber-ORB and ORB:s supplied
      by another vendor or another Orber-ORB. The purpose of this chapter is to inform
      about the most common mistakes and what tools one can use to overcome these 
      problems. </p>

    <section>
      <title>Tools</title>
      <p>To begin with, Orber can be configured to run in debug mode. There are four ways
        to set this parameter:</p>
      <list type="bulleted">
        <item><em>erl -orber orber_debug_level 10</em> - can be added to a start-script.</item>
        <item><em>corba:orb_init([{orber_debug_level, 10}])</em> - this operation must
         be invoked <em>before</em> starting Orber.</item>
        <item><em>orber:configure(orber_debug_level, 10)</em> - this operation can
         be invoked at any time.</item>
        <item><em>OrberWeb</em> - via the <c>Configuration</c> menu one can easily change
         the configuration. For more information, see the OrberWeb chapter in this
         User's Guide.</item>
      </list>
      <p>When Orber runs i debug mode, printouts will be generated if anything abnormal occurs
        (not necessarily an error). An error message typically looks like:</p>
      <code type="none">
=ERROR REPORT==== 29-Nov-2001::14:09:55 ===
=================== Orber =================
[410] corba:common_create(orber_test_server, [{pseudo,truce}]); 
not a boolean(truce).
===========================================
      </code>
      <p>In the example above, we tried to create an object with an incorrect option (i.e. should
        have been <c>{pseudo,true}</c>).</p>
      <p>If you are not able to solve the problem, you should include all generated reports when
        contacting support or using the erlang-questions mailing list.</p>
      <p>It is easy to forget to, for example, set all fields in a struct, which
        one may not discover when developing an application using Orber. When using
        a typed language, such faults would cause a compile time error. To avoid
        these mistakes, Orber allows the user to activate automatic typechecking
        of all local invocations of CORBA Objects. For this feature to be really
        useful, the user must create test suites which cover as much as 
        possible. For example, invoking an operation with invalid or incorrect
        arguments should also be tested. This option can be activated for one object
        or all object via:</p>
      <list type="bulleted">
        <item><em>'MyModuyle_MyInterface':oe_create(Env, [{local_typecheck, true}])</em> - 
         This approach will only activate, or deactivate, typechecking for
         the returned instance. Naturally, this option can also be passed
         to <c>oe_create_link/2</c>, <c>corba:create/4</c> and 
        <c>corba:create_link/4</c>.</item>
        <item><em>erl -orber flags 2</em> - can be added to a start-script.
         All object invocations will be typechecked, unless overridden by the
         previous option.</item>
        <item><em>corba:orb_init([{flags, 16#0002}])</em> - this operation must
         be invoked <em>before</em> starting Orber. Behaves as the previous
         option.</item>
      </list>
      <p>If incorrect data is passed or returned, Orber uses the <c>error_logger</c>
        to generate logs, which can look like:</p>
      <code type="none">
=ERROR REPORT==== 10-Jul-2002::12:36:09 ===
========= Orber Typecheck Request =========
Invoked......: MyModule_MyInterface:foo/1
Typecode.....: [{tk_enum,"IDL:MyModule/enumerant:1.0",
                         "enumerant",
                         ["one","two"]}]
Arguments....: [three]
Result.......: {'EXCEPTION',{'MARSHAL',[],102,'COMPLETED_NO'}}
===========================================
      </code>
      <p>Note, that the arity is equivalent to the IDL-file. In the example above,
        an undefined enumerant was used. In most cases, it is useful to set the
        configuration parameter <c>orber_debug_level 10</c> as well. Due to the
        extra overhead, this option <em>MAY ONLY</em> be used during testing and
        development.
        For more information, see also
        <seealso marker="ch_install#config">configuration settings</seealso>.</p>
      <p>It is also possible to trace all communication between an Orber-ORB and, for example,
        a Java-ORB, communicating via IIOP. All you need to do is to activate an 
        <seealso marker="ch_interceptors">interceptor</seealso>. Normally, the users must
        implement the interceptor themselves, but for your convenience Orber includes three
        pre-compiled interceptors called <c>orber_iiop_tracer</c>,
        <c>orber_iiop_tracer_silent</c> and <c>orber_iiop_tracer_stealth</c>.</p>
      <warning>
        <p>Logging all traffic is <em>expensive</em>. Hence, only use the supplied 
          interceptors during test and development.</p>
      </warning>
      <p>The <c>orber_iiop_tracer</c> and <c>orber_iiop_tracer_silent</c> interceptors
        uses the <c>error_logger</c> module to generate the logs. If the traffic 
        is intense you probably want to write the reports to a log-file. 
        This is done by, for example, invoking:</p>
      <code type="none">
erl> error_logger:tty(false). 
erl> error_logger:logfile({open, "/tmp/IIOPTrace"}). 
      </code>
      <p>The <c>IIOPTrace</c> file will contain, if you use the <c>orber_iiop_tracer</c> 
        interceptor, reports which looks like:</p>
      <code type="none">
=INFO REPORT==== 13-Jul-2005::18:22:39 ===
=============== new_out_connection =======
Node      : myNode@myHost
From      : 192.0.0.10:47987
To        : 192.0.0.20:4001
==========================================

=INFO REPORT==== 29-Nov-2001::15:26:28 ===
=============== out_request ==============
Connection: {"192.0.0.20",4001,"192.0.0.10",47987}
Operation : resolve
Parameters: [[{'CosNaming_NameComponent',
                "AIK","SwedishIcehockeyChampions"}]]
Context   : [{'IOP_ServiceContext',1,
               {'CONV_FRAME_CodeSetContext',65537,65801}}]
==========================================
      </code>
      <p>The <c>orber_iiop_tracer_silent</c> will not log GIOP encoded data. To activate
        one the interceptors, you have two options:</p>
      <list type="bulleted">
        <item><em>erl -orber interceptors "{native,[orber_iiop_tracer]}"</em> - can be added to a start-script.</item>
        <item><em>corba:orb_init([{interceptors, {native, [orber_iiop_tracer_silent]}}])</em> - this operation must
         be invoked <em>before</em> starting Orber.</item>
      </list>
      <p>It is also possible to active and deactivate an interceptor during
        run-time, but this will only affect currently existing connections. 
        For more information, consult Orber's Reference Manual regarding the
        operations <c>orber:activate_audit_trail/0/1</c> and
        <c>orber:activate_audit_trail/0/1.</c></p>
    </section>

    <section>
      <title>FAQ</title>
      <p><em>Q: When my client, typically written in C++ or Java, invoke narrow on an Orber  object reference it fails?</em></p>
      <p>A: You must register your application in the IFR by invoking <c>oe_register()</c>. 
        If the object was created by a COS-application, you must run install 
        (e.g. <c>cosEventApp:install()</c>).</p>
      <p>A: Confirm, by consulting the IDL specifications, that the received object reference really
        inherit from the interface you are trying to narrow it to.</p>
      <br></br>
      <p><em>Q: I am trying to register my application in the IFR but it fails. Why?</em></p>
      <p>A: If one, or more, interface in your IDL-specification inherits from
        other interface(s), you must register them before registering your
        application. Note, this also apply when you inherit interfaces
        supported by a COS-application. Hence, they must be installed prior to
        registration of your application.</p>
      <br></br>
      <p><em>Q: I have a Orber client and server residing on two different Orber instances but I only get the 'OBJECT_NOT_EXIST' exception, even though I am sure that the object is still alive?</em></p>
      <p>A: If the two Orber-ORB's are not intended to be a part of multi-node ORB, make sure that the
        two Orber-ORB's have different <em>domain</em> names set (see
        <seealso marker="ch_install#config">configuration settings</seealso>). The easiest way
        to confirm this is to invoke <c>orber:info()</c> on each node.</p>
      <br></br>
      <p><em>Q: When I'm trying to install and/or start Orber it fails?</em></p>
      <p>A: Make sure that no other Orber-ORB is already running on the same node. If so,
        change the <c>iiop_port</c> configuration parameter (see
        <seealso marker="ch_install#config">configuration settings</seealso>).</p>
      <br></br>
      <p><em>Q: My Orber server is invoked via IIOP but Orber cannot marshal the  reply?</em></p>
      <p>A: Consult your IDL file to confirm that your replies are of the correct
        type. If it is correct and the return type is, for example,
        a struct, make sure you have set every field in the struct. If
        you do not do that it will be set to the atom 'undefined', which
        most certainly is not correct.</p>
      <br></br>
      <p>A: Check that you handle <c>inout</c> and <c>out</c> parameters correctly
        (see the IDL specification). For example, a function which have one
        out-parameter and should return void, then your call-back module
        should return <c>{reply, {ok, OutParam}, State}</c>. Note, even though
        the return value is void (IDL) you must reply with ok.</p>
      <br></br>
      <p><em>Q: I cannot run Orber as a multi-node ORB?</em></p>
      <p>A: Make sure that the Erlang distribution have been started for each
        node and the <c>cookies</c> are correct. For more information,
        consult the <c>System Documentation</c></p>
      <br></br>
    </section>
  </section>
</chapter>

