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