XFileEE Resumable Upload

XFileEE Documentation
You will find the complete XFileEE documentation at FileUpEE/XFile/XFile.chm, or on the SoftArtisans support site.

XFile Enterprise Edition (XFileEE) supports resumable uploading from client to web server. In a resumable upload, if the file transfer fails, the user will be able to resume the upload from the point at which it stopped.

In a resumable upload, XFileEE stores upload data in a temporary directory on the client, before starting the upload. XFileEE's ResumeInfo.CacheRequest property allows you to specify whether XFileEE should cache the whole request - including the files to upload - or just store information about the upload. Caching the whole request guarantees the integrity of the request data when an upload is resumed, but caching large files can use a significant amount of disk space. If you are only going to resume the current upload, it may be better not to cache.

When using ASP on the server, FileUpEE saves information about the upload in a status database. When the upload is resumed, FileUpEE gets the status of the upload - the number of bytes uploaded to the server - from the status database. FileUpEE then sends the upload status to XFileEE, and XFileEE resumes the upload from the point at which it stopped. The upload status database FileUpEEWS.mdb is included in the XFileEE samples directory.

The XFileEE Script

For complete instructions on using XFileEE, see the XFileEE documentation.

XFileEE's ResumeInfo object is used to enable resumable file transfers, and to set several properties that specify how XFileEE should handle a resumable transfer. The ResumeInfo object tells XFileEE that a file transfer is resumable, before the transfer begins. If a resumable transfer fails, the XFileEE's XFResume object is used to get information about the failed request, and to set properties that relate to the resumed transfer request.

To enable resumable uploading from XFileEE:

To load the XFResume object into your page, use:
```
<object classid="clsid:53B29E97-9753-44B4-AE57-D51322B2BD49" id="XFResume" >
</object>
```
- Set a ResumeInfo object through the XFRequest object's ResumeInfo property, for example:
```
Set XFileResumeInfo = SAXFileEE.ResumeInfo
```
- Set ResumeInfo's Resumable property to true to tell XFileEE that the upload is resumable, for example:
```
XFileResumeInfo.Resumable = True
```
- Set ResumeInfo's StatusURL property, for example:
```
XFileResumeInfo.StatusUrl = "http://localhost/xfilesamples/status.asp"
```
Before resuming an upload, XFileEE gets status information about the failed upload - the number of bytes received on the server so far - from FileUpEE on the server. StatusURL specifies the URL of the FileUpEE script from which to get the status information.
Set ResumeInfo's CacheRequest property to tell XFileEE whether to cache the whole request on the client before uploading, or to cache information about the upload only. Caching the whole request before uploading guarantees the integrity of a resumed upload request. To cache the whole request, set CacheRequest to true, for example:
```
XFileResumeInfo.CacheRequest = True
```
To cache only information about the upload, set CacheRequest to false, for example:
```
XFileResumeInfo.CacheRequest = False
```
Set ResumeInfo's TopFolder property to let XFileEE know where to cache the upload data that allows a failed upload to be resumed, for example:
```
XFileResumeInfo.TopFolder = "C:\TopFolder\"
```
If CacheRequest is set to true, the whole file transfer request will be stored in the folder specified by TopFolder. If CacheRequest is set to false, only information about the request will be stored.
If you set CacheRequest to false, and you want to make sure that a failed upload is not resumed if the files to upload were modified since the initial upload request, set ResumeInfo's VerifyChecksums property to true, for example:
```
XFileResumeInfo.VerifyChecksums = True
```
Create a message to display if the upload fails. The message should tell the user that the transfer failed and can be resumed.

Create a "Resume" button that calls XFRequest.Resume to resume a failed upload, for example:


Sub ResumeButton_onClick() 
    MsgBox "Resuming." document.all("ResumeButton").disabled = true 
    
    '--- Call Resume and pass the current JobID to resume 
    '--- the transfer.
    SAXFileEE.Resume     
    SAXFileEE.ResumeInfo.JobId 
    ... 
End Sub

In the sample above, when the upload fails, the script gets information about the failed upload and displays it to the user. The information is retrieved from the request's RequestRecord, which is accessed through the XFResume object:

Set XFResumeRecord = XFResume.GetRequestRecord(SAXFileEE.ResumeInfo.JobID)

Top

The FileUpEE Upload Processing Script

To enable XFileEE to FileUpEE resumable uploading, include the following in your FileUpEE script, before calling FileUpEE's ProcessRequest method:

Set FileUpEE's Resumable(saWebServer) property to true.
(ASP Only) Set FileUpEE's ResumeConnectionString(saWebServer) property to the connection string for the upload status database on the web server.

To demonstrate a resumable upload, the FileUpEE script in the sample above forces a transfer failure if XFileEE sent the header HTTP_X_FAIL with the transfer request. The XFileEE script above will send this header if you select the "Force failure" radio button when submitting the upload request. If the header was sent, FileUpEE's MaxKBytesToCancel is set to 1 kb to force an upload failure:


oFileUpEE.MaxKBytesToCancel(saWebServer) = 999999 

If Request.ServerVariables("HTTP_X_FAIL") = "true" Then 
    If Request.ServerVariables("HTTP_IGNORE_X_FAIL") <> "true" Then 
        oFileUpEE.MaxKBytesToCancel(saWebServer) = 1 
    End If 
End If

Are MaxKBytesToCancel and HTTP_X_FAIL required in a resumable upload?
No. MaxKBytesToCancel and HTTP_X_FAIL are use in this sample script to demonstrate a failed and resumed upload.

Top

The FileUpEE Status Script

When the user clicks the "Resume" button in the XFileEE sample above, the XFileEE's Resume method is called. To resume the upload, XFileEE sends a status request to the FileUpEE status page specified by XFileEE's ResumeInfo.StatusURL property. The status page calls FileUpEE's ReturnStatus method, which sends the number of bytes received on the server back to XFileEE. XFileEE then resumes the upload from the point at which it stopped.

Top

The Upload Status Database (ASP Only)

When a resumable XFileEE to FileUpEE upload fails, FileUpEE saves information about the upload in a status database on the server. When the user clicks XFileEE's "Resume" button, FileUpEE gets the status of the upload - the number of bytes uploaded to the file server - from the status database. FileUpEE's ReturnStatus method returns this information to XFileEE, and XFileEE resumes the upload from the point at which it stopped. The upload status database FileUpEEWS.mdb is included in the FileUpEE samples directory.

There are two ways to set the connection string for an upload status database:

Set the ResumeConnectionString property for the specified upload database (Web server or file server).

OR
Set the web server and file server connection strings in two udl files. On the web server, in WINDOWS\system32\fileupee.udl, save the web server's status database connection string. On the file server, in WINDOWS\system32\fileupee.udl, save the file server's status database connection string.

To store a database connection string in a udl file:
1. Go to C:\WINDOWS\system32.
2. Right click within the system32 directory and select New -> Text Document.
3. Name the file fileupee.udl.
4. Double-click fileupee.udl to open it.
5. Select the Provider tab.
6. Select the appropriate Provider, and click Next. (If you are using the Microsoft Access files included with FileUpEE, select Microsoft Jet 4.0 OLE DB Provider).
7. Configure the database provider. (If you are using the Microsoft Access files included with FileUpEE, browse to FileUpEEWS.mdb if you are at the web server, or FileUpEEFS.mdb if you are at the file server.)
8. Click Test Connection.

Top