CATALOG

#### Search Results

Search

# CATALOG

File | 8
Op-Sys | z/OS, z/VSE, BS2000 Note Support for z/VSE is deprecated. Support for BS2000 is also deprecated, except in conjunction with the ESM adapter. Features that are z/VSE and BS2000 specific will be removed from future releases.
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.

### On this page

- Common Fields for all Operating Systems
- Additional Fields Supported for z/OS
- Additional Fields Supported for z/OS, z/VSE
- Additional Fields Supported for z/VSE
- Additional Fields Supported for BS2000
- Relevant Error Codes
- Field Descriptions
- Example: Using CATALOG View