csASPUpload Version 2.0 - Online Manual

Introduction

This ASP component is used to save files that have been attached to HTML forms using the <input type="file"...> tag. The files can be saved to disk on the server or extracted in a binary form for saving in a database or for passing to an image manipulation component.

Multiple files can be saved and functionality is provided to read the form variables, which cannot be read using the usual ASP request object following a file upload. Some file utility functions have been provided.

As of version 2.0 some additional HTTP methods have been included. These allow files to be transferred between servers, both by uploading and downloading. Form variables can be used and there is support for Windows Authentication.

A free, fully functional trial version of csASPUpload is available. This trial version has a built in expiry date that causes the main functions to stop working after that time. This is the only difference in functionality between the trial and full versions. This means that you can fully test if this component is suitable for your application before considering whether to license the full version.

Using these Instructions

These instructions are divided into a number of sections with the relevant methods and properties described in each. There are quick links to some sections below. A full Table of Contents is available on the next page and an index listing all commands in alphabetical order is included at the back for easy reference. The PDF version also has bookmarks for direct navigation to each heading.

The component contains two classes, one for saving uploaded files (as well as the utility functions) and another for transferring files by HTTP. These classes have separate sections in the instructions and a separate alphabetical command list at the end.

Click on one of the links below to go directly to the section of interest:

Table of Contents

1. Registering the Component and Getting Started

1.1. Registration and Server Permissions

Before the component can be used the DLL file, csASPUpload.dll (or csASPUploadTrial.dll for the trial version) must be registered on the server. This can be done using the command line tool REGSVR32.EXE which should be in the Windows System folder. The syntax is:

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 which can be easier although the result is identical. This tool can be downloaded from the Chestysoft web site: www.chestysoft.com/dllregsvr/default.asp

Both classes will be registered at once. If you are upgrading from an earlier version of csASPUpload which only contained the Process class it is important to unregister the old component first, and IIS must be stopped before unregistration can take place.

The application that uses the component must have permission to read and execute the DLL. In a web application like ASP this means giving the Internet Guest User account Read and Execute permission on the file. This account must also have the appropriate permissions for file handling. Read permission is required to read/open an image from disk. Write permission is required to create a new file or edit an existing file and Modify is required to delete an existing file. These permissions can be set in Windows Explorer and applied to either a folder or individual files.

Before the component can be used the DLL file, csFTPQuick.dll (or csFTPQuickTrial.dll for the trial version) must be registered on the server. This can be done using the command line tool REGSVR32.EXE which should be in the Windows System folder. The syntax is:

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 which can be easier although the result is identical. This tool can be downloaded from the Chestysoft web site: www.chestysoft.com/dllregsvr/default.asp

The application that uses the component must have permission to read and execute the DLL. In a web application like ASP this means giving the Internet Guest User account Read and Execute permission on the file. This account must also have the appropriate permissions for any file reading, writing or deleting that the component is to perform.

1.2. Object Creation

In any script or programme that uses the component an object instance must be created. There are two classes inside the component, Process is used for saving uploaded files and for the file utility functions. HTTP is used for the file transfer functionality. The syntax in ASP to create both classes is as follows.

For the full version:

For the trial version:

The object names are "Upload" and "Http", but any variable names could be used. It is not necessary to create a class instance unless that class is used in the script.

1.3. The Trial Version

The trial version of the component is supplied as a separate DLL called csASPUploadTrial.dll This trial version is fully functional but it has an expiry date, after which time it will stop working.

The expiry date can be found by reading the Version property of the Process class.

Version - String, read only. This returns the version information and for the trial, the expiry date.

Example:

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

1.4. Using csASPUpload with Windows 2003 and Later

Windows 2003 (IIS 6) introduced 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 an error will result.

In IIS 7, if Friendly Names are used, it will be called Maximum Entity Requesting Body Limit.

1.5. Using csASPUpload with 64 Bit Operating Systems

csASPUpload is a 32 bit DLL but it can be used on 64 bit systems if it is added to a COM+ Application. An online description of configuring Component Services is available here:

http://www.chestysoft.com/component-services.asp.

On Windows 2008 it is important to "Allow intrinsic IIS properties" in the COM+ component properties.

2. Saving Uploaded Files and Reading Form Variables

All the methods and properties described in this section use the Process class, which is instantiated as described in section 1.2 above, using the class name "csASPUpload.Process" (or "csASPUploadTrial.Process" for the trial version of the component). The Process class can only be created from an ASP script.

2.1. POSTing a File in an HTML Form

The HTML code used to attach a file for upload is shown below. It is important to set the enctype attribute as shown. Only a single file can be selected with the <input type="file"> tag and to upload multiple files, multiple tags must be used. Form variables can be included in the usual way.

In this example the script "filesave.asp" will receive the file and will be the script that uses the csASPUpload component.

2.2. Form Variable Properties and Methods

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 - Integer, read only. The number of variables received.

Value(VariableName) - String, read only. The value of a named variable, VariableName.

Example:

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

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

Example:

This displays the value of the first variable.

VarName(index) - String, read only. Returns the name of the variable given its index.

Example:

This displays the name of the first variable.

Where variable names are duplicated the value returned by Value or VarByIndex will be a delimited string. By default this will be comma delimited but a different character or string can be specified in the VarDelimiter property.

VarDelimiter - String. The string used to delimit duplicated variables.

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.

2.3. File Properties

File properties are also stored as zero based arrays. When a single file has been uploaded the index will always be zero but it must be included for correct syntax.

FileQty - Integer, read only. 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) - String, read only. The name of the file complete with extension.

LocalName(index) - String, read only. The full path, complete with name and extension, of the file as stored on the client computer.

Extension(index) - String, read only. The file extension without the period character.

NameOnly(index) - String, read only. The file name without the extension.

NewName(index) - String, read only. 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) - String, read only. The content encoding type e.g. "image/gif".

FileSize(index) - Integer, read only. The size of the file in bytes.

Example:

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

FileData(index) - Variant, read only. The file as binary data. This is used when saving to a database or passing the file straight to our csImageFile component. 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".

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.

2.4. The FileSave Method

The uploaded file is saved to disk on the server using the FileSave method.

FileSave Filename, index - Filename is the physical path and file name to be saved. Index is the file to be saved where zero is the first or only file to have been uploaded.

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 required in VBScript.

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

2.5. Overwrite Mode

OverwriteMode - Integer, 0, 1 or 2. This property 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.

OverwriteChr - String. The character or characters added before the number when a file is renamed using OverwriteMode. (Default = "~")

2.6. 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. Server.MapPath could also be used to find the physical path on the server.

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.

2.7. Matching Multiple Files With the HTML Tag

If multiple files are uploaded and the file must be matched with the tag on the HTML form, use the TagNameIndex property to find the index of the file.

TagNameIndex(TagName) - String, read only. This returns an integer which is the index needed to access the file and its details. TagName is the string value of the name attribute of the file tag 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. It is dangerous to assume that the second file will always have an index of 1, because if no file is selected in the first tag, the file in the second tag will have an index of zero.

2.8. 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 and how to resize an image using csImageFile. Follow this link for more details:

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

3. File Utilities

There are a number of file utility functions included in the Process class. They are not intended to be a comprehensive set, because ASP has the built in File System Object 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. The physical path is required.

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

Rename OldName, NewName - This renames the file OldName to NewName. Physical paths are required. 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 System Object.

CreateDir Directory - This creates a directory, where Directory is the physical path on the server, with or without the trailing backslash and including the drive letter. It has a boolean return value that is true if the directory was created or if it already exists.

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

4. File Transfer Between Servers

All the methods and properties described in this section use the HTTP class, which is instantiated as described in section 1.2 above, using the class name "csASPUpload.HTTP" (or "csASPUploadTrial.HTTP" for the trial version of the component). The HTTP class is not restricted to ASP and can be called from a wide range of COM enabled environments. It uses the Wininet.dll so Microsoft Internet Explorer must be installed on any machine where it is to be used.

Files can be uploaded (sent from the server running the component to a remote server) and downloaded (copied from a remote server to the server running the component) using HTTP. Uploaded files can be sent from disk or a binary variable. Downloaded files can be saved to disk or to a binary variable. Form variables can be sent with the upload and with the request for a file download. A username and password can be sent of the remote server requires authentication.

We have another component, csFTPQuick, that has FTP functionality for transferring files to and from a remote FTP server.

4.1. HTTP Properties

These properties apply to uploading or downloading a file. Some are set before an HTTP operation and two provide status information following an upload.

Username - String. The username to be sent with a request when the remote server requires authentication.

Password - String. The password to be sent with a request when the remote server requires authentication.

UserAgent - String. The User Agent header can be set to identify the caller of the request to the remote server. (Default = empty string)

TagName - String. Used with an upload, this is the equivalent of the name attribute of the file tag when a file is uploaded through the browser. (Default = empty string)

RequestMethod - String. Used with a download, this can be set to either "POST" or "GET" to specify the request method. It is not case sensitive and if an invalid value is given it will use the default. When the method is "POST" the form variables added with AddFormVar will be included. If the value is "GET" the form variables are not included and are not automatically added to the URL. (Default = "GET")

HTTPTimeOut - Integer. Timeout for the upload and download requests, in seconds. Zero is unlimited. (Default = 30)

ReturnFile - String, read only. This is the text of the web page returned by the remote server following an upload post. It can be used with Response.Write to display the complete page which is useful during debugging.

ReturnCode - Integer, read only. This is the HTTP code returned by the remote server following an upload post.

4.2. HTTP Methods

There are two methods for posting uploads and two methods for requesting downloads. In each case, one method works with files on disk and other with files stored in memory as a variant binary variable.

UploadFile URL, LocalFile - This uploads the file at LocalFile to the address at URL. URL must be the full URL starting with "http://" or "https://" and it must be a server side script capable of saving a file upload. It has a Boolean return value which returns true when a 200 message is received from the server. An exception will be raised if the URL cannot be reached.

UploadData URL, FileData, Name - This uploads a file stored in the variant array variable FileData to the remote address at URL. Name is the file name and this is the equivalent of the file name field when uploading through a browser. The method has a Boolean return value which returns true when a 200 message is received from the server. An exception will be raised if the URL cannot be reached.

DownloadFile URL, LocalFile - This downloads a file from the remote URL and saves it to LocalFile. URL must be a full URL starting with "http://" or "https://". LocalFile is the physical path and file name on the same server as the script where the file will be saved. This method has no return value and raises an exception if it fails.

DownloadData URL - Variant return value. This downloads a file from the remote URL and returns it as a variant array. This can be used for further processing.

Example:

This will download the logo from our web site and display it in the browser.

Form variables can be sent with uploads and with requests for downloads. Form variables are added by calling the AddFormVar method before the upload or download. In the case of downloads, the RequestMethod property must be set to "POST".

AddFormVar Name, Value - Name and Value are both strings and are the name and value of the form variable. Multiple variables are added by making multiple calls to AddFormVar.

ClearFormVars - This clears the list of form variables that have been added using AddFormVar.

Sometimes plain text is returned from a remote page and this can be difficult to extract in ASP when it is in a variant form. The VariantToString method can be used for a conversion. This may be used with the DownloadData method when a form has been posted and a text based result is returned.

VariantToString InVar - String return value. This will take a variant input parameter, such as the value returned by DownloadData, and return a string.

Example:

5. Revision History

The current version of csASPUpload is 2.0.

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 made obsolete.
User friendly error messages added for array index errors.

New in Version 1.3

TagNameIndex property added.

New in Version 2.0

HTTP class added.

6. Other Products From Chestysoft

ActiveX Controls

csXImage - An ActiveX control to display, edit and scan images.

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

csXThumbUpload - Upload multiple files by HTTP or FTP with previews and image edits.

csXPostUpload - A control to upload batches of files from a client to a server using an HTTP post.

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

ASP Components

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

csASPUpload - Process file uploads through a browser.

csDrawGraph - Draw pie charts, bar charts and line graphs in ASP.

csIniFile - Read and Edit Windows style inifiles.

csASPZipFile - Create zip files and control binary file downloads.

csFileDownload - Control file downloads with an ASP script.

csASPGif - Create and edit animated GIFs.

csFTPQuick - Create zip files and control binary file downloads.

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.

7. Alphabetical List of Commands - Process Class

These commands are used for saving uploaded files in ASP. Click on one of the links to go directly to information about that command:

8. Alphabetical List of Commands - HTTP Class

These commands are used for transferring files by HTTP. Click on one of the links to go directly to information about that command: