Class ZFileRecordReader

java.lang.Object
com.ibm.jzos.RecordReader
com.ibm.jzos.ZFileRecordReader
All Implemented Interfaces:
ZFileConstants, AutoCloseable
public class ZFileRecordReader extends RecordReader implements ZFileConstants, AutoCloseable
This ZFile wrapper is no longer the most efficient way to read dataset records. Please see RecordReader.

In order to provide more efficient dataset record mode read performance, it is often beneficial to read a block, rather than a record, at a time from the underlying dataset. This class wraps an instance of ZFile, re-opens it with RECFM=U, and provides an interface for reading a record at a time. The underlying ZFile must have been opened with the following options:

  • type=record
  • read mode, either text or binary ("r", "rb" or "rt")

Reading the dataset a block at a time limits the number of calls to the C library fread() function and also reduces the number of JNI calls that need to be made. The z/OS XL C/C++ Programming Guide SC09-4765 (Chapter 34 - I/O Performance considerations) recommends taking this approach to increase performance when possible.

All record formats are supported, however performance gains will only be realized when the average record lengths are significantly less than the average block size. The class implements AutoCloseable. It can be used with the AutoCloseable with a try-with-resources block or without, as shown in the two examples below: Example 1: Allocate and close a ZFile when a try-with-resources block is not used. The an explicit call to the close() close the ZFile object and release the associated resources. The close() method is called in a finally block to assure that the close is performed after the try block completes. 

   ZFile zfile = new  new ZFile(fileName, options);
   try {
       byte[] recBuf = new byte[lrecl];
       // read the records sequentially
       while (zfile.read(recBuf) != -1) {
           String record = new String(recBuf);
           System.out.println("Record=" + record);
       }
   }
   finally {
     zfile.close();
   }
Example 2: Allocate a ZFile when a try-with-resources block is used. The method close() is not needed. Upon exiting a try-with-resources block, the AutoCloseable will automatically call the close() method which will lose the ZFile object and release the associated resources. 
   try (ZFile zfile = new  new ZFile(fileName, options)) {
       byte[] recBuf = new byte[lrecl];
       // read the records sequentially
       while (zfile.read(recBuf) != -1) {
           String record = new String(recBuf);
           System.out.println("Record=" + record);
       }
   }
   ...
Since:
2.3.0
See Also: