Newcopy

Reloads in-memory copies of resource definitions associated with a CICS® program definition or document template definition. This does not affect the stored resource definition referred to by the CICS configuration.

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

Request format

Figure 1. Change packages:

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

<CCV510>
  <Newcopy>
    <SelectionCriteria>
      <CPID> change_package_ID </CPID>
      <Scheme> migration_scheme </Scheme>
    </SelectionCriteria>
 
    <ProcessParms>
      <PhaseIn> No | Yes </PhaseIn>  1 
      <CPSMParms>
        <TargetScope> target_scope </TargetScope>  2 
      </CPSMParms>
    </ProcessParms>
  </Newcopy>
</CCV510>
 1 
<PhaseIn>Yes</PhaseIn> issues a phase-in action instead of a newcopy, to cater for in-use programs. For details, see the CICS documentation.
 2 
If the change package contains candidates for migration to context-based target CICS configurations, target_scope is required.
Figure 2. Ad hoc:

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

<CCV510>
  <Newcopy>
    <LocationCriteria>
      <LocationName> CICS_configuration </LocationName>
      <LocationType> CConfig </LocationType>
    </LocationCriteria>
 
    <ObjectCriteria>  1 
      <ListCount> element_count </ListCount>
      <ListElement>
        <ObjectData>
          <ObjName> resource_name </ObjName>
          <ObjGroup> resource_group </ObjGroup>
          <ObjType> MAPDEF | PROGDEF | PRTNDEF | DOCDEF </ObjType>
        </ObjectData>
      </ListElement>
 
      More list elements…
 
    </ObjectCriteria>
 
    <ProcessParms>
      <PhaseIn> No | Yes </PhaseIn>  2 
 
      <CSDParms>  3 
        <ConnectionCount> All | element_count | Local </ConnectionCount>
        <ConnectionElement>
          <ConnectionName> remote_system_connection </ConnectionName>
        </ConnectionElement>
 
        More connection elements…
 
      </CSDParms>
 
      <CPSMParms>
        <TargetScope> target_scope </TargetScope>  4 
      </CPSMParms>
 
    </ProcessParms>
  </Newcopy>
</CCV510>
 1 
<ObjectCriteria> identifies the resource definitions that you want to newcopy.
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>
 2 
<PhaseIn>Yes</PhaseIn> issues a phase-in action instead of a newcopy, to cater for in-use programs. For details, see the CICS documentation.
 3 
<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).
 4 
Context-based CICS configurations only: target_scope is required.

Response format

Figure 3. Change packages:
<CCV510>
  <Newcopy>
    <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>
  </Newcopy>
</CCV510>
 1 
<CSDInfo> contains information for CSD-based resource definitions. <CPSMInfo> contains information for context-based resource definitions.
Figure 4. Ad hoc:
<CCV510>
  <Newcopy>
    <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>
  </Newcopy>
</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.NEW.migration_scheme---------------------------------><

Ad hoc:

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


Reference Reference

Feedback


Timestamp icon Last updated: Friday, 7 February 2014


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