public abstract class RecordWriter extends java.lang.Object implements ZFileConstants
newWriterForDD
and
newWriter(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
using ZFile.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.
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 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.
jzos.bsam.disable
- if this is set to true, then ZFile implementations will be used in all cases rather than direct BSAM implementation classes.
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
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 bits
|
static 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 after
close() . |
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.
|
public static RecordWriter newWriterForDD(java.lang.String ddname) throws ZFileException
ddname
- the previously allocated DD name that is associated with the dataset or file.ZFileException
- if there was an error opening the datasetpublic static RecordWriter newWriter(java.lang.String name, int flags) throws ZFileException, RcException
name
- the 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.flags
- DD:DDNAME, then flags must be 0.
ZFileException
- if the file could not be openedRcException
- if an error occurs when attempting to allocate the dataset,
the exception from ZFile.bpxwdyn(String)
is thrownpublic abstract void write(byte[] buf) throws ZFileException
buf
- the byte array representing the record to be writtenZFileException
- if the native call failspublic abstract void write(byte[] buf, int offset, int len) throws ZFileException
buf
- the byte array representing the record to be writtenoffset
- the offset, inclusive, in buf to start writing byteslen
- the number of bytes to writeZFileException
- if the native call failspublic abstract void close() throws ZFileException
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.
ZFileException
- if the native call failspublic abstract void flush() throws ZFileException
ZFileException
- if the native call failspublic abstract int getLrecl()
public abstract int getBlksize()
public abstract int getRecfmBits()
ZFile.getRecfmBits()
public abstract java.lang.String getRecfm()
ZFile.getRecfm()
public abstract java.lang.String getDDName()
public abstract java.lang.String getDsn()
public boolean getAutoFree()
newWriter()
supplying a dataset name.public void setAutoFree(boolean autoFree)
close()
.getAutoFree()