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:

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

<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>
 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.

Response format

<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>
 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.

 4 
The List command returns <HashingValue> only if hashing_scope is Partial or Full.

Security key

API command (READ access authority):

Read syntax diagramSkip visual syntax diagram
>>-prefix.LIS.-+-object_type-+-.location_type.-+-location_name-+-><
               '-ALL---------'                 +-ALL-----------+   
                                               '-NONE----------'   

Examples

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>

Reference Reference

Feedback


Timestamp icon Last updated: Friday, 8 February 2013


http://pic.dhe.ibm.com/infocenter/cicsts/v5r1/topic//ccv-api-cmd-list.htm