# Copyright (c) IBM Corporation 2021


DOCUMENTATION = r"""
role: zmf_cpm_remove_software_instance
short_description: Role removes a z/OS software instance
description:
    - >
      The B(IBM z/OSMF collection) provides an Ansible role, referred to as
      B(zmf_cpm_remove_software_instance), to remove a deprovisioned instance
      of z/OS middleware such as IBM Customer Information Control System
      (CICS®), IBM Db2®, IBM Information Management System (IMS™), IBM MQ, and
      IBM WebSphere Application Server or any other software service from
      B(IBM Cloud Provisioning and Management (CP&M)) registry.
author:
    - Hiren Shah (@shreeji818)
options:
    zmf_host:
        description:
            - >
              Hostname of the z/OSMF server, specified in the inventory file
              or vars file.
        required: True
        type: str
    zmf_port:
        description:
            - >
              Port number of the z/OSMF server.
              If z/OSMF is not using the default port, you need to specify
              value for this parameter in the inventory file or vars file.
        required: False
        type: str
        default: 443
    zmf_user:
        description:
            - User name to be used for authenticating with the z/OSMF server.
            - >
              This variable can be specified in the inventory file or vars
              file, or prompted when playbook is run.
        required: True
        type: str
    zmf_password:
        description:
            - Password to be used for authenticating with z/OSMF server.
            - >
              This variable can be specified in the inventory file or vars
              file, or prompted when playbook is run.
        required: True
        type: str
    instance_info_json_path:
        description:
            - >
              Directory path for the JSON file that holds provisioned instance
              information.
            - >
              Specify the file name that was generated when the
              M(zmf_cpm_provision_software_service) role was performed.
        required: True
        type: str
notes:
    - >
      The given example assumes that you have an inventory file
      I(inventory.yml) and host vars I(sampleHost.yml) with appropriate values
      to identify the target z/OSMF server end point.
"""

EXAMPLES = r"""
- name: Remove deprovisioned instance of z/OS Middleware
  hosts: sampleHost
  gather_facts: no
  collections: 
    - ibm.ibm_zosmf
  tasks: 
    - include_role:
        name: zmf_cpm_remove_software_instance
      vars:
        instance_info_json_path: "<full-instance-json-file-path>"
"""

# Roles don't return anything.
# But RETURN block must be defined for doc extraction tooling to avoid error.
# The content in RETURN block will not be display in doc-site.
RETURN = r"""
changed:
    description: Indicates if any change is made during the role operation.
    returned: always
    type: bool
"""