aboutsummaryrefslogtreecommitdiffstats
path: root/lib/orber/doc/src/ch_debugging.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/orber/doc/src/ch_debugging.xml')
-rw-r--r--lib/orber/doc/src/ch_debugging.xml209
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>
+