10.71 IAMPRINT Report
LISTCAT Report
The IAMPRINT report is produced by an IDCAMS LISTCAT ALL command. This report contains information about the data set attributes, the DASD volumes being used, along with the amount of space on each volume, plus various statistics about the data set. The statistics that are presented in the IAMPRINT report are generally only updated when the data set is closed. If the data set is currently open for update the statistics may not accurately reflect the current status of the data set. A message will appear at the bottom of the report if this is determined to be true by the IAM LISTCAT processor. The statistics can also be invalid due to a system failure that prevented the data set from being properly closed, or if the data set was being concurrently shared by multiple jobs for update processing, without going through IAMRLS.
LISTCAT Example
Specification of the IAMPRINT DD is optional. If the IAMPRINT DD is not specified, then IAM will allocate one to SYSOUT=* for batch jobs, providing that the SYSPRINT DD is also allocated to a SYSOUT class. For TSO users, the IAM output will be displayed directly on the screen. In both cases, the report will be produced on the IAMPRINT DD data set, if the file was explicitly specified by the user. TheIAM LISTCAT processing can be disabled by placing a //IAMNOLIC DD DUMMY card in the job step performing the LISTCATs. Using the IAMNOLIC DD card is intended for jobs that are performing generic LISTCAT operations, and the IAM information is not necessary.
JCL to Obtain IAM Listcat (IAMPRINT) Output (EX1071A)
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
LISTCAT ENT(IAMV.VAR100.CLUSTER) ALL
/*
LISTCAT Output
The results of running the above job in an IAM data set are visible in two printed reports. The first report is produced by IDCAMS on SYSPRINT that displays the information on the actual non-VSAM catalog entry for the IAM data set. The second report is produced by IAM on IAMPRINT that displays the attributes and other information about the data set itself. The two reports are shown below.
IDCAMS LISTCAT Output from SYSPRINT
LISTC ENT(IAMV.VAR100.CLUSTER) ALL 00790001
CLUSTER ------- IAMV.VAR100.CLUSTER
IN-CAT --- IAMVT.CATALOG
HISTORY
DATASET-OWNER-------$IAM CREATION--------2023.194
RELEASE----------------2 EXPIRATION------0000.000
SMSDATA
STORAGECLASS ----TSTDATA MANAGEMENTCLASS---(NULL)
DATACLASS --------(NULL) LBACKUP ---0000.000.0000
CA-RECLAIM---------(YES)
EATTR-------------(NULL)
BWO STATUS------00000000 BWO TIMESTAMP---00000 00:00:00.0
BWO---------------(NULL)
RLSDATA
LOG ------------------NONE RECOVERY REQUIRED --(NO) FRLOG ------------(NULL)
VSAM QUIESCED -------(NO) RLS IN USE --------(YES) LOGREPLICATE-------------(NO)
LOGSTREAMID---------------------IAMLOGR.RLSMQA
RECOVERY TIMESTAMP LOCAL-----X'0000000000000000'
RECOVERY TIMESTAMP GMT-------X'0000000000000000'
DATABASE -----------------(NULL)
ENCRYPTIONDATA
DATA SET ENCRYPTION-----(NO)
PROTECTION-PSWD-----(NULL) RACF----------------(NO)
ASSOCIATIONS
DATA-----IAMV.VAR100.DATA
INDEX----IAMV.VAR100.INDEX
DATA ------- IAMV.VAR100.DATA
IN-CAT --- IAMVT.CATALOG
As you can see, the IDCAMS output indicates that the data set type is non-VSAM. While the OWNER field is set to ‘$IAM’, it is not a reliable indicator that the data set is in fact an IAM data set.
IAMPRINT Output
Below is an example of the IAMPRINT Report for an Enhanced Format IAM data set. The fields displayed on the report will vary, depending on the type and status of the IAM file.
Example of IAMPRINT Output of an Enhanced Format Data Set
0IAM100 IAM FILE ANALYSIS - DSN=CPAMOB.IAQA.LOCAL.IVTK1
-------------------------------------------------------------------------------
DATASET TYPE - = KSDS - REUSABLE ------------- = YES -
RECORD SIZE -- = 200 - AVERAGE RECORD SIZE -- = 200 -
KEY SIZE ----- = 41 - KEY OFFSET ----------- = 8 -
SIMULATED CISZ = 4096 - RELEASE -------------- = NO -
SHARE OPTIONS = 2 - FREESPACE - CI% - CA% = 8 4 -
DATA COMPRESS = SOFTWARE - INDEX COMPRESS ------- = NO -
MIN 64 BUFNO - = 12500 - MAX 64 BUFNO --------- = 18200 -
ENCRYPTED ---- = YES - OVERFLOW FORMAT ------ = VARIABLE -
KEYLABEL - = IAM.KEY01 -
-
FILE DEFINED - = 2021.237 - 08/25/2021 - 1:42 PM = 13:42:55 -
FILE LOADED -- = 2021.237 - 08/25/2021 - 1:42 PM = 13:42:55 -
-
FILE FORMAT -- = LINEAR - FILE STATUS ---------- = LOADED -
CI SIZE ------ = 20480 - CI PER CA ------------ = 37 -
PHYS BLKSIZE - = 10240 - TRACKS PER CA -------- = 15 -
PHYS BLKS/TRK = 5 - BLOCK FACTOR --------- = 4 -
STORCLAS ----- = TSTDATA - MGMTCLAS ------------- = NULL -
DATACLAS ----- = IAMCRYPT - EATTR ---------------- = OPT -
VOLUME COUNT - = 1 - SPACE USED ----------- = 60 TRACKS -
VOLSER ------- = SYTS22 - SPACE ALLOCATED ------ = 75 TRACKS -
TOTAL EXTENTS = 1 - TOTAL SPACE ---------- = 75 TRACKS -
PRIMARY SPACE = 5 - SECONDARY SPACE ------ = 1 CYL -
MULTIVOL ----- = SECONDARY - MAXSECONDARY---------- = 1 -
-
HURBN ---- = 123 - TOTAL RECORDS -------- = 11,000 -
HARBN ---- = 123 - TOTAL RECORDS LOADED - = 11,000 -
PRIME DATA = 122 - TOTAL INSERTS -------- = 0 -
HURBA ---- = 2,519,040 - TOTAL DELETES -------- = 0 -
HARBA ---- = 2,519,040 - TOTAL UPDATES -------- = 0 -
-
OVRFLW BLKS - = 0 - OVERFLOW RECORDS ----- = 0 -
PE BLOCKS --- = 0 - EXT BLOCKS USED ------ = 0 -
EXT ALLOC --- = 0 - EXT BLOCKS AVAILABLE - = 0 -
-
STORAGE REQUIRED FOR PRIME INDEX ------------- = 4920 -
OVERFLOW INDEX STORAGE ESTIMATE (KB) --------- = 4 -
-------------------------------------------------------------------------------
0IAM499 IAM LISTCAT(10.0.01P SPIN LEVEL 01) PROCESSING COMPLETED
IAMPRINT Output for an Alternate Index
The IAMPRINT output for an alternate index is almost identical to the report for a base cluster. An IAM Alternate Index is essentially an IAM KSDS type of file. The file type indicates that this is an AIX (Alternate Index) data set. Below the DATA COMPRESS line, is an additional line that includes the alternate key offset in the base record, and to the right of that is the indication of whether or not the alternate index keys are unique. At the bottom of the report are the associations. The associations will also appear on a base cluster once there are defined alternate indexes and paths to that base cluster. An example of IAMPRINT for an IAM Alternate Index is as follows:
Example of IAMPRINT Output for an Alternate Index
IAM100 IAM FILE ANALYSIS - DSN=IAMV.MANUFAC.DATA.AIX
--------------------------------------------------------------------------
DATASET TYPE - = AIX - REUSABLE ------------- = YES
RECORD SIZE -- = 100 - AVERAGE RECORD SIZE -- = 100
KEY SIZE ----- = 52 - KEY OFFSET ----------- = 5
SIMULATED CISZ = 4096 - RELEASE -------------- = NO
AIX KEY OFFSET = 51 - UNIQUE KEYS ---------- = YES
SHARE OPTIONS = 1 - FREESPACE - CI% - CA% = 4 2
DATA COMPRESS = SOFTWARE - INDEX COMPRESS ------- = YES/LONG
FILE DEFINED - = 2019.337 - 12/03/2019 - 1:42 PM = 13:42:32
FILE LOADED -- = 2019.337 - 12/03/2019 - 1:42 PM = 13:42:50
FILE FORMAT -- = LARGE-FRMT - FILE STATUS ---------- = LOADED
BLOCK SIZE --- = 13682 - BLOCK FACTOR --------- = 4
STORCLAS ----- = TSTDATA - MGMTCLAS ------------- = NULL
DATACLAS ----- = NULL - EATTR ---------------- = OPT
VOLUME COUNT - = 1 - SPACE USED ----------- = 1153 TRACKS
VOLSER ------- = SYTS14 - SPACE ALLOCATED ------ = 1155 TRACKS
TOTAL EXTENTS = 1 - TOTAL SPACE ---------- = 1155 TRACKS
PRIMARY SPACE = 137 - SECONDARY SPACE ------ = 52 CYL
MULTIVOL ----- = PRIMARY - MAXSECONDARY---------- = 137
HURBN ---- = 4,611 - TOTAL RECORDS -------- = 600,000
HARBN ---- = 4,611 - TOTAL RECORDS LOADED - = 600,000
PRIME DATA = 4,591 - TOTAL INSERTS -------- = 0
HURBA ---- = 63,087,702 - TOTAL DELETES -------- = 0
HARBA ---- = 63,087,702 - TOTAL UPDATES -------- = 0
OVRFLW BLKS - = 0 - OVERFLOW RECORDS ----- = 0
PE BLOCKS --- = 0 - EXT BLOCKS USED ------ = 0
EXT ALLOC --- = 0 - EXT BLOCKS AVAILABLE - = 0
STORAGE REQUIRED FOR PRIME INDEX ------------- = 23092
--------------------------------------------------------------------------
ASSOCIATIONS -
CLUSTER ------ = IAMV.MANUFAC.DATA
AIX ---------- = IAMV.MANUFAC.DATA.AIX UPGRADE
PATH --------- = IAMV.MANUFAC.DATA.PATH UPDATE
IAM499 IAM LISTCAT(10.0.01/00P SPIN LEVEL 00) PROCESSING COMPLETED
IAMPRINT Report on a Path
The report for an IAM Path data set is similar in format to the above report, only much shorter. An IAM Path is a 1-track data set, which is used to provide access to a base cluster through an alternate index, or to the base cluster directly. The information of most interest and concern in this report is the associations. The Path serves as a connector that is used by OPEN processing to determine what data sets need to be allocated and opened.
The file attributes that are displayed, including record size, alternate key size, and alternate key offset, will reflect the data record as retrieved through the path. The record size will always be the base cluster maximum record size. If the Path is for an Alternate Index, then the alternate key size and alternate key offset will be as defined for the alternate index. If the Path is for a base cluster, then the alternate key size and alternate key offset will be the base cluster’s key size and offset.
An example of an IAMPRINT report on a PATH is shown below.
Example of an LISTCAT Output for an IAM Path
IAM100 IAM FILE ANALYSIS - DSN=IAMV.MANUFAC.DATA.PATH
---------------------------------------------------------------------------
DATASET TYPE - = PATH - REUSABLE ------------- = YES
RECORD SIZE -- = 104 - AVERAGE RECORD SIZE -- = 0
KEY SIZE ----- = 52 - KEY OFFSET ----------- = 9
SIMULATED CISZ = 0 - RELEASE -------------- = YES
SHARE OPTIONS = 1 - FREESPACE - CI% - CA% = 4 0
DATASET TYPE - = PATH - ALTERNATE KEY SIZE --- = 52
RECORD SIZE -- = 325 - ALTERNATE KEY OFFSET - = 51
STORAGE REQUIRED FOR PRIME INDEX ------------- = 16
---------------------------------------------------------------------------
ASSOCIATIONS -
CLUSTER ------ = IAMV.MANUFAC.DATA
AIX ---------- = IAMV.MANUFAC.DATA.AIX UPGRADE
PATH --------- = IAMV.MANUFAC.DATA.PATH UPDATE
IAM499 IAM LISTCAT(9.4/01P SPIN LEVEL 00) PROCESSING COMPLETED
IAMPRINT Field Descriptions
The fields on the IAMPRINT report for an Enhanced format file are described below. The table starts with the fields on the left column of the report, and is followed by all of the fields on the right column of the report. The last portion describes the fields that appear as a single column at the bottom of the report.
The header of the report has an IAM400 message followed by the IAM100 message. The message numbers are not displayed when the output is directed at a TSO terminal. The IAM400 message indicates that the report is from a catalog information request (i.e., LISTCAT) along with the version and level of IAM producing the report. The date and time of the report is included in that message. The data set name is indicated on the IAM100 message.
IAMPRINT Field Descriptions (Left column)
Left Column: | Description of Field Contents: |
|---|---|
File Format | Indicates the file format use to store the data. Possible values are: ENHANCED – Indicates that the file is an enhanced format IAM file. LARGE-FRMT – Indicates an Enhanced format IAM file that is stored in a Large Format sequential data set, meaning, that it can exceed 64K tracks per volume. SMS-EXT – Indicates that the file is a SMS Extended format and an IAM enhanced format file. ENCRYPTED - Indicates that the file is a Pervasively Encrypted IAM enhanced format file stored on DASD as a SMS Extended format VSAM Linear file. COMPATIBLE – Indicates that the file is a compatible format file, which can be used with the older non-VSAM interfaces toIAM. |
Record Size | The maximum amount of data that can be contained in a single record. Value is from the RECORDSIZE parameter on the IDCAMS DEFINE statement. |
CI Size | The specified Control Interval (CI) size from the DEFINE. If CI size was not specified on the Define, IAM calculates a valid VSAM CI size based on the maximum record size. |
Block Size | The physical block size IAMis using for the file. A block is the amount of data transferred in an I/O operation, and that is stored in a single contiguous stream of data on the actual device |
Block Factor | Indicates the number of blocks per track, or the user specified block size from an IAM CREATE Override. |
Var Overflow | Indicates if IAM is using variable length overflow for this file. If the value is YES, IAM will put as many records as can fit within each overflow block. If the value is PRO, then IAM is using the Prime Related Overflow format, which is a variable length overflow. If the value is NO, IAM will only place in each overflow block the number of maximum length records that will fit in an overflow block. |
Key Size | For KSDS type of files, indicates the defined length for the key of each data record. |
Key Offset | Specifies the relative position of the key, as an offset from the beginning of the record, where a value of 0 indicates the first byte. For an AIX type of data set, this is the key offset within the alternate index data set itself, and will always be 5. |
File Type | Indicates the file type. Possible values are: KSDS – Keyed sequence data set ESDS – Entry sequence data set. ESDS/P – Entry sequence data set with PSEUDORBA. ESDS/EA – Entry sequence data set with 8-byte RBA values. AIX – An IAM Alternate Index data set PATH – An IAM Path data set RRDS – Fixed length record RRDS VRRDS – Variable length record RRDS |
Device Type | Indicates the type of DASD device architecture on which the data set currently resides, for example a 3390. |
EATTR | If the file was defined with an EATTR attribute this line is printed and the value appears here. Possible values are OPT or NO. |
Volume Count | The number of volumes contained in the catalog entry for this file. |
Volser | This indicates the volumes to which the data set is cataloged. This line is repeated for each volume that is in the catalog entry for the file, except for SMS candidate volumes. |
Total Extents | Indicates the total DASD extents allocated to the file. An extent is a contiguous area of space on the device being used by the data set. |
Primary Space | Indicates the requested primary space quantity that was specified when the file was originally defined. |
Multivolume | Has a value of PRIMARY or SECONDARY, which indicates from which space parameter the size of the first extent on each DASD volume is allocated. |
Release | Indicates if DASD space will be released when the file is loaded again. Generally this is YES before a file has been loaded, and is set to NO after the first load. |
Data Compress | Indicates whether this file can contain IAM data compressed records. Possible values are: YES – Indicates file is eligible for IAM software compression. HARDWARE – Indicates file is eligible for IAM use of the IBM hardware compression function. NO – No data compression will be performed for this file. |
Dictionary | Indicates the name of the hardware compression dictionary that the user has specified for this file. This is only present when the file is enabled for hardware compression. A value of *DYN indicates that the dictionary was dynamically built by IAM during the load of the file. Any other value indicates the name of customized hardware compression dictionary. |
RLSID | Displays the four character name of the preferred RLSID of an IAM RLS address space for this data set. This field is only displayed if the data set was DEFINED or LOADED with the IAM CREATE Override of RLSID. If the displayed RLSID is prefixed with an ‘*’, then it is displaying the value of the RLSID from the current Global Options Table, and indicates that the RLSID keyword was specified on the CREATE override with no value. |
AIX Key Offset | For an Alternate Index type of data set, indicates the offset of the alternate key within the base cluster. |
Total Records | The number of user data records in the file, as of the last close. |
Updates | The number of user data records that have been updated since the file was last loaded. |
High Used RBA | For IAM KSDS files, indicates the amount of space used for the file, in bytes. For IAM ESDS files, indicates the amount of actual user data contained within the file. |
IAM Journal | Indicates that IAM journaling has been specified, either through the JRNAD= IAM override, or through the LOG() IDCAMS define keyword. Possible values are ENABLED indicating that IAM journaling is active, or NONE indicating journaling has been explicitly disabled for this file. |
IAMPRINT Field Descriptions (Right column)
Right Column: | Description of Field Contents: |
|---|---|
File Status | Indicates if the file is LOADED or UNLOADED. A file will be in the UNLOADED state if it has been defined but has not had a successful load, or if a file load or reorganization has failed or is in progress. |
Avg Record Size | Value is the average record size specified when the file was defined, which may not be equal to the actual stored average record size. |
Freespace - CI% - CA% | The amount of CI% and CA% free space specified on the file definition. |
Extended Overflow - Recs | The number of records in the Extended Overflow area of the file, as of the last time the file was closed. |
Requested Overflow - Recs | This is the overridden value for the size of the overflow area, in records, when the file was defined or loaded. This value, if provided, will be used when calculating the percentage of overflow used. |
Extended Overflow Blocks | The number of blocks assigned to the Extended Overflow area. |
Extended Overflow Used | Indicates, as a percentage, the amount of overflow space used. If a value for overflow records is provided as an override (O=), then the used percentage is based on that value. Otherwise, this is the percentage of the currently allocated extended blocks that are being used. |
Extended PE | The number of Extended blocks assigned as Prime Extension (PE) blocks. |
Extended Allocated | The total number of extended area blocks that the file can contain within the currently allocated extents. |
Extended Available | The number of extended area blocks that are available for use, which could be assigned to either Extended Overflow, or Extended PE. |
EADSCB | Specifies whether or not this data set has the type of dscb (VTOC entry) that would make the data set eligible for an EAV volume. Only printed if EATTR has been specified. |
Space Used | The amount of DASD space currently required for the file. (Does not include space required for Extended Available blocks.) |
Space Allocated | For each volume, indicates the amount of DASD space allocated, in tracks. |
Total Space Allocated | Total DASD space allocated, for all volumes. |
Secondary Space | Indicates the amount of space to be requested when a secondary extent is required, as specified on the file defines. |
Max Secondary | The maximum amount of DASD space IAM will request, when additional DASD space is needed for this data set. |
Share Options | Indicates the defined cross-region share option. |
Index Compress | Indicates whether a compressed index structure exists for this file. |
Dictionary Saved | When the IAM file is compressed by hardware, indicates either YES that the dictionary has been saved within the data set, or NO that the dictionary is not contained within the data set. |
RLS USAGE | Indicates if IAM RLS processing is REQUIRED or only REQUESTED for this data set. This will only be displayed if the IAMCREATE Override of RLSID was specified when this data set was defined or loaded. The value displayed of REQUESTED or REQUIRED is based on the settings of the RLS keyword in the IAM Global Options Table. If OPTIONAL is specified, then the value will be REQUESTED, otherwise it will indicate REQUIRED. |
Unique Keys | For an alternate index, indicates if the alternate keys are UNIQUE (YES) or NONUNIQUE(NO). Unique keys means that each alternate key can only index one data record in the base cluster. A value of NO means non-unique keys, where each alternate key can index multiple data records in the base cluster. |
Inserts | Indicates the number of records added since the file was last loaded. |
Deletes | Indicates the number of records deleted since the file was last loaded. |
High Allocated RBA | Total number of bytes of DASD storage allocated to the file. For ESDS type files, this value can actually be lower than the High Used RBA field. The reason is that the High Used is based on the length of the actual user data. If the file is data compressed, the high allocated could be substantially lower. |
Alternate Key Size | Field is printed for a Path type of data set only, indicates the size of the key for the data accessed via this path. For a path on an alternate index, this will be the alternate key size. For a path on a base cluster, this will be the primary key size. |
Alternate Key Offset | Field is printed for a Path type of data set only. This is the key offset for the data as accessed via this path. For a path on an alternate index, this is the offset of the alternate key within the prime record. For a path on a base cluster, this is the offset of the primary key. |
Journal Records | Indicates what type of journal records will be produced. Possible values include ALL, BEFORE, AFTER or NONE. |
IAMPRINT Field Descriptions (Center column)
Center Column: | Description of Field Contents: |
|---|---|
File Defined | The date and time when the file was last defined. The date can be in either mm/dd/yyyy format, or if the EURODATE Global Option is set, will be in the dd/mm/yyyy format. |
File Loaded | The date and time that the last file load was completed. However, if a file load had started, but is not yet complete, this time will be the starting time of the last attempted file load. |
Last Updated | The date and time of the last close of the file from a program that updated the file. |
Pseudo Maximum Logical Record Length | If a PSEUDOLRECL value was specified when the file was defined, this field will appear with the value that was specified. Programs doing a SHOWCB for the LRECL field, or a SHOWCAT will be returned this value for the maximum record length in the data set. |
Storage Required for (Compressed) Prime Index | Indicates the amount of virtual storage that is required to contain the index to the Prime Data area of the file, and whether or not the index has been compressed. |
Number of IAM Data Blocks | Indicates the number of blocks in the data set preceding the index area. This value may need to be supplied via the MAXBLKS parameter to IAMRECVR on a RECOVER operation. |
Extended High Allocated RBN | Indicates the high allocated block number, to be used when it is necessary to run IAMRECVR to recover a file after it has been damaged. Value is specified via the XTNDEDHARBN keyword. |
A few additional informational messages may appear based on the status of the file at the time the LISTCAT was done. Unless they do not reflect the actual file status, they generally are of no major concern. These messages include the following:
FILE REORG HAS STARTED, AND HAS NOT COMPLETED
FILE REORGANIZATION IS RECOMMENDED
FILE IS OPEN, STATISTICS MAY BE INACCURATE
Associations
For IAM data sets that are part of an Alternate Index Sphere, there will be an Associations section of the report. This section will follow all of the above described sections, and include an entry for each associated data set. The data set name will be preceded by the type of data set (Cluster, AIX, or Path). Then after each AIX entry name, the UPGRADE or NOUPGRADE attribute will be displayed. For Path’s, the UPDATE or NOUPDATE attribute will be displayed. The data set names displayed are those that have been defined. If one or more of the associated data sets has been renamed, copied to a new name, or restored with a new name, then a DEFINE RECATALOG must be performed to update the association information. See Section 10.65 for information on performing a Define Recatalog.