$Web Proc Receive or $Web Proc Recv: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(24 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$Web_Proc_Receive}}
{{DISPLAYTITLE:$Web_Proc_Receive or $Web_Proc_Recv}}
<span class="pageSubtitle"><section begin="desc" />Receive uploaded file into procedure<section end="desc" /></span>
<span class="pageSubtitle">Receive uploaded file into procedure</span>


$Web_Proc_Receive receives file upload data into a procedure. $WEB_PROC_RECV is a synonym for $Web_Proc_Receive.
<var>$Web_Proc_Receive</var> receives file upload data into a procedure.  
 
<b>Note:</b> <var>$Web_Proc_Recv</var> is a synonym for <var>$Web_Proc_Receive</var>.
 
<var>$Web_Proc_Receive</var> is a [[Calling_Sirius_Mods_$functions|callable]] $function that
takes five arguments and returns a status code.


==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> %RC = $WEB_PROC_[RECEIVE | RECV]( filename, procname, -
<p class="syntax"><span class="term">%rc</span> = $Web_Proc_[Receive | Recv]( <span class="term">filename, procname, fieldname, occurrence,  p_flag</span> )
fieldname, occurrence, -
</p>
  p_flag )
<section end="syntax" /></p>
 
$Web_Proc_Receive is a callable $function (see [[Calling_Sirius_Mods_$functions|Calling Sirius Mods $functions]]).


$Web_Proc_Receive takes five arguments and returns a status code.
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>filename
<tr><th>filename</th>
<td>The name of the <var class="product">Model 204</var> file or group into which the data is to be received. This parameter is optional. If it is not specified, the default file or group is used. This parameter may be specified as either of the following:
<ul>
<ul>
<li>A name only.
<li>A name only  
<li>Prefixed with "FILE" or "GROUP".
<li>Prefixed with "FILE" or "GROUP"  
</ul>
<p>
</th>
In this case, "FILE JANWEB" will look for the specified procedure in the file named JANWEB, "GROUP JANWEB" will look for the procedure in the group named JANWEB, and a bare "JANWEB" will look in a group first if it is open, then in a file.</p></ul></td></tr>
<td>The name of the ''Model 204'' file or group into which the data is to be received. This parameter is optional. If it is not specified, the default file or group is used. This parameter may be specified as either of the following: In this case, "FILE JANWEB" will look for the specified procedure in the file named JANWEB, "GROUP JANWEB" will look for the procedure in the group named JANWEB, and a bare "JANWEB" will look in a group first if it is open, then in a file.</td></tr>
<tr><th>procname</th>
<tr><th>procname</th>
<td>The name of the ''Model 204'' procedure into which data will be received. If the procedure does not exist, it will be created. If it already exists, it will be replaced. This parameter is required.</td></tr>
<td>The name of the <var class="product">Model 204</var> procedure into which data will be received. If the procedure does not exist, it will be created. If it already exists, it will be replaced. This parameter is required.</td></tr>
<tr><th>fieldname</th>
<tr><th>fieldname</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. This argument cannot be present if the upload request was the result of an HTTP PUT rather than a form-based upload. On a form-based upload if neither ''fieldname'' nor ''occurrence'' is present, the first (or only) file in the form will be uploaded.</td></tr>
<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. This argument cannot be present if the upload request was the result of an HTTP PUT rather than a form-based upload. On a form-based upload if neither ''fieldname'' nor ''occurrence'' is present, the first (or only) file in the form will be uploaded.</td></tr>
Line 31: Line 32:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>BINARY</th>
<tr><th>BINARY</th>
<td>''[[Janus Web Server]]'' performs no ASCII to EBCDIC translation on the contents and converts the data to the special ''[[Janus Web Server]]'' format binary procedure.</td></tr>
<td><var class="product">[[Janus Web Server]]</var> performs no ASCII to EBCDIC translation on the contents and converts the data to the special ''Janus Web Server'' format binary procedure.</td></tr>
<tr><th>BASE64</th>
<tr><th>BASE64</th>
<td>''[[Janus Web Server]]'' performs no ASCII to EBCDIC translation on the contents and converts the data to the special ''[[Janus Web Server]]'' format base64 encoded procedure.</td></tr>
<td>''Janus Web Server'' performs no ASCII to EBCDIC translation on the contents and converts the data to the special ''Janus Web Server'' format base64 encoded procedure.</td></tr>
<tr><th>TEXT</th>
<tr><th>TEXT</th>
<td>''[[Janus Web Server]]'' translates the data from ASCII to EBCDIC, separating the text into records (or lines) at any point where an ASCII carriage return (X'0D') or carriage return and line feed (X'0A') are found.
<td>''Janus Web Server'' translates the data from ASCII to EBCDIC, separating the text into records (or lines) at any point where an ASCII carriage return (X'0D') or carriage return and line feed (X'0A') are found.
</td></tr></table>
</td></tr></table>
</td></tr></table>
</td></tr></table>


<table class="syntaxTable">
==Usage notes==
<tr><th>Code</th>
<td>Meaning</td></tr>
<tr><th>1</th>
<td>Procedure successfully received.</td></tr>
<tr><th>0</th>
<td>Form field not found.</td></tr>
<tr><th>-1</th>
<td>Not a web thread</td></tr>
 
</table>
<p class="caption">$WEB_PROC_RECEIVE return codes</p>
 
 
Usage notes:
<ul>
<ul>
<li><var>$Web_Proc_Receive</var> does not close the connection with the browser and does not send any response to the browser. It is the responsibility of the <var class="product">User Language</var> programmer to ensure that an appropriate <var>$Web_Done</var> is sent to end the request.
<li>When <var>$Web_Proc_Receive</var> receives network data, it is first written to CCATEMP. Once the data is received completely in CCATEMP, it is quickly copied to the procedure file. A termination of the write to CCATEMP does not result in partially written procedure file.


<li>$Web_Proc_Receive does not close the connection with the browser and does not send any response to the browser. It is the responsibility of the User Language programmer to ensure that an appropriate $Web_Done is sent to end the request.
The setting of the <var>[[MAXTEMP]]</var> parameter of <var>JANUS DEFINE</var> as well as the CCATEMP size itself limit the number of pages an uploaded procedure may occupy.  
<li>When $Web_Proc_Receive receives network data, it is first written to CCATEMP. Once the data is received completely in CCATEMP, it is quickly copied to the procedure file. A termination of the write to CCATEMP does not result in partially written procedure file.
<li>For a form-based upload, the value returned by <var>$Web_Form_Parm</var> for the field associated with the file is the name of the file on the workstation that is being uploaded.
 
The setting of the MAXTEMP parameter of JANUS DEFINE as well as the CCATEMP size itself limit the number of pages an uploaded procedure may occupy.  
<li>For a form-based upload, the value returned by $Web_Form_Parm for the field associated with the file is the name of the file on the workstation that is being uploaded.
In the following example, a form-based file upload is stored in a procedure with a name of 'UP.' followed by the IP address of the browser followed by the name of the file on the browser. The use of IP address in this case, ensures that different users will not overlay each others files.
In the following example, a form-based file upload is stored in a procedure with a name of 'UP.' followed by the IP address of the browser followed by the name of the file on the browser. The use of IP address in this case, ensures that different users will not overlay each others files.


<p class="code"> %PROCNAME = 'UP.' WITH - $Web_IPAddr WITH '.' -
<p class="code">%PROCNAME = 'UP.' WITH - $Web_IPAddr WITH '.' -
WITH $Web_Form_Parm('UPFILE')
WITH $Web_Form_Parm('UPFILE')
   
   
%RC = $WEB_PROC_RECV('UPPROC', %PROCNAME)
%RC = $WEB_PROC_RECV('UPPROC', %PROCNAME)
</p>
</p>


Note that even though the field name was specified on the $Web_Form_Parm call (because there were other non-file input fields) it was not specified on the $WEB_PROC_RECV call (because there was only one file input field).  
Note that even though the field name was specified on the <var>$Web_Form_Parm</var> call (because there were other non-file input fields) it was not specified on the <var>$Web_Proc_Recv</var> call (because there was only one file input field).  
<li>It appears that most browser implementations of form-based uploads send the "type=file" fields whether or not the end-user selected a file to be uploaded. Because of this, $WEB_PROC_RECV will always return a 1 with these browsers if the indicated field appeared on the form being posted.  
 
<li>It appears that most browser implementations of form-based uploads send the "type=file" fields whether or not the end-user selected a file to be uploaded. Because of this, <var>$Web_Proc_Recv</var> will always return a 1 with these browsers if the indicated field appeared on the form being posted.
 
The way to distinguish the case where a user selected no file from the case where the user selected an empty file is to check if the value of the form parameter associated with the "type=file" field is null. If it is null, it probably means that the user has not selected a file to be uploaded. If it is not null but the target proc is empty after the <var>$Web_Proc_Recv</var>, it probably means that the user uploaded an empty file.  


The way to distinguish the case where a user selected no file from the case where the user selected an empty file is to check if the value of the form parameter associated with the "type=file" field is null. If it is null, it probably means that the user has not selected a file to be uploaded. If it is not null but the target proc is empty after the $WEB_PROC_RECV, it probably means that the user uploaded an empty file.  
It is quite possible that an HTTP/HTML standards-compliant browser will simply not upload a "type=file" field at all if the end-user did not select a file to be uploaded. In this latter case, a <var>$Web_Proc_Recv</var> would return a 0, but a <var>$Web_Form_Parm</var> for the "type=file" field would still return a null.  


It is quite possible that an HTTP/HTML standards-compliant browser will simply not upload a "type=file" field at all if the end-user did not select a file to be uploaded. In this latter case, a $WEB_PROC_RECV would return a 0, but a $Web_Form_Parm for the "type=file" field would still return a null.
<li>Since the file data you upload is less likely to be encoded as text, you can use code like the following to make your <var>$Web_Proc_Recv</var> more versatile:
<li>Since the file data you upload is less likely to be encoded as text, you can use code like the following to make your $WEB_PROC_RECV more versatile:


<p class="code"> %FORMAT = 'BASE64'
<p class="code">%FORMAT = 'BASE64'
%SUFFIX = $ParseX(%PROC,'.')
%SUFFIX = $ParseX(%PROC,'.')
IF $ONEOF(%SUFFIX, 'TXT/HTML/HTM/JAVA/JAV/RTF/CSV/DIF/-
IF $ONEOF(%SUFFIX, 'TXT/HTML/HTM/JAVA/JAV/RTF/CSV/DIF/-
EPS/INC/PL/DB/CGI/CSS/XML/DTD','/') THEN
EPS/INC/PL/DB/CGI/CSS/XML/DTD','/') THEN
%FORMAT = 'TEXT'
%FORMAT = 'TEXT'
END IF
END IF
  ...
  ...
%RC = $WEB_PROC_RECV(%FGNAME, %PROC, 'source',, %FORMAT)
%RC = $WEB_PROC_RECV(%FGNAME, %PROC, 'source',, %FORMAT)
</p>
</p>


<li>See also [[$Web_Line]].
<li>See also <var>[[$Web_Line]]</var>.
</ul>
</ul>




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

Latest revision as of 22:07, 5 June 2013

Receive uploaded file into procedure

$Web_Proc_Receive receives file upload data into a procedure.

Note: $Web_Proc_Recv is a synonym for $Web_Proc_Receive.

$Web_Proc_Receive is a callable $function that takes five arguments and returns a status code.

Syntax

%rc = $Web_Proc_[Receive | Recv]( filename, procname, fieldname, occurrence, p_flag )

Syntax terms

filename The name of the Model 204 file or group into which the data is to be received. This parameter is optional. If it is not specified, the default file or group is used. This parameter may be specified as either of the following:
  • A name only
  • Prefixed with "FILE" or "GROUP"

    In this case, "FILE JANWEB" will look for the specified procedure in the file named JANWEB, "GROUP JANWEB" will look for the procedure in the group named JANWEB, and a bare "JANWEB" will look in a group first if it is open, then in a file.

procname The name of the Model 204 procedure into which data will be received. If the procedure does not exist, it will be created. If it already exists, it will be replaced. This parameter is required.
fieldname 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. This argument cannot be present if the upload request was the result of an HTTP PUT rather than a form-based upload. On a form-based upload if neither fieldname nor occurrence is present, the first (or only) file in the form will be uploaded.
occurrence The number of the form field associated with the "<input type=file>" tag in the HTML form. This argument must be 1 or not present if the upload request was the result of an HTTP PUT rather than a form-based upload. On a form-based upload if neither fieldname nor occurrence is present, the first (or only) file in the form will be uploaded. If occurrence is present but fieldname is not, the occurrence number file is uploaded regardless of its name. If both occurrence and fieldname are present, the occurrence number file with name fieldname is uploaded.
p_flag Processing indicators for how the server should handle the procedure. This parameter is optional. Valid values are:
BINARY Janus Web Server performs no ASCII to EBCDIC translation on the contents and converts the data to the special Janus Web Server format binary procedure.
BASE64 Janus Web Server performs no ASCII to EBCDIC translation on the contents and converts the data to the special Janus Web Server format base64 encoded procedure.
TEXT Janus Web Server translates the data from ASCII to EBCDIC, separating the text into records (or lines) at any point where an ASCII carriage return (X'0D') or carriage return and line feed (X'0A') are found.

Usage notes

  • $Web_Proc_Receive does not close the connection with the browser and does not send any response to the browser. It is the responsibility of the User Language programmer to ensure that an appropriate $Web_Done is sent to end the request.
  • When $Web_Proc_Receive receives network data, it is first written to CCATEMP. Once the data is received completely in CCATEMP, it is quickly copied to the procedure file. A termination of the write to CCATEMP does not result in partially written procedure file. The setting of the MAXTEMP parameter of JANUS DEFINE as well as the CCATEMP size itself limit the number of pages an uploaded procedure may occupy.
  • For a form-based upload, the value returned by $Web_Form_Parm for the field associated with the file is the name of the file on the workstation that is being uploaded. In the following example, a form-based file upload is stored in a procedure with a name of 'UP.' followed by the IP address of the browser followed by the name of the file on the browser. The use of IP address in this case, ensures that different users will not overlay each others files.

    %PROCNAME = 'UP.' WITH - $Web_IPAddr WITH '.' - WITH $Web_Form_Parm('UPFILE') %RC = $WEB_PROC_RECV('UPPROC', %PROCNAME)

    Note that even though the field name was specified on the $Web_Form_Parm call (because there were other non-file input fields) it was not specified on the $Web_Proc_Recv call (because there was only one file input field).

  • It appears that most browser implementations of form-based uploads send the "type=file" fields whether or not the end-user selected a file to be uploaded. Because of this, $Web_Proc_Recv will always return a 1 with these browsers if the indicated field appeared on the form being posted. The way to distinguish the case where a user selected no file from the case where the user selected an empty file is to check if the value of the form parameter associated with the "type=file" field is null. If it is null, it probably means that the user has not selected a file to be uploaded. If it is not null but the target proc is empty after the $Web_Proc_Recv, it probably means that the user uploaded an empty file. It is quite possible that an HTTP/HTML standards-compliant browser will simply not upload a "type=file" field at all if the end-user did not select a file to be uploaded. In this latter case, a $Web_Proc_Recv would return a 0, but a $Web_Form_Parm for the "type=file" field would still return a null.
  • Since the file data you upload is less likely to be encoded as text, you can use code like the following to make your $Web_Proc_Recv more versatile:

    %FORMAT = 'BASE64' %SUFFIX = $ParseX(%PROC,'.') IF $ONEOF(%SUFFIX, 'TXT/HTML/HTM/JAVA/JAV/RTF/CSV/DIF/- EPS/INC/PL/DB/CGI/CSS/XML/DTD','/') THEN %FORMAT = 'TEXT' END IF ... %RC = $WEB_PROC_RECV(%FGNAME, %PROC, 'source',, %FORMAT)

  • See also $Web_Line.