VTOC TSO Command

The VTOC TSO command displays information from the Volume Table of Contents of selected DASD.  It allows an incredible permutation of various selection criteria, yielding a very powerful command for your toolbox.

It is located in File #112 of the older version #129 CBT tape.  It was written by R. L. Miller of Fireman's Fund Insurance in San Rafael, CA.  There is a later version of VTOC on the more current versions of CBT, but they require modification in order to install/use on MVS 3.8j, and this version is quite acceptable on our older version of MVS.

 

Installation

The older versions of the CBT tape, including #129 require a bit of pre-processing to get to the point of installing.  So, I have done several steps "behind the scene".  First, I extracted the CBT tape image to individual files on a 3350 volume.  File #112 is in IEBUPDTE format, so I then "punched" the file to get it over to a PC manageable file.  Then I modified the install JCL to achieve a single jobstream that:

  • uses IEBUPDTE to create an install PDS with the source, macro and help text
  • assembles and link-edits the VTOC load modules into SYS2.CMDLIB
  • copies the help text into SYS2.HELP

and then deletes the PDS created in the first step.  There were no changes required to any source in order to install a working copy of VTOC under MVS 3.8j.  If you do not have SYS2.CMDLIB and SYS2.HELP defined on your system, you can edit the jobstream, replacing these names with SYS1.CMDLIB and SYS1.HELP before submitting it.

The resulting jobstream - vtoc$.jcl - is contained in the archive vtoc.tgz [MD5: 9EEC83EF8D519883349560ADDEE9AFB2].  Download the archive and extract the jobstream (WinZip on Windows/?? or tar on Linux).  Submit the jobstream and you are done.

 

Utilizing VTOC

The help text provided for VTOC is quite thorough, so I have simply reproduced it here (with some formatting changes to make it more readable).  There was one option that took me a while to figure out - specifying multiple volumes - so I have added an example of that below.

 

Syntax -

   VTOC     'VOLUME-LIST'    LEVEL('DSNAME-START')
                             CONTAINING('DSNAME-STRING')
                             ENDING('DSNAME-END')
                             BREAK('BREAK-CHARS')
            CAT
            NOSORT/SORT('SORT-FIELDS')
            NOPRINT/PRINT('PRINT-OP' ('PRINT-ITEM-LIST'))
            LIMIT('KEYWORD' 'OPER' 'VALUE')
            AND1/OR1('KEYWORD' 'OPER' 'VALUE')
            AND2/OR2('KEYWORD' 'OPER' 'VALUE')
            AND3/OR3('KEYWORD' 'OPER' 'VALUE')
            CHARS('CHARS-PER-LINE')
            LINES('LINES-PER-PAGE')
            NOHEADING/HEADING('TEXT')
            DSNLEN('LENGTH')

Required - 'VOLUME-LIST'
Defaults - list all datasets on the volume(s) selected.
           SORT, PRINT

Operands -
'VOLUME-LIST'
 A volume serial number or a list of volume serial numbers.  If the first one to five characters of a volume serial number are entered, all volumes taht are mounted on the machine which start with those characters will be listed.  If 'ALL' is specified, all non-virtual volumes which are online and ready will be processed.  If 'ALV' is specified, all virtual volumes which are online and ready will be processed, if they are mounted PRIVATE/RESERVED or PRIVATE/RESIDENT. 
LEVEL('DSNAME-START')
 Specifies the high level qualifiers to be searched.  This will not be prefixed by your USERID or prefix.  Only datasets starting with these prefixes will be listed. 
CONTAINING('DSNAME-STRING')
 Specifies a character string contained in the dataset name.  At least one of the strings must be in the DSName for the dataset to be listed.  These strings must conform to DSName standards.  They cannot begin with a period or a number. 
ENDING('DSNAME-END')
 Specifies the ending characters of the DSName.  The final nonblank characters of the DSName must be one of these strings to allow the dataset to be listed.  These strings must conform to DSName standards. 
CAT
 A locate is done for each DSName on the volumes listed and status is indicated.  Note - this option uses a considerable amount of processing time.

   C - catalogued on this volume
   N - not catalogued
   W - catalogued on another volume
   E - catalog processing error

 
NOSORT
 The datasets are not sorted.  They are output as they are found. 
SORT('SORT-FIELDS')
 Datasets are sorted into alphabetical order, based upon the sort fields specified.  DSNAME, VOLUME, ALLOC, USED, UNUSED, PCT, EX, DSO, RFM, LRECL, BLKSZ, CDATE, EXPDT, REFDT are valid sort fields.  

'A/D' are required after each sort field to indicate ascending/descending sequence.

 
BREAK('BREAK-CHARS')
 The listing will contain a new header (on a new page if the VTOCOUT DD card option is used),  whenever the specified number of characters differs from the preceding dataset.  This option functions only with the SORT option. 
CHARS('CHARS-PER-LINE')
 Specifies the number of characters on each line of output.  The default is 150 for print and the LINESIZE of the terminal for TSO sessions.  You can get more information by specifying a larger number of characters per line or you can limit the printing by setting a smaller number of characters per line of output. 
LINES('LINES-PER-PAGE')
 Specifies the number of lines before a new title line is produced.  It defaults to 60 for print and to the screen size for TSO sessions. 
NOHEADING
 Do not produce a heading.  The heading will only be output if the VTOCOUT DD statement is present. 
HEADING('TEXT')
 If a DD statement with a DDName of VTOCOUT is present, this text will be used to begin every page.  Carriage control should be included (ASA).  The default header consists of VTOC COMMAND VERSION 02 and the command that was entered. 
DSNLEN('LENGTH')
 Specifies the length of the DSName to print.  The rest of the DSName is truncated.  The CHARS parameter will also cause the DSName to be truncated, if the name and the preceding information exceeds the print line. 
NOPRINT
 Specifies that individual items are not to be listed.  The command can be used to calculate totals from the selected datasets. 
PRINT('PRINT-OP' ('PRINT-ITEM-LIST'))
 Specifies the items to print.  The 'PRINT-OP' is the operation to be done.  They include the following:

  NEW - The 'PRINT-ITEM-LIST' is a complete list of what to print.
  REP - The first 'PRINT-ITEM' will be replaced with the rest of the items on the list.
  ADD - The rest of the 'PRINT-ITEM-LIST' will be added after the first item on the list.
  DEL - The items on the 'PRINT-ITEM-LIST' will not be printed.

The 'PRINT-ITEM-LIST' names are the same keywords used in LIM, AND, and OR functions and are also the titles as printed.  

The ADD, DEL, and REP print operations refer to the default print list.  The default list is ALLOC, UNUSED, PCT, EX, DSO, RFM, BLKSZ, LRECL, REFDT, CDATE, VOLUME, DSNAME, EXPDT, SECQ, SECT, ROUND, PASS, ACTION, and TYPE.

As noted under CHARS above, only the items that will fit on the print line will be listed.

 
LIMIT('VALUE' 'OPER' 'KEYWORD')
 Specifies which datasets are to be listed.  Only datasets that satisfy the relation are listed. 
'KEYWORD'
 Is the name of a dataset field.  The list of currently provided fields follows.  The keywords and their values are the same as in teh VTOC output.

  ALLOC - dataset allocation, number of KILOBYTES, TRACKS, CYLINDERS, or MEGABYTES allocated.  Default is KILOBYTES.

  UNUSED - amount of unused space in the dataset.  Same units as in ALLOC.

  USED - amount of space used in the dataset.  Same units as in ALLOC.

  PCT - percentage of space used in the dataset.

  EX - number of extents in the dataset.

  DSO - dataset organization - PS=sequential, PO=partitioned, VS=VSAM, IS=ISAM, DA=Direct Access, U=Unmoveable

  RFM - record format - F=fixed, V=variable, U=undefined, B=blocked, T=track overflow, S=spanned or standard, A=ASA carriage control, M=Machine carriage control

  BLKSZ - blocksize for physical blocks of data

  LRECL - logical record length in bytes

  CDATE - create date in the form YYDDD, sometimes called Julian

  EXPDT - expiration date in the same form

  REFDT - last use date in the same form; this date is when the dataset was last opened

  SECT - type of allocation - A=absolute track, B=blocks, T=tracks, C=cylinders

  PASS - protection indicators - N=none, R=read and write protection, W=write protection

  ROUND - space rounded up to cylinders - R=round, N=no round

  CCHH - cylinder and head address, in 4 or 8 hexadecimal digits.  If 4 digits are used, only the cylinder is used for comparison, otherwise, the CYL and TRACK are compared.

  VOLUME - volume serial or disk name

  DSNAME - name of the dataset

  ACTION - some error indications

  TYPE - reserved for exit usage

 

 
'OPER'
 Is an operator.  The list of operators follows:

  EQ - is equal to
  NE - is not equal to
  LE - is less than or equal to
  LT - is less than
  GE - is greater than or equal to
  GT - is greater than

 
'VALUE'
 Gives the value of the item for comparison, such as FB, PS, R, or a number. 
AND1('VALUE' 'OPER' 'KEYWORD')
 Specifies which datasets are to be listed.  Both the limit and this condition must be true to allow the listing. 
OR1('VALUE' 'OPER' 'KEYWORD')
 Specifies which datasets are to be listed.  Either the limit or this condition must be true to allow the listing. 
AND2('VALUE' 'OPER' 'KEYWORD')
 Specifies which datasets are to be listed.  Both the previous result and this condition must e true to allow the listing. 
OR2('VALUE' 'OPER' 'KEYWORD')
 Specifies which datasets are to be listed.  Either the previous result or this condition must be true to allow the listing. 
AND3('VALUE' 'OPER' 'KEYWORD')
 Specifies which datasets are to be listed.  Both the previous result and this condition must e true to allow the listing. 
OR3('VALUE' 'OPER' 'KEYWORD')
 Specifies which datasets are to be listed.  Either the previous result or this condition must be true to allow the listing. 
Examples -
List all datasets on volume 
VTOC VOL
List all datasets on all volumes 
VTOC ALL
List all datasets that start with XXX on any MVXXXX volume 
VTOC MV LEV(XXX)
List all recently created datasets 
VTOC VOL LIM(CDATE GT 79001)
List datasets with unused space 
VTOC VOL LIM(PCT LT 50)  - OR1(UNUSED GT 30)
List datasets with multiple extents 
VTOC VOL LIM(EX GT 1)
List all of user's datasets on TSO0001 
VTOC TSO001 LEVEL(TMTCEXX)
List all datasets over 100 tracks 
VTOC VOL LIM(ALLOC GT 100)
List datasets under the fixed heads 
VTOC VOL LIM(CC EQ 0001) -
OR1(CC EQ 0002)
List used space instead of unused, in tracks 
VTOC VOL PRINT(REP (UNUSED USED)) TRK
List CLIST datasets 
VTOC VOL END(CLIST)
List all of the information about user's datasets at a 3270 
VTOC VOL CHAR(150)
Check if datasets are catalogued on this volume 
VTOC VOL CAT PRINT(NEW (ALLOC PCT CAT DSNAME))
List all datasets on 335XXX volumes sorted by ALLOC in descending sequence, VOLUME and DSNAME in ascending sequence 
VTOC 335 SORT(ALLOC,D,VOLUME,A,DSNAME,A)
List all datasets beginning with SYS2 on volumes MVSRES and SMP001 
VTOC (MVSRES SMP001) LEVEL(SYS2)

I hope that you have found my instructions useful.  If you have questions that I can answer to help expand upon my explanations and examples shown here, please don't hesitate to send them to me:

This page was last updated on April 22, 2008 .