CORBA Interface IBinaryStream

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

Definition

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.

Java Class IBinaryStreamHelper

public class IBinaryStreamHelper

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

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

Java Class IBinaryStreamHolder

public class IBinaryStreamHolder

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

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

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

Example

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.

Example

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.

Example

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