InvalidChar (XmlDoc property): Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:XmlDoc:InvalidChar subtitle}}
{{Template:XmlDoc:InvalidChar subtitle}}
   
   
'''Note:'''
<p class="warn">'''NOTE:''' As described in [[#Usage notes|Usage notes]] below, the <var>InvalidChar</var> property was deprecated as of <var class="product">[[Sirius Mods]]</var> Version 7.3, and it is '''''invalid''''' as of <var class="product">Sirius Mods</var> Version 7.6. </p>
As described in the [[#Usage notes|Usage notes]]
below, the <var>InvalidChar</var> property was deprecated as of <var class="product">Sirius Mods</var> version 7.3,
and it is '''invalid''' as of <var class="product">Sirius Mods</var> version 7.6.
   
   
Prior to <var class="product">Sirius Mods</var> 7.3, you use this property to control whether a string
Prior to <var class="product">Sirius Mods</var> Version 7.3, you use this property to control whether a string containing an invalid XML character can be added to an <var>XmlDoc</var>. A character is invalid if it is not one of the valid characters specified in the W3C Recommendation for XML (see [[XML_processing_in_Janus_SOAP#Char_and_Reference|"Char and Reference"]]). Prior to the introduction of this <var>InvalidChar</var> property (<var class="product">Sirius Mods</var> Version 6.8), <var class="product">[[Janus SOAP]]</var> did not permit such characters in an <var>XmlDoc</var>. An example is the "control character" X'01'.
containing an invalid XML character can be added to an <var>XmlDoc</var>.
A character is invalid if it is not one of the valid characters specified in
the W3C Recommendation for XML (see [[??]] refid=char.).
Prior to the introduction of this <var>InvalidChar</var> property (<var class="product">Sirius Mods</var> version 6.8),
[[Janus SOAP]] did not permit such characters in an <var>XmlDoc</var>.
An example is the &amp;amp;ldquo;control character&amp;amp;rdquo; X'01'.
   
   
This property is designed to let
This property is designed to let you use an <var>XmlDoc</var> to contain data that is '''not''' exchanged with other applications, yet whose content cannot be controlled by your application. If you present such a document to a W3C-compliant XML processor, it will be rejected as erroneous.
you use an <var>XmlDoc</var> to contain data that is '''not''' exchanged with other
 
applications, yet whose content cannot be controlled by your application.
If you present such a document
to a W3C-compliant XML processor, it will be rejected as erroneous.
==Syntax==
==Syntax==
{{Template:XmlDoc:InvalidChar syntax}}
{{Template:XmlDoc:InvalidChar syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%currentXmlInvalidChar</th>
<tr><th nowrap>%currentXmlInvalidChar</th>
<td>The <var>XmlInvalidChar</var> enumeration value (see below) of <var class="term">doc</var>'s <var>InvalidChar</var> property. Valid values are <var>Allow</var> and <var>Disallow</var>. </td></tr>
<td>The <var>XmlInvalidChar</var> enumeration value (see below) of <var class="term">doc</var>'s <var>InvalidChar</var> property. Valid values are <var>Allow</var> and <var>Disallow</var>.</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>
 
<tr><th><var>newXMLInvalidChar</var></th>
<tr><th><var>newXMLInvalidChar</var></th>
<td>The <var>XmlInvalidChar</var> enumeration value (<var>Allow</var> or <var>Disallow</var>) to assign to <var class="term">doc</var>'s <var>InvalidChar</var> property.</td></tr>
<td>The <var>XmlInvalidChar</var> enumeration value (<var>Allow</var> or <var>Disallow</var>) to assign to <var class="term">doc</var>'s <var>InvalidChar</var> property.</td></tr>
</table>
</table>
<h3>InvalidChar enumeration</h3>
 
The values of the <var>InvalidChar</var> property are of type <var>[[Enumerations|Enumeration]]</var> <var>XmlInvalidChar</var>:
===XmlInvalidChar enumeration===
The values of the <var>XmlInvalidChar</var> property are of type <var>[[Enumerations|Enumeration]]</var> <var>XmlInvalidChar</var>:
<table>
<table>
<tr><th>Allow
<tr><th><var>Allow</var>
</th><td>An <var>XmlDoc</var> with this setting allows invalid characters.
</th><td>An <var>XmlDoc</var> with this setting allows invalid characters.
</td></tr>
</td></tr>
<tr><th>Disallow
 
<tr><th><var>Disallow</var>
</th><td>An <var>XmlDoc</var> with this setting does '''not''' allow invalid characters. This is the default setting.
</th><td>An <var>XmlDoc</var> with this setting does '''not''' allow invalid characters. This is the default setting.
</td></tr></table>
</td></tr>
</table>
 
<p class="note">'''Note:''' As with all enumerations, the <var>ToString</var> method implicitly converts an enumeration value to a character string whose value is the name of the enumeration value. For more information about methods available to all enumerations, see [[Enumerations#Common enumeration methods|Common enumeration methods]]. </p>
 
==Usage notes==
==Usage notes==
<ul>
<ul>
<li>Pror to <var class="product">Sirius Mods</var> version 7.3,
<li>Pror to <var class="product">Sirius Mods</var> Version 7.3, setting the <var>InvalidChar</var> property to <code>Allow</code> lets you store any EBCDIC character, including the null character and including a character that does not translate to Unicode. However, as of version 7.3:
setting the <var>InvalidChar</var> property to <tt>Allow</tt> let you store any
EBCDIC character, including the null character and including a character that does not
translate to Unicode.
However, as of version 7.3:
<ul>
<ul>
<li>The XML Element- or Attribute-updating methods allow the storing of any
<li>The XML Element- or Attribute-updating methods allow the storing of any non-null EBCDIC character that translates to Unicode.
non-null EBCDIC character that translates to Unicode.
 
<li><var>InvalidChar</var> is deprecated, and it has no effect if invoked.
<li><var>InvalidChar</var> is deprecated, and it has no effect if invoked. Sirius recommends that <var>InvalidChar</var> not be used. See also the discussion below in [[#Examples|Examples]].
Sirius recommends that <var>InvalidChar</var> not be used.
See also the discussion below in [[#Examples]].
</ul>
</ul>
As of <var class="product">Sirius Mods</var> Version 7.6:
As of <var class="product">Sirius Mods</var> 7.6:
<ul>
<ul>
<li><var>XmlDocs</var> are maintained in Unicode, and
<li><var>XmlDocs</var> are maintained in Unicode, and all Unicode characters can always be stored in an <var>XmlDoc</var>, except null (U+0000), which is prohibited by the XML Recommendation.
all Unicode characters can always be stored in an <var>XmlDoc</var>, except null
 
(U+0000), which is prohibited by the XML Recommendation.
<li>The <var>InvalidChar</var> property is no longer supported, and requests containing <var>InvalidChar</var> will fail. If you are using <var>InvalidChar</var> in source code to allow null characters, you can use the <var>[[AllowNull (XmlDoc property)|AllowNull]]</var> property instead.
<li>The <var>InvalidChar</var> property is no longer supported, and
 
requests containing <var>InvalidChar</var> will fail.
<li>EBCDIC characters to be stored in an <var>XmlDoc</var> must be translatable to Unicode. If you have EBCDIC strings that may not be translatable, you must handle them before passing them to an <var>XmlDoc</var>
If you are using <var>InvalidChar</var> in source code to allow null characters, you
update operation. For example, you may be able to use the <var>Untranslatable</var> parameter of the <var>[[EbcdicToUnicode (String function)|EbcdicToUnicode]]</var> function.
can use the [[AllowNull (XmlDoc property)|AllowNull]]) property instead.
<li>EBCDIC characters to be stored in an <var>XmlDoc</var>
must be translatable to Unicode.
If you have EBCDIC strings that
may not be translatable, you must handle them before passing them to an <var>XmlDoc</var>
update operation.
For example, you may be able to use the <var>Untranslatable</var> parameter
of the <var>[[EbcdicToUnicode (String function)|EbcdicToUnicode]]</var> function.
</ul>
</ul>
<li>The <var>InvalidChar</var> property applies to updates to Element or Attribute
 
values.
<li>The <var>InvalidChar</var> property applies to updates to <var>Element</var> or <var>Attribute</var> values. If <var>InvalidChar</var> is <code>Allow</code>, an invalid XML string is allowed in these cases:
If <var>InvalidChar</var> is <code>Allow</code>, an invalid XML string is allowed in
 
these cases:
<ul>
<ul>
<li>As the second argument of the <var>AddElement</var>, <var>InsertElementBefore</var>,
<li>As the second argument of the <var>[[AddElement_(XmlDoc/XmlNode_function)|AddElement]]</var>, <var>[[InsertElementBefore (XmlNode function)|InsertElementBefore]]</var>, <var>[[AddText_(XmlNode_function)|AddText]]</var>, <var>[[InsertTextBefore_(XmlNode_function)|insertTextBefore]]</var>, and <var>[[AddAttribute_(XmlNode_function)|AddAttribute]]</var> methods.
<var>AddText</var>, InsertTextBefore,
 
and <var>AddAttribute</var> methods
<li>As the right-hand side of an assignment to the <var>[[Value_(XmlDoc/XmlNode_property)|Value]]</var> property of an <var>Element</var>, <var>Text</var>, or <var>Attribute</var> node.
<li>As the right-hand side of an assignment to the <var>Value</var> property
of an <var>Element</var>, <var>Text</var>, or <var>Attribute</var> node
</ul>
</ul>
'''Note:'''
<p class="note">'''Note:'''
The above operations imply that the string contains an EBCDIC value.
The above operations imply that the string contains an EBCDIC value. </p>
<li>This property does ''not'' affect updates to <var>Comment</var> or <var>Pi</var> nodes.
 
It also does ''not'' affect deserialization operations, such as the
<li>This property does ''not'' affect updates to <var>Comment</var> or <var>Pi</var> nodes. It also does ''not'' affect deserialization operations, such as the <var>[[LoadXml_(XmlDoc/XmlNode_function)|LoadXml]]</var> method, although in future versions of <var class="product">[[Janus SOAP]]</var> it may be extended to allow invalid <var>Attribute</var> and <var>Element</var> values created with deserialization methods.
<var>LoadXml</var> method, although in future versions of [[Janus SOAP]] it may be
 
extended to allow invalid <var>Attribute</var> and <var>Element</var> values created
<li>If <var>InvalidChar</var> is set to <code>Disallow</code> in the method object of the <var>[[AddSubtree_(XmlDoc/XmlNode_function)|AddSubtree]]</var> or <var>[[InsertSubtreeBefore_(XmlNode_function)|InsertSubtreeBefore]]</var> methods, the request is cancelled if the source <var>XmlDoc</var> &ldquo;possibly&rdquo; has any invalid characters. That is, it is cancelled if the <var>XmlDoc</var> containing the argument <var>XmlNode</var> has been updated (in any form) while its <var>InvalidChar</var> property was set to <code>Allow</code>. This is '''any''' form of update, including, for instance, deserialization, all the "Add*" and "Insert*" methods, assigning to the <var>Value</var> property, and assigning a non-null string to the <var>[[SelectionNamespace_(XmlDoc_property)|SelectionNamespace]]</var> property.
with deserialization methods.
 
<li>If <var>InvalidChar</var> is set to <code>Disallow</code> in the method object of the
<li>You can also check that a string is a valid XML string by using <var>[[InvalidCharacterPosition (XmlDoc function)|InvalidCharacterPosition]]</var>.
<var>AddSubtree</var> or <var>InsertSubtreeBefore</var> methods, the request is
 
cancelled if the source <var>XmlDoc</var> &amp;amp;ldquo;possibly&amp;amp;rdquo; has any invalid
<li>If you attempt to add an invalid character, the error message produced by <var>AddElement</var>, for example, contains a fragment of the value that includes the invalid character.
characters.
That is, it is cancelled if the <var>XmlDoc</var> containing the argument
<var>XmlNode</var> has been updated (in any form) while its <var>InvalidChar</var>
property was set to <code>Allow</code>.
This is '''any''' form of update,
including, for instance, deserialization, all the Add* and Insert*
methods, assigning to the <var>Value</var> property, and assigning a non-null
string to the <var>SelectionNamespace</var> property.
<li>You can also check that a string is a valid XML string by using
<var>[[InvalidCharacterPosition (XmlDoc function)|InvalidCharacterPosition]]</var>.
<li>If you attempt to add an invalid character,
the error message produced by <var>AddElement</var>, for example,
contains a fragment of the value that includes the invalid character.
</ul>
</ul>


==Examples==
==Examples==
<ol>
Prior to <var class="product">Sirius Mods</var> 7.3, <var>InvalidChar</var> let you store any EBCDIC character.
<li>Prior to <var class="product">Sirius Mods</var> Version 7.3, <var>InvalidChar</var> let you store any EBCDIC character. For example, the following fragment:
For example, the following fragment:
<p class="code">%doc:invalidChar = Allow
<p class="code"><nowiki>%doc:InvalidChar = Allow
%doc:[[AddElement_(XmlDoc/XmlNode_function)|addElement]]('A', $X2C('FF00'))
%doc:AddElement('A', $X2C('FF00'))
print 'Value is (hex):' and $C2X(%doc:[[Value_(XmlDoc/XmlNode_property)|value]])
Print 'Value is (hex):' And $C2X(%doc:Value)
</p>
</nowiki></p>
Produced the following result:
Produced the following result:
<p class="code"><nowiki>Value is (hex): FF00
<p class="code">Value is (hex): FF00
</nowiki></p>
</p>
However, as of <var class="product">Sirius Mods</var> Version 7.3, if <var>AddElement</var> (or another XML &ldquo;storing&rdquo; method) contains either the null character (X'00') or any EBCDIC character (such as X'FF') that does not translate to Unicode, it causes a request cancellation.
As of version 7.3, however, if <var>AddElement</var> (or another XML &amp;amp;ldquo;storing&amp;amp;rdquo; method)
 
contains either the null character (X'00') or any EBCDIC character (such as X'FF')
<li>If you have an <var>XmlDoc</var> with arbitrary EBCDIC byte streams, it is recommended that you store them in the <var>XmlDoc</var> using base-64 encoding. For example:
that does not translate to Unicode, it causes a request cancellation.
<p class="code">%node:addElement('binaryData', %data:[[StringToBase64_(String_function)|stringToBase64]])
If you have an
<var>XmlDoc</var> with arbitrary EBCDIC byte streams, it is
recommended that you store them in the <var>XmlDoc</var> using base-64 encoding.
For example:
<p class="code"><nowiki>%node:AddElement('binaryData', %data:StringToBase64)
  ...
  ...
%val = %node:Value:Base64ToString
%val = %node:value:[[Base64ToString_(String_function)|base64ToString]]
</nowiki></p>
</p></ol>
===Request-Cancellation Errors===
 
==Request-cancellation errors==
<ul>
<ul>
<li>InvalidChar has no request cancellation errors.
<li><var>InvalidChar</var> has no request-cancellation errors.
</ul>
</ul>
==See also==
==See also==
{{Template:XmlDoc:InvalidChar footer}}
{{Template:XmlDoc:InvalidChar footer}}

Latest revision as of 21:20, 2 September 2015

Allow invalid characters (obsolete) (XmlDoc class)


NOTE: As described in Usage notes below, the InvalidChar property was deprecated as of Sirius Mods Version 7.3, and it is invalid as of Sirius Mods Version 7.6.

Prior to Sirius Mods Version 7.3, you use this property to control whether a string containing an invalid XML character can be added to an XmlDoc. A character is invalid if it is not one of the valid characters specified in the W3C Recommendation for XML (see "Char and Reference"). Prior to the introduction of this InvalidChar property (Sirius Mods Version 6.8), Janus SOAP did not permit such characters in an XmlDoc. An example is the "control character" X'01'.

This property is designed to let you use an XmlDoc to contain data that is not exchanged with other applications, yet whose content cannot be controlled by your application. If you present such a document to a W3C-compliant XML processor, it will be rejected as erroneous.

Syntax

%currentXmlInvalidChar = doc:InvalidChar doc:InvalidChar = newXmlInvalidChar

Syntax terms

%currentXmlInvalidChar The XmlInvalidChar enumeration value (see below) of doc's InvalidChar property. Valid values are Allow and Disallow.
doc An XmlDoc object expression.
newXMLInvalidChar The XmlInvalidChar enumeration value (Allow or Disallow) to assign to doc's InvalidChar property.

XmlInvalidChar enumeration

The values of the XmlInvalidChar property are of type Enumeration XmlInvalidChar:

Allow An XmlDoc with this setting allows invalid characters.
Disallow An XmlDoc with this setting does not allow invalid characters. This is the default setting.

Note: As with all enumerations, the ToString method implicitly converts an enumeration value to a character string whose value is the name of the enumeration value. For more information about methods available to all enumerations, see Common enumeration methods.

Usage notes

  • Pror to Sirius Mods Version 7.3, setting the InvalidChar property to Allow lets you store any EBCDIC character, including the null character and including a character that does not translate to Unicode. However, as of version 7.3:
    • The XML Element- or Attribute-updating methods allow the storing of any non-null EBCDIC character that translates to Unicode.
    • InvalidChar is deprecated, and it has no effect if invoked. Sirius recommends that InvalidChar not be used. See also the discussion below in Examples.

    As of Sirius Mods Version 7.6:

    • XmlDocs are maintained in Unicode, and all Unicode characters can always be stored in an XmlDoc, except null (U+0000), which is prohibited by the XML Recommendation.
    • The InvalidChar property is no longer supported, and requests containing InvalidChar will fail. If you are using InvalidChar in source code to allow null characters, you can use the AllowNull property instead.
    • EBCDIC characters to be stored in an XmlDoc must be translatable to Unicode. If you have EBCDIC strings that may not be translatable, you must handle them before passing them to an XmlDoc update operation. For example, you may be able to use the Untranslatable parameter of the EbcdicToUnicode function.
  • The InvalidChar property applies to updates to Element or Attribute values. If InvalidChar is Allow, an invalid XML string is allowed in these cases:

    Note: The above operations imply that the string contains an EBCDIC value.

  • This property does not affect updates to Comment or Pi nodes. It also does not affect deserialization operations, such as the LoadXml method, although in future versions of Janus SOAP it may be extended to allow invalid Attribute and Element values created with deserialization methods.
  • If InvalidChar is set to Disallow in the method object of the AddSubtree or InsertSubtreeBefore methods, the request is cancelled if the source XmlDoc “possibly” has any invalid characters. That is, it is cancelled if the XmlDoc containing the argument XmlNode has been updated (in any form) while its InvalidChar property was set to Allow. This is any form of update, including, for instance, deserialization, all the "Add*" and "Insert*" methods, assigning to the Value property, and assigning a non-null string to the SelectionNamespace property.
  • You can also check that a string is a valid XML string by using InvalidCharacterPosition.
  • If you attempt to add an invalid character, the error message produced by AddElement, for example, contains a fragment of the value that includes the invalid character.

Examples

  1. Prior to Sirius Mods Version 7.3, InvalidChar let you store any EBCDIC character. For example, the following fragment:

    %doc:invalidChar = Allow %doc:addElement('A', $X2C('FF00')) print 'Value is (hex):' and $C2X(%doc:value)

    Produced the following result:

    Value is (hex): FF00

    However, as of Sirius Mods Version 7.3, if AddElement (or another XML “storing” method) contains either the null character (X'00') or any EBCDIC character (such as X'FF') that does not translate to Unicode, it causes a request cancellation.

  2. If you have an XmlDoc with arbitrary EBCDIC byte streams, it is recommended that you store them in the XmlDoc using base-64 encoding. For example:

    %node:addElement('binaryData', %data:stringToBase64) ... %val = %node:value:base64ToString

Request-cancellation errors

  • InvalidChar has no request-cancellation errors.

See also