Cssh doc fix 9222 8949 (#284)

Author: cssh-erik

docs/source/modules.rst

@@ -9,18 +9,31 @@ Modules
 Modules can be used in a playbook to automate tasks. Ansible® executes each
 module on the target node and returns the result back to the controller.
 
-The **IBM® z/OS® CICS® collection** provides modules for interacting with CMCI 
-over an HTTP connection by leveraging the `CMCI REST API`_, as well as modules
-to automate provisioning of a CICS TS region. These modules have different 
-requirements of the managed node. For more detail see :doc:`requirements_managed`.
+The **IBM® z/OS® CICS® collection** provides two categories of modules:
+
+* Modules for working with CICS and CICSPlex SM resources and definitions.
+  These modules interact with CMCI over an HTTP connection by leveraging
+  the `CMCI REST API`_. These modules are collectively referred to as
+  **CMCI modules** in documentation.
+* Modules for provisioning and deprovisioning of CICS TS regions and for
+  CICS startup and shutdown operations. These modules are collectively
+  referred to as CICS **provisioning modules** in documentation.
+
+These modules have different requirements of the managed node. For details, see :doc:`requirements_managed`.
 
 .. _CMCI REST API:
    https://www.ibm.com/docs/en/cics-ts/latest?topic=cmci-how-it-works-rest-api
 
-The region provisioning modules use two defaults groups that allow a 
-user to specify the location of a CICS installation and a high level qualifier 
-for all region data sets to be created under. The example below shows how to 
-use these default groups within the *cics_global_catalog* module.
+
+Using Defaults Groups in CICS Provisioning Modules
+---------------
+
+The CICS provisioning modules use several defaults groups. In particular, these two defaults groups are used for specific purposes:
+
+* ``cics_data_sets`` can be used to specify the location of a CICS installation.
+* ``region_data_sets`` can be used to specify a high level qualifier for the data sets used by a single CICS region.
+
+The example below shows how to use these default groups within the **global_catalog** module.
 
 .. code-block:: yaml+jinja
 
@@ -34,13 +47,12 @@ use these default groups within the *cics_global_catalog* module.
         state: "initial"
 
 
-In the above example, the global catalog will be created at the data set location 
-*REGIONS.ABCD0001.DFHGCD*, and the CICS load libraries can be found at the 
-location *CICSTS61.CICS*, which means that the SDFHLOAD library could be found at 
-*CICSTS61.CICS.SDFHLOAD*.
+In the above example, the global catalog is created at the data set location of ``REGIONS.ABCD0001.DFHGCD``,
+and the CICS load libraries can be found at ``CICSTS61.CICS``, which means that the SDFHLOAD library can be
+found at ``CICSTS61.CICS.SDFHLOAD``.
 
 These groups can be placed in a `module_defaults`_ section, which means that all 
-the CICS provisioning modules will use the same high level qualifier for the 
+the CICS provisioning modules use the same high level qualifier for the 
 region data sets, and the location of the CICS installation only has to be 
 declared once for all the modules.
 
@@ -64,6 +76,10 @@ for a global catalog data set below.
 .. _module_defaults:
     https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_module_defaults.html
 
+
+Module Reference
+---------------
+
 The **IBM® z/OS® CICS® collection** contains these modules. For each module,
 the accepted parameters, return values, and examples are provided in the
 documentation.

docs/source/modules/region_jcl.rst

@@ -8,8 +8,8 @@
 .. _region_jcl_module:
 
 
-region_jcl -- Create CICS region JCL data set
-=============================================
+region_jcl -- Create CICS startup JCL data set
+==============================================
 
 
 
@@ -20,7 +20,8 @@ region_jcl -- Create CICS region JCL data set
 
 Synopsis
 --------
-- Create a data set containing JCL to start a CICS® region by providing CICS system data sets and system initialization parameters for CICS startup using the \ :literal:`DFHSIP`\  program.
+- Create a data set containing the JCL to start a CICS® region.
+- The JCL is generated by your input of CICS system data sets and system initialization parameters for CICS startup using the \ :literal:`DFHSIP`\  program.
 
 
 
@@ -124,7 +125,7 @@ cpsm_data_sets
 
 
 dfhrpl
-  Any locations of additional DFHRPL libraries to add, that are not \ :literal:`SDFHLOAD`\ , \ :literal:`SCEECICS`\ , \ :literal:`SCEERUN`\ , or \ :literal:`SCEERUN2`\ .
+  Any locations of additional data sets other than \ :literal:`SDFHLOAD`\ , \ :literal:`SCEECICS`\ , \ :literal:`SCEERUN`\ , or \ :literal:`SCEERUN2`\ , to be added to the DFHRPL concatenation. The DFHRPL concatenation is where you specify the libraries that contain modules loaded by CICS, for example, the libraries containing your CICS application programs, your CICS control tables, and so on. You can either add data sets at the very top of the list or append them to the bottom of the list. There are other data sets in between, as determined by the defaults or other input parameters; for example, \ :literal:`SCEERUN`\  and \ :literal:`SCEERUN2`\  as specified with \ :literal:`le\_data\_sets`\ , \ :literal:`SDFHLOAD`\  as specified with \ :literal:`cics\_data\_sets`\ , and so on.
 
 
   | **required**: False
@@ -133,7 +134,7 @@ dfhrpl
 
 
   data_sets
-    The DFHRPL data sets to be appended to the bottom of the list.
+    The \ :literal:`DFHRPL`\  data sets to be added to the bottom of the list.
 
 
     | **required**: False
@@ -142,7 +143,7 @@ dfhrpl
 
 
   top_data_sets
-    The DFHRPL data sets to be appended to the very top of the statement.
+    The \ :literal:`DFHRPL`\  data sets to be added to the very top of the list.
 
 
     | **required**: False
@@ -3441,7 +3442,7 @@ space_primary
 
   This option takes effect only when the CICS startup JCL data set is being created. If the CICS startup JCL data set already exists, the option has no effect.
 
-  If this option is not set the primary space is dynamically calculated based on the size of the generated CICS startup JCL
+  If this option is not set, the primary space is dynamically calculated based on the size of the generated CICS startup JCL.
 
 
   | **required**: False
@@ -3454,7 +3455,7 @@ space_secondary
 
   This option takes effect only when the CICS startup JCL data set is being created. If the CICS startup JCL data set already exists, the option has no effect.
 
-  If this option is not set the primary space is dynamically calculated as 10% of the total size of the generated CICS startup JCL
+  If this option is not set, the secondary space is dynamically calculated as 10% of the total size of the generated CICS startup JCL.
 
 
   | **required**: False
@@ -3469,7 +3470,7 @@ space_type
 
   The size can be specified in megabytes (\ :literal:`M`\ ), kilobytes (\ :literal:`K`\ ), cylinders (\ :literal:`CYL`\ ), or tracks (\ :literal:`TRK`\ ).
 
-  If neither \ :literal:`space\_secondary`\  or \ :literal:`space\_primary`\  are set, then this value will not have any effect
+  If neither \ :literal:`space\_secondary`\  nor \ :literal:`space\_primary`\  is set, then this value does not have any effect.
 
 
   | **required**: False
@@ -3496,7 +3497,7 @@ state
 
 
 steplib
-  Any locations of additional \ :literal:`STEPLIB`\  libraries to add, that are not \ :literal:`SDFHAUTH`\ , \ :literal:`SDFHLIC`\ , \ :literal:`SCEERUN`\ , or \ :literal:`SCEERUN2`\ .
+  Any locations of additional data sets other than \ :literal:`SDFHAUTH`\ , \ :literal:`SDFHLIC`\ , \ :literal:`SCEERUN`\ , or \ :literal:`SCEERUN2`\ , to be added to the STEPLIB concatenation. The STEPLIB concatenation is where you specify the libraries that contain the modules loaded by the z/OS operating system. You can either add data sets at the very top of the list or append them to the bottom of the list. There are other data sets in between, as determined by the defaults or other input parameters; for example, \ :literal:`SEYUAUTH`\  and \ :literal:`SEYULOAD`\  as sepcified with \ :literal:`cpsm\_data\_sets`\ , \ :literal:`SCEERUN`\  and \ :literal:`SCEERUN2`\  as specified with \ :literal:`le\_data\_sets`\ , \ :literal:`SDFHAUTH`\  and \ :literal:`SDFHLIC`\  as specified with \ :literal:`cics\_data\_sets`\ , and so on.
 
 
   | **required**: False
@@ -3505,7 +3506,7 @@ steplib
 
 
   data_sets
-    The \ :literal:`STEPLIB`\  data sets to be appended to the bottom of the library list.
+    The \ :literal:`STEPLIB`\  data sets to be added to the bottom of the list.
 
 
     | **required**: False
@@ -3514,7 +3515,7 @@ steplib
 
 
   top_data_sets
-    The \ :literal:`STEPLIB`\  data sets to be appended to the very top of the statement.
+    The \ :literal:`STEPLIB`\  data sets to be added to the very top of the list.
 
 
     | **required**: False
@@ -3539,7 +3540,7 @@ Examples
 .. code-block:: yaml+jinja
 
 
-   - name: Create CICS region JCL data set
+   - name: Create CICS startup JCL data set
      ibm.ibm_zos_cics.region_jcl:
        applid: ABC9ABC1
        cics_data_sets:
@@ -3573,7 +3574,7 @@ Examples
          wrkarea: 2048
          sysidnt: ZPY1
 
-   - name: Create CICS region JCL data set with more customization
+   - name: Create CICS startup JCL data set with more customization
      ibm.ibm_zos_cics.region_jcl:
        applid: ABC9ABC1
        job_parameters:
@@ -3771,7 +3772,7 @@ Return Values
 
 
        msg
-        | A string containing an error message if applicable
+        | A string containing an error message if applicable.
       
         | **returned**: always
         | **type**: str

docs/source/playbooks.rst

@@ -12,7 +12,7 @@ functionality in the `samples repository`_.
 The sample playbooks fall into two categories:
 
 - Operations on CICS and CICSPlex SM resources and definitions. The sample playbooks use the CMCI modules to achieve various real-life use cases.
-- CICS provisioning. The sample playbook demonstrates how a set of modules for provisioning and managing CICS TS data sets and utilities can be used to provision, start, stop, and deprovision a CICS region.
+- CICS provisioning. The sample playbooks demonstrate how a set of modules for provisioning and managing CICS TS data sets and utilities can be used to provision and deprovision a CICS region and to perform CICS startup or shutdown operations.
 
 .. _samples repository:
    https://github.com/IBM/z_ansible_collections_samples
@@ -137,7 +137,7 @@ and group variables files may help you organize your variable values more
 easily. An example of one of these variable files is the `zos_host.yml`_
 file included with the `deploy_program sample`_, which is used to provide the
 required environment variables. Another such example is the `variables.yml`_ file
-included with the `CICS provisioning`_ playbook.
+included with the `CICS provisioning`_ playbooks.
 
 The properties that define the environment variables are as follows:
 
@@ -158,9 +158,10 @@ The properties that define the environment variables are as follows:
 
 .. note::
    In ZOAU 1.0.2 and later, the property **ZOAU_ROOT** is no longer supported
-   and can be replaced with the property **ZOAU_HOME**. If you are using ZOAU
-   version 1.0.1 or lower, you must continue to use the property
-   **ZOAU_ROOT** which is the ZOA Utilities install root path required for
+   and can be replaced with the property **ZOAU_HOME**.
+   
+   If you are using ZOAU version 1.0.1 or lower, you must continue to use the property
+   **ZOAU_ROOT**, which is the ZOA Utilities install root path required for
    ZOAU; for example, ``/usr/lpp/IBM/zoautil``.
 
 .. _zos_host.yml:
@@ -177,7 +178,7 @@ The properties that define the environment variables are as follows:
 Module Defaults
 ---------------
 
-Ansible has a module defaults feature to use the same values during every use of
+Ansible has a module defaults feature, which allows you to use the same values during every use of
 a module, rather than repeating them everytime.
 
 For example, when using CMCI modules to manage CICS and CICSPlex SM resources and definitions, you can set the host url and
@@ -206,14 +207,14 @@ to the group called **cmci**.
 
 
 Likewise, you can easily apply a default set of CICS TS data sets and utilities for the provisioning or de-provisioning of CICS regions.
-If you want to use the same values in **all** CICS TS data set provisioning modules, you can assign them to the group called **region_group**.
+If you want to use the same values in **all** CICS TS data set provisioning modules, you can assign them to the group called **region**.
 The following **module_defaults** example illustrates the use of a templated location for some data sets and a user-specified name for
 some other data sets instead of the template.
 
 .. code-block:: yaml
 
    module_defaults:
-     group/ibm.ibm_zos_cics.region_group:
+     group/ibm.ibm_zos_cics.region:
        state: initial
        cics_data_sets:
          template: "CTS610.CICS740.<< data_set_name >>"
@@ -222,18 +223,19 @@ some other data sets instead of the template.
          template: "{{ansible_user}}.REGIONS.{{applid}}.<< data_set_name >>"
          dfhgcd: "REGIONS.{{applid}}.GCD"
 
-The **cics_data_sets** parameter defines the data set names of the SDFHAUTH, SDFHLOAD and SDFHLIC libraries. These libraries can be used by
-multiple CICS regions. In this example, the SDFHLOAD and SDFHLIC libraries are created by default using the templated location
-of ``CTS610.CICS740.<< data_set_name >>``, so their data set names are ``CTS610.CICS740.SDFHLOAD`` and ``CTS610.CICS740.SDFHLIC`` respectively.
-However, SDFHAUTH is created with the data set name of ``CICSTS61.OVERRDE.TEMPLT.SDFHAUTH``, overriding the template.
+The **cics_data_sets** parameter defines a defaults group through which you can specify the location of a CICS installation. It is used to define
+the data set names of the SDFHAUTH, SDFHLOAD and SDFHLIC libraries. These libraries can be used by multiple CICS regions. In this example, the SDFHLOAD
+and SDFHLIC libraries are created by default using the templated location of ``CTS610.CICS740.<< data_set_name >>``, so their data set names are
+``CTS610.CICS740.SDFHLOAD`` and ``CTS610.CICS740.SDFHLIC`` respectively. However, the SDFHAUTH library is created with the data set name of
+``CICSTS61.OVERRDE.TEMPLT.SDFHAUTH``, overriding the template.
 
-The **region_data_sets** parameter defines the data sets that are used by a single CICS region. In this example, all the region data sets except
-DFHGCD are created by default using the templated location of ``{{ansible_user}}.REGIONS.{{applid}}.<< data_set_name >>``, while DFHGCD is created
-with the data set name of ``REGIONS.{{applid}}.GCD``, overriding the template.
+The **region_data_sets** parameter defines a defaults group through which you can specify a high level qualifier for the data sets that are used by a
+single CICS region. In this example, all the region data sets except DFHGCD are created by default using the templated location of
+``{{ansible_user}}.REGIONS.{{applid}}.<< data_set_name >>``, while DFHGCD is created with the data set name of ``REGIONS.{{applid}}.GCD``, overriding the template.
 
 
 .. note::
-   Group module defaults are only available in ``ansible-core`` 2.12 or later. If
+   Group module defaults are available in ``ansible-core`` 2.12 or later. If
    this syntax is used with ``ansible-core`` 2.11 or earlier, the values are
    perceived as not present, and a 'missing required arguments' error is thrown.
 
@@ -246,22 +248,30 @@ Access the `collection samples repository`_ and ensure you have navigated to
 the directory containing the playbook you want to run. For example:
 ``zos_subsystems/cics/cmci/deploy_program/``.
 
-Use the Ansible command ``ansible-playbook`` to run the sample playbook.  The
-command syntax is ``ansible-playbook -i <inventory> <playbook>`` which, using
-the example above of ``deploy_program``, is
-``ansible-playbook -i inventory deploy_program.yaml``.
+Use the Ansible command ``ansible-playbook`` to run the sample playbook.
+
+**Command Syntax**
+
+``ansible-playbook -i <inventory> <playbook>``
+
+Assuming the example above of ``deploy_program``, the command to issue is as follows:
+
+``ansible-playbook -i inventory deploy_program.yaml``
 
 This command assumes that the controller's public SSH key has been shared with
 the managed node. If you want to avoid entering a username and password each
-time, copy the SSH public key to the managed node using the ``ssh-copy-id``
-command; for example, ``ssh-copy-id -i ~/.ssh/mykey.pub user@<hostname>``.
+time, copy the SSH public key to the managed node by using the ``ssh-copy-id``
+command, as shown in the following example:
+
+``ssh-copy-id -i ~/.ssh/mykey.pub user@<hostname>``
+
+Alternatively, you can use the ``--ask-pass`` option, as shown in the following example, so that
+the user is prompted to enter a connection password each time a playbook is run.
 
-Alternatively, you can use the ``--ask-pass`` option to be prompted for the
-user's password each time a playbook is run; for example,
-``ansible-playbook -i inventory deploy_program.yaml --ask-pass``.
+``ansible-playbook -i inventory deploy_program.yaml --ask-pass``
 
 .. note::
-   * Using ``--ask-pass`` is not recommended because it will hinder performance.
+   * Using ``--ask-pass`` is not recommended because it hinders performance.
    * Using ``--ask-pass`` requires ``sshpass`` be installed on the controller.
      For further reference, see the `ask-pass documentation`_.
 
@@ -274,15 +284,15 @@ ERROR, DEBUG.
 
 .. note::
    It is a good practice to review the playbook samples before executing them.
-   It will help you understand what requirements in terms of space, location,
-   names, authority, and artifacts will be created and cleaned up. Although
+   This helps you understand what requirements are expected in terms of space, location,
+   names, authority, and artifacts that are created and cleaned up. Although
    samples are always written to operate without the need for the user's
    configuration, flexibility is written into the samples because it is not
-   easy to determine if a sample has access to the host's resources.
-   Review the playbook notes sections for additional details and
+   easy to determine whether a sample has access to the host's resources.
+   Review the notes sections in the playbooks for additional details and
    configuration.
 
-   Playbooks often submit JCL that is included in the samples repository
+   Playbooks often submit a JCL that is included in the samples repository
    under the `files directory`_. Review the sample JCL for necessary edits to
    allow for submission on the target system. The most common changes are to
    add a CLASS parameter and change the NOTIFY user parameter. For more details,
@@ -293,4 +303,4 @@ ERROR, DEBUG.
 .. _collection samples repository:
    https://github.com/IBM/z_ansible_collections_samples
 .. _files directory:
-   https://github.com/IBM/z_ansible_collections_samples/tree/main/zos_basics/constructs/files
+   https://github.com/IBM/z_ansible_collections_samples/tree/main/zos_basics/constructs/files