cmci_get – Query CICS and CICSPlex SM resources and definitions¶
Synopsis¶
Get information about installed and definitional CICS® and CICSPlex® SM resources from CICS regions, by initiating GET 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 CMCI REST API. For information about how to compose GET requests, see CMCI GET requests.
Parameters¶
- cmci_cert
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 cmci_key is specified.
Authentication prioritises certificate authentication if cmci_cert and cmci_key are provided, then basic authentication if cmci_user and cmci_password are provided, and then unauthenticated if none is provided.
required: Falsetype: str- cmci_host
The TCP/IP host name of CMCI connection.
required: Truetype: str- cmci_key
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 cmci_cert is specified.
Authentication prioritises certificate authentication if cmci_cert and cmci_key are provided, then basic authentication if cmci_user and cmci_password are provided, and then unauthenticated if none is provided.
required: Falsetype: str- cmci_password
The password of cmci_user to pass HTTP basic authentication.
Can also be specified using the environment variable CMCI_PASSWORD.
Required if cmci_user is specified.
Authentication prioritises certificate authentication if cmci_cert and cmci_key are provided, then basic authentication if cmci_user and cmci_password are provided, and then unauthenticated if none is provided.
required: falsetype: str- cmci_port
The port number of the CMCI connection.
required: Truetype: int- cmci_user
The user ID under which the CMCI request will run.
Can also be specified using the environment variable CMCI_USER.
Required if cmci_password is specified.
Authentication prioritises certificate authentication if cmci_cert and cmci_key are provided, then basic authentication if cmci_user and cmci_password are provided, and then unauthenticated if none is provided.
required: falsetype: str- context
If CMCI is installed in a CICSPlex® SM environment, context is the name of the CICSplex or CMAS associated with the request, for example,
PLEX1. To determine whether a CMAS can be specified as context, see the CMAS context entry in the CICSPlex SM resource table reference of a resource. For example, according to the PROGRAM resource table, CMAS context is not supported for PROGRAM.If CMCI is installed in a single region (SMSS), context is the APPLID of the CICS region associate with the request.
The value of context must contain no spaces. context is not case-sensitive.
required: Truetype: str- fail_on_nodata
Specifies whether the module should fail if no data is returned by the query. If set to true, the module will fail if no data is returned.
Default behaviour is for the module to fail if no data is returned. When set to false, the module will return OK, just with no records.
required: Falsetype: booldefault: True- insecure
When set to
true, disables SSL certificate trust chain verification when using HTTPS.required: Falsetype: bool- record_count
Identifies a subset of records in the results cache, starting either from the first record in the results cache or from the record specified by the index parameter. If not specified, all the records are returned by default.
A negative number indicates a count back from the last record; for example,
-1means the last record,-2the last record but one, and so on.The count value must be an integer; a value of zero is not permitted.
required: Falsetype: int- resources
Options that specify a target resource.
required: Falsetype: dict- complex_filter
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
andoperator, or a list of filter expressions to be composed with theoroperator.The
attribute,andandoroptions are mutually exclusive with each other.Can contain one or more filters. Multiple filters must be combined using
andororlogical operators.Filters can be nested.
When supplying the
attributeoption, you must also supply avaluefor the filter. You can also override the default operator of=with theoperatoroption.For examples, see “Examples” in ibm.ibm_zos_cics.cmci_get.
required: Falsetype: dict- and
A list of filter expressions to be combined with an
andoperation.Filter expressions are nested
complex_filterelements. Each nested filter expression can be either anattribute,andororcomplex filter expression.required: Falsetype: list- attribute
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, PROGDEF resource table reference.
required: Falsetype: str- operator
These operators are accepted:
<orLT(less than),<=orLE(less than or equal to),=orEQ(equal to),>orGT(greater than),>=orGE(greater than or equal to),==orIS(is),¬=,!=, orNE(not equal to). If not supplied whenattributeis used,EQis assumed.required: Falsetype: strchoices: <, >, <=, >=, =, ==, !=, ¬=, EQ, GT, GE, LT, LE, NE, IS- or
A list of filter expressions to be combined with an
oroperation.Filter expressions are nested
complex_filterelements. Each nested filter expression can be either anattribute,andororcomplex filter expression.required: Falsetype: list- value
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, PROGDEF resource table reference.
required: Falsetype: str
- filter
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
=operator.Filters for
stringtype attributes can use the*and+wildcard operators.*is a wildcard representing an unknown number of characters, and must appear at the end of the value.+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
andandoroperators, see thecomplex_filterparameter.For more details, see How to build a filter expression.
For examples, see ibm.ibm_zos_cics.cmci_get.
For supported attributes of different resource types, see their resource table reference, for example, PROGDEF resource table reference.
required: Falsetype: dict- get_parameters
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 PROGDEF resource table reference.
required: Falsetype: list- name
Parameter name available for the GET operation.
required: Truetype: str- value
Parameter value if any.
required: Falsetype: str
- scheme
The HTTP scheme to use when establishing a connection to the CMCI REST API.
required: falsetype: strdefault: httpschoices: http, https- scope
Specifies the name of a CICSplex, CICS region group, CICS region, or logical scope that is associated with the query.
scope is a subset of context and limits the request to particular CICS systems or resources.
scope is optional. If it’s not specified, the request is limited by the value of context alone.
The value of scope must contain no spaces. scope is not case-sensitive.
required: falsetype: str- timeout
HTTP request timeout in seconds
required: Falsetype: intdefault: 30- type
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 CMCI resource names.
required: Truetype: str
Examples¶
- name: get 2 LOCFILEs from a CICSplex
cmci_get:
cmci_host: "winmvs2c.hursley.ibm.com"
cmci_port: 10080
cmci_user: "ibmuser"
cmci_password: "123456"
context: "iyk3z0r9"
type: CICSLocalFile
record_count: 2
resource:
filter:
dsname: "CTS*"
- name: get a localfile in a CICS region
cmci_get:
cmci_host: "winmvs2c.hursley.ibm.com"
cmci_port: 10080
cmci_cert: "./sec/ansible.pem"
cmci_key: "./sec/ansible.key"
context: "iyk3z0r9"
type: "CICSLocalFile"
resources:
filter:
dsname: "XIAOPIN*"
file: "DFH*"
record_count: 1
- name: get a progdef from a CSD
cmci_get:
cmci_host: "winmvs2c.hursley.ibm.com"
cmci_port: 10080
cmci_cert: "./sec/ansible.pem"
cmci_key: "./sec/ansible.key"
context: "iyk3z0r9"
type: cicsdefinitionprogram
resources:
filter:
name: MYPROG
get_parameters:
- name: csdgroup
value: MYGRP
record_count: 1
- name: pass module even if bundle definition is not found
cmci_get:
cmci_host: "winmvs2c.hursley.ibm.com"
cmci_port: 10080
cmci_cert: "./sec/ansible.pem"
cmci_key: "./sec/ansible.key"
context: "iyk3z0r9"
type: cicsdefinitionbundle
resources:
filter:
name: MYBUNDLE
get_parameters:
- name: csdgroup
value: MYGRP
record_count: 1
fail_on_nodata: "false"
- name: Using complex_filter to combine filter expressions and change operators
cmci_get:
cmci_host: "winmvs2c.hursley.ibm.com"
cmci_port: 10080
cmci_cert: "./sec/ansible.pem"
cmci_key: "./sec/ansible.key"
context: "iyk3z0r9"
type: "CICSRegion"
resources:
complex_filter:
or:
[
{ attribute: "currtasks", value: "10", operator: "<" },
{ attribute: "currtasks", value: "100", operator: ">" },
]
record_count: 1
Return Values¶
- changed
- failed
- connect_version
- cpsm_reason
- cpsm_reason_code
- cpsm_response
- cpsm_response_code
- http_status
- http_status_code
- record_count
- records
- request
- body
- method
- url
- feedback
- action
- attribute1
- attribute2
- attribute3
- attribute4
- attribute5
- attribute6
- eibfn
- eibfn_alt
- errorcode
- eyu_cicsname
- keydata
- resp
- resp2
- resp_alt
- installerror
- eibfn
- eyu_cicsname
- cresp1
- cresp2
- errorcode
- ressname
- resver
- inconsistentscope
- eibfn
- eyu_cicsname
- erroroperation
- errorcode
- targetassignment
- targetdescription
- relatedassignment
- relateddescription
- relatedscope
- inconsistentset
- candidatename
- candidateversion
- candidategroup
- candidateassignment
- candidatedescription
- candidateusage
- candidatesystemgroup
- candidatetype
- candidateoverride
- eyu_cicsname
- erroroperation
- existingname
- existingversion
- existinggroup
- existingassignment
- existingdescription
- existingusage
- existingsystemgroup
- existingtype
- existingoverride