AddToRecordError class

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.

Method	Description
Description	Description of error
FieldOrFieldgroupName	Name of field or fieldgroup for which error occurred
InputRecordNumber	Value of 'number' attribute from input XmlDoc
New	Create new AddToRecordError object
NodeName	Name of node in input XmlDoc for which error occurred
NodeType	XmlNodeType of node in input XmlDoc for which error occurred
Reason	Enumerated reason for error
UntranslatableHexValue	Hexadecimal representation of untranslatable Unicode character, if that is reason for error
Value	Value from input XmlDoc for which error occurred

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

• "Notation conventions for methods" has information about the conventions followed.
• "AddToRecordError methods syntax" is a single page that contains the syntax diagrams of all the methods in the class.

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.