/** \page errorpage CCMIO Error Handling

<p>
Error handling in C APIs is fairly cumbersome if you need to check for errors
frequently, as you either need to check return values (or parameters) or a
global error after each function call to ensure that the next one does not go
bad.  However, most of the time you would like to call API routines if there has
been no error, otherwise skip until the end.  libsff has appropriated error
handling ideas from dataflow programming in an attempt to make error handling
less cumbersome for the API user.  All functions return an error, in case it
is convenient, but most functions also take an error pointer, the value of which
will be set to the error returned.  Should the value of this pointer be an
error upon entrance to the function, the function will do nothing.  Occasionally
you will want to test whether an function call will succeed.  In this case,
<tt>NULL</tt>, which is always interpreted as <tt>kCCMIONoErr</tt>, should be
passed to the function and the return value checked for success.  If the error
pointer were passed then an error would be recorded and no succeeding function
would execute, even though they should.

<p>
Dataflow error handling allows the API user to write code that opens a file,
does some reading or writing, and then closes it, without checking for errors
until the end.  The API guarantees that any return parameters of the function
will be usable (i.e not crash), unless otherwise documented, and that, should
an error occur early on, all memory will properly be deallocated.

<p>
There are several things to keep in mind when using errors:
<ul>
    <li>Because this is a C, not C++ API, it is of paramount importance to initialize the error when it is created.  Thus, an error should always be declared:<br>
<pre>                CCMIOError err = kCCMIONoErr;</pre><br>
unless it is being assigned as a result of an API call
(e.g. <tt>CCMIOOpenFile</tt>).</li>
    <li>Although <tt>kCCMIONoErr</tt> should always have a value of 0 (zero),
	it is preferable to compare errors to <tt>kCCMIONoErr</tt> to avoid
	confusion, since while <tt>!err</tt> is a correct test for an
	error, <tt>!CCMIOOpenFile</tt> reads like it checks for the failure of
	the function, but in reality returns true only if there was not an
	error.  Thus<br>
	<pre>                if (CCMIOOpenFile(...) != kCCMIONoErr)</pre>
	should be the canonical test.</li>
    <li>Either pass NULL for the error when looping through nodes or reset
	the error afterwards, because the terminal condition is that there
	is an error (<tt>kCCMIONoNodeErr</tt>):<br><br>
	<tt>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; i = 0;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; while (CCMIONextEntity(<b>NULL</b>, parentID, kCCMIOField, &i, &child) == kCCMIONoErr)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;	... do stuff ...<br>
	</tt></li>
</ul>
*/
