View source for Value (XmlDoc/XmlNode property)

{{Template:XmlDoc/XmlNode:Value subtitle}}
This settable property obtains a substring of the [[XPath]] "string-value" of a <var>node</var>, including its <var>Text</var> descendants. The string-value depends on the node type, as shown in [[Value_(XmlDoc/XmlNode_property)#Usage_notes|Usage Notes]], below.

==Syntax==
{{Template:XmlDoc/XmlNode:Value syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%currentUnicode</th>
<td>A <var>Unicode</var> string that is the string-value of the context node. Prior to <var class="product">[[Sirius Mods]]</var> Version 7.6, this is an EBCDIC string.</td></tr>

<tr><th>nr</th>
<td>An <var>XmlDoc</var> or <var>XmlNode</var>, used as the context node for the <var class="term">xpath</var> expression. If an <var>XmlDoc</var>, the <var>Root</var> node is the context node.</td></tr>

<tr><th>xpath</th>
<td>An [[XPath#XPath_syntax|Xpath expression]] that results in a nodelist, the head of which is the node to process. Any other nodes in the nodelist are ignored.
<p>
This is an optional argument, and its default is a period (<code>.</code>), that is, the <var>XmlNode</var> referenced by the method object (<var class="term">nr</var>).</p></td></tr>

<tr><th>newUnicode</th>
<td>A <var>Unicode</var> string that is the string-value to assign to the context <var>XmlNode</var>'s <var>Value</var> property. Prior to <var class="product">Sirius Mods</var> Version 7.6, this is an EBCDIC string.</td></tr>
</table>

==Usage notes==
<ul>
<li>As of <var class="product">Sirius Mods</var> Version 7.3, the string terms in the method syntax may include only non-null EBCDIC characters that translate to <var>Unicode</var>.  As of <var class="product">Sirius Mods</var> Version 7.6, these strings are <var>Unicode</var> or are converted to <var>Unicode</var>.
<p>
For more information about the effects of this Version 7.6 change, see [[XmlDoc API#Strings and Unicode with the XmlDoc API|Strings and Unicode with the XmlDoc API]]. For an example of a specific effect that involves the <var>Value</var> method, see [[#ampexmp|this example]], below.</p></li>

<li>The string-value of a node depends on the node's type:
<table>
<tr class="head"><th>Node type</th>
<th>String-value</th></tr>

<tr><td><var>Attribute</var></td>
<td>The [[XML_processing_in_Janus_SOAP#Normalized_attribute_value|"normalized attribute value"]]</td></tr>

<tr><td><var>Comment</var> or <var>Text</var></td>
<td>The content of the node</td></tr>

<tr><td><var>Element</var> or <var>Root</var></td>
<td>The concatenation of the value of all its <var>Text</var> descendants, in document order</td></tr>

<tr><td><var>PI</var></td>
<td>The portion of the processing instruction following its target and any whitespace immediately following the target</td></tr>
</table></li>

<li><var>Value</var> is '''not''' allowed to be set if the head of the argument XPath result is the <var>Root</var> or is an <var>Element</var> with a non-<var>Text</var> child.</li>
</ul>

==Examples==
<ol>
<li>The following example displays the string "Hello, world!":
<p class="code">begin
   %d object xmlDoc
   %d = new
   %d:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<t><a>Hell</a>' with '<nowiki><b>o, world!'</b></nowiki></t>')
   print %d:value('/t')
end
</p>
<li>The following example assigns a new value to the "billRate" element:
<p class="code">%worker:value('billRate') = %worker:value('billRate') - 10
</p>
<div id="ampexmp"></div><li>In the following request, run under <var class="product">Sirius Mods</var> Version 7.6 or greater, an ampersand (<code>&amp;</code>) in an <var>Element</var> value is returned by the <var>Value</var> method and displayed by two <var>Print</var> statements.
<p class="code">begin
   %d object xmlDoc auto new
   %nodex is xmlNode
   %nodey is xmlNode
   %ebc is longstring

   %nodey = %d:[[AddElement_(XmlDoc/XmlNode_function)|addElement]]('top')
   %nodex = %nodeY:addElement('abc', 'Jack &amp; Jill')

   %ebc = %nodex:value
   print %ebc

   print %nodex:value
end
</p>
The result is:
<p class="output">Jack & Jill
Jack &amp;amp; Jill
</p>
Because the <var>Unicode</var> string returned from <var>Value</var> in the example above is assigned to an EBCDIC variable before it is printed for the first time, the initial <var>Print</var> statement simply displays the EBCDIC variable value as is.  The assignment to EBCDIC causes a straight character-by-character conversion using the current <var>Unicode</var> translation tables.

The second <var>Print</var> statement has to convert the <var>Unicode</var> value returned by the <var>Value</var> expression.  For this, under <var class="product">Sirius Mods</var> Version 7.6 or greater, Print uses character encoding for any <var>Unicode</var> characters that do not translate to EBCDIC, and an ampersand is converted to the string <code>&amp;amp;</code>. In effect, <var>Print</var> calls the <var>[[UnicodeToEbcdic_(Unicode_function)|UnicodeToEbcdic]]</var> method with parameter setting <code>CharacterEncode=True</code> to [[Unicode#Implicit_Unicode_conversions|implicitly convert]] the <var>Unicode</var> value.
</ol>

==Request-cancellation errors==
This list is not exhaustive: it does <i>not</i> include all the errors that are request  cancelling.
<ul>
<li><var class="term">xpath</var> expression is invalid.
<li>Result of <var class="term">xpath</var> is empty.
<li>Insufficient free space exists in CCATEMP.
</ul>

==See also==
<ul>
<li><var>[[ValueDefault_(XmlDoc/XmlNode_function)|ValueDefault]]</var> is a function that obtains an <var>XmlNode</var>'s string value and that allows an empty XPath result.</li>
<li>For more information about using XPath expressions, see [[XPath]].</li>
</ul>

{{Template:XmlDoc/XmlNode:Value footer}}