Value (XmlDoc/XmlNode property): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (xpath arg)
 
(18 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:XmlDoc/XmlNode:Value subtitle}}
{{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.


This settable property obtains a substring of the XPath "string-value" of a
node, including its Text descendants.
The string-value depends on the node type, as shown in "Usage Notes,"
below.
==Syntax==
==Syntax==
{{Template:XmlDoc/XmlNode:Value syntax}}
{{Template:XmlDoc/XmlNode:Value syntax}}
Line 10: Line 7:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%currentUnicode</th>
<tr><th>%currentUnicode</th>
<td>A <var>Unicode</var> string that is the string-value of the context node. Prior to ''Sirius Mods'' version 7.6, this is an EBCDIC string. </td></tr>
<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>
<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 Root node is the context node. </td></tr>
<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>
<tr><th>xpath</th>
<td>An xpath expression that results in a nodelist, the head of which is the node to process. An optional argument, its default is a period (.), that is, the node referenced by the method object (<var class="term">nr</var>). </td></tr>
<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.
<tr><th>currentUnicode</th>
<p>
<td>A <var>Unicode</var> string that is the string-value to assign to the context node's <var>Value</var> property. Prior to ''Sirius Mods'' version 7.6, this is an EBCDIC string.</td></tr>
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>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>As of ''Sirius Mods'' version 7.3, the string terms in the method syntax may include
<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>.
only non-null EBCDIC characters that translate to <var>Unicode</var>.
<p>
As of ''Sirius Mods'' version 7.6, these 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 [[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>
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 Xml API"]].
For an example of a specific effect that involves the <var>Value</var> method, see [[#ampexmp|this example]], below.
<li>The string-value of a node depends on the node's type:
<li>The string-value of a node depends on the node's type:
<dl>
<table>
<dt>Node type
<tr class="head"><th>Node type</th>
<dd><var>String</var>-value
<th>String-value</th></tr>
<dt>Attribute
 
<dd>The normalized attribute value (see [[??]] refid=norval.)
<tr><td><var>Attribute</var></td>
<dt>Comment or Text
<td>The [[XML_processing_in_Janus_SOAP#Normalized_attribute_value|"normalized attribute value"]]</td></tr>
<dd>The content of the node
 
<dt>Element or Root
<tr><td><var>Comment</var> or <var>Text</var></td>
<dd>The concatenation of the value of all its Text descendants, in document
<td>The content of the node</td></tr>
order
 
<dt>PI
<tr><td><var>Element</var> or <var>Root</var></td>
<dd>The portion of the processing instruction following its target and any
<td>The concatenation of the value of all its <var>Text</var> descendants, in document order</td></tr>
whitespace immediately following the target
 
</dl>
<tr><td><var>PI</var></td>
<li><var>Value</var> is '''not''' allowed to be set if
<td>The portion of the processing instruction following its target and any whitespace immediately following the target</td></tr>
the head of the argument XPath result is
</table></li>
the Root or is an Element with a non-text child.
 
<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>
</ul>


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


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


%ebc = %nodeX:<var>Value</var>
  %ebc = %nodex:value
Print %ebc
  print %ebc


Print %nodeX:<var>Value</var>
  print %nodex:value
End
end
</p>
</p>
The result is:
The result is:
<p class="output">Jack & Jill
<p class="output">Jack & Jill
Jack &amp;amp; Jill
Jack &amp;amp; Jill
</p>
</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.


Because the <var>Unicode</var> string returned from <var>Value</var> in the example above
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.
is assigned to an EBCDIC variable before it is printed for the first time,
the initial Print 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 Print statement has to convert the <var>Unicode</var> value returned by the
<var>Value</var> expression.
For this, under ''Sirius Mods'' 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 to the string <tt>&amp;amp;</tt>.
In effect, Print calls the <var>Unicode</var>ToEbcdic method ([[??]] refid=fu2e.)
with parameter setting <tt>CharacterEncode=True</tt> to implicitly
convert the <var>Unicode</var> value.
Implicit <var>Unicode</var> conversions are further described [[??]] reftxt=* refid=uniconv..
</ol>
</ol>


===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><i>XPath</i> is invalid.
<li><var class="term">xpath</var> expression is invalid.
<li>Result of (<i>XPath</i>) is empty.
<li>Result of <var class="term">xpath</var> is empty.
<li>Insufficient free space exists in CCATEMP.
<li>Insufficient free space exists in CCATEMP.
</ul>
</ul>


==See also==
==See also==
{{Template:XmlDoc/XmlNode:Value footer}}
<ul>
<ul>
<li>[[??]] reftxt=<var>Value</var>Default refid=valdf. is a function
<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>
that obtains a node's string value and
<li>For more information about using XPath expressions, see [[XPath]].</li>
that allows an empty XPath result.
<li>For more information about using XPath expressions, see [[XPath]].
</ul>
</ul>
{{Template:XmlDoc/XmlNode:Value footer}}

Latest revision as of 18:10, 18 February 2015

String-value of selected node (XmlDoc and XmlNode classes)

This settable property obtains a substring of the XPath "string-value" of a node, including its Text descendants. The string-value depends on the node type, as shown in Usage Notes, below.

Syntax

%currentUnicode = nr:Value[( [xpath])] nr:Value[( [xpath])] = newUnicode Throws XPathError

Syntax terms

%currentUnicode A Unicode string that is the string-value of the context node. Prior to Sirius Mods Version 7.6, this is an EBCDIC string.
nr An XmlDoc or XmlNode, used as the context node for the xpath expression. If an XmlDoc, the Root node is the context node.
xpath An Xpath expression that results in a nodelist, the head of which is the node to process. Any other nodes in the nodelist are ignored.

This is an optional argument, and its default is a period (.), that is, the XmlNode referenced by the method object (nr).

newUnicode A Unicode string that is the string-value to assign to the context XmlNode's Value property. Prior to Sirius Mods Version 7.6, this is an EBCDIC string.

Usage notes

  • As of Sirius Mods Version 7.3, the string terms in the method syntax may include only non-null EBCDIC characters that translate to Unicode. As of Sirius Mods Version 7.6, these 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. For an example of a specific effect that involves the Value method, see this example, below.

  • The string-value of a node depends on the node's type:
    Node type String-value
    Attribute The "normalized attribute value"
    Comment or Text The content of the node
    Element or Root The concatenation of the value of all its Text descendants, in document order
    PI The portion of the processing instruction following its target and any whitespace immediately following the target
  • Value is not allowed to be set if the head of the argument XPath result is the Root or is an Element with a non-Text child.

Examples

  1. The following example displays the string "Hello, world!":

    begin %d object xmlDoc %d = new %d:loadXml('<t><a>Hell</a>' with '<b>o, world!'</b></t>') print %d:value('/t') end

  2. The following example assigns a new value to the "billRate" element:

    %worker:value('billRate') = %worker:value('billRate') - 10

  3. In the following request, run under Sirius Mods Version 7.6 or greater, an ampersand (&) in an Element value is returned by the Value method and displayed by two Print statements.

    begin %d object xmlDoc auto new %nodex is xmlNode %nodey is xmlNode %ebc is longstring %nodey = %d:addElement('top') %nodex = %nodeY:addElement('abc', 'Jack & Jill') %ebc = %nodex:value print %ebc print %nodex:value end

    The result is:

    Jack & Jill Jack &amp; Jill

    Because the Unicode string returned from Value in the example above is assigned to an EBCDIC variable before it is printed for the first time, the initial Print statement simply displays the EBCDIC variable value as is. The assignment to EBCDIC causes a straight character-by-character conversion using the current Unicode translation tables.

    The second Print statement has to convert the Unicode value returned by the Value expression. For this, under Sirius Mods Version 7.6 or greater, Print uses character encoding for any Unicode characters that do not translate to EBCDIC, and an ampersand is converted to the string &amp;. In effect, Print calls the UnicodeToEbcdic method with parameter setting CharacterEncode=True to implicitly convert the Unicode value.

Request-cancellation errors

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

  • xpath expression is invalid.
  • Result of xpath is empty.
  • Insufficient free space exists in CCATEMP.

See also

  • ValueDefault is a function that obtains an XmlNode's string value and that allows an empty XPath result.
  • For more information about using XPath expressions, see XPath.
Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Value_(XmlDoc/XmlNode_property)&oldid=75151"