WebReceive (XmlDoc function): Difference between revisions
Jump to navigation
Jump to search
m (move footer template to actual end; edits, tags and links) |
mNo edit summary |
||
| (6 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:XmlDoc:WebReceive subtitle}} | {{Template:XmlDoc:WebReceive subtitle}} | ||
<var>WebReceive</var> converts an HTTP request received on a <var class="product">[[Janus Web Server | <var>WebReceive</var> converts an HTTP request received on a <var class="product">[[Janus Web Server]]</var> thread from the text representation of an XML document to an <var>XmlDoc</var> tree (this process is called '''deserialization''', because the text representation of a document is called the '''serial''' form). It returns a zero value if the deserialization is successful; it returns a non-zero value if deserialization is unsuccessful and the <var>ErrRet</var> option is used and the particular error is tolerated. | ||
==Syntax== | ==Syntax== | ||
{{Template:XmlDoc:WebReceive syntax}} | {{Template:XmlDoc:WebReceive syntax}} | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%errorPosition</th> | <tr><th>%errorPosition</th> | ||
<td>A %variable set to 0 if the deserialization is successful, or, if the <var | <td>A %variable set to 0 if the deserialization is successful, or, if the <var>ErrRet</var> option is used, to the position within the uploaded data at which an error is found.</td></tr> | ||
<tr><th>doc</th> | <tr><th>doc</th> | ||
<td>An expression that points to the <var>XmlDoc</var> to contain the deserialized representation of the XML document.</td></tr> | <td>An expression that points to the <var>XmlDoc</var> to contain the deserialized representation of the XML document.</td></tr> | ||
<tr><th>formFieldName</th> | <tr><th>formFieldName</th> | ||
<td>The name of the form field associated with the "<input type=file>" tag in the HTML form, that is, the value of the "name" parameter in that tag. See the <var class="term">fieldname</var> argument of <var>[[$Web_Proc_Receive|$Web_Proc_Recv]]</var> | <td>The name of the form field associated with the "<input type=file>" tag in the HTML form, that is, the value of the "name" parameter in that tag. See the <var class="term">fieldname</var> argument of <var>[[$Web_Proc_Receive|$Web_Proc_Recv]]</var>.</td></tr> | ||
<tr><th>fieldOccurrence</th> | <tr><th>fieldOccurrence</th> | ||
<td>The number of the form field associated with the "<input type=file>" tag in the HTML form. See the <var class="term">occurrence</var> argument of <var>$Web_Proc_Recv</var> | <td>The number of the form field associated with the "<input type=file>" tag in the HTML form. See the <var class="term">occurrence</var> argument of <var>$Web_Proc_Recv</var>. </td></tr> | ||
<tr><th>options</th> | <tr><th>options</th> | ||
<td>See the <var class="term">[[LoadXml (XmlDoc/XmlNode function)#options|options]]</var> argument of <var>LoadXml</var>.</td></tr> | <td>See the <var class="term">[[LoadXml (XmlDoc/XmlNode function)#options|options]]</var> argument of <var>LoadXml</var>.</td></tr> | ||
| Line 22: | Line 27: | ||
<dl> | <dl> | ||
<dt><var>XmlParseError</var> | <dt><var>XmlParseError</var> | ||
<dd>If the method encounters a parsing error, properties of the | <dd>If the method encounters a parsing error, properties of the <var>[[XmlParseError_class|XMLParseError]]</var> exception object may indicate the location and type of problem. | ||
</dl> | </dl> | ||
| Line 31: | Line 36: | ||
==Examples== | ==Examples== | ||
The following <var class="product">Janus Web Server</var> program uses <var>WebReceive</var> to obtain the XML document from the HTTP request: | |||
The following <var class="product"> | |||
<p class="code">begin | <p class="code">begin | ||
%d object xmlDoc | %d object xmlDoc | ||
| Line 40: | Line 44: | ||
%d2 = new | %d2 = new | ||
%d2:[[LoadXml (XmlDoc/XmlNode function)|loadXml]]('<sum>' With - | %d2:[[LoadXml (XmlDoc/XmlNode function)|loadXml]]('<sum>' With - | ||
%d:[[Value_(XmlDoc/XmlNode_property)|value]]('/*/*[1]') + %d:value('/*/*[2]') | %d:[[Value_(XmlDoc/XmlNode_property)|value]]('/*/*[1]') + %d:value('/*/*[2]') with '</sum>') | ||
%d2:[[WebSend_(XmlDoc_subroutine)|webSend]] | %d2:[[WebSend_(XmlDoc_subroutine)|webSend]] | ||
end | end | ||
</p | </p> | ||
==Request- | ==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">doc</var> is not EMPTY. | <li>The <var class="term">doc</var> object is not EMPTY. | ||
<li><var class="term">options</var> is invalid. | <li>An <var class="term">options</var> argument is invalid. | ||
<li>Insufficient free space exists in CCATEMP. | <li>Insufficient free space exists in CCATEMP. | ||
<li>A syntax error occurred in the text string representation of the XML document (these are tolerated if the <var | <li>A syntax error occurred in the text string representation of the XML document (these are tolerated if the <var>ErrRet</var> option is specified). | ||
</ul> | </ul> | ||
==See also== | ==See also== | ||
<ul> | <ul> | ||
<li> | <li>To deserialize a string, use <var>[[LoadXml (XmlDoc/XmlNode function)|LoadXml]]</var>. | ||
<li>The subroutine that serializes an <var>XmlDoc</var> and sends it as a Web response is <var>[[WebSend_(XmlDoc_subroutine)|WebSend]]</var>. | <li>The subroutine that serializes an <var>XmlDoc</var> and sends it as a Web response is <var>[[WebSend_(XmlDoc_subroutine)|WebSend]]</var>. | ||
</ul> | </ul> | ||
{{Template:XmlDoc:WebReceive footer}} | {{Template:XmlDoc:WebReceive footer}} | ||
Latest revision as of 21:43, 10 March 2014
Deserialize Web request into this XmlDoc (XmlDoc class)
[Requires Janus SOAP]
WebReceive converts an HTTP request received on a Janus Web Server thread from the text representation of an XML document to an XmlDoc tree (this process is called deserialization, because the text representation of a document is called the serial form). It returns a zero value if the deserialization is successful; it returns a non-zero value if deserialization is unsuccessful and the ErrRet option is used and the particular error is tolerated.
Syntax
[%errorPosition =] doc:WebReceive[( [formFieldname], [fieldOccurrence], - [options])] Throws XmlParseError
Syntax terms
| %errorPosition | A %variable set to 0 if the deserialization is successful, or, if the ErrRet option is used, to the position within the uploaded data at which an error is found. |
|---|---|
| doc | An expression that points to the XmlDoc to contain the deserialized representation of the XML document. |
| formFieldName | The name of the form field associated with the "<input type=file>" tag in the HTML form, that is, the value of the "name" parameter in that tag. See the fieldname argument of $Web_Proc_Recv. |
| fieldOccurrence | The number of the form field associated with the "<input type=file>" tag in the HTML form. See the occurrence argument of $Web_Proc_Recv. |
| options | See the options argument of LoadXml. |
Exceptions
This function can throw the following exception:
- XmlParseError
- If the method encounters a parsing error, properties of the XMLParseError exception object may indicate the location and type of problem.
Usage notes
- See the LoadXml function.
Examples
The following Janus Web Server program uses WebReceive to obtain the XML document from the HTTP request:
begin %d object xmlDoc %d = new %d:webReceive %d2 object xmlDoc %d2 = new %d2:loadXml('<sum>' With - %d:value('/*/*[1]') + %d:value('/*/*[2]') with '</sum>') %d2:webSend end
Request-cancellation errors
This list is not exhaustive: it does not include all the errors that are request cancelling.
- The doc object is not EMPTY.
- An options argument is invalid.
- Insufficient free space exists in CCATEMP.
- A syntax error occurred in the text string representation of the XML document (these are tolerated if the ErrRet option is specified).
See also
- To deserialize a string, use LoadXml.
- The subroutine that serializes an XmlDoc and sends it as a Web response is WebSend.