Discard

Discards the in-memory image of resource definitions from active CICS® regions. This does not affect the CSD file Start of changeor CICSPlex® SM contextEnd of change where the resource definition is stored.

Request format

Change package:

<CCV530>
  <Discard>
    <SelectionCriteria>
      <CPID> change_package_ID </CPID>
      <Scheme> migration_scheme </Scheme>
    </SelectionCriteria>
 
    <ProcessParms>
      <Quiesce> No | Yes </Quiesce>  1 
      Start of change<QualificationData> exit-data </QualificationData>End of change  2 
      <CPSMParms>
        <TargetScope> target_scope </TargetScope>  3 
      </CPSMParms> 4 
 
    </ProcessParms>
  </Discard>
</CCV530>
 1 
<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.
 2 
<QualificationData> is optional data passed through the Discard operations qualification exit point. The needs of your organization determine whether you use an exit program and what processing it performs.
 3 
If the change package contains candidates for migration to context-based target CICS configurations, target_scope is required.
 4 
No <CSDParms> element applies for change packages.

Ad hoc:

<CCV530>
  <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 
      Start of change<QualificationData> exit-data </QualificationData>End of change  5 
      <CSDParms>
        <ConnectionCount> All | element_count | Local </ConnectionCount>  6 
        <ConnectionElement>
          <ConnectionName> remote_system_connection </ConnectionName>
        </ConnectionElement>
 
        More connection elements…
 
      </CSDParms>
      
     Start of change <CPSMParms>
        <TargetScope> target_scope </TargetScope> 7 
      </CPSMParms>End of change

    </ProcessParms>
  </Discard>
</CCV530>
 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 
<QualificationData> is optional data passed through the Discard operations qualification exit point. Whether you use an exit program and what processing it performs is up to you.
 6 
<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).
 7 
If the change package contains candidates for migration to context-based target CICS configurations, target_scope is required.

Response format

Start of changeChange package:End of change

Start of change
<CCV530>
  <Discard>
    <OutputData>
      <ReturnCode> return_code </ReturnCode>
      <ReasonCode> reason_code </ReasonCode>
      <TaskNo> CICS_task_number </TaskNo>
 
      <ListCount> element_count </ListCount>
      <ListElement>
        <ReturnCode> return_code </ReturnCode>
        <ReasonCode> reason_code </ReasonCode>
        <ObjName> resource_name </ObjName>
        <ObjType> MAPDEF | PROGDEF | PRTNDEF </ObjType>
        <ObjGroup> resource_group </ObjGroup>
        <Config> CICS_configuration </Config>
        <LocationName> CSD_DSN | context </LocationName>
 
        <CSDInfo>  1 
          <ConnectionCount> element_count </ConnectionCount>
          <ConnectionElement>
            <ConnectionName> remote_system_connection </ConnectionName>
            <ReturnCode> return_code </ReturnCode>
            <ReasonCode> reason_code </ReasonCode>
          </ConnectionElement>
 
          More connection elements…
 
        </CSDInfo>             

        <CPSMInfo>  1 
          <ReturnCode> return_code </ReturnCode>
          <ReasonCode> reason_code </ReasonCode>
        </CPSMnfo>
      </ListElement>
 
      More list elements…
 
    </OutputData>
  </Discard>
</CCV530>
End of change Start of change
 1 
<CSDInfo> contains information for CSD-based resource definitions. <CPSMInfo> contains information for context-based resource definitions.
End of change

Ad hoc:

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

        Start of change<CPSMInfo>  3 
          <ReturnCode> return_code </ReturnCode>
          <ReasonCode> reason_code </ReasonCode>
        </CPSMnfo>End of change

      </ListElement>
 
      More list elements…
 
    </OutputData>
  </Discard>
</CCV530>
 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.
Start of change 3 End of change
Start of change<CSDInfo> contains information for CSD-based resource definitions. <CPSMInfo> contains information for context-based resource definitions.End of change

Security key

API command (READ access authority):

Change package:

Read syntax diagramSkip visual syntax diagram
>>-prefix.DSC.migration_scheme---------------------------------><

Ad hoc:

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

Example

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

<CCV530>

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

</CCV530>