$Web List Receive or $Web List Recv: Difference between revisions
Jump to navigation
Jump to search
m (→Syntax) |
m (→Syntax) |
||
| (23 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
{{DISPLAYTITLE:$Web_List_Receive or $Web_List_Recv}} | {{DISPLAYTITLE:$Web_List_Receive or $Web_List_Recv}} | ||
<span class="pageSubtitle" | <span class="pageSubtitle">Receive uploaded file into $list</span> | ||
<var>$Web_List_Receive</var> receives file upload data into a [[$lists|$list]]. <var>$Web_List_Recv</var> is a synonym for <var>$Web_List_Receive</var>. $list's are special '''Sirius Software''' data structures that act much like arrays that are stored in CCATEMP. . | |||
<var>$Web_List_Receive</var> is a [[Calling Sirius Mods $functions|callable]] $function. | |||
<var>$Web_List_Receive</var> takes 4 arguments and returns a status code. | |||
==Syntax== | ==Syntax== | ||
<p class="syntax">< | <p class="syntax"><span class="term">%rc</span> = $WEB_LIST_[RECEIVE | RECV]( <span class="term">listid, fieldname, occurrence, p_flag</span> ) | ||
</p> | |||
< | |||
===Syntax terms=== | |||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%rc</th> | <tr><th>%rc</th> | ||
| Line 28: | Line 27: | ||
<tr><th>listid</th> | <tr><th>listid</th> | ||
<td>The identifier of the $list to receive the uploaded data. This identifier is probably the output from a $ListNew call. This parameter is required. If the $list is non-empty, the uploaded data will be added to the end of the $list.</td></tr> | <td>The identifier of the $list to receive the uploaded data. This identifier is probably the output from a $ListNew call. This parameter is required. If the $list is non-empty, the uploaded data will be added to the end of the $list.</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> | ||
<tr><th>occurrence</th> | <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> | <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> | <tr><th>p_flag</th> | ||
<td>Processing indicators for how the server should handle the $list. This parameter is optional. Valid values are: | <td>Processing indicators for how the server should handle the $list. This parameter is optional. Valid values are: | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>BINARY</th> | <tr><th><var>BINARY</var></th> | ||
<td> | <td><var class="product">Janus Web Server</var> performs no ASCII to EBCDIC translation on the contents and converts the data to the special <var class="product">Janus Web Server</var> format binary $list.</td></tr> | ||
<tr><th>BASE64</th> | |||
<td> | <tr><th><var>BASE64</var></th> | ||
<tr><th>TEXT</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 <var class="product">Janus Web Server</var> format base64 encoded $list.</td></tr> | ||
<td> | |||
<tr><th><var>TEXT</var></th> | |||
<td><var class="product">Janus Web Server</var> translates the data from ASCII to EBCDIC, separating the text into list items at any point where an ASCII carriage return (X'0D') or carriage return and line feed (X'0A') are found. | |||
</td></tr> | </td></tr> | ||
</table> | </table> | ||
| Line 47: | Line 51: | ||
==Usage notes== | ==Usage notes== | ||
<ul> | <ul> | ||
<li>$Web_List_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 <var>$Web_Done</var> is sent to end the request. | <li>$Web_List_Receive 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>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. | <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 loaded into a $list, then stored into a record with the IP address of the browser, the current date and time, and the name of the uploaded file. | In the following example, a form-based file upload is loaded into a $list, then stored into a record with the IP address of the browser, the current date and time, and the name of the uploaded file. | ||
<p class="code"> %IPADDR = $Web_IPAddr | <p class="code">%IPADDR = $Web_IPAddr | ||
%TIME = $WEB_DATENS | |||
%FILENAME = $Web_Form_Parm('UPFILE') | |||
%LIST = $ListNew | |||
%RC = $WEB_LIST_RECV(%LIST, , , 'TEXT') | |||
IN FILE UPLOAD STORE RECORD | |||
IPADDR = %IPADDR | |||
TIME = %TIME | |||
FILENAME = %FILENAME | |||
END STORE | |||
%CURREC + $CURREC | |||
IN FILE UPLOAD FOR RECORD NUMBER %CURREC | |||
FOR %I FROM 1 TO $ListCnt(%LIST) | |||
%LINE = $ListInf(%LIST, %I) | |||
ADD LINE = %LINE | |||
END FOR | |||
END FOR | |||
</p> | </p> | ||
Note that even though the fieldname was specified on the $Web_Form_Parm call (because there were other non-file input fields), it was not specified on the $ | Note that even though the fieldname 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_List_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, $ | <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_List_Recv</var> will always return a 1 with these browsers if the indicated field appeared on the form being posted. | ||
To distinguish the case where a user selected no file from the case where the user selected an empty file, 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 no data was added to the target $list, it probably means that the user uploaded an empty file. | To distinguish the case where a user selected no file from the case where the user selected an empty file, 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 no data was added to the target $list, 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 $ | 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_List_Recv</var> would return a 0, but a <var>$Web_Form_Parm</var> for the "type=file" field would still return a null. | ||
<li>See also <var>[[$Web_Proc_Receive]]</var>. | <li>See also <var>[[$Web_Proc_Receive]]</var>. | ||
</ul> | </ul> | ||
Latest revision as of 22:18, 5 June 2013
Receive uploaded file into $list
$Web_List_Receive receives file upload data into a $list. $Web_List_Recv is a synonym for $Web_List_Receive. $list's are special Sirius Software data structures that act much like arrays that are stored in CCATEMP. .
$Web_List_Receive is a callable $function.
$Web_List_Receive takes 4 arguments and returns a status code.
Syntax
%rc = $WEB_LIST_[RECEIVE | RECV]( listid, fieldname, occurrence, p_flag )
Syntax terms
| %rc | A numeric variable to contain a return code. The possible code values are:
| ||||||
|---|---|---|---|---|---|---|---|
| listid | The identifier of the $list to receive the uploaded data. This identifier is probably the output from a $ListNew call. This parameter is required. If the $list is non-empty, the uploaded data will be added to the end of the $list. | ||||||
| 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 $list. This parameter is optional. Valid values are:
|
Usage notes
- $Web_List_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.
- 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 loaded into a $list, then stored into a record with the IP address of the browser, the current date and time, and the name of the uploaded file.
%IPADDR = $Web_IPAddr %TIME = $WEB_DATENS %FILENAME = $Web_Form_Parm('UPFILE') %LIST = $ListNew %RC = $WEB_LIST_RECV(%LIST, , , 'TEXT') IN FILE UPLOAD STORE RECORD IPADDR = %IPADDR TIME = %TIME FILENAME = %FILENAME END STORE %CURREC + $CURREC IN FILE UPLOAD FOR RECORD NUMBER %CURREC FOR %I FROM 1 TO $ListCnt(%LIST) %LINE = $ListInf(%LIST, %I) ADD LINE = %LINE END FOR END FOR
Note that even though the fieldname was specified on the $Web_Form_Parm call (because there were other non-file input fields), it was not specified on the $Web_List_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_List_Recv will always return a 1 with these browsers if the indicated field appeared on the form being posted. To distinguish the case where a user selected no file from the case where the user selected an empty file, 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 no data was added to the target $list, 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_List_Recv would return a 0, but a $Web_Form_Parm for the "type=file" field would still return a null.
- See also $Web_Proc_Receive.