diff options
Diffstat (limited to 'lib/orber/doc/src/ch_debugging.xml')
| -rw-r--r-- | lib/orber/doc/src/ch_debugging.xml | 209 |
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> + |