csASPUpload Version 1.3 - Online Manual

Introduction

These instructions are also available in pdf format. We recommend using the PDF version if a printable manual is required.

This component is used to save files that have been attached to HTML forms using the <input type="file"...> tag. It can be used to save the file or files to disk on the server or it can be used to save to a binary field in a database. The form attributes "method=post" and "enctype=multipart/form-data" must be used.

Any number of files can be attached and form variables can be passed as usual. However, the Request.Form collection cannot be used and alternative properties for reading form variables are provided with this component.

The ActiveX file csASPUpload.dll should be registered on the server using REGSVR32.EXE. Regsvr32 is usually to be found in the Windows System folder, and it runs at the command prompt using the syntax:

regsvr32 dllname

where dllname is the path and name of the dll to register. Chestysoft has a free utility that performs this function through a Windows interface.

For more information on this, visit the Chestysoft web site, or follow: www.chestysoft.com/dllregsvr/default.asp

Object Creation

The code:

creates an instance of the object called "Upload".

In the trial version, use:

Visit the Chestysoft web site for details of how to buy the full version - www.chestysoft.com

After creating the object the component properties are set and can be read and any uploaded files saved.

Form Variable Properties

The form variables cannot be read using the Request.Form collection, so properties are included specifically to access the form variables. Do not use any Request.Form commands on the same ASP page as the csASPUpload component as an error will be generated.

VarCount - the number of variables received.

Value(VariableName) - the value of a named variable, VariableName

Example:

This displays the value of the form variable "UserName".

VarByIndex(index) - the variables are stored in a zero based array and can be retrieved using the index.

Example:

This returns the value of the first variable.

VarName(index) - returns the name of the variable given its index.

Example:

This returns the name of the first variable.

DecodeUTF8(UTF8String) - returns a Unicode string by decoding the UTF-8 encoded string, UTF8String.

Example:

If UTF-8 encoding is used to submit the form, the above example will convert the form variable back to Unicode characters.

File Properties

File properties are also stored as zero based arrays.

FileQty - Returns the number of files received. This property is important as a check that files have been received, and for looping when multiple files are uploaded.

Example:

FileName(index) - the name of the file complete with extension.

LocalName(index) - the full path complete with name and extension, as the file was stored on the client computer.

Extension(index) - the file extension without the period character.

NameOnly(index) - the file name without the extension.

NewName(index) - if the file is renamed during saving to prevent overwriting, this property is set to the new file name. See also the section on OverwriteMode.

ContentType(index) - the content encoding type e.g. "image/gif"

FileSize(index) - the size of the file in bytes.

Example:

This would display the size of the first file in the array.

FileData - the file as binary data. This is used when saving to a database. It could also be used with the Response.BinaryWrite method to stream the file back to the browser.

Example:

This line would write the first file in the array to the database field "Image", assuming a recordset called "RSet" had been opened. In MS Access, the data type for the field would be "OLE Object".

Version - The version of the csASPUpload.dll file.

Note that when the form allows only one file to be uploaded, the index will always be zero. If the form is submitted with no file attached, i.e. the input field is blank no file will be added to the FileQty total. Use FileQty to loop through arrays and to prevent index errors. Use FileSize to check that a file actually contains data.

The FileSave Method

The syntax is: FileSave filename , index

Example:

This saves the first file in the array using the path and name stated. Note that the index is after the comma and no brackets are used.

Note: For any ASP script to save a file on the server, the Internet Guest User Account must have write permissions for that particular directory.

Overwrite Mode

The property OverwriteMode has the value 0, 1 or 2 and it determines what happens if the FileSave method attempts to write to a file that already exists. The default value is 0.

OverwriteMode = 0 - Any existing file will be overwritten.

OverwriteMode = 1 - The new file will not be saved if an existing file has the same name.

OverwriteMode = 2 - If the new file name matches an existing name the characters "~x" will be added at the end where "x" is the smallest number needed to make the name unique.

When an OverwriteMode of 2 is used, the file property NewName will be set to the name of the file that was actually saved.

Example:

This will save the uploaded file as "newfile.gif", if that name is not already used. If a file with that name exists, it will save it as "newfile~1.gif" (or newfile~2.gif ... etc.) The name actually used will be written out in the Response.Write statement.

If an alternative character to the '~' is needed this can be assigned to the property OverwriteChr. This might be necessary on Windows 2003 or if URLScan is used because URLs containing this character may be blocked from downloading.

Simple Examples of Saving Files

Here are some simple examples of using the FileSave method to save files on the server. In each case the files are saved in the same directory as the script. Replace Upload.CurrentDir with the directory path to save somewhere else. Each example uses the FileQty property to check for at least one file before proceeding. This prevents array index errors.

Example 1 - Single file

Example 2 - Single file where uploads bigger than 1 MB are rejected.

Example 3 - Multiple uploads using OverwriteMode to rename duplicates

Matching Multiple Files With the HTML Tag

New in version 1.3 is a property that allows the uploaded file to be matched with the tag name from the HTML form. This can be used when multiple files are uploaded if the files need to be treated separately, unlike in Example 3 above where they are all saved together. The read only property TagNameIndex returns the index of the file.

TagNameIndex (TagName) - Returns an integer which is the index needed to access the file and its details. TagName is the string value of the tag name and it is not case sensitive. If no file has been uploaded using that tag name the index will be -1.

This is where the tag name is defined in the form:

The code needed to save the second file, if present, might look like this:

Path is the path to the directory. This code checks that the second file has been attached and then finds the index. It uses this index to access the file name and save the file.

Obsolete Properties and Methods

Before version 1.2 there was a property called "MaxKB" and a method called "Read". MaxKB was used to reject uploads bigger than a specified size. This has been removed. Use Request.TotalBytes to check the upload size. Read has also been removed. Calling either of these will not produce an error.

File Utilities

There are a number of file utility functions included for convenience. They are not intended to be a comprehensive set, because asp has the built in File Access component to cover most file utilities. These are the functions most likely to be useful while processing file uploads.

FileExists(FileName) - Returns a Boolean value. FileName is the physical path and file name of the file in question.

CurrentDir - Returns the physical path of the directory containing the script. It is complete with the trailing backslash character.

ParentDir(Directory) - Directory is a string value and must be a full physical directory path. The return value is the parent directory.

Example:

This would display the parent directory to the one containing the current script.

Delete(FileName) - This deletes the file FileName. Note that it is permanently deleted, NOT placed in the Recycle Bin.

Copy OldName, NewName - This copies the file OldName to the location and name given by NewName. Again, full paths are required.

Rename OldName, NewName - This renames the file OldName to NewName. Full paths are required, and so renaming to a different directory is the equivalent of moving the file.

AppendToFile FileName, NewLine - This appends the string NewLine to the text file FileName. If the text file does not exist, it will be created if possible. The full server path is required.

Example:

This will append the line "Hello" at the end of a text file called test.txt which is in the same directory as the current script. If the file does not exist it will create it.

AppendToFile is the only command in this component for manipulating text files. It is useful for maintaining a simple log or to assist with testing. There is a full set of commands for dealing with text files in the built in File Access component.

All the file handling routines require that the Internet Guest Account has the appropriate permissions on the server, otherwise errors will result.

Code Examples

There are some downloadable examples available on the Chestysoft web site, including how to save files into a directory, saving to a database, how to preview an image in Javascript and how to resize an image using csImageFile. Follow this link for more details:

http://www.chestysoft.com/upload/default.asp

Using csASPUpload with Windows 2003

Windows 2003 (IIS 6) contains a property that limits the amount of data that can be received using a POST operation, and this has a relatively low default value. This property can be changed by editing the metabase.xml file and it is called AspMaxRequestEntityAllowed. If a file is uploaded that is larger than specified by this property a DNS error will result.

Revision History

The current version of csASPUpload is 1.3

New in Version 1.1:

File utilities included for copying, renaming and deleting files and for obtaining the physical path on the server.
OverwriteMode introduced.

New in Version 1.2:

Maximum file size removed.
MaxKB property and Read method obsolete.
User friendly error messages added for array index errors.

New in Version 1.3:

TagNameIndex property added.

Other Products From Chestysoft

ASP Components

csImageFile - Resize and edit JPG, BMP, GIF, PNG, PCX, PSD, TIF and WBMP images.

csDrawGraph - Draw pie charts, bar charts and line graphs from an asp script.

csASPGif - Create and edit animated GIFs.

csFileDownload - Control file downloads from an asp script.

csASPZipFile - Create zip files and control binary file downloads.

csIniFile - Use Windows style inifiles in your asp applications.

ActiveX Controls

csXImage - ActiveX control to display, edit and scan JPG, PNG, BMP, PCX, PSD, TIF and WBMP images.

csXGraph - ActiveX control to display pie charts, bar charts and line graphs.

csXPostUpload - A control for uploading the contents of a folder to a server using HTTP.

csXMultiUpload - Select and upload multiple files and post to a server using HTTP.

ASP.NET Components

csASPNetGraph - .NET component for drawing pie charts, bar charts and line graphs.

csNetUpload - ASP.NET component for saving HTTP uploads.

csNetDownload - ASP.NET class to control file downloads.

Web Hosting

We can offer ASP enabled web hosting with our components installed. Click for more details.