InvalidChar (XmlDoc property)

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:
  • 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

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

XmlDoc class XmlNode class XmlNodelist class	List of XmlDoc methods List of XmlNode methods List of XmlNodelist methods List of XmlDoc API methods	XmlDoc methods syntax XmlNode methods syntax XmlNodelist methods syntax
Notation conventions for methods