WriteError class: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "This page is under construction. __NOTOC__ WriteError exceptions are typically thrown by the Parse function in the WriteError class when...")
 
No edit summary
 
(3 intermediate revisions by one other user not shown)
Line 1: Line 1:
This page is [[under construction]].  
__NOTOC__
<var>WriteError</var> exceptions are thrown by the <var>Close</var>, <var>WriteBlock</var>, <var>WriteRecord</var>, and <var>WriteRecords</var> methods in the [[Dataset class]] if they encounter a full output <var>Dataset</var> object.  


__NOTOC__
Before the existence of the <var>WriteError</var> exception class, these <var>Dataset</var> methods would cancel the request in this situation. With the exception, the full condition is brought to your attention with an opportunity to take some mitigating action.  
WriteError exceptions are typically thrown by the [[?? (WriteError function)|Parse function]] in the [[WriteError class]] when there is an error parsing record data.
   
   
To create a <var>WriteError</var> exception yourself, you typically use a SOUL <var>[[Exceptions#Using the Throw statement|Throw]]</var> statement with an <var>WriteError</var> <var>[[New_(WriteError_constructor)|New]]</var> constructor. This statement must be issued from within a method, and it can only be caught by the code that calls the method. For example, the following statement throws a <var>WriteError</var> exception:
To create a <var>WriteError</var> exception yourself, you typically use a SOUL <var>[[Exceptions#Using the Throw statement|Throw]]</var> statement with a <var>WriteError</var> <var>[[New_(WriteError_constructor)|New]]</var> constructor. This statement must be issued from within a method, and it can only be caught by the code that calls the method. For example, the following statement throws a <var>WriteError</var> exception:
<p class="code">throw %(WriteError):new(characterPosition=%pos)
<p class="code">throw %(WriteError):new(returnCode=%rc)
</p>
</p>
   
   
Remember that you catch an exception with the <var>[[Exceptions#Try and Catch|Catch]]</var> statement; if an exception condition occurs outside a <var>Catch</var> for it, the request is canceled.
Remember that you catch an exception with the <var>[[Exceptions#Try and Catch|Catch]]</var> statement. If an exception condition occurs outside a <var>Catch</var> for it, the request is canceled. Here is a sample testing loop with a <var>Dataset</var> object:
<p class="code">for %i from 1 to 10000
  try
    %ds:writeRecord("This is a test " %i)
  catch writeError to %writeError
    printText {~=%writeError:returnCode}
    loop end
  end try
end for </p>
   
   
The <var>WriteError</var> class, like the WriteError class is available as of <var class="product">Model 204</var> 7.6.
The <var>WriteError</var> class is available as of <var class="product">Model 204</var> 7.7.
   
   
==The WriteError methods==
==The WriteError methods==
Line 17: Line 25:
The methods in the class are described in the subsections that follow. In addition:
The methods in the class are described in the subsections that follow. In addition:
<ul>
<ul>
<li>[[Notation conventions for methods|"Notation conventions for methods"]] has information
<li>[[Notation conventions for methods]] has information
about the conventions followed.
about the conventions followed. </li>
<li>[[WriteError methods syntax|"WriteError methods syntax"]] is a single page that contains the syntax diagrams of all the methods in the class.
 
<li>[[WriteError methods syntax]] is a single page that contains the syntax diagrams of all the methods in the class. </li>
</ul>
</ul>
==CharacterPosition property==
 
{{Template:WriteError:CharacterPosition subtitle}}
==ReturnCode property==
{{Template:WriteError:ReturnCode subtitle}}
   
   
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns a number that indicates the character position (unicode characters are each two bytes long) in the unicode string being parsed where the error was detected.
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns a number that indicates the type of error encountered.  
 
===Syntax===
===Syntax===
{{Template:WriteError:CharacterPosition syntax}}
{{Template:WriteError:ReturnCode syntax}}
   
   
====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table>
<tr><th>%number</th>
<tr><th>%number</th>
<td>The character position in the input unicode string where the parse error was detected.</td></tr>
<td>An I/O error return code. The most likely codes are:
<p class="codeInTable"> 4  Permanent I/O error
<tr><th>jsonParseError</th>
10  Offload process failed
<td>A reference to an instance of a <var>[[WriteError_class|WriteError]]</var> object.</td></tr>
12  File full condition </p>
</table>
</td></tr>
==Description property==
{{Template:WriteError:Description subtitle}}
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns a string that describes the error that was encountered while parsing the JSON data.
===Syntax===
{{Template:WriteError:Description syntax}}
   
   
====Syntax terms====
<tr><th>writeError</th>
<table class="syntaxTable">
<tr><th>%string</th>
<td>Text the describes the error that was encountered while parsing JSON data.</td></tr>
<tr><th>jsonParseError</th>
<td>A reference to an instance of a <var>[[WriteError_class|WriteError]]</var> object.</td></tr>
<td>A reference to an instance of a <var>[[WriteError_class|WriteError]]</var> object.</td></tr>
</table>
</table>
Line 56: Line 55:
{{Template:WriteError:New subtitle}}
{{Template:WriteError:New subtitle}}
   
   
This <var>Constructor</var> generates an instance of a <var>[[WriteError_class|WriteError]]</var> exception. The <var>New</var> method format follows:
This <var>Constructor</var> generates an instance of a <var>[[WriteError_class|WriteError]]</var> exception.  
 
===Syntax===
===Syntax===
{{Template:WriteError:New syntax}}
{{Template:WriteError:New syntax}}
Line 62: Line 62:
====Syntax terms====
====Syntax terms====
<table>
<table>
<tr><th>%jsonParseError</th><td>A reference to an instance of a <var>WriteError</var> object.</td></tr>
<tr><th>%writeError</th>
<tr><th><var>[%(WriteError):]</var></th><td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr>
<td>A reference to an instance of a <var>WriteError</var> object.</td></tr>
<tr><th>number</th><td>The character position in the input unicode string where the parse error was detected.</td></tr>
 
<tr><th>string</th><td>Text that describes the error. It must be 127 characters long or less.</td></tr>
<tr><th><var>[%(WriteError):]</var></th>
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr>
 
<tr><th>number</th>
<td>A <var>ReturnCode</var> property value that indicates the type of error encountered.</td></tr>
</table>
</table>
===Usage notes===
<ul>
<li>Since the WriteError exception does not provide
</ul>


[[Category:System exception classes]]
[[Category:System exception classes]]

Latest revision as of 20:41, 17 August 2016

WriteError exceptions are thrown by the Close, WriteBlock, WriteRecord, and WriteRecords methods in the Dataset class if they encounter a full output Dataset object.

Before the existence of the WriteError exception class, these Dataset methods would cancel the request in this situation. With the exception, the full condition is brought to your attention with an opportunity to take some mitigating action.

To create a WriteError exception yourself, you typically use a SOUL Throw statement with a WriteError New constructor. This statement must be issued from within a method, and it can only be caught by the code that calls the method. For example, the following statement throws a WriteError exception:

throw %(WriteError):new(returnCode=%rc)

Remember that you catch an exception with the Catch statement. If an exception condition occurs outside a Catch for it, the request is canceled. Here is a sample testing loop with a Dataset object:

for %i from 1 to 10000 try %ds:writeRecord("This is a test " %i) catch writeError to %writeError printText {~=%writeError:returnCode} loop end end try end for

The WriteError class is available as of Model 204 7.7.

The WriteError methods

The following are the available WriteError class methods.

MethodDescription
NewCreate a new WriteError object
ReturnCodeReturn code from failed write

The methods in the class are described in the subsections that follow. In addition:

ReturnCode property

Return code from failed write (WriteError class)

This ReadOnly property returns a number that indicates the type of error encountered.

Syntax

%number = writeError:ReturnCode

Syntax terms

%number An I/O error return code. The most likely codes are:

4 Permanent I/O error 10 Offload process failed 12 File full condition

writeError A reference to an instance of a WriteError object.

New constructor

Create a new WriteError object (WriteError class)

This Constructor generates an instance of a WriteError exception.

Syntax

%writeError = [%(WriteError):]New( ReturnCode= number)

Syntax terms

%writeError A reference to an instance of a WriteError object.
[%(WriteError):] The class name in parentheses denotes a Constructor.
number A ReturnCode property value that indicates the type of error encountered.