Contents:
How To Do File Upload
UploadForm Object Reference
Examples
Product Installation
File upload is a standard HTML feature and supported by Netscape Navigator since version 2.0 and Internet Explorer version 3.02. Specifically, on your HTML form, you can use an <INPUT> element with attribute TYPE="FILE" for each file you want the user to upload. Also, the <FORM> element must have these attributes ENCTYPE="multipart/form-data" and METHOD="POST". This is how your HTML form should look like:
<form enctype="multipart/form-data" action="formProcessor.asp" method="post"> <!-- you can have other form elements --> File 1: <input type="file" name="file1"> <input type="submit" value="Submit"> </form>
On the server side, however, special processing is required in the ACTION file: formProcessor.asp, and this is why we have made FileUpload/ASP for you. FileUpload/ASP provides the UploadForm object, which you can use in lieu of the standard ASP Request.Form. UploadForm has all the features of Request.Form and the same interface for processing non-FILE type elements on the HTML form. In addition, it has new properties and methods for dealing with FILE elements, which enable you to save the uploaded file content into a file on the server, or to insert it into a database. The following content for the ACTION file formProcessor.asp will save the uploaded file content as a file called tmp.tmp on the server:
<%
set form = server.createObject("bkupload.form")
' use this form object the same way you would Request.Form
' to process other elements on the original HTML form
form("file1").SaveToFile("C:\\tmp.tmp")
response.write("File upload succeeded.")
%>
UploadForm and Request.Form are mutually exclusive, and you should use one or the other
but not both.
The UploadForm object is to be used in place of the Request.Form object in ASP when the HTML form contains File elements. It has the same interface as Request.Form, but it also implements additional features specific to file upload. Unlike Request.Form, however, before it can be used, an UploadForm object has to be created explicitly (this is no different from any other non built-in ASP objects):
Set UploadForm = Server.CreateObject("bkupload.form")
If you use UploadForm, then you cannot use Request.Form any more, and vice versa. From the features point of view, UploadForm supersedes Request.Form.
UploadForm.Count
UploadForm(element).Count
UploadForm(element)
UploadForm(element)[(index)].Content
UploadForm(element)(index)
UploadForm(element)[(index)].IsFile
UploadForm(element)[(index)].ContentType
UploadForm(element)[(index)].SourceFile
UploadForm(element)[(index)].TotalBytes
UploadForm(element)[(index)].SaveToFile(FilePath, MaxLength)
UploadForm(element)[(index)].GetChunk(ChunkSize)
UploadForm.Count returns the number of form elements with unique HTML Name attribute.
When used as a prefix, UploadForm(element) gives the collection of the form elements having the same name element. So UploadForm(element).Count gives the number of elements in this collection. Most often, there's only one element in this collection, but HTML allows you to define more than one element with the same Name attribute.
When no element exists for a given name element, UploadForm(element) returns EMPTY, and an error will be thrown if you try to access any property or method of this element, including the Count property; this is slightly different from the behavior Request.Form(element).Count, which returns 0 if no element exists for the given name.
The index parameter is mandatory when there's only one element for a given element name; otherwise, it can be dropped.
UploadForm(element) returns the value of the element if there's only one element for the given name; if there are multiple elements for the given name, it returns the values of all the elements in a comma separated string. These multiple elements cannot include any File type elements, however.
UploadForm(element)[(index)].Content returns the value of an element. For a regular element, this is a string; for a File type element, this is a SafeArray. UploadForm(element)[(index)].Content can be shortened as UploadForm(element)(index). If there's only one element for the given element name, it's also equivalent to UploadForm(element) above.
UploadForm(element)(index) is equivalent to UploadForm(element)[(index)].Content above.
UploadForm(element)[(index)].IsFile returns true if the element is of File type.
UploadForm(element)[(index)].ContentType returns the element content type as reported by the web browser. For example, it's "image/gif" if the element is a File type element and if the user has uploaded a gif file. (The browser merely deduces this by looking at the file extension.)
UploadForm(element)[(index)].SourceFile applies only to File type elements. It returns the path of the source file on the remote user's machine that's being uploaded.
UploadForm(element)[(index)].TotalBytes applies only to File type elements. It returns the total number of bytes of the file being uploaded.
UploadForm(element)[(index)].SaveToFile(FilePath, MaxLength) applies only to File type elements. It saves the uploaded file content to a local file. FilePath is an absolute file path where the content is to be saved; if you know only the URL-relative file path, you can use the ASP Server.MapPath function to convert it into an absolute path. MaxLength is an optional parameter that allows you to specify the maximum number of bytes you want to save.
UploadForm(element)[(index)].GetChunk(ChunkSize) applies only to File type
elements. It returns the next chunk, of ChunkSize bytes maximum, of the uploaded file content. When end of the uploaded content
is reached, null is returned; the next call to this method will wrap around to the very beginning and returns the first chunk. You might want to
make multiple calls to this method and then append each chunk to a database blob field, instead of using UploadForm(element)[(index)]
(or equivalently UploadForm(element)[(index)].Content) to retrieve the file content
as a single block. This reduces the memory overhead.
This is a minimalist example.
Content of your HTML page:
<form enctype="multipart/form-data" action="upload1.asp" method="post"> File 1: <input type="file" name="file1"><br> <input type="submit" value="Submit"> </form>
The corresponding upload1.asp file:
<%
set form = server.createObject("bkupload.form")
form("file1").SaveToFile("C:\\tmp.tmp")
response.write("File upload succeeded.")
%>
This example expands the previous one to allow you to upload two files.
Content of your HTML page:
<form enctype="multipart/form-data" action="upload2.asp" method="post"> File 1: <input type="file" name="file1"><br> File 2: <input type="file" name="file2"><br> <input type="submit" value="Submit"> </form>
The corresponding upload2.asp file:
<%
set form = server.createObject("bkupload.form")
form("file1").SaveToFile("C:\\tmp1.tmp")
form("file2").SaveToFile("C:\\tmp2.tmp")
response.write("File upload succeeded.")
%>
This example demonstrates the use of the GetChunk method.
The HTML page is similar to that in Example 1 earlier. The form processing ASP file has the following content:
<%
set form = server.createObject("bkupload.form")
chunk = form("file1").GetChunk(1000)
do while not IsNull(chunk)
' TODO: call ADO appendField() to add chunk to database field
chunk = form("file1").GetChunk(1000)
loop
response.write("File content added to database.")
%>
Note: if the uploaded file is expected to be small, you might want to use
simply UploadForm(element)[(index)] to retrieve
the whole file content in one shot.
Copy the bkupload.dll file (or bkupload_TRIAL.dll for the trial version) to a directoy where you keep all your ASP components, or any other directory of your choice, and then run:
regsvr32 bkupload.dll
on a command prompt window. FileUpload/ASP is then ready to be used in your ASP scripts.