Install
Dynamically makes resource definitions available to an active CICS® region.
- For resource definitions that are in a change package
- For ad hoc selection of resource definitions
Request format
Change package:
<CCV530>
<Install>
<SelectionCriteria>
<CPID> change_package_ID </CPID>
<Scheme> migration_scheme </Scheme>
</SelectionCriteria>
<ProcessParms>
<Quiesce> No | Yes </Quiesce> 1
<QualificationData> exit-data </QualificationData> 2
<Discard> No | Yes </Discard> 3
<Force> No | Yes </Force> 4
CICSPlex SM parameters 4
</ProcessParms>
</Install>
</CCV530>
Ad hoc:
<CCV530>
<Install>
<LocationCriteria>
<LocationName> CICS_configuration </LocationName>
<LocationType> CConfig </LocationType>
</LocationCriteria>
<ObjectCriteria> 5
<ListCount> element_count </ListCount>
<ListElement>
<ObjName> resource_name </ObjName>
<ObjType> resource_type </ObjType>
<ObjGroup> resource_group </ObjGroup> 6
</ListElement>
More list elements…
</ObjectCriteria>
<ProcessParms>
<Quiesce> No | Yes </Quiesce> 1
<QualificationData> exit-data </QualificationData> 2
<Discard> No | Yes </Discard> 3
<CSDParms> 8
<ConnectionCount> All | element_count | Local </ConnectionCount>
<ConnectionElement>
<ConnectionName> remote_system_connection </ConnectionName>
</ConnectionElement>
More connection elements…
</CSDParms>
<Force> No | Yes </Force> 4
CICSPlex SM parameters 4
</ProcessParms>
</Install>
</CCV530>
CICSPlex® SM parameters:
<CPSMParms>
<TargetScope> target_scope </TargetScope> 9
<ResGroupObjectType> * | resource_type </ResGroupObjectType> 7
<CONNDEF>
<RefAssign> resource_assignment </RefAssign>
</CONNDEF>
<FILEDEF>
<RelatedScope> related_scope </RelatedScope>
<Usage> LOCAL | REMOTE </Usage>
</FILEDEF>
<PROGDEF>
<RelatedScope> related_scope </RelatedScope>
<Usage> LOCAL | REMOTE </Usage>
<Mode> N/A | AUTO </Mode>
</PROGDEF>
<TDQDEF>
<RelatedScope> related_scope </RelatedScope>
<Usage> LOCAL | REMOTE </Usage>
<Mode> N/A | IND | INTRA | EXTRA </RelatedScope>
</TDQDEF>
<TRANDEF>
<RelatedScope> related_scope </RelatedScope>
<Usage> LOCAL | REMOTE </Usage>
<Mode> N/A | DYNAM | STAT </Mode>
</TRANDEF>
</CPSMParms>
These notes apply to both command formats:
- 1
- CSD-based CICS configurations only: <Quiesce> specifies whether or not to set the resource to a status that allows its definition to be installed (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 install action, then the install action for that resource definition will fail.
- 2
- <QualificationData> is optional data passed through the Install operations qualification exit point. The needs of your organization determine whether you use an exit program and what processing it performs.
- 3
- <Discard> specifies whether or not to discard the resource definition before attempting to install it.
- 4
- Context-based CICS configurations only: for information about these CICSPlex SM parameters, see the CICS Transaction Server for z/OS®: CICSPlex SM Application Programming Reference.
These notes apply only to the ad hoc format:
- 5
- <ObjectCriteria> identifies the resources that you want to install. 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.
- 6
- To install an entire group of resource definitions (as opposed
to selecting resource definitions individually, or using masking values),
specify the name of the group, specify the resource type as ResGroup,
and omit the resource group. (If the resource type is ResGroup, the <ObjGroup> element
is ignored.)
Context-based CICS configurations only: to select resource definitions of a particular type in the ResGroup, specify <ResGroupObjectType> in the CICSPlex SM parameters (see item 6 ).
- 7
- Context-based CICS configurations only: for list elements that identify a ResGroup, <ResGroupObjectType> sets a filter to select resource definitions of a particular type, excluding any other types of resource definition in the ResGroup. If you omit <ResGroupObjectType>, all resource definitions in the ResGroup are selected.
- 8
- <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).
This note applies only to the CICSPlex SM parameters:
- 9
- Context-based CICS configurations only: target_scope is required.
Response format
<CCV530>
<Install>
<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> resource_type </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>
</Install>
</CCV530>
- 1
- <CSDInfo> contains information for CSD-based resource definitions. <CPSMInfo> contains information for context-based resource definitions.
Security key
API command (READ access authority):
Examples
The following example installs three programs into two active CSD-based CICS regions, via the selected remote system connections defined in the CICS configuration:
<CCV530>
<Install>
<LocationCriteria>
<LocationName> QAACSD22 </LocationName>
<LocationType> CCONFIG </LocationType>
</LocationCriteria>
<ObjectCriteria>
<Listcount> 3 </Listcount>
<ListElement>
<ObjName> DFH$AALL </ObjName>
<ObjGroup> DFH$AFLA </ObjGroup>
<ObjType> PROGDEF </ObjType>
</ListElement>
<ListElement>
<ObjName> ACCT00 </ObjName>
<ObjGroup> DFH$ACCT </ObjGroup>
<ObjType> PROGDEF </ObjType>
</ListElement>
<ListElement>
<ObjName> DFH$AREP </ObjName>
<ObjGroup> DFH$AFLA </ObjGroup>
<ObjType> PROGDEF </ObjType>
</ListElement>
</ObjectCriteria>
<ProcessParms>
<Quiesce> No </Quiesce>
<Discard> No </Discard>
<CSDPARMS>
<CONNECTIONCOUNT> 2 </CONNECTIONCOUNT>
<CONNECTIONELEMENT>
<CONNECTIONNAME> T22T </CONNECTIONNAME>
</CONNECTIONELEMENT>
<CONNECTIONELEMENT>
<CONNECTIONNAME> T13T </CONNECTIONNAME>
</CONNECTIONELEMENT>
</CSDPARMS>
</ProcessParms>
</Install>
</CCV530>
The following example installs a program via all of the remote system connections defined in the CICS configuration:
<CCV530>
<Install>
<LocationCriteria>
<LocationName> QAACSD22 </LocationName>
<LocationType> CCONFIG </LocationType>
</LocationCriteria>
<ObjectCriteria>
<Listcount> 1 </Listcount>
<ListElement>
<ObjName> DFH$SXP1 </ObjName>
<ObjGroup> DFH$SXP </ObjGroup>
<ObjType> PROGDEF </ObjType>
</ListElement>
</ObjectCriteria>
<ProcessParms>
<Quiesce> YES </Quiesce>
<Discard> NO </Discard>
</ProcessParms>
</Install>
</CCV530>