[Documentation] [zos_copy] [zos_mvs_raw] [zos_tso_cmd] Tell users how to recall migrated data sets (#2098)

* Update docs

* Add changelog fragment

* Fix changelog fragment

* Update changelogs/fragments/2098-docs-migrated-data-sets-examples.yml

Co-authored-by: Fernando Flores <[email protected]>

---------

Co-authored-by: Fernando Flores <[email protected]>

Author: rexemin

changelogs/fragments/2098-docs-migrated-data-sets-examples.yml

@@ -0,0 +1,9 @@
+trivial:
+  - zos_copy - Added a note to the documentation redirecting users to other
+    modules to see how to recall migrated data sets before trying to copy
+    them.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2098)
+  - zos_mvs_raw - Added an example for how to recall a migrated data set.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2098)
+  - zos_tso_cmd - Added an example for how to recall a migrated data set.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2098)

docs/source/modules/zos_copy.rst

@@ -930,7 +930,7 @@ Notes
 
    It is the playbook author or user's responsibility to ensure they have appropriate authority to the RACF FACILITY resource class. A user is described as the remote user, configured either for the playbook or playbook tasks, who can also obtain escalated privileges to execute as root or another user.
 
-   To use this module, you must define the RACF FACILITY class profile and allow READ access to RACF FACILITY profile MVS.MCSOPER.ZOAU. If your system uses a different security product, consult that product's documentation to configure the required security classes.
+   If trying to copy a migrated data set, first recall it before executing this module. This module does not perform recalls automatically. See modules `zos_mvs_raw <./zos_mvs_raw.html>`_ and `zos_tso_cmd <./zos_tso_cmd.html>`_ for examples of how to recall migrated data sets using this collection.
 
 
 
@@ -941,6 +941,8 @@ See Also
 
    - :ref:`zos_fetch_module`
    - :ref:`zos_data_set_module`
+   - :ref:`zos_mvs_raw_module`
+   - :ref:`zos_tso_cmd_module`
 
 
 

docs/source/modules/zos_mvs_raw.rst

@@ -1809,6 +1809,20 @@ Examples
              dd_name: sysin
              content: " LISTCAT ENTRIES('SOME.DATASET.*')"
 
+   - name: Recall a migrated data set.
+     zos_mvs_raw:
+       program_name: ikjeft01
+       auth: true
+       dds:
+         - dd_output:
+             dd_name: systsprt
+             return_content:
+               type: text
+         - dd_input:
+             dd_name: systsin
+             content:
+               - "HRECALL 'MY.DATASET' WAIT"
+
 
 
 

docs/source/modules/zos_tso_command.rst

@@ -98,6 +98,11 @@ Examples
          ALLOCATE DDNAME(OUT1) DSNAME('HLQ.PDSE.DATA.DEST(OUTPUT)') SHR;
          OCOPY INDD(IN1) OUTDD(OUT1) BINARY;
 
+   - name: Recall a migrated data set.
+     zos_tso_command:
+       commands:
+         - HRECALL 'MY.DATASET' WAIT
+
 
 
 

plugins/modules/zos_copy.py

@@ -563,9 +563,15 @@
       described as the remote user, configured either for the playbook or
       playbook tasks, who can also obtain escalated privileges to execute as
       root or another user.
+    - If trying to copy a migrated data set, first recall it before executing this module.
+      This module does not perform recalls automatically. See modules L(zos_mvs_raw,./zos_mvs_raw.html)
+      and L(zos_tso_cmd,./zos_tso_cmd.html) for examples of how to recall migrated data sets
+      using this collection.
 seealso:
 - module: zos_fetch
 - module: zos_data_set
+- module: zos_mvs_raw
+- module: zos_tso_cmd
 """
 
 EXAMPLES = r"""

plugins/modules/zos_mvs_raw.py

@@ -1637,6 +1637,20 @@
       - dd_input:
           dd_name: sysin
           content: " LISTCAT ENTRIES('SOME.DATASET.*')"
+
+- name: Recall a migrated data set.
+  zos_mvs_raw:
+    program_name: ikjeft01
+    auth: true
+    dds:
+      - dd_output:
+          dd_name: systsprt
+          return_content:
+            type: text
+      - dd_input:
+          dd_name: systsin
+          content:
+            - "HRECALL 'MY.DATASET' WAIT"
 """
 
 from ansible_collections.ibm.ibm_zos_core.plugins.module_utils.better_arg_parser import (

plugins/modules/zos_tso_command.py

@@ -134,6 +134,11 @@
       ALLOCATE DDNAME(IN1) DSNAME('HLQ.PDSE.DATA.SRC(INPUT)') SHR;
       ALLOCATE DDNAME(OUT1) DSNAME('HLQ.PDSE.DATA.DEST(OUTPUT)') SHR;
       OCOPY INDD(IN1) OUTDD(OUT1) BINARY;
+
+- name: Recall a migrated data set.
+  zos_tso_command:
+    commands:
+      - HRECALL 'MY.DATASET' WAIT
 """
 
 from ansible.module_utils.basic import AnsibleModule