stewartfrancis.ibm_zos_cics.cmci_update (1.0.3) — module

Install collection

Install with ansible-galaxy collection install stewartfrancis.ibm_zos_cics:==1.0.3

Add to requirements.yml

  collections:
    - name: stewartfrancis.ibm_zos_cics
      version: 1.0.3

Description

Make changes to CICS® and CICSPlex® SM resources in CICS regions, by initiating PUT requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see L(CMCI REST API, https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-system-programming/cmci/clientapi_overview.html). For information about how to compose PUT requests, see L(CMCI PUT requests,https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-system-programming/cmci/clientapi_put.html).

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: update a bundle definition in a CICS region
  cmci_update:
    cmci_host: 'winmvs2c.hursley.ibm.com'
    cmci_port: '10080'
    context: 'iyk3z0r9'
    type: 'CICSDefinitionBundle'
    attributes:
      description: 'New description'
    update_parameters:
      - name: csd
    resource:
      filter:
        name: 'PONGALT'
      get_parameters:
        - name: csdgroup
          value: JVMGRP

Inputs

    
type:
    description:
    - The CMCI external resource name that maps to the target CICS or CICSPlex SM resource
      type. For a list of CMCI external resource names, see L(CMCI resource names,https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-system-programming/cmci/clientapi_resources.html).
    required: true
    type: str

scope:
    description:
    - Specifies the name of a CICSplex, CICS region group, CICS region, or logical scope
      that is associated with the query.
    - I(scope) is a subset of I(context) and limits the request to particular CICS systems
      or resources.
    - I(scope) is optional. If it's not specified, the request is limited by the value
      of I(context) alone.
    - The value of I(scope) must contain no spaces. I(scope) is not case-sensitive.
    type: str

scheme:
    choices:
    - http
    - https
    default: https
    description: The HTTP scheme to use when establishing a connection to the CMCI REST
      API.
    type: str

context:
    description:
    - "If CMCI is installed in a CICSPlex\xAE SM environment, I(context) is the name of\
      \ the CICSplex or CMAS associated with the request, for example, C(PLEX1). To determine\
      \ whether a CMAS can be specified as I(context), see the B(CMAS context) entry in\
      \ the CICSPlex SM resource table reference of a resource. For example, according\
      \ to the L(PROGRAM resource table,https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGRAMtab.html),\
      \ CMAS context is not supported for PROGRAM."
    - If CMCI is installed in a single region (SMSS), I(context) is the APPLID of the
      CICS region associate with the request.
    - The value of I(context) must contain no spaces. I(context) is not case-sensitive.
    required: true
    type: str

cmci_key:
    description:
    - Location of the PEM-formatted file storing your private key to be used for HTTPS
      client authentication.
    - Can also be specified using the environment variable CMCI_KEY.
    - Required if I(cmci_cert) is specified.
    - Authentication prioritises certificate authentication if I(cmci_cert) and I(cmci_key)
      are provided, then basic authentication if I(cmci_user) and (cmci_password) are
      provided, and then unauthenticated if none is provided.
    required: false
    type: str

insecure:
    default: false
    description: When set to C(true), disables SSL certificate trust chain verification
      when using HTTPS.
    required: false
    type: bool

cmci_cert:
    description:
    - Location of the PEM-formatted certificate chain file to be used for HTTPS client
      authentication.
    - Can also be specified using the environment variable CMCI_CERT.
    - Required if I(cmci_key) is specified.
    - Authentication prioritises certificate authentication if I(cmci_cert) and I(cmci_key)
      are provided, then basic authentication if I(cmci_user) and (cmci_password) are
      provided, and then unauthenticated if none is provided.
    required: false
    type: str

cmci_host:
    description:
    - The TCP/IP host name of CMCI connection.
    required: true
    type: str

cmci_port:
    description:
    - The port number of the CMCI connection.
    required: true
    type: int

cmci_user:
    description:
    - The user ID under which the CMCI request will run.
    - Can also be specified using the environment variable CMCI_USER.
    - Required if I(cmci_password) is specified.
    - Authentication prioritises certificate authentication if I(cmci_cert) and I(cmci_key)
      are provided, then basic authentication if I(cmci_user) and (cmci_password) are
      provided, and then unauthenticated if none is provided.
    type: str

resources:
    description:
    - Options that specify a target resource.
    required: false
    suboptions:
      complex_filter:
        description:
        - A dictionary representing a complex filter expression. Complex filters are composed
          of filter expressions, represented as dictionaries. Each dictionary can specify
          either an attribute expression, a list of filter expressions to be composed
          with the C(and) operator, or a list of filter expressions to be composed with
          the C(or) operator.
        - The C(attribute), C(and) and C(or) options are mutually exclusive with each
          other.
        - Can contain one or more filters. Multiple filters must be combined using C(and)
          or C(or) logical operators.
        - Filters can be nested.
        - When supplying the C(attribute) option, you must also supply a C(value) for
          the filter. You can also override the default operator of C(=) with the C(operator)
          option.
        - For examples, see "Examples" in M(cmci_get).
        required: false
        suboptions:
          and:
            description:
            - A list of filter expressions to be combined with an C(and) operation.
            - Filter expressions are nested C(complex_filter) elements. Each nested filter
              expression can be either an C(attribute), C(and) or C(or) complex filter
              expression.
            elements: dict
            required: false
            type: list
          attribute:
            description:
            - The name of a resource table attribute on which to filter.
            - For supported attributes of different resource types, see their resource
              table reference, for example, L(PROGDEF resource table reference, https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGDEFtab.html).
            required: false
            type: str
          operator:
            choices:
            - <
            - '>'
            - <=
            - '>='
            - '='
            - ==
            - '!='
            - "\xAC="
            - EQ
            - GT
            - GE
            - LT
            - LE
            - NE
            - IS
            description: "These operators are accepted: C(<) or C(LT) (less than), C(<=)\
              \ or C(LE) (less than or equal to), C(=) or C(EQ) (equal to), C(>) or C(GT)\
              \ (greater than), C(>=) or C(GE) (greater than or equal to), C(==) or C(IS)\
              \ (is), C(\xAC=), C(!=), or C(NE) (not equal to). If not supplied when C(attribute)\
              \ is used, C(EQ) is assumed.\n"
            required: false
            type: str
          or:
            description:
            - A list of filter expressions to be combined with an C(or) operation.
            - Filter expressions are nested C(complex_filter) elements. Each nested filter
              expression can be either an C(attribute), C(and) or C(or) complex filter
              expression.
            elements: dict
            required: false
            type: list
          value:
            description:
            - The value by which you are to filter the resource attributes.
            - The value must be a valid one for the resource table attribute as documented
              in the resource table reference, for example, L(PROGDEF resource table reference,https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGDEFtab.html).
            required: false
            type: str
        type: dict
      filter:
        description:
        - A dictionary with attribute names as keys, and target values, to be used as
          criteria to filter the set of resources returned from CICSPlex SM.
        - Filters implicitly use the C(=) operator.
        - Filters for C(string) type attributes can use the C(*) and C(+) wildcard operators.
        - C(*) is a wildcard representing an unknown number of characters, and must appear
          at the end of the value.
        - C(+) is a wildcard representing a single character, and can appear in any place
          in the value, potentially multiple times.
        - To use more complicated filter expressions, including a range of different filter
          operators, and the ability to compose filters with C(and) and C(or) operators,
          see the C(complex_filter) parameter.
        - For more details, see L(How to build a filter expression,https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/system-programming/cpsm/eyup1a0.html).
        - For examples, see M(cmci_get).
        - For supported attributes of different resource types, see their resource table
          reference, for example, L(PROGDEF resource table reference,https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGDEFtab.html).
        required: false
        type: dict
      get_parameters:
        description: 'A list of one or more parameters with optional values used to identify
          the resources for this request. Eligible parameters for identifying the target
          resources can be found in the resource table reference for the target resource
          type, as valid parameters for the GET operation in the "Valid CPSM operations"
          table. For example, the valid parameters for identifying a PROGDEF resource
          are CICSSYS, CSDGROUP and RESGROUP, as found in the L(PROGDEF resource table
          reference,https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGDEFtab.html).

          '
        elements: dict
        required: false
        suboptions:
          name:
            description: Parameter name available for the GET operation.
            required: true
            type: str
          value:
            description: Parameter value if any.
            required: false
            type: str
        type: list
    type: dict

attributes:
    description:
    - "The resource attributes to be created or updated. Available attributes can be found\
      \ in the CICSPlex\xAE SM resource table reference for the target resource type,\
      \ for example, L(PROGDEF resource table reference,https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGDEFtab.html)."
    required: false
    type: dict

cmci_password:
    description:
    - The password of I(cmci_user) to pass HTTP basic authentication.
    - Can also be specified using the environment variable CMCI_PASSWORD.
    - Required if I(cmci_user) is specified.
    - Authentication prioritises certificate authentication if I(cmci_cert) and I(cmci_key)
      are provided, then basic authentication if I(cmci_user) and (cmci_password) are
      provided, and then unauthenticated if none is provided.
    type: str

update_parameters:
    description: 'A list of one or more parameters that control the I(update) operation.
      Eligible parameters for the UPDATE operation can be found in the resource table
      reference for the target resource type, as listed in the UPDATE operation section
      of the "Valid CPSM operations" table. For example, the only valid parameter for
      a PROGDEF UPDATE operation is CSD, as found in the L(PROGDEF resource table reference,https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGDEFtab.html).

      '
    elements: dict
    required: false
    suboptions:
      name:
        description: Parameter name for the UPDATE operation.
        required: true
        type: str
      value:
        description: Parameter value if any. Can be omitted if the parameter requires
          no value to be supplied, as shown in the resource table reference. For example,
          the CSD parameter for the PROGDEF UPDATE operation doesn't require a value.
        required: false
        type: str
    type: list

Outputs

changed:
  description: True if the state was changed, otherwise False.
  returned: always
  type: bool
connect_version:
  description: Version of the CMCI REST API.
  returned: success
  type: str
cpsm_reason:
  description:
  - The character value of the REASON code returned by each CICSPlex SM API command.
    For a list of REASON character values, see https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-system-programming/commands-cpsm/eyup2ky.html.
  returned: success
  type: str
cpsm_reason_code:
  description:
  - The numeric value of the REASON code returned by each CICSPlex SM API command.
    For a list of REASON numeric values, see https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-system-programming/commands-cpsm/eyup2kw.html.
  returned: success
  type: int
cpsm_response:
  description:
  - The character value of the RESPONSE code returned by each CICSPlex SM API command.
    For a list of RESPONSE character values, see https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-system-programming/commands-cpsm/eyup2kx.html.
  returned: success
  type: str
cpsm_response_code:
  description:
  - The numeric value of the RESPONSE code returned by each CICSPlex SM API command.
    For a list of RESPONSE numeric values, see https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-system-programming/commands-cpsm/eyup2kv.html.
  returned: success
  type: str
failed:
  description: True if the query job failed, otherwise False.
  returned: always
  type: bool
http_status:
  description:
  - The message associated with HTTP status code that is returned by CMCI.
  returned: success
  type: str
http_status_code:
  description:
  - The HTTP status code returned by CMCI.
  returned: success
  type: int
record_count:
  description:
  - The number of records returned.
  returned: success
  type: int
records:
  description:
  - A list of the returned records.
  elements: dict
  returned: success
  sample:
  - _keydata: C1D5E2C9E3C5E2E3
    aloadtime: '00:00:00.000000'
    apist: CICSAPI
    application: ''
    applmajorver: '-1'
    applmicrover: '-1'
    applminorver: '-1'
    basdefinever: '0'
    cedfstatus: CEDF
    changeagent: CSDAPI
    changeagrel: '0730'
    changetime: '2020-12-15T02:34:31.000000+00:00'
    changeusrid: YQCHEN
    coboltype: NOTAPPLIC
    concurrency: QUASIRENT
    copy: NOTREQUIRED
    currentloc: NOCOPY
    datalocation: ANY
    definesource: ANSITEST
    definetime: '2020-12-15T02:34:29.000000+00:00'
    dynamstatus: NOTDYNAMIC
    entrypoint: FF000000
    execkey: USEREXECKEY
    executionset: FULLAPI
    eyu_cicsname: IYCWEMW2
    eyu_cicsrel: E730
    eyu_reserved: '0'
    fetchcnt: '0'
    fetchtime: '00:00:00.000000'
    holdstatus: NOTAPPLIC
    installagent: CSDAPI
    installtime: '2020-12-15T02:34:33.000000+00:00'
    installusrid: YQCHEN
    jvmclass: ''
    jvmserver: ''
    language: NOTDEFINED
    length: '0'
    library: ''
    librarydsn: ''
    loadpoint: FF000000
    lpastat: NOTAPPLIC
    newcopycnt: '0'
    operation: ''
    pgrjusecount: '0'
    platform: ''
    program: ANSITEST
    progtype: PROGRAM
    remotename: ''
    remotesystem: ''
    removecnt: '0'
    rescount: '0'
    residency: NONRESIDENT
    rloading: '0.000'
    rplid: '0'
    rremoval: '0.000'
    runtime: UNKNOWN
    ruse: '0.000'
    sharestatus: PRIVATE
    status: DISABLED
    transid: ''
    useagelstat: '0'
    usecount: '0'
    usefetch: '0.000'
  type: list
request:
  contains:
    body:
      description: The XML body sent with the request, if any.
      returned: success
      type: str
    method:
      description: The HTTP method used for the request.
      returned: success
      type: str
    url:
      description: The URL used for the request.
      returned: success
      type: str
  description: Information about the request that was made to CMCI.
  returned: success
  type: dict