CORBA Interface ITextStream

Supports sequential access to textual data sources such as text files.

Definition

ITextStream Description

This component 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 operation 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.

CORBA Definitions
exception LineTruncated	Warns that a line exceeded the TruncationLength.
exception ContainsNull	Warns that the text being read contains an embedded NULL.
attribute Container	The containing component for this stream.
method Close	Closes the stream.
method Read	Reads text from the stream into a character string.
method ReadLines	Reads lines of text from the stream.
method Write	Writes text to the stream.
method WriteLines	Writes lines of text to the stream.
attribute Separator	The line separator, used in the Read and Write methods.
attribute Line	The current line number of the location in the stream.
attribute TruncationLength	The maximum length for a line of text.

Java Classes
ITextStreamHelper	Used to manipulate the ITextStream type
ITextStreamHolder	Used to process the ITextStream type as an out parameter
LineTruncated	Warns that a line exceeded the TruncationLength.
LineTruncatedHelper	Used to manipulate the LineTruncated type
LineTruncatedHolder	Used to process the LineTruncated type as an out parameter
ContainsNull	Warns that the text being read contains an embedded NULL.
ContainsNullHelper	Used to manipulate the ContainsNull type
ContainsNullHolder	Used to process the ContainsNull type as an out parameter

Java Interfaces
ITextStream	Supports sequential access to textual data sources such as text files.

Java Interface ITextStream

Supports sequential access to textual data sources such as text files.

Package com.sas.iom.SAS

ITextStream Description
This component 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 operation 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.

public interface ITextStream
extends org.omg.CORBA.Object

Method Summary

void	Close () Closes the stream.
java.lang.String	Read ( int numCharsRequested ) throws ( LineTruncated, ContainsNull, GenericError ); Reads text from the stream into a character string.
void	ReadLines ( int numLinesRequested , IntSeqHolder truncatedLines , StringSeqHolder textLines ) throws ( GenericError ); Reads lines of text from the stream.
void	Write ( java.lang.String text ) throws ( GenericError ); Writes text to the stream.
void	WriteLines ( java.lang.String[] textLines , IntSeqHolder truncatedLines ) throws ( GenericError ); Writes lines of text to the stream.

Java Class ITextStreamHelper

public class ITextStreamHelper

Description
Implementing class for methods (insert, extract, type, id, read, write, narrow) used to manipulate the ITextStream type.

java.lang.Object
  |
  +--com.sas.iom.SAS.ITextStreamHelper

Java Class ITextStreamHolder

public class ITextStreamHolder

Description
Implementing class for methods (_read, _write, _type) used to process the ITextStream type as an out parameter.

java.lang.Object
  |
  +--com.sas.iom.SAS.ITextStreamHolder

CORBA Exception LineTruncated

Warns that a line exceeded the TruncationLength.

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.

Java Class LineTruncated

public class LineTruncated

java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--org.omg.CORBA.UserException
                    |
                    +--com.sas.iom.SAS.ITextStream_1_0Package.LineTruncated

Java Class LineTruncatedHelper

public class LineTruncatedHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate the LineTruncated type.

java.lang.Object
  |
  +--com.sas.iom.SAS.ITextStream_1_0Package.LineTruncatedHelper

Java Class LineTruncatedHolder

public class LineTruncatedHolder

Description
Implementing class for methods (_read, _write, _type) used to process the LineTruncated type as an out parameter.

java.lang.Object
  |
  +--com.sas.iom.SAS.ITextStream_1_0Package.LineTruncatedHolder

CORBA Exception ContainsNull

Warns that the text being read contains an embedded NULL.

Description
This component must not be used with data that contains null characters. If your data might contain nulls, you should use a BinaryStream component instead.

Java Class ContainsNull

public class ContainsNull

java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--org.omg.CORBA.UserException
                    |
                    +--com.sas.iom.SAS.ITextStream_1_0Package.ContainsNull

Java Class ContainsNullHelper

public class ContainsNullHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate the ContainsNull type.

java.lang.Object
  |
  +--com.sas.iom.SAS.ITextStream_1_0Package.ContainsNullHelper

Java Class ContainsNullHolder

public class ContainsNullHolder

Description
Implementing class for methods (_read, _write, _type) used to process the ContainsNull type as an out parameter.

java.lang.Object
  |
  +--com.sas.iom.SAS.ITextStream_1_0Package.ContainsNullHolder

CORBA Attribute Container (readonly)

The containing component for this stream.

Description
The containing component for this stream. If, for example, the stream was created from a Fileref, then this attribute references that Fileref.

Usage

Java Method Container

public Object Container ();

CORBA Method Close

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

Java Method Close

void Close ( )

Example

CORBA Method Read

Reads text from the stream into a character string.

Description
Lines are separated using the value of the Separator attribute.

This read operation will fail (returning LineTruncated) 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.

Java Method Read

java.lang.String Read (

    int numCharsRequested 
    )
    throws (
            LineTruncated,
            ContainsNull,
            GenericError
    );

Parameter Details

Parameter	Direction	Type	Description
numCharsRequested	in	int	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.

Example

CORBA Method ReadLines

Reads lines of text from the stream.

Description
This operation 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 attribute.

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.

Java Method ReadLines

void ReadLines (

    int numLinesRequested ,
    IntSeqHolder truncatedLines ,
    StringSeqHolder textLines 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter	Direction	Type	Description
numLinesRequested	in	int	The maximum number of lines to read.
truncatedLines	out	IntSeqHolder	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	StringSeqHolder	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

CORBA Method Write

Writes text to the stream.

Description
The text should contain separators that match the Separator attribute. 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 LineTruncated 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.

Java Method Write

void Write (

    java.lang.String text 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter	Direction	Type	Description
text	in	java.lang.String	A text string with embedded separators between the lines.

Example

CORBA Method WriteLines

Writes lines of text to the stream.

Description
Thie operation 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.

Java Method WriteLines

void WriteLines (

    java.lang.String[] textLines ,
    IntSeqHolder truncatedLines 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter	Direction	Type	Description
textLines	in	java.lang.String[]	The array of lines to write. These lines are not scanned for line separators.
truncatedLines	out	IntSeqHolder	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

CORBA Attribute Separator

The line separator, used in the Read and Write methods.

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 operation, 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.

Usage

Java Method Separator

public java.lang.String Separator ();
public void Separator ( java.lang.String Separator );

CORBA Attribute Line (readonly)

The current line number of the location in the stream.

Description
This cannot be set, and it is automatically updated when Read, ReadLines, Write, or WriteLines is called.

Usage

Java Method Line

public int Line ();

CORBA Attribute TruncationLength (readonly)

The maximum length for a line of text.

Description
This is set at the time the file is opened, and it cannot be changed. Operations which create a TextStream component typically let you specify this value.

Usage

Java Method TruncationLength

public int TruncationLength ();