Configuring Zowe with JCL

note

Configuring Zowe with JCL is currently in technical preview. In a later release, this will become the default method of configuration.

Zowe can be configured on your system with JCL using the zwe commands, or by customizing and running JCL entirely manually. Both of these configuration methods require a zowe.yaml configuration file. Between these two options, we recommend sticking with zwe commands rather than manually submitting JCL, as there's additional validation zwe can perform on your configuration prior to creating and submitting JCL.

• Getting started with zwe and JCL
  • Generating JCL
  • Adding Job Parameters to generated JCL
  • Reviewing JCL before submission
  • Following existing zwe command documentation
  • Following existing z/OSMF workflows
• Getting started with manual JCL submission
  • Preparing the JCL
  • Manual JCL Core Tasks
  • Manual JCL Keyring Tasks
  • Manual JCL Caching Service VSAM Task (Deprecated)

Getting started with zwe and JCL

By default, zwe will not submit solely JCL to configure Zowe, instead relying on a mix of unix services and JCL. To enable zwe to rely solely on JCL, you can either add --jcl to the end of every zwe install or zwe init command, or set zowe.setup.jcl.enable in your zowe.yaml file.

Example zowe.yaml:

zowe:
  setup:
    jcl:
      enable: true

Example commands: --jcl overrides zowe.setup.jcl.enable

zwe install -c /path/to/my/zowe.yaml --jcl
zwe init mvs -c /path/to/my/zowe.yaml --jcl

Generating JCL

Running zwe init commands with JCL require that you to first generate JCL using values present in your zowe.yaml file. To do this, run:

zwe init generate -c /path/to/my/zowe.yaml

This takes the configuration values present in your zowe.yaml file, uses them to populate JCL templates in SZWESAMP, and creates a JCLLIB data set with the final generated JCL. The JCLLIB will be created using the value of zowe.setup.dataset.jcllib.

For example, zwe init generate with the below zowe.yaml creates the dataset MY.DS.PREFIX.JCLLIB. If this data set already exists, it is always overwritten by init generate command.

zowe:
  setup:
    dataset:
      # ... other fields
      jcllib: MY.DS.PREFIX.JCLLIB

important

If you make any changes to values which begin with zowe.setup in your zowe.yaml file, you must re-run zwe init generate to create fresh JCL. Optionally, zwe init commands provide a --generate flag which will run init generate on-the-fly as well. For example, zwe init mvs --generate will run init generate before the init mvs.

Adding Job Parameters to generated JCL

If you require specific job parameters to run JCL on your system, you can add them via the zowe.setup.jcl.header field in your zowe.yaml file. The zwe commands will not validate the syntax of the supplied parameters, so you should always review the generated JCL to ensure the headers are correct.

This header field can be supplied as either a single or multi-line string. The first line requires no formatting, while next lines require you to follow JCL syntax. If using a single line for the header field, use \n to indicate new lines. If using multi-line strings, ensure your indentation remains aligned with each new line.

Example zowe.yaml, with header as a single line:

zowe:
  setup:
    jcl: 
      enable: true
      # Double quotes are required around the entire string:
      header: "'ZWECFJOB'\n//   REGION=0M\n//* atestcomment"
    dataset: # ...the rest of your zowe.yaml

Example zowe.yaml, with header as multi-line field:

zowe:
  setup:
    jcl: 
      enable: true
      # Ensure spacing is aligned here, column 1 is under the 'a' of 'header'
      header: |
        'ZWECFJOB',
        //   REGION=0M
        //* atestcomment
    dataset: # ...the rest of your zowe.yaml

Both zowe.yaml files create the below job card:

//ZWEGENER JOB 'ZWECFJOB',
//   REGION=0M
//* atestcomment

Reviewing JCL before submission

One advantage to JCL is the ability to review all the actions it will take on your system before submitting it. There are a few ways to review JCL used by zwe before submission. All zwe init and zwe install commands support the --dry-run command line parameter, which will print the command's final JCL to the console and exit. When running zwe init generate or zwe install specifically, this is the only way to review the final JCL prior to submission. For other zwe init commands, you can choose to run them with --dry-run and review the console output, or you can review their JCL in the JCLLIB dataset created by init generate. We recommend reviewing using --dry-run, and inspecting the JCLLIB only if --dry-run is insufficient.

Following existing zwe command documentation

To configure Zowe successfully with JCL, you can follow all existing documentation for zwe install and zwe init with minor modifications:

1. Setup JCL enablement and JCL job parameters as described in this guide first.
2. Run zwe init generate before any other init command, and after any change to a zowe.setup field in the zowe.yaml file.

Differences to note:

1. zwe init security no longer submits ZWESECUR, and instead uses ZWEI***, where *** is your configured ESM.

Following existing z/OSMF workflow documentation

Both the Zowe Configuration Workflow and the Stand-alone APIML Workflow support configuration with JCL. When you start your configuration, you will see the option to enable JCL and a field labeled with Job statement positional parameters... where you can fill in job statement information. Note: Do not enter a start-of-line // for lines 2 or later in the workflow text field; it will be added automatically for you. This entire text field can be left blank if you do not need to add any job statement parameters. Once you have reviewed and set these fields, follow the workflow instructions normally.

Getting started with manual JCL submission

If you do not wish to use the zwe command-line tool to configure Zowe, you can submit the same set of JCL yourself directly through MVS data sets. Do note that you will still need a zowe.yaml file.

Preparing the JCL

The Zowe Sample Data set SZWESAMP contains JCL samples that have templates referencing Zowe YAML parameters. These samples should not be submitted without modification. Samples that are submitted without modification will end unsuccessfully with a JCL ERROR status.

Edit and submit the job SZWESAMP(ZWEGENER) to validate the contents of your zowe.yaml before resolving the JCL templates and placing the resulting JCL into a separate data set created by the job ZWEGENER. The location is specified in zowe.setup.dataset.jcllib.

note

zowe.setup.dataset.jcllib is deleted and created each time the job SZWESAMP(ZWEGENER) is submitted.

When the JCL is prepared, the following jobs can be submitted to perform the following instance configuration actions. In addition to core JCL samples, you can also customize JCL samples for various keyring setup options according to your security manager.

• For sample JCLs corresponding to core tasks, see the table Core Tasks.
• For sample JCLs corresponding to keyring tasks, see the section Keyring Tasks later in this article.
• For JCL samples if you are using VSAM as your storage solution for the Caching service, see the table corresponding to (Deprecated) Caching Service VSAM Task.

Manual JCL Core Tasks

Task	Description	Sample JCL
Create Instance Data sets	Purpose: Create data sets for Zowe's PARMLIB content and non-ZFS extension content for a given Zowe Instance Action: 1) Allocate the PDSE FB80 data set with at least 15 tracks named from Zowe parameter zowe.setup.dataset.parmlib 2) Allocate the PDSE FB80 data set with at least 30 tracks named from Zowe parameter zowe.setup.dataset.authPluginLib 3) Copy the member ZWESIP00 from zowe.setup.dataset.prefix.SZWESAMP into zowe.setup.dataset.parmlib	ZWEIMVS
APF Authorize privileged content	Purpose: The majority of Zowe is unprivileged code running in Key 8. Zowe relies on a single component called ZIS to own all of the privileged code logic. The load library for the ZIS component and its extension library must be set as APF authorized and run in Key 4 to use ZIS and components that depend upon it. Action: 1) APF authorize the data sets defined at zowe.setup.dataset.authLoadlib and zowe.setup.dataset.authPluginLib. 2) Define PPT entries for the members ZWESIS01 and ZWESAUX as Key 4, NOSWAP in the SCHEDxx member of the system PARMLIB.	ZWEIAPF2
Grant SAF permissions	Purpose: The STC accounts for Zowe need permissions for operating servers, and users need permissions for interacting with the servers. Action: Set SAF permissions for accounts	RACF: ZWEIRAC TSS: ZWEITSS ACF2: ZWEIACF
(z/OS v2.4 ONLY) Create Zowe SAF Resource Class	On z/OS v2.4, the SAF resource class for Zowe is not included, and must be created. This step is not needed on z/OS v2.5 and later versions.	RACF: ZWEIRACZ TSS: ZWEITSSZ ACF2: ZWEIACFZ
Copy STC JCL to PROCLIB	Purpose: The job ZWESLSTC runs Zowe's webservers. The job ZWESISTC runs the APF authorized cross-memory server. The job ZWESASTC is started by ZWESISTC on an as-needed basis. Action: Copy the members ZWESLSTC, ZWESISTC, and ZWESASTC into your desired PROCLIB. If the job names are customized, also modify the YAML values of them in zowe.setup.security.stcs.	ZWEISTC

Manual JCL Keyring Tasks

Certificate requirements
Ensure that your Zowe keyring has the following elements:

• Private key & certificate pair
  The Zowe Servers will use this certificate. Ensure that the certificate either does not have the Extended Key Usage attribute, or alternatively, that the certificate does have Extended Key Usage with both Server Authorization and Client Authorization values. For more information about extended key usage, see Extended key usage heading in the article Configuring certificates.

• Certificate Authorities
  Every intermediate and root Certificate Authority (CA) that Zowe interacts with must be within the Keyring, unless the zowe.yaml value zowe.verifyCertificates is set to DISABLED. CAs that must be within the keyring include z/OSMF's CAs if using z/OSMF, and Zowe's own certificate's CAs as Zowe servers must be able to verify each other.

There are four options for setting up keyrings: Three scenarios presented in the following table include JCL samples where a keyring is created for you. If you already have a keyring, you can configure Zowe to use this keyring by configuring zowe.yaml values within zowe.certificate according to the following example:

zowe:
  certificate:
    keystore:
      type: JCERACFKS
      file: "safkeyring://<STC Account Name>/<Ring Name>"
      alias: "<Name of your certificate>"
      password: "password" #literally "password". keyrings do not use passwords, so this is a placeholder.
    truststore:
      type: JCERACFKS
      file: "safkeyring://<STC Account Name>/<Ring Name>"
      password: "password" #literally "password". keyrings do not use passwords, so this is a placeholder.

If you would like Zowe to create a keyring instead, click here for options

Keyring Setup Type	Description	Sample JCL
1	Zowe will create a keyring and populate it with a newly generated certificate and certificate authority. The certificate would be seen as "self-signed" by clients unless import of the CA to clients is performed	RACF: ZWEIKRR1 TSS: ZWEIKRT1 ACF2: ZWEIKRA1
2	Zowe will create a keyring and populate it by connecting pre-existing certificates and CAs that you specify.	RACF: [ZWEIKRR2]https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEIKRR2) TSS: ZWEIKRT2 ACF2: ZWEIKRA2
3	Zowe will create a keyring and populate it by importing PKCS12 content from a dataset that you specify.	RACF: ZWEIKRR3 TSS: ZWEIKRT3 ACF2: ZWEIKRA3

Manual JCL Caching Service VSAM Task (Deprecated)

The Caching Service is a server of Zowe that improves the high availability and fault tolerance of Zowe. It is enabled by default and uses Infinispan for its backing storage by default.

Using VSAM instead of Infinispan is deprecated, but still possible.

Click here to see how to set up a VSAM dataset for the Caching Service.

Task	Description	Sample JCL
Create VSAM Dataset for Caching Service	Action: Create a RLS or NONRLS dataset for the caching service, and set the name into the YAML value components.caching-service.storage.vsam.name	ZWECSVSM

You can also use JCL samples for removing Zowe configuration:

Action	Sample JCL
Remove Instance Data sets	ZWERMVS
Remove SAF Permissions	ZWENOSEC
Remove Keyring	ACF2: ZWENOKRA RACF: ZWENOKRR TSS: ZWENOKRT
Remove Caching Service VSAM Data set	ZWECSRVS