The .grace/deck/ directory is an operational subdirectory created and managed by Grace within your workflow workspace. Its primary purpose is to store the Job Control Language (JCL) files that Grace generates or processes before they are potentially uploaded to the mainframe.

your-workflow-name/
├── .grace/
│   ├── deck/             # <-- Generated/processed JCL files
│   │   ├── JOB1.jcl
│   │   └── JOB2.jcl
│   └── logs/
│       └── ...
├── src/
│   └── ...
└── grace.yml

This directory is typically located at .grace/deck/ relative to your grace.yml file.

Purpose and contents

When you run the grace deck command, Grace performs several actions related to JCL processing for each z/OS job type (compile, linkedit, execute) defined in your grace.yml:

1. JCL generation/sourcing:

   • Default templates: If a job does not specify a jcl: source, Grace uses its internal JCL templates for that job type. It populates these templates with data derived from your grace.yml (e.g., program names, dataset names for DD statements, compiler/linker options).

   • User-Provided file:// JCL: If a job specifies jcl: file://path/to/your.jcl or jcl: file://path/to/your.jcl.tmpl, Grace reads this local file.

     • If the file contains template syntax (and --no-compile is not used), Grace renders it using data from grace.yml.
     • If the file is plain JCL, or if --no-compile is used, Grace uses the file content as-is.

2. Local storage:

   • The resulting JCL (either fully generated by Grace or processed from a user's file:// source) for each job is written as a separate file into the .grace/deck/ directory.
   • The filename corresponds to the job name, e.g., a job named CMPHELLO will result in a .grace/deck/CMPHELLO.jcl file.

3. Source for upload:

   • If uploads are enabled (i.e., --no-upload is not specified), the JCL files within .grace/deck/ are then uploaded by grace deck to the PDS specified in your datasets.jcl configuration (e.g., YOUR.HLQ.JCL(JOBNAME)).

What about jcl: zos://?

If a job in grace.yml uses jcl: zos://EXISTING.PDS(MEMBER), Grace does not generate or resolve any JCL for that specific job in the .grace/deck/ directory. The JCL is assumed to already exist on the mainframe.

Key behaviors

• Created by grace deck:

  • The .grace/deck/ directory and its contents are primarily managed by the grace deck command.

• Inspectable output:

  • This directory provides a tangible place for you to inspect the exact JCL that Grace has prepared before it's uploaded or submitted.
  • This is useful for debugging JCL issues or understanding how Grace translates your grace.yml into JCL.

• Effect of --no-compile:

  • For jobs using Grace's default templates: No JCL file is written to .grace/deck/ by the current command invocation. If a file existed from a previous run, it remains.
  • For jobs using jcl: file://...: The content of the user's local file (template or static) is copied as-is into .grace/deck/JOBNAME.jcl without any template rendering.

• Source for grace run:

  • When you execute grace run, it does not look into .grace/deck/. It expects the JCL to have already been uploaded to the mainframe PDS (specified in datasets.jcl) by a prior grace deck command, or to exist at a specified zos:// location.

Version control (.gitignore)

Since the contents of .grace/deck/ are generated by Grace based on your grace.yml and local JCL/template files, this directory is often a good candidate to be added to your project's .gitignore file.

# .gitignore
.grace/deck/*

Exception: You might choose not to ignore .grace/deck/ (and commit its contents) if:

• You generate the JCL with grace deck.
• You then manually edit the JCL files within .grace/deck/ for fine-tuning.
• You subsequently use grace deck --no-compile to upload these manually edited versions. In this specific workflow, the committed files in .grace/deck/ become your source of truth for the uploaded JCL.

Understanding the role of the .grace/deck/ directory helps you manage your Grace workflow, debug JCL, and decide on your version control strategy for generated artifacts.