XML-level errors, warnings and other diagnostics.
This class of objects is defined by libSBML only and has no direct
equivalent in terms of SBML components. This class is not prescribed by
the SBML specifications, although it is used to implement features
defined in SBML.
LibSBML can be configured to use any of a number of XML parsers; at the time of this writing, libSBML supports Xerces versions 2.4 through 3.1, Expat version 1.95.x and higher, and libxml2 version 2.6.16 and higher. These parsers each report different status codes for the various exceptions that can occur during XML processing. The XMLError_t object class abstracts away from the particular diagnostics reported by the different parsers and presents a single uniform interface and set of status codes, along with operations for manipulating the error objects.
When the libSBML XML parser layer encounters an error in the XML content being processed, or when there is something else wrong (such as an out-of-memory condition), the problems are reported as XMLError_t objects. Each XMLError_t object instance has an identification number that identifies the nature of the problem. This error identifier will be up to five digits long and drawn from the enumeration XMLErrorCode_t. Applications can use the error identifiers as a means of recognizing the error encountered and changing their behavior if desired.
Integer error codes are useful for software, but not so much for telling humans what happened. For this reason, XMLError_t also provides two text messages describing the nature of the error. These messages are accessible by means of the methods XMLError_t::getShortMessage() and XMLError_t::getMessage(). The method XMLError_t::getShortMessage() returns a very brief synopsis of the warning or error condition, whereas XMLError_t::getMessage() returns a longer explanation. These text strings are suitable for displaying to human users.
Each XMLError_t object also contains a category code; its value may be retrieved using the method XMLError_t::getCategory(). Category values are drawn from the enumeration XMLErrorCategory_t described below. Categories are used by libSBML to provide more information to calling programs about the nature of a given error.
In addition to category codes, each XMLError_t object also has a severity code; its value may be retrieved using the method XMLError_t::getSeverity(). Severity code values are drawn from the enumeration XMLErrorSeverity_t, described below. Severity levels range from informational (LIBSBML_SEV_INFO) to fatal errors (LIBSBML_SEV_FATAL).
Finally, XMLError_t objects record the line and column near where the problem occurred in the XML content. The values can be retrieved using the methods XMLError_t::getLine() and XMLError_t::getColumn(). We say "near
where the problem occurred", because many factors affect how accurate the line/column information ultimately is. For example, sometimes, the underlying XML parsers can only report such information for the parent XML element where an error occurs, and not for the specific point where the problem occurs. In other situations, some parsers report invalid line and/or column numbers altogether. If this occurs, libSBML sets the line and/or column number in the XMLError_t object to either 0 or the value of the maximum unsigned long integer representable on the platform where libSBML is running. The probability that a true line or column number in an SBML model would equal this value is vanishingly small; thus, if an application encounters these values in an XMLError_t object, it can assume no valid line/column number could be provided by libSBML in that situation.
XMLErrorCode_t
This is an enumeration of all the error and warning codes returned by the XML layer in libSBML. Each code is an integer with a 4-digit value less than 10000. The following table lists each possible value and a brief description of its meaning.
Possible XMLError_t error codes. Depending on the programming language in use, the Enumerator values will be defined either as a value from an enumeration type (XMLErrorCode_t) or as integer constants. To make this table more compact, we have shortened the identifiers for the category and severity codes to their essential parts. To get the actual names of the constants, prepend LIBSBML_CAT_ to the category names and LIBSBML_SEV_ to the severity names shown in the two right-hand columns.
| Enumerator | Meaning | Category | Severity |
| XMLUnknownError | Unrecognized error encountered internally | INTERNAL | FATAL |
| XMLOutOfMemory | Out of memory | SYSTEM | FATAL |
| XMLFileUnreadable | File unreadable | SYSTEM | ERROR |
| XMLFileUnwritable | File unwritable | SYSTEM | ERROR |
| XMLFileOperationError | Error encountered while attempting file operation | SYSTEM | ERROR |
| XMLNetworkAccessError | Network access error | SYSTEM | ERROR |
| InternalXMLParserError | Internal XML parser state error | INTERNAL | FATAL |
| UnrecognizedXMLParserCode | XML parser returned an unrecognized error code | INTERNAL | FATAL |
| XMLTranscoderError | Character transcoder error | INTERNAL | FATAL |
| MissingXMLDecl | Missing XML declaration at beginning of XML input | XML | ERROR |
| MissingXMLEncoding | Missing encoding attribute in XML declaration | XML | ERROR |
| BadXMLDecl | Invalid or unrecognized XML declaration or XML encoding | XML | ERROR |
| BadXMLDOCTYPE | Invalid, malformed or unrecognized XML DOCTYPE declaration | XML | ERROR |
| InvalidCharInXML | Invalid character in XML content | XML | ERROR |
| BadlyFormedXML | XML content is not well-formed | XML | ERROR |
| UnclosedXMLToken | Unclosed XML token | XML | ERROR |
| InvalidXMLConstruct | XML construct is invalid or not permitted | XML | ERROR |
| XMLTagMismatch | Element tag mismatch or missing tag | XML | ERROR |
| DuplicateXMLAttribute | Duplicate XML attribute | XML | ERROR |
| UndefinedXMLEntity | Undefined XML entity | XML | ERROR |
| BadProcessingInstruction | Invalid, malformed or unrecognized XML processing instruction | XML | ERROR |
| BadXMLPrefix | Invalid or undefined XML namespace prefix | XML | ERROR |
| BadXMLPrefixValue | Invalid XML namespace prefix value | XML | ERROR |
| MissingXMLRequiredAttribute | Missing a required XML attribute | XML | ERROR |
| XMLAttributeTypeMismatch | Data type mismatch for the value of an attribute | XML | ERROR |
| XMLBadUTF8Content | Invalid UTF8 content | XML | ERROR |
| MissingXMLAttributeValue | Missing or improperly formed attribute value | XML | ERROR |
| BadXMLAttributeValue | Invalid or unrecognizable attribute value | XML | ERROR |
| BadXMLAttribute | Invalid, unrecognized or malformed attribute | XML | ERROR |
| UnrecognizedXMLElement | Element either not recognized or not permitted | XML | ERROR |
| BadXMLComment | Badly formed XML comment | XML | ERROR |
| BadXMLDeclLocation | XML declaration not permitted in this location | XML | ERROR |
| XMLUnexpectedEOF | Reached end of input unexpectedly | XML | ERROR |
| BadXMLIDValue | Value is invalid for XML ID, or has already been used | XML | ERROR |
| BadXMLIDRef | XML ID value was never declared | XML | ERROR |
| UninterpretableXMLContent | Unable to interpret content | XML | ERROR |
| BadXMLDocumentStructure | Bad XML document structure | XML | ERROR |
| InvalidAfterXMLContent | Encountered invalid content after expected content | XML | ERROR |
| XMLExpectedQuotedString | Expected to find a quoted string | XML | ERROR |
| XMLEmptyValueNotPermitted | An empty value is not permitted in this context | XML | ERROR |
| XMLBadNumber | Invalid or unrecognized number | XML | ERROR |
| XMLBadColon | Colon characters are invalid in this context | XML | ERROR |
| MissingXMLElements | One or more expected elements are missing | XML | ERROR |
| XMLContentEmpty | Main XML content is empty | XML | ERROR |
XMLErrorCategory_t
As discussed above, each XMLError_t object contains a value for a category identifier, describing the type of issue that the XMLError_t object represents. The category can be retrieved from an XMLError_t object using the method XMLError_t::getCategory(). The value is chosen from the enumeration of category codes XMLErrorCategory_t. The following table lists each possible value and a brief description of its meaning.
| Enumerator | Meaning |
| LIBSBML_CAT_INTERNAL | A problem involving the libSBML software itself or the underlying XML parser. This almost certainly indicates a software defect (i.e., bug) in libSBML. Please report instances of this to the libSBML developers. |
| LIBSBML_CAT_SYSTEM | A problem reported by the operating system, such as an inability to read or write a file. This indicates something that is not a program error but is outside of the control of libSBML. |
| LIBSBML_CAT_XML | A problem in the XML content itself. This usually arises from malformed XML or the use of constructs not permitted in SBML. |
XMLErrorSeverity_t
As described above, each XMLError_t object contains a value for a severity code, describing how critical is the issue that the XMLError_t object represents. The severity can be retrieved from an XMLError_t object using the method XMLError_t::getSeverity(). The value is chosen from the enumeration of category codes XMLErrorSeverity_t. The following table lists each possible value and a brief description of its meaning.
| Enumerator | Meaning |
| LIBSBML_SEV_INFO | The error is actually informational and not necessarily a serious problem. |
| LIBSBML_SEV_WARNING | The error object represents a problem that is not serious enough to necessarily stop the problem, but applications should take note of the problem and evaluate what its implications may be. |
| LIBSBML_SEV_ERROR | The error object represents a serious error. The application may continue running but it is unlikely to be able to continue processing the same XML file or data stream. |
| LIBSBML_SEV_FATAL | A serious error occurred, such as an out-of-memory condition, and the software should terminate immediately. |
- Examples:
- createExampleSBML.c.
