ca.idms.io
Class NativeDataOutputStream

java.lang.Object
  java.io.OutputStream
      java.io.FilterOutputStream
          ca.idms.io.NativeDataOutputStream

All Implemented Interfaces:

java.io.Closeable, java.io.DataOutput, java.io.Flushable

Direct Known Subclasses:

FloDataOutputStream, LoDataOutputStream, UnicodeDataOutputStream, UtfDataOutputStream

public class NativeDataOutputStream
extends java.io.FilterOutputStream
implements java.io.DataOutput

A NativeDataOutputStream writes "native" data to a buffered output stream. This class combines a DataOutputStream, a NativeFormat, and a TraceBufferOutputStream, and provides additional features to those defined by the DataOutput interface:

The data conversion methods are optimized to take advantage of the direct access to the byte array buffer provided by the TraceBufferOutputStream.

The methods provided by the TraceBufferOutputStream to access the underlying byte array are exposed to the caller.

The native data conversion options specifed in the NativeFormat are encapsulated and transparent to the caller in most cases.

Methods are provided to write data in OS/390 formats, including packed decimal, zoned decimal, and DBCS.

Unlike DataOutputStream, the methods are not final, so this class can be a base class for specialized data output classes. The exceptions are the same as those defined by the DataOutput interface and the DataOutputStream class. Note that there is no size() method.

Since:

CA IDMS Server 4.2 OS/390 Edition

Version:

1.00, 12/14/99

Author:

Dave Ross

See Also:

TraceBufferOutputStream, NativeFormat, LoDataInputStream, FloDataInputStream, UtfDataInputStream, UnicodeDataInputStream

Field Summary

protected java.io.DataOutputStream	dos Contains the default methods.
protected NativeFormat	fmt Describes the native data formats.

Fields inherited from class java.io.FilterOutputStream

out

Method Summary

byte[]	getBuffer() Gets the buffer.
int	getCount() Gets the number of valid bytes in the buffer.
NativeFormat	getFormat()
void	setBuffer(byte[] buf, int len) Sets the buffer.
void	setCount(int len) Set the number of valid bytes in the buffer.
void	setSize(int len) Sets the size of the buffer.
void	snap(boolean f) Displays the contents of this buffer if tracing is enabled.
protected char[]	toCharArray(java.math.BigDecimal big, int prec, int scale) Converts a BigDecimal object to a "numeric" string.
void	write(byte[] b, int off, int len) Writes len bytes from the specified byte array starting at offset off to the underlying output stream.
void	writeBoolean(boolean b) Writes a boolean to the data output stream.
void	writeByte(int v) Writes a byte to the data output stream.
void	writeBytes(java.lang.String str) Writes a string to a stream as an array of bytes.
void	writeBytes(java.lang.String str, int len) Writes a string to a stream as fixed length an array of bytes.
void	writeBytesInternal(java.lang.String str, int len) Writes an internal control block string to a stream as fixed length an array of bytes.
void	writeBytesVariable(java.lang.String str, int len) Writes an variable length string (VARCHAR) to a stream.
void	writeChar(int v) Writes a char to the data output stream.
void	writeChars(java.lang.String s) Writes a string to the data output stream as a sequence of Unicode characters.
void	writeDouble(double v) Converts the double argument to a long using the doubleToLongBits method in class Double, and then writes that long value to the underlying output stream as an 8-byte quantity, low byte first.
void	writeFloat(float v) Converts the float argument to an int using the floatToIntBits method in class Float, and then writes that int value to the underlying output stream as a 4-byte quantity, low byte first.
void	writeGraphic(java.lang.String s, int len) Writes a String as OS/390 DBCS data.
void	writeInt(int v) Writes an int to the data output stream.
void	writeLong(long v) Writes a long to the data output stream.
void	writeNulls(int len) Writes null bytes to a stream as filler.
void	writePacked(java.math.BigDecimal big, int prec, int scale, boolean signed) Writes a BigDecimal in "PACKED DECIMAL" format.
void	writeShort(int v) Writes a short to the data output stream.
void	writeUTF(java.lang.String s) Writes a string to the data output stream using UTF-8.
void	writeZoned(java.math.BigDecimal big, int prec, int scale, boolean signed) Write a BigDecimal in "ZONED DECIMAL" format.

Methods inherited from class java.io.FilterOutputStream

close, flush, write, write

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.io.DataOutput

write, write

Field Detail

dos

protected java.io.DataOutputStream dos

Contains the default methods.

fmt

protected NativeFormat fmt

Describes the native data formats.

Method Detail

setSize

public void setSize(int len)

Sets the size of the buffer.

Parameters:

len - new buffer size.

See Also:

TraceBufferOutputStream.setSize(int)

getFormat

public NativeFormat getFormat()

Returns:

the format specifier.

getBuffer

public byte[] getBuffer()

Gets the buffer.

Returns:

a reference to the underlying buffer.

See Also:

TraceBufferOutputStream.getBuffer()

setBuffer

public void setBuffer(byte[] buf,
                      int len)

Sets the buffer.

Parameters:

buf - the new buffer contents

len - the length of the array

See Also:

TraceBufferOutputStream.setBuffer(byte[], int)

getCount

public int getCount()

Gets the number of valid bytes in the buffer.

Returns:

the size() of the underlying buffer.

See Also:

TraceBufferOutputStream.getCount()

setCount

public void setCount(int len)

Set the number of valid bytes in the buffer.

Parameters:

len - new count, ignored if out of range

See Also:

TraceBufferOutputStream.setCount(int)

snap

public void snap(boolean f)

Displays the contents of this buffer if tracing is enabled.

See Also:

TraceBufferOutputStream.snap(boolean)

write

public void write(byte[] b,
                  int off,
                  int len)
           throws java.io.IOException

Writes len bytes from the specified byte array starting at offset off to the underlying output stream.

Specified by:

write in interface java.io.DataOutput

Overrides:

write in class java.io.FilterOutputStream

Parameters:

b - the data.

off - the start offset in the data.

len - the number of bytes to write.

Throws:

java.io.IOException - if an I/O error occurs.

writeBoolean

public void writeBoolean(boolean b)
                  throws java.io.IOException

Writes a boolean to the data output stream.

Specified by:

writeBoolean in interface java.io.DataOutput

Parameters:

b - a boolean value to be written.

Throws:

java.io.IOException

writeByte

public void writeByte(int v)
               throws java.io.IOException

Writes a byte to the data output stream.

Specified by:

writeByte in interface java.io.DataOutput

Parameters:

v - a byte value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeShort

public void writeShort(int v)
                throws java.io.IOException

Writes a short to the data output stream.

Specified by:

writeShort in interface java.io.DataOutput

Parameters:

v - a short to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeChar

public void writeChar(int v)
               throws java.io.IOException

Writes a char to the data output stream.

Specified by:

writeChar in interface java.io.DataOutput

Parameters:

v - a char value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeInt

public void writeInt(int v)
              throws java.io.IOException

Writes an int to the data output stream.

Specified by:

writeInt in interface java.io.DataOutput

Parameters:

v - an int to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeLong

public void writeLong(long v)
               throws java.io.IOException

Writes a long to the data output stream.

Specified by:

writeLong in interface java.io.DataOutput

Parameters:

v - a long to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeFloat

public void writeFloat(float v)
                throws java.io.IOException

Converts the float argument to an int using the floatToIntBits method in class Float, and then writes that int value to the underlying output stream as a 4-byte quantity, low byte first.

Specified by:

writeFloat in interface java.io.DataOutput

Parameters:

v - a float value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

Float.floatToIntBits(float)

writeDouble

public void writeDouble(double v)
                 throws java.io.IOException

Converts the double argument to a long using the doubleToLongBits method in class Double, and then writes that long value to the underlying output stream as an 8-byte quantity, low byte first.

Specified by:

writeDouble in interface java.io.DataOutput

Parameters:

v - a double value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

Double.doubleToLongBits(double)

writeBytes

public void writeBytes(java.lang.String str)
                throws java.io.IOException

Writes a string to a stream as an array of bytes. The String is converted according to the encoding specified by the NativeFormat object and written to the output stream. This overrides the deprecated writeBytes function in DataOutputStream and handles character encoding as a Writer class would.

Specified by:

writeBytes in interface java.io.DataOutput

Parameters:

str - String to convert

Throws:

java.io.UnsupportedEncodingException - if the character set encoding is not supported

java.io.IOException - if an IO error occurs

writeChars

public void writeChars(java.lang.String s)
                throws java.io.IOException

Writes a string to the data output stream as a sequence of Unicode characters.

Specified by:

writeChars in interface java.io.DataOutput

Parameters:

s - a String value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeUTF

public void writeUTF(java.lang.String s)
              throws java.io.IOException

Writes a string to the data output stream using UTF-8.

Specified by:

writeUTF in interface java.io.DataOutput

Parameters:

s - a String to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeBytes

public void writeBytes(java.lang.String str,
                       int len)
                throws java.io.IOException,
                       java.io.UnsupportedEncodingException,
                       DataTruncationException

Writes a string to a stream as fixed length an array of bytes. The String is converted according to the encoding specified by the NativeFormat object and written to the output stream, padded with spaces if needed.

Parameters:

str - String to convert

len - the length of the output in bytes

Throws:

DataTruncationException - if the result is truncated

java.io.UnsupportedEncodingException - if the character set encoding is not supported

java.io.IOException - if an IO error occurs

See Also:

NativeDataInputStream.readBytes(int)

writeBytesInternal

public void writeBytesInternal(java.lang.String str,
                               int len)
                        throws java.io.IOException,
                               java.io.UnsupportedEncodingException,
                               DataTruncationException

Writes an internal control block string to a stream as fixed length an array of bytes. The String is converted according to the internal control block encoding specified by the NativeFormat object and written to the output stream, padded with spaces if needed. When the "network" encoding is being used (UTF8 or Unicode) the string is converted "normally", that is, by the derived class method.

Parameters:

str - String to convert

len - the length of the output in bytes

Throws:

DataTruncationException - if the result is truncated

java.io.UnsupportedEncodingException - if the character set encoding is not supported

java.io.IOException - if an IO error occurs

See Also:

NativeDataInputStream.readBytesInternal(int)

writeBytesVariable

public void writeBytesVariable(java.lang.String str,
                               int len)
                        throws java.io.IOException,
                               java.io.UnsupportedEncodingException,
                               DataTruncationException

Writes an variable length string (VARCHAR) to a stream. as a two byte length, followed by a variable length array of bytes, padded with null bytes to aling the buffer. The String is converted according to the encoding specified by the NativeFormat object and written to the output stream, prefaced by the converted length and padded with nulls if needed. When the "network" encoding is being used (UTF8 or Unicode) the length is set as the number of characters in the string before conversion, and it is padded with spaces (which don't really matter).

Parameters:

str - String to convert

len - the length of the output in bytes

Throws:

DataTruncationException - if the result is truncated

java.io.UnsupportedEncodingException - if the character set encoding is not supported

java.io.IOException - if an IO error occurs

See Also:

NativeDataInputStream.readBytesInternal(int)

writeNulls

public void writeNulls(int len)
                throws java.io.IOException

Writes null bytes to a stream as filler.

Parameters:

len - number of bytes to send

Throws:

java.io.IOException - if an IO error occurs

writePacked

public void writePacked(java.math.BigDecimal big,
                        int prec,
                        int scale,
                        boolean signed)
                 throws DataTruncationException,
                        java.io.IOException

Writes a BigDecimal in "PACKED DECIMAL" format. The packed decimal format is used internally on IBM mainframe computers to do computations on decimal values, and is exposed to applications in databases as the DECIMAL type. The decimal values of two digits are packed in each byte, except the low order byte, which contains an encoding of the sign.

Parameters:

big - a BigDecimal value.

prec - total number of digits

scale - number of digits after the decimal

signed - true if type is signed

Throws:

DataTruncationException - if scale or precision exceeded

java.io.IOException - if an IO error occurs

See Also:

toCharArray(java.math.BigDecimal, int, int)

writeZoned

public void writeZoned(java.math.BigDecimal big,
                       int prec,
                       int scale,
                       boolean signed)
                throws DataTruncationException,
                       java.io.IOException

Write a BigDecimal in "ZONED DECIMAL" format. The zoned decimal format is used internally on IBM mainframe computers to store and display decimal values, and is exposed to applications in databases as the NUMERIC type. The decimal value of each digit is represented by character value for that digit in each byte, except the low order byte, which contains an encoding of the sign along with the low order digit.

Since zoned decimal is essentially a character format, the actual binary value written to the output stream depends on the encoding (but will be either ASCII or EBCDIC). Note that encoding the sign in the low order digit may make it a non numeric character.

The absolute value will be set if the type is UNSIGNED NUMERIC.

Parameters:

big - a BigDecimal value.

prec - total number of digits

scale - number of digits after the decimal

signed - true if type is signed

Throws:

java.io.UnsupportedEncodingException - not likely

DataTruncationException - if scale or precision exceeded

java.io.IOException - if an IO error occurs

toCharArray

protected char[] toCharArray(java.math.BigDecimal big,
                             int prec,
                             int scale)
                      throws DataTruncationException

Converts a BigDecimal object to a "numeric" string. This converts a BigDecimal object to an internal representation of a numeric value, used to write native packed and zoned decimal data. This representation consists of a character array with leading 0's to fill out the precision, the decimal point removed, and an explicit trailing sign (+/-).

Parameters:

big - a BigDecimal object.

prec - total number of digits

scale - number of digits after the decimal

Returns:

a "numeric" string.

Throws:

DataTruncationException - if scale or precision exceeded

See Also:

writePacked(java.math.BigDecimal, int, int, boolean), writeZoned(java.math.BigDecimal, int, int, boolean)

writeGraphic

public void writeGraphic(java.lang.String s,
                         int len)
                  throws DataTruncationException,
                         java.io.IOException

Writes a String as OS/390 DBCS data. This method converts the String encoding in effect for this stream. When this encoding in effect for this stream is some variant of EBCDIC, DBCS is assumed, and it also removes the SO and SI from the resulting byte array, converts any SBCS characters to "42nd ward" DBCS characters, and writes the result to the output stream.

The CharToByte converter classes for DBCS_EBCDIC convert a String to mixed SBCS and DBCS characters.

OS/390 databases support two types of DBCS data. The CHAR and VARCHAR types can contain mixed data, that is, SBCS EBCDIC with embedded sequences. The GRAPHIC and VARGRAPHIC (or equivalent) types contain only DBCS characters. The so called "42nd ward" of the DBCS character corresponds to the SBCS characters, where the first byte is X'42' and the second byte is the hexadecimal value of corresonding EBCDIC character. SO and SI are not used.

Parameters:

s - a String

len - number of characters defined for GRAPHIC column

Throws:

DataTruncationException - if it won't fit

java.io.IOException - if an IO error occurs

See Also:

writeBytes(java.lang.String), UtfDataOutputStream.writeBytes(java.lang.String), UnicodeDataOutputStream.writeBytes(java.lang.String), NativeFormat.getBytes(java.lang.String)