InvalidChar (XmlDoc property) - Revision history

ELowell: /* Syntax terms */

2015-09-02T21:20:47Z

Syntax terms

← Older revision		Revision as of 21:20, 2 September 2015
Line 12:		Line 12:
	===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>

JALWiccan: Automatically generated page update

2014-08-25T16:36:52Z

Automatically generated page update

← Older revision		Revision as of 16:36, 25 August 2014
Line 18:		Line 18:
	<td>An <var>XmlDoc</var> object expression.</td></tr>		<td>An <var>XmlDoc</var> object expression.</td></tr>

	<tr><th>newXMLInvalidChar</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>

JAL: /* Syntax terms */

2014-08-25T16:34:43Z

Syntax terms

← Older revision		Revision as of 16:34, 25 August 2014
Line 18:		Line 18:
	<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>newXMLInvalidChar</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>

JAL at 20:51, 31 July 2014

2014-07-31T20:51:32Z

← Older revision		Revision as of 20:51, 31 July 2014
Line 3:		Line 3:
	<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>		<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>

	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'.		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'.

	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.		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.
Line 14:		Line 14:
	<tr><th>%currentXmlInvalidChar</th>		<tr><th>%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>

JAL at 19:37, 30 June 2014

2014-06-30T19:37:23Z

← Older revision		Revision as of 19:37, 30 June 2014
Line 1:		Line 1:
	{{Template:XmlDoc:InvalidChar subtitle}}		{{Template:XmlDoc:InvalidChar subtitle}}

	'''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 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>

	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'.		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'.
Line 9:		Line 9:
	==Syntax==		==Syntax==
	{{Template:XmlDoc:InvalidChar syntax}}		{{Template:XmlDoc:InvalidChar syntax}}

	===Syntax terms===		===Syntax terms===
	<table class="syntaxTable">		<table class="syntaxTable">
Line 22:		Line 23:
	The values of the <var>XmlInvalidChar</var> property are of type <var>[[Enumerations\|Enumeration]]</var> <var>XmlInvalidChar</var>:		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>

	'''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 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==
Line 36:		Line 39:
	<ul>		<ul>
	<li>The XML Element- or Attribute-updating methods allow the storing of any non-null EBCDIC character that translates to Unicode.		<li>The XML Element- or Attribute-updating methods allow the storing of any non-null EBCDIC character that translates to Unicode.
	<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"]].
			<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]].
	</ul>		</ul>
	As of <var class="product">Sirius Mods</var> Version 7.6:		As of <var class="product">Sirius Mods</var> Version 7.6:
	<ul>		<ul>
	<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.		<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.

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

	<ul>		<ul>
	<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.		<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.

	<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_(XmlDoc/XmlNode_property)\|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 <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.		<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.

	<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> “possibly” 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.		<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> “possibly” 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.

	<li>You can also check that a string is a valid XML string by using <var>[[InvalidCharacterPosition (XmlDoc function)\|InvalidCharacterPosition]]</var>.		<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.		<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><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:		<ol>
			<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:
	<p class="code">%doc:invalidChar = Allow		<p class="code">%doc:invalidChar = Allow
	%doc:[[AddElement_(XmlDoc/XmlNode_function)\|addElement]]('A', $X2C('FF00'))		%doc:[[AddElement_(XmlDoc/XmlNode_function)\|addElement]]('A', $X2C('FF00'))
Line 68:		Line 82:
	</p>		</p>
	However, as of <var class="product">Sirius Mods</var> Version 7.3, if <var>AddElement</var> (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.		However, as of <var class="product">Sirius Mods</var> Version 7.3, if <var>AddElement</var> (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.

	<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:		<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:
	<p class="code">%node:addElement('binaryData', %data:[[StringToBase64_(String_function)\|stringToBase64]])		<p class="code">%node:addElement('binaryData', %data:[[StringToBase64_(String_function)\|stringToBase64]])

JAL2 at 21:25, 16 August 2011

2011-08-16T21:25:26Z

← Older revision		Revision as of 21:25, 16 August 2011
Line 28:		Line 28:
	</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>

			'''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"]].

	==Usage notes==		==Usage notes==
Line 50:		Line 52:
	'''Note:'''		'''Note:'''
	The above operations imply that the string contains an EBCDIC value.		The above operations imply that the string contains an EBCDIC value.
	<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.		<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.
	<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> “possibly” 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.		<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> “possibly” 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.
	<li>You can also check that a string is a valid XML string by using <var>[[InvalidCharacterPosition (XmlDoc function)\|InvalidCharacterPosition]]</var>.		<li>You can also check that a string is a valid XML string by using <var>[[InvalidCharacterPosition (XmlDoc function)\|InvalidCharacterPosition]]</var>.

JAL2 at 00:10, 1 June 2011

2011-06-01T00:10:56Z

Goff: edits, tags and links

2011-05-29T02:50:50Z

edits, tags and links

Show changes

JAL2: /* Syntax terms */

2011-05-18T15:52:07Z

Syntax terms

← Older revision		Revision as of 15:52, 18 May 2011
Line 30:		Line 30:
	<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>		<h3>XmlInvalidChar enumeration</h3>
	The values of the <var>~~InvalidChar~~</var> property are of type <var>[[Enumerations\|Enumeration]]</var> <var>XmlInvalidChar</var>:		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>Allow
Line 39:		Line 39:
	</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>

	==Usage notes==		==Usage notes==
	<ul>		<ul>

JAL2: /* Usage notes */

2011-05-18T15:49:07Z

Usage notes

← Older revision		Revision as of 15:49, 18 May 2011
Line 51:		Line 51:
	<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.		Sirius recommends that <var>InvalidChar</var> not be used.
	See also the discussion below in [[#Examples]].		See also the discussion below in [[#Examples\|"Examples"]].
	</ul>		</ul>

← Older revision		Revision as of 00:10, 1 June 2011
Line 1:		Line 1:
	{{Template:XmlDoc:InvalidChar subtitle}}		{{Template:XmlDoc:InvalidChar subtitle}}

	'''NOTE:''' 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.		'''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.

	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'.		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'.
Line 12:		Line 12:
	<table class="syntaxTable">		<table class="syntaxTable">
	<tr><th>%currentXmlInvalidChar</th>		<tr><th>%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 <~~code~~>Allow</~~code~~> and <~~code~~>Disallow</~~code~~>.</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 (<~~code~~>Allow</~~code~~> or <~~code~~>Disallow</~~code~~>) 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>

Line 36:		Line 36:
	<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"]].		<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"]].
	</ul>		</ul>
	~~while as~~ of <var class="product">Sirius Mods</var> Version 7.6:		As of <var class="product">Sirius Mods</var> Version 7.6:
	<ul>		<ul>
	<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.		<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.
	<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. 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>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>		<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.		update operation. For example, you may be able to use the <var>Untranslatable</var> parameter of the <var>[[EbcdicToUnicode (String function)\|EbcdicToUnicode]]</var> function.
Line 45:		Line 45:
	<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:		<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:
	<ul>		<ul>
	<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.		<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.
	<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_(XmlDoc/XmlNode_property)\|Value]]</var> property of an <var>Element</var>, <var>Text</var>, or <var>Attribute</var> node.
	</ul>		</ul>
	'''Note:'''		'''Note:'''
	The above operations imply that the string contains an EBCDIC value.		The above operations imply that the string contains an EBCDIC value.
	<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.		<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.
	<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> “possibly” 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 ~~<var>~~Add~~</var>~~ and ~~<var>~~Insert~~</var>~~ methods, assigning to the <var>Value</var> property, and assigning a non-null string to the <var>[[SelectionNamespace_(XmlDoc_property)\|~~selectionNamespace~~]]</var> property.		<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> “possibly” 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.
	<li>You can also check that a string is a valid XML string by using <var>[[InvalidCharacterPosition (XmlDoc function)\|InvalidCharacterPosition]]</var>.		<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.		<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.
Line 72:		Line 72:
	</p></ol>		</p></ol>

	==Request-~~Cancellation Errors~~==		==Request-cancellation errors==
	<ul>		<ul>
	<li><var>InvalidChar</var> 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}}