* VSAMCOND TXT * --------------------------------------------- 20/03/93

             Batch program VSAMCOND, to do shrunk Listcat

-------------------------------------------------------------- Rel. 1.0




1)                      I N T R O D U C T I O N


    With VSAMCOND program you can obtain a list of files belonging to
a ICF (or VSAM) catalog in a more readable manner in respect to a
traditional Listcat made with IDCAMS. 
This listing is very concise compared to a Listcat: parameters of a
file are written only in a line, to have an overview of files that
allows an immediate display of anomalies and a catalog management
for exceptions. 
    Is possible to restrict the files listed for name, for type (Cluster,
Path, GDG etc.) or for volume, besides obviously for catalog.
Instead of a print, output can be written in a file for a further
processing or to maintain an history of your data.

    Program obtain data from catalog not directly but thru an intermediate
LISTCAT IDCAMS, that can be obtained from the same program or from a
previous step. 

    Program can accept commands thru PARM='....' in EXEC statement; 
if Listcat is generated by program itself, then an input card in SYSIN
is required with this typical IDCAMS command:
    LISTCAT ALL CAT(catalog.name)
with this command VSAMCOND will recall IDCAMS to generate a LISTCAT ALL
of the catalog on a work file (with DDname LSTWORK, open in output); 
at end of this step program continue opening the same file in input, 
reading every entry listed and 'condensing' it only in a line.
Therefore is important to use ALL in LISTCAT command: only if all 
informations are present in this transient file, VSAMCOND is capable of
extract all file attributes and features.
Moreover, can be used any variation of the command LISTCAT to reduce
the number of listed files, for example:
    LISTCAT LEVEL(qualific) ALL
to have all files starting with a specific qualifier, or
    LISTCAT ENTRY(my.file.name) ALL 
to have a list of only an entry, or
    LISTCAT CLUSTER ALL CAT(catalog.name)
to have only VSAM cluster excluding PATH, NONVSAM etc.
Is possible also to do more LISTCAT at the same time; all this listings
are queued on the same work file and are interpreted as a unique Listcat.
Anyway, SYSIN cards must have valid IDCAMS commands and so must follow
the syntax rules of IDCAMS (for example to continue a line with '-')

    MVS and VSE programs have the same parameters; CMS version cannot 
produce automatically listcat in temporary file but must read in input a 
CMS file in which there is a LISTCAT previously obtained with IDCAMS; 
default output in CMS is terminal.







2)            C O M M A N D S       D E S C R I P T I O N


    Commands (or, to be precise, options) can be put in the PARM= parameter
in the EXEC card of your jcl; every command must be divided each other 
with a comma or a semicolon; blanks between commands aren't allowed.
    In CMS version parameters are written left to VSAMCOND name, and are
the same that MVS or VSE versions.

    Let's list, one by one, these commands:

GEN    : temporary listcat (in IDCAMS format) is generated internally
         by program and so a LISTCAT command is required in SYSIN.
         A work file with DD name LSTWORK is required and must be big
         enough to contain results of IDCAMS LISTCAT you want; in MVS:
          //LSTWORK DD DSN=&&LISTWORK,SPACE=(TRK,(2,1)),DISP=(NEW,PASS),
          //           UNIT=SYSDA
         in VSE:
          // DLBL LSTWORK,'LISTCAT.TEMP',,VSAM,CAT=catalname,
                         RECORDS=(numpri,numsec),RECLEN=133,DISP=(OLD,KEEP)
         in VSE this transitory file must be previously created but must
         be empty, because in the same step this file is opened first in
         output and next in input.

         In MVS and VSE, GEN command is the default and so can be omitted;
         in CMS internal generation of listcat is not possible and this
         parameter is ignored.

NOGEN  : program take in input a file containing listing of a IDCAMS
         LISTCAT; logical default name is 'LISTCAT'; record length (if
         not set with LRECLIN= parameter) is 133 and record format
         (in MVS) must be FB.
         This parameter is the default in CMS version and cannot be 
         changed; input default file is LISTCAT VSAMCOND A1.

LRECLIN=n : record length of input listcat file; default is 133.

OUTPUT=ddname : specify DDname (or DLBL) of file on which you want to write
         program output. If isn't changed by LRECLOUT= parameter, record
         length of this file is 133. 
         By default output go in print spool in this way:
         in DD SYSOUT (in MVS version), for example:
          //SYSOUT DD SYSOUT=A
         in logical unit SYS001 (in VSE version):
          // ASSGN SYS001,01E
         in which 01E is a virtual printer defined by a LST card in POWER.
         If you want output on file pointed by OUTPUT= parameter, you must
         write, in MVS:
          //ddname DD DSN=output.file.name,DISP=  etc.
         and in VSE version:
          // DLBL ddname,'output.file.name',,VSAM,CAT=catname,DISP=(NEW,KEEP),
                         RECORDS=(n1,n2),LRECL=133

LRECLOUT=m : record length of output file; default is 133.
           If FULL parameter is present and output is on a file with
           OUTPUT= , then record length by default is 236.

NOHEADER : don't write header in output and printer control characters are
           omitted. can be shorted in NOH.

NOTITLE  : don't write Title in the first two lines, in which there is
           catalog name and date / time. The remainder of header is 
           unchanged and page skip is unaltered. Can be shorted in NOTIT.

PAGELEN=l: set printed page length; default is 58 lines.

FULL   : with this parameter VSAMCOND print a more complete report about
         files in catalog.
         Without 'FULL' every file is listed in one line, and so only the
         most important features are printed; with 'FULL' every VSAM
         file is printed on two lines reporting near every attribute
         present in a traditional LISTCAT FULL.
         If output is on a file, also with 'FULL' there is only a line
         for one entry, but record length in this case is 250 bytes 
         instead of 133: in the remainder are reported data listed in
         the second line. See later for an explain of the meaning of the
         data.

DATE   : add a date at the record start; its purpose is to accumulate
         on the same file a history of the same files in different times.
         This parameter is valid only if output is on a file (OUTPUT=
         is used).

NOEXIT : (MVS only) don't use routine ASKVTOC to collect data for NONVSAM
         files and leave blank these fields. A ICF catalog, for NONVSAM
         files, contain only filename and volume name, so is necessary
         another external routine (ASKVTOC) to know other data as extents,
         organization, record length, etc. This routine is available only
         for MVS version. Moreover, if file or volume is not available,
         an error message is printed, useful to detect possible disagrees
         between Catalog and Vtoc.
         I don't know any reason to avoid the use of ASKVTOC.

NOMECHECK: check that the name of data component and index component (if
         present) of a Vsam Cluster is an extension af the Cluster name;
         in other words data or index component names must be the cluster
         name with a qualifier (as .DATA or .INDEX) added at the end.
         If file don't agree to this standard, a message is printed.
         This check is done only for ESDS, KSDS, RRDS and AIX files.
         This command can be shorted in NOMEC.

Parameter starting with slash (/) are a negative selection for file type.

/VOLUME: don't write final report on Vsam spaces in Catalog. Note that
         in MVS, for ICF catalogs this report never exist, because vsam
         spaces don't exists.

/PATH  : avoid to print report for PATH entries.

/NONVSAM: avoid to print report for cataloged sequential files (NONVSAM
         files). MVS only; can be shorted to /NONV.

/GDG   : avoid to print report for GDG entries. MVS only.

/ALIAS : avoid to print report for ALIAS entries. MVS only.

/CLUSTER: avoid to print report for this Vsam files: ESDS, KSDS, RRDS,
         AIX, USERCATALOG, LINEAR, PAGESPACE. Can be shorted into /CLUS.

CMSFTYPE= : only for CMS version, change default FileType from 'VSAMCOND'
         as you like.

VOLDD=ddname : write final report about Vsam Spaces on sequential file 
         with ddname specified. No mean for a MVS system with ICF catalogs.

VTOCDD=ddname: write a report with all entry that take up disk space 
         (that is VTOC entry) on the sequential file with ddname specified.
         These entries are (MVS only):
         - data and index component (if present) of cluster, aix, linear
           and usercatalog 
         - MVS pagespaces
         - nonvsam files
         are excluded path, alias, and gdg
         The purpose of this report is display possible mismatch between
         Catalog and VTOC.

ONLY=  : with this parameter is possible to select by name the entries
         to print: you can write a model of the physical name, using the
         star '*' on qualifiers you want, to take the place of whatever
         number of characters. Star at the very end of the name replace
         not only characters but also whatever qualifier; can use only
         one star in every qualifier and must be only at start or at end
         of the qualifier itself.
               Correct:      SMITH.PAPER*.*NSON
                             *TH.MARY.JO*
                             *.SMITH.*
               Wrong:        *SMITH*.JOHN
                             SM*TH.JOHN

VOLONLY= : select entries in accordance with the volume specified;
         can be written only one volume; if volume name is shorter than
         six character, are selected all the disks with volume name
         starting with the characters written.

      These last following three parameters are criterion that allow
to select critical clusters, that require a reorganization or an increase
of space.

EXTENT>n : are printed only clusters (or aix) that have a number of 
         extents greater than the specified number; number of extents
         are the sum of data and index extent; if file has a index, 
         value n you put is automatically incremented by one, so to
         select files with at least a secondary extent, you can write
         EXTENT>1.

CISPLIT>n : are printed only KSDS or AIX clusters that have a number of
         control interval splits greater than the specified value.

CASPLIT>n : are printed only KSDS or AIX clusters that have a number of
         control area splits greater than the specified value.


      If is specified more that one of these parameters, conditions of
selection are as a logical OR, that is file is printed if meets at least
one of the specified conditions.
      For other conditions (ONLY=, VOLONLY= etc.) a logical AND is done,
that is file must satisfy all the specified conditions.


      Restrictions:
   Multi-volume files are not supported; both files with primary extent
multi-volume and files with secondary extent multi-volume. The program
will print only one volume, the first met on the Listcat IDCAMS.
   Is understood that Listcat in temporary file display files belonging
to the same catalog; consider this when in the same step you write
more LISTCAT commands in SYSIN (or use LVL() keyword without CATALOG() )
   Listcat input file, when you use 'NOGEN' must be of fixed record 
length otherwise program don't work correctly; if for example file has
RECFM=VBA, you must previously copy this file with a REPRO into a file 
with RECFM=FB.



3)             R E P O R T     E X P L A N A T I O N


      There are three types of report:

- standard report 
- added fields when you set 'FULL' parameter
- final report about volumes state when you have Vsam spaces



      Standard Report 
(in column number is not considered the printer control character)

Column:
  1 -  44 ! Cluster Name (or aix, path, etc.)
 45 -  48 ! Entry Type: ESDS, KSDS, RRDS, AIX, PATH, ALIAS, UCAT, NONV,
            GDG, PAGE
 49 -  55 ! Primary space of data component in tracks; is implied that
            there are always 15 tracks / cylinder, that is value is
            always correct for 3380 and 3390; other types (like old
            disk as FBA) are not supported
 56 -  61 ! Secondary space of data component in tracks;
 62 -  65 ! Primary space of index component in tracks; for NONVSAM files
            in MVS environment is present instead file organization:
            PS for sequential files, PO for partitioned libraries
 66 -  69 ! Secondary space of index component in tracks; for NONVSAM
            files in MVS there is record format instead; for example
            FB for fixed blocked, U for Undefined (for executable 
            libraries) and so on.
 70 -  73 ! Extent number of data component (not present for NONVSAM)
 74 -  77 ! Extent number of index component (not present for NONVSAM)
 78 -  83 ! Number of control interval split (only for KSDS and AIX)
 84 -  88 ! Number of control area split (only for KSDS and AIX)
 89 -  91 ! Free space data component in  % (only for KSDS and AIX)
 92 -  94 ! Free space index component in  % (only for KSDS and AIX)
 95 - 100 ! Record length; if file have variable record length, this is
            the average length (is maximum length if file is a NONVSAM)
101 - 106 ! Control interval length for data component (is BlockSize
            if file is NONVSAM)
107 - 114 ! Number of records in file; for NONVSAM files this number is
            not present: instead can be present an indicator of a special
            feature, for example SMS if file is SMS managed.
115 - 118 ! Percentage of space take up by records; is reckoned with:
            (HI-USED-RBA  /  HI-ALLOC-RBA)
120 - 125 ! Volume on which data component resides



      Report FULL

When you set 'FULL', every VSAM cluster is printed on two lines: the first
is the same that before (containing the most important data), while the
second line contain less important data. When output is on file, (OUTPUT=
parameter) line is always one and this data are added on the right of
the same record so, instead to be 133 bytes long must be 220 long.
Here we report this added data, in which columns are for an output on
a file.

Column:
130 - 137 ! Percentage of file that is read from file creation.
            Value is reckoned in this way:
              (Num.Read.Records  /  Num.Present.Records)
            This percentage can vary from 0 to many millions (because
            records in file can be very few in respect to number of reads;
            so value can be shorted with a 'K' (abbreviation for a multiply
            by 1000) or with a 'M' (a multiply by 1000000). If field is
            not present, file has 0 records.
138 - 142 ! Percentage of file that is update from creation.
            Value is reckoned in this way:
              (Num.Updated,Rec. + Num.Deleted.Rec. + Num.Inserted.Rec)
                / (Num.Present.Rec.)
            Also this value can vary and can be shorted with 'K' or 'M'.
143 - 147 ! Key length if file is a KSDS or an AIX
148 - 151 ! Key offset if file is a KSDS on an AIX
153 - 157 ! Share option in form '(n,m)'
160 - 167 ! Creation date in form  YEAR.DDD where DDD is the progressive day
170 - 175 ! Buffer size
178 - 185 ! Flags that display some other characteristics:
            are eight letters corresponding to attributes;
            if a letter is not present this attribute has default value.
            'N'   Noallocate
            'R'   Reuse
            'S'   Speed
            'I'   Imbed
            'T'   Replicate
            'E'   Erase
            'P'   Spanned
            'W'   Writecheck
189 - 192 ! Maximum record length if file has a variable length record
193 - 198 ! Control interval size if index component, if present
200 - 206 ! Total number of records of index component if present
207 - 210 ! Percentage of space take up by index component:
            is reckoned with  (HI-USED-RBA  /  HI-ALLOC-RBA)
            where  RBA is in index part
212 - 217 ! Volume on which index component resides.
219 - 226 ! Date of the last access to file (present only if output is
            on file)
228 - 235 ! Expiration date (present only if output is on file)


If we are in MVS, file is NONVSAM and output is on file (parameter
OUTPUT=) in this additional area are present this data:
133 - 140 ! Creation date of NONVSAM file
142 - 149 ! Last access date of file
151 - 158 ! Expiration date (if is 00.000, this date is not used)

If file is a NONVSAM and output is in spool, isn't present any added line.
There isn't nothing also if entry is a GDG, a PATH, a ALIAS or an
USERCATALOG.


      Report about Volumes if Vsam spaces are used

Column:
  1 -  44 ! Catalog name
 45 -  50 ! Volume name to which space belong
 55 -  64 ! Total number of tracks taken up by space
 65 -  74 ! Total number of tracks free inside space
 77 -  79 ! Extent number of VSAM space (normally is 1)
 83 -  87 ! Dataset number in VSAM space


      All fields in default report have a value if entry is a vsam
cluster or aix; if data are not present there is some problems, for
example you have omitted ALL in LISTCAT command.
      Some entries anyway don't have value in fields because IDCAMS don't
report it in LISTCAT ALL: this is what happen for NONVSAM, for PATH, 
ALIAS and GDG.
      If output is on file, you must add 1 to columns displayed before,
as already pointed out.





4)                           E X A M P L E S



- Example in VSE to a standard print of a catalog

* $$ JOB JNM=VSAMCOND,CLASS=0,DISP=D
* $$ LST LST=SYSLST,DISP=D,CLASS=X,DEST=(,PIERO),JSEP=0 
* $$ LST LST=01E,DISP=H,CLASS=A,JSEP=0
// JOB VSAMCOND --------  SYNTETICAL PRINT OF  LISTCAT CATALOG
// ASSGN SYSLST,IGN    <-- ignore IDCAMS messages for DELETE
// ASSGN SYS001,01E    <-- put shrinked Listcat in class  A
// EXEC IDCAMS,SIZE=AUTO      <-- only to delete temporary file
  DELETE  PROVA.PIERO.LISTCAT CLUSTER PURGE  CAT(CATALOGO.SYSWKA)
  SET MAXCC = 0
/*
/* ----- Step to create a temporary empty file
// DLBL LSTWORK,'PROVA.PIERO.LISTCAT',,VSAM,CAT=SYSWKA,                X
               RECSIZE=133,RECORDS=(1000,1000),DISP=(NEW,KEEP)
// EXEC OPENSAM,SIZE=AUTO,PARM='LSTWORK,133'
/* ----- Step to generate shrinked listcat
// DLBL LSTWORK,'PROVA.PIERO.LISTCAT',,VSAM,CAT=SYSWKA,DISP=(OLD,KEEP)
// EXEC VSAMCOND,SIZE=200K
      LISTCAT ALL  CAT(CATALOGO.SYSWK3)
/*
/* ----- Step to delete temporary
// EXEC IDCAMS,SIZE=AUTO
  DELETE  PROVA.PIERO.LISTCAT CLUSTER PURGE  CAT(CATALOGO.SYSWKA)
/*
/&
* $$ EOJ

Note: step with program OPENSAM has the purpose to create an empty
      transitory file; can be replaced for example by a IDCAMS DEFINE of
      a sequential file, using SAM feature.
      Temporary file cannot be created by VSAMCOND step putting
      DISP=(NEW,KEEP): this because program first open in output the
      file to write the Listcat with IDCAMS utility, then close it and
      reopen it in input; VSE don't accept an input open of a file with
      DISP=NEW, so this file must be created in a preceding step.
      Program OPENSAM simply open this file in output with the 
      specified record length and then close it.



- MVS example to standard print of a catalog:

//LISTCOND JOB (TSO,PIERO),'PIERO',NOTIFY=PIERO,
//             CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//*
//* Print of shrinked Listcat of CATALOGO.COGE
//* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
//*
//LISTCOND EXEC PGM=VSAMCOND
//LSTWORK  DD DSN=&&LISTCAT,DISP=(NEW,PASS),
//         UNIT=SYSDA,SPACE=(TRK,(2,2)),
//         DCB=(RECFM=FB,LRECL=133,BLKSIZE=1330)
//SYSPRINT DD  SYSOUT=*
//SYSOUT   DD  SYSOUT=A
//SYSIN    DD  *
  LISTCAT ALL CAT(CATALOG.COGE)
/*


- Example of VSAMCOND in CMS environment, supposing that a IDCAMS LISTCAT
  coming from a VSE or MVS is already present in a CMS minidisk with name:
     LISTCAT VSAMCOND A

  To generate the report on a CMS file write at CMS prompt:

     VSAMCOND OUTPUT=LISTCOND

  and report is in file LISTCOND VSAMCOND A.


      In the next examples we omit jcl cards, that are the same.


- Example of a Listcat of only an entry, to save on a history
  file that has name OUTPUT (in MVS):

//LISTCOND EXEC PGM=VSAMCOND,PARM='FULL,DATE,OUTPUT=OUTPUT'
//LSTWORK  DD DSN=&&LISTCAT,DISP=(NEW,PASS),
//         UNIT=SYSDA,SPACE=(TRK,(2,2)),
//         DCB=(RECFM=FB,LRECL=133,BLKSIZE=1330)
//SYSPRINT DD  SYSOUT=*
//SYSOUT   DD  SYSOUT=*
//OUTPUT   DD DSN=LISTCAT.OUTPUT.SAM,DISP=MOD   <-----
//SYSIN    DD  *
     LISTCAT ENTRY(SOCI.LIRA.ANSO) ALL  CAT(CATALOGO.SOCI)
/*

Note: See DISP=MOD to add records at end of file.
      Can be necessary to specify  LRECLOUT to fit record length to
      existing file.



- Example to detect all files requiring a reorganization (in VSE):


/* ----- LISTCAT SHRINKED OF ALL CATALOGS WITH A SELECTIN
// DLBL LSTWORK,'VSAMCOND.PIERO.LISTCAT',,VSAM,CAT=SYSWKB,             X
               DISP=(OLD,KEEP)
// EXEC VSAMCOND,SIZE=200K,PARM='NOTITLE,CASPLIT>0,EXTENT>1,/VOLUME'
  LISTCAT ALL  CAT(VSESP.USER.CATALOG)
  LISTCAT ALL  CAT(CATALOGO.SYSWK2)
  LISTCAT ALL  CAT(CATALOGO.SYSWK4)
  LISTCAT ALL  CAT(CATALOGO.SYSWK5)
  LISTCAT ALL  CAT(CATALOGO.SYSWK7)
  LISTCAT ALL  CAT(CATALOGO.SYSWK8)
  LISTCAT ALL  CAT(CATALOGO.SYSWK9)
  LISTCAT ALL  CAT(CATALOGO.SYSWKB)
  LISTCAT ALL  CAT(CATALOGO.SYSWKC)
  LISTCAT ALL  CAT(CATALOGO.SYSWKE)
  LISTCAT ALL  CAT(CATALOGO.SYSWKF)
  LISTCAT ALL  CAT(CATALOGO.SYSWKG)
  LISTCAT ALL  CAT(CATALOGO.SYSWKI)
/*

Note: title is removed because should be wrong.


