$Web_List_Receive or $Web_List_Recv

<section begin="desc" />Receive uploaded file into $list<section end="desc" />

$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. For more information about $list's see the Sirius Functions Reference Manual.

Syntax

<section begin="syntax" /> %rc = $WEB_LIST_[RECEIVE | RECV]( listid, fieldname, - occurrence, p_flag ) <section end="syntax" />

$Web_List_Receive is a callable $function (see Calling Sirius Mods $functions).

$Web_List_Receive takes 4 arguments and returns a status code.

%rc	A numeric variable to contain a return code. The possible code values are: 1 $list successfully received. 0 Form field not found. -1 Not a web thread
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: 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 $list. 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 $list. TEXT Janus Web Server 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.

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.