List
Returns selected fields from one or more resource definitions, CICS® Configuration Manager repository objects, or CICS Configuration Manager journal objects.
You can use the List command in your client to display object selection lists (for example, of resource definitions) and to generate reports.
By default, the List command returns a subset of the fields for an object, plus any fields named by <RestrictionCriteria>. For resource definitions, the default subset consists of:
- TYPE
- GROUP
- CHANGETIME
- CHANGEAGENT
- CHANGEUSRID
- CHANGEAGREL
- DEFVER (this field is relevant only to context-based resource definitions; for CSD-based resource definitions, the List command response returns this field with value 0)
- NAME
For the default subset returned for other object types, see API object types.
To include additional fields in the response, add the fields to the <RestrictionCriteria>, even if you do not want to restrict their values. To include a field in the output data without restricting its values, specify = (or EQ) as the restriction operator, and * (an asterisk, representing any value) as the restriction value:
<RestrictionField> field_name </RestrictionField>
<RestrictionOperator> eq </RestrictionOperator>
<RestrictionValue> * </RestrictionValue>
To return the complete set of fields (that is, all attributes) for resource definitions, specify the <AllAttributes>YES</AllAttributes> process parameter. This process parameter applies only when listing resource definitions. You must specify the value YES in uppercase.
Request format
<CCV530>
<List>
<LocationCriteria>
<LocationName> location_name </LocationName>
<LocationType> CConfig | Context | CSD | Repository | Journal </LocationType> 1
</LocationCriteria>
<JnlCriteria> 2
Journal record criteria
</JnlCriteria>
<ObjectCriteria> 3
<ObjType> object_type | All | * </ObjType> 4
Criteria for this object type
</ObjectCriteria>
<RestrictionCriteria> 5
<RestrictionCount> element_count </RestrictionCount>
<RestrictionElement>
<ListCount> element_count </ListCount>
<ListElement>
<RestrictionField> restriction_field_name </RestrictionField>
<RestrictionOperator> restriction_operator </RestrictionOperator>
<RestrictionValue> restriction_field_value </RestrictionValue>
</ListElement>
More list elements…
</RestrictionElement>
More restriction elements…
</RestrictionCriteria>
<ProcessParms> 6
<HashingScope> hashing_scope </HashingScope>
<ObjectHistory> No | Yes </ObjectHistory>
<CPIDFormula> APPROVE? | MIGRATE? </CPIDFormula>
<Counts> None | All </Counts>
<FilterDate> yyyy/mm/dd.hh:mm </FilterDate>
<Limit> maximum_objects_to_return </Counts>
</ProcessParms>
</List>
</CCV530>
Journal record criteria:
<JnlRecType> journal_record_type </JnlRecType>
<JnlCCVRel> CCV_release </JnlCCVRel>
<JnlCICSRel> CICS_release </JnlCICSRel>
<JnlCPID> change_package_ID </JnlCPID>
<JnlScheme> migration_scheme </JnlScheme>
<JnlUserID> user_ID </JnlUserID>
<JnlObjGroup> resource_group </JnlObjGroup>
<JnlObjName> resource_name </JnlName>
<JnlObjType> resource_type </JnlObjType>
<JnlCSD> CSD_DSN </JnlCSD>
<JnlContext> context </JnlContext>
The following alternative "search within results" request format enables you to send a list of resource definition keys (name, type, and group) to the server along with restriction criteria. The server returns results that match the restriction criteria within the list of resource definitions that you sent. This request format is characterized by the presence of the elements <ListCount> and <ListElement> inside <ObjectCriteria>.
Alternative request format, to search within results:
<CCV530>
<List>
<LocationCriteria>
<LocationName> location_name </LocationName>
<LocationType> CConfig | Context | CSD </LocationType>
</LocationCriteria>
<ObjectCriteria>
<ListCount> element_count </ListCount>
<ListElement>
<ObjName> resource_name </ObjName>
<ObjGroup> resource_group </ObjGroup>
<ObjType> resource_type </ObjType>
</ListElement>
More list elements…
</ObjectCriteria>
<RestrictionCriteria>
<RestrictionCount> element_count </RestrictionCount>
<RestrictionElement>
<ListCount> element_count </ListCount>
<ListElement>
<RestrictionField> restriction_field_name </RestrictionField> 5
<RestrictionOperator> restriction_operator </RestrictionOperator>
<RestrictionValue> restriction_field_value </RestrictionValue>
</ListElement>
More list elements…
</RestrictionElement>
More restriction elements…
</RestrictionCriteria>
</List>
</CCV530>
- 1
- If the location type is CConfig, Context, or CSD, then object_type can be All or * to indicate all resource types.
- 2
- If the location type is Journal, then <JnlCriteria> is optional. Otherwise, <JnlCriteria> is ignored.
- 3
- If the location type is Journal and you specify <JnlCriteria>,
then <ObjectCriteria> is optional. Otherwise, <ObjectCriteria> is
required.
If you specify both <JnlCriteria> and <ObjectCriteria>, then <ObjectCriteria> describes a resource definition embedded in a BAImage (before/after image) journal record.
- 4
- To include all object types in the list, specify object_type as All or *. This limits the object criteria and the restriction criteria that you can specify to the fields that are common to all object types for the location type. For details, see The All object type.
- 5
- Restriction criteria are optional: they further limit the list within the object
criteria. Fields that you name in the restriction criteria are included in the response
<ObjectData>.
When processing a List command request, CICS Configuration Manager combines multiple <RestrictionElement> elements using a logical OR operator. Within a <RestrictionElement>, CICS Configuration Manager combines multiple <ListElement> using a logical AND operator.
When listing BAImage journal records, you must prefix the field names of the embedded resource definitions with B_ for "before" or A_ for "after". For example, to limit the list to journal records whose "before" resource definition was changed after 26 June 2004, specify:
<RestrictionField> B_ChangeTime </RestrictionField> <RestrictionOperator> gt </RestrictionOperator> <RestrictionValue> 2004/06/26 </RestrictionValue>
- 6
- You can customize the List command response using process parameters
(all of these elements are optional):
- <AllAttributes> specifies whether
to return all attributes of the requested resource definitions or
only a subset. Acceptable values are:
- NO
- Return the default subset of attributes, plus any attributes named by <RestrictionCriteria>.
- YES
- Return all attributes. This produces results similar to an Inquire command, but for multiple resource definitions: while the Inquire command returns all attributes from a single resource definition, the List command with this process parameter returns all attributes from one or more resource definitions.
You must specify these values in uppercase.
<AllAttributes> is relevant only when listing resource definitions.
- <HashingScope> determines
whether or not the List command response contains a <HashingValue> element
with a checksum for each selected object, and which fields it uses
to calculate the checksum:
- None
- Default. Do not calculate checksums, and do not include <HashingValue> elements in the List command response.
- Full
- Calculate the checksum using all object fields. This checksum will be identical to the integrity token calculated by the Inquire and Update commands.
- Partial
- Calculate the checksum using a subset of the object fields: exclude fields that typically differ between definitions of the same type. This includes the object name, group, description, and other fields depending on the object type. For details, see Comparing a list panel of objects with a checksum column.
- Group
- Only for use with when the object criteria specify the object type ResDesc: calculate the checksum using the names of the groups/ResDescs in the lists/ResDescs.
- Name
- Only for use when the object criteria specify the object type ResGroup: calculate the checksum using the names of the resource definitions in the groups/ResDescs.
- List
- Only for use when the object criteria specify a resource definition object type (not ResGroup or
ResDesc), *, or All (to select all resource types): calculate the checksum using the specifically
requested attributes for each object type.
To specify the attributes to calculate the checksum for each object type, you must include elements of the following format in <ProcessParms>:
<object_type> <FieldCount> element_count </FieldCount> <FieldName> attribute_name </FieldName> More field names… </object_type> More object type elements…
For example, if the object criteria specify an object type of TranDef:
<ProcessParms> <HashingScope>List</HashingScope> <TranDef> <FieldCount>2</FieldCount> <FieldName>Description</FieldName> <FieldName>Program</FieldName> </TranDef> ⋮ </ProcessParms>
(If the object criteria specify * or All as the object type, then you can specify an <object_type> element for each resource definition object type.)
- Critical
- Calculate the checksum from all attributes excluding those that are not critical to the operation of the resource.
For details on each checksum type, see Comparing a list panel of objects with a checksum column.
- <ObjectHistory> specifies whether to return
all versions of an object from the repository, or only the current
version. Acceptable values are:
- No
- Default. Return only the current (latest) version of the object.
- Yes
- Return all versions of the object.
<ObjectHistory> is relevant only if the location type is Repository. Otherwise, <ObjectHistory> is ignored. If the location type is Journal, then the List command always returns all versions of the selected object.
- <CPIDFormula> is relevant only when listing
change packages (object_type is ChgPkg).
Acceptable values are:
- APPROVE?
- Limits the list to change packages that are ready, and that require approval for a particular migration scheme.
- MIGRATE?
- Limits the list to change packages that require migration. These are change packages that are ready and approved (if necessary), and either have not yet been migrated or have been backed out from a previous migration.
- <Counts>All</Counts> requests the server to include various count values in the response. For details, see the response format.
- <FilterDate> limits the objects returned by List to those changed on or before the specified date and time. You can use this instead of, or in addition to, restriction criteria for change time.
- <Limit> sets an upper limit to the number of resource definitions returned by List. If the number of resource definitions that match the specifications of the List command exceeds this limit, then the List command returns an error, with no resource definitions. This avoids the problems associated with returning a subset of objects that match the specifications: for example, depending on how a client sorts the results of the List command, omissions might not be apparent to the end user.
- <ReportSet> limits the resource definitions
returned by List according to one of the following options. <ReportSet> is
only valid if the location type is CConfig, Context, or
CSD.
- All
- Returns all objects (this is the default).
- DuplicateNames
- Returns resource definitions that have the same name and resource type as one or more other resource definitions.
- UniqueNames
- Returns resource definitions that have a unique combination of name and resource type in the specified location.
- DuplicateChecksums
- Returns resource definitions that have the same checksum value as one or more other resource definitions in the specified location.
- UniqueChecksums
- Returns resource definitions that have a unique checksum value in the specified location, according to the type of checksum specified by <HashingScope>.
- CPSMOrphans
- Returns resources definitions in the selected CICSPlex SM context that are not related to any ResGroups. Only valid if the location criteria specifies a context or a CICS configuration that refers to a context. This option does not support ResGroup or ResDesc resource types; however, you can specify object type All (or *) to return orphans of all other resource types.
- CPSMShared
- Returns resources definitions in the selected CICSPlex SM context where the same version of a resource definition belongs to multiple ResGroups. Only valid if the location criteria specifies a context or a CICS configuration that refers to a context.
The List command applies these formulas after applying object criteria and restriction criteria to the resource definitions in the specified location.
These report set options are used by the CICS Configuration Manager ISPF dialog interface options described in Analyzing relationships between resource definitions.
- <AllAttributes> specifies whether
to return all attributes of the requested resource definitions or
only a subset. Acceptable values are:
Response format
<CCV530>
<List>
<OutputData>
<ReturnCode> return_code </ReturnCode>
<ReasonCode> reason_code </ReasonCode>
<TaskNo> CICS_task_number </TaskNo>
<ListCount> element_count </ListCount>
<ObjectKeysCount> count </ObjectKeysCount> 1
<FilterDateCount> count </FilterDateCount>
<FilterCriteriaCount> count </FilterCriteriaCount>
<ResultsCount> count </ResultsCount>
<ListElement>
<ObjectData>
<Type> object_type </Type> 2
<ObjectInstance> object_instance </ObjectInstance> 3
Data for this object type
<HashingValue> checksum </HashingValue> 4
</ObjectData>
</ListElement>
More list elements…
</OutputData>
</List>
</CCV530>
- 1
- If the List command specified <Counts>All</Counts>,
then the output data contains the following elements:
- <ObjectKeysCount>
- Count of resource definitions matching the object criteria.
- <FilterDateCount>
- Count of resource definitions excluded because of date filtering.
- <FilterCriteriaCount>
- Count of resource definitions excluded because of restriction criteria.
- <ResultsCount>
- Count of resource definitions that match the specifications of the List command.
- 2
- If the List command specified a location_type of Journal, then object_type is always JournCom.
- 3
- The output data contains <ObjectInstance> only
if the List command request specified:
- location_type of Journal
or
- location_type of Repository and Yes for <ObjectHistory>
You can use the returned object_instance with the Inquire command to retrieve specific versions of journal or repository objects, or with the Delete command to delete specific versions of repository objects.
- location_type of Journal
- 4
- The List command returns <HashingValue> only if hashing_scope is Partial or Full.
Security key
API command (READ access authority):
>>-prefix.LIS.-+-object_type-+-.location_type.-+-location_name-+->< '-ALL---------' +-ALL-----------+ '-NONE----------'
Examples
The following example lists PROGDEF resource definitions that:
- Have a name beginning with the letter Q.
- Belong to the group named QAACRE01
- Have a CEDF attribute value of YES, DATALOCATION of BELOW, and EXECKEY of USER
<CCV530>
<LIST>
<LocationCriteria>
<LocationName> CCVPLEXD </LocationName>
<LocationType> CONTEXT </LocationType>
</LocationCriteria>
<ObjectCriteria>
<ObjName> Q* </ObjName>
<ObjGroup> QAACRE01 </ObjGroup>
<ObjType> PROGDEF </ObjType>
</ObjectCriteria>
<RestrictionCriteria>
<ListCount> 3 </ListCount>
<ListElement>
<RestrictionField> CEDF </RestrictionField>
<RestrictionOperator> = </RestrictionOperator>
<RestrictionValue> YES </RestrictionValue
</ListElement>
<ListElement>
<RestrictionField> DATALOCATION </RestrictionField>
<RestrictionOperator> = </RestrictionOperator>
<RestrictionValue> BELOW </RestrictionValue
</ListElement>
<ListElement>
<RestrictionField> EXECKEY </RestrictionField>
<RestrictionOperator> = </RestrictionOperator>
<RestrictionValue> USER </RestrictionValue
</ListElement>
</RestrictionCriteria>
</LIST>
</CCV530>
The following example lists the candidate resource definitions for a particular change package and migration scheme.
<CCV530>
<LIST>
<LOCATIONCRITERIA>
<LOCATIONTYPE> REPOSITORY </LOCATIONTYPE>
</LOCATIONCRITERIA>
<OBJECTCRITERIA>
<OBJTYPE> READYLST </OBJTYPE>
<CPID> 00000015 </CPID>
<SCHEME> PJCTEST </SCHEME>
</OBJECTCRITERIA>
<PROCESSPARMS>
<HASHINGSCOPE> FULL </HASHINGSCOPE>
</PROCESSPARMS>
</LIST>
</CCV530>