ansible-collections
diff --git a/‎docs/source/modules/zos_apf.rst‎
Lines changed: 342 additions & 0 deletions b/‎docs/source/modules/zos_apf.rst‎
Lines changed: 342 additions & 0 deletions
@@ -0,0 +1,342 @@
+
+:github_url: https://github.com/ansible-collections/ibm_zos_core/blob/dev/plugins/modules/zos_apf.py
+
+.. _zos_apf_module:
+
+
+zos_apf -- Add or remove libraries to Authorized Program Facility (APF)
+=======================================================================
+
+
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Synopsis
+--------
+- Adds or removes libraries to Authorized Program Facility (APF).
+- Manages APF statement persistent entries to a data set or data set member.
+- Changes APF list format to "DYNAMIC" or "STATIC".
+- Gets the current APF list entries.
+
+
+
+
+
+Parameters
+----------
+
+
+     
+batch
+  A list of dictionaries for adding or removing libraries.
+
+  This is mutually exclusive with ``library``, ``volume``, ``sms``
+
+  Can be used with ``persistent``
+
+
+  | **required**: False
+  | **type**: list
+
+
+     
+  library
+    The library name to be added or removed from the APF list.
+
+
+    | **required**: True
+    | **type**: str
+
+
+     
+  sms
+    Indicates that the library specified in the ``library`` parameter is managed by the storage management subsystem (SMS), and therefore no volume is associated with the library.
+
+    If true ``volume`` will be ignored.
+
+
+    | **required**: False
+    | **type**: bool
+
+
+     
+  volume
+    The identifier for the volume containing the library specified on the ``library`` parameter. The values must be one of the following.
+
+    1. The volume serial number
+
+    2. Six asterisks (******), indicating that the system must use the volume serial number of the current system residence (SYSRES) volume.
+
+    3. *MCAT*, indicating that the system must use the volume serial number of the volume containing the master catalog.
+
+    If ``volume`` is not specified, ``library`` has to be cataloged.
+
+
+    | **required**: False
+    | **type**: str
+
+
+
+     
+force_dynamic
+  Will force the APF list format to "DYNAMIC" before adding or removing libraries.
+
+  If the format is "STATIC", the format will be changed to "DYNAMIC".
+
+
+  | **required**: False
+  | **type**: bool
+
+
+     
+library
+  The library name to be added or removed from the APF list.
+
+
+  | **required**: False
+  | **type**: str
+
+
+     
+operation
+  Change APF list format to "DYNAMIC" ``operation=set_dynamic`` or "STATIC" ``operation=set_static``
+
+  Display APF list current format ``operation=check_format``
+
+  Display APF list entries when ``operation=list`` ``library``, ``volume`` and ``sms`` will be used as filters.
+
+  If ``operation`` is not set, add or remove operation will be ignored.
+
+
+  | **required**: False
+  | **type**: str
+  | **choices**: set_dynamic, set_static, check_format, list
+
+
+     
+persistent
+  Add/remove persistent entries to or from *data_set_name*
+
+  ``library`` will not be persisted or removed if ``persistent=None``
+
+
+  | **required**: False
+  | **type**: dict
+
+
+     
+  backup
+    Creates a backup file or backup data set for *data_set_name*, including the timestamp information to ensure that you retrieve the original APF list defined in *data_set_name*".
+
+    *backup_name* can be used to specify a backup file name if *backup=true*.
+
+    The backup file name will be return on either success or failure of module execution such that data can be retrieved.
+
+
+    | **required**: False
+    | **type**: bool
+
+
+     
+  backup_name
+    Specify the USS file name or data set name for the destination backup.
+
+    If the source *data_set_name* is a USS file or path, the backup_name name must be a file or path name, and the USS file or path must be an absolute path name.
+
+    If the source is an MVS data set, the backup_name must be an MVS data set name.
+
+    If the backup_name is not provided, the default backup_name will be used. If the source is a USS file or path, the name of the backup file will be the source file or path name appended with a timestamp. For example, ``/path/file_name.2020-04-23-08-32-29-bak.tar``.
+
+    If the source is an MVS data set, it will be a data set with a random name generated by calling the ZOAU API. The MVS backup data set recovery can be done by renaming it.
+
+
+    | **required**: False
+    | **type**: str
+
+
+     
+  data_set_name
+    The data set name used for persisting or removing a ``library`` from the APF list.
+
+
+    | **required**: True
+    | **type**: str
+
+
+     
+  marker
+    The marker line template.
+
+    ``{mark}`` will be replaced with "BEGIN" and "END".
+
+    Using a custom marker without the ``{mark}`` variable may result in the block being repeatedly inserted on subsequent playbook runs.
+
+    ``{mark}`` length may not exceed 72 characters.
+
+
+    | **required**: False
+    | **type**: str
+    | **default**: /* {mark} ANSIBLE MANAGED BLOCK <timestamp> */
+
+
+
+     
+sms
+  Indicates that the library specified in the ``library`` parameter is managed by the storage management subsystem (SMS), and therefore no volume is associated with the library.
+
+  If ``sms=True``, ``volume`` value will be ignored.
+
+
+  | **required**: False
+  | **type**: bool
+
+
+     
+state
+  Ensure that the library is added ``state=present`` or removed ``state=absent``.
+
+  The APF list format has to be "DYNAMIC".
+
+
+  | **required**: False
+  | **type**: str
+  | **default**: present
+  | **choices**: absent, present
+
+
+     
+volume
+  The identifier for the volume containing the library specified in the ``library`` parameter. The values must be one the following.
+
+  1. The volume serial number.
+
+  2. Six asterisks (******), indicating that the system must use the volume serial number of the current system residence (SYSRES) volume.
+
+  3. *MCAT*, indicating that the system must use the volume serial number of the volume containing the master catalog.
+
+  If ``volume`` is not specified, ``library`` has to be cataloged.
+
+
+  | **required**: False
+  | **type**: str
+
+
+
+
+Examples
+--------
+
+.. code-block:: yaml+jinja
+
+   
+   - name: Add a library to the APF list
+     zos_apf:
+       library: SOME.SEQUENTIAL.DATASET
+       volume: T12345
+   - name: Add a library (cataloged) to the APF list and persistence
+     zos_apf:
+       library: SOME.SEQUENTIAL.DATASET
+       force_dynamic: True
+       persistent:
+         data_set_name: SOME.PARTITIONED.DATASET(MEM)
+   - name: Remove a library from the APF list and persistence
+     zos_apf:
+       state: absent
+       library: SOME.SEQUENTIAL.DATASET
+       volume: T12345
+       persistent:
+         data_set_name: SOME.PARTITIONED.DATASET(MEM)
+   - name: Batch libraries with custom marker, persistence for the APF list
+     zos_apf:
+       persistent:
+         data_set_name: "SOME.PARTITIONED.DATASET(MEM)"
+         marker: "/* {mark} PROG001 USR0010 */"
+       batch:
+         - library: SOME.SEQ.DS1
+         - library: SOME.SEQ.DS2
+           sms: True
+         - library: SOME.SEQ.DS3
+           volume: T12345
+   - name: Print the APF list matching library pattern or volume serial number
+     zos_apf:
+       operation: list
+       library: SOME.SEQ.*
+       volume: T12345
+   - name: Set the APF list format to STATIC
+     zos_apf:
+       operation: set_static
+
+
+
+
+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 either for the playbook or playbook tasks, who can also obtain escalated privileges to execute as root or another user.
+
+   To add or delete the APF list entry for library libname, you must have UPDATE authority to the RACF® FACILITY resource class entity CSVAPF.libname, or there must be no FACILITY class profile that protects that entity.
+
+   To change the format of the APF list to dynamic, you must have UPDATE authority to the RACF FACILITY resource class profile CSVAPF.MVS.SETPROG.FORMAT.DYNAMIC, or there must be no FACILITY class profile that protects that entity.
+
+   To change the format of the APF list back to static, you must have UPDATE authority to the RACF FACILITY resource class profile CSVAPF.MVS.SETPROG.FORMAT.STATIC, or there must be no FACILITY class profile that protects that entity.
+
+
+
+
+
+
+Return Values
+-------------
+
+
+   
+                              
+       stdout
+        | The stdout from ZOAU command apfadm. Output varies based on the type of operation.
+      
+        | **returned**: always
+        | **type**: str
+      
+      
+                              
+       stderr
+        | The error messages from ZOAU command apfadm
+      
+        | **returned**: always
+        | **type**: str
+        | **sample**: BGYSC1310E ADD Error: Dataset COMMON.LINKLIB volume COMN01 is already present in APF list.
+
+            
+      
+      
+                              
+       rc
+        | The return code from ZOAU command apfadm
+      
+        | **returned**: always
+        | **type**: int
+      
+      
+                              
+       msg
+        | The module messages
+      
+        | **returned**: failure
+        | **type**: str
+        | **sample**: Parameter verification failed
+
+            
+      
+      
+                              
+       backup_name
+        | Name of the backup file or data set that was created.
+      
+        | **returned**: if backup=true, always
+        | **type**: str
+      
+