How to Use the Dundas Upload Control

How to Use the Dundas Upload Control

Overview | Properties | Methods

To use the Dundas Upload control the client must be using a browser which is capable of html form-based uploading (as per RFC 1867). Netscape 3.0+ and Microsoft's Internet Explorer 4.0+ both support this.

The POST html form MUST use an "EncType" of: "Multipart/Form-Data" (i.e. <form method="POST" name="SomeName" EncType="Multipart/Form-Data">.

Click here for list of steps to be followed when implementing the Upload control.

Files to be uploaded are determined through the use of file input boxes in the POST form.

The Form and Files collections of the control are especially important. The Form collection is used to access form data such as input elements, select elements, etc... . This collection also allows you to retrieve the values of multiple-entry form items (e.g. multi-select listbox). The Files collection (consisting of UploadedFile objects) is used to access and manipulate uploaded files.

To determine the file input box which corresponds to a particular uploaded file use the TagName property of the UploadedFile object (the TagName property is the same as the Name attribute of the corresponding file input box). You can iterate through all uploaded files with either a standard For loop or a For Each loop. To determine the file type that was uploaded use VBScript's InStr method with the ContentType property of an UploadedFile object. Note that the NextFile object also exposes the ContentType and TagName properties. Remember that calling the Save or SaveToMemory methods of the NextFile object will also update the Files collection.

To retrieve the values of form elements other than file input boxes use the control's Form collection (you can not retrieve form elements with the ASP Request.Form object when the encoding type of the form is "Multipart/Form-Data"). To retrieve particular form values use the name of the form element (e.g. strVariable = objUpload.Form("txtSomeTextbox")). You can also retrieve items by their numerical index. For example, to retrieve the value of the first form element you can use: strVariable = objUpload.Form(0).

Form data is either retrieved all at once or incrementally. To retrieve all of the form data with one method call you must use either the control's Save or SaveToMemory methods. The Save method saves all uploaded files to disk locally, while SaveToMemory saves uploaded files to memory. Irregardless of which method is used it is VERY IMPORTANT to know that either method populates the Files collection with ALL uploaded files as well as the control's Form collection with ALL form data.

You can retrieve form data incrementally by repeatedly calling the GetNextFile method (as opposed to using either Save or SaveToMemory). GetNextFile returns NextFile objects, with each NextFile object containing the header information for one uploaded file. The first NextFile object will correspond to the first file uploaded by the user, the next NextFile object (obtained by calling GetNextFile again) will contain the header information for the next populated file input box in the POST form, etc... . It is IMPORTANT to realize that each call to the GetNextFile method will populate the control's Form collection with all form data which appears BEFORE the form's populated file input box which corresponds to the current NextFile object. The NextFile object (like the control itself) exposes both Save and SaveToMemory methods. Use either of these methods while looping through all NextFile objects to optionally save uploaded files in their entirety. You can use whatever deciding criteria you want, but the TagName and ContentType properties in particular can be very useful when deciding whether or not to save files uploaded by the user (see the paragraph below). To skip uploading a file just call the GetNextFile method again without first calling the object's Save or SaveToMemory methods. Note that if you choose to retrieve the file in its entirety by calling either Save or SaveToMemory then the Files collection of the control will be populated with the uploaded file in question.

If a form element was not populated by the user then there will be no corresponding FormItem object in the control's Form collection (e.g. if you loop through the Form collection with a For ... Each loop there will be no FormItem object for the form elements left empty by the user). If you retrieve the value of a particular form element which was left empty by the user the return will be "Empty". You can test to see if the user left a form element blank, or empty, by using VBScript's IsEmpty method.

To find out how to implement a progress bar (via the ProgressBar and StateServer Components) click here.

You can disable or preset certain features of the Upload control through the use of registry keys. Click here for more information.

NOTE: to utilize named constants in your ASP code use a server-side include and include the UploadControl.inc file (distributed with the application).

Most methods will throw an exception if an error occurs so make sure that you have enabled inline error trapping by using an On Error Resume Next statement. Examine VBScript's Err object after a function call to check for the success/failure of the operation.

The Dundas Upload Control 2.0 provides many methods for performing file operations, such as FileCopy, FileMove, etc... .

You can also temorarily assume a valid Windows account other than the default web account by calling the ImpersonateUser method. You might want to use this method if the default web account does not have the rights to perform a particular operation. Once you have finished using the impersonated account you can revert back to the default account by calling the ImpersonationTerminate method. Other methods of the control which are related to rights/permissions are: AllowAccess, DenyAccess, RevokeAccess and SetOwner.

Perform the following steps when utilizing the Upload control:

1. Make sure that the form which is POSTING the data is using an EncType of "Multipart/Form-Data". You will also need to use file input elements (<input type="file">) in this form so the user can browse for files to be uploaded.

2. Enable inline error trapping in the page being POSTED to with an "On Error Resume Next" statement. Most methods of the control will throw an exception if unsuccessful, so you can perform error trapping using VBScript's Err object.

3. Create an instance of the Upload control in the page which the form is POSTING to. To do this use the Server.CreateObject method with a ProgID of either "Dundas.Upload" or "Dundas.Upload.2".

4. You can either retrieve ALL form data (uploaded files as well as form input elements) at once by using the Save or SaveToMemory methods of the control. Alternatively you can retrieve form data incrementally by using the GetNextFile method. Please note that retrieving form data incrementally will result in the Form and Files collections also being populated incrementally.

5. Retrieve any form element values via the control's Form collection. Note that empty form elements WILL NOT be inserted into the Form collection, and attempting to retrieve the value of a form element which was left empty by the user will result in an exception being thrown (which you can trap for).

6. Manipulate files saved to either disk or memory via the Files collection. This collection is populated with either one Save or SaveToMermory call of the control, unlike the Save and SaveToMemory methods of the NextFile object (NextFile objects are returned by GetNextFile calls) which populates the Files collection one file at a time.

7. Set the Upload object to nothing.

See Also: Overview (Dundas Upload Control 2.0) | Tutorial 1: Uploading Multiple Files and Using the Form and Files Collections | Tutorial 2: Retrieving Form Data Incrementally Using the GetNextFile Method | Tutorial 3: ADO Support and Saving a File as a BLOB | Tutorial 4: Implementing a Progress Bar