Add recommendations based on testing for PSWI deployment

docs/user-guide/configuring-at-tls-for-zowe-server.md

@@ -385,7 +385,7 @@ TTLSRule ZoweServerRule
 {
   LocalAddr All
   RemoteAddr All
-  LocalPortRange 7554-7559 # Range covers all possible Zowe services
+  LocalPortRange 7551-7559 # Range covers all possible Zowe services
   Jobname ZWE1*
   Direction Inbound
   TTLSGroupActionRef ServerGroupAction

docs/user-guide/install-zowe-pswi-acquire.md

@@ -21,7 +21,8 @@ To acquire the portable software instance, you can download it from the Zowe Dow
 2. Download the latest version of the package to your workstation.
 3. Use an file transfer utility such as an FTP client to transfer the single pax file to the mainframe.
 4. Execute the JCL to unpack the installation file and restore the individual pax files. Sample JCL follows:
-```
+
+```jcl
     //USSBATCH EXEC PGM=BPXBATCH
     //STDOUT DD SYSOUT=*
     //STDERR DD SYSOUT=*
@@ -30,13 +31,14 @@ To acquire the portable software instance, you can download it from the Zowe Dow
     pax -rvf yourpaxfilename.ZOSMF.pax.Z
     /*
 ```
-5. Customize the sample JCL as follows and then submit for execution:
+
+1. Customize the sample JCL as follows and then submit for execution:
 
     1. Add a JOB statement.
     2. Update the USS directory (*yourUSSpaxdirectory*) with the path name where you want to copy the pax file.
     3. Update *yourpaxfilename* with the name of the pax file that you want to copy to the mainframe.  
 
-:::tip Expected results: 
+:::tip Expected results:
 USSBATCH can take several minutes to execute. You will receive a return code of 0 if this job runs correctly.
 :::
 

docs/user-guide/install-zowe-pswi-deployment.md

@@ -5,7 +5,7 @@
 
 After the portable software instance or software instance is registered in z/OSMF, you can use z/OSMF Deployments to install the product software and create the product data sets (global, CSI, target libraries, and distribution libraries) for the new software instance. The deployment jobs create a copy of the source product data sets to create the product target runtime environment. Creating a copy of the SMP/E target data sets keeps the SMP/E environment clean and separates the product runtime environment for maintenance activities. You can also perform z/OSMF workflows to customize the SMP/E data sets, mount UNIX System Services (USS) files if necessary, and configure the new software instance on the target system.
 
-To install Zowe PSWI using z/OSMF and make the product software available for use on a system by users and other programs, you need to define a new deployment. This step defines the SMP/E environment name and the prefix of the CSI data set in z/OSMF. Specify data set allocation parameters for all SMP/E data sets, target libraries, and distribution libraries. 
+To install Zowe PSWI using z/OSMF and make the product software available for use on a system by users and other programs, you need to define a new deployment. This step defines the SMP/E environment name and the prefix of the CSI data set in z/OSMF. Specify data set allocation parameters for all SMP/E data sets, target libraries, and distribution libraries.
 
 To define a new deployment, complete the deployment checklist (specify the USS path, DSN, VOLSERs), and submit the deployment jobs through the z/OSMF user interface. When the deployment is complete, you have a source and target copy of the software.
 
@@ -41,20 +41,21 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re
         **Example:** `_targetpathname_**/staticpathextension**`.  
         **Note:** If your product does not include USS directories, ignore this instruction.
 
-    6. Define the job settings to generate the JCL to install the software and view the deployment summary. Update the JOB statement as needed.  
-    **Note:** If the target system for the deployment is in a JES Multi-Access Spool (MAS) and the mount point is only accessible from the target system, add a System Affinity (SYSAFF) to the job card to ensure execution on the system where the zFS resides.
+    6. Define the job settings to generate the JCL to install the software and view the deployment summary. Update the JOB statement as needed.
+
+        **Note:** If the target system for the deployment is in a JES Multi-Access Spool (MAS) and the mount point is only accessible from the target system, add a System Affinity (SYSAFF) to the job card to ensure execution on the system where the zFS resides.
 
     7. Submit the deployment jobs in sequential order, wait for each job to complete, and then select **Refresh** to register job completion in z/OSMF.  
     :::tip Expected results:
     You will receive a return code of 0 if this job runs correctly. When all deployment jobs are executed successfully, you have unzipped, renamed and copied the product data sets, updated the CSI data set, and specified the properties for the target software instance.
     :::
-    
+
     8. Complete **Mount Workflow** to mount the Zowe zFS. Complete both steps in the workflow. Perform the following steps to execute each step individually:
        1. Click the title of the step.
        2. Select the Perform tab.
        3. Review the step contents and update the JCL if needed.
        4. Select Next.
-       5. Repeat the previous two steps to complete all items until the Finish option is available. 
+       5. Repeat the previous two steps to complete all items until the Finish option is available.
 
     9. (Optional) To configure your Zowe instance, follow the procedure in [Configuring Zowe with z/OSMF Workflows](configure-zowe-zosmf-workflow.md).
 
@@ -64,3 +65,28 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re
         **Note:** You do not have to execute all workflows during PSWI provisioning in z/OSMF immediately.
 
 The deployment process is complete. The new software instance is defined to z/OSMF. You are now ready to Import Product Information into z/OSMF before you install product maintenance.
+
+## Recommendations
+
+### Cleanup
+
+If the job execution fails, the deployment process does not perform a full cleanup of the datasets, before attempting it again, make sure the following datasets are deleted:
+
+```plaintext
+{TARGET_HLQ}.D.AZWEAUTH.#
+{TARGET_HLQ}.D.AZWEZFS.#
+{TARGET_HLQ}.SMPLOG.#
+{TARGET_HLQ}.SMPLOGA.#
+{TARGET_HLQ}.SMPLTS.#
+{TARGET_HLQ}.SMPMTS.#
+{TARGET_HLQ}.SMPSCDS.#
+{TARGET_HLQ}.T.SZWEAUTH.#
+{TARGET_HLQ}.T.SZWEEXEC.#
+{TARGET_HLQ}.T.SZWELOAD.#
+
+{TARGET_HLQ}.CSI.#
+```
+
+### Resources
+
+It is recommended to update the job card to run with `REGION=0M`, particularly for job `IZUD01DZ` which unpaxes the contents.

docs/user-guide/install-zowe-pswi.md

@@ -3,7 +3,7 @@
 As a systems programmer, your responsibilities include acquiring, installing, maintaining, and configuring mainframe products on your systems. z/OSMF lets you perform these tasks. z/OSMF lets you manage software on your z/OS systems through a browser at any time, from any location. By streamlining some traditional tasks and automating others, z/OSMF can simplify some areas of system management and also reduce the level of expertise that is required for managing system activities. Experienced users can view, define, and update policies that affect system behavior, monitor system performance, and manage their z/OS software.
 As products and vendors adopt z/OSMF services, you can install and maintain all your mainframe products in a common way according to industry best practices. After configuration is complete, you can execute the product and easily provision new software instances for use on other systems throughout your environment.
 
-## End-to-end installation diagram 
+## End-to-end installation diagram
 
 ![PSWI installation diagram](../images/install/PSWI-install.png)
 
@@ -19,19 +19,20 @@ To install Zowe using z/OSMF, ensure that you meet the following requirements:
 
 Refer to the following subpages to guide you through the installation procedure using z/OSMF.
 
-* [Address z/OSMF Requirements](./install-zowe-pswi-address-requirements.md)
+- [Address z/OSMF Requirements](./install-zowe-pswi-address-requirements.md)
 
 Provides information about z/OSMF general configuration and security requirements.
 
-* [Acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire.md)
+- [Acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire.md)
 
 Provides the steps to acquire the product software by downloading the z/OSMF portable software instance to the z/OSMF host. You must then register the portable software instance in z/OSMF.
 
-* [Install Product Software Using z/OSMF Deployments](./install-zowe-pswi-deployment.md) 
+- [Install Product Software Using z/OSMF Deployments](./install-zowe-pswi-deployment.md)
 
 Provides the steps to install (deploy) the portable software instance to an LPAR using z/OSMF Deployments. This step creates the SMP/E environment and runs the RECEIVE, APPLY, and ACCEPT steps to prepare the software instance for SMP/E operations. This step also:
-    * Customizes the data set names that are defined to SMP/E.
-    * Mounts required USS files if necessary.
-    * Performs workflow execution to customize the deployed runtime environment for use on a specific z/OS system.
+
+- Customizes the data set names that are defined to SMP/E.
+- Mounts required USS files if necessary.
+- Performs workflow execution to customize the deployed runtime environment for use on a specific z/OS system.
 
 When these tasks are completed, you are ready to install preventive maintenance.

versioned_docs/version-v2.18.x/user-guide/configuring-at-tls-for-zowe-server.md

@@ -209,7 +209,7 @@ TTLSRule ApimlClientRule
   LocalAddr All
   LocalPortRange 1024-65535
   RemoteAddr All
-  RemotePortRange 7551-7555 # Range covers API ML services (gateway, discovery, api catalog, caching service)
+  RemotePortRange 7551-7559 # Range covers API ML services (gateway, discovery, api catalog, caching service)
   Jobname ZWE1A* # Generate according to zowe.job.prefix in zowe.yaml
   Direction Outbound
   TTLSGroupActionRef ClientGroupAction
@@ -393,7 +393,7 @@ TTLSRule ZoweServerRule
 {
   LocalAddr All
   RemoteAddr All
-  LocalPortRange 7554-7559 # Range covers all possible Zowe services
+  LocalPortRange 7551-7559 # Range covers all possible Zowe services
   Jobname ZWE1*
   Direction Inbound
   TTLSGroupActionRef ServerGroupAction

versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-acquire.md

@@ -21,7 +21,8 @@ To acquire the portable software instance, you can download it from the Zowe Dow
 2. Download the latest version of the package to your workstation.
 3. Use an file transfer utility such as an FTP client to transfer the single pax file to the mainframe.
 4. Execute the JCL to unpack the installation file and restore the individual pax files. Sample JCL follows:
-```
+
+```jcl
     //USSBATCH EXEC PGM=BPXBATCH
     //STDOUT DD SYSOUT=*
     //STDERR DD SYSOUT=*
@@ -30,13 +31,14 @@ To acquire the portable software instance, you can download it from the Zowe Dow
     pax -rvf yourpaxfilename.ZOSMF.pax.Z
     /*
 ```
-5. Customize the sample JCL as follows and then submit for execution:
+
+1. Customize the sample JCL as follows and then submit for execution:
 
     1. Add a JOB statement.
     2. Update the USS directory (*yourUSSpaxdirectory*) with the path name where you want to copy the pax file.
     3. Update *yourpaxfilename* with the name of the pax file that you want to copy to the mainframe.  
 
-:::tip Expected results: 
+:::tip Expected results:
 USSBATCH can take several minutes to execute. You will receive a return code of 0 if this job runs correctly.
 :::
 

versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md

@@ -5,7 +5,7 @@
 
 After the portable software instance or software instance is registered in z/OSMF, you can use z/OSMF Deployments to install the product software and create the product data sets (global, CSI, target libraries, and distribution libraries) for the new software instance. The deployment jobs create a copy of the source product data sets to create the product target runtime environment. Creating a copy of the SMP/E target data sets keeps the SMP/E environment clean and separates the product runtime environment for maintenance activities. You can also perform z/OSMF workflows to customize the SMP/E data sets, mount UNIX System Services (USS) files if necessary, and configure the new software instance on the target system.
 
-To install Zowe PSWI using z/OSMF and make the product software available for use on a system by users and other programs, you need to define a new deployment. This step defines the SMP/E environment name and the prefix of the CSI data set in z/OSMF. Specify data set allocation parameters for all SMP/E data sets, target libraries, and distribution libraries. 
+To install Zowe PSWI using z/OSMF and make the product software available for use on a system by users and other programs, you need to define a new deployment. This step defines the SMP/E environment name and the prefix of the CSI data set in z/OSMF. Specify data set allocation parameters for all SMP/E data sets, target libraries, and distribution libraries.
 
 To define a new deployment, complete the deployment checklist (specify the USS path, DSN, VOLSERs), and submit the deployment jobs through the z/OSMF user interface. When the deployment is complete, you have a source and target copy of the software.
 
@@ -41,20 +41,21 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re
         **Example:** `_targetpathname_**/staticpathextension**`.  
         **Note:** If your product does not include USS directories, ignore this instruction.
 
-    6. Define the job settings to generate the JCL to install the software and view the deployment summary. Update the JOB statement as needed.  
-    **Note:** If the target system for the deployment is in a JES Multi-Access Spool (MAS) and the mount point is only accessible from the target system, add a System Affinity (SYSAFF) to the job card to ensure execution on the system where the zFS resides.
+    6. Define the job settings to generate the JCL to install the software and view the deployment summary. Update the JOB statement as needed.
+
+        **Note:** If the target system for the deployment is in a JES Multi-Access Spool (MAS) and the mount point is only accessible from the target system, add a System Affinity (SYSAFF) to the job card to ensure execution on the system where the zFS resides.
 
     7. Submit the deployment jobs in sequential order, wait for each job to complete, and then select **Refresh** to register job completion in z/OSMF.  
-    :::tip Expected results: 
+    :::tip Expected results:
     You will receive a return code of 0 if this job runs correctly. When all deployment jobs are executed successfully, you have unzipped, renamed and copied the product data sets, updated the CSI data set, and specified the properties for the target software instance.
     :::
-     
+
     8. Complete **Mount Workflow** to mount the Zowe zFS. Complete both steps in the workflow. Perform the following steps to execute each step individually:
        1. Click the title of the step.
        2. Select the Perform tab.
        3. Review the step contents and update the JCL if needed.
        4. Select Next.
-       5. Repeat the previous two steps to complete all items until the Finish option is available. 
+       5. Repeat the previous two steps to complete all items until the Finish option is available.
 
     9. (Optional) To configure your Zowe instance, follow the procedure in [Configuring Zowe with z/OSMF Workflows](configure-zowe-zosmf-workflow.md).
 
@@ -64,3 +65,28 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re
         **Note:** You do not have to execute all workflows during PSWI provisioning in z/OSMF immediately.
 
 The deployment process is complete. The new software instance is defined to z/OSMF. You are now ready to Import Product Information into z/OSMF before you install product maintenance.
+
+## Recommendations
+
+### Cleanup
+
+If the job execution fails, the deployment process does not perform a full cleanup of the datasets, before attempting it again, make sure the following datasets are deleted:
+
+```plaintext
+{TARGET_HLQ}.D.AZWEAUTH.#
+{TARGET_HLQ}.D.AZWEZFS.#
+{TARGET_HLQ}.SMPLOG.#
+{TARGET_HLQ}.SMPLOGA.#
+{TARGET_HLQ}.SMPLTS.#
+{TARGET_HLQ}.SMPMTS.#
+{TARGET_HLQ}.SMPSCDS.#
+{TARGET_HLQ}.T.SZWEAUTH.#
+{TARGET_HLQ}.T.SZWEEXEC.#
+{TARGET_HLQ}.T.SZWELOAD.#
+
+{TARGET_HLQ}.CSI.#
+```
+
+### Resources
+
+It is recommended to update the job card to run with `REGION=0M`, particularly for job `IZUD01DZ` which unpaxes the contents.

versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi.md

@@ -3,7 +3,7 @@
 As a systems programmer, your responsibilities include acquiring, installing, maintaining, and configuring mainframe products on your systems. z/OSMF lets you perform these tasks. z/OSMF lets you manage software on your z/OS systems through a browser at any time, from any location. By streamlining some traditional tasks and automating others, z/OSMF can simplify some areas of system management and also reduce the level of expertise that is required for managing system activities. Experienced users can view, define, and update policies that affect system behavior, monitor system performance, and manage their z/OS software.
 As products and vendors adopt z/OSMF services, you can install and maintain all your mainframe products in a common way according to industry best practices. After configuration is complete, you can execute the product and easily provision new software instances for use on other systems throughout your environment.
 
-## End-to-end installation diagram 
+## End-to-end installation diagram
 
 ![PSWI installation diagram](../images/install/PSWI-install.png)
 
@@ -19,19 +19,20 @@ To install Zowe using z/OSMF, ensure that you meet the following requirements:
 
 Refer to the following subpages to guide you through the installation procedure using z/OSMF.
 
-* [Address z/OSMF Requirements](./install-zowe-pswi-address-requirements.md)
+- [Address z/OSMF Requirements](./install-zowe-pswi-address-requirements.md)
 
 Provides information about z/OSMF general configuration and security requirements.
 
-* [Acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire.md)
+- [Acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire.md)
 
 Provides the steps to acquire the product software by downloading the z/OSMF portable software instance to the z/OSMF host. You must then register the portable software instance in z/OSMF.
 
-* [Install Product Software Using z/OSMF Deployments](./install-zowe-pswi-deployment.md) 
+- [Install Product Software Using z/OSMF Deployments](./install-zowe-pswi-deployment.md)
 
 Provides the steps to install (deploy) the portable software instance to an LPAR using z/OSMF Deployments. This step creates the SMP/E environment and runs the RECEIVE, APPLY, and ACCEPT steps to prepare the software instance for SMP/E operations. This step also:
-    * Customizes the data set names that are defined to SMP/E.
-    * Mounts required USS files if necessary.
-    * Performs workflow execution to customize the deployed runtime environment for use on a specific z/OS system.
+
+- Customizes the data set names that are defined to SMP/E.
+- Mounts required USS files if necessary.
+- Performs workflow execution to customize the deployed runtime environment for use on a specific z/OS system.
 
 When these tasks are completed, you are ready to install preventive maintenance.