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

Class MemberWriter

java.lang.Object

java.io.Writer

com.compuware.api.topaz.hostresources.zos.MemberWriter

All Implemented Interfaces:

Closeable, Flushable, Appendable, AutoCloseable

public class MemberWriter
extends Writer

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

When an instance is constructed, an exclusive enqueue will be obtained on the associated member. 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 member records, it is advisable to wrap a BufferedWriter around a MemberWriter. For example,

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

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

A PDS member name is considered invalid if:

• The length of the name is 0 or is greater than 8 characters.
• Any characters outside of the code page 1047 hex values for A-Z, a-z, 0-9, @, #, or $ are present.
• The name starts with a digit (0-9).

Since:

1.1.0

Version:

2.0.0

See Also:

IPartitionedDataSetMember

Restriction:

This class is not intended to be extended by clients.

Constructor Summary

Constructors

Constructor	Description
MemberWriter(IZOSHostConnection zosHostConnection, String pdsName, String memberName)	Constructs a MemberWriter using the specified z/OS host connection, partitioned dataset name, and member name.
MemberWriter(IPartitionedDataSetMember pdsMember)	Constructs a MemberWriter using the specified partitioned dataset member.

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

MemberWriter

public MemberWriter(IPartitionedDataSetMember pdsMember)
             throws DataSetAccessException,
                    DataSetInUseException,
                    DataSetMigratedException,
                    DataSetNotFoundException,
                    MemberNotFoundException,
                    MemberInUseException

Constructs a MemberWriter using the specified partitioned dataset member.

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

This constructor will attempt to obtain an exclusive enqueue on the specified partitioned dataset member.

Parameters:

pdsMember - the partitioned dataset member to write to

Throws:

IllegalArgumentException - if pdsMember is null

HostIOException - if an IOException occurs writing to the partitioned dataset member

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 parent partitioned dataset

DataSetInUseException - if an exclusive enqueue exists on the parent partitioned dataset

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

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

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

MemberInUseException - if an exclusive enqueue exists on the partitioned dataset member

Since:

1.0.0

See Also:

IPartitionedDataSetMember

MemberWriter

public MemberWriter(IZOSHostConnection zosHostConnection,
                    String pdsName,
                    String memberName)
             throws DataSetAccessException,
                    DataSetInUseException,
                    DataSetMigratedException,
                    DataSetNotFoundException,
                    MemberNotFoundException,
                    MemberInUseException

Constructs a MemberWriter using the specified z/OS host connection, partitioned dataset name, and member name.

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

This constructor will attempt to obtain an exclusive enqueue on the specified partitioned dataset member.

Parameters:

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

pdsName - the name of the partitioned dataset

memberName - the name of the member to write to

Throws:

IllegalArgumentException - if zosHostConnection is null, if pdsName is null or invalid, or if memberName is null or invalid

HostIOException - if an IOException occurs writing to the partitioned 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 partitioned dataset

DataSetInUseException - if an exclusive enqueue exists on the partitioned dataset

DataSetMigratedException - if the partitioned dataset is migrated

DataSetNotFoundException - if the partitioned dataset does not exist

MemberNotFoundException - if the partitioned dataset member does not exist

MemberInUseException - if an exclusive enqueue exists on the partitioned dataset member

Since:

1.0.0

See Also:

IPartitionedDataSetMember

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