Automated commit to update documentation

Author: ddimatos

_sources/ibm_zos_core/docs/source/filters.rst.txt

@@ -5,13 +5,9 @@
 Filters
 =======
 
-Filters in Ansible are from Jinja2, and are used to transform data inside
-a template expression. The templates operate on the Ansible controller, and not
-on the target host. Therefore, filters execute on the controller as they augment
-the data locally.
-
-Jinja2 ships with many filters as does Ansible, and also allows users to add
-their own custom filters.
+Filters are used to transform data inside a template expression. The templates
+operate on the Ansible controller, not on the managed node. Therefore,
+filters execute on the controller as they augment the data locally.
 
 The **IBM z/OS core collection** includes filters and their usage in sample
 playbooks. Unlike collections that can be identified at the top level using the

_sources/ibm_zos_core/docs/source/modules/zos_archive.rst.txt

@@ -342,15 +342,15 @@ Examples
    # Simple archive
    - name: Archive file into a tar
      zos_archive:
-       path: /tmp/archive/foo.txt
+       src: /tmp/archive/foo.txt
        dest: /tmp/archive/foo_archive_test.tar
        format:
          name: tar
 
    # Archive multiple files
    - name: Compress list of files into a zip
      zos_archive:
-       path:
+       src:
          - /tmp/archive/foo.txt
          - /tmp/archive/bar.txt
        dest: /tmp/archive/foo_bar_archive_test.zip
@@ -360,15 +360,15 @@ Examples
    # Archive one data set into terse
    - name: Compress data set into a terse
      zos_archive:
-       path: "USER.ARCHIVE.TEST"
+       src: "USER.ARCHIVE.TEST"
        dest: "USER.ARCHIVE.RESULT.TRS"
        format:
          name: terse
 
    # Use terse with different options
    - name: Compress data set into a terse, specify pack algorithm and use adrdssu
      zos_archive:
-       path: "USER.ARCHIVE.TEST"
+       src: "USER.ARCHIVE.TEST"
        dest: "USER.ARCHIVE.RESULT.TRS"
        format:
          name: terse
@@ -379,7 +379,7 @@ Examples
    # Use a pattern to store
    - name: Compress data set pattern using xmit
      zos_archive:
-       path: "USER.ARCHIVE.*"
+       src: "USER.ARCHIVE.*"
        exclude_sources: "USER.ARCHIVE.EXCLUDE.*"
        dest: "USER.ARCHIVE.RESULT.XMIT"
        format:

_sources/ibm_zos_core/docs/source/modules/zos_copy.rst.txt

@@ -91,6 +91,8 @@ dest
 
   If ``dest`` is a nonexistent USS file, it will be created.
 
+  If ``dest`` is a new USS file or replacement, the file will be appropriately tagged with either the system's default locale or the encoding option defined. If the USS file is a replacement, the user must have write authority to the file either through ownership, group or other permissions, else the copy will fail.
+
   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 32760, 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.
@@ -787,9 +789,9 @@ Notes
 
    For supported character sets used to encode data, refer to the `documentation <https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/resources/character_set.html>`_.
 
-   `zos_copy <./zos_copy.html>`_ uses SFTP (Secure File Transfer Protocol) for the underlying transfer protocol; Co:Z SFTP is not supported. In the case of Co:z SFTP, you can exempt the Ansible userid on z/OS from using Co:Z thus falling back to using standard SFTP.
+   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 autocorrect 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 be responded with 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 ``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.
 
 
 

_sources/ibm_zos_core/docs/source/modules/zos_fetch.rst.txt

@@ -204,7 +204,7 @@ Notes
 
    For supported character sets used to encode data, refer to the `documentation <https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/resources/character_set.html>`_.
 
-   `zos_fetch <./zos_fetch.html>`_ uses SFTP (Secure File Transfer Protocol) for the underlying transfer protocol; Co:Z SFTP is not supported. In the case of Co:z SFTP, you can exempt the Ansible userid on z/OS from using Co:Z thus falling back to using standard SFTP.
+   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.
 
 
 

_sources/ibm_zos_core/docs/source/modules/zos_job_submit.rst.txt

@@ -16,9 +16,8 @@ zos_job_submit -- Submit JCL
 
 Synopsis
 --------
-- Submit JCL from a data set, USS, or from the controller.
-- Submit a job and optionally monitor for completion.
-- Optionally, wait a designated time until the job finishes.
+- Submit JCL in a data set, USS file, or file on the controller.
+- Submit a job and monitor for completion.
 - For an uncataloged dataset, specify the volume serial number.
 
 
@@ -58,9 +57,9 @@ location
 
 
 wait
-  Setting this option will yield no change, it is deprecated. There is no no need to set *wait*; setting *wait_times_s* is the correct way to configure the amount of tme to wait for a job to execute.
+  Setting this option will yield no change, it is disabled. There is no need to set *wait*; setting *wait_times_s* is the correct way to configure the amount of time to wait for a job to execute.
 
-  Configuring wait used by the `zos_job_submit <./zos_job_submit.html>`_ module has been deprecated and will be removed in ibm.ibm_zos_core collection.
+  This option will be removed in ibm.ibm_zos_core collection version 1.10.0
 
   See option *wait_time_s*.
 
@@ -333,6 +332,8 @@ Notes
 .. note::
    For supported character sets used to encode data, refer to the `documentation <https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/resources/character_set.html>`_.
 
+   This module uses `zos_copy <./zos_copy.html>`_ to copy local scripts to the remote machine which 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.
+
 
 
 
@@ -689,24 +690,46 @@ jobs
           }
 
     msg
-      Return code resulting from the job submission. Jobs that take longer to assign a value can have a value of '?'.
+      Job status resulting from the job submission.
+
+      Job status `ABEND` indicates the job ended abnormally.
+
+      Job status `AC` indicates the job is active, often a started task or job taking long.
+
+      Job status `CAB` indicates a converter abend.
+
+      Job status `CANCELED` indicates the job was canceled.
+
+      Job status `CNV` indicates a converter error.
+
+      Job status `FLU` indicates the job was flushed.
+
+      Job status `JCLERR` or `JCL ERROR` indicates the JCL has an error.
+
+      Job status `SEC` or `SEC ERROR` indicates the job as encountered a security error.
+
+      Job status `SYS` indicates a system failure.
+
+      Job status `?` indicates status can not be determined.
 
       | **type**: str
-      | **sample**: CC 0000
+      | **sample**: AC
 
     msg_code
-      Return code extracted from the `msg` so that it can be evaluated as a string. Jobs that take longer to assign a value can have a value of '?'.
+      The return code from the submitted job as a string.
 
       | **type**: str
 
     msg_txt
-      Returns additional information related to the job. Jobs that take longer to assign a value can have a value of '?'.
+      Returns additional information related to the submitted job.
 
       | **type**: str
-      | **sample**: The job completion code (CC) was not available in the job output, please review the job log."
+      | **sample**: The job JOB00551 was run with special job processing TYPRUN=SCAN. This will result in no completion, return code or job steps and changed will be false.
 
     code
-      Return code converted to an integer value (when possible). For JCL ERRORs, this will be None.
+      The return code converted to an integer value when available.
+
+      Jobs which have no return code will return NULL, such is the case of a job that errors or is active.
 
       | **type**: int
 

_sources/ibm_zos_core/docs/source/modules/zos_ping.rst.txt

@@ -40,10 +40,22 @@ Examples
 
 
 
+Notes
+-----
 
+.. note::
+   This module is written in REXX and relies on the SCP protocol to transfer the source to the managed z/OS node and encode it in the managed nodes default encoding, eg IBM-1047. Starting with OpenSSH 9.0, it switches from SCP to use SFTP by default, meaning transfers are no longer treated as text and are transferred as binary preserving the source files encoding resulting in a module failure. If you are using OpenSSH 9.0 (ssh -V) or later, you can instruct SSH to use SCP by adding the entry ``scp_extra_args="-O"`` into the ini file named ``ansible.cfg``.
 
 
 
+See Also
+--------
+
+.. seealso::
+
+   - :ref:`ansible.builtin.ssh_module`
+
+
 
 
 Return Values

_sources/ibm_zos_core/docs/source/modules/zos_script.rst.txt

@@ -296,9 +296,7 @@ Notes
 
    For supported character sets used to encode data, refer to the `documentation <https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/resources/character_set.html>`_.
 
-   This module uses `zos_copy <./zos_copy.html>`_ to copy local scripts to the remote machine.
-
-   `zos_copy <./zos_copy.html>`_ uses SFTP (Secure File Transfer Protocol) for the underlying transfer protocol; Co:Z SFTP is not supported. In the case of Co:z SFTP, you can exempt the Ansible userid on z/OS from using Co:Z thus falling back to using standard SFTP.
+   This module uses `zos_copy <./zos_copy.html>`_ to copy local scripts to the remote machine which 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.
 
    This module executes scripts inside z/OS UNIX System Services. For running REXX scripts contained in data sets or CLISTs, consider issuing a TSO command with `zos_tso_command <./zos_tso_command.html>`_.
 

_sources/ibm_zos_core/docs/source/modules/zos_tso_command.rst.txt

@@ -55,27 +55,34 @@ Examples
 .. code-block:: yaml+jinja
 
 
-   - name: Execute TSO commands to allocate a new dataset
+   - name: Execute TSO commands to allocate a new dataset.
      zos_tso_command:
-         commands:
-             - alloc da('TEST.HILL3.TEST') like('TEST.HILL3')
-             - delete 'TEST.HILL3.TEST'
+       commands:
+         - alloc da('TEST.HILL3.TEST') like('TEST.HILL3')
+         - delete 'TEST.HILL3.TEST'
 
-   - name: Execute TSO command list user TESTUSER to obtain TSO information
+   - name: Execute TSO command List User (LU) for TESTUSER to obtain TSO information.
      zos_tso_command:
-         commands:
-              - LU TESTUSER
+       commands:
+         - LU TESTUSER
 
-   - name: Execute TSO command to list dataset data (allow 4 for no dataset listed or cert found)
+   - name: Execute TSO command List Dataset (LISTDSD) and allow for maximum return code of 4.
      zos_tso_command:
-         commands:
-              - LISTDSD DATASET('HLQ.DATA.SET') ALL GENERIC
-         max_rc: 4
+       commands:
+         - LISTDSD DATASET('HLQ.DATA.SET') ALL GENERIC
+       max_rc: 4
 
    - name: Execute TSO command to run a REXX script explicitly from a data set.
      zos_tso_command:
-         commands:
-              - EXEC HLQ.DATASET.REXX exec
+       commands:
+         - EXEC HLQ.DATASET.REXX exec
+
+   - name: Chain multiple TSO commands into one invocation using semicolons.
+     zos_tso_command:
+       commands: >-
+         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;
 
 
 

_sources/ibm_zos_core/docs/source/modules/zos_unarchive.rst.txt

@@ -362,14 +362,14 @@ Examples
    # Simple extract
    - name: Copy local tar file and unpack it on the managed z/OS node.
      zos_unarchive:
-       path: "./files/archive_folder_test.tar"
+       src: "./files/archive_folder_test.tar"
        format:
          name: tar
 
    # use include
    - name: Unarchive a bzip file selecting only a file to unpack.
      zos_unarchive:
-       path: "/tmp/test.bz2"
+       src: "/tmp/test.bz2"
        format:
          name: bz2
        include:
@@ -378,7 +378,7 @@ Examples
    # Use exclude
    - name: Unarchive a terse data set and excluding data sets from unpacking.
      zos_unarchive:
-       path: "USER.ARCHIVE.RESULT.TRS"
+       src: "USER.ARCHIVE.RESULT.TRS"
        format:
          name: terse
        exclude:
@@ -388,7 +388,7 @@ Examples
    # List option
    - name: List content from XMIT
      zos_unarchive:
-       path: "USER.ARCHIVE.RESULT.XMIT"
+       src: "USER.ARCHIVE.RESULT.XMIT"
        format:
          name: xmit
          format_options:
@@ -404,14 +404,16 @@ Notes
 .. note::
    VSAMs are not supported.
 
+   This module uses `zos_copy <./zos_copy.html>`_ to copy local scripts to the remote machine which 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.
+
 
 
 See Also
 --------
 
 .. seealso::
 
-   - :ref:`zos_unarchive_module`
+   - :ref:`zos_archive_module`
 
 
 
@@ -420,14 +422,14 @@ Return Values
 -------------
 
 
-path
-  File path or data set name unarchived.
+src
+  File path or data set name unpacked.
 
   | **returned**: always
   | **type**: str
 
 dest_path
-  Destination path where archive was extracted.
+  Destination path where archive was unpacked.
 
   | **returned**: always
   | **type**: str

_sources/ibm_zos_core/docs/source/plugins.rst.txt

@@ -5,30 +5,33 @@
 Plugins
 =======
 
-Plugins that come with the **IBM z/OS core collection** augment Ansible's core
+Plugins that come with the **IBM z/OS core collection** complement Ansible's core
 functionality. Ansible uses a plugin architecture to enable a rich, flexible
 and expandable feature set.
 
 Action
 ------
 
-* ``zos_ping``: Manages the REXX source transferred to the z/OS managed node for
-  `zos_ping`_.
-* ``zos_copy``: Used to `copy data`_ from the controller to the z/OS managed
-  node.
-* ``zos_fetch``: Used to `fetch data`_ from the z/OS managed node to the
-  controller.
-* ``zos_job_submit``: Used to `submit a job`_ from the controller and optionally
-  monitor the job completion.
+Action plugins integrate local processing and local data with module functionality.
+Action plugins are executed by default when an associated module is used; no additional
+user action is required, this documentation is reference only.
 
-.. _normal:
-   https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/action/normal.py
-.. _zos_ping:
-   modules/zos_ping.html
-.. _copy data:
+* `zos_copy`_: Used to copy data from the controller to the z/OS manage node.
+* `zos_fetch`_: Used to fetch data from the z/OS managed node to the controller.
+* `zos_job_submit`_: Used to submit a job from the controller to the z/OS manage node.
+* `zos_ping`: Used to transfer the modules REXX source to the z/OS managed node.
+* `zos_script`: Used to transfer scripts from the controller to the z/OS manage node.
+* `_zos_unarchive`: Used to transfer archives from the controller to the z/OS manage node.
+
+.. _zos_copy:
    modules/zos_copy.html
-.. _fetch data:
+.. _zos_fetch:
    modules/zos_fetch.html
-.. _submit a job:
+.. _zos_job_submit:
    modules/zos_job_submit.html
-
+.. _zos_ping:
+   modules/zos_ping.html
+.. _zos_script:
+   modules/zos_script.html
+.. _zos_unarchive:
+   modules/zos_unarchive.html