Reading record I/O files

To read from a VSAM data set opened with type=record, use the Standard C fread() library function. If you set the size argument to 1 and the count argument to the maximum record size, fread() returns the number of bytes read successfully. For more information on fread(), see z/OS XL C/C++ Runtime Library Reference.

fread() reads one record from the system from the current file position. Thus, if you want to read a certain record, you can call flocate() to position the file pointer to point to it; the subsequent call to fread() reads in that record.

If you use an fread() call to request more bytes than the record about to be read contains, fread() reads the entire record and returns the number of bytes read. If you use fread() to request fewer bytes than the record about to read contains, fread() reads the number of bytes that you specified and returns your request.

z/OS® XL C/C++ VSAM Record I/O does not allow a read operation to immediately follow a write operation without an intervening reposition. z/OS XL C/C++ treats the following as read operations:

Calls to read functions that request 0 bytes
Read requests that fail because of a system error
Calls to the ungetc() function

Calling fread() several times in succession, with no other operations on this file in between, reads several records in sequence (sequential processing), which can be forward or backward, depending on the access direction, as described in the following.

KSDS, KSDS AIX and ESDS AIX
The records are retrieved according to the sequence of the key of reference, or in reverse key sequence.

Note: Records with duplicate alternate index keys are processed in order of arrival time (oldest to newest) regardless of the current processing direction
ESDS
The records are retrieved according to the sequence they were written to the file (entry sequence), or in reverse entry sequence.
RRDS
The records are retrieved according to relative record number sequence or reverse relative record number sequence.

When records are being read, RRNs without an associated record are ignored. For example, if a file has relative records of 1, 2, and 5, the nonexistent records 3 and 4 are ignored.

By default, in record mode, fread() must be called with a pointer to an RRDS record structure. The field __rrds_key_type.__fill must be set to either 0 or 1 indicating the type of the structure, and the count argument must include the length of the __rrds_key_type. fread() returns the RRN number in the __recnum field, and includes the length of the __rrds_key_type in the return value. You can override these operations by setting the _EDC_RRDS_HIDE_KEY environment variable to Y. Once this variable is set, fread() is called with a data buffer and not an RRDS data structure. The return value of fread() is now only the length of the data read. In this case, fread() cannot return the RRN. For information on setting environment variables, see Using environment variables.