XmlDoc API - Revision history

JAL: add word

2016-05-13T19:39:11Z

add word

← Older revision		Revision as of 19:39, 13 May 2016
Line 747:		Line 747:
	<p class="output">AD		<p class="output">AD
	</p>		</p>
	<p class="note"><b>Note:</b> Model 204 7.6 added left and right square bracket XHTML entities to reduce your concern about [[Unicode#sqbrackets\|codepages and square brackets]]. For an example, see the [[UnicodeAfter (Unicode function)#Examples\|UnicodeAfter method]].</p></li>		<p class="note"><b>Note:</b> Model 204 7.6 maintenance added left and right square bracket XHTML entities to reduce your concern about [[Unicode#sqbrackets\|codepages and square brackets]]. For an example, see the [[UnicodeAfter (Unicode function)#Examples\|UnicodeAfter method]].</p></li>

	<li>The <var>[[Print (XmlDoc/XmlNode subroutine)\|Print]]</var> subroutine		<li>The <var>[[Print (XmlDoc/XmlNode subroutine)\|Print]]</var> subroutine

JAL: add note and link

2016-05-13T19:37:07Z

add note and link

← Older revision		Revision as of 19:37, 13 May 2016
Line 747:		Line 747:
	<p class="output">AD		<p class="output">AD
	</p>		</p>
			<p class="note"><b>Note:</b> Model 204 7.6 added left and right square bracket XHTML entities to reduce your concern about [[Unicode#sqbrackets\|codepages and square brackets]]. For an example, see the [[UnicodeAfter (Unicode function)#Examples\|UnicodeAfter method]].</p></li>

	<li>The <var>[[Print (XmlDoc/XmlNode subroutine)\|Print]]</var> subroutine		<li>The <var>[[Print (XmlDoc/XmlNode subroutine)\|Print]]</var> subroutine
Line 759:		Line 760:
	a character reference and avoid request cancellation.		a character reference and avoid request cancellation.

	<li>As described further in [[Unicode#Implicit Unicode conversions\|"Implicit Unicode conversions"]],		<li>As described further in [[Unicode#Implicit Unicode conversions\|Implicit Unicode conversions]],
	the <var class="product">User Language</var> <var>Print</var>		the <var class="product">User Language</var> <var>Print</var>
	statement under <var class="product">Sirius Mods</var> 7.6 does not cancel the request		statement under <var class="product">Sirius Mods</var> 7.6 does not cancel the request

JAL: /* Information form and content */

2014-03-24T18:20:20Z

Information form and content

← Older revision		Revision as of 18:20, 24 March 2014
Line 596:		Line 596:
	A given piece of information content has many potential serializations, including variations in line ends, CDATA sections, quotation characters used in attributes, attribute and namespace declaration order, etc. And in general, the character form of an XML document before it is deserialized will not be the same after it is re-serialized. It is a user task to determine to what degree to [[#Updating\|update]] an XmlDoc or to select serialization options to produce the desired form of character string output of the XML document information.		A given piece of information content has many potential serializations, including variations in line ends, CDATA sections, quotation characters used in attributes, attribute and namespace declaration order, etc. And in general, the character form of an XML document before it is deserialized will not be the same after it is re-serialized. It is a user task to determine to what degree to [[#Updating\|update]] an XmlDoc or to select serialization options to produce the desired form of character string output of the XML document information.

	For example, trying to obtain output like the second serialization in the example above (<code><top><foo></foo>1</top></code>), you specify literal start and end tags for <code>foo</code> in a SOUL deserialization method. But you discover that the default XmlDoc serialization result is <code><top><foo/>1</top></code>. One way to produce the tag presentation you want in this case is to use the serialization method option (<var>[[XmlDoc API serialization options#NoEmptyElt\|NoEmptyElt]]</var>) that forces start and end tags for childless elements. But a better way is discussed in the next paragraph, using the <var>NoEmptyElement</var> property.		For example, trying to obtain output like the second serialization in the example above (<code><top><foo></foo>1</top></code>), you specify literal start and end tags for <code>foo</code> in a SOUL deserialization method. But you discover that the default XmlDoc serialization result is <code><top><foo/>1</top></code>. One way (now deprecated) to produce the tag presentation you want in this case is to use the serialization method option (<var>[[XmlDoc API serialization options#NoEmptyElt\|NoEmptyElt]]</var>) that forces start and end tags for childless elements. But a better way is discussed in the next paragraph, using the <var>NoEmptyElement</var> property.

	A related conversion issue arises when using SOUL to generate HTML. Because some browsers work correctly for certain childless elements (for example, <code><br></code> tags) only if they have an empty element tag, and for other childless elements (for example, <code><div></code> tags) only if they have separate start and end tags, the <var>NoEmptyElt</var> solution just mentioned will produce HTML that works for some elements but not for others. The resolution for this is not in the serialization or deserialization methods but rather in the [[#Updating\|updating methods]] described above. You can use the updating methods to build or modify the HTML elements in your <var>XmlDoc</var>, getting information content equivalent to the deserialization methods, but providing better control and access. For the issue in this example, the <var>[[NoEmptyElement (XmlNode property)\|NoEmptyElement]]</var> property would let you selectively apply the tag format needed for successful HTML, as shown in the following request fragment:		A related conversion issue arises when using SOUL to generate HTML. Because some browsers work correctly for certain childless elements (for example, <code><br></code> tags) only if they have an empty element tag, and for other childless elements (for example, <code><div></code> tags) only if they have separate start and end tags, the <var>NoEmptyElt</var> solution just mentioned will produce HTML that works for some elements but not for others. The resolution for this is not in the serialization or deserialization methods but rather in the [[#Updating\|updating methods]] described above. You can use the updating methods to build or modify the HTML elements in your <var>XmlDoc</var>, getting information content equivalent to the deserialization methods, but providing better control and access. For the issue in this example, the <var>[[NoEmptyElement (XmlNode property)\|NoEmptyElement]]</var> property would let you selectively apply the tag format needed for successful HTML, as shown in the following request fragment:

JAL: /* Information form and content */

2014-03-18T03:25:06Z

Information form and content

← Older revision		Revision as of 03:25, 18 March 2014
Line 608:		Line 608:
	%body:addText('bar')		%body:addText('bar')
	</p>		</p>
	If you use the <var>Print</var> method to display the fragment above, the result is this <var>XmlDoc</var> (note the <code><div></code> and <code><br></code> tags):		If you use the <var>[[Print (XmlDoc/XmlNode subroutine)\|Print]]</var> method to display the fragment above, the result is this <var>XmlDoc</var> (note the <code><div></code> and <code><br></code> tags):
	<p class="output"><html>		<p class="output"><html>
	<body>		<body>

JAL: /* Transport: receiving and sending XML */

2014-03-18T03:01:37Z

Transport: receiving and sending XML

@@ Line 547: / Line 547: @@
 ==Transport: receiving and sending XML==
-Distinct sets of methods provide the for receiving and sending of XML:
+Distinct sets of methods provide for the receiving and sending of XML:
 <ul>
 <li>Receiving XML involves converting the information from the character,
@@ Line 583: / Line 583: @@
 </ul>
 </ul>
-About encoding:
 <ul>
 <li>When the internal representation of an <var>XmlDoc</var> is EBCDIC (prior to <var class="product">Sirius Mods</var>

JAL at 00:58, 18 March 2014

2014-03-18T00:58:34Z

Show changes

JAL at 17:49, 13 March 2014

2014-03-13T17:49:30Z

← Older revision		Revision as of 17:49, 13 March 2014
Line 1:		Line 1:
			<div class="toclimit-3">
	<!-- The XmlDoc API -->		<!-- The XmlDoc API -->
	<span style="font-size:120%; color:black"><b>XmlDoc API concepts and data structures</b></span>		<span style="font-size:120%; color:black"><b>XmlDoc API concepts and data structures</b></span>
Line 869:		Line 870:
	</ul>		</ul>
	</ul>		</ul>

	==See also==		==See also==
	<ul>		<ul>
	<li>[[XPath]]		<li>[[XPath]]
	</ul>		</ul>

			<!-- end of toclimit div -->

	[[Category:Overviews]]		[[Category:Overviews]]
	[[Category:Janus SOAP]]		[[Category:Janus SOAP]]

JAL: /* Transport: receiving and sending XML */

2014-03-13T17:16:16Z

Transport: receiving and sending XML

← Older revision		Revision as of 17:16, 13 March 2014
Line 546:		Line 546:

	===Transport: receiving and sending XML===		===Transport: receiving and sending XML===
	~~The provision~~ for receiving and sending XML ~~is very simple~~:		Distinct sets of methods provide the for receiving and sending of XML:
	<ul>		<ul>
	<li>Receiving XML involves converting the information from the character,		<li>Receiving XML involves converting the information from the character,

JAL at 00:33, 12 March 2014

2014-03-12T00:33:29Z

← Older revision		Revision as of 00:33, 12 March 2014
Line 118:		Line 118:
	steps:		steps:
	<ol>		<ol>
	<li>Converting the ~~<var>~~XmlDoc~~</var>~~ into its serial text representation.		<li>[[#About converting\|Converting the XmlDoc]] into its serial text representation.

	<li>Sending the document text using some "transport"; mechanism, such as <var class="product">Janus Web Server</var> (HTTP, as server),		<li>Sending the document text using some "transport"; mechanism, such as <var class="product">Janus Web Server</var> (HTTP, as server),
Line 130:		Line 130:
	For other forms of transport, the steps are performed separately:		For other forms of transport, the steps are performed separately:
	the <var>XmlDoc</var> is converted into external form by the		the <var>XmlDoc</var> is converted into external form by the
	<var>[[Serial (XmlDoc/XmlNode function)\|Serial]]</var> function		<var>[[Serial (XmlDoc/XmlNode function)\|Serial]]</var> function,
	and the converted result is sent using the appropriate transport.		and the converted result is sent using the appropriate transport.

JAL at 22:23, 10 March 2014

2014-03-10T22:23:30Z

← Older revision		Revision as of 18:20, 24 March 2014
Line 596:		Line 596:
	A given piece of information content has many potential serializations, including variations in line ends, CDATA sections, quotation characters used in attributes, attribute and namespace declaration order, etc. And in general, the character form of an XML document before it is deserialized will not be the same after it is re-serialized. It is a user task to determine to what degree to [[#Updating\|update]] an XmlDoc or to select serialization options to produce the desired form of character string output of the XML document information.		A given piece of information content has many potential serializations, including variations in line ends, CDATA sections, quotation characters used in attributes, attribute and namespace declaration order, etc. And in general, the character form of an XML document before it is deserialized will not be the same after it is re-serialized. It is a user task to determine to what degree to [[#Updating\|update]] an XmlDoc or to select serialization options to produce the desired form of character string output of the XML document information.

	For example, trying to obtain output like the second serialization in the example above (<code><top><foo></foo>1</top></code>), you specify literal start and end tags for <code>foo</code> in a SOUL deserialization method. But you discover that the default XmlDoc serialization result is <code><top><foo/>1</top></code>. One way to produce the tag presentation you want in this case is to use the serialization method option (<var>[[XmlDoc API serialization options#NoEmptyElt\|NoEmptyElt]]</var>) that forces start and end tags for childless elements. But a better way is discussed in the next paragraph, using the <var>NoEmptyElement</var> property.		For example, trying to obtain output like the second serialization in the example above (<code><top><foo></foo>1</top></code>), you specify literal start and end tags for <code>foo</code> in a SOUL deserialization method. But you discover that the default XmlDoc serialization result is <code><top><foo/>1</top></code>. One way (now deprecated) to produce the tag presentation you want in this case is to use the serialization method option (<var>[[XmlDoc API serialization options#NoEmptyElt\|NoEmptyElt]]</var>) that forces start and end tags for childless elements. But a better way is discussed in the next paragraph, using the <var>NoEmptyElement</var> property.

	A related conversion issue arises when using SOUL to generate HTML. Because some browsers work correctly for certain childless elements (for example, <code><br></code> tags) only if they have an empty element tag, and for other childless elements (for example, <code><div></code> tags) only if they have separate start and end tags, the <var>NoEmptyElt</var> solution just mentioned will produce HTML that works for some elements but not for others. The resolution for this is not in the serialization or deserialization methods but rather in the [[#Updating\|updating methods]] described above. You can use the updating methods to build or modify the HTML elements in your <var>XmlDoc</var>, getting information content equivalent to the deserialization methods, but providing better control and access. For the issue in this example, the <var>[[NoEmptyElement (XmlNode property)\|NoEmptyElement]]</var> property would let you selectively apply the tag format needed for successful HTML, as shown in the following request fragment:		A related conversion issue arises when using SOUL to generate HTML. Because some browsers work correctly for certain childless elements (for example, <code><br></code> tags) only if they have an empty element tag, and for other childless elements (for example, <code><div></code> tags) only if they have separate start and end tags, the <var>NoEmptyElt</var> solution just mentioned will produce HTML that works for some elements but not for others. The resolution for this is not in the serialization or deserialization methods but rather in the [[#Updating\|updating methods]] described above. You can use the updating methods to build or modify the HTML elements in your <var>XmlDoc</var>, getting information content equivalent to the deserialization methods, but providing better control and access. For the issue in this example, the <var>[[NoEmptyElement (XmlNode property)\|NoEmptyElement]]</var> property would let you selectively apply the tag format needed for successful HTML, as shown in the following request fragment:

← Older revision		Revision as of 22:23, 10 March 2014
Line 18:		Line 18:
	</table>		</table>
	The <var>XmlDoc</var> API is based on the use of XML documents.		The <var>XmlDoc</var> API is based on the use of XML documents.
	"[[XML processing in Janus SOAP]]" and various XML references		[[XML processing in Janus SOAP]] and various XML references
	explain that an XML document can contain any type of		explain that an XML document can contain any type of
	data, so an XML document may not be primarily intended for human reading.		data, so an XML document may not be primarily intended for human reading.
Line 31:		Line 31:
	<table class="thJustBold">		<table class="thJustBold">
	<tr><th>Receive</th>		<tr><th>Receive</th>
	<td>Receive the transmitted text of a document and convert it into an <var>XmlDoc</var>, ~~containing~~ nodes to represent the hierarchy of the XML document.</td></tr>		<td>Receive the transmitted text of a document and convert it into an <var>XmlDoc</var>, which uses nodes to represent the hierarchy of the XML document.</td></tr>

	<tr><th>Update</th>		<tr><th>Update</th>
Line 101:		Line 101:
	where in the hierarchy an update is performed.		where in the hierarchy an update is performed.

	Selecting nodes from an <var>XmlDoc</var> is performed using the XPath language		Selecting nodes from an <var>XmlDoc</var> is performed using the XPath language,
	(introduced in [[XML processing in Janus SOAP#XML Path Language (XPath): used in the XmlDoc API\|XML Path Language (XPath)]]).		introduced in [[XML processing in Janus SOAP#XML Path Language (XPath): used in the XmlDoc API\|XML Path Language (XPath)]].
	XPath can be used for accessing a single node in the document, for		XPath can be used for accessing a single node in the document, for
	example, getting an element node's string value using the		example, getting an element node's string value using the
Line 255:		Line 255:
	Most operations on the "contents" of an <var>XmlDoc</var>		Most operations on the "contents" of an <var>XmlDoc</var>
	select one or more nodes using XPath expressions ("PathExpr" is the XPath syntax term, as explained in		select one or more nodes using XPath expressions ("PathExpr" is the XPath syntax term, as explained in
	[[XML processing in Janus SOAP#XPath syntax\|"XPath syntax"]].		[[XML processing in Janus SOAP#XPath syntax\|XPath syntax]].
	All methods that accept an XPath LocationPath expression argument are		All methods that accept an XPath LocationPath expression argument are
	members of both the <var>XmlDoc</var> and the <var>XmlNode</var> classes.		members of both the <var>XmlDoc</var> and the <var>XmlNode</var> classes.
Line 288:		Line 288:
	The [[#An example of XmlDoc methods and XPath\|following section]] continues the explanation of		The [[#An example of XmlDoc methods and XPath\|following section]] continues the explanation of
	XPath, <var>XmlNode</var>s, and <var>XmlNodelist</var>s.		XPath, <var>XmlNode</var>s, and <var>XmlNodelist</var>s.
	Further information about XPath expressions and node sets is also contained in [[XPath~~\|"XPath"~~]].		Further information about XPath expressions and node sets is also contained in [[XPath]].

	===An example of XmlDoc API methods and XPath===		===An example of XmlDoc API methods and XPath===
Line 349:		Line 349:
	argument's XPath expression.		argument's XPath expression.
	That first node is called the '''head of the argument XPath result'''.		That first node is called the '''head of the argument XPath result'''.
	Note that '''first''' is defined in terms of "document order" (see "[[XPath#Order of nodes: node sets versus nodelists\|Order of nodes: node sets versus nodelists]]").		Note that '''first''' is defined in terms of "document order" (see [[XPath#Order of nodes: node sets versus nodelists\|Order of nodes: node sets versus nodelists]]).

	===Updating===		===Updating===
Line 747:		Line 747:

	For more information about the characters that are valid in an <var>XmlDoc</var> API XML document, see		For more information about the characters that are valid in an <var>XmlDoc</var> API XML document, see
	[[XML_processing_in_Janus_SOAP#ISO-10646_and_EBCDIC_characters\|"XML processing in Janus_SOAP: ISO-10646 and EBCDIC characters"]]		[[XML_processing_in_Janus_SOAP#ISO-10646_and_EBCDIC_characters\|XML processing in Janus_SOAP: ISO-10646 and EBCDIC characters]]

	====Using Longstrings or Unicode instead of Strings====		====Using Longstrings or Unicode instead of Strings====
Line 822:		Line 822:

	===Conventions and terminology for XmlDoc API methods===		===Conventions and terminology for XmlDoc API methods===
	In addition to those described in [[Notation conventions for methods~~\|"Notation conventions for methods"~~]],		In addition to those described in [[Notation conventions for methods]],
	the following conventions are also used in the individual <var>XmlDoc</var> API method descriptions:		the following conventions are also used in the individual <var>XmlDoc</var> API method descriptions:
	<ul>		<ul>