1cckd(4)                    Kernel Interfaces Manual                    cckd(4)
2
3
4

NAME

6       cckd - Hercules Compressed CKD DASD image file
7
8

DESCRIPTION

10       Hercules  DASD image file that emulates IBM mainframe DASD devices on a
11       (usually) non-mainframe platform.  Specified in the Hercules configura‐
12       tion file (default name hercules.cnf) to describe the DASD devices Her‐
13       cules is to emulate.  Also specified as input  and/or  output  file  to
14       several  Hercules utilities.  Hercules compressed DASD devices are fre‐
15       quently referred to as CCKD.  Hercules uncompressed  DASD  devices  are
16       frequently  referred  to  as  CKD.   Hercules  CKD DASD image files are
17       largely compatible with P/390 AWS DASD files.
18
19

TECHNICAL OVERVIEW

21       The following provides a technical overview  of  CCKD  internal  struc‐
22       tures.   Except as indicated below, data in the following structures is
23       stored in the byte order indicated by the  CDEVHDR.options  CCKD_BIGEN‐
24       DIAN  bit  (the  0x02 bit).  This bit is 1 when data is big-endian byte
25       order, 0 when data is little-endian byte order.
26
27   DEVHDR
28       occupies the first 512 bytes of a CKD or CCKD DASD  file.   The  DEVHDR
29       contains  the  device  type  and the number of heads per cylinder.  Its
30       contents are the same whether the DASD image is  compressed  (CCKD)  or
31       not (CKD).  Described by the CKDDASD_DEVHDR struct; 512 bytes in size.
32
33   CDEVHDR
34       immediately follows the DEVHDR, and contains fields describing the num‐
35       ber of L1ENTs in the L1TAB, the number of L2ENTs  in  each  L2TAB,  and
36       anchors the free space chain.  Described by the CCKDDASD_DEVHDR struct;
37       512 bytes in size.
38
39   L1TAB
40       immediately follows the CDEVHDR, and consists of L1ENT entries, each of
41       which  points  to an L2TAB.  Each L1ENT is an U32 (4 bytes) offset into
42       the CCKD DASD file.  The CDEVHDR  numl1tab  field  describes  how  many
43       L1ENTs  are in the L1TAB.  L1ENTs are described by the CCKD_L1ENT type‐
44       def; the L1TAB is of variable size.  Conceptually each L1ENT  describes
45       cdevhdr.numl2tab tracks.
46
47   L2TAB
48       is pointed to by an L1ENT, and is composed of L2ENT entries, the number
49       of which is described by the  CDEVHDR  numl2tab  field;  currently  256
50       L2ENTs in each L2TAB.  L2ENTs contain the offset to the TRKHDR, and the
51       combined length of the TRKHDR and (optionally) compressed  track  data.
52       The CDEVHDR numl2tab field describes how many L2ENTs are in each L2TAB.
53       Currently, there are 256  L2ENTs  in  each  L2TAB.   Described  by  the
54       CCKD_L2ENT  struct;  (256  * 8) bytes in size.  Conceptually each L2ENT
55       describes one track.
56
57   FREEBLK
58       describes free space in the CCKD DASD image, anchored  by  the  CDEVHDR
59       free  field.   Consists  of  a 4 byte offset to the next free space (or
60       zero for end of free space chain), and a 4  byte  length  of  the  free
61       space  (which  length  includes  the  8  bytes  occupied by the FREEBLK
62       itself), followed by zero or more bytes of residual data.  Described by
63       the first 8 bytes of the CCKD_FREEBLK struct; 8 bytes in size.
64
65   TRKHDR
66       Occurs  once at the beginning of each track.  contains flag (one byte),
67       CC (two bytes), and HH (two bytes) of the track.  When the flag byte  =
68       0x00,  TRKHDR  is the same as the Home Address on real DASD.  Flag bits
69       are described in hercules.h, and are of the format nlllllcc  where  n=1
70       for new track header format, lllll is used for track recovery purposes,
71       and cc describes the  track  compression  algorithm.   The  compression
72       algorithms  are:  B'00'  =  uncompressed,  B'01' = zlib, B'10' = bzip2,
73       B'11' is currently invalid.  Data in TRKHDR  is  stored  in  big-endian
74       byte order.  Described by the CKDDASD_TRKHDR struct; 5 bytes in size.
75
76   COUNT field
77       8  bytes,  containing  CC (two bytes), HH (two bytes), R (one byte), KL
78       (one byte), and DL (two bytes).  CC is  the  (relative  zero)  cylinder
79       number.   HH  is  the  (relative zero) head number.  R is the (relative
80       zero) record number on the track.  KL is the key length; if zero no key
81       is  present.   DL  is the length of the data record.  Data in the COUNT
82       field is stored in  big-endian  byte  order.   Described  by  the  CKD‐
83       DASD_RECHDR struct; 8 bytes in size.
84
85   KEY field
86       if  present,  KL  bytes  of  record  key; immediately follows the COUNT
87       field.  Byte order is not a factor for the KEY field; to the extent  it
88       is examined by Hercules code it is simply a byte stream.  Size varies.
89
90   DATA field.
91       if  present, DL bytes of record data; immediately follows the KEY field
92       for keyed record, else immediately follows the COUNT field for  unkeyed
93       records.   Byte order is not a factor for the DATA field; to the extent
94       it is examined by Hercules code it  is  simply  a  byte  stream.   Size
95       varies.
96
97

GLOSSARY

99   CKD
100       Count,  Key,  Data - contents of an track.  Also refers to the Hercules
101       uncompressed DASD image file.
102
103   CCKD
104       Compressed Count, Key, Data - compressed contents  of  a  track.   Also
105       refers to the Hercules compressed DASD image file.
106
107   DASD
108       Direct  Access  Storage  Device  - term the IBM mainframe world uses to
109       refer to hard drives.
110
111   EOT
112       End Of Track - indicated by 8X'FF' in the COUNT field.
113
114

SEE ALSO

116       http://www.conmicro.cx/hercules/ the Hercules emulator homepage.
117
118       http://www.conmicro.cx/hercules/cckddasd.html which describes
119              the Hercules CCKD DASD facility.
120
121       http://www.conmicro.cx/hercules/hercconf.html which describes
122              the Hercules configuration file.
123
124

HISTORY

126       2003-02-07 originally written by James M. Morrison
127
128
129
130
131
132                                  2003-02-03                           cckd(4)
Impressum