$Web File Content: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
 
(22 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$Web_File_Content}}
{{DISPLAYTITLE:$Web_File_Content}}
<span class="pageSubtitle"><section begin="desc" />Retrieve input contents<section end="desc" /></span>
<span class="pageSubtitle">Retrieve input contents</span>


<var>$Web_File_Content</var> retrieves the "content" of a file that was sent using the <tt>multipart/form-data</tt> format on an HTTP Post. <var>$Web_File_Content</var> returns this content as a longstring.


$Web_File_Content retrieves the "content" of a file that was sent using the <tt>multipart/form-data</tt> format on an HTTP Post. $Web_File_Content returns this content as a longstring.
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> %LSTR = $Web_File_Content( name, occurrence, type )
<p class="syntax"><span class="term">%lstr</span> = <span class="literal">$Web_File_Content</span>( [<span class="term">name</span>], [<span class="term">occurrence</span>], [<span class="term">type</span>] )
<section end="syntax" /></p>
</p>


<table class="syntaxTable">
<tr><th>%lstr</th>
<td>A <var>[[Longstrings|Longstring]]</var> variable for the returned content.


$Web_File_Content takes three arguments and returns a longstring.
<table class="syntaxTable">
<tr><th>name</th>
<tr><th>name</th>
<td>The name of the form field specified as <tt><input type="file"...></tt> from which content is to be retrieved. This is an optional argument; if it is not specified, all form fields are considered to match the request.</td></tr>
<td>The name of the form field specified as <code><input type="file"...></code> from which content is to be retrieved. This is an optional argument; if it is not specified, all form fields are considered to match the request.</td></tr>
 
<tr><th>occurrence</th>
<tr><th>occurrence</th>
<td>The occurrence number of the form field specified as <tt><input type="file"...></tt> that matches the first argument from which content is to be retrieved. This is an optional argument; if it is not specified, content is retrieved from the first form field that matches the ''name'' argument.</td></tr>
<td>The occurrence number of the form field specified as <code><input type="file"...></code> that matches the first argument from which content is to be retrieved. This is an optional argument; if it is not specified, content is retrieved from the first form field that matches the <var class="term">name</var> argument.</td></tr>
 
<tr><th>type</th>
<tr><th>type</th>
 
<td>A case-independent string set to one of the following:
<table class="syntaxTable">
<table class="thJustBold">
<td>A case-independent string set to one of the following:</td></tr>
<tr><th>Text</th>
<tr><th>Text</th>
<td>The data is text and is to be translated from ASCII to EBCDIC.</td></tr>
<td>The data is text and is to be translated from ASCII to EBCDIC.</td></tr>
<tr><th>Binary</th>
<tr><th>Binary</th>
<td>The data is to be left unchanged.</td></tr>
<td>The data is to be left unchanged.</td></tr>
<tr><th>TextUtf8</th>
<tr><th>TextUtf8</th>
<td>The data is UTF-8 and is to be converted to EBCDIC: each two-byte UTF-8 sequence is converted to the corresponding ASCII character, which is then translated to EBCDIC using the translation table in effect for the <var class="product">[[Janus Web Server]]</var> connection.</td></tr>
</table>
<var class="term">type</var> is an optional argument, and it defaults to <var>Binary</var>.</td></tr>
</table>


==Usage notes==
<ul>
<li>Interplay of the <var class="term">name</var> and <var class="term">occurrence</var> arguments:
<ul>
<li>If both field <var class="term">name</var> (argument 1) and field <var class="term">occurrence</var> (argument 2) are set, the indicated occurrence of the indicated field is retrieved. </li>


<td>The data is UTF-8 and is to be converted to EBCDIC: each two-byte UTF-8 sequence is converted to the corresponding ASCII character, which is then translated to EBCDIC using the translation table in effect for the ''[[Janus Web Server]]'' connection. This option was first provided as maintenance to ''[[Sirius Mods]]'' version 7.3.
<li>If the field <var class="term">name</var> is set, and the field <var class="term">occurrence</var> is '''not''', the first occurrence of the indicated field is retrieved. </li>
</td></tr></table>


<li>If the field <var class="term">name</var> is '''not''' set, and the field <var class="term">occurrence</var> is, the indicated field number is retrieved regardless of its name. That is, if occurrence number 4 is requested, the fourth received field is retrieved. </li>


''type'' is an optional argument, and it defaults to <tt>Binary</tt>.
<li>If neither the field <var class="term">name</var> nor the field <var class="term">occurrence</var> is set, the first field is retrieved regardless of its name.</li>
</td></tr></table>
</ul></li>


 
<li>A null is returned by both of these:
Notes:
<ul>
<ul>
<li>A request for a field that was not uploaded </li>
<li>A request for a field that has no file content, because it was not specified as <code><input type="file"...></code> on the HTML page, or because the HTML form was not specified with<code>enctype="multipart/form-data"</code> </li>
</ul> </li>


<li>If both field ''name'' (argument 1) and field ''occurrence'' (argument 2) are set, the indicated occurrence of the indicated field is retrieved.
<li><p class="note"><b>Note:</b> Text data retrieved by <var>$Web_File_Content</var> is not affected by the setting of the <var>JANUS DEFINE</var>, <var>JANUS WEB ON</var>, or <var>$Web_ProcSend</var> parameters <var>CR</var>, <var>LF</var>, or <var>CRLF</var>. But to facilitate subsequent parsing, ASCII carriage returns (X'0D') and linefeeds (X'0A') that a client sends as line-separators are translated by <var>$Web_File_Content</var> to EBCDIC carriage returns (X'0D') and linefeeds (X'25').</p> </li>
<li>If the field ''name'' is set, and the field ''occurrence'' is '''not''', the first occurrence of the indicated field is retrieved.
<li>If the field ''name'' is '''not''' set, and the field ''occurrence'' is, the indicated field number is retrieved regardless of its name. That is, if occurrence number 4 is requested, the fourth received field is retrieved.
<li>If neither the field ''name'' nor the field ''occurrence'' is set, the first field is retrieved regardless of its name.
</ul>
 
 
A null is returned by both of these:
<ul>


<li>A request for a field that was not uploaded
<li>Having the file content as a single longstring might be inconvenient for many applications, especially if the data is line-oriented. It is the application's responsibility to parse this longstring using either longstring parsing functions (see [[Longstrings]]) or <var>Stringlist</var> parsing methods (see [[List of Stringlist methods]] &mdash; the <var>Stringlist</var> class <var>ParseLines</var> method is likely to be particularly helpful). </li>
<li>A request for a field that has no file content, because it was not specified as <tt><input type="file"...></tt> on the HTML page, or because the HTML form was not specified with<tt>enctype="multipart/form-data"</tt>
</ul>
</ul>


 
==See also==
<blockquote> Text data retrieved by $Web_File_Content is not affected by the setting of the JANUS DEFINE, JANUS WEB ON, or $Web_ProcSend parameters CR, LF, or CRLF. But to facilitate subsequent parsing, ASCII carriage returns (X'0D') and linefeeds (X'0A') that a client sends as line-separators are translated by $Web_File_Content to EBCDIC carriage returns (X'0D') and linefeeds (X'25').</blockquote>  
<var>[[$Web_Output_Content]]</var> and <var>[[$Web_Input_Content]]</var>
 
Having the file content as a single longstring might be inconvenient for many applications, especially if the data is line-oriented. It is the application's responsibility to parse this longstring using either longstring parsing functions (see the ''Sirius Functions Reference Manual'') or Stringlist parsing methods (see the ''Janus SOAP Reference Manual'' -- the Stringlist class ParseLines method is likely to be particularly helpful).
 
$Web_File_Content is available only in Versions 6.7 and later of the ''[[Sirius Mods]]''.
 
See also [[$Web_Output_Content]] and [[$Web_Input_Content]].


[[Category:Janus Web Server $functions|$Web_File_Content]]
[[Category:Janus Web Server $functions|$Web_File_Content]]

Latest revision as of 19:49, 25 August 2014

Retrieve input contents

$Web_File_Content retrieves the "content" of a file that was sent using the multipart/form-data format on an HTTP Post. $Web_File_Content returns this content as a longstring.

Syntax

%lstr = $Web_File_Content( [name], [occurrence], [type] )

%lstr A Longstring variable for the returned content.
name The name of the form field specified as <input type="file"...> from which content is to be retrieved. This is an optional argument; if it is not specified, all form fields are considered to match the request.
occurrence The occurrence number of the form field specified as <input type="file"...> that matches the first argument from which content is to be retrieved. This is an optional argument; if it is not specified, content is retrieved from the first form field that matches the name argument.
type A case-independent string set to one of the following:
Text The data is text and is to be translated from ASCII to EBCDIC.
Binary The data is to be left unchanged.
TextUtf8 The data is UTF-8 and is to be converted to EBCDIC: each two-byte UTF-8 sequence is converted to the corresponding ASCII character, which is then translated to EBCDIC using the translation table in effect for the Janus Web Server connection.
type is an optional argument, and it defaults to Binary.

Usage notes

  • Interplay of the name and occurrence arguments:
    • If both field name (argument 1) and field occurrence (argument 2) are set, the indicated occurrence of the indicated field is retrieved.
    • If the field name is set, and the field occurrence is not, the first occurrence of the indicated field is retrieved.
    • If the field name is not set, and the field occurrence is, the indicated field number is retrieved regardless of its name. That is, if occurrence number 4 is requested, the fourth received field is retrieved.
    • If neither the field name nor the field occurrence is set, the first field is retrieved regardless of its name.
  • A null is returned by both of these:
    • A request for a field that was not uploaded
    • A request for a field that has no file content, because it was not specified as <input type="file"...> on the HTML page, or because the HTML form was not specified withenctype="multipart/form-data"
  • Note: Text data retrieved by $Web_File_Content is not affected by the setting of the JANUS DEFINE, JANUS WEB ON, or $Web_ProcSend parameters CR, LF, or CRLF. But to facilitate subsequent parsing, ASCII carriage returns (X'0D') and linefeeds (X'0A') that a client sends as line-separators are translated by $Web_File_Content to EBCDIC carriage returns (X'0D') and linefeeds (X'25').

  • Having the file content as a single longstring might be inconvenient for many applications, especially if the data is line-oriented. It is the application's responsibility to parse this longstring using either longstring parsing functions (see Longstrings) or Stringlist parsing methods (see List of Stringlist methods — the Stringlist class ParseLines method is likely to be particularly helpful).

See also

$Web_Output_Content and $Web_Input_Content