|
|
Developing Windows Clients |
Supports sequential access to textual data sources such as text files.
Attributes
Container Property
Separator Property
Line Property
TruncationLength Property
Methods
Close Method
Read Method
ReadLines Method
Write Method
WriteLines Method
Exceptions
TextStreamLineTruncated Error
TextStreamContainsNull Error
This object provides sequential access to textual (character-oriented) data streams. Text files are the most common source for such streams.
All characters in the stream are transcoded between the encoding in which the stream is read and written within the SAS System and the encoding being used by the client. Most commonly, the transcoding is between some form of ASCII or EBCDIC (within the SAS System) and Unicode (for many kinds of clients).
SAS always reads text files using a record-oriented approach. The maximum size of the records ( TruncationLength) must have been provided - typically as a parameter to the open call. The ReadLines method reads the long text lines, but truncates them to this length. The text that was truncated on each line cannot be obtained. Read fails when a line would be truncated. It is not possible to disable truncation. While it is possible to close the stream, and then open it again with a larger TruncationLength, but for really large values, a host-imposed limit on line lengths might make this ineffectual.
The containing object for this stream.
Type: Object
Description
The containing object for this stream. If, for example, the stream was created from a Fileref, then this attribute references that Fileref.
Example
Usage
The line separator, used in the Read and Write methods.
Type: String
Description
As a file is read using the Read method, this separator value is inserted between lines of text. As a file is written using the Write method, this separator is removed from the provided text and each line is written with a host defined separator (or record boundary).
To write a file that was originally created on a PC (and thus contains a separator of CarriageReturn LineFeed) to Unix, first set the Separator to CarriageReturn LineFeed then call Write.
Default: A single linefeed character (also called LF or newline).
Example
Usage
The current line number of the location in the stream.
Type: Long
Description
This cannot be set, and it is automatically updated when Read, ReadLines, Write, or WriteLines is called.
Example
Usage
The maximum length for a line of text.
Type: Long
Description
This is set at the time the file is opened, and it cannot be changed. Methods which create a TextStream object typically let you specify this value.
Example
Usage
Closes the stream.
Description
Frees resources associated with the stream. You should close a stream when you are finished with it. Streams are also closed when their container is closed. Deassigning a Fileref, for example, closes its streams.
Closing the stream releases any locks held by the stream. If, for example, the stream is being used to write a file and the SAS System obtained an exclusive-use lock on the file, that lock is released when the stream is closed.
Usage
Parameters: None
Example
See Also
Reads text from the stream into a character string.
Description
Lines are separated using the value of the Separator property.
This read operation will fail (returning TextStreamLineTruncated) if you attempt to read any lines that are longer than the TruncationLength.
Usage
The stream must have been previously opened with StreamOpenModeForReading or StreamOpenModeForUpdating.
Parameters
| Name | Direction | Type | Description |
|---|---|---|---|
| numCharsRequested | in | Long | An upper bound on the number of characters to be returned by this request. This should not be excessively large since SAS allocates a buffer based on this size. |
Returns String
Errors Returned
Example
See Also
Reads lines of text from the stream.
Description
This method returns an array of strings read from the stream. Lines are truncated based on the TruncationLength.
ReadLines differs from Read in a number of ways.
ReadLines returns an array of text, with each element of the array containing a line. There are no separators in these lines. ReadLines does not use the Separator property.
ReadLines returns successfully when lines are truncated and describes which lines were too long.
ReadLines takes a number of lines to read, while Read takes a number of characters.
Usage
The stream must have been previously opened with StreamOpenModeForReading or StreamOpenModeForUpdating.
Parameters
| Name | Direction | Type | Description |
|---|---|---|---|
| numLinesRequested | in | Long | The maximum number of lines to read. |
| truncatedLines | out | Long(index) | An output array containing the index
of each line that was truncated. These indices correspond to
elements in the "textLines" output parameter.
For example, if the third and fifth lines of a file are longer than TruncationLength, this array will have two elements: truncatedLines(0) will be 2 (the third element) and truncatedLines(1) will be 4. |
| textLines | out | String(index) | An array of text lines that were read from the stream. An array with zero elements indicates that the end of the stream has been reached. |
Example
' Get the selected file from the filelist and read it to c:\temp\readFile.txt
Dim obFileService As SAS.FileService
Dim obFileref As SAS.Fileref
Dim assignedName As String
Dim obLocalFileSystem As New Scripting.FileSystemObject
Dim obLocalTextStream As Scripting.TextStream
Dim obRemoteTextStream As SAS.TextStream
Dim textLines() As String
Dim truncatedLines() As Long
Dim linesRead As Integer
Set obFileService = obSAS.FileService
' Create a temporary fileref to the selected file
fullPathName = obFileService.FullName(ListView1.SelectedItem.Text, currentPath)
Set obFileref = obFileService.AssignFileref("", "DISK", fullPathName, "", assignedName)
Set obRemoteTextStream = obFileref.OpenTextStream(SASForReading, 16500)
' VB automatically uses the right thing for vbNewLine. This is typically
' CR/LF
obRemoteTextStream.Separator = vbNewLine
Set obLocalTextStream = obLocalFileSystem.CreateTextFile("c:\temp\readFile.txt", True, False)
linesRead = 1
While (linesRead > 0)
obRemoteTextStream.ReadLines 100, truncatedLines, textLines
linesRead = UBound(textLines)
For i = 0 To linesRead
obLocalTextStream.WriteLine textLines(i)
Next
Wend
See Also
Writes text to the stream.
Description
The text should contain separators that match the Separator property. This method writes the text to the stream, replacing any separators found with a host-dependent separator (or record boundary). The value of the host-dependent separator is defined by host conventions for the particular type of file.
A final separator is written after the buffer has been processed, so the buffer should not contain partial lines or have a separator after the (intended) final line.
Lines longer than TruncationLength are truncated, and a TextStreamLineTruncated exception is returned. Any text written before the exception remains in the stream (including text on the line that was truncated, up to the TruncationLength.)
Usage
The stream must have been previously opened with StreamOpenModeForWriting or StreamOpenModeForUpdating.
Parameters
| Name | Direction | Type | Description |
|---|---|---|---|
| text | in | String | A text string with embedded separators between the lines. |
Example
See Also
Writes lines of text to the stream.
Description
Thie method writes an array of strings to the stream. Each element of the array represents a line of text.
Usage
The stream must have been previously opened with StreamOpenModeForWriting or StreamOpenModeForUpdating.
Parameters
| Name | Direction | Type | Description |
|---|---|---|---|
| textLines | in | String(index) | The array of lines to write. These lines are not scanned for line separators. |
| truncatedLines | out | Long(index) | For example, if the third and fifth lines of a file are longer than TruncationLength, then this array will have two elements: truncatedLines(0) will be 2 (the third element) and truncatedLines(1) will be 4. |
Example
See Also
Description
A line is truncated when it is longer than the TruncationLength. The
TruncationLength is set as a parameter when the file is opened. It is not
possible to get the text that was truncated, unless you switch to using a
binary stream.
Description
This object must not be used with data that contains
null characters. If your data might contain nulls, you should
use a BinaryStream object instead.
|
|
Developing Windows Clients |