READ-FILE

#### Search Results

Search

# READ-FILE

File | 2
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 makes it possible to read all or a selected set of records from a sequential or partitioned disk file (for example, PDS, z/VSE/Librarian, LMS). Using the `SCAN` fields, only those records containing the specified string are returned.

## 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.
`RECORD` | A253 |  | D |
`RECORD-LENGTH` | N5 |  | D |
`SEGMENT-NUMBER` | N5 |  | D |
`RECORD-NUMBER` | N9 |  | D |
`END-OF-FILE` | A3 |  | D |
`POSITION` | N5 |  | D |
`PASSWORD` | A8 |  | D |
`SEGMENT-LENGTH` | N3 |  | D |
`BLOCK-LENGTH` | N5 |  | D |
`SCAN` | A3 |  | D |
`SCAN-LIMIT` | N7 |  | D |
`SCAN-TYPE` | A1 |  | D |
`SCAN-LENGTH` | N3 |  | D | Relevant with `SCAN-TYPE=A`.
`SCAN-COLUMN-FROM` | N5 |  | D | Relevant with `SCAN-TYPE=A`.
`SCAN-COLUMN-TO` | N5 |  | D | Relevant with `SCAN-TYPE=A`.
`TIME-LIMIT` | N5 |  | D |
`DIRECT` | A3 |  | D |

## Additional Fields Supported for z/OS

Dictionary Field Name | F/L | Mu | DE | Remarks
--- | --- | --- | --- | ---
`VOLSER` | A6 |  | D | Required in z/VSE. In z/OS only if dataset is not cataloged.
`MEMBER` | A10 |  | D |
`PRODUCT` | A1 |  | D |
`KEY` | A253 |  | D |
`BLOCK-TTR` | B3 |  | D |
`BLOCK-TOKEN` | B4 |  | D |
`GENERATION` | N9 |  | D |
`OPTIONS` | A80 |  | D |
`BLOCK-NUMBER` | N9 |  | D |
`SPANNED` | A8 |  | D |

## Additional Fields Supported for z/VSE

Dictionary Field Name | F/L | Mu | DE | Remarks
--- | --- | --- | --- | ---
`VOLSER` | A6 |  | D | Required in z/VSE. In z/OS only if dataset is not cataloged.
`MEMBER` | A10 |  | D |
`MEMBER-TYPE` | A8 |  | D |
`LIBRARY` | A8 |  | D | Required if `DSNAME` not specified.
`SUB-LIBRARY` | A8 |  | D | Required if Librarian file.
`VSAM-CATALOG` | A8 |  | D | Required if VSAM-controlled Librarian file.
`LRECL` | B2 |  | D | Relevant with `RECFM=F`.
`BLKSIZE` | B2 |  | D |
`RECFM` | A2 |  | D |
`BLOCK-NUMBER` | N9 |  | D |

## Additional Fields Supported for BS2000

Dictionary Field Name | F/L | Mu | DE | Remarks
--- | --- | --- | --- | ---
`PRODUCT` | A1 |  | D |
`KEY` | A253 |  | D |
`DIRECTION` | A1 |  | D |
`ELEMENT` | A64 |  | D |
`ELEMENT-RECORD-TYPE` | N3 |  | D |
`ELEMENT-TYPE` | A8 |  | D |
`ELEMENT-VERSION` | A24 |  | D |
`ELEMENT-PASSWORD` | A8 |  | D |
`SYSTEM-CODE` | B2 |  |  |

## Relevant Error Codes

Code | Text | z/OS | z/VSE | BS2000
--- | --- | --- | --- | ---
500 | VSAM error. | X | X |
530 | Access denied by Security Facility. |  |  | X
531 | Password missing or incorrect. |  |  | X
533 | Requested number or records scanned. | X | X |
537 | Time limit reached. | X | X | X
541 | Member generation not found in directory. | X |  |
551 | `MEMBER` not specified. | X | X | X
556 | File is in use. | X |  | X
565 | Syntax error in dataset name. |  |  | X
673 | Access error due to `FILETABLE=STATIC`. |  | X |
674 | VTOC error reading format-3 labels. |  | X |
675 | :1: not supported. |  | X |
676 | Not first volume of multi-volume file. |  | X |
687 | Bad variable record. | X | X |
692 | You are not permitted to access member. |  |  | X
697 | `LIBRARY/SUBLIB` not found. |  | X |
698 | Internal Librarian error. |  | X |
699 | Not enough main storage available. | X | X | X
700 | Invalid value specified (`DSORG RECFM/TYPE`). |  |  | X
701 | `DSNAME` missing. | X | X | X
772 | Requested dataset not found. |  |  | X
798 | Task was not started under TSOS. |  |  | X
799 | Entire System Server internal error. |  |  | X
854 | Permanent I/O error. |  |  | X
856 | Operator unable to mount volume. |  |  | X
872 | Record format not supported. |  |  | X
873 | Record length missing. |  |  | X
874 | Record length > `LRECL`. |  | X | X
877 | VSAM (`SHOWCAT`) processing error |  | X |
881 | Error occurred while opening file. |  |  | X
882 | Error occurred while closing file. |  |  | X
899 | Permanent I/O error while reading dataset. | X | X | X
981 | Invalid value specified (`BLKCTRL/BLKSIZE/LRECL`). |  | X | X
982 | Error during use of ISAM-key. |  |  | X
985 | Access to tape file not allowed. |  |  | X
991 | Unknown product. | X |  | X
993 | `OPEN` error. | X | X |
997 | File not PDS/Sequential. | X |  |
998 | Member not found. | X | X | X

## Field Descriptions

Field Name | Type/Length | Operating System
--- | --- | ---
`BLKSIZE` | (B2) | z/VSE

Block size of dataset.

Field Name | Type/Length | Operating System
--- | --- | ---
`BLOCK-LENGTH` | (N5) | z/OS, z/VSE, BS2000

Length of block.

Field Name | Type/Length | Operating System
--- | --- | ---
`BLOCK-NUMBER` | (N9) | z/OS, z/VSE

Number of block.

Field Name | Type/Length | Operating System
--- | --- | ---
`BLOCK-TTR` | (B3) | z/OS

TTR of the block which was read.

Field Name | Type/Length | Operating System
--- | --- | ---
`BLOCK-TOKEN` | (B4) | z/OS

Token value of the block which was read.

For a large format sequential data set, the token is in the format `TTTR` where `TTT` is the relative track address and `R` the number of the block on that track.

Field Name | Type/Length | Operating System
--- | --- | ---
`DIRECT` | (A3) | z/OS, z/VSE, BS2000

Possible options:

Option | Explanation
--- | ---
`NO` | Default. The block is not read directly.
`YES` | If `REFM=F` and `DSORG=PS` or `DA`, the block is read directly according to `RECORD-NUMBER` and `BLOCK-NUMBER`. In BS2000: SAM files with `RECFORM=F` are read directly according to `RECORD-NUMBER`. PAM files and LMS elements are always read directly, if a `RECORD-NUMBER` is specified.

Field Name | Type/Length | Operating System
--- | --- | ---
`DIRECTION` | (A1) | BS2000

Possible values:

Value | Explanation
--- | ---
`B` | Read backwards (ISAM files only)
`F` | Read forward

Field Name | Type/Length | Operating System
--- | --- | ---
`DSNAME` | (A54) | z/OS, z/VSE, BS2000

Fully qualified dataset name.

Field Name | Type/Length | Operating System
--- | --- | ---
`ELEMENT` | (A64) | BS2000

Name of LMS element to be read.

Field Name | Type/Length | Operating System
--- | --- | ---
`ELEMENT-TYPE` | (A8) | BS2000

Type of LMS element to be read.

Types `C` and `L` are currently not supported.

Field Name | Type/Length | Operating System
--- | --- | ---
`ELEMENT-PASSWORD` | (A8) | BS2000

Password, for protected LMS element (LMS V2 or above).

Field Name | Type/Length | Operating System
--- | --- | ---
`ELEMENT-RECORD-TYPE` | (N3) | BS2000

Record type (LMS only)

Field Name | Type/Length | Operating System
--- | --- | ---
`ELEMENT-VERSION` | (A24) | BS2000

Version of LMS element to be read.

Field Name | Type/Length | Operating System
--- | --- | ---
`END-OF-FILE` | (A3) | z/OS, z/VSE, BS2000

Contains `YES`, if the end of record is reached. The `RECORD-NUMBER` field then contains the number of records in the dataset.

Field Name | Type/Length | Operating System
--- | --- | ---
`GENERATION` | (N9) | z/OS

Generation number of member (only valid for PDSE version 2 with MAXGENS > 0).

Field Name | Type/Length | Operating System
--- | --- | ---
`KEY` | (A253) | z/OS, BS2000

ISAM or VSAM key.

Field Name | Type/Length | Operating System
--- | --- | ---
`LIBRARY` | (A8) | z/VSE

Name of library.

Field Name | Type/Length | Operating System
--- | --- | ---
`LRECL` | (B2) | z/VSE

Required with RECFM=F. Logical record length. Default is 80.

Field Name | Type/Length | Operating System
--- | --- | ---
`MEMBER` | (A10) | z/OS, z/VSE

If the dataset is a PDS, member name.

Field Name | Type/Length | Operating System
--- | --- | ---
`MEMBER-TYPE` | (A8) | z/VSE

Member type.

Field Name | Type/Length | Operating System
--- | --- | ---
`OPTIONS` | (A80) | z/OS

Specify `X` to cause expansion of all `++INCLUDE` statements for CA-Panvalet.

Field Name | Type/Length | Operating System
--- | --- | ---
`PASSWORD` | (A8) | z/OS, z/VSE, BS2000

Password for protected dataset.

Field Name | Type/Length | Operating System
--- | --- | ---
`POSITION` | (N5) | z/OS, z/VSE, BS2000

Starting position within record. The `RECORD` field contains input record starting at this position.

Field Name | Type/Length | Operating System
--- | --- | ---
`PRODUCT` | (A1) | z/OS, BS2000

Access mode used. Possible values:

Value | Explanation
--- | ---
`L` | CA-Librarian
`M` | BS2000 LMS
`P` | CA-Panvalet

Field Name | Type/Length | Operating System
--- | --- | ---
`RECFM` | (A2) | z/VSE

Record format of dataset. Default is `F`.

Field Name | Type/Length | Operating System
--- | --- | ---
`RECORD` | (A253) | z/OS, z/VSE, BS2000

Gives the retrieved record. The length of this field as it appears in the format buffer determines the portion of the record retrieved each time a record is requested. Field `SEGMENT-NUMBER` contains the segment number within the record. For example, the record is 240 bytes long and the calling program requests 80 bytes (in Natural reporting mode: `OBTAIN RECORD (A80)`). The calling program will then receive three segments.

Field Name | Type/Length | Operating System
--- | --- | ---
`RECORD-LENGTH` | (N5) | z/OS, z/VSE, BS2000

Length of entire record (not the segment length).

Field Name | Type/Length | Operating System
--- | --- | ---
`RECORD-NUMBER` | (N9) | z/OS, z/VSE, BS2000

Record position within the dataset.

For BS2000, in case of a PAM file, the PAM block number must be specified here.

Field Name | Type/Length | Operating System
--- | --- | ---
`SCAN` | (A3) | z/OS, z/VSE, BS2000

Specify `YES` to return the first record that meets all selection criteria and all subsequent records.

Field Name | Type/Length | Operating System
--- | --- | ---
`SCAN-COLUMN-FROM` | (N5) | z/OS, z/VSE, BS2000

Relevant if `SCAN-TYPE=A`. Specifies the column number where the scan is to start. Default is 1.

Field Name | Type/Length | Operating System
--- | --- | ---
`SCAN-COLUMN-TO` | (N5) | z/OS, z/VSE, BS2000

Relevant if `SCAN-TYPE=A`. Specifies the column number where the scan is to end. Default is the end of the record.

Field Name | Type/Length | Operating System
--- | --- | ---
`SCAN-LENGTH` | (N3) | z/OS, z/VSE, BS2000

Relevant if `SCAN-TYPE=A`. Specifies the length of the scan string in field `RECORD`.

Field Name | Type/Length | Operating System
--- | --- | ---
`SCAN-LIMIT` | (N7) | z/OS, z/VSE, BS2000

Specifies the maximum number of records to be scanned before the record is selected. If the limit is reached and no record found, Error Code 533 is issued.

Field Name | Type/Length | Operating System
--- | --- | ---
`SCAN-TYPE` | (A1) | z/OS, z/VSE, BS2000

Specify `A` to perform an absolute scan. Wildcard symbols * (asterisk) and _ (underline) are treated as normal characters.

Field Name | Type/Length | Operating System
--- | --- | ---
`SEGMENT-LENGTH` | (N3) | z/OS, z/VSE, BS2000

Length of segment.

Field Name | Type/Length | Operating System
--- | --- | ---
`SEGMENT-NUMBER` | (N5) | z/OS, z/VSE, BS2000

Segment number within record.

Field Name | Type/Length | Operating System
--- | --- | ---
`SPANNED` | (A8) | z/OS

Spanned records, when `RECFM` is `VBS` or `VS`. Possible options:

Option | Explanation
--- | ---
`FIRST` | Record returned is the first part.
`LAST` | Record returned is the last part.
`MIDDLE` | Record returned is the middle part (not `FIRST` and not `LAST`).
`NO` | Record is not spanned.

Field Name | Type/Length | Operating System
--- | --- | ---
`SUB-LIBRARY` | (A8) | z/VSE

Name of sublibrary.

Field Name | Type/Length | Operating System
--- | --- | ---
`TIME-LIMIT` | (N5) | z/OS, z/VSE, BS2000

Specifies the maximum number of seconds a given record is to be scanned for.

Field Name | Type/Length | Operating System
--- | --- | ---
`VOLSER` | (A6) | z/OS, z/VSE

Volume serial number (not relevant for BS2000).

Field Name | Type/Length | Operating System
--- | --- | ---
`VSAM-CATALOG` | (A8) | z/VSE

Name of VSAM catalog where the library is kept.

If you want to read a given dataset / member it may happen, that the dataset / member is empty. Then the following applies:

- If field `END-OF-FILE` is in `DEFINE DATA` clause, then exactly one record is returned also for empty datasets / members containing `END-OF-FILE=YES`.

- If field `END-OF-FILE` is `NOT` in define data clause, then no record are returned and the `NO RECORDS FOUND` clause apply.

## Default Order of Data Returned

Records are returned in order from the start of the file.

## Programming notes BS2000

Sequential files currently in creation are exclusively locked for the creating task and cannot be read by any other task. However, locked files can be accessed if the Entire System Server startup parameter`READ-LOCKED-FILE` is set to `YES` or was not specified, and class 2 system parameter `SVC79` allows the usage of SVC 79. The Entire System Server will make a copy of the original data and use this file for `READ-FILE`. This technique is currently implemented for SAM files only.

### On this page

- Common Fields for all Operating Systems
- Additional Fields Supported for z/OS
- Additional Fields Supported for z/VSE
- Additional Fields Supported for BS2000
- Relevant Error Codes
- Field Descriptions
- Default Order of Data Returned
- Programming notes BS2000