DEPLOY

Purpose

Requests a deployment analysis report. For a description of each type of deployment analysis report, see Table 1.

Format

Read syntax diagramSkip visual syntax diagram
           .----------------------------.   
           V  (1)                       |   
>>-DEPLOY----------| Collection phase |-+----------------------->

>--,PHASE=REPORT,TYPE=-+-COLDSTARTCOMPARE--+-------------------->
                       +-CANDIDATESCOMPARE-+   
                       +-RUNTIMECOMPARE----+   
                       +-RUNTIME-----------+   
                       +-CANDIDATES--------+   
                       '-CHECK-------------'   

>--+-----------------------+-----------------------------------><
   '-,FILTERDATASET=dsname-'   

Notes:
  1. The number and type of collection phases depends on the report type. For details, see the description of the PHASE parameter.
Read syntax diagramSkip visual syntax diagram
Collection phase

|--PHASE=COLLECT--,REPORTSET=-+-1-+----------------------------->
                              '-2-'   

                                                    .-------------------------.                          
                                                    V  (1)                    |                          
>--+-,TYPE=CANDIDATES--+-,CONFIGURATION=config_CSD----------+-,GROUP=group--+-+--,LOCALSYSID=sysid-+-+--|
   |                   |                                    '-,GRPLIST=list-'                      | |   
   |                   '-,CONFIGURATION=config_context--,SCOPE=scope-------------------------------' |   
   '-,TYPE=RUNTIME--+-,CONFIGURATION=config_CSD--,CONNECTION=connection-+----------------------------'   
                    '-,CONFIGURATION=config_context--,SCOPE=scope-------'                                

Notes:
  1. The total number of GROUP and GRPLIST parameters is limited to 1000.
PHASE
A DEPLOY command consists of one or more collection phases, each marked by a PHASE=COLLECT parameter, followed by one reporting phase, marked by a PHASE=REPORT parameter. Each collection phase specifies candidate or runtime resource definitions required for the report. The report phase specifies the type of report that you want to produce.

Deployment analysis reports refer to the input to each collection phase as a data source. The reports assign a two-digit ID to each data source: 01, 02, 03, etc. These IDs match the order of the PHASE=COLLECT parameters in the DEPLOY command. For example, the ID of the data source for the first PHASE=COLLECT parameter is 01.

The type of report determines the number and type of collection phases. To understand this relationship, it is useful to think of collection phases in terms of report sets (the sets of collected data that the report requires):

  • Depending on the report type, the report either lists one report set or compares two report sets.
  • Collecting a report set of runtime resource definitions requires one collection phase.
  • Collecting a report set of candidate resource definitions requires either one or two collection phases (two, if you want to combine candidates from a CSD file and a context).

The following table shows the number and type of collection phases for each report type.

In the DEPLOY command formats in the following table:

  • Square brackets ([]) indicate optional parameters.
  • Ellipses (…) indicate required parameters omitted from this listing. For details of the omitted parameters, see the syntax diagram for the DEPLOY command.
  • If you specify two collection phases for a report set of candidate resource definitions, then the CONFIGURATION parameter of one of these collection phases must specify a CICS® configuration that refers to a CSD file, and the other must specify a CICS configuration that refers to a context.
Table 1. Deployment analysis report types: number and type of collection phases
Report type Number and type of collection phases DEPLOY command format
Cold start compare Two or three collection phases:
  • One collection phase for the report set of runtime resource definitions.
  • One or two collection phases for the report set of candidate resource definitions.
DEPLOY
  PHASE=COLLECT,REPORTSET=1,TYPE=RUNTIME,…,
  PHASE=COLLECT,REPORTSET=2,TYPE=CANDIDATES,…,
 [PHASE=COLLECT,REPORTSET=2,TYPE=CANDIDATES,…,]
  PHASE=REPORT,TYPE=COLDSTARTCOMPARE
Candidates compare Two to four collection phases:
  • One or two collection phases for the first report set of candidate resource definitions.
  • One or two collection phases for the second report set of candidate resource definitions.
DEPLOY
  PHASE=COLLECT,REPORTSET=1,TYPE=CANDIDATES,…,
 [PHASE=COLLECT,REPORTSET=1,TYPE=CANDIDATES,…,]
  PHASE=COLLECT,REPORTSET=2,TYPE=CANDIDATES,…,
 [PHASE=COLLECT,REPORTSET=2,TYPE=CANDIDATES,…,]
  PHASE=REPORT,TYPE=CANDIDATESCOMPARE
Runtime resource compare Two collection phases: one for each report set of runtime resource definitions.
DEPLOY
  PHASE=COLLECT,REPORTSET=1,TYPE=RUNTIME,…,
  PHASE=COLLECT,REPORTSET=2,TYPE=RUNTIME,…,
  PHASE=REPORT,TYPE=RUNTIMECOMPARE
Runtime resources One collection phase.
DEPLOY
  PHASE=COLLECT,REPORTSET=1,TYPE=RUNTIME,…,
  PHASE=REPORT,TYPE=RUNTIME
Candidates One or two collection phases for the report set of candidate resource definitions.
DEPLOY
  PHASE=COLLECT,REPORTSET=1,TYPE=CANDIDATES,…,
 [PHASE=COLLECT,REPORTSET=1,TYPE=CANDIDATES,…,]
  PHASE=REPORT,TYPE=CANDIDATES
Check Same as the candidates report: one or two collection phases for the report set of candidate resource definitions.
DEPLOY
  PHASE=COLLECT,REPORTSET=1,TYPE=CANDIDATES,…,
 [PHASE=COLLECT,REPORTSET=1,TYPE=CANDIDATES,…,]
  PHASE=REPORT,TYPE=CHECK
REPORTSET
Identifies the report set to which a collection phase belongs.

For example, the following DEPLOY command compares two report sets of candidate resource definitions. One set is for a test environment, the other set is for a production environment. Each set combines resource definitions from a CSD file and a CICSPlex® SM data repository. The REPORTSET parameter groups together the appropriate pairs of collection phases. Report set 1 identifies the candidate resource definitions for the test environment, where TESTCSD1 specifies a CICS configuration that refers to a CSD file, and TESTPLX1 refers to a context. Similarly, report set 2 identifies the candidates for the production environment.

DEPLOY PHASE=COLLECT,REPORTSET=1,
         TYPE=CANDIDATES,CONFIGURATION=TESTCSD1,GRPLIST=DFHLIST,LOCALSYSID=TST1,
       PHASE=COLLECT,REPORTSET=1,
         TYPE=CANDIDATES,CONFIGURATION=TESTPLX1,SCOPE=TEST1,
       PHASE=COLLECT,REPORTSET=2,
         TYPE=CANDIDATES,CONFIGURATION=PRODCSD1,GRPLIST=DFHLIST,LOCALSYSID=PRD1,
       PHASE=COLLECT,REPORTSET=2,
         TYPE=CANDIDATES,CONFIGURATION=PRODPLX1,SCOPE=PROD1,
       PHASE=REPORT,TYPE=CANDIDATESCOMPARE
TYPE (for PHASE=COLLECT)
Specifies whether to collect candidate resource definitions or runtime resource definitions:
CANDIDATES
Collects candidate resource definitions from a CSD file or a context.
RUNTIME
Collects in-memory resource definitions from an active CICS region.
FILTERDATASET
Optional. The fully qualified data set name of a filter file, without enclosing quotes. The filter file specifies criteria for items that you want to suppress from the report. For details, see Filtering resource definitions from deployment analysis reports.
CONFIGURATION
A CICS configuration that refers to a CSD file or a context.
GROUP and GRPLIST
Valid only when collecting candidate resource definitions from a CSD file. The names of the groups (specified by GROUP) and the lists (specified by GRPLIST) containing the candidate resource definitions that you want to collect from a CSD file.

The order of the GROUP and GRPLIST parameters is significant: specify them in the order that you would want the groups and lists to be installed. The total number of GROUP and GRPLIST parameters is limited to 1000.

Similar to the CICS system initialization (SIT) parameter GRPLIST, the DEPLOY command parameters GROUP and GRPLIST specify a group sequence. However, the DEPLOY command parameters provide more flexibility than the SIT parameter, enabling you to easily simulate and test changes in group sequence, such as the addition or removal of groups or lists in the sequence.

The following examples show how to use GROUP and GRPLIST to collect candidate resource definitions for a cold start compare report. In these examples, the runtime resource definitions for the report are from a CICS region that was started using the following GRPLIST SIT parameter:

GRPLIST(DFHLIST,LISTA,LISTB,LISTC*)
Simple case: same group sequence for candidate and runtime resource definitions

If you simply want to collect candidate resource definitions using the same group sequence as the runtime definitions, then you specify GRPLIST parameters to match the lists that initialized the CICS region. For example, to match the GRPLIST SIT parameter shown previously, specify the following GRPLIST parameters in your DEPLOY command:

GRPLIST=DFHLIST,
GRPLIST=LISTA,
GRPLIST=LISTB,
GRPLIST=LISTC*

(One GRPLIST parameter for each list, following the same sequence as the SIT parameter. In this simple case, the GROUP parameter is unnecessary.)

Adding a group to the group sequence

Instead of having to actually add the group to a list, you can use the GROUP parameter to simulate adding the group. For example, suppose you want to analyze the effect of appending a new group, called NEWGROUP, to LISTA. You can simulate this by inserting a GROUP parameter for NEWGROUP after the GRPLIST parameter for LISTA:

GRPLIST=DFHLIST,
GRPLIST=LISTA,
GROUP=NEWGROUP,
GRPLIST=LISTB,
GRPLIST=LISTC*

Now suppose that, instead of appending NEWGROUP to LISTA, you want to insert NEWGROUP among the groups in LISTB. (LISTB consists of the groups GROUPB1, GROUPB2, and GROUPB3.) You can simulate this by replacing the GRPLIST parameter for LISTB with GROUP parameters that explicitly specify each group in LISTB, and then inserting NEWGROUP where you want it:

GRPLIST=DFHLIST,
GRPLIST=LISTA,
GROUP=GROUPB1,
GROUP=NEWGROUP,
GROUP=GROUPB2,
GROUP=GROUPB3,
GRPLIST=LISTC*
Removing a group from the group sequence

Instead of having to actually remove the group from a list, you can use GROUP parameters to simulate removing the group. For example, suppose LISTA consists of the groups GROUPA1, GROUPA2, and GROUPA3. You want to analyze the effect of removing GROUPA2. Instead of specifying a GRPLIST parameter for LISTA, you specify a GROUP parameter for each of its groups except GROUPA2:

GRPLIST=DFHLIST,
GROUP=GROUPA1,
GROUP=GROUPA3,
GRPLIST=LISTB,
GRPLIST=LISTC*
Removing a list from a group sequence that specifies a generic group list name

Suppose that the LISTC* pattern specified by your GRPLIST SIT parameter matches the lists LISTC1, LISTC2, and LISTC3. You want to analyze the effect of removing LISTC2 from this sequence. In your DEPLOY command, instead of a GRPLIST=LISTC* parameter, specify a separate GRPLIST parameter for each of the remaining lists:

GRPLIST=DFHLIST,
GRPLIST=LISTA,
GRPLIST=LISTB,
GRPLIST=LISTC1,
GRPLIST=LISTC3

Notice that, in this example, we have specified more than four GRPLIST parameters, which would not be allowed in a GRPLIST SIT parameter.

The GRPLIST parameter can specify the same values for a name as the GRPLIST SIT parameter: either a real group list name or a generic group list name that incorporates global filename characters (+ and *). For more information on the allowed values for GRPLIST, see the CICS documentation for the GRPLIST SIT parameter.

The GROUP parameter must specify a particular group name: it does not allow generic names.

If the CONFIGURATION parameter specifies a CICS configuration that refers to a CSD file, then you must specify at least one GROUP or GRPLIST parameter. (Unlike the GRPLIST CICS system initialization parameter, these parameters have no default value; the GRPLIST parameter of the DEPLOY command does not default to DFHLIST.)

If the CONFIGURATION parameter specifies a CICS configuration that refers to a context, GRPLIST and GROUP are not allowed.

LOCALSYSID
Valid only when collecting candidate resource definitions from a CSD file.

The SYSID of the CICS region where, for the purposes of this deployment analysis report, the resource definitions would be installed. This enables the report to handle any candidate resource definitions that specify remote system (REMOTESYSTEM) attribute values:

  • If the REMOTESYSTEM attribute value matches the SYSID that you specify for the report, the report interprets the resource definition as a local resource definition.
  • Otherwise, the report interprets the resource definition as a remote resource definition.

Whether the report interprets a resource definition as local or remote is especially significant for comparison reports, which notify you when a resource definition has been installed locally in one set of resource definitions, but as a remote resource definition in the other set.

SCOPE
Valid only when collecting candidate or runtime resource definitions via CICSPlex SM.

The CICSPlex SM target scope. This must match a CSYSDEF name. CSYSGRP names are not supported.

CONNECTION
Valid only when collecting runtime resource definitions via the CICS Configuration Manager agent.

The name of the connection that the CICS Configuration Manager server uses to connect to the CICS Configuration Manager agent.

The DFHCSD file data set name of the CICS region must match the CSD file data set name referred to by the CICS configuration (specified by the CONFIGURATION parameter).

TYPE (for PHASE=REPORT)
The type of deployment analysis report that you want to produce:
  • COLDSTARTCOMPARE
  • CANDIDATESCOMPARE
  • RUNTIMECOMPARE
  • RUNTIME
  • CANDIDATES
  • CHECK

For a description of each type of deployment analysis report, see Table 1.

Security key

You can use the following security key format to restrict who can collect data from particular CICS configurations, and who can request deployment analysis reports:

API command (READ access authority):

Read syntax diagramSkip visual syntax diagram
>>-prefix.DEP.-+-COLLECT.CCONFIG.CICS_configuration-+----------><
               '-REPORT.NONE.NONE-------------------'   

For information on using security keys, see Restricting access to API commands and resource definitions.


Reference Reference

Feedback


Timestamp icon Last updated: Friday, 7 February 2014


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