%XML_DOC_ADDDECLARATION

Add a declaration to an XML document

status = %XML_DOC_ADDDECLARATION(document, declaration_name, declaration)

Return value

status

One of the following values:

XML_SUCCESS = A declaration is added successfully.

XML_FAIL = A declaration is not added successfully.

Arguments

document

The XML document instance to add a declaration to. (XML_DOC_TYPE)

declaration_name

The name of the declaration. Valid characters are alphanumeric characters, underscores, and dashes. (a)

declaration

The declaration text to add to the specified document. (See the Discussion below for the declaration format.) (a)

Discussion

%XML_DOC_ADDDECLARATION adds the specified declaration to an XML document (if it doesn’t already exist in the document) by appending it to the list of declarations for that document. If a declaration with the same name is found, the existing declaration is updated.

A declaration is a processing instruction that begins with “<?” and ends with “?>”. Editors, browsers, and document processors use declarations to determine how a document should be processed.

Every XML document should begin with a declaration of the following form, which identifies the document as XML and specifies the version of XML being used:

<?xml version='version' [standalone='stand_status'] [encoding='encoding_name']?>

version

The current XML version number.

stand_status

One of the following:

yes = The XML document has an internal DTD.

no = The XML document has an external DTD. (default)

encoding_name

The encoding name of the character set being used. The default is UTF-8, or US-ASCII. The Synergy XML API only processes encodings that can be represented without decoding, such as US-ASCII and ISO-8559-1.

A stand_status value of yes tells a validating parser (one that validates a document against a DTD) to generate an error if an external DTD is encountered. A Synergy XML parser is not a validating parser.

For example:

status = %xml_doc_adddeclaration(doc, "xml", "version='1.0' 
  &      standalone='yes' encoding='UTF-8'")

adds the following full XML declaration to the document:

<?xml version='1.0' standalone='yes' encoding='UTF-8'?>

In addition to the XML version declaration, you can add declarations with other names, such as

status = %xml_doc_adddeclaration(mydoc, "word", "document='test.doc'")

which adds this processing instruction to the document:

<?word document="test.doc"?>

The maximum length for a document declaration string, including the declaration name and the opening and closing “<?” and “?>” is 250 characters. The default declaration, if none is explicitly set, is

<?xml version='1.0'?>

This function is defined as ^VAL.

Examples

The following call

status = %xml_doc_adddeclaration(doc, "xml-stylesheet", "type='text/xsl'
  &      href='inprintdelivery.xsl'")

adds this full processing instruction to the document:

<?xml-stylesheet type='text/xsl' href='inprintdelivery.xsl'?>