AddAttribute (XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(14 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Template:XmlNode:AddAttribute subtitle}}
{{Template:XmlNode:AddAttribute subtitle}}
This callable function adds an <var>Attribute</var> node to the method <var>Element</var> node.
==Syntax==
==Syntax==
{{Template:XmlNode:AddAttribute syntax}}
{{Template:XmlNode:AddAttribute syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%outNod</th>
<tr><th nowrap>%outNod</th>
<td>If specified, an <var>XmlNode</var> that is set to point to the <var>Attribute</var> node that is added. </td></tr>
<td>If specified, an <var>XmlNode</var> that is set to point to the [[XmlDoc API#XmlDoc node types|Attribute node]] that is added. </td></tr>
<tr><th>nod</th>
<tr><th>nod</th>
<td><var>XmlNode</var> that points to the <var>Element</var> node parent of the added <var>Attribute</var>. </td></tr>
<td><var>XmlNode</var> that points to the <var>Element</var> node parent of the added <var>Attribute</var>. </td></tr>
<tr><th>name</th>
<tr><th>name</th>
<td>A <var>Unicode</var> string that is the name of the added <var>Attribute</var>.
<td>A <var>Unicode</var> string that is the name of the added <var>Attribute</var>.
<p>Multiple <var>Attributes</var> with the same name may <b><i>not</i></b> be added to a single parent <var>Element</var> (in contrast with the <var>[[AddElement_(XmlDoc/XmlNode_function)|Add Element]]</var> method, which allows multiple <var>Elements</var> with the same name to be added to a single parent <var>Element</var>). The name must conform to the XML syntax rules for an attribute name; the maximum length of each of the prefix part and local name part is 127 characters (100 characters prior to version 7.7 of [[Janus SOAP]]).</p></td></tr>
<p>Multiple <var>Attributes</var> with the same name may <b><i>not</i></b> be added to a single parent <var>Element</var> (in contrast with the <var>[[AddElement_(XmlDoc/XmlNode_function)|AddElement]]</var> method, which allows multiple <var>Elements</var> with the same name to be added to a single parent <var>Element</var>). The name must conform to the XML syntax rules for an attribute name; the maximum length of each of the prefix part and local name part is 300 characters (127 characters prior to version 7.9, and 100 characters prior to version 7.7).</p></td></tr>
<tr><th>value</th>
<tr><th>value</th>
<td>A <var>Unicode</var> string that is the value of the added <var>Attribute</var>; stored exactly as is, that is, without whitespace normalization nor conversion of any substring which may be equal to a character or entity reference. </td></tr>
<td>A <var>Unicode</var> string that is the value of the added <var>Attribute</var>; stored exactly as is, that is, without whitespace normalization nor conversion of any substring which may be equal to a character or entity reference. </td></tr>
<tr><th>uri</th>
<tr><th>uri</th>
<td>A <var>Unicode</var> string that is the Uniform Resource Identifier of the namespace of the name of the added <var>Attribute</var>. This is an optional argument (see [[AddAttribute_(XmlNode_function)#Usage_notes|"Usage Notes"]], below).</td></tr>
<td>A <var>Unicode</var> string that is the Uniform Resource Identifier of the namespace of the name of the added <var>Attribute</var>. This is an optional argument (see [[AddAttribute_(XmlNode_function)#Usage_notes|"Usage notes"]], below).</td></tr>
</table>
</table>


Line 22: Line 20:
<ul>
<ul>
<li>Since the return value of <var>AddAttribute</var> is frequently not needed, you may want to <var>[[Notation_conventions_for_methods#Callable_methods|Call]]</var> it instead of saving its return value.
<li>Since the return value of <var>AddAttribute</var> is frequently not needed, you may want to <var>[[Notation_conventions_for_methods#Callable_methods|Call]]</var> it instead of saving its return value.
<li><var class="term">Attribute</var> nodes are kept in the order in which they are added.
 
<li>As of <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.3, the <var>AddAttribute</var> method arguments may include only non-null EBCDIC characters that translate to <var>Unicode</var>.
<li><var>Attribute</var> nodes are kept in the order in which they are added.
As of <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.6, these argument strings are <var>Unicode</var> or are converted to <var>Unicode</var>.  For more information about the effects of this Version 7.6 change, see <var>[[XmlNodelist_class#Strings_and_Unicode_with_the_XmlDoc_API|Strings and Unicode]]</var>.
 
<li>If the <i>URI</i> argument is present, it must not be the null string, <var class="term">name</var> must contain a prefix, and the <var>XmlDoc's</var> <var>[[Namespace_(XmlDoc_property)|Namespace property]]</var> must be <code>On</code>.  If there is no such declaration in effect at the <var>Element</var> pointed to by <var class="term">nod</var> for that prefix, a declaration is added at that <var>Element</var>, unless it would conflict with an existing declaration at the <var>Element</var> (which cancels the request).
<li>As of <var class="product">[[Sirius Mods|Sirius Mods]]</var> Version 7.3, the <var>AddAttribute</var> method arguments may include only non-null EBCDIC characters that translate to <var>Unicode</var>.
<li>If the <i>URI</i> argument is omitted, <var class="term">name</var> contains a prefix, and the <var>XmlDoc's</var> <var>[[Namespace_(XmlDoc_property)|Namespace property]]</var> is <code>On</code>,
As of <var class="product">Sirius Mods</var> Version 7.6, these argument strings are <var>Unicode</var> or are converted to <var>Unicode</var>.  For more information about the effects of this Version 7.6 change, see [[XmlNodelist_class#Strings_and_Unicode_with_the_XmlDoc_API|Strings and Unicode with the XmlDoc API]].
 
<li>If the <var class="term">uri</var> argument is present, it must not be the null string, <var class="term">name</var> must contain a prefix, and the <var>XmlDoc's</var> <var>[[Namespace_(XmlDoc_property)|Namespace property]]</var> must be <code>On</code>.  If there is no such declaration in effect at the <var>Element</var> pointed to by <var class="term">nod</var> for that prefix, a declaration is added at that <var>Element</var>, unless it would conflict with an existing declaration at the <var>Element</var> (which cancels the request).
 
<li>If the <var class="term">uri</var> argument is omitted, <var class="term">name</var> contains a prefix, and the <var>XmlDoc's</var> <var>Namespace</var> property value is <var>On</var>,
there must be a namespace declaration for the prefix in effect at the element pointed to by <var class="term">nod</var> (otherwise the request is canceled).
there must be a namespace declaration for the prefix in effect at the element pointed to by <var class="term">nod</var> (otherwise the request is canceled).
<li>To modify the value stored in an <var class="term">Attribute</var> node, change the Value property of an <var>XmlNode</var> that points to the <var class="term">Attribute</var> node.
 
<li>To modify the value stored in an <var>Attribute</var> node, change the <var>[[Value (XmlDoc/XmlNode property)|Value]]</var> property of an <var>XmlNode</var> that points to the <var>Attribute</var> node.
<li>Processing of an <var>XmlDoc</var> is likely to be more efficient if you add nodes in document order (that is, top-to-bottom, left-to-right).
<li>Processing of an <var>XmlDoc</var> is likely to be more efficient if you add nodes in document order (that is, top-to-bottom, left-to-right).
</ul>
</ul>
Line 37: Line 40:
</p>
</p>


==Request-Cancellation Errors==
==Request-cancellation errors==
This list is not exhaustive: it does <i>not</i> include all the errors that are request  cancelling.
<ul>
<ul>
<li><var class="term">Nod</var> is not an <var>Element</var> node.
<li>The <var class="term">nod</var> argument is not an <var>Element</var> node.
<li><var class="term">Name</var> violates the rules for an XML attribute name.
 
<li><var class="term">Name</var> is prefixed, but the <var>XmlDoc</var> Namespace property is None.
<li>The <var class="term">name</var> argument violates the rules for an XML attribute name.
<li><var class="term">Name</var> is the name of an attribute already present in the node pointed to by <var class="term">nod</var>.
 
<li><var class="term">Name</var> prefixed and Namespace On, but URI missing and no declaration for prefix in scope.
<li><var class="term">name</var> is prefixed, but the <var>XmlDoc</var> <var>Namespace</var> property is None.
<li><var class="term">Value</var> violates the rules for an XML attribute value (that is, it contains an invalid character).
 
<p><b>Note:</b> that as of <var>Sirius Mods</var> Version 7.6, this check can no longer be bypassed using the InvalidChar method &amp;amp;mdash; see [[InvalidChar (XmlDoc property)#Usage notes|"Usage notes for the InvalidChar property"]].</p>
<li><var class="term">name</var> is the name of an attribute already present in the node pointed to by <var class="term">nod</var>.
<li><var class="term">URI</var> violates the rules for an
 
<li><var class="term">name</var> prefixed and <var>Namespace</var> On, but URI missing and no declaration for prefix in scope.
 
<li>The <var class="term">value</var> argument violates the rules for an XML attribute value (that is, it contains an invalid character).
<p class="note"><b>Note:</b> As of <var class="product">Sirius Mods</var> Version 7.6, this check can no longer be bypassed using the <var>[[InvalidChar_(XmlDoc_property)|InvalidChar]]</var> method &mdash; see [[InvalidChar (XmlDoc property)#Usage notes|the InvalidChar property usage notes]].</p>
 
<li>The <var class="term">uri</var> argument violates the rules for an
absolute Uniform Resource Identifier.
absolute Uniform Resource Identifier.
<li><var class="term">URI</var> specified and Namespace property is not <code>On</code> or <var class="term">name</var> is not prefixed.
 
<li><var class="term">URI</var> specified and prefix of <var class="term">name</var> is declared with a different URI at the <var>Element</var> pointed to by <var class="term">nod</var> (not simply in scope at that <var>Element</var>).
<li><var class="term">uri</var> specified and <var>Namespace</var> property is not <code>On</code> or <var class="term">name</var> is not prefixed.
 
<li><var class="term">uri</var> specified and prefix of <var class="term">name</var> is declared with a different URI at the <var>Element</var> pointed to by <var class="term">nod</var> (not simply in scope at that <var>Element</var>).
<li>Insufficient free space exists in CCATEMP.
<li>Insufficient free space exists in CCATEMP.
</ul>
</ul>

Latest revision as of 23:20, 1 September 2015

Add Attribute to Element node (XmlNode class)

[Requires Janus SOAP]

Syntax

[%outNod =] nod:AddAttribute( name, value, [uri])

Syntax terms

%outNod If specified, an XmlNode that is set to point to the Attribute node that is added.
nod XmlNode that points to the Element node parent of the added Attribute.
name A Unicode string that is the name of the added Attribute.

Multiple Attributes with the same name may not be added to a single parent Element (in contrast with the AddElement method, which allows multiple Elements with the same name to be added to a single parent Element). The name must conform to the XML syntax rules for an attribute name; the maximum length of each of the prefix part and local name part is 300 characters (127 characters prior to version 7.9, and 100 characters prior to version 7.7).

value A Unicode string that is the value of the added Attribute; stored exactly as is, that is, without whitespace normalization nor conversion of any substring which may be equal to a character or entity reference.
uri A Unicode string that is the Uniform Resource Identifier of the namespace of the name of the added Attribute. This is an optional argument (see "Usage notes", below).

Usage notes

  • Since the return value of AddAttribute is frequently not needed, you may want to Call it instead of saving its return value.
  • Attribute nodes are kept in the order in which they are added.
  • As of Sirius Mods Version 7.3, the AddAttribute method arguments may include only non-null EBCDIC characters that translate to Unicode. As of Sirius Mods Version 7.6, these argument strings are Unicode or are converted to Unicode. For more information about the effects of this Version 7.6 change, see Strings and Unicode with the XmlDoc API.
  • If the uri argument is present, it must not be the null string, name must contain a prefix, and the XmlDoc's Namespace property must be On. If there is no such declaration in effect at the Element pointed to by nod for that prefix, a declaration is added at that Element, unless it would conflict with an existing declaration at the Element (which cancels the request).
  • If the uri argument is omitted, name contains a prefix, and the XmlDoc's Namespace property value is On, there must be a namespace declaration for the prefix in effect at the element pointed to by nod (otherwise the request is canceled).
  • To modify the value stored in an Attribute node, change the Value property of an XmlNode that points to the Attribute node.
  • Processing of an XmlDoc is likely to be more efficient if you add nodes in document order (that is, top-to-bottom, left-to-right).

Example

The following fragment adds the attribute named "option" to the element pointed to by %nod:

%nod:AddAttribute('option', 'abc')

Request-cancellation errors

This list is not exhaustive: it does not include all the errors that are request cancelling.

  • The nod argument is not an Element node.
  • The name argument violates the rules for an XML attribute name.
  • name is prefixed, but the XmlDoc Namespace property is None.
  • name is the name of an attribute already present in the node pointed to by nod.
  • name prefixed and Namespace On, but URI missing and no declaration for prefix in scope.
  • The value argument violates the rules for an XML attribute value (that is, it contains an invalid character).

    Note: As of Sirius Mods Version 7.6, this check can no longer be bypassed using the InvalidChar method — see the InvalidChar property usage notes.

  • The uri argument violates the rules for an absolute Uniform Resource Identifier.
  • uri specified and Namespace property is not On or name is not prefixed.
  • uri specified and prefix of name is declared with a different URI at the Element pointed to by nod (not simply in scope at that Element).
  • Insufficient free space exists in CCATEMP.

See also