/ home / stewartfrancis / stewartfrancis.ibm_zos_cics / 1.0.3 / module / cmci_create

stewartfrancis.ibm_zos_cics.cmci_create (1.0.3) — module

Create CICS and CICSPlex SM definitions

Authors: Stewart Francis (@stewartfrancis), Tom Latham (@Tom-Latham), Sophie Green (@sophiegreen), Ya Qing Chen (@vera-chan)

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

Create definitional CICS® or CICSPlex® SM resources in CSD and BAS repositories, by initiating POST 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 POST requests, see L(CMCI POST requests,https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-system-programming/cmci/clientapi_post.html).

Usage examples

Scanned by Steampunk Spotter

- name: define a BUNDLE in a CSD
  cmci_create:
    cmci_host: 'winmvs2c.hursley.ibm.com'
    cmci_port: 10080
    context: 'iyk3z0r9'
    type: 'CICSDefinitionBundle'
    attributes:
      name: PONGALT
      bundledir: /u/ibmuser/bundle/pong/pongbundle_1.0.0
      csdgroup: JVMGRP
    create_parameters:
      - name: 'csd'

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

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

create_parameters:
description: 'A list of one or more parameters that control the I(create) operation.
Eligible parameters for the CREATE operation can be found in the resource table
reference for the target resource type, as listed in the CREATE operation section
of the "Valid CPSM operations" table. For example, the valid parameters for a PROGDEF
CREATE operation are CSD 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 for the CREATE 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 CREATE 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