Migrate to JCL: update

.github/workflows/link-checker.yml

@@ -26,16 +26,24 @@ jobs:
           done
 
       - name: Restore lychee cache
-        uses: actions/cache@v4
+        id: lychee-cache-restore
+        uses: actions/cache/restore@v4
         with:
           path: .lycheecache
-          key: cache-lychee-${{ github.base_ref || github.ref_name }}
+          key: cache-lychee-${{ github.event.pull_request.head.ref || github.base_ref || github.ref_name }}
           restore-keys: cache-lychee-
-          save-always: true
 
       - name: Run lychee
         uses: lycheeverse/lychee-action@v1
         with:
           args: "--accept 403,406,429 --cache --include-fragments --max-cache-age 1d --max-concurrency 2 --no-progress --timeout 60 --verbose 'docs/**/*.md'"
           fail: true
           token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Always save lychee cache
+        id: save-lychee-cache
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+            key: ${{ steps.lychee-cache-restore.outputs.cache-primary-key }}
+            path: .lycheecache

docs/user-guide/configure-zowe-runtime.md

@@ -18,7 +18,7 @@ After your installation of Zowe runtime, you can run the `zwe init` command to p
 * Create user IDs and security manager settings (Security Admin)
 * Provide APF authorize load libraries (Security Admin)
 * Configure Zowe to use TLS certificates (Security Admin)
-* Configure VSAM files to run the Zowe caching service used for high availability (HA)
+* Configure the Zowe caching service for high availability (HA)
 * Configure the system to launch the Zowe started task
 
 For more information about this z/OS runtime initialization method, see [Configuring Zowe with zwe init](./initialize-zos-system.md)

docs/user-guide/configuring-zowe-via-jcl.md

@@ -1,6 +1,129 @@
- # Configuring Zowe via JCL
+ # Configuring Zowe with JCL
 
-One option to configure Zowe is by directly customizing JCLs. The Zowe Runtime Dataset `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.
+:::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](./installandconfig.md#zowe-configuration-file-zoweyaml). Between these two options, we recommend sticking with `zwe` commands rather than manually submitting JCL from scratch, as there's additional validation we can perform on your configuration prior to creating and submitting JCL.
+
+- [Getting started with `zwe` and JCL](#getting-started-with-zwe-and-jcl)
+  - [Generating JCL](#generating-jcl)
+  - [Adding Job Parameters to generated JCL](#adding-job-parameters-to-generated-jcl)
+  - [Reviewing JCL before submission](#reviewing-jcl-before-submission)
+  - [Following existing `zwe` command documentation](#following-existing-zwe-command-documentation)
+  - [Following existing z/OSMF workflows](#following-existing-zosmf-workflow-documentation)
+- [Getting started with manual JCL submission](#getting-started-with-manual-jcl-submission)
+  - [Preparing the JCL](#preparing-the-jcl)
+  - [Manual JCL Core Tasks](#manual-jcl-core-tasks)
+  - [Manual JCL Keyring Tasks](#manual-jcl-keyring-tasks)
+  - [Manual JCL Caching Service VSAM Task (Deprecated)](#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:
+```yaml
+zowe:
+  setup:
+    jcl:
+      enable: true
+```
+
+Example commands: `--jcl` overrides `zowe.setup.jcl.enable`
+```shell
+zwe install -c /path/to/your/zowe.yaml --jcl
+zwe init mvs -c /path/to/your/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:
+
+```shell
+zwe init generate -c /path/to/your/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` dataset 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 dataset already exists, you must add `--allow-overwrite` to the `init generate` command.
+```yaml
+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. Line 1 requires no formatting, while lines 2 and onward require you to supply `//  ` before the job parameters. 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:
+```yaml
+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  line:
+```yaml
+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 outputs, or you can review their JCL in the `JCLLIB` dataset created by `init generate`.  We recommend reviewing using `--dry-run`.
+
+### 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.
+
+That's it!
+
+### Following existing z/OSMF workflow documentation
+
+Both the [Zowe Configuration Workflow](https://docs.zowe.org/stable/user-guide/configure-apiml-zosmf-workflow) and the [Stand-alone APIML Workflow](https://docs.zowe.org/stable/user-guide/configure-apiml-zosmf-workflow) support JCL enablement. When you start your configuration, you will see the option to enable JCL and a field labeled with `Job statement positionial parameters...` where you can fill in job statement information. 
+**Note:** Unlike when editing the zowe.yaml file directly, do not enter a start-of-line `// ` for lines 2 or more in the workflow text field. This 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.
+
+![Workflow](../images/zosmf/inputvars-jcl-enable.png)
+
+## 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 datasets. Do note that you will still need a zowe.yaml file.
+
+### Preparing the JCL
+
+The Zowe Runtime Dataset `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`.
 
@@ -13,11 +136,11 @@ Edit and submit the job `SZWESAMP(ZWEGENER)` to validate the contents of your `z
 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](#core-tasks). 
-* For sample JCLs corresponding to keyring tasks, see the section [Keyring Tasks](#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](#deprecated-caching-service-vsam-task).
+* For sample JCLs corresponding to core tasks, see the table [Core Tasks](#manual-jcl-core-tasks). 
+* For sample JCLs corresponding to keyring tasks, see the section [Keyring Tasks](#manual-jcl-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-caching-service-vsam-task-deprecated).
 
-## Core Tasks
+## Manual JCL Core Tasks 
 
 | Task | Description | Sample JCL|
 |------|-------------|-----------|
@@ -27,7 +150,7 @@ In addition to core JCL samples, you can also customize JCL samples for various
  |(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](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEIRACZ) <br />TSS: [ZWEITSSZ](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEITSSZ) <br />ACF2: [ZWEIACFZ](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEIACFZ)
  Copy STC JCL to PROCLIB | <br />**Purpose:**<br /> 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. <br /> **Action:**<br /> 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](https://github.com/zowe/zowe-install-packaging/blob/v2.x/staging/files/SZWESAMP/ZWEISTC)
 
-## Keyring Tasks
+## Manual JCL Keyring Tasks
 **Certificate requirements**  
 Ensure that your Zowe keyring has the following elements:
 
@@ -64,7 +187,7 @@ zowe:
 </details>
 
 
-## (Deprecated) Caching Service VSAM Task 
+## 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.
 

docs/user-guide/initialize-zos-system.md

@@ -6,9 +6,10 @@ Once you complete the installation of the Zowe runtime, begin configuration by i
 :::
 
 ## About the `zwe init` command
-
-The `zwe init` command is a combination of the following subcommands. Each subcommand defines a configuration.
-
+ Each subcommand defines a configuration.
+The `zwe init` command is a combination of the following subcommands. Except the generate, each subcommand defines a configuration.
+- **generate**
+Generates ready to execute JCL samples from YAML configuration values.
 - **mvs**
 Copies the data sets provided with Zowe to custom data sets.
 - **security**
@@ -31,22 +32,9 @@ We recommend you to run these sub commands one by one to clearly see the output
 Enter `zwe init --help` to learn more about the command or see the [`zwe init` command reference](../appendix/zwe_server_command_reference/zwe/init/zwe-init-vsam.md) for detailed explanation, examples, and parameters.
 :::
 
-## zwe init arguments
-
-The following `zwe init` arguments can assist you with the initization process:
-
-- **--update-config**  
- This argument allows the init process to update your configuration file based on automatic detection and your `zowe.setup` settings. For example, if `java.home` and `node.home` are not defined, they can be updated based on the information that is collected on the system. `zowe.certificate` section can also be updated automatically based on your `zowe.setup.certificate` settings.
-- **--allow-overwrite**  
- This argument allows you to rerun the `zwe init` command repeatedly regardless of whether some data sets are already created.
-- **-v** or **--verbose**  
-   This argument provides execution details of the `zwe` command. You can use it for troubleshooting purposes if the error message is not clear enough.
-- **-vv** or **--trace**  
- This argument provides you more execution details than the `--verbose` mode for troubleshooting purposes.
-
 ## Zowe initilization command
 
-The `zwe init` command runs the subcommands in sequence automatically. If you have the Zowe configuration file preparted and have security administrator privileges, or security and certificates setup was already completed on the system, you can run the following command:
+The `zwe init` command runs the subcommands in sequence automatically. If you have the Zowe configuration file prepared and have security administrator privileges, or security and certificates setup was already completed on the system, you can run the following command:
 
 ```
 zwe init --config /path/to/zowe.yaml