Contents Developing Java Clients  

CORBA Interface IBinaryStream

Supports sequential access to binary data sources such as binary files.

Definition

CORBA Module SAS

IBinaryStream Description

This component provides sequential access to binary (byte-oriented) data streams. Binary files are the most common source for such streams.

While the most common use of this interface is the tranfer of files in binary formats, the interface is also useful for the transfer of text data in cases where you need to bypass the standard text transcoding. For text, one common case is the transfer of single-byte encoded HTML containing the "meta charset" tag. In such a case, transferring the HTML by using a character-oriented data type (such as the Unicode strings common for many client environments), would invalidate the "meta charset" tag.

When you are bypassing standard transcoding, this interface also supports optional non-standard transcoding based on the values specified in StreamEncoding and CallerEncoding. If StreamEncoding and CallerEncoding are the same, no transcoding is performed. They default to the same value.

The main differences between the BinaryStream and the TextStream are: the BinaryStream can recode text based on provided encodings of the source and destination, while the TextStream automatically determines the system code page of the source and destination and recodes based on that; the BinaryStream uses an array of bytes, while the TextStream uses an array of character strings or a single character string; the BinaryStream has no concept of lines and therefore does not truncate lines and does nothing with line separators.

CORBA Definitions
 attribute Container  The containing component for this stream.
 method Close  Closes the stream.
 method Read  Reads the requested number of bytes from the current position in the stream.
 method Write  Writes bytes to the stream.
 attribute StreamEncoding  The encoding of the data as it exists in the stream, before reading or after writing.
 attribute CallerEncoding  The encoding of the data desired by the caller in a read, or supplied by the caller in a write.

Java Classes
 IBinaryStreamHelper  Used to manipulate the IBinaryStream type
 IBinaryStreamHolder  Used to process the IBinaryStream type as an out parameter

Java Interfaces
 IBinaryStream  Supports sequential access to binary data sources such as binary files.

Java Interface IBinaryStream

Supports sequential access to binary data sources such as binary files.

Package com.sas.iom.SAS

IBinaryStream Description
This component provides sequential access to binary (byte-oriented) data streams. Binary files are the most common source for such streams.

While the most common use of this interface is the tranfer of files in binary formats, the interface is also useful for the transfer of text data in cases where you need to bypass the standard text transcoding. For text, one common case is the transfer of single-byte encoded HTML containing the "meta charset" tag. In such a case, transferring the HTML by using a character-oriented data type (such as the Unicode strings common for many client environments), would invalidate the "meta charset" tag.

When you are bypassing standard transcoding, this interface also supports optional non-standard transcoding based on the values specified in StreamEncoding and CallerEncoding. If StreamEncoding and CallerEncoding are the same, no transcoding is performed. They default to the same value.

The main differences between the BinaryStream and the TextStream are: the BinaryStream can recode text based on provided encodings of the source and destination, while the TextStream automatically determines the system code page of the source and destination and recodes based on that; the BinaryStream uses an array of bytes, while the TextStream uses an array of character strings or a single character string; the BinaryStream has no concept of lines and therefore does not truncate lines and does nothing with line separators.

public interface IBinaryStream
extends org.omg.CORBA.Object

Method Summary

 void Close ()

Closes the stream.

 void Read ( int requestedLength , OctetSeqHolder binaryData )
throws ( GenericError );

Reads the requested number of bytes from the current position in the stream.

 void Write ( octet[] binaryData )
throws ( GenericError );

Writes bytes to the stream.

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 will reference 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 the requested number of bytes from the current position in the stream.

Description
The current position in the stream is updated to reflect the number of bytes read. Subsequent calls to read will continue at the point the previous call stopped.

Usage
The stream must have been previously opened with StreamOpenModeForReading or StreamOpenModeForUpdating.

Java Method Read

void Read ( 

    int requestedLength ,
    OctetSeqHolder binaryData 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter Direction Type Description
requestedLength  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.  
binaryData  out  OctetSeqHolder  This is the array of data that was read from the stream. This parameter returns a zero-sized array when end of stream is reached.  

CORBA Method Write

Writes bytes to the stream.

Description
Bytes are written starting at the current position in the stream. After the write operation is performed, the stream's current position is updated to reflect the bytes just written.

Usage
The stream must have been previously opened with StreamOpenModeForWriting or StreamOpenModeForUpdating.

Java Method Write

void Write ( 

    octet[] binaryData 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter Direction Type Description
binaryData  in  octet[]  The bytes to be written.  

CORBA Attribute StreamEncoding (readonly)

The encoding of the data as it exists in the stream, before reading or after writing.

Description

Usage

Java Method StreamEncoding 

public java.lang.String StreamEncoding ();

CORBA Attribute CallerEncoding (readonly)

The encoding of the data desired by the caller in a read, or supplied by the caller in a write.

Description

Usage

Java Method CallerEncoding 

public java.lang.String CallerEncoding ();

Contents Developing Java Clients