From ddcf29b355c31080b2af683834c88cd3c93f5fa2 Mon Sep 17 00:00:00 2001 From: ddimatos Date: Thu, 8 Aug 2024 10:02:17 -0700 Subject: [PATCH] Automated commit to update documentation --- .../docs/source/release_notes.rst.txt | 114 +--- .../docs/source/modules/zos_apf.rst.txt | 68 +- .../docs/source/modules/zos_archive.rst.txt | 88 +-- .../source/modules/zos_backup_restore.rst.txt | 70 +- .../source/modules/zos_blockinfile.rst.txt | 52 +- .../docs/source/modules/zos_copy.rst.txt | 180 ++--- .../docs/source/modules/zos_data_set.rst.txt | 299 +++----- .../docs/source/modules/zos_encode.rst.txt | 58 +- .../docs/source/modules/zos_fetch.rst.txt | 42 +- .../docs/source/modules/zos_find.rst.txt | 20 +- .../source/modules/zos_gather_facts.rst.txt | 14 +- .../source/modules/zos_job_output.rst.txt | 16 +- .../docs/source/modules/zos_job_query.rst.txt | 20 +- .../source/modules/zos_job_submit.rst.txt | 76 +-- .../source/modules/zos_lineinfile.rst.txt | 68 +- .../docs/source/modules/zos_mount.rst.txt | 86 +-- .../docs/source/modules/zos_mvs_raw.rst.txt | 366 +++++----- .../docs/source/modules/zos_operator.rst.txt | 8 +- .../modules/zos_operator_action_query.rst.txt | 20 +- .../docs/source/modules/zos_ping.rst.txt | 8 +- .../docs/source/modules/zos_script.rst.txt | 32 +- .../source/modules/zos_tso_command.rst.txt | 4 +- .../docs/source/modules/zos_unarchive.rst.txt | 58 +- .../source/modules/zos_volume_init.rst.txt | 34 +- .../ibm_zos_core/docs/source/plugins.rst.txt | 2 +- .../docs/source/reference/community.rst.txt | 2 +- .../docs/source/release_notes.rst.txt | 5 +- .../resources/releases_maintenance.rst.txt | 63 +- .../docs/source/bibliography.rst.txt | 12 + .../docs/source/development.rst.txt | 97 ++- .../docs/source/modules.rst.txt | 6 + .../docs/source/modules/zhmc_adapter.rst.txt | 22 +- .../source/modules/zhmc_adapter_list.rst.txt | 16 +- .../docs/source/modules/zhmc_console.rst.txt | 22 +- .../docs/source/modules/zhmc_cpc.rst.txt | 24 +- .../source/modules/zhmc_cpc_capacity.rst.txt | 419 ++++++++++++ .../docs/source/modules/zhmc_cpc_list.rst.txt | 12 +- .../modules/zhmc_crypto_attachment.rst.txt | 16 +- .../docs/source/modules/zhmc_hba.rst.txt | 16 +- .../zhmc_ldap_server_definition.rst.txt | 18 +- .../zhmc_ldap_server_definition_list.rst.txt | 14 +- .../docs/source/modules/zhmc_lpar.rst.txt | 40 +- .../source/modules/zhmc_lpar_command.rst.txt | 197 ++++++ .../source/modules/zhmc_lpar_list.rst.txt | 18 +- .../source/modules/zhmc_lpar_messages.rst.txt | 16 +- .../docs/source/modules/zhmc_nic.rst.txt | 16 +- .../docs/source/modules/zhmc_nic_list.rst.txt | 14 +- .../source/modules/zhmc_partition.rst.txt | 49 +- .../modules/zhmc_partition_command.rst.txt | 196 ++++++ .../modules/zhmc_partition_list.rst.txt | 16 +- .../modules/zhmc_partition_messages.rst.txt | 16 +- .../source/modules/zhmc_password_rule.rst.txt | 18 +- .../modules/zhmc_password_rule_list.rst.txt | 14 +- .../docs/source/modules/zhmc_session.rst.txt | 10 +- .../source/modules/zhmc_storage_group.rst.txt | 28 +- .../zhmc_storage_group_attachment.rst.txt | 14 +- .../modules/zhmc_storage_volume.rst.txt | 20 +- .../docs/source/modules/zhmc_user.rst.txt | 26 +- .../source/modules/zhmc_user_list.rst.txt | 12 +- .../source/modules/zhmc_user_pattern.rst.txt | 288 ++++++++ .../modules/zhmc_user_pattern_list.rst.txt | 192 ++++++ .../source/modules/zhmc_user_role.rst.txt | 28 +- .../modules/zhmc_user_role_list.rst.txt | 12 +- .../docs/source/modules/zhmc_versions.rst.txt | 276 ++++++++ .../modules/zhmc_virtual_function.rst.txt | 16 +- .../docs/source/release_notes.rst.txt | 168 ++++- genindex.html | 39 +- ibm_zos_cics/docs/source/release_notes.html | 154 +---- ibm_zos_core/docs/source/modules/zos_apf.html | 4 +- .../docs/source/modules/zos_archive.html | 6 +- .../docs/source/modules/zos_blockinfile.html | 10 +- .../docs/source/modules/zos_copy.html | 6 +- .../docs/source/modules/zos_data_set.html | 122 +--- .../docs/source/modules/zos_encode.html | 25 +- .../docs/source/modules/zos_fetch.html | 24 +- .../docs/source/modules/zos_job_output.html | 2 +- .../docs/source/modules/zos_job_query.html | 10 +- .../docs/source/modules/zos_job_submit.html | 61 +- .../docs/source/modules/zos_lineinfile.html | 6 +- .../docs/source/modules/zos_mvs_raw.html | 36 +- .../docs/source/modules/zos_operator.html | 13 +- .../docs/source/modules/zos_ping.html | 20 +- .../docs/source/modules/zos_unarchive.html | 2 +- .../docs/source/modules/zos_volume_init.html | 2 +- ibm_zos_core/docs/source/release_notes.html | 16 +- .../resources/releases_maintenance.html | 66 +- objects.inv | Bin 5458 -> 5977 bytes release/release.html | 2 +- searchindex.js | 2 +- .../docs/source/bibliography.html | 34 +- .../docs/source/development.html | 128 ++-- zhmc-ansible-modules/docs/source/modules.html | 104 +-- .../docs/source/modules/zhmc_adapter.html | 84 +-- .../source/modules/zhmc_adapter_list.html | 78 ++- .../docs/source/modules/zhmc_console.html | 78 ++- .../docs/source/modules/zhmc_cpc.html | 82 +-- .../source/modules/zhmc_cpc_capacity.html | 646 ++++++++++++++++++ .../docs/source/modules/zhmc_cpc_list.html | 68 +- .../modules/zhmc_crypto_attachment.html | 76 ++- .../docs/source/modules/zhmc_hba.html | 76 ++- .../modules/zhmc_ldap_server_definition.html | 78 ++- .../zhmc_ldap_server_definition_list.html | 74 +- .../docs/source/modules/zhmc_lpar.html | 96 ++- .../source/modules/zhmc_lpar_command.html | 434 ++++++++++++ .../docs/source/modules/zhmc_lpar_list.html | 78 ++- .../source/modules/zhmc_lpar_messages.html | 74 +- .../docs/source/modules/zhmc_nic.html | 76 ++- .../docs/source/modules/zhmc_nic_list.html | 76 ++- .../docs/source/modules/zhmc_partition.html | 118 ++-- .../modules/zhmc_partition_command.html | 434 ++++++++++++ .../source/modules/zhmc_partition_list.html | 78 ++- .../modules/zhmc_partition_messages.html | 76 ++- .../source/modules/zhmc_password_rule.html | 76 ++- .../modules/zhmc_password_rule_list.html | 74 +- .../docs/source/modules/zhmc_session.html | 64 +- .../source/modules/zhmc_storage_group.html | 88 +-- .../zhmc_storage_group_attachment.html | 74 +- .../source/modules/zhmc_storage_volume.html | 80 ++- .../docs/source/modules/zhmc_user.html | 82 +-- .../docs/source/modules/zhmc_user_list.html | 68 +- .../source/modules/zhmc_user_pattern.html | 523 ++++++++++++++ .../modules/zhmc_user_pattern_list.html | 435 ++++++++++++ .../docs/source/modules/zhmc_user_role.html | 86 +-- .../source/modules/zhmc_user_role_list.html | 68 +- .../docs/source/modules/zhmc_versions.html | 522 ++++++++++++++ .../source/modules/zhmc_virtual_function.html | 76 ++- .../docs/source/release_notes.html | 139 +++- 127 files changed, 7462 insertions(+), 3034 deletions(-) create mode 100644 _sources/zhmc-ansible-modules/docs/source/modules/zhmc_cpc_capacity.rst.txt create mode 100644 _sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar_command.rst.txt create mode 100644 _sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition_command.rst.txt create mode 100644 _sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_pattern.rst.txt create mode 100644 _sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_pattern_list.rst.txt create mode 100644 _sources/zhmc-ansible-modules/docs/source/modules/zhmc_versions.rst.txt create mode 100644 zhmc-ansible-modules/docs/source/modules/zhmc_cpc_capacity.html create mode 100644 zhmc-ansible-modules/docs/source/modules/zhmc_lpar_command.html create mode 100644 zhmc-ansible-modules/docs/source/modules/zhmc_partition_command.html create mode 100644 zhmc-ansible-modules/docs/source/modules/zhmc_user_pattern.html create mode 100644 zhmc-ansible-modules/docs/source/modules/zhmc_user_pattern_list.html create mode 100644 zhmc-ansible-modules/docs/source/modules/zhmc_versions.html diff --git a/_sources/ibm_zos_cics/docs/source/release_notes.rst.txt b/_sources/ibm_zos_cics/docs/source/release_notes.rst.txt index 6c9c2095..fe309b76 100644 --- a/_sources/ibm_zos_cics/docs/source/release_notes.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/release_notes.rst.txt @@ -15,33 +15,24 @@ What's New **New modules** **General Availability of CICS provisioning modules.** You can use these Ansible modules to create automation tasks that provision or deprovision, and start or stop -a CICS region. Sample playbooks show you how to do this with the latest version of the Ansible IBM z/OS CICS collection. All modules were initially released -with Version 1.1.0-beta as noted below. Subsequent Version 1.1.0-beta releases may include enhancements and bugfixes for these modules. Refer to the What's new -of Version 1.1.0-beta releases for details. - -You can use the following modules for provisioning and managing CICS TS data sets: - -* ``aux_temp_storage`` for the CICS auxiliary temporary storage data set. This module was initially - released as ``auxiliary_temp`` with Version 1.1.0-beta.4. The module is changed to ``aux_temp_storage`` in Version 2.1.0. -* ``aux_trace`` for the CICS auxiliary trace data sets. This module was initially released as ``trace`` with Version 1.1.0-beta.4. - The module is changed to ``aux_trace`` in Version 2.1.0. -* ``csd`` for the CICS system definition data set. This module was initially released with Version 1.1.0-beta.4. -* ``global_catalog`` for the CICS global catalog data set. This module was initially released with Version 1.1.0-beta.4. -* ``local_request_queue`` for the CICS local request queue data set. This module was initially released with Version 1.1.0-beta.3. -* ``td_intrapartition`` for the CICS transient data intrapartition data set. This module was initially released as ``intrapartition`` with - Version 1.1.0-beta.4. The module is changed to ``td_intrapartition`` in Version 2.1.0. -* ``transaction_dump`` for the CICS transaction dump data sets. This module was initially released with Version 1.1.0-beta.4. +a CICS region. Sample playbooks show you how to do this with the latest version of the Ansible IBM z/OS CICS collection. + +You can use the following modules to provision and manage CICS TS data sets: + +* ``aux_temp_storage`` can be used to create or remove the CICS auxiliary temporary storage data set. +* ``aux_trace`` can be used to allocate the CICS auxiliary trace data sets. +* ``csd`` can be used to create, manage, or remove the CICS system definition data set. +* ``global_catalog`` can be used to create, manage, or remove the CICS global catalog data set. +* ``local_request_queue`` can be used to create, manage, or remove the CICS local request queue data set. +* ``td_intrapartition`` can be used to create or remove the CICS transient data intrapartition data set. +* ``transaction_dump`` can be used to allocate the CICS transaction dump data sets. You can use the following modules for CICS startup and shutdown operations: -* ``region_jcl`` - Create a CICS startup JCL data set. This module replaces ``start_cics``, which was released with Version 1.1.0-beta.5. - ``region_jcl`` is significantly different from ``start_cics`` in function. ``region_jcl`` creates a data set that contains the startup JCL, but - doesn't perform the actual startup processing. ``region_jcl`` also supports definition and allocation of user data sets with the ``user_data_sets`` parameter. -* ``stop_region`` - Stop a CICS region. This module was initially released as ``stop_cics`` with Version 1.1.0-beta.5. The module is changed to ``stop_region`` - in Version 2.1.0. In Version 2.1.0, ``stop_region`` supports a new input parameter, ``job_name`` so that you can use the job name, which is typically the CICS's - APPLID, to identify a running CICS region. +* ``region_jcl`` can be used to create a CICS startup JCL data set. +* ``stop_region`` can be used to stop a CICS region. -The group name for the CICS provisioning modules is ``region``. However, in the Version 1.1.0-beta releases, the group name was ``region_group``. +The group name for the CICS provisioning modules is ``region``. CICS provisioning modules provide support for all in-service CICS TS releases including the latest CICS TS 6.2. @@ -62,84 +53,11 @@ What's New * **Removed support for Python 2.7.** Python 2.7 is no longer supported as the managed node runtime. -Version 1.1.0-beta.5 -============= -What's New -------------------- - -**New modules** - -* ``start_cics`` - Start a CICS region. -* ``stop_cics`` - Stop a CICS region. - -**Changed modules** - -* ``csd`` - A new ``state`` option, ``script`` is introduced so that you can now supply a script that contains ``CSDUP`` commands to update an existing CSD. The script can be either a data set or a z/OS UNIX file. -* All modules for CICS region data sets - New option ``space_secondary`` is introduced so that you can specify the size of the secondary extent. -* All modules for CICS region data sets - Return values now use ``data_set_organization`` to indicate the organization of the data set. The ``vsam`` field has been removed from the return structure. - - -Version 1.1.0-beta.4 +Version 1.0.6 ============= What's New ------------------- - -**New modules** - -* ``auxiliary_temp`` - Create and remove the CICS auxiliary temporary storage data set. -* ``csd`` - Create, remove, and manage the CICS system definition data set. -* ``intrapartition`` - Create and remove the CICS transient data intrapartition data set. -* ``trace`` - Allocate the CICS auxiliary trace data sets. -* ``transaction_dump`` - Allocate the CICS transaction dump data sets. - -**Changed modules** - -* ``local_request_queue`` - New option ``warm`` added to the ``state`` input parameter. - -**Bugfixes** - -* ``local_request_queue`` and ``local_request_queue`` - The behavior of these modules with ``state`` set to ``initial`` is updated to match documentation. - -Version 1.1.0-beta.3 -============= -What's New -------------------- - -**New modules** - -* ``local_request_queue`` - Create and remove the CICS local request queue data set. - -**Changed modules** - -* ``global_catalog`` and ``local_catalog`` - Added support for the ``region_data_sets`` and ``cics_data_sets`` defaults groups. This enhancement changes the way you specify the data set location for these modules. - -Version 1.1.0-beta.2 -============= -What's New -------------------- - -**New modules** - -* ``local_catalog`` - Create, initialize, and manage the CICS local catalog data set. - -**Changed modules** - -* ``global_catalog`` - Added return values ``start_state``, ``end_state``, and ``executions``. - -**Bugfixes** - -* ``global_catalog`` - Fixed an issue that when input parameters were lowercase, the module failed. Now these input parameters are not case sensitive. -* ``global_catalog`` - Fixed an issue that was found in the ``changed`` flag. Now the ``changed`` flag corresponds with the actions taken during the ``global_catalog`` execution. - - -Version 1.1.0-beta.1 -============= -What's New -------------------- - -**New modules** - -* ``global_catalog`` - Create, initialize, and manage the CICS global catalog data set. +* Bug fix that allows the CICSPlex SM Scope and Context to contain special characters '$', '@', and '#'. Version 1.0.5 diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_apf.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_apf.rst.txt index 265d3fff..a94fdc95 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_apf.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_apf.rst.txt @@ -37,7 +37,7 @@ library state - Ensure that the library is added \ :literal:`state=present`\ or removed \ :literal:`state=absent`\ . + Ensure that the library is added ``state=present`` or removed ``state=absent``. The APF list format has to be "DYNAMIC". @@ -58,24 +58,24 @@ force_dynamic volume - The identifier for the volume containing the library specified in the \ :literal:`library`\ parameter. The values must be one the following. + The identifier for the volume containing the library specified in the ``library`` parameter. The values must be one the following. 1. The volume serial number. - 2. Six asterisks \ :literal:`\*\*\*\*\*\*`\ , indicating that the system must use the volume serial number of the current system residence (SYSRES) volume. + 2. Six asterisks ``******``, indicating that the system must use the volume serial number of the current system residence (SYSRES) volume. - 3. \*MCAT\*, indicating that the system must use the volume serial number of the volume containing the master catalog. + 3. *MCAT*, indicating that the system must use the volume serial number of the volume containing the master catalog. - If \ :literal:`volume`\ is not specified, \ :literal:`library`\ has to be cataloged. + If ``volume`` is not specified, ``library`` has to be cataloged. | **required**: False | **type**: str sms - Indicates that the library specified in the \ :literal:`library`\ parameter is managed by the storage management subsystem (SMS), and therefore no volume is associated with the library. + Indicates that the library specified in the ``library`` parameter is managed by the storage management subsystem (SMS), and therefore no volume is associated with the library. - If \ :literal:`sms=True`\ , \ :literal:`volume`\ value will be ignored. + If ``sms=True``, ``volume`` value will be ignored. | **required**: False | **type**: bool @@ -83,13 +83,13 @@ sms operation - Change APF list format to "DYNAMIC" \ :literal:`operation=set\_dynamic`\ or "STATIC" \ :literal:`operation=set\_static`\ + Change APF list format to "DYNAMIC" ``operation=set_dynamic`` or "STATIC" ``operation=set_static`` - Display APF list current format \ :literal:`operation=check\_format`\ + Display APF list current format ``operation=check_format`` - Display APF list entries when \ :literal:`operation=list`\ \ :literal:`library`\ , \ :literal:`volume`\ and \ :literal:`sms`\ will be used as filters. + Display APF list entries when ``operation=list`` ``library``, ``volume`` and ``sms`` will be used as filters. - If \ :literal:`operation`\ is not set, add or remove operation will be ignored. + If ``operation`` is not set, add or remove operation will be ignored. | **required**: False | **type**: str @@ -99,23 +99,23 @@ operation tmp_hlq Override the default high level qualifier (HLQ) for temporary and backup datasets. - The default HLQ is the Ansible user used to execute the module and if that is not available, then the value \ :literal:`TMPHLQ`\ is used. + The default HLQ is the Ansible user used to execute the module and if that is not available, then the value ``TMPHLQ`` is used. | **required**: False | **type**: str persistent - Add/remove persistent entries to or from \ :emphasis:`data\_set\_name`\ + Add/remove persistent entries to or from *data_set_name* - \ :literal:`library`\ will not be persisted or removed if \ :literal:`persistent=None`\ + ``library`` will not be persisted or removed if ``persistent=None`` | **required**: False | **type**: dict data_set_name - The data set name used for persisting or removing a \ :literal:`library`\ from the APF list. + The data set name used for persisting or removing a ``library`` from the APF list. | **required**: True | **type**: str @@ -124,13 +124,13 @@ persistent marker The marker line template. - \ :literal:`{mark}`\ will be replaced with "BEGIN" and "END". + ``{mark}`` will be replaced with "BEGIN" and "END". - Using a custom marker without the \ :literal:`{mark}`\ variable may result in the block being repeatedly inserted on subsequent playbook runs. + Using a custom marker without the ``{mark}`` variable may result in the block being repeatedly inserted on subsequent playbook runs. - \ :literal:`{mark}`\ length may not exceed 72 characters. + ``{mark}`` length may not exceed 72 characters. - The timestamp (\) used in the default marker follows the '+%Y%m%d-%H%M%S' date format + The timestamp () used in the default marker follows the '+%Y%m%d-%H%M%S' date format | **required**: False | **type**: str @@ -138,9 +138,9 @@ persistent backup - Creates a backup file or backup data set for \ :emphasis:`data\_set\_name`\ , including the timestamp information to ensure that you retrieve the original APF list defined in \ :emphasis:`data\_set\_name`\ ". + 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*". - \ :emphasis:`backup\_name`\ can be used to specify a backup file name if \ :emphasis:`backup=true`\ . + *backup_name* can be used to specify a backup file name if *backup=true*. The backup file name will be return on either success or failure of module execution such that data can be retrieved. @@ -152,11 +152,11 @@ persistent backup_name Specify the USS file name or data set name for the destination backup. - If the source \ :emphasis:`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 *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 is an MVS data set, the backup\_name must be an MVS data set name. + If the source is an MVS data set, the backup_name must be an MVS data set name. - If the backup\_name is not provided, the default backup\_name will be used. If the source is a USS file or path, the name of the backup file will be the source file or path name appended with a timestamp. For example, \ :literal:`/path/file\_name.2020-04-23-08-32-29-bak.tar`\ . + If the backup_name is not provided, the default backup_name will be used. If the source is a USS file or path, the name of the backup file will be the source file or path name appended with a timestamp. For example, ``/path/file_name.2020-04-23-08-32-29-bak.tar``. If the source is an MVS data set, it will be a data set with a random name generated by calling the ZOAU API. The MVS backup data set recovery can be done by renaming it. @@ -168,9 +168,9 @@ persistent batch A list of dictionaries for adding or removing libraries. - This is mutually exclusive with \ :literal:`library`\ , \ :literal:`volume`\ , \ :literal:`sms`\ + This is mutually exclusive with ``library``, ``volume``, ``sms`` - Can be used with \ :literal:`persistent`\ + Can be used with ``persistent`` | **required**: False | **type**: list @@ -185,24 +185,24 @@ batch volume - The identifier for the volume containing the library specified on the \ :literal:`library`\ parameter. The values must be one of the following. + The identifier for the volume containing the library specified on the ``library`` parameter. The values must be one of the following. 1. The volume serial number - 2. Six asterisks \ :literal:`\*\*\*\*\*\*`\ , indicating that the system must use the volume serial number of the current system residence (SYSRES) volume. + 2. Six asterisks ``******``, indicating that the system must use the volume serial number of the current system residence (SYSRES) volume. - 3. \*MCAT\*, indicating that the system must use the volume serial number of the volume containing the master catalog. + 3. *MCAT*, indicating that the system must use the volume serial number of the volume containing the master catalog. - If \ :literal:`volume`\ is not specified, \ :literal:`library`\ has to be cataloged. + If ``volume`` is not specified, ``library`` has to be cataloged. | **required**: False | **type**: str sms - Indicates that the library specified in the \ :literal:`library`\ parameter is managed by the storage management subsystem (SMS), and therefore no volume is associated with the library. + Indicates that the library specified in the ``library`` parameter is managed by the storage management subsystem (SMS), and therefore no volume is associated with the library. - If true \ :literal:`volume`\ will be ignored. + If true ``volume`` will be ignored. | **required**: False | **type**: bool @@ -283,9 +283,9 @@ Return Values stdout The stdout from ZOAU command apfadm. Output varies based on the type of operation. - state\> stdout of the executed operator command (opercmd), "SETPROG" from ZOAU command apfadm + state> stdout of the executed operator command (opercmd), "SETPROG" from ZOAU command apfadm - operation\> stdout of operation options list\> Returns a list of dictionaries of APF list entries [{'vol': 'PP0L6P', 'ds': 'DFH.V5R3M0.CICS.SDFHAUTH'}, {'vol': 'PP0L6P', 'ds': 'DFH.V5R3M0.CICS.SDFJAUTH'}, ...] set\_dynamic\> Set to DYNAMIC set\_static\> Set to STATIC check\_format\> DYNAMIC or STATIC + operation> stdout of operation options list> Returns a list of dictionaries of APF list entries [{'vol': 'PP0L6P', 'ds': 'DFH.V5R3M0.CICS.SDFHAUTH'}, {'vol': 'PP0L6P', 'ds': 'DFH.V5R3M0.CICS.SDFJAUTH'}, ...] set_dynamic> Set to DYNAMIC set_static> Set to STATIC check_format> DYNAMIC or STATIC | **returned**: always | **type**: str diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_archive.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_archive.rst.txt index b900fdcd..f2971fc6 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_archive.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_archive.rst.txt @@ -20,7 +20,7 @@ Synopsis - Sources for archiving must be on the remote z/OS system. - Supported sources are USS (UNIX System Services) or z/OS data sets. - The archive remains on the remote z/OS system. -- For supported archive formats, see option \ :literal:`format`\ . +- For supported archive formats, see option ``format``. @@ -35,7 +35,7 @@ src USS file paths should be absolute paths. - MVS data sets supported types are: \ :literal:`SEQ`\ , \ :literal:`PDS`\ , \ :literal:`PDSE`\ . + MVS data sets supported types are: ``SEQ``, ``PDS``, ``PDSE``. VSAMs are not supported. @@ -68,7 +68,7 @@ format terse_pack - Compression option for use with the terse format, \ :emphasis:`name=terse`\ . + Compression option for use with the terse format, *name=terse*. Pack will compress records in a data set so that the output results in lossless data compression. @@ -88,14 +88,14 @@ format If the data set provided exists, the data set must have the following attributes: LRECL=255, BLKSIZE=3120, and RECFM=VB - When providing the \ :emphasis:`xmit\_log\_data\_set`\ name, ensure there is adequate space. + When providing the *xmit_log_data_set* name, ensure there is adequate space. | **required**: False | **type**: str use_adrdssu - If set to true, the \ :literal:`zos\_archive`\ module will use Data Facility Storage Management Subsystem data set services (DFSMSdss) program ADRDSSU to compress data sets into a portable format before using \ :literal:`xmit`\ or \ :literal:`terse`\ . + If set to true, the ``zos_archive`` module will use Data Facility Storage Management Subsystem data set services (DFSMSdss) program ADRDSSU to compress data sets into a portable format before using ``xmit`` or ``terse``. | **required**: False | **type**: bool @@ -107,19 +107,19 @@ format dest The remote absolute path or data set where the archive should be created. - \ :emphasis:`dest`\ can be a USS file or MVS data set name. + *dest* can be a USS file or MVS data set name. - If \ :emphasis:`dest`\ has missing parent directories, they will be created. + If *dest* has missing parent directories, they will be created. - If \ :emphasis:`dest`\ is a nonexistent USS file, it will be created. + If *dest* is a nonexistent USS file, it will be created. - If \ :emphasis:`dest`\ is an existing file or data set and \ :emphasis:`force=true`\ , the existing \ :emphasis:`dest`\ will be deleted and recreated with attributes defined in the \ :emphasis:`dest\_data\_set`\ option or computed by the module. + If *dest* is an existing file or data set and *force=true*, the existing *dest* will be deleted and recreated with attributes defined in the *dest_data_set* option or computed by the module. - If \ :emphasis:`dest`\ is an existing file or data set and \ :emphasis:`force=false`\ or not specified, the module exits with a note to the user. + If *dest* is an existing file or data set and *force=false* or not specified, the module exits with a note to the user. - Destination data set attributes can be set using \ :emphasis:`dest\_data\_set`\ . + Destination data set attributes can be set using *dest_data_set*. - Destination data set space will be calculated based on space of source data sets provided and/or found by expanding the pattern name. Calculating space can impact module performance. Specifying space attributes in the \ :emphasis:`dest\_data\_set`\ option will improve performance. + Destination data set space will be calculated based on space of source data sets provided and/or found by expanding the pattern name. Calculating space can impact module performance. Specifying space attributes in the *dest_data_set* option will improve performance. | **required**: True | **type**: str @@ -128,9 +128,9 @@ dest exclude Remote absolute path, glob, or list of paths, globs or data set name patterns for the file, files or data sets to exclude from src list and glob expansion. - Patterns (wildcards) can contain one of the following, \`?\`, \`\*\`. + Patterns (wildcards) can contain one of the following, `?`, `*`. - \* matches everything. + * matches everything. ? matches any single character. @@ -144,7 +144,7 @@ group When left unspecified, it uses the current group of the current use unless you are root, in which case it can preserve the previous ownership. - This option is only applicable if \ :literal:`dest`\ is USS, otherwise ignored. + This option is only applicable if ``dest`` is USS, otherwise ignored. | **required**: False | **type**: str @@ -153,13 +153,13 @@ group mode The permission of the destination archive file. - If \ :literal:`dest`\ is USS, this will act as Unix file mode, otherwise ignored. + If ``dest`` is USS, this will act as Unix file mode, otherwise ignored. - It should be noted that modes are octal numbers. The user must either add a leading zero so that Ansible's YAML parser knows it is an octal number (like \ :literal:`0644`\ or \ :literal:`01777`\ )or quote it (like \ :literal:`'644'`\ or \ :literal:`'1777'`\ ) so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results. + It should be noted that modes are octal numbers. The user must either add a leading zero so that Ansible's YAML parser knows it is an octal number (like ``0644`` or ``01777``)or quote it (like ``'644'`` or ``'1777'``) so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results. The mode may also be specified as a symbolic mode (for example, 'u+rwx' or 'u=rw,g=r,o=r') or a special string 'preserve'. - \ :emphasis:`mode=preserve`\ means that the file will be given the same permissions as the src file. + *mode=preserve* means that the file will be given the same permissions as the src file. | **required**: False | **type**: str @@ -170,14 +170,14 @@ owner When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. - This option is only applicable if \ :literal:`dest`\ is USS, otherwise ignored. + This option is only applicable if ``dest`` is USS, otherwise ignored. | **required**: False | **type**: str remove - Remove any added source files , trees or data sets after module \ `zos\_archive <./zos_archive.html>`__\ adds them to the archive. Source files, trees and data sets are identified with option \ :emphasis:`src`\ . + Remove any added source files , trees or data sets after module `zos_archive <./zos_archive.html>`_ adds them to the archive. Source files, trees and data sets are identified with option *src*. | **required**: False | **type**: bool @@ -185,7 +185,7 @@ remove dest_data_set - Data set attributes to customize a \ :literal:`dest`\ data set to be archived into. + Data set attributes to customize a ``dest`` data set to be archived into. | **required**: False | **type**: dict @@ -208,18 +208,18 @@ dest_data_set space_primary - If the destination \ :emphasis:`dest`\ data set does not exist , this sets the primary space allocated for the data set. + If the destination *dest* data set does not exist , this sets the primary space allocated for the data set. - The unit of space used is set using \ :emphasis:`space\_type`\ . + The unit of space used is set using *space_type*. | **required**: False | **type**: int space_secondary - If the destination \ :emphasis:`dest`\ data set does not exist , this sets the secondary space allocated for the data set. + If the destination *dest* data set does not exist , this sets the secondary space allocated for the data set. - The unit of space used is set using \ :emphasis:`space\_type`\ . + The unit of space used is set using *space_type*. | **required**: False | **type**: int @@ -228,7 +228,7 @@ dest_data_set space_type If the destination data set does not exist, this sets the unit of measurement to use when defining primary and secondary space. - Valid units of size are \ :literal:`k`\ , \ :literal:`m`\ , \ :literal:`g`\ , \ :literal:`cyl`\ , and \ :literal:`trk`\ . + Valid units of size are ``k``, ``m``, ``g``, ``cyl``, and ``trk``. | **required**: False | **type**: str @@ -236,7 +236,7 @@ dest_data_set record_format - If the destination data set does not exist, this sets the format of the data set. (e.g \ :literal:`FB`\ ) + If the destination data set does not exist, this sets the format of the data set. (e.g ``FB``) Choices are case-sensitive. @@ -313,18 +313,18 @@ dest_data_set tmp_hlq Override the default high level qualifier (HLQ) for temporary data sets. - The default HLQ is the Ansible user used to execute the module and if that is not available, then the environment variable value \ :literal:`TMPHLQ`\ is used. + The default HLQ is the Ansible user used to execute the module and if that is not available, then the environment variable value ``TMPHLQ`` is used. | **required**: False | **type**: str force - If set to \ :literal:`true`\ and the remote file or data set \ :literal:`dest`\ will be deleted. Otherwise it will be created with the \ :literal:`dest\_data\_set`\ attributes or default values if \ :literal:`dest\_data\_set`\ is not specified. + If set to ``true`` and the remote file or data set ``dest`` will be deleted. Otherwise it will be created with the ``dest_data_set`` attributes or default values if ``dest_data_set`` is not specified. - If set to \ :literal:`false`\ , the file or data set will only be copied if the destination does not exist. + If set to ``false``, the file or data set will only be copied if the destination does not exist. - If set to \ :literal:`false`\ and destination exists, the module exits with a note to the user. + If set to ``false`` and destination exists, the module exits with a note to the user. | **required**: False | **type**: bool @@ -392,11 +392,11 @@ Notes ----- .. note:: - This module does not perform a send or transmit operation to a remote node. If you want to transport the archive you can use zos\_fetch to retrieve to the controller and then zos\_copy or zos\_unarchive for copying to a remote or send to the remote and then unpack the archive respectively. + This module does not perform a send or transmit operation to a remote node. If you want to transport the archive you can use zos_fetch to retrieve to the controller and then zos_copy or zos_unarchive for copying to a remote or send to the remote and then unpack the archive respectively. - When packing and using \ :literal:`use\_adrdssu`\ flag the module will take up to two times the space indicated in \ :literal:`dest\_data\_set`\ . + When packing and using ``use_adrdssu`` flag the module will take up to two times the space indicated in ``dest_data_set``. - tar, zip, bz2 and pax are archived using python \ :literal:`tarfile`\ library which uses the latest version available for each format, for compatibility when opening from system make sure to use the latest available version for the intended format. + tar, zip, bz2 and pax are archived using python ``tarfile`` library which uses the latest version available for each format, for compatibility when opening from system make sure to use the latest available version for the intended format. @@ -416,27 +416,27 @@ Return Values state - The state of the input \ :literal:`src`\ . + The state of the input ``src``. - \ :literal:`absent`\ when the source files or data sets were removed. + ``absent`` when the source files or data sets were removed. - \ :literal:`present`\ when the source files or data sets were not removed. + ``present`` when the source files or data sets were not removed. - \ :literal:`incomplete`\ when \ :literal:`remove`\ was true and the source files or data sets were not removed. + ``incomplete`` when ``remove`` was true and the source files or data sets were not removed. | **returned**: always | **type**: str dest_state - The state of the \ :emphasis:`dest`\ file or data set. + The state of the *dest* file or data set. - \ :literal:`absent`\ when the file does not exist. + ``absent`` when the file does not exist. - \ :literal:`archive`\ when the file is an archive. + ``archive`` when the file is an archive. - \ :literal:`compress`\ when the file is compressed, but not an archive. + ``compress`` when the file is compressed, but not an archive. - \ :literal:`incomplete`\ when the file is an archive, but some files under \ :emphasis:`src`\ were not found. + ``incomplete`` when the file is an archive, but some files under *src* were not found. | **returned**: success | **type**: str @@ -454,7 +454,7 @@ archived | **type**: list arcroot - If \ :literal:`src`\ is a list of USS files, this returns the top most parent folder of the list of files, otherwise is empty. + If ``src`` is a list of USS files, this returns the top most parent folder of the list of files, otherwise is empty. | **returned**: always | **type**: str diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_backup_restore.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_backup_restore.rst.txt index e8216dd3..69ca57cd 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_backup_restore.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_backup_restore.rst.txt @@ -47,34 +47,34 @@ data_sets include - When \ :emphasis:`operation=backup`\ , specifies a list of data sets or data set patterns to include in the backup. + When *operation=backup*, specifies a list of data sets or data set patterns to include in the backup. - When \ :emphasis:`operation=restore`\ , specifies a list of data sets or data set patterns to include when restoring from a backup. + When *operation=restore*, specifies a list of data sets or data set patterns to include when restoring from a backup. - The single asterisk, \ :literal:`\*`\ , is used in place of exactly one qualifier. In addition, it can be used to indicate to DFSMSdss that only part of a qualifier has been specified. + The single asterisk, ``*``, is used in place of exactly one qualifier. In addition, it can be used to indicate to DFSMSdss that only part of a qualifier has been specified. - When used with other qualifiers, the double asterisk, \ :literal:`\*\*`\ , indicates either the nonexistence of leading, trailing, or middle qualifiers, or the fact that they play no role in the selection process. + When used with other qualifiers, the double asterisk, ``**``, indicates either the nonexistence of leading, trailing, or middle qualifiers, or the fact that they play no role in the selection process. Two asterisks are the maximum permissible in a qualifier. If there are two asterisks in a qualifier, they must be the first and last characters. - A question mark \ :literal:`?`\ or percent sign \ :literal:`%`\ matches a single character. + A question mark ``?`` or percent sign ``%`` matches a single character. | **required**: False | **type**: raw exclude - When \ :emphasis:`operation=backup`\ , specifies a list of data sets or data set patterns to exclude from the backup. + When *operation=backup*, specifies a list of data sets or data set patterns to exclude from the backup. - When \ :emphasis:`operation=restore`\ , specifies a list of data sets or data set patterns to exclude when restoring from a backup. + When *operation=restore*, specifies a list of data sets or data set patterns to exclude when restoring from a backup. - The single asterisk, \ :literal:`\*`\ , is used in place of exactly one qualifier. In addition, it can be used to indicate that only part of a qualifier has been specified." + The single asterisk, ``*``, is used in place of exactly one qualifier. In addition, it can be used to indicate that only part of a qualifier has been specified." - When used with other qualifiers, the double asterisk, \ :literal:`\*\*`\ , indicates either the nonexistence of leading, trailing, or middle qualifiers, or the fact that they play no role in the selection process. + When used with other qualifiers, the double asterisk, ``**``, indicates either the nonexistence of leading, trailing, or middle qualifiers, or the fact that they play no role in the selection process. Two asterisks are the maximum permissible in a qualifier. If there are two asterisks in a qualifier, they must be the first and last characters. - A question mark \ :literal:`?`\ or percent sign \ :literal:`%`\ matches a single character. + A question mark ``?`` or percent sign ``%`` matches a single character. | **required**: False | **type**: raw @@ -84,22 +84,22 @@ data_sets volume This applies to both data set restores and volume restores. - When \ :emphasis:`operation=backup`\ and \ :emphasis:`data\_sets`\ are provided, specifies the volume that contains the data sets to backup. + When *operation=backup* and *data_sets* are provided, specifies the volume that contains the data sets to backup. - When \ :emphasis:`operation=restore`\ , specifies the volume the backup should be restored to. + When *operation=restore*, specifies the volume the backup should be restored to. - \ :emphasis:`volume`\ is required when restoring a full volume backup. + *volume* is required when restoring a full volume backup. | **required**: False | **type**: str full_volume - When \ :emphasis:`operation=backup`\ and \ :emphasis:`full\_volume=True`\ , specifies that the entire volume provided to \ :emphasis:`volume`\ should be backed up. + When *operation=backup* and *full_volume=True*, specifies that the entire volume provided to *volume* should be backed up. - When \ :emphasis:`operation=restore`\ and \ :emphasis:`full\_volume=True`\ , specifies that the volume should be restored (default is dataset). + When *operation=restore* and *full_volume=True*, specifies that the volume should be restored (default is dataset). - \ :emphasis:`volume`\ must be provided when \ :emphasis:`full\_volume=True`\ . + *volume* must be provided when *full_volume=True*. | **required**: False | **type**: bool @@ -109,18 +109,18 @@ full_volume temp_volume Specifies a particular volume on which the temporary data sets should be created during the backup and restore process. - When \ :emphasis:`operation=backup`\ and \ :emphasis:`backup\_name`\ is a data set, specifies the volume the backup should be placed in. + When *operation=backup* and *backup_name* is a data set, specifies the volume the backup should be placed in. | **required**: False | **type**: str backup_name - When \ :emphasis:`operation=backup`\ , the destination data set or UNIX file to hold the backup. + When *operation=backup*, the destination data set or UNIX file to hold the backup. - When \ :emphasis:`operation=restore`\ , the destination data set or UNIX file backup to restore. + When *operation=restore*, the destination data set or UNIX file backup to restore. - There are no enforced conventions for backup names. However, using a common extension like \ :literal:`.dzp`\ for UNIX files and \ :literal:`.DZP`\ for data sets will improve readability. + There are no enforced conventions for backup names. However, using a common extension like ``.dzp`` for UNIX files and ``.DZP`` for data sets will improve readability. | **required**: True | **type**: str @@ -135,9 +135,9 @@ recover overwrite - When \ :emphasis:`operation=backup`\ , specifies if an existing data set or UNIX file matching \ :emphasis:`backup\_name`\ should be deleted. + When *operation=backup*, specifies if an existing data set or UNIX file matching *backup_name* should be deleted. - When \ :emphasis:`operation=restore`\ , specifies if the module should overwrite existing data sets with matching name on the target device. + When *operation=restore*, specifies if the module should overwrite existing data sets with matching name on the target device. | **required**: False | **type**: bool @@ -145,35 +145,35 @@ overwrite sms_storage_class - When \ :emphasis:`operation=restore`\ , specifies the storage class to use. The storage class will also be used for temporary data sets created during restore process. + When *operation=restore*, specifies the storage class to use. The storage class will also be used for temporary data sets created during restore process. - When \ :emphasis:`operation=backup`\ , specifies the storage class to use for temporary data sets created during backup process. + When *operation=backup*, specifies the storage class to use for temporary data sets created during backup process. - If neither of \ :emphasis:`sms\_storage\_class`\ or \ :emphasis:`sms\_management\_class`\ are specified, the z/OS system's Automatic Class Selection (ACS) routines will be used. + If neither of *sms_storage_class* or *sms_management_class* are specified, the z/OS system's Automatic Class Selection (ACS) routines will be used. | **required**: False | **type**: str sms_management_class - When \ :emphasis:`operation=restore`\ , specifies the management class to use. The management class will also be used for temporary data sets created during restore process. + When *operation=restore*, specifies the management class to use. The management class will also be used for temporary data sets created during restore process. - When \ :emphasis:`operation=backup`\ , specifies the management class to use for temporary data sets created during backup process. + When *operation=backup*, specifies the management class to use for temporary data sets created during backup process. - If neither of \ :emphasis:`sms\_storage\_class`\ or \ :emphasis:`sms\_management\_class`\ are specified, the z/OS system's Automatic Class Selection (ACS) routines will be used. + If neither of *sms_storage_class* or *sms_management_class* are specified, the z/OS system's Automatic Class Selection (ACS) routines will be used. | **required**: False | **type**: str space - If \ :emphasis:`operation=backup`\ , specifies the amount of space to allocate for the backup. Please note that even when backing up to a UNIX file, backup contents will be temporarily held in a data set. + If *operation=backup*, specifies the amount of space to allocate for the backup. Please note that even when backing up to a UNIX file, backup contents will be temporarily held in a data set. - If \ :emphasis:`operation=restore`\ , specifies the amount of space to allocate for data sets temporarily created during the restore process. + If *operation=restore*, specifies the amount of space to allocate for data sets temporarily created during the restore process. - The unit of space used is set using \ :emphasis:`space\_type`\ . + The unit of space used is set using *space_type*. - When \ :emphasis:`full\_volume=True`\ , \ :emphasis:`space`\ defaults to \ :literal:`1`\ , otherwise default is \ :literal:`25`\ + When *full_volume=True*, *space* defaults to ``1``, otherwise default is ``25`` | **required**: False | **type**: int @@ -182,9 +182,9 @@ space space_type The unit of measurement to use when defining data set space. - Valid units of size are \ :literal:`k`\ , \ :literal:`m`\ , \ :literal:`g`\ , \ :literal:`cyl`\ , and \ :literal:`trk`\ . + Valid units of size are ``k``, ``m``, ``g``, ``cyl``, and ``trk``. - When \ :emphasis:`full\_volume=True`\ , \ :emphasis:`space\_type`\ defaults to \ :literal:`g`\ , otherwise default is \ :literal:`m`\ + When *full_volume=True*, *space_type* defaults to ``g``, otherwise default is ``m`` | **required**: False | **type**: str @@ -203,7 +203,7 @@ hlq tmp_hlq Override the default high level qualifier (HLQ) for temporary and backup data sets. - The default HLQ is the Ansible user that executes the module and if that is not available, then the value of \ :literal:`TMPHLQ`\ is used. + The default HLQ is the Ansible user that executes the module and if that is not available, then the value of ``TMPHLQ`` is used. | **required**: False | **type**: str diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_blockinfile.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_blockinfile.rst.txt index 8cd6f756..f3eef596 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_blockinfile.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_blockinfile.rst.txt @@ -38,9 +38,9 @@ src state - Whether the block should be inserted or replaced using \ :emphasis:`state=present`\ . + Whether the block should be inserted or replaced using *state=present*. - Whether the block should be removed using \ :emphasis:`state=absent`\ . + Whether the block should be removed using *state=absent*. | **required**: False | **type**: str @@ -51,9 +51,9 @@ state marker The marker line template. - \ :literal:`{mark}`\ will be replaced with the values \ :literal:`in marker\_begin`\ (default="BEGIN") and \ :literal:`marker\_end`\ (default="END"). + ``{mark}`` will be replaced with the values ``in marker_begin`` (default="BEGIN") and ``marker_end`` (default="END"). - Using a custom marker without the \ :literal:`{mark}`\ variable may result in the block being repeatedly inserted on subsequent playbook runs. + Using a custom marker without the ``{mark}`` variable may result in the block being repeatedly inserted on subsequent playbook runs. | **required**: False | **type**: str @@ -63,7 +63,7 @@ marker block The text to insert inside the marker lines. - Multi-line can be separated by '\\n'. + Multi-line can be separated by '\n'. Any double-quotation marks will be removed. @@ -74,11 +74,11 @@ block insertafter If specified, the block will be inserted after the last match of the specified regular expression. - A special value \ :literal:`EOF`\ for inserting a block at the end of the file is available. + A special value ``EOF`` for inserting a block at the end of the file is available. - If a specified regular expression has no matches, \ :literal:`EOF`\ will be used instead. + If a specified regular expression has no matches, ``EOF`` will be used instead. - Choices are EOF or '\*regex\*'. + Choices are EOF or '*regex*'. Default is EOF. @@ -89,18 +89,18 @@ insertafter insertbefore If specified, the block will be inserted before the last match of specified regular expression. - A special value \ :literal:`BOF`\ for inserting the block at the beginning of the file is available. + A special value ``BOF`` for inserting the block at the beginning of the file is available. If a specified regular expression has no matches, the block will be inserted at the end of the file. - Choices are BOF or '\*regex\*'. + Choices are BOF or '*regex*'. | **required**: False | **type**: str marker_begin - This will be inserted at \ :literal:`{mark}`\ in the opening ansible block marker. + This will be inserted at ``{mark}`` in the opening ansible block marker. | **required**: False | **type**: str @@ -108,7 +108,7 @@ marker_begin marker_end - This will be inserted at \ :literal:`{mark}`\ in the closing ansible block marker. + This will be inserted at ``{mark}`` in the closing ansible block marker. | **required**: False | **type**: str @@ -116,9 +116,9 @@ marker_end backup - Specifies whether a backup of destination should be created before editing the source \ :emphasis:`src`\ . + Specifies whether a backup of destination should be created before editing the source *src*. - When set to \ :literal:`true`\ , the module creates a backup file or data set. + When set to ``true``, the module creates a backup file or data set. The backup file name will be returned on either success or failure of module execution such that data can be retrieved. @@ -130,15 +130,15 @@ backup backup_name Specify the USS file name or data set name for the destination backup. - If the source \ :emphasis:`src`\ 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 *src* 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 name must be an MVS data set name, and the dataset must not be preallocated. + If the source is an MVS data set, the backup_name name must be an MVS data set name, and the dataset must not be preallocated. - If the backup\_name is not provided, the default backup\_name name will be used. If the source is a USS file or path, the name of the backup file will be the source file or path name appended with a timestamp, e.g. \ :literal:`/path/file\_name.2020-04-23-08-32-29-bak.tar`\ . + If the backup_name is not provided, the default backup_name name will be used. If the source is a USS file or path, the name of the backup file will be the source file or path name appended with a timestamp, e.g. ``/path/file_name.2020-04-23-08-32-29-bak.tar``. If the source is an MVS data set, it will be a data set with a random name generated by calling the ZOAU API. The MVS backup data set recovery can be done by renaming it. - If \ :emphasis:`src`\ is a data set member and backup\_name is not provided, the data set member will be backed up to the same partitioned data set with a randomly generated member name. + If *src* is a data set member and backup_name is not provided, the data set member will be backed up to the same partitioned data set with a randomly generated member name. | **required**: False | **type**: str @@ -147,14 +147,14 @@ backup_name tmp_hlq Override the default high level qualifier (HLQ) for temporary and backup datasets. - The default HLQ is the Ansible user used to execute the module and if that is not available, then the value \ :literal:`TMPHLQ`\ is used. + The default HLQ is the Ansible user used to execute the module and if that is not available, then the value ``TMPHLQ`` is used. | **required**: False | **type**: str encoding - The character set of the source \ :emphasis:`src`\ . \ `zos\_blockinfile <./zos_blockinfile.html>`__\ requires it to be provided with correct encoding to read the content of a USS file or data set. If this parameter is not provided, this module assumes that USS file or data set is encoded in IBM-1047. + The character set of the source *src*. `zos_blockinfile <./zos_blockinfile.html>`_ requires it to be provided with correct encoding to read the content of a USS file or data set. If this parameter is not provided, this module assumes that USS file or data set is encoded in IBM-1047. Supported character sets rely on the charset conversion utility (iconv) version; the most common character sets are supported. @@ -168,7 +168,7 @@ force This is helpful when a data set is being used in a long running process such as a started task and you are wanting to update or read. - The \ :literal:`force`\ option enables sharing of data sets through the disposition \ :emphasis:`DISP=SHR`\ . + The ``force`` option enables sharing of data sets through the disposition *DISP=SHR*. | **required**: False | **type**: bool @@ -290,13 +290,13 @@ Notes .. note:: It is the playbook author or user's responsibility to avoid files that should not be encoded, such as binary files. 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. - All data sets are always assumed to be cataloged. If an uncataloged data set needs to be encoded, it should be cataloged first. The \ `zos\_data\_set <./zos_data_set.html>`__\ module can be used to catalog uncataloged data sets. + All data sets are always assumed to be cataloged. If an uncataloged data set needs to be encoded, it should be cataloged first. The `zos_data_set <./zos_data_set.html>`_ module can be used to catalog uncataloged data sets. - For supported character sets used to encode data, refer to the \ `documentation `__\ . + For supported character sets used to encode data, refer to the `documentation `_. - When using \`\`with\_\*\`\` loops be aware that if you do not set a unique mark the block will be overwritten on each iteration. + When using ``with_*`` loops be aware that if you do not set a unique mark the block will be overwritten on each iteration. - When more then one block should be handled in a file you must change the \ :emphasis:`marker`\ per task. + When more then one block should be handled in a file you must change the *marker* per task. @@ -315,7 +315,7 @@ Return Values changed - Indicates if the source was modified. Value of 1 represents \`true\`, otherwise \`false\`. + Indicates if the source was modified. Value of 1 represents `true`, otherwise `false`. | **returned**: success | **type**: bool diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_copy.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_copy.rst.txt index b63b3956..611f5136 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_copy.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_copy.rst.txt @@ -16,7 +16,7 @@ zos_copy -- Copy data to z/OS Synopsis -------- -- The \ `zos\_copy <./zos_copy.html>`__\ module copies a file or data set from a local or a remote machine to a location on the remote machine. +- The `zos_copy <./zos_copy.html>`_ module copies a file or data set from a local or a remote machine to a location on the remote machine. @@ -27,17 +27,17 @@ Parameters asa_text - If set to \ :literal:`true`\ , indicates that either \ :literal:`src`\ or \ :literal:`dest`\ or both contain ASA control characters. + If set to ``true``, indicates that either ``src`` or ``dest`` or both contain ASA control characters. - When \ :literal:`src`\ is a USS file and \ :literal:`dest`\ is a data set, the copy will preserve ASA control characters in the destination. + When ``src`` is a USS file and ``dest`` is a data set, the copy will preserve ASA control characters in the destination. - When \ :literal:`src`\ is a data set containing ASA control characters and \ :literal:`dest`\ is a USS file, the copy will put all control characters as plain text in the destination. + When ``src`` is a data set containing ASA control characters and ``dest`` is a USS file, the copy will put all control characters as plain text in the destination. - If \ :literal:`dest`\ is a non-existent data set, it will be created with record format Fixed Block with ANSI format (FBA). + If ``dest`` is a non-existent data set, it will be created with record format Fixed Block with ANSI format (FBA). - If neither \ :literal:`src`\ or \ :literal:`dest`\ have record format Fixed Block with ANSI format (FBA) or Variable Block with ANSI format (VBA), the module will fail. + 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 \ :literal:`is\_binary`\ is \ :literal:`true`\ or \ :literal:`executable`\ is \ :literal:`true`\ as well, 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. | **required**: False | **type**: bool @@ -47,7 +47,7 @@ asa_text backup Specifies whether a backup of the destination should be created before copying data. - When set to \ :literal:`true`\ , the module creates a backup file or data set. + When set to ``true``, the module creates a backup file or data set. The backup file name will be returned on either success or failure of module execution such that data can be retrieved. @@ -59,24 +59,24 @@ backup backup_name Specify a unique USS file name or data set name for the destination backup. - If the destination \ :literal:`dest`\ is a USS file or path, the \ :literal:`backup\_name`\ must be an absolute path name. + If the destination ``dest`` is a USS file or path, the ``backup_name`` must be an absolute path name. - If the destination is an MVS data set name, the \ :literal:`backup\_name`\ provided must meet data set naming conventions of one or more qualifiers, each from one to eight characters long, that are delimited by periods. + If the destination is an MVS data set name, the ``backup_name`` provided must meet data set naming conventions of one or more qualifiers, each from one to eight characters long, that are delimited by periods. - If the \ :literal:`backup\_name`\ is not provided, the default \ :literal:`backup\_name`\ will be used. If the \ :literal:`dest`\ is a USS file or USS path, the name of the backup file will be the destination file or path name appended with a timestamp, e.g. \ :literal:`/path/file\_name.2020-04-23-08-32-29-bak.tar`\ . If the \ :literal:`dest`\ is an MVS data set, it will be a data set with a randomly generated name. + If the ``backup_name`` is not provided, the default ``backup_name`` will be used. If the ``dest`` is a USS file or USS path, the name of the backup file will be the destination file or path name appended with a timestamp, e.g. ``/path/file_name.2020-04-23-08-32-29-bak.tar``. If the ``dest`` is an MVS data set, it will be a data set with a randomly generated name. - If \ :literal:`dest`\ is a data set member and \ :literal:`backup\_name`\ is not provided, the data set member will be backed up to the same partitioned data set with a randomly generated member name. + If ``dest`` is a data set member and ``backup_name`` is not provided, the data set member will be backed up to the same partitioned data set with a randomly generated member name. | **required**: False | **type**: str content - When used instead of \ :literal:`src`\ , sets the contents of a file or data set directly to the specified value. + When used instead of ``src``, sets the contents of a file or data set directly to the specified value. - Works only when \ :literal:`dest`\ is a USS file, sequential data set, or a partitioned data set member. + Works only when ``dest`` is a USS file, sequential data set, or a partitioned data set member. - If \ :literal:`dest`\ is a directory, then content will be copied to \ :literal:`/path/to/dest/inline\_copy`\ . + If ``dest`` is a directory, then content will be copied to ``/path/to/dest/inline_copy``. | **required**: False | **type**: str @@ -85,27 +85,27 @@ content dest The remote absolute path or data set where the content should be copied to. - \ :literal:`dest`\ can be a USS file, directory or MVS data set name. + ``dest`` can be a USS file, directory or MVS data set name. - If \ :literal:`dest`\ has missing parent directories, they will be created. + If ``dest`` has missing parent directories, they will be created. - If \ :literal:`dest`\ is a nonexistent USS file, it will be created. + If ``dest`` is a nonexistent USS file, it will be created. - If \ :literal:`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 module will fail. + 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 module will fail. - If \ :literal:`dest`\ is a nonexistent data set, it will be created following the process outlined here and in the \ :literal:`volume`\ option. + If ``dest`` is a nonexistent data set, it will be created following the process outlined here and in the ``volume`` option. - If \ :literal:`dest`\ is a nonexistent data set, the attributes assigned will depend on the type of \ :literal:`src`\ . If \ :literal:`src`\ is a USS file, \ :literal:`dest`\ will have a Fixed Block (FB) record format and the remaining attributes will be computed. If \ :emphasis:`is\_binary=true`\ , \ :literal:`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 \ :emphasis:`executable=true`\ ,\ :literal:`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 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. - When \ :literal:`dest`\ is a data set, precedence rules apply. If \ :literal:`dest\_data\_set`\ is set, this will take precedence over an existing data set. If \ :literal:`dest`\ is an empty data set, the empty data set will be written with the expectation its attributes satisfy the copy. Lastly, if no precendent rule has been exercised, \ :literal:`dest`\ will be created with the same attributes of \ :literal:`src`\ . + When ``dest`` is a data set, precedence rules apply. If ``dest_data_set`` is set, this will take precedence over an existing data set. If ``dest`` is an empty data set, the empty data set will be written with the expectation its attributes satisfy the copy. Lastly, if no precendent rule has been exercised, ``dest`` will be created with the same attributes of ``src``. - When the \ :literal:`dest`\ is an existing VSAM (KSDS) or VSAM (ESDS), then source can be an ESDS, a KSDS or an RRDS. The VSAM (KSDS) or VSAM (ESDS) \ :literal:`dest`\ will be deleted and recreated following the process outlined in the \ :literal:`volume`\ option. + When the ``dest`` is an existing VSAM (KSDS) or VSAM (ESDS), then source can be an ESDS, a KSDS or an RRDS. The VSAM (KSDS) or VSAM (ESDS) ``dest`` will be deleted and recreated following the process outlined in the ``volume`` option. - When the \ :literal:`dest`\ is an existing VSAM (RRDS), then the source must be an RRDS. The VSAM (RRDS) will be deleted and recreated following the process outlined in the \ :literal:`volume`\ option. + When the ``dest`` is an existing VSAM (RRDS), then the source must be an RRDS. The VSAM (RRDS) will be deleted and recreated following the process outlined in the ``volume`` option. - When \ :literal:`dest`\ is and existing VSAM (LDS), then source must be an LDS. The VSAM (LDS) will be deleted and recreated following the process outlined in the \ :literal:`volume`\ option. + When ``dest`` is and existing VSAM (LDS), then source must be an LDS. The VSAM (LDS) will be deleted and recreated following the process outlined in the ``volume`` option. - When \ :literal:`dest`\ is a data set, you can override storage management rules by specifying \ :literal:`volume`\ if the storage class being used has GUARANTEED\_SPACE=YES specified, otherwise, the allocation will fail. See \ :literal:`volume`\ for more volume related processes. + When ``dest`` is a data set, you can override storage management rules by specifying ``volume`` if the storage class being used has GUARANTEED_SPACE=YES specified, otherwise, the allocation will fail. See ``volume`` for more volume related processes. | **required**: True | **type**: str @@ -114,9 +114,9 @@ dest encoding Specifies which encodings the destination file or data set should be converted from and to. - If \ :literal:`encoding`\ is not provided, the module determines which local and remote charsets to convert the data from and to. Note that this is only done for text data and not binary data. + If ``encoding`` is not provided, the module determines which local and remote charsets to convert the data from and to. Note that this is only done for text data and not binary data. - Only valid if \ :literal:`is\_binary`\ is false. + Only valid if ``is_binary`` is false. | **required**: False | **type**: dict @@ -140,22 +140,22 @@ encoding tmp_hlq Override the default high level qualifier (HLQ) for temporary and backup datasets. - The default HLQ is the Ansible user used to execute the module and if that is not available, then the value \ :literal:`TMPHLQ`\ is used. + The default HLQ is the Ansible user used to execute the module and if that is not available, then the value ``TMPHLQ`` is used. | **required**: False | **type**: str force - If set to \ :literal:`true`\ and the remote file or data set \ :literal:`dest`\ is empty, the \ :literal:`dest`\ will be reused. + If set to ``true`` and the remote file or data set ``dest`` is empty, the ``dest`` will be reused. - If set to \ :literal:`true`\ and the remote file or data set \ :literal:`dest`\ is NOT empty, the \ :literal:`dest`\ will be deleted and recreated with the \ :literal:`src`\ data set attributes, otherwise it will be recreated with the \ :literal:`dest`\ data set attributes. + 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. - To backup data before any deletion, see parameters \ :literal:`backup`\ and \ :literal:`backup\_name`\ . + To backup data before any deletion, see parameters ``backup`` and ``backup_name``. - If set to \ :literal:`false`\ , the file or data set will only be copied if the destination does not exist. + If set to ``false``, the file or data set will only be copied if the destination does not exist. - If set to \ :literal:`false`\ and destination exists, the module exits with a note to the user. + If set to ``false`` and destination exists, the module exits with a note to the user. | **required**: False | **type**: bool @@ -163,11 +163,11 @@ force force_lock - By default, when \ :literal:`dest`\ is a MVS data set and is being used by another process with DISP=SHR or DISP=OLD the module will fail. Use \ :literal:`force\_lock`\ to bypass this check and continue with copy. + 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 this check and continue with copy. - If set to \ :literal:`true`\ and destination is a MVS data set opened by another process then zos\_copy will try to copy using DISP=SHR. + 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 \ :literal:`force\_lock`\ uses operations that are subject to race conditions and can lead to data loss, use with caution. + Using ``force_lock`` 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. @@ -177,9 +177,9 @@ force_lock ignore_sftp_stderr - During data transfer through SFTP, the module fails if the SFTP command directs any content to stderr. The user is able to override this behavior by setting this parameter to \ :literal:`true`\ . By doing so, the module would essentially ignore the stderr stream produced by SFTP and continue execution. + During data transfer through SFTP, the module fails if the SFTP command directs any content to stderr. The user is able to override this behavior by setting this parameter to ``true``. By doing so, the module would essentially ignore the stderr stream produced by SFTP and continue execution. - When Ansible verbosity is set to greater than 3, either through the command line interface (CLI) using \ :strong:`-vvvv`\ or through environment variables such as \ :strong:`verbosity = 4`\ , then this parameter will automatically be set to \ :literal:`true`\ . + When Ansible verbosity is set to greater than 3, either through the command line interface (CLI) using **-vvvv** or through environment variables such as **verbosity = 4**, then this parameter will automatically be set to ``true``. | **required**: False | **type**: bool @@ -187,11 +187,11 @@ ignore_sftp_stderr is_binary - If set to \ :literal:`true`\ , indicates that the file or data set to be copied is a binary file or data set. + If set to ``true``, indicates that the file or data set to be copied is a binary file or data set. - When \ :emphasis:`is\_binary=true`\ , no encoding conversion is applied to the content, all content transferred retains the original state. + When *is_binary=true*, no encoding conversion is applied to the content, all content transferred retains the original state. - Use \ :emphasis:`is\_binary=true`\ when copying a Database Request Module (DBRM) to retain the original state of the serialized SQL statements of a program. + Use *is_binary=true* when copying a Database Request Module (DBRM) to retain the original state of the serialized SQL statements of a program. | **required**: False | **type**: bool @@ -199,15 +199,15 @@ is_binary executable - If set to \ :literal:`true`\ , indicates that the file or library to be copied is an executable. + If set to ``true``, indicates that the file or library to be copied is an executable. - If the \ :literal:`src`\ executable has an alias, the alias information is also copied. If the \ :literal:`dest`\ is Unix, the alias is not visible in Unix, even though the information is there and will be visible if copied to a library. + If the ``src`` executable has an alias, the alias information is also copied. If the ``dest`` is Unix, the alias is not visible in Unix, even though the information is there and will be visible if copied to a library. - If \ :emphasis:`executable=true`\ , and \ :literal:`dest`\ is a data set, it must be a PDS or PDSE (library). + If *executable=true*, and ``dest`` is a data set, it must be a PDS or PDSE (library). - If \ :literal:`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. + 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. - If \ :literal:`dest`\ is a file, execute permission for the user will be added to the file (\`\`u+x\`\`). + If ``dest`` is a file, execute permission for the user will be added to the file (``u+x``). | **required**: False | **type**: bool @@ -215,9 +215,9 @@ executable aliases - If set to \ :literal:`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. + 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 \ :literal:`executable=True`\ and \ :literal:`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 ``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. @@ -239,7 +239,7 @@ group When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. - This option is only applicable if \ :literal:`dest`\ is USS, otherwise ignored. + This option is only applicable if ``dest`` is USS, otherwise ignored. | **required**: False | **type**: str @@ -248,13 +248,13 @@ group mode The permission of the destination file or directory. - If \ :literal:`dest`\ is USS, this will act as Unix file mode, otherwise ignored. + If ``dest`` is USS, this will act as Unix file mode, otherwise ignored. - It should be noted that modes are octal numbers. The user must either add a leading zero so that Ansible's YAML parser knows it is an octal number (like \ :literal:`0644`\ or \ :literal:`01777`\ )or quote it (like \ :literal:`'644'`\ or \ :literal:`'1777'`\ ) so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results. + It should be noted that modes are octal numbers. The user must either add a leading zero so that Ansible's YAML parser knows it is an octal number (like ``0644`` or ``01777``)or quote it (like ``'644'`` or ``'1777'``) so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results. - The mode may also be specified as a symbolic mode (for example, \`\`u+rwx\`\` or \`\`u=rw,g=r,o=r\`\`) or a special string \`preserve\`. + The mode may also be specified as a symbolic mode (for example, ``u+rwx`` or ``u=rw,g=r,o=r``) or a special string `preserve`. - \ :emphasis:`mode=preserve`\ means that the file will be given the same permissions as the source file. + *mode=preserve* means that the file will be given the same permissions as the source file. | **required**: False | **type**: str @@ -265,16 +265,16 @@ owner When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. - This option is only applicable if \ :literal:`dest`\ is USS, otherwise ignored. + This option is only applicable if ``dest`` is USS, otherwise ignored. | **required**: False | **type**: str remote_src - If set to \ :literal:`false`\ , the module searches for \ :literal:`src`\ at the local machine. + If set to ``false``, the module searches for ``src`` at the local machine. - If set to \ :literal:`true`\ , the module goes to the remote/target machine for \ :literal:`src`\ . + If set to ``true``, the module goes to the remote/target machine for ``src``. | **required**: False | **type**: bool @@ -284,23 +284,23 @@ remote_src src Path to a file/directory or name of a data set to copy to remote z/OS system. - If \ :literal:`remote\_src`\ is true, then \ :literal:`src`\ must be the path to a Unix System Services (USS) file, name of a data set, or data set member. + If ``remote_src`` is true, then ``src`` must be the path to a Unix System Services (USS) file, name of a data set, or data set member. - If \ :literal:`src`\ is a local path or a USS path, it can be absolute or relative. + If ``src`` is a local path or a USS path, it can be absolute or relative. - If \ :literal:`src`\ is a directory, \ :literal:`dest`\ must be a partitioned data set or a USS directory. + If ``src`` is a directory, ``dest`` must be a partitioned data set or a USS directory. - If \ :literal:`src`\ is a file and \ :literal:`dest`\ ends with "/" or is a directory, the file is copied to the directory with the same filename as \ :literal:`src`\ . + If ``src`` is a file and ``dest`` ends with "/" or is a directory, the file is copied to the directory with the same filename as ``src``. - If \ :literal:`src`\ is a directory and ends with "/", the contents of it will be copied into the root of \ :literal:`dest`\ . If it doesn't end with "/", the directory itself will be copied. + If ``src`` is a directory and ends with "/", the contents of it will be copied into the root of ``dest``. If it doesn't end with "/", the directory itself will be copied. - If \ :literal:`src`\ is a directory or a file, file names will be truncated and/or modified to ensure a valid name for a data set or member. + If ``src`` is a directory or a file, file names will be truncated and/or modified to ensure a valid name for a data set or member. - If \ :literal:`src`\ is a VSAM data set, \ :literal:`dest`\ must also be a VSAM. + If ``src`` is a VSAM data set, ``dest`` must also be a VSAM. Wildcards can be used to copy multiple PDS/PDSE members to another PDS/PDSE. - Required unless using \ :literal:`content`\ . + Required unless using ``content``. | **required**: False | **type**: str @@ -317,22 +317,22 @@ validate volume - If \ :literal:`dest`\ does not exist, specify which volume \ :literal:`dest`\ should be allocated to. + If ``dest`` does not exist, specify which volume ``dest`` should be allocated to. Only valid when the destination is an MVS data set. The volume must already be present on the device. - If no volume is specified, storage management rules will be used to determine the volume where \ :literal:`dest`\ will be allocated. + If no volume is specified, storage management rules will be used to determine the volume where ``dest`` will be allocated. - If the storage administrator has specified a system default unit name and you do not set a \ :literal:`volume`\ name for non-system-managed data sets, then the system uses the volumes associated with the default unit name. Check with your storage administrator to determine whether a default unit name has been specified. + If the storage administrator has specified a system default unit name and you do not set a ``volume`` name for non-system-managed data sets, then the system uses the volumes associated with the default unit name. Check with your storage administrator to determine whether a default unit name has been specified. | **required**: False | **type**: str dest_data_set - Data set attributes to customize a \ :literal:`dest`\ data set to be copied into. + Data set attributes to customize a ``dest`` data set to be copied into. | **required**: False | **type**: dict @@ -347,18 +347,18 @@ dest_data_set space_primary - If the destination \ :emphasis:`dest`\ data set does not exist , this sets the primary space allocated for the data set. + If the destination *dest* data set does not exist , this sets the primary space allocated for the data set. - The unit of space used is set using \ :emphasis:`space\_type`\ . + The unit of space used is set using *space_type*. | **required**: False | **type**: int space_secondary - If the destination \ :emphasis:`dest`\ data set does not exist , this sets the secondary space allocated for the data set. + If the destination *dest* data set does not exist , this sets the secondary space allocated for the data set. - The unit of space used is set using \ :emphasis:`space\_type`\ . + The unit of space used is set using *space_type*. | **required**: False | **type**: int @@ -367,7 +367,7 @@ dest_data_set space_type If the destination data set does not exist, this sets the unit of measurement to use when defining primary and secondary space. - Valid units of size are \ :literal:`k`\ , \ :literal:`m`\ , \ :literal:`g`\ , \ :literal:`cyl`\ , and \ :literal:`trk`\ . + Valid units of size are ``k``, ``m``, ``g``, ``cyl``, and ``trk``. | **required**: False | **type**: str @@ -375,7 +375,7 @@ dest_data_set record_format - If the destination data set does not exist, this sets the format of the data set. (e.g \ :literal:`fb`\ ) + If the destination data set does not exist, this sets the format of the data set. (e.g ``fb``) Choices are case-sensitive. @@ -412,9 +412,9 @@ dest_data_set key_offset The key offset to use when creating a KSDS data set. - \ :emphasis:`key\_offset`\ is required when \ :emphasis:`type=ksds`\ . + *key_offset* is required when *type=ksds*. - \ :emphasis:`key\_offset`\ should only be provided when \ :emphasis:`type=ksds`\ + *key_offset* should only be provided when *type=ksds* | **required**: False | **type**: int @@ -423,9 +423,9 @@ dest_data_set key_length The key length to use when creating a KSDS data set. - \ :emphasis:`key\_length`\ is required when \ :emphasis:`type=ksds`\ . + *key_length* is required when *type=ksds*. - \ :emphasis:`key\_length`\ should only be provided when \ :emphasis:`type=ksds`\ + *key_length* should only be provided when *type=ksds* | **required**: False | **type**: int @@ -472,13 +472,13 @@ dest_data_set use_template - Whether the module should treat \ :literal:`src`\ as a Jinja2 template and render it before continuing with the rest of the module. + Whether the module should treat ``src`` as a Jinja2 template and render it before continuing with the rest of the module. - Only valid when \ :literal:`src`\ is a local file or directory. + Only valid when ``src`` is a local file or directory. - All variables defined in inventory files, vars files and the playbook will be passed to the template engine, as well as \ `Ansible special variables `__\ , such as \ :literal:`playbook\_dir`\ , \ :literal:`ansible\_version`\ , etc. + All variables defined in inventory files, vars files and the playbook will be passed to the template engine, as well as `Ansible special variables `_, such as ``playbook_dir``, ``ansible_version``, etc. - If variables defined in different scopes share the same name, Ansible will apply variable precedence to them. You can see the complete precedence order \ `in Ansible's documentation `__\ + If variables defined in different scopes share the same name, Ansible will apply variable precedence to them. You can see the complete precedence order `in Ansible's documentation `_ | **required**: False | **type**: bool @@ -488,9 +488,9 @@ use_template template_parameters Options to set the way Jinja2 will process templates. - Jinja2 already sets defaults for the markers it uses, you can find more information at its \ `official documentation `__\ . + Jinja2 already sets defaults for the markers it uses, you can find more information at its `official documentation `_. - These options are ignored unless \ :literal:`use\_template`\ is true. + These options are ignored unless ``use_template`` is true. | **required**: False | **type**: dict @@ -569,7 +569,7 @@ template_parameters trim_blocks Whether Jinja2 should remove the first newline after a block is removed. - Setting this option to \ :literal:`False`\ will result in newlines being added to the rendered template. This could create invalid code when working with JCL templates or empty records in destination data sets. + Setting this option to ``False`` will result in newlines being added to the rendered template. This could create invalid code when working with JCL templates or empty records in destination data sets. | **required**: False | **type**: bool @@ -803,17 +803,17 @@ Notes .. note:: Destination data sets are assumed to be in catalog. When trying to copy to an uncataloged data set, the module assumes that the data set does not exist and will create it. - Destination will be backed up if either \ :literal:`backup`\ is \ :literal:`true`\ or \ :literal:`backup\_name`\ is provided. If \ :literal:`backup`\ is \ :literal:`false`\ but \ :literal:`backup\_name`\ is provided, task will fail. + Destination will be backed up if either ``backup`` is ``true`` or ``backup_name`` is provided. If ``backup`` is ``false`` but ``backup_name`` is provided, task will fail. When copying local files or directories, temporary storage will be used on the remote z/OS system. The size of the temporary storage will correspond to the size of the file or directory being copied. Temporary files will always be deleted, regardless of success or failure of the copy task. VSAM data sets can only be copied to other VSAM data sets. - For supported character sets used to encode data, refer to the \ `documentation `__\ . + For supported character sets used to encode data, refer to the `documentation `_. 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 \ :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. + 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. 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. @@ -924,7 +924,7 @@ destination_attributes checksum - SHA256 checksum of the file after running zos\_copy. + SHA256 checksum of the file after running zos_copy. | **returned**: When ``validate=true`` and if ``dest`` is USS | **type**: str diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_data_set.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_data_set.rst.txt index caed66ba..34162d72 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_data_set.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_data_set.rst.txt @@ -28,11 +28,11 @@ Parameters name - The name of the data set being managed. (e.g \ :literal:`USER.TEST`\ ) + The name of the data set being managed. (e.g ``USER.TEST``) - If \ :emphasis:`name`\ is not provided, a randomized data set name will be generated with the HLQ matching the module-runners username. + If *name* is not provided, a randomized data set name will be generated with the HLQ matching the module-runners username. - Required if \ :emphasis:`type=member`\ or \ :emphasis:`state!=present`\ and not using \ :emphasis:`batch`\ . + Required if *type=member* or *state!=present* and not using *batch*. | **required**: False | **type**: str @@ -41,52 +41,49 @@ name state The final state desired for specified data set. - If \ :emphasis:`state=absent`\ and the data set does not exist on the managed node, no action taken, module completes successfully with \ :emphasis:`changed=False`\ . + If *state=absent* and the data set does not exist on the managed node, no action taken, module completes successfully with *changed=False*. - If \ :emphasis:`state=absent`\ and the data set does exist on the managed node, remove the data set, module completes successfully with \ :emphasis:`changed=True`\ . + If *state=absent* and the data set does exist on the managed node, remove the data set, module completes successfully with *changed=True*. - If \ :emphasis:`state=absent`\ and \ :emphasis:`type=member`\ and \ :emphasis:`force=True`\ , the data set will be opened with \ :emphasis:`DISP=SHR`\ such that the entire data set can be accessed by other processes while the specified member is deleted. + If *state=absent* and *type=member* and *force=True*, the data set will be opened with *DISP=SHR* such that the entire data set can be accessed by other processes while the specified member is deleted. - If \ :emphasis:`state=absent`\ and \ :emphasis:`volumes`\ is provided, and the data set is not found in the catalog, the module attempts to perform catalog using supplied \ :emphasis:`name`\ and \ :emphasis:`volumes`\ . If the attempt to catalog the data set catalog is successful, then the data set is removed. Module completes successfully with \ :emphasis:`changed=True`\ . + If *state=absent* and *volumes* is provided, and the data set is not found in the catalog, the module attempts to perform catalog using supplied *name* and *volumes*. If the attempt to catalog the data set catalog is successful, then the data set is removed. Module completes successfully with *changed=True*. - If \ :emphasis:`state=absent`\ and \ :emphasis:`volumes`\ is provided, and the data set is not found in the catalog, the module attempts to perform catalog using supplied \ :emphasis:`name`\ and \ :emphasis:`volumes`\ . If the attempt to catalog the data set catalog fails, then no action is taken. Module completes successfully with \ :emphasis:`changed=False`\ . + If *state=absent* and *volumes* is provided, and the data set is not found in the catalog, the module attempts to perform catalog using supplied *name* and *volumes*. If the attempt to catalog the data set catalog fails, then no action is taken. Module completes successfully with *changed=False*. - If \ :emphasis:`state=absent`\ and \ :emphasis:`volumes`\ is provided, and the data set is found in the catalog, the module compares the catalog volume attributes to the provided \ :emphasis:`volumes`\ . If the volume attributes are different, the cataloged data set will be uncataloged temporarily while the requested data set be deleted is cataloged. The module will catalog the original data set on completion, if the attempts to catalog fail, no action is taken. Module completes successfully with \ :emphasis:`changed=False`\ . + If *state=absent* and *volumes* is provided, and the data set is found in the catalog, the module compares the catalog volume attributes to the provided *volumes*. If the volume attributes are different, the cataloged data set will be uncataloged temporarily while the requested data set be deleted is cataloged. The module will catalog the original data set on completion, if the attempts to catalog fail, no action is taken. Module completes successfully with *changed=False*. - If \ :emphasis:`state=absent`\ and \ :emphasis:`type=gdg`\ and the GDG base has active generations the module will complete successfully with \ :emphasis:`changed=False`\ . To remove it option \ :emphasis:`force`\ needs to be used. If the GDG base does not have active generations the module will complete successfully with \ :emphasis:`changed=True`\ . + If *state=present* and the data set does not exist on the managed node, create and catalog the data set, module completes successfully with *changed=True*. - If \ :emphasis:`state=present`\ and the data set does not exist on the managed node, create and catalog the data set, module completes successfully with \ :emphasis:`changed=True`\ . + If *state=present* and *replace=True* and the data set is present on the managed node the existing data set is deleted, and a new data set is created and cataloged with the desired attributes, module completes successfully with *changed=True*. - If \ :emphasis:`state=present`\ and \ :emphasis:`replace=True`\ and the data set is present on the managed node the existing data set is deleted, and a new data set is created and cataloged with the desired attributes, module completes successfully with \ :emphasis:`changed=True`\ . + If *state=present* and *replace=False* and the data set is present on the managed node, no action taken, module completes successfully with *changed=False*. - If \ :emphasis:`state=present`\ and \ :emphasis:`replace=False`\ and the data set is present on the managed node, no action taken, module completes successfully with \ :emphasis:`changed=False`\ . + If *state=present* and *type=member* and the member does not exist in the data set, create a member formatted to store data, module completes successfully with *changed=True*. Note, a PDSE does not allow a mixture of formats such that there is executables (program objects) and data. The member created is formatted to store data, not an executable. - If \ :emphasis:`state=present`\ and \ :emphasis:`type=member`\ and the member does not exist in the data set, create a member formatted to store data, module completes successfully with \ :emphasis:`changed=True`\ . Note, a PDSE does not allow a mixture of formats such that there is executables (program objects) and data. The member created is formatted to store data, not an executable. + If *state=cataloged* and *volumes* is provided and the data set is already cataloged, no action taken, module completes successfully with *changed=False*. - If \ :emphasis:`state=cataloged`\ and \ :emphasis:`volumes`\ is provided and the data set is already cataloged, no action taken, module completes successfully with \ :emphasis:`changed=False`\ . + If *state=cataloged* and *volumes* is provided and the data set is not cataloged, module attempts to perform catalog using supplied *name* and *volumes*. If the attempt to catalog the data set catalog is successful, module completes successfully with *changed=True*. - If \ :emphasis:`state=cataloged`\ and \ :emphasis:`volumes`\ is provided and the data set is not cataloged, module attempts to perform catalog using supplied \ :emphasis:`name`\ and \ :emphasis:`volumes`\ . If the attempt to catalog the data set catalog is successful, module completes successfully with \ :emphasis:`changed=True`\ . + If *state=cataloged* and *volumes* is provided and the data set is not cataloged, module attempts to perform catalog using supplied *name* and *volumes*. If the attempt to catalog the data set catalog fails, returns failure with *changed=False*. - If \ :emphasis:`state=cataloged`\ and \ :emphasis:`volumes`\ is provided and the data set is not cataloged, module attempts to perform catalog using supplied \ :emphasis:`name`\ and \ :emphasis:`volumes`\ . If the attempt to catalog the data set catalog fails, returns failure with \ :emphasis:`changed=False`\ . + If *state=uncataloged* and the data set is not found, no action taken, module completes successfully with *changed=False*. - If \ :emphasis:`state=uncataloged`\ and the data set is not found, no action taken, module completes successfully with \ :emphasis:`changed=False`\ . - - - If \ :emphasis:`state=uncataloged`\ and the data set is found, the data set is uncataloged, module completes successfully with \ :emphasis:`changed=True`\ . + If *state=uncataloged* and the data set is found, the data set is uncataloged, module completes successfully with *changed=True*. | **required**: False @@ -96,22 +93,22 @@ state type - The data set type to be used when creating a data set. (e.g \ :literal:`pdse`\ ). + The data set type to be used when creating a data set. (e.g ``pdse``). - \ :literal:`member`\ expects to be used with an existing partitioned data set. + ``member`` expects to be used with an existing partitioned data set. Choices are case-sensitive. | **required**: False | **type**: str | **default**: pds - | **choices**: ksds, esds, rrds, lds, seq, pds, pdse, library, basic, large, member, hfs, zfs, gdg + | **choices**: ksds, esds, rrds, lds, seq, pds, pdse, library, basic, large, member, hfs, zfs space_primary The amount of primary space to allocate for the dataset. - The unit of space used is set using \ :emphasis:`space\_type`\ . + The unit of space used is set using *space_type*. | **required**: False | **type**: int @@ -121,7 +118,7 @@ space_primary space_secondary The amount of secondary space to allocate for the dataset. - The unit of space used is set using \ :emphasis:`space\_type`\ . + The unit of space used is set using *space_type*. | **required**: False | **type**: int @@ -131,7 +128,7 @@ space_secondary space_type The unit of measurement to use when defining primary and secondary space. - Valid units of size are \ :literal:`k`\ , \ :literal:`m`\ , \ :literal:`g`\ , \ :literal:`cyl`\ , and \ :literal:`trk`\ . + Valid units of size are ``k``, ``m``, ``g``, ``cyl``, and ``trk``. | **required**: False | **type**: str @@ -140,11 +137,11 @@ space_type record_format - The format of the data set. (e.g \ :literal:`FB`\ ) + The format of the data set. (e.g ``FB``) Choices are case-sensitive. - When \ :emphasis:`type=ksds`\ , \ :emphasis:`type=esds`\ , \ :emphasis:`type=rrds`\ , \ :emphasis:`type=lds`\ or \ :emphasis:`type=zfs`\ then \ :emphasis:`record\_format=None`\ , these types do not have a default \ :emphasis:`record\_format`\ . + When *type=ksds*, *type=esds*, *type=rrds*, *type=lds* or *type=zfs* then *record_format=None*, these types do not have a default *record_format*. | **required**: False | **type**: str @@ -219,9 +216,9 @@ directory_blocks key_offset The key offset to use when creating a KSDS data set. - \ :emphasis:`key\_offset`\ is required when \ :emphasis:`type=ksds`\ . + *key_offset* is required when *type=ksds*. - \ :emphasis:`key\_offset`\ should only be provided when \ :emphasis:`type=ksds`\ + *key_offset* should only be provided when *type=ksds* | **required**: False | **type**: int @@ -230,96 +227,28 @@ key_offset key_length The key length to use when creating a KSDS data set. - \ :emphasis:`key\_length`\ is required when \ :emphasis:`type=ksds`\ . + *key_length* is required when *type=ksds*. - \ :emphasis:`key\_length`\ should only be provided when \ :emphasis:`type=ksds`\ + *key_length* should only be provided when *type=ksds* | **required**: False | **type**: int -empty - Sets the \ :emphasis:`empty`\ attribute for Generation Data Groups. - - If false, removes only the oldest GDS entry when a new GDS is created that causes GDG limit to be exceeded. - - If true, removes all GDS entries from a GDG base when a new GDS is created that causes the GDG limit to be exceeded. - - Default is false. - - | **required**: False - | **type**: bool - - -extended - Sets the \ :emphasis:`extended`\ attribute for Generation Data Groups. - - If false, allow up to 255 generation data sets (GDSs) to be associated with the GDG. - - If true, allow up to 999 generation data sets (GDS) to be associated with the GDG. - - Default is false. - - | **required**: False - | **type**: bool - - -fifo - Sets the \ :emphasis:`fifo`\ attribute for Generation Data Groups. - - If false, the order is the newest GDS defined to the oldest GDS. This is the default value. - - If true, the order is the oldest GDS defined to the newest GDS. - - Default is false. - - | **required**: False - | **type**: bool - - -limit - Sets the \ :emphasis:`limit`\ attribute for Generation Data Groups. - - Specifies the maximum number, from 1 to 255(up to 999 if extended), of GDS that can be associated with the GDG being defined. - - \ :emphasis:`limit`\ is required when \ :emphasis:`type=gdg`\ . - - | **required**: False - | **type**: int - - -purge - Sets the \ :emphasis:`purge`\ attribute for Generation Data Groups. - - Specifies whether to override expiration dates when a generation data set (GDS) is rolled off and the \ :literal:`scratch`\ option is set. - - | **required**: False - | **type**: bool - - -scratch - Sets the \ :emphasis:`scratch`\ attribute for Generation Data Groups. - - Specifies what action is to be taken for a generation data set located on disk volumes when the data set is uncataloged from the GDG base as a result of EMPTY/NOEMPTY processing. - - | **required**: False - | **type**: bool - - volumes - If cataloging a data set, \ :emphasis:`volumes`\ specifies the name of the volume(s) where the data set is located. + If cataloging a data set, *volumes* specifies the name of the volume(s) where the data set is located. - If creating a data set, \ :emphasis:`volumes`\ specifies the volume(s) where the data set should be created. + If creating a data set, *volumes* specifies the volume(s) where the data set should be created. - If \ :emphasis:`volumes`\ is provided when \ :emphasis:`state=present`\ , and the data set is not found in the catalog, \ `zos\_data\_set <./zos_data_set.html>`__\ will check the volume table of contents to see if the data set exists. If the data set does exist, it will be cataloged. + If *volumes* is provided when *state=present*, and the data set is not found in the catalog, `zos_data_set <./zos_data_set.html>`_ will check the volume table of contents to see if the data set exists. If the data set does exist, it will be cataloged. - If \ :emphasis:`volumes`\ is provided when \ :emphasis:`state=absent`\ and the data set is not found in the catalog, \ `zos\_data\_set <./zos_data_set.html>`__\ will check the volume table of contents to see if the data set exists. If the data set does exist, it will be cataloged and promptly removed from the system. + If *volumes* is provided when *state=absent* and the data set is not found in the catalog, `zos_data_set <./zos_data_set.html>`_ will check the volume table of contents to see if the data set exists. If the data set does exist, it will be cataloged and promptly removed from the system. - \ :emphasis:`volumes`\ is required when \ :emphasis:`state=cataloged`\ . + *volumes* is required when *state=cataloged*. Accepts a string when using a single volume and a list of strings when using multiple. @@ -328,12 +257,12 @@ volumes replace - When \ :emphasis:`replace=True`\ , and \ :emphasis:`state=present`\ , existing data set matching \ :emphasis:`name`\ will be replaced. + When *replace=True*, and *state=present*, existing data set matching *name* will be replaced. Replacement is performed by deleting the existing data set and creating a new data set with the same name and desired attributes. Since the existing data set will be deleted prior to creating the new data set, no data set will exist if creation of the new data set fails. - If \ :emphasis:`replace=True`\ , all data in the original data set will be lost. + If *replace=True*, all data in the original data set will be lost. | **required**: False | **type**: bool @@ -343,7 +272,7 @@ replace tmp_hlq Override the default high level qualifier (HLQ) for temporary and backup datasets. - The default HLQ is the Ansible user used to execute the module and if that is not available, then the value \ :literal:`TMPHLQ`\ is used. + The default HLQ is the Ansible user used to execute the module and if that is not available, then the value ``TMPHLQ`` is used. | **required**: False | **type**: str @@ -354,11 +283,9 @@ force This is helpful when a data set is being used in a long running process such as a started task and you are wanting to delete a member. - The \ :emphasis:`force=True`\ option enables sharing of data sets through the disposition \ :emphasis:`DISP=SHR`\ . + The *force=True* option enables sharing of data sets through the disposition *DISP=SHR*. - The \ :emphasis:`force=True`\ only applies to data set members when \ :emphasis:`state=absent`\ and \ :emphasis:`type=member`\ and when removing a GDG base with active generations. - - If \ :emphasis:`force=True`\ , \ :emphasis:`type=gdg`\ and \ :emphasis:`state=absent`\ it will force remove a GDG base with active generations. + The *force=True* only applies to data set members when *state=absent* and *type=member*. | **required**: False | **type**: bool @@ -374,11 +301,11 @@ batch name - The name of the data set being managed. (e.g \ :literal:`USER.TEST`\ ) + The name of the data set being managed. (e.g ``USER.TEST``) - If \ :emphasis:`name`\ is not provided, a randomized data set name will be generated with the HLQ matching the module-runners username. + If *name* is not provided, a randomized data set name will be generated with the HLQ matching the module-runners username. - Required if \ :emphasis:`type=member`\ or \ :emphasis:`state!=present`\ + Required if *type=member* or *state!=present* | **required**: False | **type**: str @@ -387,49 +314,49 @@ batch state The final state desired for specified data set. - If \ :emphasis:`state=absent`\ and the data set does not exist on the managed node, no action taken, module completes successfully with \ :emphasis:`changed=False`\ . + If *state=absent* and the data set does not exist on the managed node, no action taken, module completes successfully with *changed=False*. - If \ :emphasis:`state=absent`\ and the data set does exist on the managed node, remove the data set, module completes successfully with \ :emphasis:`changed=True`\ . + If *state=absent* and the data set does exist on the managed node, remove the data set, module completes successfully with *changed=True*. - If \ :emphasis:`state=absent`\ and \ :emphasis:`type=member`\ and \ :emphasis:`force=True`\ , the data set will be opened with \ :emphasis:`DISP=SHR`\ such that the entire data set can be accessed by other processes while the specified member is deleted. + If *state=absent* and *type=member* and *force=True*, the data set will be opened with *DISP=SHR* such that the entire data set can be accessed by other processes while the specified member is deleted. - If \ :emphasis:`state=absent`\ and \ :emphasis:`volumes`\ is provided, and the data set is not found in the catalog, the module attempts to perform catalog using supplied \ :emphasis:`name`\ and \ :emphasis:`volumes`\ . If the attempt to catalog the data set catalog is successful, then the data set is removed. Module completes successfully with \ :emphasis:`changed=True`\ . + If *state=absent* and *volumes* is provided, and the data set is not found in the catalog, the module attempts to perform catalog using supplied *name* and *volumes*. If the attempt to catalog the data set catalog is successful, then the data set is removed. Module completes successfully with *changed=True*. - If \ :emphasis:`state=absent`\ and \ :emphasis:`volumes`\ is provided, and the data set is not found in the catalog, the module attempts to perform catalog using supplied \ :emphasis:`name`\ and \ :emphasis:`volumes`\ . If the attempt to catalog the data set catalog fails, then no action is taken. Module completes successfully with \ :emphasis:`changed=False`\ . + If *state=absent* and *volumes* is provided, and the data set is not found in the catalog, the module attempts to perform catalog using supplied *name* and *volumes*. If the attempt to catalog the data set catalog fails, then no action is taken. Module completes successfully with *changed=False*. - If \ :emphasis:`state=absent`\ and \ :emphasis:`volumes`\ is provided, and the data set is found in the catalog, the module compares the catalog volume attributes to the provided \ :emphasis:`volumes`\ . If they volume attributes are different, the cataloged data set will be uncataloged temporarily while the requested data set be deleted is cataloged. The module will catalog the original data set on completion, if the attempts to catalog fail, no action is taken. Module completes successfully with \ :emphasis:`changed=False`\ . + If *state=absent* and *volumes* is provided, and the data set is found in the catalog, the module compares the catalog volume attributes to the provided *volumes*. If they volume attributes are different, the cataloged data set will be uncataloged temporarily while the requested data set be deleted is cataloged. The module will catalog the original data set on completion, if the attempts to catalog fail, no action is taken. Module completes successfully with *changed=False*. - If \ :emphasis:`state=present`\ and the data set does not exist on the managed node, create and catalog the data set, module completes successfully with \ :emphasis:`changed=True`\ . + If *state=present* and the data set does not exist on the managed node, create and catalog the data set, module completes successfully with *changed=True*. - If \ :emphasis:`state=present`\ and \ :emphasis:`replace=True`\ and the data set is present on the managed node the existing data set is deleted, and a new data set is created and cataloged with the desired attributes, module completes successfully with \ :emphasis:`changed=True`\ . + If *state=present* and *replace=True* and the data set is present on the managed node the existing data set is deleted, and a new data set is created and cataloged with the desired attributes, module completes successfully with *changed=True*. - If \ :emphasis:`state=present`\ and \ :emphasis:`replace=False`\ and the data set is present on the managed node, no action taken, module completes successfully with \ :emphasis:`changed=False`\ . + If *state=present* and *replace=False* and the data set is present on the managed node, no action taken, module completes successfully with *changed=False*. - If \ :emphasis:`state=present`\ and \ :emphasis:`type=member`\ and the member does not exist in the data set, create a member formatted to store data, module completes successfully with \ :emphasis:`changed=True`\ . Note, a PDSE does not allow a mixture of formats such that there is executables (program objects) and data. The member created is formatted to store data, not an executable. + If *state=present* and *type=member* and the member does not exist in the data set, create a member formatted to store data, module completes successfully with *changed=True*. Note, a PDSE does not allow a mixture of formats such that there is executables (program objects) and data. The member created is formatted to store data, not an executable. - If \ :emphasis:`state=cataloged`\ and \ :emphasis:`volumes`\ is provided and the data set is already cataloged, no action taken, module completes successfully with \ :emphasis:`changed=False`\ . + If *state=cataloged* and *volumes* is provided and the data set is already cataloged, no action taken, module completes successfully with *changed=False*. - If \ :emphasis:`state=cataloged`\ and \ :emphasis:`volumes`\ is provided and the data set is not cataloged, module attempts to perform catalog using supplied \ :emphasis:`name`\ and \ :emphasis:`volumes`\ . If the attempt to catalog the data set catalog is successful, module completes successfully with \ :emphasis:`changed=True`\ . + If *state=cataloged* and *volumes* is provided and the data set is not cataloged, module attempts to perform catalog using supplied *name* and *volumes*. If the attempt to catalog the data set catalog is successful, module completes successfully with *changed=True*. - If \ :emphasis:`state=cataloged`\ and \ :emphasis:`volumes`\ is provided and the data set is not cataloged, module attempts to perform catalog using supplied \ :emphasis:`name`\ and \ :emphasis:`volumes`\ . If the attempt to catalog the data set catalog fails, returns failure with \ :emphasis:`changed=False`\ . + If *state=cataloged* and *volumes* is provided and the data set is not cataloged, module attempts to perform catalog using supplied *name* and *volumes*. If the attempt to catalog the data set catalog fails, returns failure with *changed=False*. - If \ :emphasis:`state=uncataloged`\ and the data set is not found, no action taken, module completes successfully with \ :emphasis:`changed=False`\ . + If *state=uncataloged* and the data set is not found, no action taken, module completes successfully with *changed=False*. - If \ :emphasis:`state=uncataloged`\ and the data set is found, the data set is uncataloged, module completes successfully with \ :emphasis:`changed=True`\ . + If *state=uncataloged* and the data set is found, the data set is uncataloged, module completes successfully with *changed=True*. | **required**: False @@ -439,22 +366,22 @@ batch type - The data set type to be used when creating a data set. (e.g \ :literal:`pdse`\ ) + The data set type to be used when creating a data set. (e.g ``pdse``) - \ :literal:`member`\ expects to be used with an existing partitioned data set. + ``member`` expects to be used with an existing partitioned data set. Choices are case-sensitive. | **required**: False | **type**: str | **default**: pds - | **choices**: ksds, esds, rrds, lds, seq, pds, pdse, library, basic, large, member, hfs, zfs, gdg + | **choices**: ksds, esds, rrds, lds, seq, pds, pdse, library, basic, large, member, hfs, zfs space_primary The amount of primary space to allocate for the dataset. - The unit of space used is set using \ :emphasis:`space\_type`\ . + The unit of space used is set using *space_type*. | **required**: False | **type**: int @@ -464,7 +391,7 @@ batch space_secondary The amount of secondary space to allocate for the dataset. - The unit of space used is set using \ :emphasis:`space\_type`\ . + The unit of space used is set using *space_type*. | **required**: False | **type**: int @@ -474,7 +401,7 @@ batch space_type The unit of measurement to use when defining primary and secondary space. - Valid units of size are \ :literal:`k`\ , \ :literal:`m`\ , \ :literal:`g`\ , \ :literal:`cyl`\ , and \ :literal:`trk`\ . + Valid units of size are ``k``, ``m``, ``g``, ``cyl``, and ``trk``. | **required**: False | **type**: str @@ -483,11 +410,11 @@ batch record_format - The format of the data set. (e.g \ :literal:`FB`\ ) + The format of the data set. (e.g ``FB``) Choices are case-sensitive. - When \ :emphasis:`type=ksds`\ , \ :emphasis:`type=esds`\ , \ :emphasis:`type=rrds`\ , \ :emphasis:`type=lds`\ or \ :emphasis:`type=zfs`\ then \ :emphasis:`record\_format=None`\ , these types do not have a default \ :emphasis:`record\_format`\ . + When *type=ksds*, *type=esds*, *type=rrds*, *type=lds* or *type=zfs* then *record_format=None*, these types do not have a default *record_format*. | **required**: False | **type**: str @@ -562,9 +489,9 @@ batch key_offset The key offset to use when creating a KSDS data set. - \ :emphasis:`key\_offset`\ is required when \ :emphasis:`type=ksds`\ . + *key_offset* is required when *type=ksds*. - \ :emphasis:`key\_offset`\ should only be provided when \ :emphasis:`type=ksds`\ + *key_offset* should only be provided when *type=ksds* | **required**: False | **type**: int @@ -573,96 +500,28 @@ batch key_length The key length to use when creating a KSDS data set. - \ :emphasis:`key\_length`\ is required when \ :emphasis:`type=ksds`\ . - - \ :emphasis:`key\_length`\ should only be provided when \ :emphasis:`type=ksds`\ - - | **required**: False - | **type**: int - - - empty - Sets the \ :emphasis:`empty`\ attribute for Generation Data Groups. - - If false, removes only the oldest GDS entry when a new GDS is created that causes GDG limit to be exceeded. - - If true, removes all GDS entries from a GDG base when a new GDS is created that causes the GDG limit to be exceeded. - - Default is false. - - | **required**: False - | **type**: bool - - - extended - Sets the \ :emphasis:`extended`\ attribute for Generation Data Groups. - - If false, allow up to 255 generation data sets (GDSs) to be associated with the GDG. - - If true, allow up to 999 generation data sets (GDS) to be associated with the GDG. - - Default is false. - - | **required**: False - | **type**: bool - + *key_length* is required when *type=ksds*. - fifo - Sets the \ :emphasis:`fifo`\ attribute for Generation Data Groups. - - If false, the order is the newest GDS defined to the oldest GDS. This is the default value. - - If true, the order is the oldest GDS defined to the newest GDS. - - Default is false. - - | **required**: False - | **type**: bool - - - limit - Sets the \ :emphasis:`limit`\ attribute for Generation Data Groups. - - Specifies the maximum number, from 1 to 255(up to 999 if extended), of GDS that can be associated with the GDG being defined. - - \ :emphasis:`limit`\ is required when \ :emphasis:`type=gdg`\ . + *key_length* should only be provided when *type=ksds* | **required**: False | **type**: int - purge - Sets the \ :emphasis:`purge`\ attribute for Generation Data Groups. - - Specifies whether to override expiration dates when a generation data set (GDS) is rolled off and the \ :literal:`scratch`\ option is set. - - | **required**: False - | **type**: bool - - - scratch - Sets the \ :emphasis:`scratch`\ attribute for Generation Data Groups. - - Specifies what action is to be taken for a generation data set located on disk volumes when the data set is uncataloged from the GDG base as a result of EMPTY/NOEMPTY processing. - - | **required**: False - | **type**: bool - - volumes - If cataloging a data set, \ :emphasis:`volumes`\ specifies the name of the volume(s) where the data set is located. + If cataloging a data set, *volumes* specifies the name of the volume(s) where the data set is located. - If creating a data set, \ :emphasis:`volumes`\ specifies the volume(s) where the data set should be created. + If creating a data set, *volumes* specifies the volume(s) where the data set should be created. - If \ :emphasis:`volumes`\ is provided when \ :emphasis:`state=present`\ , and the data set is not found in the catalog, \ `zos\_data\_set <./zos_data_set.html>`__\ will check the volume table of contents to see if the data set exists. If the data set does exist, it will be cataloged. + If *volumes* is provided when *state=present*, and the data set is not found in the catalog, `zos_data_set <./zos_data_set.html>`_ will check the volume table of contents to see if the data set exists. If the data set does exist, it will be cataloged. - If \ :emphasis:`volumes`\ is provided when \ :emphasis:`state=absent`\ and the data set is not found in the catalog, \ `zos\_data\_set <./zos_data_set.html>`__\ will check the volume table of contents to see if the data set exists. If the data set does exist, it will be cataloged and promptly removed from the system. + If *volumes* is provided when *state=absent* and the data set is not found in the catalog, `zos_data_set <./zos_data_set.html>`_ will check the volume table of contents to see if the data set exists. If the data set does exist, it will be cataloged and promptly removed from the system. - \ :emphasis:`volumes`\ is required when \ :emphasis:`state=cataloged`\ . + *volumes* is required when *state=cataloged*. Accepts a string when using a single volume and a list of strings when using multiple. @@ -671,12 +530,12 @@ batch replace - When \ :emphasis:`replace=True`\ , and \ :emphasis:`state=present`\ , existing data set matching \ :emphasis:`name`\ will be replaced. + When *replace=True*, and *state=present*, existing data set matching *name* will be replaced. Replacement is performed by deleting the existing data set and creating a new data set with the same name and desired attributes. Since the existing data set will be deleted prior to creating the new data set, no data set will exist if creation of the new data set fails. - If \ :emphasis:`replace=True`\ , all data in the original data set will be lost. + If *replace=True*, all data in the original data set will be lost. | **required**: False | **type**: bool @@ -688,9 +547,9 @@ batch This is helpful when a data set is being used in a long running process such as a started task and you are wanting to delete a member. - The \ :emphasis:`force=True`\ option enables sharing of data sets through the disposition \ :emphasis:`DISP=SHR`\ . + The *force=True* option enables sharing of data sets through the disposition *DISP=SHR*. - The \ :emphasis:`force=True`\ only applies to data set members when \ :emphasis:`state=absent`\ and \ :emphasis:`type=member`\ . + The *force=True* only applies to data set members when *state=absent* and *type=member*. | **required**: False | **type**: bool diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_encode.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_encode.rst.txt index 51bcca12..2134b336 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_encode.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_encode.rst.txt @@ -37,7 +37,7 @@ encoding from - The character set of the source \ :emphasis:`src`\ . + The character set of the source *src*. | **required**: False | **type**: str @@ -45,7 +45,7 @@ encoding to - The destination \ :emphasis:`dest`\ character set for the output to be written as. + The destination *dest* character set for the output to be written as. | **required**: False | **type**: str @@ -54,13 +54,11 @@ 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, a generation data set (GDS) 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, 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. + If *src* is a USS directory, all files will be encoded. | **required**: True | **type**: str @@ -69,24 +67,22 @@ src 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, a generation data set (GDS) or KSDS (VSAM data set). + The destination *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). - 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 the length of the PDSE member name used in *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`\ . + If *dest* is not specified, the *src* will be used as the destination and will overwrite the *src* with the character set in the option *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 backup - Creates a backup file or backup data set for \ :emphasis:`dest`\ , including the timestamp information to ensure that you retrieve the original file. + Creates a backup file or backup data set for *dest*, including the timestamp information to ensure that you retrieve the original file. - \ :emphasis:`backup\_name`\ can be used to specify a backup file name if \ :emphasis:`backup=true`\ . + *backup_name* can be used to specify a backup file name if *backup=true*. | **required**: False | **type**: bool @@ -96,15 +92,13 @@ backup backup_name Specify the USS file name or data set name for the dest backup. - If dest is a USS file or path, \ :emphasis:`backup\_name`\ must be a file or path name, and the USS path or file must be an absolute pathname. - - If dest is an MVS data set, the \ :emphasis:`backup\_name`\ must be an MVS data set name. + If dest is a USS file or path, *backup_name* must be a file or path name, and the USS path or file must be an absolute pathname. - If \ :emphasis:`backup\_name`\ is not provided, the default backup name will be used. The default backup name for a USS file or path will be the destination file or path name appended with a timestamp, e.g. /path/file\_name.2020-04-23-08-32-29-bak.tar. If dest is an MVS data set, the default backup name will be a random name generated by IBM Z Open Automation Utilities. + If dest is an MVS data set, the *backup_name* must be an MVS data set name. - \ :literal:`backup\_name`\ will be returned on either success or failure of module execution such that data can be retrieved. + If *backup_name* is not provided, the default backup name will be used. The default backup name for a USS file or path will be the destination file or path name appended with a timestamp, e.g. /path/file_name.2020-04-23-08-32-29-bak.tar. If dest is an MVS data set, the default backup name will be a random name generated by IBM Z Open Automation Utilities. - If \ :emphasis:`backup\_name`\ is a generation data set (GDS), it must be a relative positive name (for example, \ :literal:`HLQ.USER.GDG(+1)`\ ). + ``backup_name`` will be returned on either success or failure of module execution such that data can be retrieved. | **required**: False | **type**: str @@ -113,7 +107,7 @@ backup_name backup_compress Determines if backups to USS files or paths should be compressed. - \ :emphasis:`backup\_compress`\ is only used when \ :emphasis:`backup=true`\ . + *backup_compress* is only used when *backup=true*. | **required**: False | **type**: bool @@ -123,7 +117,7 @@ backup_compress tmp_hlq Override the default high level qualifier (HLQ) for temporary and backup datasets. - The default HLQ is the Ansible user used to execute the module and if that is not available, then the value \ :literal:`TMPHLQ`\ is used. + The default HLQ is the Ansible user used to execute the module and if that is not available, then the value ``TMPHLQ`` is used. | **required**: False | **type**: str @@ -259,24 +253,6 @@ 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) - @@ -288,7 +264,7 @@ Notes All data sets are always assumed to be cataloged. If an uncataloged data set needs to be encoded, it should be cataloged first. - For supported character sets used to encode data, refer to the \ `documentation `__\ . + For supported character sets used to encode data, refer to the `documentation `_. @@ -301,7 +277,7 @@ Return Values src - The location of the input characters identified in option \ :emphasis:`src`\ . + The location of the input characters identified in option *src*. | **returned**: always | **type**: str diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_fetch.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_fetch.rst.txt index 23d58c86..87a50a65 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_fetch.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_fetch.rst.txt @@ -16,13 +16,11 @@ zos_fetch -- Fetch data from z/OS Synopsis -------- -- This module fetches a UNIX System Services (USS) file, PS (sequential data set), PDS, PDSE, member of a PDS or PDSE, generation data set (GDS), generation data group (GDG), or KSDS (VSAM data set) from a remote z/OS system. +- This module fetches a UNIX System Services (USS) file, PS (sequential data set), PDS, PDSE, member of a PDS or PDSE, or KSDS (VSAM data set) from a remote z/OS system. - When fetching a sequential data set, the destination file name will be the same as the data set name. - When fetching a PDS or PDSE, the destination will be a directory with the same name as the PDS or PDSE. - When fetching a PDS/PDSE member, destination will be a file. -- Files that already exist at \ :literal:`dest`\ will be overwritten if they are different than \ :literal:`src`\ . -- When fetching a GDS, the relative name will be resolved to its absolute one. -- When fetching a generation data group, the destination will be a directory with the same name as the GDG. +- Files that already exist at ``dest`` will be overwritten if they are different than ``src``. @@ -33,7 +31,7 @@ Parameters src - Name of a UNIX System Services (USS) file, PS (sequential data set), PDS, PDSE, member of a PDS, PDSE, GDS, GDG or KSDS (VSAM data set). + Name of a UNIX System Services (USS) file, PS (sequential data set), PDS, PDSE, member of a PDS, PDSE or KSDS (VSAM data set). USS file paths should be absolute paths. @@ -98,7 +96,7 @@ encoding from - The character set of the source \ :emphasis:`src`\ . + The character set of the source *src*. Supported character sets rely on the charset conversion utility (iconv) version; the most common character sets are supported. @@ -107,7 +105,7 @@ encoding to - The destination \ :emphasis:`dest`\ character set for the output to be written as. + The destination *dest* character set for the output to be written as. Supported character sets rely on the charset conversion utility (iconv) version; the most common character sets are supported. @@ -119,16 +117,16 @@ encoding tmp_hlq Override the default high level qualifier (HLQ) for temporary and backup datasets. - The default HLQ is the Ansible user used to execute the module and if that is not available, then the value \ :literal:`TMPHLQ`\ is used. + The default HLQ is the Ansible user used to execute the module and if that is not available, then the value ``TMPHLQ`` is used. | **required**: False | **type**: str ignore_sftp_stderr - During data transfer through sftp, the module fails if the sftp command directs any content to stderr. The user is able to override this behavior by setting this parameter to \ :literal:`true`\ . By doing so, the module would essentially ignore the stderr stream produced by sftp and continue execution. + During data transfer through sftp, the module fails if the sftp command directs any content to stderr. The user is able to override this behavior by setting this parameter to ``true``. By doing so, the module would essentially ignore the stderr stream produced by sftp and continue execution. - When Ansible verbosity is set to greater than 3, either through the command line interface (CLI) using \ :strong:`-vvvv`\ or through environment variables such as \ :strong:`verbosity = 4`\ , then this parameter will automatically be set to \ :literal:`true`\ . + When Ansible verbosity is set to greater than 3, either through the command line interface (CLI) using **-vvvv** or through environment variables such as **verbosity = 4**, then this parameter will automatically be set to ``true``. | **required**: False | **type**: bool @@ -189,24 +187,6 @@ Examples to: ISO8859-1 flat: true - - name: Fetch the current generation data set from a GDG - zos_fetch: - src: USERHLQ.DATA.SET(0) - dest: /tmp/ - flat: true - - - name: Fetch a previous generation data set from a GDG - zos_fetch: - src: USERHLQ.DATA.SET(-3) - dest: /tmp/ - flat: true - - - name: Fetch a generation data group - zos_fetch: - src: USERHLQ.TEST.GDG - dest: /tmp/ - flat: true - @@ -216,13 +196,13 @@ Notes .. note:: When fetching PDSE and VSAM data sets, temporary storage will be used on the remote z/OS system. After the PDSE or VSAM data set is successfully transferred, the temporary storage will be deleted. The size of the temporary storage will correspond to the size of PDSE or VSAM data set being fetched. If module execution fails, the temporary storage will be deleted. - To ensure optimal performance, data integrity checks for PDS, PDSE, and members of PDS or PDSE are done through the transfer methods used. As a result, the module response will not include the \ :literal:`checksum`\ parameter. + To ensure optimal performance, data integrity checks for PDS, PDSE, and members of PDS or PDSE are done through the transfer methods used. As a result, the module response will not include the ``checksum`` parameter. All data sets are always assumed to be cataloged. If an uncataloged data set needs to be fetched, it should be cataloged first. Fetching HFS or ZFS type data sets is currently not supported. - For supported character sets used to encode data, refer to the \ `documentation `__\ . + For supported character sets used to encode data, refer to the `documentation `_. 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. @@ -283,7 +263,7 @@ data_set_type | **sample**: PDSE note - Notice of module failure when \ :literal:`fail\_on\_missing`\ is false. + Notice of module failure when ``fail_on_missing`` is false. | **returned**: failure and fail_on_missing=false | **type**: str diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_find.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_find.rst.txt index 83082b5c..f195b2c2 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_find.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_find.rst.txt @@ -18,7 +18,7 @@ Synopsis -------- - Return a list of data sets based on specific criteria. - Multiple criteria can be added (AND'd) together. -- The \ :literal:`zos\_find`\ module can only find MVS data sets. Use the \ `find `__\ module to find USS files. +- The ``zos_find`` module can only find MVS data sets. Use the `find `_ module to find USS files. @@ -44,9 +44,9 @@ age age_stamp Choose the age property against which to compare age. - \ :literal:`creation\_date`\ is the date the data set was created and \ :literal:`ref\_date`\ is the date the data set was last referenced. + ``creation_date`` is the date the data set was created and ``ref_date`` is the date the data set was last referenced. - \ :literal:`ref\_date`\ is only applicable to sequential and partitioned data sets. + ``ref_date`` is only applicable to sequential and partitioned data sets. | **required**: False | **type**: str @@ -80,7 +80,7 @@ patterns This parameter expects a list, which can be either comma separated or YAML. - If \ :literal:`pds\_patterns`\ is provided, \ :literal:`patterns`\ must be member patterns. + If ``pds_patterns`` is provided, ``patterns`` must be member patterns. When searching for members within a PDS/PDSE, pattern can be a regular expression. @@ -107,7 +107,7 @@ pds_patterns Required when searching for data set members. - Valid only for \ :literal:`nonvsam`\ resource types. Otherwise ignored. + Valid only for ``nonvsam`` resource types. Otherwise ignored. | **required**: False | **type**: list @@ -117,9 +117,9 @@ pds_patterns resource_type The type of resource to search. - \ :literal:`nonvsam`\ refers to one of SEQ, LIBRARY (PDSE), PDS, LARGE, BASIC, EXTREQ, or EXTPREF. + ``nonvsam`` refers to one of SEQ, LIBRARY (PDSE), PDS, LARGE, BASIC, EXTREQ, or EXTPREF. - \ :literal:`cluster`\ refers to a VSAM cluster. The \ :literal:`data`\ and \ :literal:`index`\ are the data and index components of a VSAM cluster. + ``cluster`` refers to a VSAM cluster. The ``data`` and ``index`` are the data and index components of a VSAM cluster. | **required**: False | **type**: str @@ -192,11 +192,11 @@ Notes ----- .. note:: - Only cataloged data sets will be searched. If an uncataloged data set needs to be searched, it should be cataloged first. The \ `zos\_data\_set <./zos_data_set.html>`__\ module can be used to catalog uncataloged data sets. + Only cataloged data sets will be searched. If an uncataloged data set needs to be searched, it should be cataloged first. The `zos_data_set <./zos_data_set.html>`_ module can be used to catalog uncataloged data sets. - The \ `zos\_find <./zos_find.html>`__\ module currently does not support wildcards for high level qualifiers. For example, \ :literal:`SOME.\*.DATA.SET`\ is a valid pattern, but \ :literal:`\*.DATA.SET`\ is not. + The `zos_find <./zos_find.html>`_ module currently does not support wildcards for high level qualifiers. For example, ``SOME.*.DATA.SET`` is a valid pattern, but ``*.DATA.SET`` is not. - If a data set pattern is specified as \ :literal:`USER.\*`\ , the matching data sets will have two name segments such as \ :literal:`USER.ABC`\ , \ :literal:`USER.XYZ`\ etc. If a wildcard is specified as \ :literal:`USER.\*.ABC`\ , the matching data sets will have three name segments such as \ :literal:`USER.XYZ.ABC`\ , \ :literal:`USER.TEST.ABC`\ etc. + If a data set pattern is specified as ``USER.*``, the matching data sets will have two name segments such as ``USER.ABC``, ``USER.XYZ`` etc. If a wildcard is specified as ``USER.*.ABC``, the matching data sets will have three name segments such as ``USER.XYZ.ABC``, ``USER.TEST.ABC`` etc. The time taken to execute the module is proportional to the number of data sets present on the system and how large the data sets are. diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_gather_facts.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_gather_facts.rst.txt index 02a56fd2..0247ffd9 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_gather_facts.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_gather_facts.rst.txt @@ -17,8 +17,8 @@ zos_gather_facts -- Gather z/OS system facts. Synopsis -------- - Retrieve variables from target z/OS systems. -- Variables are added to the \ :emphasis:`ansible\_facts`\ dictionary, available to playbooks. -- Apply filters on the \ :emphasis:`gather\_subset`\ list to reduce the variables that are added to the \ :emphasis:`ansible\_facts`\ dictionary. +- Variables are added to the *ansible_facts* dictionary, available to playbooks. +- Apply filters on the *gather_subset* list to reduce the variables that are added to the *ansible_facts* dictionary. - Note, the module will fail fast if any unsupported options are provided. This is done to raise awareness of a failure in an automation setting. @@ -32,7 +32,7 @@ Parameters gather_subset If specified, it will collect facts that come under the specified subset (eg. ipl will return ipl facts). Specifying subsets is recommended to reduce time in gathering facts when the facts needed are in a specific subset. - The following subsets are available \ :literal:`ipl`\ , \ :literal:`cpu`\ , \ :literal:`sys`\ , and \ :literal:`iodf`\ . Depending on the version of ZOAU, additional subsets may be available. + The following subsets are available ``ipl``, ``cpu``, ``sys``, and ``iodf``. Depending on the version of ZOAU, additional subsets may be available. | **required**: False | **type**: list @@ -41,13 +41,13 @@ gather_subset filter - Filter out facts from the \ :emphasis:`ansible\_facts`\ dictionary. + Filter out facts from the *ansible_facts* dictionary. - Uses shell-style \ `fnmatch `__\ pattern matching to filter out the collected facts. + Uses shell-style `fnmatch `_ pattern matching to filter out the collected facts. - An empty list means 'no filter', same as providing '\*'. + An empty list means 'no filter', same as providing '*'. - Filtering is performed after the facts are gathered such that no compute is saved when filtering. Filtering only reduces the number of variables that are added to the \ :emphasis:`ansible\_facts`\ dictionary. To restrict the facts that are collected, refer to the \ :emphasis:`gather\_subset`\ parameter. + Filtering is performed after the facts are gathered such that no compute is saved when filtering. Filtering only reduces the number of variables that are added to the *ansible_facts* dictionary. To restrict the facts that are collected, refer to the *gather_subset* parameter. | **required**: False | **type**: list diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_job_output.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_job_output.rst.txt index 59e37aeb..efea6ea2 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_job_output.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_job_output.rst.txt @@ -18,9 +18,9 @@ Synopsis -------- - Display the z/OS job output for a given criteria (Job id/Job name/owner) with/without a data definition name as a filter. - At least provide a job id/job name/owner. -- The job id can be specific such as "STC02560", or one that uses a pattern such as "STC\*" or "\*". -- The job name can be specific such as "TCPIP", or one that uses a pattern such as "TCP\*" or "\*". -- The owner can be specific such as "IBMUSER", or one that uses a pattern like "\*". +- The job id can be specific such as "STC02560", or one that uses a pattern such as "STC*" or "*". +- The job name can be specific such as "TCPIP", or one that uses a pattern such as "TCP*" or "*". +- The owner can be specific such as "IBMUSER", or one that uses a pattern like "*". - If there is no ddname, or if ddname="?", output of all the ddnames under the given job will be displayed. @@ -32,21 +32,21 @@ Parameters job_id - The z/OS job ID of the job containing the spool file. (e.g "STC02560", "STC\*") + The z/OS job ID of the job containing the spool file. (e.g "STC02560", "STC*") | **required**: False | **type**: str job_name - The name of the batch job. (e.g "TCPIP", "C\*") + The name of the batch job. (e.g "TCPIP", "C*") | **required**: False | **type**: str owner - The owner who ran the job. (e.g "IBMUSER", "\*") + The owner who ran the job. (e.g "IBMUSER", "*") | **required**: False | **type**: str @@ -97,7 +97,7 @@ Return Values jobs - The output information for a list of jobs matching specified criteria. If no job status is found, this will return ret\_code dictionary with parameter msg\_txt = The job could not be found. + The output information for a list of jobs matching specified criteria. If no job status is found, this will return ret_code dictionary with parameter msg_txt = The job could not be found. | **returned**: success | **type**: list @@ -416,7 +416,7 @@ jobs | **sample**: CC 0000 msg_code - Return code extracted from the \`msg\` so that it can be evaluated. For example, ABEND(S0C4) would yield "S0C4". + Return code extracted from the `msg` so that it can be evaluated. For example, ABEND(S0C4) would yield "S0C4". | **type**: str | **sample**: S0C4 diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_job_query.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_job_query.rst.txt index e4da7134..ea320dfc 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_job_query.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_job_query.rst.txt @@ -17,8 +17,8 @@ zos_job_query -- Query job status Synopsis -------- - List z/OS job(s) and the current status of the job(s). -- Uses job\_name to filter the jobs by the job name. -- Uses job\_id to filter the jobs by the job identifier. +- Uses job_name to filter the jobs by the job name. +- Uses job_id to filter the jobs by the job identifier. - Uses owner to filter the jobs by the job owner. - Uses system to filter the jobs by system where the job is running (or ran) on. @@ -35,9 +35,9 @@ job_name A job name can be up to 8 characters long. - The \ :emphasis:`job\_name`\ can contain include multiple wildcards. + The *job_name* can contain include multiple wildcards. - The asterisk (\`\*\`) wildcard will match zero or more specified characters. + The asterisk (`*`) wildcard will match zero or more specified characters. | **required**: False | **type**: str @@ -56,13 +56,13 @@ owner job_id The job id that has been assigned to the job. - A job id must begin with \`STC\`, \`JOB\`, \`TSU\` and are followed by up to 5 digits. + A job id must begin with `STC`, `JOB`, `TSU` and are followed by up to 5 digits. - When a job id is greater than 99,999, the job id format will begin with \`S\`, \`J\`, \`T\` and are followed by 7 digits. + When a job id is greater than 99,999, the job id format will begin with `S`, `J`, `T` and are followed by 7 digits. - The \ :emphasis:`job\_id`\ can contain include multiple wildcards. + The *job_id* can contain include multiple wildcards. - The asterisk (\`\*\`) wildcard will match zero or more specified characters. + The asterisk (`*`) wildcard will match zero or more specified characters. | **required**: False | **type**: str @@ -122,7 +122,7 @@ changed | **type**: bool jobs - The output information for a list of jobs matching specified criteria. If no job status is found, this will return ret\_code dictionary with parameter msg\_txt = The job could not be found. + The output information for a list of jobs matching specified criteria. If no job status is found, this will return ret_code dictionary with parameter msg_txt = The job could not be found. | **returned**: success | **type**: list @@ -211,7 +211,7 @@ jobs | **sample**: CC 0000 msg_code - Return code extracted from the \`msg\` so that it can be evaluated. For example, ABEND(S0C4) would yield "S0C4". + Return code extracted from the `msg` so that it can be evaluated. For example, ABEND(S0C4) would yield "S0C4". | **type**: str | **sample**: S0C4 diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_job_submit.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_job_submit.rst.txt index bec95cb5..a6f55acf 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_job_submit.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_job_submit.rst.txt @@ -31,26 +31,24 @@ Parameters src The source file or data set containing the JCL to submit. - It could be a physical sequential data set, a partitioned data set qualified by a member or a path (e.g. \ :literal:`USER.TEST`\ , \ :literal:`USER.JCL(TEST)`\ ), or a generation data set from a generation data group (for example, \ :literal:`USER.TEST.GDG(-2)`\ ). + It could be a physical sequential data set, a partitioned data set qualified by a member or a path. (e.g "USER.TEST","USER.JCL(TEST)") - Or a USS file. (e.g \ :literal:`/u/tester/demo/sample.jcl`\ ) + Or a USS file. (e.g "/u/tester/demo/sample.jcl") - Or a LOCAL file in ansible control node. (e.g \ :literal:`/User/tester/ansible-playbook/sample.jcl`\ ) - - When using a generation data set, only already created generations are valid. If either the relative name is positive, or negative but not found, the module will fail. + Or a LOCAL file in ansible control node. (e.g "/User/tester/ansible-playbook/sample.jcl") | **required**: True | **type**: str location - The JCL location. Supported choices are \ :literal:`data\_set`\ , \ :literal:`uss`\ or \ :literal:`local`\ . + The JCL location. Supported choices are ``data_set``, ``uss`` or ``local``. - \ :literal:`data\_set`\ can be a PDS, PDSE, sequential data set, or a generation data set. + ``data_set`` can be a PDS, PDSE, or sequential data set. - \ :literal:`uss`\ means the JCL location is located in UNIX System Services (USS). + ``uss`` means the JCL location is located in UNIX System Services (USS). - \ :literal:`local`\ means locally to the Ansible control node. + ``local`` means locally to the ansible control node. | **required**: False | **type**: str @@ -59,9 +57,9 @@ location wait_time_s - Option \ :emphasis:`wait\_time\_s`\ is the total time that module \ `zos\_job\_submit <./zos_job_submit.html>`__\ will wait for a submitted job to complete. The time begins when the module is executed on the managed node. + Option *wait_time_s* is the total time that module `zos_job_submit <./zos_job_submit.html>`_ will wait for a submitted job to complete. The time begins when the module is executed on the managed node. - \ :emphasis:`wait\_time\_s`\ is measured in seconds and must be a value greater than 0 and less than 86400. + *wait_time_s* is measured in seconds and must be a value greater than 0 and less than 86400. | **required**: False | **type**: int @@ -88,9 +86,9 @@ return_output volume The volume serial (VOLSER) is where the data set resides. The option is required only when the data set is not cataloged on the system. - When configured, the \ `zos\_job\_submit <./zos_job_submit.html>`__\ will try to catalog the data set for the volume serial. If it is not able to, the module will fail. + When configured, the `zos_job_submit <./zos_job_submit.html>`_ will try to catalog the data set for the volume serial. If it is not able to, the module will fail. - Ignored for \ :emphasis:`location=uss`\ and \ :emphasis:`location=local`\ . + Ignored for *location=uss* and *location=local*. | **required**: False | **type**: str @@ -99,7 +97,7 @@ volume encoding Specifies which encoding the local JCL file should be converted from and to, before submitting the job. - This option is only supported for when \ :emphasis:`location=local`\ . + This option is only supported for when *location=local*. If this parameter is not provided, and the z/OS systems default encoding can not be identified, the JCL file will be converted from UTF-8 to IBM-1047 by default, otherwise the module will detect the z/OS system encoding. @@ -131,13 +129,13 @@ encoding use_template - Whether the module should treat \ :literal:`src`\ as a Jinja2 template and render it before continuing with the rest of the module. + Whether the module should treat ``src`` as a Jinja2 template and render it before continuing with the rest of the module. - Only valid when \ :literal:`src`\ is a local file or directory. + Only valid when ``src`` is a local file or directory. - All variables defined in inventory files, vars files and the playbook will be passed to the template engine, as well as \ `Ansible special variables `__\ , such as \ :literal:`playbook\_dir`\ , \ :literal:`ansible\_version`\ , etc. + All variables defined in inventory files, vars files and the playbook will be passed to the template engine, as well as `Ansible special variables `_, such as ``playbook_dir``, ``ansible_version``, etc. - If variables defined in different scopes share the same name, Ansible will apply variable precedence to them. You can see the complete precedence order \ `in Ansible's documentation `__\ + If variables defined in different scopes share the same name, Ansible will apply variable precedence to them. You can see the complete precedence order `in Ansible's documentation `_ | **required**: False | **type**: bool @@ -147,9 +145,9 @@ use_template template_parameters Options to set the way Jinja2 will process templates. - Jinja2 already sets defaults for the markers it uses, you can find more information at its \ `official documentation `__\ . + Jinja2 already sets defaults for the markers it uses, you can find more information at its `official documentation `_. - These options are ignored unless \ :literal:`use\_template`\ is true. + These options are ignored unless ``use_template`` is true. | **required**: False | **type**: dict @@ -228,7 +226,7 @@ template_parameters trim_blocks Whether Jinja2 should remove the first newline after a block is removed. - Setting this option to \ :literal:`False`\ will result in newlines being added to the rendered template. This could create invalid code when working with JCL templates or empty records in destination data sets. + Setting this option to ``False`` will result in newlines being added to the rendered template. This could create invalid code when working with JCL templates or empty records in destination data sets. | **required**: False | **type**: bool @@ -313,16 +311,6 @@ Examples location: data_set max_rc: 16 - - name: Submit JCL from the latest generation data set in a generation data group. - zos_job_submit: - src: HLQ.DATA.GDG(0) - location: data_set - - - name: Submit JCL from a previous generation data set in a generation data group. - zos_job_submit: - src: HLQ.DATA.GDG(-2) - location: data_set - @@ -330,9 +318,9 @@ Notes ----- .. note:: - For supported character sets used to encode data, refer to the \ `documentation `__\ . + For supported character sets used to encode data, refer to the `documentation `_. - 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 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. @@ -345,7 +333,7 @@ Return Values jobs - List of jobs output. If no job status is found, this will return an empty ret\_code with msg\_txt explanation. + List of jobs output. If no job status is found, this will return an empty ret_code with msg_txt explanation. | **returned**: success | **type**: list @@ -692,25 +680,25 @@ jobs msg Job status resulting from the job submission. - Job status \`ABEND\` indicates the job ended abnormally. + 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 `AC` indicates the job is active, often a started task or job taking long. - Job status \`CAB\` indicates a converter abend. + Job status `CAB` indicates a converter abend. - Job status \`CANCELED\` indicates the job was canceled. + Job status `CANCELED` indicates the job was canceled. - Job status \`CNV\` indicates a converter error. + Job status `CNV` indicates a converter error. - Job status \`FLU\` indicates the job was flushed. + Job status `FLU` indicates the job was flushed. - Job status \`JCLERR\` or \`JCL ERROR\` indicates the JCL has an error. + 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 `SEC` or `SEC ERROR` indicates the job as encountered a security error. - Job status \`SYS\` indicates a system failure. + Job status `SYS` indicates a system failure. - Job status \`?\` indicates status can not be determined. + Job status `?` indicates status can not be determined. Jobs where status can not be determined will result in None (NULL). diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_lineinfile.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_lineinfile.rst.txt index e8d0b0eb..4e416f97 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_lineinfile.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_lineinfile.rst.txt @@ -40,13 +40,13 @@ src regexp The regular expression to look for in every line of the USS file or data set. - For \ :literal:`state=present`\ , the pattern to replace if found. Only the last line found will be replaced. + For ``state=present``, the pattern to replace if found. Only the last line found will be replaced. - For \ :literal:`state=absent`\ , the pattern of the line(s) to remove. + For ``state=absent``, the pattern of the line(s) to remove. - If the regular expression is not matched, the line will be added to the USS file or data set in keeping with \ :literal:`insertbefore`\ or \ :literal:`insertafter`\ settings. + If the regular expression is not matched, the line will be added to the USS file or data set in keeping with ``insertbefore`` or ``insertafter`` settings. - When modifying a line the regexp should typically match both the initial state of the line as well as its state after replacement by \ :literal:`line`\ to ensure idempotence. + When modifying a line the regexp should typically match both the initial state of the line as well as its state after replacement by ``line`` to ensure idempotence. | **required**: False | **type**: str @@ -64,22 +64,22 @@ state line The line to insert/replace into the USS file or data set. - Required for \ :literal:`state=present`\ . + Required for ``state=present``. - If \ :literal:`backrefs`\ is set, may contain backreferences that will get expanded with the \ :literal:`regexp`\ capture groups if the regexp matches. + If ``backrefs`` is set, may contain backreferences that will get expanded with the ``regexp`` capture groups if the regexp matches. | **required**: False | **type**: str backrefs - Used with \ :literal:`state=present`\ . + Used with ``state=present``. - If set, \ :literal:`line`\ can contain backreferences (both positional and named) that will get populated if the \ :literal:`regexp`\ matches. + If set, ``line`` can contain backreferences (both positional and named) that will get populated if the ``regexp`` matches. - This parameter changes the operation of the module slightly; \ :literal:`insertbefore`\ and \ :literal:`insertafter`\ will be ignored, and if the \ :literal:`regexp`\ does not match anywhere in the USS file or data set, the USS file or data set will be left unchanged. + This parameter changes the operation of the module slightly; ``insertbefore`` and ``insertafter`` will be ignored, and if the ``regexp`` does not match anywhere in the USS file or data set, the USS file or data set will be left unchanged. - If the \ :literal:`regexp`\ does match, the last matching line will be replaced by the expanded line parameter. + If the ``regexp`` does match, the last matching line will be replaced by the expanded line parameter. | **required**: False | **type**: bool @@ -87,23 +87,23 @@ backrefs insertafter - Used with \ :literal:`state=present`\ . + Used with ``state=present``. If specified, the line will be inserted after the last match of specified regular expression. If the first match is required, use(firstmatch=yes). - A special value is available; \ :literal:`EOF`\ for inserting the line at the end of the USS file or data set. + A special value is available; ``EOF`` for inserting the line at the end of the USS file or data set. If the specified regular expression has no matches, EOF will be used instead. - If \ :literal:`insertbefore`\ is set, default value \ :literal:`EOF`\ will be ignored. + If ``insertbefore`` is set, default value ``EOF`` will be ignored. - If regular expressions are passed to both \ :literal:`regexp`\ and \ :literal:`insertafter`\ , \ :literal:`insertafter`\ is only honored if no match for \ :literal:`regexp`\ is found. + If regular expressions are passed to both ``regexp`` and ``insertafter``, ``insertafter`` is only honored if no match for ``regexp`` is found. - May not be used with \ :literal:`backrefs`\ or \ :literal:`insertbefore`\ . + May not be used with ``backrefs`` or ``insertbefore``. - Choices are EOF or '\*regex\*' + Choices are EOF or '*regex*' Default is EOF @@ -112,30 +112,30 @@ insertafter insertbefore - Used with \ :literal:`state=present`\ . + Used with ``state=present``. If specified, the line will be inserted before the last match of specified regular expression. - If the first match is required, use \ :literal:`firstmatch=yes`\ . + If the first match is required, use ``firstmatch=yes``. - A value is available; \ :literal:`BOF`\ for inserting the line at the beginning of the USS file or data set. + A value is available; ``BOF`` for inserting the line at the beginning of the USS file or data set. If the specified regular expression has no matches, the line will be inserted at the end of the USS file or data set. - If regular expressions are passed to both \ :literal:`regexp`\ and \ :literal:`insertbefore`\ , \ :literal:`insertbefore`\ is only honored if no match for \ :literal:`regexp`\ is found. + If regular expressions are passed to both ``regexp`` and ``insertbefore``, ``insertbefore`` is only honored if no match for ``regexp`` is found. - May not be used with \ :literal:`backrefs`\ or \ :literal:`insertafter`\ . + May not be used with ``backrefs`` or ``insertafter``. - Choices are BOF or '\*regex\*' + Choices are BOF or '*regex*' | **required**: False | **type**: str backup - Creates a backup file or backup data set for \ :emphasis:`src`\ , including the timestamp information to ensure that you retrieve the original file. + Creates a backup file or backup data set for *src*, including the timestamp information to ensure that you retrieve the original file. - \ :emphasis:`backup\_name`\ can be used to specify a backup file name if \ :emphasis:`backup=true`\ . + *backup_name* can be used to specify a backup file name if *backup=true*. The backup file name will be return on either success or failure of module execution such that data can be retrieved. @@ -147,11 +147,11 @@ backup backup_name Specify the USS file name or data set name for the destination backup. - If the source \ :emphasis:`src`\ is a USS file or path, the backup\_name must be a file or path name, and the USS file or path must be an absolute path name. + If the source *src* is a USS file or path, the backup_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. + If the source is an MVS data set, the backup_name must be an MVS data set name. - If the backup\_name is not provided, the default backup\_name will be used. If the source is a USS file or path, the name of the backup file will be the source file or path name appended with a timestamp, e.g. \ :literal:`/path/file\_name.2020-04-23-08-32-29-bak.tar`\ . + If the backup_name is not provided, the default backup_name will be used. If the source is a USS file or path, the name of the backup file will be the source file or path name appended with a timestamp, e.g. ``/path/file_name.2020-04-23-08-32-29-bak.tar``. If the source is an MVS data set, it will be a data set with a random name generated by calling the ZOAU API. The MVS backup data set recovery can be done by renaming it. @@ -162,16 +162,16 @@ backup_name tmp_hlq Override the default high level qualifier (HLQ) for temporary and backup datasets. - The default HLQ is the Ansible user used to execute the module and if that is not available, then the value \ :literal:`TMPHLQ`\ is used. + The default HLQ is the Ansible user used to execute the module and if that is not available, then the value ``TMPHLQ`` is used. | **required**: False | **type**: str firstmatch - Used with \ :literal:`insertafter`\ or \ :literal:`insertbefore`\ . + Used with ``insertafter`` or ``insertbefore``. - If set, \ :literal:`insertafter`\ and \ :literal:`insertbefore`\ will work with the first line that matches the given regular expression. + If set, ``insertafter`` and ``insertbefore`` will work with the first line that matches the given regular expression. | **required**: False | **type**: bool @@ -179,7 +179,7 @@ firstmatch encoding - The character set of the source \ :emphasis:`src`\ . \ `zos\_lineinfile <./zos_lineinfile.html>`__\ requires to be provided with correct encoding to read the content of USS file or data set. If this parameter is not provided, this module assumes that USS file or data set is encoded in IBM-1047. + The character set of the source *src*. `zos_lineinfile <./zos_lineinfile.html>`_ requires to be provided with correct encoding to read the content of USS file or data set. If this parameter is not provided, this module assumes that USS file or data set is encoded in IBM-1047. Supported character sets rely on the charset conversion utility (iconv) version; the most common character sets are supported. @@ -193,7 +193,7 @@ force This is helpful when a data set is being used in a long running process such as a started task and you are wanting to update or read. - The \ :literal:`force`\ option enables sharing of data sets through the disposition \ :emphasis:`DISP=SHR`\ . + The ``force`` option enables sharing of data sets through the disposition *DISP=SHR*. | **required**: False | **type**: bool @@ -259,7 +259,7 @@ Notes All data sets are always assumed to be cataloged. If an uncataloged data set needs to be encoded, it should be cataloged first. - For supported character sets used to encode data, refer to the \ `documentation `__\ . + For supported character sets used to encode data, refer to the `documentation `_. @@ -272,7 +272,7 @@ Return Values changed - Indicates if the source was modified. Value of 1 represents \`true\`, otherwise \`false\`. + Indicates if the source was modified. Value of 1 represents `true`, otherwise `false`. | **returned**: success | **type**: bool diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_mount.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_mount.rst.txt index 5bd28345..3b30be90 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_mount.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_mount.rst.txt @@ -16,9 +16,9 @@ zos_mount -- Mount a z/OS file system. Synopsis -------- -- The module \ `zos\_mount <./zos_mount.html>`__\ can manage mount operations for a z/OS UNIX System Services (USS) file system data set. -- The \ :emphasis:`src`\ data set must be unique and a Fully Qualified Name (FQN). -- The \ :emphasis:`path`\ will be created if needed. +- The module `zos_mount <./zos_mount.html>`_ can manage mount operations for a z/OS UNIX System Services (USS) file system data set. +- The *src* data set must be unique and a Fully Qualified Name (FQN). +- The *path* will be created if needed. @@ -31,7 +31,7 @@ Parameters path The absolute path name onto which the file system is to be mounted. - The \ :emphasis:`path`\ is case sensitive and must be less than or equal 1023 characters long. + The *path* is case sensitive and must be less than or equal 1023 characters long. | **required**: True | **type**: str @@ -40,9 +40,9 @@ path src The name of the file system to be added to the file system hierarchy. - The file system \ :emphasis:`src`\ must be a data set of type \ :emphasis:`fs\_type`\ . + The file system *src* must be a data set of type *fs_type*. - The file system \ :emphasis:`src`\ data set must be cataloged. + The file system *src* data set must be cataloged. | **required**: True | **type**: str @@ -53,7 +53,7 @@ fs_type The physical file systems data set format to perform the logical mount. - The \ :emphasis:`fs\_type`\ is required to be lowercase. + The *fs_type* is required to be lowercase. | **required**: True | **type**: str @@ -63,25 +63,25 @@ fs_type state The desired status of the described mount (choice). - If \ :emphasis:`state=mounted`\ and \ :emphasis:`src`\ are not in use, the module will add the file system entry to the parmlib member \ :emphasis:`persistent/data\_store`\ if not present. The \ :emphasis:`path`\ will be updated, the device will be mounted and the module will complete successfully with \ :emphasis:`changed=True`\ . + If *state=mounted* and *src* are not in use, the module will add the file system entry to the parmlib member *persistent/data_store* if not present. The *path* will be updated, the device will be mounted and the module will complete successfully with *changed=True*. - If \ :emphasis:`state=mounted`\ and \ :emphasis:`src`\ are in use, the module will add the file system entry to the parmlib member \ :emphasis:`persistent/data\_store`\ if not present. The \ :emphasis:`path`\ will not be updated, the device will not be mounted and the module will complete successfully with \ :emphasis:`changed=False`\ . + If *state=mounted* and *src* are in use, the module will add the file system entry to the parmlib member *persistent/data_store* if not present. The *path* will not be updated, the device will not be mounted and the module will complete successfully with *changed=False*. - If \ :emphasis:`state=unmounted`\ and \ :emphasis:`src`\ are in use, the module will \ :strong:`not`\ add the file system entry to the parmlib member \ :emphasis:`persistent/data\_store`\ . The device will be unmounted and the module will complete successfully with \ :emphasis:`changed=True`\ . + If *state=unmounted* and *src* are in use, the module will **not** add the file system entry to the parmlib member *persistent/data_store*. The device will be unmounted and the module will complete successfully with *changed=True*. - If \ :emphasis:`state=unmounted`\ and \ :emphasis:`src`\ are not in use, the module will \ :strong:`not`\ add the file system entry to parmlib member \ :emphasis:`persistent/data\_store`\ .The device will remain unchanged and the module will complete with \ :emphasis:`changed=False`\ . + If *state=unmounted* and *src* are not in use, the module will **not** add the file system entry to parmlib member *persistent/data_store*.The device will remain unchanged and the module will complete with *changed=False*. - If \ :emphasis:`state=present`\ , the module will add the file system entry to the provided parmlib member \ :emphasis:`persistent/data\_store`\ if not present. The module will complete successfully with \ :emphasis:`changed=True`\ . + If *state=present*, the module will add the file system entry to the provided parmlib member *persistent/data_store* if not present. The module will complete successfully with *changed=True*. - If \ :emphasis:`state=absent`\ , the module will remove the file system entry to the provided parmlib member \ :emphasis:`persistent/data\_store`\ if present. The module will complete successfully with \ :emphasis:`changed=True`\ . + If *state=absent*, the module will remove the file system entry to the provided parmlib member *persistent/data_store* if present. The module will complete successfully with *changed=True*. - If \ :emphasis:`state=remounted`\ , the module will \ :strong:`not`\ add the file system entry to parmlib member \ :emphasis:`persistent/data\_store`\ . The device will be unmounted and mounted, the module will complete successfully with \ :emphasis:`changed=True`\ . + If *state=remounted*, the module will **not** add the file system entry to parmlib member *persistent/data_store*. The device will be unmounted and mounted, the module will complete successfully with *changed=True*. | **required**: False @@ -91,7 +91,7 @@ state persistent - Add or remove mount command entries to provided \ :emphasis:`data\_store`\ + Add or remove mount command entries to provided *data_store* | **required**: False | **type**: dict @@ -105,9 +105,9 @@ persistent backup - Creates a backup file or backup data set for \ :emphasis:`data\_store`\ , including the timestamp information to ensure that you retrieve the original parameters defined in \ :emphasis:`data\_store`\ . + Creates a backup file or backup data set for *data_store*, including the timestamp information to ensure that you retrieve the original parameters defined in *data_store*. - \ :emphasis:`backup\_name`\ can be used to specify a backup file name if \ :emphasis:`backup=true`\ . + *backup_name* can be used to specify a backup file name if *backup=true*. The backup file name will be returned on either success or failure of module execution such that data can be retrieved. @@ -119,11 +119,11 @@ persistent backup_name Specify the USS file name or data set name for the destination backup. - If the source \ :emphasis:`data\_store`\ is a USS file or path, the \ :emphasis:`backup\_name`\ name can be relative or absolute for file or path name. + If the source *data_store* is a USS file or path, the *backup_name* name can be relative or absolute for file or path name. - If the source is an MVS data set, the backup\_name must be an MVS data set name. + If the source is an MVS data set, the backup_name must be an MVS data set name. - If the backup\_name is not provided, the default \ :emphasis:`backup\_name`\ will be used. If the source is a USS file or path, the name of the backup file will be the source file or path name appended with a timestamp. For example, \ :literal:`/path/file\_name.2020-04-23-08-32-29-bak.tar`\ . + If the backup_name is not provided, the default *backup_name* will be used. If the source is a USS file or path, the name of the backup file will be the source file or path name appended with a timestamp. For example, ``/path/file_name.2020-04-23-08-32-29-bak.tar``. If the source is an MVS data set, it will be a data set with a random name generated by calling the ZOAU API. The MVS backup data set recovery can be done by renaming it. @@ -132,9 +132,9 @@ persistent comment - If provided, this is used as a comment that surrounds the command in the \ :emphasis:`persistent/data\_store`\ + If provided, this is used as a comment that surrounds the command in the *persistent/data_store* - Comments are used to encapsulate the \ :emphasis:`persistent/data\_store`\ entry such that they can easily be understood and located. + Comments are used to encapsulate the *persistent/data_store* entry such that they can easily be understood and located. | **required**: False | **type**: list @@ -145,7 +145,7 @@ persistent unmount_opts Describes how the unmount will be performed. - For more on coded character set identifiers, review the IBM documentation topic \ :strong:`UNMOUNT - Remove a file system from the file hierarchy`\ . + For more on coded character set identifiers, review the IBM documentation topic **UNMOUNT - Remove a file system from the file hierarchy**. | **required**: False | **type**: str @@ -156,13 +156,13 @@ unmount_opts mount_opts Options available to the mount. - If \ :emphasis:`mount\_opts=ro`\ on a mounted/remount, mount is performed read-only. + If *mount_opts=ro* on a mounted/remount, mount is performed read-only. - If \ :emphasis:`mount\_opts=same`\ and (unmount\_opts=remount), mount is opened in the same mode as previously opened. + If *mount_opts=same* and (unmount_opts=remount), mount is opened in the same mode as previously opened. - If \ :emphasis:`mount\_opts=nowait`\ , mount is performed asynchronously. + If *mount_opts=nowait*, mount is performed asynchronously. - If \ :emphasis:`mount\_opts=nosecurity`\ , security checks are not enforced for files in this file system. + If *mount_opts=nosecurity*, security checks are not enforced for files in this file system. | **required**: False | **type**: str @@ -184,11 +184,11 @@ tag_untagged When the file system is unmounted, the tags are lost. - If \ :emphasis:`tag\_untagged=notext`\ none of the untagged files in the file system are automatically converted during file reading and writing. + If *tag_untagged=notext* none of the untagged files in the file system are automatically converted during file reading and writing. - If \ :emphasis:`tag\_untagged=text`\ each untagged file is implicitly marked as containing pure text data that can be converted. + If *tag_untagged=text* each untagged file is implicitly marked as containing pure text data that can be converted. - If this flag is used, use of tag\_ccsid is encouraged. + If this flag is used, use of tag_ccsid is encouraged. | **required**: False | **type**: str @@ -198,13 +198,13 @@ tag_untagged tag_ccsid Identifies the coded character set identifier (ccsid) to be implicitly set for the untagged file. - For more on coded character set identifiers, review the IBM documentation topic \ :strong:`Coded Character Sets`\ . + For more on coded character set identifiers, review the IBM documentation topic **Coded Character Sets**. Specified as a decimal value from 0 to 65535. However, when TEXT is specified, the value must be between 0 and 65535. The value is not checked as being valid and the corresponding code page is not checked as being installed. - Required when \ :emphasis:`tag\_untagged=TEXT`\ . + Required when *tag_untagged=TEXT*. | **required**: False | **type**: int @@ -214,10 +214,10 @@ allow_uid Specifies whether the SETUID and SETGID mode bits on an executable in this file system are considered. Also determines whether the APF extended attribute or the Program Control extended attribute is honored. - If \ :emphasis:`allow\_uid=True`\ the SETUID and SETGID mode bits are considered when a program in this file system is run. SETUID is the default. + If *allow_uid=True* the SETUID and SETGID mode bits are considered when a program in this file system is run. SETUID is the default. - If \ :emphasis:`allow\_uid=False`\ the SETUID and SETGID mode bits are ignored when a program in this file system is run. The program runs as though the SETUID and SETGID mode bits were not set. Also, if you specify the NOSETUID option on MOUNT, the APF extended attribute and the Program Control Bit values are ignored. + If *allow_uid=False* the SETUID and SETGID mode bits are ignored when a program in this file system is run. The program runs as though the SETUID and SETGID mode bits were not set. Also, if you specify the NOSETUID option on MOUNT, the APF extended attribute and the Program Control Bit values are ignored. | **required**: False @@ -226,10 +226,10 @@ allow_uid sysname - For systems participating in shared file system, \ :emphasis:`sysname`\ specifies the particular system on which a mount should be performed. This system will then become the owner of the file system mounted. This system must be IPLed with SYSPLEX(YES). + For systems participating in shared file system, *sysname* specifies the particular system on which a mount should be performed. This system will then become the owner of the file system mounted. This system must be IPLed with SYSPLEX(YES). - \ :emphasis:`sysname`\ is the name of a system participating in shared file system. The name must be 1-8 characters long; the valid characters are A-Z, 0-9, $, @, and #. + *sysname* is the name of a system participating in shared file system. The name must be 1-8 characters long; the valid characters are A-Z, 0-9, $, @, and #. | **required**: False @@ -240,13 +240,13 @@ automove These parameters apply only in a sysplex where systems are exploiting the shared file system capability. They specify what happens to the ownership of a file system when a shutdown, PFS termination, dead system takeover, or file system move occurs. The default setting is AUTOMOVE where the file system will be randomly moved to another system (no system list used). - \ :emphasis:`automove=automove`\ indicates that ownership of the file system can be automatically moved to another system participating in a shared file system. + *automove=automove* indicates that ownership of the file system can be automatically moved to another system participating in a shared file system. - \ :emphasis:`automove=noautomove`\ prevents movement of the file system's ownership in some situations. + *automove=noautomove* prevents movement of the file system's ownership in some situations. - \ :emphasis:`automove=unmount`\ allows the file system to be unmounted in some situations. + *automove=unmount* allows the file system to be unmounted in some situations. | **required**: False @@ -275,7 +275,7 @@ automove_list tmp_hlq Override the default high level qualifier (HLQ) for temporary and backup datasets. - The default HLQ is the Ansible user used to execute the module and if that is not available, then the value \ :literal:`TMPHLQ`\ is used. + The default HLQ is the Ansible user used to execute the module and if that is not available, then the value ``TMPHLQ`` is used. | **required**: False | **type**: str @@ -388,7 +388,7 @@ Notes If an uncataloged data set needs to be fetched, it should be cataloged first. - Uncataloged data sets can be cataloged using the \ `zos\_data\_set <./zos_data_set.html>`__\ module. + Uncataloged data sets can be cataloged using the `zos_data_set <./zos_data_set.html>`_ module. @@ -466,7 +466,7 @@ persistent | **sample**: SYS1.FILESYS(PRMAABAK) comment - The text that was used in markers around the \ :emphasis:`Persistent/data\_store`\ entry. + The text that was used in markers around the *Persistent/data_store* entry. | **returned**: always | **type**: list @@ -528,7 +528,7 @@ allow_uid true sysname - \ :emphasis:`sysname`\ specifies the particular system on which a mount should be performed. + *sysname* specifies the particular system on which a mount should be performed. | **returned**: if Non-None | **type**: str diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_mvs_raw.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_mvs_raw.rst.txt index f4841826..d98c9493 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_mvs_raw.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_mvs_raw.rst.txt @@ -45,9 +45,9 @@ parm auth Determines whether this program should run with authorized privileges. - If \ :emphasis:`auth=true`\ , the program runs as APF authorized. + If *auth=true*, the program runs as APF authorized. - If \ :emphasis:`auth=false`\ , the program runs as unauthorized. + If *auth=false*, the program runs as unauthorized. | **required**: False | **type**: bool @@ -57,7 +57,7 @@ auth verbose Determines if verbose output should be returned from the underlying utility used by this module. - When \ :emphasis:`verbose=true`\ verbose output is returned on module failure. + When *verbose=true* verbose output is returned on module failure. | **required**: False | **type**: bool @@ -67,19 +67,19 @@ verbose dds The input data source. - \ :emphasis:`dds`\ supports 6 types of sources + *dds* supports 6 types of sources - 1. \ :emphasis:`dd\_data\_set`\ for data set files. + 1. *dd_data_set* for data set files. - 2. \ :emphasis:`dd\_unix`\ for UNIX files. + 2. *dd_unix* for UNIX files. - 3. \ :emphasis:`dd\_input`\ for in-stream data set. + 3. *dd_input* for in-stream data set. - 4. \ :emphasis:`dd\_dummy`\ for no content input. + 4. *dd_dummy* for no content input. - 5. \ :emphasis:`dd\_concat`\ for a data set concatenation. + 5. *dd_concat* for a data set concatenation. - 6. \ :emphasis:`dds`\ supports any combination of source types. + 6. *dds* supports any combination of source types. | **required**: False | **type**: list @@ -89,7 +89,7 @@ dds dd_data_set Specify a data set. - \ :emphasis:`dd\_data\_set`\ can reference an existing data set or be used to define a new data set to be created during execution. + *dd_data_set* can reference an existing data set or be used to define a new data set to be created during execution. | **required**: False | **type**: dict @@ -110,7 +110,7 @@ dds type - The data set type. Only required when \ :emphasis:`disposition=new`\ . + The data set type. Only required when *disposition=new*. Maps to DSNTYPE on z/OS. @@ -120,7 +120,7 @@ dds disposition - \ :emphasis:`disposition`\ indicates the status of a data set. + *disposition* indicates the status of a data set. Defaults to shr. @@ -130,7 +130,7 @@ dds disposition_normal - \ :emphasis:`disposition\_normal`\ indicates what to do with the data set after a normal termination of the program. + *disposition_normal* indicates what to do with the data set after a normal termination of the program. | **required**: False | **type**: str @@ -138,7 +138,7 @@ dds disposition_abnormal - \ :emphasis:`disposition\_abnormal`\ indicates what to do with the data set after an abnormal termination of the program. + *disposition_abnormal* indicates what to do with the data set after an abnormal termination of the program. | **required**: False | **type**: str @@ -146,15 +146,15 @@ dds reuse - Determines if a data set should be reused if \ :emphasis:`disposition=new`\ and if a data set with a matching name already exists. + Determines if a data set should be reused if *disposition=new* and if a data set with a matching name already exists. - If \ :emphasis:`reuse=true`\ , \ :emphasis:`disposition`\ will be automatically switched to \ :literal:`SHR`\ . + If *reuse=true*, *disposition* will be automatically switched to ``SHR``. - If \ :emphasis:`reuse=false`\ , and a data set with a matching name already exists, allocation will fail. + If *reuse=false*, and a data set with a matching name already exists, allocation will fail. - Mutually exclusive with \ :emphasis:`replace`\ . + Mutually exclusive with *replace*. - \ :emphasis:`reuse`\ is only considered when \ :emphasis:`disposition=new`\ + *reuse* is only considered when *disposition=new* | **required**: False | **type**: bool @@ -162,17 +162,17 @@ dds replace - Determines if a data set should be replaced if \ :emphasis:`disposition=new`\ and a data set with a matching name already exists. + Determines if a data set should be replaced if *disposition=new* and a data set with a matching name already exists. - If \ :emphasis:`replace=true`\ , the original data set will be deleted, and a new data set created. + If *replace=true*, the original data set will be deleted, and a new data set created. - If \ :emphasis:`replace=false`\ , and a data set with a matching name already exists, allocation will fail. + If *replace=false*, and a data set with a matching name already exists, allocation will fail. - Mutually exclusive with \ :emphasis:`reuse`\ . + Mutually exclusive with *reuse*. - \ :emphasis:`replace`\ is only considered when \ :emphasis:`disposition=new`\ + *replace* is only considered when *disposition=new* - \ :emphasis:`replace`\ will result in loss of all data in the original data set unless \ :emphasis:`backup`\ is specified. + *replace* will result in loss of all data in the original data set unless *backup* is specified. | **required**: False | **type**: bool @@ -180,9 +180,9 @@ dds backup - Determines if a backup should be made of an existing data set when \ :emphasis:`disposition=new`\ , \ :emphasis:`replace=true`\ , and a data set with the desired name is found. + Determines if a backup should be made of an existing data set when *disposition=new*, *replace=true*, and a data set with the desired name is found. - \ :emphasis:`backup`\ is only used when \ :emphasis:`replace=true`\ . + *backup* is only used when *replace=true*. | **required**: False | **type**: bool @@ -190,7 +190,7 @@ dds space_type - The unit of measurement to use when allocating space for a new data set using \ :emphasis:`space\_primary`\ and \ :emphasis:`space\_secondary`\ . + The unit of measurement to use when allocating space for a new data set using *space_primary* and *space_secondary*. | **required**: False | **type**: str @@ -200,9 +200,9 @@ dds space_primary The primary amount of space to allocate for a new data set. - The value provided to \ :emphasis:`space\_type`\ is used as the unit of space for the allocation. + The value provided to *space_type* is used as the unit of space for the allocation. - Not applicable when \ :emphasis:`space\_type=blklgth`\ or \ :emphasis:`space\_type=reclgth`\ . + Not applicable when *space_type=blklgth* or *space_type=reclgth*. | **required**: False | **type**: int @@ -211,9 +211,9 @@ dds space_secondary When primary allocation of space is filled, secondary space will be allocated with the provided size as needed. - The value provided to \ :emphasis:`space\_type`\ is used as the unit of space for the allocation. + The value provided to *space_type* is used as the unit of space for the allocation. - Not applicable when \ :emphasis:`space\_type=blklgth`\ or \ :emphasis:`space\_type=reclgth`\ . + Not applicable when *space_type=blklgth* or *space_type=reclgth*. | **required**: False | **type**: int @@ -231,7 +231,7 @@ dds sms_management_class The desired management class for a new SMS-managed data set. - \ :emphasis:`sms\_management\_class`\ is ignored if specified for an existing data set. + *sms_management_class* is ignored if specified for an existing data set. All values must be between 1-8 alpha-numeric characters. @@ -242,7 +242,7 @@ dds sms_storage_class The desired storage class for a new SMS-managed data set. - \ :emphasis:`sms\_storage\_class`\ is ignored if specified for an existing data set. + *sms_storage_class* is ignored if specified for an existing data set. All values must be between 1-8 alpha-numeric characters. @@ -253,7 +253,7 @@ dds sms_data_class The desired data class for a new SMS-managed data set. - \ :emphasis:`sms\_data\_class`\ is ignored if specified for an existing data set. + *sms_data_class* is ignored if specified for an existing data set. All values must be between 1-8 alpha-numeric characters. @@ -264,7 +264,7 @@ dds block_size The maximum length of a block in bytes. - Default is dependent on \ :emphasis:`record\_format`\ + Default is dependent on *record_format* | **required**: False | **type**: int @@ -280,9 +280,9 @@ dds key_label The label for the encryption key used by the system to encrypt the data set. - \ :emphasis:`key\_label`\ is the public name of a protected encryption key in the ICSF key repository. + *key_label* is the public name of a protected encryption key in the ICSF key repository. - \ :emphasis:`key\_label`\ should only be provided when creating an extended format data set. + *key_label* should only be provided when creating an extended format data set. Maps to DSKEYLBL on z/OS. @@ -304,7 +304,7 @@ dds Key label must have a private key associated with it. - \ :emphasis:`label`\ can be a maximum of 64 characters. + *label* can be a maximum of 64 characters. Maps to KEYLAB1 on z/OS. @@ -313,9 +313,9 @@ dds encoding - How the label for the key encrypting key specified by \ :emphasis:`label`\ is encoded by the Encryption Key Manager. + How the label for the key encrypting key specified by *label* is encoded by the Encryption Key Manager. - \ :emphasis:`encoding`\ can either be set to \ :literal:`l`\ for label encoding, or \ :literal:`h`\ for hash encoding. + *encoding* can either be set to ``l`` for label encoding, or ``h`` for hash encoding. Maps to KEYCD1 on z/OS. @@ -339,7 +339,7 @@ dds Key label must have a private key associated with it. - \ :emphasis:`label`\ can be a maximum of 64 characters. + *label* can be a maximum of 64 characters. Maps to KEYLAB2 on z/OS. @@ -348,9 +348,9 @@ dds encoding - How the label for the key encrypting key specified by \ :emphasis:`label`\ is encoded by the Encryption Key Manager. + How the label for the key encrypting key specified by *label* is encoded by the Encryption Key Manager. - \ :emphasis:`encoding`\ can either be set to \ :literal:`l`\ for label encoding, or \ :literal:`h`\ for hash encoding. + *encoding* can either be set to ``l`` for label encoding, or ``h`` for hash encoding. Maps to KEYCD2 on z/OS. @@ -363,7 +363,7 @@ dds key_length The length of the keys used in a new data set. - If using SMS, setting \ :emphasis:`key\_length`\ overrides the key length defined in the SMS data class of the data set. + If using SMS, setting *key_length* overrides the key length defined in the SMS data class of the data set. Valid values are (0-255 non-vsam), (1-255 vsam). @@ -376,14 +376,14 @@ dds The first byte of a logical record is position 0. - Provide \ :emphasis:`key\_offset`\ only for VSAM key-sequenced data sets. + Provide *key_offset* only for VSAM key-sequenced data sets. | **required**: False | **type**: int record_length - The logical record length. (e.g \ :literal:`80`\ ). + The logical record length. (e.g ``80``). For variable data sets, the length must include the 4-byte prefix area. @@ -417,11 +417,11 @@ dds type The type of the content to be returned. - \ :literal:`text`\ means return content in encoding specified by \ :emphasis:`response\_encoding`\ . + ``text`` means return content in encoding specified by *response_encoding*. - \ :emphasis:`src\_encoding`\ and \ :emphasis:`response\_encoding`\ are only used when \ :emphasis:`type=text`\ . + *src_encoding* and *response_encoding* are only used when *type=text*. - \ :literal:`base64`\ means return content in binary mode. + ``base64`` means return content in binary mode. | **required**: True | **type**: str @@ -463,7 +463,7 @@ dds path The path to an existing UNIX file. - Or provide the path to an new created UNIX file when \ :emphasis:`status\_group=OCREAT`\ . + Or provide the path to an new created UNIX file when *status_group=OCREAT*. The provided path must be absolute. @@ -488,7 +488,7 @@ dds mode - The file access attributes when the UNIX file is created specified in \ :emphasis:`path`\ . + The file access attributes when the UNIX file is created specified in *path*. Specify the mode as an octal number similarly to chmod. @@ -499,47 +499,47 @@ dds status_group - The status for the UNIX file specified in \ :emphasis:`path`\ . + The status for the UNIX file specified in *path*. - If you do not specify a value for the \ :emphasis:`status\_group`\ parameter, the module assumes that the pathname exists, searches for it, and fails the module if the pathname does not exist. + If you do not specify a value for the *status_group* parameter, the module assumes that the pathname exists, searches for it, and fails the module if the pathname does not exist. Maps to PATHOPTS status group file options on z/OS. You can specify up to 6 choices. - \ :emphasis:`oappend`\ sets the file offset to the end of the file before each write, so that data is written at the end of the file. + *oappend* sets the file offset to the end of the file before each write, so that data is written at the end of the file. - \ :emphasis:`ocreat`\ specifies that if the file does not exist, the system is to create it. If a directory specified in the pathname does not exist, a new directory and a new file are not created. If the file already exists and \ :emphasis:`oexcl`\ was not specified, the system allows the program to use the existing file. If the file already exists and \ :emphasis:`oexcl`\ was specified, the system fails the allocation and the job step. + *ocreat* specifies that if the file does not exist, the system is to create it. If a directory specified in the pathname does not exist, a new directory and a new file are not created. If the file already exists and *oexcl* was not specified, the system allows the program to use the existing file. If the file already exists and *oexcl* was specified, the system fails the allocation and the job step. - \ :emphasis:`oexcl`\ specifies that if the file does not exist, the system is to create it. If the file already exists, the system fails the allocation and the job step. The system ignores \ :emphasis:`oexcl`\ if \ :emphasis:`ocreat`\ is not also specified. + *oexcl* specifies that if the file does not exist, the system is to create it. If the file already exists, the system fails the allocation and the job step. The system ignores *oexcl* if *ocreat* is not also specified. - \ :emphasis:`onoctty`\ specifies that if the PATH parameter identifies a terminal device, opening of the file does not make the terminal device the controlling terminal for the process. + *onoctty* specifies that if the PATH parameter identifies a terminal device, opening of the file does not make the terminal device the controlling terminal for the process. - \ :emphasis:`ononblock`\ specifies the following, depending on the type of file + *ononblock* specifies the following, depending on the type of file For a FIFO special file - 1. With \ :emphasis:`ononblock`\ specified and \ :emphasis:`ordonly`\ access, an open function for reading-only returns without delay. + 1. With *ononblock* specified and *ordonly* access, an open function for reading-only returns without delay. - 2. With \ :emphasis:`ononblock`\ not specified and \ :emphasis:`ordonly`\ access, an open function for reading-only blocks (waits) until a process opens the file for writing. + 2. With *ononblock* not specified and *ordonly* access, an open function for reading-only blocks (waits) until a process opens the file for writing. - 3. With \ :emphasis:`ononblock`\ specified and \ :emphasis:`owronly`\ access, an open function for writing-only returns an error if no process currently has the file open for reading. + 3. With *ononblock* specified and *owronly* access, an open function for writing-only returns an error if no process currently has the file open for reading. - 4. With \ :emphasis:`ononblock`\ not specified and \ :emphasis:`owronly`\ access, an open function for writing-only blocks (waits) until a process opens the file for reading. + 4. With *ononblock* not specified and *owronly* access, an open function for writing-only blocks (waits) until a process opens the file for reading. 5. For a character special file that supports nonblocking open - 6. If \ :emphasis:`ononblock`\ is specified, an open function returns without blocking (waiting) until the device is ready or available. Device response depends on the type of device. + 6. If *ononblock* is specified, an open function returns without blocking (waiting) until the device is ready or available. Device response depends on the type of device. - 7. If \ :emphasis:`ononblock`\ is not specified, an open function blocks (waits) until the device is ready or available. + 7. If *ononblock* is not specified, an open function blocks (waits) until the device is ready or available. - \ :emphasis:`ononblock`\ has no effect on other file types. + *ononblock* has no effect on other file types. - \ :emphasis:`osync`\ specifies that the system is to move data from buffer storage to permanent storage before returning control from a callable service that performs a write. + *osync* specifies that the system is to move data from buffer storage to permanent storage before returning control from a callable service that performs a write. - \ :emphasis:`otrunc`\ specifies that the system is to truncate the file length to zero if all the following are true: the file specified exists, the file is a regular file, and the file successfully opened with \ :emphasis:`ordwr`\ or \ :emphasis:`owronly`\ . + *otrunc* specifies that the system is to truncate the file length to zero if all the following are true: the file specified exists, the file is a regular file, and the file successfully opened with *ordwr* or *owronly*. - When \ :emphasis:`otrunc`\ is specified, the system does not change the mode and owner. \ :emphasis:`otrunc`\ has no effect on FIFO special files or character special files. + When *otrunc* is specified, the system does not change the mode and owner. *otrunc* has no effect on FIFO special files or character special files. | **required**: False | **type**: list @@ -548,7 +548,7 @@ dds access_group - The kind of access to request for the UNIX file specified in \ :emphasis:`path`\ . + The kind of access to request for the UNIX file specified in *path*. | **required**: False | **type**: str @@ -556,7 +556,7 @@ dds file_data_type - The type of data that is (or will be) stored in the file specified in \ :emphasis:`path`\ . + The type of data that is (or will be) stored in the file specified in *path*. Maps to FILEDATA on z/OS. @@ -569,7 +569,7 @@ dds block_size The block size, in bytes, for the UNIX file. - Default is dependent on \ :emphasis:`record\_format`\ + Default is dependent on *record_format* | **required**: False | **type**: int @@ -578,7 +578,7 @@ dds record_length The logical record length for the UNIX file. - \ :emphasis:`record\_length`\ is required in situations where the data will be processed as records and therefore, \ :emphasis:`record\_length`\ , \ :emphasis:`block\_size`\ and \ :emphasis:`record\_format`\ need to be supplied since a UNIX file would normally be treated as a stream of bytes. + *record_length* is required in situations where the data will be processed as records and therefore, *record_length*, *block_size* and *record_format* need to be supplied since a UNIX file would normally be treated as a stream of bytes. Maps to LRECL on z/OS. @@ -589,7 +589,7 @@ dds record_format The record format for the UNIX file. - \ :emphasis:`record\_format`\ is required in situations where the data will be processed as records and therefore, \ :emphasis:`record\_length`\ , \ :emphasis:`block\_size`\ and \ :emphasis:`record\_format`\ need to be supplied since a UNIX file would normally be treated as a stream of bytes. + *record_format* is required in situations where the data will be processed as records and therefore, *record_length*, *block_size* and *record_format* need to be supplied since a UNIX file would normally be treated as a stream of bytes. | **required**: False | **type**: str @@ -608,11 +608,11 @@ dds type The type of the content to be returned. - \ :literal:`text`\ means return content in encoding specified by \ :emphasis:`response\_encoding`\ . + ``text`` means return content in encoding specified by *response_encoding*. - \ :emphasis:`src\_encoding`\ and \ :emphasis:`response\_encoding`\ are only used when \ :emphasis:`type=text`\ . + *src_encoding* and *response_encoding* are only used when *type=text*. - \ :literal:`base64`\ means return content in binary mode. + ``base64`` means return content in binary mode. | **required**: True | **type**: str @@ -638,7 +638,7 @@ dds dd_input - \ :emphasis:`dd\_input`\ is used to specify an in-stream data set. + *dd_input* is used to specify an in-stream data set. Input will be saved to a temporary data set with a record length of 80. @@ -656,15 +656,15 @@ dds content The input contents for the DD. - \ :emphasis:`dd\_input`\ supports single or multiple lines of input. + *dd_input* supports single or multiple lines of input. Multi-line input can be provided as a multi-line string or a list of strings with 1 line per list item. If a list of strings is provided, newlines will be added to each of the lines when used as input. - If a multi-line string is provided, use the proper block scalar style. YAML supports both \ `literal `__\ and \ `folded `__\ scalars. It is recommended to use the literal style indicator "|" with a block indentation indicator, for example; \ :emphasis:`content: | 2`\ is a literal block style indicator with a 2 space indentation, the entire block will be indented and newlines preserved. The block indentation range is 1 - 9. While generally unnecessary, YAML does support block \ `chomping `__\ indicators "+" and "-" as well. + If a multi-line string is provided, use the proper block scalar style. YAML supports both `literal `_ and `folded `_ scalars. It is recommended to use the literal style indicator "|" with a block indentation indicator, for example; *content: | 2* is a literal block style indicator with a 2 space indentation, the entire block will be indented and newlines preserved. The block indentation range is 1 - 9. While generally unnecessary, YAML does support block `chomping `_ indicators "+" and "-" as well. - When using the \ :emphasis:`content`\ option for instream-data, the module will ensure that all lines contain a blank in columns 1 and 2 and add blanks when not present while retaining a maximum length of 80 columns for any line. This is true for all \ :emphasis:`content`\ types; string, list of strings and when using a YAML block indicator. + When using the *content* option for instream-data, the module will ensure that all lines contain a blank in columns 1 and 2 and add blanks when not present while retaining a maximum length of 80 columns for any line. This is true for all *content* types; string, list of strings and when using a YAML block indicator. | **required**: True | **type**: raw @@ -682,11 +682,11 @@ dds type The type of the content to be returned. - \ :literal:`text`\ means return content in encoding specified by \ :emphasis:`response\_encoding`\ . + ``text`` means return content in encoding specified by *response_encoding*. - \ :emphasis:`src\_encoding`\ and \ :emphasis:`response\_encoding`\ are only used when \ :emphasis:`type=text`\ . + *src_encoding* and *response_encoding* are only used when *type=text*. - \ :literal:`base64`\ means return content in binary mode. + ``base64`` means return content in binary mode. | **required**: True | **type**: str @@ -696,7 +696,7 @@ dds src_encoding The encoding of the data set on the z/OS system. - for \ :emphasis:`dd\_input`\ , \ :emphasis:`src\_encoding`\ should generally not need to be changed. + for *dd_input*, *src_encoding* should generally not need to be changed. | **required**: False | **type**: str @@ -714,7 +714,7 @@ dds dd_output - Use \ :emphasis:`dd\_output`\ to specify - Content sent to the DD should be returned to the user. + Use *dd_output* to specify - Content sent to the DD should be returned to the user. | **required**: False | **type**: dict @@ -739,11 +739,11 @@ dds type The type of the content to be returned. - \ :literal:`text`\ means return content in encoding specified by \ :emphasis:`response\_encoding`\ . + ``text`` means return content in encoding specified by *response_encoding*. - \ :emphasis:`src\_encoding`\ and \ :emphasis:`response\_encoding`\ are only used when \ :emphasis:`type=text`\ . + *src_encoding* and *response_encoding* are only used when *type=text*. - \ :literal:`base64`\ means return content in binary mode. + ``base64`` means return content in binary mode. | **required**: True | **type**: str @@ -753,7 +753,7 @@ dds src_encoding The encoding of the data set on the z/OS system. - for \ :emphasis:`dd\_input`\ , \ :emphasis:`src\_encoding`\ should generally not need to be changed. + for *dd_input*, *src_encoding* should generally not need to be changed. | **required**: False | **type**: str @@ -771,9 +771,9 @@ dds dd_dummy - Use \ :emphasis:`dd\_dummy`\ to specify - No device or external storage space is to be allocated to the data set. - No disposition processing is to be performed on the data set. + Use *dd_dummy* to specify - No device or external storage space is to be allocated to the data set. - No disposition processing is to be performed on the data set. - \ :emphasis:`dd\_dummy`\ accepts no content input. + *dd_dummy* accepts no content input. | **required**: False | **type**: dict @@ -788,7 +788,7 @@ dds dd_vio - \ :emphasis:`dd\_vio`\ is used to handle temporary data sets. + *dd_vio* is used to handle temporary data sets. VIO data sets reside in the paging space; but, to the problem program and the access method, the data sets appear to reside on a direct access storage device. @@ -807,7 +807,7 @@ dds dd_concat - \ :emphasis:`dd\_concat`\ is used to specify a data set concatenation. + *dd_concat* is used to specify a data set concatenation. | **required**: False | **type**: dict @@ -821,7 +821,7 @@ dds dds - A list of DD statements, which can contain any of the following types: \ :emphasis:`dd\_data\_set`\ , \ :emphasis:`dd\_unix`\ , and \ :emphasis:`dd\_input`\ . + A list of DD statements, which can contain any of the following types: *dd_data_set*, *dd_unix*, and *dd_input*. | **required**: False | **type**: list @@ -831,7 +831,7 @@ dds dd_data_set Specify a data set. - \ :emphasis:`dd\_data\_set`\ can reference an existing data set. The data set referenced with \ :literal:`data\_set\_name`\ must be allocated before the module \ `zos\_mvs\_raw <./zos_mvs_raw.html>`__\ is run, you can use \ `zos\_data\_set <./zos_data_set.html>`__\ to allocate a data set. + *dd_data_set* can reference an existing data set. The data set referenced with ``data_set_name`` must be allocated before the module `zos_mvs_raw <./zos_mvs_raw.html>`_ is run, you can use `zos_data_set <./zos_data_set.html>`_ to allocate a data set. | **required**: False | **type**: dict @@ -845,7 +845,7 @@ dds type - The data set type. Only required when \ :emphasis:`disposition=new`\ . + The data set type. Only required when *disposition=new*. Maps to DSNTYPE on z/OS. @@ -855,7 +855,7 @@ dds disposition - \ :emphasis:`disposition`\ indicates the status of a data set. + *disposition* indicates the status of a data set. Defaults to shr. @@ -865,7 +865,7 @@ dds disposition_normal - \ :emphasis:`disposition\_normal`\ indicates what to do with the data set after normal termination of the program. + *disposition_normal* indicates what to do with the data set after normal termination of the program. | **required**: False | **type**: str @@ -873,7 +873,7 @@ dds disposition_abnormal - \ :emphasis:`disposition\_abnormal`\ indicates what to do with the data set after abnormal termination of the program. + *disposition_abnormal* indicates what to do with the data set after abnormal termination of the program. | **required**: False | **type**: str @@ -881,15 +881,15 @@ dds reuse - Determines if data set should be reused if \ :emphasis:`disposition=new`\ and a data set with matching name already exists. + Determines if data set should be reused if *disposition=new* and a data set with matching name already exists. - If \ :emphasis:`reuse=true`\ , \ :emphasis:`disposition`\ will be automatically switched to \ :literal:`SHR`\ . + If *reuse=true*, *disposition* will be automatically switched to ``SHR``. - If \ :emphasis:`reuse=false`\ , and a data set with a matching name already exists, allocation will fail. + If *reuse=false*, and a data set with a matching name already exists, allocation will fail. - Mutually exclusive with \ :emphasis:`replace`\ . + Mutually exclusive with *replace*. - \ :emphasis:`reuse`\ is only considered when \ :emphasis:`disposition=new`\ + *reuse* is only considered when *disposition=new* | **required**: False | **type**: bool @@ -897,17 +897,17 @@ dds replace - Determines if data set should be replaced if \ :emphasis:`disposition=new`\ and a data set with matching name already exists. + Determines if data set should be replaced if *disposition=new* and a data set with matching name already exists. - If \ :emphasis:`replace=true`\ , the original data set will be deleted, and a new data set created. + If *replace=true*, the original data set will be deleted, and a new data set created. - If \ :emphasis:`replace=false`\ , and a data set with a matching name already exists, allocation will fail. + If *replace=false*, and a data set with a matching name already exists, allocation will fail. - Mutually exclusive with \ :emphasis:`reuse`\ . + Mutually exclusive with *reuse*. - \ :emphasis:`replace`\ is only considered when \ :emphasis:`disposition=new`\ + *replace* is only considered when *disposition=new* - \ :emphasis:`replace`\ will result in loss of all data in the original data set unless \ :emphasis:`backup`\ is specified. + *replace* will result in loss of all data in the original data set unless *backup* is specified. | **required**: False | **type**: bool @@ -915,9 +915,9 @@ dds backup - Determines if a backup should be made of existing data set when \ :emphasis:`disposition=new`\ , \ :emphasis:`replace=true`\ , and a data set with the desired name is found. + Determines if a backup should be made of existing data set when *disposition=new*, *replace=true*, and a data set with the desired name is found. - \ :emphasis:`backup`\ is only used when \ :emphasis:`replace=true`\ . + *backup* is only used when *replace=true*. | **required**: False | **type**: bool @@ -925,7 +925,7 @@ dds space_type - The unit of measurement to use when allocating space for a new data set using \ :emphasis:`space\_primary`\ and \ :emphasis:`space\_secondary`\ . + The unit of measurement to use when allocating space for a new data set using *space_primary* and *space_secondary*. | **required**: False | **type**: str @@ -935,9 +935,9 @@ dds space_primary The primary amount of space to allocate for a new data set. - The value provided to \ :emphasis:`space\_type`\ is used as the unit of space for the allocation. + The value provided to *space_type* is used as the unit of space for the allocation. - Not applicable when \ :emphasis:`space\_type=blklgth`\ or \ :emphasis:`space\_type=reclgth`\ . + Not applicable when *space_type=blklgth* or *space_type=reclgth*. | **required**: False | **type**: int @@ -946,9 +946,9 @@ dds space_secondary When primary allocation of space is filled, secondary space will be allocated with the provided size as needed. - The value provided to \ :emphasis:`space\_type`\ is used as the unit of space for the allocation. + The value provided to *space_type* is used as the unit of space for the allocation. - Not applicable when \ :emphasis:`space\_type=blklgth`\ or \ :emphasis:`space\_type=reclgth`\ . + Not applicable when *space_type=blklgth* or *space_type=reclgth*. | **required**: False | **type**: int @@ -966,7 +966,7 @@ dds sms_management_class The desired management class for a new SMS-managed data set. - \ :emphasis:`sms\_management\_class`\ is ignored if specified for an existing data set. + *sms_management_class* is ignored if specified for an existing data set. All values must be between 1-8 alpha-numeric characters. @@ -977,7 +977,7 @@ dds sms_storage_class The desired storage class for a new SMS-managed data set. - \ :emphasis:`sms\_storage\_class`\ is ignored if specified for an existing data set. + *sms_storage_class* is ignored if specified for an existing data set. All values must be between 1-8 alpha-numeric characters. @@ -988,7 +988,7 @@ dds sms_data_class The desired data class for a new SMS-managed data set. - \ :emphasis:`sms\_data\_class`\ is ignored if specified for an existing data set. + *sms_data_class* is ignored if specified for an existing data set. All values must be between 1-8 alpha-numeric characters. @@ -999,7 +999,7 @@ dds block_size The maximum length of a block in bytes. - Default is dependent on \ :emphasis:`record\_format`\ + Default is dependent on *record_format* | **required**: False | **type**: int @@ -1015,9 +1015,9 @@ dds key_label The label for the encryption key used by the system to encrypt the data set. - \ :emphasis:`key\_label`\ is the public name of a protected encryption key in the ICSF key repository. + *key_label* is the public name of a protected encryption key in the ICSF key repository. - \ :emphasis:`key\_label`\ should only be provided when creating an extended format data set. + *key_label* should only be provided when creating an extended format data set. Maps to DSKEYLBL on z/OS. @@ -1039,7 +1039,7 @@ dds Key label must have a private key associated with it. - \ :emphasis:`label`\ can be a maximum of 64 characters. + *label* can be a maximum of 64 characters. Maps to KEYLAB1 on z/OS. @@ -1048,9 +1048,9 @@ dds encoding - How the label for the key encrypting key specified by \ :emphasis:`label`\ is encoded by the Encryption Key Manager. + How the label for the key encrypting key specified by *label* is encoded by the Encryption Key Manager. - \ :emphasis:`encoding`\ can either be set to \ :literal:`l`\ for label encoding, or \ :literal:`h`\ for hash encoding. + *encoding* can either be set to ``l`` for label encoding, or ``h`` for hash encoding. Maps to KEYCD1 on z/OS. @@ -1074,7 +1074,7 @@ dds Key label must have a private key associated with it. - \ :emphasis:`label`\ can be a maximum of 64 characters. + *label* can be a maximum of 64 characters. Maps to KEYLAB2 on z/OS. @@ -1083,9 +1083,9 @@ dds encoding - How the label for the key encrypting key specified by \ :emphasis:`label`\ is encoded by the Encryption Key Manager. + How the label for the key encrypting key specified by *label* is encoded by the Encryption Key Manager. - \ :emphasis:`encoding`\ can either be set to \ :literal:`l`\ for label encoding, or \ :literal:`h`\ for hash encoding. + *encoding* can either be set to ``l`` for label encoding, or ``h`` for hash encoding. Maps to KEYCD2 on z/OS. @@ -1098,7 +1098,7 @@ dds key_length The length of the keys used in a new data set. - If using SMS, setting \ :emphasis:`key\_length`\ overrides the key length defined in the SMS data class of the data set. + If using SMS, setting *key_length* overrides the key length defined in the SMS data class of the data set. Valid values are (0-255 non-vsam), (1-255 vsam). @@ -1111,14 +1111,14 @@ dds The first byte of a logical record is position 0. - Provide \ :emphasis:`key\_offset`\ only for VSAM key-sequenced data sets. + Provide *key_offset* only for VSAM key-sequenced data sets. | **required**: False | **type**: int record_length - The logical record length. (e.g \ :literal:`80`\ ). + The logical record length. (e.g ``80``). For variable data sets, the length must include the 4-byte prefix area. @@ -1152,11 +1152,11 @@ dds type The type of the content to be returned. - \ :literal:`text`\ means return content in encoding specified by \ :emphasis:`response\_encoding`\ . + ``text`` means return content in encoding specified by *response_encoding*. - \ :emphasis:`src\_encoding`\ and \ :emphasis:`response\_encoding`\ are only used when \ :emphasis:`type=text`\ . + *src_encoding* and *response_encoding* are only used when *type=text*. - \ :literal:`base64`\ means return content in binary mode. + ``base64`` means return content in binary mode. | **required**: True | **type**: str @@ -1191,7 +1191,7 @@ dds path The path to an existing UNIX file. - Or provide the path to an new created UNIX file when \ :emphasis:`status\_group=ocreat`\ . + Or provide the path to an new created UNIX file when *status_group=ocreat*. The provided path must be absolute. @@ -1216,7 +1216,7 @@ dds mode - The file access attributes when the UNIX file is created specified in \ :emphasis:`path`\ . + The file access attributes when the UNIX file is created specified in *path*. Specify the mode as an octal number similar to chmod. @@ -1227,47 +1227,47 @@ dds status_group - The status for the UNIX file specified in \ :emphasis:`path`\ . + The status for the UNIX file specified in *path*. - If you do not specify a value for the \ :emphasis:`status\_group`\ parameter the module assumes that the pathname exists, searches for it, and fails the module if the pathname does not exist. + If you do not specify a value for the *status_group* parameter the module assumes that the pathname exists, searches for it, and fails the module if the pathname does not exist. Maps to PATHOPTS status group file options on z/OS. You can specify up to 6 choices. - \ :emphasis:`oappend`\ sets the file offset to the end of the file before each write, so that data is written at the end of the file. + *oappend* sets the file offset to the end of the file before each write, so that data is written at the end of the file. - \ :emphasis:`ocreat`\ specifies that if the file does not exist, the system is to create it. If a directory specified in the pathname does not exist, one is not created, and the new file is not created. If the file already exists and \ :emphasis:`oexcl`\ was not specified, the system allows the program to use the existing file. If the file already exists and \ :emphasis:`oexcl`\ was specified, the system fails the allocation and the job step. + *ocreat* specifies that if the file does not exist, the system is to create it. If a directory specified in the pathname does not exist, one is not created, and the new file is not created. If the file already exists and *oexcl* was not specified, the system allows the program to use the existing file. If the file already exists and *oexcl* was specified, the system fails the allocation and the job step. - \ :emphasis:`oexcl`\ specifies that if the file does not exist, the system is to create it. If the file already exists, the system fails the allocation and the job step. The system ignores \ :emphasis:`oexcl`\ if \ :emphasis:`ocreat`\ is not also specified. + *oexcl* specifies that if the file does not exist, the system is to create it. If the file already exists, the system fails the allocation and the job step. The system ignores *oexcl* if *ocreat* is not also specified. - \ :emphasis:`onoctty`\ specifies that if the PATH parameter identifies a terminal device, opening of the file does not make the terminal device the controlling terminal for the process. + *onoctty* specifies that if the PATH parameter identifies a terminal device, opening of the file does not make the terminal device the controlling terminal for the process. - \ :emphasis:`ononblock`\ specifies the following, depending on the type of file + *ononblock* specifies the following, depending on the type of file For a FIFO special file - 1. With \ :emphasis:`ononblock`\ specified and \ :emphasis:`ordonly`\ access, an open function for reading-only returns without delay. + 1. With *ononblock* specified and *ordonly* access, an open function for reading-only returns without delay. - 2. With \ :emphasis:`ononblock`\ not specified and \ :emphasis:`ordonly`\ access, an open function for reading-only blocks (waits) until a process opens the file for writing. + 2. With *ononblock* not specified and *ordonly* access, an open function for reading-only blocks (waits) until a process opens the file for writing. - 3. With \ :emphasis:`ononblock`\ specified and \ :emphasis:`owronly`\ access, an open function for writing-only returns an error if no process currently has the file open for reading. + 3. With *ononblock* specified and *owronly* access, an open function for writing-only returns an error if no process currently has the file open for reading. - 4. With \ :emphasis:`ononblock`\ not specified and \ :emphasis:`owronly`\ access, an open function for writing-only blocks (waits) until a process opens the file for reading. + 4. With *ononblock* not specified and *owronly* access, an open function for writing-only blocks (waits) until a process opens the file for reading. 5. For a character special file that supports nonblocking open - 6. If \ :emphasis:`ononblock`\ is specified, an open function returns without blocking (waiting) until the device is ready or available. Device response depends on the type of device. + 6. If *ononblock* is specified, an open function returns without blocking (waiting) until the device is ready or available. Device response depends on the type of device. - 7. If \ :emphasis:`ononblock`\ is not specified, an open function blocks (waits) until the device is ready or available. + 7. If *ononblock* is not specified, an open function blocks (waits) until the device is ready or available. - \ :emphasis:`ononblock`\ has no effect on other file types. + *ononblock* has no effect on other file types. - \ :emphasis:`osync`\ specifies that the system is to move data from buffer storage to permanent storage before returning control from a callable service that performs a write. + *osync* specifies that the system is to move data from buffer storage to permanent storage before returning control from a callable service that performs a write. - \ :emphasis:`otrunc`\ specifies that the system is to truncate the file length to zero if all the following are true: the file specified exists, the file is a regular file, and the file successfully opened with \ :emphasis:`ordwr`\ or \ :emphasis:`owronly`\ . + *otrunc* specifies that the system is to truncate the file length to zero if all the following are true: the file specified exists, the file is a regular file, and the file successfully opened with *ordwr* or *owronly*. - When \ :emphasis:`otrunc`\ is specified, the system does not change the mode and owner. \ :emphasis:`otrunc`\ has no effect on FIFO special files or character special files. + When *otrunc* is specified, the system does not change the mode and owner. *otrunc* has no effect on FIFO special files or character special files. | **required**: False | **type**: list @@ -1276,7 +1276,7 @@ dds access_group - The kind of access to request for the UNIX file specified in \ :emphasis:`path`\ . + The kind of access to request for the UNIX file specified in *path*. | **required**: False | **type**: str @@ -1284,7 +1284,7 @@ dds file_data_type - The type of data that is (or will be) stored in the file specified in \ :emphasis:`path`\ . + The type of data that is (or will be) stored in the file specified in *path*. Maps to FILEDATA on z/OS. @@ -1297,7 +1297,7 @@ dds block_size The block size, in bytes, for the UNIX file. - Default is dependent on \ :emphasis:`record\_format`\ + Default is dependent on *record_format* | **required**: False | **type**: int @@ -1306,7 +1306,7 @@ dds record_length The logical record length for the UNIX file. - \ :emphasis:`record\_length`\ is required in situations where the data will be processed as records and therefore, \ :emphasis:`record\_length`\ , \ :emphasis:`block\_size`\ and \ :emphasis:`record\_format`\ need to be supplied since a UNIX file would normally be treated as a stream of bytes. + *record_length* is required in situations where the data will be processed as records and therefore, *record_length*, *block_size* and *record_format* need to be supplied since a UNIX file would normally be treated as a stream of bytes. Maps to LRECL on z/OS. @@ -1317,7 +1317,7 @@ dds record_format The record format for the UNIX file. - \ :emphasis:`record\_format`\ is required in situations where the data will be processed as records and therefore, \ :emphasis:`record\_length`\ , \ :emphasis:`block\_size`\ and \ :emphasis:`record\_format`\ need to be supplied since a UNIX file would normally be treated as a stream of bytes. + *record_format* is required in situations where the data will be processed as records and therefore, *record_length*, *block_size* and *record_format* need to be supplied since a UNIX file would normally be treated as a stream of bytes. | **required**: False | **type**: str @@ -1336,11 +1336,11 @@ dds type The type of the content to be returned. - \ :literal:`text`\ means return content in encoding specified by \ :emphasis:`response\_encoding`\ . + ``text`` means return content in encoding specified by *response_encoding*. - \ :emphasis:`src\_encoding`\ and \ :emphasis:`response\_encoding`\ are only used when \ :emphasis:`type=text`\ . + *src_encoding* and *response_encoding* are only used when *type=text*. - \ :literal:`base64`\ means return content in binary mode. + ``base64`` means return content in binary mode. | **required**: True | **type**: str @@ -1366,7 +1366,7 @@ dds dd_input - \ :emphasis:`dd\_input`\ is used to specify an in-stream data set. + *dd_input* is used to specify an in-stream data set. Input will be saved to a temporary data set with a record length of 80. @@ -1377,15 +1377,15 @@ dds content The input contents for the DD. - \ :emphasis:`dd\_input`\ supports single or multiple lines of input. + *dd_input* supports single or multiple lines of input. Multi-line input can be provided as a multi-line string or a list of strings with 1 line per list item. If a list of strings is provided, newlines will be added to each of the lines when used as input. - If a multi-line string is provided, use the proper block scalar style. YAML supports both \ `literal `__\ and \ `folded `__\ scalars. It is recommended to use the literal style indicator "|" with a block indentation indicator, for example; \ :emphasis:`content: | 2`\ is a literal block style indicator with a 2 space indentation, the entire block will be indented and newlines preserved. The block indentation range is 1 - 9. While generally unnecessary, YAML does support block \ `chomping `__\ indicators "+" and "-" as well. + If a multi-line string is provided, use the proper block scalar style. YAML supports both `literal `_ and `folded `_ scalars. It is recommended to use the literal style indicator "|" with a block indentation indicator, for example; *content: | 2* is a literal block style indicator with a 2 space indentation, the entire block will be indented and newlines preserved. The block indentation range is 1 - 9. While generally unnecessary, YAML does support block `chomping `_ indicators "+" and "-" as well. - When using the \ :emphasis:`content`\ option for instream-data, the module will ensure that all lines contain a blank in columns 1 and 2 and add blanks when not present while retaining a maximum length of 80 columns for any line. This is true for all \ :emphasis:`content`\ types; string, list of strings and when using a YAML block indicator. + When using the *content* option for instream-data, the module will ensure that all lines contain a blank in columns 1 and 2 and add blanks when not present while retaining a maximum length of 80 columns for any line. This is true for all *content* types; string, list of strings and when using a YAML block indicator. | **required**: True | **type**: raw @@ -1403,11 +1403,11 @@ dds type The type of the content to be returned. - \ :literal:`text`\ means return content in encoding specified by \ :emphasis:`response\_encoding`\ . + ``text`` means return content in encoding specified by *response_encoding*. - \ :emphasis:`src\_encoding`\ and \ :emphasis:`response\_encoding`\ are only used when \ :emphasis:`type=text`\ . + *src_encoding* and *response_encoding* are only used when *type=text*. - \ :literal:`base64`\ means return content in binary mode. + ``base64`` means return content in binary mode. | **required**: True | **type**: str @@ -1417,7 +1417,7 @@ dds src_encoding The encoding of the data set on the z/OS system. - for \ :emphasis:`dd\_input`\ , \ :emphasis:`src\_encoding`\ should generally not need to be changed. + for *dd_input*, *src_encoding* should generally not need to be changed. | **required**: False | **type**: str @@ -1440,7 +1440,7 @@ dds tmp_hlq Override the default high level qualifier (HLQ) for temporary and backup datasets. - The default HLQ is the Ansible user used to execute the module and if that is not available, then the value \ :literal:`TMPHLQ`\ is used. + The default HLQ is the Ansible user used to execute the module and if that is not available, then the value ``TMPHLQ`` is used. | **required**: False | **type**: str @@ -1755,11 +1755,11 @@ Notes ----- .. note:: - When executing programs using \ `zos\_mvs\_raw <./zos_mvs_raw.html>`__\ , you may encounter errors that originate in the programs implementation. Two such known issues are noted below of which one has been addressed with an APAR. + When executing programs using `zos_mvs_raw <./zos_mvs_raw.html>`_, you may encounter errors that originate in the programs implementation. Two such known issues are noted below of which one has been addressed with an APAR. - 1. \ `zos\_mvs\_raw <./zos_mvs_raw.html>`__\ module execution fails when invoking Database Image Copy 2 Utility or Database Recovery Utility in conjunction with FlashCopy or Fast Replication. + 1. `zos_mvs_raw <./zos_mvs_raw.html>`_ module execution fails when invoking Database Image Copy 2 Utility or Database Recovery Utility in conjunction with FlashCopy or Fast Replication. - 2. \ `zos\_mvs\_raw <./zos_mvs_raw.html>`__\ module execution fails when invoking DFSRRC00 with parm "UPB,PRECOMP", "UPB, POSTCOMP" or "UPB,PRECOMP,POSTCOMP". This issue is addressed by APAR PH28089. + 2. `zos_mvs_raw <./zos_mvs_raw.html>`_ module execution fails when invoking DFSRRC00 with parm "UPB,PRECOMP", "UPB, POSTCOMP" or "UPB,PRECOMP,POSTCOMP". This issue is addressed by APAR PH28089. 3. When executing a program, refer to the programs documentation as each programs requirments can vary fom DDs, instream-data indentation and continuation characters. @@ -1837,20 +1837,8 @@ backups | **type**: str backup_name - The name of the data set containing the backup of content from data set in original\_name. + The name of the data set containing the backup of content from data set in original_name. | **type**: str -stdout - The stdout from a USS command or MVS command, if applicable. - - | **returned**: always - | **type**: str - -stderr - The stderr of a USS command or MVS command, if applicable. - - | **returned**: failure - | **type**: str - diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_operator.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_operator.rst.txt index 8f7e76df..d05126d1 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_operator.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_operator.rst.txt @@ -56,7 +56,7 @@ wait_time_s This option is helpful on a busy system requiring more time to execute commands. - Setting \ :emphasis:`wait`\ can instruct if execution should wait the full \ :emphasis:`wait\_time\_s`\ . + Setting *wait* can instruct if execution should wait the full *wait_time_s*. | **required**: False | **type**: int @@ -96,12 +96,6 @@ Examples -Notes ------ - -.. note:: - Commands may need to use specific prefixes like $, they can be discovered by issuing the following command \ :literal:`D OPDATA,PREFIX`\ . - diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_operator_action_query.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_operator_action_query.rst.txt index b7956c8b..ba9398b5 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_operator_action_query.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_operator_action_query.rst.txt @@ -31,7 +31,7 @@ system If the system name is not specified, all outstanding messages for that system and for the local systems attached to it are returned. - A trailing asterisk, (\*) wildcard is supported. + A trailing asterisk, (*) wildcard is supported. | **required**: False | **type**: str @@ -42,7 +42,7 @@ message_id If the message identifier is not specified, all outstanding messages for all message identifiers are returned. - A trailing asterisk, (\*) wildcard is supported. + A trailing asterisk, (*) wildcard is supported. | **required**: False | **type**: str @@ -53,7 +53,7 @@ job_name If the message job name is not specified, all outstanding messages for all job names are returned. - A trailing asterisk, (\*) wildcard is supported. + A trailing asterisk, (*) wildcard is supported. | **required**: False | **type**: str @@ -69,24 +69,24 @@ message_filter filter - Specifies the substring or regex to match to the outstanding messages, see \ :emphasis:`use\_regex`\ . + Specifies the substring or regex to match to the outstanding messages, see *use_regex*. All special characters in a filter string that are not a regex are escaped. - Valid Python regular expressions are supported. See \ `the official documentation `__\ for more information. + Valid Python regular expressions are supported. See `the official documentation `_ for more information. - Regular expressions are compiled with the flag \ :strong:`re.DOTALL`\ which makes the \ :strong:`'.'`\ special character match any character including a newline." + Regular expressions are compiled with the flag **re.DOTALL** which makes the **'.'** special character match any character including a newline." | **required**: True | **type**: str use_regex - Indicates that the value for \ :emphasis:`filter`\ is a regex or a string to match. + Indicates that the value for *filter* is a regex or a string to match. - If False, the module assumes that \ :emphasis:`filter`\ is not a regex and matches the \ :emphasis:`filter`\ substring on the outstanding messages. + If False, the module assumes that *filter* is not a regex and matches the *filter* substring on the outstanding messages. - If True, the module creates a regex from the \ :emphasis:`filter`\ string and matches it to the outstanding messages. + If True, the module creates a regex from the *filter* string and matches it to the outstanding messages. | **required**: False | **type**: bool @@ -222,7 +222,7 @@ actions | **sample**: STC01537 message_text - Content of the outstanding message requiring operator action awaiting a reply. If \ :emphasis:`message\_filter`\ is set, \ :emphasis:`message\_text`\ will be filtered accordingly. + Content of the outstanding message requiring operator action awaiting a reply. If *message_filter* is set, *message_text* will be filtered accordingly. | **returned**: success | **type**: str diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_ping.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_ping.rst.txt index acb90179..a4405b47 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_ping.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_ping.rst.txt @@ -16,9 +16,9 @@ zos_ping -- Ping z/OS and check dependencies. Synopsis -------- -- \ `zos\_ping <./zos_ping.html>`__\ verifies the presence of z/OS Web Client Enablement Toolkit, iconv, and Python. -- \ `zos\_ping <./zos_ping.html>`__\ returns \ :literal:`pong`\ when the target host is not missing any required dependencies. -- If the target host is missing optional dependencies, the \ `zos\_ping <./zos_ping.html>`__\ will return one or more warning messages. +- `zos_ping <./zos_ping.html>`_ verifies the presence of z/OS Web Client Enablement Toolkit, iconv, and Python. +- `zos_ping <./zos_ping.html>`_ returns ``pong`` when the target host is not missing any required dependencies. +- If the target host is missing optional dependencies, the `zos_ping <./zos_ping.html>`_ will return one or more warning messages. - If a required dependency is missing from the target host, an explanatory message will be returned with the module failure. @@ -44,7 +44,7 @@ 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 \ :literal:`scp\_extra\_args="-O"`\ into the ini file named \ :literal:`ansible.cfg`\ . + 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``. diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_script.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_script.rst.txt index d2977c48..10660d38 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_script.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_script.rst.txt @@ -16,7 +16,7 @@ zos_script -- Run scripts in z/OS Synopsis -------- -- The \ `zos\_script <./zos_script.html>`__\ module runs a local or remote script in the remote machine. +- The `zos_script <./zos_script.html>`_ module runs a local or remote script in the remote machine. @@ -56,7 +56,7 @@ creates encoding Specifies which encodings the script should be converted from and to. - If \ :literal:`encoding`\ is not provided, the module determines which local and remote charsets to convert the data from and to. + If ``encoding`` is not provided, the module determines which local and remote charsets to convert the data from and to. | **required**: False | **type**: dict @@ -87,9 +87,9 @@ executable remote_src - If set to \ :literal:`false`\ , the module will search the script in the controller. + If set to ``false``, the module will search the script in the controller. - If set to \ :literal:`true`\ , the module will search the script in the remote machine. + If set to ``true``, the module will search the script in the remote machine. | **required**: False | **type**: bool @@ -103,13 +103,13 @@ removes use_template - Whether the module should treat \ :literal:`src`\ as a Jinja2 template and render it before continuing with the rest of the module. + Whether the module should treat ``src`` as a Jinja2 template and render it before continuing with the rest of the module. - Only valid when \ :literal:`src`\ is a local file or directory. + Only valid when ``src`` is a local file or directory. - All variables defined in inventory files, vars files and the playbook will be passed to the template engine, as well as \ `Ansible special variables `__\ , such as \ :literal:`playbook\_dir`\ , \ :literal:`ansible\_version`\ , etc. + All variables defined in inventory files, vars files and the playbook will be passed to the template engine, as well as `Ansible special variables `_, such as ``playbook_dir``, ``ansible_version``, etc. - If variables defined in different scopes share the same name, Ansible will apply variable precedence to them. You can see the complete precedence order \ `in Ansible's documentation `__\ + If variables defined in different scopes share the same name, Ansible will apply variable precedence to them. You can see the complete precedence order `in Ansible's documentation `_ | **required**: False | **type**: bool @@ -119,9 +119,9 @@ use_template template_parameters Options to set the way Jinja2 will process templates. - Jinja2 already sets defaults for the markers it uses, you can find more information at its \ `official documentation `__\ . + Jinja2 already sets defaults for the markers it uses, you can find more information at its `official documentation `_. - These options are ignored unless \ :literal:`use\_template`\ is true. + These options are ignored unless ``use_template`` is true. | **required**: False | **type**: dict @@ -200,7 +200,7 @@ template_parameters trim_blocks Whether Jinja2 should remove the first newline after a block is removed. - Setting this option to \ :literal:`False`\ will result in newlines being added to the rendered template. This could create invalid code when working with JCL templates or empty records in destination data sets. + Setting this option to ``False`` will result in newlines being added to the rendered template. This could create invalid code when working with JCL templates or empty records in destination data sets. | **required**: False | **type**: bool @@ -290,7 +290,7 @@ Notes .. note:: When executing local scripts, temporary storage will be used on the remote z/OS system. The size of the temporary storage will correspond to the size of the file being copied. - The location in the z/OS system where local scripts will be copied to can be configured through Ansible's \ :literal:`remote\_tmp`\ option. Refer to \ `Ansible's documentation `__\ for more information. + The location in the z/OS system where local scripts will be copied to can be configured through Ansible's ``remote_tmp`` option. Refer to `Ansible's documentation `_ for more information. All local scripts copied to a remote z/OS system will be removed from the managed node before the module finishes executing. @@ -298,13 +298,13 @@ Notes The module will only add execution permissions for the file owner. - If executing REXX scripts, make sure to include a newline character on each line of the file. Otherwise, the interpreter may fail and return error \ :literal:`BPXW0003I`\ . + If executing REXX scripts, make sure to include a newline character on each line of the file. Otherwise, the interpreter may fail and return error ``BPXW0003I``. - For supported character sets used to encode data, refer to the \ `documentation `__\ . + For supported character sets used to encode data, refer to the `documentation `_. - 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 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>`__\ . + 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>`_. The community script module does not rely on Python to execute scripts on a managed node, while this module does. Python must be present on the remote machine. diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_tso_command.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_tso_command.rst.txt index b35c13a1..4af6b1b5 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_tso_command.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_tso_command.rst.txt @@ -40,7 +40,7 @@ commands max_rc Specifies the maximum return code allowed for a TSO command. - If more than one TSO command is submitted, the \ :emphasis:`max\_rc`\ applies to all TSO commands. + If more than one TSO command is submitted, the *max_rc* applies to all TSO commands. | **required**: False | **type**: int @@ -119,7 +119,7 @@ output max_rc Specifies the maximum return code allowed for a TSO command. - If more than one TSO command is submitted, the \ :emphasis:`max\_rc`\ applies to all TSO commands. + If more than one TSO command is submitted, the *max_rc* applies to all TSO commands. | **returned**: always | **type**: int diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_unarchive.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_unarchive.rst.txt index ed6a26a8..f2d7aba8 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_unarchive.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_unarchive.rst.txt @@ -16,8 +16,8 @@ zos_unarchive -- Unarchive files and data sets in z/OS. Synopsis -------- -- The \ :literal:`zos\_unarchive`\ module unpacks an archive after optionally transferring it to the remote system. -- For supported archive formats, see option \ :literal:`format`\ . +- The ``zos_unarchive`` module unpacks an archive after optionally transferring it to the remote system. +- For supported archive formats, see option ``format``. - Supported sources are USS (UNIX System Services) or z/OS data sets. - Mixing MVS data sets with USS files for unarchiving is not supported. - The archive is sent to the remote as binary, so no encoding is performed. @@ -33,11 +33,11 @@ Parameters src The remote absolute path or data set of the archive to be uncompressed. - \ :emphasis:`src`\ can be a USS file or MVS data set name. + *src* can be a USS file or MVS data set name. USS file paths should be absolute paths. - MVS data sets supported types are \ :literal:`SEQ`\ , \ :literal:`PDS`\ , \ :literal:`PDSE`\ . + MVS data sets supported types are ``SEQ``, ``PDS``, ``PDSE``. | **required**: True | **type**: str @@ -72,14 +72,14 @@ format If the data set provided exists, the data set must have the following attributes: LRECL=255, BLKSIZE=3120, and RECFM=VB - When providing the \ :emphasis:`xmit\_log\_data\_set`\ name, ensure there is adequate space. + When providing the *xmit_log_data_set* name, ensure there is adequate space. | **required**: False | **type**: str use_adrdssu - If set to true, the \ :literal:`zos\_archive`\ module will use Data Facility Storage Management Subsystem data set services (DFSMSdss) program ADRDSSU to uncompress data sets from a portable format after using \ :literal:`xmit`\ or \ :literal:`terse`\ . + If set to true, the ``zos_archive`` module will use Data Facility Storage Management Subsystem data set services (DFSMSdss) program ADRDSSU to uncompress data sets from a portable format after using ``xmit`` or ``terse``. | **required**: False | **type**: bool @@ -87,7 +87,7 @@ format dest_volumes - When \ :emphasis:`use\_adrdssu=True`\ , specify the volume the data sets will be written to. + When *use_adrdssu=True*, specify the volume the data sets will be written to. If no volume is specified, storage management rules will be used to determine the volume where the file will be unarchived. @@ -103,7 +103,7 @@ format dest The remote absolute path or data set where the content should be unarchived to. - \ :emphasis:`dest`\ can be a USS file, directory or MVS data set name. + *dest* can be a USS file, directory or MVS data set name. If dest has missing parent directories, they will not be created. @@ -116,7 +116,7 @@ group When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. - This option is only applicable if \ :literal:`dest`\ is USS, otherwise ignored. + This option is only applicable if ``dest`` is USS, otherwise ignored. | **required**: False | **type**: str @@ -125,13 +125,13 @@ group mode The permission of the uncompressed files. - If \ :literal:`dest`\ is USS, this will act as Unix file mode, otherwise ignored. + If ``dest`` is USS, this will act as Unix file mode, otherwise ignored. - It should be noted that modes are octal numbers. The user must either add a leading zero so that Ansible's YAML parser knows it is an octal number (like \ :literal:`0644`\ or \ :literal:`01777`\ )or quote it (like \ :literal:`'644'`\ or \ :literal:`'1777'`\ ) so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results. + It should be noted that modes are octal numbers. The user must either add a leading zero so that Ansible's YAML parser knows it is an octal number (like ``0644`` or ``01777``)or quote it (like ``'644'`` or ``'1777'``) so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results. - The mode may also be specified as a symbolic mode (for example, \`\`u+rwx\`\` or \`\`u=rw,g=r,o=r\`\`) or a special string \`preserve\`. + The mode may also be specified as a symbolic mode (for example, ``u+rwx`` or ``u=rw,g=r,o=r``) or a special string `preserve`. - \ :emphasis:`mode=preserve`\ means that the file will be given the same permissions as the source file. + *mode=preserve* means that the file will be given the same permissions as the source file. | **required**: False | **type**: str @@ -149,7 +149,7 @@ owner include A list of directories, files or data set names to extract from the archive. - When \ :literal:`include`\ is set, only those files will we be extracted leaving the remaining files in the archive. + When ``include`` is set, only those files will we be extracted leaving the remaining files in the archive. Mutually exclusive with exclude. @@ -177,7 +177,7 @@ list dest_data_set - Data set attributes to customize a \ :literal:`dest`\ data set that the archive will be copied into. + Data set attributes to customize a ``dest`` data set that the archive will be copied into. | **required**: False | **type**: dict @@ -200,18 +200,18 @@ dest_data_set space_primary - If the destination \ :emphasis:`dest`\ data set does not exist , this sets the primary space allocated for the data set. + If the destination *dest* data set does not exist , this sets the primary space allocated for the data set. - The unit of space used is set using \ :emphasis:`space\_type`\ . + The unit of space used is set using *space_type*. | **required**: False | **type**: int space_secondary - If the destination \ :emphasis:`dest`\ data set does not exist , this sets the secondary space allocated for the data set. + If the destination *dest* data set does not exist , this sets the secondary space allocated for the data set. - The unit of space used is set using \ :emphasis:`space\_type`\ . + The unit of space used is set using *space_type*. | **required**: False | **type**: int @@ -220,7 +220,7 @@ dest_data_set space_type If the destination data set does not exist, this sets the unit of measurement to use when defining primary and secondary space. - Valid units of size are \ :literal:`k`\ , \ :literal:`m`\ , \ :literal:`g`\ , \ :literal:`cyl`\ , and \ :literal:`trk`\ . + Valid units of size are ``k``, ``m``, ``g``, ``cyl``, and ``trk``. | **required**: False | **type**: str @@ -228,7 +228,7 @@ dest_data_set record_format - If the destination data set does not exist, this sets the format of the data set. (e.g \ :literal:`fb`\ ) + If the destination data set does not exist, this sets the format of the data set. (e.g ``fb``) Choices are case-sensitive. @@ -265,9 +265,9 @@ dest_data_set key_offset The key offset to use when creating a KSDS data set. - \ :emphasis:`key\_offset`\ is required when \ :emphasis:`type=ksds`\ . + *key_offset* is required when *type=ksds*. - \ :emphasis:`key\_offset`\ should only be provided when \ :emphasis:`type=ksds`\ + *key_offset* should only be provided when *type=ksds* | **required**: False | **type**: int @@ -276,9 +276,9 @@ dest_data_set key_length The key length to use when creating a KSDS data set. - \ :emphasis:`key\_length`\ is required when \ :emphasis:`type=ksds`\ . + *key_length* is required when *type=ksds*. - \ :emphasis:`key\_length`\ should only be provided when \ :emphasis:`type=ksds`\ + *key_length* should only be provided when *type=ksds* | **required**: False | **type**: int @@ -327,7 +327,7 @@ dest_data_set tmp_hlq Override the default high level qualifier (HLQ) for temporary data sets. - The default HLQ is the Ansible user used to execute the module and if that is not available, then the environment variable value \ :literal:`TMPHLQ`\ is used. + The default HLQ is the Ansible user used to execute the module and if that is not available, then the environment variable value ``TMPHLQ`` is used. | **required**: False | **type**: str @@ -342,9 +342,9 @@ force remote_src - If set to true, \ :literal:`zos\_unarchive`\ retrieves the archive from the remote system. + If set to true, ``zos_unarchive`` retrieves the archive from the remote system. - If set to false, \ :literal:`zos\_unarchive`\ searches the local machine (Ansible controller) for the archive. + If set to false, ``zos_unarchive`` searches the local machine (Ansible controller) for the archive. | **required**: False | **type**: bool @@ -404,7 +404,7 @@ 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. + 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. diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_volume_init.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_volume_init.rst.txt index a2b6f25a..5647ad99 100644 --- a/_sources/ibm_zos_core/docs/source/modules/zos_volume_init.rst.txt +++ b/_sources/ibm_zos_core/docs/source/modules/zos_volume_init.rst.txt @@ -17,14 +17,14 @@ zos_volume_init -- Initialize volumes or minidisks. Synopsis -------- - Initialize a volume or minidisk on z/OS. -- \ :emphasis:`zos\_volume\_init`\ will create the volume label and entry into the volume table of contents (VTOC). +- *zos_volume_init* will create the volume label and entry into the volume table of contents (VTOC). - Volumes are used for storing data and executable programs. - A minidisk is a portion of a disk that is linked to your virtual machine. - A VTOC lists the data sets that reside on a volume, their location, size, and other attributes. -- \ :emphasis:`zos\_volume\_init`\ uses the ICKDSF command INIT to initialize a volume. In some cases the command could be protected by facility class \`STGADMIN.ICK.INIT\`. Protection occurs when the class is active, and the class profile is defined. Ensure the user executing the Ansible task is permitted to execute ICKDSF command INIT, otherwise, any user can use the command. -- ICKDSF is an Authorized Program Facility (APF) program on z/OS, \ :emphasis:`zos\_volume\_init`\ will run in authorized mode but if the program ICKDSF is not APF authorized, the task will end. +- *zos_volume_init* uses the ICKDSF command INIT to initialize a volume. In some cases the command could be protected by facility class `STGADMIN.ICK.INIT`. Protection occurs when the class is active, and the class profile is defined. Ensure the user executing the Ansible task is permitted to execute ICKDSF command INIT, otherwise, any user can use the command. +- ICKDSF is an Authorized Program Facility (APF) program on z/OS, *zos_volume_init* will run in authorized mode but if the program ICKDSF is not APF authorized, the task will end. - Note that defaults set on target z/OS systems may override ICKDSF parameters. -- If is recommended that data on the volume is backed up as the \ :emphasis:`zos\_volume\_init`\ module will not perform any backups. You can use the \ `zos\_backup\_restore <./zos_backup_restore.html>`__\ module to backup a volume. +- If is recommended that data on the volume is backed up as the *zos_volume_init* module will not perform any backups. You can use the `zos_backup_restore <./zos_backup_restore.html>`_ module to backup a volume. @@ -35,9 +35,9 @@ Parameters address - \ :emphasis:`address`\ is a 3 or 4 digit hexadecimal number that specifies the address of the volume or minidisk. + *address* is a 3 or 4 digit hexadecimal number that specifies the address of the volume or minidisk. - \ :emphasis:`address`\ can be the number assigned to the device (device number) when it is installed or the virtual address. + *address* can be the number assigned to the device (device number) when it is installed or the virtual address. | **required**: True | **type**: str @@ -46,15 +46,15 @@ address verify_volid Verify that the volume serial matches what is on the existing volume or minidisk. - \ :emphasis:`verify\_volid`\ must be 1 to 6 alphanumeric characters or \ :literal:`\*NONE\*`\ . + *verify_volid* must be 1 to 6 alphanumeric characters or ``*NONE*``. - To verify that a volume serial number does not exist, use \ :emphasis:`verify\_volid=\*NONE\*`\ . + To verify that a volume serial number does not exist, use *verify_volid=*NONE**. - If \ :emphasis:`verify\_volid`\ is specified and the volume serial number does not match that found on the volume or minidisk, initialization does not complete. + If *verify_volid* is specified and the volume serial number does not match that found on the volume or minidisk, initialization does not complete. - If \ :emphasis:`verify\_volid=\*NONE\*`\ is specified and a volume serial is found on the volume or minidisk, initialization does not complete. + If *verify_volid=*NONE** is specified and a volume serial is found on the volume or minidisk, initialization does not complete. - Note, this option is \ :strong:`not`\ a boolean, leave it blank to skip the verification. + Note, this option is **not** a boolean, leave it blank to skip the verification. | **required**: False | **type**: str @@ -73,11 +73,11 @@ volid Expects 1-6 alphanumeric, national ($,#,@) or special characters. - A \ :emphasis:`volid`\ with less than 6 characters will be padded with spaces. + A *volid* with less than 6 characters will be padded with spaces. - A \ :emphasis:`volid`\ can also be referred to as volser or volume serial number. + A *volid* can also be referred to as volser or volume serial number. - When \ :emphasis:`volid`\ is not specified for a previously initialized volume or minidisk, the volume serial number will remain unchanged. + When *volid* is not specified for a previously initialized volume or minidisk, the volume serial number will remain unchanged. | **required**: False | **type**: str @@ -99,7 +99,7 @@ index The VTOC index enhances the performance of VTOC access. - When set to \ :emphasis:`false`\ , no index will be created. + When set to *false*, no index will be created. | **required**: False | **type**: bool @@ -109,7 +109,7 @@ index sms_managed Specifies that the volume be managed by Storage Management System (SMS). - If \ :emphasis:`sms\_managed`\ is \ :emphasis:`true`\ then \ :emphasis:`index`\ must also be \ :emphasis:`true`\ . + If *sms_managed* is *true* then *index* must also be *true*. | **required**: False | **type**: bool @@ -127,7 +127,7 @@ verify_volume_empty tmp_hlq Override the default high level qualifier (HLQ) for temporary and backup datasets. - The default HLQ is the Ansible user used to execute the module and if that is not available, then the value \ :literal:`TMPHLQ`\ is used. + The default HLQ is the Ansible user used to execute the module and if that is not available, then the value ``TMPHLQ`` is used. | **required**: False | **type**: str diff --git a/_sources/ibm_zos_core/docs/source/plugins.rst.txt b/_sources/ibm_zos_core/docs/source/plugins.rst.txt index 3c8858f4..b2634ab5 100644 --- a/_sources/ibm_zos_core/docs/source/plugins.rst.txt +++ b/_sources/ibm_zos_core/docs/source/plugins.rst.txt @@ -35,4 +35,4 @@ user action is required, this documentation is reference only. modules/zos_script.html .. _zos_unarchive: modules/zos_unarchive.html - + diff --git a/_sources/ibm_zos_core/docs/source/reference/community.rst.txt b/_sources/ibm_zos_core/docs/source/reference/community.rst.txt index 41bdbe9b..9c09aeea 100644 --- a/_sources/ibm_zos_core/docs/source/reference/community.rst.txt +++ b/_sources/ibm_zos_core/docs/source/reference/community.rst.txt @@ -1,5 +1,5 @@ .. ........................................................................... -.. © Copyright IBM Corporation 2024 . +.. © Copyright IBM Corporation 2020, 2021 . .. ........................................................................... ============ diff --git a/_sources/ibm_zos_core/docs/source/release_notes.rst.txt b/_sources/ibm_zos_core/docs/source/release_notes.rst.txt index c8c2f6e9..82539a0d 100644 --- a/_sources/ibm_zos_core/docs/source/release_notes.rst.txt +++ b/_sources/ibm_zos_core/docs/source/release_notes.rst.txt @@ -276,6 +276,9 @@ 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 ------------ @@ -663,7 +666,7 @@ controller and z/OS managed node dependencies. .. _FAQs: https://ibm.github.io/z_ansible_collections_doc/faqs/faqs.html .. _z/OS core support matrix: - https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/resources/releases_maintenance.html + https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/build/html/resources/releases_maintenance.html .. ............................................................................. .. Playbook Links diff --git a/_sources/ibm_zos_core/docs/source/resources/releases_maintenance.rst.txt b/_sources/ibm_zos_core/docs/source/resources/releases_maintenance.rst.txt index 39145676..70fa46e0 100644 --- a/_sources/ibm_zos_core/docs/source/resources/releases_maintenance.rst.txt +++ b/_sources/ibm_zos_core/docs/source/resources/releases_maintenance.rst.txt @@ -6,60 +6,16 @@ Releases and maintenance ======================== -This section describes the collections release dates, dependency versions and End of Life dates (EOL) -and support coverage. +This table describes the collections release dates, dependency versions and End of Life dates (EOL). 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 a dependency reaches EOL 1 year later, then the collection will EOL +For example, if a collection has released and its 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. @@ -77,15 +33,8 @@ For IBM product lifecycle information, you can search for products using a produ 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 | +=========+============================+===================================================+===============+===============+ @@ -150,6 +99,4 @@ The z/OS managed node includes several shells, currently the only supported shel .. _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 -.. _/bin/sh: - https://www.ibm.com/docs/en/zos/3.1.0?topic=descriptions-sh-invoke-shell \ No newline at end of file + https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix \ No newline at end of file diff --git a/_sources/zhmc-ansible-modules/docs/source/bibliography.rst.txt b/_sources/zhmc-ansible-modules/docs/source/bibliography.rst.txt index 465b036c..cf5f06cf 100644 --- a/_sources/zhmc-ansible-modules/docs/source/bibliography.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/bibliography.rst.txt @@ -21,6 +21,8 @@ Resources .. glossary:: +.. _`HMC API`: + HMC API The Web Services API of the z Systems Hardware Management Console, described in the following books: @@ -48,3 +50,13 @@ Resources HMC API 2.15.0 `IBM SC27-2638, IBM Z Hardware Management Console Web Services API (Version 2.15.0) `_ (covers both GA1 and GA2) + +.. _`Java regular expressions`: + + Java regular expressions + `Java class java.util.regex.Pattern `_ + +.. _`CoD Users Guide`: + + Capacity on Demand User's Guide + `IBM SC28-6985, IBM Z Capacity on Demand User's Guide `_ diff --git a/_sources/zhmc-ansible-modules/docs/source/development.rst.txt b/_sources/zhmc-ansible-modules/docs/source/development.rst.txt index 43ed50f7..5baeb193 100644 --- a/_sources/zhmc-ansible-modules/docs/source/development.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/development.rst.txt @@ -138,8 +138,11 @@ Again, an invocation of Make runs against the currently active Python environmen There are four kinds of tests currently, available as make targets: * ``make check`` - Run flake8 +* ``make pylint`` - Run pylint * ``make linkcheck`` - Check links in documentation -* ``make sanity`` - Run Ansible sanity tests (includes flake8, pylint, validate-modules) +* ``make sanity`` - Run Ansible sanity tests +* ``make ansible_lint`` - Run ansible_lint +* ``make safety`` - Run safety vulnerability checks * ``make check_reqs`` - Run pip-missing-reqs to perform missing dependency checks * ``make test`` - Run unit and function tests with test coverage * ``make end2end_mocked`` - Run end2end tests against a mocked environment @@ -168,40 +171,28 @@ test matrix in the ``.github/workflows/test.yml`` file. The following table shows for the full set of test environments which Ansible versions are tested on which Python versions. The 'Packages' column indicates whether the latest versions of Python packages are used (i.e. what pip installs -by default, given the ``requirements.txt`` and ``dev-requirements.txt`` files), -the minimum versions as defined in the ``minimum-constraint.txt`` file, or -specific Ansible versions as defined in the ``ansible-constraint.txt`` file: +by default, given the ``requirements*.txt`` files), +the minimum versions as defined in the ``minimum-constraints*.txt`` files, or +specific Ansible versions as defined in the ``ansible-constraints.txt`` file: ====== ======== ======= ============ Python Packages Ansible Ansible core ------ -------- ------- ------------ -2.7 latest 4.x 2.11 -3.5 latest 4.x 2.11 -3.6 latest 4.x 2.11 -3.7 latest 4.x 2.11 3.8 latest 6.x 2.13 3.9 latest 8.x 2.15 3.10 latest 9.x 2.16 3.11 latest 9.x 2.16 3.12 latest 9.x 2.16 -2.7 minimum 2.9 2.9 -3.5 minimum 2.9 2.9 -3.6 minimum 2.9 2.9 -3.7 minimum 2.9 2.9 3.8 minimum 2.9 2.9 3.9 minimum 4.0 2.11 3.10 minimum 5.0 2.12 3.11 minimum 7.0 2.14 3.12 minimum 9.0 2.16 -2.7 ansible 2.9 2.9 -3.5 ansible 2.10 2.10 -3.6 ansible 3.x 2.10 -3.7 ansible 4.x 2.11 -3.8 ansible 5.x 2.12 -3.9 ansible 6.x 2.13 -3.10 ansible 7.x 2.14 -3.11 ansible 8.x 2.15 -3.12 ansible 9.x 2.16 +3.8 ansible 6.x 2.13 +3.9 ansible 7.x 2.14 +3.10 ansible 8.x 2.15 +3.11 ansible 9.x 2.16 +3.12 ansible 10.x 2.17 ====== ======== ======= ============ The versions for the 'latest' and 'minimum' package levels are in sync with the @@ -305,20 +296,68 @@ local clone of the zhmc-ansible-modules Git repo. add text for any known issues you want users to know about. * Remove all empty list items. -5. Update the authors: +5. When releasing a new major or minor version, edit the support matrix: + + .. code-block:: sh + + vi docs/source/installation.rst + + and make the following changes in section "Support matrix": + + * Set the End of Life date of the previous minor version (M.N-1.x) to + today's date. + * Add a new row in the table for the current release (M.N.U), that has + today's date as the GA date and an empty End of Life cell. + +6. Edit the change log table: + + .. code-block:: sh + + vi README.md + + and make the following changes in section "Release Notes and Roadmap": + + * When releasing a fix version, update the fix version in the table. + * When releasing a major or minor version, add a row with the released + version to the table, and increase the version in development. + +7. Update the authors: .. code-block:: sh make authors -6. Commit your changes and push the topic branch to the remote repo: +8. Run the Safety tool: + + .. code-block:: sh + + RUN_TYPE=release make safety + + When releasing a version, the safety run for all dependencies will fail + if there are any safety issues reported. In normal and scheduled runs, + safety issues reported for all dependencies will be ignored. + + If the safety run fails, you need to fix the safety issues that are + reported. + +9. Review the result of the latest Mend scan in + `this Box folder `_. + + If the Mend scan shows any issues, fix them. + +10. Check for any + `dependabot issues `_. + + If there are any dependebot issues, fix them. + +11. Commit your changes and push the topic branch to the remote repo: .. code-block:: sh git commit -asm "Release ${MNU}" git push --set-upstream origin release_${MNU} -7. On GitHub, create a Pull Request for branch ``release_M.N.U``. +12. On GitHub, create a Pull Request for branch ``release_M.N.U``. Important: When creating Pull Requests, GitHub by default targets the ``master`` branch. When releasing based on a stable branch, you need to @@ -328,18 +367,18 @@ local clone of the zhmc-ansible-modules Git repo. tests for all defined environments, since it discovers by the branch name that this is a PR for a release. -8. On GitHub, once the checks for that Pull Request have succeeded, merge the +13. On GitHub, once the checks for that Pull Request have succeeded, merge the Pull Request (no review is needed). This automatically deletes the branch on GitHub. If the PR did not succeed, fix the issues. -9. On GitHub, close milestone ``M.N.U``. +14. On GitHub, close milestone ``M.N.U``. Verify that the milestone has no open items anymore. If it does have open items, investigate why and fix. -10. Publish the collection to Ansible Galaxy +15. Publish the collection to Ansible Galaxy .. code-block:: sh @@ -355,7 +394,7 @@ local clone of the zhmc-ansible-modules Git repo. it on Github, and finally creates a new stable branch on Github if the master branch was released. -11. Verify the publishing +16. Verify the publishing * Verify that the new version is available on Ansible Galaxy at https://galaxy.ansible.com/ibm/ibm_zhmc/ @@ -370,7 +409,7 @@ local clone of the zhmc-ansible-modules Git repo. * Verify that the new version has documentation on Github pages at https://zhmcclient.github.io/zhmc-ansible-modules/release_notes.html -12. Publish the collection to Ansible AutomationHub +17. Publish the collection to Ansible AutomationHub This needs to be done in addition to the prior publish step, and it has not successfully been automated as of today. diff --git a/_sources/zhmc-ansible-modules/docs/source/modules.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules.rst.txt index 69688326..2b5fd407 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules.rst.txt @@ -39,6 +39,7 @@ Modules targeting the HMC (i.e. not a specific CPC): :maxdepth: 1 :glob: + modules/zhmc_versions modules/zhmc_console modules/zhmc_user modules/zhmc_user_list @@ -46,6 +47,8 @@ Modules targeting the HMC (i.e. not a specific CPC): modules/zhmc_password_rule_list modules/zhmc_user_role modules/zhmc_user_role_list + modules/zhmc_user_pattern + modules/zhmc_user_pattern_list modules/zhmc_ldap_server_definition modules/zhmc_ldap_server_definition_list @@ -57,6 +60,7 @@ Modules supported with CPCs in any operational mode: modules/zhmc_cpc modules/zhmc_cpc_list + modules/zhmc_cpc_capacity Modules supported only with CPCs in DPM operational mode: @@ -71,6 +75,7 @@ Modules supported only with CPCs in DPM operational mode: modules/zhmc_nic modules/zhmc_nic_list modules/zhmc_partition + modules/zhmc_partition_command modules/zhmc_partition_list modules/zhmc_partition_messages modules/zhmc_storage_group @@ -85,6 +90,7 @@ Modules supported only with CPCs in classic operational mode: :glob: modules/zhmc_lpar + modules/zhmc_lpar_command modules/zhmc_lpar_list modules/zhmc_lpar_messages diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_adapter.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_adapter.rst.txt index f4514f30..3d8b0b81 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_adapter.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_adapter.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_adapter_module: -zhmc_adapter -- Update adapters and create Hipersocket adapters -=============================================================== +zhmc_adapter -- Manage an adapter (DPM mode) +============================================ @@ -52,35 +52,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -142,9 +142,9 @@ properties \* \ :literal:`name`\ : Cannot be specified as a property because the name has already been specified in the \ :literal:`name`\ module parameter. - \* \ :literal:`type`\ : The desired adapter type can be specified in order to support adapters that can change their type (e.g. the FICON Express adapter can change its type between 'not-configured', 'fcp' and 'fc'). + \* \ :literal:`type`\ : The desired adapter type can be specified in order to support adapters that can change their type (e.g. the FICON Express adapter can change its type between \ :literal:`not-configured`\ , \ :literal:`fcp`\ and \ :literal:`fc`\ ). - \* \ :literal:`crypto\_type`\ : The crypto type can be specified in order to support the ability of the Crypto Express adapters to change their crypto type. Valid values are 'ep11', 'cca' and 'acc'. Changing to 'acc' will zeroize the crypto adapter. + \* \ :literal:`crypto\_type`\ : The crypto type can be specified in order to support the ability of the Crypto Express adapters to change their crypto type. Valid values are \ :literal:`ep11`\ , \ :literal:`cca`\ and \ :literal:`acc`\ . Changing to \ :literal:`acc`\ will zeroize the crypto adapter. | **required**: False | **type**: dict @@ -309,7 +309,7 @@ adapter | **type**: str {property} - Additional properties of the adapter, as described in the data model of the 'Adapter' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the adapter, as described in the data model of the 'Adapter' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw @@ -325,7 +325,7 @@ adapter | **type**: str {property} - Additional properties of the port, as described in the data model of the 'Network Port' or 'Storage Port' element object of the 'Adapter' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. In case of unconfigured FICON adapters, the property list is short. + Additional properties of the port, as described in the data model of the 'Network Port' or 'Storage Port' element object of the 'Adapter' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. In case of unconfigured FICON adapters, the property list is short. | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_adapter_list.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_adapter_list.rst.txt index 0f8c7fc3..4b7b7fd8 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_adapter_list.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_adapter_list.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_adapter_list_module: -zhmc_adapter_list -- List adapters -================================== +zhmc_adapter_list -- List adapters (DPM mode) +============================================= @@ -51,35 +51,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -227,7 +227,7 @@ msg | **type**: str adapters - The list of adapters, with a subset of their properties. For details on the properties, see the data model of the 'Adapter' resource (see :term:\`HMC API\`) + The list of adapters, with a subset of their properties. For details on the properties, see the data model of the 'Adapter' resource (see \ :ref:`HMC API `\ ) | **returned**: success | **type**: list diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_console.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_console.rst.txt index f93498ff..828f6ff9 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_console.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_console.rst.txt @@ -50,35 +50,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -99,7 +99,7 @@ state bundle_level - Name of the bundle to be installed on the HMC (e.g. 'H71') + Name of the bundle to be installed on the HMC (e.g. \ :literal:`H71`\ ) Required for \ :literal:`state=upgrade`\ @@ -118,11 +118,11 @@ upgrade_timeout backup_location_type Type of backup location for the HMC backup that is performed: - \* 'ftp': The FTP server that was used for the last console backup as defined on the 'Configure Backup Settings' user interface task in the HMC GUI. + \* \ :literal:`ftp`\ : The FTP server that was used for the last console backup as defined on the 'Configure Backup Settings' user interface task in the HMC GUI. - \* 'usb': The USB storage device mounted to the HMC. + \* \ :literal:`usb`\ : The USB storage device mounted to the HMC. - Optional for \ :literal:`state=upgrade`\ , default: 'usb' + Optional for \ :literal:`state=upgrade`\ , default: \ :literal:`usb`\ | **required**: False | **type**: str @@ -222,7 +222,7 @@ hmc | **type**: str {property} - Additional properties of the Console object representing the targeted HMC, as described in the data model of the 'Console' object in the :term:\`HMC API\` book. Note that the set of properties has been extended over the past HMC versions, so you will get less properties on older HMC versions. The property names have hyphens (-) as described in that book. + Additional properties of the Console object representing the targeted HMC, as described in the data model of the 'Console' object in the \ :ref:`HMC API `\ book. Note that the set of properties has been extended over the past HMC versions, so you will get less properties on older HMC versions. The property names have hyphens (-) as described in that book. | **type**: raw @@ -232,7 +232,7 @@ hmc | **type**: dict {property} - The properties returned from the 'Query API Version' operation, as described in the :term:\`HMC API\` book. Note that the set of properties has been extended over the past HMC versions, so you will get less properties on older HMC versions. The property names have hyphens (-) as described in that book. + The properties returned from the 'Query API Version' operation, as described in the \ :ref:`HMC API `\ book. Note that the set of properties has been extended over the past HMC versions, so you will get less properties on older HMC versions. The property names have hyphens (-) as described in that book. | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_cpc.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_cpc.rst.txt index e2c9a005..90a6e8b2 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_cpc.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_cpc.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_cpc_module: -zhmc_cpc -- Manage CPCs -======================= +zhmc_cpc -- Manage a CPC +======================== @@ -53,35 +53,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -155,7 +155,7 @@ properties bundle_level - Name of the bundle to be installed on the SE of the CPC (e.g. 'S71') + Name of the bundle to be installed on the SE of the CPC (e.g. \ :literal:`S71`\ ) Required for \ :literal:`state=upgrade`\ @@ -339,12 +339,12 @@ cpc | **type**: str {property} - Additional properties of the CPC, as described in the data model of the 'CPC' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the CPC, as described in the data model of the 'CPC' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw adapters - The adapters of the CPC, with a subset of their properties. For details, see the :term:\`HMC API\` book. + The adapters of the CPC, with a subset of their properties. For details, see the \ :ref:`HMC API `\ book. | **type**: list | **elements**: dict @@ -381,7 +381,7 @@ cpc partitions - The defined partitions of the CPC, with a subset of their properties. For details, see the :term:\`HMC API\` book. + The defined partitions of the CPC, with a subset of their properties. For details, see the \ :ref:`HMC API `\ book. | **type**: list | **elements**: dict @@ -408,7 +408,7 @@ cpc storage-groups - The storage groups associated with the CPC, with a subset of their properties. For details, see the :term:\`HMC API\` book. + The storage groups associated with the CPC, with a subset of their properties. For details, see the \ :ref:`HMC API `\ book. | **type**: list | **elements**: dict diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_cpc_capacity.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_cpc_capacity.rst.txt new file mode 100644 index 00000000..504849f5 --- /dev/null +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_cpc_capacity.rst.txt @@ -0,0 +1,419 @@ + +:github_url: https://github.com/ansible-collections/ibm_zos_core/blob/dev/plugins/modules/zhmc_cpc_capacity.py + +.. _zhmc_cpc_capacity_module: + + +zhmc_cpc_capacity -- Manage temporary processor capacity +======================================================== + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Gather facts about the processor capacity of a CPC (Z system). +- Update the processor capacity of a CPC (Z system) via adding or removing temporary capacity (On/Off CoD). +- For details on processor capacity on demand, see the \ :ref:`Capacity on Demand User's Guide `\ . + + +Requirements +------------ + +- The HMC userid must have these task permissions: 'Perform Model Conversion'. +- The HMC userid must have object-access permissions to these objects: Target CPCs. +- The CPC must be enabled for On-Off Capacity-On-Demand. + + + + +Parameters +---------- + + +hmc_host + The hostnames or IP addresses of a single HMC or of a list of redundant HMCs. A single HMC can be specified as a string type or as an HMC list with one item. An HMC list can be specified as a list type or as a string type containing a Python list representation. + + The first available HMC of a list of redundant HMCs is used for the entire execution of the module. + + | **required**: True + | **type**: raw + + +hmc_auth + The authentication credentials for the HMC. + + | **required**: True + | **type**: dict + + + userid + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . + + | **required**: False + | **type**: str + + + password + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . + + | **required**: False + | **type**: str + + + session_id + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . + + | **required**: False + | **type**: str + + + ca_certs + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + + | **required**: False + | **type**: str + + + verify + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. + + | **required**: False + | **type**: bool + | **default**: True + + + +name + The name of the target CPC. + + | **required**: True + | **type**: str + + +state + The desired state for the operation: + + \* \ :literal:`set`\ : Ensures that the CPC has the specified specialty processor capacity and the specified software model, and returns the resulting processor capacity of the CPC. + + \* \ :literal:`facts`\ : Does not change anything on the CPC and returns the current processor capacity of the CPC. + + | **required**: True + | **type**: str + | **choices**: set, facts + + +record_id + The ID of the capacity record to be used for any updates of the processor capacity. + + Required for \ :literal:`state=set`\ . + + | **required**: False + | **type**: str + + +software_model + The target software model to be active. This value must be one of the software models defined within the specified capacity record. The software model implies the number of general purpose processors that will be active. + + If null or not provided, the software model and the number of general purpose processors of the CPC will remain unchanged. + + | **required**: False + | **type**: str + + +software_model_direction + Indicates the direction of the capacity change for general purpose processors in \ :literal:`software\_model`\ , relative to the current software model: + + \* \ :literal:`increase`\ : The specified software model defines more general purpose processors than the current software model. + + \* \ :literal:`decrease`\ : The specified software model defines less general purpose processors than the current software model. + + Ignored when \ :literal:`software\_model`\ is null, not provided, or specifies the current software model. Otherwise required. + + | **required**: False + | **type**: str + | **choices**: increase, decrease + + +specialty_processors + The target number of specialty processors to be active. Processor types not provided will not be changed. Target numbers of general purpose processors can be set via the \ :literal:`software\_model`\ parameter. + + Each item in the dictionary identifies the target number of processors of one type of specialty processor. The key identifies the type of specialty processor (\ :literal:`icf`\ , \ :literal:`ifl`\ , \ :literal:`iip`\ , \ :literal:`sap`\ ), and the value is the target number of processors of that type. Note that the target number is the number of permanently activated processors plus the number of temporarily activated processors. + + The target number for each processor type may be larger, equal or lower than the current number, but it must not be lower than the number of permanent processors of that type. + + If the target number of processors is not installed in the CPC, the \ :literal:`force`\ parameter controls what happens. + + If null, empty or not provided, the specialty processor capacity will remain unchanged. + + | **required**: False + | **type**: dict + + +test_activation + Indicates that test resources instead of real resources from the capacity record should be activated. Test resources are automatically deactivated after 24h. This is mainly used for Capacity Backup Upgrade (CBU) test activations. For details, see the \ :ref:`Capacity on Demand User's Guide `\ . + + | **required**: False + | **type**: bool + + +force + Indicates that an increase of capacity should be performed even if the necessary processors are not currently installed in the CPC. + + | **required**: False + | **type**: bool + + +log_file + File path of a log file to which the logic flow of this module as well as interactions with the HMC are logged. If null, logging will be propagated to the Python root logger. + + | **required**: False + | **type**: str + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + --- + # Note: The following examples assume that some variables named 'my_*' are set. + + - name: Gather facts about the CPC processor capacity + zhmc_cpc_capacity: + hmc_host: "{{ my_hmc_host }}" + hmc_auth: "{{ my_hmc_auth }}" + name: "{{ my_cpc_name }}" + state: facts + register: cap1 + + - name: Ensure the CPC has a certain general purpose processor capacity active + zhmc_cpc_capacity: + hmc_host: "{{ my_hmc_host }}" + hmc_auth: "{{ my_hmc_auth }}" + name: "{{ my_cpc_name }}" + state: set + record_id: R1234 + software_model: "710" + register: cap1 + + - name: Ensure the CPC has a certain IFL processor capacity active + zhmc_cpc_capacity: + hmc_host: "{{ my_hmc_host }}" + hmc_auth: "{{ my_hmc_auth }}" + name: "{{ my_cpc_name }}" + state: set + record_id: R1234 + specialty_processors: + ifl: 20 + register: cap1 + + + + + + + + + + +Return Values +------------- + + +changed + Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + + | **returned**: always + | **type**: bool + +msg + An error message that describes the failure. + + | **returned**: failure + | **type**: str + +cpc + A dictionary with capacity related properties of the CPC. + + | **returned**: success + | **type**: dict + + name + CPC name + + | **type**: str + + has_temporary_capacity_change_allowed + Boolean indicating whether API applications are allowed to make changes to temporary capacity. + + | **type**: bool + + is_on_off_cod_enabled + Boolean indicating whether the On/Off Capacity on Demand feature is enabled for the CPC. + + | **type**: bool + + is_on_off_cod_installed + Boolean indicating whether an On/Off Capacity on Demand record is installed on the CPC. + + | **type**: bool + + is_on_off_cod_activated + Boolean indicating whether an On/Off Capacity on Demand record is installed and active on the CPC. + + | **type**: bool + + on_off_cod_activation_date + Timestamp when the On/Off Capacity on Demand record was activated on the CPC. + + | **type**: int + + software_model_purchased + The software model based on the originally purchased processors. Omitted for SE version below 2.16.0. + + | **type**: str + + software_model_permanent + The software model based on the permanently present processors (including any permanent capacity changes since the original purchase). + + | **type**: str + + software_model_permanent_plus_billable + The software model based on the permanently present processors plus billable temporary processors. + + | **type**: str + + software_model_permanent_plus_temporary + The software model based on the permanently present processors plus all temporary processors. + + | **type**: str + + msu_purchased + The MSU value associated with the software model based on the originally purchased processors. Omitted for SE version below 2.16.0. + + | **type**: int + + msu_permanent + The MSU value associated with the software model based on the permanently present processors (including any permanent capacity changes since the original purchase). + + | **type**: int + + msu_permanent_plus_billable + The MSU value associated with the software model based on the permanently present processors plus billable temporary processors. + + | **type**: int + + msu_permanent_plus_temporary + The MSU value associated with the software model based on the permanently present processors plus all temporary processors. + + | **type**: int + + processor_count_general_purpose + The count of active general purpose processors. + + | **type**: int + + processor_count_ifl + The count of active Integrated Facility for Linux (IFL) processors. + + | **type**: int + + processor_count_icf + The count of active Internal Coupling Facility (ICF) processors. + + | **type**: int + + processor_count_iip + The count of active IBM z Integrated Information Processor (zIIP) processors. + + | **type**: int + + processor_count_service_assist + The count of active service assist processors. + + | **type**: int + + processor_count_spare + The count of spare processors, across all processor types. + + | **type**: int + + processor_count_defective + The count of defective processors, across all processor types. + + | **type**: int + + processor_count_pending_general_purpose + The number of general purpose processors that will become active, when more processors are made available by adding new hardware or by deactivating capacity records. + + | **type**: int + + processor_count_pending_ifl + The number of Integrated Facility for Linux processors that will become active, when more processors are made available by adding new hardware or by deactivating capacity records. + + | **type**: int + + processor_count_pending_icf + The number of Integrated Coupling Facility processors that will become active, when more processors are made available by adding new hardware or by deactivating capacity records. + + | **type**: int + + processor_count_pending_iip + The number of z Integrated Information Processors that will become active, when more processors are made available by adding new hardware or by deactivating capacity records. + + | **type**: int + + processor_count_pending_service_assist + The number of service assist processors that will become active, when more processors are made available by adding new hardware or by deactivating capacity records. + + | **type**: int + + processor_count_permanent_ifl + The number of Integrated Facility for Linux processors that are permanent. Omitted for SE version below 2.16.0. + + | **type**: int + + processor_count_permanent_icf + The number of Integrated Coupling Facility processors that are permanent. Omitted for SE version below 2.16.0. + + | **type**: int + + processor_count_permanent_iip + The number of z Integrated Information Processors that are permanent. Omitted for SE version below 2.16.0. + + | **type**: int + + processor_count_permanent_service_assist + The number of service assist processors that are permanent. Omitted for SE version below 2.16.0. + + | **type**: int + + processor_count_unassigned_ifl + The number of Integrated Facility for Linux processors that are unassigned. Omitted for SE version below 2.16.0. + + | **type**: int + + processor_count_unassigned_icf + The number of Integrated Coupling Facility processors that are unassigned. Omitted for SE version below 2.16.0. + + | **type**: int + + processor_count_unassigned_iip + The number of z Integrated Information Processors that are unassigned. Omitted for SE version below 2.16.0. + + | **type**: int + + processor_count_unassigned_service_assist + The number of service assist processors that are unassigned. Omitted for SE version below 2.16.0. + + | **type**: int + + diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_cpc_list.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_cpc_list.rst.txt index dceb273a..5a71e619 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_cpc_list.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_cpc_list.rst.txt @@ -48,35 +48,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -192,7 +192,7 @@ cpcs | **type**: bool status - The current status of the CPC. For details, see the description of the 'status' property in the data model of the 'CPC' resource (see :term:\`HMC API\`). Only included for managed CPCs. + The current status of the CPC. For details, see the description of the 'status' property in the data model of the 'CPC' resource (see \ :ref:`HMC API `\ ). Only included for managed CPCs. | **type**: str diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_crypto_attachment.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_crypto_attachment.rst.txt index d169421b..03fc85c4 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_crypto_attachment.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_crypto_attachment.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_crypto_attachment_module: -zhmc_crypto_attachment -- Attach crypto resources to partitions -=============================================================== +zhmc_crypto_attachment -- Manage the crypto configuration of a partition (DPM mode) +=================================================================================== @@ -52,35 +52,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -342,7 +342,7 @@ crypto_configuration | **type**: str {property} - Additional properties of the adapter, as described in the data model of the 'Adapter' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the adapter, as described in the data model of the 'Adapter' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_hba.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_hba.rst.txt index de31eb6a..91398200 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_hba.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_hba.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_hba_module: -zhmc_hba -- Create HBAs in partitions -===================================== +zhmc_hba -- Manage an HBA of a partition (z13 only, DPM mode) +============================================================= @@ -51,35 +51,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -220,7 +220,7 @@ hba | **type**: str {property} - Additional properties of the HBA, as described in the data model of the 'HBA' element object of the 'Partition' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the HBA, as described in the data model of the 'HBA' element object of the 'Partition' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_ldap_server_definition.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_ldap_server_definition.rst.txt index b93dda77..7c43dae6 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_ldap_server_definition.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_ldap_server_definition.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_ldap_server_definition_module: -zhmc_ldap_server_definition -- Manage LDAP Server Definitions -============================================================= +zhmc_ldap_server_definition -- Manage an LDAP Server Definition on the HMC +========================================================================== @@ -49,35 +49,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -115,7 +115,7 @@ properties \* \ :literal:`name`\ : Cannot be specified because the name has already been specified in the \ :literal:`name`\ module parameter. - Properties omitted in this dictionary will remain unchanged when the LDAP Server Definition already exists, and will get the default value defined in the data model for LDAP Server Definitions in the :term:\`HMC API\` when the LDAP Server Definition is being created. + Properties omitted in this dictionary will remain unchanged when the LDAP Server Definition already exists, and will get the default value defined in the data model for LDAP Server Definitions in the \ :ref:`HMC API `\ book when the LDAP Server Definition is being created. | **required**: False | **type**: dict @@ -228,7 +228,7 @@ ldap_server_definition | **type**: str {property} - Additional properties of the LDAP Server Definition, as described in the data model of the 'LDAP Server Definition' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the LDAP Server Definition, as described in the data model of the 'LDAP Server Definition' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_ldap_server_definition_list.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_ldap_server_definition_list.rst.txt index bd207f73..ef645ebf 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_ldap_server_definition_list.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_ldap_server_definition_list.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_ldap_server_definition_list_module: -zhmc_ldap_server_definition_list -- List LDAP Server Definitions -================================================================ +zhmc_ldap_server_definition_list -- List LDAP Server Definitions on the HMC +=========================================================================== @@ -48,35 +48,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar.rst.txt index a7d2d686..c0a78635 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_lpar_module: -zhmc_lpar -- Manage LPARs -========================= +zhmc_lpar -- Manage an LPAR (classic mode) +========================================== @@ -55,35 +55,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -208,13 +208,33 @@ store_status_indicator timeout - Timeout in seconds, for activate (if needed) and for load (if needed). + Timeout in seconds, for the HMC operation to complete, for \ :literal:`state=inactive`\ , \ :literal:`state=active`\ and \ :literal:`state=loaded`\ . | **required**: False | **type**: int | **default**: 60 +status_timeout + Timeout in seconds, for reaching the desired status after the HMC operation completed, for \ :literal:`state=inactive`\ , \ :literal:`state=active`\ and \ :literal:`state=loaded`\ . + + | **required**: False + | **type**: int + | **default**: 60 + + +allow_status_exceptions + Controls whether LPAR status 'exceptions' is considered an additional acceptable end status: + + If True (default), it is considered acceptable, and the module returns once that status (or one of the other desired end states) is reached. + + If False, it is not considered acceptable, and the module keeps waiting for one of the other desired end states to be reached. + + | **required**: False + | **type**: bool + | **default**: True + + force Controls whether operations that change the LPAR status are performed when the LPAR is currently loaded (i.e. status 'operating' or 'exceptions'): @@ -372,7 +392,7 @@ lpar For \ :literal:`state=active|loaded|set|facts`\ , the resource properties of the LPAR after after any specified updates have been applied. - Note that the returned properties may show different values than the ones that were specified as input for the update. For example, memory properties may be rounded up, hexadecimal strings may be shown with a different representation format, and other properties may change as a result of updating some properties. For details, see the data model of the 'Logical Partition' object in the :term:\`HMC API\` book. + Note that the returned properties may show different values than the ones that were specified as input for the update. For example, memory properties may be rounded up, hexadecimal strings may be shown with a different representation format, and other properties may change as a result of updating some properties. For details, see the data model of the 'Logical Partition' object in the \ :ref:`HMC API `\ book. | **returned**: success | **type**: dict @@ -540,7 +560,7 @@ lpar | **type**: str {property} - Additional properties of the LPAR, as described in the data model of the 'Logical Partition' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the LPAR, as described in the data model of the 'Logical Partition' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar_command.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar_command.rst.txt new file mode 100644 index 00000000..fec81ee8 --- /dev/null +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar_command.rst.txt @@ -0,0 +1,197 @@ + +:github_url: https://github.com/ansible-collections/ibm_zos_core/blob/dev/plugins/modules/zhmc_lpar_command.py + +.. _zhmc_lpar_command_module: + + +zhmc_lpar_command -- Execute OS console command in an LPAR (classic mode) +========================================================================= + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Execute a command in the console of the OS running in an LPAR and get back the command output. +- Note: The OS console interface provided by the HMC WS-API does not allow separating multiple concurrent interactions. For example, when OS console commands are executed via the HMC GUI at the same time when executing this Ansible module, the command output returned by the Ansible module may be mixed with output from the concurrently executed command. +- Note: The logic for determining which lines on the OS console belong to the executed command is as follows: The OS console messages are started to be captured just before the console command is sent. The captured console messages are then searched for the occurrence of the command. The command itself and all messages following the command are considered part of the command output, until there are no more new messages for 2 seconds. If there is a lot of traffic on the OS console, that may lead to other messages being included in the command output. + + +Requirements +------------ + +- The targeted CPC must be in the classic operational mode. +- The targeted LPAR must be loaded (i.e. running an operating system). +- The HMC userid must have these task permissions: 'Operating System Messages' (view-only is sufficient) +- The HMC userid must have object-access permissions to these objects: Target CPC, target LPAR. + + + + +Parameters +---------- + + +hmc_host + The hostnames or IP addresses of a single HMC or of a list of redundant HMCs. A single HMC can be specified as a string type or as an HMC list with one item. An HMC list can be specified as a list type or as a string type containing a Python list representation. + + The first available HMC of a list of redundant HMCs is used for the entire execution of the module. + + | **required**: True + | **type**: raw + + +hmc_auth + The authentication credentials for the HMC. + + | **required**: True + | **type**: dict + + + userid + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . + + | **required**: False + | **type**: str + + + password + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . + + | **required**: False + | **type**: str + + + session_id + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . + + | **required**: False + | **type**: str + + + ca_certs + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + + | **required**: False + | **type**: str + + + verify + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. + + | **required**: False + | **type**: bool + | **default**: True + + + +cpc_name + The name of the CPC with the target LPAR. + + | **required**: True + | **type**: str + + +name + The name of the target LPAR. + + | **required**: True + | **type**: str + + +command + The OS console command to be executed. + + | **required**: True + | **type**: str + + +is_priority + Controls whether the command is executed as a priority command. + + | **required**: False + | **type**: bool + + +log_file + File path of a log file to which the logic flow of this module as well as interactions with the HMC are logged. If null, logging will be propagated to the Python root logger. + + | **required**: False + | **type**: str + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + --- + # Note: The following examples assume that some variables named 'my_*' are set. + + - name: Get z/OS system time via OS console command + zhmc_lpar_command: + hmc_host: "{{ my_hmc_host }}" + hmc_auth: "{{ my_hmc_auth }}" + cpc_name: "{{ my_cpc_name }}" + name: "{{ my_lpar_name }}" + command: "D T" + register: zos_time_output + + + + + + + + + + +Return Values +------------- + + +changed + Indicates if any change has been made by the module. + + This will always be true, because it is not clear whether the command has performed a change. Note that a playbook using this module with a command that does not perform a change can override that by specifying \ :literal:`changed\_when: false`\ . + + | **returned**: always + | **type**: bool + +msg + An error message that describes the failure. + + | **returned**: failure + | **type**: str + +output + The command and its output, as one item per line, without any trailing newlines. + + The format of each message text depends on the type of OS. Typical formats are, showing the message with the command: + + z/VM: \ :literal:`04:30:02 Q CPLEVEL`\ + + z/OS: \ :literal:`D T`\ + + Linux: \ :literal:`uname -a`\ + + | **returned**: success + | **type**: list + | **elements**: str + | **sample**: + + .. code-block:: json + + [ + "D T", + "RESPONSE=GR1 IEE136I LOCAL: TIME=09.25.08 DATE=2024.194 UTC:", + "RESPONSE=TIME=07.25.08 DATE=2024.194" + ] + diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar_list.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar_list.rst.txt index 1866ce12..3220f9b4 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar_list.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar_list.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_lpar_list_module: -zhmc_lpar_list -- List LPARs -============================ +zhmc_lpar_list -- List LPARs (classic mode) +=========================================== @@ -51,35 +51,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -214,7 +214,7 @@ lpars | **type**: str status - The current status of the LPAR. For details, see the description of the 'status' property in the data model of the 'Logical Partition' resource (see :term:\`HMC API\`). + The current status of the LPAR. For details, see the description of the 'status' property in the data model of the 'Logical Partition' resource (see \ :ref:`HMC API `\ ). | **type**: str @@ -224,7 +224,7 @@ lpars | **type**: bool activation_mode - The activation mode of the LPAR. For details, see the description of the 'activation-mode' property in the data model of the 'Logical Partition' resource (see :term:\`HMC API\`). + The activation mode of the LPAR. For details, see the description of the 'activation-mode' property in the data model of the 'Logical Partition' resource (see \ :ref:`HMC API `\ ). | **type**: str diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar_messages.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar_messages.rst.txt index 6bab51e5..32f50938 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar_messages.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_lpar_messages.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_lpar_messages_module: -zhmc_lpar_messages -- Get console messages for OS in an LPAR -============================================================ +zhmc_lpar_messages -- Get console messages for OS in an LPAR (classic mode) +=========================================================================== @@ -51,35 +51,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -281,7 +281,7 @@ messages | **type**: str os_name - The name of the operating system that generated this omessage, or null indicating there is no operating system name associated with this message. + The name of the operating system that generated this message, or null indicating there is no operating system name associated with this message. This name is determined by the operating system and may be unrelated to the name of the LPAR in which the operating system is running. diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_nic.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_nic.rst.txt index c205fd73..7c0dd977 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_nic.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_nic.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_nic_module: -zhmc_nic -- Create NICs in partitions -===================================== +zhmc_nic -- Manage a NIC of a partition (DPM mode) +================================================== @@ -52,35 +52,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -258,7 +258,7 @@ nic | **type**: str {property} - Additional properties of the NIC, as described in the data model of the 'NIC' element object of the 'Partition' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the NIC, as described in the data model of the 'NIC' element object of the 'Partition' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_nic_list.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_nic_list.rst.txt index b44733ee..0f757235 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_nic_list.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_nic_list.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_nic_list_module: -zhmc_nic_list -- List NICs -========================== +zhmc_nic_list -- List NICs of a partition (DPM mode) +==================================================== @@ -48,35 +48,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition.rst.txt index 4ef706c3..539115c9 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_partition_module: -zhmc_partition -- Create partitions -=================================== +zhmc_partition -- Manage a partition (DPM mode) +=============================================== @@ -52,35 +52,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -113,7 +113,7 @@ state \* \ :literal:`mount\_iso`\ : Ensures that an ISO image with the specified name is mounted to the partition, and that the specified INS file is set. The content of a currnetly mounted ISO image is not verified. - \* \ :literal:`unmount\_iso`\ : Ensures that no ISO image is mounted to the partition. + \* \ :literal:`unmount\_iso`\ : Ensures that no ISO image is unmounted to the partition. \* \ :literal:`facts`\ : Returns the partition properties and the properties of its child resources (HBAs, NICs, and virtual functions). @@ -159,9 +159,9 @@ properties \* \ :literal:`boot\_network\_nic\_name`\ : The name of the NIC whose URI is used to construct \ :literal:`boot\_network\_device`\ . Specifying it requires that the partition exists. - \* \ :literal:`crypto\_configuration`\ : The crypto configuration for the partition, in the format of the \ :literal:`crypto-configuration`\ property of the partition (see :term:\`HMC API\` for details), with the exception that adapters are specified with their names in field \ :literal:`crypto\_adapter\_names`\ instead of their URIs in field \ :literal:`crypto\_adapter\_uris`\ . If the \ :literal:`crypto\_adapter\_names`\ field is null, all crypto adapters of the CPC will be used. + \* \ :literal:`crypto\_configuration`\ : The crypto configuration for the partition, in the format of the \ :literal:`crypto-configuration`\ property of the partition (see \ :ref:`HMC API `\ for details), with the exception that adapters are specified with their names in field \ :literal:`crypto\_adapter\_names`\ instead of their URIs in field \ :literal:`crypto\_adapter\_uris`\ . If the \ :literal:`crypto\_adapter\_names`\ field is null, all crypto adapters of the CPC will be used. - Properties omitted in this dictionary will remain unchanged when the partition already exists, and will get the default value defined in the data model for partitions in the :term:\`HMC API\` when the partition is being created. + Properties omitted in this dictionary will remain unchanged when the partition already exists, and will get the default value defined in the data model for partitions in the \ :ref:`HMC API `\ book when the partition is being created. | **required**: False | **type**: dict @@ -199,14 +199,14 @@ ins_file expand_storage_groups - Boolean that controls whether the returned partition contains an additional artificial property 'storage-groups' that is the list of storage groups attached to the partition, with properties as described for the zhmc\_storage\_group module with expand=true. + Boolean that controls whether the returned partition contains an additional artificial property \ :literal:`partition.storage-groups`\ that is the list of storage groups attached to the partition, with properties as described for the zhmc\_storage\_group module with \ :literal:`expand=true`\ . | **required**: False | **type**: bool expand_crypto_adapters - Boolean that controls whether the returned partition contains an additional artificial property 'crypto-adapters' in its 'crypto-configuration' property that is the list of crypto adapters attached to the partition, with properties as described for the zhmc\_adapter module. + Boolean that controls whether the returned partition contains an additional artificial property \ :literal:`crypto-adapters`\ in its \ :literal:`crypto-configuration`\ property that is the list of crypto adapters attached to the partition, with properties as described for the zhmc\_adapter module. | **required**: False | **type**: bool @@ -515,7 +515,7 @@ partition | **type**: str {property} - Additional properties of the partition, as described in the data model of the 'Partition' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the partition, as described in the data model of the 'Partition' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw @@ -531,7 +531,7 @@ partition | **type**: str {property} - Additional properties of the HBA, as described in the data model of the 'HBA' element object of the 'Partition' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the HBA, as described in the data model of the 'HBA' element object of the 'Partition' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw @@ -548,7 +548,7 @@ partition | **type**: str {property} - Additional properties of the NIC, as described in the data model of the 'NIC' element object of the 'Partition' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the NIC, as described in the data model of the 'NIC' element object of the 'Partition' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw @@ -565,7 +565,24 @@ partition | **type**: str {property} - Additional properties of the virtual function, as described in the data model of the 'Virtual Function' element object of the 'Partition' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the virtual function, as described in the data model of the 'Virtual Function' element object of the 'Partition' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. + + | **type**: raw + + + storage-groups + Storage groups attached to the partition. Only present for \ :literal:`expand\_storage\_groups=true`\ . + + | **type**: list + | **elements**: dict + + name + Storage group name + + | **type**: str + + {property} + Additional properties of the storage group, as described for the zhmc\_storage\_group module with \ :literal:`expand=true`\ . | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition_command.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition_command.rst.txt new file mode 100644 index 00000000..8094469f --- /dev/null +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition_command.rst.txt @@ -0,0 +1,196 @@ + +:github_url: https://github.com/ansible-collections/ibm_zos_core/blob/dev/plugins/modules/zhmc_partition_command.py + +.. _zhmc_partition_command_module: + + +zhmc_partition_command -- Execute OS console command in a partition (DPM mode) +============================================================================== + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Execute a command in the console of the OS running in a partition and get back the command output. +- Note: The OS console interface provided by the HMC WS-API does not allow separating multiple concurrent interactions. For example, when OS console commands are executed via the HMC GUI at the same time when executing this Ansible module, the command output returned by the Ansible module may be mixed with output from the concurrently executed command. +- Note: The logic for determining which lines on the OS console belong to the executed command is as follows: The OS console messages are started to be captured just before the console command is sent. The captured console messages are then searched for the occurrence of the command. The command itself and all messages following the command are considered part of the command output, until there are no more new messages for 2 seconds. If there is a lot of traffic on the OS console, that may lead to other messages being included in the command output. + + +Requirements +------------ + +- The targeted CPC must be in the DPM operational mode. +- The targeted partition must be active (i.e. running an operating system). +- The HMC userid must have these task permissions: 'Operating System Messages' (view-only is sufficient) +- The HMC userid must have object-access permissions to these objects: Target CPC, target partition. + + + + +Parameters +---------- + + +hmc_host + The hostnames or IP addresses of a single HMC or of a list of redundant HMCs. A single HMC can be specified as a string type or as an HMC list with one item. An HMC list can be specified as a list type or as a string type containing a Python list representation. + + The first available HMC of a list of redundant HMCs is used for the entire execution of the module. + + | **required**: True + | **type**: raw + + +hmc_auth + The authentication credentials for the HMC. + + | **required**: True + | **type**: dict + + + userid + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . + + | **required**: False + | **type**: str + + + password + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . + + | **required**: False + | **type**: str + + + session_id + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . + + | **required**: False + | **type**: str + + + ca_certs + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + + | **required**: False + | **type**: str + + + verify + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. + + | **required**: False + | **type**: bool + | **default**: True + + + +cpc_name + The name of the CPC with the target partition. + + | **required**: True + | **type**: str + + +name + The name of the target partition. + + | **required**: True + | **type**: str + + +command + The OS console command to be executed. + + | **required**: True + | **type**: str + + +is_priority + Controls whether the command is executed as a priority command. + + | **required**: False + | **type**: bool + + +log_file + File path of a log file to which the logic flow of this module as well as interactions with the HMC are logged. If null, logging will be propagated to the Python root logger. + + | **required**: False + | **type**: str + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + --- + # Note: The following examples assume that some variables named 'my_*' are set. + + - name: Get z/VM CP level via OS console command + zhmc_partition_command: + hmc_host: "{{ my_hmc_host }}" + hmc_auth: "{{ my_hmc_auth }}" + cpc_name: "{{ my_cpc_name }}" + name: "{{ my_partition_name }}" + command: "Q CPLEVEL" + register: zvm_cplevel_output + + + + + + + + + + +Return Values +------------- + + +changed + Indicates if any change has been made by the module. + + This will always be true, because it is not clear whether the command has performed a change. Note that a playbook using this module with a command that does not perform a change can override that by specifying \ :literal:`changed\_when: false`\ . + + | **returned**: always + | **type**: bool + +msg + An error message that describes the failure. + + | **returned**: failure + | **type**: str + +output + The command and its output, as one item per line, without any trailing newlines. + + The format of each message text depends on the type of OS. Typical formats are, showing the message with the command: + + z/VM: \ :literal:`04:30:02 Q CPLEVEL`\ + + Linux: \ :literal:`uname -a`\ + + | **returned**: success + | **type**: list + | **elements**: str + | **sample**: + + .. code-block:: json + + [ + "04:30:02 Q CPLEVEL", + "04:30:02 z/VM Version 7 Release 2.0, service level 2101 (64-bit)", + "04:30:02 Generated at 05/19/21 10:00:00 CES", + "04:30:02 IPL at 06/04/24 19:18:57 CES" + ] + diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition_list.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition_list.rst.txt index c0c55ea8..320b3fa2 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition_list.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition_list.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_partition_list_module: -zhmc_partition_list -- List partitions -====================================== +zhmc_partition_list -- List partitions (DPM mode) +================================================= @@ -51,35 +51,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -219,7 +219,7 @@ partitions | **type**: str status - The current status of the partition. For details, see the description of the 'status' property in the data model of the 'Logical Partition' resource (see :term:\`HMC API\`). + The current status of the partition. For details, see the description of the 'status' property in the data model of the 'Logical Partition' resource (see \ :ref:`HMC API `\ ). | **type**: str diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition_messages.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition_messages.rst.txt index 5acdd12c..65f40fc9 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition_messages.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_partition_messages.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_partition_messages_module: -zhmc_partition_messages -- Get console messages for OS in a partition -===================================================================== +zhmc_partition_messages -- Get console messages for OS in a partition (DPM mode) +================================================================================ @@ -51,35 +51,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -254,7 +254,7 @@ messages | **type**: str os_name - The name of the operating system that generated this omessage, or null indicating there is no operating system name associated with this message. + The name of the operating system that generated this message, or null indicating there is no operating system name associated with this message. This name is determined by the operating system and may be unrelated to the name of the partition in which the operating system is running. diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_password_rule.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_password_rule.rst.txt index 4c690ad6..ec00da60 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_password_rule.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_password_rule.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_password_rule_module: -zhmc_password_rule -- Create HMC password rules -=============================================== +zhmc_password_rule -- Manage an HMC password rule +================================================= @@ -49,35 +49,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -113,7 +113,7 @@ properties \* \ :literal:`name`\ : Cannot be specified because the name has already been specified in the \ :literal:`name`\ module parameter. - Properties omitted in this dictionary will remain unchanged when the password rule already exists, and will get the default value defined in the data model for password rules in the :term:\`HMC API\` when the password rule is being created. + Properties omitted in this dictionary will remain unchanged when the password rule already exists, and will get the default value defined in the data model for password rules in the \ :ref:`HMC API `\ book when the password rule is being created. | **required**: False | **type**: dict @@ -248,7 +248,7 @@ password_rule | **type**: str {property} - Additional properties of the password rule, as described in the data model of the 'Password Rule' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the password rule, as described in the data model of the 'Password Rule' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_password_rule_list.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_password_rule_list.rst.txt index 977ab517..9b56f3a3 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_password_rule_list.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_password_rule_list.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_password_rule_list_module: -zhmc_password_rule_list -- List Password Rules -============================================== +zhmc_password_rule_list -- List HMC password rules +================================================== @@ -48,35 +48,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_session.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_session.rst.txt index dc0827b6..5fe26756 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_session.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_session.rst.txt @@ -73,7 +73,7 @@ hmc_auth ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. Optional for \ :literal:`action=create`\ , not permitted for \ :literal:`action=delete`\ . @@ -82,7 +82,7 @@ hmc_auth verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. Optional for \ :literal:`action=create`\ , not permitted for \ :literal:`action=delete`\ . @@ -175,7 +175,7 @@ msg | **type**: str hmc_host - The hostname or IP address of the HMC that was actually used for the session creation, for \ :literal:`action=create`\ . This value must be specified as 'hmc\_host' for \ :literal:`action=delete`\ . + The hostname or IP address of the HMC that was actually used for the session creation, for \ :literal:`action=create`\ . This value must be specified as \ :literal:`hmc\_host`\ for \ :literal:`action=delete`\ . For \ :literal:`action=delete`\ , returns the null value. @@ -203,12 +203,12 @@ hmc_auth | **type**: str ca_certs - Value of \ :literal:`ca\_certs`\ input parameter for \ :literal:`action=create`\ , or null for \ :literal:`action=delete`\ . + Value of \ :literal:`hmc\_auth.ca\_certs`\ input parameter for \ :literal:`action=create`\ , or null for \ :literal:`action=delete`\ . | **type**: str verify - Value of \ :literal:`verify`\ input parameter for \ :literal:`action=create`\ , or null for \ :literal:`action=delete`\ . + Value of \ :literal:`hmc\_auth.verify`\ input parameter for \ :literal:`action=create`\ , or null for \ :literal:`action=delete`\ . | **type**: bool diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group.rst.txt index f9c671b2..2f792e79 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_storage_group_module: -zhmc_storage_group -- Create storage groups -=========================================== +zhmc_storage_group -- Manage a storage group (DPM mode) +======================================================= @@ -51,35 +51,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -126,7 +126,7 @@ properties \* \ :literal:`type`\ : Cannot be changed once the storage group exists. - Properties omitted in this dictionary will remain unchanged when the storage group already exists, and will get the default value defined in the data model for storage groups in the :term:\`HMC API\` when the storage group is being created. + Properties omitted in this dictionary will remain unchanged when the storage group already exists, and will get the default value defined in the data model for storage groups in the \ :ref:`HMC API `\ book when the storage group is being created. | **required**: False | **type**: dict @@ -473,7 +473,7 @@ storage_group | **type**: str {property} - Additional properties of the storage group, as described in the data model of the 'Storage Group' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the storage group, as described in the data model of the 'Storage Group' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw @@ -501,7 +501,7 @@ storage_group | **type**: int {property} - Additional properties of the storage port, as described in the data model of the 'Storage Port' element object of the 'Adapter' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the storage port, as described in the data model of the 'Storage Port' element object of the 'Adapter' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw @@ -516,7 +516,7 @@ storage_group | **type**: str {property} - Additional properties of the storage adapter, as described in the data model of the 'Adapter' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the storage adapter, as described in the data model of the 'Adapter' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw @@ -535,7 +535,7 @@ storage_group | **type**: str {property} - Additional properties of the storage volume, as described in the data model of the 'Storage Volume' element object of the 'Storage Group' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the storage volume, as described in the data model of the 'Storage Volume' element object of the 'Storage Group' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw @@ -548,7 +548,7 @@ storage_group | **elements**: dict {property} - Properties of the virtual storage resource, as described in the data model of the 'Virtual Storage Resource' element object of the 'Storage Group' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Properties of the virtual storage resource, as described in the data model of the 'Virtual Storage Resource' element object of the 'Storage Group' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw @@ -561,7 +561,7 @@ storage_group | **elements**: dict {property} - Properties of the partition, as described in the data model of the 'Partition' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Properties of the partition, as described in the data model of the 'Partition' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group_attachment.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group_attachment.rst.txt index dd15831b..b7b964c7 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group_attachment.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group_attachment.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_storage_group_attachment_module: -zhmc_storage_group_attachment -- Attach storage groups to partitions -==================================================================== +zhmc_storage_group_attachment -- Manage attachment of a storage group to a partition (DPM mode) +=============================================================================================== @@ -51,35 +51,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_storage_volume.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_storage_volume.rst.txt index 8f7f2fc1..c65d3544 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_storage_volume.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_storage_volume.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_storage_volume_module: -zhmc_storage_volume -- Create storage volumes -============================================= +zhmc_storage_volume -- Manage a storage volume (DPM mode) +========================================================= @@ -51,35 +51,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -129,7 +129,7 @@ properties \* \ :literal:`name`\ : Cannot be specified because the name has already been specified in the \ :literal:`name`\ module parameter. - Properties omitted in this dictionary will remain unchanged when the storage volume already exists, and will get the default value defined in the data model for storage volumes in the :term:\`HMC API\` when the storage volume is being created. + Properties omitted in this dictionary will remain unchanged when the storage volume already exists, and will get the default value defined in the data model for storage volumes in the \ :ref:`HMC API `\ book when the storage volume is being created. | **required**: False | **type**: dict @@ -256,12 +256,12 @@ storage_volume | **type**: str type - Type of the storage volume ('fc' or 'fcp'), as defined in its storage group. + Type of the storage volume (\ :literal:`fc`\ or \ :literal:`fcp`\ ), as defined in its storage group. | **type**: str {property} - Additional properties of the storage volume, as described in the data model of the 'Storage Volume' element object of the 'Storage Group' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the storage volume, as described in the data model of the 'Storage Volume' element object of the 'Storage Group' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user.rst.txt index b62905e9..80758405 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_user_module: -zhmc_user -- Create HMC users -============================= +zhmc_user -- Manage an HMC user +=============================== @@ -50,35 +50,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -126,7 +126,7 @@ properties \* \ :literal:`default\_group\_uri`\ : Cannot be set directly, but indirectly via the artificial property \ :literal:`default\_group\_name`\ . - Properties omitted in this dictionary will remain unchanged when the user already exists, and will get the default value defined in the data model for users in the :term:\`HMC API\` when the user is being created. + Properties omitted in this dictionary will remain unchanged when the user already exists, and will get the default value defined in the data model for users in the \ :ref:`HMC API `\ book when the user is being created. | **required**: False | **type**: dict @@ -277,7 +277,7 @@ user | **type**: str {property} - Additional properties of the user, as described in the data model of the 'User' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the user, as described in the data model of the 'User' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw @@ -294,7 +294,7 @@ user | **type**: dict {property} - Properties of the user role, as described in the data model of the 'User Pattern' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Properties of the user role, as described in the data model of the 'User Pattern' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw @@ -312,7 +312,7 @@ user | **type**: dict {property} - Properties of the user pattern, as described in the data model of the 'User Pattern' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Properties of the user pattern, as described in the data model of the 'User Pattern' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw @@ -330,7 +330,7 @@ user | **type**: dict {property} - Properties of the password rule, as described in the data model of the 'Password Rule' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Properties of the password rule, as described in the data model of the 'Password Rule' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw @@ -348,7 +348,7 @@ user | **type**: dict {property} - Properties of the LDAP server definition, as described in the data model of the 'LDAP Server Definition' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Properties of the LDAP server definition, as described in the data model of the 'LDAP Server Definition' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_list.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_list.rst.txt index 4dbeb0f5..be221bd5 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_list.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_list.rst.txt @@ -48,35 +48,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -169,7 +169,7 @@ users | **type**: str type - Type of the user ('standard', 'template', 'pattern-based', 'system-defined') + Type of the user (\ :literal:`standard`\ , \ :literal:`template`\ , \ :literal:`pattern-based`\ , \ :literal:`system-defined`\ ) | **type**: str diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_pattern.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_pattern.rst.txt new file mode 100644 index 00000000..db96d454 --- /dev/null +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_pattern.rst.txt @@ -0,0 +1,288 @@ + +:github_url: https://github.com/ansible-collections/ibm_zos_core/blob/dev/plugins/modules/zhmc_user_pattern.py + +.. _zhmc_user_pattern_module: + + +zhmc_user_pattern -- Manage an HMC user pattern +=============================================== + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Gather facts about a user pattern on an HMC of a Z system. +- Create, delete, or update a user pattern on an HMC. + + +Requirements +------------ + +- The HMC userid must have these task permissions: 'Manage User Patterns'. + + + + +Parameters +---------- + + +hmc_host + The hostnames or IP addresses of a single HMC or of a list of redundant HMCs. A single HMC can be specified as a string type or as an HMC list with one item. An HMC list can be specified as a list type or as a string type containing a Python list representation. + + The first available HMC of a list of redundant HMCs is used for the entire execution of the module. + + | **required**: True + | **type**: raw + + +hmc_auth + The authentication credentials for the HMC. + + | **required**: True + | **type**: dict + + + userid + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . + + | **required**: False + | **type**: str + + + password + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . + + | **required**: False + | **type**: str + + + session_id + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . + + | **required**: False + | **type**: str + + + ca_certs + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + + | **required**: False + | **type**: str + + + verify + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. + + | **required**: False + | **type**: bool + | **default**: True + + + +name + The name of the target user pattern. + + | **required**: True + | **type**: str + + +state + The desired state for the HMC user pattern. All states are fully idempotent within the limits of the properties that can be changed: + + \* \ :literal:`absent`\ : Ensures that the user pattern does not exist. + + \* \ :literal:`present`\ : Ensures that the user pattern exists and has the specified properties. + + \* \ :literal:`facts`\ : Returns the user pattern properties. + + | **required**: True + | **type**: str + | **choices**: absent, present, facts + + +properties + Dictionary with desired properties for the user pattern. Used for \ :literal:`state=present`\ ; ignored for \ :literal:`state=absent|facts`\ . Dictionary key is the property name with underscores instead of hyphens, and dictionary value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. + + The possible input properties in this dictionary are the properties defined as writeable in the data model for User Pattern resources (where the property names contain underscores instead of hyphens), with the following exceptions: + + \* \ :literal:`name`\ : Cannot be specified because the name has already been specified in the \ :literal:`name`\ module parameter. + + \* \ :literal:`...\_uri`\ : Cannot be set directly, but indirectly via the corresponding artificial property \ :literal:`...\_name`\ . An empty string for the name will set the URI to null. + + Properties omitted in this dictionary will remain unchanged when the user pattern already exists, and will get the default value defined in the data model for user patterns in the \ :ref:`HMC API `\ book when the user pattern is being created. + + | **required**: False + | **type**: dict + + +log_file + File path of a log file to which the logic flow of this module as well as interactions with the HMC are logged. If null, logging will be propagated to the Python root logger. + + | **required**: False + | **type**: str + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + --- + # Note: The following examples assume that some variables named 'my_*' are set. + + - name: Gather facts about a user pattern + zhmc_user_pattern: + hmc_host: "{{ my_hmc_host }}" + hmc_auth: "{{ my_hmc_auth }}" + name: "{{ my_user_pattern_name }}" + state: facts + register: userpattern1 + + - name: Ensure the user pattern does not exist + zhmc_user_pattern: + hmc_host: "{{ my_hmc_host }}" + hmc_auth: "{{ my_hmc_auth }}" + name: "{{ my_user_pattern_name }}" + state: absent + + - name: Ensure the user pattern exists and has certain properties + zhmc_user_pattern: + hmc_host: "{{ my_hmc_host }}" + hmc_auth: "{{ my_hmc_auth }}" + name: "{{ my_user_pattern_name }}" + state: present + properties: + description: "Example user pattern 1" + register: userpattern1 + + + + + + + + + + +Return Values +------------- + + +changed + Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + + | **returned**: always + | **type**: bool + +msg + An error message that describes the failure. + + | **returned**: failure + | **type**: str + +user_pattern + For \ :literal:`state=absent`\ , an empty dictionary. + + For \ :literal:`state=present|facts`\ , a dictionary with the resource properties of the target user pattern and some additional artificial properties. + + | **returned**: success + | **type**: dict + | **sample**: + + .. code-block:: json + + { + "class": "user-pattern", + "description": "A pattern that matches a bluepages email address.", + "domain_name_restrictions": null, + "domain_name_restrictions_ldap_server_definition_name": null, + "domain_name_restrictions_ldap_server_definition_uri": null, + "element_id": "cbcaf7a0-46cc-11e9-bfd3-f44a39cd42f9", + "element_uri": "/api/console/user-patterns/cbcaf7a0-46cc-11e9-bfd3-f44a39cd42f9", + "ldap_group_default_template_name": null, + "ldap_group_default_template_uri": null, + "ldap_group_ldap_server_definition_name": null, + "ldap_group_ldap_server_definition_uri": null, + "ldap_group_to_template_mappings": null, + "ldap_server_definition_name": null, + "ldap_server_definition_uri": null, + "name": "Bluepages email address", + "parent": "/api/console", + "pattern": "*@*ibm.com", + "replication_overwrite_possible": false, + "retention_time": 90, + "search_order_index": 0, + "specific_template_name": "Product Engineering and Access Administrator", + "specific_template_uri": "/api/users/97769500-4a81-11e9-aa1b-00106f23f636", + "template_name_override": null, + "template_name_override_default_template_name": null, + "template_name_override_default_template_uri": null, + "template_name_override_ldap_server_definition_name": null, + "template_name_override_ldap_server_definition_uri": null, + "type": "glob-like", + "user_template_name": "Product Engineering and Access Administrator", + "user_template_uri": "/api/users/97769500-4a81-11e9-aa1b-00106f23f636" + } + + name + User Pattern name + + | **type**: str + + {property} + Additional properties of the user pattern, as described in the data model of the 'User Pattern' object in the \ :ref:`HMC API `\ book. The property names will have underscores instead of hyphens. + + The items in the \ :literal:`ldap\_group\_to\_template\_mappings`\ property have an additional item \ :literal:`template-name`\ which is the name of the resource object referenced by \ :literal:`template-uri`\ . + + | **type**: raw + + domain_name_restrictions_ldap_server_definition_name + Name of the resource object referenced by the corresponding ...\_uri property. + + | **type**: str + + ldap_group_default_template_name + Name of the resource object referenced by the corresponding ...\_uri property. + + | **type**: str + + ldap_group_ldap_server_definition_name + Name of the resource object referenced by the corresponding ...\_uri property. + + | **type**: str + + ldap_server_definition_name + Name of the resource object referenced by the corresponding ...\_uri property. + + | **type**: str + + specific_template_name + Name of the resource object referenced by the corresponding ...\_uri property. + + | **type**: str + + template_name_override_default_template_name + Name of the resource object referenced by the corresponding ...\_uri property. + + | **type**: str + + template_name_override_ldap_server_definition_name + Name of the resource object referenced by the corresponding ...\_uri property. + + | **type**: str + + user_template_name + Name of the resource object referenced by the corresponding ...\_uri property. + + | **type**: str + + diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_pattern_list.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_pattern_list.rst.txt new file mode 100644 index 00000000..0b154866 --- /dev/null +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_pattern_list.rst.txt @@ -0,0 +1,192 @@ + +:github_url: https://github.com/ansible-collections/ibm_zos_core/blob/dev/plugins/modules/zhmc_user_pattern_list.py + +.. _zhmc_user_pattern_list_module: + + +zhmc_user_pattern_list -- List HMC user patterns +================================================ + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- List User Patterns on the HMC. + + +Requirements +------------ + +- The HMC userid must have object-access permission to the User Pattern objects included in the result, or task permission to the 'Manage User Patterns' task. + + + + +Parameters +---------- + + +hmc_host + The hostnames or IP addresses of a single HMC or of a list of redundant HMCs. A single HMC can be specified as a string type or as an HMC list with one item. An HMC list can be specified as a list type or as a string type containing a Python list representation. + + The first available HMC of a list of redundant HMCs is used for the entire execution of the module. + + | **required**: True + | **type**: raw + + +hmc_auth + The authentication credentials for the HMC. + + | **required**: True + | **type**: dict + + + userid + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . + + | **required**: False + | **type**: str + + + password + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . + + | **required**: False + | **type**: str + + + session_id + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . + + | **required**: False + | **type**: str + + + ca_certs + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + + | **required**: False + | **type**: str + + + verify + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. + + | **required**: False + | **type**: bool + | **default**: True + + + +full_properties + If True, all properties of each user pattern will be returned. Default: False. + + Note: Setting this to True causes a loop of 'Get User Pattern Properties' operations to be executed. + + | **required**: False + | **type**: bool + + +log_file + File path of a log file to which the logic flow of this module as well as interactions with the HMC are logged. If null, logging will be propagated to the Python root logger. + + | **required**: False + | **type**: str + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + --- + # Note: The following examples assume that some variables named 'my_*' are set. + + - name: List User Patterns + zhmc_user_pattern_list: + hmc_host: "{{ my_hmc_host }}" + hmc_auth: "{{ my_hmc_auth }}" + register: upattern_list + + + + + + + + + + +Return Values +------------- + + +changed + Indicates if any change has been made by the module. This will always be false. + + | **returned**: always + | **type**: bool + +msg + An error message that describes the failure. + + | **returned**: failure + | **type**: str + +user_patterns + The list of User Patterns, with a subset or all of their properties, dependent on \ :literal:`full\_properties`\ . + + | **returned**: success + | **type**: list + | **elements**: dict + | **sample**: + + .. code-block:: json + + [ + { + "element_uri": "/api/console/user-patterns/cbcaf7a0-46cc-11e9-bfd3-f44a39cd42f9", + "name": "Bluepages email address", + "type": "glob-like" + }, + { + "element_uri": "/api/console/user-patterns/fb22d4a2-4e40-11e9-a8a8-00106f23f636", + "name": "regexp pattern 1", + "type": "regular-expression" + } + ] + + name + User pattern name + + | **type**: str + + element_uri + Element URI of the User Pattern object + + | **type**: str + + type + The style in which the user pattern is expressed, as one of the following values: + + \ :literal:`glob-like`\ - Glob-like pattern as used in file names, supporting the special characters \ :literal:`\*`\ and \ :literal:`?`\ . + + \ :literal:`regular-expression`\ - Regular expression pattern using \ :ref:`Java regular expressions `\ . + + | **type**: str + + {additional_property} + Additional properties requested via \ :literal:`full\_properties`\ , as described in the data model of the 'User Pattern' object in the \ :ref:`HMC API `\ book. The property names will have underscores instead of hyphens. + + | **type**: raw + + diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_role.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_role.rst.txt index 4fa8197e..bf6d4aa5 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_role.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_role.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_user_role_module: -zhmc_user_role -- Create HMC user roles -======================================= +zhmc_user_role -- Manage an HMC user role +========================================= @@ -49,35 +49,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -119,7 +119,7 @@ properties \* \ :literal:`permissions`\ : Can be specified as if it were writeable. - Properties omitted in this dictionary will remain unchanged when the user role already exists, and will get the default value defined in the data model for user roles in the :term:\`HMC API\` when the user role is being created. + Properties omitted in this dictionary will remain unchanged when the user role already exists, and will get the default value defined in the data model for user roles in the \ :ref:`HMC API `\ book when the user role is being created. | **required**: False | **type**: dict @@ -135,7 +135,7 @@ properties associated_system_defined_user_role_name The name of the associated system-defined user role. Specifying it requires that the referenced user role exists. - Optional, default: 'hmc-operator-tasks'. + Optional, default: \ :literal:`hmc-operator-tasks`\ . | **required**: False | **type**: str @@ -144,7 +144,7 @@ properties permissions The permissions for this user role. - This property is represented different from its description in the :term:\`HMC API\`: The property is a list of permissions. Each list item is a dictionary that specifies a single permission item, any required scoping items, and optional option items. + This property is represented different from its description in the \ :ref:`HMC API `\ : The property is a list of permissions. Each list item is a dictionary that specifies a single permission item, any required scoping items, and optional option items. | **required**: False | **type**: list @@ -166,7 +166,7 @@ properties class - Permission item: Object permission to all objects of the specified resource class (= value of 'class' property). + Permission item: Object permission to all objects of the specified resource class (= value of \ :literal:`class`\ property). | **required**: False | **type**: str @@ -387,7 +387,7 @@ user_role permissions The permissions for this user role. - This property is represented different from its description in the :term:\`HMC API\`: The property is a list of permissions. Each list item is a dictionary that specifies a single permission item, any needed scoping items, and any applicable option items. + This property is represented different from its description in the \ :ref:`HMC API `\ : The property is a list of permissions. Each list item is a dictionary that specifies a single permission item, any needed scoping items, and any applicable option items. | **type**: list | **elements**: dict @@ -403,7 +403,7 @@ user_role | **type**: bool class - Permission item: Object permission to all objects of the specified resource class (= value of 'class' property). + Permission item: Object permission to all objects of the specified resource class (= value of \ :literal:`class`\ property). | **type**: str @@ -461,7 +461,7 @@ user_role {property} - Additional properties of the user role, as described in the data model of the 'User Role' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the user role, as described in the data model of the 'User Role' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_role_list.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_role_list.rst.txt index 72edd741..937cf30a 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_role_list.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_user_role_list.rst.txt @@ -48,35 +48,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -169,7 +169,7 @@ user_roles | **type**: str type - Type of the user role ('system-defined', 'user-defined') + Type of the user role (\ :literal:`system-defined`\ , \ :literal:`user-defined`\ ) | **type**: str diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_versions.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_versions.rst.txt new file mode 100644 index 00000000..0644642f --- /dev/null +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_versions.rst.txt @@ -0,0 +1,276 @@ + +:github_url: https://github.com/ansible-collections/ibm_zos_core/blob/dev/plugins/modules/zhmc_versions.py + +.. _zhmc_versions_module: + + +zhmc_versions -- Retrieve HMC/CPC version and feature facts +=========================================================== + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Retrieve version and feature facts for the targeted HMC and its managed CPCs. + + +Requirements +------------ + +- No specific task or object-access permissions are required. + + + + +Parameters +---------- + + +hmc_host + The hostnames or IP addresses of a single HMC or of a list of redundant HMCs. A single HMC can be specified as a string type or as an HMC list with one item. An HMC list can be specified as a list type or as a string type containing a Python list representation. + + The first available HMC of a list of redundant HMCs is used for the entire execution of the module. + + | **required**: True + | **type**: raw + + +hmc_auth + The authentication credentials for the HMC. + + | **required**: True + | **type**: dict + + + userid + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . + + | **required**: False + | **type**: str + + + password + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . + + | **required**: False + | **type**: str + + + session_id + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . + + | **required**: False + | **type**: str + + + ca_certs + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + + | **required**: False + | **type**: str + + + verify + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. + + | **required**: False + | **type**: bool + | **default**: True + + + +cpc_names + List of CPC names for which facts are to be included in the result. + + Default: All managed CPCs. + + | **required**: False + | **type**: list + | **elements**: str + + +log_file + File path of a log file to which the logic flow of this module as well as interactions with the HMC are logged. If null, logging will be propagated to the Python root logger. + + | **required**: False + | **type**: str + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + --- + # Note: The following examples assume that some variables named 'my_*' are set. + + - name: Retrieve version and feature information for HMC and all managed CPCs + zhmc_versions: + hmc_host: "{{ my_hmc_host }}" + hmc_auth: "{{ my_hmc_auth }}" + register: hmc1 + + - name: Retrieve version and feature information for HMC only + zhmc_versions: + hmc_host: "{{ my_hmc_host }}" + hmc_auth: "{{ my_hmc_auth }}" + cpc_names: [] + register: hmc1 + + + + + + + + + + +Return Values +------------- + + +changed + Indicates if any change has been made by the module. This will always be false. + + | **returned**: always + | **type**: bool + +msg + An error message that describes the failure. + + | **returned**: failure + | **type**: str + +versions + The version information. + + | **returned**: success + | **type**: dict + | **sample**: + + .. code-block:: json + + { + "cpcs": [ + { + "cpc_api_features": [ + "adapter-network-information", + "..." + ], + "dpm_enabled": true, + "has_unacceptable_status": false, + "name": "CPC1", + "se_version": "2.16.0", + "se_version_info": [ + 2, + 16, + 0 + ], + "status": "active" + } + ], + "hmc_api_features": [ + "adapter-network-information", + "..." + ], + "hmc_api_version": "4.10", + "hmc_api_version_info": [ + 4, + 10 + ], + "hmc_name": "HMC1", + "hmc_version": "2.16.0", + "hmc_version_info": [ + 2, + 16, + 0 + ] + } + + hmc_name + HMC name + + | **type**: str + + hmc_version + HMC version, as a string. + + | **type**: str + + hmc_version_info + HMC version, as a list of integers. + + | **type**: list + | **elements**: int + + hmc_api_version + HMC API version, as a string. + + | **type**: str + + hmc_api_version_info + HMC API version, as a list of integers. + + | **type**: list + | **elements**: int + + hmc_api_features + The available HMC API features. + + | **type**: list + | **elements**: str + + cpcs + Version data for the requested CPCs of the HMC. + + | **type**: list + | **elements**: dict + + name + CPC name. + + | **type**: str + + status + The current status of the CPC. For details, see the description of the 'status' property in the data model of the 'CPC' resource (see \ :ref:`HMC API `\ ). + + | **type**: str + + has_unacceptable_status + Indicates whether the current status of the CPC is unacceptable, based on its 'acceptable-status' property. + + | **type**: bool + + dpm_enabled + Indicates wehether the CPC is in DPM mode (true) or in classic mode (false). + + | **type**: bool + + se_version + SE version of the CPC, as a string. + + | **type**: str + + se_version_info + SE version of the CPC, as a list of integers. + + | **type**: list + | **elements**: int + + cpc_api_features + The available CPC API features. + + | **type**: list + | **elements**: str + + + diff --git a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_virtual_function.rst.txt b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_virtual_function.rst.txt index 4e51748a..15daf050 100644 --- a/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_virtual_function.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/modules/zhmc_virtual_function.rst.txt @@ -4,8 +4,8 @@ .. _zhmc_virtual_function_module: -zhmc_virtual_function -- Create virtual functions in partitions -=============================================================== +zhmc_virtual_function -- Manage a virtual function of a partition (DPM mode) +============================================================================ @@ -51,35 +51,35 @@ hmc_auth userid - The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str password - The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ . + The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ . | **required**: False | **type**: str session_id - HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`. + HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module `\ . | **required**: False | **type**: str ca_certs - Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. + Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate. | **required**: False | **type**: str verify - If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate. + If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate. | **required**: False | **type**: bool @@ -217,7 +217,7 @@ virtual_function | **type**: str {property} - Additional properties of the virtual function, as described in the data model of the 'Virtual Function' element object of the 'Partition' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. + Additional properties of the virtual function, as described in the data model of the 'Virtual Function' element object of the 'Partition' object in the \ :ref:`HMC API `\ book. The property names have hyphens (-) as described in that book. | **type**: raw diff --git a/_sources/zhmc-ansible-modules/docs/source/release_notes.rst.txt b/_sources/zhmc-ansible-modules/docs/source/release_notes.rst.txt index 0a059d6f..32cfd6a1 100644 --- a/_sources/zhmc-ansible-modules/docs/source/release_notes.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/release_notes.rst.txt @@ -20,52 +20,180 @@ Releases ======== -Version 1.8.3 +Version 1.9.1 ------------- -Released: 2024-02-29 +Released: 2024-07-18 Availability: `AutomationHub`_, `Galaxy`_, `GitHub`_ **Bug fixes:** -* Fixed safety issues up to 2024-02-18. +* Sanity test: Fixed the sanity test on AutomationHub which failed because the + "compile" and "import" tests were run for all target node Python versions, + which includes Python 2.7. As we had dropped support for Python < 3.8 in + collection version 1.9.0, the source code now uses Python 3-only features + such as f-strings. -* Fixed dependabot issues up to 2024-02-18. - -* Fixed readable attribute error when ensuring ISO mounted onto the partition. - (related to issue #932) + This was done by adding a file tests/config.yml to the distribution archive + that is consumed by the sanity test if present and that declares that the + modules of this collection run only on the controller node, so the additional + Python versions for the target node are no longer used for these sanity tests. **Cleanup:** -* Resolved the 'no-log-needed' issue raised by the sanity test and ansible-lint - on the 'os_ipl_token' input parameter of the 'zhmc_lpar' module. That - allowed to get rid of the corresponding entries in the ignore files. - (issue #915) +* Removed the unnecessary .pylintrc file from the distribution archive of the + collection. -* Resolved the 'return-syntax-error' issue raised by the sanity test and - ansible-lint on all modules that specify generic return properties. That - allowed to get rid of the corresponding entries in the ignore files. - (issue #915) +* Dev: Brought the list of dependent files for the distribution archive in the + Makefile back in sync with its content. -Version 1.8.2 +Version 1.9.0 ------------- -Released: 2024-01-28 +This version contains all fixes up to version 1.8.3. + +Released: 2024-07-18 Availability: `AutomationHub`_, `Galaxy`_, `GitHub`_ +**Incompatible changes:** + +* Value of 'password' property will be replaced with '\*\*\*\*\*\*\*\*' in log messages and + 'result' dictionary returned by zhmc_user.ensure_present(). + +* Dropped support for Python 2.7, 3.5, 3.6, and 3.7. + +* Increased minimum officially supported Ansible version to Ansible 8 / + ansible-core 2.15. (issue #988) + **Bug fixes:** -* Fixed safety issues up to 2024-01-26. +* Fixed safety issues up to 2024-06-24. + +* Fixed dependabot issues up to 2024-02-18. * Fixed a performance issue in the 'zhmc_lpar_list' and 'zhmc_partition_list' modules where the 'se-version' property was fetched from CPCs even if it was already available in the LPAR/partition properties. (issue #904) -* Increased the minimum version of zhmcclient to 1.13.3 to pick up fixes and - performance improvements. (related to issue #904) +* Increased the minimum version of zhmcclient to 1.17.0 to pick up fixes, + performance improvements and new functions. (related to issue #904 and others) + +* Fixed readable attribute error when ensuring ISO mounted onto the partition. (related to issue #932) + +* In the Github Actions test workflow for Python 3.5, 3.6 and 3.7, changed + macos-latest back to macos-12 because macos-latest got upgraded from macOS 12 + to macOS 14 which no longer supports these Python versions. + +* In the Github Actions test workflow for Python 3.5, added a circumvention + for the Pip certificate issue. + +* Fixed that the 'timeout' parameter of the zhmc_lpar module was not used for + 'state=inactive'. (related to issue #986) + +* Test: Fixed that coverage was calculated only for the Ansible module + source files, but not for the utility files in module_utils. (issue #1020) + +* Test: Fixed exception handling in end2end tests for password rules. + +**Enhancements:** + +* Test: Added tests for Ansible 10. The testing of Ansible 3 was dropped + because we can test only one Ansible version on each Python version and + we ran out of Python versions. + +* Added a new make target 'end2end_show' to show the HMCs defined for end2end + tests. (issue #888) + +* Changed safety run for install dependencies to use the exact minimum versions + of the dependent packages, by moving them into a separate + minimum-constraints-install.txt file that is included by the existing + minimum-constraints.txt file. (issue #939) + +* The safety run for all dependencies now must succeed when the test workflow + is run for a release (i.e. branch name 'release\_...'). + +* Aded check to the test workflow when running on macos or Ubuntu for whether + the 'xz' tool is at a version that is affected by CVE-2024-3094. + +* Added support for running the 'bandit' checker with a new make target + 'bandit', and added that to the GitHub Actions test workflow. + +* Dev: Added a final run of the "safety" and "bandit" tools to the "publish" + workflow, to ensure that a release cannot happen with any findings. + +* Docs: Improved the short descriptions of the modules. (issue #998) + +* Added a new module zhmc_versions that retrieves facts for HMC/CPC versions + and features. + +* Added a new 'status_timeout' parameter to the zhmc_lpar module for + 'state=inactive,active,loaded'. (issue #986) + +* Added a new 'allow_status_exceptions' parameters to the zhmc_lpar module for + 'state=active,loaded'. For backwards compatibility, its default value is True. + (issue #986) + +* Test: Added a separate pylint run (in addition to the one in the Ansible + sanity test), because it can be run on the test sources as well, and because + the santy test pylint has important checks disabled. (issue #1007) + +* Test: Added virtual storage resource objects to the mocked end2end test + environments. + +* Docs: Added a chapter 'Installing a development version' that describes + how to build and install a development version of the collection from + the repo. (issue #1008) + +* Added new Ansible modules 'zhmc_user_pattern_list' and 'zhmc_user_pattern' + for listing and managing user patterns on the HMC. (issue #361) + +* Test: Added end2end tests for adding and removing user roles to/from existing + users. (related to issue #716) + +* Added a new Ansible module 'zhmc_cpc_capacity' for managing the temporary + processor capacity of a CPC. (issue #243) + +* Added new modules 'zhmc_lpar_command' and 'zhmc_partition_command' for + executing an OS consosle command in the OS running in an LPAR or + partition. (issue #938) + +* Enabled notification logging via the 'zhmcclient.jms' Python logger. + (related to issue #938) + +**Cleanup:** + +* Modernized the code to match the minimum Python version 3.8 (use of f-strings, + no Python 2 compatibility, 'mock' is used from 'unittest'). + +* Increased versions of GitHub Actions plugins to increase node.js runtime + to version 20. + +* Resolved the 'no-log-needed' issue raised by the sanity test and ansible-lint + on the 'os_ipl_token' input parameter of the 'zhmc_lpar' module. That + allowed to get rid of the corresponding entries in the ignore files. + (issue #915) + +* Resolved the 'return-syntax-error' issue raised by the sanity test and + ansible-lint on all modules that specify generic return properties. That + allowed to get rid of the corresponding entries in the ignore files. + (issue #915) + +* Test: Upgraded Githubb Actionb plugins that used the deprecated node version + 16. (issue #974) + +* Docs: Reduced the number of versions in the generated documentaion to only the + latest fix version of each minor version starting with version 1.0.x. + (issue #1000) + +* Dev: Suppressed the errors in the Makefile when ansible is not yet installed + but the Makefile sets variables that depend on ansible being installed. + That situation was handled correctly, but the error messages were confusing. + +* Docs: Adjusted README file to new Ansible Automation Hub requirements. + (issue #993) Version 1.8.1 diff --git a/genindex.html b/genindex.html index b4415658..13729606 100644 --- a/genindex.html +++ b/genindex.html @@ -177,31 +177,38 @@

Index

- H + C + | E + | R
-

H

+

C

+
+ +

E

+ +
+ +

R

+ +
diff --git a/ibm_zos_cics/docs/source/release_notes.html b/ibm_zos_cics/docs/source/release_notes.html index a81d1b54..85894d0e 100644 --- a/ibm_zos_cics/docs/source/release_notes.html +++ b/ibm_zos_cics/docs/source/release_notes.html @@ -108,40 +108,24 @@
  • What’s New
  • -
  • Version 1.1.0-beta.5 @@ -274,14 +280,14 @@

    Parameterstype: str -
    ca_certs

    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the ‘REQUESTS_CA_BUNDLE’ environment variable or the path name in the ‘CURL_CA_BUNDLE’ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the ‘certifi’ Python package are used for verifying the HMC certificate.

    +
    ca_certs

    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the REQUESTS_CA_BUNDLE environment variable or the path name in the CURL_CA_BUNDLE environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the ‘certifi’ Python package are used for verifying the HMC certificate.

    Optional for action=create, not permitted for action=delete.

    required: False
    type: str
    -
    verify

    If True (default), verify the HMC certificate as specified in the ca_certs parameter. If False, ignore what is specified in the ca_certs parameter and do not verify the HMC certificate.

    +
    verify

    If True (default), verify the HMC certificate as specified in the hmc_auth.ca_certs parameter. If False, ignore what is specified in the hmc_auth.ca_certs parameter and do not verify the HMC certificate.

    Optional for action=create, not permitted for action=delete.

    -
    hmc_host

    The hostname or IP address of the HMC that was actually used for the session creation, for action=create. This value must be specified as ‘hmc_host’ for action=delete.

    +
    hmc_host

    The hostname or IP address of the HMC that was actually used for the session creation, for action=create. This value must be specified as hmc_host for action=delete.

    For action=delete, returns the null value.

    -
    ca_certs

    Value of ca_certs input parameter for action=create, or null for action=delete.

    +
    ca_certs

    Value of hmc_auth.ca_certs input parameter for action=create, or null for action=delete.

    type: str
    -
    verify

    Value of verify input parameter for action=create, or null for action=delete.

    +
    verify

    Value of hmc_auth.verify input parameter for action=create, or null for action=delete.

    type: bool
    diff --git a/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group.html b/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group.html index 5cada101..8f916e6a 100644 --- a/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group.html +++ b/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group.html @@ -8,7 +8,7 @@ - zhmc_storage_group – Create storage groups — Red Hat Ansible Certified Content for IBM Z documentation + zhmc_storage_group – Manage a storage group (DPM mode) — Red Hat Ansible Certified Content for IBM Z documentation @@ -35,8 +35,8 @@ - - + + @@ -96,27 +96,32 @@
  • Z HMC
  • -
    {property}

    Additional properties of the storage port, as described in the data model of the ‘Storage Port’ element object of the ‘Adapter’ object in the :term:`HMC API` book. The property names have hyphens (-) as described in that book.

    +
    {property}

    Additional properties of the storage port, as described in the data model of the ‘Storage Port’ element object of the ‘Adapter’ object in the HMC API book. The property names have hyphens (-) as described in that book.

    type: raw
    @@ -697,7 +703,7 @@

    Return Valuestype: str

    -
    {property}

    Additional properties of the storage adapter, as described in the data model of the ‘Adapter’ object in the :term:`HMC API` book. The property names have hyphens (-) as described in that book.

    +
    {property}

    Additional properties of the storage adapter, as described in the data model of the ‘Adapter’ object in the HMC API book. The property names have hyphens (-) as described in that book.

    type: raw
    @@ -718,7 +724,7 @@

    Return Valuestype: str

    -
    {property}

    Additional properties of the storage volume, as described in the data model of the ‘Storage Volume’ element object of the ‘Storage Group’ object in the :term:`HMC API` book. The property names have hyphens (-) as described in that book.

    +
    {property}

    Additional properties of the storage volume, as described in the data model of the ‘Storage Volume’ element object of the ‘Storage Group’ object in the HMC API book. The property names have hyphens (-) as described in that book.

    type: raw
    @@ -732,7 +738,7 @@

    Return Valueselements: dict
    -
    {property}

    Properties of the virtual storage resource, as described in the data model of the ‘Virtual Storage Resource’ element object of the ‘Storage Group’ object in the :term:`HMC API` book. The property names have hyphens (-) as described in that book.

    +
    {property}

    Properties of the virtual storage resource, as described in the data model of the ‘Virtual Storage Resource’ element object of the ‘Storage Group’ object in the HMC API book. The property names have hyphens (-) as described in that book.

    type: raw
    @@ -746,7 +752,7 @@

    Return Valueselements: dict
    -
    {property}

    Properties of the partition, as described in the data model of the ‘Partition’ object in the :term:`HMC API` book. The property names have hyphens (-) as described in that book.

    +
    {property}

    Properties of the partition, as described in the data model of the ‘Partition’ object in the HMC API book. The property names have hyphens (-) as described in that book.

    type: raw
    diff --git a/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group_attachment.html b/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group_attachment.html index 5e60e606..aea1bb0a 100644 --- a/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group_attachment.html +++ b/zhmc-ansible-modules/docs/source/modules/zhmc_storage_group_attachment.html @@ -8,7 +8,7 @@ - zhmc_storage_group_attachment – Attach storage groups to partitions — Red Hat Ansible Certified Content for IBM Z documentation + zhmc_storage_group_attachment – Manage attachment of a storage group to a partition (DPM mode) — Red Hat Ansible Certified Content for IBM Z documentation @@ -35,8 +35,8 @@ - - + + @@ -96,28 +96,33 @@
  • Z HMC
  • -
    {property}

    Additional properties of the user role, as described in the data model of the ‘User Role’ object in the :term:`HMC API` book. The property names have hyphens (-) as described in that book.

    +
    {property}

    Additional properties of the user role, as described in the data model of the ‘User Role’ object in the HMC API book. The property names have hyphens (-) as described in that book.

    type: raw
    diff --git a/zhmc-ansible-modules/docs/source/modules/zhmc_user_role_list.html b/zhmc-ansible-modules/docs/source/modules/zhmc_user_role_list.html index 87e95908..51581c26 100644 --- a/zhmc-ansible-modules/docs/source/modules/zhmc_user_role_list.html +++ b/zhmc-ansible-modules/docs/source/modules/zhmc_user_role_list.html @@ -35,8 +35,8 @@ - - + + @@ -96,12 +96,13 @@
  • Z HMC @@ -259,31 +265,31 @@

    Parameterstype: dict
    -
    userid

    The userid (username) for authenticating with the HMC. This is mutually exclusive with providing session_id.

    +
    userid

    The userid (username) for authenticating with the HMC. This is mutually exclusive with providing hmc_auth.session_id.

    required: False
    type: str
    -
    password

    The password for authenticating with the HMC. This is mutually exclusive with providing session_id.

    +
    password

    The password for authenticating with the HMC. This is mutually exclusive with providing hmc_auth.session_id.

    required: False
    type: str
    -
    session_id

    HMC session ID to be used. This is mutually exclusive with providing userid and password and can be created as described in :ref:`zhmc_session_module`.

    +
    session_id

    HMC session ID to be used. This is mutually exclusive with providing hmc_auth.userid and hmc_auth.password and can be created as described in the zhmc_session module.

    required: False
    type: str
    -
    ca_certs

    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the ‘REQUESTS_CA_BUNDLE’ environment variable or the path name in the ‘CURL_CA_BUNDLE’ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the ‘certifi’ Python package are used for verifying the HMC certificate.

    +
    ca_certs

    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the REQUESTS_CA_BUNDLE environment variable or the path name in the CURL_CA_BUNDLE environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the ‘certifi’ Python package are used for verifying the HMC certificate.

    required: False
    type: str
    -
    verify

    If True (default), verify the HMC certificate as specified in the ca_certs parameter. If False, ignore what is specified in the ca_certs parameter and do not verify the HMC certificate.

    +
    verify

    If True (default), verify the HMC certificate as specified in the hmc_auth.ca_certs parameter. If False, ignore what is specified in the hmc_auth.ca_certs parameter and do not verify the HMC certificate.

    required: False
    type: bool
    @@ -362,7 +368,7 @@

    Return Valuestype: str

    -
    type

    Type of the user role (‘system-defined’, ‘user-defined’)

    +
    type

    Type of the user role (system-defined, user-defined)

    type: str
    diff --git a/zhmc-ansible-modules/docs/source/modules/zhmc_versions.html b/zhmc-ansible-modules/docs/source/modules/zhmc_versions.html new file mode 100644 index 00000000..94b271eb --- /dev/null +++ b/zhmc-ansible-modules/docs/source/modules/zhmc_versions.html @@ -0,0 +1,522 @@ + + + + + + + + + + + zhmc_versions – Retrieve HMC/CPC version and feature facts — Red Hat Ansible Certified Content for IBM Z documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + +
    + + + + + +
    + +
    + + + + + + + + + + + + + + + + + + + +
    + +
      + +
    • Docs »
    • + +
    • Z HMC »
    • + +
    • Modules »
    • + +
    • zhmc_versions – Retrieve HMC/CPC version and feature facts
    • + + + +
    + + +
    +
    +
    +
    + +
    +

    zhmc_versions – Retrieve HMC/CPC version and feature facts

    + +
    +

    Synopsis

    +
      +
    • Retrieve version and feature facts for the targeted HMC and its managed CPCs.

    • +
    +
    +
    +

    Requirements

    +
      +
    • No specific task or object-access permissions are required.

    • +
    +
    +
    +

    Parameters

    +
    +
    hmc_host

    The hostnames or IP addresses of a single HMC or of a list of redundant HMCs. A single HMC can be specified as a string type or as an HMC list with one item. An HMC list can be specified as a list type or as a string type containing a Python list representation.

    +

    The first available HMC of a list of redundant HMCs is used for the entire execution of the module.

    +
    +
    required: True
    +
    type: raw
    +
    +
    +
    hmc_auth

    The authentication credentials for the HMC.

    +
    +
    required: True
    +
    type: dict
    +
    +
    +
    userid

    The userid (username) for authenticating with the HMC. This is mutually exclusive with providing hmc_auth.session_id.

    +
    +
    required: False
    +
    type: str
    +
    +
    +
    password

    The password for authenticating with the HMC. This is mutually exclusive with providing hmc_auth.session_id.

    +
    +
    required: False
    +
    type: str
    +
    +
    +
    session_id

    HMC session ID to be used. This is mutually exclusive with providing hmc_auth.userid and hmc_auth.password and can be created as described in the zhmc_session module.

    +
    +
    required: False
    +
    type: str
    +
    +
    +
    ca_certs

    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the REQUESTS_CA_BUNDLE environment variable or the path name in the CURL_CA_BUNDLE environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the ‘certifi’ Python package are used for verifying the HMC certificate.

    +
    +
    required: False
    +
    type: str
    +
    +
    +
    verify

    If True (default), verify the HMC certificate as specified in the hmc_auth.ca_certs parameter. If False, ignore what is specified in the hmc_auth.ca_certs parameter and do not verify the HMC certificate.

    +
    +
    required: False
    +
    type: bool
    +
    default: True
    +
    +
    +
    +
    +
    cpc_names

    List of CPC names for which facts are to be included in the result.

    +

    Default: All managed CPCs.

    +
    +
    required: False
    +
    type: list
    +
    elements: str
    +
    +
    +
    log_file

    File path of a log file to which the logic flow of this module as well as interactions with the HMC are logged. If null, logging will be propagated to the Python root logger.

    +
    +
    required: False
    +
    type: str
    +
    +
    +
    +
    +
    +

    Examples

    +
    ---
    +# Note: The following examples assume that some variables named 'my_*' are set.
    +
    +- name: Retrieve version and feature information for HMC and all managed CPCs
    +  zhmc_versions:
    +    hmc_host: "{{ my_hmc_host }}"
    +    hmc_auth: "{{ my_hmc_auth }}"
    +  register: hmc1
    +
    +- name: Retrieve version and feature information for HMC only
    +  zhmc_versions:
    +    hmc_host: "{{ my_hmc_host }}"
    +    hmc_auth: "{{ my_hmc_auth }}"
    +    cpc_names: []
    +  register: hmc1
    +
    +
    +
    +
    +

    Return Values

    +
    +
    changed

    Indicates if any change has been made by the module. This will always be false.

    +
    +
    returned: always
    +
    type: bool
    +
    +
    +
    msg

    An error message that describes the failure.

    +
    +
    returned: failure
    +
    type: str
    +
    +
    +
    versions

    The version information.

    +
    +
    returned: success
    +
    type: dict
    +
    sample:
    +
    +
    +
    {
    +    "cpcs": [
    +        {
    +            "cpc_api_features": [
    +                "adapter-network-information",
    +                "..."
    +            ],
    +            "dpm_enabled": true,
    +            "has_unacceptable_status": false,
    +            "name": "CPC1",
    +            "se_version": "2.16.0",
    +            "se_version_info": [
    +                2,
    +                16,
    +                0
    +            ],
    +            "status": "active"
    +        }
    +    ],
    +    "hmc_api_features": [
    +        "adapter-network-information",
    +        "..."
    +    ],
    +    "hmc_api_version": "4.10",
    +    "hmc_api_version_info": [
    +        4,
    +        10
    +    ],
    +    "hmc_name": "HMC1",
    +    "hmc_version": "2.16.0",
    +    "hmc_version_info": [
    +        2,
    +        16,
    +        0
    +    ]
    +}
    +
    +
    +
    +
    +
    hmc_name

    HMC name

    +
    +
    type: str
    +
    +
    +
    hmc_version

    HMC version, as a string.

    +
    +
    type: str
    +
    +
    +
    hmc_version_info

    HMC version, as a list of integers.

    +
    +
    type: list
    +
    elements: int
    +
    +
    +
    hmc_api_version

    HMC API version, as a string.

    +
    +
    type: str
    +
    +
    +
    hmc_api_version_info

    HMC API version, as a list of integers.

    +
    +
    type: list
    +
    elements: int
    +
    +
    +
    hmc_api_features

    The available HMC API features.

    +
    +
    type: list
    +
    elements: str
    +
    +
    +
    cpcs

    Version data for the requested CPCs of the HMC.

    +
    +
    type: list
    +
    elements: dict
    +
    +
    +
    name

    CPC name.

    +
    +
    type: str
    +
    +
    +
    status

    The current status of the CPC. For details, see the description of the ‘status’ property in the data model of the ‘CPC’ resource (see HMC API).

    +
    +
    type: str
    +
    +
    +
    has_unacceptable_status

    Indicates whether the current status of the CPC is unacceptable, based on its ‘acceptable-status’ property.

    +
    +
    type: bool
    +
    +
    +
    dpm_enabled

    Indicates wehether the CPC is in DPM mode (true) or in classic mode (false).

    +
    +
    type: bool
    +
    +
    +
    se_version

    SE version of the CPC, as a string.

    +
    +
    type: str
    +
    +
    +
    se_version_info

    SE version of the CPC, as a list of integers.

    +
    +
    type: list
    +
    elements: int
    +
    +
    +
    cpc_api_features

    The available CPC API features.

    +
    +
    type: list
    +
    elements: str
    +
    +
    +
    +
    +
    +
    +
    +
    +
    + + +
    + +
    +
    + + +
    + +
    +

    + © Copyright IBM Corp. 2020, 2023 + +

    +
    + +
    + +
    +
    + +
    + +
    + + + + + + + + + + + + \ No newline at end of file diff --git a/zhmc-ansible-modules/docs/source/modules/zhmc_virtual_function.html b/zhmc-ansible-modules/docs/source/modules/zhmc_virtual_function.html index 1a96159f..d175feae 100644 --- a/zhmc-ansible-modules/docs/source/modules/zhmc_virtual_function.html +++ b/zhmc-ansible-modules/docs/source/modules/zhmc_virtual_function.html @@ -8,7 +8,7 @@ - zhmc_virtual_function – Create virtual functions in partitions — Red Hat Ansible Certified Content for IBM Z documentation + zhmc_virtual_function – Manage a virtual function of a partition (DPM mode) — Red Hat Ansible Certified Content for IBM Z documentation @@ -35,8 +35,8 @@ - - + + @@ -96,30 +96,35 @@
  • Z HMC
  • -
    {property}

    Additional properties of the virtual function, as described in the data model of the ‘Virtual Function’ element object of the ‘Partition’ object in the :term:`HMC API` book. The property names have hyphens (-) as described in that book.

    +
    {property}

    Additional properties of the virtual function, as described in the data model of the ‘Virtual Function’ element object of the ‘Partition’ object in the HMC API book. The property names have hyphens (-) as described in that book.

    type: raw
    diff --git a/zhmc-ansible-modules/docs/source/release_notes.html b/zhmc-ansible-modules/docs/source/release_notes.html index bde88aec..69449538 100644 --- a/zhmc-ansible-modules/docs/source/release_notes.html +++ b/zhmc-ansible-modules/docs/source/release_notes.html @@ -104,8 +104,8 @@
  • z/OS Sys Auto
  • z/OS z/OSMF
  • Z HMC
      -
    • Version 1.8.3
    • -
    • Version 1.8.2
    • +
    • Version 1.9.1
    • +
    • Version 1.9.0
    • Version 1.8.1
    • Version 1.8.0
    • Version 1.7.0
    • @@ -209,19 +209,118 @@

      Releases

      -
      -

      Version 1.8.3

      -

      Released: 2024-02-29

      +
      +

      Version 1.9.1

      +

      Released: 2024-07-18

      Availability: AutomationHub, Galaxy, GitHub

      Bug fixes:

      +
        +
      • Sanity test: Fixed the sanity test on AutomationHub which failed because the +“compile” and “import” tests were run for all target node Python versions, +which includes Python 2.7. As we had dropped support for Python < 3.8 in +collection version 1.9.0, the source code now uses Python 3-only features +such as f-strings.

        +

        This was done by adding a file tests/config.yml to the distribution archive +that is consumed by the sanity test if present and that declares that the +modules of this collection run only on the controller node, so the additional +Python versions for the target node are no longer used for these sanity tests.

        +
      • +
      +

      Cleanup:

        -
      • Fixed safety issues up to 2024-02-18.

      • +
      • Removed the unnecessary .pylintrc file from the distribution archive of the +collection.

      • +
      • Dev: Brought the list of dependent files for the distribution archive in the +Makefile back in sync with its content.

      • +
      +
      +
      +

      Version 1.9.0

      +

      This version contains all fixes up to version 1.8.3.

      +

      Released: 2024-07-18

      +

      Availability: AutomationHub, Galaxy, GitHub

      +

      Incompatible changes:

      +
        +
      • Value of ‘password’ property will be replaced with ‘********’ in log messages and +‘result’ dictionary returned by zhmc_user.ensure_present().

      • +
      • Dropped support for Python 2.7, 3.5, 3.6, and 3.7.

      • +
      • Increased minimum officially supported Ansible version to Ansible 8 / +ansible-core 2.15. (issue #988)

      • +
      +

      Bug fixes:

      +
        +
      • Fixed safety issues up to 2024-06-24.

      • Fixed dependabot issues up to 2024-02-18.

      • -
      • Fixed readable attribute error when ensuring ISO mounted onto the partition. -(related to issue #932)

      • +
      • Fixed a performance issue in the ‘zhmc_lpar_list’ and ‘zhmc_partition_list’ +modules where the ‘se-version’ property was fetched from CPCs even if it +was already available in the LPAR/partition properties. (issue #904)

      • +
      • Increased the minimum version of zhmcclient to 1.17.0 to pick up fixes, +performance improvements and new functions. (related to issue #904 and others)

      • +
      • Fixed readable attribute error when ensuring ISO mounted onto the partition. (related to issue #932)

      • +
      • In the Github Actions test workflow for Python 3.5, 3.6 and 3.7, changed +macos-latest back to macos-12 because macos-latest got upgraded from macOS 12 +to macOS 14 which no longer supports these Python versions.

      • +
      • In the Github Actions test workflow for Python 3.5, added a circumvention +for the Pip certificate issue.

      • +
      • Fixed that the ‘timeout’ parameter of the zhmc_lpar module was not used for +‘state=inactive’. (related to issue #986)

      • +
      • Test: Fixed that coverage was calculated only for the Ansible module +source files, but not for the utility files in module_utils. (issue #1020)

      • +
      • Test: Fixed exception handling in end2end tests for password rules.

      • +
      +

      Enhancements:

      +
        +
      • Test: Added tests for Ansible 10. The testing of Ansible 3 was dropped +because we can test only one Ansible version on each Python version and +we ran out of Python versions.

      • +
      • Added a new make target ‘end2end_show’ to show the HMCs defined for end2end +tests. (issue #888)

      • +
      • Changed safety run for install dependencies to use the exact minimum versions +of the dependent packages, by moving them into a separate +minimum-constraints-install.txt file that is included by the existing +minimum-constraints.txt file. (issue #939)

      • +
      • The safety run for all dependencies now must succeed when the test workflow +is run for a release (i.e. branch name ‘release_…’).

      • +
      • Aded check to the test workflow when running on macos or Ubuntu for whether +the ‘xz’ tool is at a version that is affected by CVE-2024-3094.

      • +
      • Added support for running the ‘bandit’ checker with a new make target +‘bandit’, and added that to the GitHub Actions test workflow.

      • +
      • Dev: Added a final run of the “safety” and “bandit” tools to the “publish” +workflow, to ensure that a release cannot happen with any findings.

      • +
      • Docs: Improved the short descriptions of the modules. (issue #998)

      • +
      • Added a new module zhmc_versions that retrieves facts for HMC/CPC versions +and features.

      • +
      • Added a new ‘status_timeout’ parameter to the zhmc_lpar module for +‘state=inactive,active,loaded’. (issue #986)

      • +
      • Added a new ‘allow_status_exceptions’ parameters to the zhmc_lpar module for +‘state=active,loaded’. For backwards compatibility, its default value is True. +(issue #986)

      • +
      • Test: Added a separate pylint run (in addition to the one in the Ansible +sanity test), because it can be run on the test sources as well, and because +the santy test pylint has important checks disabled. (issue #1007)

      • +
      • Test: Added virtual storage resource objects to the mocked end2end test +environments.

      • +
      • Docs: Added a chapter ‘Installing a development version’ that describes +how to build and install a development version of the collection from +the repo. (issue #1008)

      • +
      • Added new Ansible modules ‘zhmc_user_pattern_list’ and ‘zhmc_user_pattern’ +for listing and managing user patterns on the HMC. (issue #361)

      • +
      • Test: Added end2end tests for adding and removing user roles to/from existing +users. (related to issue #716)

      • +
      • Added a new Ansible module ‘zhmc_cpc_capacity’ for managing the temporary +processor capacity of a CPC. (issue #243)

      • +
      • Added new modules ‘zhmc_lpar_command’ and ‘zhmc_partition_command’ for +executing an OS consosle command in the OS running in an LPAR or +partition. (issue #938)

      • +
      • Enabled notification logging via the ‘zhmcclient.jms’ Python logger. +(related to issue #938)

      Cleanup:

        +
      • Modernized the code to match the minimum Python version 3.8 (use of f-strings, +no Python 2 compatibility, ‘mock’ is used from ‘unittest’).

      • +
      • Increased versions of GitHub Actions plugins to increase node.js runtime +to version 20.

      • Resolved the ‘no-log-needed’ issue raised by the sanity test and ansible-lint on the ‘os_ipl_token’ input parameter of the ‘zhmc_lpar’ module. That allowed to get rid of the corresponding entries in the ignore files. @@ -230,20 +329,16 @@

        Version 1.8.3 -

        Version 1.8.2

        -

        Released: 2024-01-28

        -

        Availability: AutomationHub, Galaxy, GitHub

        -

        Bug fixes:

        -
          -
        • Fixed safety issues up to 2024-01-26.

        • -
        • Fixed a performance issue in the ‘zhmc_lpar_list’ and ‘zhmc_partition_list’ -modules where the ‘se-version’ property was fetched from CPCs even if it -was already available in the LPAR/partition properties. (issue #904)

        • -
        • Increased the minimum version of zhmcclient to 1.13.3 to pick up fixes and -performance improvements. (related to issue #904)

        • +
        • Test: Upgraded Githubb Actionb plugins that used the deprecated node version +16. (issue #974)

        • +
        • Docs: Reduced the number of versions in the generated documentaion to only the +latest fix version of each minor version starting with version 1.0.x. +(issue #1000)

        • +
        • Dev: Suppressed the errors in the Makefile when ansible is not yet installed +but the Makefile sets variables that depend on ansible being installed. +That situation was handled correctly, but the error messages were confusing.

        • +
        • Docs: Adjusted README file to new Ansible Automation Hub requirements. +(issue #993)