Package com.compuware.api.topaz.hostresources.zos

Class DataSetWriter

java.lang.Object

java.io.Writer

com.compuware.api.topaz.hostresources.zos.DataSetWriter

All Implemented Interfaces:

Closeable, Flushable, Appendable, AutoCloseable

public class DataSetWriter
extends Writer

Writes text to a z/OS dataset, providing for the efficient writing of characters.

When an instance is constructed, an exclusive enqueue will be obtained on the associated dataset. If an enqueue could not be obtained, an exception will be thrown.

The data written must be in UTF-8 encoding and will be encoded using the code page specified in the credentials of the associated host. If any binary characters were mapped to UTF-8 (see DataSetReader), they will be translated back to binary bytes. If unmappable characters are part of any write, an exception will be thrown and the text will not be written.

If the logical record length of the dataset is exceeded during any write, an exception will be thrown and the text will not be written.

When close is called, the data will be written on the host and the enqueue will be released.

For efficient writing of dataset records, it is advisable to wrap a BufferedWriter around a DataSetWriter. For example,

BufferedWriter out = new BufferedWriter(new DataSetWriter(...));

Regarding parameter validation for the methods within this class:

A dataset name is considered invalid if:

• The total length of the name is 0 or is greater than 44 characters.
• The length of any qualifier within the name is 0 or is greater than 8 characters.
• Qualifiers are delimited by anything other than a '.' character.
• Any characters outside of the code page 1047 hex values for A-Z, a-z, 0-9, @, #, $, or - are present.
• Any qualifier (and hence the name itself) starts with a digit (0-9) or a hyphen (-).

Since:

1.1.0

Version:

2.0.0

See Also:

ISequentialDataSet

Restriction:

This class is not intended to be extended by clients.

Constructor Summary

Constructors

Constructor	Description
DataSetWriter(IZOSHostConnection zosHostConnection, String sequentialDataSetName)	Constructs a DataSetWriter using the specified z/OS host connection and sequential dataset name.
DataSetWriter(ISequentialDataSet sequentialDataSet)	Constructs a DataSetWriter using the specified sequential dataset.

Method Summary

Modifier and Type	Method	Description
void	close()
void	flush()
void	write(char[] dataBuffer, int offset, int length)	Writes a portion of an array of characters.

Methods inherited from class java.io.Writer

append, append, append, nullWriter, write, write, write, write

Methods inherited from class java.lang.Object

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

Constructor Detail

DataSetWriter

public DataSetWriter(ISequentialDataSet sequentialDataSet)
              throws DataSetAccessException,
                     DataSetInUseException,
                     DataSetMigratedException,
                     DataSetNotFoundException

Constructs a DataSetWriter using the specified sequential dataset.

This dataset writer can be used to write UTF-8 characters to the specified sequential dataset. This is ideally used for writing displayable characters to a sequential dataset.

This constructor will attempt to obtain an exclusive enqueue on the specified sequential datatset.

Parameters:

sequentialDataSet - the sequential dataset to write to

Throws:

IllegalArgumentException - if sequentialDataSet is null

HostIOException - if an IOException occurs writing to the dataset

ZOSSystemException - if a z/OS system error occurs

ZOSAbendException - if a z/OS ABEND occurs

DataSetAccessException - if the user's credentials do not grant access authority for the sequential dataset

DataSetInUseException - if an exclusive enqueue exists on the sequential dataset

DataSetMigratedException - if the sequential dataset is migrated (this may occur if the dataset is migrated after it is retrieved from the z/OS host)

DataSetNotFoundException - if the sequential dataset no longer exists (this may occur if the dataset is deleted after it is retrieved from the z/OS host)

Since:

1.0.0

See Also:

ISequentialDataSet

DataSetWriter

public DataSetWriter(IZOSHostConnection zosHostConnection,
                     String sequentialDataSetName)
              throws DataSetAccessException,
                     DataSetInUseException,
                     DataSetMigratedException,
                     DataSetNotFoundException

Constructs a DataSetWriter using the specified z/OS host connection and sequential dataset name.

This dataset writer can be used to write UTF-8 characters to the specified sequential dataset. This is ideally used for writing displayable characters to a sequential dataset.

This constructor will attempt to obtain an exclusive enqueue on the specified sequential datatset.

Parameters:

zosHostConnection - a connection to the z/OS host on which the sequential dataset resides

sequentialDataSetName - the name of the sequential dataset to write to

Throws:

IllegalArgumentException - if zosHostConnection is null, or if sequentialDataSetName is null or invalid

HostIOException - if an IOException occurs writing to the sequential dataset

HostNotConnectedException - if zosHostConnection is not connected

ZOSSystemException - if a z/OS system error occurs

ZOSAbendException - if a z/OS ABEND occurs

DataSetAccessException - if the user's credentials do not grant access authority for the sequential dataset

DataSetInUseException - if an exclusive enqueue exists on the sequential dataset

DataSetMigratedException - if the sequential dataset is migrated

DataSetNotFoundException - if the sequential dataset does not exist

Since:

1.0.0

See Also:

IZOSHostConnection

Method Detail

write

public void write(char[] dataBuffer,
                  int offset,
                  int length)
           throws IOException

Writes a portion of an array of characters.

Specified by:

write in class Writer

Parameters:

dataBuffer - the array of characters

offset - the offset from which to start writing characters

length - the number of characters to write

Throws:

UnmappableCharacterException - if one or more UTF-8 characters exist in the given character buffer that do not map into the code page associated with the host

MalformedInputException - if non-displayable binary data exists in the given character buffer (x00 - x3F, shift-out (x0E) and shift-in (x0F) are not considered invalid for double-byte (DBCS) code pages)

LogicalRecordLengthExceededException - if the data will exceed the logical record length of the sequential dataset

IOException - if any other I/O error occurs

Since:

1.0.0

flush

public void flush()
           throws IOException

Specified by:

flush in interface Flushable

Specified by:

flush in class Writer

Throws:

IOException

Since:

1.0.0

close

public void close()
           throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Specified by:

close in class Writer

Throws:

IOException

Since:

1.0.0