Automated commit to update documentation

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

@@ -815,6 +815,10 @@ Notes
 
    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 \ :literal:`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.
+
+   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.
+
 
 
 See Also

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

@@ -54,27 +54,31 @@ encoding
 
 
 src
-  The location can be a UNIX System Services (USS) file or path, PS (sequential data set), PDS, PDSE, member of a PDS or PDSE, or KSDS (VSAM data set).
+  The location can be a UNIX System Services (USS) file or path, PS (sequential data set), PDS, PDSE, member of a PDS or PDSE, a generation data set (GDS) or KSDS (VSAM data set).
 
   The USS path or file must be an absolute pathname.
 
   If \ :emphasis:`src`\  is a USS directory, all files will be encoded.
 
+  Encoding a whole generation data group (GDG) is not supported.
+
   | **required**: True
   | **type**: str
 
 
 dest
   The location where the converted characters are output.
 
-  The destination \ :emphasis:`dest`\  can be a UNIX System Services (USS) file or path, PS (sequential data set), PDS, PDSE, member of a PDS or PDSE, or KSDS (VSAM data set).
+  The destination \ :emphasis:`dest`\  can be a UNIX System Services (USS) file or path, PS (sequential data set), PDS, PDSE, member of a PDS or PDSE, a generation data set (GDS) or KSDS (VSAM data set).
 
   If the length of the PDSE member name used in \ :emphasis:`dest`\  is greater than 8 characters, the member name will be truncated when written out.
 
   If \ :emphasis:`dest`\  is not specified, the \ :emphasis:`src`\  will be used as the destination and will overwrite the \ :emphasis:`src`\  with the character set in the option \ :emphasis:`to\_encoding`\ .
 
   The USS file or path must be an absolute pathname.
 
+  If \ :emphasis:`dest`\  is a data set, it must be already allocated.
+
   | **required**: False
   | **type**: str
 
@@ -100,6 +104,8 @@ backup_name
 
   \ :literal:`backup\_name`\  will be returned on either success or failure of module execution such that data can be retrieved.
 
+  If \ :emphasis:`backup\_name`\  is a generation data set (GDS), it must be a relative positive name (for example, \ :literal:`HLQ.USER.GDG(+1)`\ ).
+
   | **required**: False
   | **type**: str
 
@@ -253,6 +259,24 @@ Examples
          from: ISO8859-1
          to: IBM-1047
 
+   - name: Convert file encoding from a USS file to a generation data set
+     zos_encode:
+       src: /zos_encode/test.data
+       dest: USER.TEST.GDG(0)
+       encoding:
+         from: ISO8859-1
+         to: IBM-1047
+
+   - name: Convert file encoding from a USS file to a data set while using a GDG for backup
+     zos_encode:
+       src: /zos_encode/test.data
+       dest: USER.TEST.PS
+       encoding:
+         from: ISO8859-1
+         to: IBM-1047
+       backup: true
+       backup_name: USER.BACKUP.GDG(+1)
+
 
 
 

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

@@ -35,7 +35,7 @@ cmd
 
   If the command contains any special characters ($, &, etc), they must be escaped using double backslashes like \\\\\\$.
 
-  For example, to display job by job name the command would be \ :literal:`cmd:"\\\\$dj''HELLO''"`\ 
+  For example, to display job by job name the command would be ``cmd:"\\$dj''HELLO''"``
 
   | **required**: True
   | **type**: str

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

@@ -275,6 +275,12 @@ Examples
        cmd: ./scripts/PROGRAM
        removes: /u/user/pgm_input.txt
 
+   - name: Run a shell script on the remote system
+     zos_script:
+       cmd: ./scripts/program.sh
+       executable: /bin/sh
+       remote_src: true
+
 
 
 

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

@@ -6,8 +6,8 @@
 Releases
 ========
 
-Version 1.10.0-beta.1
-=====================
+Version 1.10.0
+==============
 
 Major Changes
 -------------
@@ -95,6 +95,7 @@ It is intended to assist in updating your playbooks so this collection will cont
 Availability
 ------------
 
+* `Automation Hub`_
 * `Galaxy`_
 * `GitHub`_
 
@@ -106,19 +107,24 @@ controller and z/OS managed node dependencies.
 
 Known Issues
 ------------
-
+- ``zos_job_submit`` - when setting 'location' to 'local' and not specifying the from and to encoding, the modules defaults are not read leaving the file in its original encoding; explicitly set the encodings instead of relying on the default.
 - ``zos_job_submit`` - when submitting JCL, the response value returned for **byte_count** is incorrect.
+- ``zos_data_set`` - When data set creation fails, exception can throw a bad import error instead of data set creation error.
+- ``zos_copy`` - 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.
+- ``zos_job_submit``, ``zos_job_output``, ``zos_operator_action_query`` - encounters JSON decoding (DecodeError, TypeError, KeyError) errors when interacting with results that contain non-printable UTF-8 characters in the response. This will be addressed in **ZOAU version 1.3.2** and later.
 
-- ``zos_job_submit``, ``zos_job_output``, ``zos_operator_action_query`` - encounters UTF-8 decoding errors when interacting with results that contain non-printable UTF-8 characters in the response.
-
-   - If you encounter this, some options are to:
+   - Some options to work around this known issue are:
 
       - Specify that the ASA assembler option be enabled to instruct the assembler to use ANSI control characters instead of machine code control characters.
       - Ignore module errors by using  **ignore_errors:true** for a specific playbook task.
       - If the error is resulting from a batch job, add **ignore_errors:true** to the task and capture the output into a registered variable to extract the
         job ID with a regular expression. Then use ``zos_job_output`` to display the DD without the non-printable character such as the DD **JESMSGLG**.
       - If the error is the result of a batch job, set option **return_output** to false so that no DDs are read which could contain the non-printable UTF-8 characters.
 
+- In the past, choices could be defined in either lower or upper case. Now, only the case that is identified in the docs can be set, this is so that the collection can continue to maintain certified status.
+- Use of special characters (#, @, $, \- ) in different options like data set names and commands is not fully supported, some modules support them but is the user responsibility to escape them. Read each module documentation for further details.
+
+
 Version 1.9.1
 =============
 
@@ -144,7 +150,7 @@ controller and z/OS managed node dependencies.
 Known Issues
 ------------
 
-- ``zos_job_submit`` - when setting 'location' to 'LOCAL' and not specifying the from and to encoding, the modules defaults are not read leaving the file in its original encoding; explicitly set the encodings instead of relying on the default.
+- ``zos_job_submit`` - when setting 'location' to 'local' and not specifying the from and to encoding, the modules defaults are not read leaving the file in its original encoding; explicitly set the encodings instead of relying on the default.
 - ``zos_job_submit`` - when submitting JCL, the response value returned for **byte_count** is incorrect.
 
 - ``zos_job_submit``, ``zos_job_output``, ``zos_operator_action_query`` - encounters UTF-8 decoding errors when interacting with results that contain non-printable UTF-8 characters in the response. This has been addressed in this release and corrected with **ZOAU version 1.2.5.6** or later.
@@ -270,9 +276,6 @@ Several modules have reported UTF-8 decoding errors when interacting with result
 An undocumented option **size** was defined in module **zos_data_set**, this has been removed to satisfy collection certification, use the intended
 and documented **space_primary** option.
 
-In the past, choices could be defined in either lower or upper case. Now, only the case that is identified in the docs can be set,
-this is so that the collection can continue to maintain certified status.
-
 Availability
 ------------
 

_sources/ibm_zos_core/docs/source/resources/releases_maintenance.rst.txt

@@ -6,39 +6,90 @@
 Releases and maintenance
 ========================
 
-This table describes the collections release dates, dependency versions and End of Life dates (EOL).
+This section describes the collections release dates, dependency versions and End of Life dates (EOL)
+and support coverage.
 
 The ``ibm_zos_core`` collection is developed and released on a flexible release cycle; generally, each quarter
 a beta is released followed by a GA version. Occasionally, the cycle may be extended to properly implement and
 test larger changes before a new release is made available.
 
 End of Life for this collection is generally a 2-year cycle unless a dependency reaches EOL prior to the 2 years.
-For example, if a collection has released and its dependency reaches EOL 1 year later, then the collection will EOL
+For example, if a collection has released and a dependency reaches EOL 1 year later, then the collection will EOL
 at the same time as the dependency, 1 year later.
 
+Life Cycle Phase
+================
+
+To encourage the adoption of new features while keeping the high standard of stability inherent,
+support is divided into life cycle phases; **full support** which covers the first year
+and **maintenance support** which covers the second year.
+
++--------------------------+------------------------------------+---------------------------+
+| Life Cycle Phase         | Full Support                       | Maintenance Support       |
++==========================+====================================+===========================+
+| Critical security fixes  | Yes                                | Yes                       |
++--------------------------+------------------------------------+---------------------------+
+| Bug fixes by severity    | Critical and high severity issues  | Critical severity issues  |
++--------------------------+------------------------------------+---------------------------+
+
+Severities
+==========
+
+Severity 1 (Critical):
+A problem that severely impacts your use of the software in a production environment (such as loss
+of production data or in which your production systems are not functioning). The situation halts
+your business operations and no procedural workaround exists.
+
+Severity 2 (high):
+A problem where the software is functioning but your use in a production environment is severely
+reduced. The situation is causing a high impact to portions of your business operations and no
+procedural workaround exists.
+
+Severity 3 (medium):
+A problem that involves partial, non-critical loss of use of the software in a production environment
+or development environment and your business continues to function, including by using a procedural
+workaround.
+
+Severity 4 (low):
+A general usage question, reporting of a documentation error, or recommendation for a future product
+enhancement or modification.
+
+Severities 3 and 4 are generally addressed in subsequent releases to ensure a high standard of stability
+remains available for production environments.
+
+Support Matrix
+==============
+
 These are the component versions available when the collection was made generally available (GA). The underlying
 component version is likely to change as it reaches EOL, thus components must be a version that is
 currently supported.
 
 For example, if a collection releases with a minimum version of ``ansible-core`` 2.14.0 (Ansible 7.0) and later this
 enters into EOL, then a newer supported version of ``ansible-core`` (Ansible) must be selected. When choosing a newer
 ``ansible-core`` (Ansible) version, review the `ansible-core support matrix`_ to select the appropriate dependencies.
-This is important to note, different releases of ``ansible-core`` can require newer controller and managed node
+This is important to note, different releases of ``ansible-core`` can require newer control node and managed node
 dependencies such as is the case with Python.
 
-If the controller is Ansible Automation Platform (AAP), review the `Red Hat Ansible Automation Platform Life Cycle`_
+If the control node is Ansible Automation Platform (AAP), review the `Red Hat Ansible Automation Platform Life Cycle`_
 to select a supported AAP version.
 
 For IBM product lifecycle information, you can search for products using a product name, version or ID. For example,
-to view IBM's **Open Enterprise SDK for Python** lifecycle, search on product ID `5655-PYT`_, and for **Z Open Automation Utilities**,
-search on product ID `5698-PA1`_.
+to view IBM's `Open Enterprise SDK for Python lifecycle`_, search on product ID `5655-PYT`_, and for
+`Z Open Automation Utilities lifecycle`_, search on product ID `5698-PA1`_.
+
+The z/OS managed node includes several shells, currently the only supported shell is the z/OS Shell located in path
+`/bin/sh`_. To configure which shell the ansible control node will use on the target machine, set inventory variable
+**ansible_shell_executable**.
+
+.. code-block:: sh
+
+   ansible_shell_executable: /bin/sh
+
 
-Support Matrix
-==============
 +---------+----------------------------+---------------------------------------------------+---------------+---------------+
 | Version | Controller                 | Managed Node                                      | GA            | End of Life   |
 +=========+============================+===================================================+===============+===============+
-| 1.10.x  |- `ansible-core`_ >=2.15.x  |- `z/OS`_ V2R4 - V2Rx                              | In preview    | TBD           |
+| 1.10.x  |- `ansible-core`_ >=2.15.x  |- `z/OS`_ V2R4 - V2Rx                              | 21 June 2024  | 21 June 2026  |
 |         |- `Ansible`_ >=8.0.x        |- `z/OS shell`_                                    |               |               |
 |         |- `AAP`_ >=2.4              |- IBM `Open Enterprise SDK for Python`_            |               |               |
 |         |                            |- IBM `Z Open Automation Utilities`_ >=1.3.0       |               |               |
@@ -88,11 +139,17 @@ Support Matrix
    https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.4.0/com.ibm.zos.v2r4.bpxa400/part1.htm
 .. _z/OS:
    https://www.ibm.com/docs/en/zos
+.. _Open Enterprise SDK for Python lifecycle:
+   https://www.ibm.com/support/pages/lifecycle/search?q=5655-PYT
 .. _5655-PYT:
    https://www.ibm.com/support/pages/lifecycle/search?q=5655-PYT
+.. _Z Open Automation Utilities lifecycle:
+   https://www.ibm.com/support/pages/lifecycle/search?q=5698-PA1
 .. _5698-PA1:
    https://www.ibm.com/support/pages/lifecycle/search?q=5698-PA1
 .. _ansible-core:
    https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix
 .. _Ansible:
-   https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix
+   https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix
+.. _/bin/sh:
+   https://www.ibm.com/docs/en/zos/3.1.0?topic=descriptions-sh-invoke-shell

ibm_zos_core/docs/source/modules/zos_copy.html

@@ -876,6 +876,8 @@ <h2><a class="toc-backref" href="#id4">Notes</a><a class="headerlink" href="#not
 <p>For supported character sets used to encode data, refer to the <a class="reference external" href="https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/resources/character_set.html">documentation</a>.</p>
 <p>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.</p>
 <p>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 <code class="docutils literal notranslate"><span class="pre">executable</span></code> 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.</p>
+<p>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.</p>
+<p>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.</p>
 </div>
 </div>
 <div class="section" id="see-also">