From 48231e3f58429ccb7d51df43419f8df543b101e8 Mon Sep 17 00:00:00 2001 From: Fernando Flores Date: Thu, 6 Feb 2025 10:36:09 -0600 Subject: [PATCH] Automated commit to update documentation --- .../ibm_zos_cics/docs/source/modules.rst.txt | 2 + .../source/modules/aux_temp_storage.rst.txt | 18 +- .../docs/source/modules/aux_trace.rst.txt | 20 +- .../docs/source/modules/cmci_action.rst.txt | 123 ++- .../docs/source/modules/cmci_create.rst.txt | 54 +- .../docs/source/modules/cmci_delete.rst.txt | 105 ++- .../docs/source/modules/cmci_get.rst.txt | 131 ++- .../docs/source/modules/cmci_update.rst.txt | 102 ++- .../docs/source/modules/csd.rst.txt | 43 +- .../source/modules/global_catalog.rst.txt | 28 +- .../docs/source/modules/local_catalog.rst.txt | 26 +- .../modules/local_request_queue.rst.txt | 18 +- .../docs/source/modules/region_jcl.rst.txt | 118 +-- .../docs/source/modules/stop_region.rst.txt | 16 +- .../source/modules/td_intrapartition.rst.txt | 18 +- .../source/modules/transaction_dump.rst.txt | 20 +- .../docs/source/release_notes.rst.txt | 114 +-- .../docs/source/modules/zos_archive.rst.txt | 39 +- .../source/modules/zos_backup_restore.rst.txt | 39 +- .../source/modules/zos_blockinfile.rst.txt | 22 + .../docs/source/modules/zos_copy.rst.txt | 105 ++- .../docs/source/modules/zos_data_set.rst.txt | 147 ++- .../docs/source/modules/zos_encode.rst.txt | 28 +- .../docs/source/modules/zos_fetch.rst.txt | 28 +- .../docs/source/modules/zos_find.rst.txt | 67 +- .../source/modules/zos_job_output.rst.txt | 2 +- .../docs/source/modules/zos_job_query.rst.txt | 32 + .../source/modules/zos_job_submit.rst.txt | 54 +- .../source/modules/zos_lineinfile.rst.txt | 18 + .../docs/source/modules/zos_mvs_raw.rst.txt | 73 +- .../docs/source/modules/zos_operator.rst.txt | 16 + .../docs/source/modules/zos_script.rst.txt | 10 +- .../docs/source/modules/zos_unarchive.rst.txt | 13 + .../source/modules/zos_zfs_resize.rst.txt | 298 +++++++ .../ibm_zos_core/docs/source/plugins.rst.txt | 2 +- .../docs/source/reference/community.rst.txt | 2 +- .../docs/source/release_notes.rst.txt | 454 +++++++++- .../resources/releases_maintenance.rst.txt | 78 +- .../docs/source/modules/ims_acb_gen.rst.txt | 40 +- .../docs/source/modules/ims_ddl.rst.txt | 20 +- .../docs/source/release_notes.rst.txt | 54 +- .../docs/source/bibliography.rst.txt | 35 +- .../docs/source/development.rst.txt | 97 +- .../docs/source/modules.rst.txt | 6 + .../docs/source/modules/zhmc_adapter.rst.txt | 46 +- .../source/modules/zhmc_adapter_list.rst.txt | 24 +- .../docs/source/modules/zhmc_console.rst.txt | 36 +- .../docs/source/modules/zhmc_cpc.rst.txt | 54 +- .../source/modules/zhmc_cpc_capacity.rst.txt | 419 +++++++++ .../docs/source/modules/zhmc_cpc_list.rst.txt | 14 +- .../modules/zhmc_crypto_attachment.rst.txt | 34 +- .../docs/source/modules/zhmc_hba.rst.txt | 36 +- .../zhmc_ldap_server_definition.rst.txt | 34 +- .../zhmc_ldap_server_definition_list.rst.txt | 14 +- .../docs/source/modules/zhmc_lpar.rst.txt | 90 +- .../source/modules/zhmc_lpar_command.rst.txt | 197 ++++ .../source/modules/zhmc_lpar_list.rst.txt | 26 +- .../source/modules/zhmc_lpar_messages.rst.txt | 16 +- .../docs/source/modules/zhmc_nic.rst.txt | 38 +- .../docs/source/modules/zhmc_nic_list.rst.txt | 16 +- .../source/modules/zhmc_partition.rst.txt | 95 +- .../modules/zhmc_partition_command.rst.txt | 196 ++++ .../modules/zhmc_partition_list.rst.txt | 26 +- .../modules/zhmc_partition_messages.rst.txt | 16 +- .../source/modules/zhmc_password_rule.rst.txt | 34 +- .../modules/zhmc_password_rule_list.rst.txt | 16 +- .../docs/source/modules/zhmc_session.rst.txt | 34 +- .../source/modules/zhmc_storage_group.rst.txt | 60 +- .../zhmc_storage_group_attachment.rst.txt | 22 +- .../modules/zhmc_storage_volume.rst.txt | 36 +- .../docs/source/modules/zhmc_user.rst.txt | 80 +- .../source/modules/zhmc_user_list.rst.txt | 14 +- .../source/modules/zhmc_user_pattern.rst.txt | 288 ++++++ .../modules/zhmc_user_pattern_list.rst.txt | 192 ++++ .../source/modules/zhmc_user_role.rst.txt | 78 +- .../modules/zhmc_user_role_list.rst.txt | 14 +- .../docs/source/modules/zhmc_versions.rst.txt | 276 ++++++ .../modules/zhmc_virtual_function.rst.txt | 34 +- .../docs/source/release_notes.rst.txt | 222 ++++- genindex.html | 39 +- ibm_zos_cics/docs/source/modules.html | 1 + .../docs/source/modules/cmci_action.html | 36 +- .../docs/source/modules/cmci_create.html | 13 +- .../docs/source/modules/cmci_delete.html | 25 +- .../docs/source/modules/cmci_get.html | 49 +- .../docs/source/modules/cmci_update.html | 17 +- ibm_zos_cics/docs/source/modules/csd.html | 3 + .../docs/source/modules/region_jcl.html | 2 + ibm_zos_cics/docs/source/release_notes.html | 154 +--- ibm_zos_core/docs/source/filters.html | 2 +- ibm_zos_core/docs/source/modules.html | 2 + ibm_zos_core/docs/source/modules/zos_apf.html | 1 + .../docs/source/modules/zos_archive.html | 36 +- .../source/modules/zos_backup_restore.html | 37 +- .../docs/source/modules/zos_blockinfile.html | 19 + .../docs/source/modules/zos_copy.html | 82 +- .../docs/source/modules/zos_data_set.html | 107 ++- .../docs/source/modules/zos_encode.html | 26 +- .../docs/source/modules/zos_fetch.html | 29 +- .../docs/source/modules/zos_find.html | 55 +- .../docs/source/modules/zos_gather_facts.html | 1 + .../docs/source/modules/zos_job_output.html | 3 +- .../docs/source/modules/zos_job_query.html | 27 + .../docs/source/modules/zos_job_submit.html | 44 +- .../docs/source/modules/zos_lineinfile.html | 17 + .../docs/source/modules/zos_mount.html | 1 + .../docs/source/modules/zos_mvs_raw.html | 69 +- .../docs/source/modules/zos_operator.html | 22 +- .../modules/zos_operator_action_query.html | 1 + .../docs/source/modules/zos_ping.html | 1 + .../docs/source/modules/zos_script.html | 10 +- .../docs/source/modules/zos_tso_command.html | 1 + .../docs/source/modules/zos_unarchive.html | 11 + .../docs/source/modules/zos_volume_init.html | 3 +- .../docs/source/modules/zos_zfs_resize.html | 536 +++++++++++ ibm_zos_core/docs/source/release_notes.html | 838 +++++++++++++++--- .../resources/releases_maintenance.html | 129 ++- .../docs/source/modules/ims_acb_gen.html | 7 +- ibm_zos_ims/docs/source/modules/ims_ddl.html | 8 +- ibm_zos_ims/docs/source/release_notes.html | 162 ++-- objects.inv | Bin 5458 -> 6040 bytes release/release.html | 2 +- searchindex.js | 2 +- .../docs/source/bibliography.html | 39 +- .../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 | 182 +++- 161 files changed, 11059 insertions(+), 2782 deletions(-) create mode 100644 _sources/ibm_zos_core/docs/source/modules/zos_zfs_resize.rst.txt 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 ibm_zos_core/docs/source/modules/zos_zfs_resize.html 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/modules.rst.txt b/_sources/ibm_zos_cics/docs/source/modules.rst.txt index 68863a68..d487ba70 100644 --- a/_sources/ibm_zos_cics/docs/source/modules.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules.rst.txt @@ -60,6 +60,8 @@ To override the data set location or name for a specific task, you can provide a additional parameter to the ``region_data_sets`` group as shown in the example for a global catalog data set below. +N.B. There is a known limitation with ansible-core version 2.15.0 and 2.15.1, where the custom templating may fail. + .. code-block:: yaml+jinja diff --git a/_sources/ibm_zos_cics/docs/source/modules/aux_temp_storage.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/aux_temp_storage.rst.txt index 92dff8d3..634a3e4a 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/aux_temp_storage.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/aux_temp_storage.rst.txt @@ -20,9 +20,9 @@ aux_temp_storage -- Create and remove the CICS auxiliary temporary storage data Synopsis -------- -- Create and remove the \ `auxiliary temporary storage `__\ data set used by a CICS® region. +- Create and remove the \ `auxiliary temporary storage `__ data set used by a CICS® region. - You can use this module when provisioning or de-provisioning a CICS region. -- Use the \ :literal:`state`\ option to specify the intended state for the auxiliary temporary storage data set. For example, use \ :literal:`state=initial`\ to create an auxiliary temporary storage data set if it doesn't exist. +- Use the :literal:`state` option to specify the intended state for the auxiliary temporary storage data set. For example, use :literal:`state=initial` to create an auxiliary temporary storage data set if it doesn't exist. @@ -34,7 +34,7 @@ Parameters region_data_sets - The location of the region data sets to be created by using a template, for example, \ :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`\ . + The location of the region data sets to be created by using a template, for example, :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`. If you want to use a data set that already exists, ensure that the data set is an auxiliary temporary storage data set. @@ -74,7 +74,7 @@ region_data_sets space_primary - The size of the primary space allocated to the auxiliary temporary storage data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the primary space allocated to the auxiliary temporary storage data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the auxiliary temporary storage data set is being created. If the data set already exists, the option has no effect. @@ -86,7 +86,7 @@ space_primary space_secondary - The size of the secondary space allocated to the auxiliary temporary storage data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the secondary space allocated to the auxiliary temporary storage data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the auxiliary temporary storage data set is being created. If the data set already exists, the option has no effect. @@ -98,7 +98,7 @@ space_secondary space_type - The unit portion of the auxiliary temporary storage data set size. Note that this is just the unit; the value for the primary space is specified with \ :literal:`space\_primary`\ and the value for the secondary space is specified with \ :literal:`space\_secondary`\ . + The unit portion of the auxiliary temporary storage data set size. Note that this is just the unit; the value for the primary space is specified with :literal:`space\_primary` and the value for the secondary space is specified with :literal:`space\_secondary`. This option takes effect only when the auxiliary temporary storage data set is being created. If the data set already exists, the option has no effect. @@ -115,11 +115,11 @@ space_type state The intended state for the auxiliary temporary storage data set, which the module aims to achieve. - Specify \ :literal:`absent`\ to remove the auxiliary temporary storage data set entirely, if it already exists. + Specify :literal:`absent` to remove the auxiliary temporary storage data set entirely, if it already exists. - Specify \ :literal:`initial`\ to create the auxiliary temporary storage data set, if it does not exist. If the specified data set exists but is empty, the module leaves the data set as is. If the specified data set exists and has contents, the module deletes the data set and then creates a new, empty data set. + Specify :literal:`initial` to create the auxiliary temporary storage data set, if it does not exist. If the specified data set exists but is empty, the module leaves the data set as is. If the specified data set exists and has contents, the module deletes the data set and then creates a new, empty data set. - Specify \ :literal:`warm`\ to retain an existing auxiliary temporary storage data set in its current state. The module checks whether the specified data set exists, and if it does, leaves the data set as is. If the data set does not exist, the operation fails. + Specify :literal:`warm` to retain an existing auxiliary temporary storage data set in its current state. The module checks whether the specified data set exists, and if it does, leaves the data set as is. If the data set does not exist, the operation fails. | **required**: True diff --git a/_sources/ibm_zos_cics/docs/source/modules/aux_trace.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/aux_trace.rst.txt index 1f4a4084..4a9e354a 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/aux_trace.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/aux_trace.rst.txt @@ -20,7 +20,7 @@ aux_trace -- Allocate auxiliary trace data sets Synopsis -------- -- Allocates the two \ `auxiliary trace `__\ data sets used by a CICS® region. When CICS auxiliary trace is activated, trace entries produced by CICS are written to the auxiliary trace data sets. These data sets can hold large amounts of trace data. +- Allocates the two \ `auxiliary trace `__ data sets used by a CICS® region. When CICS auxiliary trace is activated, trace entries produced by CICS are written to the auxiliary trace data sets. These data sets can hold large amounts of trace data. - The two data sets are referred to as auxiliary trace data set A (DFHAUXT) and auxiliary trace data set B (DFHBUXT). @@ -35,9 +35,9 @@ Parameters destination Identify which one of the auxiliary trace data sets is the target of the operation. If the value is left blank, A is implied, but you can specify A or B. - Specify \ :literal:`A`\ to create or delete the A data set. + Specify :literal:`A` to create or delete the A data set. - Specify \ :literal:`B`\ to create or delete the B data set. This MUST be set for the creation of the B data set. + Specify :literal:`B` to create or delete the B data set. This MUST be set for the creation of the B data set. | **required**: False @@ -48,7 +48,7 @@ destination region_data_sets - The location of the region data sets to be created by using a template, for example, \ :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`\ . + The location of the region data sets to be created by using a template, for example, :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`. If you want to use a data set that already exists, ensure that the data set is an auxiliary trace data set. @@ -107,7 +107,7 @@ region_data_sets space_primary - The size of the primary space allocated to the auxiliary trace data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the primary space allocated to the auxiliary trace data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the auxiliary trace data set is being created. If the data set already exists, the option has no effect. @@ -119,7 +119,7 @@ space_primary space_secondary - The size of the secondary space allocated to the auxiliary trace data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the secondary space allocated to the auxiliary trace data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the auxiliary trace data set is being created. If the data set already exists, the option has no effect. @@ -131,7 +131,7 @@ space_secondary space_type - The unit portion of the auxiliary trace data set size. Note that this is just the unit; the value for the primary space is specified with \ :literal:`space\_primary`\ and the value for the secondary space is specified with \ :literal:`space\_secondary`\ . + The unit portion of the auxiliary trace data set size. Note that this is just the unit; the value for the primary space is specified with :literal:`space\_primary` and the value for the secondary space is specified with :literal:`space\_secondary`. This option takes effect only when the auxiliary trace data set is being created. If the data set already exists, the option has no effect. @@ -148,11 +148,11 @@ space_type state The intended state for the auxiliary trace data set, which the module aims to achieve. - Specify \ :literal:`absent`\ to remove the auxiliary trace data set data set entirely, if it exists. + Specify :literal:`absent` to remove the auxiliary trace data set data set entirely, if it exists. - Specify \ :literal:`initial`\ to create the auxiliary trace data set if it does not exist. If the specified data set exists but is empty, the module leaves the data set as is. If the specified data set exists and has contents, the module deletes the data set and then creates a new, empty one. + Specify :literal:`initial` to create the auxiliary trace data set if it does not exist. If the specified data set exists but is empty, the module leaves the data set as is. If the specified data set exists and has contents, the module deletes the data set and then creates a new, empty one. - Specify \ :literal:`warm`\ to retain an existing auxiliary trace data set in its current state. The module checks whether the specified data set exists, and if it does, leaves the data set as is. If the data set does not exist, the operation fails. + Specify :literal:`warm` to retain an existing auxiliary trace data set in its current state. The module checks whether the specified data set exists, and if it does, leaves the data set as is. If the data set does not exist, the operation fails. | **required**: True diff --git a/_sources/ibm_zos_cics/docs/source/modules/cmci_action.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/cmci_action.rst.txt index 877481ae..bb9d53a9 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/cmci_action.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/cmci_action.rst.txt @@ -20,7 +20,7 @@ cmci_action -- Perform actions on CICS and CICSPlex SM resources Synopsis -------- -- Perform actions on CICS® or CICSPlex® SM definitions and resources, by initiating PUT requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see \ `CMCI REST API `__\ . For information about how to compose PUT requests, see \ `CMCI PUT requests `__\ . +- Perform actions on CICS® or CICSPlex® SM definitions and resources, by initiating PUT requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see \ `CMCI REST API `__. For information about how to compose PUT requests, see \ `CMCI PUT requests `__. @@ -32,8 +32,7 @@ Parameters action_name - The name of the target action. To find the name of the appropriate action, consult the CICSPlex SM resource tables for the target resource type. For example, the \ `PROGRAM resource table reference `__\ lists the eligible actions for CICS programs. - + The name of the target action. To find the name of the appropriate action, consult the CICSPlex SM resource tables for the target resource type. For example, the \ `PROGRAM resource table reference `__ lists the eligible actions for CICS programs. | **required**: True @@ -42,8 +41,7 @@ action_name action_parameters - A list of one or more parameters that control the \ :emphasis:`action`\ operation. Eligible actions and corresponding parameters for the target operation can be found in the resource table reference for the target resource type, as listed in the PERFORM SET operation section of the "Valid CPSM operations" table. For example, the valid parameters for a PROGDEF CSDCOPY action are \ :literal:`AS\_RESOURCE`\ , \ :literal:`DUPACTION`\ and \ :literal:`TO\_CSDGROUP`\ , as found in the \ `PROGDEF resource table reference `__\ . - + A list of one or more parameters that control the :emphasis:`action` operation. Eligible actions and corresponding parameters for the target operation can be found in the resource table reference for the target resource type, as listed in the PERFORM SET operation section of the "Valid CPSM operations" table. For example, the valid parameters for a PROGDEF CSDCOPY action are :literal:`AS\_RESOURCE`\ , :literal:`DUPACTION` and :literal:`TO\_CSDGROUP`\ , as found in the \ `PROGDEF resource table reference `__. | **required**: False @@ -64,7 +62,6 @@ action_parameters Parameter value if any. Can be omitted if the parameter requires no value to be supplied, as shown in the resource table reference. For example, the OVERRIDE parameter for the PROGDEF INSTALL action doesn't require a value. - | **required**: False | **type**: str @@ -76,9 +73,9 @@ cmci_cert Can also be specified using the environment variable CMCI\_CERT. - Required if \ :emphasis:`cmci\_key`\ is specified. + Required if :emphasis:`cmci\_key` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: False @@ -100,9 +97,9 @@ cmci_key Can also be specified using the environment variable CMCI\_KEY. - Required if \ :emphasis:`cmci\_cert`\ is specified. + Required if :emphasis:`cmci\_cert` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: False @@ -111,13 +108,13 @@ cmci_key cmci_password - The password of \ :emphasis:`cmci\_user`\ to pass HTTP basic authentication. + The password of :emphasis:`cmci\_user` to pass HTTP basic authentication. Can also be specified using the environment variable CMCI\_PASSWORD. - Required if \ :emphasis:`cmci\_user`\ is specified. + Required if :emphasis:`cmci\_user` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: false @@ -139,9 +136,9 @@ cmci_user Can also be specified using the environment variable CMCI\_USER. - Required if \ :emphasis:`cmci\_password`\ is specified. + Required if :emphasis:`cmci\_password` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: false @@ -150,11 +147,11 @@ cmci_user context - If CMCI is installed in a CICSPlex® SM environment, \ :emphasis:`context`\ is the name of the CICSplex or CMAS associated with the request, for example, \ :literal:`PLEX1`\ . To determine whether a CMAS can be specified as \ :emphasis:`context`\ , see the \ :strong:`CMAS context`\ entry in the CICSPlex SM resource table reference of a resource. For example, according to the \ `PROGRAM resource table `__\ , CMAS context is not supported for PROGRAM. + If CMCI is installed in a CICSPlex® SM environment, :emphasis:`context` is the name of the CICSplex or CMAS associated with the request, for example, :literal:`PLEX1`. To determine whether a CMAS can be specified as :emphasis:`context`\ , see the :strong:`CMAS context` entry in the CICSPlex SM resource table reference of a resource. For example, according to the \ `PROGRAM resource table `__\ , CMAS context is not supported for PROGRAM. - If CMCI is installed in a single region (SMSS), \ :emphasis:`context`\ is the APPLID of the CICS region associate with the request. + If CMCI is installed in a single region (SMSS), :emphasis:`context` is the APPLID of the CICS region associate with the request. - The value of \ :emphasis:`context`\ must contain no spaces. \ :emphasis:`context`\ is not case-sensitive. + The value of :emphasis:`context` must contain no spaces. :emphasis:`context` is not case-sensitive. | **required**: True @@ -163,7 +160,7 @@ context insecure - When set to \ :literal:`true`\ , disables SSL certificate trust chain verification when using HTTPS. + When set to :literal:`true`\ , disables SSL certificate trust chain verification when using HTTPS. | **required**: False @@ -181,17 +178,17 @@ resources complex_filter - A dictionary representing a complex filter expression. Complex filters are composed of filter expressions, represented as dictionaries. Each dictionary can specify either an attribute expression, a list of filter expressions to be composed with the \ :literal:`and`\ operator, or a list of filter expressions to be composed with the \ :literal:`or`\ operator. + A dictionary representing a complex filter expression. Complex filters are composed of filter expressions, represented as dictionaries. Each dictionary can specify either an attribute expression, a list of filter expressions to be composed with the :literal:`and` operator, or a list of filter expressions to be composed with the :literal:`or` operator. - The \ :literal:`attribute`\ , \ :literal:`and`\ and \ :literal:`or`\ options are mutually exclusive with each other. + The :literal:`attribute`\ , :literal:`and` and :literal:`or` options are mutually exclusive with each other. - Can contain one or more filters. Multiple filters must be combined using \ :literal:`and`\ or \ :literal:`or`\ logical operators. + Can contain one or more filters. Multiple filters must be combined using :literal:`and` or :literal:`or` logical operators. Filters can be nested. - When supplying the \ :literal:`attribute`\ option, you must also supply a \ :literal:`value`\ for the filter. You can also override the default operator of \ :literal:`=`\ with the \ :literal:`operator`\ option. + When supplying the :literal:`attribute` option, you must also supply a :literal:`value` for the filter. You can also override the default operator of :literal:`=` with the :literal:`operator` option. - For examples, see "Examples" in \ :ref:`ibm.ibm\_zos\_cics.cmci\_get `\ . + For examples, see "Examples" in :ref:`ibm.ibm\_zos\_cics.cmci\_get `. | **required**: False @@ -200,9 +197,9 @@ resources and - A list of filter expressions to be combined with an \ :literal:`and`\ operation. + A list of filter expressions to be combined with an :literal:`and` operation. - Filter expressions are nested \ :literal:`complex\_filter`\ elements. Each nested filter expression can be either an \ :literal:`attribute`\ , \ :literal:`and`\ or \ :literal:`or`\ complex filter expression. + Filter expressions are nested :literal:`complex\_filter` elements. Each nested filter expression can be either an :literal:`attribute`\ , :literal:`and` or :literal:`or` complex filter expression. | **required**: False @@ -213,7 +210,7 @@ resources attribute The name of a resource table attribute on which to filter. - For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__\ . + For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -222,8 +219,7 @@ resources operator - These operators are accepted: \ :literal:`\<`\ or \ :literal:`LT`\ (less than), \ :literal:`\<=`\ or \ :literal:`LE`\ (less than or equal to), \ :literal:`=`\ or \ :literal:`EQ`\ (equal to), \ :literal:`\>`\ or \ :literal:`GT`\ (greater than), \ :literal:`\>=`\ or \ :literal:`GE`\ (greater than or equal to), \ :literal:`==`\ or \ :literal:`IS`\ (is), \ :literal:`¬=`\ , \ :literal:`!=`\ , or \ :literal:`NE`\ (not equal to). If not supplied when \ :literal:`attribute`\ is used, \ :literal:`EQ`\ is assumed. - + These operators are accepted: :literal:`\<` or :literal:`LT` (less than), :literal:`\<=` or :literal:`LE` (less than or equal to), :literal:`=` or :literal:`EQ` (equal to), :literal:`\>` or :literal:`GT` (greater than), :literal:`\>=` or :literal:`GE` (greater than or equal to), :literal:`==` or :literal:`IS` (is), :literal:`¬=`\ , :literal:`!=`\ , or :literal:`NE` (not equal to). If not supplied when :literal:`attribute` is used, :literal:`EQ` is assumed. | **required**: False @@ -233,9 +229,9 @@ resources or - A list of filter expressions to be combined with an \ :literal:`or`\ operation. + A list of filter expressions to be combined with an :literal:`or` operation. - Filter expressions are nested \ :literal:`complex\_filter`\ elements. Each nested filter expression can be either an \ :literal:`attribute`\ , \ :literal:`and`\ or \ :literal:`or`\ complex filter expression. + Filter expressions are nested :literal:`complex\_filter` elements. Each nested filter expression can be either an :literal:`attribute`\ , :literal:`and` or :literal:`or` complex filter expression. | **required**: False @@ -246,7 +242,7 @@ resources value The value by which you are to filter the resource attributes. - The value must be a valid one for the resource table attribute as documented in the resource table reference, for example, \ `PROGDEF resource table reference `__\ . + The value must be a valid one for the resource table attribute as documented in the resource table reference, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -258,21 +254,21 @@ resources filter A dictionary with attribute names as keys, and target values, to be used as criteria to filter the set of resources returned from CICSPlex SM. - Filters implicitly use the \ :literal:`=`\ operator. + Filters implicitly use the :literal:`=` operator. - Filters for \ :literal:`string`\ type attributes can use the \ :literal:`\*`\ and \ :literal:`+`\ wildcard operators. + Filters for :literal:`string` type attributes can use the :literal:`\*` and :literal:`+` wildcard operators. - \ :literal:`\*`\ is a wildcard representing an unknown number of characters, and must appear at the end of the value. + :literal:`\*` is a wildcard representing an unknown number of characters, and must appear at the end of the value. - \ :literal:`+`\ is a wildcard representing a single character, and can appear in any place in the value, potentially multiple times. + :literal:`+` is a wildcard representing a single character, and can appear in any place in the value, potentially multiple times. - To use more complicated filter expressions, including a range of different filter operators, and the ability to compose filters with \ :literal:`and`\ and \ :literal:`or`\ operators, see the \ :literal:`complex\_filter`\ parameter. + To use more complicated filter expressions, including a range of different filter operators, and the ability to compose filters with :literal:`and` and :literal:`or` operators, see the :literal:`complex\_filter` parameter. - For more details, see \ `How to build a filter expression `__\ . + For more details, see \ `How to build a filter expression `__. - For examples, see \ :ref:`ibm.ibm\_zos\_cics.cmci\_get `\ . + For examples, see :ref:`ibm.ibm\_zos\_cics.cmci\_get `. - For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__\ . + For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -281,8 +277,7 @@ resources get_parameters - A list of one or more parameters with optional values used to identify the resources for this request. Eligible parameters for identifying the target resources can be found in the resource table reference for the target resource type, as valid parameters for the GET operation in the "Valid CPSM operations" table. For example, the valid parameters for identifying a PROGDEF resource are CICSSYS, CSDGROUP and RESGROUP, as found in the \ `PROGDEF resource table reference `__\ . - + A list of one or more parameters with optional values used to identify the resources for this request. Eligible parameters for identifying the target resources can be found in the resource table reference for the target resource type, as valid parameters for the GET operation in the "Valid CPSM operations" table. For example, the valid parameters for identifying a PROGDEF resource are CICSSYS, CSDGROUP and RESGROUP, as found in the \ `PROGDEF resource table reference `__. | **required**: False @@ -324,11 +319,11 @@ scheme scope Specifies the name of a CICSplex, CICS region group, CICS region, or logical scope that is associated with the query. - \ :emphasis:`scope`\ is a subset of \ :emphasis:`context`\ and limits the request to particular CICS systems or resources. + :emphasis:`scope` is a subset of :emphasis:`context` and limits the request to particular CICS systems or resources. - \ :emphasis:`scope`\ is optional. If it's not specified, the request is limited by the value of \ :emphasis:`context`\ alone. + :emphasis:`scope` is optional. If it's not specified, the request is limited by the value of :emphasis:`context` alone. - The value of \ :emphasis:`scope`\ must contain no spaces. \ :emphasis:`scope`\ is not case-sensitive. + The value of :emphasis:`scope` must contain no spaces. :emphasis:`scope` is not case-sensitive. | **required**: false @@ -347,7 +342,7 @@ timeout type - The CMCI external resource name that maps to the target CICS or CICSPlex SM resource type. For a list of CMCI external resource names, see \ `CMCI resource names `__\ . + The CMCI external resource name that maps to the target CICS or CICSPlex SM resource type. For a list of CMCI external resource names, see \ `CMCI resource names `__. | **required**: True @@ -364,31 +359,29 @@ Examples - name: Newcopy a program cmci_action: - cmci_host: "winmvs2c.hursley.ibm.com" - cmci_port: 10080 - context: "iyk3z0r9" - type: "CICSProgram" + cmci_host: "example.com" + cmci_port: 12345 + context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment + type: CICSProgram action_name: NEWCOPY - resource: + resources: filter: - name: "PONGALT" - get_parameters: - - name: "csdgroup" - value: "JVMGRP" + name: PONGALT - - name: install a bundle in a CICS region + - name: Install a bundle definition from CSD in a CICS region cmci_action: - cmci_host: "winmvs2c.hursley.ibm.com" - cmci_port: "10080" - context: "iyk3z0r9" + cmci_host: "example.com" + cmci_port: 1234 + context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment + scope: IJKLMNOP # scope only applies if you're in a CPSM environment and is the name of a CICS system definition (CSYSDEF) or CICS system group (CSYSGRP) type: CICSBundle - action_name: install - resource: + action_name: CSDINSTALL + resources: filter: - name: "PONGALT" - action_parameters: - - name: "usage" - value: "local" + name: mybund + get_parameters: + - name: csdgroup + value: mygrp diff --git a/_sources/ibm_zos_cics/docs/source/modules/cmci_create.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/cmci_create.rst.txt index 6c1d4d9c..3094349c 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/cmci_create.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/cmci_create.rst.txt @@ -20,7 +20,7 @@ cmci_create -- Create CICS and CICSPlex SM definitions Synopsis -------- -- Create definitional CICS® or CICSPlex® SM resources in CSD and BAS repositories, by initiating POST requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see \ `CMCI REST API `__\ . For information about how to compose POST requests, see \ `CMCI POST requests `__\ . +- Create definitional CICS® or CICSPlex® SM resources in CSD and BAS repositories, by initiating POST requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see \ `CMCI REST API `__. For information about how to compose POST requests, see \ `CMCI POST requests `__. @@ -32,7 +32,7 @@ Parameters attributes - The resource attributes to be created or updated. Available attributes can be found in the CICSPlex® SM resource table reference for the target resource type, for example, \ `PROGDEF resource table reference `__\ . + The resource attributes to be created or updated. Available attributes can be found in the CICSPlex® SM resource table reference for the target resource type, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -45,9 +45,9 @@ cmci_cert Can also be specified using the environment variable CMCI\_CERT. - Required if \ :emphasis:`cmci\_key`\ is specified. + Required if :emphasis:`cmci\_key` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: False @@ -69,9 +69,9 @@ cmci_key Can also be specified using the environment variable CMCI\_KEY. - Required if \ :emphasis:`cmci\_cert`\ is specified. + Required if :emphasis:`cmci\_cert` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: False @@ -80,13 +80,13 @@ cmci_key cmci_password - The password of \ :emphasis:`cmci\_user`\ to pass HTTP basic authentication. + The password of :emphasis:`cmci\_user` to pass HTTP basic authentication. Can also be specified using the environment variable CMCI\_PASSWORD. - Required if \ :emphasis:`cmci\_user`\ is specified. + Required if :emphasis:`cmci\_user` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: false @@ -108,9 +108,9 @@ cmci_user Can also be specified using the environment variable CMCI\_USER. - Required if \ :emphasis:`cmci\_password`\ is specified. + Required if :emphasis:`cmci\_password` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: false @@ -119,11 +119,11 @@ cmci_user context - If CMCI is installed in a CICSPlex® SM environment, \ :emphasis:`context`\ is the name of the CICSplex or CMAS associated with the request, for example, \ :literal:`PLEX1`\ . To determine whether a CMAS can be specified as \ :emphasis:`context`\ , see the \ :strong:`CMAS context`\ entry in the CICSPlex SM resource table reference of a resource. For example, according to the \ `PROGRAM resource table `__\ , CMAS context is not supported for PROGRAM. + If CMCI is installed in a CICSPlex® SM environment, :emphasis:`context` is the name of the CICSplex or CMAS associated with the request, for example, :literal:`PLEX1`. To determine whether a CMAS can be specified as :emphasis:`context`\ , see the :strong:`CMAS context` entry in the CICSPlex SM resource table reference of a resource. For example, according to the \ `PROGRAM resource table `__\ , CMAS context is not supported for PROGRAM. - If CMCI is installed in a single region (SMSS), \ :emphasis:`context`\ is the APPLID of the CICS region associate with the request. + If CMCI is installed in a single region (SMSS), :emphasis:`context` is the APPLID of the CICS region associate with the request. - The value of \ :emphasis:`context`\ must contain no spaces. \ :emphasis:`context`\ is not case-sensitive. + The value of :emphasis:`context` must contain no spaces. :emphasis:`context` is not case-sensitive. | **required**: True @@ -132,8 +132,7 @@ context create_parameters - A list of one or more parameters that control the \ :emphasis:`create`\ operation. Eligible parameters for the CREATE operation can be found in the resource table reference for the target resource type, as listed in the CREATE operation section of the "Valid CPSM operations" table. For example, the valid parameters for a PROGDEF CREATE operation are CSD and RESGROUP, as found in the \ `PROGDEF resource table reference `__\ . - + A list of one or more parameters that control the :emphasis:`create` operation. Eligible parameters for the CREATE operation can be found in the resource table reference for the target resource type, as listed in the CREATE operation section of the "Valid CPSM operations" table. For example, the valid parameters for a PROGDEF CREATE operation are CSD and RESGROUP, as found in the \ `PROGDEF resource table reference `__. | **required**: False @@ -161,7 +160,7 @@ create_parameters insecure - When set to \ :literal:`true`\ , disables SSL certificate trust chain verification when using HTTPS. + When set to :literal:`true`\ , disables SSL certificate trust chain verification when using HTTPS. | **required**: False @@ -183,11 +182,11 @@ scheme scope Specifies the name of a CICSplex, CICS region group, CICS region, or logical scope that is associated with the query. - \ :emphasis:`scope`\ is a subset of \ :emphasis:`context`\ and limits the request to particular CICS systems or resources. + :emphasis:`scope` is a subset of :emphasis:`context` and limits the request to particular CICS systems or resources. - \ :emphasis:`scope`\ is optional. If it's not specified, the request is limited by the value of \ :emphasis:`context`\ alone. + :emphasis:`scope` is optional. If it's not specified, the request is limited by the value of :emphasis:`context` alone. - The value of \ :emphasis:`scope`\ must contain no spaces. \ :emphasis:`scope`\ is not case-sensitive. + The value of :emphasis:`scope` must contain no spaces. :emphasis:`scope` is not case-sensitive. | **required**: false @@ -206,7 +205,7 @@ timeout type - The CMCI external resource name that maps to the target CICS or CICSPlex SM resource type. For a list of CMCI external resource names, see \ `CMCI resource names `__\ . + The CMCI external resource name that maps to the target CICS or CICSPlex SM resource type. For a list of CMCI external resource names, see \ `CMCI resource names `__. | **required**: True @@ -221,18 +220,19 @@ Examples .. code-block:: yaml+jinja - - name: define a BUNDLE in a CSD + - name: Define a BUNDLE in CSD cmci_create: - cmci_host: "winmvs2c.hursley.ibm.com" - cmci_port: 10080 - context: "iyk3z0r9" - type: "CICSDefinitionBundle" + cmci_host: "example.com" + cmci_port: 12345 + context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment + type: CICSDefinitionBundle + scope: IJKLMNOP # scope only applies if you're in a CPSM environment and is the name of a CICS system definition (CSYSDEF) or CICS system group (CSYSGRP) attributes: name: PONGALT bundledir: /u/ibmuser/bundle/pong/pongbundle_1.0.0 csdgroup: JVMGRP create_parameters: - - name: "csd" + - name: csd diff --git a/_sources/ibm_zos_cics/docs/source/modules/cmci_delete.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/cmci_delete.rst.txt index 5ba2e80f..8f7a2228 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/cmci_delete.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/cmci_delete.rst.txt @@ -20,7 +20,7 @@ cmci_delete -- Delete CICS and CICSPlex SM resources Synopsis -------- -- Remove or discard definitional or installed CICS® and CICSPlex® SM resources from CICS regions, by initiating DELETE requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see \ `CMCI REST API `__\ . For information about how to compose DELETE requests, see \ `CMCI DELETE requests `__\ . +- Remove or discard definitional or installed CICS® and CICSPlex® SM resources from CICS regions, by initiating DELETE requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see \ `CMCI REST API `__. For information about how to compose DELETE requests, see \ `CMCI DELETE requests `__. @@ -36,9 +36,9 @@ cmci_cert Can also be specified using the environment variable CMCI\_CERT. - Required if \ :emphasis:`cmci\_key`\ is specified. + Required if :emphasis:`cmci\_key` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: False @@ -60,9 +60,9 @@ cmci_key Can also be specified using the environment variable CMCI\_KEY. - Required if \ :emphasis:`cmci\_cert`\ is specified. + Required if :emphasis:`cmci\_cert` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: False @@ -71,13 +71,13 @@ cmci_key cmci_password - The password of \ :emphasis:`cmci\_user`\ to pass HTTP basic authentication. + The password of :emphasis:`cmci\_user` to pass HTTP basic authentication. Can also be specified using the environment variable CMCI\_PASSWORD. - Required if \ :emphasis:`cmci\_user`\ is specified. + Required if :emphasis:`cmci\_user` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: false @@ -99,9 +99,9 @@ cmci_user Can also be specified using the environment variable CMCI\_USER. - Required if \ :emphasis:`cmci\_password`\ is specified. + Required if :emphasis:`cmci\_password` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: false @@ -110,11 +110,11 @@ cmci_user context - If CMCI is installed in a CICSPlex® SM environment, \ :emphasis:`context`\ is the name of the CICSplex or CMAS associated with the request, for example, \ :literal:`PLEX1`\ . To determine whether a CMAS can be specified as \ :emphasis:`context`\ , see the \ :strong:`CMAS context`\ entry in the CICSPlex SM resource table reference of a resource. For example, according to the \ `PROGRAM resource table `__\ , CMAS context is not supported for PROGRAM. + If CMCI is installed in a CICSPlex® SM environment, :emphasis:`context` is the name of the CICSplex or CMAS associated with the request, for example, :literal:`PLEX1`. To determine whether a CMAS can be specified as :emphasis:`context`\ , see the :strong:`CMAS context` entry in the CICSPlex SM resource table reference of a resource. For example, according to the \ `PROGRAM resource table `__\ , CMAS context is not supported for PROGRAM. - If CMCI is installed in a single region (SMSS), \ :emphasis:`context`\ is the APPLID of the CICS region associate with the request. + If CMCI is installed in a single region (SMSS), :emphasis:`context` is the APPLID of the CICS region associate with the request. - The value of \ :emphasis:`context`\ must contain no spaces. \ :emphasis:`context`\ is not case-sensitive. + The value of :emphasis:`context` must contain no spaces. :emphasis:`context` is not case-sensitive. | **required**: True @@ -123,7 +123,7 @@ context insecure - When set to \ :literal:`true`\ , disables SSL certificate trust chain verification when using HTTPS. + When set to :literal:`true`\ , disables SSL certificate trust chain verification when using HTTPS. | **required**: False @@ -141,17 +141,17 @@ resources complex_filter - A dictionary representing a complex filter expression. Complex filters are composed of filter expressions, represented as dictionaries. Each dictionary can specify either an attribute expression, a list of filter expressions to be composed with the \ :literal:`and`\ operator, or a list of filter expressions to be composed with the \ :literal:`or`\ operator. + A dictionary representing a complex filter expression. Complex filters are composed of filter expressions, represented as dictionaries. Each dictionary can specify either an attribute expression, a list of filter expressions to be composed with the :literal:`and` operator, or a list of filter expressions to be composed with the :literal:`or` operator. - The \ :literal:`attribute`\ , \ :literal:`and`\ and \ :literal:`or`\ options are mutually exclusive with each other. + The :literal:`attribute`\ , :literal:`and` and :literal:`or` options are mutually exclusive with each other. - Can contain one or more filters. Multiple filters must be combined using \ :literal:`and`\ or \ :literal:`or`\ logical operators. + Can contain one or more filters. Multiple filters must be combined using :literal:`and` or :literal:`or` logical operators. Filters can be nested. - When supplying the \ :literal:`attribute`\ option, you must also supply a \ :literal:`value`\ for the filter. You can also override the default operator of \ :literal:`=`\ with the \ :literal:`operator`\ option. + When supplying the :literal:`attribute` option, you must also supply a :literal:`value` for the filter. You can also override the default operator of :literal:`=` with the :literal:`operator` option. - For examples, see "Examples" in \ :ref:`ibm.ibm\_zos\_cics.cmci\_get `\ . + For examples, see "Examples" in :ref:`ibm.ibm\_zos\_cics.cmci\_get `. | **required**: False @@ -160,9 +160,9 @@ resources and - A list of filter expressions to be combined with an \ :literal:`and`\ operation. + A list of filter expressions to be combined with an :literal:`and` operation. - Filter expressions are nested \ :literal:`complex\_filter`\ elements. Each nested filter expression can be either an \ :literal:`attribute`\ , \ :literal:`and`\ or \ :literal:`or`\ complex filter expression. + Filter expressions are nested :literal:`complex\_filter` elements. Each nested filter expression can be either an :literal:`attribute`\ , :literal:`and` or :literal:`or` complex filter expression. | **required**: False @@ -173,7 +173,7 @@ resources attribute The name of a resource table attribute on which to filter. - For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__\ . + For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -182,8 +182,7 @@ resources operator - These operators are accepted: \ :literal:`\<`\ or \ :literal:`LT`\ (less than), \ :literal:`\<=`\ or \ :literal:`LE`\ (less than or equal to), \ :literal:`=`\ or \ :literal:`EQ`\ (equal to), \ :literal:`\>`\ or \ :literal:`GT`\ (greater than), \ :literal:`\>=`\ or \ :literal:`GE`\ (greater than or equal to), \ :literal:`==`\ or \ :literal:`IS`\ (is), \ :literal:`¬=`\ , \ :literal:`!=`\ , or \ :literal:`NE`\ (not equal to). If not supplied when \ :literal:`attribute`\ is used, \ :literal:`EQ`\ is assumed. - + These operators are accepted: :literal:`\<` or :literal:`LT` (less than), :literal:`\<=` or :literal:`LE` (less than or equal to), :literal:`=` or :literal:`EQ` (equal to), :literal:`\>` or :literal:`GT` (greater than), :literal:`\>=` or :literal:`GE` (greater than or equal to), :literal:`==` or :literal:`IS` (is), :literal:`¬=`\ , :literal:`!=`\ , or :literal:`NE` (not equal to). If not supplied when :literal:`attribute` is used, :literal:`EQ` is assumed. | **required**: False @@ -193,9 +192,9 @@ resources or - A list of filter expressions to be combined with an \ :literal:`or`\ operation. + A list of filter expressions to be combined with an :literal:`or` operation. - Filter expressions are nested \ :literal:`complex\_filter`\ elements. Each nested filter expression can be either an \ :literal:`attribute`\ , \ :literal:`and`\ or \ :literal:`or`\ complex filter expression. + Filter expressions are nested :literal:`complex\_filter` elements. Each nested filter expression can be either an :literal:`attribute`\ , :literal:`and` or :literal:`or` complex filter expression. | **required**: False @@ -206,7 +205,7 @@ resources value The value by which you are to filter the resource attributes. - The value must be a valid one for the resource table attribute as documented in the resource table reference, for example, \ `PROGDEF resource table reference `__\ . + The value must be a valid one for the resource table attribute as documented in the resource table reference, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -218,21 +217,21 @@ resources filter A dictionary with attribute names as keys, and target values, to be used as criteria to filter the set of resources returned from CICSPlex SM. - Filters implicitly use the \ :literal:`=`\ operator. + Filters implicitly use the :literal:`=` operator. - Filters for \ :literal:`string`\ type attributes can use the \ :literal:`\*`\ and \ :literal:`+`\ wildcard operators. + Filters for :literal:`string` type attributes can use the :literal:`\*` and :literal:`+` wildcard operators. - \ :literal:`\*`\ is a wildcard representing an unknown number of characters, and must appear at the end of the value. + :literal:`\*` is a wildcard representing an unknown number of characters, and must appear at the end of the value. - \ :literal:`+`\ is a wildcard representing a single character, and can appear in any place in the value, potentially multiple times. + :literal:`+` is a wildcard representing a single character, and can appear in any place in the value, potentially multiple times. - To use more complicated filter expressions, including a range of different filter operators, and the ability to compose filters with \ :literal:`and`\ and \ :literal:`or`\ operators, see the \ :literal:`complex\_filter`\ parameter. + To use more complicated filter expressions, including a range of different filter operators, and the ability to compose filters with :literal:`and` and :literal:`or` operators, see the :literal:`complex\_filter` parameter. - For more details, see \ `How to build a filter expression `__\ . + For more details, see \ `How to build a filter expression `__. - For examples, see \ :ref:`ibm.ibm\_zos\_cics.cmci\_get `\ . + For examples, see :ref:`ibm.ibm\_zos\_cics.cmci\_get `. - For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__\ . + For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -241,8 +240,7 @@ resources get_parameters - A list of one or more parameters with optional values used to identify the resources for this request. Eligible parameters for identifying the target resources can be found in the resource table reference for the target resource type, as valid parameters for the GET operation in the "Valid CPSM operations" table. For example, the valid parameters for identifying a PROGDEF resource are CICSSYS, CSDGROUP and RESGROUP, as found in the \ `PROGDEF resource table reference `__\ . - + A list of one or more parameters with optional values used to identify the resources for this request. Eligible parameters for identifying the target resources can be found in the resource table reference for the target resource type, as valid parameters for the GET operation in the "Valid CPSM operations" table. For example, the valid parameters for identifying a PROGDEF resource are CICSSYS, CSDGROUP and RESGROUP, as found in the \ `PROGDEF resource table reference `__. | **required**: False @@ -284,11 +282,11 @@ scheme scope Specifies the name of a CICSplex, CICS region group, CICS region, or logical scope that is associated with the query. - \ :emphasis:`scope`\ is a subset of \ :emphasis:`context`\ and limits the request to particular CICS systems or resources. + :emphasis:`scope` is a subset of :emphasis:`context` and limits the request to particular CICS systems or resources. - \ :emphasis:`scope`\ is optional. If it's not specified, the request is limited by the value of \ :emphasis:`context`\ alone. + :emphasis:`scope` is optional. If it's not specified, the request is limited by the value of :emphasis:`context` alone. - The value of \ :emphasis:`scope`\ must contain no spaces. \ :emphasis:`scope`\ is not case-sensitive. + The value of :emphasis:`scope` must contain no spaces. :emphasis:`scope` is not case-sensitive. | **required**: false @@ -307,7 +305,7 @@ timeout type - The CMCI external resource name that maps to the target CICS or CICSPlex SM resource type. For a list of CMCI external resource names, see \ `CMCI resource names `__\ . + The CMCI external resource name that maps to the target CICS or CICSPlex SM resource type. For a list of CMCI external resource names, see \ `CMCI resource names `__. | **required**: True @@ -324,26 +322,27 @@ Examples - name: delete a bundle in a CICS region cmci_delete: - cmci_host: "winmvs2c.hursley.ibm.com" - cmci_port: 10080 - context: "iyk3z0r9" + cmci_host: "example.com" + cmci_port: 12345 + context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment type: CICSBundle - resource: + resources: filter: - name: "PONGALT" + name: PONGALT - name: delete a bundle definition in a CICS region cmci_delete: - cmci_host: "winmvs2c.hursley.ibm.com" - cmci_port: 10080 - context: "iyk3z0r9" + cmci_host: "example.com" + cmci_port: 12345 + context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment type: CICSDefinitionBundle - resource: + scope: IJKLMNOP # scope only applies if you're in a CPSM environment and is the name of a CICS system definition (CSYSDEF) or CICS system group (CSYSGRP) + resources: filter: - name: "PONGALT" + name: PONGALT get_parameters: - - name: "csdgroup" - value: "JVMGRP" + - name: csdgroup + value: JVMGRP diff --git a/_sources/ibm_zos_cics/docs/source/modules/cmci_get.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/cmci_get.rst.txt index 3d926506..e76b51ea 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/cmci_get.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/cmci_get.rst.txt @@ -20,7 +20,7 @@ cmci_get -- Query CICS and CICSPlex SM resources and definitions Synopsis -------- -- Get information about installed and definitional CICS® and CICSPlex® SM resources from CICS regions, by initiating GET requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see \ `CMCI REST API `__\ . For information about how to compose GET requests, see \ `CMCI GET requests `__\ . +- Get information about installed and definitional CICS® and CICSPlex® SM resources from CICS regions, by initiating GET requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see \ `CMCI REST API `__. For information about how to compose GET requests, see \ `CMCI GET requests `__. @@ -36,9 +36,9 @@ cmci_cert Can also be specified using the environment variable CMCI\_CERT. - Required if \ :emphasis:`cmci\_key`\ is specified. + Required if :emphasis:`cmci\_key` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: False @@ -60,9 +60,9 @@ cmci_key Can also be specified using the environment variable CMCI\_KEY. - Required if \ :emphasis:`cmci\_cert`\ is specified. + Required if :emphasis:`cmci\_cert` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: False @@ -71,13 +71,13 @@ cmci_key cmci_password - The password of \ :emphasis:`cmci\_user`\ to pass HTTP basic authentication. + The password of :emphasis:`cmci\_user` to pass HTTP basic authentication. Can also be specified using the environment variable CMCI\_PASSWORD. - Required if \ :emphasis:`cmci\_user`\ is specified. + Required if :emphasis:`cmci\_user` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: false @@ -99,9 +99,9 @@ cmci_user Can also be specified using the environment variable CMCI\_USER. - Required if \ :emphasis:`cmci\_password`\ is specified. + Required if :emphasis:`cmci\_password` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: false @@ -110,11 +110,11 @@ cmci_user context - If CMCI is installed in a CICSPlex® SM environment, \ :emphasis:`context`\ is the name of the CICSplex or CMAS associated with the request, for example, \ :literal:`PLEX1`\ . To determine whether a CMAS can be specified as \ :emphasis:`context`\ , see the \ :strong:`CMAS context`\ entry in the CICSPlex SM resource table reference of a resource. For example, according to the \ `PROGRAM resource table `__\ , CMAS context is not supported for PROGRAM. + If CMCI is installed in a CICSPlex® SM environment, :emphasis:`context` is the name of the CICSplex or CMAS associated with the request, for example, :literal:`PLEX1`. To determine whether a CMAS can be specified as :emphasis:`context`\ , see the :strong:`CMAS context` entry in the CICSPlex SM resource table reference of a resource. For example, according to the \ `PROGRAM resource table `__\ , CMAS context is not supported for PROGRAM. - If CMCI is installed in a single region (SMSS), \ :emphasis:`context`\ is the APPLID of the CICS region associate with the request. + If CMCI is installed in a single region (SMSS), :emphasis:`context` is the APPLID of the CICS region associate with the request. - The value of \ :emphasis:`context`\ must contain no spaces. \ :emphasis:`context`\ is not case-sensitive. + The value of :emphasis:`context` must contain no spaces. :emphasis:`context` is not case-sensitive. | **required**: True @@ -135,7 +135,7 @@ fail_on_nodata insecure - When set to \ :literal:`true`\ , disables SSL certificate trust chain verification when using HTTPS. + When set to :literal:`true`\ , disables SSL certificate trust chain verification when using HTTPS. | **required**: False @@ -146,7 +146,7 @@ insecure record_count Identifies a subset of records in the results cache, starting either from the first record in the results cache or from the record specified by the index parameter. If not specified, all the records are returned by default. - A negative number indicates a count back from the last record; for example, \ :literal:`-1`\ means the last record, \ :literal:`-2`\ the last record but one, and so on. + A negative number indicates a count back from the last record; for example, :literal:`-1` means the last record, :literal:`-2` the last record but one, and so on. The count value must be an integer; a value of zero is not permitted. @@ -166,17 +166,17 @@ resources complex_filter - A dictionary representing a complex filter expression. Complex filters are composed of filter expressions, represented as dictionaries. Each dictionary can specify either an attribute expression, a list of filter expressions to be composed with the \ :literal:`and`\ operator, or a list of filter expressions to be composed with the \ :literal:`or`\ operator. + A dictionary representing a complex filter expression. Complex filters are composed of filter expressions, represented as dictionaries. Each dictionary can specify either an attribute expression, a list of filter expressions to be composed with the :literal:`and` operator, or a list of filter expressions to be composed with the :literal:`or` operator. - The \ :literal:`attribute`\ , \ :literal:`and`\ and \ :literal:`or`\ options are mutually exclusive with each other. + The :literal:`attribute`\ , :literal:`and` and :literal:`or` options are mutually exclusive with each other. - Can contain one or more filters. Multiple filters must be combined using \ :literal:`and`\ or \ :literal:`or`\ logical operators. + Can contain one or more filters. Multiple filters must be combined using :literal:`and` or :literal:`or` logical operators. Filters can be nested. - When supplying the \ :literal:`attribute`\ option, you must also supply a \ :literal:`value`\ for the filter. You can also override the default operator of \ :literal:`=`\ with the \ :literal:`operator`\ option. + When supplying the :literal:`attribute` option, you must also supply a :literal:`value` for the filter. You can also override the default operator of :literal:`=` with the :literal:`operator` option. - For examples, see "Examples" in \ :ref:`ibm.ibm\_zos\_cics.cmci\_get `\ . + For examples, see "Examples" in :ref:`ibm.ibm\_zos\_cics.cmci\_get `. | **required**: False @@ -185,9 +185,9 @@ resources and - A list of filter expressions to be combined with an \ :literal:`and`\ operation. + A list of filter expressions to be combined with an :literal:`and` operation. - Filter expressions are nested \ :literal:`complex\_filter`\ elements. Each nested filter expression can be either an \ :literal:`attribute`\ , \ :literal:`and`\ or \ :literal:`or`\ complex filter expression. + Filter expressions are nested :literal:`complex\_filter` elements. Each nested filter expression can be either an :literal:`attribute`\ , :literal:`and` or :literal:`or` complex filter expression. | **required**: False @@ -198,7 +198,7 @@ resources attribute The name of a resource table attribute on which to filter. - For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__\ . + For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -207,8 +207,7 @@ resources operator - These operators are accepted: \ :literal:`\<`\ or \ :literal:`LT`\ (less than), \ :literal:`\<=`\ or \ :literal:`LE`\ (less than or equal to), \ :literal:`=`\ or \ :literal:`EQ`\ (equal to), \ :literal:`\>`\ or \ :literal:`GT`\ (greater than), \ :literal:`\>=`\ or \ :literal:`GE`\ (greater than or equal to), \ :literal:`==`\ or \ :literal:`IS`\ (is), \ :literal:`¬=`\ , \ :literal:`!=`\ , or \ :literal:`NE`\ (not equal to). If not supplied when \ :literal:`attribute`\ is used, \ :literal:`EQ`\ is assumed. - + These operators are accepted: :literal:`\<` or :literal:`LT` (less than), :literal:`\<=` or :literal:`LE` (less than or equal to), :literal:`=` or :literal:`EQ` (equal to), :literal:`\>` or :literal:`GT` (greater than), :literal:`\>=` or :literal:`GE` (greater than or equal to), :literal:`==` or :literal:`IS` (is), :literal:`¬=`\ , :literal:`!=`\ , or :literal:`NE` (not equal to). If not supplied when :literal:`attribute` is used, :literal:`EQ` is assumed. | **required**: False @@ -218,9 +217,9 @@ resources or - A list of filter expressions to be combined with an \ :literal:`or`\ operation. + A list of filter expressions to be combined with an :literal:`or` operation. - Filter expressions are nested \ :literal:`complex\_filter`\ elements. Each nested filter expression can be either an \ :literal:`attribute`\ , \ :literal:`and`\ or \ :literal:`or`\ complex filter expression. + Filter expressions are nested :literal:`complex\_filter` elements. Each nested filter expression can be either an :literal:`attribute`\ , :literal:`and` or :literal:`or` complex filter expression. | **required**: False @@ -231,7 +230,7 @@ resources value The value by which you are to filter the resource attributes. - The value must be a valid one for the resource table attribute as documented in the resource table reference, for example, \ `PROGDEF resource table reference `__\ . + The value must be a valid one for the resource table attribute as documented in the resource table reference, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -243,21 +242,21 @@ resources filter A dictionary with attribute names as keys, and target values, to be used as criteria to filter the set of resources returned from CICSPlex SM. - Filters implicitly use the \ :literal:`=`\ operator. + Filters implicitly use the :literal:`=` operator. - Filters for \ :literal:`string`\ type attributes can use the \ :literal:`\*`\ and \ :literal:`+`\ wildcard operators. + Filters for :literal:`string` type attributes can use the :literal:`\*` and :literal:`+` wildcard operators. - \ :literal:`\*`\ is a wildcard representing an unknown number of characters, and must appear at the end of the value. + :literal:`\*` is a wildcard representing an unknown number of characters, and must appear at the end of the value. - \ :literal:`+`\ is a wildcard representing a single character, and can appear in any place in the value, potentially multiple times. + :literal:`+` is a wildcard representing a single character, and can appear in any place in the value, potentially multiple times. - To use more complicated filter expressions, including a range of different filter operators, and the ability to compose filters with \ :literal:`and`\ and \ :literal:`or`\ operators, see the \ :literal:`complex\_filter`\ parameter. + To use more complicated filter expressions, including a range of different filter operators, and the ability to compose filters with :literal:`and` and :literal:`or` operators, see the :literal:`complex\_filter` parameter. - For more details, see \ `How to build a filter expression `__\ . + For more details, see \ `How to build a filter expression `__. - For examples, see \ :ref:`ibm.ibm\_zos\_cics.cmci\_get `\ . + For examples, see :ref:`ibm.ibm\_zos\_cics.cmci\_get `. - For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__\ . + For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -266,8 +265,7 @@ resources get_parameters - A list of one or more parameters with optional values used to identify the resources for this request. Eligible parameters for identifying the target resources can be found in the resource table reference for the target resource type, as valid parameters for the GET operation in the "Valid CPSM operations" table. For example, the valid parameters for identifying a PROGDEF resource are CICSSYS, CSDGROUP and RESGROUP, as found in the \ `PROGDEF resource table reference `__\ . - + A list of one or more parameters with optional values used to identify the resources for this request. Eligible parameters for identifying the target resources can be found in the resource table reference for the target resource type, as valid parameters for the GET operation in the "Valid CPSM operations" table. For example, the valid parameters for identifying a PROGDEF resource are CICSSYS, CSDGROUP and RESGROUP, as found in the \ `PROGDEF resource table reference `__. | **required**: False @@ -309,11 +307,11 @@ scheme scope Specifies the name of a CICSplex, CICS region group, CICS region, or logical scope that is associated with the query. - \ :emphasis:`scope`\ is a subset of \ :emphasis:`context`\ and limits the request to particular CICS systems or resources. + :emphasis:`scope` is a subset of :emphasis:`context` and limits the request to particular CICS systems or resources. - \ :emphasis:`scope`\ is optional. If it's not specified, the request is limited by the value of \ :emphasis:`context`\ alone. + :emphasis:`scope` is optional. If it's not specified, the request is limited by the value of :emphasis:`context` alone. - The value of \ :emphasis:`scope`\ must contain no spaces. \ :emphasis:`scope`\ is not case-sensitive. + The value of :emphasis:`scope` must contain no spaces. :emphasis:`scope` is not case-sensitive. | **required**: false @@ -332,7 +330,7 @@ timeout type - The CMCI external resource name that maps to the target CICS or CICSPlex SM resource type. For a list of CMCI external resource names, see \ `CMCI resource names `__\ . + The CMCI external resource name that maps to the target CICS or CICSPlex SM resource type. For a list of CMCI external resource names, see \ `CMCI resource names `__. | **required**: True @@ -347,40 +345,40 @@ Examples .. code-block:: yaml+jinja - - name: get 2 LOCFILEs from a CICSplex + - name: Get 2 LOCFILEs from a CICSplex cmci_get: - cmci_host: "winmvs2c.hursley.ibm.com" - cmci_port: 10080 - cmci_user: "ibmuser" + cmci_host: "example.com" + cmci_port: 12345 + cmci_user: ibmuser cmci_password: "123456" - context: "iyk3z0r9" + context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment type: CICSLocalFile record_count: 2 - resource: + resources: filter: dsname: "CTS*" - - name: get a localfile in a CICS region + - name: Get a localfile in a CICS region cmci_get: - cmci_host: "winmvs2c.hursley.ibm.com" - cmci_port: 10080 + cmci_host: "example.com" + cmci_port: 12345 cmci_cert: "./sec/ansible.pem" cmci_key: "./sec/ansible.key" - context: "iyk3z0r9" - type: "CICSLocalFile" + context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment + type: CICSLocalFile resources: filter: dsname: "XIAOPIN*" file: "DFH*" record_count: 1 - - name: get a progdef from a CSD + - name: Get a progdef from CSD cmci_get: - cmci_host: "winmvs2c.hursley.ibm.com" - cmci_port: 10080 + cmci_host: "example.com" + cmci_port: 12345 cmci_cert: "./sec/ansible.pem" cmci_key: "./sec/ansible.key" - context: "iyk3z0r9" + context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment type: cicsdefinitionprogram resources: filter: @@ -390,13 +388,14 @@ Examples value: MYGRP record_count: 1 - - name: pass module even if bundle definition is not found + - name: Ignore errors when bundle definition is not found cmci_get: - cmci_host: "winmvs2c.hursley.ibm.com" - cmci_port: 10080 + cmci_host: "example.com" + cmci_port: 12345 cmci_cert: "./sec/ansible.pem" cmci_key: "./sec/ansible.key" - context: "iyk3z0r9" + context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment + scope: IJKLMNOP # scope only applies if you're in a CPSM environment and is the name of a CICS system definition (CSYSDEF) or CICS system group (CSYSGRP) type: cicsdefinitionbundle resources: filter: @@ -405,16 +404,16 @@ Examples - name: csdgroup value: MYGRP record_count: 1 - fail_on_nodata: "false" + fail_on_nodata: false - name: Using complex_filter to combine filter expressions and change operators cmci_get: - cmci_host: "winmvs2c.hursley.ibm.com" - cmci_port: 10080 + cmci_host: "example.com" + cmci_port: 12345 cmci_cert: "./sec/ansible.pem" cmci_key: "./sec/ansible.key" - context: "iyk3z0r9" - type: "CICSRegion" + context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment + type: CICSRegion resources: complex_filter: or: diff --git a/_sources/ibm_zos_cics/docs/source/modules/cmci_update.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/cmci_update.rst.txt index 2aaf20d0..bc5293df 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/cmci_update.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/cmci_update.rst.txt @@ -20,7 +20,7 @@ cmci_update -- Update CICS and CICSPlex resources and definitions Synopsis -------- -- Make changes to CICS® and CICSPlex® SM resources in CICS regions, by initiating PUT requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see \ `CMCI REST API `__\ . For information about how to compose PUT requests, see \ `CMCI PUT requests `__\ . +- Make changes to CICS® and CICSPlex® SM resources in CICS regions, by initiating PUT requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see \ `CMCI REST API `__. For information about how to compose PUT requests, see \ `CMCI PUT requests `__. @@ -32,7 +32,7 @@ Parameters attributes - The resource attributes to be created or updated. Available attributes can be found in the CICSPlex® SM resource table reference for the target resource type, for example, \ `PROGDEF resource table reference `__\ . + The resource attributes to be created or updated. Available attributes can be found in the CICSPlex® SM resource table reference for the target resource type, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -45,9 +45,9 @@ cmci_cert Can also be specified using the environment variable CMCI\_CERT. - Required if \ :emphasis:`cmci\_key`\ is specified. + Required if :emphasis:`cmci\_key` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: False @@ -69,9 +69,9 @@ cmci_key Can also be specified using the environment variable CMCI\_KEY. - Required if \ :emphasis:`cmci\_cert`\ is specified. + Required if :emphasis:`cmci\_cert` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: False @@ -80,13 +80,13 @@ cmci_key cmci_password - The password of \ :emphasis:`cmci\_user`\ to pass HTTP basic authentication. + The password of :emphasis:`cmci\_user` to pass HTTP basic authentication. Can also be specified using the environment variable CMCI\_PASSWORD. - Required if \ :emphasis:`cmci\_user`\ is specified. + Required if :emphasis:`cmci\_user` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: false @@ -108,9 +108,9 @@ cmci_user Can also be specified using the environment variable CMCI\_USER. - Required if \ :emphasis:`cmci\_password`\ is specified. + Required if :emphasis:`cmci\_password` is specified. - Authentication prioritises certificate authentication if \ :emphasis:`cmci\_cert`\ and \ :emphasis:`cmci\_key`\ are provided, then basic authentication if \ :emphasis:`cmci\_user`\ and \ :emphasis:`cmci\_password`\ are provided, and then unauthenticated if none is provided. + Authentication prioritises certificate authentication if :emphasis:`cmci\_cert` and :emphasis:`cmci\_key` are provided, then basic authentication if :emphasis:`cmci\_user` and :emphasis:`cmci\_password` are provided, and then unauthenticated if none is provided. | **required**: false @@ -119,11 +119,11 @@ cmci_user context - If CMCI is installed in a CICSPlex® SM environment, \ :emphasis:`context`\ is the name of the CICSplex or CMAS associated with the request, for example, \ :literal:`PLEX1`\ . To determine whether a CMAS can be specified as \ :emphasis:`context`\ , see the \ :strong:`CMAS context`\ entry in the CICSPlex SM resource table reference of a resource. For example, according to the \ `PROGRAM resource table `__\ , CMAS context is not supported for PROGRAM. + If CMCI is installed in a CICSPlex® SM environment, :emphasis:`context` is the name of the CICSplex or CMAS associated with the request, for example, :literal:`PLEX1`. To determine whether a CMAS can be specified as :emphasis:`context`\ , see the :strong:`CMAS context` entry in the CICSPlex SM resource table reference of a resource. For example, according to the \ `PROGRAM resource table `__\ , CMAS context is not supported for PROGRAM. - If CMCI is installed in a single region (SMSS), \ :emphasis:`context`\ is the APPLID of the CICS region associate with the request. + If CMCI is installed in a single region (SMSS), :emphasis:`context` is the APPLID of the CICS region associate with the request. - The value of \ :emphasis:`context`\ must contain no spaces. \ :emphasis:`context`\ is not case-sensitive. + The value of :emphasis:`context` must contain no spaces. :emphasis:`context` is not case-sensitive. | **required**: True @@ -132,7 +132,7 @@ context insecure - When set to \ :literal:`true`\ , disables SSL certificate trust chain verification when using HTTPS. + When set to :literal:`true`\ , disables SSL certificate trust chain verification when using HTTPS. | **required**: False @@ -150,17 +150,17 @@ resources complex_filter - A dictionary representing a complex filter expression. Complex filters are composed of filter expressions, represented as dictionaries. Each dictionary can specify either an attribute expression, a list of filter expressions to be composed with the \ :literal:`and`\ operator, or a list of filter expressions to be composed with the \ :literal:`or`\ operator. + A dictionary representing a complex filter expression. Complex filters are composed of filter expressions, represented as dictionaries. Each dictionary can specify either an attribute expression, a list of filter expressions to be composed with the :literal:`and` operator, or a list of filter expressions to be composed with the :literal:`or` operator. - The \ :literal:`attribute`\ , \ :literal:`and`\ and \ :literal:`or`\ options are mutually exclusive with each other. + The :literal:`attribute`\ , :literal:`and` and :literal:`or` options are mutually exclusive with each other. - Can contain one or more filters. Multiple filters must be combined using \ :literal:`and`\ or \ :literal:`or`\ logical operators. + Can contain one or more filters. Multiple filters must be combined using :literal:`and` or :literal:`or` logical operators. Filters can be nested. - When supplying the \ :literal:`attribute`\ option, you must also supply a \ :literal:`value`\ for the filter. You can also override the default operator of \ :literal:`=`\ with the \ :literal:`operator`\ option. + When supplying the :literal:`attribute` option, you must also supply a :literal:`value` for the filter. You can also override the default operator of :literal:`=` with the :literal:`operator` option. - For examples, see "Examples" in \ :ref:`ibm.ibm\_zos\_cics.cmci\_get `\ . + For examples, see "Examples" in :ref:`ibm.ibm\_zos\_cics.cmci\_get `. | **required**: False @@ -169,9 +169,9 @@ resources and - A list of filter expressions to be combined with an \ :literal:`and`\ operation. + A list of filter expressions to be combined with an :literal:`and` operation. - Filter expressions are nested \ :literal:`complex\_filter`\ elements. Each nested filter expression can be either an \ :literal:`attribute`\ , \ :literal:`and`\ or \ :literal:`or`\ complex filter expression. + Filter expressions are nested :literal:`complex\_filter` elements. Each nested filter expression can be either an :literal:`attribute`\ , :literal:`and` or :literal:`or` complex filter expression. | **required**: False @@ -182,7 +182,7 @@ resources attribute The name of a resource table attribute on which to filter. - For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__\ . + For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -191,8 +191,7 @@ resources operator - These operators are accepted: \ :literal:`\<`\ or \ :literal:`LT`\ (less than), \ :literal:`\<=`\ or \ :literal:`LE`\ (less than or equal to), \ :literal:`=`\ or \ :literal:`EQ`\ (equal to), \ :literal:`\>`\ or \ :literal:`GT`\ (greater than), \ :literal:`\>=`\ or \ :literal:`GE`\ (greater than or equal to), \ :literal:`==`\ or \ :literal:`IS`\ (is), \ :literal:`¬=`\ , \ :literal:`!=`\ , or \ :literal:`NE`\ (not equal to). If not supplied when \ :literal:`attribute`\ is used, \ :literal:`EQ`\ is assumed. - + These operators are accepted: :literal:`\<` or :literal:`LT` (less than), :literal:`\<=` or :literal:`LE` (less than or equal to), :literal:`=` or :literal:`EQ` (equal to), :literal:`\>` or :literal:`GT` (greater than), :literal:`\>=` or :literal:`GE` (greater than or equal to), :literal:`==` or :literal:`IS` (is), :literal:`¬=`\ , :literal:`!=`\ , or :literal:`NE` (not equal to). If not supplied when :literal:`attribute` is used, :literal:`EQ` is assumed. | **required**: False @@ -202,9 +201,9 @@ resources or - A list of filter expressions to be combined with an \ :literal:`or`\ operation. + A list of filter expressions to be combined with an :literal:`or` operation. - Filter expressions are nested \ :literal:`complex\_filter`\ elements. Each nested filter expression can be either an \ :literal:`attribute`\ , \ :literal:`and`\ or \ :literal:`or`\ complex filter expression. + Filter expressions are nested :literal:`complex\_filter` elements. Each nested filter expression can be either an :literal:`attribute`\ , :literal:`and` or :literal:`or` complex filter expression. | **required**: False @@ -215,7 +214,7 @@ resources value The value by which you are to filter the resource attributes. - The value must be a valid one for the resource table attribute as documented in the resource table reference, for example, \ `PROGDEF resource table reference `__\ . + The value must be a valid one for the resource table attribute as documented in the resource table reference, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -227,21 +226,21 @@ resources filter A dictionary with attribute names as keys, and target values, to be used as criteria to filter the set of resources returned from CICSPlex SM. - Filters implicitly use the \ :literal:`=`\ operator. + Filters implicitly use the :literal:`=` operator. - Filters for \ :literal:`string`\ type attributes can use the \ :literal:`\*`\ and \ :literal:`+`\ wildcard operators. + Filters for :literal:`string` type attributes can use the :literal:`\*` and :literal:`+` wildcard operators. - \ :literal:`\*`\ is a wildcard representing an unknown number of characters, and must appear at the end of the value. + :literal:`\*` is a wildcard representing an unknown number of characters, and must appear at the end of the value. - \ :literal:`+`\ is a wildcard representing a single character, and can appear in any place in the value, potentially multiple times. + :literal:`+` is a wildcard representing a single character, and can appear in any place in the value, potentially multiple times. - To use more complicated filter expressions, including a range of different filter operators, and the ability to compose filters with \ :literal:`and`\ and \ :literal:`or`\ operators, see the \ :literal:`complex\_filter`\ parameter. + To use more complicated filter expressions, including a range of different filter operators, and the ability to compose filters with :literal:`and` and :literal:`or` operators, see the :literal:`complex\_filter` parameter. - For more details, see \ `How to build a filter expression `__\ . + For more details, see \ `How to build a filter expression `__. - For examples, see \ :ref:`ibm.ibm\_zos\_cics.cmci\_get `\ . + For examples, see :ref:`ibm.ibm\_zos\_cics.cmci\_get `. - For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__\ . + For supported attributes of different resource types, see their resource table reference, for example, \ `PROGDEF resource table reference `__. | **required**: False @@ -250,8 +249,7 @@ resources get_parameters - A list of one or more parameters with optional values used to identify the resources for this request. Eligible parameters for identifying the target resources can be found in the resource table reference for the target resource type, as valid parameters for the GET operation in the "Valid CPSM operations" table. For example, the valid parameters for identifying a PROGDEF resource are CICSSYS, CSDGROUP and RESGROUP, as found in the \ `PROGDEF resource table reference `__\ . - + A list of one or more parameters with optional values used to identify the resources for this request. Eligible parameters for identifying the target resources can be found in the resource table reference for the target resource type, as valid parameters for the GET operation in the "Valid CPSM operations" table. For example, the valid parameters for identifying a PROGDEF resource are CICSSYS, CSDGROUP and RESGROUP, as found in the \ `PROGDEF resource table reference `__. | **required**: False @@ -293,11 +291,11 @@ scheme scope Specifies the name of a CICSplex, CICS region group, CICS region, or logical scope that is associated with the query. - \ :emphasis:`scope`\ is a subset of \ :emphasis:`context`\ and limits the request to particular CICS systems or resources. + :emphasis:`scope` is a subset of :emphasis:`context` and limits the request to particular CICS systems or resources. - \ :emphasis:`scope`\ is optional. If it's not specified, the request is limited by the value of \ :emphasis:`context`\ alone. + :emphasis:`scope` is optional. If it's not specified, the request is limited by the value of :emphasis:`context` alone. - The value of \ :emphasis:`scope`\ must contain no spaces. \ :emphasis:`scope`\ is not case-sensitive. + The value of :emphasis:`scope` must contain no spaces. :emphasis:`scope` is not case-sensitive. | **required**: false @@ -316,7 +314,7 @@ timeout type - The CMCI external resource name that maps to the target CICS or CICSPlex SM resource type. For a list of CMCI external resource names, see \ `CMCI resource names `__\ . + The CMCI external resource name that maps to the target CICS or CICSPlex SM resource type. For a list of CMCI external resource names, see \ `CMCI resource names `__. | **required**: True @@ -325,8 +323,7 @@ type update_parameters - A list of one or more parameters that control the \ :emphasis:`update`\ operation. Eligible parameters for the UPDATE operation can be found in the resource table reference for the target resource type, as listed in the UPDATE operation section of the "Valid CPSM operations" table. For example, the only valid parameter for a PROGDEF UPDATE operation is CSD, as found in the \ `PROGDEF resource table reference `__\ . - + A list of one or more parameters that control the :emphasis:`update` operation. Eligible parameters for the UPDATE operation can be found in the resource table reference for the target resource type, as listed in the UPDATE operation section of the "Valid CPSM operations" table. For example, the only valid parameter for a PROGDEF UPDATE operation is CSD, as found in the \ `PROGDEF resource table reference `__. | **required**: False @@ -360,19 +357,20 @@ Examples .. code-block:: yaml+jinja - - name: update a bundle definition in a CICS region + - name: Update the description of a bundle definition in CSD cmci_update: - cmci_host: "winmvs2c.hursley.ibm.com" - cmci_port: "10080" - context: "iyk3z0r9" - type: "CICSDefinitionBundle" + cmci_host: "example.com" + cmci_port: 12345 + context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment + scope: IJKLMNOP # scope only applies if you're in a CPSM environment and is the name of a CICS system definition (CSYSDEF) or CICS system group (CSYSGRP) + type: CICSDefinitionBundle attributes: - description: "New description" + description: New description update_parameters: - name: csd - resource: + resources: filter: - name: "PONGALT" + name: PONGALT get_parameters: - name: csdgroup value: JVMGRP diff --git a/_sources/ibm_zos_cics/docs/source/modules/csd.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/csd.rst.txt index 20e624aa..b07fcd66 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/csd.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/csd.rst.txt @@ -20,9 +20,9 @@ csd -- Create, remove, and manage the CICS CSD Synopsis -------- -- Create, remove, and manage the \ `CICS system definition data set `__\ (CSD) used by a CICS® region. +- Create, remove, and manage the \ `CICS system definition data set `__ (CSD) used by a CICS® region. - You can use this module when provisioning or de-provisioning a CICS region, or when managing the state of the CSD during upgrades or restarts. -- Use the \ :literal:`state`\ option to specify the intended state for the CSD. For example, use \ :literal:`state=initial`\ to create and initialize a CSD if it doesn't exist, or empty an existing CSD of all records. +- Use the :literal:`state` option to specify the intended state for the CSD. For example, use :literal:`state=initial` to create and initialize a CSD if it doesn't exist, or empty an existing CSD of all records. @@ -34,7 +34,7 @@ Parameters cics_data_sets - The name of the \ :literal:`SDFHLOAD`\ library of the CICS installation, for example, \ :literal:`CICSTS61.CICS.SDFHLOAD`\ . + The name of the :literal:`SDFHLOAD` library of the CICS installation, for example, :literal:`CICSTS61.CICS.SDFHLOAD`. | **required**: True @@ -43,7 +43,7 @@ cics_data_sets sdfhload - The location of the \ :literal:`SDFHLOAD`\ library. If \ :literal:`cics\_data\_sets.template`\ is provided, this value overrides the template. + The location of the :literal:`SDFHLOAD` library. If :literal:`cics\_data\_sets.template` is provided, this value overrides the template. | **required**: False @@ -52,7 +52,7 @@ cics_data_sets template - The templated location of the \ :literal:`SDFHLOAD`\ library. + The templated location of the :literal:`SDFHLOAD` library. | **required**: False @@ -62,7 +62,7 @@ cics_data_sets input_content - The content of the DFHCSDUP script to submit, if you are using the \ :literal:`input\_location=INLINE`\ option. + The content of the DFHCSDUP script to submit, if you are using the :literal:`input\_location=INLINE` option. | **required**: False @@ -73,13 +73,13 @@ input_content input_location The type of location from which to load the DFHCSDUP script. - Specify \ :literal:`DATA\_SET`\ to load from a PDS, PDSE, or sequential data set. + Specify :literal:`DATA\_SET` to load from a PDS, PDSE, or sequential data set. - Specify \ :literal:`USS`\ to load from a file on UNIX System Services (USS). + Specify :literal:`USS` to load from a file on UNIX System Services (USS). - Specify \ :literal:`LOCAL`\ to load from a file local to the Ansible control node. + Specify :literal:`LOCAL` to load from a file local to the Ansible control node. - Specify \ :literal:`INLINE`\ to allow a script to be passed directly through the \ :literal:`input\_content`\ parameter. + Specify :literal:`INLINE` to allow a script to be passed directly through the :literal:`input\_content` parameter. | **required**: False @@ -111,7 +111,7 @@ log Specify UNDO for a CSD that is limited to file backout only. - Specify ALL for a CSD for which you want both forward recovery and file backout. If you specify \ :literal:`log=ALL`\ , you must also specify LOGSTREAMID to identify the 26-character name of the z/OS™ log stream to be used as the forward recovery log. The CICS collection does not support defining forward recovery log streams; you must follow the instructions in \ `Defining forward recovery log streams `__\ . + Specify ALL for a CSD for which you want both forward recovery and file backout. If you specify :literal:`log=ALL`\ , you must also specify LOGSTREAMID to identify the 26-character name of the z/OS™ log stream to be used as the forward recovery log. The CICS collection does not support defining forward recovery log streams; you must follow the instructions in \ `Defining forward recovery log streams `__. | **required**: False @@ -123,7 +123,7 @@ log logstream_id The 26-character name of the z/OS™ log stream to be used as the forward recovery log. - This is required when you use \ :literal:`log=ALL`\ . + This is required when you use :literal:`log=ALL`. | **required**: False @@ -132,7 +132,7 @@ logstream_id region_data_sets - The location of the region data sets to be created by using a template, for example, \ :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`\ . + The location of the region data sets to be created by using a template, for example, :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`. | **required**: True @@ -170,7 +170,7 @@ region_data_sets space_primary - The size of the primary space allocated to the CSD. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the primary space allocated to the CSD. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the CSD is being created. If the CSD already exists, the option has no effect. @@ -182,7 +182,7 @@ space_primary space_secondary - The size of the secondary space allocated to the CSD. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the secondary space allocated to the CSD. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the CSD is being created. If the CSD already exists, the option has no effect. @@ -194,7 +194,7 @@ space_secondary space_type - The unit portion of the CSD size. Note that this is just the unit; the value for the primary space is specified with \ :literal:`space\_primary`\ and the value for the secondary space is specified with \ :literal:`space\_secondary`\ . + The unit portion of the CSD size. Note that this is just the unit; the value for the primary space is specified with :literal:`space\_primary` and the value for the secondary space is specified with :literal:`space\_secondary`. This option takes effect only when the CSD is being created. If the CSD already exists, the option has no effect. @@ -211,13 +211,13 @@ space_type state The intended state for the CSD, which the module aims to achieve. - Specify \ :literal:`absent`\ to remove the CSD entirely, if it already exists. + Specify :literal:`absent` to remove the CSD entirely, if it already exists. - Specify \ :literal:`initial`\ to create the CSD if it does not already exist, and initialize it by using DFHCSDUP. + Specify :literal:`initial` to create the CSD if it does not already exist, and initialize it by using DFHCSDUP. - Specify \ :literal:`warm`\ to retain an existing CSD in its current state. The module verifies whether the specified data set exists and whether it contains any records. If both conditions are met, the module leaves the data set as is. If the data set does not exist or if it is empty, the operation fails. + Specify :literal:`warm` to retain an existing CSD in its current state. The module verifies whether the specified data set exists and whether it contains any records. If both conditions are met, the module leaves the data set as is. If the data set does not exist or if it is empty, the operation fails. - Specify \ :literal:`changed`\ to run a DFHCSDUP script to update an existing CSD. + Specify :literal:`changed` to run a DFHCSDUP script to update an existing CSD. | **required**: True @@ -319,6 +319,7 @@ Examples template: "REGIONS.ABCD0001.<< data_set_name >>" cics_data_sets: template: "CICSTS61.CICS.<< lib_name >>" + state: changed input_location: "USS" input_src: "/u/tester/defs/script.csdup" @@ -328,6 +329,7 @@ Examples template: "REGIONS.ABCD0001.<< data_set_name >>" cics_data_sets: template: "CICSTS61.CICS.<< lib_name >>" + state: changed input_location: "LOCAL" input_src: "/User/tester/defs/script.csdup" @@ -337,6 +339,7 @@ Examples template: "REGIONS.ABCD0001.<< data_set_name >>" cics_data_sets: template: "CICSTS61.CICS.<< lib_name >>" + state: changed input_location: "INLINE" input_content: | DEFINE PROGRAM(TESTPRG1) GROUP(TESTGRP1) diff --git a/_sources/ibm_zos_cics/docs/source/modules/global_catalog.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/global_catalog.rst.txt index 0c605a17..e8d0ef58 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/global_catalog.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/global_catalog.rst.txt @@ -20,9 +20,9 @@ global_catalog -- Create, remove, and manage the CICS global catalog Synopsis -------- -- Create, remove, and manage the \ `global catalog `__\ data set used by a CICS® region. The global catalog is used to store start type information, location of the CICS system log, installed resource definitions, terminal control information and profiles. It contains information that CICS requires on a restart. +- Create, remove, and manage the \ `global catalog `__ data set used by a CICS® region. The global catalog is used to store start type information, location of the CICS system log, installed resource definitions, terminal control information and profiles. It contains information that CICS requires on a restart. - You can use this module when provisioning or de-provisioning a CICS region, or when managing the state of the global catalog during upgrades or restarts. -- Use the \ :literal:`state`\ option to specify the intended state for the global catalog. For example, use \ :literal:`state=initial`\ to create and initialize a global catalog data set if it doesn't exist, or set the autostart override record of an existing global catalog to \ :literal:`AUTOINIT`\ . In either case, a CICS region that is using this global catalog and set with the \ :literal:`START=AUTO`\ system initialization parameter performs an initial start. +- Use the :literal:`state` option to specify the intended state for the global catalog. For example, use :literal:`state=initial` to create and initialize a global catalog data set if it doesn't exist, or set the autostart override record of an existing global catalog to :literal:`AUTOINIT`. In either case, a CICS region that is using this global catalog and set with the :literal:`START=AUTO` system initialization parameter performs an initial start. @@ -34,9 +34,9 @@ Parameters cics_data_sets - The name of the \ :literal:`SDFHLOAD`\ library of the CICS installation, for example, \ :literal:`CICSTS61.CICS.SDFHLOAD`\ . + The name of the :literal:`SDFHLOAD` library of the CICS installation, for example, :literal:`CICSTS61.CICS.SDFHLOAD`. - This module uses the \ :literal:`DFHRMUTL`\ utility internally, which is found in the \ :literal:`SDFHLOAD`\ library. + This module uses the :literal:`DFHRMUTL` utility internally, which is found in the :literal:`SDFHLOAD` library. | **required**: True @@ -45,7 +45,7 @@ cics_data_sets sdfhload - The location of the \ :literal:`SDFHLOAD`\ library. If \ :literal:`cics\_data\_sets.template`\ is provided, this value overrides the template. + The location of the :literal:`SDFHLOAD` library. If :literal:`cics\_data\_sets.template` is provided, this value overrides the template. | **required**: False @@ -54,7 +54,7 @@ cics_data_sets template - The templated location of the \ :literal:`SDFHLOAD`\ library. + The templated location of the :literal:`SDFHLOAD` library. | **required**: False @@ -64,7 +64,7 @@ cics_data_sets region_data_sets - The location of the region data sets to be created by using a template, for example, \ :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`\ . + The location of the region data sets to be created by using a template, for example, :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`. If you want to use a data set that already exists, ensure that the data set is a global catalog data set. @@ -104,7 +104,7 @@ region_data_sets space_primary - The size of the primary space allocated to the global catalog data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the primary space allocated to the global catalog data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the global catalog data set is being created. If the global catalog data set already exists, the option has no effect. @@ -116,7 +116,7 @@ space_primary space_secondary - The size of the secondary space allocated to the global catalog data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the secondary space allocated to the global catalog data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the global catalog data set is being created. If the global catalog data set already exists, the option has no effect. @@ -128,7 +128,7 @@ space_secondary space_type - The unit portion of the global catalog data set size. Note that this is just the unit; the value for the primary space is specified with \ :literal:`space\_primary`\ and the value for the secondary space is specified with \ :literal:`space\_secondary`\ . + The unit portion of the global catalog data set size. Note that this is just the unit; the value for the primary space is specified with :literal:`space\_primary` and the value for the secondary space is specified with :literal:`space\_secondary`. This option takes effect only when the global catalog data set is being created. If the global catalog data set already exists, the option has no effect. @@ -145,13 +145,13 @@ space_type state The intended state for the global catalog data set, which the module aims to achieve. - Specify \ :literal:`absent`\ to remove the global catalog data set entirely, if it exists. + Specify :literal:`absent` to remove the global catalog data set entirely, if it exists. - Specify \ :literal:`initial`\ to set the autostart override record to \ :literal:`AUTOINIT`\ . If the specified global catalog data set does not already exist, the module creates the data set. + Specify :literal:`initial` to set the autostart override record to :literal:`AUTOINIT`. If the specified global catalog data set does not already exist, the module creates the data set. - Specify \ :literal:`cold`\ to set the autostart override record of an existing global catalog to \ :literal:`AUTOCOLD`\ . If the specified global catalog data set does not already exist, the operation fails. + Specify :literal:`cold` to set the autostart override record of an existing global catalog to :literal:`AUTOCOLD`. If the specified global catalog data set does not already exist, the operation fails. - Specify \ :literal:`warm`\ to set the autostart override record of an existing global catalog to \ :literal:`AUTOASIS`\ , undoing any previous setting of \ :literal:`AUTOINIT`\ or \ :literal:`AUTOCOLD`\ . The module verifies whether the specified data set exists and whether it contains any records. If either condition is not met, the operation fails. + Specify :literal:`warm` to set the autostart override record of an existing global catalog to :literal:`AUTOASIS`\ , undoing any previous setting of :literal:`AUTOINIT` or :literal:`AUTOCOLD`. The module verifies whether the specified data set exists and whether it contains any records. If either condition is not met, the operation fails. | **required**: True diff --git a/_sources/ibm_zos_cics/docs/source/modules/local_catalog.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/local_catalog.rst.txt index 73ae81e4..8146f468 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/local_catalog.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/local_catalog.rst.txt @@ -20,9 +20,9 @@ local_catalog -- Create, remove, and manage the CICS local catalog Synopsis -------- -- Create, remove, and manage the \ `local catalog `__\ data set used by a CICS® region. CICS domains use the local catalog to save some of their information between CICS runs and to preserve this information across a cold start. +- Create, remove, and manage the \ `local catalog `__ data set used by a CICS® region. CICS domains use the local catalog to save some of their information between CICS runs and to preserve this information across a cold start. - You can use this module when provisioning or de-provisioning a CICS region, or when managing the state of the local catalog during upgrades or restarts. -- Use the \ :literal:`state`\ option to specify the intended state for the local catalog. For example, use \ :literal:`state=initial`\ to create and initialize a local catalog data set if it doesn't exist, or empty an existing local catalog of all records. +- Use the :literal:`state` option to specify the intended state for the local catalog. For example, use :literal:`state=initial` to create and initialize a local catalog data set if it doesn't exist, or empty an existing local catalog of all records. @@ -34,9 +34,9 @@ Parameters cics_data_sets - The name of the \ :literal:`SDFHLOAD`\ library of the CICS installation, for example, \ :literal:`CICSTS61.CICS.SDFHLOAD`\ . + The name of the :literal:`SDFHLOAD` library of the CICS installation, for example, :literal:`CICSTS61.CICS.SDFHLOAD`. - This module uses the \ :literal:`DFHCCUTL`\ utility internally, which is found in the \ :literal:`SDFHLOAD`\ library. + This module uses the :literal:`DFHCCUTL` utility internally, which is found in the :literal:`SDFHLOAD` library. | **required**: True @@ -45,7 +45,7 @@ cics_data_sets sdfhload - The location of the \ :literal:`SDFHLOAD`\ library. If \ :literal:`cics\_data\_sets.template`\ is provided, this value overrides the template. + The location of the :literal:`SDFHLOAD` library. If :literal:`cics\_data\_sets.template` is provided, this value overrides the template. | **required**: False @@ -54,7 +54,7 @@ cics_data_sets template - The templated location of the \ :literal:`SDFHLOAD`\ library. + The templated location of the :literal:`SDFHLOAD` library. | **required**: False @@ -64,7 +64,7 @@ cics_data_sets region_data_sets - The location of the region data sets to be created by using a template, for example, \ :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`\ . + The location of the region data sets to be created by using a template, for example, :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`. If you want to use a data set that already exists, ensure that the data set is a local catalog data set. @@ -104,7 +104,7 @@ region_data_sets space_primary - The size of the primary space allocated to the local catalog data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the primary space allocated to the local catalog data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the local catalog data set is being created. If the local catalog data set already exists, the option has no effect. @@ -116,7 +116,7 @@ space_primary space_secondary - The size of the secondary space allocated to the local catalog data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the secondary space allocated to the local catalog data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the local catalog data set is being created. If the local catalog data set already exists, the option has no effect. @@ -128,7 +128,7 @@ space_secondary space_type - The unit portion of the local catalog data set size. Note that this is just the unit; the value for the primary space is specified with \ :literal:`space\_primary`\ and the value for the secondary space is specified with \ :literal:`space\_secondary`\ . + The unit portion of the local catalog data set size. Note that this is just the unit; the value for the primary space is specified with :literal:`space\_primary` and the value for the secondary space is specified with :literal:`space\_secondary`. This option takes effect only when the local catalog data set is being created. If the local catalog data set already exists, the option has no effect. @@ -145,11 +145,11 @@ space_type state The intended state for the local catalog, which the module aims to achieve. - Specify \ :literal:`absent`\ to remove the local catalog data set entirely, if it already exists. + Specify :literal:`absent` to remove the local catalog data set entirely, if it already exists. - Specify \ :literal:`initial`\ to create the local catalog data set if it does not exist, or empty this existing local catalog of all records. + Specify :literal:`initial` to create the local catalog data set if it does not exist, or empty this existing local catalog of all records. - Specify \ :literal:`warm`\ to retain an existing local catalog in its current state. The module verifies whether the specified data set exists and whether it contains any records. If both conditions are met, the module leaves the data set as is. If the data set does not exist or if it is empty, the operation fails. + Specify :literal:`warm` to retain an existing local catalog in its current state. The module verifies whether the specified data set exists and whether it contains any records. If both conditions are met, the module leaves the data set as is. If the data set does not exist or if it is empty, the operation fails. | **required**: True diff --git a/_sources/ibm_zos_cics/docs/source/modules/local_request_queue.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/local_request_queue.rst.txt index 34bf6b77..10716a96 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/local_request_queue.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/local_request_queue.rst.txt @@ -20,9 +20,9 @@ local_request_queue -- Create and remove the CICS local request queue Synopsis -------- -- Create and remove the \ `local request queue `__\ data set used by a CICS® region. The local request queue data set stores pending BTS requests. It ensures that, if CICS fails, no pending requests are lost. +- Create and remove the \ `local request queue `__ data set used by a CICS® region. The local request queue data set stores pending BTS requests. It ensures that, if CICS fails, no pending requests are lost. - You can use this module when provisioning or de-provisioning a CICS region. -- Use the \ :literal:`state`\ option to specify the intended state for the local request queue. For example, use \ :literal:`state=initial`\ to create a local request queue data set if it doesn't yet exist, or empty an existing local request queue of all records. +- Use the :literal:`state` option to specify the intended state for the local request queue. For example, use :literal:`state=initial` to create a local request queue data set if it doesn't yet exist, or empty an existing local request queue of all records. @@ -34,7 +34,7 @@ Parameters region_data_sets - The location of the region data sets to be created by using a template, for example, \ :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`\ . + The location of the region data sets to be created by using a template, for example, :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`. If you want to use a data set that already exists, ensure that the data set is a local request queue data set. @@ -74,7 +74,7 @@ region_data_sets space_primary - The size of the primary space allocated to the local request queue data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the primary space allocated to the local request queue data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect when the local request queue data set is being created. If the data set already exists, the option has no effect. @@ -86,7 +86,7 @@ space_primary space_secondary - The size of the secondary space allocated to the local request queue data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the secondary space allocated to the local request queue data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect when the local request queue data set is being created. If the data set already exists, the option has no effect. @@ -98,7 +98,7 @@ space_secondary space_type - The unit portion of the local request queue data set size. Note that this is just the unit; the value for the primary space is specified with \ :literal:`space\_primary`\ and the value for the secondary space is specified with \ :literal:`space\_secondary`\ . + The unit portion of the local request queue data set size. Note that this is just the unit; the value for the primary space is specified with :literal:`space\_primary` and the value for the secondary space is specified with :literal:`space\_secondary`. This option takes effect only when the local request queue data set is being created. If the data set already exists, the option has no effect. @@ -115,11 +115,11 @@ space_type state The intended state for the local request queue, which the module aims to achieve. - Specify \ :literal:`absent`\ to remove the local request queue data set entirely, if it exists. + Specify :literal:`absent` to remove the local request queue data set entirely, if it exists. - Specify \ :literal:`initial`\ to create the local request queue data set if it does not exist, or empty this existing local request queue of all records. + Specify :literal:`initial` to create the local request queue data set if it does not exist, or empty this existing local request queue of all records. - Specify \ :literal:`warm`\ to retain an existing local request queue data set in its current state. The module checks whether the specified data set exists, and if it does, leaves the data set as is. If the data set does not exist, the operation fails. + Specify :literal:`warm` to retain an existing local request queue data set in its current state. The module checks whether the specified data set exists, and if it does, leaves the data set as is. If the data set does not exist, the operation fails. | **required**: True diff --git a/_sources/ibm_zos_cics/docs/source/modules/region_jcl.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/region_jcl.rst.txt index 8e5728b9..b42964e2 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/region_jcl.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/region_jcl.rst.txt @@ -21,7 +21,7 @@ region_jcl -- Create CICS startup JCL data set Synopsis -------- - Create a data set containing the JCL to start a CICS® region. -- The JCL is generated by your input of CICS system data sets and system initialization parameters for CICS startup using the \ :literal:`DFHSIP`\ program. +- The JCL is generated by your input of CICS system data sets and system initialization parameters for CICS startup using the :literal:`DFHSIP` program. @@ -42,7 +42,7 @@ applid cics_data_sets - The data set names of the \ :literal:`SDFHAUTH`\ , \ :literal:`SDFHLOAD`\ and \ :literal:`SDFHLIC`\ libraries, for example, \ :literal:`CICSTS61.CICS.SDFHAUTH`\ and \ :literal:`CICSTS61.CICS.SDFHLOAD`\ . + The data set names of the :literal:`SDFHAUTH`\ , :literal:`SDFHLOAD` and :literal:`SDFHLIC` libraries, for example, :literal:`CICSTS61.CICS.SDFHAUTH` and :literal:`CICSTS61.CICS.SDFHLOAD`. | **required**: True @@ -51,7 +51,7 @@ cics_data_sets sdfhauth - The location of the \ :literal:`SDFHAUTH`\ librarty to override the template. + The location of the :literal:`SDFHAUTH` librarty to override the template. | **required**: False @@ -60,7 +60,7 @@ cics_data_sets sdfhlic - The location of the \ :literal:`SDFHLIC`\ library. If \ :literal:`cics\_data\_sets.template`\ is provided, this value overrides the template. + The location of the :literal:`SDFHLIC` library. If :literal:`cics\_data\_sets.template` is provided, this value overrides the template. | **required**: False @@ -69,7 +69,7 @@ cics_data_sets sdfhload - The location of the \ :literal:`SDFHLOAD`\ library. If \ :literal:`cics\_data\_sets.template`\ is provided, this value overrides the template. + The location of the :literal:`SDFHLOAD` library. If :literal:`cics\_data\_sets.template` is provided, this value overrides the template. | **required**: False @@ -88,7 +88,7 @@ cics_data_sets cpsm_data_sets - The data set names of the \ :literal:`SEYUAUTH`\ and \ :literal:`SEYULOAD`\ libraries, for example, \ :literal:`CTS610.CPSM610.SEYUAUTH`\ . + The data set names of the :literal:`SEYUAUTH` and :literal:`SEYULOAD` libraries, for example, :literal:`CTS610.CPSM610.SEYUAUTH`. | **required**: False @@ -97,7 +97,7 @@ cpsm_data_sets seyuauth - The location of the \ :literal:`SEYUAUTH`\ library. If \ :literal:`cpsm\_data\_sets.template`\ is provided, this value overrides the template. + The location of the :literal:`SEYUAUTH` library. If :literal:`cpsm\_data\_sets.template` is provided, this value overrides the template. | **required**: False @@ -106,7 +106,7 @@ cpsm_data_sets seyuload - The location of the \ :literal:`SEYULOAD`\ library. If \ :literal:`cpsm\_data\_sets.template`\ is provided, this value overrides the template. + The location of the :literal:`SEYULOAD` library. If :literal:`cpsm\_data\_sets.template` is provided, this value overrides the template. | **required**: False @@ -125,7 +125,7 @@ cpsm_data_sets dfhrpl - Any locations of additional data sets other than \ :literal:`SDFHLOAD`\ , \ :literal:`SCEECICS`\ , \ :literal:`SCEERUN`\ , or \ :literal:`SCEERUN2`\ , to be added to the DFHRPL concatenation. The DFHRPL concatenation is where you specify the libraries that contain modules loaded by CICS, for example, the libraries containing your CICS application programs, your CICS control tables, and so on. You can either add data sets at the very top of the list or append them to the bottom of the list. There are other data sets in between, as determined by the defaults or other input parameters; for example, \ :literal:`SCEERUN`\ and \ :literal:`SCEERUN2`\ as specified with \ :literal:`le\_data\_sets`\ , \ :literal:`SDFHLOAD`\ as specified with \ :literal:`cics\_data\_sets`\ , and so on. + Any locations of additional data sets other than :literal:`SDFHLOAD`\ , :literal:`SCEECICS`\ , :literal:`SCEERUN`\ , or :literal:`SCEERUN2`\ , to be added to the DFHRPL concatenation. The DFHRPL concatenation is where you specify the libraries that contain modules loaded by CICS, for example, the libraries containing your CICS application programs, your CICS control tables, and so on. You can either add data sets at the very top of the list or append them to the bottom of the list. There are other data sets in between, as determined by the defaults or other input parameters; for example, :literal:`SCEERUN` and :literal:`SCEERUN2` as specified with :literal:`le\_data\_sets`\ , :literal:`SDFHLOAD` as specified with :literal:`cics\_data\_sets`\ , and so on. | **required**: False @@ -134,7 +134,7 @@ dfhrpl data_sets - The \ :literal:`DFHRPL`\ data sets to be added to the bottom of the list. + The :literal:`DFHRPL` data sets to be added to the bottom of the list. | **required**: False @@ -143,7 +143,7 @@ dfhrpl top_data_sets - The \ :literal:`DFHRPL`\ data sets to be added to the very top of the list. + The :literal:`DFHRPL` data sets to be added to the very top of the list. | **required**: False @@ -262,7 +262,7 @@ job_parameters job_name - The name of the CICS startup job. The default value is \ :literal:`APPLID`\ . + The name of the CICS startup job. The default value is :literal:`APPLID`. | **required**: False @@ -347,7 +347,7 @@ job_parameters le_data_sets - The data set names of the \ :literal:`SCEECICS`\ , \ :literal:`SCEERUN`\ and \ :literal:`SCEERUN2`\ libraries. + The data set names of the :literal:`SCEECICS`\ , :literal:`SCEERUN` and :literal:`SCEERUN2` libraries. | **required**: True @@ -356,7 +356,7 @@ le_data_sets sceecics - The location of the \ :literal:`SCEECICS`\ library. If \ :literal:`le\_data\_sets.template`\ is provided, this value overrides the template. + The location of the :literal:`SCEECICS` library. If :literal:`le\_data\_sets.template` is provided, this value overrides the template. | **required**: False @@ -365,7 +365,7 @@ le_data_sets sceerun - The location of the \ :literal:`SCEERUN`\ library. If \ :literal:`le\_data\_sets.template`\ is provided, this value overrides the template. + The location of the :literal:`SCEERUN` library. If :literal:`le\_data\_sets.template` is provided, this value overrides the template. | **required**: False @@ -374,7 +374,7 @@ le_data_sets sceerun2 - The location of the \ :literal:`SCEERUN2`\ library. If \ :literal:`le\_data\_sets.template`\ is provided, this value overrides the template. + The location of the :literal:`SCEERUN2` library. If :literal:`le\_data\_sets.template` is provided, this value overrides the template. | **required**: False @@ -393,7 +393,7 @@ le_data_sets output_data_sets - The system output data sets such as \ :literal:`CEEMSG`\ and \ :literal:`SYSPRINT`\ , as well as the destination class of the output. + The system output data sets such as :literal:`CEEMSG` and :literal:`SYSPRINT`\ , as well as the destination class of the output. | **required**: False @@ -402,7 +402,7 @@ output_data_sets ceemsg - Overrides the default class to use a custom class for the \ :literal:`CEEMSG`\ data set. Alternatively, omit the \ :literal:`CEEMSG`\ data set from being added to the job. + Overrides the default class to use a custom class for the :literal:`CEEMSG` data set. Alternatively, omit the :literal:`CEEMSG` data set from being added to the job. | **required**: False @@ -411,7 +411,7 @@ output_data_sets omit - Specifies whether \ :literal:`CEEMSG`\ should be excluded from being added to the list of sysout data sets. + Specifies whether :literal:`CEEMSG` should be excluded from being added to the list of sysout data sets. | **required**: False @@ -420,7 +420,7 @@ output_data_sets sysout - Specify the output class to assign the \ :literal:`CEEMSG`\ data set to. + Specify the output class to assign the :literal:`CEEMSG` data set to. | **required**: False @@ -430,7 +430,7 @@ output_data_sets ceeout - Overrides the default class to use a custom class for the \ :literal:`CEEOUT`\ data set. Alternatively, omit the \ :literal:`CEEOUT`\ data set from being added to the job. + Overrides the default class to use a custom class for the :literal:`CEEOUT` data set. Alternatively, omit the :literal:`CEEOUT` data set from being added to the job. | **required**: False @@ -439,7 +439,7 @@ output_data_sets omit - Specifies whether \ :literal:`CEEOUT`\ should be excluded from being added to the list of sysout data sets. + Specifies whether :literal:`CEEOUT` should be excluded from being added to the list of sysout data sets. | **required**: False @@ -448,7 +448,7 @@ output_data_sets sysout - Specify the output class to assign the \ :literal:`CEEOUT`\ data set to. + Specify the output class to assign the :literal:`CEEOUT` data set to. | **required**: False @@ -467,7 +467,7 @@ output_data_sets dfhcxrf - Overrides the default class to use a custom class for the \ :literal:`DFHCXRF`\ data set. Alternatively, omit the \ :literal:`DFHCXRF`\ data set from being added to the job. + Overrides the default class to use a custom class for the :literal:`DFHCXRF` data set. Alternatively, omit the :literal:`DFHCXRF` data set from being added to the job. | **required**: False @@ -476,7 +476,7 @@ output_data_sets omit - Specifies whether \ :literal:`DFHCXRF`\ should be excluded from being added to the list of sysout data sets. + Specifies whether :literal:`DFHCXRF` should be excluded from being added to the list of sysout data sets. | **required**: False @@ -485,7 +485,7 @@ output_data_sets sysout - Specify the output class to assign the \ :literal:`DFHCXRF`\ data set to. + Specify the output class to assign the :literal:`DFHCXRF` data set to. | **required**: False @@ -495,7 +495,7 @@ output_data_sets logusr - Overrides the default class to use a custom class for the \ :literal:`LOGUSR`\ data set. Alternatively, omit the \ :literal:`LOGUSR`\ data set from being added to the job. + Overrides the default class to use a custom class for the :literal:`LOGUSR` data set. Alternatively, omit the :literal:`LOGUSR` data set from being added to the job. | **required**: False @@ -504,7 +504,7 @@ output_data_sets omit - Specifies whether \ :literal:`LOGUSR`\ should be excluded from being added to the list of sysout data sets. + Specifies whether :literal:`LOGUSR` should be excluded from being added to the list of sysout data sets. | **required**: False @@ -513,7 +513,7 @@ output_data_sets sysout - Specify the output class to assign the \ :literal:`LOGUSR`\ data set to. + Specify the output class to assign the :literal:`LOGUSR` data set to. | **required**: False @@ -523,7 +523,7 @@ output_data_sets msgusr - Overrides the default class to use a custom class for the \ :literal:`MSGUSR`\ data set. Alternatively, omit the \ :literal:`MSGUSR`\ data set from being added to the job. + Overrides the default class to use a custom class for the :literal:`MSGUSR` data set. Alternatively, omit the :literal:`MSGUSR` data set from being added to the job. | **required**: False @@ -532,7 +532,7 @@ output_data_sets omit - Specifies whether \ :literal:`MSGUSR`\ should be excluded from being added to the list of sysout data sets. + Specifies whether :literal:`MSGUSR` should be excluded from being added to the list of sysout data sets. | **required**: False @@ -541,7 +541,7 @@ output_data_sets sysout - Specify the output class to assign the \ :literal:`MSGUSR`\ data set to. + Specify the output class to assign the :literal:`MSGUSR` data set to. | **required**: False @@ -551,7 +551,7 @@ output_data_sets sysabend - Overrides the default class to use a custom class for the \ :literal:`SYSABEND`\ data set. Alternatively, omit the \ :literal:`SYSABEND`\ data set from being added to the job. + Overrides the default class to use a custom class for the :literal:`SYSABEND` data set. Alternatively, omit the :literal:`SYSABEND` data set from being added to the job. | **required**: False @@ -560,7 +560,7 @@ output_data_sets omit - Specifies whether \ :literal:`SYSABEND`\ should be excluded from being added to the list of sysout data sets. + Specifies whether :literal:`SYSABEND` should be excluded from being added to the list of sysout data sets. | **required**: False @@ -569,7 +569,7 @@ output_data_sets sysout - Specify the output class to assign the \ :literal:`SYSABEND`\ data set to. + Specify the output class to assign the :literal:`SYSABEND` data set to. | **required**: False @@ -579,7 +579,7 @@ output_data_sets sysout - Overrides the default class to use a custom class for the \ :literal:`SYSOUT`\ data set. Alternatively, omit the \ :literal:`SYSOUT`\ data set from being added to the job. + Overrides the default class to use a custom class for the :literal:`SYSOUT` data set. Alternatively, omit the :literal:`SYSOUT` data set from being added to the job. | **required**: False @@ -588,7 +588,7 @@ output_data_sets omit - Specifies whether \ :literal:`SYSOUT`\ should be excluded from being added to the list of sysout data sets. + Specifies whether :literal:`SYSOUT` should be excluded from being added to the list of sysout data sets. | **required**: False @@ -597,7 +597,7 @@ output_data_sets sysout - Specify the output class to assign the \ :literal:`SYSOUT`\ data set to. + Specify the output class to assign the :literal:`SYSOUT` data set to. | **required**: False @@ -607,7 +607,7 @@ output_data_sets sysprint - Overrides the default class to use a custom class for the \ :literal:`SYSPRINT`\ data set. Alternatively, omit the \ :literal:`SYSPRINT`\ data set from being added to the job. + Overrides the default class to use a custom class for the :literal:`SYSPRINT` data set. Alternatively, omit the :literal:`SYSPRINT` data set from being added to the job. | **required**: False @@ -616,7 +616,7 @@ output_data_sets omit - Specifies whether \ :literal:`SYSPRINT`\ should be excluded from being added to the list of sysout data sets. + Specifies whether :literal:`SYSPRINT` should be excluded from being added to the list of sysout data sets. | **required**: False @@ -625,7 +625,7 @@ output_data_sets sysout - Specify the output class to assign the \ :literal:`SYSPRINT`\ data set to. + Specify the output class to assign the :literal:`SYSPRINT` data set to. | **required**: False @@ -635,7 +635,7 @@ output_data_sets sysudump - Overrides the default class to use a custom class for the \ :literal:`SYSUDUMP`\ data set. Alternatively, omit the \ :literal:`SYSUDUMP`\ data set from being added to the job. + Overrides the default class to use a custom class for the :literal:`SYSUDUMP` data set. Alternatively, omit the :literal:`SYSUDUMP` data set from being added to the job. | **required**: False @@ -644,7 +644,7 @@ output_data_sets omit - Specifies whether \ :literal:`SYSUDUMP`\ should be excluded from being added to the list of sysout data sets. + Specifies whether :literal:`SYSUDUMP` should be excluded from being added to the list of sysout data sets. | **required**: False @@ -653,7 +653,7 @@ output_data_sets sysout - Specify the output class to assign the \ :literal:`SYSUDUMP`\ data set to. + Specify the output class to assign the :literal:`SYSUDUMP` data set to. | **required**: False @@ -664,7 +664,7 @@ output_data_sets region_data_sets - The location of the region data sets, for example, \ :literal:`REGIONS.ABCD01.DFHAUXT`\ , \ :literal:`REGIONS.ABCD01.DFHCSD`\ and \ :literal:`REGIONS.ABCD01.DFHGCD`\ . + The location of the region data sets, for example, :literal:`REGIONS.ABCD01.DFHAUXT`\ , :literal:`REGIONS.ABCD01.DFHCSD` and :literal:`REGIONS.ABCD01.DFHGCD`. | **required**: True @@ -884,7 +884,7 @@ region_data_sets template - The base location of the region data sets to be created by using a template, for example, \ :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`\ . This is not required if you provide the data set name (dsn) of all the data sets individually. + The base location of the region data sets to be created by using a template, for example, :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`. This is not required if you provide the data set name (dsn) of all the data sets individually. | **required**: False @@ -2731,7 +2731,7 @@ sit_parameters You can provide several dictionaries to specify the level of special tracing for several components. Each component is defined by one dictionary. - For information about CICS components and their respetive two-letter code, see \ `Component names and abbreviations `__\ . + For information about CICS components and their respetive two-letter code, see \ `Component names and abbreviations `__. | **required**: False @@ -2879,7 +2879,7 @@ sit_parameters You can provide several dictionaries to specify the level of standard tracing for several components. Each component is defined by one dictionary. For components that are not defined here, their standard tracing levels are determined by STNTR. - For information about CICS components and their respective two-letter code, see \ `Component names and abbreviations `__\ . + For information about CICS components and their respective two-letter code, see \ `Component names and abbreviations `__. | **required**: False @@ -3440,7 +3440,7 @@ sit_parameters space_primary - The size of the primary space allocated to the CICS startup JCL data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the primary space allocated to the CICS startup JCL data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the CICS startup JCL data set is being created. If the CICS startup JCL data set already exists, the option has no effect. @@ -3455,7 +3455,7 @@ space_primary space_secondary - The size of the secondary space allocated to the CICS startup JCL data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the secondary space allocated to the CICS startup JCL data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the CICS startup JCL data set is being created. If the CICS startup JCL data set already exists, the option has no effect. @@ -3470,13 +3470,13 @@ space_secondary space_type - The unit portion of the CICS startup JCL data set size. Note that this is just the unit; the value for the primary space is specified with \ :literal:`space\_primary`\ and the value for the secondary space is specified with \ :literal:`space\_secondary`\ . + The unit portion of the CICS startup JCL data set size. Note that this is just the unit; the value for the primary space is specified with :literal:`space\_primary` and the value for the secondary space is specified with :literal:`space\_secondary`. This option takes effect only when the CICS startup JCL data set is being created. If the CICS startup JCL data set already exists, the option has no effect. The size can be specified in megabytes (\ :literal:`M`\ ), kilobytes (\ :literal:`K`\ ), cylinders (\ :literal:`CYL`\ ), or tracks (\ :literal:`TRK`\ ). - If neither \ :literal:`space\_secondary`\ nor \ :literal:`space\_primary`\ is set, then this value does not have any effect. + If neither :literal:`space\_secondary` nor :literal:`space\_primary` is set, then this value does not have any effect. If the target data set is a member in a PDS or PDSE, then this value does not have any effect. @@ -3491,11 +3491,11 @@ space_type state The intended state for the CICS startup JCL data set, which the module aims to achieve. - Specify \ :literal:`absent`\ to remove the CICS startup JCL data set entirely, if it already exists. + Specify :literal:`absent` to remove the CICS startup JCL data set entirely, if it already exists. - Specify \ :literal:`initial`\ to create the CICS startup JCL data set if it does not already exist. + Specify :literal:`initial` to create the CICS startup JCL data set if it does not already exist. - Specify \ :literal:`warm`\ to retain an existing CICS startup JCL data set in its current state. The module verifies whether the specified data set exists and whether it matches the generated startup JCL. If both conditions are met, the module leaves the data set as is. If the data set does not exist or does not match, the operation fails. + Specify :literal:`warm` to retain an existing CICS startup JCL data set in its current state. The module verifies whether the specified data set exists and whether it matches the generated startup JCL. If both conditions are met, the module leaves the data set as is. If the data set does not exist or does not match, the operation fails. | **required**: True @@ -3505,7 +3505,7 @@ state steplib - Any locations of additional data sets other than \ :literal:`SDFHAUTH`\ , \ :literal:`SDFHLIC`\ , \ :literal:`SCEERUN`\ , or \ :literal:`SCEERUN2`\ , to be added to the STEPLIB concatenation. The STEPLIB concatenation is where you specify the libraries that contain the modules loaded by the z/OS operating system. You can either add data sets at the very top of the list or append them to the bottom of the list. There are other data sets in between, as determined by the defaults or other input parameters; for example, \ :literal:`SEYUAUTH`\ and \ :literal:`SEYULOAD`\ as sepcified with \ :literal:`cpsm\_data\_sets`\ , \ :literal:`SCEERUN`\ and \ :literal:`SCEERUN2`\ as specified with \ :literal:`le\_data\_sets`\ , \ :literal:`SDFHAUTH`\ and \ :literal:`SDFHLIC`\ as specified with \ :literal:`cics\_data\_sets`\ , and so on. + Any locations of additional data sets other than :literal:`SDFHAUTH`\ , :literal:`SDFHLIC`\ , :literal:`SCEERUN`\ , or :literal:`SCEERUN2`\ , to be added to the STEPLIB concatenation. The STEPLIB concatenation is where you specify the libraries that contain the modules loaded by the z/OS operating system. You can either add data sets at the very top of the list or append them to the bottom of the list. There are other data sets in between, as determined by the defaults or other input parameters; for example, :literal:`SEYUAUTH` and :literal:`SEYULOAD` as sepcified with :literal:`cpsm\_data\_sets`\ , :literal:`SCEERUN` and :literal:`SCEERUN2` as specified with :literal:`le\_data\_sets`\ , :literal:`SDFHAUTH` and :literal:`SDFHLIC` as specified with :literal:`cics\_data\_sets`\ , and so on. | **required**: False @@ -3514,7 +3514,7 @@ steplib data_sets - The \ :literal:`STEPLIB`\ data sets to be added to the bottom of the list. + The :literal:`STEPLIB` data sets to be added to the bottom of the list. | **required**: False @@ -3523,7 +3523,7 @@ steplib top_data_sets - The \ :literal:`STEPLIB`\ data sets to be added to the very top of the list. + The :literal:`STEPLIB` data sets to be added to the very top of the list. | **required**: False @@ -3583,6 +3583,7 @@ Examples wlmhealth: "OFF" wrkarea: 2048 sysidnt: ZPY1 + state: initial - name: Create CICS startup JCL data set with more customization ibm.ibm_zos_cics.region_jcl: @@ -3636,6 +3637,7 @@ Examples wlmhealth: "OFF" wrkarea: 2048 sysidnt: ZPY1 + state: initial diff --git a/_sources/ibm_zos_cics/docs/source/modules/stop_region.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/stop_region.rst.txt index 065132c0..79be18ca 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/stop_region.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/stop_region.rst.txt @@ -20,11 +20,11 @@ stop_region -- Stop a CICS region Synopsis -------- -- Stop a CICS region by issuing a CEMT PERFORM SHUTDOWN command, or by canceling the job through the \ :literal:`jobs.cancel`\ utility provided by Z Open Automation Utilities (ZOAU). You can choose the shutdown mode from NORMAL, IMMEDIATE, or CANCEL. -- The \ :literal:`job\_id`\ , \ :literal:`job\_name`\ , or both can be used to shut down a CICS region. If mulitple jobs are running with the same name, the \ :literal:`job\_id`\ is required. +- Stop a CICS region by issuing a CEMT PERFORM SHUTDOWN command, or by canceling the job through the :literal:`jobs.cancel` utility provided by Z Open Automation Utilities (ZOAU). You can choose the shutdown mode from NORMAL, IMMEDIATE, or CANCEL. +- The :literal:`job\_id`\ , :literal:`job\_name`\ , or both can be used to shut down a CICS region. If mulitple jobs are running with the same name, the :literal:`job\_id` is required. - During a NORMAL or IMMEDIATE shutdown, a shutdown assist transaction should run to enable CICS to shut down in a controlled manner. By default, the CICS-supplied shutdown assist transaction, CESD is used. You can specify a custom shutdown assist transaction in the SDTRAN system initialization parameter. The task runs until the region has successfully shut down, or until the shutdown fails. -- You must have a console installed in the CICS region so that the stop\_region module can communicate with CICS. To define a console, you must install a terminal with the CONSNAME attribute set to your TSO user ID. For detailed instructions, see \ `Defining TSO users as console devices `__\ . Add your console definition into one of the resource lists defined on the GRPLIST system initialization parameter so that it gets installed into the CICS region. Alternatively, you can use a DFHCSDUP script to update an existing CSD. This function is provided by the csd module. -- You can specify a timeout, in seconds, for CICS shutdown processing. After a request to stop CICS is issued, if CICS shutdown processing is not completed when this timeout is reached, the module completes in a failed state. By default, the stop\_region module does not use a timeout, that is, the \ :literal:`timeout`\ parameter assumes a value of -1. +- You must have a console installed in the CICS region so that the stop\_region module can communicate with CICS. To define a console, you must install a terminal with the CONSNAME attribute set to your TSO user ID. For detailed instructions, see \ `Defining TSO users as console devices `__. Add your console definition into one of the resource lists defined on the GRPLIST system initialization parameter so that it gets installed into the CICS region. Alternatively, you can use a DFHCSDUP script to update an existing CSD. This function is provided by the csd module. +- You can specify a timeout, in seconds, for CICS shutdown processing. After a request to stop CICS is issued, if CICS shutdown processing is not completed when this timeout is reached, the module completes in a failed state. By default, the stop\_region module does not use a timeout, that is, the :literal:`timeout` parameter assumes a value of -1. @@ -51,7 +51,7 @@ job_name The stop\_region module uses this job name to identify the state of the CICS region and shut it down. - The \ :literal:`job\_name`\ must be unique; if multiple jobs with the same name are running, use \ :literal:`job\_id`\ . + The :literal:`job\_name` must be unique; if multiple jobs with the same name are running, use :literal:`job\_id`. | **required**: False @@ -62,11 +62,11 @@ job_name mode Specify the type of shutdown to be executed on the CICS region. - Specify \ :literal:`normal`\ to perform a normal shutdown. This instructs the stop\_region module to issue a CEMT PERFORM SHUTDOWN command. + Specify :literal:`normal` to perform a normal shutdown. This instructs the stop\_region module to issue a CEMT PERFORM SHUTDOWN command. - Specify \ :literal:`immediate`\ to perform an immediate shutdown. This instructs the stop\_region module to issue a CEMT PERFORM SHUTDOWN IMMEDIATE command. + Specify :literal:`immediate` to perform an immediate shutdown. This instructs the stop\_region module to issue a CEMT PERFORM SHUTDOWN IMMEDIATE command. - Specify \ :literal:`cancel`\ to cancel the CICS region. This instructs the stop\_region module to use ZOAU's \ :literal:`jobs.cancel`\ utility to process the request. + Specify :literal:`cancel` to cancel the CICS region. This instructs the stop\_region module to use ZOAU's :literal:`jobs.cancel` utility to process the request. | **required**: False diff --git a/_sources/ibm_zos_cics/docs/source/modules/td_intrapartition.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/td_intrapartition.rst.txt index bf22970c..675bf67a 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/td_intrapartition.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/td_intrapartition.rst.txt @@ -20,9 +20,9 @@ td_intrapartition -- Create and remove the CICS transient data intrapartition da Synopsis -------- -- Create and remove the \ `transient data intrapartition `__\ data set used by a CICS® region. This data set holds all the data for intrapartition queues. +- Create and remove the \ `transient data intrapartition `__ data set used by a CICS® region. This data set holds all the data for intrapartition queues. - You can use this module when provisioning or de-provisioning a CICS region. -- Use the \ :literal:`state`\ option to specify the intended state for the transient data intrapartition data set. For example, use \ :literal:`state=initial`\ to create a transient data intrapartition data set if it doesn't exist. +- Use the :literal:`state` option to specify the intended state for the transient data intrapartition data set. For example, use :literal:`state=initial` to create a transient data intrapartition data set if it doesn't exist. @@ -34,7 +34,7 @@ Parameters region_data_sets - The location of the region data sets to be created by using a template, for example, \ :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`\ . + The location of the region data sets to be created by using a template, for example, :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`. If you want to use a data set that already exists, ensure that the data set is a transient data intrapartition data set. @@ -74,7 +74,7 @@ region_data_sets space_primary - The size of the primary space allocated to the transient data intrapartition data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the primary space allocated to the transient data intrapartition data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the transient data intrapartition data set is being created. If the data set already exists, the option has no effect. @@ -86,7 +86,7 @@ space_primary space_secondary - The size of the secondary space allocated to the transient data intrapartition data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the secondary space allocated to the transient data intrapartition data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the transient data intrapartition data set is being created. If the data set already exists, the option has no effect. @@ -98,7 +98,7 @@ space_secondary space_type - The unit portion of the transient data intrapartition data set size. Note that this is just the unit; the value for the primary space is specified with \ :literal:`space\_primary`\ and the value for the secondary space is specified with \ :literal:`space\_secondary`\ . + The unit portion of the transient data intrapartition data set size. Note that this is just the unit; the value for the primary space is specified with :literal:`space\_primary` and the value for the secondary space is specified with :literal:`space\_secondary`. This option takes effect only when the transient data intrapartition data set is being created. If the data set already exists, the option has no effect. @@ -115,11 +115,11 @@ space_type state The intended state for the transient data intrapartition data set, which the module aims to achieve. - Specify \ :literal:`absent`\ to remove the transient data intrapartition data set entirely, if it exists. + Specify :literal:`absent` to remove the transient data intrapartition data set entirely, if it exists. - Specify \ :literal:`initial`\ to create the transient data intrapartition data set if it does not exist. If the specified data set exists but is empty, the module leaves the data set as is. If the specified data set exists and has contents, the module deletes the data set and then creates a new, empty one. + Specify :literal:`initial` to create the transient data intrapartition data set if it does not exist. If the specified data set exists but is empty, the module leaves the data set as is. If the specified data set exists and has contents, the module deletes the data set and then creates a new, empty one. - Specify \ :literal:`warm`\ to retain an existing transient data intrapartition data set in its current state. The module verifies whether the specified data set exists and whether it contains any records. If both conditions are met, the module leaves the data set as is. If the data set does not exist or if it is empty, the operation fails. + Specify :literal:`warm` to retain an existing transient data intrapartition data set in its current state. The module verifies whether the specified data set exists and whether it contains any records. If both conditions are met, the module leaves the data set as is. If the data set does not exist or if it is empty, the operation fails. | **required**: True diff --git a/_sources/ibm_zos_cics/docs/source/modules/transaction_dump.rst.txt b/_sources/ibm_zos_cics/docs/source/modules/transaction_dump.rst.txt index f8bf3d49..4f3072d7 100644 --- a/_sources/ibm_zos_cics/docs/source/modules/transaction_dump.rst.txt +++ b/_sources/ibm_zos_cics/docs/source/modules/transaction_dump.rst.txt @@ -20,7 +20,7 @@ transaction_dump -- Allocate transaction dump data sets Synopsis -------- -- Allocates the two \ `transaction dump `__\ data sets used by a CICS® region. +- Allocates the two \ `transaction dump `__ data sets used by a CICS® region. - The two data sets are referred to as transaction dump data set A (DFHDMPA) and transaction dump data set B (DFHDMPB). @@ -35,9 +35,9 @@ Parameters destination Identifies which one of the transaction dump data sets is the target of the operation. If the value is left blank, A is implied, but you can specify A or B. - Specify \ :literal:`A`\ to create or delete the A data set. + Specify :literal:`A` to create or delete the A data set. - Specify \ :literal:`B`\ to create or delete the B data set. This MUST be set for the creation of the B data set. + Specify :literal:`B` to create or delete the B data set. This MUST be set for the creation of the B data set. | **required**: False @@ -48,7 +48,7 @@ destination region_data_sets - The location of the region data sets to be created by using a template, for example, \ :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`\ . + The location of the region data sets to be created by using a template, for example, :literal:`REGIONS.ABCD0001.\<\< data\_set\_name \>\>`. | **required**: True @@ -105,7 +105,7 @@ region_data_sets space_primary - The size of the primary space allocated to the transaction dump data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the primary space allocated to the transaction dump data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the transaction dump data set is being created. If the data set already exists, the option has no effect. @@ -117,7 +117,7 @@ space_primary space_secondary - The size of the secondary space allocated to the transaction dump data set. Note that this is just the value; the unit is specified with \ :literal:`space\_type`\ . + The size of the secondary space allocated to the transaction dump data set. Note that this is just the value; the unit is specified with :literal:`space\_type`. This option takes effect only when the transaction dump data set is being created. If the data set already exists, the option has no effect. @@ -129,7 +129,7 @@ space_secondary space_type - The unit portion of the transaction dump data set size. Note that this is just the unit; the value for the primary space is specified with \ :literal:`space\_primary`\ and the value for the secondary space is specified with \ :literal:`space\_secondary`\ . + The unit portion of the transaction dump data set size. Note that this is just the unit; the value for the primary space is specified with :literal:`space\_primary` and the value for the secondary space is specified with :literal:`space\_secondary`. This option takes effect only when the transaction dump data set is being created. If the data set already exists, the option has no effect. @@ -146,11 +146,11 @@ space_type state The intended state for the transaction dump data set, which the module aims to achieve. - Specify \ :literal:`absent`\ to remove the transaction dump data set entirely, if it exists. + Specify :literal:`absent` to remove the transaction dump data set entirely, if it exists. - Specify \ :literal:`initial`\ to create the transaction dump data set if it does not exist. If the specified data set exists but is empty, the module leaves the data set as is. If the specified data set exists and has contents, the module deletes the data set and then creates a new, empty one. + Specify :literal:`initial` to create the transaction dump data set if it does not exist. If the specified data set exists but is empty, the module leaves the data set as is. If the specified data set exists and has contents, the module deletes the data set and then creates a new, empty one. - Specify \ :literal:`warm`\ to retain an existing transaction dump data set in its current state. The module verifies whether the specified data set exists and whether it contains any records. If both conditions are met, the module leaves the data set as is. If the data set does not exist or if it is empty, the operation fails. + Specify :literal:`warm` to retain an existing transaction dump data set in its current state. The module verifies whether the specified data set exists and whether it contains any records. If both conditions are met, the module leaves the data set as is. If the data set does not exist or if it is empty, the operation fails. | **required**: True 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_archive.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_archive.rst.txt index f2971fc6..86a6ffd8 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 @@ -35,10 +35,14 @@ src USS file paths should be absolute paths. + GDS relative notation is supported. + MVS data sets supported types are: ``SEQ``, ``PDS``, ``PDSE``. VSAMs are not supported. + GDS relative names are supported. e.g. *USER.GDG(-1*). + | **required**: True | **type**: list | **elements**: str @@ -121,12 +125,14 @@ dest 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. + GDS relative names are supported. e.g. *USER.GDG(-1*). + | **required**: True | **type**: str 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. + Remote absolute path, glob, or list of paths, globs, data set name patterns or generation data sets (GDSs) in relative notation for the file, files or data sets to exclude from src list and glob expansion. Patterns (wildcards) can contain one of the following, `?`, `*`. @@ -134,6 +140,8 @@ exclude ? matches any single character. + GDS relative names are supported. e.g. *USER.GDG(-1*). + | **required**: False | **type**: list | **elements**: str @@ -348,7 +356,7 @@ Examples name: tar # Archive multiple files - - name: Compress list of files into a zip + - name: Archive list of files into a zip zos_archive: src: - /tmp/archive/foo.txt @@ -358,7 +366,7 @@ Examples name: zip # Archive one data set into terse - - name: Compress data set into a terse + - name: Archive data set into a terse zos_archive: src: "USER.ARCHIVE.TEST" dest: "USER.ARCHIVE.RESULT.TRS" @@ -366,7 +374,7 @@ Examples name: terse # Use terse with different options - - name: Compress data set into a terse, specify pack algorithm and use adrdssu + - name: Archive data set into a terse, specify pack algorithm and use adrdssu zos_archive: src: "USER.ARCHIVE.TEST" dest: "USER.ARCHIVE.RESULT.TRS" @@ -377,7 +385,7 @@ Examples use_adrdssu: true # Use a pattern to store - - name: Compress data set pattern using xmit + - name: Archive data set pattern using xmit zos_archive: src: "USER.ARCHIVE.*" exclude_sources: "USER.ARCHIVE.EXCLUDE.*" @@ -385,6 +393,27 @@ Examples format: name: xmit + - name: Archive multiple GDSs into a terse + zos_archive: + src: + - "USER.GDG(0)" + - "USER.GDG(-1)" + - "USER.GDG(-2)" + dest: "USER.ARCHIVE.RESULT.TRS" + format: + name: terse + format_options: + use_adrdssu: true + + - name: Archive multiple data sets into a new GDS + zos_archive: + src: "USER.ARCHIVE.*" + dest: "USER.GDG(+1)" + format: + name: terse + format_options: + use_adrdssu: true + 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 69ca57cd..86f4b438 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 @@ -49,6 +49,8 @@ data_sets include When *operation=backup*, specifies a list of data sets or data set patterns to include in the backup. + When *operation=backup* GDS relative names are supported. + When *operation=restore*, specifies a list of data sets or data set patterns to include when restoring from a backup. 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. @@ -66,6 +68,8 @@ data_sets exclude When *operation=backup*, specifies a list of data sets or data set patterns to exclude from the backup. + When *operation=backup* GDS relative names are supported. + When *operation=restore*, specifies a list of data sets or data set patterns to exclude when restoring from a backup. 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." @@ -122,12 +126,14 @@ backup_name 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. + GDS relative names are supported when *operation=restore*. + | **required**: True | **type**: str recover - Specifies if potentially recoverable errors should be ignored. + When *recover=true* and *operation=backup* then potentially recoverable errors will be ignored. | **required**: False | **type**: bool @@ -194,16 +200,18 @@ space_type hlq Specifies the new HLQ to use for the data sets being restored. - Defaults to running user's username. + If no value is provided, the data sets will be restored with their original HLQs. | **required**: False | **type**: str tmp_hlq - Override the default high level qualifier (HLQ) for temporary and backup data sets. + Override the default high level qualifier (HLQ) for temporary data sets used in the module's operation. + + If *tmp_hlq* is set, this value will be applied to all temporary data sets. - The default HLQ is the Ansible user that executes the module and if that is not available, then the value of ``TMPHLQ`` is used. + If *tmp_hlq* is not set, the value will be the username who submits the ansible task, this is the default behavior. If the username can not be identified, the value ``TMPHLQ`` is used. | **required**: False | **type**: str @@ -235,6 +243,15 @@ Examples exclude: user.private.* backup_name: MY.BACKUP.DZP + - name: Backup a list of GDDs to data set my.backup.dzp + zos_backup_restore: + operation: backup + data_sets: + include: + - user.gdg(-1) + - user.gdg(0) + backup_name: my.backup.dzp + - name: Backup all datasets matching the pattern USER.** to UNIX file /tmp/temp_backup.dzp, ignore recoverable errors. zos_backup_restore: operation: backup @@ -275,8 +292,8 @@ Examples space: 1 space_type: g - - name: Restore data sets from backup stored in the UNIX file /tmp/temp_backup.dzp. - Use z/OS username as new HLQ. + - name: Restore data sets from a backup stored in the UNIX file /tmp/temp_backup.dzp. + Restore the data sets with the original high level qualifiers. zos_backup_restore: operation: restore backup_name: /tmp/temp_backup.dzp @@ -332,6 +349,16 @@ Examples +Notes +----- + +.. note:: + 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 to run either the playbook or playbook tasks, who can also obtain escalated privileges to execute as root or another user. + + When using this module, if the RACF FACILITY class profile **STGADMIN.ADR.DUMP.TOLERATE.ENQF** is active, you must have READ access authority to use the module option *recover=true*. If the RACF FACILITY class checking is not set up, any user can use the module option without access to the class. + + If your system uses a different security product, consult that product's documentation to configure the required security classes. + 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 f3eef596..72c6889f 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 @@ -33,6 +33,8 @@ src The USS file must be an absolute pathname. + Generation data set (GDS) relative name of generation already created. e.g. *SOME.CREATION(-1*). + | **required**: True | **type**: str @@ -102,6 +104,8 @@ insertbefore marker_begin This will be inserted at ``{mark}`` in the opening ansible block marker. + Value needs to be different from *marker_end*. + | **required**: False | **type**: str | **default**: BEGIN @@ -110,6 +114,8 @@ marker_begin marker_end This will be inserted at ``{mark}`` in the closing ansible block marker. + Value must be different from *marker_begin*. + | **required**: False | **type**: str | **default**: END @@ -122,6 +128,8 @@ backup The backup file name will be returned on either success or failure of module execution such that data can be retrieved. + Use generation data set (GDS) relative positive name. e.g. *SOME.CREATION(+1*). + | **required**: False | **type**: bool | **default**: False @@ -281,6 +289,20 @@ Examples marker_end: "End Ansible Block Insertion 2" block: "{{ CONTENT }}" + - name: Add a block to a gds + zos_blockinfile: + src: TEST.SOME.CREATION(0) + insertafter: EOF + block: "{{ CONTENT }}" + + - name: Add a block to dataset and backup in a new generation of gds + zos_blockinfile: + src: SOME.CREATION.TEST + insertbefore: BOF + backup: true + backup_name: CREATION.GDS(+1) + block: "{{ CONTENT }}" + 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 611f5136..e838325c 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 @@ -67,6 +67,8 @@ backup_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. + If *backup_name* is a generation data set (GDS), it must be a relative positive name (for example, V(HLQ.USER.GDG(+1\))). + | **required**: False | **type**: str @@ -97,6 +99,8 @@ dest 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. + If ``src`` is a file and ``dest`` a partitioned data set, ``dest`` does not need to include a member in its value, the module can automatically compute the resulting member name from ``src``. + 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 ``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. @@ -105,6 +109,10 @@ dest 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. + ``dest`` can be a previously allocated generation data set (GDS) or a new GDS. + + When ``dest`` is a generation data group (GDG), ``src`` must be a GDG too. The copy will allocate successive new generations in ``dest``, the module will verify it has enough available generations before starting the copy operations. + 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 @@ -163,7 +171,7 @@ force force_lock - By default, when ``dest`` is a MVS data set and is being used by another process with DISP=SHR or DISP=OLD the module will fail. Use ``force_lock`` to bypass 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 DISP=SHR and continue with the copy operation. If set to ``true`` and destination is a MVS data set opened by another process then zos_copy will try to copy using DISP=SHR. @@ -177,13 +185,13 @@ 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 ``true``. By doing so, the module would essentially ignore the stderr stream produced by SFTP and continue execution. + During data transfer through SFTP, the SFTP command directs content to stderr. By default, the module essentially ignores the stderr stream produced by SFTP and continues execution. The user is able to override this behavior by setting this parameter to ``false``. By doing so, any content written to stderr is considered an error by Ansible and will cause the module to fail. 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 - | **default**: False + | **default**: True is_binary @@ -298,6 +306,10 @@ src If ``src`` is a VSAM data set, ``dest`` must also be a VSAM. + If ``src`` is a generation data set (GDS), it must be a previously allocated one. + + If ``src`` is a generation data group (GDG), ``dest`` can be another GDG or a USS directory. + Wildcards can be used to copy multiple PDS/PDSE members to another PDS/PDSE. Required unless using ``content``. @@ -334,6 +346,8 @@ volume dest_data_set Data set attributes to customize a ``dest`` data set to be copied into. + Some attributes only apply when ``dest`` is a generation data group (GDG). + | **required**: False | **type**: dict @@ -343,7 +357,7 @@ dest_data_set | **required**: True | **type**: str - | **choices**: ksds, esds, rrds, lds, seq, pds, pdse, member, basic, library + | **choices**: ksds, esds, rrds, lds, seq, pds, pdse, member, basic, library, gdg space_primary @@ -470,6 +484,68 @@ dest_data_set | **type**: str + limit + Sets the *limit* attribute for a GDG. + + Specifies the maximum number, from 1 to 255(up to 999 if extended), of generations that can be associated with the GDG being defined. + + *limit* is required when *type=gdg*. + + | **required**: False + | **type**: int + + + empty + Sets the *empty* attribute for a GDG. + + 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. + + | **required**: False + | **type**: bool + + + scratch + Sets the *scratch* attribute for a GDG. + + 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 + + + purge + Sets the *purge* attribute for a GDG. + + Specifies whether to override expiration dates when a generation data set (GDS) is rolled off and the ``scratch`` option is set. + + | **required**: False + | **type**: bool + + + extended + Sets the *extended* attribute for a GDG. + + 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. + + | **required**: False + | **type**: bool + + + fifo + Sets the *fifo* attribute for a GDG. + + 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. + + | **required**: False + | **type**: bool + + use_template Whether the module should treat ``src`` as a Jinja2 template and render it before continuing with the rest of the module. @@ -601,6 +677,14 @@ template_parameters | **default**: False + autoescape + Whether to enable autoescape of XML/HTML elements on a template. + + | **required**: False + | **type**: bool + | **default**: True + + @@ -794,6 +878,19 @@ Examples dest: HLQ.PRINT.NEW asa_text: true + - name: Copy a file to a new generation data set. + zos_copy: + src: /path/to/uss/src + dest: HLQ.TEST.GDG(+1) + remote_src: true + + - name: Copy a local file and take a backup of the existing file with a GDS. + zos_copy: + src: /path/to/local/file + dest: /path/to/dest + backup: true + backup_name: HLQ.BACKUP.GDG(+1) + 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 34162d72..7a56cfe8 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 @@ -59,6 +59,9 @@ state 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 *state=absent* and *type=gdg* and the GDG base has active generations the module will complete successfully with *changed=False*. To remove it option *force* needs to be used. If the GDG base does not have active generations the module will complete successfully with *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*. @@ -102,7 +105,7 @@ type | **required**: False | **type**: str | **default**: pds - | **choices**: ksds, esds, rrds, lds, seq, pds, pdse, library, basic, large, member, hfs, zfs + | **choices**: ksds, esds, rrds, lds, seq, pds, pdse, library, basic, large, member, hfs, zfs, gdg space_primary @@ -235,6 +238,74 @@ key_length | **type**: int +empty + Sets the *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 *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 *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 *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. + + *limit* is required when *type=gdg*. + + | **required**: False + | **type**: int + + +purge + Sets the *purge* attribute for Generation Data Groups. + + Specifies whether to override expiration dates when a generation data set (GDS) is rolled off and the ``scratch`` option is set. + + | **required**: False + | **type**: bool + + +scratch + Sets the *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, *volumes* specifies the name of the volume(s) where the data set is located. @@ -285,7 +356,9 @@ force The *force=True* option enables sharing of data sets through the disposition *DISP=SHR*. - The *force=True* only applies to data set members when *state=absent* and *type=member*. + The *force=True* only applies to data set members when *state=absent* and *type=member* and when removing a GDG base with active generations. + + If *force=True*, *type=gdg* and *state=absent* it will force remove a GDG base with active generations. | **required**: False | **type**: bool @@ -375,7 +448,7 @@ batch | **required**: False | **type**: str | **default**: pds - | **choices**: ksds, esds, rrds, lds, seq, pds, pdse, library, basic, large, member, hfs, zfs + | **choices**: ksds, esds, rrds, lds, seq, pds, pdse, library, basic, large, member, hfs, zfs, gdg space_primary @@ -508,6 +581,74 @@ batch | **type**: int + empty + Sets the *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 *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 *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 *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. + + *limit* is required when *type=gdg*. + + | **required**: False + | **type**: int + + + purge + Sets the *purge* attribute for Generation Data Groups. + + Specifies whether to override expiration dates when a generation data set (GDS) is rolled off and the ``scratch`` option is set. + + | **required**: False + | **type**: bool + + + scratch + Sets the *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, *volumes* specifies the name of the volume(s) where the data set is located. 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 2134b336..860a150b 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 @@ -54,12 +54,14 @@ encoding src - The location can be a UNIX System Services (USS) file or path, PS (sequential data set), PDS, PDSE, member of a PDS or PDSE, or KSDS (VSAM data set). + The location can be a UNIX System Services (USS) file or path, PS (sequential data set), PDS, PDSE, member of a PDS or PDSE, a generation data set (GDS) or KSDS (VSAM data set). The USS path or file must be an absolute pathname. If *src* is a USS directory, all files will be encoded. + Encoding a whole generation data group (GDG) is not supported. + | **required**: True | **type**: str @@ -67,7 +69,7 @@ src dest The location where the converted characters are output. - 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). + 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, a generation data set (GDS) or KSDS (VSAM data set). 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. @@ -75,6 +77,8 @@ dest The USS file or path must be an absolute pathname. + If *dest* is a data set, it must be already allocated. + | **required**: False | **type**: str @@ -100,6 +104,8 @@ backup_name ``backup_name`` will be returned on either success or failure of module execution such that data can be retrieved. + If *backup_name* is a generation data set (GDS), it must be a relative positive name (for example, V(HLQ.USER.GDG(+1\))). + | **required**: False | **type**: str @@ -253,6 +259,24 @@ Examples from: ISO8859-1 to: IBM-1047 + - name: Convert file encoding from a USS file to a generation data set + zos_encode: + src: /zos_encode/test.data + dest: USER.TEST.GDG(0) + encoding: + from: ISO8859-1 + to: IBM-1047 + + - name: Convert file encoding from a USS file to a data set while using a GDG for backup + zos_encode: + src: /zos_encode/test.data + dest: USER.TEST.PS + encoding: + from: ISO8859-1 + to: IBM-1047 + backup: true + backup_name: USER.BACKUP.GDG(+1) + 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 87a50a65..0c424fd0 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,11 +16,13 @@ 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, 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, generation data set (GDS), generation data group (GDG), 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 ``dest`` will be overwritten if they are different than ``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. @@ -31,7 +33,7 @@ Parameters src - Name of a UNIX System Services (USS) file, PS (sequential data set), PDS, PDSE, member of a PDS, PDSE or KSDS (VSAM data set). + 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). USS file paths should be absolute paths. @@ -124,13 +126,13 @@ tmp_hlq 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 ``true``. By doing so, the module would essentially ignore the stderr stream produced by sftp and continue execution. + During data transfer through SFTP, the SFTP command directs content to stderr. By default, the module essentially ignores the stderr stream produced by SFTP and continues execution. The user is able to override this behavior by setting this parameter to ``false``. By doing so, any content written to stderr is considered an error by Ansible and will cause the module to fail. 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 - | **default**: False + | **default**: True @@ -187,6 +189,24 @@ 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 + 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 f195b2c2..5c23a28a 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 @@ -121,10 +121,12 @@ resource_type ``cluster`` refers to a VSAM cluster. The ``data`` and ``index`` are the data and index components of a VSAM cluster. + ``gdg`` refers to Generation Data Groups. The module searches based on the GDG base name. + | **required**: False | **type**: str | **default**: nonvsam - | **choices**: nonvsam, cluster, data, index + | **choices**: nonvsam, cluster, data, index, gdg volume @@ -135,6 +137,60 @@ volume | **elements**: str +empty + A GDG attribute, only valid when ``resource_type=gdg``. + + If provided, will search for data sets with *empty* attribute set as provided. + + | **required**: False + | **type**: bool + + +extended + A GDG attribute, only valid when ``resource_type=gdg``. + + If provided, will search for data sets with *extended* attribute set as provided. + + | **required**: False + | **type**: bool + + +fifo + A GDG attribute, only valid when ``resource_type=gdg``. + + If provided, will search for data sets with *fifo* attribute set as provided. + + | **required**: False + | **type**: bool + + +limit + A GDG attribute, only valid when ``resource_type=gdg``. + + If provided, will search for data sets with *limit* attribute set as provided. + + | **required**: False + | **type**: int + + +purge + A GDG attribute, only valid when ``resource_type=gdg``. + + If provided, will search for data sets with *purge* attribute set as provided. + + | **required**: False + | **type**: bool + + +scratch + A GDG attribute, only valid when ``resource_type=gdg``. + + If provided, will search for data sets with *scratch* attribute set as provided. + + | **required**: False + | **type**: bool + + Examples @@ -185,6 +241,15 @@ Examples - USER.* resource_type: cluster + - name: Find all Generation Data Groups starting with the word 'USER' and specific GDG attributes. + zos_find: + patterns: + - USER.* + resource_type: gdg + limit: 30 + scratch: true + purge: true + 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 efea6ea2..c92b12e5 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 @@ -265,7 +265,7 @@ jobs | **type**: str content_type - Type of address space. + Type of address space used by the job, can be one of the following types. - APPC for an APPC Initiator. - JGRP for a JOBGROUP. - JOB for a Batch job. - STC for a Started task. - TSU for a Time sharing user. - \? for an unknown or pending job. | **type**: str | **sample**: JOB 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 ea320dfc..c450ac17 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 @@ -134,6 +134,7 @@ jobs [ { "asid": 0, + "content_type": "JOB", "creation_date": "2023-05-03", "creation_time": "12:13:00", "job_class": "K", @@ -147,6 +148,7 @@ jobs }, { "asid": 4, + "content_type": "JOB", "creation_date": "2023-05-03", "creation_time": "12:14:00", "job_class": "A", @@ -181,6 +183,36 @@ jobs | **type**: str | **sample**: JOB01427 + content_type + Type of address space used by the job, can be one of the following types. + + APPC for an APPC Initiator. + + JGRP for a JOBGROUP. + + JOB for a Batch job. + + STC for a Started task. + + TSU for a Time sharing user. + + \? for an unknown or pending job. + + | **type**: str + | **sample**: STC + + system + The job entry system that MVS uses to do work. + + | **type**: str + | **sample**: STL1 + + subsystem + The job entry subsystem that MVS uses to do work. + + | **type**: str + | **sample**: STL1 + ret_code Return code output collected from job log. 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 a6f55acf..a9a434a4 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,11 +31,13 @@ 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 "USER.TEST","USER.JCL(TEST)") + 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 generation data set from a generation data group (for example, ``USER.TEST.GDG(-2)``). - Or a USS file. (e.g "/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 "/User/tester/ansible-playbook/sample.jcl") + Or a LOCAL file in ansible control node. (e.g ``/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. | **required**: True | **type**: str @@ -44,11 +46,11 @@ src location The JCL location. Supported choices are ``data_set``, ``uss`` or ``local``. - ``data_set`` can be a PDS, PDSE, or sequential data set. + ``data_set`` can be a PDS, PDSE, sequential data set, or a generation data set. ``uss`` means the JCL location is located in UNIX System Services (USS). - ``local`` means locally to the ansible control node. + ``local`` means locally to the Ansible control node. | **required**: False | **type**: str @@ -61,6 +63,8 @@ wait_time_s *wait_time_s* is measured in seconds and must be a value greater than 0 and less than 86400. + The module can submit and forget jobs by setting *wait_time_s* to 0. This way the module will not try to retrieve the job details other than job id. Job details and contents can be retrieved later by using `zos_job_query <./zos_job_query.html>`_ or `zos_job_output <./zos_job_output.html>`_ if needed. + | **required**: False | **type**: int | **default**: 10 @@ -258,6 +262,14 @@ template_parameters | **default**: False + autoescape + Whether to enable autoescape of XML/HTML elements on a template. + + | **required**: False + | **type**: bool + | **default**: True + + @@ -311,6 +323,16 @@ 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 + @@ -580,6 +602,24 @@ jobs | **type**: str | **sample**: HELLO + content_type + Type of address space used by the job, can be one of the following types. + + APPC for an APPC Initiator. + + JGRP for a JOBGROUP. + + JOB for a Batch job. + + STC for a Started task. + + TSU for a Time sharing user. + + \? for an unknown or pending job. + + | **type**: str + | **sample**: STC + duration The total lapsed time the JCL ran for. @@ -700,6 +740,10 @@ jobs Job status `?` indicates status can not be determined. + Job status `TYPRUN=SCAN` indicates that the job had the TYPRUN parameter with SCAN option. + + Job status `NOEXEC` indicates that the job had the TYPRUN parameter with COPY option. + Jobs where status can not be determined will result in None (NULL). | **type**: str 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 4e416f97..a7162127 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 @@ -33,6 +33,8 @@ src The USS file must be an absolute pathname. + Generation data set (GDS) relative name of generation already created. e.g. *SOME.CREATION(-1*). + | **required**: True | **type**: str @@ -139,6 +141,8 @@ backup The backup file name will be return on either success or failure of module execution such that data can be retrieved. + Use generation data set (GDS) relative positive name SOME.CREATION(+1) + | **required**: False | **type**: bool | **default**: False @@ -248,6 +252,20 @@ Examples line: 'Should be a working test now' force: true + - name: Add a line to a gds + zos_lineinfile: + src: SOME.CREATION(-2) + insertafter: EOF + line: 'Should be a working test now' + + - name: Add a line to dataset and backup in a new generation of gds + zos_lineinfile: + src: SOME.CREATION.TEST + insertafter: EOF + backup: true + backup_name: CREATION.GDS(+1) + line: 'Should be a working test now' + 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 d98c9493..904ab293 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 @@ -64,6 +64,14 @@ verbose | **default**: False +max_rc + Specifies the maximum return code allowed for the program output. If the program generates a return code higher than the specified maximum, the module will fail. + + | **required**: False + | **type**: int + | **default**: 0 + + dds The input data source. @@ -105,6 +113,10 @@ dds data_set_name The data set name. + A data set name can be a GDS relative name. + + When using GDS relative name and it is a positive generation, *disposition=new* must be used. + | **required**: False | **type**: str @@ -421,7 +433,7 @@ dds *src_encoding* and *response_encoding* are only used when *type=text*. - ``base64`` means return content in binary mode. + ``base64`` means return content as base64 encoded in binary. | **required**: True | **type**: str @@ -612,7 +624,7 @@ dds *src_encoding* and *response_encoding* are only used when *type=text*. - ``base64`` means return content in binary mode. + ``base64`` means return content as base64 encoded in binary. | **required**: True | **type**: str @@ -686,7 +698,7 @@ dds *src_encoding* and *response_encoding* are only used when *type=text*. - ``base64`` means return content in binary mode. + ``base64`` means return content as base64 encoded in binary. | **required**: True | **type**: str @@ -743,7 +755,7 @@ dds *src_encoding* and *response_encoding* are only used when *type=text*. - ``base64`` means return content in binary mode. + ``base64`` means return content as base64 encoded in binary. | **required**: True | **type**: str @@ -840,6 +852,10 @@ dds data_set_name The data set name. + A data set name can be a GDS relative name. + + When using GDS relative name and it is a positive generation, *disposition=new* must be used. + | **required**: False | **type**: str @@ -1156,7 +1172,7 @@ dds *src_encoding* and *response_encoding* are only used when *type=text*. - ``base64`` means return content in binary mode. + ``base64`` means return content as base64 encoded in binary. | **required**: True | **type**: str @@ -1340,7 +1356,7 @@ dds *src_encoding* and *response_encoding* are only used when *type=text*. - ``base64`` means return content in binary mode. + ``base64`` means return content as base64 encoded in binary. | **required**: True | **type**: str @@ -1407,7 +1423,7 @@ dds *src_encoding* and *response_encoding* are only used when *type=text*. - ``base64`` means return content in binary mode. + ``base64`` means return content as base64 encoded in binary. | **required**: True | **type**: str @@ -1748,6 +1764,37 @@ Examples VOLUMES(222222) - UNIQUE) + - name: List data sets matching pattern in catalog, + save output to a new generation of gdgs. + zos_mvs_raw: + program_name: idcams + auth: true + dds: + - dd_data_set: + dd_name: sysprint + data_set_name: TEST.CREATION(+1) + disposition: new + return_content: + type: text + - dd_input: + dd_name: sysin + content: " LISTCAT ENTRIES('SOME.DATASET.*')" + + - name: List data sets matching pattern in catalog, + save output to a gds already created. + zos_mvs_raw: + program_name: idcams + auth: true + dds: + - dd_data_set: + dd_name: sysprint + data_set_name: TEST.CREATION(-2) + return_content: + type: text + - dd_input: + dd_name: sysin + content: " LISTCAT ENTRIES('SOME.DATASET.*')" + @@ -1842,3 +1889,15 @@ backups | **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 d05126d1..83e43089 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 @@ -37,6 +37,8 @@ cmd For example, to display job by job name the command would be ``cmd:"\\$dj''HELLO''"`` + By default, the command will be converted to uppercase before execution, to control this behavior, see the *case_sensitive* option below. + | **required**: True | **type**: str @@ -63,6 +65,14 @@ wait_time_s | **default**: 1 +case_sensitive + If ``true``, the command will not be converted to uppercase before execution. Instead, the casing will be preserved just as it was written in a task. + + | **required**: False + | **type**: bool + | **default**: False + + Examples @@ -96,6 +106,12 @@ Examples +Notes +----- + +.. note:: + Commands may need to use specific prefixes like $, they can be discovered by issuing the following command ``D OPDATA,PREFIX``. + 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 10660d38..735bfbf3 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 @@ -232,6 +232,14 @@ template_parameters | **default**: False + autoescape + Whether to enable autoescape of XML/HTML elements on a template. + + | **required**: False + | **type**: bool + | **default**: True + + @@ -294,7 +302,7 @@ Notes All local scripts copied to a remote z/OS system will be removed from the managed node before the module finishes executing. - Execution permissions for the group assigned to the script will be added to remote scripts. The original permissions for remote scripts will be restored by the module before the task ends. + Execution permissions for the group assigned to the script will be added to remote scripts if they are missing. The original permissions for remote scripts will be restored by the module before the task ends. The module will only add execution permissions for the file owner. 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 f2d7aba8..07988a47 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 @@ -39,6 +39,8 @@ src MVS data sets supported types are ``SEQ``, ``PDS``, ``PDSE``. + GDS relative names are supported. e.g. *USER.GDG(-1*). + | **required**: True | **type**: str @@ -149,6 +151,8 @@ owner include A list of directories, files or data set names to extract from the archive. + GDS relative names are supported. e.g. *USER.GDG(-1*). + When ``include`` is set, only those files will we be extracted leaving the remaining files in the archive. Mutually exclusive with exclude. @@ -161,6 +165,8 @@ include exclude List the directory and file or data set names that you would like to exclude from the unarchive action. + GDS relative names are supported. e.g. *USER.GDG(-1*). + Mutually exclusive with include. | **required**: False @@ -385,6 +391,13 @@ Examples - USER.ARCHIVE.TEST1 - USER.ARCHIVE.TEST2 + # Unarchive a GDS + - name: Unarchive a terse data set and excluding data sets from unpacking. + zos_unarchive: + src: "USER.ARCHIVE(0)" + format: + name: terse + # List option - name: List content from XMIT zos_unarchive: diff --git a/_sources/ibm_zos_core/docs/source/modules/zos_zfs_resize.rst.txt b/_sources/ibm_zos_core/docs/source/modules/zos_zfs_resize.rst.txt new file mode 100644 index 00000000..7dac9b2e --- /dev/null +++ b/_sources/ibm_zos_core/docs/source/modules/zos_zfs_resize.rst.txt @@ -0,0 +1,298 @@ + +:github_url: https://github.com/ansible-collections/ibm_zos_core/blob/dev/plugins/modules/zos_zfs_resize.py + +.. _zos_zfs_resize_module: + + +zos_zfs_resize -- Resize a zfs data set. +======================================== + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- The module `zos_zfs_resize. `_ can resize a zFS aggregate data set. +- The *target* data set must be a unique and a Fully Qualified Name (FQN) of a z/OS zFS aggregate data set. +- The data set must be attached as read-write. +- *size* must be provided. + + + + + +Parameters +---------- + + +target + The Fully Qualified Name of the zFS data set that will be resized. + + | **required**: True + | **type**: str + + +size + The desired size of the data set after the resizing is performed. + + | **required**: True + | **type**: int + + +space_type + The unit of measurement to use when defining the size. + + Valid units are ``k`` (kilobytes), ``m`` (megabytes), ``g`` (gigabytes), ``cyl`` (cylinders), and ``trk`` (tracks). + + | **required**: False + | **type**: str + | **default**: k + | **choices**: k, m, g, cyl, trk + + +no_auto_increase + Option controls whether the data set size will be automatically increased when performing a shrink operation. + + When set to ``true``, during the shrinking of the zFS aggregate, if more space be needed the total size will not be increased and the module will fail. + + | **required**: False + | **type**: bool + | **default**: False + + +verbose + Return diagnostic messages that describe the module's execution. + + Verbose includes standard out (stdout) of the module's execution which can be excessive, to avoid writing this to stdout, optionally you can set the ``trace_destination`` instead. + + | **required**: False + | **type**: bool + | **default**: False + + +trace_destination + Specify a unique USS file name or data set name for ``trace_destination``. + + If the destination ``trace_destination`` is a USS file or path, the ``trace_destination`` must be an absolute path name. + + Support MVS data set type SEQ, PDS, PDS/E(MEMBER) + + If the destination is an MVS data set name, the ``trace_destination`` provided must meet data set naming conventions of one or more qualifiers, each from one to eight characters long, that are delimited by periods. + + | **required**: False + | **type**: str + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + - name: Resize an aggregate data set to 2500 kilobytes. + zos_zfs_resize: + target: TEST.ZFS.DATA + size: 2500 + + - name: Resize an aggregate data set to 20 tracks. + zos_zfs_resize: + target: TEST.ZFS.DATA + space_type: trk + size: 20 + + - name: Resize an aggregate data set to 4 megabytes. + zos_zfs_resize: + target: TEST.ZFS.DATA + space_type: m + size: 4 + + - name: Resize an aggregate data set to 1000 kilobytes and set no auto increase if it's shrinking. + zos_zfs_resize: + target: TEST.ZFS.DATA + size: 1000 + no_auto_increase: true + + - name: Resize an aggregate data set and get verbose output. + zos_zfs_resize: + target: TEST.ZFS.DATA + size: 2500 + verbose: true + + - name: Resize an aggregate data set and get the full trace on a file. + zos_zfs_resize: + target: TEST.ZFS.DATA + size: 2500 + trace_destination: /tmp/trace.txt + + - name: Resize an aggregate data set and capture the trace into a PDS member. + zos_zfs_resize: + target: TEST.ZFS.DATA + size: 2500 + trace_destination: "TEMP.HELPER.STORAGE(RESIZE)" + + - name: Resize an aggregate data set and capture the trace into a file with verbose output. + zos_zfs_resize: + target: TEST.ZFS.DATA + size: 2500 + verbose: true + trace_destination: /tmp/trace.txt + + + + +Notes +----- + +.. note:: + If needed, allocate the zFS trace output data set as a PDSE with RECFM=VB, LRECL=133 with a primary allocation of at least 50 cylinders and a secondary allocation of 30 cylinders. + + `zfsadm documentation `_. + + + + + + + +Return Values +------------- + + +cmd + The zfsadm command executed on the remote node. + + | **returned**: always + | **type**: str + | **sample**: zfsadm grow -aggregate SOMEUSER.VVV.ZFS -size 4096 + +target + The Fully Qualified Name of the resized zFS data set. + + | **returned**: always + | **type**: str + | **sample**: SOMEUSER.VVV.ZFS + +mount_target + The original share/mount of the data set. + + | **returned**: always + | **type**: str + | **sample**: /tmp/zfs_agg + +size + The desired size from option ``size`` according to ``space_type``. The resulting size can vary slightly, the actual space utilization is returned in ``new_size``. + + | **returned**: always + | **type**: int + | **sample**: 4024 + +rc + The return code of the zfsadm command. + + | **returned**: always + | **type**: int + +old_size + The original data set size according to ``space_type`` before resizing was performed. + + | **returned**: always + | **type**: float + | **sample**: + + .. code-block:: json + + 3096 + +old_free_space + The original data sets free space according to ``space_type`` before resizing was performed. + + | **returned**: always + | **type**: float + | **sample**: + + .. code-block:: json + + 2.1 + +new_size + The data set size according to ``space_type`` after resizing was performed. + + | **returned**: success + | **type**: float + | **sample**: + + .. code-block:: json + + 4032 + +new_free_space + The data sets free space according to ``space_type`` after resizing was performed. + + | **returned**: success + | **type**: float + | **sample**: + + .. code-block:: json + + 1.5 + +space_type + The measurement unit of space used to report all size values. + + | **returned**: always + | **type**: str + | **sample**: k + +stdout + The modules standard out (stdout) that is returned. + + | **returned**: always + | **type**: str + | **sample**: IOEZ00173I Aggregate TEST.ZFS.DATA.USER successfully grown. + +stderr + The modules standard error (stderr) that is returned. it may have no return value. + + | **returned**: always + | **type**: str + | **sample**: IOEZ00181E Could not open trace output dataset. + +stdout_lines + List of strings containing individual lines from standard out (stdout). + + | **returned**: always + | **type**: list + | **sample**: + + .. code-block:: json + + [ + "IOEZ00173I Aggregate TEST.ZFS.DATA.USER successfully grown." + ] + +stderr_lines + List of strings containing individual lines from standard error (stderr). + + | **returned**: always + | **type**: list + | **sample**: + + .. code-block:: json + + [ + "IOEZ00181E Could not open trace output dataset." + ] + +verbose_output + If ``verbose=true``, the operation's full traceback will show for this property. + + | **returned**: always + | **type**: str + | **sample**: 6FB2F8 print_trace_table printing contents of table Main Trace Table... + diff --git a/_sources/ibm_zos_core/docs/source/plugins.rst.txt b/_sources/ibm_zos_core/docs/source/plugins.rst.txt index b2634ab5..3c8858f4 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 9c09aeea..41bdbe9b 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 2020, 2021 . +.. © Copyright IBM Corporation 2024 . .. ........................................................................... ============ 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 82539a0d..d63e7815 100644 --- a/_sources/ibm_zos_core/docs/source/release_notes.rst.txt +++ b/_sources/ibm_zos_core/docs/source/release_notes.rst.txt @@ -1,11 +1,309 @@ .. ........................................................................... -.. © Copyright IBM Corporation 2020, 2024 . +.. © Copyright IBM Corporation 2020, 2025 . .. ........................................................................... ======== Releases ======== +Version 1.13.0-beta.1 +===================== + +Minor Changes +------------- + +- ``import_handler`` - When importing a non supported ZOAU version like 1.2.x the module would throw a non user friendly error message. Error message is now explicit about ZOAU not being properly configured for Ansible. +- ``zos_copy`` + + - Added new option ``autoescape`` to ``template_parameters``, allowing users to disable autoescaping of common XML/HTML characters when working with Jinja templates. + - Adds error message when a PDS/E source member does not exist or is not cataloged. + +- ``zos_job_submit`` + + - Add deploy and forget capability. Now when wait_time_s is 0, the module will submit the job and will not wait to get the job details or content, returning only the job id. + - Added new option ``autoescape`` to ``template_parameters``, allowing users to disable autoescaping of common XML/HTML characters when working with Jinja templates. + - Added support to run zos_job_submit tasks in async mode inside playbooks. + +- ``zos_mvs_raw`` - Added ``max_rc`` option. Now when the user sets ``max_rc``, the module tolerates the failure if the return code is smaller than the ``max_rc`` specified, however, return value ``changed`` will be False if the program return code is not 0. +- ``zos_script`` - Added new option ``autoescape`` to ``template_parameters``, allowing users to disable autoescaping of common XML/HTML characters when working with Jinja templates. + +Bugfixes +-------- + +- ``zos_copy`` - Improve module zos_copy error handling when the user does not have universal access authority set to UACC(READ) for SAF Profile 'MVS.MCSOPER.ZOAU' and SAF Class OPERCMDS. The module now handles the exception and returns an informative message. +- ``zos_fetch`` - Some relative paths were not accepted as a parameter e.g. C(files/fetched_file). Change now allows the user to use different types of relative paths as a parameter. +- ``zos_find`` + + - Module would not find VSAM data and index resource types. Fix now finds the data and index resource types. + - Module would not find a VSAM cluster resource type if it was in use with DISP=OLD. Fix now finds the VSAM cluster. + +- ``zos_job_query`` - Module was not returning values for system and subsystem. Fix now returns these values. +- ``zos_mvs_raw`` + + - If a program failed with a non-zero return code and verbose was false, the module would succeed. Whereas, if the program failed and verbose was true the module would fail. Fix now has a consistent behavior and fails in both cases. + - Module would not populate stderr return value. Fix now populates stderr in return values. + - Module would obfuscate the return code from the program when failing returning 8 instead. Fix now returns the proper return code from the program. + - Module would return the stderr content in stdout when verbose was true and return code was 0. Fix now does not replace stdout content with stderr. + - Option ``tmp_hlq`` was not being used as HLQ when creating backup data sets. Fix now uses ``tmp_hlq`` as HLQ for backup data sets. + +- ``zos_script`` - When the user trying to run a remote script had execute permissions but wasn't owner of the file, the module would fail while trying to change permissions on it. Fix now ensures the module first checks if the user can execute the script and only try to change permissions when necessary. + +New Modules +----------- + +- ibm.ibm_zos_core.zos_zfs_resize - Resize a zfs data set. + +Availability +------------ + +* `Galaxy`_ +* `GitHub`_ + +Requirements +------------ + +The IBM z/OS core collection has several dependencies, please review the `z/OS core support matrix`_ to understand both the +control node and z/OS managed node dependencies. + +Known Issues +------------ +- ``zos_job_submit`` - when setting 'location' to 'local' and not specifying the from and to encoding, the modules defaults are not read leaving the file in its original encoding; explicitly set the encodings instead of relying on the default. +- ``zos_job_submit`` - when submitting JCL, the response value returned for **byte_count** is incorrect. +- ``zos_apf`` - When trying to remove a library that contains the '$' character in the name for an APF(authorized program facility), the operation will fail. + +Version 1.12.0 +============== + +Minor Changes +------------- + +- ``zos_backup_restore`` - default behavior for module option **hlq** changed. When option **operation** is set to **restore** and the **hlq** is not provided, the original high level qualifiers in a backup will be used for a restore. + +- ``zos_job_output`` - has added the address space type for a job returned as **content_type** in the module response. + +- ``zos_job_query`` - has added the address space type for a job returned as **content_type** in the module response. + +- ``zos_job_submit`` - has added the address space type for a job returned as **content_type** in the module response. + +- ``zos_mvs_raw`` - updates the stdout and stderr when an unknown, unrecognized, or unrepresentable characters with the 'replacement character' (�), found in the Unicode standard at code point U+FFFD. + +- ``zos_operator`` - has added the option **case_sensitive**, allowing the module to control the commands case. + +- ``zos_script`` - updates the stdout and stderr when an unknown, unrecognized, or unrepresentable characters with the 'replacement character' (�), found in the Unicode standard at code point U+FFFD. + +- ``zos_tso_command`` - updates the stdout and stderr when an unknown, unrecognized, or unrepresentable characters with the 'replacement character' (�), found in the Unicode standard at code point U+FFFD. + +Bugfixes +-------- + +- ``zos_apf`` - module option **tmp_hlq** was previously ignored and default values were used. Now the module uses the value set in the option. + +- ``zos_archive`` - module option **tmp_hlq** was previously ignored and default values were used. Now the module uses the value set in the option. + +- ``zos_backup_restore`` - when a recoverable error was encountered and **recover = True**, the module would fail. The change now allows the module to recover. + +- ``zos_blockinfile`` + + - when the modules **marker_begin** and **marker_end** were set to the same value, the module would not delete the block. Now the module requires the **marker_begin** and **marker_end** to have different values. + - module option **tmp_hlq** was previously ignored and default values were used. Now the module uses the value set in the option.. + +- ``zos_copy`` + + - module option **tmp_hlq** was previously ignored and default values were used. Now the module uses the value set in the option. + - module would fail if the user did not have Universal Access Authority for SAF Profile **MVS.MCSOPER.ZOAU** and SAF Class **OPERCMDS**. Now the module handles the exception and returns an informative message. + - module would ignore the value set for **remote_tmp** in the Ansible configuration file. Now the module uses the value of **remote_tmp** or the default value **~/.ansible/tmp** if none is given. + +- ``zos_data_set`` - module option **tmp_hlq** was previously ignored and default values were used. Now the module uses the value set in the option. + +- ``zos_encode`` - module option **tmp_hlq** was previously ignored and default values were used. Now the module uses the value set in the option. + +- ``zos_fetch`` - module option **tmp_hlq** was previously ignored and default values were used. Now the module uses the value set in the option. + +- ``zos_find`` + + - Module would not find VSAM data and index resource types. Fix now finds the data and index resource types. + - Module would not find a VSAM cluster resource type if it was in use with DISP=OLD. Fix now finds the VSAM cluster. + +- ``zos_job_output`` - module would raise an invalid argument error for a user ID that contained **@**, **$**, or **#**. Now the module supports RACF user naming conventions. + +- ``zos_job_query`` + + - module did not return values for properties **system** and **subsystem**. Now the module returns these values. + - module would raise an invalid argument error for a user ID that contained **@**, **$**, or **#**. Now the module supports RACF user naming conventions. + +- ``zos_lineinfile`` - module option **tmp_hlq** was previously ignored and default values were used. Now the module uses the value set in the option. + +- ``zos_mount`` - module option **tmp_hlq** was previously ignored and default values were used. Now the module uses the value set in the option. + +- ``zos_mvs_raw`` + + - Module sub-option **base64** for **return_content** did not retrieve DD output as Base64. Now the module returns Base64 encoded contents for the DD. + - Module would return the stderr content in stdout when verbose was true and return code was 0. Fix now does not replace stdout content with stderr. + - Module would obfuscate the return code from the program when failing returning 8 instead. Fix now returns the proper return code from the program. + - If a program failed with a non-zero return code and verbose was false, the module would succeed (false positive). Fix now fails the module for all instances where a program has a non-zero return code. + +- ``zos_script`` - module would only read the first command line argument if more than one was used. Now the module passes all arguments to the remote command. + +- ``zos_unarchive`` - module option **tmp_hlq** was previously ignored and default values were used. Now the module uses the value set in the option. + +Availability +------------ + +* `Ansible Automation Platform`_ +* `Galaxy`_ +* `GitHub`_ + +Requirements +------------ + +The IBM z/OS core collection has several dependencies, please review the `z/OS core support matrix`_ to understand both the +control node and z/OS managed node dependencies. + +Known Issues +------------ +- ``zos_job_submit`` - when setting 'location' to 'local' and not specifying the from and to encoding, the modules defaults are not read leaving the file in its original encoding; explicitly set the encodings instead of relying on the default. +- ``zos_job_submit`` - when submitting JCL, the response value returned for **byte_count** is incorrect. +- ``zos_apf`` - When trying to remove a library that contains the '$' character in the name for an APF(authorized program facility), the operation will fail. +- ``zos_find`` - When trying to find a VSAM data set that is allocated with DISP=OLD using age filter the module will not find it. + +Version 1.11.1 +============== + +Bugfixes +-------- + +- ``zos_mvs_raw`` + + - If a program failed with a non-zero return code and verbose was false, the module would succeed. Whereas, if the program failed and verbose was true the module would fail(false positive). Fix now has a consistent behavior and fails in both cases. + - Module would obfuscate the return code from the program when failing returning 8 instead. Fix now returns the proper return code from the program. + - Module would return the stderr content in stdout when verbose was true and return code was 0. Fix now does not replace stdout content with stderr. + + +Availability +------------ + +* `Ansible Automation Platform`_ +* `Galaxy`_ +* `GitHub`_ + +Requirements +------------ + +The IBM z/OS core collection has several dependencies, please review the `z/OS core support matrix`_ to understand both the +control node and z/OS managed node dependencies. + +Known Issues +------------ +- ``zos_job_submit`` - when setting 'location' to 'local' and not specifying the from and to encoding, the modules defaults are not read leaving the file in its original encoding; explicitly set the encodings instead of relying on the default. +- ``zos_job_submit`` - when submitting JCL, the response value returned for **byte_count** is incorrect. +- ``zos_apf`` - When trying to remove a library that contains the '$' character in the name from APF(authorized program facility), operation will fail. + +Version 1.11.0 +============== + +Minor Changes +------------- + +- ``zos_apf`` - Added support for data set names (libraries) with special characters ($, /#, /- and @). +- ``zos_archive`` + + - Added support for GDG and GDS relative name notation to archive data sets. + - Added support for data set names with special characters ($, /#, /- and @). + +- ``zos_backup_restore`` + + - Added support for GDS relative name notation to include or exclude data sets when operation is backup. + - Added support for data set names with special characters ($, /#, /- and @). + +- ``zos_blockinfile`` + + - Added support for GDG and GDS relative name notation to specify a data set. And backup in new generations. + - Added support for data set names with special characters ($, /#, /- and @). + +- ``zos_copy`` + + - Added support for copying from and to generation data sets (GDS) and generation data groups (GDG) including using a GDS for backup. + - Added support for data set names with special characters ($, /#, /- and @). + +- ``zos_data_set`` + + - Added support for GDG and GDS relative name notation to create, delete, catalog and uncatalog a data set. + - Added support for data set names with special characters ($, /#, /- and @). + +- ``zos_encode`` + + - Added support for converting the encodings of generation data sets (GDS). + - Added support for data set names with special characters ($, /#, /- and @). + +- ``zos_fetch`` + + - Added support for fetching generation data groups (GDG) and generation data sets (GDS). + - Added support for data set names with special characters ($, /#, /- and @). + +- ``zos_find`` + + - Added support for finding generation data groups (GDG) and generation data sets (GDS). + - Added support for data set names with special characters ($, /#, /- and @). + +- ``zos_job_submit`` + + - Improved the mechanism for copying to remote systems by removing the use of deepcopy, which had previously resulted in the module failing on some systems. + - Added support for running JCL stored in generation data groups (GDG) and generation data sets (GDS). + - Added support for data set names with special characters ($, /#, /- and @). + +- ``zos_lineinfile`` + + - Added support for GDG and GDS relative name notation to specify the target data set and to backup into new generations. + - Added support for data set names with special characters ($, /#, /- and @). + +- ``zos_mount`` - Added support for data set names with special characters ($, /#, /- and @). +- ``zos_mvs_raw`` + + - Added support for GDG and GDS relative name notation to specify data set names. + - Added support for data set names with special characters ($, /#, /- and @). + +- ``zos_script`` - Improved the mechanism for copying to remote systems by removing the use of deepcopy, which had previously resulted in the module failing on some systems. +- ``zos_tso_command`` + + - Added support for using GDG and GDS relative name notation in running TSO commands. + - Added support for data set names with special characters ($, /#, /- and @). + +- ``zos_unarchive`` + + - Improved the mechanism for copying to remote systems by removing the use of deepcopy, which had previously resulted in the module failing on some systems. + - Added support for data set names with special characters ($, /#, /- and @). + +Bugfixes +-------- + +- ``zos_copy`` + + - Fixes the issue that prevents the module from automatically computing member names when copying a file into a PDS/E. The module now computes the member name when copying into a PDS/E. + - Fixes an issue that would perform an unnecessary check if a destination data set is locked for data sets the module created. The module only performs this check for destinations that are present. + +- ``zos_data_set`` - When checking if a data set is cataloged, module failed to account for exceptions which occurred during the LISTCAT. The module now raises an MVSCmdExecError if the return code from LISTCAT exceeds the determined threshold. +- ``zos_job_submit`` - Was not propagating any error types including UnicodeDecodeError, JSONDecodeError, TypeError, KeyError when encountered. The module now shares the error type (UnicodeDecodeError, JSONDecodeError, TypeError, KeyError) in the error message. +- ``zos_mvs_raw`` - The first character of each line in dd_output was missing. The module now includes the first character of each line. + +Availability +------------ + +* `Ansible Automation Platform`_ +* `Galaxy`_ +* `GitHub`_ + +Requirements +------------ + +The IBM z/OS core collection has several dependencies, please review the `z/OS core support matrix`_ to understand both the +control node and z/OS managed node dependencies. + +Known Issues +------------ +- ``zos_job_submit`` - when setting 'location' to 'local' and not specifying the from and to encoding, the modules defaults are not read leaving the file in its original encoding; explicitly set the encodings instead of relying on the default. +- ``zos_job_submit`` - when submitting JCL, the response value returned for **byte_count** is incorrect. +- ``zos_apf`` - When trying to remove a library that contains the '$' character in the name for an APF(authorized program facility), the operation will fail. + Version 1.10.0 ============== @@ -95,7 +393,7 @@ It is intended to assist in updating your playbooks so this collection will cont Availability ------------ -* `Automation Hub`_ +* `Ansible Automation Platform`_ * `Galaxy`_ * `GitHub`_ @@ -124,20 +422,63 @@ Known Issues - In the past, choices could be defined in either lower or upper case. Now, only the case that is identified in the docs can be set, this is so that the collection can continue to maintain certified status. - Use of special characters (#, @, $, \- ) in different options like data set names and commands is not fully supported, some modules support them but is the user responsibility to escape them. Read each module documentation for further details. +Version 1.9.4 +============= -Version 1.9.1 +Bugfixes +-------- + +- ``zos_mvs_raw`` - If verbose was true, even if the program return code was 0, the module would fail. Fix now ensures the module fails on non-zero return code only. + +Availability +------------ + +* `Ansible Automation Platform`_ +* `Galaxy`_ +* `GitHub`_ + +Requirements +------------ + +The IBM z/OS core collection has several dependencies, please review the `z/OS core support matrix`_ to understand both the +controller and z/OS managed node dependencies. + +Known Issues +------------ + +- ``zos_job_submit`` - when setting 'location' to 'LOCAL' and not specifying the from and to encoding, the modules defaults are not read leaving the file in its original encoding; explicitly set the encodings instead of relying on the default. +- ``zos_job_submit`` - when submitting JCL, the response value returned for **byte_count** is incorrect. + +- ``zos_job_submit``, ``zos_job_output``, ``zos_operator_action_query`` - encounters UTF-8 decoding errors when interacting with results that contain non-printable UTF-8 characters in the response. This has been addressed in this release and corrected with **ZOAU version 1.2.5.6** or later. + + - If the appropriate level of ZOAU can not be installed, some options are to: + + - Specify that the ASA assembler option be enabled to instruct the assembler to use ANSI control characters instead of machine code control characters. + - Ignore module errors by using **ignore_errors:true** for a specific playbook task. + - If the error is resulting from a batch job, add **ignore_errors:true** to the task and capture the output into a registered variable to extract the + job ID with a regular expression. Then use ``zos_job_output`` to display the DD without the non-printable character such as the DD **JESMSGLG**. + - If the error is the result of a batch job, set option **return_output** to false so that no DDs are read which could contain the non-printable UTF-8 characters. + +- ``zos_data_set`` - 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. + +Version 1.9.3 ============= Bugfixes -------- -- ``zos_find`` - Option size failed if a PDS/E matched the pattern, now filtering on utilized size for a PDS/E is supported. -- ``zos_mvs_raw`` - Option **tmp_hlq** when creating temporary data sets was previously ignored, now the option honors the High Level Qualifier for temporary data sets created during the module execution. +- ``zos_job_submit`` - module did not return values for properties **system** and **subsystem**. Now the module returns these values. +- ``zos_mvs_raw`` + + - If a program failed with a non-zero return code and verbose was false, the module would succeed. Whereas, if the program failed and verbose was true the module would fail. Fix now has a consistent behavior and fails in both cases. + - Module would obfuscate the return code from the program when failing returning 8 instead. Fix now returns the proper return code from the program. Availability ------------ -* `Automation Hub`_ +* `Ansible Automation Platform`_ * `Galaxy`_ * `GitHub`_ @@ -150,7 +491,49 @@ controller and z/OS managed node dependencies. Known Issues ------------ -- ``zos_job_submit`` - when setting 'location' to 'local' and not specifying the from and to encoding, the modules defaults are not read leaving the file in its original encoding; explicitly set the encodings instead of relying on the default. +- ``zos_job_submit`` - when setting 'location' to 'LOCAL' and not specifying the from and to encoding, the modules defaults are not read leaving the file in its original encoding; explicitly set the encodings instead of relying on the default. +- ``zos_job_submit`` - when submitting JCL, the response value returned for **byte_count** is incorrect. + +- ``zos_job_submit``, ``zos_job_output``, ``zos_operator_action_query`` - encounters UTF-8 decoding errors when interacting with results that contain non-printable UTF-8 characters in the response. This has been addressed in this release and corrected with **ZOAU version 1.2.5.6** or later. + + - If the appropriate level of ZOAU can not be installed, some options are to: + + - Specify that the ASA assembler option be enabled to instruct the assembler to use ANSI control characters instead of machine code control characters. + - Ignore module errors by using **ignore_errors:true** for a specific playbook task. + - If the error is resulting from a batch job, add **ignore_errors:true** to the task and capture the output into a registered variable to extract the + job ID with a regular expression. Then use ``zos_job_output`` to display the DD without the non-printable character such as the DD **JESMSGLG**. + - If the error is the result of a batch job, set option **return_output** to false so that no DDs are read which could contain the non-printable UTF-8 characters. + +- ``zos_data_set`` - 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. + + +Version 1.9.2 +============= + +Bugfixes +-------- + +- ``zos_copy`` - when creating the destination data set, the module would unnecessarily check if a data set is locked by another process. The module no longer performs this check when it creates the data set. + +Availability +------------ + +* `Ansible Automation Platform`_ +* `Galaxy`_ +* `GitHub`_ + +Requirements +------------ + +The IBM z/OS core collection has several dependencies, please review the `z/OS core support matrix`_ to understand both the +controller and z/OS managed node dependencies. + +Known Issues +------------ + +- ``zos_job_submit`` - when setting 'location' to 'LOCAL' and not specifying the from and to encoding, the modules defaults are not read leaving the file in its original encoding; explicitly set the encodings instead of relying on the default. - ``zos_job_submit`` - when submitting JCL, the response value returned for **byte_count** is incorrect. - ``zos_job_submit``, ``zos_job_output``, ``zos_operator_action_query`` - encounters UTF-8 decoding errors when interacting with results that contain non-printable UTF-8 characters in the response. This has been addressed in this release and corrected with **ZOAU version 1.2.5.6** or later. @@ -167,6 +550,46 @@ Known Issues - 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. +Version 1.9.1 +============= + +Bugfixes +-------- + +- ``zos_find`` - Option size failed if a PDS/E matched the pattern, now filtering on utilized size for a PDS/E is supported. +- ``zos_mvs_raw`` - Option **tmp_hlq** when creating temporary data sets was previously ignored, now the option honors the High Level Qualifier for temporary data sets created during the module execution. + +Known Issues +------------ + +- ``zos_job_submit`` - when setting 'location' to 'local' and not specifying the from and to encoding, the modules defaults are not read leaving the file in its original encoding; explicitly set the encodings instead of relying on the default. +- ``zos_job_submit`` - when submitting JCL, the response value returned for **byte_count** is incorrect. + +- ``zos_job_submit``, ``zos_job_output``, ``zos_operator_action_query`` - encounters UTF-8 decoding errors when interacting with results that contain non-printable UTF-8 characters in the response. This has been addressed in this release and corrected with **ZOAU version 1.2.5.6** or later. + + - If the appropriate level of ZOAU can not be installed, some options are to: + + - Specify that the ASA assembler option be enabled to instruct the assembler to use ANSI control characters instead of machine code control characters. + - Ignore module errors by using **ignore_errors:true** for a specific playbook task. + - If the error is resulting from a batch job, add **ignore_errors:true** to the task and capture the output into a registered variable to extract the + job ID with a regular expression. Then use ``zos_job_output`` to display the DD without the non-printable character such as the DD **JESMSGLG**. + - If the error is the result of a batch job, set option **return_output** to false so that no DDs are read which could contain the non-printable UTF-8 characters. + +- ``zos_data_set`` - 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. + +Availability +------------ + +* `Ansible Automation Platform`_ +* `Galaxy`_ +* `GitHub`_ + +Requirements +------------ + +The IBM z/OS core collection has several dependencies, please review the `z/OS core support matrix`_ to understand both the +controller and z/OS managed node dependencies. + Version 1.9.0 ============= @@ -276,13 +699,10 @@ 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 ------------ -* `Automation Hub`_ +* `Ansible Automation Platform`_ * `Galaxy`_ * `GitHub`_ @@ -366,7 +786,7 @@ unique, some options to work around the error are below. Availability ------------ -* `Automation Hub`_ +* `Ansible Automation Platform`_ * `Galaxy`_ * `GitHub`_ @@ -431,7 +851,7 @@ Bugfixes Availability ------------ -* `Automation Hub`_ +* `Ansible Automation Platform`_ * `Galaxy`_ * `GitHub`_ @@ -492,7 +912,7 @@ Bugfixes Availability ------------ -* `Automation Hub`_ +* `Ansible Automation Platform`_ * `Galaxy`_ * `GitHub`_ @@ -606,7 +1026,7 @@ Deprecated Features Availability ------------ -* `Automation Hub`_ +* `Ansible Automation Platform`_ * `Galaxy`_ * `GitHub`_ @@ -623,7 +1043,7 @@ controller and z/OS managed node dependencies. https://github.com/ansible-collections/ibm_zos_core .. _Galaxy: https://galaxy.ansible.com/ibm/ibm_zos_core -.. _Automation Hub: +.. _Ansible Automation Platform: https://www.ansible.com/products/automation-hub .. _IBM Open Enterprise SDK for Python: https://www.ibm.com/products/open-enterprise-python-zos @@ -666,7 +1086,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/build/html/resources/releases_maintenance.html + https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/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 70fa46e0..45f761fb 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,16 +6,60 @@ Releases and maintenance ======================== -This table describes the collections release dates, dependency versions and End of Life dates (EOL). +This section describes the collections release dates, dependency versions and End of Life dates (EOL) +and support coverage. The ``ibm_zos_core`` collection is developed and released on a flexible release cycle; generally, each quarter a beta is released followed by a GA version. Occasionally, the cycle may be extended to properly implement and test larger changes before a new release is made available. End of Life for this collection is generally a 2-year cycle unless a dependency reaches EOL prior to the 2 years. -For example, if a collection has released and its dependency reaches EOL 1 year later, then the collection will EOL +For example, if a collection has released and a dependency reaches EOL 1 year later, then the collection will EOL at the same time as the dependency, 1 year later. +Life Cycle Phase +================ + +To encourage the adoption of new features while keeping the high standard of stability inherent, +support is divided into life cycle phases; **full support** which covers the first year +and **maintenance support** which covers the second year. + ++--------------------------+------------------------------------+---------------------------+ +| Life Cycle Phase | Full Support | Maintenance Support | ++==========================+====================================+===========================+ +| Critical security fixes | Yes | Yes | ++--------------------------+------------------------------------+---------------------------+ +| Bug fixes by severity | Critical and high severity issues | Critical severity issues | ++--------------------------+------------------------------------+---------------------------+ + +Severities +========== + +Severity 1 (Critical): +A problem that severely impacts your use of the software in a production environment (such as loss +of production data or in which your production systems are not functioning). The situation halts +your business operations and no procedural workaround exists. + +Severity 2 (high): +A problem where the software is functioning but your use in a production environment is severely +reduced. The situation is causing a high impact to portions of your business operations and no +procedural workaround exists. + +Severity 3 (medium): +A problem that involves partial, non-critical loss of use of the software in a production environment +or development environment and your business continues to function, including by using a procedural +workaround. + +Severity 4 (low): +A general usage question, reporting of a documentation error, or recommendation for a future product +enhancement or modification. + +Severities 3 and 4 are generally addressed in subsequent releases to ensure a high standard of stability +remains available for production environments. + +Support Matrix +============== + These are the component versions available when the collection was made generally available (GA). The underlying component version is likely to change as it reaches EOL, thus components must be a version that is currently supported. @@ -33,11 +77,33 @@ 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`_. -Support Matrix -============== +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 + + +---------+----------------------------+---------------------------------------------------+---------------+---------------+ | Version | Controller | Managed Node | GA | End of Life | +=========+============================+===================================================+===============+===============+ +| 1.13.x |- `ansible-core`_ >=2.15.x |- `z/OS`_ V2R4 - V3Rx | TBD | TBD | +| |- `Ansible`_ >=8.0.x |- `z/OS shell`_ | | | +| |- `AAP`_ >=2.4 |- IBM `Open Enterprise SDK for Python`_ | | | +| | |- IBM `Z Open Automation Utilities`_ >=1.3.3 | | | ++---------+----------------------------+---------------------------------------------------+---------------+---------------+ +| 1.12.x |- `ansible-core`_ >=2.15.x |- `z/OS`_ V2R5 - V3Rx | 6 Dec 2024 | 6 Dec 2026 | +| |- `Ansible`_ >=8.0.x |- `z/OS shell`_ | | | +| |- `AAP`_ >=2.4 |- IBM `Open Enterprise SDK for Python`_ | | | +| | |- IBM `Z Open Automation Utilities`_ >=1.3.2 | | | ++---------+----------------------------+---------------------------------------------------+---------------+---------------+ +| 1.11.x |- `ansible-core`_ >=2.15.x |- `z/OS`_ V2R4 - V2Rx | 1 Oct 2024 | 1 Oct 2026 | +| |- `Ansible`_ >=8.0.x |- `z/OS shell`_ | | | +| |- `AAP`_ >=2.4 |- IBM `Open Enterprise SDK for Python`_ | | | +| | |- IBM `Z Open Automation Utilities`_ >=1.3.1 | | | ++---------+----------------------------+---------------------------------------------------+---------------+---------------+ | 1.10.x |- `ansible-core`_ >=2.15.x |- `z/OS`_ V2R4 - V2Rx | 21 June 2024 | 21 June 2026 | | |- `Ansible`_ >=8.0.x |- `z/OS shell`_ | | | | |- `AAP`_ >=2.4 |- IBM `Open Enterprise SDK for Python`_ | | | @@ -99,4 +165,6 @@ Support Matrix .. _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 \ No newline at end of file + 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 diff --git a/_sources/ibm_zos_ims/docs/source/modules/ims_acb_gen.rst.txt b/_sources/ibm_zos_ims/docs/source/modules/ims_acb_gen.rst.txt index 2827b3c1..fdc5bf3f 100644 --- a/_sources/ibm_zos_ims/docs/source/modules/ims_acb_gen.rst.txt +++ b/_sources/ibm_zos_ims/docs/source/modules/ims_acb_gen.rst.txt @@ -16,8 +16,8 @@ ims_acb_gen -- Generate IMS ACB Synopsis -------- -- The ims_acb_gen module generates an IMS application control block (ACB) necessary for an IMS application program to be scheduled and run. -- The ims_dbd_gen and ims_psb_gen modules can be used to generate the associated IMS database descriptors (DBDs) and program specification block (PSBs) to be used with the ims_acb_gen module. +- The ims\_acb\_gen module generates an IMS application control block (ACB) necessary for an IMS application program to be scheduled and run. +- The ims\_dbd\_gen and ims\_psb\_gen modules can be used to generate the associated IMS database descriptors (DBDs) and program specification block (PSBs) to be used with the ims\_acb\_gen module. - The DBD and PSB control blocks will be merged and expanded into an IMS internal format called application control blocks (ACBs). @@ -43,17 +43,15 @@ command_input compression PRECOMP,POSTCOMP, in any combination, cause the required in-place compression. - The choices are not mutually exclusive -- PRECOMP or POSTCOMP or PRECOMP,POSTCOMP can be used - The default is none. | **required**: False | **type**: str - | **choices**: PRECOMP, POSTCOMP + | **choices**: precomp, postcomp, precomp,postcomp, PRECOMP, POSTCOMP, PRECOMP,POSTCOMP psb_name - The name of the PS**s**. Specifies that blocks are built or deleted for all PSBs that are named on this control statement. + The name of the PSB(s). Specifies that blocks are built or deleted for all PSBs that are named on this control statement. This field requires "ALL" or a list of psb names to be specified. @@ -73,7 +71,7 @@ dbd_name acb_lib The ACB Maintenance utility maintains the prebuilt blocks (ACB) library (IMS.ACBLIB). The ACB library is a consolidated library of program (PSB) and database (DBD) descriptions. - The IMS acb_lib must be used exclusively. The module can only be executed using an ACB library which is not concurrently allocated to an active IMS system. + The IMS acb\_lib must be used exclusively. The module can only be executed using an ACB library which is not concurrently allocated to an active IMS system. | **required**: True | **type**: str @@ -82,7 +80,7 @@ acb_lib psb_lib The ACB Maintenance utility receives input from the IMS PSBLIB data set. - The ACB Maintenance utility does not change the PS**s** in PSBLIB. If changes are made in PSBs or DBDs that require changes in the associated PSB, make these changes before running the module. + The ACB Maintenance utility does not change the PSB(s) in PSBLIB. If changes are made in PSBs or DBDs that require changes in the associated PSB, make these changes before running the module. Changes in PSBs might also require modifications to the affected application programs. For example, if a DBD has a segment name changed, all PSBs which are sensitive to that segment must have their SENSEG statements changed. @@ -102,11 +100,11 @@ dbd_lib steplib - Points to the IMS SDFSRESL data set, which contains the IMS nucleus and required IMS modules. If STEPLIB is unauthorized by having unauthorized libraries that are concatenated to SDFSRESL, you must specify the *reslib* parameter. + Points to the IMS SDFSRESL data set, which contains the IMS nucleus and required IMS modules. If STEPLIB is unauthorized by having unauthorized libraries that are concatenated to SDFSRESL, you must specify the \ :emphasis:`reslib`\ parameter. - The steplib parameter can also be specified in the target inventory's environment_vars. + The steplib parameter can also be specified in the target inventory's environment\_vars. - The steplib input parameter to the module will take precedence over the value specified in the environment_vars. + The steplib input parameter to the module will take precedence over the value specified in the environment\_vars. | **required**: False | **type**: list @@ -122,11 +120,11 @@ reslib build_psb - Specifies whether ims_acb_gen rebuilds all PSBs that reference a changed DBD in the *dbdname* parameter. + Specifies whether ims\_acb\_gen rebuilds all PSBs that reference a changed DBD in the \ :emphasis:`dbdname`\ parameter. - TRUE indicates that ims_acb_gen rebuilds all PSBs that reference the changed DBD on the *dbdname* parameter. + TRUE indicates that ims\_acb\_gen rebuilds all PSBs that reference the changed DBD on the \ :emphasis:`dbdname`\ parameter. - FALSE indicates that ims_acb_gen does not rebuild PSBs that reference the changed DBD if the changed DBD does not change the physical structure of the database. + FALSE indicates that ims\_acb\_gen does not rebuild PSBs that reference the changed DBD if the changed DBD does not change the physical structure of the database. | **required**: False | **type**: bool @@ -201,15 +199,15 @@ Notes ----- .. note:: - The *steplib* parameter can also be specified in the target inventory's environment_vars. + The \ :emphasis:`steplib`\ parameter can also be specified in the target inventory's environment\_vars. - The *steplib* input parameter to the module will take precedence over the value specified in the environment_vars. + The \ :emphasis:`steplib`\ input parameter to the module will take precedence over the value specified in the environment\_vars. - If only the *steplib* parameter is specified, then only the *steplib* concatenation will be used to resolve the IMS RESLIB dataset. + If only the \ :emphasis:`steplib`\ parameter is specified, then only the \ :emphasis:`steplib`\ concatenation will be used to resolve the IMS RESLIB dataset. - If both *steplib* and *reslib* are specified, then both parameters will be used by the ACB Maintenenace Utility and *reslib* will be used to resolve the IMS RESLIB dataset. + If both \ :emphasis:`steplib`\ and \ :emphasis:`reslib`\ are specified, then both parameters will be used by the ACB Maintenenace Utility and \ :emphasis:`reslib`\ will be used to resolve the IMS RESLIB dataset. - Specifying only *reslib* without *steplib* is not supported. + Specifying only \ :emphasis:`reslib`\ without \ :emphasis:`steplib`\ is not supported. The ACB Maintenenace utility SYSUT3/SYSUT4 DD options are not supported by this module. @@ -224,7 +222,7 @@ Return Values msg - Execution result message from the ims_acb_gen module. + Execution result message from the ims\_acb\_gen module. | **returned**: always | **type**: str @@ -254,7 +252,7 @@ changed debug additional messages returned from ZOAU. - For more information, refer to the `ZOAU messages documentation `_ + For more information, refer to the \ `ZOAU messages documentation `__\ | **returned**: always | **type**: str diff --git a/_sources/ibm_zos_ims/docs/source/modules/ims_ddl.rst.txt b/_sources/ibm_zos_ims/docs/source/modules/ims_ddl.rst.txt index a3b7e9b6..b7fde045 100644 --- a/_sources/ibm_zos_ims/docs/source/modules/ims_ddl.rst.txt +++ b/_sources/ibm_zos_ims/docs/source/modules/ims_ddl.rst.txt @@ -66,9 +66,9 @@ proclib steplib Points to IMS.SDFSRESL, which contains the IMS nucleus and required IMS modules. - The steplib parameter can also be specified in the target inventory's environment_vars. + The steplib parameter can also be specified in the target inventory's environment\_vars. - The steplib input parameter to the module will take precedence over the value specified in the environment_vars. + The steplib input parameter to the module will take precedence over the value specified in the environment\_vars. | **required**: False | **type**: list @@ -133,7 +133,7 @@ Examples - name: Example of DDL statements are in a dataset - ims_data_definition: + ims_ddl: online: True ims_id: IMS1 reslib: @@ -144,7 +144,7 @@ Examples - SOME.IMS.PROCLIB sql_input: SOME.IMS.SQL - name: Example of DDL statements in which VERBOSE and AUTOCOMMIT control options are specified - ims_data_definition: + ims_ddl: online: True ims_id: IMS1 reslib: @@ -158,7 +158,7 @@ Examples auto_commit: true - name: Example of DDL statements in which SIMULATE control options is specified - ims_data_definition: + ims_ddl: online: True ims_id: IMS1 reslib: @@ -171,7 +171,7 @@ Examples simulate: true - name: Example of DDL statements in which DYNAMIC_PROGRAMVIEW control option is specified - ims_data_definition: + ims_ddl: online: True ims_id: IMS1 reslib: @@ -191,13 +191,13 @@ Notes ----- .. note:: - The *steplib* parameter can also be specified in the target inventory's environment_vars. + The \ :emphasis:`steplib`\ parameter can also be specified in the target inventory's environment\_vars. - The *steplib* input parameter to the module will take precedence over the value specified in the environment_vars. + The \ :emphasis:`steplib`\ input parameter to the module will take precedence over the value specified in the environment\_vars. - If only the *steplib* parameter is specified, then only the *steplib* concatenation will be used to resolve the IMS RESLIB data set. + If only the \ :emphasis:`steplib`\ parameter is specified, then only the \ :emphasis:`steplib`\ concatenation will be used to resolve the IMS RESLIB data set. - Specifying only *reslib* without *steplib* is not supported. + Specifying only \ :emphasis:`reslib`\ without \ :emphasis:`steplib`\ is not supported. Currently ddl error messages are returned within the content block of the module response. diff --git a/_sources/ibm_zos_ims/docs/source/release_notes.rst.txt b/_sources/ibm_zos_ims/docs/source/release_notes.rst.txt index f02bbee1..ec977b21 100644 --- a/_sources/ibm_zos_ims/docs/source/release_notes.rst.txt +++ b/_sources/ibm_zos_ims/docs/source/release_notes.rst.txt @@ -6,6 +6,56 @@ Releases ======== + +Version 1.3.0 +==================== + +Notes +----- + +* Update recommended + + * type() was replaced by isinstance() in the code for gen utilities since ansible-core 2.16 supports Python 3.12 and that version deprecated type() function. + * No other changes from version 1.3.0-beta.1 release. Collection promoted to certified content with version 1.3.0. + +Availability +------------ + +* `Automation Hub`_ +* `Galaxy`_ +* `GitHub`_ + + + +Known Issues +------------ + +- ``ims_command`` - STEPLIB is required and needs to be defined as an environment variable. +- ``ims_command`` - Currently, this module requires to have plex parameter defined. + + + +Reference +--------- + +* Supported by IBM z/OS core collection v1.5.0 or later +* Supported by IBM Z Open Enterprise Python for z/OS 3.9 - 3.12 +* Supported by IBM Z Open Automation Utilities 1.2.2 or later (but prior to 1.3) + + * ZOAU minimum supported version may vary depending on the z/OS core collection version that is chosen. For details on z/OS core collection requirements, see: https://github.com/ansible-collections/ibm_zos_core/releases +* Supported by z/OS V2R4 (or later) but prior to version V3R1 +* The z/OS® shell + +.. _centralized content: + https://ibm.github.io/z_ansible_collections_doc/index.html + +.. _GitHub: + https://github.com/ansible-collections/ibm_zos_ims + +.. _Galaxy: + https://galaxy.ansible.com/ibm/ibm_zos_ims + + Version 1.3.0-beta.1 ==================== @@ -43,7 +93,9 @@ Reference * Supported by IBM z/OS core collection v1.5.0 or later * Supported by IBM Z Open Enterprise Python for z/OS: 3.9 or later * Supported by IBM Z Open Automation Utilities 1.2.2 or later (but prior to 1.3) -* Supported by z/OS V2R4 + + * ZOAU minimum supported version may vary depending on the z/OS core collection version that is chosen. For details on z/OS core collection requirements, see: https://github.com/ansible-collections/ibm_zos_core/releases +* Supported by z/OS V2R4 (or later) but prior to version V3R1 * The z/OS® shell .. _centralized content: diff --git a/_sources/zhmc-ansible-modules/docs/source/bibliography.rst.txt b/_sources/zhmc-ansible-modules/docs/source/bibliography.rst.txt index 465b036c..a6e5baa0 100644 --- a/_sources/zhmc-ansible-modules/docs/source/bibliography.rst.txt +++ b/_sources/zhmc-ansible-modules/docs/source/bibliography.rst.txt @@ -21,30 +21,49 @@ Resources .. glossary:: +.. _`HMC API`: + HMC API The Web Services API of the z Systems Hardware Management Console, described in the following books: HMC API 2.11.1 - `IBM SC27-2616, System z Hardware Management Console Web Services API (Version 2.11.1) `_ + IBM SC27-2616, System z Hardware Management Console Web Services API (Version 2.11.1) (no longer available for download) HMC API 2.12.0 - `IBM SC27-2617, System z Hardware Management Console Web Services API (Version 2.12.0) `_ + IBM SC27-2617, System z Hardware Management Console Web Services API (Version 2.12.0) (no longer available for download) HMC API 2.12.1 - `IBM SC27-2626, System z Hardware Management Console Web Services API (Version 2.12.1) `_ + IBM SC27-2626, System z Hardware Management Console Web Services API (Version 2.12.1) (no longer available for download) HMC API 2.13.0 - `IBM SC27-2627, z Systems Hardware Management Console Web Services API (Version 2.13.0) `_ + `IBM SC27-2627-00a, z Systems Hardware Management Console Web Services API (Version 2.13.0) `_ HMC API 2.13.1 - `IBM SC27-2634, z Systems Hardware Management Console Web Services API (Version 2.13.1) `_ + `IBM SC27-2634-03a, z Systems Hardware Management Console Web Services API (Version 2.13.1) `_ HMC API 2.14.0 - `IBM SC27-2636, IBM Z Hardware Management Console Web Services API (Version 2.14.0) `_ + `IBM SC27-2636-04a, IBM Z Hardware Management Console Web Services API (Version 2.14.0) `_ HMC API 2.14.1 - `IBM SC27-2637, IBM Z Hardware Management Console Web Services API (Version 2.14.1) `_ + `IBM SC27-2637-01a, IBM Z Hardware Management Console Web Services API (Version 2.14.1) `_ HMC API 2.15.0 - `IBM SC27-2638, IBM Z Hardware Management Console Web Services API (Version 2.15.0) `_ + `IBM SC27-2638-04c, IBM Z Hardware Management Console Web Services API (Version 2.15.0) `_ + (covers both GA1 and GA2) + + HMC API 2.16.0 + `IBM SC27-2642-02, IBM Z Hardware Management Console Web Services API (Version 2.16.0) `_ (covers both GA1 and GA2) + + HMC Security + `IBM SC28-6987-01, Hardware Management Console Security `_ + +.. _`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..4a89040b 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 @@ -103,15 +103,15 @@ name match - Only for \ :literal:`state=set`\ : Match properties for identifying the target adapter in the set of adapters in the CPC, if an adapter with the name specified in the \ :literal:`name`\ module parameter does not exist in that set. This parameter will be ignored otherwise. + Only for :literal:`state=set`\ : Match properties for identifying the target adapter in the set of adapters in the CPC, if an adapter with the name specified in the :literal:`name` module parameter does not exist in that set. This parameter will be ignored otherwise. - Use of this parameter allows renaming an adapter: The \ :literal:`name`\ module parameter specifies the new name of the target adapter, and the \ :literal:`match`\ module parameter identifies the adapter to be renamed. This can be combined with other property updates by using the \ :literal:`properties`\ module parameter. + Use of this parameter allows renaming an adapter: The :literal:`name` module parameter specifies the new name of the target adapter, and the :literal:`match` module parameter identifies the adapter to be renamed. This can be combined with other property updates by using the :literal:`properties` module parameter. The parameter is a dictionary. The key of each dictionary item is the property name as specified in the data model for adapter resources, with underscores instead of hyphens. The value of each dictionary item is the match value for the property (in YAML syntax). Integer properties may also be provided as decimal strings. The specified match properties follow the rules of filtering for the zhmcclient library as described in https://python-zhmcclient.readthedocs.io/en/stable/concepts.html#filtering - The possible match properties are all properties in the data model for adapter resources, including \ :literal:`name`\ . + The possible match properties are all properties in the data model for adapter resources, including :literal:`name`. | **required**: False | **type**: dict @@ -120,13 +120,13 @@ match state The desired state for the adapter. All states are fully idempotent within the limits of the properties that can be changed: - \* \ :literal:`set`\ : Ensures that an existing adapter has the specified properties. + \* :literal:`set`\ : Ensures that an existing adapter has the specified properties. - \* \ :literal:`present`\ : Ensures that a Hipersockets adapter exists and has the specified properties. + \* :literal:`present`\ : Ensures that a Hipersockets adapter exists and has the specified properties. - \* \ :literal:`absent`\ : Ensures that a Hipersockets adapter does not exist. + \* :literal:`absent`\ : Ensures that a Hipersockets adapter does not exist. - \* \ :literal:`facts`\ : Returns the adapter properties including its ports. + \* :literal:`facts`\ : Returns the adapter properties including its ports. | **required**: True | **type**: str @@ -134,17 +134,17 @@ state properties - Only for \ :literal:`state=set|present`\ : New values for the properties of the adapter. Properties omitted in this dictionary will remain unchanged. This parameter will be ignored for other states. + Only for :literal:`state=set|present`\ : New values for the properties of the adapter. Properties omitted in this dictionary will remain unchanged. This parameter will be ignored for other states. The parameter is a dictionary. The key of each dictionary item is the property name as specified in the data model for adapter resources, with underscores instead of hyphens. The value of each dictionary item is the property value (in YAML syntax). Integer properties may also be provided as decimal strings. The possible properties in this dictionary are the properties defined as writeable in the data model for adapter resources, with the following exceptions: - \* \ :literal:`name`\ : Cannot be specified as a property because the name has already been specified in the \ :literal:`name`\ module parameter. + \* :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 @@ -243,7 +243,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -255,9 +255,9 @@ msg | **type**: str adapter - For \ :literal:`state=absent`\ , an empty dictionary. + For :literal:`state=absent`\ , an empty dictionary. - For \ :literal:`state=set|present|facts`\ , the adapter and its ports. + For :literal:`state=set|present|facts`\ , the adapter and its ports. | **returned**: success | **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..5d46dea9 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 @@ -134,7 +134,7 @@ status additional_properties List of additional properties to be returned for each adapter, in addition to the default properties (see result description). - Mutually exclusive with \ :literal:`full\_properties`\ . + Mutually exclusive with :literal:`full\_properties`. The property names are specified with underscores instead of hyphens. @@ -148,9 +148,9 @@ additional_properties full_properties If True, all properties of each adapter will be returned. Default: False. - Mutually exclusive with \ :literal:`additional\_properties`\ . + Mutually exclusive with :literal:`additional\_properties`. - Note: Setting this to True causes a loop of 'Get Adapter Properties' operations to be executed. It is preferable from a performance perspective to use the \ :literal:`additional\_properties`\ parameter instead. + Note: Setting this to True causes a loop of 'Get Adapter Properties' operations to be executed. It is preferable from a performance perspective to use the :literal:`additional\_properties` parameter instead. | **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 @@ -278,7 +278,7 @@ adapters | **type**: str {additional_property} - Additional properties requested via \ :literal:`full\_properties`\ or \ :literal:`additional\_properties`\ . The property names will have underscores instead of hyphens. + Additional properties requested via :literal:`full\_properties` or :literal:`additional\_properties`. The property names will have underscores instead of hyphens. | **type**: raw 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..fc472e79 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 @@ -23,8 +23,8 @@ Synopsis Requirements ------------ -- For \ :literal:`state=facts`\ , no specific task or object-access permissions are required. -- For \ :literal:`state=upgrade`\ , task permission to the 'Single Step Console Internal Code' task is required. +- For :literal:`state=facts`\ , no specific task or object-access permissions are required. +- For :literal:`state=upgrade`\ , task permission to the 'Single Step Console Internal Code' task is required. @@ -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 @@ -89,9 +89,9 @@ hmc_auth state The action to be performed on the HMC: - \* \ :literal:`facts`\ : Returns facts about the HMC. + \* :literal:`facts`\ : Returns facts about the HMC. - \* \ :literal:`upgrade`\ : Upgrades the firmware of the HMC and returns the new facts after the upgrade. If the HMC firmware is already at the requested bundle level, nothing is changed and the module succeeds. + \* :literal:`upgrade`\ : Upgrades the firmware of the HMC and returns the new facts after the upgrade. If the HMC firmware is already at the requested bundle level, nothing is changed and the module succeeds. | **required**: True | **type**: str @@ -99,9 +99,9 @@ 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`\ + Required for :literal:`state=upgrade` | **required**: False | **type**: str @@ -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 @@ -133,7 +133,7 @@ backup_location_type accept_firmware Accept the previous bundle level before installing the new level. - Optional for \ :literal:`state=upgrade`\ , default: True + Optional for :literal:`state=upgrade`\ , default: True | **required**: False | **type**: bool @@ -188,7 +188,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -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..2451751e 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 @@ -99,15 +99,15 @@ name state The desired state for the CPC. All states are fully idempotent within the limits of the properties that can be changed: - \* \ :literal:`inactive`\ : Ensures the CPC is inactive. + \* :literal:`inactive`\ : Ensures the CPC is inactive. - \* \ :literal:`active`\ : Ensures the CPC is active and then ensures that the CPC has the specified properties. The operational mode of the CPC cannot be changed. + \* :literal:`active`\ : Ensures the CPC is active and then ensures that the CPC has the specified properties. The operational mode of the CPC cannot be changed. - \* \ :literal:`set`\ : Ensures that the CPC has the specified properties. + \* :literal:`set`\ : Ensures that the CPC has the specified properties. - \* \ :literal:`facts`\ : Returns the CPC properties including its child resources. + \* :literal:`facts`\ : Returns the CPC properties including its child resources. - \* \ :literal:`upgrade`\ : Upgrades the firmware of the SE of the CPC and returns the new facts after the upgrade. If the SE firmware is already at the requested bundle level, nothing is changed and the module succeeds. + \* :literal:`upgrade`\ : Upgrades the firmware of the SE of the CPC and returns the new facts after the upgrade. If the SE firmware is already at the requested bundle level, nothing is changed and the module succeeds. | **required**: True | **type**: str @@ -115,13 +115,13 @@ state select_properties - Limits the returned properties of the CPC to those specified in this parameter plus those specified in the \ :literal:`properties`\ parameter. + Limits the returned properties of the CPC to those specified in this parameter plus those specified in the :literal:`properties` parameter. The properties can be specified with underscores or hyphens in their names. Null indicates not to limit the returned properties in this way. - This parameter is ignored for \ :literal:`state`\ values that cause no properties to be returned. + This parameter is ignored for :literal:`state` values that cause no properties to be returned. The returned child resources (adapters, partitions, storage groups) cannot be excluded using this parameter. @@ -133,18 +133,18 @@ select_properties activation_profile_name - The name of the reset activation profile to be used when activating the CPC in the classic operational mode, for \ :literal:`state=active`\ . This parameter is ignored when the CPC is in classic mode and was already active, and when the CPC is in DPM mode. + The name of the reset activation profile to be used when activating the CPC in the classic operational mode, for :literal:`state=active`. This parameter is ignored when the CPC is in classic mode and was already active, and when the CPC is in DPM mode. Default: The reset activation profile specified in the 'next-activation-profile-name' property of the CPC. - This parameter is not allowed for the other \ :literal:`state`\ values. + This parameter is not allowed for the other :literal:`state` values. | **required**: False | **type**: str properties - Only for \ :literal:`state=set`\ and \ :literal:`state=active`\ : New values for the properties of the CPC. Properties omitted in this dictionary will remain unchanged. This parameter will be ignored for other \ :literal:`state`\ values. + Only for :literal:`state=set` and :literal:`state=active`\ : New values for the properties of the CPC. Properties omitted in this dictionary will remain unchanged. This parameter will be ignored for other :literal:`state` values. The parameter is a dictionary. The key of each dictionary item is the property name as specified in the data model for CPC resources, with underscores instead of hyphens. The value of each dictionary item is the property value (in YAML syntax). Integer properties may also be provided as decimal strings. @@ -155,9 +155,9 @@ 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`\ + Required for :literal:`state=upgrade` | **required**: False | **type**: str @@ -174,7 +174,7 @@ upgrade_timeout accept_firmware Accept the previous bundle level before installing the new level. - Optional for \ :literal:`state=upgrade`\ , default: True + Optional for :literal:`state=upgrade`\ , default: True | **required**: False | **type**: bool @@ -258,7 +258,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -270,9 +270,9 @@ msg | **type**: str cpc - For \ :literal:`state=inactive`\ , an empty dictionary. + For :literal:`state=inactive`\ , an empty dictionary. - For \ :literal:`state=active|set|facts|upgrade`\ , the resource properties of the CPC after after any specified updates have been applied, and its adapters, partitions, and storage groups. + For :literal:`state=active|set|facts|upgrade`\ , the resource properties of the CPC after after any specified updates have been applied, and its adapters, partitions, and storage groups. | **returned**: success | **type**: dict @@ -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..783af1d8 --- /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..cc11ee6f 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 @@ -212,7 +212,7 @@ cpcs | **type**: str {additional_property} - Additional properties requested via \ :literal:`full\_properties`\ . The property names will have underscores instead of hyphens. + Additional properties requested via :literal:`full\_properties`. The property names will have underscores instead of hyphens. | **type**: raw 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..38f329bc 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 @@ -105,11 +105,11 @@ partition_name state The desired state for the crypto attachment. All states are fully idempotent within the limits of the properties that can be changed: - \* \ :literal:`attached`\ : Ensures that the specified number of crypto adapters of the specified crypto type, and the specified range of domain index numbers in the specified access mode are attached to the partition. + \* :literal:`attached`\ : Ensures that the specified number of crypto adapters of the specified crypto type, and the specified range of domain index numbers in the specified access mode are attached to the partition. - \* \ :literal:`detached`\ : Ensures that no crypto adapter and no crypto domains are attached to the partition. + \* :literal:`detached`\ : Ensures that no crypto adapter and no crypto domains are attached to the partition. - \* \ :literal:`facts`\ : Returns the crypto configuration of the partition. + \* :literal:`facts`\ : Returns the crypto configuration of the partition. | **required**: True | **type**: str @@ -117,14 +117,14 @@ state adapter_count - Only for \ :literal:`state=attached`\ : The number of crypto adapters the partition needs to have attached. The special value -1 means all adapters of the desired crypto type in the CPC. The \ :literal:`adapter\_names`\ and \ :literal:`adapter\_count`\ parameters are mutually exclusive and one of them must be specified. + Only for :literal:`state=attached`\ : The number of crypto adapters the partition needs to have attached. The special value -1 means all adapters of the desired crypto type in the CPC. The :literal:`adapter\_names` and :literal:`adapter\_count` parameters are mutually exclusive and one of them must be specified. | **required**: False | **type**: int crypto_type - Only for \ :literal:`state=attached`\ : The crypto type of the crypto adapters that will be selected from when \ :literal:`adapter\_count`\ is specified. Ignored when \ :literal:`adapter\_names`\ is specified. + Only for :literal:`state=attached`\ : The crypto type of the crypto adapters that will be selected from when :literal:`adapter\_count` is specified. Ignored when :literal:`adapter\_names` is specified. | **required**: False | **type**: str @@ -133,7 +133,7 @@ crypto_type adapter_names - Only for \ :literal:`state=attached`\ : The names of the crypto adapters the partition needs to have attached. The \ :literal:`adapter\_names`\ and \ :literal:`adapter\_count`\ parameters are mutually exclusive and one of them must be specified. + Only for :literal:`state=attached`\ : The names of the crypto adapters the partition needs to have attached. The :literal:`adapter\_names` and :literal:`adapter\_count` parameters are mutually exclusive and one of them must be specified. | **required**: False | **type**: list @@ -141,7 +141,7 @@ adapter_names domain_range - Only for \ :literal:`state=attached`\ : The domain range the partition needs to have attached, as a tuple of integers (min, max) that specify the inclusive range of domain index numbers. Other domains attached to the partition remain unchanged. The special value -1 for the max item means the maximum supported domain index number. + Only for :literal:`state=attached`\ : The domain range the partition needs to have attached, as a tuple of integers (min, max) that specify the inclusive range of domain index numbers. Other domains attached to the partition remain unchanged. The special value -1 for the max item means the maximum supported domain index number. | **required**: False | **type**: list @@ -150,7 +150,7 @@ domain_range access_mode - Only for \ :literal:`state=attached`\ : The access mode in which the crypto domains specified in \ :literal:`domain\_range`\ need to be attached. + Only for :literal:`state=attached`\ : The access mode in which the crypto domains specified in :literal:`domain\_range` need to be attached. | **required**: False | **type**: str @@ -246,7 +246,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **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..cfe079d4 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 @@ -111,9 +111,9 @@ name state The desired state for the HBA. All states are fully idempotent within the limits of the properties that can be changed: - \* \ :literal:`absent`\ : Ensures that the HBA does not exist in the specified partition. + \* :literal:`absent`\ : Ensures that the HBA does not exist in the specified partition. - \* \ :literal:`present`\ : Ensures that the HBA exists in the specified partition and has the specified properties. + \* :literal:`present`\ : Ensures that the HBA exists in the specified partition and has the specified properties. | **required**: True | **type**: str @@ -121,17 +121,17 @@ state properties - Dictionary with input properties for the HBA, for \ :literal:`state=present`\ . Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. Will be ignored for \ :literal:`state=absent`\ . + Dictionary with input properties for the HBA, for :literal:`state=present`. Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. Will be ignored for :literal:`state=absent`. The possible input properties in this dictionary are the properties defined as writeable in the data model for HBA 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:`name`\ : Cannot be specified because the name has already been specified in the :literal:`name` module parameter. - \* \ :literal:`adapter\_port\_uri`\ : Cannot be specified because this information is specified using the artificial properties \ :literal:`adapter\_name`\ and \ :literal:`adapter\_port`\ . + \* :literal:`adapter\_port\_uri`\ : Cannot be specified because this information is specified using the artificial properties :literal:`adapter\_name` and :literal:`adapter\_port`. - \* \ :literal:`adapter\_name`\ : The name of the adapter that has the port backing the target HBA. Cannot be changed after the HBA exists. + \* :literal:`adapter\_name`\ : The name of the adapter that has the port backing the target HBA. Cannot be changed after the HBA exists. - \* \ :literal:`adapter\_port`\ : The port index of the adapter port backing the target HBA. Cannot be changed after the HBA exists. + \* :literal:`adapter\_port`\ : The port index of the adapter port backing the target HBA. Cannot be changed after the HBA exists. Properties omitted in this dictionary will remain unchanged when the HBA already exists, and will get the default value defined in the data model for HBAs when the HBA is being created. @@ -195,7 +195,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -207,9 +207,9 @@ msg | **type**: str hba - For \ :literal:`state=absent`\ , an empty dictionary. + For :literal:`state=absent`\ , an empty dictionary. - For \ :literal:`state=present`\ , the resource properties of the HBA after any changes. + For :literal:`state=present`\ , the resource properties of the HBA after any changes. | **returned**: success | **type**: dict @@ -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..473b0b32 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 @@ -97,11 +97,11 @@ name state The desired state for the LDAP Server Definition. All states are fully idempotent within the limits of the properties that can be changed: - \* \ :literal:`absent`\ : Ensures that the LDAP Server Definition does not exist. + \* :literal:`absent`\ : Ensures that the LDAP Server Definition does not exist. - \* \ :literal:`present`\ : Ensures that the LDAP Server Definition exists and has the specified properties. + \* :literal:`present`\ : Ensures that the LDAP Server Definition exists and has the specified properties. - \* \ :literal:`facts`\ : Returns the LDAP Server Definition properties. + \* :literal:`facts`\ : Returns the LDAP Server Definition properties. | **required**: True | **type**: str @@ -109,13 +109,13 @@ state properties - Dictionary with desired properties for the LDAP Server Definition. 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. + Dictionary with desired properties for the LDAP Server Definition. 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 LDAP Server Definition 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:`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 @@ -180,7 +180,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -192,9 +192,9 @@ msg | **type**: str ldap_server_definition - For \ :literal:`state=absent`\ , an empty dictionary. + For :literal:`state=absent`\ , an empty dictionary. - For \ :literal:`state=present|facts`\ , a dictionary with the resource properties of the target LDAP Server Definition. + For :literal:`state=present|facts`\ , a dictionary with the resource properties of the target LDAP Server Definition. | **returned**: success | **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. Write-only properties in the data model are not included. 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..3b6653a1 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..cada73dd 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 @@ -108,19 +108,19 @@ name state The desired state for the LPAR: - \* \ :literal:`inactive`\ : Ensures that the LPAR is inactive (i.e. status 'not-activated'), unless the LPAR is currently operating and the \ :literal:`force`\ parameter was not set to True. Properties cannot be updated. The LPAR is deactivated if needed. + \* :literal:`inactive`\ : Ensures that the LPAR is inactive (i.e. status 'not-activated'), unless the LPAR is currently operating and the :literal:`force` parameter was not set to True. Properties cannot be updated. The LPAR is deactivated if needed. - \* \ :literal:`active`\ : Ensures that the LPAR is at least active (i.e. status is 'not-operating', 'operating' or 'exceptions'), and then ensures that the LPAR properties have the specified values. The LPAR is activated if needed using the 'Activate Logical Partition' operation. In certain cases, that operation will automatically load the LPAR. For details, see the \ :literal:`activation\_profile\_name`\ parameter. + \* :literal:`active`\ : Ensures that the LPAR is at least active (i.e. status is 'not-operating', 'operating' or 'exceptions'), and then ensures that the LPAR properties have the specified values. The LPAR is activated if needed using the 'Activate Logical Partition' operation. In certain cases, that operation will automatically load the LPAR. For details, see the :literal:`activation\_profile\_name` parameter. - \* \ :literal:`loaded`\ : Ensures that the LPAR is loaded (i.e. status is 'operating' or 'exceptions'), and then ensures that the LPAR properties have the specified values. The LPAR is first activated if needed using the 'Activate Logical Partition' operation, and then loaded if needed using the 'Load Logical Partition' operation. For details, see the \ :literal:`activation\_profile\_name`\ parameter. + \* :literal:`loaded`\ : Ensures that the LPAR is loaded (i.e. status is 'operating' or 'exceptions'), and then ensures that the LPAR properties have the specified values. The LPAR is first activated if needed using the 'Activate Logical Partition' operation, and then loaded if needed using the 'Load Logical Partition' operation. For details, see the :literal:`activation\_profile\_name` parameter. - \* \ :literal:`reset\_clear`\ : Performs the 'Reset Clear' HMC operation on the LPAR. This initializes the LPAR for loading by clearing its pending interruptions, resetting its channel subsystem, resetting its processors, and clearing its memory). The LPAR must be in status 'not-operating', 'operating', or 'exceptions'. If the LPAR status is 'operating' or 'exceptions', the operation will fail unless the \ :literal:`force`\ parameter is set to True. Properties cannot be updated. + \* :literal:`reset\_clear`\ : Performs the 'Reset Clear' HMC operation on the LPAR. This initializes the LPAR for loading by clearing its pending interruptions, resetting its channel subsystem, resetting its processors, and clearing its memory). The LPAR must be in status 'not-operating', 'operating', or 'exceptions'. If the LPAR status is 'operating' or 'exceptions', the operation will fail unless the :literal:`force` parameter is set to True. Properties cannot be updated. - \* \ :literal:`reset\_normal`\ : Performs the 'Reset Normal' HMC operation on the LPAR. This initializes the LPAR for loading by clearing its pending interruptions, resetting its channel subsystem, and resetting its processors). It does not clear the memory. The LPAR must be in status 'not-operating', 'operating', or 'exceptions'. If the LPAR status is 'operating' or 'exceptions', the operation will fail unless the \ :literal:`force`\ parameter is set to True. Properties cannot be updated. + \* :literal:`reset\_normal`\ : Performs the 'Reset Normal' HMC operation on the LPAR. This initializes the LPAR for loading by clearing its pending interruptions, resetting its channel subsystem, and resetting its processors). It does not clear the memory. The LPAR must be in status 'not-operating', 'operating', or 'exceptions'. If the LPAR status is 'operating' or 'exceptions', the operation will fail unless the :literal:`force` parameter is set to True. Properties cannot be updated. - \* \ :literal:`set`\ : Ensures that the LPAR properties have the specified values. Requires that the LPAR is at least active (i.e. status is 'not-operating', 'operating' or 'exceptions') but does not activate the LPAR if that is not the case. + \* :literal:`set`\ : Ensures that the LPAR properties have the specified values. Requires that the LPAR is at least active (i.e. status is 'not-operating', 'operating' or 'exceptions') but does not activate the LPAR if that is not the case. - \* \ :literal:`facts`\ : Returns the current LPAR properties. + \* :literal:`facts`\ : Returns the current LPAR properties. In all cases, the LPAR must exist. @@ -130,13 +130,13 @@ state select_properties - Limits the returned properties of the LPAR to those specified in this parameter plus those specified in the \ :literal:`properties`\ parameter. + Limits the returned properties of the LPAR to those specified in this parameter plus those specified in the :literal:`properties` parameter. The properties can be specified with underscores or hyphens in their names. Null indicates not to limit the returned properties in this way. - This parameter is ignored for \ :literal:`state`\ values that cause no properties to be returned. + This parameter is ignored for :literal:`state` values that cause no properties to be returned. The specified properties are passed to the 'Get Logical Partition Properties' HMC operation using the 'properties' query parameter and save time for the HMC to pull together all properties. @@ -146,9 +146,9 @@ select_properties activation_profile_name - The name of the image or load activation profile to be used when the LPAR needs to be activated, for \ :literal:`state=active`\ and \ :literal:`state=loaded`\ . + The name of the image or load activation profile to be used when the LPAR needs to be activated, for :literal:`state=active` and :literal:`state=loaded`. - This parameter is not allowed for the other \ :literal:`state`\ values. + This parameter is not allowed for the other :literal:`state` values. Default: The image or load activation profile specified in the 'next-activation-profile-name' property of the LPAR is used when the LPAR needs to be activated. @@ -161,9 +161,9 @@ activation_profile_name load_address - The hexadecimal address of an I/O device that provides access to the control program to be loaded, for \ :literal:`state=loaded`\ . + The hexadecimal address of an I/O device that provides access to the control program to be loaded, for :literal:`state=loaded`. - This parameter is not allowed for the other \ :literal:`state`\ values. + This parameter is not allowed for the other :literal:`state` values. This parameter is used only when the LPAR is explicitly loaded using the 'Load Logical Partition' operation. It is not used when the LPAR is automatically loaded during the 'Activate Logical Partition' operation. @@ -174,9 +174,9 @@ load_address load_parameter - A parameter string that is passed to the control program when loading it, for \ :literal:`state=loaded`\ . + A parameter string that is passed to the control program when loading it, for :literal:`state=loaded`. - This parameter is not allowed for the other \ :literal:`state`\ values. + This parameter is not allowed for the other :literal:`state` values. This parameter is used only when the LPAR is explicitly loaded using the 'Load Logical Partition' operation. It is not used when the LPAR is automatically loaded during the 'Activate Logical Partition' operation. @@ -185,9 +185,9 @@ load_parameter clear_indicator - Controls whether memory is cleared before performing the load, for \ :literal:`state=loaded`\ . + Controls whether memory is cleared before performing the load, for :literal:`state=loaded`. - This parameter is not allowed for the other \ :literal:`state`\ values. + This parameter is not allowed for the other :literal:`state` values. This parameter is used only when the LPAR is explicitly loaded using the 'Load Logical Partition' operation. It is not used when the LPAR is automatically loaded during the 'Activate Logical Partition' operation. @@ -197,9 +197,9 @@ clear_indicator store_status_indicator - Controls whether the current values of CPU timer, clock comparator, program status word, and the contents of the processor registers are stored to their assigned absolute storage locations, for \ :literal:`state=loaded`\ . + Controls whether the current values of CPU timer, clock comparator, program status word, and the contents of the processor registers are stored to their assigned absolute storage locations, for :literal:`state=loaded`. - This parameter is not allowed for the other \ :literal:`state`\ values. + This parameter is not allowed for the other :literal:`state` values. This parameter is used only when the LPAR is explicitly loaded using the 'Load Logical Partition' operation. It is not used when the LPAR is automatically loaded during the 'Activate Logical Partition' operation. @@ -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'): @@ -227,20 +247,20 @@ force os_ipl_token - Setting this parameter for \ :literal:`state=reset\_clear`\ or \ :literal:`state=reset\_normal`\ requests that the corresponding HMC operations only be performed if the provided value matches the current value of the 'os-ipl-token' property of the LPAR, and be rejected otherwise. Note that the 'os-ipl-token' property of the LPAR is set by the operating system and is set only by some operating systems, such as z/OS. This parameter is ignored for other \ :literal:`state`\ values. + Setting this parameter for :literal:`state=reset\_clear` or :literal:`state=reset\_normal` requests that the corresponding HMC operations only be performed if the provided value matches the current value of the 'os-ipl-token' property of the LPAR, and be rejected otherwise. Note that the 'os-ipl-token' property of the LPAR is set by the operating system and is set only by some operating systems, such as z/OS. This parameter is ignored for other :literal:`state` values. | **required**: False | **type**: str properties - Dictionary with new values for the LPAR properties, for \ :literal:`state=active`\ , \ :literal:`state=loaded`\ and \ :literal:`state=set`\ . Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. + Dictionary with new values for the LPAR properties, for :literal:`state=active`\ , :literal:`state=loaded` and :literal:`state=set`. Key is the property name with underscores instead of hyphens, and 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 LPAR resources (where the property names contain underscores instead of hyphens). Properties omitted in this dictionary will not be updated. - This parameter is not allowed for the other \ :literal:`state`\ values. + This parameter is not allowed for the other :literal:`state` values. | **required**: False | **type**: dict @@ -356,7 +376,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -368,11 +388,11 @@ msg | **type**: str lpar - For \ :literal:`state=inactive|reset\_clear|reset\_normal`\ , an empty dictionary. + For :literal:`state=inactive|reset\_clear|reset\_normal`\ , an empty dictionary. - For \ :literal:`state=active|loaded|set|facts`\ , the resource properties of the LPAR after after any specified updates have been applied. + 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. Write-only properties in the data model are not included. 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..a8149fad --- /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..e292183d 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 @@ -99,7 +99,7 @@ cpc_name additional_properties List of additional properties to be returned for each LPAR, in addition to the default properties (see result description). - Mutually exclusive with \ :literal:`full\_properties`\ . + Mutually exclusive with :literal:`full\_properties`. The property names are specified with underscores instead of hyphens. @@ -113,9 +113,9 @@ additional_properties full_properties If True, all properties of each LPAR will be returned. Default: False. - Mutually exclusive with \ :literal:`additional\_properties`\ . + Mutually exclusive with :literal:`additional\_properties`. - Note: Setting this to True causes a loop of 'Get Logical Partition Properties' operations to be executed. It is preferable from a performance perspective to use the \ :literal:`additional\_properties`\ parameter instead. + Note: Setting this to True causes a loop of 'Get Logical Partition Properties' operations to be executed. It is preferable from a performance perspective to use the :literal:`additional\_properties` parameter instead. | **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,12 +224,12 @@ 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 {additional_property} - Additional properties requested via \ :literal:`full\_properties`\ or \ :literal:`additional\_properties`\ . The property names will have underscores instead of hyphens. + Additional properties requested via :literal:`full\_properties` or :literal:`additional\_properties`. The property names will have underscores instead of hyphens. | **type**: raw 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..af46fd48 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..9db08155 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 @@ -112,11 +112,11 @@ name state The desired state for the NIC. All states are fully idempotent within the limits of the properties that can be changed: - \* \ :literal:`absent`\ : Ensures that the NIC does not exist in the specified partition. + \* :literal:`absent`\ : Ensures that the NIC does not exist in the specified partition. - \* \ :literal:`present`\ : Ensures that the NIC exists in the specified partition and has the specified properties. + \* :literal:`present`\ : Ensures that the NIC exists in the specified partition and has the specified properties. - \* \ :literal:`facts`\ : Returns the NIC properties. + \* :literal:`facts`\ : Returns the NIC properties. | **required**: True | **type**: str @@ -124,17 +124,17 @@ state properties - Dictionary with input properties for the NIC, for \ :literal:`state=present`\ . Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. Will be ignored for \ :literal:`state=absent`\ . + Dictionary with input properties for the NIC, for :literal:`state=present`. Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. Will be ignored for :literal:`state=absent`. The possible input properties in this dictionary are the properties defined as writeable in the data model for NIC 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:`name`\ : Cannot be specified because the name has already been specified in the :literal:`name` module parameter. - \* \ :literal:`network\_adapter\_port\_uri`\ and \ :literal:`virtual\_switch\_uri`\ : Cannot be specified because this information is specified using the artificial properties \ :literal:`adapter\_name`\ and \ :literal:`adapter\_port`\ . + \* :literal:`network\_adapter\_port\_uri` and :literal:`virtual\_switch\_uri`\ : Cannot be specified because this information is specified using the artificial properties :literal:`adapter\_name` and :literal:`adapter\_port`. - \* \ :literal:`adapter\_name`\ : The name of the adapter that has the port backing the target NIC. Used for all adapter families (ROCE, OSA, Hipersockets). + \* :literal:`adapter\_name`\ : The name of the adapter that has the port backing the target NIC. Used for all adapter families (ROCE, OSA, Hipersockets). - \* \ :literal:`adapter\_port`\ : The port index of the adapter port backing the target NIC. Used for all adapter families (ROCE, OSA, Hipersockets). + \* :literal:`adapter\_port`\ : The port index of the adapter port backing the target NIC. Used for all adapter families (ROCE, OSA, Hipersockets). Properties omitted in this dictionary will remain unchanged when the NIC already exists, and will get the default value defined in the data model for NICs when the NIC is being created. @@ -208,7 +208,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -220,9 +220,9 @@ msg | **type**: str nic - For \ :literal:`state=absent`\ , an empty dictionary. + For :literal:`state=absent`\ , an empty dictionary. - For \ :literal:`state=present|facts`\ , the resource properties of the NIC after any changes. + For :literal:`state=present|facts`\ , the resource properties of the NIC after any changes. | **returned**: success | **type**: dict @@ -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..326b08b9 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 @@ -198,7 +198,7 @@ nics | **type**: str {additional_property} - Additional properties requested via \ :literal:`full\_properties`\ . The property names will have underscores instead of hyphens. + Additional properties requested via :literal:`full\_properties`. The property names will have underscores instead of hyphens. | **type**: raw 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..0d3faf26 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 @@ -105,17 +105,17 @@ name state The desired state for the partition. All states are fully idempotent within the limits of the properties that can be changed: - \* \ :literal:`absent`\ : Ensures that the partition does not exist in the specified CPC. + \* :literal:`absent`\ : Ensures that the partition does not exist in the specified CPC. - \* \ :literal:`stopped`\ : Ensures that the partition exists in the specified CPC, has the specified properties, and is in one of the inactive statuses ('stopped', 'terminated', 'paused', 'reservation-error'). + \* :literal:`stopped`\ : Ensures that the partition exists in the specified CPC, has the specified properties, and is in one of the inactive statuses ('stopped', 'terminated', 'paused', 'reservation-error'). - \* \ :literal:`active`\ : Ensures that the partition exists in the specified CPC, has the specified properties, and is in one of the active statuses ('active', 'degraded'). + \* :literal:`active`\ : Ensures that the partition exists in the specified CPC, has the specified properties, and is in one of the active statuses ('active', 'degraded'). - \* \ :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:`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). + \* :literal:`facts`\ : Returns the partition properties and the properties of its child resources (HBAs, NICs, and virtual functions). | **required**: True | **type**: str @@ -123,13 +123,13 @@ state select_properties - Limits the returned properties of the partition to those specified in this parameter plus those specified in the \ :literal:`properties`\ parameter. + Limits the returned properties of the partition to those specified in this parameter plus those specified in the :literal:`properties` parameter. The properties can be specified with underscores or hyphens in their names. Null indicates not to limit the returned properties in this way. - This parameter is ignored for \ :literal:`state`\ values that cause no properties to be returned. + This parameter is ignored for :literal:`state` values that cause no properties to be returned. The specified properties are passed to the 'Get Partition Properties' HMC operation using the 'properties' query parameter and save time for the HMC to pull together all properties. @@ -139,36 +139,36 @@ select_properties properties - Dictionary with input properties for the partition, for \ :literal:`state=stopped`\ and \ :literal:`state=active`\ . Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. Will be ignored for \ :literal:`state=absent`\ . + Dictionary with input properties for the partition, for :literal:`state=stopped` and :literal:`state=active`. Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. Will be ignored for :literal:`state=absent`. The possible input properties in this dictionary are the properties defined as writeable in the data model for Partition 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:`name`\ : Cannot be specified because the name has already been specified in the :literal:`name` module parameter. - \* \ :literal:`type`\ : Cannot be changed once the partition exists, because updating it is not supported. + \* :literal:`type`\ : Cannot be changed once the partition exists, because updating it is not supported. - \* \ :literal:`boot\_storage\_device`\ : Cannot be specified because this information is specified using the artificial property \ :literal:`boot\_storage\_hba\_name`\ . + \* :literal:`boot\_storage\_device`\ : Cannot be specified because this information is specified using the artificial property :literal:`boot\_storage\_hba\_name`. - \* \ :literal:`boot\_network\_device`\ : Cannot be specified because this information is specified using the artificial property \ :literal:`boot\_network\_nic\_name`\ . + \* :literal:`boot\_network\_device`\ : Cannot be specified because this information is specified using the artificial property :literal:`boot\_network\_nic\_name`. - \* \ :literal:`boot\_storage\_hba\_name`\ : The name of the HBA whose URI is used to construct \ :literal:`boot\_storage\_device`\ . Specifying it requires that the partition exists. Only valid when the partition is on a z13. + \* :literal:`boot\_storage\_hba\_name`\ : The name of the HBA whose URI is used to construct :literal:`boot\_storage\_device`. Specifying it requires that the partition exists. Only valid when the partition is on a z13. - \* \ :literal:`boot\_storage\_group\_name`\ : The name of the storage group that contains the boot volume specified with \ :literal:`boot\_storage\_volume\_name`\ . + \* :literal:`boot\_storage\_group\_name`\ : The name of the storage group that contains the boot volume specified with :literal:`boot\_storage\_volume\_name`. - \* \ :literal:`boot\_storage\_volume\_name`\ : The name of the storage volume in storage group \ :literal:`boot\_storage\_group\_name`\ whose URI is used to construct \ :literal:`boot\_storage\_volume`\ . This property is mutually exclusive with \ :literal:`boot\_storage\_volume`\ . Specifying it requires that the partition and storage group exist. Only valid when the partition is on a z14 or later. + \* :literal:`boot\_storage\_volume\_name`\ : The name of the storage volume in storage group :literal:`boot\_storage\_group\_name` whose URI is used to construct :literal:`boot\_storage\_volume`. This property is mutually exclusive with :literal:`boot\_storage\_volume`. Specifying it requires that the partition and storage group exist. Only valid when the partition is on a z14 or later. - \* \ :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:`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 image_name - Name of the ISO image for \ :literal:`state=iso\_mount`\ (required). Not permitted for any other \ :literal:`state`\ values. + Name of the ISO image for :literal:`state=iso\_mount` (required). Not permitted for any other :literal:`state` values. This value is shown in the 'boot-iso-image-name' property of the partition. @@ -179,16 +179,16 @@ image_name image_file - Path name of the local ISO image file for \ :literal:`state=iso\_mount`\ (required). Not permitted for any other \ :literal:`state`\ values. + Path name of the local ISO image file for :literal:`state=iso\_mount` (required). Not permitted for any other :literal:`state` values. - When mounting an ISO image, this file is opened for reading and its content is sent to the HMC using the 'Mount ISO Image' operation. This file is not used when an image with the name specified in \ :literal:`image\_name`\ was already mounted. + When mounting an ISO image, this file is opened for reading and its content is sent to the HMC using the 'Mount ISO Image' operation. This file is not used when an image with the name specified in :literal:`image\_name` was already mounted. | **required**: False | **type**: str ins_file - Path name of the INS file within the ISO image that will be used when booting from the ISO image for \ :literal:`state=iso\_mount`\ (required). Not permitted for any other \ :literal:`state`\ values. + Path name of the INS file within the ISO image that will be used when booting from the ISO image for :literal:`state=iso\_mount` (required). Not permitted for any other :literal:`state` values. This value is shown in the 'boot-iso-ins-file' property of the partition. @@ -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 @@ -352,7 +352,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -364,9 +364,9 @@ msg | **type**: str partition - For \ :literal:`state=absent|iso\_mount|iso\_unmount`\ , an empty dictionary. + For :literal:`state=absent|iso\_mount|iso\_unmount`\ , an empty dictionary. - For \ :literal:`state=stopped|active|facts`\ , the resource properties of the partition after any changes, including its child resources as described below. + For :literal:`state=stopped|active|facts`\ , the resource properties of the partition after any changes, including its child resources as described below. | **returned**: success | **type**: dict @@ -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. Write-only properties in the data model are not included. 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..64ee10a6 --- /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..cf3ff675 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) +================================================= @@ -19,7 +19,7 @@ Synopsis - List partitions on a specific CPC (Z system) or on all managed CPCs. - CPCs in classic mode are ignored (i.e. do not lead to a failure). - Partitions for which the user has no object access permission are ignored (i.e. do not lead to a failure). -- On HMCs with version 2.14.0 or higher and when the \ :literal:`additional\_properties`\ module parameter is not used, the "List Permitted Partitions" operation is used by this module. Otherwise, the managed CPCs are listed and then the partitions on each desired CPC or CPCs are listed. This improves the execution time of the module on newer HMCs but does not affect the module result data. +- On HMCs with version 2.14.0 or higher and when the :literal:`additional\_properties` module parameter is not used, the "List Permitted Partitions" operation is used by this module. Otherwise, the managed CPCs are listed and then the partitions on each desired CPC or CPCs are listed. This improves the execution time of the module on newer HMCs but does not affect the module result data. Requirements @@ -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 @@ -99,7 +99,7 @@ cpc_name additional_properties List of additional properties to be returned for each partition, in addition to the default properties (see result description). - Mutually exclusive with \ :literal:`full\_properties`\ . + Mutually exclusive with :literal:`full\_properties`. The property names are specified with underscores instead of hyphens. @@ -113,9 +113,9 @@ additional_properties full_properties If True, all properties of each partition will be returned. Default: False. - Mutually exclusive with \ :literal:`additional\_properties`\ . + Mutually exclusive with :literal:`additional\_properties`. - Note: Setting this to True causes a loop of 'Get Partition Properties' operations to be executed. It is preferable from a performance perspective to use the \ :literal:`additional\_properties`\ parameter instead. + Note: Setting this to True causes a loop of 'Get Partition Properties' operations to be executed. It is preferable from a performance perspective to use the :literal:`additional\_properties` parameter instead. | **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 @@ -229,7 +229,7 @@ partitions | **type**: bool {additional_property} - Additional properties requested via \ :literal:`full\_properties`\ or \ :literal:`additional\_properties`\ . The property names will have underscores instead of hyphens. + Additional properties requested via :literal:`full\_properties` or :literal:`additional\_properties`. The property names will have underscores instead of hyphens. | **type**: raw 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..337c4a3a 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..990a531a 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 @@ -95,11 +95,11 @@ name state The desired state for the HMC password rule. All states are fully idempotent within the limits of the properties that can be changed: - \* \ :literal:`absent`\ : Ensures that the password rule does not exist. + \* :literal:`absent`\ : Ensures that the password rule does not exist. - \* \ :literal:`present`\ : Ensures that the password rule exists and has the specified properties. + \* :literal:`present`\ : Ensures that the password rule exists and has the specified properties. - \* \ :literal:`facts`\ : Returns the password rule properties. + \* :literal:`facts`\ : Returns the password rule properties. | **required**: True | **type**: str @@ -107,13 +107,13 @@ state properties - Dictionary with desired properties for the password rule. 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. + Dictionary with desired properties for the password rule. 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 Password Rule 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:`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 @@ -176,7 +176,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -188,9 +188,9 @@ msg | **type**: str password_rule - For \ :literal:`state=absent`\ , an empty dictionary. + For :literal:`state=absent`\ , an empty dictionary. - For \ :literal:`state=present|facts`\ , a dictionary with the resource properties of the target password rule. + For :literal:`state=present|facts`\ , a dictionary with the resource properties of the target password rule. | **returned**: success | **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..34141e16 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 @@ -167,7 +167,7 @@ password_rules | **type**: str {additional_property} - Additional properties requested via \ :literal:`full\_properties`\ . The property names will have underscores instead of hyphens. + Additional properties requested via :literal:`full\_properties`. The property names will have underscores instead of hyphens. | **type**: raw 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..03e162cb 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 @@ -16,8 +16,8 @@ zhmc_session -- Manage HMC sessions across tasks Synopsis -------- -- Create a session on the HMC for use by other ibm\_zhmc modules, with \ :literal:`action=create`\ . -- Delete a session on the HMC, with \ :literal:`action=delete`\ . +- Create a session on the HMC for use by other ibm\_zhmc modules, with :literal:`action=create`. +- Delete a session on the HMC, with :literal:`action=delete`. - This module can be used in order to create an HMC session once and then use it for multiple tasks that use ibm\_zhmc modules, reducing the number of HMC sessions that need to be created, to just one. When this module is not used, each ibm\_zhmc module invocation will create and delete a separate HMC session. @@ -48,7 +48,7 @@ hmc_auth userid The userid (username) for creating the HMC session. - Required for \ :literal:`action=create`\ , not permitted for \ :literal:`action=delete`\ . + Required for :literal:`action=create`\ , not permitted for :literal:`action=delete`. | **required**: False | **type**: str @@ -57,7 +57,7 @@ hmc_auth password The password for creating the HMC session. - Required for \ :literal:`action=create`\ , not permitted for \ :literal:`action=delete`\ . + Required for :literal:`action=create`\ , not permitted for :literal:`action=delete`. | **required**: False | **type**: str @@ -66,25 +66,25 @@ hmc_auth session_id Session ID of the HMC session to be deleted. - Required for \ :literal:`action=delete`\ , not permitted for \ :literal:`action=create`\ . + Required for :literal:`action=delete`\ , not permitted for :literal:`action=create`. | **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. - Optional for \ :literal:`action=create`\ , not permitted for \ :literal:`action=delete`\ . + Optional for :literal:`action=create`\ , not permitted for :literal:`action=delete`. | **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. - Optional for \ :literal:`action=create`\ , not permitted for \ :literal:`action=delete`\ . + Optional for :literal:`action=create`\ , not permitted for :literal:`action=delete`. | **required**: False | **type**: bool @@ -95,9 +95,9 @@ hmc_auth action The action to perform for the HMC session. Since an HMC session does not have a name, it is not possible to specify the desired end state in an idempotent manner, so this module uses actions: - \* \ :literal:`create`\ : Create a new session on the HMC and verify that the credentials are valid. Requires \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and uses \ :literal:`hmc\_auth.ca\_certs`\ and \ :literal:`hmc\_auth.verify`\ if provided. + \* :literal:`create`\ : Create a new session on the HMC and verify that the credentials are valid. Requires :literal:`hmc\_auth.userid` and :literal:`hmc\_auth.password` and uses :literal:`hmc\_auth.ca\_certs` and :literal:`hmc\_auth.verify` if provided. - \* \ :literal:`delete`\ : Delete the specified session on the HMC. No longer existing sessions are tolerated. Requires \ :literal:`hmc\_auth.session\_id`\ . + \* :literal:`delete`\ : Delete the specified session on the HMC. No longer existing sessions are tolerated. Requires :literal:`hmc\_auth.session\_id`. | **required**: True | **type**: str @@ -175,15 +175,15 @@ 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. + For :literal:`action=delete`\ , returns the null value. | **returned**: success | **type**: str hmc_auth - Credentials for the HMC session, for use by other tasks. This return value should be protected with \ :literal:`no\_log=true`\ for \ :literal:`action=create`\ , since it contains the HMC session ID. For \ :literal:`action=delete`\ , the same structure is returned, just with null values. This can be used to reset the variable that was set for \ :literal:`action=create`\ . + Credentials for the HMC session, for use by other tasks. This return value should be protected with :literal:`no\_log=true` for :literal:`action=create`\ , since it contains the HMC session ID. For :literal:`action=delete`\ , the same structure is returned, just with null values. This can be used to reset the variable that was set for :literal:`action=create`. | **returned**: success | **type**: dict @@ -198,17 +198,17 @@ hmc_auth } session_id - New HMC session ID for \ :literal:`action=create`\ , or null for \ :literal:`action=delete`\ . + New HMC session ID for :literal:`action=create`\ , or null for :literal:`action=delete`. | **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..ca84cdf5 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 @@ -104,13 +104,13 @@ name state The desired state for the storage group. All states are fully idempotent within the limits of the properties that can be changed, unless otherwise stated: - \* \ :literal:`absent`\ : Ensures that the storage group does not exist. If the storage group is currently attached to any partitions, the module will fail (this is an idempotency limitation). + \* :literal:`absent`\ : Ensures that the storage group does not exist. If the storage group is currently attached to any partitions, the module will fail (this is an idempotency limitation). - \* \ :literal:`present`\ : Ensures that the storage group exists and is associated with the specified CPC, and has the specified properties. The attachment state of an already existing storage group to a partition is not changed. + \* :literal:`present`\ : Ensures that the storage group exists and is associated with the specified CPC, and has the specified properties. The attachment state of an already existing storage group to a partition is not changed. - \* \ :literal:`discover`\ : Triggers LUN discovery. If \ :literal:`discover\_wait`\ is specified, waits for completion of the discovery. Requires that the storage group exists and is of type 'fcp'. + \* :literal:`discover`\ : Triggers LUN discovery. If :literal:`discover\_wait` is specified, waits for completion of the discovery. Requires that the storage group exists and is of type 'fcp'. - \* \ :literal:`facts`\ : Returns the storage group properties. + \* :literal:`facts`\ : Returns the storage group properties. | **required**: True | **type**: str @@ -118,15 +118,15 @@ state properties - Dictionary with desired properties for the storage group. 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. + Dictionary with desired properties for the storage group. 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 Storage Group 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:`name`\ : Cannot be specified because the name has already been specified in the :literal:`name` module parameter. - \* \ :literal:`type`\ : Cannot be changed once the storage group exists. + \* :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 @@ -140,14 +140,14 @@ expand discover_wait - Boolean that controls whether to wait for completion of the FCP discovery for \ :literal:`state=discover`\ . + Boolean that controls whether to wait for completion of the FCP discovery for :literal:`state=discover`. | **required**: False | **type**: bool discover_timeout - Timeout in seconds for how long to wait for completion of the FCP discovery for \ :literal:`state=discover`\ . + Timeout in seconds for how long to wait for completion of the FCP discovery for :literal:`state=discover`. | **required**: False | **type**: int @@ -237,7 +237,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -249,9 +249,9 @@ msg | **type**: str storage_group - For \ :literal:`state=absent`\ , an empty dictionary. + For :literal:`state=absent`\ , an empty dictionary. - For \ :literal:`state=present|facts|discover`\ , the resource properties of the target storage group after any changes, plus additional artificial properties as described below. + For :literal:`state=present|facts|discover`\ , the resource properties of the target storage group after any changes, plus additional artificial properties as described below. | **returned**: success | **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 @@ -484,7 +484,7 @@ storage_group | **elements**: str candidate-adapter-ports - Only present if \ :literal:`expand=true`\ : List of candidate storage adapter ports of the storage group. Will be empty for storage group types other than FCP. + Only present if :literal:`expand=true`\ : List of candidate storage adapter ports of the storage group. Will be empty for storage group types other than FCP. | **returned**: success+expand | **type**: list @@ -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,14 +516,14 @@ 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 storage-volumes - Only present if \ :literal:`expand=true`\ : Storage volumes of the storage group. + Only present if :literal:`expand=true`\ : Storage volumes of the storage group. | **returned**: success+expand | **type**: list @@ -535,33 +535,33 @@ 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 virtual-storage-resources - Only present if \ :literal:`expand=true`\ : Virtual storage resources of the storage group. Will be empty for storage group types other than FCP. + Only present if :literal:`expand=true`\ : Virtual storage resources of the storage group. Will be empty for storage group types other than FCP. | **returned**: success+expand | **type**: list | **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 attached-partitions - Only present if \ :literal:`expand=true`\ : Partitions to which the storage group is attached. + Only present if :literal:`expand=true`\ : Partitions to which the storage group is attached. | **returned**: success+expand | **type**: list | **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..bdd3386f 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 @@ -111,11 +111,11 @@ partition_name state The desired state for the storage group attachment. All states are fully idempotent within the limits of the properties that can be changed, unless otherwise stated: - \* \ :literal:`detached`\ : Ensures that the storage group is not attached to the partition. If the storage group is currently attached to the partition and the partition is currently active, the module will fail (this is an idempotency limitation). + \* :literal:`detached`\ : Ensures that the storage group is not attached to the partition. If the storage group is currently attached to the partition and the partition is currently active, the module will fail (this is an idempotency limitation). - \* \ :literal:`attached`\ : Ensures that the storage group is attached to the partition. + \* :literal:`attached`\ : Ensures that the storage group is attached to the partition. - \* \ :literal:`facts`\ : Returns the attachment status. + \* :literal:`facts`\ : Returns the attachment status. | **required**: True | **type**: str @@ -188,7 +188,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **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..bb352a90 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 @@ -111,11 +111,11 @@ name state The desired state for the storage volume. All states are fully idempotent within the limits of the properties that can be changed: - \* \ :literal:`absent`\ : Ensures that the storage volume does not exist in the specified storage group. + \* :literal:`absent`\ : Ensures that the storage volume does not exist in the specified storage group. - \* \ :literal:`present`\ : Ensures that the storage volume exists in the specified storage group, and has the specified properties. + \* :literal:`present`\ : Ensures that the storage volume exists in the specified storage group, and has the specified properties. - \* \ :literal:`facts`\ : Returns the storage volume properties. + \* :literal:`facts`\ : Returns the storage volume properties. | **required**: True | **type**: str @@ -123,13 +123,13 @@ state properties - Dictionary with desired properties for the storage volume. 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. + Dictionary with desired properties for the storage volume. 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 Storage Volume 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:`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 @@ -205,7 +205,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -217,9 +217,9 @@ msg | **type**: str storage_volume - For \ :literal:`state=absent`\ , an empty dictionary. + For :literal:`state=absent`\ , an empty dictionary. - For \ :literal:`state=present|facts`\ , the resource properties of the storage volume after any changes. + For :literal:`state=present|facts`\ , the resource properties of the storage volume after any changes. | **returned**: success | **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..a762718d 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 @@ -96,11 +96,11 @@ name state The desired state for the HMC user. All states are fully idempotent within the limits of the properties that can be changed: - \* \ :literal:`absent`\ : Ensures that the user does not exist. + \* :literal:`absent`\ : Ensures that the user does not exist. - \* \ :literal:`present`\ : Ensures that the user exists and has the specified properties. + \* :literal:`present`\ : Ensures that the user exists and has the specified properties. - \* \ :literal:`facts`\ : Returns the user properties. + \* :literal:`facts`\ : Returns the user properties. | **required**: True | **type**: str @@ -108,32 +108,32 @@ state properties - Dictionary with desired properties for the user. 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. + Dictionary with desired properties for the user. 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 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:`name`\ : Cannot be specified because the name has already been specified in the :literal:`name` module parameter. - \* \ :literal:`type`\ : Cannot be changed once the user exists. + \* :literal:`type`\ : Cannot be changed once the user exists. - \* \ :literal:`user\_roles`\ : Cannot be set directly, but indirectly via the artificial property \ :literal:`user\_role\_names`\ which replaces the current user roles, if specified. + \* :literal:`user\_roles`\ : Cannot be set directly, but indirectly via the artificial property :literal:`user\_role\_names` which replaces the current user roles, if specified. - \* \ :literal:`user\_pattern\_uri`\ : Cannot be set directly, but indirectly via the artificial property \ :literal:`user\_pattern\_name`\ . + \* :literal:`user\_pattern\_uri`\ : Cannot be set directly, but indirectly via the artificial property :literal:`user\_pattern\_name`. - \* \ :literal:`password\_rule\_uri`\ : Cannot be set directly, but indirectly via the artificial property \ :literal:`password\_rule\_name`\ . + \* :literal:`password\_rule\_uri`\ : Cannot be set directly, but indirectly via the artificial property :literal:`password\_rule\_name`. - \* \ :literal:`ldap\_server\_definition\_uri`\ : Cannot be set directly, but indirectly via the artificial property \ :literal:`ldap\_server\_definition\_name`\ . + \* :literal:`ldap\_server\_definition\_uri`\ : Cannot be set directly, but indirectly via the artificial property :literal:`ldap\_server\_definition\_name`. - \* \ :literal:`default\_group\_uri`\ : Cannot be set directly, but indirectly via the artificial property \ :literal:`default\_group\_name`\ . + \* :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 expand - Deprecated: The \ :literal:`expand`\ parameter is deprecated because the returned password rule, user role, user pattern and LDAP server definition objects have an independent lifecycle, so the same objects are returned when invoking this module in a loop through all users. Use the respective other modules of this collection to get the properties of these objects. + Deprecated: The :literal:`expand` parameter is deprecated because the returned password rule, user role, user pattern and LDAP server definition objects have an independent lifecycle, so the same objects are returned when invoking this module in a loop through all users. Use the respective other modules of this collection to get the properties of these objects. Boolean that controls whether the returned user contains additional artificial properties that expand certain URI or name properties to the full set of resource properties (see description of return values of this module). @@ -205,7 +205,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -217,9 +217,9 @@ msg | **type**: str user - For \ :literal:`state=absent`\ , an empty dictionary. + For :literal:`state=absent`\ , an empty dictionary. - For \ :literal:`state=present|facts`\ , a dictionary with the resource properties of the target user, plus additional artificial properties as described in the following list items. + For :literal:`state=present|facts`\ , a dictionary with the resource properties of the target user, plus additional artificial properties as described in the following list items. | **returned**: success | **type**: dict @@ -277,78 +277,78 @@ 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. Write-only properties in the data model are not included. The property names have hyphens (-) as described in that book. | **type**: raw user-role-names - Name of the user roles referenced by property \ :literal:`user-roles`\ . + Name of the user roles referenced by property :literal:`user-roles`. | **type**: str user-role-objects - Deprecated: This result property is deprecated because the \ :literal:`expand`\ parameter is deprecated. + Deprecated: This result property is deprecated because the :literal:`expand` parameter is deprecated. - Only if \ :literal:`expand=true`\ : User roles referenced by property \ :literal:`user-roles`\ . + Only if :literal:`expand=true`\ : User roles referenced by property :literal:`user-roles`. | **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 user-pattern-name - Only for users with \ :literal:`type=pattern`\ : Name of the user pattern referenced by property \ :literal:`user-pattern-uri`\ . + Only for users with :literal:`type=pattern`\ : Name of the user pattern referenced by property :literal:`user-pattern-uri`. | **type**: str user-pattern - Deprecated: This result property is deprecated because the \ :literal:`expand`\ parameter is deprecated. + Deprecated: This result property is deprecated because the :literal:`expand` parameter is deprecated. - Only for users with \ :literal:`type=pattern`\ and if \ :literal:`expand=true`\ : User pattern referenced by property \ :literal:`user-pattern-uri`\ . + Only for users with :literal:`type=pattern` and if :literal:`expand=true`\ : User pattern referenced by property :literal:`user-pattern-uri`. | **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 password-rule-name - Only for users with \ :literal:`authentication-type=local`\ : Name of the password rule referenced by property \ :literal:`password-rule-uri`\ . + Only for users with :literal:`authentication-type=local`\ : Name of the password rule referenced by property :literal:`password-rule-uri`. | **type**: str password-rule - Deprecated: This result property is deprecated because the \ :literal:`expand`\ parameter is deprecated. + Deprecated: This result property is deprecated because the :literal:`expand` parameter is deprecated. - Only for users with \ :literal:`authentication-type=local`\ and if \ :literal:`expand=true`\ : Password rule referenced by property \ :literal:`password-rule-uri`\ . + Only for users with :literal:`authentication-type=local` and if :literal:`expand=true`\ : Password rule referenced by property :literal:`password-rule-uri`. | **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 ldap-server-definition-name - Only for users with \ :literal:`authentication-type=ldap`\ : Name of the LDAP server definition referenced by property \ :literal:`ldap-server-definition-uri`\ . + Only for users with :literal:`authentication-type=ldap`\ : Name of the LDAP server definition referenced by property :literal:`ldap-server-definition-uri`. | **type**: str ldap-server-definition - Deprecated: This result property is deprecated because the \ :literal:`expand`\ parameter is deprecated. + Deprecated: This result property is deprecated because the :literal:`expand` parameter is deprecated. - Only for users with \ :literal:`authentication-type=ldap`\ and if \ :literal:`expand=true`\ : LDAP server definition referenced by property \ :literal:`ldap-server-definition-uri`\ . + Only for users with :literal:`authentication-type=ldap` and if :literal:`expand=true`\ : LDAP server definition referenced by property :literal:`ldap-server-definition-uri`. | **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. Write-only properties in the data model are not included. 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..39ab46f6 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,12 +169,12 @@ 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 {additional_property} - Additional properties requested via \ :literal:`full\_properties`\ . The property names will have underscores instead of hyphens. + Additional properties requested via :literal:`full\_properties`. The property names will have underscores instead of hyphens. | **type**: raw 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..2a19eb6e --- /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..0aebe832 --- /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..1a9949a4 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 @@ -95,11 +95,11 @@ name state The desired state for the HMC user role. All states are fully idempotent within the limits of the properties that can be changed: - \* \ :literal:`absent`\ : Ensures that the user role does not exist. + \* :literal:`absent`\ : Ensures that the user role does not exist. - \* \ :literal:`present`\ : Ensures that the user role exists and has the specified properties. + \* :literal:`present`\ : Ensures that the user role exists and has the specified properties. - \* \ :literal:`facts`\ : Returns the user role properties. + \* :literal:`facts`\ : Returns the user role properties. | **required**: True | **type**: str @@ -107,19 +107,19 @@ state properties - Dictionary with desired properties for the user role. 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. + Dictionary with desired properties for the user role. 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 role 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:`name`\ : Cannot be specified because the name has already been specified in the :literal:`name` module parameter. - \* \ :literal:`associated\_system\_defined\_user\_role\_uri`\ : Cannot be specified because this information is specified using the artificial property \ :literal:`associated\_system\_defined\_user\_role\_name`\ . + \* :literal:`associated\_system\_defined\_user\_role\_uri`\ : Cannot be specified because this information is specified using the artificial property :literal:`associated\_system\_defined\_user\_role\_name`. - \* \ :literal:`associated\_system\_defined\_user\_role\_name`\ : The name of the associated system-defined user role. + \* :literal:`associated\_system\_defined\_user\_role\_name`\ : The name of the associated system-defined user role. - \* \ :literal:`permissions`\ : Can be specified as if it were writeable. + \* :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 @@ -159,14 +159,14 @@ properties view_only - Option item only for \ :literal:`task`\ : Indicates whether the task's view-only version is subject of the permission. Only certain tasks have a view-only version. Default: true. + Option item only for :literal:`task`\ : Indicates whether the task's view-only version is subject of the permission. Only certain tasks have a view-only version. Default: true. | **required**: False | **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). | **required**: False | **type**: str @@ -180,7 +180,7 @@ properties include_members - Option item only for \ :literal:`group`\ : Indicates whether the group members are included in the permission. Default: false. + Option item only for :literal:`group`\ : Indicates whether the group members are included in the permission. Default: false. | **required**: False | **type**: bool @@ -198,7 +198,7 @@ properties partition Permission item: Object permission to the partition with the specified name on the specified CPC (in DPM mode). - Requires \ :literal:`cpc`\ to be specified as a scoping item. + Requires :literal:`cpc` to be specified as a scoping item. | **required**: False | **type**: str @@ -207,7 +207,7 @@ properties lpar Permission item: Object permission to the LPAR with the specified name on the specified CPC (in classic mode). - Requires \ :literal:`cpc`\ to be specified as a scoping item. + Requires :literal:`cpc` to be specified as a scoping item. | **required**: False | **type**: str @@ -216,7 +216,7 @@ properties adapter Permission item: Object permission to the adapter with the specified name on the specified CPC (in DPM mode). - Requires \ :literal:`cpc`\ to be specified as a scoping item. + Requires :literal:`cpc` to be specified as a scoping item. | **required**: False | **type**: str @@ -225,7 +225,7 @@ properties storage_group Permission item: Object permission to the storage group with the specified name that is associated with the specified CPC (in DPM mode). - Requires \ :literal:`cpc`\ to be specified as a scoping item. + Requires :literal:`cpc` to be specified as a scoping item. | **required**: False | **type**: str @@ -234,7 +234,7 @@ properties storage_group_template Permission item: Object permission to the storage group template with the specified name that is associated with the specified CPC (in DPM mode). - Requires \ :literal:`cpc`\ to be specified as a scoping item. + Requires :literal:`cpc` to be specified as a scoping item. | **required**: False | **type**: str @@ -313,7 +313,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -325,9 +325,9 @@ msg | **type**: str user_role - For \ :literal:`state=absent`\ , an empty dictionary. + For :literal:`state=absent`\ , an empty dictionary. - For \ :literal:`state=present|facts`\ , a dictionary with the resource properties of the target user role. + For :literal:`state=present|facts`\ , a dictionary with the resource properties of the target user role. | **returned**: success | **type**: dict @@ -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 @@ -398,12 +398,12 @@ user_role | **type**: str view_only - Option item present for \ :literal:`task`\ : Indicates whether the task's view-only version is subject of the permission. Only certain tasks have a view-only version, but the option item will be present for all tasks. + Option item present for :literal:`task`\ : Indicates whether the task's view-only version is subject of the permission. Only certain tasks have a view-only version, but the option item will be present for all tasks. | **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 @@ -413,7 +413,7 @@ user_role | **type**: str include_members - Option item present for \ :literal:`group`\ : Indicates whether the group members are included in the permission. The option item will be present for all groups. + Option item present for :literal:`group`\ : Indicates whether the group members are included in the permission. The option item will be present for all groups. | **type**: bool @@ -427,41 +427,41 @@ user_role partition Permission item: Object permission to the partition with the specified name on the specified CPC (in DPM mode). - \ :literal:`cpc`\ will be present as a scoping item. + :literal:`cpc` will be present as a scoping item. | **type**: str lpar Permission item: Object permission to the LPAR with the specified name on the specified CPC (in classic mode). - \ :literal:`cpc`\ will be present as a scoping item. + :literal:`cpc` will be present as a scoping item. | **type**: str adapter Permission item: Object permission to the adapter with the specified name on the specified CPC (in DPM mode). - \ :literal:`cpc`\ will be present as a scoping item. + :literal:`cpc` will be present as a scoping item. | **type**: str storage_group Permission item: Object permission to the storage group with the specified name that is associated with the specified CPC (in DPM mode). - \ :literal:`cpc`\ will be present as a scoping item. + :literal:`cpc` will be present as a scoping item. | **type**: str storage_group_template Permission item: Object permission to the storage group template with the specified name that is associated with the specified CPC (in DPM mode). - \ :literal:`cpc`\ will be present as a scoping item. + :literal:`cpc` will be present as a scoping item. | **type**: str {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..ce8bb637 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,12 +169,12 @@ 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 {additional_property} - Additional properties requested via \ :literal:`full\_properties`\ . The property names will have underscores instead of hyphens. + Additional properties requested via :literal:`full\_properties`. The property names will have underscores instead of hyphens. | **type**: raw 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..0116d3e8 --- /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..9307a3a6 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 @@ -111,9 +111,9 @@ name state The desired state for the virtual function. All states are fully idempotent within the limits of the properties that can be changed: - \* \ :literal:`absent`\ : Ensures that the virtual function does not exist in the specified partition. + \* :literal:`absent`\ : Ensures that the virtual function does not exist in the specified partition. - \* \ :literal:`present`\ : Ensures that the virtual function exists in the specified partition and has the specified properties. + \* :literal:`present`\ : Ensures that the virtual function exists in the specified partition and has the specified properties. | **required**: True | **type**: str @@ -121,15 +121,15 @@ state properties - Dictionary with input properties for the virtual function, for \ :literal:`state=present`\ . Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. Will be ignored for \ :literal:`state=absent`\ . + Dictionary with input properties for the virtual function, for :literal:`state=present`. Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. Will be ignored for :literal:`state=absent`. The possible input properties in this dictionary are the properties defined as writeable in the data model for Virtual Function 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:`name`\ : Cannot be specified because the name has already been specified in the :literal:`name` module parameter. - \* \ :literal:`adapter\_uri`\ : Cannot be specified because this information is specified using the artificial property \ :literal:`adapter\_name`\ . + \* :literal:`adapter\_uri`\ : Cannot be specified because this information is specified using the artificial property :literal:`adapter\_name`. - \* \ :literal:`adapter\_name`\ : The name of the adapter that backs the target virtual function. + \* :literal:`adapter\_name`\ : The name of the adapter that backs the target virtual function. Properties omitted in this dictionary will remain unchanged when the virtual function already exists, and will get the default value defined in the data model for virtual functions when the virtual function is being created. @@ -192,7 +192,7 @@ Return Values changed - Indicates if any change has been made by the module. For \ :literal:`state=facts`\ , always will be false. + Indicates if any change has been made by the module. For :literal:`state=facts`\ , always will be false. | **returned**: always | **type**: bool @@ -204,9 +204,9 @@ msg | **type**: str virtual_function - For \ :literal:`state=absent`\ , an empty dictionary. + For :literal:`state=absent`\ , an empty dictionary. - For \ :literal:`state=present`\ , the resource properties of the virtual function after any changes. + For :literal:`state=present`\ , the resource properties of the virtual function after any changes. | **returned**: success | **type**: dict @@ -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..974ec8ba 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,236 @@ Releases ======== -Version 1.8.3 +Version 1.9.3 ------------- -Released: 2024-02-29 +Released: 2024-11-29 Availability: `AutomationHub`_, `Galaxy`_, `GitHub`_ **Bug fixes:** -* Fixed safety issues up to 2024-02-18. +* Increased zhmcclient version to 1.18.2 to pick up fixes. (issue #1074) -* Fixed dependabot issues up to 2024-02-18. +* Fixed that all password-like input parameters that were written in clear text + to the module entry log are now blanked out. This affected the following + modules: zhmc_ldap_server_definition, zhmc_lpar, zhmc_partition, zhmc_user. + +* Fixed that all password-like input parameters that were added to the + module return value in clear text for 'state' values that created or updated + the resource are now removed from the return value. This affected the + following modules: zhmc_ldap_server_definition, zhmc_lpar, zhmc_partition. + +* Docs: Ignored www.ansible.com in linkcheck, because it occasionally times out. + + +Version 1.9.2 +------------- + +Released: 2024-11-22 + +Availability: `AutomationHub`_, `Galaxy`_, `GitHub`_ + +**Bug fixes:** + +* Fixed safety issues up to 2024-11-21. + +* Dev: Fixed removal of some files in the Makefile. + +* Fixed that the zhmc_user module blanked out the 'password' property in + the input params before passing them on to the zhmcclient + 'User.update_properties()' method. (issue #1081) + +* Docs: Fixed broken links to IBM documentation and updated permanently + redirected links. + +**Enhancements:** + +* Support for ansible-core 2.18, by adding an ignore file for the sanity tests. + +* The 'hmc_auth' input parameter is no longer completely removed from the + module entry log, but instead its sensitive items 'password' and 'session_id' + are now blanked out. + + +Version 1.9.1 +------------- + +Released: 2024-07-18 -* Fixed readable attribute error when ensuring ISO mounted onto the partition. - (related to issue #932) +Availability: `AutomationHub`_, `Galaxy`_, `GitHub`_ + +**Bug fixes:** + +* Fixed safety issues up to 20024-07-19. + +* 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. + +* Dev: Fixed new issue 'too-many-positional-arguments' reported by Pylint 3.3.0. **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/modules.html b/ibm_zos_cics/docs/source/modules.html index e8310919..84af47ed 100644 --- a/ibm_zos_cics/docs/source/modules.html +++ b/ibm_zos_cics/docs/source/modules.html @@ -242,6 +242,7 @@

Using Defaults Groups in CICS Provisioning ModulesTo override the data set location or name for a specific task, you can provide an additional parameter to the region_data_sets group as shown in the example for a global catalog data set below.

+

N.B. There is a known limitation with ansible-core version 2.15.0 and 2.15.1, where the custom templating may fail.

- name: Initialize a global catalog with a custom name
   ibm.ibm_zos_cics.global_catalog:
     region_data_sets:
diff --git a/ibm_zos_cics/docs/source/modules/cmci_action.html b/ibm_zos_cics/docs/source/modules/cmci_action.html
index 1ac5d5ac..d179c2e8 100644
--- a/ibm_zos_cics/docs/source/modules/cmci_action.html
+++ b/ibm_zos_cics/docs/source/modules/cmci_action.html
@@ -437,31 +437,29 @@ 

ParametersExamples

- name: Newcopy a program
   cmci_action:
-    cmci_host: "winmvs2c.hursley.ibm.com"
-    cmci_port: 10080
-    context: "iyk3z0r9"
-    type: "CICSProgram"
+    cmci_host: "example.com"
+    cmci_port: 12345
+    context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment
+    type: CICSProgram
     action_name: NEWCOPY
-    resource:
+    resources:
       filter:
-        name: "PONGALT"
-      get_parameters:
-        - name: "csdgroup"
-          value: "JVMGRP"
+        name: PONGALT
 
-- name: install a bundle in a CICS region
+- name: Install a bundle definition from CSD in a CICS region
   cmci_action:
-    cmci_host: "winmvs2c.hursley.ibm.com"
-    cmci_port: "10080"
-    context: "iyk3z0r9"
+    cmci_host: "example.com"
+    cmci_port: 1234
+    context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment
+    scope: IJKLMNOP # scope only applies if you're in a CPSM environment and is the name of a CICS system definition (CSYSDEF) or CICS system group (CSYSGRP)
     type: CICSBundle
-    action_name: install
-    resource:
+    action_name: CSDINSTALL
+    resources:
       filter:
-        name: "PONGALT"
-    action_parameters:
-      - name: "usage"
-        value: "local"
+        name: mybund
+      get_parameters:
+        - name: csdgroup
+          value: mygrp
 
diff --git a/ibm_zos_cics/docs/source/modules/cmci_create.html b/ibm_zos_cics/docs/source/modules/cmci_create.html index d9c1b175..f2c2f5b1 100644 --- a/ibm_zos_cics/docs/source/modules/cmci_create.html +++ b/ibm_zos_cics/docs/source/modules/cmci_create.html @@ -345,18 +345,19 @@

Parameters

Examples

-
- name: define a BUNDLE in a CSD
+
- name: Define a BUNDLE in CSD
   cmci_create:
-    cmci_host: "winmvs2c.hursley.ibm.com"
-    cmci_port: 10080
-    context: "iyk3z0r9"
-    type: "CICSDefinitionBundle"
+    cmci_host: "example.com"
+    cmci_port: 12345
+    context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment
+    type: CICSDefinitionBundle
+    scope: IJKLMNOP # scope only applies if you're in a CPSM environment and is the name of a CICS system definition (CSYSDEF) or CICS system group (CSYSGRP)
     attributes:
       name: PONGALT
       bundledir: /u/ibmuser/bundle/pong/pongbundle_1.0.0
       csdgroup: JVMGRP
     create_parameters:
-      - name: "csd"
+      - name: csd
 
diff --git a/ibm_zos_cics/docs/source/modules/cmci_delete.html b/ibm_zos_cics/docs/source/modules/cmci_delete.html index ff6437dc..e416cfde 100644 --- a/ibm_zos_cics/docs/source/modules/cmci_delete.html +++ b/ibm_zos_cics/docs/source/modules/cmci_delete.html @@ -411,26 +411,27 @@

ParametersExamples

- name: delete a bundle in a CICS region
   cmci_delete:
-    cmci_host: "winmvs2c.hursley.ibm.com"
-    cmci_port: 10080
-    context: "iyk3z0r9"
+    cmci_host: "example.com"
+    cmci_port: 12345
+    context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment
     type: CICSBundle
-    resource:
+    resources:
       filter:
-        name: "PONGALT"
+        name: PONGALT
 
 - name: delete a bundle definition in a CICS region
   cmci_delete:
-    cmci_host: "winmvs2c.hursley.ibm.com"
-    cmci_port: 10080
-    context: "iyk3z0r9"
+    cmci_host: "example.com"
+    cmci_port: 12345
+    context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment
     type: CICSDefinitionBundle
-    resource:
+    scope: IJKLMNOP # scope only applies if you're in a CPSM environment and is the name of a CICS system definition (CSYSDEF) or CICS system group (CSYSGRP)
+    resources:
       filter:
-        name: "PONGALT"
+        name: PONGALT
       get_parameters:
-        - name: "csdgroup"
-          value: "JVMGRP"
+        - name: csdgroup
+          value: JVMGRP
 
diff --git a/ibm_zos_cics/docs/source/modules/cmci_get.html b/ibm_zos_cics/docs/source/modules/cmci_get.html index 9d7c70dc..ffca3265 100644 --- a/ibm_zos_cics/docs/source/modules/cmci_get.html +++ b/ibm_zos_cics/docs/source/modules/cmci_get.html @@ -425,40 +425,40 @@

Parameters

Examples

-
- name: get 2 LOCFILEs from a CICSplex
+
- name: Get 2 LOCFILEs from a CICSplex
   cmci_get:
-    cmci_host: "winmvs2c.hursley.ibm.com"
-    cmci_port: 10080
-    cmci_user: "ibmuser"
+    cmci_host: "example.com"
+    cmci_port: 12345
+    cmci_user: ibmuser
     cmci_password: "123456"
-    context: "iyk3z0r9"
+    context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment
     type: CICSLocalFile
     record_count: 2
-    resource:
+    resources:
       filter:
         dsname: "CTS*"
 
-- name: get a localfile in a CICS region
+- name: Get a localfile in a CICS region
   cmci_get:
-    cmci_host: "winmvs2c.hursley.ibm.com"
-    cmci_port: 10080
+    cmci_host: "example.com"
+    cmci_port: 12345
     cmci_cert: "./sec/ansible.pem"
     cmci_key: "./sec/ansible.key"
-    context: "iyk3z0r9"
-    type: "CICSLocalFile"
+    context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment
+    type: CICSLocalFile
     resources:
       filter:
         dsname: "XIAOPIN*"
         file: "DFH*"
     record_count: 1
 
-- name: get a progdef from a CSD
+- name: Get a progdef from CSD
   cmci_get:
-    cmci_host: "winmvs2c.hursley.ibm.com"
-    cmci_port: 10080
+    cmci_host: "example.com"
+    cmci_port: 12345
     cmci_cert: "./sec/ansible.pem"
     cmci_key: "./sec/ansible.key"
-    context: "iyk3z0r9"
+    context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment
     type: cicsdefinitionprogram
     resources:
       filter:
@@ -468,13 +468,14 @@ 

Examplesvalue: MYGRP record_count: 1 -- name: pass module even if bundle definition is not found +- name: Ignore errors when bundle definition is not found cmci_get: - cmci_host: "winmvs2c.hursley.ibm.com" - cmci_port: 10080 + cmci_host: "example.com" + cmci_port: 12345 cmci_cert: "./sec/ansible.pem" cmci_key: "./sec/ansible.key" - context: "iyk3z0r9" + context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment + scope: IJKLMNOP # scope only applies if you're in a CPSM environment and is the name of a CICS system definition (CSYSDEF) or CICS system group (CSYSGRP) type: cicsdefinitionbundle resources: filter: @@ -483,16 +484,16 @@

Examples- name: csdgroup value: MYGRP record_count: 1 - fail_on_nodata: "false" + fail_on_nodata: false - name: Using complex_filter to combine filter expressions and change operators cmci_get: - cmci_host: "winmvs2c.hursley.ibm.com" - cmci_port: 10080 + cmci_host: "example.com" + cmci_port: 12345 cmci_cert: "./sec/ansible.pem" cmci_key: "./sec/ansible.key" - context: "iyk3z0r9" - type: "CICSRegion" + context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment + type: CICSRegion resources: complex_filter: or: diff --git a/ibm_zos_cics/docs/source/modules/cmci_update.html b/ibm_zos_cics/docs/source/modules/cmci_update.html index fd0f1c72..9d2cc8c6 100644 --- a/ibm_zos_cics/docs/source/modules/cmci_update.html +++ b/ibm_zos_cics/docs/source/modules/cmci_update.html @@ -435,19 +435,20 @@

Parameters

Examples

-
- name: update a bundle definition in a CICS region
+
- name: Update the description of a bundle definition in CSD
   cmci_update:
-    cmci_host: "winmvs2c.hursley.ibm.com"
-    cmci_port: "10080"
-    context: "iyk3z0r9"
-    type: "CICSDefinitionBundle"
+    cmci_host: "example.com"
+    cmci_port: 12345
+    context: ABCDEFGH # context is the name of your CICSplex in a CPSM environment or the applid of your region in an SMSS environment
+    scope: IJKLMNOP # scope only applies if you're in a CPSM environment and is the name of a CICS system definition (CSYSDEF) or CICS system group (CSYSGRP)
+    type: CICSDefinitionBundle
     attributes:
-      description: "New description"
+      description: New description
     update_parameters:
       - name: csd
-    resource:
+    resources:
       filter:
-        name: "PONGALT"
+        name: PONGALT
       get_parameters:
         - name: csdgroup
           value: JVMGRP
diff --git a/ibm_zos_cics/docs/source/modules/csd.html b/ibm_zos_cics/docs/source/modules/csd.html
index 1dfae3a6..bf2591c5 100644
--- a/ibm_zos_cics/docs/source/modules/csd.html
+++ b/ibm_zos_cics/docs/source/modules/csd.html
@@ -441,6 +441,7 @@ 

Examplestemplate: "REGIONS.ABCD0001.<< data_set_name >>" cics_data_sets: template: "CICSTS61.CICS.<< lib_name >>" + state: changed input_location: "USS" input_src: "/u/tester/defs/script.csdup" @@ -450,6 +451,7 @@

Examplestemplate: "REGIONS.ABCD0001.<< data_set_name >>" cics_data_sets: template: "CICSTS61.CICS.<< lib_name >>" + state: changed input_location: "LOCAL" input_src: "/User/tester/defs/script.csdup" @@ -459,6 +461,7 @@

Examplestemplate: "REGIONS.ABCD0001.<< data_set_name >>" cics_data_sets: template: "CICSTS61.CICS.<< lib_name >>" + state: changed input_location: "INLINE" input_content: | DEFINE PROGRAM(TESTPRG1) GROUP(TESTGRP1) diff --git a/ibm_zos_cics/docs/source/modules/region_jcl.html b/ibm_zos_cics/docs/source/modules/region_jcl.html index bc467f7d..3820299e 100644 --- a/ibm_zos_cics/docs/source/modules/region_jcl.html +++ b/ibm_zos_cics/docs/source/modules/region_jcl.html @@ -2676,6 +2676,7 @@

Exampleswlmhealth: "OFF" wrkarea: 2048 sysidnt: ZPY1 + state: initial - name: Create CICS startup JCL data set with more customization ibm.ibm_zos_cics.region_jcl: @@ -2729,6 +2730,7 @@

Exampleswlmhealth: "OFF" wrkarea: 2048 sysidnt: ZPY1 + state: initial

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
      +
    • Version 1.0.6
    • -
    • Version 1.1.0-beta.4 -
    • -
    • Version 1.1.0-beta.3 -
    • -
    • Version 1.1.0-beta.2 -
    • -
    • Version 1.1.0-beta.1 -
    • Version 1.0.5
    • Version 1.0.4
    • Version 1.0.3
    • Version 1.0.1 @@ -240,32 +224,23 @@

      Version 2.1.0

      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:

      +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 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.

      • +
      • 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.

      Changed modules

      The group name for the CMCI modules is changed to cmci instead of cmci_group. cmci_group is deprecated.

      @@ -284,92 +259,19 @@

      What’s New -

      Version 1.1.0-beta.5

      +
      +

      Version 1.0.6

      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

      -
      -

      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

      -
      -

      What’s New

      +
      +

      What’s New

      • Bug fix that includes the requirements.txt file in the built collection.

      @@ -377,8 +279,8 @@

      What’s New

      Version 1.0.4

      -
      -

      What’s New

      +
      +

      What’s New

      diff --git a/ibm_zos_core/docs/source/modules/zos_apf.html b/ibm_zos_core/docs/source/modules/zos_apf.html index 91dccafa..4b21be54 100644 --- a/ibm_zos_core/docs/source/modules/zos_apf.html +++ b/ibm_zos_core/docs/source/modules/zos_apf.html @@ -121,6 +121,7 @@
    • zos_tso_command – Execute TSO commands
    • zos_unarchive – Unarchive files and data sets in z/OS.
    • zos_volume_init – Initialize volumes or minidisks.
    • +
    • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • diff --git a/ibm_zos_core/docs/source/modules/zos_archive.html b/ibm_zos_core/docs/source/modules/zos_archive.html index b2cca08c..0ed70130 100644 --- a/ibm_zos_core/docs/source/modules/zos_archive.html +++ b/ibm_zos_core/docs/source/modules/zos_archive.html @@ -122,6 +122,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -245,8 +246,10 @@

    Parameters
    src

    List of names or globs of UNIX System Services (USS) files, PS (sequential data sets), PDS, PDSE to compress or archive.

    USS file paths should be absolute paths.

    +

    GDS relative notation is supported.

    MVS data sets supported types are: SEQ, PDS, PDSE.

    VSAMs are not supported.

    +

    GDS relative names are supported. e.g. USER.GDG(-1).

    -
    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.

    +
    exclude

    Remote absolute path, glob, or list of paths, globs, data set name patterns or generation data sets (GDSs) in relative notation for the file, files or data sets to exclude from src list and glob expansion.

    Patterns (wildcards) can contain one of the following, ?, *.

    • matches everything.

    ? matches any single character.

    +

    GDS relative names are supported. e.g. USER.GDG(-1).

    diff --git a/ibm_zos_core/docs/source/modules/zos_backup_restore.html b/ibm_zos_core/docs/source/modules/zos_backup_restore.html index 0fb01121..7704d2cb 100644 --- a/ibm_zos_core/docs/source/modules/zos_backup_restore.html +++ b/ibm_zos_core/docs/source/modules/zos_backup_restore.html @@ -97,6 +97,7 @@
  • Synopsis
  • Parameters
  • Examples
  • +
  • Notes
  • zos_blockinfile – Manage block of multi-line textual data on z/OS
  • @@ -119,6 +120,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -222,6 +224,7 @@
  • Synopsis

  • Parameters

  • Examples

  • +
  • Notes

  • @@ -252,6 +255,7 @@

    Parameters
    include

    When operation=backup, specifies a list of data sets or data set patterns to include in the backup.

    +

    When operation=backup GDS relative names are supported.

    When operation=restore, specifies a list of data sets or data set patterns to include when restoring from a backup.

    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, **, indicates either the nonexistence of leading, trailing, or middle qualifiers, or the fact that they play no role in the selection process.

    @@ -263,6 +267,7 @@

    Parameters

    exclude

    When operation=backup, specifies a list of data sets or data set patterns to exclude from the backup.

    +

    When operation=backup GDS relative names are supported.

    When operation=restore, specifies a list of data sets or data set patterns to exclude when restoring from a backup.

    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, **, indicates either the nonexistence of leading, trailing, or middle qualifiers, or the fact that they play no role in the selection process.

    @@ -303,12 +308,13 @@

    Parametersbackup_name

    When operation=backup, the destination data set or UNIX file to hold the backup.

    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 .dzp for UNIX files and .DZP for data sets will improve readability.

    +

    GDS relative names are supported when operation=restore.

    required: True
    type: str
    -
    recover

    Specifies if potentially recoverable errors should be ignored.

    +
    recover

    When recover=true and operation=backup then potentially recoverable errors will be ignored.

    hlq

    Specifies the new HLQ to use for the data sets being restored.

    -

    Defaults to running user’s username.

    +

    If no value is provided, the data sets will be restored with their original HLQs.

    required: False
    type: str
    -
    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 TMPHLQ is used.

    +
    tmp_hlq

    Override the default high level qualifier (HLQ) for temporary data sets used in the module’s operation.

    +

    If tmp_hlq is set, this value will be applied to all temporary data sets.

    +

    If tmp_hlq is not set, the value will be the username who submits the ansible task, this is the default behavior. If the username can not be identified, the value TMPHLQ is used.

    required: False
    type: str
    @@ -393,6 +400,15 @@

    Examplesexclude: user.private.* backup_name: MY.BACKUP.DZP +- name: Backup a list of GDDs to data set my.backup.dzp + zos_backup_restore: + operation: backup + data_sets: + include: + - user.gdg(-1) + - user.gdg(0) + backup_name: my.backup.dzp + - name: Backup all datasets matching the pattern USER.** to UNIX file /tmp/temp_backup.dzp, ignore recoverable errors. zos_backup_restore: operation: backup @@ -433,8 +449,8 @@

    Examplesspace: 1 space_type: g -- name: Restore data sets from backup stored in the UNIX file /tmp/temp_backup.dzp. - Use z/OS username as new HLQ. +- name: Restore data sets from a backup stored in the UNIX file /tmp/temp_backup.dzp. + Restore the data sets with the original high level qualifiers. zos_backup_restore: operation: restore backup_name: /tmp/temp_backup.dzp @@ -489,6 +505,15 @@

    Examples +

    Notes

    +
    +

    Note

    +

    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 to run either the playbook or playbook tasks, who can also obtain escalated privileges to execute as root or another user.

    +

    When using this module, if the RACF FACILITY class profile STGADMIN.ADR.DUMP.TOLERATE.ENQF is active, you must have READ access authority to use the module option recover=true. If the RACF FACILITY class checking is not set up, any user can use the module option without access to the class.

    +

    If your system uses a different security product, consult that product’s documentation to configure the required security classes.

    +
    +

    diff --git a/ibm_zos_core/docs/source/modules/zos_blockinfile.html b/ibm_zos_core/docs/source/modules/zos_blockinfile.html index d02e21c6..fff8ded8 100644 --- a/ibm_zos_core/docs/source/modules/zos_blockinfile.html +++ b/ibm_zos_core/docs/source/modules/zos_blockinfile.html @@ -122,6 +122,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -243,6 +244,7 @@

    Parameters
    src

    The location can be a UNIX System Services (USS) file, PS (sequential data set), member of a PDS or PDSE, PDS, PDSE.

    The USS file must be an absolute pathname.

    +

    Generation data set (GDS) relative name of generation already created. e.g. SOME.CREATION(-1).

    marker_begin

    This will be inserted at {mark} in the opening ansible block marker.

    +

    Value needs to be different from marker_end.

    marker_end

    This will be inserted at {mark} in the closing ansible block marker.

    +

    Value must be different from marker_begin.

    diff --git a/ibm_zos_core/docs/source/modules/zos_copy.html b/ibm_zos_core/docs/source/modules/zos_copy.html index e6a703c7..b5e572c4 100644 --- a/ibm_zos_core/docs/source/modules/zos_copy.html +++ b/ibm_zos_core/docs/source/modules/zos_copy.html @@ -122,6 +122,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -265,6 +266,7 @@

    ParametersIf 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 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 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.

    +

    If backup_name is a generation data set (GDS), it must be a relative positive name (for example, V(HLQ.USER.GDG(+1))).

    required: False
    type: str
    @@ -285,10 +287,13 @@

    ParametersIf 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 nonexistent data set, it will be created following the process outlined here and in the volume option.

    If dest is a nonexistent data set, the attributes assigned will depend on the type of src. If src is a USS file, dest will have a Fixed Block (FB) record format and the remaining attributes will be computed. If is_binary=true, dest will have a Fixed Block (FB) record format with a record length of 80, block size of 32760, and the remaining attributes will be computed. If executable=true,``dest`` will have an Undefined (U) record format with a record length of 0, block size of 32760, and the remaining attributes will be computed.

    +

    If src is a file and dest a partitioned data set, dest does not need to include a member in its value, the module can automatically compute the resulting member name from src.

    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 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 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 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.

    +

    dest can be a previously allocated generation data set (GDS) or a new GDS.

    +

    When dest is a generation data group (GDG), src must be a GDG too. The copy will allocate successive new generations in dest, the module will verify it has enough available generations before starting the copy operations.

    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.

    -
    force_lock

    By default, when dest is a MVS data set and is being used by another process with DISP=SHR or DISP=OLD the module will fail. Use force_lock to bypass this check and continue with copy.

    +
    force_lock

    By default, when dest is a MVS data set and is being used by another process with DISP=SHR or DISP=OLD the module will fail. Use force_lock to bypass DISP=SHR and continue with the copy operation.

    If set to true and destination is a MVS data set opened by another process then zos_copy will try to copy using DISP=SHR.

    Using force_lock uses operations that are subject to race conditions and can lead to data loss, use with caution.

    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.

    @@ -345,12 +350,12 @@

    Parametersdefault: False

    -
    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 true. By doing so, the module would essentially ignore the stderr stream produced by SFTP and continue execution.

    +
    ignore_sftp_stderr

    During data transfer through SFTP, the SFTP command directs content to stderr. By default, the module essentially ignores the stderr stream produced by SFTP and continues execution. The user is able to override this behavior by setting this parameter to false. By doing so, any content written to stderr is considered an error by Ansible and will cause the module to fail.

    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
    -
    default: False
    +
    default: True
    is_binary

    If set to true, indicates that the file or data set to be copied is a binary file or data set.

    @@ -431,6 +436,8 @@

    ParametersIf 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 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 VSAM data set, dest must also be a VSAM.

    +

    If src is a generation data set (GDS), it must be a previously allocated one.

    +

    If src is a generation data group (GDG), dest can be another GDG or a USS directory.

    Wildcards can be used to copy multiple PDS/PDSE members to another PDS/PDSE.

    Required unless using content.

    dest_data_set

    Data set attributes to customize a dest data set to be copied into.

    +

    Some attributes only apply when dest is a generation data group (GDG).

    space_primary

    If the destination dest data set does not exist , this sets the primary space allocated for the data set.

    @@ -562,6 +570,52 @@

    Parameterstype: str

    +
    limit

    Sets the limit attribute for a GDG.

    +

    Specifies the maximum number, from 1 to 255(up to 999 if extended), of generations that can be associated with the GDG being defined.

    +

    limit is required when type=gdg.

    +
    +
    required: False
    +
    type: int
    +
    +
    +
    empty

    Sets the empty attribute for a GDG.

    +

    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.

    +
    +
    required: False
    +
    type: bool
    +
    +
    +
    scratch

    Sets the scratch attribute for a GDG.

    +

    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
    +
    +
    +
    purge

    Sets the purge attribute for a GDG.

    +

    Specifies whether to override expiration dates when a generation data set (GDS) is rolled off and the scratch option is set.

    +
    +
    required: False
    +
    type: bool
    +
    +
    +
    extended

    Sets the extended attribute for a GDG.

    +

    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.

    +
    +
    required: False
    +
    type: bool
    +
    +
    +
    fifo

    Sets the fifo attribute for a GDG.

    +

    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.

    +
    +
    required: False
    +
    type: bool
    +
    +
    use_template

    Whether the module should treat src as a Jinja2 template and render it before continuing with the rest of the module.

    @@ -673,6 +727,13 @@

    Parametersdefault: False

    +
    autoescape

    Whether to enable autoescape of XML/HTML elements on a template.

    +
    +
    required: False
    +
    type: bool
    +
    default: True
    +
    +
    @@ -862,6 +923,19 @@

    Examplessrc: ./files/print.txt dest: HLQ.PRINT.NEW asa_text: true + +- name: Copy a file to a new generation data set. + zos_copy: + src: /path/to/uss/src + dest: HLQ.TEST.GDG(+1) + remote_src: true + +- name: Copy a local file and take a backup of the existing file with a GDS. + zos_copy: + src: /path/to/local/file + dest: /path/to/dest + backup: true + backup_name: HLQ.BACKUP.GDG(+1) diff --git a/ibm_zos_core/docs/source/modules/zos_data_set.html b/ibm_zos_core/docs/source/modules/zos_data_set.html index f2d2bd8f..9b99ec34 100644 --- a/ibm_zos_core/docs/source/modules/zos_data_set.html +++ b/ibm_zos_core/docs/source/modules/zos_data_set.html @@ -120,6 +120,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -251,6 +252,7 @@

    ParametersIf 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 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 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 state=absent and type=gdg and the GDG base has active generations the module will complete successfully with changed=False. To remove it option force needs to be used. If the GDG base does not have active generations the module will complete successfully with 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 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 state=present and replace=False and the data set is present on the managed node, no action taken, module completes successfully with changed=False.

    @@ -274,7 +276,7 @@

    Parametersrequired: False
    type: str
    default: pds
    -
    choices: ksds, esds, rrds, lds, seq, pds, pdse, library, basic, large, member, hfs, zfs
    +
    choices: ksds, esds, rrds, lds, seq, pds, pdse, library, basic, large, member, hfs, zfs, gdg
    space_primary

    The amount of primary space to allocate for the dataset.

    @@ -375,6 +377,55 @@

    Parameterstype: int

    +
    empty

    Sets the 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 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 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 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.

    +

    limit is required when type=gdg.

    +
    +
    required: False
    +
    type: int
    +
    +
    +
    purge

    Sets the purge attribute for Generation Data Groups.

    +

    Specifies whether to override expiration dates when a generation data set (GDS) is rolled off and the scratch option is set.

    +
    +
    required: False
    +
    type: bool
    +
    +
    +
    scratch

    Sets the 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, volumes specifies the name of the volume(s) where the data set is located.

    If creating a data set, volumes specifies the volume(s) where the data set should be created.

    If volumes is provided when state=present, and the data set is not found in the catalog, zos_data_set will check the volume table of contents to see if the data set exists. If the data set does exist, it will be cataloged.

    @@ -405,7 +456,8 @@

    Parametersforce

    Specifies that the data set can be shared with others during a member delete operation which results in the data set you are updating to be simultaneously updated by others.

    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 force=True option enables sharing of data sets through the disposition DISP=SHR.

    -

    The force=True only applies to data set members when state=absent and type=member.

    +

    The force=True only applies to data set members when state=absent and type=member and when removing a GDG base with active generations.

    +

    If force=True, type=gdg and state=absent it will force remove a GDG base with active generations.

    type: str
    default: pds
    -
    choices: ksds, esds, rrds, lds, seq, pds, pdse, library, basic, large, member, hfs, zfs
    +
    choices: ksds, esds, rrds, lds, seq, pds, pdse, library, basic, large, member, hfs, zfs, gdg
    space_primary

    The amount of primary space to allocate for the dataset.

    @@ -558,6 +610,55 @@

    Parameterstype: int

    +
    empty

    Sets the 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 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 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 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.

    +

    limit is required when type=gdg.

    +
    +
    required: False
    +
    type: int
    +
    +
    +
    purge

    Sets the purge attribute for Generation Data Groups.

    +

    Specifies whether to override expiration dates when a generation data set (GDS) is rolled off and the scratch option is set.

    +
    +
    required: False
    +
    type: bool
    +
    +
    +
    scratch

    Sets the 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, volumes specifies the name of the volume(s) where the data set is located.

    If creating a data set, volumes specifies the volume(s) where the data set should be created.

    If volumes is provided when state=present, and the data set is not found in the catalog, zos_data_set will check the volume table of contents to see if the data set exists. If the data set does exist, it will be cataloged.

    diff --git a/ibm_zos_core/docs/source/modules/zos_encode.html b/ibm_zos_core/docs/source/modules/zos_encode.html index 9919be9c..070294b8 100644 --- a/ibm_zos_core/docs/source/modules/zos_encode.html +++ b/ibm_zos_core/docs/source/modules/zos_encode.html @@ -121,6 +121,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -261,19 +262,21 @@

    Parameters

    -
    src

    The location can be a UNIX System Services (USS) file or path, PS (sequential data set), PDS, PDSE, member of a PDS or PDSE, or KSDS (VSAM data set).

    +
    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 USS path or file must be an absolute pathname.

    If src is a USS directory, all files will be encoded.

    +

    Encoding a whole generation data group (GDG) is not supported.

    required: True
    type: str
    dest

    The location where the converted characters are output.

    -

    The destination dest can be a UNIX System Services (USS) file or path, PS (sequential data set), PDS, PDSE, member of a PDS or PDSE, or KSDS (VSAM data set).

    +

    The destination dest can be a UNIX System Services (USS) file or path, PS (sequential data set), PDS, PDSE, member of a PDS or PDSE, a generation data set (GDS) or KSDS (VSAM data set).

    If the length of the PDSE member name used in dest is greater than 8 characters, the member name will be truncated when written out.

    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 dest is a data set, it must be already allocated.

    diff --git a/ibm_zos_core/docs/source/modules/zos_fetch.html b/ibm_zos_core/docs/source/modules/zos_fetch.html index c936de5f..e345d27d 100644 --- a/ibm_zos_core/docs/source/modules/zos_fetch.html +++ b/ibm_zos_core/docs/source/modules/zos_fetch.html @@ -122,6 +122,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -233,17 +234,19 @@

    Synopsis

      -
    • 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.

    • +
    • 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.

    • 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 dest will be overwritten if they are different than 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.

    Parameters

    -
    src

    Name of a UNIX System Services (USS) file, PS (sequential data set), PDS, PDSE, member of a PDS, PDSE or KSDS (VSAM data set).

    +
    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).

    USS file paths should be absolute paths.

    required: True
    @@ -321,12 +324,12 @@

    Parameterstype: 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 true. By doing so, the module would essentially ignore the stderr stream produced by sftp and continue execution.

    +
    ignore_sftp_stderr

    During data transfer through SFTP, the SFTP command directs content to stderr. By default, the module essentially ignores the stderr stream produced by SFTP and continues execution. The user is able to override this behavior by setting this parameter to false. By doing so, any content written to stderr is considered an error by Ansible and will cause the module to fail.

    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
    -
    default: False
    +
    default: True
    @@ -378,6 +381,24 @@

    Examplesfrom: IBM-037 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 diff --git a/ibm_zos_core/docs/source/modules/zos_find.html b/ibm_zos_core/docs/source/modules/zos_find.html index 36e81e5b..064ad39d 100644 --- a/ibm_zos_core/docs/source/modules/zos_find.html +++ b/ibm_zos_core/docs/source/modules/zos_find.html @@ -122,6 +122,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -307,11 +308,12 @@

    Parametersresource_type

    The type of resource to search.

    nonvsam refers to one of SEQ, LIBRARY (PDSE), PDS, LARGE, BASIC, EXTREQ, or EXTPREF.

    cluster refers to a VSAM cluster. The data and index are the data and index components of a VSAM cluster.

    +

    gdg refers to Generation Data Groups. The module searches based on the GDG base name.

    required: False
    type: str
    default: nonvsam
    -
    choices: nonvsam, cluster, data, index
    +
    choices: nonvsam, cluster, data, index, gdg
    volume

    If provided, only the data sets allocated in the specified list of volumes will be searched.

    @@ -321,6 +323,48 @@

    Parameterselements: str

    +
    empty

    A GDG attribute, only valid when resource_type=gdg.

    +

    If provided, will search for data sets with empty attribute set as provided.

    +
    +
    required: False
    +
    type: bool
    +
    +
    +
    extended

    A GDG attribute, only valid when resource_type=gdg.

    +

    If provided, will search for data sets with extended attribute set as provided.

    +
    +
    required: False
    +
    type: bool
    +
    +
    +
    fifo

    A GDG attribute, only valid when resource_type=gdg.

    +

    If provided, will search for data sets with fifo attribute set as provided.

    +
    +
    required: False
    +
    type: bool
    +
    +
    +
    limit

    A GDG attribute, only valid when resource_type=gdg.

    +

    If provided, will search for data sets with limit attribute set as provided.

    +
    +
    required: False
    +
    type: int
    +
    +
    +
    purge

    A GDG attribute, only valid when resource_type=gdg.

    +

    If provided, will search for data sets with purge attribute set as provided.

    +
    +
    required: False
    +
    type: bool
    +
    +
    +
    scratch

    A GDG attribute, only valid when resource_type=gdg.

    +

    If provided, will search for data sets with scratch attribute set as provided.

    +
    +
    required: False
    +
    type: bool
    +
    +
    diff --git a/ibm_zos_core/docs/source/modules/zos_gather_facts.html b/ibm_zos_core/docs/source/modules/zos_gather_facts.html index e061b84f..d7443a33 100644 --- a/ibm_zos_core/docs/source/modules/zos_gather_facts.html +++ b/ibm_zos_core/docs/source/modules/zos_gather_facts.html @@ -120,6 +120,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • diff --git a/ibm_zos_core/docs/source/modules/zos_job_output.html b/ibm_zos_core/docs/source/modules/zos_job_output.html index eb784421..f0fdf8eb 100644 --- a/ibm_zos_core/docs/source/modules/zos_job_output.html +++ b/ibm_zos_core/docs/source/modules/zos_job_output.html @@ -120,6 +120,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -458,7 +459,7 @@

    Return Valuestype: str

    -
    content_type

    Type of address space.

    +
    content_type

    Type of address space used by the job, can be one of the following types. - APPC for an APPC Initiator. - JGRP for a JOBGROUP. - JOB for a Batch job. - STC for a Started task. - TSU for a Time sharing user. - ? for an unknown or pending job.

    +
    content_type

    Type of address space used by the job, can be one of the following types.

    +

    APPC for an APPC Initiator.

    +

    JGRP for a JOBGROUP.

    +

    JOB for a Batch job.

    +

    STC for a Started task.

    +

    TSU for a Time sharing user.

    +

    ? for an unknown or pending job.

    +
    +
    type: str
    +
    sample: STC
    +
    +
    +
    system

    The job entry system that MVS uses to do work.

    +
    +
    type: str
    +
    sample: STL1
    +
    +
    +
    subsystem

    The job entry subsystem that MVS uses to do work.

    +
    +
    type: str
    +
    sample: STL1
    +
    +
    ret_code

    Return code output collected from job log.

    type: dict
    diff --git a/ibm_zos_core/docs/source/modules/zos_job_submit.html b/ibm_zos_core/docs/source/modules/zos_job_submit.html index 2eee8285..8942a0df 100644 --- a/ibm_zos_core/docs/source/modules/zos_job_submit.html +++ b/ibm_zos_core/docs/source/modules/zos_job_submit.html @@ -121,6 +121,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -240,18 +241,19 @@

    SynopsisParameters

    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 “USER.TEST”,”USER.JCL(TEST)”)

    -

    Or a USS file. (e.g “/u/tester/demo/sample.jcl”)

    -

    Or a LOCAL file in ansible control node. (e.g “/User/tester/ansible-playbook/sample.jcl”)

    +

    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 generation data set from a generation data group (for example, USER.TEST.GDG(-2)).

    +

    Or a USS file. (e.g /u/tester/demo/sample.jcl)

    +

    Or a LOCAL file in ansible control node. (e.g /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.

    required: True
    type: str
    location

    The JCL location. Supported choices are data_set, uss or local.

    -

    data_set can be a PDS, PDSE, or sequential data set.

    +

    data_set can be a PDS, PDSE, sequential data set, or a generation data set.

    uss means the JCL location is located in UNIX System Services (USS).

    -

    local means locally to the ansible control node.

    +

    local means locally to the Ansible control node.

    required: False
    type: str
    @@ -261,6 +263,7 @@

    Parameters
    wait_time_s

    Option wait_time_s is the total time that module zos_job_submit will wait for a submitted job to complete. The time begins when the module is executed on the managed node.

    wait_time_s is measured in seconds and must be a value greater than 0 and less than 86400.

    +

    The module can submit and forget jobs by setting wait_time_s to 0. This way the module will not try to retrieve the job details other than job id. Job details and contents can be retrieved later by using zos_job_query or zos_job_output if needed.

    required: False
    type: int
    @@ -425,6 +428,13 @@

    Parametersdefault: False

    +
    autoescape

    Whether to enable autoescape of XML/HTML elements on a template.

    +
    +
    required: False
    +
    type: bool
    +
    default: True
    +
    +
    @@ -474,6 +484,16 @@

    Examplessrc: HLQ.DATA.LLQ 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 @@ -737,6 +757,18 @@

    Return Valuessample: HELLO +
    content_type

    Type of address space used by the job, can be one of the following types.

    +

    APPC for an APPC Initiator.

    +

    JGRP for a JOBGROUP.

    +

    JOB for a Batch job.

    +

    STC for a Started task.

    +

    TSU for a Time sharing user.

    +

    ? for an unknown or pending job.

    +
    +
    type: str
    +
    sample: STC
    +
    +
    duration

    The total lapsed time the JCL ran for.

    type: int
    @@ -848,6 +880,8 @@

    Return ValuesJob status SEC or SEC ERROR indicates the job as encountered a security error.

    Job status SYS indicates a system failure.

    Job status ? indicates status can not be determined.

    +

    Job status TYPRUN=SCAN indicates that the job had the TYPRUN parameter with SCAN option.

    +

    Job status NOEXEC indicates that the job had the TYPRUN parameter with COPY option.

    Jobs where status can not be determined will result in None (NULL).

    type: str
    diff --git a/ibm_zos_core/docs/source/modules/zos_lineinfile.html b/ibm_zos_core/docs/source/modules/zos_lineinfile.html index 50705faf..cd729e77 100644 --- a/ibm_zos_core/docs/source/modules/zos_lineinfile.html +++ b/ibm_zos_core/docs/source/modules/zos_lineinfile.html @@ -121,6 +121,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -241,6 +242,7 @@

    Parameters
    src

    The location can be a UNIX System Services (USS) file, PS (sequential data set), member of a PDS or PDSE, PDS, PDSE.

    The USS file must be an absolute pathname.

    +

    Generation data set (GDS) relative name of generation already created. e.g. SOME.CREATION(-1).

    diff --git a/ibm_zos_core/docs/source/modules/zos_mount.html b/ibm_zos_core/docs/source/modules/zos_mount.html index acf564e0..2cc696f2 100644 --- a/ibm_zos_core/docs/source/modules/zos_mount.html +++ b/ibm_zos_core/docs/source/modules/zos_mount.html @@ -122,6 +122,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • diff --git a/ibm_zos_core/docs/source/modules/zos_mvs_raw.html b/ibm_zos_core/docs/source/modules/zos_mvs_raw.html index 4ebc3b35..0d48122a 100644 --- a/ibm_zos_core/docs/source/modules/zos_mvs_raw.html +++ b/ibm_zos_core/docs/source/modules/zos_mvs_raw.html @@ -122,6 +122,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -270,6 +271,13 @@

    Parametersdefault: False

    +
    max_rc

    Specifies the maximum return code allowed for the program output. If the program generates a return code higher than the specified maximum, the module will fail.

    +
    +
    required: False
    +
    type: int
    +
    default: 0
    +
    +
    dds

    The input data source.

    dds supports 6 types of sources

      @@ -300,6 +308,8 @@

      Parameters

    data_set_name

    The data set name.

    +

    A data set name can be a GDS relative name.

    +

    When using GDS relative name and it is a positive generation, disposition=new must be used.

    required: False
    type: str
    @@ -539,7 +549,7 @@

    Parameterstype

    The type of the content to be returned.

    text means return content in encoding specified by response_encoding.

    src_encoding and response_encoding are only used when type=text.

    -

    base64 means return content in binary mode.

    +

    base64 means return content as base64 encoded in binary.

    required: True
    type: str
    @@ -685,7 +695,7 @@

    Parameterstype

    The type of the content to be returned.

    text means return content in encoding specified by response_encoding.

    src_encoding and response_encoding are only used when type=text.

    -

    base64 means return content in binary mode.

    +

    base64 means return content as base64 encoded in binary.

    required: True
    type: str
    @@ -744,7 +754,7 @@

    Parameterstype

    The type of the content to be returned.

    text means return content in encoding specified by response_encoding.

    src_encoding and response_encoding are only used when type=text.

    -

    base64 means return content in binary mode.

    +

    base64 means return content as base64 encoded in binary.

    required: True
    type: str
    @@ -792,7 +802,7 @@

    Parameterstype

    The type of the content to be returned.

    text means return content in encoding specified by response_encoding.

    src_encoding and response_encoding are only used when type=text.

    -

    base64 means return content in binary mode.

    +

    base64 means return content as base64 encoded in binary.

    required: True
    type: str
    @@ -876,6 +886,8 @@

    Parameters
    data_set_name

    The data set name.

    +

    A data set name can be a GDS relative name.

    +

    When using GDS relative name and it is a positive generation, disposition=new must be used.

    required: False
    type: str
    @@ -1115,7 +1127,7 @@

    Parameterstype

    The type of the content to be returned.

    text means return content in encoding specified by response_encoding.

    src_encoding and response_encoding are only used when type=text.

    -

    base64 means return content in binary mode.

    +

    base64 means return content as base64 encoded in binary.

    @@ -1737,6 +1780,18 @@

    Return Values

    +
    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/ibm_zos_core/docs/source/modules/zos_operator.html b/ibm_zos_core/docs/source/modules/zos_operator.html index 4a2836c2..391f858d 100644 --- a/ibm_zos_core/docs/source/modules/zos_operator.html +++ b/ibm_zos_core/docs/source/modules/zos_operator.html @@ -111,6 +111,7 @@
  • Synopsis
  • Parameters
  • Examples
  • +
  • Notes
  • Return Values
  • @@ -120,6 +121,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -223,7 +225,8 @@
  • Synopsis

  • Parameters

  • Examples

  • -
  • Return Values

  • +
  • Notes

  • +
  • Return Values

  • +
    case_sensitive

    If true, the command will not be converted to uppercase before execution. Instead, the casing will be preserved just as it was written in a task.

    +
    +
    required: False
    +
    type: bool
    +
    default: False
    +
    +

    @@ -290,8 +301,15 @@

    Examples +

    Notes

    +
    +

    Note

    +

    Commands may need to use specific prefixes like $, they can be discovered by issuing the following command D OPDATA,PREFIX.

    +
    +

    -

    Return Values

    +

    Return Values

    rc

    Return code for the submitted operator command.

    diff --git a/ibm_zos_core/docs/source/modules/zos_operator_action_query.html b/ibm_zos_core/docs/source/modules/zos_operator_action_query.html index 6401d498..2f5996a9 100644 --- a/ibm_zos_core/docs/source/modules/zos_operator_action_query.html +++ b/ibm_zos_core/docs/source/modules/zos_operator_action_query.html @@ -121,6 +121,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • diff --git a/ibm_zos_core/docs/source/modules/zos_ping.html b/ibm_zos_core/docs/source/modules/zos_ping.html index aedfac69..0cbf034b 100644 --- a/ibm_zos_core/docs/source/modules/zos_ping.html +++ b/ibm_zos_core/docs/source/modules/zos_ping.html @@ -121,6 +121,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • diff --git a/ibm_zos_core/docs/source/modules/zos_script.html b/ibm_zos_core/docs/source/modules/zos_script.html index c7b3b260..147f4a81 100644 --- a/ibm_zos_core/docs/source/modules/zos_script.html +++ b/ibm_zos_core/docs/source/modules/zos_script.html @@ -122,6 +122,7 @@
  • zos_tso_command – Execute TSO commands
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -410,6 +411,13 @@

    Parametersdefault: False

    +
    autoescape

    Whether to enable autoescape of XML/HTML elements on a template.

    +
    +
    required: False
    +
    type: bool
    +
    default: True
    +
    +
    @@ -465,7 +473,7 @@

    Notesremote_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.

    -

    Execution permissions for the group assigned to the script will be added to remote scripts. The original permissions for remote scripts will be restored by the module before the task ends.

    +

    Execution permissions for the group assigned to the script will be added to remote scripts if they are missing. The original permissions for remote scripts will be restored by the module before the task ends.

    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 BPXW0003I.

    For supported character sets used to encode data, refer to the documentation.

    diff --git a/ibm_zos_core/docs/source/modules/zos_tso_command.html b/ibm_zos_core/docs/source/modules/zos_tso_command.html index 7bc8a41e..559a1f2c 100644 --- a/ibm_zos_core/docs/source/modules/zos_tso_command.html +++ b/ibm_zos_core/docs/source/modules/zos_tso_command.html @@ -120,6 +120,7 @@
  • zos_unarchive – Unarchive files and data sets in z/OS.
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • diff --git a/ibm_zos_core/docs/source/modules/zos_unarchive.html b/ibm_zos_core/docs/source/modules/zos_unarchive.html index 95f368cc..c3403db0 100644 --- a/ibm_zos_core/docs/source/modules/zos_unarchive.html +++ b/ibm_zos_core/docs/source/modules/zos_unarchive.html @@ -122,6 +122,7 @@
  • zos_volume_init – Initialize volumes or minidisks.
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • @@ -247,6 +248,7 @@

    Parameterssrc can be a USS file or MVS data set name.

    USS file paths should be absolute paths.

    MVS data sets supported types are SEQ, PDS, PDSE.

    +

    GDS relative names are supported. e.g. USER.GDG(-1).

    required: True
    type: str
    @@ -334,6 +336,7 @@

    Parameters
    include

    A list of directories, files or data set names to extract from the archive.

    +

    GDS relative names are supported. e.g. USER.GDG(-1).

    When include is set, only those files will we be extracted leaving the remaining files in the archive.

    Mutually exclusive with exclude.

    exclude

    List the directory and file or data set names that you would like to exclude from the unarchive action.

    +

    GDS relative names are supported. e.g. USER.GDG(-1).

    Mutually exclusive with include.

    required: False
    @@ -524,6 +528,13 @@

    Examples- USER.ARCHIVE.TEST1 - USER.ARCHIVE.TEST2 +# Unarchive a GDS +- name: Unarchive a terse data set and excluding data sets from unpacking. + zos_unarchive: + src: "USER.ARCHIVE(0)" + format: + name: terse + # List option - name: List content from XMIT zos_unarchive: diff --git a/ibm_zos_core/docs/source/modules/zos_volume_init.html b/ibm_zos_core/docs/source/modules/zos_volume_init.html index 713ddb4d..f2d96e41 100644 --- a/ibm_zos_core/docs/source/modules/zos_volume_init.html +++ b/ibm_zos_core/docs/source/modules/zos_volume_init.html @@ -35,7 +35,7 @@ - + @@ -121,6 +121,7 @@
  • Return Values
  • +
  • zos_zfs_resize – Resize a zfs data set.
  • Filters
  • diff --git a/ibm_zos_core/docs/source/modules/zos_zfs_resize.html b/ibm_zos_core/docs/source/modules/zos_zfs_resize.html new file mode 100644 index 00000000..b369d00f --- /dev/null +++ b/ibm_zos_core/docs/source/modules/zos_zfs_resize.html @@ -0,0 +1,536 @@ + + + + + + + + + + + zos_zfs_resize – Resize a zfs data set. — Red Hat Ansible Certified Content for IBM Z documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + +
    + + + + + +
    + +
    + + + + + + + + + + + + + + + + + + + +
    + + + + +
    +
    +
    +
    + +
    +

    zos_zfs_resize – Resize a zfs data set.

    + +
    +

    Synopsis

    +
      +
    • The module zos_zfs_resize. can resize a zFS aggregate data set.

    • +
    • The target data set must be a unique and a Fully Qualified Name (FQN) of a z/OS zFS aggregate data set.

    • +
    • The data set must be attached as read-write.

    • +
    • size must be provided.

    • +
    +
    +
    +

    Parameters

    +
    +
    target

    The Fully Qualified Name of the zFS data set that will be resized.

    +
    +
    required: True
    +
    type: str
    +
    +
    +
    size

    The desired size of the data set after the resizing is performed.

    +
    +
    required: True
    +
    type: int
    +
    +
    +
    space_type

    The unit of measurement to use when defining the size.

    +

    Valid units are k (kilobytes), m (megabytes), g (gigabytes), cyl (cylinders), and trk (tracks).

    +
    +
    required: False
    +
    type: str
    +
    default: k
    +
    choices: k, m, g, cyl, trk
    +
    +
    +
    no_auto_increase

    Option controls whether the data set size will be automatically increased when performing a shrink operation.

    +

    When set to true, during the shrinking of the zFS aggregate, if more space be needed the total size will not be increased and the module will fail.

    +
    +
    required: False
    +
    type: bool
    +
    default: False
    +
    +
    +
    verbose

    Return diagnostic messages that describe the module’s execution.

    +

    Verbose includes standard out (stdout) of the module’s execution which can be excessive, to avoid writing this to stdout, optionally you can set the trace_destination instead.

    +
    +
    required: False
    +
    type: bool
    +
    default: False
    +
    +
    +
    trace_destination

    Specify a unique USS file name or data set name for trace_destination.

    +

    If the destination trace_destination is a USS file or path, the trace_destination must be an absolute path name.

    +

    Support MVS data set type SEQ, PDS, PDS/E(MEMBER)

    +

    If the destination is an MVS data set name, the trace_destination provided must meet data set naming conventions of one or more qualifiers, each from one to eight characters long, that are delimited by periods.

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

    Examples

    +
    - name: Resize an aggregate data set to 2500 kilobytes.
    +  zos_zfs_resize:
    +    target: TEST.ZFS.DATA
    +    size: 2500
    +
    +- name: Resize an aggregate data set to 20 tracks.
    +  zos_zfs_resize:
    +    target: TEST.ZFS.DATA
    +    space_type: trk
    +    size: 20
    +
    +- name: Resize an aggregate data set to 4 megabytes.
    +  zos_zfs_resize:
    +    target: TEST.ZFS.DATA
    +    space_type: m
    +    size: 4
    +
    +- name: Resize an aggregate data set to 1000 kilobytes and set no auto increase if it's shrinking.
    +  zos_zfs_resize:
    +    target: TEST.ZFS.DATA
    +    size: 1000
    +    no_auto_increase: true
    +
    +- name: Resize an aggregate data set and get verbose output.
    +  zos_zfs_resize:
    +    target: TEST.ZFS.DATA
    +    size: 2500
    +    verbose: true
    +
    +- name: Resize an aggregate data set and get the full trace on a file.
    +  zos_zfs_resize:
    +    target: TEST.ZFS.DATA
    +    size: 2500
    +    trace_destination: /tmp/trace.txt
    +
    +- name: Resize an aggregate data set and capture the trace into a PDS member.
    +  zos_zfs_resize:
    +    target: TEST.ZFS.DATA
    +    size: 2500
    +    trace_destination: "TEMP.HELPER.STORAGE(RESIZE)"
    +
    +- name: Resize an aggregate data set and capture the trace into a file with verbose output.
    +  zos_zfs_resize:
    +    target: TEST.ZFS.DATA
    +    size: 2500
    +    verbose: true
    +    trace_destination: /tmp/trace.txt
    +
    +
    +
    +
    +

    Notes

    +
    +

    Note

    +

    If needed, allocate the zFS trace output data set as a PDSE with RECFM=VB, LRECL=133 with a primary allocation of at least 50 cylinders and a secondary allocation of 30 cylinders.

    +

    zfsadm documentation.

    +
    +
    +
    +

    Return Values

    +
    +
    cmd

    The zfsadm command executed on the remote node.

    +
    +
    returned: always
    +
    type: str
    +
    sample: zfsadm grow -aggregate SOMEUSER.VVV.ZFS -size 4096
    +
    +
    +
    target

    The Fully Qualified Name of the resized zFS data set.

    +
    +
    returned: always
    +
    type: str
    +
    sample: SOMEUSER.VVV.ZFS
    +
    +
    +
    mount_target

    The original share/mount of the data set.

    +
    +
    returned: always
    +
    type: str
    +
    sample: /tmp/zfs_agg
    +
    +
    +
    size

    The desired size from option size according to space_type. The resulting size can vary slightly, the actual space utilization is returned in new_size.

    +
    +
    returned: always
    +
    type: int
    +
    sample: 4024
    +
    +
    +
    rc

    The return code of the zfsadm command.

    +
    +
    returned: always
    +
    type: int
    +
    +
    +
    old_size

    The original data set size according to space_type before resizing was performed.

    +
    +
    returned: always
    +
    type: float
    +
    sample:
    +
    +
    +
    3096
    +
    +
    +
    +
    +
    old_free_space

    The original data sets free space according to space_type before resizing was performed.

    +
    +
    returned: always
    +
    type: float
    +
    sample:
    +
    +
    +
    2.1
    +
    +
    +
    +
    +
    new_size

    The data set size according to space_type after resizing was performed.

    +
    +
    returned: success
    +
    type: float
    +
    sample:
    +
    +
    +
    4032
    +
    +
    +
    +
    +
    new_free_space

    The data sets free space according to space_type after resizing was performed.

    +
    +
    returned: success
    +
    type: float
    +
    sample:
    +
    +
    +
    1.5
    +
    +
    +
    +
    +
    space_type

    The measurement unit of space used to report all size values.

    +
    +
    returned: always
    +
    type: str
    +
    sample: k
    +
    +
    +
    stdout

    The modules standard out (stdout) that is returned.

    +
    +
    returned: always
    +
    type: str
    +
    sample: IOEZ00173I Aggregate TEST.ZFS.DATA.USER successfully grown.
    +
    +
    +
    stderr

    The modules standard error (stderr) that is returned. it may have no return value.

    +
    +
    returned: always
    +
    type: str
    +
    sample: IOEZ00181E Could not open trace output dataset.
    +
    +
    +
    stdout_lines

    List of strings containing individual lines from standard out (stdout).

    +
    +
    returned: always
    +
    type: list
    +
    sample:
    +
    +
    +
    [
    +    "IOEZ00173I Aggregate TEST.ZFS.DATA.USER successfully grown."
    +]
    +
    +
    +
    +
    +
    stderr_lines

    List of strings containing individual lines from standard error (stderr).

    +
    +
    returned: always
    +
    type: list
    +
    sample:
    +
    +
    +
    [
    +    "IOEZ00181E Could not open trace output dataset."
    +]
    +
    +
    +
    +
    +
    verbose_output

    If verbose=true, the operation’s full traceback will show for this property.

    +
    +
    returned: always
    +
    type: str
    +
    sample: 6FB2F8 print_trace_table printing contents of table Main Trace Table…
    +
    +
    +
    +
    +
    + + +
    + +
    +
    + + +
    + +
    +

    + © Copyright IBM Corp. 2020, 2023 + +

    +
    + +
    + +
    +
    + +
    + +
    + + + + + + + + + + + + \ No newline at end of file diff --git a/ibm_zos_core/docs/source/release_notes.html b/ibm_zos_core/docs/source/release_notes.html index 6fcb2adf..92cd9cce 100644 --- a/ibm_zos_core/docs/source/release_notes.html +++ b/ibm_zos_core/docs/source/release_notes.html @@ -99,66 +99,119 @@