zOS Batch Manager

This Manager is at Beta level. You can view the Javadoc documentation for the Manager here.

Overview
Provided annotation
Code snippets and examples

Overview

This Manager enables Galasa tests to submit batch jobs to run on a z/OS image.

The Manager is implemented using the z/OS MF Manager by default.

Provided annotations

The following annotations are available with the zOS Batch Manager

Annotation:	z/OS Batch
Name:	@ZosBatch
Description:	The `@ZosBatch` annotation requests the z/OS Batch Manager to provide a z/OS Batch instance associated with a z/OS image. The test can request multiple z/OS Batch instances, with the default being associated with the primary zOS image. At test end, the Manager stores the job output with the test results archive and removes jobs from the JES queue.
Attribute: `imageTag`	The `imageTag` is used to identify the z/OS image.
Syntax:	@ZosImage(imageTag="A") public IZosImage zosImageA; @ZosBatch(imageTag="A") public IZosBatch zosBatchA;
Notes:	The `IZosBatch` interface has a single method, {@link IZosBatch#submitJob(String, IZosBatchJobname)} to submit a JCL as a `String` and returns a `IZosBatchJob` instance. See ZosBatch, IZosBatch and IZosBatchJob to find out more.

Annotation:	z/OS Console
Name:	@ZosConsole
Description:	The `@ZosConsole` annotation requests the z/OS Console Manager to provide a z/OS Console instance associated with a z/OS image. The test can request multiple z/OS Console instances, with the default being associated with the primary z/OS image.
Attribute: `imageTag`	The tag of the zOS Image this variable is to be populated with
Syntax:	@ZosImage(imageTag="A") public IZosImage zosImageA; @ZosConsole(imageTag="A") public IZosConsole zosConsoleA;
Notes:	The `IZosConsole` interface has two methods, {@link IZosConsole#issueCommand(String)} and {@link IZosConsole#issueCommand(String, String)} to issue a command to the z/OS console and returns a `IZosConsoleCommand` instance. See ZosConsole, IZosConsole and IZosConsoleCommand to find out more.

Annotation:	z/OS File
Name:	@ZosFileHandler
Description:	The `@ZosFileHandler` annotation requests the z/OS File Manager to provide a handler to manage data sets and UNIX files on a z/OS image. A single z/OS File Handler instance can manage multiple z/OS data sets and UNIX files on multiple z/OS images. Files are deleted at method end unless created with the object's createRetain() method where it is deleted at test end.
Syntax:	`@ZosFileHandler public IZosFileHandler zosFileHandler;`
Notes:	The `IZosFileHandler` interface has three methods supplying file name and z/OS image: {@link IZosFileHandler#newDataset(String, dev.galasa.zos.IZosImage)} {@link IZosFileHandler#newVSAMDataset(String, dev.galasa.zos.IZosImage)} {@link IZosFileHandler#newUNIXFile(String, dev.galasa.zos.IZosImage)} returning an object representing the type of file requested. This can be an existing file or can be created via a method on the file object. See ZosFileHandler, IZosFileHandler, IZosDataset, IZosVSAMDataset and IZosUNIXFile to find out more.

Code Snippets

Use the following code snippets to help you get started with the zOS Batch Manager.

Request a zOS Console instance

The following snippet shows the code that is required to request a zOS Console instance in a Galasa test:

@ZosImage(imageTag="A")
public IZosImage zosImageA;

@ZosBatch(imageTag="A")
public IZosConsole zosConsole;

The code creates a zOS Console instance associated with the zOS Image allocated in the zosImageA field.

Issue a zOS Console command and retrieve the immediate response

Issue a zOS Console command and retrieve the immediate console command response:

String command = "D A,L";
IZosConsoleCommand consoleCommand = zosConsole.issueCommand(command);
String immediateResponse = consoleCommand.getResponse();

Issue a zOS Console command and retrieve the delayed response

Issue a zOS Console command and retrieve the delayed console command response:

String command = "D A,L";
IZosConsoleCommand consoleCommand = zosConsole.issueCommand(command);
String delayedResponse = consoleCommand.requestResponse();

Request a zOS Batch instance

The following snippet shows the code that is required to request a zOS Batch instance in a Galasa test:

@ZosImage(imageTag="A")
public IZosImage zosImageA;

@ZosBatch(imageTag="A")
public IZosBatch zosBatch;

The code creates a zOS Batch instance associated with the allocated with the zOS Image allocated in the zosImageA field.

Submit a zOS Batch Job

Submit a zOS Batch Job using the supplied JCL and a Galasa allocated Job Name:

String jcl = "//STEP1    EXEC PGM=IEFBR14";
IZosBatchJob batchJob = zosBatch.submitJob(jcl, null);

Wait for zOS Batch Job to complete

Wait for zOS Batch job to complete and check maximum return code:

if (batchJob.waitForJob() > 0) {
    logger.info("Batch job failed RETCODE=" + batchJob.getRetcode();
}

prints, for example:

Batch job failed RETCODE=CC 0020

Batch job failed RETCODE=ABEND S0C4

Retrieve the job output

Use the following code to retrieve the output from a zOS Batch Job:

IZosBatchJobOutput jobOutput = batchJob.retrieveOutput();
List<IZosBatchJobOutputSpoolFile> spoolFiles = jobOutput.getSpoolFiles();
for (IZosBatchJobOutputSpoolFile spoolFile : spoolFiles) {
    String ddName = spoolFile.getDdname();
    String output = spoolFile.getRecords();
    ...
}

Request a zOS File Handler instance

The following snippet shows the code that is required to request a zOS File Handler instance in a Galasa test:

@ZosFileHandler
public IZosFileHandler zosFileHandler;

Read the content of an existing sequential data set

Create a new IZosDataset object representing an existing sequential data set. If the data set exists, retrieve the content:

@ZosImage(imageTag="A")
public IZosImage zosImageA;

@ZosFileHandler
public IZosFileHandler zosFileHandler;
...
IZosDataset dataSet = zosFileHandler.newDataset("GALASA.EXISTING.DATASET.SEQ", zosImageA);
if (dataSet.exists()) {
    String dataSet.retrieve();
    ...
}

Read the content of an existing partitioned data set member

Create a new IZosDataset object representing an existing partitioned data set (PDS). If the PDS exists, check if the member exists and retrieve it's content:

@ZosImage(imageTag="A")
public IZosImage zosImageA;

@ZosFileHandler
public IZosFileHandler zosFileHandler;
...
IZosDataset dataSet = zosFileHandler.newDataset("GALASA.EXISTING.DATASET.SEQ, zosImageA);
    String memberName = "MEMBER1";
    if (dataSet.exists() && dataSet.memberExists(memberName)) {
        String content = dataSet.memberRetrieve(memberName);
        ...
    }

Create a new sequential data set

Create a new IZosDataset object representing a new sequential data set. If the data set does not exist, allocate the data set with attributes to the equivalent of the following JCL:

//NEWDS    DD DSN=GALASA.NEW.DATASET.SEQ,DISP=(NEW,CATLG),
//            DSORG=PS,RECFM=FB,LRECL=80,BLKSIZE=32720,
//            UNIT=SYSDA,SPACE=(TRK,(1,1))

Finally, content is written to the data set:

@ZosImage(imageTag="A")
public IZosImage zosImageA;

@ZosFileHandler
public IZosFileHandler zosFileHandler;
...
IZosDataset dataSet = zosFileHandler.newDataset("GALASA.NEW.DATASET.SEQ", zosImageA);
    if (!dataSet.exists()) {
        dataSet.setDatasetOrganization(DatasetOrganization.SEQUENTIAL);
        dataSet.setRecordFormat(RecordFormat.FIXED_BLOCKED);
        dataSet.setRecordlength(80);
        dataSet.setBlockSize(32720);
        dataSet.setUnit("SYSDA");
        dataSet.setSpace(SpaceUnit.TRACKS, 1, 1);
        dataSet.create();
    }
    List<String> records = new ArrayList<>();
    records.add("RECORD 1");
    records.add("RECORD 2");
    records.add("RECORD 3");
    dataSet.store(String.join("\n", records));

Create a new partitioned data set member

Create a new IZosDataset object representing a new partitioned data (PDS) set member. If the data set does not exist, allocate the PDS with attributes to the equivalent of the following JCL:

//NEWPDS   DD DSN=GALASA.NEW.DATASET.PDS,DISP=(NEW,CATLG),
//            DSORG=PS,RECFM=FB,LRECL=80,BLKSIZE=32720,
//            UNIT=SYSDA,SPACE=(TRK,(1,1,15))

Finally, content is written to a member in the PDS:

@ZosImage(imageTag="A")
public IZosImage zosImageA;

@ZosFileHandler
public IZosFileHandler zosFileHandler;
...
IZosDataset dataSet = zosFileHandler.newDataset("GALASA.NEW.DATASET.PDS", zosImageA);
if (!dataSet.exists()) {
    dataSet.setDatasetOrganization(DatasetOrganization.SEQUENTIAL);
    dataSet.setRecordFormat(RecordFormat.FIXED_BLOCKED);
    dataSet.setRecordlength(80);
    dataSet.setBlockSize(32720);
    dataSet.setUnit("SYSDA");
    dataSet.setSpace(SpaceUnit.TRACKS, 1, 1);
    dataSet.setDirectoryBlocks(15);
    dataSet.create();
}
String memberName = "MEMBER1";
List<String> records = new ArrayList<>();
    records.add("RECORD 1");
    records.add("RECORD 2");
    records.add("RECORD 3");
    dataSet.memberStore(memberName, String.join("\n", records));
}

To create a PDS/E, i.e. the JCL equivalent of

DSNTYPE=LIBRARY

use

dataSet.setDatasetType(DSType.PDSE);

instead of setting the number of directory blocks.

Create a new VSAM KSDS

Create a new IZosVSAMDataset object representing a new VSAM KSDS data set. If the data set is allocated with a minimum set of attributes:

IZosVSAMDataset vsamDataSet = zosFileHandler.newVSAMDataset("ROBERTD.GALASA.TEST.DS.ANOTHER.KSDS", zosImageA);
vsamDataSet.setSpace(VSAMSpaceUnit.CYLINDERS, 1, 1);
vsamDataSet.setRecordSize(50, 101);
vsamDataSet.create();

Read a zOS UNIX File

To be completed...

Edit this page on GitHub