Preparing the CSD

If you are updating an existing, shared CSD, you must first prepare the CSD by running DFHCSDUP with a prepare commands file. The commands in the prepare commands file remove resources from any groups that will subsequently be updated by the CICS® TS resource builder DFHSCSDUP commands file. By running a DFHCSDUP program with the prepare commands file before the DFHCSDUP program is run with the DFHCSDUP commands file, updates to the resources in the CSD can be applied repeatedly. You create the prepare commands file with the CICS TS resource builder zrb build command. The file contains only DFHCSDUP DELETE commands.

Role icon System programmer

Important icon Resources defined through CICS TS resource builder must be added to groups that are exclusively used for resources that are defined by CICS TS resource builder. The resources cannot belong to a group that contains resource definitions that are created by other means, for example by the CICS CEDA transaction. By running DFHCSDUP with the prepare commands file, the groups that are used by the application resources that are defined by the CICS TS resource builder are put into a known empty state. Specifically, groups that are referenced in the resource definitions YAML, and any resources that they contain, are deleted.

The zrb build command creates the DFHCSDUP files in the default platform encoding. When you run DFHCSDUP with the file on z/OS®, it must be in in IBM®-037 character encoding. Depending on the configuration of the system on which you run the command, the default platform encoding might not be IBM-037. If your file has a different encoding, you must convert it.

Your actions are:

Running zrb build to build the prepare commands file

Use the zrb build command with the --prepare option. You provide the following information as input:

  • File path of the YAML file that contains the resourceModel YAML (the resource model file)
  • Optionally, file path of the YAML file that contains the application YAML, if this is not contained in the resource model file (the application constraints file)
  • File path of the YAML file that contains the resourceDefinitions YAML (the resource definitions file) from the application developer.
  • File path to the location where you want the output files.

For the syntax of the zrb build command, run zrb build --help or see zrb command syntax. See the following examples of the command in action.

zrb build --model <model file path> [--application <application constraints file path>] --resources <resources file path> --output <filepath to the DFHCSDUP commands file> --prepare <filepath to the prepare commands file>

As output, you get two files:

  • DFHCSDUP commands file with the name and location that you specified
  • prepare commands file with the name and location that you specified

The following example shows excerpts from the DFHCSDUP commands file and the prepare commands file from the CICS TS resource builder zrb build command. The DFHCSDUP commands file defines two programs in group WEBAPP:

DEFINE PROGRAM(APSERV01) GROUP(WEBAPP)
      RELOAD(NO) RESIDENT(NO) USAGE(NORMAL) USELPACOPY(NO)
      STATUS(ENABLED) RSL(0) CEDF(YES) DATALOCATION(ANY) EXECKEY(USER)
      CONCURRENCY(QUASIRENT) API(CICSAPI) DYNAMIC(NO)
      EXECUTIONSET(FULLAPI) JVM(NO) HOTPOOL(NO)

DEFINE PROGRAM(APSERV02) GROUP(WEBAPP)
      RELOAD(NO) RESIDENT(NO) USAGE(NORMAL) USELPACOPY(NO)
      STATUS(ENABLED) RSL(0) CEDF(YES) DATALOCATION(ANY) EXECKEY(USER)
      CONCURRENCY(QUASIRENT) API(CICSAPI) DYNAMIC(NO)
      EXECUTIONSET(FULLAPI) JVM(NO) HOTPOOL(NO)

To prepare the existing CSD for the new resource definitions, the prepare commands file contains a command to delete all resources from the group WEBAPP and remove the group from any lists that contain it:

DELETE ALL GROUP(WEBAPP) REMOVE

For more information about the zrb build command, run zrb build --help or see zrb command syntax.

Next steps

See Updating CICS resources for information about running DFHCSDUP with commands files from CICS TS resource builder. First you run DFHCSDUP with the prepare commands file. Then you run DFHCSDUP again with the DFHCSDUP commands file.

In the following example, the prepare commands file that is built by the zrb build command is used as input to the DFHCSDUP utility. In this example, the prepare commands file output from the zrb build command is in a z/OS UNIX System Services file space /u/userx/applications/prepare.csdup:

//CSDPREP  JOB MSGCLASS=H,MSGLEVEL=(1,1),
//         CLASS=A,NOTIFY=USERX,REGION=4M
//STEP1    EXEC PGM=DFHCSDUP,REGION=0M,
//         PARM='CSD(READONLY),PAGESIZE(60),NOCOMPAT'
//STEPLIB  DD DSN=CICS.TS.SDFHLOAD,DISP=SHR
//DFHCSD   DD DISP=SHR,DSN=CICS.APPLICATIONS.DFHCSD
//outdd    DD SYSOUT=A
//SYSPRINT DD SYSOUT=A
//SYSIN    DD PATH='/u/userx/applications/prepare.csdup',
//         RECFM=F
//