$Web Proc Receive or $Web Proc Recv
<section begin="desc" />Receive uploaded file into procedure<section end="desc" />
$Web_Proc_Receive receives file upload data into a procedure.
Note: $Web_Proc_Recv is a synonym for $Web_Proc_Receive.
Syntax
<section begin="syntax" /> %RC = $WEB_PROC_[RECEIVE | RECV]( filename, procname, - fieldname, occurrence, - p_flag ) <section end="syntax" />
$Web_Proc_Receive is a callable $function (see Calling Sirius Mods $functions).
$Web_Proc_Receive takes five arguments and returns a status code.
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: 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:
|
| Code | Meaning |
|---|---|
| 1 | Procedure successfully received. |
| 0 | Form field not found. |
| -1 | Not a web thread |
$WEB_PROC_RECEIVE return codes
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.