Anatomy of a z/VM CP-owned Volume

(Please note that the following applies to ECKD volumes only.)

A CP-owned volume is one that is defined to contain disk space used by CP for its own purposes:

  • paging
  • spooling
  • directory
  • temporary disks
  • warm start area
  • checkpoint area
  • persistent data record

CP-owned volumes can also contain data used by virtual machines (minidisks).

In order to be treated as a CP-owned volume, two things must be true

  1. The volume must have a special type of VOL1 standard label that identifies the volume as a "CPVOL".
  2. The volume must be identified in SYSTEM CONFIG as a member of the CP_OWNED list.
To create the special label, the volume is initialized using the CPFMTXA program. Under the covers, it calls ICKDSF with the CPFORMAT option.

The VOL1 label that gets created is fully compatible with other operating systems, including a slightly unusual VTOC.

The purpose of the VTOC is to tell z/VSE and z/OS, both of which use the VTOC to manage space on the volume, that there is no room on the volume. They can look, but not touch. z/VM itself doesn't use the VTOC.

The VTOC is pointed to by the label.

Volume Table of Contents (VTOC)

Now let's look at a real example. This 10-cylinder disk was formatted using CPFMTXA. It has a volume label of TEMPAA.

Label

The label is always cylinder 0, track 0, record 3, and is at least 80 bytes in length. CP-owned volumes use an IBM standard 80-byte VOL1 label. 

Rec Type  Len Byte ---------------- Hex -----------------   ------ Char ------
3  DATA    80 0000 E5D6D3F1  E3C5D4D7  C1C1F000  00000005   *VOL1TEMPAA0.....*
              0010 00000000  00404040  40404040  40404040   *.....           *
              0020 40404040  40404040  40000000  0000C3D7   *         .....CP*
              0030 E5D6D340  40404040  40404040  40404040   *VOL             *
              0040 40404040  40404040  40404040  40404040   *                *

TEMPAA is the 6-byte volume label (volser).

0000 0000 05 is the CCHHR (5-byte disk address) of the VTOC. This means cylinder 0, track 0, record 5. The VTOC on a CP-owned volume is always at this location. (Since there is one head per track, the terms head and track are interchangeable.)

5X'00',CL5'CPVOL' is a magic cookie that indicates this is a CP-owned volume. That means that it contains extent description data elsewhere on cylinder 0. CP will not read the allocation map from a volume that doesn't contain the magic cookie.

Allocation Map

The allocation map is always on record 4. 
Rec Type  Len Byte ---------------- Hex -----------------   ------ Char ------
4  KEY     16 0000 E2E2C9F1  40404040  E3C8C9E2  E2E8E240   *SSI1    THISSYS *
 
   DATA  4096 0000 08080002  00000000  00000000  00000000   *................*
              0010 0808FF00  00000000  00000000  00000000   *................*
              0020 00000000  00000000  00000000  00000000   *................*
              0030 00000000  00000000  00000000  00000000   *................*
The key area, if present, contains the owning Single System Image cluster name in the first eight bytes. The last eight bytes contain the owner system name. If present, CP will respect the values. If the volume does not belong to this system, only the PERM extents will be brought online.

The data area of record 4 contains a 16-byte header followed by a variable length data area that has one byte per formatted cylinder followed by a single byte of 0xFF. Byte values are as follows:

  • X'C0': Directory space (active)
  • X'40': Directory space (inactive)
  • X'20': Temporary disk (T-disk) space
  • X'0C': PARM space (first or only cylinder of extent)
  • X'1C': PARM space (remaining cylinders of extent)
  • X'08': PERM space
  • X'02': Spool space
  • X'01': Paging space

See the ALOC control block for details. Note that this format only applies to ECKD volumes that have 4079 or fewer cylinders (e.g. 3390-3). This is because there are only 4096 bytes on the track. Subtracting the 16-byte header and 1-byte trailer leaves only 4079 bytes to describe each cylinder.

For larger ECKD volumes (mod 9 and above) and any size FBA volumes, including EDEVICEs, an extent-based allocation map is used. Instead of having a description of each cylinder, it has a description of each extent (range of cylinders) on the volume. If an extent is not described, it is PERM space. Please look at the ALOCEXT control block for the layout.

Volume Ownership

z/VM 6.2 introduced the concept of volume ownership. There are two elements of ownership:
  • Single System Image cluster name (8 bytes)
  • System identifer (8 bytes)

These values are stored in bytes 0-15 of the key on Record 4 and are required for CP-owned volumes in an SSI cluster. For non-SSI configurations they are optional. 

Rec Type  Len Byte ---------------- Hex -----------------   ------ Char ------
4  KEY     16 0000 D4E8E2E2  C9404040  D4E8E2E8  E2404040   *MYSSI   MYSYS   *

The VTOC

The VTOC on a CPVOL contains exactly two records:
  1. A format-4 Data Set Control Block (DSCB-4) that describes the volume, and
  2. A format-5 Data Set Control Block (DSCB-5) that describes the one and only usable extent on the volume.

VTOC DSCB-4 (volume description)


The DSCB-4 is always 140 bytes in length and is always on record 5. It contains information about the volume, the device geometry at the time of formatting, and the size of the VTOC. The first 44 bytes are the key. 

Rec Type  Len Byte ---------------- Hex -----------------   ------ Char ------
5  KEY     44 0000 04040404  04040404  04040404  04040404   *................*
              0010 04040404  04040404  04040404  04040404   *................*
              0020 04040404  04040404  04040404             *............    *
 
   DATA    96 0000 F4000000  00050000  00000000  00000001   *4...............*
              0010 0000000A  000FE5A2  00000030  0000322D   *......Vs........*
              0020 00000000  00000000  00000000  00000000   *................*
              0030 00000000  00000000  00000000  00000000   *................*
              0040 00000000  00000000  00000000  00000000   *................*
              0050 00000000  00000000  00000000  00000000   *................*

0000: The VTOC is full. No more DSCBs can be allocated within it.

00: The VTOC is not indexed.

000A: Number of cylinders on the volume at the time the volume was formatted or when the label was changed. It may or may not represent the number of formatted cylinders.

Because the VTOC is simply a defensive mechanism that isn't actually used by CP, there's no issue if you copy the disk contents onto a larger volume. However, the mismatch in information in the VTOC and the size of the real volume could upset z/OS or z/VSE. Just keep that in mind.

Buried in there is also the information that there are 15 tracks per cylinder and 58 786 bytes per track.

VTOC DSCB-5 (free space)


The DSCB-5 is always 140 bytes in length and is always on record 6. It describes the (logically) available space on the volume. The first 44 bytes of this DSCB are the key, though it isn't needed since it always follows the DSCB-4 and can be read at the same time. See the picture above.

The DSCB-5 always says

  • The first extent that MAY contain free space starts on track 1.
  • There are no available cylinders or tracks in the extent starting on track 1.
  • There are no other extents on the volume.

So it doesn't really matter where this extent of (alleged) free space is located - it's full. 

Rec Type  Len Byte ---------------- Hex -----------------   ------ Char ------
6  KEY     44 0000 05050505  00010000  00000000  00000000   *................*
              0010 00000000  00000000  00000000  00000000   *................*
              0020 00000000  00000000  00000000             *............    *
 
   DATA    96 0000 F5000000  00000000  00000000  00000000   *5...............*
              0010 00000000  00000000  00000000  00000000   *................*
              0020 00000000  00000000  00000000  00000000   *................*
              0030 00000000  00000000  00000000  00000000   *................*
              0040 00000000  00000000  00000000  00000000   *................*
              0050 00000000  00000000  00000000  00000000   *................*

0001: Track offset to the first extent with free space.

0000: No unused cylinders in the extent.

00: No unused tracks in the extent.

All the other extents in this DSCB-5 (there are 26 total) are zero, as is the pointer to the next DSCB-5 in the VTOC. Why isn't the first one zero? The world may never know....

Details about these disk structures can be found in the following z/OS manuals:
  • DFSMS: Using Data Sets, SC23-6855, Appendix A (IBM VOL1 standard labels)
  • DFSMSdfp Advanced Services, SC23-6861, Chapter 1 (VTOC and DSCBs)

I hope this helps anyone who needs to understand the VTOC. I also place it here for posterity.


The information provided, and views expressed on this site are my own and do not represent the IBM Corporation.