Contents Developing Java Clients  

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 or written 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 or written 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.

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

CORBA Exception ContainsNull

Warns that the text being read or written 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

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

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.  

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.  

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.  

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.  

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

Contents Developing Java Clients