Encoding (XmlDoc property)

Encoding value specificed in the "XML declaration"

Encoding is a member of the XmlDoc class.

This property indicates the value of encoding in the “XML declaration,” if any, at the beginning of the serialized XML document.

Syntax

  %curr = doc:Encoding

  doc:Encoding = newvalue

Syntax Terms

%curr

The string value of doc's Encoding property.

doc

An XmlDoc object expression.

newvalue

The string value to assign to doc's Encoding property.

Usage Notes

• 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.

• 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 which 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, 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 given ?? reftxt='*' refid=ldenc..

• 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 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 (??Version) 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.

Example

The following example sets the Version and Encoding properties:

    Begin
    %doc Object XmlDoc
    %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)

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