DSN1 stand-alone utilities in DB2 for z/OS

Online utilities versus DSN1 programs

IBM calls COPY and RECOVER online utilities: they attach to Db2, take claims, and update SYSCOPY. Stand-alone utilities run independently of that control facility and are started only by JCL (or, for DSN1SDMP, a DSN RUN of the service aid). They are in the base utilities set—you do not need the Utilities Suite to execute them. DSNJU003/004 (BSDS) are related stand-alone tools but use the DSNJU prefix; this page stays on DSN1*.

Stop the table space (or be sure you understand fuzzy pages) before DSN1COPY overlays a VSAM cluster that Db2 might write. DSN1PRNT and DSN1COMP can often use DISP=SHR on a copy or a quiesced space. None of these programs replace a tested RECOVER job for production restore.

DSN1COPY

DSN1COPY copies pages from SYSUT1 to SYSUT2. Either DD can be a Db2 VSAM linear data set or a sequential image copy. Typical uses: restore a full copy onto a table space data set when RECOVER is not an option, move a space to another subsystem, or print selected pages. It does not write SYSCOPY and does not rebuild indexes.

OBIDXLAT is required when the target object IDs differ from the source. SYSXLAT records are pairs: source DBID then target DBID, source PSID then target PSID, then each table OBID pair. A practical trick: put 1 for unknown source IDs; DSN1COPY fails, prints the real source IDs, and you rerun. Target IDs come from SYSTABLESPACE.DBID/PSID and SYSTABLES.OBID on the receiving subsystem.

RESET clears log RBAs in data or index pages and the high-formatted page number in the header so the target is not married to the source log. Use it when the copy is landing in a different subsystem or after a point-in-time overlay. CHECK (also implied by OBIDXLAT and RESET) validates one page at a time—not cross-page structure. System pages are not checked. Specify PAGESIZE (4K, 8K, 16K, 32K), DSSIZE, LARGE, LOB, SEGMENT, PIECESIZ, and NUMPARTS so DSN1COPY interprets headers correctly. FULLCOPY without NUMPARTS tries the header; if that fails it assumes nonpartitioned.

1
2
3
4
5
6
7
8
9
10
//COPY    EXEC PGM=DSN1COPY,
//            PARM='CHECK,FULLCOPY,OBIDXLAT,RESET'
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD DISP=SHR,DSN=PAY.COPY.EMPTS.FULL(0)
//SYSUT2   DD DISP=OLD,DSN=DSNCAT.DSNDBD.PAYDB.EMPTS.I0001.A001
//SYSXLAT  DD *
0270,0284
0066,0058
0109,0205
/*

After a restore: REBUILD INDEX (the index VSAM was not copied unless you DSN1COPY each index space too), check pending states, and decide whether you need a new COPY so RECOVER has a SYSCOPY row that matches the pages you just laid down. INLCOPY requires SYSUT2 to be VSAM or DUMMY. Concurrent DFSMSdss copies are not valid FULLCOPY input.

DSN1COMP

DSN1COMP reads a table space (or a copy) and estimates how much DASD COMPRESS YES would save. It does not build a dictionary on the object and does not alter rows. You must pass geometry that matches the object: PAGESIZE, DSSIZE, and current FREEPAGE (0–255, default 0). Wrong values can produce nonsense percentages.

Default estimate is LOAD-style (dictionary built as LOAD would). REORG on the PARM switches to REORG-style full-record dictionary simulation, which usually tracks a later REORG COMPRESS more closely. REORG is not valid for LOB spaces. Output includes dictionary pages required, rows used to build the dictionary, rows sampled for the estimate, and percent data pages saved. Sampling means the percentage is an estimate, not a guarantee.

1
2
3
4
//COMP    EXEC PGM=DSN1COMP,
//            PARM='PAGESIZE(4K),DSSIZE(4G),FREEPAGE(0),REORG'
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD DISP=SHR,DSN=DSNCAT.DSNDBD.PAYDB.EMPTS.I0001.A001

DSN1LOGP

DSN1LOGP is the recovery-log extractor. It formats log records from active or archive logs into SUMMARY or DETAIL reports. Use it to see what happened to a page, a UR, or an object between two RBAs (non-data sharing) or LRSNs (data sharing). Filter with DBID, OBID, PAGE, and range start/end. Archive logs on tape are supported; do not extract an active log that the live subsystem is currently writing.

For clone objects, determine the correct PSID (base versus clone) before you filter or you will read the wrong page-set’s log. DSN1LOGP does not apply log—that is RECOVER. It only prints. Huge unfiltered DETAIL jobs can flood SYSPRINT; start with SUMMARY and a tight RBA/LRSN window.

1
2
3
4
5
6
7
8
9
//LOGP    EXEC PGM=DSN1LOGP
//SYSPRINT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//SYSSUMRY DD SYSOUT=*
//SYSIN    DD *
  RBASTART(C1A2B3C4D5E6)
  RBAEND(C1A2B3C4FFFF)
  SUMMARY
/*

DSN1PRNT

DSN1PRNT prints hexadecimal and optionally formatted dumps of pages in a table space, index space, or image copy. Prefer it over DSN1COPY PRINT when you only need a dump: the PARM set is aimed at printing (FORMAT, page ranges, VALUE to search for a string or hex pattern). You must get PAGESIZE and data-set size right, just as with DSN1COPY. Use it to inspect a broken page IBM asked for, to confirm a compressed row layout, or to see a header page’s DBID/PSID before building SYSXLAT.

1
2
3
//PRNT    EXEC PGM=DSN1PRNT,PARM='FORMAT,PAGESIZE(4K)'
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD DISP=SHR,DSN=DSNCAT.DSNDBD.PAYDB.EMPTS.I0001.A001

DSN1SDMP

DSN1SDMP is a selective dump service aid. It starts Db2 traces, can write trace records to a sequential data set, and can force a dump when IBM-specified conditions occur. Mullins and IBM both say: run it when the Support Center tells you the options. You need authority to start and stop traces plus MONITOR1 or MONITOR2. Stopping or modifying the traces while DSN1SDMP is active follows IBM’s procedure for that incident—do not treat it as a general performance monitor (that is SMF, OMPE, or similar).

DSN1SMFP

DSN1SMFP reads SMF data sets that contain Db2 IFCID records and prints a formatted report. IBM documents record layouts for many IFCIDs (examples: IFCID 003 DDF location, 004/005 trace start/stop, 023–025 utility start/change/end, 106 system parameters, 140–142 audit). Use it when you have SMF dumped and need a Db2-oriented view without a full performance monitor. It does not start traces; -START TRACE and SMF collection must already have captured the records.

DSN1CHKR (discontinued)

Older manuals described DSN1CHKR as a catalog and directory verification utility. It has been obsolete since Db2 10 new-function mode. APAR PH64707 removed the DSN1CHKR load module on Db2 13; invoking it then fails with ABEND806-04 and REQUESTED MODULE DSN1CHKR NOT FOUND. Do not schedule it. Use CHECK DATA, CHECK INDEX, IBM catalog consistency queries, and Support-directed REPAIR DBD instead.

DSN1BPM (not a current IBM utility)

The Db2 12 Utility Guide stand-alone chapters are DSN1COMP, DSN1COPY, DSN1LOGP, DSN1PRNT, and DSN1SDMP, plus appendix DSN1SMFP. There is no DSN1BPM program in that set. Older diagnostic modules with similar names (for example DSN1BUFM and DSN1MAP) were later removed as unused code. For buffer-pool work use -DISPLAY BUFFERPOOL, -ALTER BUFFERPOOL, statistics traces, and IBM Support tools—not a fictional nightly DSN1BPM job.

Explain It Like I'm Five

Online utilities are librarians who use the official checkout desk (Db2). DSN1 tools are flashlights and photocopiers you take into the stacks. DSN1COPY photocopies a whole shelf onto another shelf—you must relabel the books (OBIDXLAT) if the new room uses different numbers. DSN1COMP guesses how much smaller the books would be if you used tiny writing (compression) without actually rewriting them. DSN1LOGP reads the diary. DSN1PRNT photographs one page. DSN1SDMP and DSN1SMFP are the fire-drill camera and the attendance sheet decoder that grown-ups from IBM tell you when to use. DSN1CHKR is a retired hall monitor. DSN1BPM is a name on an old checklist that does not match a tool in the current toolbox.

Exercises

1. Write DSN1COPY JCL to restore a FULLCOPY into PAYDB.EMPTS with OBIDXLAT and RESET. List the SQL you would use to fill SYSXLAT target IDs.
2. Why must you REBUILD INDEX after DSN1COPY of a table space but not after RECOVER TABLESPACE INDEX ALL?
3. Run through DSN1COMP PARMs you would set for a 32K-page PBG with FREEPAGE 20, and say when you would add REORG.
4. A teammate wants a weekly DSN1CHKR job on Db2 13. What do you tell them, and what do you run instead?
5. Contrast DSN1LOGP SUMMARY for one RBA range with REPORT RECOVERY for the same object—what question does each answer?