Automated commit to update documentation

_sources/ibm_zos_cics/docs/ansible_content.rst.txt

@@ -1,24 +1,28 @@
 .. ...........................................................................
-.. © Copyright IBM Corporation 2020,2021                                     .
+.. © Copyright IBM Corporation 2020,2024                                     .
 .. ...........................................................................
 
 =========
 z/OS CICS
 =========
 
 The **IBM® z/OS® CICS® collection**, also represented as
-ibm_zos_cics in this document, is  part of the broader
+ibm_zos_cics in this document, is part of the broader
 initiative to bring Ansible® Automation to IBM Z® through the offering
 **Red Hat® Ansible Certified Content for IBM Z**.
 
-The **IBM® z/OS® CICS® collection** supports automation tasks that can
-define, install, and perform actions on CICS definitions and resources such as
-creating a PROGRAM definition, installing and updating it, and deleting the
-definition.
+The **IBM® z/OS® CICS® collection** provides modules for automation tasks that
+perform operations on CICS and CICSPlex SM resources and definitions, for example,
+creating and installing a PROGRAM definition, then updating or deleting the definition.
+These modules interact with the `CMCI REST API`_ of the CICS® management client
+interface (CMCI) for system management.
 
-The Ansible modules in this collection are written in Python and interact with
-the `CMCI REST API`_ of the CICS® management client interface (CMCI) for system
-management.
+The **IBM® z/OS® CICS® collection** also provides modules for provisioning and managing
+CICS TS data sets and utilities. You can use these Ansible modules to create automation
+tasks that provision or deprovision a CICS region and tasks for CICS startup and
+shutdown.
+
+The Ansible modules in this collection are written in Python.
 
 .. _CMCI REST API:
    https://www.ibm.com/docs/en/cics-ts/latest?topic=cmci-how-it-works-rest-api

_sources/ibm_zos_cics/docs/source/modules.rst.txt

@@ -9,6 +9,77 @@ 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 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
+
+
+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
+
+
+    - name: Initialize a global catalog
+      ibm.ibm_zos_cics.global_catalog:
+        region_data_sets:
+          template: "REGIONS.ABCD0001.<< data_set_name >>"
+        cics_data_sets:
+          template: "CICSTS61.CICS.<< lib_name >>"
+        state: "initial"
+
+
+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 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.
+
+To override the data set location or name for a specific task, you can provide an 
+additional parameter to the ``region_data_sets`` group as shown in the example 
+for a global catalog data set below.
+
+.. code-block:: yaml+jinja
+
+
+    - name: Initialize a global catalog with a custom name
+      ibm.ibm_zos_cics.global_catalog:
+        region_data_sets:
+          dfhgcd:
+            dsn: "MY.CICS.GLOBAL.CATALOG"
+        cics_data_sets:
+          template: "CICSTS61.CICS.<< lib_name >>"
+        state: "initial"
+
+
+.. _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.