Encoding (XmlDoc property)

Encoding of XML document (XmlDoc class)

The Encoding property indicates the value of encoding in the "XML declaration", if any, at the beginning of the serialized XML document.

Syntax

%currentString = doc:Encoding doc:Encoding = newString

Syntax terms

%currentString	The string value of doc's Encoding property.
doc	An XmlDoc object expression.
newString	The string value to assign to doc's Encoding property. The only values to which you may set the Encoding property are: The null string UTF-8 The initial value of the property is the null string.

Usage notes

• The setting of the Encoding property concerns the serialization of an XmlDoc. It is related but not equivalent to the value specified for encoding in the XML declaration of an XML document that is being deserialized (for example, <?xml version="1.0" encoding="UTF-16"...).

  An XML document that is the input to deserialization might have one of the following as the value of encoding in the XML declaration:

  UTF-8

  This encoding, part of the Unicode standard, specifies that Unicode characters with codes less than X'80' are represented by one byte, and additional bytes are used for other characters. This is also allowed in the input to deserialization if the document is represented in EBCDIC or User Language Unicode.

  UTF-16

  This encoding, part of the Unicode standard, specifies that most Unicode characters with codes less than X'10000' are represented by two bytes, and additional byte pairs are used for other characters.

  This is allowed as the input to deserialization only if the document is represented in UTF-16, which also requires that the first two bytes of the document input stream is a Byte Order Mark (either X'FEFF' for Big Endian or X'FFFE' for Little Endian).

  Obversely, if the input is represented in UTF-16 and the XML declaration is present with encoding specified, its value must be UTF-16. However, encoding may also be omitted.

  ISO-8859-n

  This encoding (where n may range from 1 through 9) is the encoding used for ASCII characters in the full range up to X'FF'. All nine of these encodings (ISO-8859-1, ISO-8859-2, etc.) are treated the same.

  This is allowed if the input contains ASCII, EBCDIC, or User Language Unicode characters.

  This is required if the input contains ASCII characters greater than X'7F'.

  none

  If there is not an XML declaration containing an encoding value, the input is examined and processed using the character code set contained in the input, whether it is UTF-8, UTF-16, ASCII, EBCDIC, or User Language Unicode.

  All of the above values of encoding in the XML declaration must be specified in all-uppercase letters.

  The allowed XML declaration encoding values and input character sets are also described in two tables shown in "Usage Notes for LoadXML".

• If a document is deserialized into an XmlDoc, the value of the Encoding property of the XmlDoc remains at or changes to UTF-8 if either UTF-8 or UTF-16 is specified as the encoding value specified in the "XML declaration" of the document. Otherwise, the value of the Encoding property does not change.
• Encoding may be a non-null string only if the value of the Version property is also a non-null string.
• The only impact of the Encoding property is the presence or absence of an encoding specification in the serialized form of the XmlDoc.

Examples

The following example sets the Version and Encoding properties:

begin %doc object xmlDoc %doc = new %doc:loadXml('<a/>') %doc:Version = '1.0' %doc:encoding = 'UTF-8' %doc:print End

The example result follows:

<?xml version="1.0" encoding="UTF-8"?> <a/>

Request-cancellation errors (for set method)

This list is not exhaustive: it does not include all the errors that are request cancelling.

• Version property is the null string, and newString argument is not the null string.
• newString is invalid.

See also

XmlDoc class XmlNode class XmlNodelist class	List of XmlDoc methods List of XmlNode methods List of XmlNodelist methods List of XmlDoc API methods	XmlDoc methods syntax XmlNode methods syntax XmlNodelist methods syntax
Notation conventions for methods