cheat sheet
DFSMShsm
Migrate, recall, back up, and recover datasets across ML0/ML1/ML2 tiers with TSO H-commands and ARC operator commands; bulk-recall recipes, recall timing, and audit messages.
DFSMShsm — Hierarchical Storage Manager
What it is
DFSMShsm (Data Facility Storage Management Subsystem — hierarchical storage manager) is IBM's z/OS storage manager that migrates inactive datasets off primary DASD to cheaper tiers and recalls them on demand, while also driving the dataset backup and disaster-recovery pipelines. End users drive it from TSO with the H* family of commands (HMIGRATE, HRECALL, HBACKDS, HRECOVER, HLIST, HBDELETE); operators and storage administrators drive it from the z/OS console with ARC* commands against the DFSMShsm address space (usually DFHSM). Reach for HSM when a job ABENDS with IEC161I 052-084 ("dataset migrated"), when you need to back up before a release, or when planning capacity — the alternative is doing the moves by hand with DFDSS/IDCAMS, which loses the automatic policy management that HSM provides.
Install
DFSMShsm ships with z/OS as part of DFSMS. There is no install — you verify the address space is running and that you have the authority to issue H* commands.
(* From TSO — check status *)
HSEND LIST HOST (* needs HSM operator authority *)
(* From z/OS console — check the started task *)
D A,DFHSM
F DFHSM,QUERY ACTIVE
Output:
IEE115I 10.30.40 2026.146 ACTIVITY
JOBNAME STEPNAME PROCSTEP CPU% STATUS
DFHSM DFHSM DFHSM 0.4 A=0042 PER=NO SMC=000
ARC0101I QUERY ACTIVE COMMAND COMPLETED
ARC0123I H1=DFHSM, ACTIVE PRIMARY HOST. NO CDS RECALLS WAITING
If HSEND returns ARC0163I PERMISSION DENIED, the security admin must grant your userid READ (issue commands) or UPDATE (modify CDS) in the FACILITY class profile STGADMIN.ARC.*.
Storage tiers — ML0, ML1, ML2
DFSMShsm partitions storage into three tiers, picked by automatic threshold policy or by the user's explicit migrate command. Knowing which tier a dataset lives on is the difference between a millisecond OPEN and a multi-minute tape recall.
| Tier | Media | Purpose | Typical recall time |
|---|---|---|---|
| ML0 | Primary DASD — SMS storage groups | Active datasets, default location | Immediate (already mounted) |
| ML1 | Secondary DASD — slower/older DASD or compressed pool | Recently-inactive datasets, fast tier-down | ~1–5 seconds |
| ML2 | Virtual or physical tape (TS7700) plus optional cloud/object | Long-term inactive | 30 s – several minutes (mount + position) |
| MLC | S3-compatible cloud object storage via DFSMS Cloud Data Manager (z/OS 3.1+) | Direct-access archive — replaces serial ML2 tape | Seconds (no tape mount, parallel reads) |
Cloud tiering (z/OS 3.1+): the IBM DFSMS Cloud Data Manager (DFSMScdm) introduces Migration Level Cloud (MLC), a new tier that holds migrated data on S3-compatible object storage. DFSMScdm can migrate existing ML2 (tape or virtual tape) datasets to MLC while preserving the migrate date and date-last-referenced metadata, and reduces MSU consumption by replacing serial tape access with direct cloud object reads. See the Sources for the IBM product page and migration guide.
HLIST DSN(ALICE.OLD.DATA) BOTH
Output:
ARC1102I LIST OF DATASET NAMES STARTING WITH ALICE.OLD.DATA
- DSNAME - VOLSER LEVEL
ALICE.OLD.DATA ARC013 ML2
ARC1100I LIST COMMAND COMPLETED
The LEVEL column above is the canonical "which tier" answer. ML0 means primary, ML1 means level-1 migration DASD, ML2 means level-2 (usually tape).
Essential TSO commands
| Command | Purpose |
|---|---|
HMIGRATE | Move a dataset down a tier (to ML1 or ML2) |
HRECALL | Bring a migrated dataset back to ML0 |
HBACKDS | Take a backup copy of an active dataset |
HRECOVER | Restore from an HSM backup |
HBDELETE | Delete an HSM backup version |
HLIST | Query HSM control dataset for status, history, versions |
HALTERDS | Change HSM attributes of a dataset (e.g., backup frequency) |
HSEND | Send any HSM operator command (for those with authority) |
Each of these has a short and a long form — HMIG, HREC, HBAC, HRCOV, HBDEL, HLST, HALT, HSND. Long form is shown below; short forms are valid on every command.
HMIGRATE — push a dataset off primary
HMIGRATE initiates a manual migration of a dataset that you no longer need on ML0 immediately. With no level keyword, HSM picks the tier based on management class; with ML2 you force migration straight past ML1 to tape.
HMIGRATE DSN(ALICE.PROJECT.OLDLOGS)
HMIGRATE DSN(ALICE.PROJECT.OLDLOGS) ML2
HMIGRATE DSN(ALICE.PROJECT.OLDLOGS) WAIT (* block TSO until migration complete *)
HMIGRATE DSN(ALICE.PROJECT.OLDLOGS) FORCEML2 (* skip CDS checks, force ML2 *)
Output:
ARC1101I MIGRATE REQUEST FOR DATASET 'ALICE.PROJECT.OLDLOGS' ACCEPTED FROM
ARC1101I (CONT.) HOST=DFHSM, REQUEST NUMBER=00012345
For bulk migration of an entire qualifier tree, queue one request per dataset from a CLIST/REXX driver — HSM rate-limits internally, so issuing 5,000 requests at once is safe.
HMIGRATE DSN(ALICE.*) ML2
Output:
ARC1101I MIGRATE REQUEST FOR DATASET 'ALICE.PROJECT.OLDLOGS' ACCEPTED ...
ARC1101I MIGRATE REQUEST FOR DATASET 'ALICE.OLD.DATA' ACCEPTED ...
ARC1101I MIGRATE REQUEST FOR DATASET 'ALICE.SCRATCH.WORK' ACCEPTED ...
Wildcard scope: the pattern is matched against catalog entries, not against HSM's CDS, so already-migrated datasets are not re-migrated. Mass migration is idempotent.
HRECALL — bring a dataset back
HRECALL issues an explicit recall request. The most common reason to issue it explicitly is staging recalls before a batch job so the job itself does not wait — the OPEN of a migrated dataset in JCL will implicitly recall it, but that recall happens inline and stretches elapsed time. Pre-recalling moves the wait outside the job's wall-clock window.
HRECALL DSN(ALICE.PROJECT.OLDLOGS)
HRECALL DSN(ALICE.PROJECT.OLDLOGS) WAIT
HRECALL DSN(ALICE.PROJECT.OLDLOGS) FORCENONSMS (* recall to non-SMS volume *)
HRECALL DSN(ALICE.PROJECT.OLDLOGS) UNIT(SYSDA) (* override target unit *)
Output:
ARC1024I RECALL REQUEST FOR DATASET 'ALICE.PROJECT.OLDLOGS' ACCEPTED FROM
ARC1024I (CONT.) HOST=DFHSM, REQUEST NUMBER=00012346
ARC1020I 'ALICE.PROJECT.OLDLOGS' RECALL COMPLETE
Recall queue behaviour — three messages tell the story:
| Message | Meaning |
|---|---|
ARC1024I ... ACCEPTED | Recall queued in the CDS |
ARC1023I ... STARTED | HSM has begun mounting/reading |
ARC1020I ... RECALL COMPLETE | Dataset is back on ML0 and OPEN-able |
ARC0584I PROCESSING DELAYED | Tape drive busy or CDS contention — retry will succeed |
ARC1001I ... DATA SET NOT MIGRATED | Already on ML0; recall is a no-op |
ARC1100I ... NOT IN CDS | Dataset is not known to HSM (typo, scratched) |
HBACKDS — back up a dataset
HBACKDS creates an HSM-managed backup version on backup-DASD or tape. HSM maintains a configurable number of versions per dataset; the newest is version 1, older versions slip to higher numbers as new backups roll in.
HBACKDS 'ALICE.PAYROLL.DATA'
HBACKDS 'ALICE.PAYROLL.DATA' WAIT
HBACKDS 'ALICE.PAYROLL.DATA' NEWNAME(ALICE.PAYROLL.PREREL01) (* alias for the backup *)
HBACKDS 'ALICE.PAYROLL.DATA' RETAINDAYS(90) (* override mgmtclass *)
Output:
ARC1300I BACKUP REQUEST FOR DATASET 'ALICE.PAYROLL.DATA' ACCEPTED FROM
ARC1300I (CONT.) HOST=DFHSM, REQUEST NUMBER=00012347
ARC1310I 'ALICE.PAYROLL.DATA' BACKUP COMPLETE, VERSION=001
Backup versions are visible with HLIST ... BCDS (see HLIST section). To suppress automatic backup of a particular dataset entirely:
HALTERDS 'ALICE.SCRATCH.WORK' FREQUENCY(0)
Output:
ARC0250I HALTERDS COMMAND COMPLETED, DSNAME=ALICE.SCRATCH.WORK
HRECOVER — restore from backup
HRECOVER rebuilds a dataset from an HSM backup version. With no VERSIONS() parameter you get version 1 (most recent). You can recover to a new name to preserve the current copy on disk.
HRECOVER 'ALICE.PAYROLL.DATA'
HRECOVER 'ALICE.PAYROLL.DATA' VERSIONS(2) (* second-newest version *)
HRECOVER 'ALICE.PAYROLL.DATA' NEWNAME(ALICE.PAYROLL.PRIOR)
HRECOVER 'ALICE.PAYROLL.DATA' REPLACE (* overwrite existing copy *)
HRECOVER 'ALICE.PAYROLL.DATA' DATE(2026/05/24) (* version active on date *)
HRECOVER 'ALICE.PAYROLL.DATA' GENERATION(0001V00) (* specific GDG generation *)
Output:
ARC1400I RECOVER REQUEST FOR DATASET 'ALICE.PAYROLL.DATA' ACCEPTED FROM
ARC1400I (CONT.) HOST=DFHSM, REQUEST NUMBER=00012348
ARC1410I 'ALICE.PAYROLL.DATA' RECOVER COMPLETE, VERSION=001
HRECOVER is the only way to restore a dataset that has been physically scratched — it pulls metadata from the BCDS rather than the catalog. If even the BCDS entry has aged out, the dataset is lost.
HBDELETE — remove a backup version
HBDELETE removes a specific backup version from the BCDS. Use this to free backup pool space, to enforce a destruction policy, or to drop a known-bad backup before it is selected on recover.
HBDELETE 'ALICE.PAYROLL.DATA' VERSIONS(3 4 5)
HBDELETE 'ALICE.PAYROLL.DATA' DATE(2026/01/01) (* delete by date *)
HBDELETE 'ALICE.PAYROLL.DATA' ALLEXCP (* keep newest, delete rest *)
Output:
ARC1331I 'ALICE.PAYROLL.DATA' BACKUP VERSION 003 DELETED
ARC1331I 'ALICE.PAYROLL.DATA' BACKUP VERSION 004 DELETED
ARC1331I 'ALICE.PAYROLL.DATA' BACKUP VERSION 005 DELETED
HLIST — query the CDS
HLIST reads HSM's control datasets (MCDS for migration metadata, BCDS for backup metadata, OCDS for offline tape catalog). It is the primary way to find out whether a dataset is migrated, when it was last backed up, and where the backup versions live.
HLIST DSN(ALICE.PROJECT.OLDLOGS) BOTH
HLIST DSN(ALICE.PROJECT.*) MCDS (* migration entries only *)
HLIST DSN(ALICE.PAYROLL.*) BCDS (* backup versions only *)
HLIST LEVEL(ALICE) MCDS (* every migrated DS under HLQ *)
HLIST DSN(ALICE.PAYROLL.DATA) BCDS OUTDATASET(ALICE.HLIST.OUT)
Output:
ARC1102I LIST OF DATASET NAMES STARTING WITH ALICE.PROJECT
- DSNAME - VOLSER LEVEL MIGRATED
ALICE.PROJECT.OLDLOGS ARC013 ML2 2026/04/02
ALICE.PROJECT.WORK1 ARC005 ML1 2026/05/14
ARC1100I LIST COMMAND COMPLETED
ARC1102I BACKUP DATASET LIST
- DSNAME - VER BACKUP DATE VOLSER
ALICE.PAYROLL.DATA 001 2026/05/24 DBKP01
ALICE.PAYROLL.DATA 002 2026/05/17 DBKP02
ALICE.PAYROLL.DATA 003 2026/05/10 DBKP02
ARC1100I LIST COMMAND COMPLETED
Useful HLIST keywords:
| Keyword | Reports |
|---|---|
BOTH | Migration and backup |
MCDS | Migration entries only |
BCDS | Backup versions only |
OCDS | Tape volumes used |
LEVEL(HLQ) | All datasets under a high-level qualifier |
DSN(pattern) | Exact or wildcard dataset names |
OUTDATASET(...) | Send list to a dataset rather than terminal |
OUTDD(ddname) | Send list to a DD-allocated dataset |
SELECT(NOMIGRATED) | Filter by status |
HALTERDS — change HSM attributes
HALTERDS updates the HSM-specific attributes on a dataset entry — backup frequency, change indicator, expiration. The base SMS classes (management/storage/data) are still owned by ACS routines; this command only flips HSM behaviour overrides.
HALTERDS 'ALICE.SCRATCH.WORK' FREQUENCY(0) (* never auto-backup *)
HALTERDS 'ALICE.IMPORTANT.DATA' FREQUENCY(1) (* back up every change *)
HALTERDS 'ALICE.PAYROLL.DATA' RETENTIONPERIOD(365)
HALTERDS 'ALICE.OLD.DATA' EXPIRATIONDATE(2027/12/31)
Output:
ARC0250I HALTERDS COMMAND COMPLETED, DSNAME=ALICE.SCRATCH.WORK
ARC0250I HALTERDS COMMAND COMPLETED, DSNAME=ALICE.IMPORTANT.DATA
SMS management classes and HSM thresholds
DFSMShsm cooperates with SMS — the management class assigned to a dataset by the ACS routines dictates how aggressively HSM will migrate and back it up. Without SMS, HSM falls back to volume-based ML0→ML1 thresholds set in ARCCMDxx.
| ACS class field | Meaning |
|---|---|
PRIMARY DAYS NON-USAGE | Days before primary→ML1 (e.g. 7) |
LEVEL 1 DAYS NON-USAGE | Days before ML1→ML2 (e.g. 60) |
COMMAND OR AUTO MIGRATE | Whether automigration is allowed |
# BACKUP VERSIONS DATA SET EXISTS | Versions retained while DS is active |
# BACKUP VERSIONS DATA SET DELETED | Versions retained after DS is deleted |
RETAIN DAYS ONLY BACKUP VERSION | Force-keep duration for the last copy |
Inspect a dataset's effective class:
LISTC ENT('ALICE.PAYROLL.DATA') ALL
Output:
NONVSAM ------- ALICE.PAYROLL.DATA
STORAGECLASS ---STANDARD MANAGEMENTCLASS-MCSTD30
DATACLASS ------DCFB80 CREATION--------2025.030
LAST BKUP-------2026.145 REFERENCE-------2026.146
STANDARD storage class + MCSTD30 management class. The names are site-defined — ask your storage admin for the policy of any class you depend on.
ARC operator commands — driving HSM from the console
Storage administrators issue ARC*-prefixed operator commands against the DFHSM started task. End users with HSEND authority can run the same commands from TSO.
(* From z/OS console *)
F DFHSM,QUERY ACTIVE
F DFHSM,QUERY WAITING
F DFHSM,QUERY REQUEST(00012345)
F DFHSM,QUERY CDS
F DFHSM,QUERY USER(ALICE)
F DFHSM,CANCEL REQUEST(00012345)
F DFHSM,HOLD MIGRATION
F DFHSM,RELEASE MIGRATION
F DFHSM,SETSYS BACKUP
F DFHSM,SETSYS NOBACKUP
F DFHSM,STOP
Output:
ARC0101I QUERY ACTIVE COMMAND COMPLETED
ARC0102I HOST=DFHSM, MIGRATION ACTIVE, RECALL TASKS=4, MIGRATE TASKS=2
ARC0103I HOST=DFHSM, BACKUP TASKS=2, DUMP TASKS=0, RECOVER TASKS=1
Common query targets:
QUERY ... | What it shows |
|---|---|
ACTIVE | Tasks currently running per function |
WAITING | Queue depth per function |
REQUEST(n) | Single request status by number |
CDS | Control dataset usage and contention |
USER(userid) | All requests submitted by a userid |
SETSYS | Effective configuration |
MWE (migration work element) | Internal queue snapshot |
Most-used HSEND equivalents from TSO:
HSEND QUERY ACTIVE
HSEND QUERY USER(ALICE)
HSEND CANCEL REQUEST(00012345)
HSEND DELETE ALICE.OLD.DATA (* uncatalog and scratch even if migrated *)
Output:
ARC0101I QUERY ACTIVE COMMAND COMPLETED
ARC0100I QUERY USER COMMAND COMPLETED
ARC0510I REQUEST 00012345 CANCELED BY USER ALICE
Common ARC messages — quick decoder
ARC* messages are the language of HSM. Memorising the most-frequent dozen lets you scan SYSLOG and JES messages at a glance.
| Message | Severity | Meaning |
|---|---|---|
ARC0584I | Info | Recall delayed — usually tape mount queue |
ARC1020I | Info | Recall complete |
ARC1021I | Warn | Recall failed — see secondary message |
ARC1024I | Info | Recall accepted |
ARC1101I | Info | Migrate accepted |
ARC1138I | Info | Migrate complete |
ARC1300I | Info | Backup accepted |
ARC1310I | Info | Backup complete |
ARC1400I | Info | Recover accepted |
ARC1410I | Info | Recover complete |
ARC1500I | Error | Generic HSM error — read text and code |
ARC0163I | Error | RACF denied |
ARC0167I | Error | Dataset already migrated/recalled — duplicate request |
IEC161I 052-084 | Error | Open failed because dataset is migrated; HSM auto-recall begins |
Recall delays in batch jobs
When a batch step opens a migrated dataset, HSM stages a synchronous recall. The job waits — sometimes for many minutes if ML2 tape is involved. To avoid surprising elapsed times, the operations team uses one of two patterns: pre-recall, or HSM-aware JCL.
Pre-recall with HRECALL WAIT
A REXX step or pre-job submits HRECALL ... WAIT for every dataset the next step will touch, blocking until the recall finishes.
//PRERECAL JOB (ACCT),'PRE-RECALL',CLASS=A,MSGCLASS=X,
// USER=ALICE
//STEP1 EXEC PGM=IKJEFT01,DYNAMNBR=20
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
HRECALL DSN(ALICE.PROJECT.OLDLOGS) WAIT
HRECALL DSN(ALICE.OLD.DATA) WAIT
HRECALL DSN(ALICE.PAYROLL.DATA) WAIT
/*
Output: (SYSTSPRT)
ARC1024I RECALL REQUEST FOR DATASET 'ALICE.PROJECT.OLDLOGS' ACCEPTED ...
ARC1020I 'ALICE.PROJECT.OLDLOGS' RECALL COMPLETE
ARC1024I RECALL REQUEST FOR DATASET 'ALICE.OLD.DATA' ACCEPTED ...
ARC1020I 'ALICE.OLD.DATA' RECALL COMPLETE
ARC1024I RECALL REQUEST FOR DATASET 'ALICE.PAYROLL.DATA' ACCEPTED ...
ARC1020I 'ALICE.PAYROLL.DATA' RECALL COMPLETE
Asynchronous batch recall
For larger batches, submit recalls without WAIT and poll HSEND QUERY USER for completion before the dependent step runs:
//ASYNCREC JOB (ACCT),'ASYNC RECALL',CLASS=A,MSGCLASS=X,
// USER=ALICE
//STEP1 EXEC PGM=IKJEFT01
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
HRECALL DSN(ALICE.PROJECT.OLDLOGS)
HRECALL DSN(ALICE.OLD.DATA)
HRECALL DSN(ALICE.PAYROLL.DATA)
/*
//STEP2 EXEC PGM=IKJEFT01,COND=(0,NE)
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
/* Wait for all recalls to complete *
HSEND QUERY USER(ALICE)
/*
Output: (SYSTSPRT — STEP2)
ARC0144I REQUEST 12350 RECALL ALICE.PROJECT.OLDLOGS WAITING
ARC0144I REQUEST 12351 RECALL ALICE.OLD.DATA RUNNING
ARC0144I REQUEST 12352 RECALL ALICE.PAYROLL.DATA COMPLETE
ARC0100I QUERY USER COMMAND COMPLETED
In production this loop typically calls REXX to parse the messages and only return RC=0 once every REQUEST line reports COMPLETE.
Auditing and reporting
HSM writes activity records to SMF (types 240–245 historically; modern systems use 245 for migration, 247 for recall, 263 for backup). The LIST and REPORT operator commands turn these into formatted reports.
F DFHSM,REPORT DAILY
F DFHSM,REPORT VOLUME(ARC013)
F DFHSM,LIST HOST(DFHSM) STATISTICS
F DFHSM,AUDIT MEDIACONTROLS VOLUMES(ARC013)
Output:
ARC0680I DAILY STATISTICS REPORT BEGINS
ARC0681I MIGRATIONS=00214 RECALLS=00087 BACKUPS=01205 RECOVERS=00012
ARC0681I BYTES MIGRATED=00012345678 BYTES RECALLED=00002345678
ARC0680I DAILY STATISTICS REPORT COMPLETE
End-user reporting is normally done by extracting the SMF records via IFASMFDP and then summarising with DFSORT/ICETOOL.
Common pitfalls
- Implicit recalls on tape elongate elapsed time — a 30-second tape mount inside the critical path of a 5-minute job is a 10% regression. Always pre-recall ML2 datasets before time-sensitive jobs.
HRECALLagainst a non-migrated dataset issuesARC0167I— harmless, but operators sometimes treat the warning as a failure. Either filter the message or checkHLISTfirst.- Wildcard
HMIGRATEon a live HLQ —HMIGRATE DSN(ALICE.*) ML2will happily migrate the dataset your next batch job needs. Use management-class policies, not wildcards, for routine tiering. - Backup expiry deletes the only copy — if
# BACKUP VERSIONS DATA SET DELETEDin the management class is0, scratching the dataset deletes its backup history immediately. Confirm withHLIST ... BCDSbefore anyDELETEon a critical dataset. - CDS contention during peak recall — symptom is
ARC0584I PROCESSING DELAYEDin bursts. The fix is on the storage admin side (more CDS extents or RLS); from the user side,HSEND QUERY CDSconfirms the cause andHRECALL ... WAITretries safely. - Forgetting
HALTERDS FREQUENCY(0)for scratch datasets — scratch/work files accumulate dozens of useless backup versions consuming tape. SetFREQUENCY(0)at allocation time or via an ACS routine. - Mixing
HRECOVERand SMS replacement —HRECOVER ... REPLACErebuilds the dataset using the original SMS classes from the backup metadata; if the classes have been retired, the recover fails withARC1410Iwarning text. UseNEWNAME(...)to land somewhere safe andIDCAMS REPROinto the current shape. - Tape stacking races — two simultaneous ML2 recalls to the same physical tape serialise on the drive.
HSEND QUERY WAITINGreveals the queue; considerRECALL ML0 RECONNECTpolicies for large datasets. - HSM not running — JCL
IEC161I 052-084keeps repeating withoutARCfollow-up ifDFHSMis down. Always checkD A,DFHSMfirst before diagnosing as a dataset problem.
Real-world recipes
Bulk-recall a list of migrated datasets ahead of a job
The night-batch window needs 47 archive datasets back on ML0 before STEP1 starts. Build a recall driver in REXX and submit it as the first job of the window.
(* ALICE.UTIL.REXX(BULKRECL) — REXX driver *)
/* REXX */
DSLIST = 'ALICE.UTIL.CNTL(BATCH47)'
"ALLOC DA('"DSLIST"') F(RECLIST) SHR REUSE"
"EXECIO * DISKR RECLIST (STEM L. FINIS"
"FREE F(RECLIST)"
DO I=1 TO L.0
DSN = STRIP(L.I)
IF DSN \= '' THEN ADDRESS TSO "HRECALL DSN('"DSN"') WAIT"
END
EXIT 0
The control file ALICE.UTIL.CNTL(BATCH47) is plain text — one dataset name per line:
ALICE.ARCH.JAN2025.LOG
ALICE.ARCH.FEB2025.LOG
ALICE.ARCH.MAR2025.LOG
... (47 lines total)
Invoke from JCL:
//BULKREC JOB (ACCT),'BULK RECALL',CLASS=A,MSGCLASS=X,USER=ALICE
//STEP1 EXEC PGM=IKJEFT01,DYNAMNBR=50
//SYSEXEC DD DSN=ALICE.UTIL.REXX,DISP=SHR
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
%BULKRECL
/*
Output: (SYSTSPRT, abbreviated)
ARC1024I RECALL REQUEST FOR DATASET 'ALICE.ARCH.JAN2025.LOG' ACCEPTED ...
ARC1020I 'ALICE.ARCH.JAN2025.LOG' RECALL COMPLETE
...
ARC1024I RECALL REQUEST FOR DATASET 'ALICE.ARCH.DEC2025.LOG' ACCEPTED ...
ARC1020I 'ALICE.ARCH.DEC2025.LOG' RECALL COMPLETE
If the window is short, drop the WAIT and add a closing HSEND QUERY USER(ALICE) loop that polls until all entries report COMPLETE.
Take an HSM-managed pre-release backup
Before a Friday release, take a known-good backup of three production datasets and tag the backups so they can be recovered by name.
HBACKDS 'ALICE.PAYROLL.DATA' NEWNAME(ALICE.PAYROLL.PREREL26)
HBACKDS 'ALICE.CUSTFILE.DATA' NEWNAME(ALICE.CUSTFILE.PREREL26)
HBACKDS 'ALICE.ORDERS.DATA' NEWNAME(ALICE.ORDERS.PREREL26)
HLIST DSN(ALICE.PAYROLL.DATA) BCDS
Output:
ARC1310I 'ALICE.PAYROLL.DATA' BACKUP COMPLETE, VERSION=001
ARC1310I 'ALICE.CUSTFILE.DATA' BACKUP COMPLETE, VERSION=001
ARC1310I 'ALICE.ORDERS.DATA' BACKUP COMPLETE, VERSION=001
ARC1102I BACKUP DATASET LIST
- DSNAME - VER BACKUP DATE ALIAS
ALICE.PAYROLL.DATA 001 2026/05/25 ALICE.PAYROLL.PREREL26
If a rollback becomes necessary:
HRECOVER 'ALICE.PAYROLL.DATA' REPLACE
Output:
ARC1410I 'ALICE.PAYROLL.DATA' RECOVER COMPLETE, VERSION=001
Migrate cold archive aggressively but never auto-backup it
A research workload generates 200 GB/day of intermediate logs under ALICE.LOG.*. Policy: keep on ML0 for 1 day, ML1 for 7 days, then ML2; never back it up.
HALTERDS 'ALICE.LOG.**' FREQUENCY(0) (* disable HSM backup for the family *)
HMIGRATE DSN(ALICE.LOG.*) ML1 (* push everything older than 1 day *)
Output:
ARC0250I HALTERDS COMMAND COMPLETED, DSNAME=ALICE.LOG.**
ARC1101I MIGRATE REQUEST FOR DATASET 'ALICE.LOG.2026.D140' ACCEPTED ...
ARC1101I MIGRATE REQUEST FOR DATASET 'ALICE.LOG.2026.D141' ACCEPTED ...
For permanent policy, ask the storage admin to assign management class MCRESEARCH with # BACKUP VERSIONS = 0, PRIMARY DAYS NON-USAGE = 1, LEVEL 1 DAYS NON-USAGE = 7 so manual HALTERDS is no longer needed.
Investigate a "dataset not found" that turns out to be migrated
A batch step ABENDs with IEC161I 052-084. The dataset is migrated and HSM should have auto-recalled — but the recall failed.
HLIST DSN(ALICE.PROD.CONFIG) BOTH
Output:
ARC1102I LIST OF DATASET NAMES STARTING WITH ALICE.PROD.CONFIG
- DSNAME - VOLSER LEVEL MIGRATED
ALICE.PROD.CONFIG ARC008 ML2 2025/11/30
ARC1100I LIST COMMAND COMPLETED
Try an explicit recall:
HRECALL DSN(ALICE.PROD.CONFIG) WAIT
Output:
ARC1024I RECALL REQUEST FOR DATASET 'ALICE.PROD.CONFIG' ACCEPTED ...
ARC1021I 'ALICE.PROD.CONFIG' RECALL FAILED, REASON=NO TAPE DRIVES
The reason is in plain sight — tape drive shortage. Either wait (HSEND QUERY WAITING shows the queue) or work with operations to bring an additional drive online. A repeat after the drive becomes available succeeds:
HRECALL DSN(ALICE.PROD.CONFIG) WAIT
Output:
ARC1020I 'ALICE.PROD.CONFIG' RECALL COMPLETE
Audit backups about to expire
A weekly task — list every backup version that will expire in the next 7 days so the team can decide which to keep.
HLIST LEVEL(ALICE) BCDS OUTDATASET(ALICE.HLIST.BCDS.WEEKLY)
Output:
ARC1102I BACKUP DATASET LIST
ARC1100I LIST COMMAND COMPLETED, OUTPUT IN ALICE.HLIST.BCDS.WEEKLY
Process the file with DFSORT to filter by expiration:
//FILTER JOB (ACCT),'EXPIRING BKUPS',CLASS=A,MSGCLASS=X,USER=ALICE
//STEP1 EXEC PGM=SORT
//SORTIN DD DSN=ALICE.HLIST.BCDS.WEEKLY,DISP=SHR
//SORTOUT DD SYSOUT=*
//SYSIN DD *
INCLUDE COND=(45,10,CH,LE,C'2026/06/01')
OPTION COPY
OUTREC FIELDS=(1,80)
/*
Output: (SYSOUT)
ALICE.ARCH.JAN2025.LOG 001 2026/05/29 (expires 2026/05/31)
ALICE.ARCH.FEB2025.LOG 001 2026/05/30 (expires 2026/06/01)
Retire a dataset and prove all its backups are gone
Compliance asks for proof that all copies of ALICE.OLDPROJ.SECRET.DATA are destroyed.
HLIST DSN(ALICE.OLDPROJ.SECRET.DATA) BOTH
HBDELETE 'ALICE.OLDPROJ.SECRET.DATA' ALLEXCP (* drop every backup version *)
HSEND DELETE 'ALICE.OLDPROJ.SECRET.DATA' (* scratch the active copy *)
HLIST DSN(ALICE.OLDPROJ.SECRET.DATA) BOTH (* should report not found *)
Output:
ARC1331I 'ALICE.OLDPROJ.SECRET.DATA' BACKUP VERSION 001 DELETED
ARC1331I 'ALICE.OLDPROJ.SECRET.DATA' BACKUP VERSION 002 DELETED
ARC1331I 'ALICE.OLDPROJ.SECRET.DATA' BACKUP VERSION 003 DELETED
ARC0250I DELETE COMMAND COMPLETED, DSNAME=ALICE.OLDPROJ.SECRET.DATA
ARC1100I LIST COMMAND COMPLETED, NO ENTRIES FOUND
The final HLIST line is the audit evidence — keep the SYSOUT in the change record.
Recover a scratched dataset under a new name
Engineering scratched ALICE.PROD.RATES by mistake. The most recent backup version is intact. Recover into a renamed copy first, validate, then rename onto the production name.
HRECOVER 'ALICE.PROD.RATES' NEWNAME(ALICE.PROD.RATES.RESTORED)
HLIST DSN(ALICE.PROD.RATES.RESTORED)
Output:
ARC1410I 'ALICE.PROD.RATES.RESTORED' RECOVER COMPLETE, VERSION=001
ARC1102I LIST OF DATASET NAMES STARTING WITH ALICE.PROD.RATES.RESTORED
- DSNAME - VOLSER LEVEL
ALICE.PROD.RATES.RESTORED PROD05 ML0
Once validated by the application team, rename onto production:
HSEND DELETE 'ALICE.PROD.RATES' (* in case a stub catalog entry remains *)
RENAME 'ALICE.PROD.RATES.RESTORED' 'ALICE.PROD.RATES'
Output:
ARC0250I DELETE COMMAND COMPLETED
RENAME COMPLETE
zEDC compression during migration and backup
The IBM Integrated Accelerator for zEnterprise Data Compression (zEDC) — an on-chip accelerator on z14/z15/z16/z17 systems — can be applied transparently during DFSMShsm migration, backup, and DFSMSdss dump processing. With zEDC active in the management class or ARCCMDxx, ML1 and ML2 datasets are compressed in flight, shrinking both DASD/tape footprint and CPU cost compared to software compression. The compression is fully transparent on recall — no application changes, no HRECOVER flags. The IBM Redpaper zEDC Compression: DFSMShsm Sample Implementation (REDP-5158) walks through SETSYS COMPACT and MIGRATIONOPTIMIZATION tuning.
F DFHSM,SETSYS COMPACT(ALL) (* enable zEDC compression site-wide *)
F DFHSM,SETSYS MIGRATIONOPTIMIZATION(SOURCE(zEDC))
F DFHSM,QUERY SETSYS (* confirm — look for COMPACT line *)
Output:
ARC0420I COMPACT=ALL, COMPACTPERCENT=40
ARC0421I MIGRATIONOPTIMIZATION=SOURCE(ZEDC)
Quick reference card
TSO end-user commands (long form / short form)
HMIGRATE / HMIG DSN(...) [ML1|ML2] [WAIT]
HRECALL / HREC DSN(...) [WAIT] [UNIT(...)]
HBACKDS / HBAC 'dsn' [WAIT] [NEWNAME(...)]
HRECOVER / HRCOV 'dsn' [VERSIONS(n)] [NEWNAME(...)] [REPLACE]
HBDELETE / HBDEL 'dsn' [VERSIONS(...)] [ALLEXCP]
HLIST / HLST DSN(...) [BOTH|MCDS|BCDS|OCDS]
HALTERDS / HALT 'dsn' [FREQUENCY(n)] [RETENTIONPERIOD(n)]
HSEND / HSND operator-command (* requires HSM authority *)
Tiers
ML0 primary DASD immediate access
ML1 level-1 DASD 1–5 seconds recall
ML2 level-2 (tape/cloud) 30 s – several minutes
Operator (console / HSEND)
F DFHSM,QUERY ACTIVE | WAITING | REQUEST(n) | USER(uid) | CDS | SETSYS
F DFHSM,CANCEL REQUEST(n)
F DFHSM,HOLD MIGRATION | RECALL | BACKUP
F DFHSM,RELEASE MIGRATION | RECALL | BACKUP
Top messages
ARC1024I recall accepted ARC1020I recall complete
ARC1101I migrate accepted ARC1138I migrate complete
ARC1300I backup accepted ARC1310I backup complete
ARC1400I recover accepted ARC1410I recover complete
ARC0584I delayed (retry-safe) ARC1500I generic error
ARC0167I duplicate request ARC0163I RACF denied
IEC161I 052-084 open of migrated dataset triggers recall