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

Class AllocateParametersBuilder

java.lang.Object

com.compuware.api.topaz.hostresources.zos.AllocateParametersBuilder

public class AllocateParametersBuilder
extends Object

Builder class used to create instances of IAllocateParameters.

This builder can be used to create allocation parameters based off of an existing dataset, or to create them based off of default parameters.

The following steps should be used to create an instance of IAllocateParameters:

• call one of the static methods of this class to create a builder instance
• optionally, call any of this builder's setter methods to specify alternate values
• call this builder's build() method to create the IAllocateParameters instance

Examples:
To create allocate parameters based off of an existing dataset:

 // note: the dataset may also be an ISequentialDataSet
 IPartitionedDataSet dataset = ...
 
 try {
     IAllocateParameters parameters = AllocateParametersBuilder.like(dataset).build();
 } catch (DataSetInUseException e1) {
     // the dataset is enqueued by another user or job
     ...
 } catch (DataSetNotFoundException e1) {
     // the dataset can no longer be found
     ...
 } catch (DataSetAccessException e1) {
     // the user does not have access to this dataset
     ...
 } catch (DataSetMigratedException e1) {
     // the dataset has been migrated since it was first retrieved
     ...
 }
 

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

To create allocate parameters based off of an existing dataset while overriding some parameters:

 // note: the dataset may also be an ISequentialDataSet
 IPartitionedDataSet dataset = ...
 
 try {
     IAllocateParameters parameters = AllocateParametersBuilder.like(dataset)
             .setRecordFormat(RecordFormat.VB).setLogicalRecordLength(120)
             .setBlockSize(124).build();
 
     // alternatively:
 
     AllocateParametersBuilder builder = AllocateParametersBuilder.like(dataset);
     builder.setRecordFormat(RecordFormat.VB);
     builder.setLogicalRecordLength(120);
     builder.setBlockSize(124);
     IAllocateParameters parameters2 = builder.build();
 } catch (DataSetInUseException e1) {
     // the dataset is enqueued by another user or job
     ...
 } catch (DataSetNotFoundException e1) {
     // the dataset can no longer be found
     ...
 } catch (DataSetAccessException e1) {
     // the user does not have access to this dataset
     ...
 } catch (DataSetMigratedException e1) {
     // the dataset has been migrated since it was first retrieved
     ...
 }
 

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

To create allocate parameters for a partitioned dataset based off of defaults:

 IAllocateParameters parameters = AllocateParametersBuilder.partitionedDefaults(true)
         .setAllocationUnit(IAllocateParameters.AllocationUnit.CYLINDERS)
         .setPrimaryQuantity(5).setSecondaryQuantity(2).build();
 
 // alternatively:
 
 AllocateParametersBuilder builder = AllocateParametersBuilder.partitionedDefaults(true);
 builder.setAllocationUnit(IAllocateParameters.AllocationUnit.CYLINDERS);
 builder.setPrimaryQuantity(5);
 builder.setSecondaryQuantity(2);
 IAllocateParameters parameters2 = builder.build();
 

To create allocate parameters for a sequential dataset based off of defaults:

 IAllocateParameters parameters = AllocateParametersBuilder.sequentialDefaults()
         .setAllocationUnit(IAllocateParameters.AllocationUnit.CYLINDERS)
         .setPrimaryQuantity(5).setSecondaryQuantity(2).build();
 
 // alternatively:
 
 AllocateParametersBuilder builder = AllocateParametersBuilder.sequentialDefaults();
 builder.setAllocationUnit(IAllocateParameters.AllocationUnit.CYLINDERS);
 builder.setPrimaryQuantity(5);
 builder.setSecondaryQuantity(2);
 IAllocateParameters parameters2 = builder.build();
 

For examples on how to allocate IPartitionedDataSets see IPartitionedDataSet.
For examples on how to allocate ISequentialDataSets see ISequentialDataSet.

Since:

1.1.0

Version:

2.0.0

See Also:

IDataSetCommandProvider.allocatePartitionedDataSet(String, IAllocateParameters), IDataSetCommandProvider.allocateSequentialDataSet(String, IAllocateParameters)

Method Summary

Modifier and Type	Method	Description
IAllocateParameters	build()	Builds an instance of IAllocateParameters as configured by this builder.
static AllocateParametersBuilder	like(IPartitionedDataSet partitionedDataSet)	Creates an allocate parameters builder instance and sets the parameters based on the specified partitioned dataset.
static AllocateParametersBuilder	like(ISequentialDataSet sequentialDataSet)	Creates an allocate parameters builder instance and sets the parameters based on the specified sequential dataset.
static AllocateParametersBuilder	partitionedDefaults(boolean isExtended)	Creates an allocate parameters builder instance for a partitioned dataset with default parameters.
static AllocateParametersBuilder	sequentialDefaults()	Creates an allocate parameters builder instance for a sequential dataset with default parameters.
AllocateParametersBuilder	setAllocationUnit(IAllocateParameters.AllocationUnit allocationUnit)	Sets the allocation unit.
AllocateParametersBuilder	setBlockSize(int blockSize)	Sets the block size.
AllocateParametersBuilder	setDataClass(String dataClass)	Sets the data class.
AllocateParametersBuilder	setDeviceType(String deviceType)	Sets the device type.
AllocateParametersBuilder	setDirectoryBlocks(int directoryBlocks)	Sets the directory blocks.
AllocateParametersBuilder	setExpirationDate(int year, int month, int day)	Sets the expiration date.
AllocateParametersBuilder	setExpirationDate(Date expirationDate)	Sets the expiration date.
AllocateParametersBuilder	setLogicalRecordLength(int logicalRecordLength)	Sets the logical record length.
AllocateParametersBuilder	setManagementClass(String managementClass)	Sets the management class.
AllocateParametersBuilder	setPrimaryQuantity(int primaryQuantity)	Sets the primary quantity.
AllocateParametersBuilder	setRecordFormat(RecordFormat recordFormat)	Sets the record format.
AllocateParametersBuilder	setSecondaryQuantity(int secondaryQuantity)	Sets the secondary quantity.
AllocateParametersBuilder	setStorageClass(String storageClass)	Sets the storage class.
AllocateParametersBuilder	setVolume(String volume)	Sets the volume.

Methods inherited from class java.lang.Object

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

Method Detail

like

public static AllocateParametersBuilder like(IPartitionedDataSet partitionedDataSet)
                                      throws DataSetInUseException,
                                             DataSetNotFoundException,
                                             DataSetAccessException,
                                             DataSetMigratedException

Creates an allocate parameters builder instance and sets the parameters based on the specified partitioned dataset.

Parameters:

partitionedDataSet - the partitioned dataset to copy parameters from

Returns:

a new allocate parameters builder

Throws:

ZOSSystemException - if a z/OS system error occurs

ZOSAbendException - if a z/OS ABEND occurs

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

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

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

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

Since:

1.1.0

like

public static AllocateParametersBuilder like(ISequentialDataSet sequentialDataSet)
                                      throws DataSetInUseException,
                                             DataSetNotFoundException,
                                             DataSetAccessException,
                                             DataSetMigratedException

Creates an allocate parameters builder instance and sets the parameters based on the specified sequential dataset.

Parameters:

sequentialDataSet - the sequential dataset to copy parameters from

Returns:

a new allocate parameters builder

Throws:

ZOSSystemException - if a z/OS system error occurs

ZOSAbendException - if a z/OS ABEND occurs

DataSetInUseException - if an exclusive enqueue exists on the specified sequential dataset

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

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

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

Since:

1.1.0

partitionedDefaults

public static AllocateParametersBuilder partitionedDefaults(boolean isExtended)

Creates an allocate parameters builder instance for a partitioned dataset with default parameters.

The builder created by this method will have its parameters set to the following values:

• allocation unit: TRACKS
• primary quantity: 2
• secondary quantity: 0
• directory blocks: 50 for non-extended partitioned datasets, unspecified for extended partitioned datasets
• record format: fixed-length, blocked (FB)
• logical record length: 80 for fixed-length and variable-length record formats, undefined for undefined-length record formats
• block size: 27920 for undefined-length record formats, determined by z/OS host for other record formats
• expiration date: no expiration
• management class: determined by z/OS host
• storage class: determined by z/OS host
• data class: determined by z/OS host
• volume: determined by z/OS host
• device type: determined by z/OS host

Parameters:

isExtended - true to create a builder for an extended partitioned dataset (PDSE), false to create one for a regular partitioned dataset (PDS)

Returns:

a new allocate parameters builder

Since:

1.1.0

sequentialDefaults

public static AllocateParametersBuilder sequentialDefaults()

Creates an allocate parameters builder instance for a sequential dataset with default parameters.

The builder created by this method will have its parameters set to the following values:

• allocation unit: TRACKS
• primary quantity: 2
• secondary quantity: 0
• record format: fixed-length, blocked (FB)
• logical record length: 80 for fixed-length and variable-length record formats, undefined for undefined-length record formats
• block size: 27920 for undefined-length record formats, determined by z/OS host for other record formats
• expiration date: no expiration
• management class: determined by z/OS host
• storage class: determined by z/OS host
• data class: determined by z/OS host
• volume: determined by z/OS host
• device type: determined by z/OS host

Returns:

a new allocate parameters builder

Since:

1.1.0

build

public IAllocateParameters build()

Builds an instance of IAllocateParameters as configured by this builder.

If any of the configured parameters are incompatible with each other, this method will throw an IllegalStateException.

The following incompatibilities will throw an illegal state exception:

• a logical record length is specified for an undefined-length record format (U, UA, or UM)
• the logical record length is less than 5 for variable-length with American Standards Association print-control characters or machine print-control characters (VA, VM, VBA, or VBM)
• a non-default block size is specified and:
  • the block size does not equal the logical record length for fixed-length, non-blocked record types (F, FA, or FM)
  • the block size is not a multiple of the logical record length for fixed-length, blocked record types (FB, FBA, FBM, or FBS)
  • the block size is not at least 4 greater than the logical record length for variable-length, non-spanned record types (V, VA, VB, VBA, VBM, or VM)

Returns:

the allocate parameters

Throws:

IllegalStateException - if any parameters are incompatible with each other

Since:

1.1.0

setAllocationUnit

public AllocateParametersBuilder setAllocationUnit(IAllocateParameters.AllocationUnit allocationUnit)

Sets the allocation unit.

The default is TRACKS.

Parameters:

allocationUnit - the allocation unit

Returns:

this allocation parameters builder to allow for method chaining

Since:

1.1.0

setPrimaryQuantity

public AllocateParametersBuilder setPrimaryQuantity(int primaryQuantity)

Sets the primary quantity.

The valid range is 1 - 999999.

The default is 2.

Parameters:

primaryQuantity - the primary quantity

Returns:

this allocation parameters builder to allow for method chaining

Throws:

IllegalArgumentException - if the primary quantity is outside of the valid range

Since:

1.1.0

setSecondaryQuantity

public AllocateParametersBuilder setSecondaryQuantity(int secondaryQuantity)

Sets the secondary quantity.

The valid range is 0 - 999999.

The default is 0.

Parameters:

secondaryQuantity - the secondary quantity

Returns:

this allocation parameters builder to allow for method chaining

Throws:

IllegalArgumentException - if the secondary quantity is outside of the valid range

Since:

1.1.0

setDirectoryBlocks

public AllocateParametersBuilder setDirectoryBlocks(int directoryBlocks)

Sets the directory blocks.

Directory blocks are only valid for non-extended partitioned datasets with a range of 1 - 9999.

The default is 50.

Parameters:

directoryBlocks - the directory blocks

Returns:

this allocation parameters builder to allow for method chaining

Throws:

IllegalStateException - if this method is called for extended partitioned or sequential datasets

IllegalArgumentException - if the directory blocks is outside of the valid range

Since:

1.1.0

setRecordFormat

public AllocateParametersBuilder setRecordFormat(RecordFormat recordFormat)

Sets the record format.

For sequential datasets, any record format other than NOT_RECOGNIZED is valid.

For partitioned datasets, any record format other than NOT_RECOGNIZED, FBS, and VBS is valid.

The default is FB.

Parameters:

recordFormat - the record format

Returns:

this allocation parameters builder to allow for method chaining

Throws:

IllegalArgumentException - if an invalid record format is specified

Since:

1.1.0

See Also:

RecordFormat

setLogicalRecordLength

public AllocateParametersBuilder setLogicalRecordLength(int logicalRecordLength)

Sets the logical record length.

The valid range is 1 - 32760.

For fixed-length and variable-length record formats, the default is 80. For undefined-length record formats, the logical record length is undefined.

Parameters:

logicalRecordLength - the logical record length

Returns:

this allocation parameters builder to allow for method chaining

Throws:

IllegalArgumentException - if the logical record length is outside of the valid range

Since:

1.1.0

setBlockSize

public AllocateParametersBuilder setBlockSize(int blockSize)

Sets the block size.

The valid range is 1 - 32760.

For undefined-length record formats, the default is 27920.

For fixed-length and variable-length record formats, the default is to let the z/OS host determine the block size.

Parameters:

blockSize - the block size

Returns:

this allocation parameters builder to allow for method chaining

Throws:

IllegalArgumentException - if the block size is outside of the valid range

Since:

1.1.0

setExpirationDate

public AllocateParametersBuilder setExpirationDate(Date expirationDate)

Sets the expiration date.

Any future date (any date later than today's date) is valid.

The default is for no expiration date.

Parameters:

expirationDate - the expiration date

Returns:

this allocation parameters builder to allow for method chaining

Throws:

IllegalArgumentException - if the date is today or earlier

Since:

1.1.0

setExpirationDate

public AllocateParametersBuilder setExpirationDate(int year,
                                                   int month,
                                                   int day)

Sets the expiration date.

Any future date (any date later than today's date) is valid.

The default is for no expiration date.

Parameters:

year - the 4-digit year

month - the month

day - the day of the month

Returns:

this allocation parameters builder to allow for method chaining

Throws:

IllegalArgumentException - if the date is today or earlier or is an invalid date

Since:

1.1.0

setManagementClass

public AllocateParametersBuilder setManagementClass(String managementClass)

Sets the management class.

The management class cannot exceed 8 characters.

The default is to let the z/OS host determine the management class.

Parameters:

managementClass - the management class

Returns:

this allocation parameters builder to allow for method chaining

Throws:

IllegalArgumentException - if the management class exceeds 8 characters

Since:

1.1.0

setStorageClass

public AllocateParametersBuilder setStorageClass(String storageClass)

Sets the storage class.

The storage class cannot exceed 8 characters.

The default is to let the z/OS host determine the storage class.

Parameters:

storageClass - the storage class

Returns:

this allocation parameters builder to allow for method chaining

Throws:

IllegalArgumentException - if the storage class exceeds 8 characters

Since:

1.1.0

setDataClass

public AllocateParametersBuilder setDataClass(String dataClass)

Sets the data class.

The data class cannot exceed 8 characters.

The default is to let the z/OS host determine the data class.

Parameters:

dataClass - the data class

Returns:

this allocation parameters builder to allow for method chaining

Throws:

IllegalArgumentException - if the data class exceeds 8 characters

Since:

1.1.0

setVolume

public AllocateParametersBuilder setVolume(String volume)

Sets the volume.

The volume cannot exceed 6 characters.

The default is to let the z/OS host determine the volume.

Parameters:

volume - the volume

Returns:

this allocation parameters builder to allow for method chaining

Throws:

IllegalArgumentException - if the volume exceeds 6 characters

Since:

1.1.0

setDeviceType

public AllocateParametersBuilder setDeviceType(String deviceType)

Sets the device type.

The device type cannot exceed 8 characters.

The default is to let the z/OS host determine the device type.

Parameters:

deviceType - the device type

Returns:

this allocation parameters builder to allow for method chaining

Throws:

IllegalArgumentException - if the device type exceeds 8 characters

Since:

1.1.0