com.ibm.jzos

Class RecordReader

  • java.lang.Object
    • com.ibm.jzos.RecordReader
  • All Implemented Interfaces:
    ZFileConstants
    Direct Known Subclasses:
    ZFileRecordReader

    public abstract class RecordReader
extends java.lang.Object
implements ZFileConstants
    This class provides record mode read access to z/OS datasets. Factory methods newReaderForDD and newReader(name, flags) may be used to return an instance of an implementation subtype of this class.

    In order to provide more efficient dataset I/O performance, subtype implementations may use native BSAM I/O to read entire blocks from the underlying dataset into Java buffers and subsequently deblock records from these blocks. In addition, native calls to underlying I/O routines may be buffered and use overlapped I/O techniques if available to improve throughput and to reduce CPU overhead. Refer to z/OS DFSMS Using Data Sets, SC26-7410 for more information.

    For datasets not supported by BSAM, such as VSAM, a call is made to an implementation subclass which uses a simple record-mode ZFile implementation. This means that this class will support reading from a VSAM dataset. The only public API to this class and its non-public implementation subclasses is via one of the static factory methods in this class; the implementation subclass instance returned is an implementation detail and is not controllable by the client, and may change in the future.

    All sequential dataset organizations and record formats supported by ZFile (the IBM z/OS C library) are supported. For DSORG=PS datasets, best performance will be realized when using blocked records and large blocking factors.

    Instances of ZFileException are thrown to report errors, but detailed codes and message text in these exceptions may reflect either BSAM access method errors or ZFile (C-library access method interface) errors.

    Example: Read a dataset using a RecordReader via a DD name 

    
 String ddname = ZFile.allocDummyDDName();
 String cmd = "alloc fi("+ddname+") da(HLQ.MYDATA) reuse shr msg(2)";
 ZFile.bpxwdyn(cmd);
 RecordReader reader = null;
 try {
   reader = RecordReader.newReaderForDD(ddname);
   byte[] recordBuf = new byte[reader.getLrecl()];
   while ((bytesRead = reader.read(recordBuf)) >= 0) {
     ...
   }
 } finally {
   if (reader != null) {
     try {
       reader.close(); 
     } catch (ZFileException zfe) {
       zfe.printStackTrace();  // but continue
     } 
   }
   try {
     ZFile.bpxwdyn("free fi(" + ddname + ") msg(2)");
   } catch (RcException rce) {
     rce.printStackTrace();  // but continue
   }
 }

    Example: Read a dataset using a RecordReader via a dataset name 

    
 RecordReader reader = null;
 try {
   reader = RecordReader.newReader("//my.dataset", ZFileConstants.FLAG_DISP_SHR);
   byte[] recordBuf = new byte[reader.getLrecl()];
   while ((bytesRead = reader.read(recordBuf)) >= 0) {
     ...
   }
 } finally {
   if (reader != null) {
     reader.close(); 
   }
 }
    There are two System properties that may be used to control the usage of BSAM implementation classes:
    1. jzos.bsam.allow.abends - if this is set to true, then ABENDs in the BSAM support will not be caught and thrown as ZFileExceptions. IBM Support may request this setting in order to get a dump.
    2. jzos.bsam.disable - if this is set to true, then ZFile implementations will be used in all cases rather than direct BSAM implementation classes.
    Since:
    2.4.1

    • Method Detail

      • newReaderForDD

        public static RecordReader newReaderForDD(java.lang.String ddname)
                                   throws ZFileException
        Construct a new RecordReader on the given DD.

        The data definition must be 1-8 characters with some rules.

        • Is 1 through 8 alphanumeric or national ($, #, @) characters.
        • The first character must be alphabetic or national ($, #, @).
        Parameters:
        ddname - the previously allocated DD name that is associated with the dataset or file
        Throws:
        ZFileException - if there was an error opening the dataset.

      • newReader

        public static RecordReader newReader(java.lang.String name,
                                     int flags)
                              throws ZFileException,
                                     RcException
        Construct a new RecordReader for the given dataset name.
        Parameters:
        name - name of the file to open, in the same syntax as ZFile.ZFile(String, String), the same syntax defined by the C-Library fopen() function. If the name specifies a DD:DDNAME, then refer to newReaderForDD(String) for supported data definition syntax
        flags -
        • If the name specifies a DD:DDNAME, then flags must be 0.
        • If FLAG_DISP_SHR and the name refers to a dataset name, the dataset will be allocated with DISP=SHR.
        • If FLAG_DISP_OLD or 0 and name refers to a dataset name, it will be allocated with DISP=OLD.
        Throws:
        ZFileException - if the file could not be opened
        RcException - if an error occurs when attempting to allocate the dataset, the exception from ZFile.bpxwdyn(String) is thrown
        Since:
        2.4.2

      • read

        public abstract int read(byte[] buf)
                  throws ZFileException
        Read a record from the dataset into a buffer.
        Parameters:
        buf - the byte array into which the bytes will be read
        Returns:
        the number of bytes read, -1 if EOF encountered.
        Throws:
        ZFileException - if the native call fails

      • read

        public abstract int read(byte[] buf,
                         int offset,
                         int len)
                  throws ZFileException
        Read a record from the dataset into a buffer.
        Parameters:
        buf - the byte array into which the bytes will be read
        offset - the offset, inclusive in buf to start reading bytes
        len - the number of bytes to read
        Returns:
        the number of bytes read, -1 if EOF encountered.
        Throws:
        ZFileException - if the native call fails

      • close

        public abstract void close()
                    throws ZFileException
        Close the reader and underlying native file.

        This will also free the associated DD if getAutoFree() is true.

        Note: close() must be issued by the same thread as the factory method that creates the instance object (opening the dataset). Reading can occur on any thread.

        Throws:
        ZFileException - if the native call fails

      • getLrecl

        public abstract int getLrecl()
        Answer the LRECL, which is the maximum record length for variable length files.

      • getBlksize

        public abstract int getBlksize()
        Answer the BLKSIZE, which is the maximum block length supported by the dataset.

      • getRecfmBits

        public abstract int getRecfmBits()
        Answer the RECFM bits
        See Also:
        ZFile.getRecfmBits()

      • getRecfm

        public abstract java.lang.String getRecfm()
        Get the native file's record format.
        See Also:
        ZFile.getRecfm()

      • getDDName

        public abstract java.lang.String getDDName()
        Answers the DD name used to open the underlying dataset.
        Returns:
        String ddname

      • getDsn

        public abstract java.lang.String getDsn()
        Answers the native dataset's absolute name, or name(member) if the native dataset is a member of a PDS.
        Returns:
        String dataset name

      • getAutoFree

        public boolean getAutoFree()
        Answer a flag that indicates whether the DD name associated with this file will automatically be freed when the file is closed. By default, this is true if this RecordReader was created using newReader() supplying a dataset name.
        Returns:
        boolean

      • setAutoFree

        public void setAutoFree(boolean autoFree)
        Sets a flag that will cause the DD to automatically be freed after close().
        See Also:
        getAutoFree()
Skip navigation links
� Copyright IBM Corporation 2005, 2022.
  • Summary: 
  • Nested | 
  • Field | 
  • Constr | 
  • Method
  • Detail: 
  • Field | 
  • Constr | 
  • Method