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

Class MemberReader

java.lang.Object

java.io.Reader

com.compuware.api.topaz.hostresources.zos.MemberReader

All Implemented Interfaces:

Closeable, AutoCloseable, Readable

public final class MemberReader
extends Reader

Reads text from a z/OS member, providing for the efficient reading of characters.

The entire content of the member will be obtained at the moment the MemberReader is constructed and stored in a temporary file. Therefore, any reads done on that MemberReader object will reflect the content of the member at the moment the MemberReader object was constructed, rather than the content of the member at the moment the of read. When close is called, the temporary file will be deleted.

The text returned will be in UTF-8 encoding. Non-displayable binary data will be substituted with Unicode characters that are outside of the code page of the mainframe host login. This allows us to distinguish text data from binary within UTF-8, and if the data is written back to the mainframe using a MemberWriter, those Unicode characters will be replaced with the corresponding binary bytes.

For efficient reading of member records, it is advisable to wrap a BufferedReader around a MemberReader. For example,

BufferedReader in = new BufferedReader(new MemberReader(...));

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.0.0

Version:

2.0.0

See Also:

IPartitionedDataSetMember

Restriction:

This class is not intended to be extended by clients.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
void	close()
boolean	containsNonDisplayableData()	Returns whether non-displayable binary data exists within the text of this reader.
char	getReplacementCharacter()	Returns the replacement character for non-displayable binary data.
int	read(char[] dataBuffer, int offset, int length)

Methods inherited from class java.io.Reader

mark, markSupported, nullReader, read, read, read, ready, reset, skip, transferTo

Methods inherited from class java.lang.Object

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

Constructor Detail

MemberReader

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

Constructs a MemberReader using the specified partitioned dataset member.

This member reader can be used to read the content of the specified partitioned dataset member in UTF-8 characters. This is ideally used for reading partitioned dataset members that contain displayable characters.

Non-displayable binary data will be substituted with a replacement character for display purposes.

Parameters:

pdsMember - the partitioned dataset member to read

Throws:

IllegalArgumentException - if pdsMember is null

HostIOException - if an IOException occurs reading 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)

Since:

1.0.0

See Also:

IPartitionedDataSetMember

MemberReader

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

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

This member reader can be used to read the content of the specified partitioned dataset member in UTF-8 characters. This is ideally used for reading partitioned dataset members that contain displayable characters.

Non-displayable binary data will be substituted with a replacement character for display purposes.

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 read

Throws:

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

HostIOException - if an IOException occurs reading 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

Since:

1.0.0

See Also:

IZOSHostConnection

Method Detail

containsNonDisplayableData

public boolean containsNonDisplayableData()

Returns whether non-displayable binary data exists within the text of this reader.

Non-displayable binary data is substituted with the replacement character for display purposes.

Returns:

true if non-displayable binary data exists, false otherwise

Since:

1.0.0

See Also:

getReplacementCharacter()

getReplacementCharacter

public char getReplacementCharacter()

Returns the replacement character for non-displayable binary data.

The replacement character is uFFFD (a lozenge).

Returns:

the replacement character

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 Reader

Throws:

IOException

Since:

1.0.0

read

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

Specified by:

read in class Reader

Throws:

IOException

Since:

1.0.0