NAME

       cckd - Hercules Compressed CKD DASD image file

DESCRIPTION

       Hercules  DASD  image  file  that  emulates IBM mainframe DASD devices on a (usually) non-
       mainframe  platform.   Specified  in  the  Hercules  configuration  file   (default   name
       hercules.cnf)  to  describe  the  DASD  devices Hercules is to emulate.  Also specified as
       input and/or output file to several Hercules utilities.  Hercules compressed DASD  devices
       are  frequently  referred  to  as CCKD.  Hercules uncompressed DASD devices are frequently
       referred to as CKD.  Hercules CKD DASD image files are largely compatible with  P/390  AWS
       DASD files.

TECHNICAL OVERVIEW

       The  following  provides  a  technical  overview  of  CCKD internal structures.  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).  This bit is 1 when data is big-
       endian byte order, 0 when data is little-endian byte order.

   DEVHDR
       occupies the first 512 bytes of a CKD or CCKD DASD file.  The DEVHDR contains  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).  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.  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.

   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.  Described by the CCKD_L2ENT
       struct; (256 * 8) bytes in size.  Conceptually each L2ENT describes one track.

   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.

   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.  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,
       and cc describes the track compression algorithm.  The compression algorithms are: 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).   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.

   DATA field.
       if present, DL bytes of record data; immediately follows the KEY field for  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.

GLOSSARY

   CKD
       Count,  Key,  Data  - contents of an track.  Also refers to the Hercules uncompressed DASD
       image file.

   CCKD
       Compressed Count, Key, Data - compressed contents of a track.  Also refers to the Hercules
       compressed DASD image file.

   DASD
       Direct Access Storage Device - term the IBM mainframe world uses to refer to hard drives.

   EOT
       End Of Track - indicated by 8X'FF' in the COUNT field.

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.

HISTORY

       2003-02-07 originally written by James M. Morrison

                                            2003-02-03                                    cckd(4)