Encoding (XmlDoc property): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
mNo edit summary
Line 1: Line 1:
<span style="font-size:120%; color:black"><b>Encoding value specificed in the "XML declaration"</b></span>
{{Template:XmlDoc:Encoding subtitle}}
[[Category:XmlDoc methods|Encoding property]]
[[Category:XmlDoc methods|Encoding property]]
[[Category:XmlDoc API methods]]
[[Category:XmlDoc API methods]]
Line 9: Line 9:
</p>
</p>


This property indicates the value of <tt>encoding</tt> in the &ldquo;XML
This property indicates the value of <tt>encoding</tt> in the "XML
declaration,&rdquo; if any, at the beginning of the serialized XML document.
declaration," if any, at the beginning of the serialized XML document.
===Syntax===
==Syntax==
  %curr = doc:Encoding
{{Template:XmlDoc:Encoding syntax}}
 
===Syntax terms===
  doc:Encoding = newvalue
 
====Syntax Terms====
<dl>
<dl>
<dt>%curr
<dt>%curr
Line 27: Line 24:
</dl>
</dl>


===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 Encoding
Line 91: Line 88:
Encoding property of the XmlDoc remains at or changes to <tt>UTF-8</tt>
Encoding property of the XmlDoc 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 &ldquo;XML
is specified as the <tt>encoding</tt> value in the "XML
declaration&rdquo; of the document.
declaration" of the document.
Otherwise, the value of the Encoding property does not change.
Otherwise, the value of the Encoding property does not change.
<li>Encoding may be a non-null string only
<li>Encoding may be a non-null string only

Revision as of 16:58, 22 January 2011

Encoding of XML document (XmlDoc class)

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

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