Install

Dynamically makes resource definitions available to an active CICS® region.

This command has two formats:
  • For resource definitions that are in a change package
  • For ad hoc selection of resource definitions

Request format

Change packages:

This format is identified by the presence of the <SelectionCriteria> element.

<CCV510>
  <Install>
    <SelectionCriteria>
      <CPID> change_package_ID </CPID>
      <Scheme> migration_scheme </Scheme>
    </SelectionCriteria>
 
    <ProcessParms>
      <Quiesce> No | Yes </Quiesce>  1 
      <Discard> No | Yes </Discard>  2 
 
      <Force> No | Yes </Force>  3 
      CICSPlex SM parameters  3 
 
    </ProcessParms>
  </Install>
</CCV510>

Ad hoc:

This format is identified by the absence of the <SelectionCriteria> element.

<CCV510>
  <Install>
    <LocationCriteria>
      <LocationName> CICS_configuration </LocationName>
      <LocationType> CConfig </LocationType>
    </LocationCriteria>
    <ObjectCriteria>  4 
      <ListCount> element_count </ListCount>
      <ListElement>
        <ObjName> resource_name </ObjName>
        <ObjType> resource_type </ObjType>
        <ObjGroup> resource_group </ObjGroup>  5 
      </ListElement>
 
      More list elements…
 
    </ObjectCriteria>
 
    <ProcessParms>
      <Quiesce> No | Yes </Quiesce>  1 
      <Discard> No | Yes </Discard>  2 
      <CSDParms>  7 
        <ConnectionCount> All | element_count | Local </ConnectionCount>
        <ConnectionElement>
          <ConnectionName> remote_system_connection </ConnectionName>
        </ConnectionElement>
 
        More connection elements…
 
      </CSDParms>
 
      <Force> No | Yes </Force>  3 
      CICSPlex SM parameters  3 
 
    </ProcessParms>
  </Install>
</CCV510>
Figure 1. CICSPlex SM parameters
<CPSMParms>
  <TargetScope> target_scope </TargetScope>  8 
  <ResGroupObjectType> * | resource_type </ResGroupObjectType>  6 
  <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 
CSD-based CICS configurations only: <Discard> specifies whether or not to discard the resource definition before attempting to install it.
 3 
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:

 4 
<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>
 5 
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 ).

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

 8 
Context-based CICS configurations only: target_scope is required.

Response format

<CCV510>
  <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>
</CCV510>
 1 
<CSDInfo> contains information for CSD-based resource definitions. <CPSMInfo> contains information for context-based resource definitions.

Security key

API command (READ access authority):

Change packages:

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

Ad hoc:

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

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:

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

The following example installs a program via all of the remote system connections defined in the CICS configuration:

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

Reference Reference

Feedback


Timestamp icon Last updated: Friday, 7 February 2014


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