<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class Error - Class Error</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class Error</h1>
<p class="faldoc_brief">Internal VM and runtime error reflection class. </p>
<p class="faldoc_funcdecl">
<b>class</b> Error( [code], [description], [extra] )
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#code">code</a></td><td>Error code associated with this error. </td></tr>
<tr><td><a href="#description">description</a></td><td>Textual description for the error.</td></tr>
<tr><td><a href="#line">line</a></td><td>Line at which the error happened.</td></tr>
<tr><td><a href="#message">message</a></td><td>Arbitrary text used to better explain and define the error conditions.</td></tr>
<tr><td><a href="#module">module</a></td><td>Name of the module where the error has been generated.</td></tr>
<tr><td><a href="#origin">origin</a></td><td>String identifying the origin of the error. </td></tr>
<tr><td><a href="#pc">pc</a></td><td>Program counter of the instruction that raised the error.</td></tr>
<tr><td><a href="#subErrors">subErrors</a></td><td>Array of sub-errors.</td></tr>
<tr><td><a href="#symbol">symbol</a></td><td>Symbol name (function or method) where the error has been raised.</td></tr>
<tr><td><a href="#systemError">systemError</a></td><td>If the error was caused by a failure.</td></tr>
<tr><td><a href="#getSysErrDesc">getSysErrDesc()</a></td><td>returns system specific error description. </td></tr>
<tr><td><a href="#heading">heading()</a></td><td>Creates a short textual representation of the error. </td></tr>
<tr><td><a href="#toString">toString()</a></td><td>Creates a textual representation of the error. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> Error( [code], [description], [extra] )
</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">code</td><td class="faldoc_optparamdesc">A numeric error code. </td></tr><tr><td class="faldoc_optparam">description</td><td class="faldoc_optparamdesc">A textual description of the error code. </td></tr><tr><td class="faldoc_optparam">extra</td><td class="faldoc_optparamdesc">A descriptive message explaining the error conditions. </td></tr>
</table>
<br/>
<p class="item_brief">Internal VM and runtime error reflection class. </p>
<p class="faldoc_text">In case the error code is a well known code (i.e. one of the codes known by the engine), the description of the error will be automatically provided. </p>
<p class="faldoc_text"> To provide an error message without setting the code description, use directly the <a href="./class_Error.html#message">Error.message</a> property after having created the object. </p>
<p class="faldoc_text">The Error class is used by the virtual machine and by the Falcon Feathers functions to communicate to the scripts, and eventually to the embedding application, about error conditions. It is also available to extension modules, and to the script themselves, that can create error instances that can be cached internally or returned to the embedder. </p>
<p class="faldoc_text"> A complete error code is formed by two letters indicating the error origin, and a numeric code specifying the correct error name. By convention, one and only one error description may be associated with one error code. The error <i>message</i> is free to be used to carry more specific informations about the error conditions. </p>
<p class="faldoc_text">Use the comment parameter when the error message is generic, and/or the error may be reported because of various reasons, or to give an hint about how to avoid the error. </p>
<p class="faldoc_text">Error codes below 5000 are reserved to Falcon engine and officially recognized modules. Extension modules should issue errors above 5001, unless raising well known error codes that are encoded and described directly by the Falcon Engine (i.e. a very common error code is 901 - invalid parameters when a user makes a mistake in calling a script function). </p>
<p class="faldoc_text">All the elements in the error class are automatically initialized by the constructor, except for the code, the message and the description. As some error are created by binary modules, which are not executed by the VM, the informations about the line and the program counter that generated the error may not always be available. </p>
<p class="faldoc_text">The toString() method returns a string representation of the error, which includes all the available informations (except for system error description). In this version, access to the TraceBack class has been removed from scripts. </p>
<h2 class="faldoc_title">Properties</h2>
<h3 class="faldoc_funcname"><a name="code">code</a></h3>
<p class="item_brief">Error code associated with this error. </p>
<h3 class="faldoc_funcname"><a name="description">description</a></h3>
<p class="item_brief">Textual description for the error.</p>
<h3 class="faldoc_funcname"><a name="line">line</a></h3>
<p class="item_brief">Line at which the error happened.</p>
<h3 class="faldoc_funcname"><a name="message">message</a></h3>
<p class="item_brief">Arbitrary text used to better explain and define the error conditions.</p>
<h3 class="faldoc_funcname"><a name="module">module</a></h3>
<p class="item_brief">Name of the module where the error has been generated.</p>
<h3 class="faldoc_funcname"><a name="origin">origin</a></h3>
<p class="item_brief">String identifying the origin of the error. </p>
<p class="faldoc_text"><p class="faldoc_text">This code allows to determine what element of the Falcon engine has raised the error (or eventually, if this error has been raised by a script or a loaded module). </p>
<p class="faldoc_text">The error origin is a string; when an error gets displayed through a standard rendering function (as the Error.toString() method), it is indicated by two letters in front of the error code for better readability. The origin code may be one of the following: </p>
<ul>
<li><b>compiler</b>- (represented in Error.toString() as CO) </li><li><b>assembler</b>- (AS) </li><li><b>loader</b>- that is, the module loader (LD) </li><li><b>vm</b>- the virtual machine (when not running a script, short VM) </li><li><b>script</b>- (that is, a VM running a script, short SS) </li><li><b>runtime</b>- (core or runtime modules, RT) </li><li><b>module</b>- an extension module (MD). </li><li></li>
</ul>
</p>
<h3 class="faldoc_funcname"><a name="pc">pc</a></h3>
<p class="item_brief">Program counter of the instruction that raised the error.</p>
<h3 class="faldoc_funcname"><a name="subErrors">subErrors</a></h3>
<p class="item_brief">Array of sub-errors.</p>
<h3 class="faldoc_funcname"><a name="symbol">symbol</a></h3>
<p class="item_brief">Symbol name (function or method) where the error has been raised.</p>
<h3 class="faldoc_funcname"><a name="systemError">systemError</a></h3>
<p class="item_brief">If the error was caused by a failure.</p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="getSysErrDesc">getSysErrDesc()</a></h3>
<p class="item_brief">returns system specific error description. </p>
<p class="faldoc_funcdecl">Error.getSysErrDesc( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">System specific error description or nil if not available. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the error was generated by the underlying system (that is, if systemError > 0) returns a system and locale dependent error description. The description is obtained by querying the relevant OS error description API/SDK. </p>
</p>
<h3 class="faldoc_funcname"><a name="heading">heading()</a></h3>
<p class="item_brief">Creates a short textual representation of the error. </p>
<p class="faldoc_funcdecl">Error.heading( )</p>
<p class="faldoc_text"><p class="faldoc_text"> This method will only render the essential informations of the error, without printing the stack trace and without checking for other sub errors in the <a href="./class_Error.html#subErrors">Error.subErrors</a> array. </p>
</p>
<h3 class="faldoc_funcname"><a name="toString">toString()</a></h3>
<p class="item_brief">Creates a textual representation of the error. </p>
<p class="faldoc_funcdecl">Error.toString( )</p>
<p class="faldoc_text"><p class="faldoc_text">This method uses the standard Falcon error representation to render the error codes, descriptions and stack traces into a string. Suberrors are also considered. </p>
<p class="faldoc_text"> To get only a descriptive string of the error without its stack trace, use the <a href="./class_Error.html#heading">Error.heading</a> method. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
