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:
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.
<CCV510>
<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>
</CCV510>
Journal record criteria:
<JnlRecType> journal_record_type </JnlRecType>
<JnlAPICMD> API_command_name </JnlAPI>
<JnlCCVRel> CCV_release </JnlCCVRel>
<JnlCICSRel> CICS_release </JnlCICSRel>
<JnlCConfig> CICS_configuration </JnlCConfig>
<JnlContext> context </JnlContext>
<JnlCSD> CSD_DSN </JnlCSD>
<JnlCreateTime> time_stamp </JnlCreateTime>
<JnlCPID> change_package_ID </JnlCPID>
<JnlScheme> migration_scheme </JnlScheme>
<JnlEventID> event_ID </JnlEventID>
<JnlJobID> job_ID </JnlJobID>
<JnlJobName> job_name </JnlJobName>
<JnlUserID> user_ID </JnlUserID>
<JnlObjGroup> resource_group </JnlObjGroup>
<JnlObjName> resource_name </JnlName>
<JnlObjType> resource_type </JnlObjType>
<JnlTaskNum> CICS_task_number </JnlTaskNum>
<JnlRC> return_code </JnlRC>
<JnlRsn> reason_code </JnlRsn>
<JnlSystem> SMF_system_identifier </JnlSystem>
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:
<CCV510>
<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>
</CCV510>
If you specify both <JnlCriteria> and <ObjectCriteria>, then <ObjectCriteria> describes a resource definition embedded in a BAImage (before/after image) journal record.
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>
You must specify these values in uppercase.
<AllAttributes> is relevant only when listing resource definitions.
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.)
For details on each checksum type, see Comparing a list panel of objects with a checksum column.
<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.
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.
<CCV510>
<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>
</CCV510>
or
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.
The following example lists PROGDEF resource definitions that:
<CCV510>
<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>
</CCV510>
The following example lists the candidate resource definitions for a particular change package and migration scheme.
<CCV510>
<LIST>
<LOCATIONCRITERIA>
<LOCATIONTYPE> REPOSITORY </LOCATIONTYPE>
</LOCATIONCRITERIA>
<OBJECTCRITERIA>
<OBJTYPE> READYLST </OBJTYPE>
<CPID> 00000015 </CPID>
<SCHEME> PJCTEST </SCHEME>
</OBJECTCRITERIA>
<PROCESSPARMS>
<HASHINGSCOPE> FULL </HASHINGSCOPE>
</PROCESSPARMS>
</LIST>
</CCV510>