The Record and Stream objects were introduced with ADO 2.5 (the present version is ADO 2.8) to extend the then data manipulation capabilities of ADO to cover a much larger information base. Especially with the Internet emerging as a global repository of data of all kinds, a means was necessary to look at the details of such a repository. Since these were file- and folder-based, methodologies to look at these hierarchical data sources were necessary. The Record and Stream objects provide such a capability and exist in the ADO Object Model.
The Record object navigates through the file and folder structure, manipulating (copying, moving, and deleting) the files and folders. The Record object is inherently associated with a Stream object, a buffer area from which the content of the Stream can be read. The nature of the contents of a Stream could be text or binary type of information, although Microsoft documentation mentions just the binary part.
Tutorial content
In an earlier tutorial we have seen how Record objects can be created using the URL of a web site and also as an object riding on top of a recordset. The recordset in this case was opened using the URL as an argument. The focus of this tutorial is to describe how one may create a Stream object using ADO.
The properties of the Stream created will be described using examples of documents on the intranet site as the record; Stream objects are really meant for looking at such objects. As for the platform for testing, MS Access 2003 is used. Of course all this can be done in VB 6. But most readers already have MS Access; that is the reason the tutorial uses this platform for examples. Typically a form is used for testing with a single button. The URL used in the tutorial is the local IIS (5.1).
Since the Stream object's content is in the record object, the Stream object can be opened after opening a record object. We have also seen that the Record object can be opened using an already open recordset object. In this case the recordset object is really looking at an URL.
The Stream object can be opened without opening either the Record or recordset (followed by record) objects. It can be opened simply by supplying the URL as an argument. Another way of creating the Stream object is to open it in memory, which holds the contents of the Stream in memory, like a local buffer. This method will not require any arguments.
There are therefore at least four ways of opening the Stream object, and they will be illustrated by examples. Based on these different ways, the Stream object's relationship vis-à-vis the other objects should be as shown in this next picture (in earlier diagrams the Stream object is sitting all by itself).
Adding a reference to the ADO 2.8 library
The MS Access Application Stream is open in the visual basic editor. Go to Tools -->References... as shown in the next picture.
This brings up the References - stream window as shown. Here you use the scroll bar to scroll down and pick ADO 2.8. The default may be ADO 2.0. Now you can access all the properties and methods of all the ADO objects including the Stream object.
At this point you may be interested in all the different properties and methods of the Stream object. There is no better place look than the Object Browser.
All arguments are optional as we discussed for the memory stream syntax for opening a Stream.
Sub Open(
[Source],
[Mode As ConnectModeEnum = adModeUnknown],
[Options As StreamOpenOptionsEnum = adOpenStreamUnspecified],
[UserName As String],
[Password As String]
)
Record opens with an open recordset and Stream uses the open Record
As mentioned in the introduction, the Stream object may be opened using an open Record object. We have seen in an earlier tutorial that the Record object may open using a recordset object. This is the case we will be considering here. We look at most of the properties for this example, but we will only look at a couple of properties in other cases, as they are not going to vary.
Place a command button on an MS Access form and use the following code in the click event of the command button. The comments before the statement provide enough information to understand the code.
While typing in the code do not forget to use the intellisense support for coding as the next picture shows while choosing what to do next. It's the multiple choice paradigm all over!
When this form is displayed we can see all the properties of the Stream object. However the values of these properties appear as numbers. These numbers are enumerated values of Constants in ADO whose description may not be available. In the drop-down cues you will find these constants. A good reference where you may find these constants listed is in the book Programming ADO (author David Sceppa; year published: 2000; ISBN: 0-7356-0764-8).
The meanings of the numeric constants are provided in the next paragraph.
Constants:
Meaning:
EOS:
false means the current position in the stream is not the end.
Line Separator:
-1 means carriage return & line feed will be used in text (vbCRLF)
Mode:
1 means Read Only permission (default); there are seven such enums
Position:
0 means current position is at the beginning of data
Size:
1130, Size of the stream in bytes
Type:
type of data stored in stream, value 2 means Text (default)
It is not necessary to open a recordset followed by a record to open the Stream. If you have a record already open you may just open the Stream object using that record. The record contains the Stream whose properties can be found. The following code shows how the default properties are found.
It is not necessary to have a record open to open a Stream object. By providing a URL reference the Stream may be opened as shown in the next code listing.
The next listing shows the print out from the debug.print statements.
strem.Type: 1
strem.Size: 5271
strem.EOS: False
strem.state: 1
You may be wondering why in spite of the resource being of type 'text,' ADO returns a value for type= 1. In fact this has appeared in a large number of FAQs and caused confusion. If you open a text directly into Stream (no other object is open except the Stream), Microsoft says (not in small print) that the initial data will be shown as binary! This means that the value for Type=1.
It is not even necessary to pass an URL to open a Stream. The Stream is now open in the memory and sitting in the memory. This can be very useful as it acts as if it caches the data which can both be persisted and read back. We will see this in a future tutorial. The next listing shows how the Stream is opened.
Private Sub Command0_Click()
Dim mstream As ADODB.stream
Set mstream = New ADODB.stream
'mstream.Type=adTypeBinary
mstream.Type = adTypeText
mstream.Open
If mstream.State = adStateOpen Then
Debug.Print ("Memory Stream is open: " & mstream.State)
Debug.Print ("Memory stream size is: " & mstream.Size)
End If
mstream.Close
Debug.Print ("Memory Stream is closed: " & mstream.State)
End Sub
The way you want to open a memory may be chosen by setting the Type property. The next listing shows the print out from the debug.print statement.
Memory Stream is open: 1
Memory stream size is: 0
Memory Stream is open: 0
Summary
This tutorial provides an introduction to the Stream object, one of the ADO objects which extends the reach of ADO to explore not only data, but other information resources. Microsoft Access 2003 on XP Professional Media Center Edition was used in testing the codes.
Using ADO`s Record Object with URLs
