Encoding (XmlDoc property): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (1 revision)
Line 8: Line 8:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%curr</th>
<tr><th>%curr</th>
<td>The string value of <i>doc</i>'s Encoding property. </td></tr>
<td>The string value of <i>doc</i>'s <var>Encoding</var> property. </td></tr>
<tr><th>doc</th>
<tr><th>doc</th>
<td>An XmlDoc object expression. </td></tr>
<td>An <var>XmlDoc</var> object expression. </td></tr>
<tr><th>newvalue</th>
<tr><th>newvalue</th>
<td>The string value to assign to <i>doc</i>'s Encoding property.</td></tr>
<td>The string value to assign to <i>doc</i>'s <var>Encoding</var> property.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>The only values to which you may ''set'' the Encoding
<li>The only values to which you may ''set'' the <var>Encoding</var>
property are:
property are:
<ul>
<ul>
Line 25: Line 25:


The initial value of the property is the null string.
The initial value of the property is the null string.
<li>The setting of the <tt>Encoding</tt> <i>property</i> concerns the
<li>The setting of the <tt><var>Encoding</var></tt> <i>property</i> concerns the
serialization of an XmlDoc.
serialization of an <var>XmlDoc</var>.
It is related but not equivalent to the value specified
It is related but not equivalent to the value specified
for <tt>encoding</tt> in the XML declaration of an XML document
for <tt>encoding</tt> in the XML declaration of an XML document
Line 36: Line 36:
<dl>
<dl>
<dt>UTF-8
<dt>UTF-8
<dd>This encoding, part of the Unicode standard, specifies that Unicode
<dd>This encoding, part of the <var>Unicode</var> standard, specifies that <var>Unicode</var>
characters with codes less than X'80' are represented by one byte, and additional
characters with codes less than X'80' are represented by one byte, and additional
bytes are used for other characters.
bytes are used for other characters.
This is also allowed in the input to deserialization if the document is
This is also allowed in the input to deserialization if the document is
represented in EBCDIC or User Language Unicode.
represented in EBCDIC or User Language <var>Unicode</var>.
<dt>UTF-16
<dt>UTF-16
<dd>This encoding, part of the Unicode standard, specifies that most
<dd>This encoding, part of the <var>Unicode</var> standard, specifies that most
Unicode characters with codes less than X'10000' are represented by two bytes,
<var>Unicode</var> characters with codes less than X'10000' are represented by two bytes,
and additional byte pairs are used for other characters.
and additional byte pairs are used for other characters.


Line 60: Line 60:
etc.) are treated the same.
etc.) are treated the same.


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


This is required if the input contains ASCII characters greater than
This is required if the input contains ASCII characters greater than
Line 68: Line 68:
value, the input is examined and processed using the character code set
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,
contained in the input, whether it is UTF-8, UTF-16, ASCII, EBCDIC,
or User Language Unicode.
or User Language <var>Unicode</var>.
</dl>
</dl>
All of the above values of <tt>encoding</tt> in the XML declaration
All of the above values of <tt>encoding</tt> in the XML declaration
Line 76: Line 76:
character sets are also described in two tables given
character sets are also described in two tables given
[[??]] reftxt='*' refid=ldenc..
[[??]] reftxt='*' refid=ldenc..
<li>If a document is deserialized into an XmlDoc, the value of the
<li>If a document is deserialized into an <var>XmlDoc</var>, the value of the
Encoding property of the XmlDoc remains at or changes to <tt>UTF-8</tt>
<var>Encoding</var> property of the <var>XmlDoc</var> remains at or changes to <tt>UTF-8</tt>
if either <tt>UTF-8</tt> or <tt>UTF-16</tt>
if either <tt>UTF-8</tt> or <tt>UTF-16</tt>
is specified as the <tt>encoding</tt> value in the "XML
is specified as the <tt>encoding</tt> value in the "XML
declaration" of the document.
declaration" of the document.
Otherwise, the value of the Encoding property does not change.
Otherwise, the value of the <var>Encoding</var> property does not change.
<li>Encoding may be a non-null string only
<li><var>Encoding</var> may be a non-null string only
if the value of the [[Version (XmlDoc property)|Version]] property
if the value of the [[Version (XmlDoc property)|Version]] property
is also a non-null string.
is also a non-null string.
<li>The only impact of the Encoding property is the presence or absence of
<li>The only impact of the <var>Encoding</var> property is the presence or absence of
an encoding specification in the serialized form of the XmlDoc.
an encoding specification in the serialized form of the <var>XmlDoc</var>.
</ul>
</ul>


===Example===
===Example===


The following example sets the Version and Encoding properties:
The following example sets the Version and <var>Encoding</var> properties:
<p class="code">Begin
<p class="code">Begin
%doc Object XmlDoc
%doc <var>Object</var> <var>XmlDoc</var>
%doc:LoadXml('<a/>')
%doc:LoadXml('<a/>')
%doc:Version = '1.0'
%doc:Version = '1.0'
%doc:Encoding = 'UTF-8'
%doc:<var>Encoding</var> = 'UTF-8'
%doc:Print
%doc:Print
End
End

Revision as of 17:46, 25 January 2011

Encoding of XML document (XmlDoc class)


This 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

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

See also