## CORBA Interface ITextStream

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

### Definition

CORBA Module 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.

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 ();