The LISTCAT command:

Using LISTCAT andInterpreting Its Output

By Dan O'DeaNovember 1, 1998

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>

2

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.

3

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.

4

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.

5

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.

6

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.

7

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).

8

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.

9

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.

10

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).

11

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.

12

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.

13

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.

14

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

15

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.

16

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.

17

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.

18

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

19

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.

20