Quickstart

After you install the collection outlined in the installation guide, you can access the collection and the ansible-doc covered in the following topics:

ibm_zos_core

After the collection is installed, you can access the collection content for a playbook by referencing the namespace ibm and the collection’s fully qualified name ibm_zos_core. For example:

- hosts: all

tasks:
- name: Query submitted job 'HELLO'
    ibm.ibm_zos_core.zos_job_query:
    job_name: HELLO

In Ansible 2.9, the collections keyword was added to reduce the need to refer to the collection repeatedly. For example, you can use the collections keyword in your playbook:

- hosts: all
  collections:
  - ibm.ibm_zos_core

  tasks:
  - name: Query submitted job 'HELLO'
    zos_job_query:
        job_name: HELLO

z/OS Connection Plugin

Since EBCDIC encoding is used on z/OS, custom plugins are required to determine the correct transport method when targeting a z/OS system. The zos_ssh.py connection plugin is a fork of the default ssh.py plugin with the added functionality to check if a module is written in REXX.

Since REXX scripts are required be in EBCDIC encoding to run, they must be handled differently during transfer. If the string __ANSIBLE_ENCODE_EBCDIC__ is found in the first line of the module, the module is transferred to the target system using SCP. Otherwise, SFTP is used. SCP treats files as text, automatically encoding as EBCDIC at transfer time. SFTP treats files as binary, performing no encoding changes.

REXX Module Configuration:

  • Ensure a REXX modules first line is a comment containing the case insensitive keyword rexx

  • Followed by the case sensitive value __ANSIBLE_ENCODE_EBCDIC__

Example REXX module:

/* rexx  __ANSIBLE_ENCODE_EBCDIC__  */
x = 55
SAY '{"SYSTEM_VERSION":"' x '"}'
RETURN 0

ansible-doc

Modules included in this collection provide additional documentation that is similar to a UNIX, or UNIX-like operating system man page (manual page). This documentation can be accessed from the command line by using the ansible-doc command.

Here’s how to use the ansible-doc command after you install the IBM z/OS core collection: ansible-doc ibm.ibm_zos_core.zos_data_set

> ZOS_DATA_SET    (/Users/user/.ansible/collections/ansible_collections/ibm/ibm_zos_core/plugins/modules/zos_data_set.py)

        Create, delete and set attributes of data sets. When forcing data set replacement, contents will not be
        preserved.

* This module is maintained by The Ansible Community
OPTIONS (= is mandatory):

- batch
        Batch can be used to perform operations on multiple data sets in a single module call.
        Each item in the list expects the same options as zos_data_set.
        [Default: (null)]
        type: list
        version_added: 2.9

- data_class
        The data class name (required for SMS-managed data sets)
        [Default: (null)]
        type: str
        version_added: 2.9

For more information on using the ansible-doc command, refer to Ansible guide.