ACE/docs/exceptions.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
   2 <!--  -->
   3 <html> <head>
   4 <title>Using ACE Exception Handling Macros to Enhance CORBA Portability</title>
   5 </head>
   6
   7 <body text="#000000" link="#0000ff" vlink="#cc0000" bgcolor="#ffffff">
   8 <Hr><P>
   9 <h3>Using ACE Exception Handling Macros to Enhance CORBA Portability</h3>
  10
  11 <P>CORBA <CODE>Environment</CODE> arguments provide a way to handle
  12 exceptions when native c++ exception handling is unavailable or
  13 undesirable.  However, writing portable code using both native C++
  14 exception handling and <CODE>CORBA::Environment</CODE> objects is very
  15 hard.  If you plan to write portable code that must run on platforms
  16 that do not have native C++ exceptions, therefore, we recommend you
  17 use the ACE exception macros.  This document explains how these macros
  18 can help alleviate much of the accidental complexity.  However, keep
  19 in mind macros cannot solve all problems perfectly.  </P>
  20
  21 <P>Before reading the rest of this document, we recommend you check
  22 out pages 307 through to 322 in the book, <A
  23 HREF="http://cseng.aw.com/bookdetail.qry?ISBN=0-201-37927-9&ptype=0">Advanced
  24 Corba Programming with C++</A> by <A
  25 HREF="http://www.triodia.com/staff/michi-henning.html">Michi
  26 Henning</A> & <A HREF="http://www.iona.com/hyplan/vinoski/">Steve
  27 Vinoski</A>.  Likewise, we recommend that you read the Error Handling chapter from the
  28 <A HREF="http://www.theaceorb.com/product/">TAO Developer's Guide</A>.
  29
  30 <P><HR><P>
  31 <h3>Table of Contents</h3>
  32 <ul>
  33   <li><a href="#nutshell">ACE Try Macros in a Nutshell</a>
  34   <li><a href="#examples">Examples</a>
  35   <li><a href="#general">General Guidelines for Exception Handling</a>
  36   <li><a href="#transition">Transition from ACE_TRY_ENV usage to the
  37       ACE_ENV_ARG macros</a>
  38   <li><a href="#caveats">Some Caveats</a>
  39 </ul>
  40
  41 <HR><P>
  42 <h3><a name="nutshell">ACE Exception Macros in a Nutshell</h3>
  43
  44 <P>This section explains some simple rules of writing programs for
  45 platforms with and without native exception support using ACE's
  46 exception macros.
  47 </P>
  48 <P>ACE exception macros are modelled like C++ language exceptions and
  49 can be used like them, but with a small difference. These macros
  50 rely on  the CORBA::Environment variable to handle exceptions
  51 on platforms that do not support exception
  52 handling. (Please note that native exceptions can be turned on
  53 or off at COMPILE time as an option to your make)
  54 The exception macros have been modelled with some extra rules to
  55 ensure this works even on
  56 platforms without native exception support.  See some <a
  57 href="#examples">quick examples</a> on  how to use ACE exception
  58 macros.
  59 </P>
  60 <ol>
  61   <li><P><em>Declaration of CORBA::Environment Parameter at Methods</em><br>
  62       On platforms lacking native exceptions, all CORBA methods take an
  63       extra parameter added at the end of their argument list. This
  64       last parameter holds the CORBA::Environment variable.
  65       However, on systems with native exceptions, no such extra method
  66       parameter is added.<br>
  67       In order for both configurations to work with the same source code,
  68       following macros are defined. In native exception configurations,
  69       they all resolve to <em>empty</em>.</p>
  70       <ul>
  71         <li><p><em>ACE_ENV_ARG_DECL</em></p>
  72         in the pseudo exception configuration resolves to
  73         <pre>
  74         , CORBA::Environment ACE_TRY_ENV
  75         </pre>
  76         It is used for declaring the extra Environment parameter
  77         at CORBA methods that take one or more regular parameters.
  78         The fact that the comma is part of the macro substitution
  79         caters for the hiding of this added argument when native
  80         exceptions are used.  However, by the same virtue its
  81         usage is a bit peculiar -<br>
  82         Example: a CORBA IDL defined method
  83         <pre>
  84         void mymethod (in boolean b);
  85         </pre>
  86         may be declared as follows in C++:
  87         <pre>
  88         void mymethod (CORBA::Boolean b  ACE_ENV_ARG_DECL);
  89         </pre>
  90         Notice the missing comma before the ACE_ENV_ARG_DECL.
  91         This notation is necessary because when using native exceptions,
  92         also the presence of the comma before the (non-existent)
  93         CORBA::Environment parameter must be hidden.</p>
  94         </li>
  95         <li><p><em>ACE_ENV_SINGLE_ARG_DECL</em></p>
  96         is similar to <code>ACE_ENV_ARG_DECL</code>, but is used when
  97         the method takes no other parameters.  It is necessary as a
  98         separate macro because it does not contain the leading comma
  99         that <code>ACE_ENV_ARG_DECL</code> does.
 100         Example: a CORBA IDL defined method
 101         <pre>
 102         void mymethod ();
 103         </pre>
 104         may look like this in C++:
 105         <pre>
 106         void mymethod (ACE_ENV_SINGLE_ARG_DECL);
 107         </pre>
 108         <li><p><em>ACE_ENV_ARG_DECL_WITH_DEFAULTS</em>,
 109         <li><em>ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS</em></p>
 110         are similar to the above two macros but add a default value
 111         to the parameter declaration. In case of TAO, the default value
 112         is <code>TAO_default_environment()</code>.<p>
 113         Notice that these macros are only used at the declaration
 114         of methods (usually in header files), not at their definition
 115         (usually in implementation files.) At the definition,
 116         instead use the corresponding macro without "_WITH_DEFAULTS".
 117         Example: the CORBA IDL defined method
 118         <pre>
 119         void mymethod ();
 120         </pre>
 121         in the C++ header file looks like this:
 122         <pre>
 123         void mymethod (ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS);
 124         </pre>
 125         and in the C++ implementation file may look something like:
 126         <pre>
 127         void mymethod (ACE_ENV_SINGLE_ARG_DECL)
 128         {
 129           // ...
 130         }
 131         </pre>
 132       </ul>
 133
 134       <br>
 135   </li>
 136
 137   <li><P><em>Passing the CORBA::Environment Parameter into Method Calls</em><br>
 138       Now that we've seen how to declare methods with Environment
 139       parameters, let's see how to invoke such methods.</p>
 140       <ul>
 141         <li><p><em>ACE_ENV_ARG_PARAMETER</em></p>
 142         in the pseudo exception configuration resolves to
 143         <pre>
 144         , ACE_TRY_ENV
 145         </pre>
 146         and is written as the last parameter of a method call that takes
 147         one or more regular parameters. Again we need to omit the
 148         comma that would normally precede this last parameter, as the
 149         comma is already part of the macro definition. For example,
 150         the CORBA IDL method
 151         <pre>
 152         void mymethod (in boolean b);
 153         </pre>
 154         would be invoked as follows:
 155         <pre>
 156         some_var.mymethod (bparam  ACE_ENV_ARG_PARAMETER);
 157         </pre>
 158       </ul>
 159
 160       <ul>
 161         <li><p><em>ACE_ENV_SINGLE_ARG_PARAMETER</em></p>
 162         is similar to <code>ACE_ENV_ARG_PARAMETER</code> but is used
 163         for calling methods that don't take any regular parameters.
 164         Our example of a CORBA IDL method
 165         <pre>
 166         void mymethod ();
 167         </pre>
 168         we would invoke as follows:
 169         <pre>
 170         some_var.mymethod (ACE_ENV_SINGLE_ARG_PARAMETER);
 171         </pre>
 172       </ul>
 173       <br>
 174   </li>
 175
 176   <li><P><em>Definition of the CORBA::Environment variable </em><br>
 177       We have seen how to declare methods with the CORBA::Environment
 178       parameter, and how to invoke such methods. However, where does
 179       the variable to pass into methods as the CORBA::Environment
 180       parameter come from in the first place?</p>
 181       <P>An environment variable can be defined in the needed scope
 182       (for example, in the main program, or in a more local scope)
 183       by the statement</p>
 184       <pre>
 185       ACE_DECLARE_NEW_CORBA_ENV;
 186       </pre>
 187       <P>You can then invoke the methods on the servant from the client
 188       side as
 189       <pre>
 190       object_reference->func_name (x, y  ACE_ENV_ARG_PARAMETER);
 191       </pre>
 192
 193       Even if you are interested in making calls within the client
 194       side, you can define your method like this
 195       <pre>
 196       int AN_OBJ::foobar (int a, int b  ACE_ENV_ARG_DECL);
 197       </pre>
 198
 199   <li><P><em>Throwing exceptions:</em><br>
 200       Use <code>ACE_THROW</code> and <code>ACE_THROW_RETURN</code> to
 201       throw exceptions.  They should never be used within a try
 202       block; please use <code>ACE_TRY_THROW</code> instead.
 203       </P>
 204   </LI>
 205
 206   <li><P><em>Propagating exceptions:</em><br>
 207       To simulate native exceptions on platforms without native
 208       exception handling, <em>every</em>  function call that may
 209       throw exceptions must be followed by <code>ACE_CHECK</code> or
 210       <code>ACE_CHECK_RETURN</code>.</p>
 211
 212       <p><a name="exc-func">Exception-throwing functions include the
 213       following categories:</p>
 214
 215       <ol>
 216         <li><p>Any function that takes a
 217             <code>CORBA_Environment</code> argument.</p>
 218         </li>
 219
 220         <li><p><code>ACE_NEW_THROW_EX</code>.  Notice that you
 221             <em>should not</em> use <code>ACE_NEW_THROW</code>,
 222             <code>ACE_NEW_THROW_RETURN</code>,
 223             <code>ACE_NEW_TRY_THROW</code> anymore because they don't
 224             work right with ACE try macros.  Instead, use
 225             <code>ACE_NEW_THROW</code> with appropriate ACE_CHECK*
 226             macros.</p>
 227         </li>
 228
 229         <li><P><code>ACE_GUARD_THROW_EX</code>,
 230             <code>ACE_READ_GURAD_THROW_EX</code>, and
 231             <code>ACE_WRITE_THROW_EX</code>.
 232
 233         <li><p><code>ACE_TRY</code> blocks.  Follow every
 234             <code>ACE_ENDTRY</code> with appropriate ACE_CHECK*
 235             macros.</p>
 236         <li>
 237       </ol>
 238
 239       <P>You should pass <code>ACE_TRY_ENV</code> to these
 240       functions.
 241       </p>
 242
 243       <P>Be very careful not to combine exception throwing functions
 244       in one statement like this:
 245       </P>
 246       <pre>
 247           x = obj1->callme (ACE_ENV_SINGLE_ARG_PARAMETER)
 248             + obj2->dare_me (ACE_ENV_SINGLE_ARG_PARAMETER);
 249           ACE_CHECK;
 250       </pre>
 251       <P>This example may work differently when native exception
 252       handling is enabled/disabled.
 253       </p>
 254   </LI>
 255
 256   <li><P><em>Catching exceptions:</em><br>
 257       Use <code>ACE_TRY</code> to catch exceptions if there's an
 258       <code>ACE_TRY_ENV</code> available.  Otherwise, you should use
 259       <code>ACE_DECLARE_NEW_CORBA_ENV</code> to create one at
 260       <em>proper</em> scope.  The use of
 261       <code>ACE_TRY_NEW_ENV</code> is considered depricated because it
 262       can't deal with the case when you have multiple <code>TRY</code>
 263       blocks in the scope of <code>ACE_TRY_NEW_ENV</code>.  If there are
 264       more than one try blocks in a function, use <code>ACE_TRY_EX</code>
 265       for all subsequence try blocks to avoid name clashing of labels.
 266       </p>
 267       <ul>
 268         <li><P>Within a <code>ACE_TRY</code> block, use the variable
 269             <code>ACE_TRY_ENV</code> to pass down the
 270             <code>CORBA_Environment</code> (see <a
 271             href="#try_env">this</a> example.)
 272             </p>
 273         </LI>
 274
 275         <li><P>Follow <em>every</em> exception throwing function with
 276             <code>ACE_TRY_CHECK</code>. If you are using a TRY block
 277             within another try block add a <code>ACE_TRY_CHECK</code>
 278             at the end of this TRY block ie. after
 279             <code>ACE_ENDTRY</code>.
 280             </p>
 281         </LI>
 282
 283         <li><P>Use <code>ACE_CATCH</code> to catch exceptions of certain
 284             type.
 285             </p>
 286         </LI>
 287
 288         <li><P><code>ACE_CATCHANY</code> catches <em>any</em> exceptions
 289             of type <code>CORBA_Exception</code>.  The caught
 290             exception is stored in a variable call
 291             <code>ACE_ANY_EXCEPTION</code>.
 292             </p>
 293         </LI>
 294
 295         <li><p><code>ACE_CATCHALL</code> emulate the <code>catch
 296             (...)</code> c++ statement.  It is identical to
 297             <code>ACE_CATCHANY</code> on platforms without native
 298             exception support.  You can not access the caught
 299             exception within the <code>ACE_CATCHALL</code> block.</p>
 300
 301         <li><P>Use <code>ACE_RE_THROW</code> to rethrow the same exception
 302             within a <code>ACE_CATCH</code> or
 303             <code>ACE_CATCHANY</code> block.
 304             </p>
 305         </LI>
 306
 307         <li><P>A <code>ACE_TRY</code> block must be terminated with
 308             a <code>ACE_ENDTRY</code> statement.
 309             </p>
 310         </LI>
 311
 312         <li><P>Throw an exception within a <code>ACE_TRY</code>
 313             block or <code>ACE_CATCH</code> block using
 314             <a href="#ace_try"><code>ACE_TRY_THROW</code></a>.
 315             </p>
 316         </LI>
 317       </ul>
 318   </li>
 319
 320   <li><p><em>Printing out exceptions.</em>  Use <code>ACE_PRINT_EXCEPTION
 321       (EX,INFO)</code> to print out an exception.  The macro takes two
 322       arguments, a reference to an exception (EX) and a <code>char
 323       *</code> string (INFO) which provides more information on the
 324       exception.  Since there's no portable way to print out
 325       exceptions, you can redefine ACE_PRINT_EXCEPTION to fit your
 326       need (or define it to null.)  <em>You should always print out
 327       the exception itself, not the CORBA_Environment that carries the
 328       exception.</em></p>
 329   </li>
 330
 331   <li><P><em>Name of CORBA::Environment variable</em><br>
 332       A function that may throw a CORBA::Exception needs a
 333       CORBA::Environment variable to pass up exceptions (to throw in
 334       the C++ sense) and to gather (catch () in the C++ sense)
 335       exceptions from functions it called.  By default, ACE exception
 336       macros assume that the variable is named <code>ACE_TRY_ENV</code>.
 337       <code>ACE_TRY_ENV</code> itself is also a macro which can be
 338       redefined.
 339       </pre>
 340
 341       <P>
 342       You can redefine the name of the variable to
 343       something else to avoid name clashing.  Alternatively, there's
 344       another macro (<code>ACE_ADOPT_CORBA_ENV</code>) that allow you
 345       to use another variable name as the default CORBA::Environment
 346       <em>within</em> a function.
 347       </P>
 348   </LI>
 349
 350 </ol>
 351
 352 <HR><P>
 353 <h3>Examples</h3><a name="examples">
 354
 355 Refer to <a href="../ace/CORBA_macros.h"><code>
 356 $ACE_ROOT/ace/CORBA_macros.h</code></a> for complete definitions of
 357 macros discussed here.
 358
 359 <ul>Examples on using ACE try macros:
 360   <li><p>
 361       <pre>
 362       <a name="try_env">
 363       ACE_TRY  // Use ACE_DECLARE_NEW_CORBA_ENV to create ACE_TRY_ENV
 364                // if you got undefined symbol warning here.
 365         {
 366           some_operation (arg1, arg2  ACE_ENV_ARG_PARAMETER);
 367           ACE_TRY_CHECK;
 368
 369           .
 370           .
 371           if (whatever)
 372             ACE_TRY_THROW (CORBA::BAD_PARAM ());
 373
 374           some_other_operation (arg1, arg2, arg3  ACE_ENV_ARG_PARAMETER);
 375           ACE_TRY_CHECK;
 376         }
 377       <a name="ace_try">
 378       ACE_CATCH (CORBA_some_exception, ex)
 379         {
 380           // error handling.
 381           if (still_has_error)
 382             ACE_TRY_THROW (CORBA::NOWAY ());
 383         }
 384       ACE_CATCHANY
 385         {
 386           // error handling.
 387           // then rethow the exception.
 388           ACE_RE_THROW;
 389         }
 390       ACE_ENDTRY;
 391       ACE_CHECK;
 392       </pre>
 393       </p>
 394   </li>
 395
 396   <li><p><code>ACE_TRY</code> and also declares a label for internal
 397       use.  To avoid defining the same label multiple times within a
 398       function, use <code>ACE_TRY_EX</code> with different labels for
 399       different try blocks instead.  For example,<br>
 400
 401       <pre>
 402       ACE_TRY_EX (block_1)
 403         {
 404           some_operation (arg1, arg2  ACE_ENV_ARG_PARAMETER);
 405           ACE_TRY_CHECK_EX (block_1);
 406
 407           some_other_operation (arg1, arg2, arg3  ACE_ENV_ARG_PARAMETER);
 408           ACE_TRY_CHECK_EX (block_1);
 409         }
 410       ACE_CATCH (CORBA_some_exception, ex)
 411         {
 412           // error handling.
 413         }
 414       ACE_CATCHANY
 415         {
 416           // error handling.
 417         }
 418       ACE_ENDTRY;
 419       ACE_CHECK_RETURN (-1);
 420
 421       // Some other operation here
 422       //       .
 423       //       .
 424       //       .
 425       //       .
 426
 427       ACE_TRY_EX (block_2)
 428         {
 429           foo (arg  ACE_ENV_ARG_PARAMETER);
 430           ACE_TRY_CHECK_EX (block_2);
 431
 432           bar (arg1, arg2  ACE_ENV_ARG_PARAMETER);
 433           ACE_TRY_CHECK_EX (block_2);
 434         }
 435       ACE_CATCH (CORBA_some_exception, ex)
 436         {
 437           // error handling.
 438         }
 439       ACE_CATCHANY
 440         {
 441           // error handling.
 442         }
 443       ACE_ENDTRY;
 444       ACE_CHECK_RETURN (-1);
 445       </pre>
 446       </p>
 447
 448   <li><p>You may want to make a different series of calls after you
 449       encounter/catch  an exception. Here is what we recommend.
 450
 451       <pre>
 452       ACE_TRY
 453         {
 454           // Calls that can raise an exception
 455           some_call1 (arg1, arg2  ACE_ENV_ARG_PARAMETER);
 456           ACE_TRY_CHECK;
 457           .
 458           .
 459           .
 460           ACE_TRY_CHECK;
 461         }
 462       ACE_CATCH (CORBA_some_exception, ex)
 463         {
 464           // Caught an exception, so we need to make some other calls
 465           // to continue..
 466
 467           ACE_TRY_EX (block1) // basically a label
 468             {
 469               some_other_call1 (arg1,..   ACE_ENV_ARG_PARAMETER);
 470               ACE_TRY_CHECK_EX (block1);
 471             }
 472           ACE_CATCH (CORBA_some_other_exception, ex1)
 473             {
 474               // Handle the exception here..
 475             }
 476           ACE_ENDTRY;
 477           ACE_CHECK_RETURN (-1); // Needed to catch uncaught exceptions
 478         }
 479       ACE_ENDTRY;
 480       ACE_CHECK_RETURN (-1);
 481       </pre>
 482       </p>
 483
 484   <li><p>Be <em>VERY</em> wary of <code>ACE_CATCHALL</code>.  It catches
 485       exceptions of any type.  If your program depends on it, then,
 486       more often than not, there're something wrong with it.
 487       </P>
 488   </li>
 489
 490   <li><p>Instead of depending on <code>ACE_CATCHALL</code>, use
 491       <code>std::unique_ptr</code> style mechanism to prevent memory leaks
 492       from exceptions.
 493       </p>
 494   </li>
 495 </ul>
 496
 497 <HR><P>
 498 <h3><a name="general">General Guidelines for Exception Handling</h3>
 499 <ul>
 500   <li><p>Don't catch an exception just to rethrow it.  Exceptions cost
 501       you performance.
 502       </p>
 503   </li>
 504
 505   <li><p>When exceptions occur, make sure an object's is still in
 506       a valid state or change to a state that can be safely
 507       destructed.
 508       </p>
 509   </li>
 510
 511   <li><p>Watch out for side effect in the expression which may cause
 512       exceptions.  In the following example, what should
 513       <code>i</code> be if an exception does occur?<br>
 514 <pre>
 515       ACE_TRY
 516         {
 517             obj[i++] = foo_bar_method (a, b  ACE_ENV_ARG_PARAMETER);
 518         }
 519 </pre></p>
 520   </li>
 521
 522   <li><p>Make sure an exception doesn't cause resource leak (memory,
 523       socket, ...) (hint: Use std::unique_ptr to avoid memory leak,
 524       and ACE_Guard for locks.)
 525       </p>
 526   </li>
 527
 528   <li><p>Don't catch any exception that you don't know how to handle.</p>
 529   </li>
 530
 531   <li><p>Never throw an exception from destructor (unless you know what
 532       it implies.)</p>
 533   </li>
 534
 535   <li><p>Use exceptions to provide more information about the error.</p>
 536   </li>
 537
 538   <li><p>Rethrow a different exception only to provide <em>more</em>
 539       information.  Do not catch an exception just to rethrow, say,
 540       <code>unknow_exception</code>.</p>
 541   </li>
 542 </ul>
 543
 544 <HR><P>
 545 <H3><a name="transition">Transition from ACE_TRY_ENV usage
 546     to the ACE_ENV_ARG macros</h3>
 547
 548 <P>Before TAO version 1.2.2, IDL defined methods were declared using
 549 direct mentions of <code>CORBA::Environment ACE_TRY_ENV</code>.
 550 The problem with this approach was that the ACE_TRY_ENV had
 551 to be passed into ORB core method calls even when native exceptions
 552 are supported. The TAO internal usage of the ACE_ENV_ARG family of
 553 macros fixes this.</p>
 554
 555 <p>For people who want to continue to use their old code that uses the
 556 old <code>ACE_TRY_ENV</code> macros, they can define
 557 <CODE>ACE_ENV_BKWD_COMPAT</CODE> in their <code>config.h</code> file.
 558
 559 <P>CORBA applications that do not need support for emulated exceptions
 560 can use direct C++ exception handling and omit the CORBA::Environment
 561 parameter entirely.<BR>
 562 On the other hand, applications that shall support environments without
 563 C++ exceptions (such as all applications that are part of to TAO itself)
 564 should use the ACE_ENV_ARG macros.<BR>
 565 The script <code>$ACE_ROOT/bin/subst_env.pl</code> can assist in the
 566 conversion from the direct ACE_TRY_ENV usage to the ACE_ENV_ARG macros.
 567 Here is a list of the substitutions that the script does. For context,
 568 two sample IDL methods are used:
 569 <PRE>
 570         void noargs ();
 571         void withargs (in boolean b);
 572 </pre>
 573 At each example, first the <em>old usage</em> is given, then its
 574 <code>subsitution</code>.
 575 </p>
 576
 577 <H4>Method declaration</h4>
 578
 579 <UL>
 580   <li><P><em>void noargs (CORBA::Environment &amp;);</em></P>
 581       <P><code>void noargs (ACE_ENV_SINGLE_ARG_DECL_NOT_USED);</code></P>
 582   </li>
 583   <li><P><em>void noargs (CORBA::Environment &amp;ACE_TRY_ENV);</em></P>
 584       <P><code>void noargs (ACE_ENV_SINGLE_ARG_DECL);</code></P>
 585   </li>
 586   <li><P><em>void noargs (CORBA::Environment &amp;ACE_TRY_ENV = TAO_default_environment ());</em></P>
 587       <P><code>void noargs (ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS);</code></P>
 588   </li>
 589   <li><P><em>void withargs (CORBA::Boolean b, CORBA::Environment &amp;);</em></P>
 590       <P><code>void withargs (CORBA::Boolean b ACE_ENV_ARG_DECL_NOT_USED);</code></P>
 591   </li>
 592   <li><P><em>void withargs (CORBA::Boolean b, CORBA::Environment &amp;ACE_TRY_ENV);</em></P>
 593       <P><code>void withargs (CORBA::Boolean b ACE_ENV_ARG_DECL);</code></P>
 594   </li>
 595   <li><P><em>void withargs (CORBA::Boolean b, CORBA::Environment &amp;
 596          ACE_TRY_ENV = TAO_default_environment ());</em></P>
 597       <P><code>void withargs (CORBA::Boolean b ACE_ENV_ARG_DECL_WITH_DEFAULTS);</code></P>
 598   </li>
 599 </ul>
 600
 601 <H4>Method invocation</h4>
 602
 603 <UL>
 604   <li><P><em>noargs (ACE_TRY_ENV);</em></P>
 605       <P><code>noargs (ACE_ENV_SINGLE_ARG_PARAMETER);</code></P>
 606   </li>
 607   <li><P><em>withargs (bparam, ACE_TRY_ENV);</em></P>
 608       <P><code>withargs (bparam ACE_ENV_ARG_PARAMETER);</code></P>
 609   </li>
 610 </ul>
 611
 612 <HR><P>
 613 <H3><a name="caveats">Caveats</H3>
 614
 615 <P>As we already mentioned no set of macros can cover all cases
 616 and preserve the semantics between native C++ exceptions and the
 617 <CODE>CORBA::Environment</CODE> based mapping.
 618 Some of the problems that our macros are described below:
 619 <P>
 620
 621 <UL>
 622   <LI><P>Using the macros in loops can produce problems with
 623       <CODE>break</CODE> and <CODE>continue</CODE> statements, for
 624       example:
 625       </P>
 626       <PRE>
 627     for (int i = 0; i < 10; ++i)
 628     {
 629       ACE_TRY
 630         {
 631           if (x[i] == 0)
 632             continue; // will *not* work
 633           if (x[i] == -1)
 634             break; // will *not* work either
 635         }
 636       ACE_CATCH (CORBA::Exception, ex)
 637         {
 638         }
 639       ACE_ENDTRY;
 640       ACE_CHECK;
 641     }
 642       </PRE>
 643   </LI>
 644 </UL>
 645
 646 <P><HR><P>
 647
 648 Back to the <A
 649 HREF="http://www.dre.vanderbilt.edu/~schmidt/ACE-documentation.html">ACE
 650 documentation</A> page.<BR>
 651 Back to <A HREF="index.html">ACE Documentation Home</A>.
 652
 653
 654 <!--#include virtual="/~schmidt/cgi-sig.html" -->
 655 </body></HTML>