CXXCLONE (Clone Environment)

The main purpose of the CXXCLONE function is to help you clone an environment to a new environment that is modeled after an existing environment.
datacom
The main purpose of the CXXCLONE function is to help you clone an environment to a new environment that is modeled after an existing environment.
The following topics are discussed on this page:
 
 
When to Use CXXCLONE
Use the CXXCLONE function when you want to clone an environment to a new environment that is modeled after an existing environment.
The CXXCLONE function, depending on the options specified, can restore one database, a range of databases, or a list with any combination of databases and ranges. Alternately, if no database ID is specified, every database of input is added to the current CXX.
Consider the following example. If you had an environment named TEST5, and you had a reason for needing another environment you decided to name TEST6, one step in the creation of the new environment would be to build a TEST6 CXX. In this case, using a LOAD AREA=CXX from a backup of the TEST5 CXX would leave every area in a loaded status and with the data set names from the TEST5 environment. The new TEST6 environment, however, needs its own data sets for every index and data area. Leaving all the areas in loaded status, and with the TEST5 data set names, risks that they might not get corrected and be used by both the TEST5 environment and the TEST6 environment, leading to a very large numbers of error conditions.
Using CXXCLONE to do CXX cloning avoids the problems just described because one strategy of using CXXCLONE is to set all the loaded tables to a status of not loaded and to do a deletion of all data set names. Using that capability, you can plan to create new data sets for the entire TEST6 environment during the initialize and load process. This is a safe approach, because the data for the loads can come from data backups of TEST5 data areas or elsewhere, such as the installation "clean" databases for system areas such as 
Datacom Datadictionary
 (usually databases 2 and 15).
Another general CXX cloning strategy is to copy all of the database data sets after building the new CXX. With this strategy, the data sets can be left loaded, but the data set names need to be altered from TEST5 to TEST6, or they should be deleted and the new names established using the DBUTLTY function CXXMAINT with OPTION=ALTER and DSN=. Also with this strategy, the data sets need to be updated to be "linked" to the new CXX named TEST6, and this is done with the DBUTLTY function LINK.
The DBUTLTY CXXCLONE function is similar to the LOAD AREA=CXX function of DBUTLTY in that it accepts a backup of a Directory (CXX) as an input data set and loads that data to an output CXX. But CXXCLONE and LOAD AREA=CXX are different in the following ways:
  • CXXCLONE provides potentially useful options not available with LOAD. When you are not just restoring a backup of a CXX to the same CXX, CXXCLONE provides options you can use to make changes during the load.
     If your goal is to make the CXX larger by doing a backup, we recommend that you use an INIT and a LOAD, using LOAD AREA=CXX.
  • By using the STATUS= keyword of CXXCLONE, you can choose how you want the loaded status handled. But when using a LOAD, if the database being loaded does not exist, the tables are set as not loaded and, if it exists, the status is left unchanged (usually loaded).
  • CXXCLONE allows input of a CXX of the same release or a CXX of the prior release. The LOAD function requires as input a backup of the same release as itself. CXXCLONE therefore supports a function similar to the DBUTLTY function CXXMAINT OPTION=CONVERT1214 but with the additional options detailed in the following syntax diagrams and descriptions.
 A CXX load done using CXXCLONE is treated by External Security the same as a LOAD AREA=CXX and therefore uses LOAD.CXX (full load, no table rights) or LOAD.CXXBASE (DBID(s) specified, CATALOG DTUTIL table rights).
 
Using CXXCLONE in the SIMPLIFY Mode
 
When using SIMPLIFY mode, when no DBID is specified the function is required to execute with the MUF not enabled. It requires that the CXX has just been initialized with the INIT function.
When at least one DBID is specified, the function expects to execute using the MUF, and all access to the CXX is controlled by and done by the MUF. However, the function might execute with the MUF not enabled and byopening and using the using the CXX in this address space, if the CXX is protected by either having this function follow a previous function that must run with MUF not enabled (such as INIT AREA=CXX), or having the MUF declared down using a function SET OPTION1=MUF_NOT_ENABLED. It is also possible to follow a function SET OPTION=MUF_ENABLED_OR_DISABLED that indicates the function should run with MUF if enabled or without MUF using a CXX locally.
 
Using CXXCLONE when not in the SIMPLIFY Mode
 
When not in the SIMPLIFY mode, CXXCLONE executes similarly to the LOAD function with AREA=CXX, in that it executes without the MUF using the CXX locally, if no DBID is specified, and with MUF and not any CXX locally, if a DBID is specified.
How to Use CXXCLONE
There are four varieties of the CXXCLONE function of DBUTLTY.
 
CXXCLONE 
case1
 Syntax
 
Following is a syntax diagram for the CXXCLONE function of DBUTLTY that executes with:
  • a DBID
  • a new DBID
  • a data set name that is either kept or deleted
►► CXXCLONE DBID=dbid,NEWDBID=newdbid,OPTION=┬ DELETE ┬,DDNAME=ddname─► └ KEEP ┘ ►──,STATUS=┬ NOT_LOADED ┬────────────────────────────────────────────►◄ └ NO_CHANGE ┘
 
CXXCLONE 
case2
 Syntax
 
Following is a syntax diagram for the CXXCLONE function of DBUTLTY that executes with:
  • a DBID
  • a new DBID
  • data set name alterations
►► CXXCLONE DBID=dbid,NEWDBID=newdbid,OPTION=ALTER,DDNAME=ddname,─────► ►─,STATUS=┬ NOT_LOADED ┬─,OPTION2=
x
*y────────────────────────────────►◄ └ NO_CHANGE ┘
 
CXXCLONE 
case3 
Syntax
 
Following is a syntax diagram for the CXXCLONE function of DBUTLTY that executes with:
  • an optional DBID
  • no new DBID
  • a data set name that is either kept or deleted
►► CXXCLONE ─┬────────────────┬─ OPTION=┬ DELETE ┬,DDNAME=ddname──────► │┌──────────────┐│ └ KEEP ┘ └▼─ DBID=dbid, ─┴┘ ►──,STATUS=┬ NOT_LOADED ┬────────────────────────────────────────────►◄ └ NO_CHANGE ┘
 
CXXCLONE 
case4
 Syntax
 
Following is a syntax diagram for the CXXCLONE function of DBUTLTY that executes with:
  • an optional DBID
  • no new DBID
  • data set name alterations
►► CXXCLONE ─┬────────────────┬─ OPTION=ALTER,DDNAME=ddname───────────► │┌──────────────┐│ └▼─ DBID=
dbid
, ─┴┘ ►─,STATUS=┬ NOT_LOADED ┬─,OPTION2=
x
*y────────────────────────────────►◄ └ NO_CHANGE ┘
 
Keyword Descriptions
 
  •  
    DBID=
    dbid
     
    (Required: case1 and case2) 
    The 
    dbid 
    in DBID
    =dbid 
    in 
    case1 
    and
     case2 
    syntax
     
    is a single database ID, that is, you can only specify one DBID, not a range of DBIDs in 
    case1 
    and
     case2 
    syntax.
    (Optional: case3 and case4) 
    If a DBID= is specified in 
    case3 
    and
     case4 
    syntax, it can be specified as a single database ID or a range of database IDs, for example DBID=4-5. Also, if you specify DBID=, you can specify more than one occurrence, for example DBID=4,DBID=5,...DBID=
    n
    .
    If
     
    DBID= is omitted in 
    case3 
    and
     case4 
    syntax, every database of input is added to the current CXX.
  •  
    DDNAME=
    ddname
     
    (Required) 
    The 
    ddname
     in DDNAME=
    ddname 
    is a one to eight (1-8) character DD name that points to a CXX backup for either Version 14.0 or Version 12.0.
    A DDNAME is not acceptable
     
    for sequential input or output files if it is a name reserved for a 
    Datacom
     area. Names with the following patterns are therefore not acceptable for DDNAME=:
  • 3-byte names that end with XX, meaning they are reserved as either current or future 
    Datacom
     control areas.
  • 6-byte names that end with what could be a database ID from 001 through 999.
  • 7-byte names that end with what could be a database ID from 1000 through 9999.
    The DDNAME= value is verified for acceptability to protect you from unintentionally causing data corruption. The DDNAME check is the default but optional. For information about how to disable the edit, see the note about DDNAME= check protection that follows.
    The data corruption risk involves not the DDNAME itself but the content of the data set. For example, suppose that you used the CXX DDNAME as the output of a backup. You then copied the CXX DD statement and changed the DDNAME of the copy to be acceptable, avoiding the DDNAME= error. The backup would, however, then overlay the CXX data set, which is not the intent of a backup.
    If you specify an unacceptable name for DDNAME=, message DB10059E is generated. 
     We recommend that you allow DDNAME= check protection. You can, however, disable DDNAME= protection. To disable protection, assemble the DBSIDPR module used for this 
    Datacom
     environment and specify NONE for the DBUTLTY_EDIT_DATA_SET= parameter. The default is DBUTLTY_EDIT_DATA_SET=FULL_1, which allows DDNAME= protection.
  •  
    NEWDBID=
    newdbid
     
    (Required: case1 and case2) 
    The NEWDBID= keyword can only be used in 
    case1 
    and
     case2 
    syntax. Use NEWDBID= to add (load) to the CXX being used by the current execution of DBUTLTY a single database with a database ID different from the one specified with DBID=. Therefore, the 
    newdbid 
    in NEWDBID
    =newdbid 
    is a single database ID, that is, you can only specify one new database ID, not a range of database IDs.
  •  
    OPTION=
    (Required) 
    The OPTION= keyword allows you to specify KEEP to keep the data set name from the input without changing It, DELETE to cause the data set name to be set to blanks (spaces), or ALTER to use the OPTION2= keyword (see following) to alter the data set name.
  •  
    OPTION2=
    x
    *
    y
     
    (Required: case2 and case4)
     The OPTION2= keyword is required (and only allowed) when OPTION=ALTER (see previous) is specified. The OPTION2= value allows you to specify a data set name string (comprised of a set of contiguous bytes), where the string (represented by 
    x
     in the syntax diagram) is followed by a single asterisk (*), followed by a replacement string, being a second set of a contiguous bytes (indicated by 
    in the syntax diagram). The combination of the keyword OPTION2= and its value must fit on a single input statement as is standard for DBUTLTY. This option is useful to those users following a best practice of having the CXX name within each data set within a database or the full CXX.
    For example, a user cloning a CXX named MUF6 to be replaced by one named MUF007 would specify OPTION2=MUF6*MUF007. However, if a single string is not in every data set name present, then OPTION=ALTER cannot be used, in which case we recommend using OPTION=DELETE to remove the data set names and force each data set to be initialized, where the appropriate data set name can then be specified as part of that process. The 
    x
     value can be longer or shorter or the same as the 
    y
     value, but if the resulting data set name is longer than 44 bytes, the function fails immediately with error message DB13285E and leaves the database not processed at all or only partially processed. The function also fails immediately with error message DB13284E if the expected string is not present in each and every data set name provided by the input, including every index area and every data area with a known DSN (not blanks), for example where the CXX name is not used as part of data set names for all areas.
  •  
    STATUS=
     
     
    (Required) 
    The STATUS= keyword is used to force the areas that are loaded to the CXX to either have the LOADED status of not loaded or allow the status to remain the same as the input. For that purpose, STATUS= can be specified as NOT_LOADED or NO_CHANGE.
     
    Note: 
    If STATUS=NOT_LOADED is specified, every table is set as not loaded, the index is set as not loaded, and the index areas and data areas are set as not initialized.
Examples
 
Example 1:
 
Build a test copy of production full CXX setting tables as not loaded and removing all data set names.
  1. Using the production CXX DD statement:
    BACKUP AREA=CXX,DDNAME=x
  2. Using the new test CXX DD statement:
    INIT AREA=CXX,DDNAME=x,DATACOM=x,CXXNAME=TEST CXXCLONE DDNAME=x,STATUS=NOT_LOADED,OPTION=DELETE
 
Example 2:
 
Build a full copy of production including CXX and all other data sets.
  1. Using the Production CXX DD statement:
    BACKUP AREA=CXX,DDNAME=x
  2. Using the new test CXX DD statement:
    INIT AREA=CXX,DDNAME=x,DATACOM=x,CXXNAME=TEST2 CXXCLONE DDNAME=x,STATUS=NO_CHANGE,OPTION=ALTER,OPTION2=PROD*TEST2
  3. Use IEBGENER to copy all data sets not the CXX to copies where the data set name in production of PROD is replaced by TEST2.
    The report provides a list of bases that were processed, such as:
    CXXCLONE DDNAME=X,DBID=497-697,DBID=797,STATUS=NO_CHANGE,OPTION=DELETE BASE PROCESSED - 497 BASE PROCESSED - 597 BASE PROCESSED - 697 BASE PROCESSED - 797 REQUEST COMPLETE
In addition to CXXCLONE, the BASE PROCESSED information has been added to the following functions:
  • BACKUP AREA=CXX
  • LOAD AREA=CXX
  • CXXMAINT OPTION=CONVERT1214
  • CXXMAINT OPTION=CONVERT1412
 The ability to use CXXCLONE or LOAD AREA=CXX with multiple occurrences of DBID= (including the use of ranges) are expected to be rare requirements, and the input file is processed from the start to the DBID= value for every candidate database. For example, whether the databases exist in the range or not, DBID=51-100 is processed by the input file 50 times.
If a NEWDBID= keyword is used in an execution of the CXXCLONE function, the additional information is also printed as shown in the following example report line:
BASE PROCESSED - 6 NEW DBID - 4,007
Example JCL (CXXCLONE)
The following shows the use if the CXXCLONE command.
 Use the following as a guide to prepare your JCL. The JCL statements are for example only. Lowercase letters in a statement indicate a value you must supply. Code all statements to your site and installation standards. It is also possible that the CXX DD statement might need to be added for some combination of options.
//jobname
See the previous note
.
// EXEC PGM=DBUTLTY,REGION=0M //STEPLIB
See the previous note
.
//Z DD DSN=cxx.bkup,DISP=(,CATLG), CXX backup data set //SYSIN DD * Command Input CXXCLONE DDNAME=Z,STATUS=NO_CHANGE,OPTION=KEEP /*
Sample Report
Following is a sample report page. For an example report header, see Sample Report Headers.
 
Sample Report 1
 
Following is a sample report when the command is:
CXXCLONE DDNAME=Z,STATUS=NO_CHANGE,OPTION=KEEP
CONTROL CARD(S) .........1.........2.........3.........4.........5.........6.........7.........8 CXXCLONE DDNAME=Z,STATUS=NO_CHANGE,OPTION=KEEP FUNCTION=CXXCLONE DDNAME=Z OPTION=KEEP STATUS=NO_CHANGE BACKUP FILE INFORMATION JOBNAME RUN UNIT DATE TIME CXXNAME DBID DATACOM VERSION DBDVL 22,943 2010/12/03 07.57.30 DBDVM0 DB 14.0 BASE PROCESSED - 2 BASE PROCESSED - 6 BASE PROCESSED - 15 BASE PROCESSED - 16 BASE PROCESSED - 17 BASE PROCESSED - 97 BASE PROCESSED - 197 BASE PROCESSED - 297 BASE PROCESSED - 397 BASE PROCESSED - 497 BASE PROCESSED - 597 BASE PROCESSED - 697 BASE PROCESSED - 796 BASE PROCESSED - 797 BASE PROCESSED - 897 BASE PROCESSED - 997 BASE PROCESSED - 1,000 BASE PROCESSED - 1,006 BASE PROCESSED - 1,007 BASE PROCESSED - 2,009 * REQUEST COMPLETE
 
Sample Report 2
 
Following is a sample report when the command is:
CXXCLONE DDNAME=Z,STATUS=NOT_LOADED,OPTION=DELETE
CONTROL CARD(S) .........1.........2.........3.........4.........5.........6.........7.........8 CXXCLONE DDNAME=Z,STATUS=NOT_LOADED,OPTION=DELETE FUNCTION=CXXCLONE DDNAME=Z OPTION=DELETE STATUS=NOT_LOADED BACKUP FILE INFORMATION JOBNAME RUN UNIT DATE TIME CXXNAME DBID DATACOM VERSION DBDVL 22,943 2010/12/03 07.57.30 DBDVM0 DB 14.0 BASE PROCESSED - 2 BASE PROCESSED - 6 BASE PROCESSED - 15 BASE PROCESSED - 16 BASE PROCESSED - 17 BASE PROCESSED - 97 BASE PROCESSED - 197 BASE PROCESSED - 297 BASE PROCESSED - 397 BASE PROCESSED - 497 BASE PROCESSED - 597 BASE PROCESSED - 697 BASE PROCESSED - 796 BASE PROCESSED - 797 BASE PROCESSED - 897 BASE PROCESSED - 997 BASE PROCESSED - 1,000 BASE PROCESSED - 1,006 BASE PROCESSED - 1,007 BASE PROCESSED - 2,009 * REQUEST COMPLETE
 
Sample Report 3
 
Following is a sample report when the command is:
CXXCLONE DDNAME=Z,STATUS=NOT_LOADED,OPTION=ALTER,OPTION2=DBDVM0*DBDVM7
CONTROL CARD(S) .........1.........2.........3.........4.........5.........6.........7.........8 CXXCLONE DDNAME=Z,STATUS=NOT_LOADED,OPTION=ALTER, OPTION2=DBDVM0*DBDVM7 FUNCTION=CXXCLONE DDNAME=Z OPTION=ALTER OPTION2=DBDVM0*DBDVM7 STATUS=NOT_LOADED BACKUP FILE INFORMATION JOBNAME RUN UNIT DATE TIME CXXNAME DBID DATACOM VERSION DBDVL 22,943 2010/12/03 07.57.30 DBDVM0 DB 14.0 BASE PROCESSED - 2 BASE PROCESSED - 6 BASE PROCESSED - 15 BASE PROCESSED - 16 BASE PROCESSED - 17 BASE PROCESSED - 97 BASE PROCESSED - 197 BASE PROCESSED - 297 BASE PROCESSED - 397 BASE PROCESSED - 497 BASE PROCESSED - 597 BASE PROCESSED - 697 BASE PROCESSED - 796 BASE PROCESSED - 797 BASE PROCESSED - 897 BASE PROCESSED - 997 BASE PROCESSED - 1,000 BASE PROCESSED - 1,006 BASE PROCESSED - 1,007 BASE PROCESSED - 2,009 * REQUEST COMPLETE
 
Sample Report 4
 
Following is a sample report when the command is:
CXXCLONE DDNAME=Z,STATUS=NOT_LOADED,NEWDBID=998,DBID=997,OPTION=ALTER,OPTION2=DEV*QA
CONTROL CARD(S) .........1.........2.........3.........4.........5.........6.........7.........8 CXXCLONE DDNAME=Z,STATUS=NOT_LOADED,NEWDBID=998,DBID=997, OPTION=ALTER,OPTION2=DEV*QA FUNCTION=CXXCLONE DBID=00997 DDNAME=Z NEWDBID=00998 OPTION=ALTER OPTION2=DEV*QA STATUS=NOT_LOADED BACKUP FILE INFORMATION JOBNAME RUN UNIT DATE TIME CXXNAME DBID DATACOM VERSION DBDVL 22,943 2010/12/03 07.57.30 DBDVM0 DB 14.0 BASE PROCESSED - 997 NEW DBID - 998 * REQUEST COMPLETE