InvalidChar (XmlDoc property)

Allow invalid characters

InvalidChar is a member of the XmlDoc class.

Note: As described in the Usage Notes for the InvalidChar property 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 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 ?? refid=char.). 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

  %curr = doc:InvalidChar

  doc:InvalidChar = newvalue

Syntax Terms

%curr

The XmlInvalidChar enumeration value of doc's InvalidChar property. Valid values are Allow and Disallow, as described in “Usage Notes,” below.

doc

An XmlDoc object expression.

newvalue

The XmlInvalidChar enumeration value (Allow or Disallow) to assign to doc's InvalidChar property.

Usage Notes

• Pror to Sirius Mods version 7.3, setting the InvalidChar property to Allow 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:
  • 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 in ?? refid=xmpinvc..

  As of Sirius Mods 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 (?? refid=fue2u.).
• The values of the InvalidChar 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.

• The InvalidChar property applies to updates to Element or Attribute values. If InvalidChar is Allow, an invalid XML string is allowed in these cases:
  • As the second argument of the AddElement, InsertElementBefore, AddText, InsertTextBefore, and AddAttribute methods
  • As the right-hand side of an assignment to the Value property of an Element, Text, or Attribute node

  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

Prior to Sirius Mods 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

As of version 7.3, however, 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.

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.