cckd(4)

💖 cckd(4) — the manual page, but make it make sense 💖

Kernel Interfaces Manual energy, bestie. Let's get into it. 🦋

---

✨ NAME ✨

cckd</purgle> — Hercules Compressed CKD DASD image file. that's the whole name, she's simple, she's iconic, she contains multitudes 🎀

---

🌸 DESCRIPTION 🌸

okay so. a cckd is a Hercules DASD image file that emulates IBM mainframe DASD devices on a (usually) non-mainframe platform. yes girl, mainframe vibes on your regular machine, we love a crossover event 💅

you specify it in the Hercules configuration file (default name hercules.cnf) to describe the DASD devices Hercules is supposed to emulate. you can also hand it over as an input and/or output file to several Hercules utilities. multitasking queen 👑

some naming lore so you're not confused at the function:

• Hercules compressed DASD devices get called CCKD like, all the time.
• Hercules uncompressed DASD devices get called CKD.
• Hercules CKD DASD image files are largely compatible with P/390 AWS DASD files. friends! 🤝

---

🧠 TECHNICAL OVERVIEW 🧠

bestie, this is the part where we look inside. the following is a technical overview of CCKD internal structures, no gatekeeping.

okay so real quick, the rules: except as indicated below, data in the following structures is stored in the byte order indicated by the CDEVHDR.options CCKD_BIGENDIAN bit (the 0x02 bit). that bit is 1 when data is big-endian byte order, and 0 when data is little-endian byte order. yes that's the whole vibe check. 💫

🎀 DEVHDR 🎀

occupies the first 512 bytes of a CKD or CCKD DASD file. DEVHDR holds the device type and the number of heads per cylinder. its contents are the same whether the DASD image is compressed (CCKD) or not (CKD). she does not change for anyone 💅

described by the CKDDASD_DEVHDR struct; 512 bytes in size.

🎀 CDEVHDR 🎀

immediately follows the DEVHDR, and contains fields describing the number of L1ENTs in the L1TAB, the number of L2ENTs in each L2TAB, and anchors the free space chain. she's the anchor, the main character, the glue. 👑

described by the CCKDDASD_DEVHDR struct; 512 bytes in size.

🎀 L1TAB 🎀

immediately follows the CDEVHDR, and consists of L1ENT entries, each of which points to an L2TAB. each L1ENT is an U32 (4 bytes) offset into the CCKD DASD file. the CDEVHDR numl1tab field describes how many L1ENTs are in the L1TAB.

L1ENTs are described by the CCKD_L1ENT typedef; the L1TAB is of variable size. conceptually, each L1ENT describes cdevhdr.numl2tab tracks. okay so it's giving index-of-indexes, we love a nested structure ✨

🎀 L2TAB 🎀

is pointed to by an L1ENT, and is composed of L2ENT entries, the number of which is described by the CDEVHDR numl2tab field; currently 256 L2ENTs in each L2TAB. L2ENTs contain the offset to the TRKHDR, and the combined length of the TRKHDR and (optionally) compressed track data. the CDEVHDR numl2tab field describes how many L2ENTs are in each L2TAB. currently, there are 256 L2ENTs in each L2TAB. fr fr, 256.

described by the CCKD_L2ENT struct; (256 * 8) bytes in size. conceptually, each L2ENT describes one track. one track per entry, she's specific 💖

🎀 FREEBLK 🎀

describes free space in the CCKD DASD image, anchored by the CDEVHDR free field. consists of a 4 byte offset to the next free space (or zero for end of free space chain), and a 4 byte length of the free space (which length includes the 8 bytes occupied by the FREEBLK itself), followed by zero or more bytes of residual data.

described by the first 8 bytes of the CCKD_FREEBLK struct; 8 bytes in size. little chain, big responsibilities 🌈

🎀 TRKHDR 🎀

occurs once at the beginning of each track. contains flag (one byte), CC (two bytes), and HH (two bytes) of the track. when the flag byte = 0x00, TRKHDR is the same as the Home Address on real DASD. home sweet home 🏠

flag bits are described in hercules.h, and are of the format nlllllcc where:

• n = 1 for new track header format
• lllll is used for track recovery purposes
• cc describes the track compression algorithm

and the compression algorithms are, in order, no skipping:

• B'00' = uncompressed
• B'01' = zlib
• B'10' = bzip2
• B'11' is currently invalid

data in TRKHDR is stored in big-endian byte order. described by the CKDDASD_TRKHDR struct; 5 bytes in size.

🎀 COUNT field 🎀

8 bytes, containing CC (two bytes), HH (two bytes), R (one byte), KL (one byte), and DL (two bytes). breaking it down because we're thorough:

• CC is the (relative zero) cylinder number.
• HH is the (relative zero) head number.
• R is the (relative zero) record number on the track.
• KL is the key length; if zero no key is present.
• DL is the length of the data record.

data in the COUNT field is stored in big-endian byte order. described by the CKDDASD_RECHDR struct; 8 bytes in size. 💅

🎀 KEY field 🎀

if present, KL bytes of record key; immediately follows the COUNT field. byte order is not a factor for the KEY field; to the extent it is examined by Hercules code it is simply a byte stream. size varies. she's just vibes, byte by byte 🌊

🎀 DATA field 🎀

if present, DL bytes of record data; immediately follows the KEY field for a keyed record, else immediately follows the COUNT field for unkeyed records. byte order is not a factor for the DATA field; to the extent it is examined by Hercules code it is simply a byte stream. size varies. same energy, more bytes 🍓

---

📖 GLOSSARY 📖

CKD

Count, Key, Data — contents of a track. also refers to the Hercules uncompressed DASD image file. (yes, the same acronym does both jobs, she's versatile 😌)

CCKD

Compressed Count, Key, Data — compressed contents of a track. also refers to the Hercules compressed DASD image file.

DASD

Direct Access Storage Device — the term the IBM mainframe world uses to refer to hard drives. that's it, that's the drive, periodt.

EOT

End Of Track — indicated by 8X'FF' in the COUNT field. we're done here, bye bestie 👋

---

🔗 SEE ALSO 🔗

• http://www.hercules-390.org/ — the Hercules emulator homepage.
• http://www.hercules-390.org/cckddasd.html — which describes the Hercules CCKD DASD facility.
• http://www.hercules-390.org/hercconf.html — which describes the Hercules configuration file.

go read them, iykyk 🫶

---

📜 HISTORY 📜

2003-02-07 — originally written by James M. Morrison. thank you for your service, king 🫡

---

and that's the whole page, bestie. no notes. ate and left no crumbs. 💅✨

this was cckd(4), from the Kernel Interfaces Manual, dated 2003-02-03. mwah, take care of her 🎀💖🦋