The datasets block in your grace.yml file is used to define the default names for key z/OS Partitioned Data Sets (PDS or PDSE) that Grace will interact with during its operations. These settings provide a centralized place to specify your site's or project's naming conventions for common dataset types.

While these are global defaults for the workflow, some can be overridden at the individual job level if a specific job needs to use a different PDS (see the datasets sub-block within a job definition).

config:
  # ...
 
datasets:
  jcl: MYPROJ.DEVL.JCL
  src: MYPROJ.DEVL.SOURCE
  loadlib: MYPROJ.DEVL.LOADLIB
 
jobs:
  # ...

Required fields

jcl

datasets:
  jcl: IBMUSER.PROJECT.JCL

• Type: String
• Description: Specifies the full name of the Partitioned Data Set (PDS or PDSE) where Grace will store JCL members.
  • When grace deck processes jobs that require JCL (e.g. compile, linkedit, execute) and the job does not use jcl: zos://
    • If Grace generates the JCL (default behavior or from a jcl: file:// user template), the resulting JCL is written to a member within this PDS. The member name will be the uppercase version of the job.name.
  • Example:
    • If job.name is CMPCBL and datasets.jcl is MY.APP.JCL, Grace uploads to MY.APP.JCL(CMPCBL).
  • This PDS must exist or be creatable by the Zowe user profile specified in config.profile. grace deck will attempt to create it if it doesn't exist.

src

datasets:
  src: IBMUSER.PROJECT.COBOL.SOURCE

• Type: String
• Description: Specifies the full name of the PDS where Grace will upload local source files referenced via src:// paths in job inputs.
  • When grace deck encounters an input like path: src://myprog.cbl, it will upload the local file your_workflow/src/myprog.cbl to a member in the PDS.
  • The member name is derived from the filename by converting it to uppercase and removing common extensions (e.g. myprog.cbl becomes MYPROG)
  • This PDS must exist or be creatable by the Zowe user profile specified in config.profile. grace deck will attempt to create it if it doesn't exist and src:// inputs are present.

loadlib

datasets:
  loadlib: IBMUSER.PROJECT.LOAD

• Type: String
• Description: Specifies the full name of the PDS that will serve as the default target load library for linkedit jobs and as the default STEPLIB for execute jobs.
  • For linkedit jobs: The output load module (specified by job.program) will be written to this PDS.
  • For execute jobs: If the job's JCL is generated by Grace, it will include a STEPLIB DD statement pointing to this loadlib to find the program specified in job.program.
  • Unlike jcl and src datasets, grace deck checks if this loadlib exists but does not automatically create it. The load library is expected to be a pre-existing, properly allocated PDS (often a PDSE for load modules).

Naming conventions and validation

All dataset names specified in the datasets block (and any job-level overrides) must adhere to standard z/OS dataset naming conventions:

• Qualifiers are separated by periods (.).
• Each qualifier can be 1 to 8 characters long.
• The first character of a qualifier must be alphabetic (A-Z) or national (#, @, $). Subsequent characters can be alphanumeric or national. Hyphens are generally not permitted by Grace's validation for simplicity, aligning with common practices on z/OS environments.
• The total length of the dataset name, including periods, typically cannot exceed 44 characters.
• Grace performs validation on these names via the grace lint command and before grace deck operations.

Refer to the IBM documentation on z/OS dataset naming rules.

These datasets definitions are fundamental to how Grace organizes and manages mainframe artifacts related to your workflow. Ensuring they are correct for your target z/OS environment is a key part of setting up a Grace workflow.