<?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>
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>
