ASPCustomUpload - Online Manual

Introduction

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

This is an ASP component for saving files that have been uploaded by HTTP using the Chestysoft csXThumbUpload ActiveX control. It supports uploads of single files and can either save this file or export it as a variant array for storing in a binary database field or exporting to our csImageFile component for further image processing. In ASP the Request.Form collection cannot be used when files are uploaded and so properties are provided for reading form variables.

This cannot be used to save general file uploads but when used with csXThumbUpload it is fully functional. For a general ASP upload component use our csASPUpload component.

Using these Instructions

These instructions are divided into a number of sections covering different types of functions available in ASPCustomUpload. 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.

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, ASPCustomUpload.dll 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. We can recommend 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 here: www.chestysoft.com/dllregsvr/default.asp

The Windows account that uses IIS must have permission to read and execute the DLL. This usually 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 that uses the component an object instance must be created. The syntax in ASP is:

The object name is "Upload", but any variable name could be used.

1.3. The Version Property

The ASPCustomUpload component can only be used to upload files uploaded with csXThumbUpload but a quick test can be made to check that the component is running by calling the Version property.

Version - String, read only. This returns the version information and can be used to confirm that the component is running.

Example:

1.4. Using ASPCustomUpload 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 ASPCustomUpload with 64 Bit Operating Systems

ASPCustomUpload 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 or Exporting the Uploaded File

The uploaded file can be saved to disk on the server using SaveFile. It can be exported as a variant array using FileAsVariant, and this would be used to send an image file to the csImageFile component for processing or if the file was to be stored in a binary database field. Some properties are available to provide information about the file, such as FileSize and Filename.

2.1. Saving to Disk

SaveFile Filename - This saves the uploaded file to the full physical path specified in Filename. The Internet Guest User must have Write permission on the destination directory to save the file and Modify permission to overwrite an existing file.

Example using a hard coded file name:

Use Server.MapPath to convert a virtual path to a physical path.

2.2. Exporting As Binary Data

FileAsVariant - Variant array, read only property. The uploaded file exported as a binary variable.

Example of saving the file to a binary database field called "Image":

Example of exporting the file to the csImageFile component for further processing:

This assumes the instance of csImageFile is called "Image".

2.3. File Properties

The following properties provide information about the uploaded file.

ContentType - String. The MIME type specified during the upload.

Filename - String. The name of the file that was uploaded, complete with extension.

FileExtension - String. The file extension, without the period character.

FilenameNoExtension - String. The file name, with the extension removed.

FileSize - Integer. The size of the uploaded file in bytes. This property can be used to check if a file was uploaded, because it will always be zero when no file is uploaded.

2.4. OverwriteMode

The OverwriteMode property provides a quick way to prevent files with duplicate names from being overwritten.

OverwriteMode - Integer, 0, 1 or 2. This property determines what happens if the SaveFile 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.5. Some Examples

Example 1 - Saving a file with no error checking.

This will save the file into the same directory as the script and it will use the existing file name for the saved file. If a file already exists by that name it will be overwritten. An error will be generated if the user submits the form without attaching a file.

Example 2 - Checking for an upload before saving.

This checks the Filesize property, which will be zero if no file was uploaded. The If..Then..Else statement will save the file if there is a file.

Example 3 - Using a form variable for the saved file name.

In this example a form variable is added to the form for the user to specify the name that will be used when the file is saved.

The script is similar to Example 2 above except the variable name is used for the saved name and the file is saved into a sub directory. The previous examples have saved the files into the same directory as the script but a separate location would often be preferable.

In practice, the file name would rarely be chosen like this and some error checking would be needed to make sure the name was valid. This example shows how to read a form variable and construct a name based on a variable and the existing extension.

The functions for reading form variables are described in the next section. Request.Form cannot be used with file uploads. Request.Querystring can be used as normal.

3. Form Variables

Form variables cannot be read using Requst.Form, so the following properties must be used instead. FormVariable reads the variable given its name. FormVariableCount returns the number of variables in the form, and FormVariableByIndex returns the value given the index of the variable within the form.

FormVariable (VariableName) - String. The value of the variable where VariableName is the string name of the variable.

Example:

This will display the value for a form variable called "User".

FormVariableCount - Integer. The number of form variables in the form. This includes the name of the uploaded file.

FormVariableByIndex (Index) - String. The value of the variable specified by Index. Index represents the number of the variable within the form, where the first has an index of zero and the last has an index of (FormVariableCount - 1).

Example of looping through all the form variables:

4. Troubleshooting

This section covers some of the common causes for errors when using the ASPCustomUpload component.

4.1. Failure to Register the Component

The component must be registered on the server as described in Section 1.1. If the component is not registered it will generate the error:

4.2. Incorrect Class Name

If the class name inside the Server.CreateObject command is incorrect it will generate exactly the same error as when the component is not registered. Take care to spell the class name correctly. See Section 1.2 for more on the class names and object creation.

4.3. Insufficient Permission on the DLL

An ASP script runs under the Internet Guest User account, unless specifically configured otherwise. This account must have Read and Execute permission on the DLL file, ASPCustomUpload.dll. Failure to do this will result in the error:

4.4. Insufficient Permission to Save Files

The Internet Guest User account must have permission to write into the directory where the files are to be saved. Insufficient permissions will result in the following error:

Modify permission is required to overwrite existing files.

4.5. Using Request.Form in the Script

Request.Form commands must not be used in the same script as the ASPCustomUpload component. The exact error generated will depend on where the Request.Form command appears in the script.

Section 3 describes how to read form variables.

5. Alphabetical Index of Commands

Click on one of the links below to go directly to information about that command: