galasa

Close menu
Open menu

z/OS Manager

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

Overview
Configuring
Provided annotation
Code snippets and examples

Overview

This Manager provides tests and Managers with access to and configuration information about z/OS images and Sysplexes. It offers services such as APF, DUMP, SMF and Log access.

Additionally, the z/OS Manager provides tests with interfaces to the following z/OS functions which are implemented by other Managers:

- z/OS Batch which enables tests and Managers to submit, monitor and retrieve the output of z/OS batch jobs. See BatchAccountsOpenTest for a walkthrough of a test that employs this Manager.

- z/OS Console which allows tests and Managers to issue and retrieve the responses from z/OS console commands.

- z/OS File which provides tests and Managers with the ability to manage and transfer files to and from z/OS. Supported file types include Sequential, PDS, PDSE, KSDS, ESDS or RRDS and z/OS UNIX files.

- z/OS TSO Command which enables tests and Managers to issue and retrieve the responses from z/OS TSO commands.

- z/OS UNIX Command which enables tests and Managers to issue and retrieve the responses from z/OS UNIX commands.



You can view the Javadoc documentation for the Manager here.

Including the Manager in a test

The z/OS Manager is not instantiated directly. To use the z/OS Manager in a test, import one or more of the following annotations into the test, as shown in the following examples:

@ZosImage
public IZosImage imagePrimary;
@ZosIpHost
public IIpHost hostPrimary;
@ZosIpPort
public IIpPort portPrimary;

You also need to add the Manager dependency into the pom.xml file if you are using Maven, or into the build.gradle file if you are using Gradle.

If you are using Maven, add the following dependencies into the pom.xml in the dependencies section:

<dependency>
<groupId>dev.galasa</groupId>
<artifactId>dev.galasa.zos.manager</artifactId>
</dependency>

If you are using Gradle, add the following dependencies into build.gradle in the dependencies closure:

dependencies {
compileOnly 'dev.galasa:dev.galasa.zos.manager'
}

Testing CICS Regions on z/OS

To connect your Galasa test to a developer supplied environment with a provisioned CICS region as a minimum you need to configure the following properties, even if you do not reference a @ZosImage in your Galasa test. This is because CICS regions sit on a z/OS LPAR, and so to provision and connect to a CICS region in a test, you also need access to the z/OS image that it sits within to make requests on the CICS region. You might need to configure additional z/OS-related CPS properties, depending on your test.

zos.dse.tag.[tag].imageid=[IMAGEID] OR zos.cluster.[clusterId].images=[IMAGEID]
zos.image.[IMAGEID].ipv4.hostname=[IP ADDRESS]
zos.image.[IMAGEID].credentials=[CREDENTIALID]

You also need to configure the following properties for the CICS TS Manager:

cicsts.provision.type=dse
cicsts.dse.tag.[TAG].applid=[APPLID]

Configuring

The following properties are used to configure the z/OS Manager.

Hostname of a z/OS system
Property: Hostname of a z/OS system
Name: zos.image.[IMAGEID].ipv4.hostname
Description: A physical TCP/IP hostname value for a z/OS system
Required: Yes, if connecting to a z/OS image
Default value: None
Valid values: A valid TCP/IP hostname
Examples: zos.image.IMAGEA.ipv4.hostname=dev.galasa.system1
zos.image.SIMBANK.ipv4.hostname=127.0.0.1
zos.image.IMAGEA.ipv4.hostname=winmvs2a.example.com
Credentials tag for logging onto a z/OS system
Property: Credentials tag for logging onto a z/OS system
Name: zos.image.[IMAGEID].credentials
Description: Tag of the credentials that are stored in the CREDS and used to log onto a z/OS system
Required: Yes, if connecting to a z/OS image
Default value: None
Valid values: Valid characters are A-Z, a - z, 0-9
Examples: zos.image.IMAGEA.credentials=KEY_TO_CREDS_STORE
zos.image.SIMBANK.credentials=SIMBANK
zos.image.IMAGEA.credentials=WINMVS2A
Extra bundle required to implement the z/OS Batch Manager
Property: Extra bundle required to implement the zOS Batch Manager
Name: zos.bundle.extra.batch.manager
Description: The name of the Bundle that implements the z/OS Batch Manager
Required: No
Default value: dev.galasa.common.zosbatch.zosmf.manager
Valid values: A 1 - 8 length character name. A name containing more than 8 characters must be segmented by periods; 1 to 8 characters can be specified between periods. Valid characters are A-Z, a - z, 0-9, special characters.
Examples: zos.bundle.extra.batch.manager=dev.galasa.common.zosbatch.zosmf.manager
The z/OS Cluster ID
Property: The zOS Cluster ID
Name: zos.tag.[tag].clusterid
Description: The z/OS Cluster ID for the specified tag
Required: No
Default value: None
Valid values: Valid value is a character string with a maximum length of 32
Examples: zos.tag.[tag].clusterid=plex1
The images for a z/OS Cluster
Property: The images for a zOS Cluster
Name: zos.cluster.[clusterId].images
Description: The z/OS Images for the specified cluster. Specify more than one image by using commas.
Required: No
Default value: None
Valid values: Valid value is a character string with a maximum length of 32
Examples: zos.cluster.[clusterId].images=SYSA,SYSB,SYSC
Extra bundle required to implement the z/OS Console Manager
Property: Extra bundle required to implement the zOS Console Manager
Name: zos.bundle.extra.console.manager
Description: The name of the Bundle that implements the z/OS Console Manager
Required: No
Default value: dev.galasa.common.zosconsole.zosmf.manager
Valid values: A 1 - 8 length character name. A name containing more than 8 characters must be segmented by periods; 1 to 8 characters can be specified between periods. Valid characters are A-Z, a - z, 0-9, special characters.
Examples: zos.bundle.extra.console.manager=dev.galasa.common.zosconsole.zosmf.manager
Developer Supplied Environment z/OS Image Cluster ID
Property: Developer Supplied Environment zOS Image Cluster ID
Name: zos.dse.tag.[tag].clusterid
Description: The Cluster ID for the specified tag
Required: No
Default value: None
Valid values: A 1 - 8 length character name
Examples: zos.dse.tag.[tag].clusterid=PLEXA
Developer Supplied Environment z/OS Image
Property: Developer Supplied Environment zOS Image
Name: zos.dse.tag.[tag].imageid
Description: The image ID of the Developer Supplied Environment for the specified tag
Required: No
Default value: None
Valid values: A valid image ID
Examples: zos.dse.tag.[tag].imageid=SYSA
Extra bundle required to implement the z/OS File Manager
Property: Extra bundle required to implement the zOS File Manager
Name: zos.bundle.extra.file.manager
Description: The name of the Bundle that implements the z/OS File Manager
Required: No
Default value: dev.galasa.common.zosfile.zosmf.manager
Valid values: A 1 - 8 length character name. A name containing more than 8 characters must be segmented by periods; 1 to 8 characters can be specified between periods. Valid characters are A-Z, a - z, 0-9, special characters.
Examples: zos.bundle.extra.file.manager=dev.galasa.common.zosfile.zosmf.manager
IP Host ID of the z/OS Image
Property: IP Host ID of the zOS Image
Name: zos.image.[tag].iphostid
Description: The IP Host ID of the z/OS Image for the supplied tag.
If CPS property zos.image.[tag].iphostid exists, then that is returned, otherwise the z/OS Image ID is returned
Required: No
Default value: None
Valid values: A valid IP Host ID
Examples: zos.image.[tag].iphostid=sysa.example.com
The z/OS Image
Property: The zOS Image
Name: zos.dse.tag.[tag].imageid
Description: The image ID for the specified tag
Required: No
Default value: None
Valid values: A valid z/OS image ID
Examples: zos.dse.tag.[tag].imageid=SYSA
Maximum slots for z/OS Image
Property: Maximum slots for zOS Image
Name: zos.image.[tag].max.slots
Description: The maximum slots available on a z/OS Image for the specified tag
Required: No
Default value: 2
Valid values: 1 to 255
Examples: zos.image.[tag].max.slots=2
Code page for z/OS Image
Property: Code page for zOS Image
Name: zos.image.[tag].codepage
Description: The EBCDIC code page used on a z/OS image for the specified tag. EBCDIC features a variety of code pages, and a subset of characters, including square brackets and currency symbols, are encoded differently between code pages. Setting the correct code page for a z/OS image can resolve issues with displaying these characters.
Required: No
Default value: 037
Valid values: A valid java.nio.charset EBCDIC character encoding
Examples: zos.image.[tag].codepage=1047
The SYSNAME for z/OS Image
Property: The SYSNAME for zOS Image
Name: zos.image.[imageid].sysname
Description: The SYSNAME for the z/OS image
Required: No
Default value: The image ID of the image
Valid values: The name must be 1-8 characters long; the valid characters are A-Z, 0-9, $, @, and #.
Examples: zos.image.IMAGEA.sysname=SYSA
The run data set HLQ for the z/OS Image
Property: The run data set HLQ for the zOS Image
Name: zos.run.[image].dataset.hlq
Description: The data set HLQ(s) for temporary data sets created on z/OS Image.
If CPS property zos.run.[image].dataset.hlq exists, then that is returned
Required: No
Default value: runuser.GALASA
Valid values: A data set name can be one name segment, or a series of joined name segments. Segments are limited to eight characters, the first of which must be alphabetic (A to Z) or special (# @ $). The remaining seven characters are either alphabetic, numeric (0 - 9), special, a hyphen (-). Name segments are separated by a period (.).
Examples: zos.run.[image].dataset.hlq=USERID.GALASA
The run data UNIX path prefix for the z/OS Image
Property: The run data UNIX path prefix for the zOS Image
Name: zos.run.[image].unix.path.prefix
Description: The UNIX path prefix for temporary data sets created on z/OS Image.
If CPS property zos.run.[image].unix.path.prefix exists, then that is returned
Required: No
Default value: /u/runuser/Galasa
Valid values: A valid path
Examples: zos.run.[image].unix.path.prefix=/u/userid/Galasa
Extra bundle required to implement the z/OS TSO Command Manager
Property: Extra bundle required to implement the zOS TSO Command Manager
Name: zos.bundle.extra.tsocommand.manager
Description: The name of the Bundle that implements the z/OS TSO Command Manager
Required: No
Default value: dev.galasa.zostsocommand.ssh.manager
Valid values: A 1 - 8 length character name. A name containing more than 8 characters must be segmented by periods; 1 to 8 characters can be specified between periods. Valid characters are A-Z, a - z, 0-9, special characters.
Examples: zos.bundle.extra.tsocommand.manager=dev.galasa.zostsocommand.ssh.manager
Extra bundle required to implement the z/OS UNIX Command Manager
Property: Extra bundle required to implement the zOS UNIX Command Manager
Name: zos.bundle.extra.unixcomand.manager
Description: The name of the Bundle that implements the z/OS UNIX Command Manager
Required: No
Default value: dev.galasa.zosunixcommand.ssh.manager
Valid values: A 1 - 8 length character name. A name containing more than 8 characters must be segmented by periods; 1 to 8 characters can be specified between periods. Valid characters are A-Z, a - z, 0-9, special characters.
Examples: zos.bundle.extra.unix.manager=dev.galasa.zosunixcommand.ssh.manager
z/OS Batch restrict processing to the server on the specified image
Property: zOS Batch restrict processing to the server on the specified image
Name: zosbatch.batchjob.[imageid].restrict.to.image
Description: Use only the server (e.g. zOSMF, RSE API, etc) running on the image associated with the z/OS Batch job
Required: No
Default value: false
Valid values: true or false
Examples: zosbatch.batchjob.MVSA.restrict.to.image=true
zosbatch.batchjob.default.restrict.to.image=false
z/OS Batch default input class
Property: zOS Batch default input class
Name: zosbatch.default.[imageid].input.class
Description: The default input class to set on the job card for submitted jobs
Required: No
Default value: A
Valid values: a valid JES input class literal
Examples: zosbatch.default.MVSA.input.class=S
zosbatch.default.input.class=A
z/OS Batch job execution wait timeout
Property: zOS Batch job execution wait timeout
Name: zosbatch.batchjob.[imageid].timeout
Description: The value in seconds to wait for the z/OS Batch job execution to complete when submitted via zOSMF
Required: No
Default value: 350
Valid values: 0 to {@link Integer#MAX_VALUE}
Examples: zosbatch.batchjob.MVSA.timeout=350
zosbatch.batchjob.default.timeout=60
z/OS Batch jobname prefix
Property: zOS Batch jobname prefix
Name: zosbatch.jobname.[imageid].prefix
Description: The z/OS Batch jobname prefix when submitted via zOSMF
Required: No
Default value: GAL
Valid values: 1-7 characters
Examples: zosbatch.jobname.MVSA.prefix=JOB
zosbatch.jobname.default.prefix=XXX
z/OS Batch default MSGCLASS
Property: zOS Batch default MSGCLASS
Name: zosbatch.default.[imageid].message.class
Description: The default message class to set on the job card for submitted jobs
Required: No
Default value: A
Valid values: a valid JES message class literal
Examples: zosbatch.default.MVSA.message.class=S
zosbatch.default.message.class=A
z/OS Batch default message level
Property: zOS Batch default message level
Name: zosbatch.default.[imageid].message.level
Description: The default message level to set on the job card for submitted jobs
Required: No
Default value: (1,1)
Valid values: a valid JES message level
Examples: zosbatch.default.MVSA.message.level=(1,1)
zosbatch.default.message.level=(2,0)
z/OS Batch job truncate JCL
Property: zOS Batch job truncate JCL
Name: zosbatch.batchjob.[imageid].truncate.jcl.records
Description: The z/OSMF submit job will fail if supplied with JCL records greater than 80 characters. Setting this property to true will truncate any records to 80 characters and issue a warning message.
Required: No
Default value: true
Valid values: true or false
Examples: zosbatch.batchjobe.MVSA.truncate.jcl.records=true
zosbatch.batchjob.default.truncate.jcl.records=false
z/OS Batch job use SYSAFF
Property: zOS Batch job use SYSAFF
Name: zosbatch.batchjob.[imageid].use.sysaff
Description: Use the run the z/OS Batch job on the specified image by specifying {@code /*JOBPARM SYSAFF=[imageid]}
Required: No
Default value: true
Valid values: true or false
Examples: zosbatch.batchjobe.MVSA.use.sysaff=true
zosbatch.batchjob.default.use.sysaff=false
Restrict z/OS console processing to the zOSMF server on the specified image
Property: Restrict zOS console processing to the zOSMF server on the specified image
Name: zosconsole.console.[imageid].restrict.to.image
Description: Use only the zOSMF server running on the image associated with the z/OS Console
Required: No
Default value: false
Valid values: true or false
Examples: zosconsole.console.restrict.to.image=true
zosconsole.console.SYSA.restrict.to.image=true
z/OS File the maximum number of items from a UNIX directory list
Property: zOS File the maximum number of items from a UNIX directory list
Name: zosfile.unix.[imageid].directory.list.max.items
Description: The maximum number of items the server (e.g. zOSMF, RSE API, etc) returns when listing the content of a UNIX directory
Required: No
Default value: 1000
Valid values: 0 to 65535
Examples: zosfile.unix.[imageid].directory.list.max.items=1000
z/OS File restrict processing to the server on the specified image
Property: zOS File restrict processing to the server on the specified image
Name: zosfile.file.[imageid].restrict.to.image
Description: Use only the server (e.g. zOSMF, RSE API, etc) running on the image associated with the z/OS data set or file
Required: No
Default value: false
Valid values: true or false
Examples: zosfile.file.restrict.to.image=true
zosfile.file.SYSA.restrict.to.image=true
z/OS File UNIX permission bits to be used in creating the file or directory
Property: zOS File UNIX permission bits to be used in creating the file or directory
Name: zosfile.[imageid].unix.file.permission
Description: The UNIX file or directory permission bits to be used in creating the file or directory
Required: No
Default value: None
Valid values: Valid values are r,w,x,s,-
Examples: zosfile.unix.file.permission=rwxrwx---
zosfile.SYSA.unix.file.permission=rwxrwxrrx

Annotations provided by the Manager

The following annotations are available with the z/OS Manager

z/OS Batch
Annotation: z/OS Batch
Name: @ZosBatch
Description: The @ZosBatch annotation requests the z/OS 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 z/OS 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.
z/OS Console
Annotation: z/OS Console
Name: @ZosConsole
Description: The @ZosConsole annotation requests the z/OS 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 z/OS 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.
z/OS File
Annotation: z/OS File
Name: @ZosFileHandler
Description: The @ZosFileHandler annotation requests the z/OS Manager to provide a handler instance 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.
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.
z/OS TSO Command
Annotation: z/OS TSO Command
Name: @ZosTSOCommand
Description: The @ZosTSOCommand annotation requests the z/OS Manager to provide a z/OS TSO Command instance associated with a z/OS image. The test can request multiple z/OS TSO Command instances, with the default being associated with the primary z/OS image.
Attribute: imageTag The tag of the z/OS Image this variable is to be populated with
Syntax: @ZosImage(imageTag="A")
public IZosImage zosImageA;
@ZosTSOCommand(imageTag="A")
public IZosTSOCpmmand zosTSOA;
Notes: The IZosTSOCommand interface provides the methods {@link IZosTSOCommand#issueCommand(String)} and {@link IZosTSOCommand#issueCommand(String, long)} to issue a command to z/OS TSO Command and returns a String.

See IZosTSOCommand to find out more.
z/OS UNIX Command
Annotation: z/OS UNIX Command
Name: @ZosUNIXCommand
Description: The @ZosUNIXCommand annotation requests the z/OS Manager to provide a z/OS UNIX instance associated with a z/OS image. The test can request multiple z/OS UNIX Command instances, with the default being associated with the primary z/OS image.
Attribute: imageTag The tag of the z/OS Image this variable is to be populated with
Syntax: @ZosImage(imageTag="A")
public IZosImage zosImageA;
@ZosUNIXCommand(imageTag="A")
public IZosUNIXCommand zosUNIXCommandA;
Notes: The IZosUNIXCommand interface provides the methods {@link IZosUNIXCommand#issueCommand(String)} and {@link IZosUNIXCommand#issueCommand(String, long)} to issue a command to z/OS UNIX and returns a String response.

See IZosUNIXCommand to find out more.

Code snippets and examples

Use the following code snippets to help you get started with the z/OS Manager.

Request a z/OS TSO Command instance

The following snippet shows the code that is required to request a z/OS TSO Command instance in a Galasa test:

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

@ZosTSOCommand(imageTag="A")
public IZosTSOCommand tsoCommand;

The code creates a z/OS TSO Command instance associated with the z/OS Image allocated in the zosImageA field.

Issue a z/OS TSO Command and retrieve the immediate response

Issue the z/OS TSO TIME Command and retrieve the response:

String tsoCommandString = "TIME";
String tsoResponse = tsoCommand.issueCommand(tsoCommandString);

The String tsoResponse contains the output of the TSO TIME command, e.g.

IKJ56650I TIME-12:01:00 PM. CPU-00:00:00 SERVICE-290 SESSION-00:00:00 APRIL 1,2020
Request a z/OS UNIX Command instance

The following snippet shows the code that is required to request a z/OS UNIX Command instance in a Galasa test:

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

@ZosUNIXCommand(imageTag="A")
public IZosUNIXCommand unixCommand;

The code creates a z/OS UNIX Command instance associated with the z/OS Image allocated in the zosImageA field.

Issue a z/OS UNIX Command and retrieve response

Issue the z/OS UNIX date Command and retrieve the response:

String unixCommandString = "date";
String unixResponse = unixCommand.issueCommand(unixCommandString);

The String unixResponse contains the output of the UNIX TIME command, e.g.

Wed Apr 1 12:01:00 BST 2020
Request a z/OS Console instance

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

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

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

The code creates a z/OS Console instance associated with the z/OS Image allocated in the zosImageA field.

Issue a z/OS Console command and retrieve the immediate response

Issue a z/OS 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 z/OS Console command and retrieve the delayed response

Issue a z/OS 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 z/OS Batch instance

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

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

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

The code creates a z/OS Batch instance associated with the allocated with the z/OS Image allocated in the zosImageA field.

Submit a z/OS Batch Job

Submit a z/OS Batch Job using the supplied JCL and a Galasa allocated Job Name:

String jcl = "//STEP1    EXEC PGM=IEFBR14";
IZosBatchJob batchJob = zosBatch.submitJob(jcl, null);
Submit a z/OS Batch Job with job card parameters

Submit a z/OS Batch Job using the supplied JCL, a Galasa allocated Job Name and overidding the default input and message class:

String jcl = "//STEP1    EXEC PGM=IEFBR14";
ZosBatchJobcard jobcard = new ZosBatchJobcard().
                          .setInputClass("B")
                          .setMsgClass("X");
IZosBatchJob batchJob = zosBatch.submitJob(jcl, null, jobcard);
Wait for z/OS Batch Job to complete

Wait for z/OS 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

or

Batch job failed RETCODE=ABEND S0C4
Retrieve the job output

Use the following code to retrieve the output from a z/OS Batch Job:

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

Use the following code to obtain a list of active jobs called MYJOB1 with an owner of USERID:

List<IZosBatchJob> jobs = zosBatch.getJobs("MYJOB1", "USERID");
for (IZosBatchJob job : jobs) {
    if (job.getStatus().equals("ACTIVE")) {
        ...
    }
}
Retrieve the content of a specific spool file from an active CICS region

Use the following code to retrieve and process the output from the MSGUSR spool file:

List<IZosBatchJob> jobs = zosBatch.getJobs("CICSRGN", "CICSUSR");
for (IZosBatchJob job : jobs) {
    if (job.getStatus().equals("ACTIVE")) {
        String msgusr = cicsJob.getSpoolFile("MSGUSR");
        if (msgusr.contains("DFHAC2236")) {
            ...
        }
        break;
    }
}

The code retrieves a list of CICS regions named CICSRGN with and owner of CICSUSR. It then loops through until it finds the first active region. The content of the MSGUSR spool file is obtained and checked for the string DFHAC2236.

In this example, we assume there will only one spool file with the ddname of MSGUSR. If this were not the case, the following code could be used:

List<IZosBatchJob> jobs = zosBatch.getJobs("CICSRGN", "CICSUSR");
for (IZosBatchJob job : jobs) {
    List<IZosBatchJobOutputSpoolFile> spoolFiles = job.retrieveOutput().getSpoolFiles();
    for (IZosBatchJobOutputSpoolFile spoolFile : spoolFiles) {
        if (spoolFile.getDdname().equals("SYSOUT") &&
            spoolFile.getStepname().equals("STEP2")) {
            String output = spoolFile.getRecords();
            ...
        }
    }
}

Here, the code retrieves the content of the SYSOUT spool file for job step STEP2.

Request a z/OS File Handler instance

The following snippet shows the code that is required to request a z/OS 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 in text mode:

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

@ZosFileHandler
public IZosFileHandler zosFileHandler;
...
IZosDataset dataSet = zosFileHandler.newDataset("GALASA.EXISTING.DATASET.SEQ", zosImage);
if (dataSet.exists()) {
    String content = dataSet.retrieveAsText();
    ...
}
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 in text mode:

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

@ZosFileHandler
public IZosFileHandler zosFileHandler;
...
IZosDataset dataSet = zosFileHandler.newDataset("GALASA.EXISTING.DATASET.SEQ, zosImage);
    String memberName = "MEMBER1";
    if (dataSet.exists() && dataSet.memberExists(memberName)) {
        String content = dataSet.memberRetrieveAsText(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 in text mode:

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

@ZosFileHandler
public IZosFileHandler zosFileHandler;
...
IZosDataset dataSet = zosFileHandler.newDataset("GALASA.NEW.DATASET.SEQ", zosImage);
    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.storeText(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 in text mode:

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

@ZosFileHandler
public IZosFileHandler zosFileHandler;
...
IZosDataset dataSet = zosFileHandler.newDataset("GALASA.NEW.DATASET.PDS", zosImage);
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.memberStoreText(memberName, String.join("\n", records));
}

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

DSNTYPE=LIBRARY

use

dataSet.setDatasetType(DSType.LIBRARY);

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", zosImage);
vsamDataSet.setSpace(VSAMSpaceUnit.CYLINDERS, 1, 1);
vsamDataSet.setRecordSize(50, 101);
vsamDataSet.create();
Read the contents of a z/OS UNIX File

Create a new IZosDataset object representing a UNIX file. If the file exists, retrieve the content in text mode:

IZosUNIXFile unixFile = zosFileHandler.newUNIXFile("/tmp/Galasa/existingFile", zosImage);
if (unixFile.exists()) {
    unixFile.setDataType(UNIXFileDataType.TEXT);
    String content = unixFile.retrieve();
}
Read the contents of a z/OS UNIX File

Create a new IZosDataset object representing a new UNIX file. If UNIX file does not exist, create it. Write to the file in binary mode:

IZosUNIXFile unixFile = zosFileHandler.newUNIXFile("/tmp/Galasa/newFile", zosImage);
if (!unixFile.exists()) {
    unixFile.create();
}
List<String> properties = new ArrayList<>();
properties.add("dev.galasa.property1=value1");
properties.add("dev.galasa.property2=value2");
properties.add("dev.galasa.property3=value3");
unixFile.setDataType(UNIXFileDataType.BINARY);
unixFile.store(String.join("\n", properties));
List the contents of a z/OS UNIX Directory

Create a new IZosDataset object representing a new UNIX directory. If UNIX directory exists, list its contents:

IZosUNIXFile unixDirectory = zosFileHandler.newUNIXFile("/tmp/Galasa/", zosImage);
if (unixDirectory.exists())
{
    Map<String, String> dir = unixDirectory.directoryListRecursive();
    for (Map.Entry<String, String> entry : dir.entrySet()) {
        logger.info(String.format("%2$-9s: %1$s", entry.getKey(), entry.getValue()));
   }
}

Example output:

directory: /tmp/Galasa/dira
file     : /tmp/Galasa/dira/file1
file     : /tmp/Galasa/dira/file2
file     : /tmp/Galasa/existingFile
file     : /tmp/Galasa/newFile