%XML_DOC_ADDDECLARATION
Add a declaration to an XML document
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
VSupported on OpenVMS
|
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)
%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'?>