ansible-collections · AndreMarcel99 · Jul 10, 2025 · Aug 14, 2025 · Aug 14, 2025 · Aug 14, 2025
diff --git a/changelogs/fragments/2239_Update_zos_replace_documentation.yml b/changelogs/fragments/2239_Update_zos_replace_documentation.yml
@@ -0,0 +1,3 @@
+trivial:
+  - zos_replace_func.py - Update documentation adding default values and add verbosity for after, before and literal options.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2239).
diff --git a/docs/source/modules/zos_apf.rst b/docs/source/modules/zos_apf.rst
@@ -106,15 +106,15 @@ tmp_hlq
 
 
 persistent
-  Add/remove persistent entries to or from *data_set_name*
+  Add/remove persistent entries to or from *target*
 
   ``library`` will not be persisted or removed if ``persistent=None``
 
   | **required**: False
   | **type**: dict
 
 
-  data_set_name
+  target
     The data set name used for persisting or removing a ``library`` from the APF list.
 
     | **required**: True
@@ -138,7 +138,7 @@ persistent
 
 
   backup
-    Creates a backup file or backup data set for *data_set_name*, including the timestamp information to ensure that you retrieve the original APF list defined in *data_set_name*".
+    Creates a backup file or backup data set for *target*, including the timestamp information to ensure that you retrieve the original APF list defined in *target*".
 
     *backup_name* can be used to specify a backup file name if *backup=true*.
 
@@ -152,7 +152,7 @@ persistent
   backup_name
     Specify the USS file name or data set name for the destination backup.
 
-    If the source *data_set_name* is a USS file or path, the backup_name name must be a file or path name, and the USS file or path must be an absolute path name.
+    If the source *target* is a USS file or path, the backup_name name must be a file or path name, and the USS file or path must be an absolute path name.
 
     If the source is an MVS data set, the backup_name must be an MVS data set name.
 
@@ -241,18 +241,18 @@ Examples
        library: SOME.SEQUENTIAL.DATASET
        force_dynamic: true
        persistent:
-         data_set_name: SOME.PARTITIONED.DATASET(MEM)
+         target: SOME.PARTITIONED.DATASET(MEM)
    - name: Remove a library from the APF list and persistence
      zos_apf:
        state: absent
        library: SOME.SEQUENTIAL.DATASET
        volume: T12345
        persistent:
-         data_set_name: SOME.PARTITIONED.DATASET(MEM)
+         target: SOME.PARTITIONED.DATASET(MEM)
    - name: Batch libraries with custom marker, persistence for the APF list
      zos_apf:
        persistent:
-         data_set_name: "SOME.PARTITIONED.DATASET(MEM)"
+         target: "SOME.PARTITIONED.DATASET(MEM)"
          marker: "/* {mark} PROG001 USR0010 */"
        batch:
          - library: SOME.SEQ.DS1
@@ -304,13 +304,32 @@ stdout
   | **returned**: always
   | **type**: str
 
+stdout_lines
+  List of strings containing individual lines from STDOUT.
+
+  | **returned**: always
+  | **type**: list
+
 stderr
   The error messages from ZOAU command apfadm
 
   | **returned**: always
   | **type**: str
   | **sample**: BGYSC1310E ADD Error: Dataset COMMON.LINKLIB volume COMN01 is already present in APF list.
 
+stderr_lines
+  List of strings containing individual lines from STDERR.
+
+  | **returned**: always
+  | **type**: list
+  | **sample**:
+
+    .. code-block:: json
+
+        [
+            "BGYSC1310E ADD Error: Dataset COMMON.LINKLIB volume COMN01 is already present in APF list."
+        ]
+
 rc
   The return code from ZOAU command apfadm
 

diff --git a/docs/source/modules/zos_backup_restore.rst b/docs/source/modules/zos_backup_restore.rst
@@ -194,6 +194,7 @@ space_type
 
   | **required**: False
   | **type**: str
+  | **default**: m
   | **choices**: k, m, g, cyl, trk
 
 

diff --git a/docs/source/modules/zos_blockinfile.rst b/docs/source/modules/zos_blockinfile.rst
@@ -397,6 +397,18 @@ stderr
   | **type**: str
   | **sample**: BGYSC1311E Iconv error, cannot open converter from ISO-88955-1 to IBM-1047
 
+stdout_lines
+  List of strings containing individual lines from stdout.
+
+  | **returned**: failure
+  | **type**: list
+
+stderr_lines
+  List of strings containing individual lines from stderr.
+
+  | **returned**: failure
+  | **type**: list
+
 rc
   The return code from ZOAU dmod when json.loads() fails to parse the result from dmod
 

diff --git a/docs/source/modules/zos_copy.rst b/docs/source/modules/zos_copy.rst
@@ -37,7 +37,7 @@ asa_text
 
   If neither ``src`` or ``dest`` have record format Fixed Block with ANSI format (FBA) or Variable Block with ANSI format (VBA), the module will fail.
 
-  This option is only valid for text files. If ``is_binary`` is ``true`` or ``executable`` is ``true`` as well, the module will fail.
+  This option is only valid for text files. If ``is_binary`` is ``true`` or ``is_executable`` is ``true`` as well, the module will fail.
 
   | **required**: False
   | **type**: bool
@@ -109,7 +109,7 @@ dest
 
   If ``dest`` is a nonexistent data set, it will be created following the process outlined here and in the ``volume`` option.
 
-  If ``dest`` is a nonexistent data set, the attributes assigned will depend on the type of ``src``. If ``src`` is a USS file, ``dest`` will have a Fixed Block (FB) record format and the remaining attributes will be computed. If *is_binary=true*, ``dest`` will have a Fixed Block (FB) record format with a record length of 80, block size of 32720, and the remaining attributes will be computed. If *executable=true*,``dest`` will have an Undefined (U) record format with a record length of 0, block size of 32760, and the remaining attributes will be computed.
+  If ``dest`` is a nonexistent data set, the attributes assigned will depend on the type of ``src``. If ``src`` is a USS file, ``dest`` will have a Fixed Block (FB) record format and the remaining attributes will be computed. If *is_binary=true*, ``dest`` will have a Fixed Block (FB) record format with a record length of 80, block size of 32720, and the remaining attributes will be computed. If *is_executable=true*,``dest`` will have an Undefined (U) record format with a record length of 0, block size of 32760, and the remaining attributes will be computed.
 
   If ``src`` is a file and ``dest`` a partitioned data set, ``dest`` does not need to include a member in its value, the module can automatically compute the resulting member name from ``src``.
 
@@ -166,7 +166,7 @@ tmp_hlq
   | **type**: str
 
 
-force
+replace
   If set to ``true`` and the remote file or data set ``dest`` is empty, the ``dest`` will be reused.
 
   If set to ``true`` and the remote file or data set ``dest`` is NOT empty, the ``dest`` will be deleted and recreated with the ``src`` data set attributes, otherwise it will be recreated with the ``dest`` data set attributes.
@@ -182,12 +182,12 @@ force
   | **default**: False
 
 
-force_lock
-  By default, when ``dest`` is a MVS data set and is being used by another process with DISP=SHR or DISP=OLD the module will fail. Use ``force_lock`` to bypass DISP=SHR and continue with the copy operation.
+force
+  By default, when ``dest`` is a MVS data set and is being used by another process with DISP=SHR or DISP=OLD the module will fail. Use ``force`` to bypass DISP=SHR and continue with the copy operation.
 
   If set to ``true`` and destination is a MVS data set opened by another process then zos_copy will try to copy using DISP=SHR.
 
-  Using ``force_lock`` uses operations that are subject to race conditions and can lead to data loss, use with caution.
+  Using ``force`` uses operations that are subject to race conditions and can lead to data loss, use with caution.
 
   If a data set member has aliases, and is not a program object, copying that member to a dataset that is in use will result in the aliases not being preserved in the target dataset. When this scenario occurs the module will fail.
 
@@ -218,10 +218,10 @@ is_binary
   | **default**: False
 
 
-executable
+is_executable
   If set to ``true``, indicates that the file or library to be copied is an executable.
 
-  If *executable=true*, and ``dest`` is a data set, it must be a PDS or PDSE (library).
+  If *is_executable=true*, and ``dest`` is a data set, it must be a PDS or PDSE (library).
 
   If ``dest`` is a nonexistent data set, the library attributes assigned will be Undefined (U) record format with a record length of 0, block size of 32760 and the remaining attributes will be computed.
 
@@ -237,7 +237,7 @@ executable
 aliases
   If set to ``true``, indicates that any aliases found in the source (USS file, USS dir, PDS/E library or member) are to be preserved during the copy operation.
 
-  Aliases are implicitly preserved when libraries are copied over to USS destinations. That is, when ``executable=True`` and ``dest`` is a USS file or directory, this option will be ignored.
+  Aliases are implicitly preserved when libraries are copied over to USS destinations. That is, when ``is_executable=True`` and ``dest`` is a USS file or directory, this option will be ignored.
 
   Copying of aliases for text-based data sets from USS sources or to USS destinations is not currently supported.
 
@@ -820,14 +820,14 @@ Examples
        src: HLQ.SAMPLE.PDSE
        dest: HLQ.EXISTING.PDSE
        remote_src: true
-       force: true
+       replace: true
 
    - name: Copy PDS member to a new PDS member. Replace if it already exists
      zos_copy:
        src: HLQ.SAMPLE.PDSE(SRCMEM)
        dest: HLQ.NEW.PDSE(DESTMEM)
        remote_src: true
-       force: true
+       replace: true
 
    - name: Copy a USS file to a PDSE member. If PDSE does not exist, allocate it
      zos_copy:
@@ -891,15 +891,15 @@ Examples
        src: HLQ.COBOLSRC.PDSE(TESTPGM)
        dest: HLQ.NEW.PDSE(MYCOBOL)
        remote_src: true
-       executable: true
+       is_executable: true
        aliases: true
 
    - name: Copy a Load Library from a USS directory /home/loadlib to a new PDSE
      zos_copy:
        src: '/home/loadlib/'
        dest: HLQ.LOADLIB.NEW
        remote_src: true
-       executable: true
+       is_executable: true
        aliases: true
 
    - name: Copy a file with ASA characters to a new sequential data set.
@@ -940,7 +940,7 @@ Notes
 
    This module uses SFTP (Secure File Transfer Protocol) for the underlying transfer protocol; SCP (secure copy protocol) and Co:Z SFTP are not supported. In the case of Co:z SFTP, you can exempt the Ansible user id on z/OS from using Co:Z thus falling back to using standard SFTP. If the module detects SCP, it will temporarily use SFTP for transfers, if not available, the module will fail.
 
-   Beginning in version 1.8.x, zos_copy will no longer attempt to correct a copy of a data type member into a PDSE that contains program objects. You can control this behavior using module option ``executable`` that will signify an executable is being copied into a PDSE with other executables. Mixing data type members with program objects will result in a (FSUM8976,./zos_copy.html) error.
+   Beginning in version 1.8.x, zos_copy will no longer attempt to correct a copy of a data type member into a PDSE that contains program objects. You can control this behavior using module option ``is_executable`` that will signify an executable is being copied into a PDSE with other executables. Mixing data type members with program objects will result in a (FSUM8976,./zos_copy.html) error.
 
    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.
 
@@ -1118,7 +1118,7 @@ state
 note
   A note to the user after module terminates.
 
-  | **returned**: When ``force=true`` and ``dest`` exists
+  | **returned**: When ``replace=true`` and ``dest`` exists
   | **type**: str
   | **sample**: No data was copied
 

diff --git a/docs/source/modules/zos_data_set.rst b/docs/source/modules/zos_data_set.rst
@@ -311,6 +311,18 @@ scratch
   | **default**: False
 
 
+noscratch
+  When ``state=absent``, specifies whether to keep the data set's entry in the VTOC.
+
+  If ``noscratch=True``, the data set is uncataloged but not physically removed from the volume. The Data Set Control Block is not removed from the VTOC.
+
+  This is the equivalent of using ``NOSCRATCH`` in an ``IDCAMS DELETE`` command.
+
+  | **required**: False
+  | **type**: bool
+  | **default**: False
+
+
 volumes
   If cataloging a data set, *volumes* specifies the name of the volume(s) where the data set is located.
 
@@ -598,6 +610,18 @@ batch
     | **default**: False
 
 
+  noscratch
+    When ``state=absent``, specifies whether to keep the data set's entry in the VTOC.
+
+    If ``noscratch=True``, the data set is uncataloged but not physically removed from the volume. The Data Set Control Block is not removed from the VTOC.
+
+    This is the equivalent of using ``NOSCRATCH`` in an ``IDCAMS DELETE`` command.
+
+    | **required**: False
+    | **type**: bool
+    | **default**: False
+
+
   extended
     Sets the *extended* attribute for Generation Data Groups.
 
@@ -783,6 +807,12 @@ Examples
        name: someds.name.here
        state: absent
 
+   - name: Uncatalog a data set but do not remove it from the volume.
+     zos_data_set:
+       name: someds.name.here
+       state: absent
+       noscratch: true
+
    - name: Delete a data set if it exists. If data set not cataloged, check on volume 222222 for the data set, and then catalog and delete if found.
      zos_data_set:
        name: someds.name.here

diff --git a/docs/source/modules/zos_encode.rst b/docs/source/modules/zos_encode.rst
@@ -333,3 +333,24 @@ backup_name
   | **type**: str
   | **sample**: /path/file_name.2020-04-23-08-32-29-bak.tar
 
+encoding
+  Specifies which encodings the destination file or data set was converted from and to.
+
+  | **returned**: always
+  | **type**: dict
+
+  from
+    The character set of the source *src*.
+
+    | **returned**: always
+    | **type**: str
+    | **sample**: IBM-1047
+
+  to
+    The destination *dest* character set for the output that was written as.
+
+    | **returned**: always
+    | **type**: str
+    | **sample**: ISO8859-1
+
+
diff --git a/docs/source/modules/zos_fetch.rst b/docs/source/modules/zos_fetch.rst
@@ -257,9 +257,11 @@ Return Values
 -------------
 
 
-file
+src
   The source file path or data set on the remote machine.
 
+  If the source is not found, then src will be empty.
+
   | **returned**: success
   | **type**: str
   | **sample**: SOME.DATA.SET
@@ -296,17 +298,10 @@ data_set_type
   | **type**: str
   | **sample**: PDSE
 
-note
-  Notice of module failure when ``fail_on_missing`` is false.
-
-  | **returned**: failure and fail_on_missing=false
-  | **type**: str
-  | **sample**: The data set USER.PROCLIB does not exist. No data was fetched.
-
 msg
-  Message returned on failure.
+  Any important messages from the module.
 
-  | **returned**: failure
+  | **returned**: always
   | **type**: str
   | **sample**: The source 'TEST.DATA.SET' does not exist or is uncataloged.