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

Interface ISequentialDataSet

All Superinterfaces:

IDataSet, IHostResource

public interface ISequentialDataSet
extends IDataSet

A sequential dataset that resides on a z/OS host.

For details on the state of an ISequentialDataSet and the function of its methods, see IHostResource.

Examples:
To allocate a sequential dataset:

 IDataSetCommandProvider commandProvider = ...
 String dataSetName = ...
 IAllocateParameters parameters = ...
 
 try {
     commandProvider.allocateSequentialDataSet(dataSetName, parameters);
 } catch (DataSetExistsException e) {
     // the dataset already exists
     ...
 } catch (AllocationFailedException e) {
     // the allocation failed - most likely because the user does not have the proper authority
     ...
 }
 

(Note: the above catch blocks can be replaced with a single catch block on HostResourceException.)

(Note: see AllocateParametersBuilder for examples of building allocate parameters.)

To retrieve a sequential dataset:

 IDataSetCommandProvider commandProvider = ...
 String dataSetName = ...
 
 // dataSet will be null if it cannot be found
 ISequentialDataSet dataSet = commandProvider
         .findSequentialDataSet(dataSetName);
 

To retrieve a list of sequential datasets matching a filter:

 IDataSetCommandProvider commandProvider = ...
 String dataSetFilter = ...
 
 // dataSets will be empty if no sequential datasets match the dataset
 // filter
 List<ISequentialDataSet> dataSets = commandProvider
         .findSequentialDataSets(dataSetFilter);
 

To retrieve a specific generation dataset of a generation data group, typed as an ISequentialDataSet, from an IDataSetCommandProvider:

 IDataSetCommandProvider commandProvider = ...
 String generationDataGroupName = ...
 int relativeGenerationNumber = ...
 
 // generationDataSet will be null if the generation data
 // group does not exist, or a generation sequential dataset does not
 // exist for the specified relative generation number
 ISequentialDataSet generationDataSet = commandProvider
         .findGenerationSequentialDataSet(generationDataGroupName,
                 relativeGenerationNumber);
 

To retrieve a specific generation dataset of a generation data group, typed as an ISequentialDataSet, from an IGenerationDataGroup:

 IGenerationDataGroup generationDataGroup = ...
 int relativeGenerationNumber = ...
 
 // generationDataSet will be null if a generation
 // sequential dataset does not exist for the specified relative
 // generation number
 ISequentialDataSet generationDataSet = generationDataGroup
         .findGenerationSequentialDataSet(relativeGenerationNumber);
 

To read a sequential dataset from an ISequentialDataSet:

 ISequentialDataSet sequentialDataSet = ...
 
 // create a BufferedReader wrapping a new DataSetReader using a
 // try-with-resources statement
 try (BufferedReader reader = new BufferedReader(new DataSetReader(
         sequentialDataSet))) {
     // read the sequential dataset data using the reader
     String record;
     while ((record = reader.readLine()) != null) {
         // note: non-displayable characters will be output as the
         // '�' (lozenge) character (displays as '?' in some
         // character sets)
         System.out.println(record);
     }
 } catch (DataSetAccessException e) {
     // the user does not have access to the sequential dataset
     ...
 } catch (DataSetInUseException e) {
     // the sequential dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the sequential dataset has been migrated since it was first
     // retrieved
     ...
 } catch (DataSetNotFoundException e) {
     // the sequential dataset can no longer be found
     ...
 } catch (IOException e) {
     // an IO error has occurred reading a line and/or closing the reader
     ...
 }
 

To read a sequential dataset using an IZOSHostConnection:

 IZOSHostConnection zosHostConnection = ...
 String sequentialDataSetName = ...
 
 // create a BufferedReader wrapping a new DataSetReader using a
 // try-with-resource statement
 try (BufferedReader reader = new BufferedReader(new DataSetReader(
         zosHostConnection, sequentialDataSetName))) {
     // read the sequential dataset data using the reader
     String record;
     while ((record = reader.readLine()) != null) {
         // note: non-displayable characters will be output as the
         // '�' (lozenge) character (displays as '?' in some
         // character sets)
         System.out.println(record);
     }
 } catch (DataSetAccessException e) {
     // the user does not have access to the sequential dataset
     ...
 } catch (DataSetInUseException e) {
     // the sequential dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the sequential dataset is migrated
     ...
 } catch (DataSetNotFoundException e) {
     // the sequential dataset could not be found or is not a sequential
     // dataset
     ...
 } catch (IOException e) {
     // an IO error has occurred reading a line and/or closing the reader
     ...
 }
 

To write to a sequential dataset from an ISequentialDataSet:

 String dataSetContents = ...
 ISequentialDataSet sequentialDataSet = ...
 
 // create a BufferedWriter wrapping a new DataSetWriter using a
 // try-with-resources statement
 try (BufferedWriter writer = new BufferedWriter(new DataSetWriter(
         sequentialDataSet))) {
     // write the sequential dataset using the writer
     writer.write(dataSetContents);
 } catch (DataSetAccessException e) {
     // the user does not have access to the sequential dataset
     ...
 } catch (DataSetInUseException e) {
     // the sequential dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the sequential dataset has been migrated since it was first
     // retrieved
     ...
 } catch (DataSetNotFoundException e) {
     // the sequential dataset can no longer be found
     ...
 } catch (IOException e) {
     // an IO error has occurred writing to the sequential dataset and/or closing the writer
     ...
 }
 

To write to a sequential dataset using an IZOSHostConnection:

 String dataSetContents = ...
 IZOSHostConnection zosHostConnection = ...
 String sequentialDataSetName = ...
 
 // create a BufferedWriter wrapping a new DataSetWriter using a
 // try-with-resource statement
 try (BufferedWriter writer = new BufferedWriter(new DataSetWriter(
         zosHostConnection, sequentialDataSetName))) {
     // write the sequential dataset data using the writer
     writer.write(dataSetContents);
 } catch (DataSetAccessException e) {
     // the user does not have access to the sequential dataset
     ...
 } catch (DataSetInUseException e) {
     // the sequential dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the sequential dataset is migrated
     ...
 } catch (DataSetNotFoundException e) {
     // the sequential dataset could not be found or is not a sequential
     // dataset
     ...
 } catch (IOException e) {
     // an IO error has occurred writing to the sequential dataset and/or closing the writer
     ...
 }
 

For examples on how to obtain an IDataSetCommandProvider, see IDataSetCommandProvider.
For examples of how to retrieve IDataSets, see IDataSet.
For examples of how to build allocate parameters, see AllocateParametersBuilder.
For examples on how to retrieve generation datasets, typed as an IDataSet, see IDataSet.

Since:

1.0.0

Version:

2.0.0

Restriction:

This interface is not intended to be extended by clients.

Restriction:

This interface is not intended to be implemented by clients.

Method Summary

Modifier and Type	Method	Description
ISequentialDataSetCharacteristics	fetchCharacteristics()	Fetches the characteristics of this sequential dataset from the z/OS host on which it resides.

Methods inherited from interface com.compuware.api.topaz.hostresources.zos.IDataSet

delete, getHostConnection, getType, isAlias

Methods inherited from interface com.compuware.api.topaz.hostresources.IHostResource

getName

Method Detail

fetchCharacteristics

ISequentialDataSetCharacteristics fetchCharacteristics()
                                                throws DataSetAccessException,
                                                       DataSetInUseException,
                                                       DataSetMigratedException,
                                                       DataSetNotFoundException

Fetches the characteristics of this sequential dataset from the z/OS host on which it resides.

The state of the sequential dataset characteristics returned from this method is a snapshot of these characteristics from the time this method is called. Any changes made to these characteristics after this method is called will not be reflected in any previously returned sequential dataset characteristics. This method may be called again to retrieve a current snapshot of the sequential dataset characteristics.

Specified by:

fetchCharacteristics in interface IDataSet

Returns:

the sequential dataset characteristics

Throws:

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 this sequential dataset

DataSetInUseException - if an exclusive enqueue exists on this sequential dataset

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

DataSetNotFoundException - if this 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