Code Snippets

The following scenarios contain a brief description as well as one or more code snippets pertinent to the scenario:

Obtaining one or more Defined z/OS Hosts

In order to connect to a z/OS host, one or more defined z/OS hosts must first be obtained.

To obtain a list of all defined z/OS hosts:

// get a IHostManager
IHostManager hostManager = HostServicesAPI.getInstance().getHostManager();

// get all defined hosts, an empty list is returned if none are defined
List<IZOSHost> zosHostList = hostManager.getZOSHosts();

To obtain a single z/OS host:

String host = ...
int port = ...

// get a IHostManager
IHostManager hostManager = HostServicesAPI.getInstance().getHostManager();

// find z/OS host, null is returned if this host is not defined
IZOSHost zosHost = hostManager.findZOSHost(host, port);

Connecting to a z/OS Host for Dataset or JES API Usage

In order to use the dataset or JES APIs on a defined z/OS host, a connection to that z/OS host must first be established.

To connect to a z/OS host for dataset or JES API usage:

IZOSHost zosHost = ...
String userID = ...
String password = ...

// use one of the several ZOSCredentialsFactory methods to get a z/OS credentials object
IZOSCredentials credentials = ZOSCredentialsFactory.createZOSCredentials(userID, password);

// create a connection from the z/OS host
IZOSHostConnection zosHostConnection = zosHost.createZOSHostConnection();

try {
	// connect to the host
	zosHostConnection.connect(credentials);
	
	// the connection is now available for use
	...
} catch (HostCredentialsException e) {
	// credentials were invalid, likely caused by incorrect login information or expired password
	...
}

Alternatively, you may connect to a z/OS host by using the credentials of the currently logged in UI user (this requires the use of the com.compuware.api.hostservices.ui bundle):

IZOSHost zosHost = ...

// make sure we have access to the UI user's credentials (either saved credentials, or the UI user is currently logged in)
if (!zosHost.hasUIUserCredentials())
{
	// connect the UI user so we can access their credentials (user will be presented with a login dialog)
	zosHost.connectUIUser();
}

// we should have the UI user's credentials now, unless they cancelled the login dialog
if (zosHost.hasUIUserCredentials())
{
	// get UI user's z/OS credentials
	IZOSCredentials credentials = zosHost.getUIUserCredentials();

	try
	{
		// create a connection from the z/OS host
		IZOSHostConnection zosHostConnection = zosHost.createZOSHostConnection();

		// connect to the host
		zosHostConnection.connect(credentials);

		// the connection is now available for use
		...
	}
	catch (HostCredentialsException e)
	{
		// credentials were invalid, likely caused by expired password
		...
	}
}

Obtaining a Dataset Command Provider

In order to obtain one or more datasets, a dataset command provider must first be obtained. To obtain a dataset command provider:

IZOSHostConnection zosHostConnection = ...

// get the dataset command provider from a z/OS host connection
// note: the command provider will only be usable while the z/OS host connection is connected to its host
IDataSetCommandProvider commandProvider = zosHostConnection.getDataSetCommandProvider();

Allocating Partitioned or Sequential Datasets

In order to allocate partitioned or sequential datasets, you first must create the allocate parameters using an AllocateParametersBuilder. After creating your allocate parameters, you can then allocate your datasets using an IDatasetCommandProvider.

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

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

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

To allocate a partitioned dataset:

IDataSetCommandProvider commandProvider = ...
String dataSetName = ...
IAllocateParameters parameters = ...

try {
    commandProvider.allocatePartitionedDataSet(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
    ...
}

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

Creating a PDS Member

To create a single PDS member from an IDatasetCommandProvider:

IDataSetCommandProvider commandProvider = ...
String pdsName = ...
String memberName = ...

try {
	// create the member
	commandProvider.createPDSMember(pdsName, memberName);
} 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 does not exist
	...
} catch (MemberAlreadyExistsException e) {
	// a member with the same name already exists in the partitioned dataset
	...
}

To create a single PDS member from an IPartitionedDataset:

IPartitionedDataSet partitionedDataSet = ...
String memberName = ...

try {
	// create the member
	partitionedDataSet.createMember(memberName);
} 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 does not exist
	...
} catch (MemberAlreadyExistsException e) {
	// a member with the same name already exists in the partitioned dataset
	...
}

Deleting a PDS Member

To delete a single PDS member from an IDatasetCommandProvider:

IDataSetCommandProvider commandProvider = ...
String pdsName = ...
String memberName = ...

try {
	// delete the member
	commandProvider.deletePDSMember(pdsName, memberName);
} 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 does not exist
	...
} catch (MemberInUseException e) {
	// the member is enqueued by another user or job
	...
} catch (MemberNotFoundException e) {
	// a member with the same name already exists in the partitioned dataset
	...
}

To delete a single PDS member from an IPartitionedDataset:

IPartitionedDataSet partitionedDataSet = ...
String memberName = ...

try {
	// delete the member
	partitionedDataSet.deleteMember(memberName);
} 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 does not exist
	...
} catch (MemberInUseException e) {
	// the member is enqueued by another user or job
	...
} catch (MemberNotFoundException e) {
	// a member with the same name already exists in the partitioned dataset
	...
}

Obtaining one or more Datasets

To retrieve a single dataset of any type:

IDataSetCommandProvider commandProvider = ...
String dataSetName = ...

// dataSet will be null if it cannot be found
IDataSet dataSet = commandProvider.findDataSet(dataSetName);

To retrieve a list of datasets of any type matching a filter:

IDataSetCommandProvider commandProvider = ...
String dataSetFilter = ...

// dataSets will be empty if no datasets match the dataset filter
List<IDataSet> dataSets = commandProvider.findDataSets(dataSetFilter);

To retrieve a single partitioned dataset:

IDataSetCommandProvider commandProvider = ...
String dataSetName = ...

// dataSet will be null if it cannot be found
IPartitionedDataSet dataSet = commandProvider.findPartitionedDataSet(dataSetName);

To retrieve a list of partitioned datasets matching a filter:

IDataSetCommandProvider commandProvider = ...
String dataSetFilter = ...

// dataSets will be empty if no partitioned datasets match the dataset filter
List<IPartitionedDataSet> dataSets = commandProvider.findPartitionedDataSets(dataSetFilter);

To retrieve a single 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 single VSAM cluster:

IDataSetCommandProvider commandProvider = ...
String vsamClusterName = ...

// vsamCluster will be null if it cannot be found
IVSAMCluster vsamCluster = commandProvider.findVSAMCluster(vsamClusterName);

To retrieve a list of VSAM clusters matching a filter:

IDataSetCommandProvider commandProvider = ...
String dataSetFilter = ...

// vsamClusters will be empty if no VSAM clusters match the dataset filter
List<IVSAMCluster> vsamClusters = commandProvider.findVSAMClusters(dataSetFilter);

To retrieve a single migrated dataset:

IDataSetCommandProvider commandProvider = ...
String dataSetName = ...

// dataSet will be null if it cannot be found
IMigratedDataSet dataSet = commandProvider.findMigratedDataSet(dataSetName);

To retrieve a list of migrated datasets matching a filter:

IDataSetCommandProvider commandProvider = ...
String dataSetFilter = ...

// dataSets will be empty if no migrated datasets match the dataset filter
List<IMigratedDataSet> dataSets = commandProvider.findMigratedDataSets(dataSetFilter);

Reading the Content of a Sequential Dataset

To read the content of 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 '\uFFFD' (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 the content of 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 '\uFFFD' (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
	...
}

Writing to a Sequential Dataset

To write the content of 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 the sequential dataset and/or closing the writer
    ...
}

To write the content of 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 the sequential dataset and/or closing the writer
    ...
}

Reading the Content of a PDS Member

To read the content of a PDS 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 '\uFFFD' (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 the content of a PDS 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 '\uFFFD' (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
	...
}

Writing Content to a PDS Member

To write to a PDS 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 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 the partitioned dataset member and/or closing the writer
    ...
}

To write to a PDS 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 the partitioned dataset member and/or closing the writer
    ...
}

Obtaining the Characteristics of a Dataset

To obtain the characteristics of a dataset of any type:

IDataSet dataSet = ...

try {
	// fetch the characteristics from the dataset
	IDataSetCharacteristics dataSetCharacteristics = dataSet.fetchCharacteristics();

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

To obtain the characteristics of a partitioned dataset:

IPartitionedDataSet dataSet = ...

try {
	// fetch the partitioned dataset characteristics from the partitioned dataset
	IPartitionedDataSetCharacteristics partitionedDataSetCharacteristics = partitionedDataSet.fetchCharacteristics();

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

To obtain the characteristics of a sequential dataset:

ISequentialDataSet sequentialDataSet = ...

try {
	// fetch the sequential dataset characteristics from the sequential dataset
	ISequentialDataSetCharacteristics sequentialDataSetCharacteristics = sequentialDataSet.fetchCharacteristics();

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

To obtain the characteristics of a VSAM cluster:

IVSAMCluster vsamCluster = ...

try {
	// fetch the VSAM cluster characteristics from the VSAM cluster
	IVSAMClusterCharacteristics vsamClusterCharacteristics = vsamCluster.fetchCharacteristics();

	...
} catch (DataSetAccessException e) {
	// the user does not have access to this VSAM cluster
	...
} catch (DataSetInUseException e) {
	// the VSAM cluster is enqueued by another user or job
	...
} catch (DataSetMigratedException e) {
	// the VSAM cluster has been migrated since it was first retrieved
	...
} catch (DataSetNotFoundException e) {
	// the VSAM cluster can no longer be found
	...
}

Obtaining the Statistics of a PDS Member

To obtain the statistics of a PDS member:

IPartitionedDataSetMember partitionedDataSetMember = ...

try {
	// fetch the partitioned dataset member statistics from the partitioned dataset member
	IPartitionedDataSetMemberStatistics partitionedDataSetMemberStatistics = partitionedDataSetMember.fetchStatistics();

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

Recalling a Migrated Dataset

To recall a migrated dataset:

IMigratedDataSet migratedDataSet = ...

try {
	// recall the migrated dataset
	IDataSet recalledDataSet = migratedDataSet.recall();
	
	...
} catch (DataSetNotFoundException e) {
	// the migrated dataset can no longer be found
	...
}

Obtaining a JES Command Provider

In order to perform various JES functions, a JES command provider must first be obtained.

To obtain a JES command provider:

IZOSHostConnection zosHostConnection = ...

// get the JES command provider from a z/OS host connection
// note: the command provider will only be usable while the z/OS host connection is connected to its host
IJESCommandProvider commandProvider = zosHostConnection.getJESCommandProvider();

Submitting a Job

To submit a job from a partitioned dataset member using an IPartitionedDataSetMember:

IJESCommandProvider commandProvider = ...
IPartitionedDataSetMember member = ...

try {
	// submit the job (the returned JobInfo may be used to retrieve/monitor the job's status)
	JobInfo jobInfo = commandProvider.submit(member);
} 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
	...
}

To submit a job from a partitioned dataset member using a partitioned dataset name and member name:

IJESCommandProvider commandProvider = ...
String pdsName = ...
String memberName = ...

try {
	// submit the job (the returned JobInfo may be used to retrieve/monitor the job's status)
	JobInfo jobInfo = commandProvider.submit(pdsName, memberName);
} catch (DataSetAccessException e) {
	// the user does not have access to the 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 partitioned dataset
	...
} catch (MemberNotFoundException e) {
	// the member could not be found
	...
}

To submit a job from a sequential dataset using an ISequentialDataSet:

IJESCommandProvider commandProvider = ...
ISequentialDataSet sequentialDataSet = ...

try {
	// submit the job (the returned JobInfo may be used to retrieve/monitor the job's status)
	JobInfo jobInfo = commandProvider.submit(sequentialDataSet);
} 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
	...
}

To submit a job from a sequential dataset using a sequential dataset name:

IJESCommandProvider commandProvider = ...
String sequentialDataSetName = ...

try {
	// submit the job (the returned JobInfo may be used to retrieve/monitor the job's status)
	JobInfo jobInfo = commandProvider.submit(sequentialDataSetName);
} catch (DataSetAccessException e) {
	// the user does not have access to the 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 sequential dataset
	...
}

To submit a job from a list of String records:

IJESCommandProvider commandProvider = ...
List<String> jclRecords = ...

// submit the job (the returned JobInfo may be used to retrieve/monitor the job's status)
JobInfo jobInfo = commandProvider.submit(jclRecords);

Checking a Job’s Status

To check a job’s status:

IJESCommandProvider commandProvider = ...
JobInfo jobInfo = ...

// get the job status from the JES command provider
JobStatus jobStatus = commandProvider.getJobStatus(jobInfo);

Launching a z/OS User Program

In order to communicate with a z/OS user program, the program must first be launched.

To launch a z/OS user program:

IZOSHost zosHost = ...
String userID = ...
String password = ...
String userProcedureName = ...
String userProgramName = ...

// use one of the several ZOSCredentialsFactory methods to create a z/OS credentials object
IZOSCredentials credentials = ZOSCredentialsFactory.createZOSCredentials(userID, password);

// create a user program connection from the z/OS host
IZOSUserProgramConnection zosUserProgramConnection = zosHost.createZOSUserProgramConnection();

try {
	// launch the user program
	zosUserProgramConnection.launchUserProgram(credentials, userProcedureName, userProgramName);

	// the user program connection is now able to communicate with the program (for as long as it remains running)
	...
} catch (HostCredentialsException e) {
	// credentials were invalid, likely caused by incorrect login information or expired password
	...
}

Alternatively, a z/OS user program can be launched using the credentials of the currently logged in UI user (this requires the use of the com.compuware.api.hostservices.ui bundle).

IZOSHost zosHost = ...
String userProcedureName = ...
String userProgramName = ...

// make sure we have access to the UI user's credentials (either saved credentials, or the UI user is currently logged in)
if (!zosHost.hasUIUserCredentials()) {
	// connect the UI user so we can access their credentials (user will be presented with a login dialog)
	zosHost.connectUIUser();
}

// we should have the UI user's credentials now, unless they cancelled the login dialog
if (zosHost.hasUIUserCredentials()) {
	// get UI user's z/OS credentials
	IZOSCredentials credentials = zosHost.getUIUserCredentials();

	try {
		// create a user program connection from the z/OS host
		IZOSUserProgramConnection zosUserProgramConnection = zosHost.createZOSUserProgramConnection();

		// launch the user program
		zosUserProgramConnection.launchUserProgram(credentials, userProcedureName, userProgramName);

		// the user program connection is now able to communicate with the program (for as long as it remains running)
		...
	} catch (HostCredentialsException e) {
		// credentials were invalid, likely caused by expired password
		...
	}
}

Writing/Reading User-Defined Data to/from a z/OS User Program

A java.io.OutputStream is used to write user-defined data to a z/OS user program. A java.io.InputStream is used to read user-defined data from a z/OS user program.

To send byte data to a z/OS user program:

IZOSUserProgramConnection zosUserProgramConnection = ...
byte[] data = ...

try {
	// get the user program's output stream
	// note: a user program must be executing before calling this method
	OutputStream outputStream = zosUserProgramConnection.getOutputStream();

	// use any of the output stream's "write" methods to write data
	outputStream.write(data);
} catch (IOException e) {
	// an IO error occurred getting the input stream or reading its data
	...
}

To send text data to a z/OS user program:

IZOSUserProgramConnection zosUserProgramConnection = ...
String data = ...

try {
	// get the user program's output stream
	// note: a user program must be executing before calling this method
	OutputStream outputStream = zosUserProgramConnection.getOutputStream();

	// wrap the user program's output stream in a buffered writer
	// note: this code assumes the user program is decoding received data using UTF-8
	BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(outputStream, "UTF-8"));

	// use any of the writer's "write" methods to write text to the user program
	writer.write(data);

	// flush the writer to ensure the data gets sent to the user program
	writer.flush();
} catch (IOException e) {
	// an IO error occurred getting the input stream or reading its data
	...
}

To read byte data from a z/OS user program:

IZOSUserProgramConnection zosUserProgramConnection = ...
byte[] buffer = ...

try {
	// get the user program's input stream
	// note: a user program must be executing before calling this method
	InputStream inputStream = zosUserProgramConnection.getInputStream();

	// use any of the input stream's "read" methods to read data
	int numBytesRead = inputStream.read(buffer);
} catch (IOException e) {
	// an IO error occurred getting the input stream or reading its data
	...
}

To read text data from a z/OS user program:

IZOSUserProgramConnection zosUserProgramConnection = ...

try {
	// get the user program's input stream
	// note: a user program must be executing before calling this method
	InputStream inputStream = zosUserProgramConnection.getInputStream();

	// wrap the user program's input stream in a buffered reader
	// note: this code assumes the user program is encoding its data using UTF-8
	BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream, "UTF-8"));

	// use the any of the reader's "read" methods to read text from the user program
	String data = reader.readLine();
} catch (IOException e) {
	// an IO error occurred getting the input stream or reading its data
	...
}

Listening for z/OS User Program Termination Events

To listen for z/OS user program termination events:

IZOSUserProgramConnection zosUserProgramConnection = ...

// create a z/OS user program termination listener
IZOSUserProgramTerminationListener terminationListener = new IZOSUserProgramTerminationListener() {
	{@code @Override}
	public void programCompleted(IZOSUserProgramCompletionEvent event) {
		// handle z/OS user program normal completion here
		...
	}

	{@code @Override}
	public void programAbended(IZOSUserProgramAbendEvent event) {
		// handle z/OS user program abend here
		...
	}
};

// add listener to z/OS user program connection
// note: this listener will be notified of the termination of all user programs launched via this z/OS user program connection until it is removed
zosUserProgramConnection.addUserProgramTerminationListener

# Code Snippets

# Obtaining one or more Defined z/OS Hosts

# Connecting to a z/OS Host for Dataset or JES API Usage

# Obtaining a Dataset Command Provider

# Allocating Partitioned or Sequential Datasets

# Creating a PDS Member

# Deleting a PDS Member

# Obtaining one or more Datasets

# Reading the Content of a Sequential Dataset

# Writing to a Sequential Dataset

# Reading the Content of a PDS Member

# Writing Content to a PDS Member

# Obtaining the Characteristics of a Dataset

# Obtaining the Statistics of a PDS Member

# Recalling a Migrated Dataset

# Obtaining a JES Command Provider

# Submitting a Job

# Checking a Job’s Status

# Launching a z/OS User Program

# Writing/Reading User-Defined Data to/from a z/OS User Program

# Listening for z/OS User Program Termination Events