Discard
Discards the in-memory image of resource definitions from active CICS® regions. This does not affect the CSD file or CICSPlex® SM context
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
<QualificationData> exit-data </QualificationData>
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
<QualificationData> exit-data </QualificationData>
5
<CSDParms>
<ConnectionCount> All | element_count | Local </ConnectionCount> 6
<ConnectionElement>
<ConnectionName> remote_system_connection </ConnectionName>
</ConnectionElement>
More connection elements…
</CSDParms>
<CPSMParms>
<TargetScope> target_scope </TargetScope> 7
</CPSMParms>
</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>
- Specify <ListCount> followed by one or
more <ListElement>. Each <ListElement> must
identify a single resource definition, with no masking.
- 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
Change package:

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


- 1
- <CSDInfo> contains information for CSD-based resource definitions. <CPSMInfo> contains information for context-based resource definitions.

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>
<CPSMInfo> 3
<ReturnCode> return_code </ReturnCode>
<ReasonCode> reason_code </ReasonCode>
</CPSMnfo>
</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.
3
<CSDInfo> contains information for CSD-based resource definitions. <CPSMInfo> contains information for context-based resource definitions.
Security key
API command (READ access authority):
Change package:
>>-prefix.DSC.migration_scheme---------------------------------><
Ad hoc:
>>-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>