Discard

Discards the in-memory image of resource definitions from active CSD-based CICS® regions. This does not affect the CSD file where the resource definition is stored.

You can only use the Discard command with CSD-based CICS configurations, not context-based CICS configurations.

Request format

<CCV510>
  <Discard>
    <LocationCriteria>
      <LocationName> CICS_configuration </LocationName>  1 
      <LocationType> CConfig </LocationType>  2 
    </LocationCriteria>
 
    <ObjectCriteria>   3 
      <ListCount> element_count </ListCount>
      <ListElement>
        <ObjectData>
          <ObjName> resource_name </ObjName>
          <ObjGroup> resource_group </ObjGroup>
          <ObjType> resource_type </ObjType>
        </ObjectData>
      </ListElement>
 
      More list elements…
 
    </ObjectCriteria>
 
    <ProcessParms>
      <Quiesce> No | Yes </Quiesce>  4 
      <CSDParms>
        <ConnectionCount> All | element_count | Local </ConnectionCount>  5 
        <ConnectionElement>
          <ConnectionName> remote_system_connection </ConnectionName>
        </ConnectionElement>
 
        More connection elements…
 
      </CSDParms>
    </ProcessParms>
  </Discard>
</CCV510>
 1 
<LocationName> must specify the name of a CSD-based CICS configuration.
 2 
<LocationType> must contain CConfig.
 3 
<ObjectCriteria> identifies the resource definitions that you want to discard.
You can specify the object criteria in several ways:
  • To identify a single resource definition, specify only one set of <ObjName>, <ObjGroup>, and <ObjType>, with no masking (wildcards). Do not specify <ListCount> or <ListElement>.
  • To identify one or more resource definitions, either:
    • Specify <ListCount> followed by one or more <ListElement>. Each <ListElement> must identify a single resource definition, with no masking.

      or

    • Specify only one set of <ObjName>, <ObjGroup>, and <ObjType> with masked values. Do not specify <ListCount> or <ListElement>. The values can be any combination of:
      • Mask or specific value for the resource name
      • Mask or specific value for the resource group
      • Specific resource type, or the value * or All to identify all resource types (you cannot use masking to identify a subset of resource types)

      For example, to identify all program resource definitions beginning with the characters PAY, from all groups beginning with the characters FIN, specify:

      <ObjectCriteria>
        <ObjName>PAY*</ObjName>
        <ObjGroup>FIN*</ObjGroup>
        <ObjType>PROGDEF</ObjType>
      </ObjectCriteria>
 4 
<Quiesce> specifies whether or not to set the resource to a status that allows its definition to be discarded (for example, disabled, closed, or out of service), prior to attempting the action. The status depends on the resource type. If you do not specify this "quiesce" option, and a resource is in a status that does not allow the discard action, then the discard action for that resource definition will fail.
 5 
<ConnectionCount> specifies the CSD-based CICS regions on which to perform this action:
All
Performs the action via all of the remote system connections defined in the CICS configuration. If you omit <ConnectionCount> or its parent <CSDParms>, this is the default.
element_count
Performs the action via the remote system connections identified by one or more <ConnectionElement> elements. The number of <ConnectionElement> elements must match element_count. Each <ConnectionElement> must refer to a remote system connection specified in the CICS configuration.
Local
Performs the action on the CICS region that is running the CICS Configuration Manager server. If you specify "local":
  • <LocationName> must specify a CICS configuration that refers to the CSD file used by the CICS Configuration Manager server.
  • Do not specify any connection elements (if you do, they are ignored).

Response format

<CCV510>
  <Discard>
    <OutputData>
      <ReturnCode> return_code </ReturnCode>  1 
      <ReasonCode> reason_code </ReasonCode>
      <TaskNo> CICS_task_number </TaskNo>
 
      <ListCount> element_count </ListCount>
      <ListElement>
        <ReturnCode> return_code </ReturnCode>  1 
        <ReasonCode> reason_code </ReasonCode>
        <ObjName> resource_name </ObjName>
        <ObjType> resource_type </ObjType>
        <ObjGroup> resource_group </ObjGroup>
        <Config> CICS_configuration </Config>
        <LocationName> CSD_DSN </LocationName>
        <CSDInfo>
          <ConnectionCount> element_count </ConnectionCount>
          <ConnectionElement>
            <ConnectionName> remote_system_connection </ConnectionName>
            <ReturnCode> return_code </ReturnCode>  1 
            <ReasonCode> reason_code </ReasonCode>
 
            <ExceptionData> exception data </ExceptionData>  2 
 
          </ConnectionElement>
 
          More connection elements…
 
        </CSDInfo>
      </ListElement>
 
      More list elements…
 
    </OutputData>
  </Discard>
</CCV510>
 1 
The output data contains three types of return code and reason code: for the command overall, for each list element, and for the remote system connections for each list element. The overall return code and reason code are from the list element with the highest return code; the list element return code and reason code are from its connection with the highest return code and reason code.
 2 
Each list element in the response matches a list element in the request, in the same order.

Security key

API command (READ access authority):

Read syntax diagramSkip visual syntax diagram
>>-prefix.DIO.object_type.location_type.location_name----------><

Examples

The following example quiesces and then discards a map resource definition in two active CICS regions.

<CCV510>

  <Discard>

    <LocationCriteria>
      <LocationName> CCVT22M </LocationName>
      <LocationType> CCONFIG </LocationType>
    </LocationCriteria>

    <ObjectCriteria>
      <Listcount> 1 </Listcount>
      <ListElement>
        <ObjName> JAMES </ObjName>
        <ObjGroup> BINGLE </ObjGroup>
        <ObjType> MAPDEF </ObjType>
      </ListElement>
    </ObjectCriteria>

    <ProcessParms>
      <Quiesce> YES </Quiesce>
      <CSDPARMS>
        <CONNECTIONCOUNT> 2 </CONNECTIONCOUNT>
         <CONNECTIONELEMENT>
          <CONNECTIONNAME> T22M </CONNECTIONNAME>
         </CONNECTIONELEMENT>
         <CONNECTIONELEMENT>
          <CONNECTIONNAME> T23M </CONNECTIONNAME>
         </CONNECTIONELEMENT>
      </CSDPARMS>
    </ProcessParms>

  </Discard>

</CCV510>

Reference Reference

Feedback


Timestamp icon Last updated: Friday, 8 February 2013


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