How to read a LISTCAT ENTRIES(ALL) for tuning purposes and understanding how your VSAM datasets are working.

1. The LISTCAT command:
Using LISTCAT and
Interpreting Its Output
By Dan O'Dea
November 1, 1998
∆ΦΟ

2. 2
Finding VSAM information: the LISTCAT Command
The Access Method Services (AMS) LISTCAT command lists catalog information for
catalogued datasets. You can limit the number of entries, or the amount of information
returned to you, by using LISTCAT options.
This handout describes the various LISTCAT operands and their syntax. It provides
descriptions of the fields in a LISTCAT report, sample LISTCAT output, and some
examples of LISTCAT commands. I'll also explain how to use the LISTCAT output to
tune your VSAM files.
This is designed for a VSAM class; it does not describe the various reports generated
for non-VSAM files.
Here is the complete syntax for the LISTCAT (abbreviated LISTC) command:
<insert picture here>

3. 3
LISTCAT Command Parameter Descriptions
All parameters of the LISTCAT (LISTC) command are optional. If LISTC runs in
batch mode with no parameters, it lists the system master catalog. If LISTC runs in
READY mode with no parameters, it lists all files beginning with the TSO user's ID.
If the CATALOG parameter is given, but ENTRIES, LEVEL, NOTUSABLE,
CREATION, and EXPIRATION are not coded (and no entry parameters are given), and
LISTC is not invoked from TSO the entire catalog specified is listed.
CATALOG ( ... ) - the name of the desired ICF catalog. LISTC normally uses the
standard catalog search algorithm. The CATALOG optional parameter forces LISTC to
search only that catalog.
ENTRIES ( ... ) - the name or generic name (see below) to be listed. If the entry
name is a cluster all of its components are listed. If the entry name is an AIX its
components, and all its PATHs, are listed.
If a generic entry name is supplied, one qualifier replaces the "*". As an example,
suppose the catalog contains these entries.
EMP.PER.CKSDS EMP.PER.AIXSSN EMP.PER.AIXSSN.PATH
EMP.PAY.CKSDS EMP.PAY.AIXSSN EMP.PAY.AIXSSN.PATH
EMP.TAX.CKSDS EMP.TAX.AIXSSN EMP.TAX.AIXSSN.PATH
If ENTRIES(EMP.PER.*) is specified, the list shows the first three entries.
If ENTRIES(EMP.*.CKSDS) is specified, the list shows the three left-most entries.
LEVEL ( ... ) - lists all entries matching the level of qualification given. This can be
any number of qualifiers. Any entry in the catalog matching level is listed regardless of
the number of qualifiers after level.
As with ENTRIES, an "*" can substitute for one level. Using the same catalog entries
as above, here are some examples:
If LEVEL(EMP) is specified, the list includes all nine entries.
If LEVEL(EMP.PER.*) is specified, only the first two entries are listed.
If LEVEL(EMP.PER) is specified, the list includes the first three entries.
If LEVEL(EMP.*.CKSDS) is specified, the list includes the three left-most entries.

4. 4
The LISTCAT Command: Restricting Entries
Use one of these restriction parameters to limit the type of entry in the list: ALIAS,
ALTERNATEINDEX (AIX), CLUSTER (CL), DATA, INDEX,
GENERATIONDATAGROUP (GDG), NONVSAM (NVSAM), SPACE (SPC),
PAGESPACE (PGSPC), PATH, USERCATALOG (UCAT).
• ALIAS lists only aliases.
• AIX lists only alternate index (AIX) entries. Unless DATA and INDEX are also
specified, only the AIX cluster is listed.
• DATA restricts the list to data components. Specify either the cluster name or the
component name.
• GDG lists only generation data group (GDG) bases.
• INDEX restricts the list to index components. Specify either the cluster name or
the component name.
• NONVSAM restricts the list to non-VSAM files.
• PAGESPACE restricts the list to page spaces.
• PATH lists only paths to alternate indexes. If the LISTC command includes the
AIX using the path, the path is automatically listed.
• SPACE is valid only for non-ICF (Integrated Catalog Facility) environments.
• UCAT lists user catalog CONNECT entries from the master catalog.
Here are some examples of LISTC commands.
LISTC ENTRIES(EMP.FILE.CKSDS) CLUSTER lists cluster information, but
not the cluster's data and index components.
LISTC ENT(EMP.FILE.AIXSSN) AIX DATA INDEX lists cluster, data, and
index information for the complete alternate index. Unless the keyword PATH is
included, no path information is displayed.
LISTC LEVEL(EMP) CLUSTER DATA INDEX lists all component information
for all files whose names begin with the high-level qualifier (HLQ) EMP.

5. 5
The LISTCAT Command: Restricting Listed Information
ALL / ALLOCATION / HISTORY / NAME / VOLUME - ALLOCATION can be
abbreviated to ALLOC, HISTORY to HIST, and VOLUME to VOL. NAME is the
default.
• ALL: LISTC lists all fields.
• ALLOC: lists the History paragraph for clusters, and the History, Allocation, and
Volume paragraphs for data and index components.
• HISTORY lists the History paragraphs.
• NAME limits the list to name and type fields.
• VOLUME limits the list to History paragraphs for cluster, data, and index
components, and includes the VOLSER and device type information for data and
index components. Allocated extent information is not listed.
CREATION (n) - abbreviated to CREAT, lists only entries "n" days ago or earlier.
"n" is decimal. Hexadecimal or binary numbers are preceded by X or B respectively.
The maximum number to specify is 9999. The default, "0", lists everything.
EXPIRATION (n) - abbreviated to EXPIR, lists entries only if they expire "n" days
from now or earlier. "n" is decimal. Hexadecimal or binary numbers are preceded by X
or B respectively. The maximum number to specify is 9999. "0" lists only expired
entries.
NOTUSABLE - lists only files marked NOTUSABLE. Datasets become unusable
when a system failure damages the catalog entry for a particular component. Unless
specifically requested, records marked UNUSABLE are not listed
OUTFILE ( ... ) - specifies a DD statement for the output file other than SYSPRINT.
The file must specify RECFM=VBA and LRECL=125.
FILE ( ... ) – For VVDS information, specifies a DD statement identifying the devices
and volumes containing the ICF VVDSes.

6. 6
Description of Keyword Fields
The HISTORY Paragraph
RELEASE - the release of VSAM. "1" is the original VSAM from prior to 1976; "2"
refers to the current release, the one in use since 1976. It has nothing to do with the OS
version or DFP version.
CREATION - the Julian create date of the object as YYYY.DDD.
EXPIRATION – An expiration date protects a dataset from deletion. Before its
expiration date, the PURGE parameter of the DELETE command is the only way to
delete the object. Specify an expiration date in the file definition using the TO or FOR
parameters. A date of 9999.999 permanently protects the file. Change this field with the
ALTER command.
RCVY-VOL, RCVY-DEVT, RCVY-CI - not applicable in an ICF environment.
The PROTECTION Paragraph
ATTEMPTS - the number of attempts may be made to enter the file's password. This
is valid only if the file is password protected.
CODE - the character string to pass to the WTO message in a failed password
attempt. This is valid only if the file is password protected.
CONTROLPW, MASTERPW, READPW, UPDATEPW - specifies the indicated
password of the file being listed. These fields are printed only if the file is password
protected.
PSWD - if the object is not password protected this value is NULL. If a password or
words are valid but not printed for some reason this value is SUPP.
RACF - if the object is RACF-protected with a discrete profile this value is YES. If
the object is protected with a generic profile or not protected at all this value is NO.
USAR - the contents of the User Security Authorization Record. The data in this field
is passed to the USVR (see below) when access to the object is attempted. If there is no
USAR this field is NULL. This is valid only if the file is password protected.
USVR - the User Security Verification Routine. The USVR is essentially a program
to verify whether the user can access the file. If the USVR is not used this value will be
NULL. This is valid only if the file is password protected.

7. 7
The ASSOCIATION Paragraph
Each object has a particular list of object types it can be associated with:
Entry Type Can be associated with:
ALIAS Its non-VSAM DSN or a VSAM user catalog entry
AIX Its data and index entries, its base cluster entry, and its PATH
entries
AIX data Its alternate index cluster entry
AIX index Its alternate index cluster entry
CLUSTER Its data entry, index entry (KSDS or variable RRDS), associated
PATH entries, and AIX entries
Cluster data Its base cluster entry
Cluster index Its base cluster entry
GDG Its non-VSAM file entries
NONVSAM Any associated alias entries
Page Space Its data entry (basically an ESDS cluster)
Path Entry The AIX entry and the AIX's data and index entries, the data entry
(over a base of the base cluster (and its index entry if a KSDS or variable RRDS)
cluster and
AIX)
Path Entry The base cluster entry, the data entry of the base cluster (and its
(over a base index entry if a KSDS or a variable RRDS)
cluster)
User catalog Its associated alias entries.

8. 8
The ATTRIBUTES Paragraph
AVGLRECL - the average record length as found in the RECORDSIZE
parameter of the define. When AVGLRECL equals MAXLRECL the component
can be assumed to contain fixed-length records, but VSAM doesn't care. When
AVGLRECL is different from MAXLRECL the component can be assumed to
contain variable-length records, but again VSAM doesn't care. Except when
AMS calculates space amounts this value is treated as documentation and can
be any value the user desires. VSAM does not attempt to maintain a true
average record length for the data.
AXRKP - the relative key position of the AIX key field within the base cluster's
record as defined in the KEYS define parameter.
BIND - the file is to be staged from the mass storage device to the virtual
DASD staging drive when it is opened, and will be retained on the drive until it is
closed.
BUFSP - the minimum number of bytes to be acquired as buffers when the
cluster is opened. This value is originally specified through the BUFFERSPACE
define parameter.
CI/CA - the number of CIs in each CA for the component.
CISIZE - the CI size of the component.
CYLFAULT - specifies the component will not be staged from the mass
storage device when it is opened, but will be staged across in groups of cylinders
as the data is needed.
DSTGWAIT - specifies the component will be destaged from the virtual DASD
staging drive back to the mass storage device before control is returned to the
user program to issue a CLOSE. Its counterpart is NODSTGWAIT.
ERASE - specifies records are to be overwritten with binary zeroes when the
file is deleted. Its counterpart is NOERASE.
EXCEPTIONEXIT - the entry name of the routine to be given control when I/O
errors occur when processing the component.
IMBED - specifies the sequence set records are to be written in the top track
of the CA they address, with each record written as many times as it will fit. Its
counterpart is NOIMBED.
INDEXED - specifies the component is part of a KSDS cluster (either a base
or alternate index).

9. 9
The ATTRIBUTES Paragraph (cont'd)
KEYLEN - the length of the search key field in the data component records for
the KSDS cluster (either a base or an alternate index).
LINEAR - specifies whether the component is an LDS cluster.
MAXLRECL - the user-defined maximum record length as defined in the
RECORDSIZE define parameter. See AVGLRECL for more information. VSAM
will not allow a record longer than MAXLRECL to be written to the component.
MAXRECS - the highest possible valid record number. This field appears
only for an RRDS. MAXRECS = 2^32 / CISZ * record slots per CI.
NONINDEXED - specifies the component is part of an ESDS cluster.
NONSPANNED - specifies the records in the component cannot span across
CIs. Its counterpart is SPANNED.
NONUNIQUEKEY - states the alternate key field defined for the associated
AIX can have multiple values in multiple records throughout the related base
cluster. It does not allow the AIX to have multiple records with the same key, but
does allow AIX records to point to more than one base cluster record. The
counterpart to this parameter is UNIQUEKEY.
NOREPLICAT - specifies the index component records are not to be repeated
around their track multiple times, but to store as many index records as possible
on the track. Its counterpart is REPLICATE.
NOREUSE - specifies the file cannot be opened as reusable. Its counterpart
is REUSE.
NOSWAP - specifies the associated Page Space is a conventional Page
Space data set and not a high speed swap data set. Its counterpart is SWAP.
NOTRKOVFL - specifies the VSAM physical blocks in a Page Space cannot
span track boundaries. Its counterpart is TRKOVFL.
NOUPDATE - specifies, for a path over an AIX, no updating of the AIX will
take place if the base cluster is opened through the "no update" path. Its
counterpart is UPDATE, which allows such updating.
NOUPGRADE - specifies, for an AIX, an open for update of the associated
base cluster will not result in an open for update of the AIX. Its counterpart is
UPGRADE, which will keep an AIX and its base cluster in sync.

10. 10
The ATTRIBUTES Paragraph (cont'd)
NOWRITECHECK - specifies VSAM will not check output operations against this
component by issuing a READ immediately following a WRITE or REWRITE.
Its counterpart is WRITECHECK.
NUMBERED - specifies the component is part of an RRDS cluster.
ORDERED - specifies the volumes assigned to this component will be
allocated in the order specified in the VOLUMES parameter of the define. Its
counterpart is UNORDERED, which is the default under ICF catalogs.
RECOVERY - specifies CAs will be preformatted at load time, with other safe-
guards to allow mid-load recovery. Its counterpart is SPEED.
RECORDS/CI - for an RRDS only, the number of logical record slots a single
CI can contain.
RECVABLE - valid only for the old-style VSAM catalog.
RKP - the relative position of the key field within the base cluster's record as
defined by the KEYS define parameter.
SHROPTNS - the share options of the file.
SUBALLOC - valid only for the old-style VSAM catalog.
TEMP-EXP - specifies a backup copy of the listed file has been made with the
EXPORT command specifying the TEMPORARY option. If this status is not set
IMPORT cannot automatically define the file at restore time.
UNIQUE - valid only in a non-ICF environment. In an ICF environment this is
the default.

11. 11
The STATISTICS Paragraph
The fields in this paragraph are brought into the Access Method Data
Statistics Block (AMDSB) when the file is opened. As the file is updated the
statistics in the AMDSB are maintained in storage. The AMDSB is not written
back to the catalog until the file has been successfully closed. If the close is not
successful, the statistics in the AMDSB are not written back to the catalog, thus
the catalog's statistics still reflect the values at the time of the open.
There are two ways for close processing to fail:
1 - An ABEND of the program opening the file. Although a program will perform
most of the functions of a close, including writing out the last buffers, the file is
not considered officially closed. If the open was for update processing, the
"open for update" bit is left on and statistics are not written.
At this time the user should determine if the file is valid. If update
transactions have not been logged, it may be necessary to delete and
recreate the file, rendering any "invalid" statistics in the catalog moot (they will
be reset as part of the recovery).
Of course, if the file is actually good an explicit VERIFY can be run to
update the catalog statistics.
2 - A system crash when a program has the file open. While the system is
crashing there is obviously no time for the system to run around closing files.
All files, VSAM and non-VSAM, will be left "open". Buffers are not written to
disk, the "open for update" bit is left on and statistics are not written. If update
transactions have not been logged, it may be necessary to delete and
recreate the file, rendering any "invalid" statistics in the catalog moot (they will
be reset as part of the recovery).

12. 12
The STATISTICS Paragraph (cont'd)
FREESPACE-%CI - the CI free space percentage as given in the define.
Neither this nor the CA% gives the actual free space remaining except
immediately following a load or resume load.
FREESPACE-%CA - the CA free space percentage as given in the define.
FREESPACE-BYTES - specifies the current number of free space bytes
within the area allocated by the component. This count includes bytes within
completely free CIs only. Free space within CIs is not included.
While this field gives a general idea of the free space remaining in the file, it
does not specify where it is located. There are four areas where free space can
be found:
1. Free CIs due to deleted records;
2. Free CIs at the end of each CA;
3. Free CIs in the last partially-filled CA before the end of file;
4. Completely empty CAs between the HURBA and HARBA.
If a free space map is required, something other than a LISTC is needed.
Four Index-only Statistics
LEVELS - the number of levels making up the index, including the sequence
set. The lower this number is the better.
ENTRIES/SECT - the number of index entries within each section of an index
record. An index record is broken down into sections to improve performance
during key compares. The number of entries per section is the square root of the
number of CI/CA for the data component. For example, if the data component
has 180 CI/CA, the nearest lower whole number to its square root is 13, so the
index has roughly 13 sections of 13 records per section.
HI-LEVEL-RBA - the RBA of the highest level index record. When the KSDS
is open for random processing, this RBA is used to locate and read the top
logical record of the index. VSAM then follows the vertical pointers through the
index structure. Note the top of the index structure is not maintained at the
physical beginning of the index.
SEQ-SET-RBA - the RBA of the first sequence set record. When the KSDS
is open for sequential processing, this RBA is used to locate and read the
beginning of the horizontal sequence set chain of records, gaining access to the
data component CAs in logical sequence. Once the KSDS is loaded, this value
does not change.

13. 13
The STATISTICS Paragraph (cont'd)
EXCPS - the total number of Execute Channel Program calls issued by VSAM
against the data component. This number corresponds to the number of physical
I/O operations against the data component since it was created or reorganized.
This value cannot be used to determine the number of logical records read or
written to the file, or even the number of CIs passed from DASD to memory and
back, since buffer amounts have a great impact on how many CIs are written for
a given EXCP.
EXTENTS - the total number of physical extent allocations, on all volumes,
the data component has made.
REC-DELETED - the total number of logical records deleted from the data
component since it was last created or reorganized.
REC-INSERTED - the total number of logical records inserted into the data
component since it was last created or reorganized. For a KSDS or an ESDS
this total does not include records added at the end of the data component or
those records initially loaded. For an RRDS this count is the number of records
inserted into empty slots, including the number initially loaded into the file.
REC-RETRIEVED - the total number of logical records read from the data
component since it was last created or reorganized. It includes reads for update
during REWRITE processing.
REC-TOTAL - the total number of logical records currently in the data
component.
REC-UPDATED - the total number of logical records updated and rewritten
back into the data component since it was last created or reorganized. This does
not include deleted records, but if a record is updated at one time and deleted in
a subsequent call is counted.
SPLITS-CA - the total number of CA splits occurring in this component since
it was last created or reorganized. To get a real idea of why CA splits are
occurring a series of LISTCATs is needed to see a trend develop.
For an index component, a CA split occurs only when an update to an
intermediate or high level record will not fit and the record has to be split. This
can happen during a data component CA split. Technically this is not a CA split,
but it shows up in this count.
Each SIS mode loading of a new CA is counted in this field. Note these are
not CA splits and are actually beneficial to the file.

14. 14
The STATISTICS Paragraph (cont'd)
SPLITS-CI - the total number of CI splits occurring in this component since it
was last created or reorganized. To get a real idea of why CI splits are occurring
a series of LISTCATs is needed to see a trend develop.
For an index component, a CI split occurs each time a data component CA
splits. Technically the splitting of a sequence set record is not a CI split, but it
shows up in this count.
SYSTEM-TIMESTAMP - the date and time the component was last closed
following an open for update. The value is from the S/370 time-of-day clock, an
8-byte binary value reflecting the number of microseconds elapsed since January
1, 1900. This value is useless in itself, but is compared to the timestamp for its
related components.
For example, in a KSDS, if the timestamp values for the data and index
components are equal, VSAM assumes the two components were opened using
the cluster, resulting in synchronization between the two components. In theory,
if the timestamps of the data and index components are not equal VSAM will fail
the open. In reality, however, the open only fails when the data component's
timestamp is greater than that of the index.
Because a VERIFY command alters the timestamp, it is highly recommended
the VERIFY be run at the cluster level.

15. 15
The ALLOCATION Paragraph
SPACE-TYPE - the type of space allocated to the file.
A type of TRACKS may mean the file was allocated in tracks, records,
megabytes, or kilobytes and VSAM was unable to build 1-cylinder-sized CAs.
When TRACKS appears in this field full tracks are allocated and aligned on track
boundaries.
A type of CYLINDERS may mean the file was allocated in cylinders, records,
megabytes, or kilobytes, as VSAM will attempt to build 1-cylinder-sized CAs.
When CYLINDERS appears in this field full cylinders are allocated and aligned
on cylinder boundaries.
SPACE-PRI - the number of space allocation units, as indicated in SPACE-
TYPE, whenever a primary allocation is made. This is the amount of space given
the file at define time as well as the first time the file extends to a candidate pack.
SPACE-SEC - the number of space allocation units, as indicated in SPACE-
TYPE, whenever a secondary allocation is made. This is the amount of space
allocated when the file extends on the same volume.
HI-ALLOCATED-RBA - referred to as HARBA, specifies the highest allocated
RBA, plus 1, for the component. This value is equal to the HARBA in the last
VOLUME paragraph for the component.
This field, as are all other RBA fields for VSAM, is kept as a 32-bit unsigned
integer. Thus the largest value possible is 232 or 4Gb. This is the maximum file
size. For example, if a KSDS is defined with NOIMBED and a 4K CI size the
maximum file size on a 3390 device is 5,826 cylinders.
HI-USED-RBA - referred to as HURBA, specifies the highest used RBA, plus
1, for the component. This value is equal to the HURBA in the last VOLUME
paragraph for the component.
For an ESDS, LDS, KSDS index, or variable length RRDS index, this value
points to the first CI following the last CI containing data. For a KSDS data
component, or any RRDS data component, this value points to the bottom of the
last CA containing data. In either case the HURBA represents the VSAM end-of-
file marker. Not all files have this “marker;” it is not present if HURBA = HARBA.
To determine if your file is overallocated:
Over-allocation = HARBA - HURBA
in CAs CI/CA * CISZ

16. 16
The VOLUMES Paragraph
Fields in this paragraph describe the physical extent allocations for a data or
index component. Candidate volumes are also listed, but without extents. There
is a separate volume group for each volume having extents.
For a KSDS, if the data component has more than one volume group listed,
each group describes the allocated extents on each volume. If the data
component has key ranges, there is a separate volume group for each key
range.
For a KSDS, if the index component has more than one volume group listed,
each group describes the entries containing index records on a specific volume.
The first volume group describes the primary extents of the index containing the
high-level index records and (if NOIMBED) the sequence set records. If IMBED
is specified, each group after the first describes extents containing the imbedded
sequence set records, corresponding to the data component's volume groups.
When IMBED is specified the index VOLUMES paragraph will always have at
least two volume groups, one for the primary index set and the other for the
imbedded sequence set records.
BYTES/TRACK - the number of bytes VSAM can write on a track of this
volume. This is only listed for Page Spaces.
DEVTYPE - the internal MVS device type code. A 3390 is 3010200F.
EXTENT-NUMBER - the number of physical extents allocated on the volume
listed for this component.
EXTENT-TYPE - descriptive attribute(s) of the extent VSAM can use to
control processing of the extent. The values shown in the list below can be
ORed together for a complete description:
X'00' - this set of extents contains data.
X'40' - this set of extents does not contain data. Some levels of DFP
report X'40' with the SPEED option. Surprisingly, second and subsequent
volumes of the same file will have extent types of X'00'.
X'80' - this set of extents contains imbedded sequence set records.
This only occurs for an index component. The LOW- and HIGH-CCHH
value for the extent is the same as that for the corresponding data
component extent, showing the full width of the data component extent
even though only the first track contains the index records.
X'FF' - this signifies a candidate volume.

17. 17
The VOLUMES Paragraph (cont'd)
EXTENTS - identifies the physical extent descriptions for each extent of the
component located on the volume, showing the VSAM RBA relationship to each
extent. Within VSAM addressing between components is done with RBA values.
These must be converted to absolute addresses (CCHHR) before an I/O can be
performed. You should note it's possible to have extents which are not physically
contiguous on DASD but whose RBAs are contiguous. There are five reported
fields in the EXTENTS section:
HIGH-CCHH - the physical ending location of the extent on the volume
in the form CCHH, where CC is the 2-byte hexadecimal number of the
DASD cylinder and HH is the 2-byte hexadecimal number of the track
within the cylinder (or read-write head).
HIGH-RBA - the RBA, in decimal, corresponding to the HIGH-CCHH
physical address of the extent.
LOW-CCHH - the physical beginning location of the extent on the
volume in the form CCHH, where CC is the 2-byte hexadecimal number of
the DASD cylinder and HH is the 2-byte hexadecimal number of the track
within the cylinder.
LOW-RBA - the RBA, in decimal, corresponding to the LOW-CCHH
physical address of the extent.
TRACKS - the number of tracks in the extent. This is given in tracks
regardless of the space parameter in the define.
HIGH-KEY - for a KSDS data component with key ranges, specifies the
highest key value allowed for records stored within this extent of the component.
It does not necessarily indicate the highest actual key in the extent. The
maximum length key value listed is 64 bytes even though the cluster may be
defined with a key up to 255 bytes. This field corresponds exactly with the high
key specified in one of the KEYRANGES subparameter of the define.
HIGH-KEY-RBA - for the data component of a KSDS defined with key ranges,
specifies the RBA, in decimal, of the CI containing the highest keyed record in
the component or key range. This field is not a function of any define parameter.
LOW-KEY - for a KSDS data component with key ranges, specifies the lowest
key value allowed for records stored within this extent of the component. It does
not necessarily indicate the lowest actual key in the extent. The maximum length
key value listed is 64 bytes even though the cluster may be defined with a key up
to 255 bytes. This field corresponds exactly with the low key specified in one of
the KEYRANGES subparameter of the define.

18. 18
The VOLUMES Paragraph (cont'd)
PHYREC/TRK - the number of physical records of the size indicated in
PHYRECS-SIZE VSAM will write on each track of the component. This is a
function of the component's CI size.
PHYREC-SIZE - the size of each physical record (actually, physical block)
VSAM will write during storage of CIs for the component. Physical records can
be thought of as the "block size" of a CI. This value is a function of the CI size.
HI-ALLOC-RBA - the highest allocated RBA of all extents of the component
on this volume.
HIGH-USED-RBA - the highest used RBA of all extents of the component on
this volume.
TRACKS/CA - the number of tracks in each CA of the component. This value
is determined during define processing based on device type and size and type
of space allocation. If the data component is allocated in cylinders the CA size is
set to 1 cylinder. If the data component is allocated in records or tracks the CA
size is based on the smaller of the primary and secondary amounts, up to a
maximum of 1 cylinder. Based on that AMS will increase the larger number to be
an even multiple of the smaller number. That way VSAM ensures all extents will
be of an integer number of CAs. If IMBED was specified the one track taken up
by imbedded sequence set records will be accounted for in this field.
For example, if the allocation is TRACKS(90 10) the CA size will be 10 tracks.
If IMBED is specified, the CA size will be increased to 11, resulting in an actual
allocation of TRACKS(99 11).
VOLFLAG - specifies whether extents have been allocated or whether this is
a candidate volume. VOLFLAG can have three values:
CANDIDATE - this volume is a candidate for future allocations. When
this VOLFLAG is active no EXTENT information is listed.
OVERFLOW - the volume is an overflow volume on which data records
from a key range are stored. When more volumes are specified than key
ranges the "extra" volumes are considered overflow volumes. When any
key range exceeds its primary volume it will use the first overflow volume.
PRIME - For a non-key range file PRIME indicates there is at least one
extent for this component on the volume. For a key range file, PRIME
indicates this is the first volume for the particular key range.
VOLSER - the volume serial number of the volume.

19. 19
Determining Proper Space Allocation using LISTCAT Output
A LISTCAT output can be quite large and confusing. Interpreting the listing
can be frustrating. Here is a straightforward method for computing the correct
space allocation for components
Once a VSAM file is loaded, it's quite easy to find out if the allocation request
was correct, or to see how much the file is over- or under-allocated. First, get a
LISTCAT of the cluster:
LISTCAT ENTRIES(<cluster.name>) ALL
In the data component listing, find the HURBA and HARBA fields in the
ALLOCATION paragraph. These RBAs represent the overall highest used and
allocated RBAs for the entire component on all its volumes. These fields are one
greater than they should be; that makes the math easier, as the numbers are
stated in terms of whole control areas for KSDS and RRDS files.
The following relationships between HURBA and HARBA must be found:
• If the HARBA and HURBA are equal, the current allocation for the file exactly
fits in the number of allocated CAs. There may be free CIs in the last CA, but
that's only important in very small files.
• If HARBA is greater than HURBA, the difference is the amount of over-
allocation in the data component. This value is in increments of full CAs, and
tells you how many empty CAs are at the end of the component. To
determine how many CAs this represents, locate the CISIZE and CI/CA fields
in the same component listing. Multiply these two numbers together to get
the number of bytes in each CA. Then, divide that number into the difference
between the HARBA and HURBA. The result is the number of extra CAs at
the end of the component. If the TRACKS/CA field shows a cylinder-sized
CA, this value is also the number of cylinders by which the file has been over-
allocated.
Over-allocation = HARBA - HURBA
in CAs CI/CA * CISZ

20. 20
Determining Proper Space Allocation (cont'd)
Check the EXTENT count in the STATISTICS paragraph. Under SMS, more
than one extent is not a bad thing. It should even be expected for files larger
than about 400 cylinders.
A VSAM file takes its primary size, not its secondary size, when extending to
a candidate volume. Consider a file defined as CYL(1200 100). Let's assume its
primary volume is full when we need to add another record.
If there is no other volume in the pool with 1,200 cylinders free, the extent
attempt will fail, causing an ABEND in the program requesting the update.
On the other hand, when the file is defined at, say, CYL(400 400), it is more
likely another volume in the pool has 400 cylinders available. Granted the file will
be 350 cylinders or more over-allocated, but that's much better than having to
recover the file.
Because of that restriction, it is far more important to pick reasonable primary
and secondary allocations, and provide several candidate volumes, in the define.
Unfortunately there really isn't a good, simple formula to calculate this; you must
do it on a case-by-case basis.
It also means large files must be more closely monitored than small ones; it's
just a matter of scale. The user should do a LISTCAT immediately after a LOAD
to see what the percentage of space the file has actually used. That provides a
benchmark to help you determine if a file is really under-allocated or not.
Using the CYL(400 400) example, say you know the loaded file used 1,175 of
its allocated 1,200 cylinders. Then, two days later, the file is using 1,600
cylinders. Use the LISTCAT output to see if the file is allocated at 1,600
cylinders only because of the 400-cylinder extent. You may want to increase the
allocation to, say, (425 425) to compensate, or maybe (400 200) would be a
better choice.
While this method will net the file more extents, you still should try to keep the
extents down to a minimum number. As the number of extents gets larger, the
file takes longer to do I/O because of disk seek time.