CATALOG

File 8
Op-Sys z/OS, z/VSE, BS2000
Statement FIND
Task This view displays the catalog information of a specified file.

In BS2000, the information retrieved is the same as returned by the BS2000 system command /FSTAT or /SHOW-FILE-ATTRIBUTES.

In z/VSE , if either VSAM-CATALOG or USER-CATALOG is specified, or OPTION='MASTER', information is returned from the appropriate VSAM catalog. Otherwise, information is returned only for files currently known to Entire System Server in its internal table - files in standard and partition standard/class labels, temporary labels defined before the // EXEC card, and files accessed during the current Entire System Server session.

Common Fields for all Operating Systems

Dictionary Field Name F/L Mu DE Remarks
ERROR-CODE N3      
ERROR-TEXT A58      
NODE N5   D  
NODE-NAME A16   D  
SYSTEM-MESSAGE-CODE A10      
DSNAME A54   D Required in z/OS.
VOLSER A6   D  
TYPE A8   D  

Additional Fields Supported for z/OS

Dictionary Field Name F/L Mu DE Remarks
DEVICE B4      
FILE-SYSTEM A3   D  
PREFIX A3   D  
SERIES A8   D  

Additional Fields Supported for z/OS, z/VSE

Dictionary Field Name F/L Mu DE Remarks
CLASS A4   D  
NUMBER-OF-VOLUMES N3     Under z/VSE , valid only when information is being returned from VSAM catalogs.
OPTION A8   D
USER-CATALOG A44   D
VOLUME-SEQUENCE N3    

Additional Fields Supported for z/VSE

Dictionary Field Name F/L Mu DE Remarks
CLASS A4   D  
DEVICE-TYPE A4   D Valid only when information is being returned from VSAM catalogs.
FILE-NAME A7   D Valid only when information is being returned from Entire System Server's internal file table.
LABEL-AREA A8    
LIBRARIAN A3   D
VSAM-CATALOG A8   D Valid as a descriptor only for retriving information from VSAM catalogs, and valid as a returned item only when information is being returned from Entire System Server's internal file table.

Additional Fields Supported for BS2000

Dictionary Field Name F/L Mu DE Remarks
SYSTEM-CODE B2      
FILE-SIZE N10      
STATE A6   D Search criteria only.
SUPPORT-TYPE A9   D Search criteria only.
BACKUP-TYPE A11   D Search criteria only.
ACCESS-TYPE A5   D Search criteria only.
FCBTYPE A11   D Search criteria only.
PASSWORD-OPTION A9   D Search criteria only.
SHARE A3   D Search criteria only.
GEN A3   D Search criteria only.
BLOCK-CONTROL-OPTION A21   D Search criteria only.
CREATION-RANGE A19   D Further define range.
EXPIRATION-RANGE A19   D Further define range.
LAST-ACCESS-RANGE A19   D Further define range.
EXTENT-RANGE A13   D Further define range.
SIZE-RANGE A19   D Further define range.
FREE-SIZE-RANGE A19   D Further define range.

Relevant Error Codes

Code Text z/OS z/VSE BS2000
530 Access denied by Security Facility.     X
562 Catalog entry not found. X    
565 Syntax error in dataset name.     X
566 Syntax error in catalog name. X    
567 Invalid OPTION, specify LONG or USERCAT X    
604 No volumes specified.     X
699 Not enough main storage available.     X
701 DSNAME missing.     X
722 Requested dataset not found.     X
733 User ID does not exist.     X
750 Invalid operand within operand list.     X
786 Unable to obtain / release storage for CSI work area. X    
787 CSI request failed, Module :1:, Reason :2:, RC :3: X    
788 Unable to substitute :1:, RC :2: X    
789 Unable to get UCB copy for :1:, RC :2: X    
798 Task was not started under TSOS.     X
799 Entire System Server internal error.     X
996 Volume not online.     X

Field Descriptions

Field Name Format/Length Operating System
ACCESS-TYPE (A5) BS2000

List all files accessible by READ or WRITE. Possible options:

  • R or READ

  • W or WRITE

Field Name Format/Length Operating System
BACKUP-TYPE (A11) BS2000

Search criteria only, this field is returned unchanged. Files of the specified type(s) are listed. Possible types: A, B, C, D, E. Multiple types must be given as: A,B,C.

Field Name Format/Length Operating System
BLOCK-CONTROL-OPTION (A21) BS2000

Search criteria only, this field is returned unchanged. Retrieves files with specified control type. Possible values:

  • DATA

  • NO

  • NONE

  • PAMKEY

Multiple values must be separated by commas and enclosed in brackets, for example: (PAMKEY,DATA).

Field Name Format/Length Operating System
CLASS (A4) z/OS, z/VSE

Device class (for example, DASD).

Field Name Format/Length Operating System
CREATION-RANGE (A19) BS2000

 Further defines ranges for catalog entries. Lists all files with a creation date as follows:

Creation Date Explanation
(,YY-MM-DD) Files created before the specified date.
(YY-MM-DD,) Files created since the specified date.
(YY-MM-DD,YY-MM-DD) Files created between the specified dates.
YY-MM-DD Files created on the specified date.
Field Name Format/Length Operating System
DEVICE (B4) z/OS

The internal UCBTYP device code which identifies the device type on which the dataset resides.

Field Name Format/Length Operating System
DEVICE-TYPE (A4) z/VSE

The type of the device where the NONVSAM file resides.

Field Name Format/Length Operating System
DSNAME (A54) z/OS, z/VSE, BS2000

Dataset name or dataset name prefix.

z/OS If the value specified is a prefix, information on all datasets with that prefix (including DSNAME itself) is retrieved (see the field PREFIX).

As an extension to the search criteria described in Search Criteria with the FIND Statement in Section Getting Started, a double asterisk (**) may be used to represent zero or more qualifiers, whereas a single asterisk is used to specify either a qualifier or one or more characters within a qualifier. A double asterisk cannot precede or follow any characters; it must be preceded or followed by either a period or a blank.

Note:
Dataset names are returned in the order of their corresponding catalog records, i.e. not necessarily in ascending order.

BS2000 This field specifies the file name.

An asterisk * can be used as wildcard as in the /FSTAT command.

Field Name Format/Length Operating System
EXPIRATION-RANGE (A19) BS2000

Further defines ranges for catalog entries. List files with an expiration date as follows:

Expiration Date Explanation
(,YY-MM-DD) Files expired before specified date.
(YY-MM-DD,) Files expired since specified date.
(YY-MM-DD,YY-MM-DD) Files expired between the specified dates.
YY-MM-DD Files expired on the specified date.
Field Name Format/Length Operating System
EXTENT-RANGE (A13) BS2000

Further defines ranges for catalog entries. List files with number of extents within a given range.

(,n) Files with fewer extents than specified number.
(n,) Files with more extents than specified number.
(n,m) Files with extents between specified numbers.
n Files with n extents.
Field Name Format/Length Operating System
FCBTYPE (A11) BS2000

Search criteria only, this field is returned unchanged. List all files with specified type(s). Possible options:

  • B or BTAM

  • I or ISAM

  • N or NONE

  • P or PAM

  • S or SAM

Specification of multiple types is possible, for example, (P,I).

Field Name Format/Length Operating System
FILE-NAME (A7) z/VSE

File name as specified in the DLBL statement for the dataset.

Field Name Format/Length Operating System
FILE-SIZE (N10) BS2000

Number of PAM pages allocated by a file.

Field Name Format/Length Operating System
FREE-SIZE-RANGE (A19) BS2000

Further defines ranges for catalog entries. List files with a number of free PAM pages expressed as follows:

(,n) Files with fewer free pages than specified number.
(n,) Files with more free pages than specified number.
(n,m) Files with free pages between specified numbers.
n Files with n free pages.
Field Name Format/Length Operating System
FILE-SYSTEM (A3) z/OS

Indicates if the catalog entry describes a z/OS UNIX file system data set (HFS or #). Possible values:

blank Not a file system data set.
HFS HFS data set.
zFS zFS data set.
Field Name Format/Length Operating System
GEN (A3) BS2000

Specify YES to list the files of a generation group.

Field Name Format/Length Operating System
LABEL-AREA (A8) z/VSE

Indicates the LABEL AREA where the LABEL is situated. Possible values:

Value Explanation
PARSTD Partition standard.
STD Standard.
TEMP Temporary.
Field Name Format/Length Operating System
LAST-ACCESS-RANGE (A19) BS2000

Further defines ranges for catalog entries. List files with last access date within a time range given as follows:

(,YY-MM-DD) Files accessed before specified date.
(YY-MM-DD,) Files accessed since specified date.
(YY-MM-DD,YY-MM-DD) Files accessed between the specified dates.
YY-MM-DD Files accessed on the specified date.
Field Name Format/Length Operating System
LIBRARIAN (A3) z/VSE

Possible options:

Option Explanation
NO  If dataset is not a z/VSE LIBRARIAN file.
YES  If dataset is a z/VSE LIBRARIAN file.
Field Name Format/Length Operating System
NUMBER-OF-VOLUMES (N3) z/OS, z/VSE

Number of volumes of dataset.

Field Name Format/Length Operating System
OPTION (A8) z/OS, z/VSE

 Possible options:

Option Explanation
LONG  Scan entire catalog. This is required if a file name value such as *MACLIB* is specified. The catalog whose name is given in USER-CATALOG is scanned. If the user catalog name is not specified, the system catalog is scanned (z/OS only).
MASTER Indicates that data is to be retrieved from the VSAM master catalog (z/VSE only).
USERCAT  Return names of all user catalogs in the USER-CATALOG field (z/OS only).
Field Name Format/Length Operating System
PASSWORD-OPTION (A9) BS2000

List the files with password options expressed as follows:

  • E or EXPASS

  • N or NONE

  • R or RDPASS

  • W or WRPASS

Multiple options can be specified, for example: (R,N).

Field Name Format/Length Operating System
PREFIX (A3) z/OS

 Possible options:

Option Explanation
YES  Default. Information on datasets with the value of the DSNAME field as prefix is retrieved.
NO  Value of the DSNAME field is taken as absolute dataset name, not a prefix.
Field Name Format/Length Operating System
SERIES (A8) z/OS

 Device series (for example, 3330-1).

Field Name Format/Length Operating System
SHARE (A3) BS2000

 Possible options:

Option Explanation
NO  List non-shareable files.
YES  List shareable files.
Field Name Format/Length Operating System
SIZE-RANGE (A19) BS2000

Further defines ranges for catalog entries. List files with size within a given range. Size means number of PAM pages:

(,n) Files smaller than specified number.
(n,) Files larger than specified number.
(n,m) Files with size between specified numbers.
n Files of size n.
Field Name Format/Length Operating System
STATE (A6) BS2000

 Search criteria only, this field is returned unchanged. Specifies state of file. Possible options:

Option Explanation
blank  List all files.
NOCLOS  List all open files.
Field Name Format/Length Operating System
SUPPORT-TYPE (A9) BS2000

 Active search criteria. List all files that are on public or private disks or on tapes. Possible options:

Option Explanation
PRV  Private.
PUB  Public.
TAP  Tapes.

These values can also be combined, for example: (PUB,PRV) for public and private.

The following values are returned: PUBLIC, PRDISC, MIGRAT or TAPE. MIGRAT indicates migrated files.

Field Name Format/Length Operating System
TYPE (A8) z/OS, z/VSE ,   BS2000

 Dataset type. Possible values:

z/OS ALIAS Alias.
AIX Alternate index
CLUSTER VSAM cluster.
DATA VSAM data component.
GDG Generation data group.
GDS Generation dataset.
INDEX VSAM index component.
NONVSAM Non-VSAM dataset.
PATH VSAM path.
USERCAT User catalog.
BS2000 FGG File generation group.
z/VSE DA Direct-access dataset.
ISAM ISAM dataset.
SAM SAM dataset.
VSAM VSAM dataset.
Field Name Format/Length Operating System
USER-CATALOG (A44) z/OS, z/VSE

z/OS only: name of the user catalog in which the dataset is cataloged (see also OPTION field).

z/VSE only: name of the VSAM catalog from which data is to be retrieved. VSAM-CATALOG takes precedence over USER-CATALOG.

Field Name Format/Length Operating System
VOLSER (A6) z/OS, z/VSE, BS2000

Volume serial number of dataset. In BS2000, this field supports search criteria. In z/VSE , when returning information from the internal file table, the field will be blank for VSAM files.

Field Name Format/Length Operating System
VOLUME-SEQUENCE (N3) z/OS, z/VSE

Volume sequence (tape datasets only).

Field Name Format/Length Operating System
VSAM-CATALOG (A8) z/VSE

For internal file table requests, the DLBL for the VSAM catalog for a VSAM file. It will be blank for a non-VSAM file.

For VSAM catalog retrieval requests, the DLBL for the VSAM catalog from which data is to be retrieved. VSAM-CATALOG takes precedence over USER-CATALOG.

Example: Using CATALOG View

Assume the following datasets exist:

  • A.B.C

  • A.B.C.D

  • A.B.C.E

The example program ... 

FIND CATALOG WITH
   DSNAME=<....>
   PREFIX=<....>
DISPLAY DSNAME

... returns the following information: 

  DSNAME        PREFIX   RETURNED DSNAMEs
  A.B.C         NO       A.B.C
  A.B.C         YES      A.B.C
                         A.B.C.D
                         A.B.C.E
  A.B           YES      A.B.C
                         A.B.C.D
                         A.B.C.E
  A.B           NO      (none) Error 5562 - Catalog entry not found.
  DSNAME        PREFIX   RETURNED DSNAMEs
  A.B.C         NO       A.B.C
  A.B.C         YES      A.B.C
                         A.B.C.D
                         A.B.C.E
  A.B           YES      A.B.C
                         A.B.C.D
                         A.B.C.E
  A.B           NO      (none) Error 5562 - Catalog entry not found.