ADO Stream Object Functions and Methods

[Previous] [Next]

Let's examine the functions and methods available on the Stream object and shown in the following table.

Stream Object Functions and Methods
Function or Method Name	Description
Cancel	Cancels a pending asynchronous call to a Stream object
Close	Closes an open Stream object
CopyTo	Copies data from the Stream object to another Stream object
Flush	Flushes the contents stored in the Stream object's buffer
LoadFromFile	Loads the contents of a file into the stream
Open	Opens the Stream object
Read	Reads binary data from the stream
ReadText	Reads text data from the stream
SaveToFile	Persists data from the Stream object to a file
SetEOS	Sets the current position as the end of the Stream object
SkipLine	Moves to the beginning of the next line of data in a text stream
Write	Appends binary data to the stream
WriteText	Appends text data to the stream

Cancel Method

You can call the Cancel method to terminate a pending asynchronous call to the Stream object's Open method. This method takes no parameters.

Close Method

The Close method closes a Stream object and releases the data associated with that Stream object. This method takes no parameters.

CopyTo Method

You can use the CopyTo method to move data from one Stream object to another. The CopyTo method takes two parameters as shown here:

 Stream.CopyTo DestStream, NumChars 

The first parameter, DestStream, is required and accepts an open Stream object. The second parameter, NumChars, is optional and accepts a long integer specifying the number of characters or bytes (starting at the current position) to copy to DestStream. The default value for this parameter is -1, which specifies that all data, from the current position to EOS, should be copied. If you specify a value that's larger than the remaining number of characters or bytes in the source Stream, this method will copy only the remaining characters or bytes and no error will occur.

If you're using a Stream of type adTypeBinary, the NumChars parameter actually specifies the number of characters to copy, regardless of whether you're using Unicode or ANSI strings. After ADO copies the data from the source Stream to the destination Stream, the current position in the source Stream will be the byte or character that follows the last byte or character copied.

Flush Method

Call the Flush method to send the data buffered in the Stream object to that object's underlying source to ensure the contents have been written. You should not need to call Flush prior to closing your Stream because calling the Close method will implicitly flush the buffered data. If you need to write the data stored in the buffer while keeping the Stream object open, that's a good time to call the Flush method. The Flush method takes no parameters.

LoadFromFile Method

If you want to load the contents of a file into a Stream object, call the LoadFromFile method. This method takes a single string parameter that contains the name and location of the file you want to load:

 Stream.LoadFromFile FileName 

The FileName parameter can contain any valid pathname and filename in Universal Naming Convention (UNC) format. If the specified file doesn't exist, a trappable error occurs.

When you use the LoadFromFile method, the contents of the file overwrite the contents of the Stream. When the LoadFromFile method completes, the Stream object's Position property will be set to 0—the beginning of the Stream.

Open Method

The Open method opens a Stream object from a Record object or a URL. The Open method accepts five optional parameters, as shown here:

 Stream.Open Source, Mode, OpenOptions, UserName, Password 

The Source parameter specifies the source of the data to retrieve into the Stream object. This parameter accepts an open Record object or a string that contains a valid URL. You can also specify an empty string for the Source parameter, to open an empty Stream object. If you omit this parameter, the value of the Source property will be used.

The Mode parameter accepts a value from ConnectModeEnum and corresponds to the Stream object's Mode property. If you omit this parameter, the value of the Mode property will be used. The OpenOptions parameter accepts values from StreamOpenOptionsEnum, shown in the following table.

StreamOpenOptionsEnum Values
Constant	Value	Description
adOpenStreamUnspecified	-1	Default; opens the Stream object with default options.
adOpenStreamAsync	1	Opens the Stream object in asynchronous mode.
adOpenStreamFromRecord	4	Specifies that the Source parameter contains an open Record object. The default stream associated with that node is opened.

The UserName and Password parameters contain strings that authorize the user to open the Stream.

Read Method

Use the Read method to retrieve binary data from the Stream object. This method accepts a long integer and returns a Variant:

 Variant = Stream.Read NumBytes 

The NumBytes parameter specifies the number of bytes to return, starting with the current position in the Stream. If you specify a number that's larger than the number of bytes remaining in the Stream, the Read method will return only the remaining data; no error will occur. If you omit this parameter, this method will return all the data from the current position through the end of the Stream. NumBytes can also accept the value adReadAll from StreamReadEnum, the values from which are shown in the following table.

StreamReadEnum Values
Constant	Value	Description
adReadAll	-1	Default; reads all remaining characters in the Stream object
adReadLine	-2	Reads until the end of the current line

ReadText Method

The ReadText method is similar to the Read method, except that it retrieves text data rather than binary data from the Stream object. ReadText takes a single parameter, NumChars, and is shown here:

 String = Stream.ReadText NumChars 

In addition to a long integer value, NumChars can accept either of the values in StreamReadEnum.

Whether the Stream object contains single-byte characters (such as ANSI) or multibyte characters (such as Unicode), ReadText will return the number of characters specified rather than the number of bytes. The Stream object's Charset property specifies the type of character data stored in the Stream.

SaveToFile Method

To save the contents of the Stream to a file, call the SaveToFile method. This method takes two parameters as follows:

 Stream.SaveToFile FileName, SaveOptions 

The FileName parameter is required and accepts a fully qualified name for the file to create. This parameter is a string data type and accepts UNC paths. The SaveOptions parameter is optional and accepts one or both of the values from SaveOptionsEnum, shown in the following table.

SaveOptionsEnum Values
Constant	Value	Description
adSaveCreateNotExist	1	Default; creates a new file. Raises a trappable error if the file already exists.
adSaveCreateOverWrite	2	Overwrites the existing file if it exists.

When the SaveToFile method completes, the Stream object's current position will be at EOS.

SetEOS Method

SetEOS designates the current position as the end of the stream of data. All data from that position onward will be lost. This method takes no parameters.

SkipLine Method

The SkipLine method skips to the beginning of the next line of text in your Stream. If your text data has no more remaining line separators, the position will be set to the end of the Stream—the Stream object's EOS property will return True and its Position property will return the same value as its Size property.

Write Method

Use the Write method to append binary data to your Stream. The Write method accepts a single parameter, shown here:

 Stream.Write Buffer 

The Buffer parameter is required and accepts a byte array containing the data to append to the Stream.

After the Write method completes, the current position of the Stream will be the byte following the data appended to the Stream. If you aren't positioned at the end of the Stream prior to calling Write, you'll overwrite data in the Stream with the data in the Buffer parameter.

WriteText Method

Use the WriteText method to append text data to your Stream. The WriteText method accepts two parameters, shown here:

 Stream.WriteText Data, Options 

The Data parameter is required and accepts a string containing the data to append to the Stream. The Options parameter is optional and accepts one of the two values in StreamWriteEnum, which the following table describes.

StreamWriteEnum Values
Constant	Value	Description
adWriteChar	0	Default; appends only the string in the Data parameter to the Stream object
adWriteLine	1	Appends the string in the Data parameter, as well as the line separator specified by the LineSeparator property, to the Stream object

After the WriteText method completes, the current position of the Stream will be the character following the data appended to the Stream. If you aren't positioned at the end of the Stream prior to calling WriteText, you'll overwrite the existing data in the Stream with the data in the Data parameter.