AllowNull (XmlDoc property): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
 
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:<tt>AllowNull</tt> (XmlDoc property)}}
{{Template:XmlDoc:AllowNull subtitle}}
{{Template:XmlDoc:AllowNull subtitle}}
The <var>AllowNull</var> property indicates whether or not the method object <var>XmlDoc</var> allows the deserialization of an XML document that contains nodes that have null characters (U+0000) in their values. A <var>[[Enumerations#Using Boolean enumerations|Boolean]]</var> value of <var>True</var> allows such deserializations. The default value, <var>False</var>, cancels the request if such a deserialization is attempted.
This property indicates whether or not the method object <var>XmlDoc</var> allows
<p>For example, the following <var>Element</var> node is acceptable for deserialization into an <var>XmlDoc</var> (for example, by using <var>[[LoadXml (XmlDoc/XmlNode function)|LoadXml]]</var>) only if <var>AllowNull</var> is <var>True</var>:</p>
the deserialization of an XML document that contains nodes
that have null characters (U+0000) in their values.
A <var>Boolean</var> value of <code>True</code> allows such deserializations.
The default value, <code>False</code>,
cancels the request if such a deserialization is attempted.
For example, the following Element node is acceptable for deserialization
into an <var>XmlDoc</var> (using the <var>[[LoadXml (XmlDoc/XmlNode function)|LoadXml]]</var> method, for example) only if <var>AllowNull</var>
is <code>True</code>:
<p class="code"><a>Element contains null: &amp;#0;</a>
<p class="code"><a>Element contains null: &amp;#0;</a>
</p>
</p>
<p>If <code>AllowNull=True</code>, null characters are also allowed for "direct setting" of a node's value using one of the many <var>Add</var> or <var>Insert</var> methods. For example:</p>
If <code>AllowNull=True</code>, null characters are also allowed for "direct setting"
of a node's value using one of the many Add or Insert methods.
For example:
<p class="code">%nod:AddElement('a', 'Element contains null:' With $X2C('00'))
<p class="code">%nod:AddElement('a', 'Element contains null:' With $X2C('00'))
</p>
</p>
   
   
The default value of <var>AllowNull</var> is <code>False</code>.
<var>AllowNull</var> is new as of version 7.6 of the ''Sirius Mods''.
==Syntax==
==Syntax==
{{Template:XmlDoc:AllowNull syntax}}
{{Template:XmlDoc:AllowNull syntax}}
Line 29: Line 13:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%currentBoolean</th>
<tr><th>%currentBoolean</th>
<td>The <var>Boolean</var> enumeration value of <var class="term">doc</var>'s <var>AllowNull</var> property. For more information about these enumerations, see [[Using Boolean enumerations]]. </td></tr>
<td>The <var>Boolean</var> enumeration value of <var class="term">doc</var>'s <var>AllowNull</var> property. </td></tr>
<tr><th>doc</th>
<tr><th>doc</th>
<td>An <var>XmlDoc</var> object expression.</td></tr>
<td>An <var>XmlDoc</var> object expression.</td></tr>
Line 35: Line 19:
<td>The <var>Boolean</var> value to assign to <var class="term">doc</var>'s <var>AllowNull</var> property.</td></tr>
<td>The <var>Boolean</var> value to assign to <var class="term">doc</var>'s <var>AllowNull</var> property.</td></tr>
</table>
</table>
 
==Usage notes==
==Usage notes==
<ul>
<ul>
<li>Nodes that are added to an <var>XmlDoc</var> that has <code>AllowNull=True</code>
<li>Nodes that are added to an <var>XmlDoc</var> that has <code>AllowNull=True</code> may not then be the source node in a subtree copy (<var>[[AddSubtree (XmlDoc/XmlNode function)|AddSubtree]]</var> or <var>[[InsertSubtreeBefore (XmlNode function)|InsertSubtreeBefore]]</var>) to a target <var>XmlDoc</var> that has <code>AllowNull=False</code>.
may not then be the source node in a subtree copy
<li>All Unicode characters except null can always be stored in an <var>XmlDoc</var>, so setting <var>AllowNull</var> to <code>True</code> means ''all'' Unicode characters can be stored. If you were using the
(<var>[[AddSubtree (XmlDoc/XmlNode function)|AddSubtree]]</var> or <var>[[InsertSubtreeBefore (XmlNode function)|InsertSubtreeBefore]]</var>) to a target
now obsolete <code>InvalidChar=Allow</code> setting to allow null characters in an <var>XmlDoc</var>, you can use <code>AllowNull=True</code> instead.
<var>XmlDoc</var> that has <code>AllowNull=False</code>.
<li>Deserialization of Unicode characters that do not translate to EBCDIC is not allowed unless the <var>[[LoadXml (XmlDoc/XmlNode function)#allowUntrans|AllowUntranslatable]]</var> deserialization option is used.
<li>All Unicode characters except null can always be stored
<li>When providing EBCDIC characters to be stored in an <var>XmlDoc</var>, those EBCDIC characters must be translatable to Unicode. If you have EBCDIC strings that may not be translatable, you must handle those before passing them to an <var>XmlDoc</var> update operation. For example, you may be able to use the <var>Untranslatable</var> argument of the <var>[[EbcdicToUnicode (String function)|EbcdicToUnicode]]</var> function.
in an <var>XmlDoc</var>, so setting <var>AllowNull</var> to <code>True</code> means ''all''
<li>A null character in an <var>XmlDoc</var> is serialized as an XML hexadecimal character reference: <code>&amp;#x0;</code>.
Unicode characters can be stored.
<li><var>AllowNull</var> is new as of <var class="product">[[Sirius Mods]]</var> Version 7.6.
If you were using the
now obsolete <code>InvalidChar=Allow</code> setting to allow null
characters in an <var>XmlDoc</var>, you can use <code>AllowNull=True</code> instead.
<li>Deserialization of Unicode characters that do not
translate to EBCDIC is not allowed unless the <code>[[LoadXml (XmlDoc/XmlNode function)#allowUntrans|AllowUntranslatable]]</code>
deserialization option is used.
<li>When providing EBCDIC characters to be stored in
an <var>XmlDoc</var>, those EBCDIC characters must be translatable to
Unicode.
If you have EBCDIC strings that may not be translatable, you
must handle those before passing them to an <var>XmlDoc</var> update operation.
For example, you may be able to use the <var>Untranslatable</var>
argument of the <var>[[EbcdicToUnicode (String function)|EbcdicToUnicode]]</var> function.
<li>A null character in an <var>XmlDoc</var> is serialized
as an XML hexadecimal character reference: <code>&amp;#x0;</code>.
</ul>
</ul>
==Examples==
==Examples==
In the following request, an EBCDIC X'FF' character requires a replacement to avoid request cancellation, but setting <var>AllowNull</var> to <code>True</code> lets a null be added to the <var>XmlDoc</var>.
In the following request, an Ebcdic X'FF' character requires a replacement
to avoid request cancellation,
but setting <var>AllowNull</var> to <code>True</code> lets a null be added to the <var>XmlDoc</var>.
<p class="code">Begin
<p class="code">Begin
%d is object Xmldoc auto new
  %d is object xmldoc auto new
%n1 is object xmlnode
  %n1 is object xmlnode
%n2 is object xmlnode
  %n2 is object xmlnode
%n3 is object xmlnode
  %n3 is object xmlnode
%txt is string len 32
  %txt is string len 32
%uni is unicode
  %uni is unicode
   
   
%d:LoadXml('<zen>The Buddha dog says</zen>')
  %d:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<zen>The Buddha dog says</zen>')
%n1 = %d:SelectSingleNode('zen')
  %n1 = %d:[[SelectSingleNode_(XmlDoc/XmlNode_function)|selectSingleNode]]('zen')
%txt = 'substitute character is ' With $X2C('FF')
  %txt = 'substitute character is ' with $X2C('FF')
%uni = %txt:EbcdicToUnicode(untranslatable='?')
  %uni = %txt:[[EbcdicToUnicode (String function)|ebcdicToUnicode]](untranslatable='?')
%n2 = %n1:AddComment(%uni)
  %n2 = %n1:[[AddComment_(XmlDoc/XmlNode_function)|addComment]](%uni)
printText {~} = {%n2:value}
  [[PrintText statement|printText]] {~} = {%n2:value}
   
   
%d:allownull = true
  %d:allownull = true
%n3 = %n1:AddElement('a', 'nothingness: ' With $X2C('00'))
  %n3 = %n1:[[AddElement_(XmlDoc/XmlNode_function)|addElement]]('a', 'nothingness: ' With $X2C('00'))
%d:print
  %d:print
end
end
</p>
</p>
Line 91: Line 58:
<zen>
<zen>
   The Buddha dog says
   The Buddha dog says
   <!--substitute character is ?-->
   <nowiki><!--substitute character is ?--></nowiki>
   <a>nothingness: &amp;#x0;</a>
   <a>nothingness: &amp;#x0;</a>
</zen>
</zen>

Latest revision as of 20:49, 31 May 2011

Allow null characters in node values? (XmlDoc class)

The AllowNull property indicates whether or not the method object XmlDoc allows the deserialization of an XML document that contains nodes that have null characters (U+0000) in their values. A Boolean value of True allows such deserializations. The default value, False, cancels the request if such a deserialization is attempted.

For example, the following Element node is acceptable for deserialization into an XmlDoc (for example, by using LoadXml) only if AllowNull is True:

<a>Element contains null: &#0;</a>

If AllowNull=True, null characters are also allowed for "direct setting" of a node's value using one of the many Add or Insert methods. For example:

%nod:AddElement('a', 'Element contains null:' With $X2C('00'))

Syntax

%currentBoolean = doc:AllowNull doc:AllowNull = newBoolean

Syntax terms

%currentBoolean The Boolean enumeration value of doc's AllowNull property.
doc An XmlDoc object expression.
newBoolean The Boolean value to assign to doc's AllowNull property.

Usage notes

  • Nodes that are added to an XmlDoc that has AllowNull=True may not then be the source node in a subtree copy (AddSubtree or InsertSubtreeBefore) to a target XmlDoc that has AllowNull=False.
  • All Unicode characters except null can always be stored in an XmlDoc, so setting AllowNull to True means all Unicode characters can be stored. If you were using the now obsolete InvalidChar=Allow setting to allow null characters in an XmlDoc, you can use AllowNull=True instead.
  • Deserialization of Unicode characters that do not translate to EBCDIC is not allowed unless the AllowUntranslatable deserialization option is used.
  • When providing EBCDIC characters to be stored in an XmlDoc, those EBCDIC characters must be translatable to Unicode. If you have EBCDIC strings that may not be translatable, you must handle those before passing them to an XmlDoc update operation. For example, you may be able to use the Untranslatable argument of the EbcdicToUnicode function.
  • A null character in an XmlDoc is serialized as an XML hexadecimal character reference: &#x0;.
  • AllowNull is new as of Sirius Mods Version 7.6.

Examples

In the following request, an EBCDIC X'FF' character requires a replacement to avoid request cancellation, but setting AllowNull to True lets a null be added to the XmlDoc.

Begin %d is object xmldoc auto new %n1 is object xmlnode %n2 is object xmlnode %n3 is object xmlnode %txt is string len 32 %uni is unicode %d:loadXml('<zen>The Buddha dog says</zen>') %n1 = %d:selectSingleNode('zen') %txt = 'substitute character is ' with $X2C('FF') %uni = %txt:ebcdicToUnicode(untranslatable='?') %n2 = %n1:addComment(%uni) printText {~} = {%n2:value} %d:allownull = true %n3 = %n1:addElement('a', 'nothingness: ' With $X2C('00')) %d:print end

The result is:

%n2:value = substitute character is ? <zen> The Buddha dog says <!--substitute character is ?--> <a>nothingness: &#x0;</a> </zen>

See also