READ-FILE

File 2
Op-Sys z/OS, z/VSE, BS2000/OSD
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/OSD

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/OSD
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/OSD

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/OSD

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/OSD: 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/OSD

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/OSD

Fully qualified dataset name.

Field Name Type/Length Operating System
ELEMENT (A64) BS2000/OSD

Name of LMS element to be read.

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

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/OSD

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

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

Record type (LMS only)

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

Version of LMS element to be read.

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

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/OSD

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/OSD

Password for protected dataset.

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

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/OSD

Access mode used. Possible values:

Value Explanation
L  CA-Librarian
M  BS2000/OSD 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/OSD

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/OSD

Length of entire record (not the segment length).

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

Record position within the dataset.

For BS2000/OSD, 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/OSD

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/OSD

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/OSD

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/OSD

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/OSD

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/OSD

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/OSD

Length of segment.

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

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/OSD

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/OSD).

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/OSD

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.