AddToRecordError class: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
m (add link)
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
<!-- AddToRecordError class -->
<!-- AddToRecordError class -->
__NOTOC__
__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.
An <var>AddToRecordError</var> [[Exceptions|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>[[Exceptions#Try and Catch|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>.
This class is new in version 7.8 of the <var class="product">[[Sirius Mods]]</var>.
   
   
==The AddToRecordError methods==
==The AddToRecordError methods==
Line 11: Line 11:
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. </li>
about the conventions followed.
<li>[[AddToRecordError methods syntax]] is a single page that contains the syntax diagrams of all the methods in the class. </li>
<li>[[AddToRecordError methods syntax|"AddToRecordError methods syntax"]] is a single page that contains the syntax diagrams of all the methods in the class.
</ul>
</ul>
   
   
Line 40: Line 39:


====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table>
<tr><th>%string</th>
<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>
<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>
Line 55: Line 54:


====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table>
<tr><th>%number</th>
<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>
<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>
Line 73: Line 72:


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


====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table>
<tr><th>%string</th>
<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>
<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>
Line 128: Line 127:


====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table>
<tr><th>%xmlNodeType</th>
<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>
<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>
Line 144: Line 143:


====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table>
<tr><th>%addToRecordErrorReason</th>
<tr><th>%addToRecordErrorReason</th>
<td>This <var>AddToRecordErrorReason</var> enumeration value (see below) describes the reason for the translation failure.</td></tr>
<td>This <var>AddToRecordErrorReason</var> enumeration value (see below) describes the reason for the translation failure.</td></tr>
Line 154: Line 153:
====AddToRecordErrorReason enumeration====
====AddToRecordErrorReason enumeration====
An <var>AddToRecordErrorReason</var> [[Enumerations|enumeration]] may have one of the following values:
An <var>AddToRecordErrorReason</var> [[Enumerations|enumeration]] may have one of the following values:
<table>
<table class="thJustBold">
 
<tr><th>InvalidNode
<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>
</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>
Line 219: Line 217:
</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.
</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>
</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"]].
<p class="note">'''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]]. </p>
 
==UntranslatableHexValue property==
==UntranslatableHexValue property==
{{Template:AddToRecordError:UntranslatableHexValue subtitle}}
{{Template:AddToRecordError:UntranslatableHexValue subtitle}}

Latest revision as of 00:42, 13 May 2015


An AddToRecordError exception can be thrown by the AddToRecord subroutine in the XmlDoc class. It indicates that not all of the fields and/or fieldgroups from the object XmlDoc were successfully added to the current record. The various read-only properties of an AddToRecordError object (which can be set by the Catch statement) provide information about the failed operation.

This class is new in version 7.8 of the Sirius Mods.

The AddToRecordError methods

The following are the available AddToRecordError class methods.

MethodDescription
DescriptionDescription of error
FieldOrFieldgroupNameName of field or fieldgroup for which error occurred
InputRecordNumberValue of 'number' attribute from input XmlDoc
NewCreate new AddToRecordError object
NodeNameName of node in input XmlDoc for which error occurred
NodeTypeXmlNodeType of node in input XmlDoc for which error occurred
ReasonEnumerated reason for error
UntranslatableHexValueHexadecimal representation of untranslatable Unicode character, if that is reason for error
ValueValue from input XmlDoc for which error occurred

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

Description property

Description of error (AddToRecordError class)

[Introduced in Sirius Mods 7.8]

Syntax

%string = addToRecordError:Description

Syntax terms

%string A string to receive the description of the exception.
addToRecordError An AddToRecordError object.


FieldOrFieldgroupName property

Name of field or fieldgroup for which error occurred (AddToRecordError class)

[Introduced in Sirius Mods 7.8]

Syntax

%string = addToRecordError:FieldOrFieldgroupName

Syntax terms

%string A string to receive the field or fieldgroup name. If the error involves a field or fieldgroup (for example, if Reason = ErrorAddingField), this is the field or fieldgroup name.
addToRecordError An AddToRecordError object.

InputRecordNumber property

Value of 'number' attribute from input XmlDoc (AddToRecordError class)

[Introduced in Sirius Mods 7.8]

Syntax

%number = addToRecordError:InputRecordNumber

Syntax terms

%number A string to receive the value of the number attribute of the Record element of AddToRecord's method object XmlDoc. Assuming that the XmlDoc was created by the LoadFromRecord subroutine (or one of the methods analagous to it), this will be the number of the record from which the XmlDoc was created.
addtoRecordError An AddToRecordError object.


New constructor

Create new AddToRecordError object (AddToRecordError class)

[Introduced in Sirius Mods 7.8]

Each argument to New sets the value of the corresponding property of the newly constructed AddToRecordError object.

Syntax

%addToRecordError = [%(AddToRecordError):]New( Reason= addToRecordErrorReason, - [Description= string], - [UntranslatableHexValue= string], - [FieldOrFieldgroupName= string], - [NodeName= string], - [NodeType= xmlNodeType], - [Value= string], - [InputRecordNumber= number])

Syntax terms

%addToRecordError An AddToRecordError object.
[%(AddToRecordError):] The class name in parentheses denotes a Constructor.
Reason This name required parameter specifies the AddToRecordErrorReason enumeration value to be assigned to the exception object's Reason property. Reason is a required parameter.
Description This name required parameter specifies the string value to be assigned to the object's Description property. Description is an optional parameter; the default value is the null string.
UntranslatableHexValue This name required parameter specifies the string value to be assigned to the object's UntranslatableHexValue property. UntranslatableHexValue is an optional parameter; the default value is the null string and, if supplied, it must be a valid hexadecimal string.
FieldOrFieldgroupName This name required parameter specifies the string value to be assigned to the object's FieldOrFieldgroupName property. FieldOrFieldgroupName is an optional parameter; the default value is the null string.
NodeName This name required parameter specifies the string value to be assigned to the object's NodeName property. NodeName is an optional parameter; the default value is the null string.
NodeType This name required parameter specifies the XmlNodeType enumeration value to be assigned to the object's NodeType property. NodeType is an optional parameter; the default value is Null.
Value This name required parameter specifies the string value to be assigned to the object's Value property. Value is an optional parameter; the default value is the null string.
InputRecordNumber This name required parameter specifies the numeric value to be assigned to the object's InputRecordNumber property. InputRecordNumber is an optional parameter; the default value is 0.

NodeName property

Name of node in input XmlDoc for which error occurred (AddToRecordError class)

[Introduced in Sirius Mods 7.8]

Syntax

%string = addToRecordError:NodeName

Syntax terms

%string A string to receive the name of a node in AddToRecord's method object XmlDoc. If the error involves a named node in the XmlDoc (for example, some cases when Reason = InvalidNode), this is the name of the node.
addToRecordError An AddToRecordError object.

NodeType property

XmlNodeType of node in input XmlDoc for which error occurred (AddToRecordError class)

[Introduced in Sirius Mods 7.8]

Syntax

%xmlNodeType = addToRecordError:NodeType

Syntax terms

%xmlNodeType A XmlNodeType enumeration to receive the type of a node in AddToRecord's method object XmlDoc. If the error involves a node in the XmlDoc (for example, if Reason = InvalidNode).
addToRecordError An AddToRecordError object.


Reason property

Enumerated reason for error (AddToRecordError class)

[Introduced in Sirius Mods 7.8]

Syntax

%addToRecordErrorReason = addToRecordError:Reason

Syntax terms

%addToRecordErrorReason This AddToRecordErrorReason enumeration value (see below) describes the reason for the translation failure.
addToRecordError An AddToRecordError object.

AddToRecordErrorReason enumeration

An AddToRecordErrorReason enumeration may have one of the following values:

InvalidNode A node in AddToRecord's method object XmlDoc does not conform to the structure as created by the LoadFromRecord subroutine.
UntranslatableFieldName A field name in AddToRecord's method object XmlDoc is not translatable to EBCDIC.
UntranslatableFieldgroupName A fieldgroup name in AddToRecord's method object XmlDoc is not translatable to EBCDIC.
UntranslatableValue A field value in AddToRecord's method object XmlDoc is not translatable to EBCDIC.
InvalidBase64 A string used for the base64 encoding of a field in AddToRecord's method object XmlDoc is not a valid base64 string.
FieldNameTooLong A field name in AddToRecord's method object XmlDoc is longer than 255 characters.
FieldgroupNameTooLong A fieldgroup name in AddToRecord's method object XmlDoc is longer than 255 characters.
ValueTooLong The value of a field in AddToRecord's method object XmlDoc that is not defined as a BLOB or CLOB field in the current file is longer than 255 characters or is longer than the defined LEN attribute, if the field is a fixed OCCURS field.
UnknownFieldName A field name in AddToRecord's method object XmlDoc is not defined in the current file.
UnknownFieldgroupName A fieldgroup name in AddToRecord's method object XmlDoc is not defined in the current file.
ExpectedField A field name in AddToRecord's method object XmlDoc is defined as a fieldgroup in the current file.
ExpectedFieldgroup A fieldgroup name in AddToRecord's method object XmlDoc is defined as a field in the current file.
ErrorAddingField An error occurred adding a field, such as a violation of a field constraint.
ErrorAddingFieldgroup An error occurred adding a fieldgroup, such as a file full condition.
ErrorObtainingRecord AddToRecord was unable to lock the record in exclusive mode.
InvalidFieldgroupID A fieldgroup ID in AddToRecord's method object XmlDoc is not numeric.
InvalidCodepage The codepage name specified on the codepage attribute of the Record element in AddToRecord's method object XmlDoc is not a known codepage name.
ErrorAddingMaxFieldgroupID The attempt to set the fieldgroup ID counter in the record failed; this is a very unusual condition.
InsufficientStorageForLOB STBL, VTBL, or User Buffer storage was unavailable.

The Description property indicates which of these is applicable.

InvalidVersion Invalid value of the version attribute of the Record element in AddToRecord's method object XmlDoc; the only allowed value is 1.
InvalidInputRecordNumber Invalid value of the number attribute of the Record element in AddToRecord's method object XmlDoc; it must either be -1 or a non-negative integer.

Note: As with all enumerations, the ToString 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 Common enumeration methods.

UntranslatableHexValue property

Hexadecimal representation of untranslatable Unicode character, if that is reason for error (AddToRecordError class)

[Introduced in Sirius Mods 7.8]

Syntax

%string = addToRecordError:UntranslatableHexValue

Syntax terms

%string A string to receive the hexadecimal value of the bytes that caused the exception to be thrown. This will only be valid if the Reason property indicates the exception was due to an untranslatable Unicode character.
addToRecordError An AddToRecordError object.


Value property

Value from input XmlDoc for which error occurred (AddToRecordError class)

[Introduced in Sirius Mods 7.8]

Syntax

%string = addToRecordError:Value

Syntax terms

%string A string to receive the value. If the error involves a value in AddToRecord's method object XmlDoc (for example, if Reason = InvalidBase64), this is the value that is in error (actually, up to 255 bytes of the value).
addToRecordError An AddToRecordError object.