View source for AddToRecordError class

<!-- AddToRecordError class -->
__NOTOC__
An <var>AddToRecordError</var> exception can be thrown by the <var>[[AddToRecord (XmlDoc subroutine)|AddToRecord]]</var> subroutine in the <var>[[XmlDoc_API#The_XmlDoc_class|XmlDoc]]</var> class.  It indicates that not all of the fields and/or fieldgroups from the object <var>XmlDoc</var> were successfully added to the current record.  The various read-only properties of an <var>AddToRecordError</var> object (which can be set by the <var>[[Catch]]</var> statement) provide information about the failed operation.
 
This class is new in version 7.8 of the <var class="product">Sirius Mods</var>.
 
==The AddToRecordError methods==
 
{{Template:List of AddToRecordError methods}}
 
The methods in the class are described in the subsections that follow. In addition:
<ul>
<li>[[Notation conventions for methods|"Notation conventions for methods"]] has information
about the conventions followed.
<li>[[AddToRecordError methods syntax|"AddToRecordError methods syntax"]] is a single page that contains the syntax diagrams of all the methods in the class.
</ul>
 
 
==Description property==
{{Template:AddToRecordError:Description subtitle}}
<h3>Syntax</h3>
{{Template:AddToRecordError:Description syntax}}
<h4>Syntax terms</h4>
<table class="syntaxTable">
<tr><th>%string</th>
<td>A string to receive the description of the exception.
</td></tr>
<tr><th>addToRecordError</th>
<td>An <var>[[AddToRecordError_class|AddToRecordError]]</var> object.
</td></tr></table>
 
 
==FieldOrFieldgroupName property==
{{Template:AddToRecordError:FieldOrFieldgroupName subtitle}}
<h3>Syntax</h3>
{{Template:AddToRecordError:FieldOrFieldgroupName syntax}}
<h4>Syntax terms</h4>
<table class="syntaxTable">
<tr><th>%string</th>
<td>A string to receive the field or fieldgroup name. If the error involves a field or fieldgroup (for example, if <code>[[Reason (AddToRecordError property)|Reason]] = ErrorAddingField</code>), this is the field or fieldgroup name.
</td></tr>
<tr><th>addToRecordError</th>
<td>An <var>[[AddToRecordError_class|AddToRecordError]]</var> object.
</td></tr></table>
 
 
==InputRecordNumber property==
{{Template:AddToRecordError:InputRecordNumber subtitle}}
<h3>Syntax</h3>
{{Template:AddToRecordError:InputRecordNumber syntax}}
<h4>Syntax terms</h4>
<table class="syntaxTable">
<tr><th>%number</th>
<td>A string to receive the value of the <code>number</code> attribute of the <code>Record</code> element of <var>[[AddToRecord (XmlDoc subroutine)|AddToRecord]]</var>'s method object <var>[[XmlDoc class|XmlDoc]]</var>. Assuming that the <var>XmlDoc</var> was created by the <var>[[LoadFromRecord (XmlDoc/XmlNode subroutine)|LoadFromRecord]]</var> subroutine (or one of the methods analagous to it), this will be the number of the record from which the <var>XmlDoc</var> was created.
</td></tr>
<tr><th>addtoRecordError</th>
<td>An <var>[[AddToRecordError_class|AddToRecordError]]</var> object.
</td></tr></table>
 
 
==New constructor==
{{Template:AddToRecordError:New subtitle}}
 
Each argument to <var>New</var> sets the value of the corresponding property of the newly constructed <var>[[AddToRecordError_class|AddToRecordError]]</var> object.
<h3>Syntax</h3>
{{Template:AddToRecordError:New syntax}}

<h4>Syntax terms</h4>
<table class="syntaxTable">
<tr><th>%addToRecordError</th>
<td>An <var>AddToRecordError</var> object.
</td></tr>

<tr><th><var>[%(AddToRecordError):]</var></th>
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>. </td></tr>
<tr><th><var>Reason</var></th>
<td>This [[Methods#Named parameters|name required]] parameter specifies the <var>[[#AddToRecordErrorReason enumeration|AddToRecordErrorReason]]</var> enumeration value to be assigned to the exception object's <var class="term>[[Reason (AddToRecordError property)|Reason]]</var> property.  <var>Reason</var> is a required parameter.
</td></tr>

<tr><th><var>Description</var></th>
<td>This name required parameter specifies the string value to be assigned to the object's <var>[[Description (AddToRecordError property)|Description]]</var> property. <var>Description</var> is an optional parameter; the default value is the null string.
</td></tr>

<tr><th><var>UntranslatableHexValue</var></th>
<td>This name required parameter specifies the string value to be assigned to the object's <var>[[UntranslatableHexValue (AddToRecordError property)|UntranslatableHexValue]]</var> property. <var>UntranslatableHexValue</var> is an optional parameter; the default value is the null string and, if supplied, it must be a valid hexadecimal string.</td></tr>

<tr><th><var>FieldOrFieldgroupName</var></th>
<td>This name required parameter specifies the string value to be assigned to the object's <var>[[FieldOrFieldgroupName (AddToRecordError property)|FieldOrFieldgroupName]]</var> property. <var>FieldOrFieldgroupName</var> is an optional parameter; the default value is the null string.</td></tr>

<tr><th><var>NodeName</var></th>
<td>This name required parameter specifies the string value to be assigned to the object's <var>[[NodeName (AddToRecordError property)|NodeName]]</var> property. <var>NodeName</var> is an optional parameter; the default value is the null string.</td></tr>

<tr><th><var>NodeType</var></th>
<td>This name required parameter specifies the <var>XmlNodeType</var> enumeration value to be assigned to the object's <var>[[NodeType (AddToRecordError property)|NodeType]]</var> property. <var>NodeType</var> is an optional parameter; the default value is Null.</td></tr>

<tr><th><var>Value</var></th>
<td>This name required parameter specifies the string value to be assigned to the object's <var>[[Value (AddToRecordError property)|Value]]</var> property. <var>Value</var> is an optional parameter; the default value is the null string.</td></tr>

<tr><th><var>InputRecordNumber</var></th>
<td>This name required parameter specifies the numeric value to be assigned to the object's <var>[[InputRecordNumber (AddToRecordError property)|InputRecordNumber]]</var> property. <var>InputRecordNumber</var> is an optional parameter; the default value is 0.</td></tr>
</table>

==NodeName property==
{{Template:AddToRecordError:NodeName subtitle}}
<h3>Syntax</h3>
{{Template:AddToRecordError:NodeName syntax}}

<h4>Syntax terms</h4>
<table class="syntaxTable">
<tr><th>%string</th>
<td>A string to receive the name of a node in <var>[[AddToRecord (XmlDoc subroutine)|AddToRecord]]</var>'s method object <var>[[XmlDoc class|XmlDoc]]</var>. If the error involves a named node in the <var>XmlDoc</var> (for example, some cases when <code>[[Reason (AddToRecordError property)|Reason]] = InvalidNode</code>), this is the name of the node.</td></tr>

<tr><th>addToRecordError</th>
<td>An <var>[[AddToRecordError_class|AddToRecordError]]</var> object.
</td></tr></table>
 
 
==NodeType property==
{{Template:AddToRecordError:NodeType subtitle}}
 
<h3>Syntax</h3>
{{Template:AddToRecordError:NodeType syntax}}

<h4>Syntax terms</h4>
<table class="syntaxTable">
<tr><th>%xmlNodeType</th>
<td>A <var>[[Type_(XmlDoc/XmlNode_function)#Usage_notes|XmlNodeType]]</var> enumeration to receive the type of a node in <var>[[AddToRecord (XmlDoc subroutine)|AddToRecord]]</var>'s method object <var>[[XmlDoc class|XmlDoc]]</var>. If the error involves a node in the <var>XmlDoc</var> (for example, if <code>[[Reason (AddToRecordError property)|Reason]] = InvalidNode</code>).</td></tr>

<tr><th>addToRecordError</th>
<td>An <var>[[AddToRecordError_class|AddToRecordError]]</var> object.
</td></tr></table>
 
 
==Reason property==
{{Template:AddToRecordError:Reason subtitle}}
<h3>Syntax</h3>
{{Template:AddToRecordError:Reason syntax}}

<h4>Syntax terms</h4>
<table class="syntaxTable">
<tr><th>%addToRecordErrorReason</th>
<td>This <var>AddToRecordErrorReason</var> enumeration value (see below) describes the reason for the translation failure.
</td></tr>

<tr><th>addToRecordError</th>
<td>An <var>[[AddToRecordError_class|AddToRecordError]]</var> object.
</td></tr></table>
 
<h4>AddToRecordErrorReason enumeration</h4>
An <var>AddToRecordErrorReason</var> [[Enumerations|enumeration]] may have one of the following values:
<table>
<tr><th>InvalidNode
</th><td>A node in <var>[[AddToRecord (XmlDoc subroutine)|AddToRecord]]</var>'s method object <var>[[XmlDoc class|XmlDoc]]</var> does not conform to the structure as created by the LoadFromRecord subroutine.
</td></tr>

<tr><th>UntranslatableFieldName
</th><td>A field name in <var>AddToRecord</var>'s method object <var>XmlDoc</var> is not translatable to EBCDIC.
</td></tr>

<tr><th>UntranslatableFieldgroupName
</th><td>A fieldgroup name in <var>AddToRecord</var>'s method object <var>XmlDoc</var> is not translatable to EBCDIC.
</td></tr>

<tr><th>UntranslatableValue
</th><td>A field value in <var>AddToRecord</var>'s method object <var>XmlDoc</var> is not translatable to EBCDIC.
</td></tr>

<tr><th>InvalidBase64
</th><td>A string used for the base64 encoding of a field in <var>AddToRecord</var>'s method object <var>XmlDoc</var> is not a valid base64 string.
</td></tr>

<tr><th>FieldNameTooLong
</th><td>A field name in <var>AddToRecord</var>'s method object <var>XmlDoc</var> is longer than 255 characters.
</td></tr>

<tr><th>FieldgroupNameTooLong
</th><td>A fieldgroup name in <var>AddToRecord</var>'s method object <var>XmlDoc</var> is longer than 255 characters.
</td></tr>

<tr><th>ValueTooLong
</th><td>The value of a field in <var>AddToRecord</var>'s method object <var>XmlDoc</var> that is not defined as a <var>BLOB</var> or <var>CLOB</var> field in the current file is longer than 255 characters or is longer than the defined <var>LEN</var> attribute, if the field is a fixed <var>OCCURS</var> field.
</td></tr>

<tr><th>UnknownFieldName
</th><td>A field name in <var>AddToRecord</var>'s method object <var>XmlDoc</var> is not defined in the current file.
</td></tr>

<tr><th>UnknownFieldgroupName
</th><td>A fieldgroup name in <var>AddToRecord</var>'s method object <var>XmlDoc</var> is not defined in the current file.
</td></tr>

<tr><th>ExpectedField
</th><td>A field name in <var>AddToRecord</var>'s method object <var>XmlDoc</var> is defined as a fieldgroup in the current file.
</td></tr>

<tr><th>ExpectedFieldgroup
</th><td>A fieldgroup name in <var>AddToRecord</var>'s method object <var>XmlDoc</var> is defined as a field in the current file.
</td></tr>

<tr><th>ErrorAddingField
</th><td>An error occurred adding a field, such as a violation of a field constraint.
</td></tr>

<tr><th>ErrorAddingFieldgroup
</th><td>An error occurred adding a fieldgroup, such as a file full condition.
</td></tr>

<tr><th>ErrorObtainingRecord
</th><td><var>AddToRecord</var> was unable to lock the record in exclusive mode.
</td></tr>

<tr><th>InvalidFieldgroupID
</th><td>A fieldgroup ID in <var>AddToRecord</var>'s method object <var>XmlDoc</var> is not numeric.
</td></tr>

<tr><th>InvalidCodepage
</th><td>The codepage name specified on the <code>codepage</code> attribute of the <code>Record</code> element in <var>AddToRecord</var>'s method object <var>XmlDoc</var> is not a known codepage name.
</td></tr>

<tr><th>ErrorAddingMaxFieldgroupID
</th><td>The attempt to set the fieldgroup ID counter in the record failed; this is a very unusual condition.
</td></tr>

<tr><th>InsufficientStorageForLOB
</th><td>STBL, VTBL, or User Buffer storage was unavailable.<p>The <var>[[Description (AddToRecordError property)|Description]]</var> property indicates which of these is applicable.</p>
</td></tr>

<tr><th>InvalidVersion
</th><td>Invalid value of the <code>version</code> attribute of the <code>Record</code> element in <var>AddToRecord</var>'s method object <var>XmlDoc</var>; the only allowed value is 1.
</td></tr>

<tr><th>InvalidInputRecordNumber
</th><td>Invalid value of the <code>number</code> attribute of the <code>Record</code> element in <var>AddToRecord</var>'s method object <var>XmlDoc</var>; it must either be -1 or a non-negative integer.
</td></tr></table>
'''Note:''' As with all enumerations, the <var>ToString</var> method implicitly converts an enumeration value to a character string whose value is the name of the enumeration value. For more information about methods available to all enumerations, see [[Enumerations#Common enumeration methods|"Common enumeration methods"]].
 
 
==UntranslatableHexValue property==
{{Template:AddToRecordError:UntranslatableHexValue subtitle}}
<h3>Syntax</h3>
{{Template:AddToRecordError:UntranslatableHexValue syntax}}
<h4>Syntax terms</h4>
<table class="syntaxTable">
<tr><th>%string</th>
<td>A string to receive the hexadecimal value of the bytes that caused the exception to be thrown.  This will only be valid if the <var>[[Reason (AddToRecordError property)|Reason]]</var> property indicates the exception was due to an untranslatable [[Unicode]] character.
</td></tr>
<tr><th>addToRecordError</th>
<td>An <var>[[AddToRecordError_class|AddToRecordError]]</var> object.
</td></tr></table>
 
 
==Value property==
{{Template:AddToRecordError:Value subtitle}}
<h3>Syntax</h3>
{{Template:AddToRecordError:Value syntax}}

<h4>Syntax terms</h4>
<table class="syntaxTable">

<tr><th>%string</th>
<td>A string to receive the value. If the error involves a value in <var>[[AddToRecord (XmlDoc subroutine)|AddToRecord]]</var>'s method object <var>[[XmlDoc class|XmlDoc]]</var> (for example, if <code>[[Reason (AddToRecordError property)|Reason]] = InvalidBase64</code>), this is the value that is in error (actually, up to 255 bytes of the value).
</td></tr>

<tr><th>addToRecordError</th>
<td>An <var>[[AddToRecordError_class|AddToRecordError]]</var> object.
</td></tr></table>
 
[[Category:System exception classes]]