editorial edits

Author: cssh-erik

docs/source/modules/region_jcl.rst

@@ -3446,7 +3446,7 @@ space_primary
 
   If this option is not set, the primary space is dynamically calculated based on the size of the generated CICS startup JCL.
 
-  If the target data set is a member in a PDS/E, then this value will not have any effect.
+  If the target data set is a member in a PDSE, then this value does not have any effect.
 
 
   | **required**: False
@@ -3461,7 +3461,7 @@ space_secondary
 
   If this option is not set, the secondary space is dynamically calculated as 10% of the total size of the generated CICS startup JCL.
 
-  If the target data set is a member in a PDS/E, then this value will not have any effect.
+  If the target data set is a member in a PDSE, then this value does not have any effect.
 
 
   | **required**: False
@@ -3478,7 +3478,7 @@ space_type
 
   If neither \ :literal:`space\_secondary`\  nor \ :literal:`space\_primary`\  is set, then this value does not have any effect.
 
-  If the target data set is a member in a PDS/E, then this value will not have any effect.
+  If the target data set is a member in a PDSE, then this value does not have any effect.
 
 
   | **required**: False

docs/source/modules/stop_region.rst

@@ -20,12 +20,11 @@ stop_region -- Stop a CICS region
 
 Synopsis
 --------
-- Stop a CICS region by issuing a CEMT PERFORM SHUTDOWN, or cancel the job using ZOAU's job cancelling capability.
-- The job\_id, job\_name, or both can be used to shutdown a region. If mulitple jobs are running with the same name, the job\_id is required.
-- You can choose the shutdown mode from NORMAL, IMMEDIATE, or CANCEL.
+- Stop a CICS region by issuing a CEMT PERFORM SHUTDOWN command, or by canceling the job through the \ :literal:`jobs.cancel`\  utility provided by Z Open Automation Utilities (ZOAU). You can choose the shutdown mode from NORMAL, IMMEDIATE, or CANCEL.
+- The \ :literal:`job\_id`\ , \ :literal:`job\_name`\ , or both can be used to shut down a CICS region. If mulitple jobs are running with the same name, the \ :literal:`job\_id`\  is required.
 - During a NORMAL or IMMEDIATE shutdown, a shutdown assist transaction should run to enable CICS to shut down in a controlled manner. By default, the CICS-supplied shutdown assist transaction, CESD is used. You can specify a custom shutdown assist transaction in the SDTRAN system initialization parameter. The task runs until the region has successfully shut down, or until the shutdown fails.
-- You must have a console installed in the CICS region so that the stop\_region module can communicate with CICS. To define a console, you must install a terminal with the CONSNAME attribute set to your TSO user ID. For detailed instructions, see \ `Defining TSO users as console devices <https://www.ibm.com/docs/en/cics-ts/6.1?topic=cics-defining-tso-users-as-console-devices>`__\ . Add your console definition into one of the resource lists defined on the GRPLIST system initialization parameter so that it gets installed into the CICS region. Alternatively, you can use a DFHCSDUP script to update an existing CSD. This function is provided by the csd module.
-- You may specify a timeout, in seconds, to wait for the region to stop after issuing the command. If this timeout is reached, the module completes in a failed state. Default behaviour does not use a timeout, which is set using a value of -1.
+- You must have a console installed in the CICS region so that the stop\_region module can communicate with CICS. To define a console, you must install a terminal with the CONSNAME attribute set to your TSO user ID. For detailed instructions, see \ `Defining TSO users as console devices <https://www.ibm.com/docs/en/cics-ts/latest?topic=cics-defining-tso-users-as-console-devices>`__\ . Add your console definition into one of the resource lists defined on the GRPLIST system initialization parameter so that it gets installed into the CICS region. Alternatively, you can use a DFHCSDUP script to update an existing CSD. This function is provided by the csd module.
+- You can specify a timeout, in seconds, for CICS shutdown processing. After a request to stop CICS is issued, if CICS shutdown processing is not completed when this timeout is reached, the module completes in a failed state. By default, the stop\_region module does not use a timeout, that is, the \ :literal:`timeout`\  parameter assumes a value of -1.
 
 
 
@@ -52,7 +51,7 @@ job_name
 
   The stop\_region module uses this job name to identify the state of the CICS region and shut it down.
 
-  The job\_name must be unique; if multiple jobs with the same name are running, use job\_id.
+  The \ :literal:`job\_name`\  must be unique; if multiple jobs with the same name are running, use \ :literal:`job\_id`\ .
 
 
   | **required**: False
@@ -63,6 +62,12 @@ job_name
 mode
   Specify the type of shutdown to be executed on the CICS region.
 
+  Specify \ :literal:`normal`\  to perform a normal shutdown. This instructs the stop\_region module to issue a CEMT PERFORM SHUTDOWN command.
+
+  Specify \ :literal:`immediate`\  to perform an immediate shutdown. This instructs the stop\_region module to issue a CEMT PERFORM SHUTDOWN IMMEDIATE command.
+
+  Specify \ :literal:`cancel`\  to cancel the CICS region. This instructs the stop\_region module to use ZOAU's \ :literal:`jobs.cancel`\  utility to process the request.
+
 
   | **required**: False
   | **type**: str
@@ -92,7 +97,7 @@ sdtran
 
 
 timeout
-  Time to wait for region to stop, in seconds.
+  The maximum time, in seconds, to wait for CICS shutdown processing to complete.
 
   Specify -1 to exclude a timeout.
 
@@ -110,26 +115,26 @@ Examples
 .. code-block:: yaml+jinja
 
 
-   - name: "Stop CICS region"
+   - name: "Stop CICS region using job ID"
      ibm.ibm_zos_cics.stop_region:
        job_id: JOB12345
 
-   - name: "Stop CICS region immediately"
+   - name: "Stop CICS region immediately using job ID"
      ibm.ibm_zos_cics.stop_region:
        job_id: JOB12354
        mode: immediate
 
-   - name: "Stop CICS region with name and ID"
+   - name: "Stop CICS region using job name and job ID"
      ibm.ibm_zos_cics.stop_region:
        job_id: JOB12354
        job_name: MYREG01
 
-   - name: "Stop CICS using job name"
+   - name: "Stop CICS region using job name"
      ibm.ibm_zos_cics.stop_region:
        job_name: ANS1234
        mode: normal
 
-   - name: "Cancel CICS region"
+   - name: "Cancel CICS region using job name"
      ibm.ibm_zos_cics.stop_region:
        job_name: ANS1234
        mode: cancel
@@ -213,7 +218,7 @@ Return Values
 
 
          jobs
-            | The output information for a list of jobs matching specified criteria.
+            | The output information for a list of jobs matching the specified criteria.
       
             | **returned**: on zos_job_query module execution
             | **type**: list
@@ -336,15 +341,15 @@ Return Values
 
 
          max_rc
-            | The maximum return code from the tso status command
+            | The maximum return code from the TSO status command
       
             | **returned**: on zos_tso_command module execution
             | **type**: int
       
 
 
          output
-            | The output from the tso command
+            | The output from the TSO command.
       
             | **returned**: on zos_tso_command module execution
             | **type**: list
@@ -390,7 +395,7 @@ Return Values
 
 
        msg
-        | A string containing an error message if applicable
+        | A string containing an error message if applicable.
       
         | **returned**: always
         | **type**: str

plugins/doc_fragments/region_jcl.py

@@ -19,8 +19,7 @@ class ModuleDocFragment(object):
         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 the target data set is a member in a PDS/E, then this value will not have any
-        effect.
+      - If the target data set is a member in a PDSE, then this value does not have any effect.
     type: int
     required: false
   space_secondary:
@@ -31,8 +30,7 @@ class ModuleDocFragment(object):
         If the CICS startup JCL data set already exists, the option has no effect.
       - If this option is not set, the secondary space is dynamically calculated as 10% of
         the total size of the generated CICS startup JCL.
-      - If the target data set is a member in a PDS/E, then this value will not have any
-        effect.
+      - If the target data set is a member in a PDSE, then this value does not have any effect.
     type: int
     required: false
   space_type:
@@ -46,8 +44,7 @@ class ModuleDocFragment(object):
         cylinders (V(CYL)), or tracks (V(TRK)).
       - If neither O(space_secondary) nor O(space_primary) is set, then this value does
         not have any effect.
-      - If the target data set is a member in a PDS/E, then this value will not have any
-        effect.
+      - If the target data set is a member in a PDSE, then this value does not have any effect.
     required: false
     type: str
     choices:

plugins/modules/stop_region.py

@@ -12,20 +12,21 @@
 module: stop_region
 short_description: Stop a CICS region
 description:
-  - Stop a CICS region by issuing a CEMT PERFORM SHUTDOWN, or cancel the job using ZOAU's job cancelling capability.
-  - The job_id, job_name, or both can be used to shutdown a region. If mulitple jobs are running with the same name, the job_id is required.
-  - You can choose the shutdown mode from NORMAL, IMMEDIATE, or CANCEL.
+  - Stop a CICS region by issuing a CEMT PERFORM SHUTDOWN command, or by canceling the job through the C(jobs.cancel) utility provided by
+    Z Open Automation Utilities (ZOAU). You can choose the shutdown mode from NORMAL, IMMEDIATE, or CANCEL.
+  - The O(job_id), O(job_name), or both can be used to shut down a CICS region. If mulitple jobs are running with the same name, the O(job_id) is required.
   - During a NORMAL or IMMEDIATE shutdown, a shutdown assist transaction should run to enable CICS to shut down in a controlled manner.
     By default, the CICS-supplied shutdown assist transaction, CESD is used. You can specify a custom shutdown assist transaction in the
     SDTRAN system initialization parameter. The task runs until the region has successfully shut down, or until the shutdown fails.
   - You must have a console installed in the CICS region so that the stop_region module can communicate with CICS. To define a console,
     you must install a terminal with the CONSNAME attribute set to your TSO user ID. For detailed instructions, see
-    L(Defining TSO users as console devices,https://www.ibm.com/docs/en/cics-ts/6.1?topic=cics-defining-tso-users-as-console-devices).
+    L(Defining TSO users as console devices,https://www.ibm.com/docs/en/cics-ts/latest?topic=cics-defining-tso-users-as-console-devices).
     Add your console definition into one of the resource lists defined on the GRPLIST system initialization parameter so that it gets
     installed into the CICS region.
     Alternatively, you can use a DFHCSDUP script to update an existing CSD. This function is provided by the csd module.
-  - You may specify a timeout, in seconds, to wait for the region to stop after issuing the command. If this timeout is reached, the module
-    completes in a failed state. Default behaviour does not use a timeout, which is set using a value of -1.
+  - You can specify a timeout, in seconds, for CICS shutdown processing. After a request to stop CICS is issued, if CICS shutdown processing is not
+    completed when this timeout is reached, the module completes in a failed state. By default, the stop_region module does not use a timeout, that is,
+    the O(timeout) parameter assumes a value of -1.
 version_added: 1.1.0-beta.5
 author:
   - Kiera Bennett (@KieraBennett)
@@ -40,12 +41,15 @@
     description:
       - Identifies the job name belonging to the running CICS region.
       - The stop_region module uses this job name to identify the state of the CICS region and shut it down.
-      - The job_name must be unique; if multiple jobs with the same name are running, use job_id.
+      - The O(job_name) must be unique; if multiple jobs with the same name are running, use O(job_id).
     type: str
     required: false
   mode:
     description:
       - Specify the type of shutdown to be executed on the CICS region.
+      - Specify C(normal) to perform a normal shutdown. This instructs the stop_region module to issue a CEMT PERFORM SHUTDOWN command.
+      - Specify C(immediate) to perform an immediate shutdown. This instructs the stop_region module to issue a CEMT PERFORM SHUTDOWN IMMEDIATE command.
+      - Specify C(cancel) to cancel the CICS region. This instructs the stop_region module to use ZOAU's C(jobs.cancel) utility to process the request.
     type: str
     required: false
     default: normal
@@ -67,7 +71,7 @@
     required: false
   timeout:
     description:
-      - Time to wait for region to stop, in seconds.
+      - The maximum time, in seconds, to wait for CICS shutdown processing to complete.
       - Specify -1 to exclude a timeout.
     type: int
     default: -1
@@ -76,26 +80,26 @@
 
 
 EXAMPLES = r'''
-- name: "Stop CICS region"
+- name: "Stop CICS region using job ID"
   ibm.ibm_zos_cics.stop_region:
     job_id: JOB12345
 
-- name: "Stop CICS region immediately"
+- name: "Stop CICS region immediately using job ID"
   ibm.ibm_zos_cics.stop_region:
     job_id: JOB12354
     mode: immediate
 
-- name: "Stop CICS region with name and ID"
+- name: "Stop CICS region using job name and job ID"
   ibm.ibm_zos_cics.stop_region:
     job_id: JOB12354
     job_name: MYREG01
 
-- name: "Stop CICS using job name"
+- name: "Stop CICS region using job name"
   ibm.ibm_zos_cics.stop_region:
     job_name: ANS1234
     mode: normal
 
-- name: "Cancel CICS region"
+- name: "Cancel CICS region using job name"
   ibm.ibm_zos_cics.stop_region:
     job_name: ANS1234
     mode: cancel
@@ -138,7 +142,7 @@
           returned: always
           type: bool
         jobs:
-          description: The output information for a list of jobs matching specified criteria.
+          description: The output information for a list of jobs matching the specified criteria.
           type: list
           returned: on zos_job_query module execution
           elements: dict
@@ -205,11 +209,11 @@
           returned: on zos_operator module execution
           type: int
         max_rc:
-          description: The maximum return code from the tso status command
+          description: The maximum return code from the TSO status command
           returned: on zos_tso_command module execution
           type: int
         output:
-          description: The output from the tso command
+          description: The output from the TSO command.
           returned: on zos_tso_command module execution
           type: list
           elements: dict
@@ -232,7 +236,7 @@
               type: int
 
 msg:
-  description: A string containing an error message if applicable
+  description: A string containing an error message if applicable.
   returned: always
   type: str
 '''