View source for $Web Proc Receive or $Web Proc Recv

{{DISPLAYTITLE:$Web_Proc_Receive or $Web_Proc_Recv}}
<span class="pageSubtitle">Receive uploaded file into procedure</span>

<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==
<p class="syntax"><span class="term">%rc</span> = $Web_Proc_[Receive | Recv]( <span class="term">filename, procname, fieldname, occurrence,  p_flag</span> )
</p>

===Syntax terms===
<table class="syntaxTable">
<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>
<li>A name only 
<li>Prefixed with "FILE" or "GROUP" 
<p>
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>
<tr><th>procname</th>
<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>
<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>
<tr><th>occurrence</th>
<td>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.</td></tr>
<tr><th>p_flag</th>
<td>Processing indicators for how the server should handle the procedure. This parameter is optional. Valid values are:
<table class="syntaxTable">
<tr><th>BINARY</th>
<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>
<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>
<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>

==Usage notes==
<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. 

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>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.
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 '.' -
WITH $Web_Form_Parm('UPFILE')
 
%RC = $WEB_PROC_RECV('UPPROC', %PROCNAME)
</p>

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, <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. 

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. 

<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:

<p class="code">%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)
</p>

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


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