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

Synopsis
Parameters
Examples
Notes
Return Values

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 ¶

library

The library name to be added or removed from the APF list.

required: False

type: str

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

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
default: False

volume

The identifier for the volume containing the library specified in the library parameter. The values must be one the following.

The volume serial number.
Six asterisks (**), indicating that the system must use the volume serial number of the current system residence (SYSRES) volume.
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

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
default: False

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

tmp_hlq

Override the default high level qualifier (HLQ) for temporary and backup datasets.

The default HLQ is the Ansible user used to execute the module and if that is not available, then the value TMPHLQ is used.

required: False

type: str

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

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.

The timestamp (<timestamp>) used in the default marker follows the ‘+%Y%m%d-%H%M%S’ date format

required: False
type: str
default: /* {mark} ANSIBLE MANAGED BLOCK <timestamp> */

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
default: False

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

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
elements: dict

library

The library name to be added or removed from the APF list.

required: True

type: str

volume

The identifier for the volume containing the library specified on the library parameter. The values must be one of the following.

The volume serial number
Six asterisks (**), indicating that the system must use the volume serial number of the current system residence (SYSRES) volume.
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

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
default: False

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.

state> stdout of the executed operator command (opercmd), “SETPROG” from ZOAU command apfadm

operation> stdout of operation options list> Returns a list of dictionaries of APF list entries [{‘vol’: ‘PP0L6P’, ‘ds’: ‘DFH.V5R3M0.CICS.SDFHAUTH’}, {‘vol’: ‘PP0L6P’, ‘ds’: ‘DFH.V5R3M0.CICS.SDFJAUTH’}, …] set_dynamic> Set to DYNAMIC set_static> Set to STATIC check_format> DYNAMIC or STATIC

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

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

Synopsis¶

Parameters¶

Examples¶

Notes¶

Return Values¶

Synopsis ¶

Parameters ¶

Examples ¶

Notes ¶

Return Values ¶