Provided by: hercules_3.06-1ubuntu1_i386 bug

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)