The R13B03 release.OTP_R13B03

1 files changed, 209 insertions, 0 deletions

diff --git a/lib/orber/doc/src/ch_debugging.xml b/lib/orber/doc/src/ch_debugging.xml
new file mode 100644
index 0000000000..8c5685bc63
--- /dev/null
+++ b/lib/orber/doc/src/ch_debugging.xml
@@ -0,0 +1,209 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2001</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>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>
+