AllowNull (XmlDoc property)

From m204wiki
Revision as of 00:13, 7 December 2010 by 198.242.244.47 (talk) (Created page with "<span style="font-size:120%; color:black"><b>Allow null characters in node values?</b></span> AllowNull property Category:XmlDoc API methods [[Cat...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Allow null characters in node values?

AllowNull is a member of the XmlDoc class.

This 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 (using the LoadXml method, for example) 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'))

The default value of AllowNull is False.

AllowNull is new as of version 7.6 of the Sirius Mods.

Syntax

  %bool = doc:AllowNull
  doc:AllowNull = %bool

Syntax Terms

%bool
The Boolean enumeration value of doc's AllowNull property. For more information about these enumerations, see Using Boolean enumerations.
doc
An XmlDoc object expression.

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 (described on ?? reftxt=* refid=allunt.) 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 (?? refid=fue2u.).
  • A null character in an XmlDoc is serialized as an XML hexadecimal character reference: &#x0;.

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>

Request-Cancellation Errors (for set method)

  • %bool is an invalid value.