Merge branch 'master' into reboot/doc/fix-caching

.github/workflows/build-docs.yml

@@ -36,14 +36,14 @@ jobs:
           # https://github.com/actions/checkout/issues/520#issuecomment-1320838255
           fetch-depth: 2147483647
 
-      - name: Use Node.js LTS
-        uses: actions/setup-node@v3
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           cache: 'npm'
 
       - name: Cache Webpack Build
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         env:
           TAR_OPTIONS: "--remove-files"
         with:
@@ -59,7 +59,7 @@ jobs:
       - name: Deploy to Netlify
         id: deploy
         if: ${{ github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository }}
-        uses: nwtgck/actions-netlify@v2
+        uses: nwtgck/actions-netlify@v3
         with:
           publish-dir: build
           production-branch: master
@@ -74,13 +74,11 @@ jobs:
 
       - name: Compress Build Archive
         if: ${{ steps.deploy.conclusion == 'skipped' }}
-        run: |
-          echo "PR_NUMBER=${{ github.event.pull_request.number }}" > build/.env
-          tar --remove-files --zstd -cf build.tar.zst build
+        run: tar --label=${{ github.event.pull_request.number }} --remove-files --zstd -cf build.tar.zst build
 
       - name: Upload Build Artifact
         if: ${{ steps.deploy.conclusion == 'skipped' }}
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: preview-build
           path: build.tar.zst

.github/workflows/deploy-preview.yml

@@ -19,7 +19,7 @@ jobs:
     steps:
       - name: Download Build Artifact
         id: download-artifact
-        uses: dawidd6/action-download-artifact@v2
+        uses: dawidd6/action-download-artifact@v6
         with:
           workflow: build-docs.yml
           run_id: ${{ github.event.workflow_run.id }}
@@ -29,13 +29,14 @@ jobs:
       - name: Extract Build Archive
         if: ${{ steps.download-artifact.outputs.found_artifact == 'true' }}
         run: |
-          tar -xf build.tar.zst && rm build.tar.zst
-          cat build/.env >> "$GITHUB_ENV" && rm build/.env
+          tar -xf build.tar.zst
+          printf "PR_NUMBER=%d\n" "$(tar --test-label -f build.tar.zst)" >> "$GITHUB_ENV"
+          rm build.tar.zst
 
       - name: Deploy to Netlify
         id: deploy
         if: ${{ steps.download-artifact.outputs.found_artifact == 'true' }}
-        uses: nwtgck/actions-netlify@v2
+        uses: nwtgck/actions-netlify@v3
         with:
           publish-dir: build
           production-deploy: false

docs/user-guide/install-zowe-zos-convenience-build.md

@@ -1,10 +1,10 @@
 # Installing the z/OS Build via Convenience Build (PAX file)
 
-You install the Zowe™ convenience build by obtaining a PAX file and using this to create the Zowe runtime environment.
+You can install the Zowe™ convenience build by obtaining a PAX file which is used to create the Zowe runtime environment.
 
 ## Introduction
 
-The Zowe installation file for Zowe z/OS components is distributed as a PAX file that contains the runtimes and the scripts to install and launch the z/OS runtime. You must obtain the PAX file and transfer it to z/OS first. Then, to install, configure and start Zowe, you use the `zwe` command. This command defines help messages, logging options, and more. For details about how to use this command, see the [ZWE Server Command Reference](../appendix/zwe_server_command_reference/zwe/zwe.md).  
+The Zowe installation file for Zowe z/OS components is distributed as a PAX file that contains the runtimes and the scripts to install and launch the z/OS runtime. You must obtain the PAX file and transfer it to z/OS first. Then, to install, configure, and start Zowe, you use the `zwe` command. This command defines help messages, logging options, and more. For details about how to use this command, see the [ZWE Server Command Reference](../appendix/zwe_server_command_reference/zwe/zwe.md).  
 
 The configuration data that is read by the `zwe` command are stored in a YAML configuration file named `zowe.yaml`. You modify the `zowe.yaml` file based on your environment. 
 
@@ -17,7 +17,7 @@ Complete the following steps to install the Zowe runtime.
 ## Step 1: Obtain the convenience build
 
 1. To download the PAX file, open your web browser on the [Zowe Download](https://www.zowe.org/download.html) website.
-2. Navigate to **Zowe V2 Preview** -> **Convenience build** section, and select the button to download the v2 convenience build.
+2. Navigate to **Zowe V3** -> **Zowe 3.v.p z/OS Convenience build** section, and select the button to download the v3 convenience build.
 
 ## Step 2: Transfer the convenience build to USS and expand it
 
@@ -52,11 +52,20 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont
     ```
     put <zowe-V.v.p>.pax
     ```
+    where:
 
-    `zowe-V.v.p` is a variable that indicates the name of the PAX file you downloaded.
+    * `zowe-V.v.p`  
+    is a variable that indicates the name of the PAX file you downloaded.
 
     **Note:** When your terminal is connected to z/OS through FTP or SFTP, you can prepend commands with `l` to have them issued against your desktop.  To list the contents of a directory on your desktop, type `lls` where `ls` lists contents of a directory on z/OS.
 
+    :::tip
+    You can simplify `sftp` usage for existing directory:
+    ```
+    echo 'put <zowe-V.v.p>.pax' | sftp [email protected]:/path/to/zowe/runtime
+    ```
+    :::
+
     After the PAX file has sucessfully transferred, exit your `sftp` or `ftp` session.
 
 1. Open a USS shell to expand the PAX file. This can either be an ssh terminal, OMVS, iShell, or any other z/OS unix system services command environment. 
@@ -67,9 +76,11 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont
    pax -ppx -rf <zowe-V.v.p>.pax
    ```
 
-   Where _zowe-V.v.p_ is a variable that indicates the name of the PAX file you downloaded.  When extracting the Zowe convenience build, you must always include the `-ppx` argument that preserves extended attributes.  
+   where:  
+   *  `zowe-V.v.p`  
+  is a variable that indicates the name of the PAX file you downloaded.  When extracting the Zowe convenience build, you must always include the `-ppx` argument that preserves extended attributes.  
 
-  This will expand to a file structure similar to the following one.
+  This command expands to a file structure similar to the following one:
 
    ```
       /bin
@@ -80,7 +91,7 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont
 
    This is the Zowe runtime directory and is referred to as `<RUNTIME_DIR>` throughout this documentation.  
 
-   **Note:** Zowe version 1 had a script `zowe-install.sh` that created a separate Zowe runtime directory from the expanded contents of the Zowe PAX file. Zowe v2 no longer has this step. **In Zowe v2, the contents of the expanded Zowe PAX file are the Zowe runtime directory.**
+   **Note:** In Zowe v2, and Zowe v3 the contents of the expanded Zowe PAX file are the Zowe runtime directory.
 
 ## Step 3: (Optional) Add the `zwe` command to your PATH
 
@@ -90,22 +101,26 @@ The `zwe` command is provided in the `<RUNTIME_DIR>/bin` directory. You can opti
 export PATH=${PATH}:<RUNTIME_DIR>/bin
 ```
 
-`<RUNTIME_DIR>` should be replaced with your real Zowe runtime directory path. This will update the `PATH` for the current shell. To make this update persistent, you can add the line to your `~/.profile` file, or the `~/.bashProfile` file if you are using a bash shell. To make this update system wide, you can update the `/etc/.profile` file. Once the PATH is updated, you can execute the `zwe` command from any USS directory. For the remainder of the documentation when `zwe` command is referenced, it is assumed that it has been added to your `PATH`. 
+`<RUNTIME_DIR>` should be replaced with your real Zowe runtime directory path. This will update the `PATH` for the current shell. To make this update persistent, you can add the line to your `~/.profile` file, or the `~/.bashProfile` file if you are using a bash shell. To make this update system wide, you can update the `/etc/.profile` file. Once the `PATH` is updated, you can execute the `zwe` command from any USS directory. For the remainder of the documentation when `zwe` command is referenced, it is assumed that it has been added to your `PATH`.
 
-The `zwe` command has built in help that can be retrieved with the `-h` suffix. For example, type `zwe -h` to display all of the supported commands. These are broken down into a number of sub-commands.  
+The `zwe` command has built in help that can be retrieved with the `-h` option. For example, type `zwe -h` to display all of the supported commands. These are broken down into a number of sub-commands:
 
 ```
 zwe -h
  ...
 Available sub-command(s):
   - certificate
   - components
+  - config
+  - diagnose
   - init
   - install
   - internal
+  - migrate
   - sample
   - start
   - stop
+  - support
   - version
 ```
 
@@ -116,7 +131,7 @@ Copy the template file `<RUNTIME_DIR>/example-zowe.yaml` file to a new location,
 When you execute the `zwe` command, the `-c` argument is used to pass the location of a `zowe.yaml` file.  
 
 :::tip
-To avoid passing `--config` or `-c` to every `zwe` commands, you can define `ZWE_CLI_PARAMETER_CONFIG` environment variable points to location of zowe.yaml.
+To avoid passing `--config` or `-c` to every `zwe` commands, you can define `ZWE_CLI_PARAMETER_CONFIG` environment variable pointing to location of `zowe.yaml`.
 
 For example, after defining
 
@@ -133,29 +148,60 @@ After you extract the Zowe convenience build, you can run the [`zwe install` com
 
 ### About the MVS data sets
 
-Zowe includes a number of files that are stored in the following three data sets. See the following table for the storage requirements.
+Zowe includes a number of files that are stored in the various data sets. See the following table for the storage requirements.
 
 Library DDNAME | Member Type | Target Volume | Type | Org | RECFM | LRECL | No. of 3390 Trks | No. of DIR Blks
 ---|---|---|---|---|---|---|---|---
 SZWESAMP | Samples | ANY | U | PDSE | FB | 80 | 15 | 5
 SZWEAUTH | Zowe APF Load Modules | ANY | U | PDSE | U | 0 | 15 | N/A
 SZWEEXEC | CLIST copy utilities | ANY | U | PDSE | FB | 80 | 15 | 5
+SZWELOAD | Executable utilities library | ANY | U | PDSE | U | 0 | 15 | N/A
 
 The `SZWESAMP` data set contains the following members.
 
-Member name | Purpose
----|---
-ZWESECUR | JCL member to configure z/OS user IDs and permissions required to run Zowe
-ZWENOSEC | JCL member to undo the configuration steps performed in ZWESECUR and revert z/OS environment changes.
-ZWEKRING | JCL member to configure a z/OS keyring containing the Zowe certificate
-ZWENOKYR | JCL member to undo the configuration steps performed in ZWEKRING
-ZWESLSTC | JCL to start Zowe
-ZWEXMSTC | JCL to start the Zowe cross memory server
-ZWESIP00 | Parmlib member for the cross memory server
-ZWESASTC | Started task JCL for the cross memory Auxiliary server
-ZWESIPRG | Console commands to APF authorize the cross memory server load library
-ZWESISCH | PPT entries required by Cross memory server and its Auxiliary address spaces to run in Key(4)
-ZWECSVSM | JCL Member to create the VSAM data set for the caching service 
+Member name | Type | Purpose
+---|---|---
+ZWECSRVS | JCL | Removes the VSAM data set for the Caching Service
+ZWECSVSM | JCL | Creates the VSAM data set for the Caching Service
+ZWEGENER | JCL | Generates JCL templates to configure Zowe
+ZWEIACF | JCL | Defines security permits for ACF2
+ZWEIACFZ | JCL | Creates the ACF2 Zowe resource class
+ZWEIAPF | JCL | Set APF for the required datasets
+ZWEIAPF2| JCL | Set APF for the required datasets
+ZWEIKRA1 | JCL | Defines ACF2 key ring and certificates
+ZWEIKRA2 | JCL | Defines ACF2 key ring and certificates
+ZWEIKRA3 | JCL | Defines ACF2 key ring and certificates
+ZWEIKRR1 | JCL | Defines RACF key ring and certificates
+ZWEIKRR2 | JCL | Defines RACF key ring and certificates
+ZWEIKRR3 | JCL | Defines RACF key ring and certificates
+ZWEIKRT1 | JCL | Defines TSS key ring and certificates
+ZWEIKRT2 | JCL | Defines TSS key ring and certificates
+ZWEIKRT3 | JCL | Defines TSS key ring and certificates
+ZWEIMVS | JCL | Creates datasets used by a Zowe instance
+ZWEIMVS2 | JCL | Creates the load library (expected to be APF)
+ZWEINSTL | JCL | Creates and copies basic installation datasets and members
+ZWEIRAC  | JCL | Defines security permits for RACF
+ZWEIRACZ | JCL | Creates the RACF Zowe resource class
+ZWEISTC | JCL | Adds `PROCLIB` members
+ZWEITSS | JCL | Defines security permits for TSS
+ZWEITSSZ | JCL | Creates the TSS Zowe resource class
+ZWEKRING | JCL | Defines key ring and certificates
+ZWENOKRA | JCL | Removes key ring and certificates for ACF2
+ZWENOKRR | JCL | Removes key ring and certificates for RACF
+ZWENOKRT | JCL | Removes key ring and certificates for TSS
+ZWENOKYR | JCL | Removes key ring and certificates
+ZWENOSEC | JCL | Defines security permits
+ZWERMVS | JCL | Removes datasets used by a Zowe instance
+ZWERMVS2 | JCL | Removes the APF load library
+ZWERSTC | JCL | Removes `PROCLIB` members
+ZWESASTC | JCL | Starts the Zowe Auxiliary server used by Cross memory server
+ZWESECKG | JCL | Sample program which generates a secret key for the PKCS#11 token
+ZWESECUR | JCL | Defines security permits for Zowe
+ZWESIPRG | Commands | Console commands to APF authorize the cross memory server load library
+ZWESIP00 | PARMLIB | Member for the cross memory server
+ZWESISCH | PPT | Defines entries required by Cross memory server and its Auxiliary address spaces to run in Key(4) 
+ZWESISTC | JCL | Starts the Zowe Cross memory server
+ZWESLSTC | JCL | Starts the Zowe
 
 The `SZWEAUTH` data set is a load library containing the following members.
 
@@ -164,9 +210,12 @@ Member name | Purpose
 ZWELNCH | The Zowe launcher that controls the startup, restart and shutdown of Zowe's address spaces
 ZWESIS01 | Load module for the cross memory server
 ZWESAUX  | Load module for the cross memory server's auxiliary address space
+ZWESISDL | ZIS Dynamic Plug-in
 
 The `SZWEEXEC` data set contains few utilities used by Zowe.
 
+The `SZWELOAD` data set contains config manager for REXX.
+
 ### Procedure
 
 The high level qualifer (or HLQ) for these data sets is specified in the `zowe.yaml` section below. Ensure that you update the `zowe.setup.dataset.prefix` value to match your system.  
@@ -180,7 +229,7 @@ zowe:
 ```
 
 To create and install the MVS data sets, use the command `zwe install`.
-1. In a USS shell, execute the command `zwe install -c /path/to/zowe.yaml`. This creates the three data sets and copy across their content.
+1. In a USS shell, execute the command `zwe install -c /path/to/zowe.yaml`. This creates the data sets and copy across their content.
 2. If the data sets already exist, specify `--allow-overwritten`.  
 3. To see the full list of parameters, execute the command `zwe install -h`. 
 
@@ -194,6 +243,7 @@ A sample run of the command is shown below using default values.
 Create MVS data sets if they are not exist
 Creating Zowe sample library - IBMUSER.ZWEV2.SZWESAMP
 Creating Zowe authorized load library - IBMUSER.ZWEV2.SZWEAUTH
+Creating Zowe load library - IBMUSER.ZWEV2.SZWELOAD
 Creating Zowe executable utilities library - IBMUSER.ZWEV2.SZWEEXEC
 
 Copy files/SZWESAMP/ZWESIPRG to IBMUSER.ZWEV2.SZWESAMP
@@ -212,4 +262,4 @@ Copy components/zss/LOADLIB/ZWESAUX to IBMUSER.ZWEV2.SZWEAUTH
 
 ## Next steps
 
-You successfully installed Zowe from the convenience build! However, before you start Zowe, you must complete several required configurations. Next, go to [Initialize the z/OS system and permissions](initialize-zos-system.md) to initialize your z/OS system for Zowe first. 
+You successfully installed Zowe from the convenience build! However, before you start Zowe, you must complete several required configurations. The next step is [Initializing Zowe z/OS runtime](./configure-zowe-runtime.md).