DEPLOY
Purpose
Requests a deployment analysis report. For a description of each type of deployment analysis report, see Table 1.
Format
.----------------------------. V (1) | >>-DEPLOY----------| Collection phase |-+-----------------------> >--,PHASE=REPORT,TYPE=-+-COLDSTARTCOMPARE---------------------------+--> +-CANDIDATESCOMPARE--------------------------+ +-RUNTIMECOMPARE-----------------------------+ +-RUNTIME------------------------------------+ +-CANDIDATES---------------------------------+ +-CHECK--------------------------------------+ '-CICSDEFSCOMPARE,CHECKSUM=-+-FULL---------+-' +-PARTIAL------+ +-CRITICAL-----+ | (2) | '-CCVXCRCn-----' >--+-----------------------+----------------------------------->< '-,FILTERDATASET=dsname-'
- The number and type of collection phases depends on the report type. For details, see the description of the PHASE parameter.
- n is a single-digit number from 1 - 9.
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-------' | '-,TYPE=CICSDEFS----,CONFIGURATION=config_CSD-----------------------------------------------------'
- The total number of GROUP and GRPLIST parameters is limited to 1000.
Phases
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).
Collecting a report set of CICS® definitions requires one collection phase.
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.
Report type | Number and type of collection phases | DEPLOY command format |
---|---|---|
Cold start compare | Two or three collection phases:
|
|
Candidates compare | Two to four collection phases:
|
|
Runtime resource compare | Two collection phases: one for each report set of runtime resource definitions. |
|
![]() ![]() |
![]() ![]() |
![]()
![]() |
Runtime resources | One collection phase. |
|
Candidates | One or two collection phases for the report set of candidate resource definitions. |
|
Check | Same as the candidates report: one or two collection phases for the report set of candidate resource definitions. |
|
Collection phase parameters
- CONFIGURATION
- A CICS configuration that refers to a CSD file or a context.
- 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).
- 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.
- 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
- 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.
- 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.
CICSDEFS
Collects CICS resource definitions from a CSD file.
Report phase parameters
CHECKSUM
Valid only when report type is CICSDEFSCOMPARE.
The name of the algorithm to use when calculating the CICS definition's checksum value that is used for comparison matching. Definitions that have the same checksum are treated as a match. By changing the checksum algorithm, you can exclude irrelevant attributes or expected differences from the checksum calculation.
- FULL
The full list of user-editable attributes, but not definition signature attributes such as CREATETIME. The FULL algorithm is predetermined by CICS Configuration Manager.
- PARTIAL
A partial list of user-editable attributes. The list excludes attributes that are expected to differ between definitions in the same group in the same CICS configuration. For example, transactions are expected to use different programs, and files can refer to different data sets. The PARTIAL algorithm is predetermined by CICS Configuration Manager .
To see which attributes are on the partial list for a resource type, use the CHECKSUM LIST command in the TSO/ISPF dialog.
- Display a list panel of resource definitions.
- Specify a resource type in the filter field above the Type column.
- Enter CHECKSUM LIST on the command line.
The Checksum PARTIAL column displays "On" for each attribute on the partial list.
- CRITICAL
A list of attributes that excludes those that are not critical to the operation of the CICS resource. For example, DESCRIPTION is excluded and, for some CICS resource types, NAME is excluded. The CRITICAL algorithm is predetermined by CICS Configuration Manager.
- CCVXCRCn (where n is 1 -
9)
For the CCVXCRCn option to work, you need a program of the same name that specifies the attributes to exclude from the checksum algorithm. For example, if CHECKSUM is set to CCVXCRC1, you need a program called CCVXCRC1. In the sample library SCCVSAMP, see member CCVXCRC$ for information about how to create a checksum algorithm program.
- FULL
- 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.
- TYPE (for PHASE=REPORT)
- The type of deployment analysis report that you want to produce:
- COLDSTARTCOMPARE
- CANDIDATESCOMPARE
- RUNTIMECOMPARE
- RUNTIME
- CANDIDATES
- CHECK
CICSDEFSCOMPARE
For a description of each type of deployment analysis report, see Table 1.
Security key
API command (READ access authority):
>>-prefix.DEP.-+-COLLECT.CCONFIG.CICS_configuration-+---------->< '-REPORT.NONE.NONE-------------------'
You can use the security key to restrict who can collect data from particular CICS configurations, and who can request deployment analysis reports.
For information on using security keys, see Restricting access to API commands and resource definitions.