PBDOM exceptions

PBDOM defines an exception class derived from the standard PowerBuilder Exception class. This class extends the Exception class with a method, GetExceptionCode, that returns the unique code that identifies the exception being thrown.

The following table lists PBDOM exceptions and their code values. The circumstances in which each exception is thrown are described after the table.


PBDOM exception descriptions

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT

Code Value: 1

This exception is thrown when you use a nameable PBDOM_OBJECT -- for example, to invoke a method or serve as a parameter -- without first being given a user-defined name.

EXCEPTION_WRONG_DOCUMENT_ERROR

Code Value: 2

This exception is thrown when you use incorrect PBDOM_DOCUMENT objects when performing a PBDOM operation. For example, in a RemoveContent method call, if the PBDOM_OBJECT you want to remove is not from the same document as the active PBDOM_DOCUMENT whose RemoveContent method is being invoked, this exception is thrown.

EXCEPTION_MULTIPLE_ROOT_ELEMENT

Code Value: 3

This exception is thrown when a PBDOM method call causes a PBDOM_DOCUMENT to contain more than one root element.

For example, in an AddContent method call, if the input PBDOM_OBJECT to add is a PBDOM_ELEMENT and the active PDBOM_DOCUMENT already contains a root element, this exception is thrown.

EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT

Code Value: 4

This exception is thrown when a PBDOM_OBJECT is used in an inappropriate manner. A typical scenario is one is which a PBDOM method call results in the violation of the well-formedness of a PBDOM_DOCUMENT.

For example, in an AddContent method invoked on a PBDOM_DOCUMENT object, only PBDOM_OBJECTs of class PBDOM_ELEMENT, PBDOM_COMMENT, PBDOM_PROCESSINGINSTRUCTION, and PBDOM_DOCTYPE can be added. The inclusion of PBDOM_OBJECTs of any other class results in this exception being thrown.

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE

Code Value: 5

This exception is thrown when an invalid PBDOM_OBJECT is used, either directly to invoke a method, or as a parameter.

Situations where a PBDOM_OBJECT is deemed invalid include those where a PBDOM_OBJECT is instantiated as a PBDOM_OBJECT and not as a derived class object. They also include the situation where a PBDOM_CHARACTERDATA object is instantiated directly as a PBDOM_CHARACTERDATA object.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT

Code Value: 6

This exception occurs when a PBDOM_OBJECT is set to be the child of another PBDOM_OBJECT, but the prospective child already has a parent PBDOM_OBJECT.

Examples of such method calls include the AddContent method and the SetParentObject, SetContent, and InsertContent methods of all classes derived from PBDOM_OBJECT classes.

EXCEPTION_MULTIPLE_DOCTYPE

Code Value: 7

This exception is thrown when a PBDOM method call causes a PBDOM_DOCUMENT to contain more than one DOCTYPE.

For example, in an AddContent method call, if the input PBDOM_OBJECT to add is a PBDOM_DOCTYPE and the active PDBOM_DOCUMENT already contains a DOCTYPE DOM Node, this exception is thrown.

EXCEPTION_ILLEGAL_PBOBJECT

Code Value: 8

This exception is thrown in method calls that take an array of PBDOM_OBJECTs in which one of the array items is invalid. A PBDOM_OBJECT array item is deemed to be invalid when it has been specifically set to null or has not been initialized properly.

EXCEPTION_WRONG_PARENT_ERROR

Code Value: 9

This exception is thrown when an incorrect parent/child relationship error is encountered during a PBDOM operation.

Method calls in which this exception might be thrown include InsertContent and RemoveContent. These methods involve at least one PBDOM_OBJECT parameter that is assumed to be a child of the PBDOM_OBJECT to which the method is applied. If this parameter is not a child of the current PBDOM_OBJECT, this exception is thrown.

EXCEPTION_INVALID_ARGUMENT

Code Value: 10

This exception is thrown when an input PBDOM_OBJECT parameter to a method is invalid. This can happen if it has not been initialized properly, or if it is a null object reference.

This exception might also be thrown when an input string parameter to a method is invalid. This can happen if the string has been set to null using the PowerScript SetNull function.

EXCEPTION_INVALID_NAME

Code Value: 11

This exception is thrown when a name is supplied as a parameter and the name does not conform to the W3C specifications for an XML name or namespace prefix or namespace URI.

Methods in which this exception might be thrown include the SetName, SetNamespace, and SetNamespace methods.

EXCEPTION_DATA_CONVERSION

Code Value: 12

This exception is thrown when you attempt to perform a data conversion operation and the conversion fails. This exception is thrown only in the PBDOM_ATTRIBUTE object's Get methods, for example, GetDateValue in PBDOM_ATTRIBUTE.

EXCEPTION_MEMORY_ALLOCATION_FAILURE

Code Value: 13

This exception is thrown when insufficient memory is encountered while executing a method. PBDOM internally allocates, frees, and reallocates memory for storing strings, structures, and so on. Each memory allocation might fail, and if this occurs, this exception is thrown.

EXCEPTION_INTERNAL_XML_ENGINE_ERROR

Code Value: 14

This exception is thrown when an internal error occurs that involves the XML engine used by PBDOM. PBDOM currently uses the Xerces XML parser as the underlying device for processing XML documents and for building up and sustaining the DOM tree.

There may be problems in the low-level XML parser engine, and if one is encountered, this exception, which is rare, might be thrown.

EXCEPTION_MULTIPLE_XMLDECL

Code Value: 15

This exception is thrown when a PBDOM method call causes a PBDOM_DOCUMENT to contain more than one XML declaration.

For example, in a SetContent method call invoked on a PBDOM_DOCUMENT object, if the input PBDOM_OBJECT array contains more than one PBDOM_PROCESSINGINSTRUCTION that is constructed as an XML declaration, this exception is thrown.

EXCEPTION_INVALID_STRING

Code Value: 16

This exception is thrown when a string is supplied as a parameter to a method that sets a text or attribute value, and the string contains characters that do not conform to the W3C specifications for acceptable XML characters.

Methods in which this exception might be thrown include SetText in PBDOM_ATTRIBUTE and SetAttribute in PBDOM_ELEMENT.

EXCEPTION_INVALID_OPERATION

Code Value: 17

This exception is thrown when a method call could potentially cause severe and unexpected problems to the currently running PowerBuilder application.

EXCEPTION_HIERARCHY_ERROR

Code Value: 18

This exception is thrown when a method call violates the well-formedness or validity of a PBDOM_DOCUMENT.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_OWNER

Code Value: 19

This exception is thrown when a PBDOM_ELEMENT is set as the owner of a PBDOM_ATTRIBUTE when the specified PBDOM_ATTRIBUTE already has an owner PBDOM_ELEMENT.

EXCEPTION_PBDOM_NOT_INITIALIZED

Code Value: 20

This exception is thrown in rare circumstances in which the PBDOM engine has failed to be initialized or has been uninitialized prematurely. In such situations, an exception is thrown to prevent a crash.