Class RecordWriter
- java.lang.Object
-
- com.ibm.jzos.RecordWriter
-
- All Implemented Interfaces:
- ZFileConstants
public abstract class RecordWriter extends java.lang.Object implements ZFileConstants
This class provides record mode write access to z/OS datasets. Factory methodsnewWriterForDD
andnewWriter(name, flags)
may be used to return an instance of an implementation subtype of this class. To create a new dataset, clients of this class must first allocate a DD statement usingZFile.bpxwdyn(String)
; all attributes (RECFM, LRECL, SPACE, etc) should be specified in the allocation, as this API will not necessarily use defaults provided by ZFile and the IBM C library.In order to provide more efficient dataset I/O performance, subtype implementations may use native BSAM I/O and accumulate records in Java into blocks which are written to the underlying dataset as they are filled (or until
flush
is called). 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 toz/OS DFSMS Using Data Sets, SC26-7410
for more information.This class does not support writing to datasets which aren't supported by BSAM. 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: Create a new dataset and write to it using a RecordWriter
String ddname = ZFile.allocDummyDDName(); String cmd = "alloc fi("+ddname+") da(HLQ.MYDATA) reuse new catalog msg(2)" + " recfm(f,b) space(100,50) cyl" + " lrecl(80)"; ZFile.bpxwdyn(cmd); // might throw RcException RecordWriter writer = null; try { writer = RecordWriter.newWriterForDD(ddname); byte[] recordBuf = new byte[writer.getLrecl()]; int bytesToWrite; while ((bytesToWrite = getNextAppRecord(recordBuf)) > 0) { writer.write(recordBuf, 0, bytesToWrite); } } finally { if (writer != null) { try { writer.close(); } catch (ZFileException zfe) { zfe.printStackTrace(); // but continue } } try { ZFile.bpxwdyn("free fi(" + ddname + ") msg(2)"); } catch (RcException rce) { rce.printStackTrace(); // but continue } }
Example: Write to an existing dataset
RecordWriter writer = null; try { writer = RecordWriter.newWriter("//my.dataset", ZFileConstants.FLAG_DISP_OLD); byte[] recordBuf = new byte[writer.getLrecl()]; int bytesToWrite; while ((bytesToWrite = getNextAppRecord(recordBuf)) > 0) { writer.write(recordBuf, 0, bytesToWrite); } } finally { if (writer != null) { writer.close(); } }
There are two System properties that may be used to control the usage of BSAM implementation classes:
jzos.bsam.allow.abends
- if this is set totrue
, 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.jzos.bsam.disable
- if this is set totrue
, then ZFile implementations will be used in all cases rather than direct BSAM implementation classes.
- Since:
- 2.4.1
-
-
Field Summary
-
Fields inherited from interface com.ibm.jzos.ZFileConstants
DEFAULT_EBCDIC_CODE_PAGE, DEVICE_DISK, DEVICE_DUMMY, DEVICE_HFS, DEVICE_HIPERSPACE, DEVICE_MEMORY, DEVICE_MSGFILE, DEVICE_OTHER, DEVICE_PRINTER, DEVICE_TAPE, DEVICE_TDQ, DEVICE_TERMINAL, DSORG_CONCAT, DSORG_HFS, DSORG_HIPER, DSORG_MEM, DSORG_PDS_DIR, DSORG_PDS_MEM, DSORG_PDSE, DSORG_PO, DSORG_PS, DSORG_TEMP, DSORG_VSAM, ERRNO_E_ABEND, ERRNO_E_DEFINEFILE, ERRNO_E_READERR, ERRNO_E_WRITEERR, ERRNO_EACCES, ERRNO_EILSEQ, ERRNO_EINVAL, ERRNO_EIO, ERRNO_EPERM, FLAG_DISP_MOD, FLAG_DISP_OLD, FLAG_DISP_SHR, FLAG_PDS_ENQ, LAST_OP_BSAM_BLDL, LAST_OP_BSAM_CLOSE, LAST_OP_BSAM_CLOSE_T, LAST_OP_BSAM_NOTE, LAST_OP_BSAM_OPEN, LAST_OP_BSAM_POINT, LAST_OP_BSAM_READ, LAST_OP_BSAM_STOW, LAST_OP_BSAM_WRITE, LAST_OP_C_CANNOT_EXTEND, LAST_OP_C_DBCS_SI_TRUNCATE, LAST_OP_C_DBCS_SO_TRUNCATE, LAST_OP_C_DBCS_TRUNCATE, LAST_OP_C_DBCS_UNEVEN, LAST_OP_C_FCBCHECK, LAST_OP_C_TRUNCATE, LAST_OP_HSP_CREATE, LAST_OP_HSP_DELETE, LAST_OP_HSP_EXTEND, LAST_OP_HSP_READ, LAST_OP_HSP_WRITE, LAST_OP_IO_CATALOG, LAST_OP_IO_DEVTYPE, LAST_OP_IO_LOCATE, LAST_OP_IO_OBTAIN, LAST_OP_IO_RDJFCB, LAST_OP_IO_RENAME, LAST_OP_IO_SCRATCH, LAST_OP_IO_SWAREQ, LAST_OP_IO_TRKCALC, LAST_OP_IO_UNCATALOG, LAST_OP_QSAM_FREEPOOL, LAST_OP_QSAM_GET, LAST_OP_QSAM_PUT, LAST_OP_QSAM_RELSE, LAST_OP_QSAM_TRUNC, LAST_OP_SVC99_ALLOC, LAST_OP_SVC99_ALLOC_NEW, LAST_OP_SVC99_UNALLOC, LAST_OP_TGET_READ, LAST_OP_TGET_WRITE, LAST_OP_VSAM_CLOSE, LAST_OP_VSAM_ENDREQ, LAST_OP_VSAM_ERASE, LAST_OP_VSAM_GENCB, LAST_OP_VSAM_GET, LAST_OP_VSAM_MODCB, LAST_OP_VSAM_OPEN_ESDS, LAST_OP_VSAM_OPEN_ESDS_PATH, LAST_OP_VSAM_OPEN_FAIL, LAST_OP_VSAM_OPEN_KSDS, LAST_OP_VSAM_OPEN_KSDS_PATH, LAST_OP_VSAM_OPEN_RRDS, LAST_OP_VSAM_POINT, LAST_OP_VSAM_PUT, LAST_OP_VSAM_SHOWCB, LAST_OP_VSAM_TESTCB, LOCATE_KEY_EQ, LOCATE_KEY_EQ_BWD, LOCATE_KEY_FIRST, LOCATE_KEY_GE, LOCATE_KEY_LAST, LOCATE_RBA_EQ, LOCATE_RBA_EQ_BWD, MODE_FLAG_APPEND, MODE_FLAG_READ, MODE_FLAG_UPDATE, MODE_FLAG_WRITE, OPEN_MODE_BINARY, OPEN_MODE_RECORD, OPEN_MODE_TEXT, RECFM_A, RECFM_B, RECFM_F, RECFM_M, RECFM_S, RECFM_U, RECFM_V, S_IRGRP, S_IROTH, S_IRUSR, S_IRWXG, S_IRWXO, S_IRWXU, S_ISGID, S_ISUID, S_ISVTX, S_IWGRP, S_IWOTH, S_IWUSR, S_IXGRP, S_IXOTH, S_IXUSR, SEEK_CUR, SEEK_END, SEEK_SET, VSAM_TYPE_ESDS, VSAM_TYPE_ESDS_PATH, VSAM_TYPE_KSDS, VSAM_TYPE_KSDS_PATH, VSAM_TYPE_NOTVSAM, VSAM_TYPE_RRDS
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method and Description abstract void
close()
Close the reader and underlying native file.abstract void
flush()
Flush any outstanding writes on the native file.boolean
getAutoFree()
Answer a flag that indicates whether the DD name associated with this file will automatically be freed when the file is closed.abstract int
getBlksize()
Answer the BLKSIZE, which is the maximum block length supported by the dataset.abstract java.lang.String
getDDName()
Answers the DD name used to open the underlying file.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.abstract int
getLrecl()
Answer the LRECL, which is the maximum record length for variable length files.abstract java.lang.String
getRecfm()
Get the native file's record format.abstract int
getRecfmBits()
Answer the RECFM bitsstatic RecordWriter
newWriter(java.lang.String name, int flags)
Construct a new RecordWriter for an existing z/OS data set.static RecordWriter
newWriterForDD(java.lang.String ddname)
Construct a new RecordWriter on the given DD.void
setAutoFree(boolean autoFree)
Sets a flag that will cause the DD to automatically be freed afterclose()
.abstract void
write(byte[] buf)
Write a record from the buffer to the native file.abstract void
write(byte[] buf, int offset, int len)
Write a record from the buffer to the native file.
-
-
-
Method Detail
-
newWriterForDD
public static RecordWriter newWriterForDD(java.lang.String ddname) throws ZFileException
Construct a new RecordWriter 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.
-
newWriter
public static RecordWriter newWriter(java.lang.String name, int flags) throws ZFileException, RcException
Construct a new RecordWriter for an existing z/OS data set.- Parameters:
name
- the name of the file to open, in the same syntax asZFile.ZFile(String, String)
, the same syntax defined by the C-Library fopen() function. If the name specifies aDD:DDNAME
, then refer tonewWriterForDD(String)
for supported data definition syntaxflags
-- 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. This option should be used with caution, since there will be no serialization of data access.
- If FLAG_DISP_OLD or 0 and name refers to a dataset name, it will be allocated with DISP=OLD.
- If FLAG_DISP_MOD and name refers to a dataset name, it will be allocated with DISP=MOD.
- If the name specifies a
- Throws:
ZFileException
- if the file could not be opened.RcException
- if an error occurs when attempting to allocate the dataset, the exception fromZFile.bpxwdyn(String)
is thrown.- Since:
- 2.4.2
-
write
public abstract void write(byte[] buf) throws ZFileException
Write a record from the buffer to the native file.- Parameters:
buf
- the byte array representing the record to be written- Throws:
ZFileException
- if the native call fails
-
write
public abstract void write(byte[] buf, int offset, int len) throws ZFileException
Write a record from the buffer to the native file.- Parameters:
buf
- the byte array representing the record to be writtenoffset
- the offset, inclusive, in buf to start writing byteslen
- the number of bytes to write- 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). Writing can occur on any thread.
- Throws:
ZFileException
- if the native call fails
-
flush
public abstract void flush() throws ZFileException
Flush any outstanding writes on the native file.- 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 file.- 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 RecordWriter was created usingnewWriter()
supplying a dataset name.- Returns:
- boolean
-
setAutoFree
public void setAutoFree(boolean autoFree)
Sets a flag that will cause the DD to automatically be freed afterclose()
.- See Also:
getAutoFree()
-
-