14.3.2- The Record Object

by NT Community Manager.
Last Updated by Sarah Welna.

Public Categorized as 14. Advanced Data Handling Techniques.

Not tagged.

The Record Object

So, we can use the Record object to represent a record in a recordset, or to represent a file or even a folder in a file system or an email message in an email folder structure. As not everyone will have access to an email server (and because it's simpler), we are going to be using the Record object to return information from a folder hierarchy. The Record object can be used to model tree-structured systems where each separate folder, or node, is an instance of a Record object in its own right. Creating an instance of the Record object is simple enough: you use the Server object's CreateObject method:

Set objRecord = Server.CreateObject("ADODB.Record")

In order to use a Record object, we have to populate it with the data that we want to work with – and once again, we can do that using the Open method of the Record object.

The Open Method

The Record object's Open method is a little different from the Recordset object's Open method – but both are related to the task of retrieving data from a data source. If you wanted to use the Record object to handle the files and folders on your web server, you could use the Open method, passing a URL on your web server, like this:

objRecord.Open "Delete.asp", "URL=http://chrisu/BegASP/"

The technology behind these objects is not always easy to set up. Security settings, for example, are very specific to your system setup. In order to open a URL on a different server, you will have to make sure that all of the relevant permissions are set.

This method takes two arguments: the first is the file or folder that we're looking for, and the second is the URL to which any actions will apply. In this case, the record will represent the file named Delete.asp, which it expects to find in the physical directory corresponding to the BegASP/ virtual folder on my web server. Having opened the Record object on that folder or file, we can use it to access the different field names in the record. This information is stored within a Fields collection.

Rather than explain in laborious detail, it's easier to look at how you can access this information with a quick example.

Try It Out – Using The Record Object's Properties

We'll write an example that uses a Record object to view the properties of a physical directory, which corresponds to a virtual directory on our web server.

1. Open up your ASP editor to create a new page, which we'll call Record.asp. Type in the following:

<%Option Explicit %>

<HTML>

<HEAD>

<TITLE>Retrieving Semi-structured Data</TITLE>

</HEAD>

<BODY>

Dim objNodeRecord, objNodeField

Set objNodeRecord = Server.CreateObject("ADODB.Record")

objNodeRecord.Open "","URL=http://my_server_name/BegASP/"

Response.Write "<H2>Properties of the folder:</H2>"

Response.Write "<TABLE BORDER='1'>"

For Each objNodeField in objNodeRecord.Fields

Response.Write "<TR>" & _

"<TD>" & objNodeField.Name & "</TD>" & _

"<TD>" & objNodeField.Value & "</TD>" & _

"</TR>"

Response.Write "</TABLE>"

objNodeRecord.Close

Set objNodeRecord = Nothing

</BODY>

</HTML>

2. Save Record.asp into your \inetpub\wwwroot\BegASPFiles directory, and then view it within your browser.

Chapter14_image017

How It Works

We start by initialising two variables. One will be used to refer to an instance of the Record object, and the other will hold the different fields of the record. Then we create our instance of the Record object:

Dim objNodeRecord, objNodeField

Set objNodeRecord = Server.CreateObject("ADODB.Record")

Then we open the URL of our node that will be our record:

objNodeRecord.Open "","URL=http://my_server_name/BegASP/"

To display the contents of our record, we create a two-column table. The first column will contain the names of the fields of the record. The second column will contain the values of those fields for our record:

Response.Write "<H2>Properties of the folder:</H2>"

Response.Write "<TABLE BORDER='1'>"

For Each objNodeField in objNodeRecord.Fields

Response.Write "<TR>" & _

"<TD>" & objNodeField.Name & "</TD>" & _

"<TD>" & objNodeField.Value & "</TD>" & _

"</TR>"

Response.Write "</TABLE>"

We iterate through fields of the record, using a For Each…Next loop, displaying the Name and Value properties of each Field object in the Record object's Fields collection. As you can see, the fields of this record represent properties of the folder such as its absolute name, and when the folder was created and last written to.

When we've finished, we can close and clean up:

objNodeRecord.Close

Set objNodeRecord = Nothing

Properties and Methods of the Record Object

As you've probably guessed from the previous example, we can use the Record object to manage our web server resources from a remote location. We've seen that we can write pages that allow us to manage database content remotely – it can be as simple as writing ASP/ADO pages that use SQL UPDATE, DELETE or INSERT commands. If you're using a Record object, there are three methods that we can use to move these records around:

MoveRecord
CopyRecord
DeleteRecord

The functions of these three methods are all fairly obvious – and as they suggest, they manage the resources in a more 'physical' way. That makes sense when you think about it: dealing with database data is easier because all the data is stored within one database; but when you're dealing with something like an email folder system, the location of your record is likely to be related to the overall organization of the data store.

Let's take a look at these three methods.

The CopyRecord Method

The CopyRecord method takes two parameters – a source file or folder and a destination file or folder. It copies the former to the location specified in the latter. In this example it copies the File.txt file from my own BegASP virtual folder into the Examples virtual folder on the www.wrox.com web server:

objRecord.Open "File.txt", "URL=http://chrisu/BegASP/"

objRecord.CopyRecord "", "http://www.wrox.com/Examples"

Of course, you need write permissions on the www.wrox.com web server, otherwise it won't allow you to put the file on its server – or you need to pass a relevant UserID and password as parameters. One limitation of the CopyRecord method is that you can't use it to copy a file from a folder into one of its subfolders.

What happens when you try to make a copy of a file, only to find that there's already a file or folder with the same name as your specified destination? In that case, you can use the fifth parameter to the Open method to specify what behavior you prefer. This parameter will take one of the CopyRecordOptionsEnum constants, some of which are shown here:

adCopyOverWrite allows the existing file to be overwritten with the new file
adCopyNonRecursive allows you to copy only a folder, and none of the folder's subfolders

You specify this option with the Open method, like this:

objRecord.Open "File.txt", "URL=http://chrisu/BegASP/", , , adCopyOverWrite

Note that this is specified as the Open method's fifth parameter – here, we've left the third and fourth parameters empty. The missing third and fourth parameters would usually be used to specify UserId and password for remote access to the file on your server. So the full set of parameters is:

objRecord.Open Source, Destination, UserId, Password, Options

The MoveRecord Method

The MoveRecord works in a similar way to CopyRecord, but moves the file from the source to the destination rather than copying it. For example:

objRecord.Open = "File.txt", "URL=http://chrisu/BegASP/"

objRecord.MoveRecord "", "http://www.wrox.com/Examples"

Like CopyRecord, there's a limitation on this method – you cannot use it to move a record from a folder into one of it's own subfolders. And again, the MoveRecord method allows you to specify a UserID and password to the data source if appropriate:

objRecord.Open = "File.txt", "URL=http://chrisu/BegASP/", _

"UserId=Chrisu", "Password=OpenSesame"

The fifth parameter allows you to select from a number of options. Valid values are:

adMoveOverWrite allows you to overwrite an existing file of the same name
adMoveDontUpdateLinks allows you to move the file without updating any hyperlinks to the file

For example:

objRecord.Open = "File.txt", "URL=http://chrisu/BegASP/", _

"UserId=Chrisu", "Password=hello", adMoveOverWrite

The DeleteRecord Method

Rather obviously, the DeleteRecord method requires no destination. Therefore, it's quite a bit simpler:

objRecord.Open = "File.txt", "URL=http://chrisu/BegASP/"

objRecord.DeleteRecord

Try It Out – Using your web page to manipulate files on the web server

Now you have an idea of how to move the records around on the server, let's run through an example that allows you to copy, move or delete a record on your web server. To give you an idea of how it works, we'll create a simple text file called MyFile.txt, and a new web folder called TestFolder, and we'll write an example that allows us to move the file between the TestFolder and BegASP web folders, or delete it altogether. It takes a bit of preparation because we need TestFolder to be a proper virtual directory, but once we've done that the code is quite simple.

1. First we'll create the file – this will be the node that our Record object represents. Start Notepad, type in some random text, and save it in your \inetpub\wwwroot\BegASPFiles folder with the name MyText.txt.

2. Now we'll create a new folder. On your web server machine, start Windows Explorer; in the \inetpub\wwwroot folder create a new subfolder, called TestFolder. Now, the \inetpub\wwwroot folder should contain two child subfolders called TestFolder and BegASPFiles.

Chapter14_image018

3. Now fire up the Microsoft Management Console (MMC) – select Start | Run and type MMC, and press OK; then select Console | Open and navigate to the snap-in file iis.msc (which you'll probably find in your C:\WINNT\system32\inetsrv folder – if not, do a search to find it on your machine). The IIS snap-in in the MMC should reveal the TestFolder file as being a regular file.

Chapter14_image019

Right-click on TestFolder and select Properties; then on the Directory tab, click the Create button to turn TestFolder into an ASP application:

Chapter14_image020

4. That's the preparations; now here's the code. Create the following new file, called RecordMove.asp, using your ASP editor:

<%Option Explicit %>

<!-- METADATA TYPE="typelib"

FILE="c:\program files\common files\system\ado\msado15.dll" -->

<HTML>

<HEAD>

<TITLE>Retrieving Semi-Structured Data</TITLE>

</HEAD>

<BODY>

If Request.Form("Task")="" Then %>

What do you want to do? <BR><BR>

Copy MyText.txt to a new file called MyText2.txt</INPUT><BR>

Move MyText.txt to a new file called MyText2.txt</INPUT><BR>

Delete MyText.txt from the BegASP file</INPUT><BR>

</FORM><%

Else

Dim objRecord

Set objRecord = Server.CreateObject("ADODB.Record")

objRecord.Open "MyText.txt", "URL=http://my_server_name /BegASP"

If Request.Form("Task") = "Copy" Then

objRecord.CopyRecord "", _

"http://my_server_name/TestFolder/MyText2.txt",,,adCopyOverWrite

Response.Write "MyText.txt file copied to a new file called MyText2.txt"

ElseIf Request.Form("Task") = "Move" Then

objRecord.MoveRecord "", _

"http://my_server_name/TestFolder/MyText2.txt",,,adMoveOverWrite

Response.Write "MyText.txt file moved to a new file called MyText2.txt"

ElseIf Request.Form("Task") = "Delete" Then

objRecord.DeleteRecord

Response.Write "MyText.txt has been deleted"

End If

objRecord.Close

Set objRecord = Nothing

End If

</BODY>

</HTML>

5. Save Recordmove.asp into your \inetpub\wwwroot\BegASPFiles folder.

6. Open Recordmove.asp in your browser of choice. Because the Request.Form collection is empty, you'll see the following form:

Chapter14_image021

7. Select the first radio button, which will have the file copied to a new filename in the TestFolder directory. Then hit Go, an the page will reload – this time it will detect the value of Request.Form ("Task"), copy the file and then display a report. But don't just take the word of the ASP page. Instead, go to Windows Explorer and the check this for sure:

Chapter14_image022

8. Use Windows Explorer to delete this occurrence of MyText2.txt, go back to Step 6 and try the other two options.

How It Works

The page is split into two. The first part is an HTML form that is just designed to find out which task you want to perform – copy, move or delete. There's nothing new here – the real action is in the second part of the form. We start by creating an instance of the Record object:

Dim objRecord

Set objRecord = Server.CreateObject("ADODB.Record")

We open our instance of the Record object, so that the record represents the MyText.txt file that lives in the http://my_server_name/BegASP virtual directory:

objRecord.Open "MyText.txt", "URL=http://my_server_name/BegASP"

Then we check the Task value that was passed as part of the HTTP request. If it's equal to Copy then we execute the CopyRecord method to copy our file from its current location to the new TestFolder directory, with the filename MyText2.txt. Then we display an appropriate message:

If Request.Form("Task") = "Copy" Then

objRecord.CopyRecord "", _

"http://my_server_name/TestFolder/MyText2.txt",,,adCopyOverWrite

Response.Write "MyText.txt file copied to a new file called MyText2.txt"

Otherwise, if it's equal to Move, then we execute the MoveRecord method to move our file to its new location; then we display an appropriate message:

ElseIf Request.Form("Task") = "Move" Then

objRecord.MoveRecord "", _

"http://my_server_name/TestFolder/MyText2.txt",,,adMoveOverWrite

Response.Write "MyText.txt file moved to a new file called MyText2.txt"

Otherwise, if it's equal to Delete then we delete the file altogether, and display a message:

ElseIf Request.Form("Task") = "Delete" Then

objRecord.DeleteRecord