READ-FILE

#### Search Results

Search

# READ-FILE

File | 2
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). Using the `SCAN` fields, only those records containing the specified string are returned.

## Fields

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 |
`VOLSER` | A6 |  | D | 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 |

## Relevant Error Codes

Code | Text
--- | ---
500 | VSAM error.
533 | Requested number or records scanned.
537 | Time limit reached.
541 | Member generation not found in directory.
551 | `MEMBER` not specified.
556 | File is in use.
687 | Bad variable record.
699 | Not enough main storage available.
701 | `DSNAME` missing.
899 | Permanent I/O error while reading dataset.
991 | Unknown product.
993 | `OPEN` error.
997 | File not PDS/Sequential.
998 | Member not found.

## Field Descriptions

Field Name | Type/Length
--- | ---
`BLOCK-LENGTH` | (N5)

Length of block.

Field Name | Type/Length
--- | ---
`BLOCK-NUMBER` | (N9)

Number of block.

Field Name | Type/Length
--- | ---
`BLOCK-TTR` | (B3)

TTR of the block which was read.

Field Name | Type/Length
--- | ---
`BLOCK-TOKEN` | (B4)

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
--- | ---
`DIRECT` | (A3)

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`.

Field Name | Type/Length
--- | ---
`DSNAME` | (A54)

Fully qualified dataset name.

Field Name | Type/Length
--- | ---
`END-OF-FILE` | (A3)

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
--- | ---
`GENERATION` | (N9)

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

Field Name | Type/Length
--- | ---
`KEY` | (A253)

ISAM or VSAM key.

Field Name | Type/Length
--- | ---
`MEMBER` | (A10)

If the dataset is a PDS, member name.

Field Name | Type/Length
--- | ---
`OPTIONS` | (A80)

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

Field Name | Type/Length
--- | ---
`PASSWORD` | (A8)

Password for protected dataset.

Field Name | Type/Length
--- | ---
`POSITION` | (N5)

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

Field Name | Type/Length
--- | ---
`PRODUCT` | (A1)

Access mode used. Possible values:

Value | Explanation
--- | ---
`L` | CA-Librarian
`P` | CA-Panvalet

Field Name | Type/Length
--- | ---
`RECORD` | (A253)

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
--- | ---
`RECORD-LENGTH` | (N5)

Length of entire record (not the segment length).

Field Name | Type/Length
--- | ---
`RECORD-NUMBER` | (N9)

Record position within the dataset.

Field Name | Type/Length
--- | ---
`SCAN` | (A3)

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

Field Name | Type/Length
--- | ---
`SCAN-COLUMN-FROM` | (N5)

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

Field Name | Type/Length
--- | ---
`SCAN-COLUMN-TO` | (N5)

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
--- | ---
`SCAN-LENGTH` | (N3)

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

Field Name | Type/Length
--- | ---
`SCAN-LIMIT` | (N7)

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
--- | ---
`SCAN-TYPE` | (A1)

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

Field Name | Type/Length
--- | ---
`SEGMENT-LENGTH` | (N3)

Length of segment.

Field Name | Type/Length
--- | ---
`SEGMENT-NUMBER` | (N5)

Segment number within record.

Field Name | Type/Length
--- | ---
`SPANNED` | (A8)

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
--- | ---
`TIME-LIMIT` | (N5)

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

Field Name | Type/Length
--- | ---
`VOLSER` | (A6)

Volume serial number.

## Default Order of Data Returned

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

### On this page

- Fields
- Relevant Error Codes
- Field Descriptions
- Default Order of Data Returned