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

Interface IPartitionedDataSetMember

  • All Superinterfaces:
    IHostResource, IMember
    public interface IPartitionedDataSetMember
extends IMember
    A partitioned dataset (PDS) member that resides on a z/OS host.

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

    Examples:
    To create a PDS member from an IDataSetCommandProvider: 

     IDataSetCommandProvider commandProvider = ...
 String pdsName = ...
 String memberName = ...
 
 try {
     commandProvider.createPDSMember(pdsName, memberName);
 
     ...
 } catch (DataSetAccessException e) {
     // the user does not have access to this dataset
     ...
 } catch (DataSetInUseException e) {
     // the dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the dataset is migrated
     ...
 } catch (DataSetNotFoundException e) {
     // the dataset could not be found or is not a PDS
     ...
 } catch (MemberAlreadyExistsException e) {
     // a member with the same name already exists in the PDS
     ...
 }
    (Note: the above catch blocks can be replaced with a single catch block on HostResourceException.)

    To create a PDS member from an IPartitionedDataSet: 

     IPartitionedDataSet pds = ...
 String memberName = ...
 
 try {
     pds.createMember(memberName);
 
     ...
 } catch (DataSetAccessException e) {
     // the user does not have access to this dataset
     ...
 } catch (DataSetInUseException e) {
     // the dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the dataset is migrated
     ...
 } catch (DataSetNotFoundException e) {
     // the dataset could not be found or is not a PDS
     ...
 } catch (MemberAlreadyExistsException e) {
     // a member with the same name already exists in the PDS
     ...
 }
    (Note: the above catch blocks can be replaced with a single catch block on HostResourceException.)

    To delete a PDS member from an IDataSetCommandProvider: 

     IDataSetCommandProvider commandProvider = ...
 String pdsName = ...
 String memberName = ...
 
 try {
     commandProvider.deletePDSMember(pdsName, memberName);
 
     ...
 } catch (DataSetAccessException e) {
     // the user does not have access to this dataset
     ...
 } catch (DataSetInUseException e) {
     // the dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the dataset is migrated
     ...
 } catch (DataSetNotFoundException e) {
     // the dataset could not be found or is not a PDS
     ...
 } catch (MemberInUseException e) {
     // the member is enqueued by another user or job
     ...
 } catch (MemberNotFoundException e) {
     // the member could not be found
     ...
 }
    (Note: the above catch blocks can be replaced with a single catch block on HostResourceException.)

    To delete a PDS member from an IPartitionedDataSet: 

     IPartitionedDataSet pds = ...
 String memberName = ...
 
 try {
     pds.deleteMember(memberName);
 
     ...
 } catch (DataSetAccessException e) {
     // the user does not have access to this dataset
     ...
 } catch (DataSetInUseException e) {
     // the dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the dataset is migrated
     ...
 } catch (DataSetNotFoundException e) {
     // the dataset could not be found or is not a PDS
     ...
 } catch (MemberInUseException e) {
     // the member is enqueued by another user or job
     ...
 } catch (MemberNotFoundException e) {
     // the member could not be found
     ...
 }
    (Note: the above catch blocks can be replaced with a single catch block on HostResourceException.)

    To retrieve a PDS member from an IDataSetCommandProvider: 

     IDataSetCommandProvider commandProvider = ...
 String pdsName = ...
 String memberName = ...
 
 try {
     // pdsMember will be null if it cannot be found
     IPartitionedDataSetMember pdsMember = commandProvider
             .findPDSMember(pdsName, memberName);
 
     ...
 } catch (DataSetAccessException e) {
     // the user does not have access to this dataset
     ...
 } catch (DataSetInUseException e) {
     // the dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the dataset is migrated
     ...
 } catch (DataSetNotFoundException e) {
     // the dataset could not be found or is not a PDS
     ...
 }
    (Note: the above catch blocks can be replaced with a single catch block on HostResourceException.)

    To retrieve a PDS member from an IPartitionedDataSet: 

     IPartitionedDataSet pds = ...
 String memberName = ...
 
 try {
     // pdsMember will be null if it cannot be found
     IPartitionedDataSetMember pdsMember = pds.findMember(memberName);
 
     ...
 } catch (DataSetAccessException e) {
     // the user does not have access to this dataset
     ...
 } catch (DataSetInUseException e) {
     // the dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the dataset has been migrated since it was first retrieved
     ...
 } catch (DataSetNotFoundException e) {
     // the dataset can no longer be found
     ...
 }
    (Note: the above catch blocks can be replaced with a single catch block on HostResourceException.)

    To retrieve a list of PDS member matching a filter from an IDataSetCommandProvider: 

     IDataSetCommandProvider commandProvider = ...
 String pdsName = ...
 String memberFilter = ...
 
 try {
     // pdsMembers will be empty if no PDS members match the member
     // filter
     List<IPartitionedDataSetMember> pdsMembers = commandProvider
             .findPDSMembers(pdsName, memberFilter);
 
     ...
 } catch (DataSetAccessException e) {
     // the user does not have access to this dataset
     ...
 } catch (DataSetInUseException e) {
     // the dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the dataset is migrated
     ...
 } catch (DataSetNotFoundException e) {
     // the dataset could not be found or is not a PDS
     ...
 }
    (Note: the above catch blocks can be replaced with a single catch block on HostResourceException.)

    To retrieve a list of PDS members matching a filter from an IPartitionedDataSet: 

     IPartitionedDataSet pds = ...
 String memberFilter = ...
 
 try {
     // pdsMembers will be empty if no PDS members match the member
     // filter
     List<IPartitionedDataSetMember> pdsMembers = pds
             .findMembers(memberFilter);
 } catch (DataSetAccessException e) {
     // the user does not have access to this dataset
     ...
 } catch (DataSetInUseException e) {
     // the dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the dataset has been migrated since it was first retrieved
     ...
 } catch (DataSetNotFoundException e) {
     // the dataset can no longer be found
     ...
 }
    (Note: the above catch blocks can be replaced with a single catch block on HostResourceException.)

    To read a partitioned dataset member from an IPartitionedDataSetMember: 

     IPartitionedDataSetMember partitionedDataSetMember = ...
 
 // create a BufferedReader wrapping a new MemberReader using a
 // try-with-resource statement
 try (BufferedReader reader = new BufferedReader(new MemberReader(
         partitionedDataSetMember))) {
     // read the partitioned dataset member 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 partitioned dataset
     ...
 } catch (DataSetInUseException e) {
     // the partitioned dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the partitioned dataset has been migrated since it was first
     // retrieved
     ...
 } catch (DataSetNotFoundException e) {
     // the partitioned dataset can no longer be found
     ...
 } catch (MemberNotFoundException e) {
     // the partitioned dataset member can no longer be found
     ...
 } catch (IOException e) {
     // an IO error has occurred reading a line and/or closing the reader
     ...
 }
    To read a partitioned dataset member using an IZOSHostConnection: 
     IZOSHostConnection zosHostConnection = ...
 String pdsName = ...
 String memberName = ...
 
 // create a BufferedReader wrapping a new MemberReader using a
 // try-with-resource statement
 try (BufferedReader reader = new BufferedReader(new MemberReader(
         zosHostConnection, pdsName, memberName))) {
     // read the partitioned dataset member 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 partitioned dataset
     ...
 } catch (DataSetInUseException e) {
     // the partitioned dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the partitioned dataset is migrated
     ...
 } catch (DataSetNotFoundException e) {
     // the partitioned dataset could not be found or is not a
     // partitioned dataset
     ...
 } catch (MemberNotFoundException e) {
     // the partitioned dataset member could not be found
     ...
 } catch (IOException e) {
     // an IO error has occurred reading a line and/or closing the reader
     ...
 }

    To write to a partitioned dataset member from an IPartitionedDataSetMember: 

     String memberContents = ...
 IPartitionedDataSetMember partitionedDataSetMember = ...
 
 // create a BufferedWriter wrapping a new MemberWriter using a
 // try-with-resource statement
 try (BufferedWriter writer = new BufferedWriter(new MemberWriter(
         partitionedDataSetMember))) {
     // write to the partitioned dataset member data using the writer
     writer.write(memberContents);
 } catch (DataSetAccessException e) {
     // the user does not have access to the partitioned dataset
     ...
 } catch (DataSetInUseException e) {
     // the partitioned dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the partitioned dataset has been migrated since it was first
     // retrieved
     ...
 } catch (DataSetNotFoundException e) {
     // the partitioned dataset can no longer be found
     ...
 } catch (MemberNotFoundException e) {
     // the partitioned dataset member can no longer be found
     ...
 } catch (MemberInUseException e) {
     // the partitioned dataset member is enqueued by another user or job
     ...
 } catch (IOException e) {
     // an IO error has occurred writing to the partitioned dataset member and/or closing the writer
     ...
 }
    To write to a partitioned dataset member using an IZOSHostConnection: 
     IZOSHostConnection zosHostConnection = ...
 String pdsName = ...
 String memberName = ...
 
 // create a BufferedWriter wrapping a new MemberWriter using a
 // try-with-resource statement
 try (BufferedWriter writer = new BufferedWriter(new MemberWriter(
         zosHostConnection, pdsName, memberName))) {
     // write the partitioned dataset member data using the writer
     writer.write(memberContents);
 } catch (DataSetAccessException e) {
     // the user does not have access to the partitioned dataset
     ...
 } catch (DataSetInUseException e) {
     // the partitioned dataset is enqueued by another user or job
     ...
 } catch (DataSetMigratedException e) {
     // the partitioned dataset is migrated
     ...
 } catch (DataSetNotFoundException e) {
     // the partitioned dataset could not be found or is not a
     // partitioned dataset
     ...
 } catch (MemberNotFoundException e) {
     // the partitioned dataset member could not be found
     ...
 } catch (MemberInUseException e) {
     // the partitioned dataset member is enqueued by another user or job
     ...
 } catch (IOException e) {
     // an IO error has occurred writing to the partitioned dataset member and/or closing the writer
     ...
 }

    For examples on how to obtain an IDataSetCommandProvider see IDataSetCommandProvider.
    For examples on how to retrieve IPartitionedDataSets see IPartitionedDataSet.

    Since:
    1.0.0
    Version:
    2.0.0
    See Also:
    MemberReader, MemberWriter
    Restriction:
    This interface is not intended to be extended by clients.
    Restriction:
    This interface is not intended to be implemented by clients.

    • Method Detail

      • getDataSet

        IPartitionedDataSet getDataSet()
        Returns the dataset that this member is part of.
        Specified by:
        getDataSet in interface IMember
        Returns:
        the partitioned dataset
        Since:
        1.0.0

      • fetchStatistics

        IPartitionedDataSetMemberStatistics fetchStatistics()
                                             throws DataSetAccessException,
                                                    DataSetInUseException,
                                                    DataSetMigratedException,
                                                    DataSetNotFoundException,
                                                    MemberNotFoundException
        Fetches the partitioned dataset member statistics of this partitioned dataset member from the z/OS host on which it resides.

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

        Returns:
        the partitioned dataset member statistics
        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 partitioned dataset
        DataSetInUseException - if an exclusive enqueue exists on this 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 this 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