The Cancel method cancels an asynchronous operation for the Stream object.

The Cancel method cancels an asynchronous operation of the Record object invoked by the Open method.

Stream.Open Method

The CharSet property indicates the character set to whioch the contents of a text Stream should be translated.

String

The CharSet property can be set to a valid character set only if the Position property of the Stream object is set to 0. Valid character sets for a system are defined in the HKEY_CLASSES_ROOT\MIME\Database\CharSet subkeys.

The default value for the CharSet property is "unicode". If the character set is changed on the fly, the data is translated as it is read from the stream and passed to the application. When writing data, the information is translated before being saved to the data source.

This property is only valid for text streams, which are Stream objects having a value of adTypeText for their Type property value.

Stream.Type Property

The Close method closes an opened Stream object.

The Close method can be called only on an open Stream object. After calling the Close method, the Open method can be called again to reopen the Stream object. Calling the Close method releases any resources allocated to the Stream object.

The CopyTo method copies data from one stream to another.

DestStream (Stream Object)

Must be set to a valid open Stream object, otherwise a runtime error occurs.

NumChars (Integer)

Optional. Specifies the number of characters to copy from the source to the destination Stream object. The default value is -1, which indicates that all remaining data should be copied.

The CopyTo method copies data from the source Stream object starting at the current stream pointer position (indicated by the Stream.Position property). The number of characters copied is either the number indicated by the NumChars argument or the rest of the source stream if the NumChars argument is greater than the number of remaining characters in the source stream or the NumChars argument value is -1.

The stream pointer position of the destination Stream object is automatically set to the next byte available in the Stream object. The CopyTo method will not remove excess data from the destination Stream object past the copy. To do this, call the SetEOS method.

You can copy data from a textual Stream to a binary Stream object, but not from a binary Stream to a textual Stream object.

Stream.Position Property, Stream.SetEOS Method

The EOS property indicates that the stream pointer is currently at the end of the stream.

Boolean

The EOS property is True when the stream pointer is located directly after the last piece of information within the stream and is now pointing to the End-Of-Stream pointer.

The Flush method ensures that all changes made to a Stream object have been persisted to the resource that the Stream object represents.

The Flush method persists any outstanding changes of the Stream object to the resource that is represented by the Stream object. Microsoft claims that this is very rarely necessary, as ADO calls this method internally in the background whenever possible. In addition, when closing a Stream object, the stream is first flushed to the data source.

The LineSeparator indicates the character (or characters) that are used to indicate the end of a line in text streams.

LineSeparatorEnum

The default value for the LineSeparator property is adCRLF, which indicates both a carriage return and a line feed.

This property is valid only for text streams, which are Stream objects having a value of adTypeText for their Type property value.

LineSeparatorEnum Enumeration, Stream.SkipLine Method

The LoadFromFile method loads a file contents into an already open Stream object.

FileName (String)

Must contain a name of a valid file to be loaded into the currently opened Stream object. If the file specified by this argument cannot be found, a runtime error occurs.

The LoadFromFile method works only with an already opened Stream object, replacing the contents of the object with the contents of the file specified within the LoadFromFile argument, FileName. All pre-existing data is overwritten, and any extra data is truncated. However, the Stream object does not lose its relationship to the resource with which it was originally opened.

The LoadFromFile method can be used to upload a file to a server from a client.

The Mode property indicates the permissions for modifying data within a Stream object.

ConnectModeEnum

The default value for the Mode property of a Stream object that is associated with an underlying source is adModeRead. Stream objects that are instantiated in memory have a default value of adModeUnknown for the Mode property.

The Mode property is read- and write-enabled while the Stream object is closed, but read-only once it is opened.

If the Mode property is not specified for a Stream object, it is inherited from the source used to open the object, such as a Record object.

ConnectModeEnum Enumeration, Stream.Open Method

The Open method opens a Stream object from a URL, an opened Record object, or without a source at all, in memory.

Source (Variant)

Optional. Indicates the source of the resource to open. This can be a URL or an open Record object. Omitting this argument instructs ADO to open the Stream object in memory only.

Mode (ConnectModeEnum)

Optional. Indicates the access permissions with which to open the Stream object. The default value is adModeUnknown; if the Stream object is opened with a Record object, the Mode value is taken from that object, ignoring this argument.

OpenOptions (StreamOpenOptions)

Optional. Can be one or more StreamOpenOptions enumeration values, which indicate whether the Stream object should be opened asynchronously or if it is being opened from a Record object, but the default value is adOpenStreamUnspecified.

UserName (String)

Optional. Indicates, if necessary, the username that will be used to access the resource indicated by the source argument. If the Stream object is being opened with a Record object, this value is ignored because access is already available for the resource.

Password (String)

Optional. Indicates, if necessary, the password to verify the UserName argument. If the Stream object is being opened with a Record object, this value is ignored because access is already available for the resource.

The Open method of the Stream object can be invoked with a URL source, an already opened Record object, or without a source at all, indicating that the Stream object is opened in memory. If this last method is used, you can read and write to the Stream object just as you can any other way, but you can persist and retrieve data only by using the SaveToFile or LoadFromFile methods.

When opening a Stream object from an already opened Record object, the Mode value is taken from the Record object, and the UserName and Password properties, if specified, are ignored because access has to be already granted to the Record object if it is open. If opening a Stream from a Record object, specify the adOpenStreamFromRecord enumeration value as the OpenOptions argument, and ADO will use the Record's default stream to populate the Stream object.

If you are opening the Stream object with a URL, you must use the URL keyword (URL=scheme://server/folder).

ConnectModeEnum Enumeration, Stream.LoadFromFile Method, Stream.Mode Property, Stream.SaveToFile Method, StreamOpenOptionsEnum Enumeration

The Position property indicates the position of the stream pointer within the Stream object.

Long

The Position property can be set to any positive number or 0. It can also be set to a value greater than the size of the current Stream object. In doing so, for streams with write permissions you may increase the size of a Stream object by automatically adding Null values. You can, although you are not advised to, do the same for read-only streams, but the size is not altered.

The Position property indicates the number of bytes the stream pointer is located away from the first byte in the stream. If your character set contains multiple bytes for each character, you must multiply this number by the position desired to get the actual character position. For example, when using Unicode, 0 represents the first character, and 2 represents the second.

The Read method reads a number of bytes from a binary stream.

NumBytes (Long or StreamReadEnum)

Optional. Specifies the number of bytes to read from the binary stream. The default value is adReadAll, which returns all the remaining bytes in the stream.

Variant (array)

The Read method is used to read binary streams (Stream.Type property is equal to adTypeBinary), while the ReadText method is used to read textual streams (Stream.Type property is equal to adTypeText).

The return value is a Variant array of bytes, which will equal the number of bytes requested or the number of remaining bytes in the stream if the number of remaining bytes is less than the requested number of bytes. If there is no data to return, a Null Variant value is returned.

Stream.ReadText Method, Stream.Type Property, StreamReadEnum Enumeration

The ReadText method reads a number of characters from a binary stream.

NumChars (Long or StreamReadEnum)

Optional. Specifies the number of characters to read from the text stream. The default value is adReadAll, which returns all the remaining characters in the stream. You can also specify to return the next line of data with the adReadLine enumeration value.

String

The ReadText method reads textual streams (Stream.Type property is equal to adTypeText), while the Read method is used to read binary streams (Stream.Type property is equal to adTypeBinary).

The return value is a String of values, which equals the number of characters requested or the number of remaining characters in the stream if the number of remaining characters is less than the requested number of characters. If there is no data to return, a Null Variant value is returned.

Stream.Read Method, Stream.Type Property, StreamReadEnum Enumeration

The SaveToFile method persists the data of a binary stream to a local file.

FileName (String)

Indicates where the contents of the current Stream object are to be persisted.

SaveOptions (SaveOptionsEnum)

Specifies whether a file is to be created if one doesn't exist, if an existing file should be overwritten, or, if a file already exists, whether an error should occur.

The SaveToFile method completely overwrites an existing file if the adSaveCreateOverwrite enumeration value is used in the SaveOptions argument.

Using this method does not change the contents of the Stream object nor its association to the original resource with which the Stream object was opened. The only difference from the Stream object is that the Position property is set to the beginning of the stream (0).

SaveOptionsEnum Enumeration, Stream.Position Property

The SetEOS method changes the EOS within a given Stream object and truncates any data that lies past the new EOS pointer.

The SetEOS method can shorten a Stream object's length when using the Write, WriteText, and CopyTo methods, which cannot truncate the stream themselves.

Stream.CopyTo Method, Stream.Write Method, Stream.WriteText Method

The Size property represents the number of bytes in a Stream object.

Long

Because the Stream object's size is only restricted by resources, a Long value may not correctly contain the size of a Stream if it exceeds the largest possible number a Long value can contain.

If the size of a stream is unknown, -1 is returned.

The SkipLine method skips entire lines when reading text streams.

The SkipLine method skips an entire line in a textual stream (Stream.Type is equal to adTypeText). This is done by searching for the next occurrence of a line separator (indicated by the LineSeparator property which is, by default, set to adCRLF) or the EOS pointer.

LineSeparatorEnum Enumeration, Stream.LineSeparator Property, Stream.Type Property

The State property indicates the current state of the Stream object.

Long (ObjectStateEnum)

The State property is read-only; returning a Long value that can be evaluated as an ObjectStateEnum enumeration value. The default value for the Stream object is closed.

For the Stream object, the State property can return multiple values when the object is executing an operation asynchronously (i.e., adStateOpen and adStateExecuting).

ObjectStateEnum Enumeration

The Type property indicates how a Stream object's data should be analyzed.

StreamTypeEnum Enumeration

The default value for a Stream object is adTypeText, but if binary data is written to a new Stream object, the Type property will automatically be changed to adTypeBinary.

The Type property is read- and write-enabled while the stream pointer is at zero (Position property equals 0) and read-only at any other position.

If the Type property is set to adTypeText, you should use the ReadText and WriteText methods for data manipulation and retrieval. If the Type property is set to adTypeBinary, you should use the Read and Write methods for data manipulation and retrieval.

Stream.Read Method, Stream.ReadText Method, Stream.Write Method, Stream.WriteText method, StreamTypeEnum Enumeration

The Write method writes a number of bytes to a binary stream.

Buffer (Variant)

Contains an array of Byte values to be written to the current binary stream.

After writing the specified bytes to the Stream object, the Position property is set to the next byte following the last byte written. If there is existing data past the end of what has been written, it is not truncated. If you want to truncate this data, call the SetEOS method.

If the written data exceeds the length of the Stream object, the new data is appended to the Stream object, the length of the stream is increased, and the EOS pointer is moved to the new end of the stream.

The Write method is used to write to binary streams (Stream.Type property is equal to adTypeBinary), while the WriteText method is used to write textual streams (Stream.Type property is equal to adTypeText).

Stream.EOS Property, Stream.SetEOS Method, Stream.Type Property, Stream.WriteText Method, StreamWriteEnum Enumeration

The WriteText method writes a number of bytes to a binary stream.

Data (String)

Represents the String data to be written to the Stream object.

Options (StreamWriteEnum)

Optional. Indicates whether just the data is written to the Stream object or if the data and a line separator (indicated by the LineSeparator property) are added to the Stream object. The default is not to add the line separator.

After writing the specified string to the Stream object, the Position property is set to the next character following the last character written. If there is existing data past the end of what has been written, it is not truncated. If you want to truncate this data, call the SetEOS method.

If the written data exceeds the length of the Stream object, the new data is appended to the Stream object, the length of the stream is increased, and the EOS pointer is moved to the new end of the stream.

The WriteText method is used to write to text streams (Stream.Type property is equal to adTypeText), while the Write method is used to write binary streams (Stream.Type property is equal to adTypeBinary).

Stream.EOS Property, Stream.SetEOS Method, Stream.Type Property, Stream.WriteText Method, StreamWriteEnum Enumeration