zos_apf – Add or remove libraries to Authorized Program Facility (APF)

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

- 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