|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.ibm.jzos.ZFile
public class ZFile
JNI Wrapper for z/OS C-Library IO routines. An instance of ZFile is a thin wrapper around a C-library file handle and can be used to access MVS datasets using a dataset or DD name.
Java native methods in this class simply call their C-library equivalents. Please refer to the following IBM C/C++ publications, which describe how to open MVS datasets and DD names in both record and stream mode.
This class allows files to be opened if they are MVS dataset names ("//x.y.z"), member names ("//x.y.z(m)"), ddnames ("//DD:ddname"), dd member names ("//DD:ddname(member)"). All dataset access methods supported by the C-library fopen() routine (for MVS datasets) are supported. Posix (HFS/zFS) files are not supported - use java.io for Posix files.Dataset names that are not enclosed in single quotes are automatically prefixed with the current userid in a manner prescribed by the C library fopen() routine documentation.
Note:If a Java security manager is active, com.ibm.recordio.RecordFile is used to check that a given dataset or ddname can be read or written. This is so that generated SecurityManager file path names ("/DATASET/X/Y") are consistent with those names used by the com.ibm.recordio (JRIO) package.
ZFile(String, String) for usage examples.
Field Summary |
---|
Constructor Summary | |
---|---|
ZFile(java.lang.String name,
java.lang.String options)
Constructor that creates a wrapper around a z/OS file based on the supplied name and options. |
Method Summary | |
---|---|
static java.lang.String |
allocDummyDDName()
Allocates and returns a new DDName, allocated to "DUMMY". |
static void |
bpxwdyn(java.lang.String command)
Calls the BPXWDYN service, which is a text-based interface to dynamic allocation. |
void |
close()
Close the file. |
static boolean |
ddExists(java.lang.String ddname)
Answer true if the given DD name exists. |
void |
delrec()
Delete the current VSAM record. |
static boolean |
dsExists(java.lang.String dsn)
Answer true if the given dataset name exists. |
static boolean |
exists(java.lang.String filename)
Answer whether the given filename exists. |
void |
flush()
Flush the native file. |
java.lang.String |
getActualFilename()
Get the actual name of the opened file as returned by the fldata() C library function in the fldata_t.__dsname field. |
int |
getBlksize()
Get the native file's blocksize. |
long |
getByteCount()
Get the number of bytes read or written to the native file. |
static java.lang.String |
getDefaultHLQ()
Returns the default datasetname high-level qualifer for the user/job. |
int |
getDevice()
Gets the __device value from the C-library fldata structure. |
int |
getDsorg()
Get the native file's dataset organization. |
java.lang.String |
getFilename()
Get the name used to open the file. |
static java.lang.String |
getFullyQualifiedDSN(java.lang.String dsn)
Returns a fully qualified dataset name. |
static java.lang.String |
getFullyQualifiedDSN(java.lang.String dsn,
boolean isFullyQualified)
Returns a fully qualified dataset name. |
java.io.InputStream |
getInputStream()
Get an InputStream that can be used to read the native file. |
int |
getLrecl()
Get the native file's logical record length. |
int |
getModeFlags()
Gets the __modeflags from the C-library fldata structure. |
int |
getOpenMode()
Gets the __openmode flags from the C-library fldata structure. |
java.lang.String |
getOptions()
Get the file options. |
java.io.OutputStream |
getOutputStream()
Return an OutputStream that can be used to write the native file. |
byte[] |
getPos()
Gets the encoded position of the native file. |
java.lang.String |
getRecfm()
Get the native file's record format. |
int |
getRecfmBits()
Get the native file's record format. |
long |
getRecordCount()
Get the number of records read/written. |
static java.lang.String |
getSlashSlashQuotedDSN(java.lang.String dsn)
Given a dataset name, answers the fully-qualified dataset name enclosed in single quotes and preceded by "//". |
static java.lang.String |
getSlashSlashQuotedDSN(java.lang.String dsn,
boolean isFullyQualified)
Given a dataset name, answers the fully-qualified dataset name enclosed in single quotes and preceded by "//". |
int |
getVsamKeyLength()
Gets the __vsamkeylen from the C-library fldata structure. |
long |
getVsamRBA()
Returns the RBA of the last VSAM record inserted or updated. |
int |
getVsamType()
Return the VSAM type. |
boolean |
locate(byte[] key,
int options)
Locate a record given a key. |
boolean |
locate(byte[] key,
int offset,
int length,
int options)
Locate a record given a key. |
boolean |
locate(long recordNumberOrRBA,
int options)
Locate a record using its record number or RBA. |
static java.lang.String[] |
locateDSN(java.lang.String dsn)
Lookup a datataset name entry in the catalog using the operating system LOCATE CAMLST. |
static void |
locateDSN(java.lang.String dsn,
DatasetVolumeList dsvl)
Lookup a datataset name entry in the catalog using the operating system LOCATE CAMLST. |
static void |
makeFifo(java.lang.String path,
int mode)
Makes a named pipe (fifo). |
static Format1DSCB |
obtainDSN(java.lang.String dsn,
java.lang.String volume)
Read the Format-1 DSCB for a DSN/volume using the OBTAIN/CAMLST SEARCH macro. |
int |
read(byte[] buf)
Read a record from the file into a buffer. |
int |
read(byte[] buf,
int offset,
int len)
Read from the native file into the supplied buffer. |
static void |
remove(java.lang.String fileName)
Removes (deletes) a file (a dataset) |
static void |
rename(java.lang.String oldName,
java.lang.String newName)
Renames a file (a dataset) |
void |
reopen(java.lang.String options)
Reopen the file with different mode options. |
void |
rewind()
Seeks the file to the beginning and resets the counts. |
void |
seek(long offset,
int origin)
Seek the file to the specified offset from origin. |
void |
setPos(byte[] position)
Sets the position of the native file. |
long |
tell()
Returns the position of the file. |
int |
update(byte[] buf)
Update a VSAM record. |
int |
update(byte[] buf,
int offset,
int length)
Update a VSAM record. |
void |
write(byte[] buf)
Write a record to the native file. |
void |
write(byte[] buf,
int offset,
int len)
Write the buffer to the native file. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public ZFile(java.lang.String name, java.lang.String options) throws ZFileException
This method calls the fopen() and fldata() C-library routines.
Note: ZFile does not support opening POSIX (HFS/zFS) files; java.io classes should be used for the POSIX filesystem. Only datasets and ddnames may be opened.
If a Java SecurityManager is in effect, permissions are constructed and checked using the com.ibm.recordio (JRIO) package, which uses the format: "/DATASET/HLQ.X.Y". Refer to JRIO documentation for more information.
The following examples illustrate how to open various types of z/OS files:
ZFile dd = new ZFile("//DD:MYDD", "r");
Opens the DD namee MYDD for reading
ZFile dsn = new ZFile("//'SYS1.HELP(ACCOUNT)'", "rt,type=record");
Opens the member ACCOUNT from the PDS SYS1.HELP for reading text records
ZFile dsn = new ZFile("//SEQ", "wb,type=record,recfm=fb,lrecl=80,noseek");
Opens the data set {MVS_USER}.SEQ for sequential binary writing. Note that ",noseek" should be specified with "type=record" if access is sequential, since performance is greatly improved.
The C-Library documentation on fopen() should be consulted for more information.
name
- the name of the native file to openoptions
- the options to use on the fopen() call
ZFileException
- if the file could not be opened.
java.lang.SecurityException
- if a SecurityManager is active and the required
permission is not granted based on the policy
in effect.Method Detail |
---|
public static java.lang.String allocDummyDDName() throws RcException
RcException
bpxwdyn(String)
public static void bpxwdyn(java.lang.String command) throws RcException
command
-
RcException
- containing the BPXWDYN return code
For more information, see: "Using REXX and z/OS UNIX System Services, SA22-7806", chapter 6,
"BPXWDYN".
Note: the BPXWDYN service requires fully qualified dataset names; it accepts
dsns in single quotes but will not add a prefix for unquoted names.
getFullyQualifiedDSN(String)
may be used to generated a fully-qualified name.
Note: the BPXWDYN keyword parameter "msg(wtp)" can be used to direct allocation error
messages to the job log.
Note: the BPXWDYN keyword parameter "reuse" can be used to reallocate an existing
DDNAME. This is often used along with allocDummyDDName()
to allocate
a system assigned DD name.
public static boolean ddExists(java.lang.String ddname) throws ZFileException
For plain DD names, this only checks that the DD name been defined, not that an underlying dataset exists.
Note: Checking the existence of DDNAME(MEMBER) is not supported.
ddname
- the ddname
May optionally be preceded by "//DD:" or "DD:".
ZFileException
public static boolean dsExists(java.lang.String dsn) throws ZFileException
dsn
- a datasetname, which may be enclosed in single quotes
if already fully qualified, and may or may not be preceded by "//".
The datasetname may include a PDS member name.
ZFileException
public static boolean exists(java.lang.String filename) throws ZFileException
If a //dataset(member) name, the dataset and specified member must exist.
If a DD name, the DDname must exist (but not necessarily refer to an existing dataset).
Note: Posix files (HFS/ZFS) are not support by ZFile; use java.io for these.
filename
- a filename with the same format as used on the ZFile() constructor
and C library fopen() routine. If a dataset name is given and not enclosed in
single quotes, then the current userid is added as a prefix in a manner identical
to the behavior of the C library fopen() routine and the
ZFile
constructor.
ZFileException
- if the given filename is not a //dataset or //dd:name; POSIX/HFS filepaths are not supported by ZFileddExists(String)
,
dsExists(String)
public static java.lang.String getFullyQualifiedDSN(java.lang.String dsn)
The name is first converted to upper case and the leading "//" is removed. If the dataset name is enclosed in single quotes, then it is already fully qualified, otherwise the default high level qualifier is used as a prefix (if it is not null or empty).
This method can be used to convert C library fopen() file name, of the form "//'fully.qualified.dsn' or //unqualified.dsn to a fully qualified dataset name (without "//" and single quotes), the format used by the com.ibm.recordio package.
dsn
- a candidate dataset name
getDefaultHLQ()
public static java.lang.String getFullyQualifiedDSN(java.lang.String dsn, boolean isFullyQualified)
Processing is as follows:
isFullyQualified
is false, the name is prefixed with the default high level
qualifier (if it is not null or empty).isFullyQualified
is true, the name is returned with no prefix
added.This method can be used to convert C library fopen() file name, of the form "//'fully.qualified.dsn' or //unqualified.dsn to a fully qualified dataset name (without "//" and single quotes), the format used by the com.ibm.recordio package.
dsn
- a candidate dataset nameisFullyQualified
- if true, assumes that the dsn is fully qualified even if
it is not wrapped in single quotes.
getDefaultHLQ()
public static java.lang.String getSlashSlashQuotedDSN(java.lang.String dsn)
dsn
- a candidate dataset name
getFullyQualifiedDSN(String)
,
getDefaultHLQ()
public static java.lang.String getSlashSlashQuotedDSN(java.lang.String dsn, boolean isFullyQualified)
dsn
- a candidate dataset nameisFullyQualified
- if true, assumes that the dsn is fully qualified even if
it is not wrapped in single quotes.
getFullyQualifiedDSN(String)
,
getDefaultHLQ()
public static java.lang.String getDefaultHLQ()
This is intended to match the default HLQ used by by the C library routine fopen() for unquoted datasets.
If we are running under TSO, we return the TSO prefix (if not empty), otherwise we return the current userid, which may be thread-specific.
which is used for getting the current MVS userid
,
ZUtil.getCurrentTsoPrefix()
public int getBlksize() throws ZFileException
This information is obtained from the C-Library filedata.__blksize.
ZFileException
- if the native call failspublic long getByteCount() throws ZFileException
Note: This is essentially a count of bytes in previous read or write calls and does not represent the actual size of an existing dataset.
ZFileException
- if the native call failspublic int getDsorg() throws ZFileException
This information is obtained via the fldata() C-Library routine's fldata._dsorg* values. See DSORG_* constants for possible values.
ZFileException
- if the native call failspublic byte[] getPos() throws ZFileException
This method calls the fgetpos() C-library routine.
ZFileException
- if the native call failspublic java.lang.String getActualFilename() throws ZFileException
According to the C++ Runtime library reference:> If the file is a DASD data set or a memory file, the field __dsname contains the dsname. If the file is an HFS file, the field __dsname contains the pathname. For all other files, it is null.
ZFileException
public java.lang.String getFilename()
public java.lang.String getOptions()
public int getOpenMode() throws ZFileException
ZFileException
- if the native call failspublic int getModeFlags() throws ZFileException
ZFileException
- if the native call failspublic int getDevice() throws ZFileException
ZFileException
- if the native call failspublic java.io.InputStream getInputStream()
Prerequisite: The native file was opened in text/stream mode (not binary).
public int getLrecl() throws ZFileException
This returns C-library filedata.__maxreclen. If the RECFM is "V"-something (filedata.__recfmV == 1), then it returns filedata.__maxreclen + 4.
For RECFM=U, the value in filedata.__maxreclen seems set by the C-library to be the same as filedata.__blksize, even though the actual DCB LRECL is unused and often set to 0.
For VSAM datasets, filedata.__maxreclen is the "maxlrecl".
ZFileException
- if the native call failspublic java.io.OutputStream getOutputStream()
Prerequisite: The native file was opened in text/stream mode (not binary).
public java.lang.String getRecfm() throws ZFileException
This information is obtained via the fldata() C-Library routine
The first character of the returned string will be one of the following:
Subsequent characters may also be present in the returned String:
ZFileException
- if the native call failsgetRecfmBits()
public int getRecfmBits() throws ZFileException
This information is obtained via the fldata() C-Library routine's fldata.__recfm* values. See the ZFileConstants.RECFM_* constants for bit mask values.
ZFileException
- if the native call failsgetRecfm()
public long getRecordCount() throws ZFileException
Note: This is essentially a count of previous read or write calls and does not represent the actual size of an existing dataset.
Prerequisite: The native file was opened in record mode.
ZFileException
- if the native call failspublic int getVsamKeyLength() throws ZFileException
ZFileException
public int getVsamType() throws ZFileException
VSAM_TYPE_* constants define values.
ZFileException
- if the native call failspublic long getVsamRBA() throws ZFileException
This value is returned as a Java long, but is in fact an unsigned 4 byte integer from the C Library __amrc.__RBA field. It is undefined for non-VSAM files.
This value may be used in subsequent calls to locate(long, int)
,
specifying the LOCATE_RBA_EQ or LOCATE_RBA_EQ_BWD option.
ZFileException
- if the native call failspublic void close() throws ZFileException
This method calls the fclose() C-Library routine.
ZFileException
- if the native call failspublic void flush() throws ZFileException
This method calls the fflush() C-library routine.
ZFileException
- if the native call failspublic boolean locate(long recordNumberOrRBA, int options) throws ZFileException
This method calls the flocate() C-library routine, using a either a 4 or 8 byte unsignedinteger key constructed from the given long int (the length is dependent on whether running in 31 or 64 bit mode).
recordNumberOrRBA
- the VSAM record number(for RRDS) or RBA to locateoptions
- the locate options to use; see ZFileConstants
.LOCATE_* constants
java.lang.IllegalArgumentException
- if the long is not a valid 4 byte unsigned integer
ZFileException
public boolean locate(byte[] key, int options) throws ZFileException
Prerequisite: The native file is VSAM.
This method calls the flocate() C-library routine
key
- the VSAM key to use for the flocate() calloptions
- the locate options to use; see ZFileConstants
.LOCATE_* constants
ZFileException
public boolean locate(byte[] key, int offset, int length, int options) throws ZFileException
Prerequisite: The native file is VSAM.
This method calls the flocate() C-library routine
key
- the VSAM key to use for the flocate() calloffset
- the offset into the key buffer to the start of the keylength
- the length of the keyoptions
- the locate options to use; see ZFileConstants
.LOCATE_* constants
ZFileException
public static java.lang.String[] locateDSN(java.lang.String dsn) throws RcException
The function and return codes for the LOCATE macro are described in the IBM publication "DFSMSdfp Advanced Services - SC26-4700".
dsn
- a datasetname, which may be enclosed in single quotes
if already fully qualified, and may or may not be preceded by "//".
May not include a PDS member name.
RcException
- containing the LOCATE return code if not 0.locateDSN(String, DatasetVolumeList)
,
getFullyQualifiedDSN(String)
public static void locateDSN(java.lang.String dsn, DatasetVolumeList dsvl) throws RcException
The function and return codes for the LOCATE macro are described in the IBM publication "DFSMSdfp Advanced Services - SC26-4700".
The argument DatasetVolumeList is updated by this api to return the contents of the 265-byte workarea return by the LOCATE macro, and also contains the DSN returned by LOCATE.
dsn
- a datasetname, which may be enclosed in single quotes
if already fully qualified, and may or may not be preceded by "//".
May not include a PDS member name.dsvl
- a DatasetVolumeList object, which is updated to hold the first 20 volumes
RcException
- containing the LOCATE return code if not 0.getFullyQualifiedDSN(String)
public static void makeFifo(java.lang.String path, int mode) throws ZFileException
This method calls the mkfifo() C-library routine.
path
- the path of the HFS file to create as a FIFOmode
- the permission bits to use; see ZFileConstants
.S_* constants
ZFileExceptionException
- if the native call fails
java.lang.SecurityException
- if there is a SecurityManager and access is disallowed.
ZFileException
public static Format1DSCB obtainDSN(java.lang.String dsn, java.lang.String volume) throws RcException
The function and return codes for the OBTAIN / CAMLST-SEARCH macro are described in the IBM publication "DFSMSdfp Advanced Services - SC26-4700".
dsn
- a datasetname, which may be enclosed in single quotes
if already fully qualified, and may or may not be preceded by "//".
May not include a PDS member name.volume
- a MVS volume name, up to six characters in length
RcException
- containing the OBTAIN return code if not 0.Format1DSCB
,
getFullyQualifiedDSN(String)
public int read(byte[] buf) throws ZFileException
This method calls the fread() C-library routine, but return code is made to be compatible with Stream.read().
buf
- the byte array into which the bytes will be read
ZFileException
- if the native call failspublic int read(byte[] buf, int offset, int len) throws ZFileException
This method calls the fread() C-library routine, but return code is made to be compatible with Stream.read().
buf
- the byte array into which the bytes will be readoffset
- the offset, inclusive in buf to start reading byteslen
- the number of bytes to read
ZFileException
- if the native call failspublic void reopen(java.lang.String options) throws ZFileException
This method calls the freopen() C-library routine.
options
- the new options to reopen the file with
ZFileException
- if the native call failspublic static void remove(java.lang.String fileName) throws ZFileException
This method calls the remove() C-library routine. To delete a dataset, use "//my.dataset" or "//'fully.qualified.dataset'".
ZFileException
- if the native call fails or file is not a dataset/ddname
java.lang.SecurityException
- if there is a SecurityManager and access is disallowed.public static void rename(java.lang.String oldName, java.lang.String newName) throws ZFileException
This method calls the rename() C-library routine. Dataset names may be specified as "//my.dataset" or "//'fully.qualified.dataset'".
ZFileException
- if the native call fails or file is not a dataset/ddname
java.lang.SecurityException
- if there is a SecurityManager and access is disallowed.public void rewind() throws ZFileException
This method calls the rewind() C-library routine. After successful execution getByteCount() and getRecordCount() will return 0.
ZFileException
- if the native call failspublic void seek(long offset, int origin) throws ZFileException
This method calls the fseeko() C-library routine.
offset
- from origin. Refer to the
C documentation for details regarding
record based files.origin
- where to offset from: SEEK_SET, SEEK_CUR, or SEEK_END
ZFileException
- if the native call failspublic void setPos(byte[] position) throws ZFileException
This method calls the fsetpos() C-library routine.
position
- the native (encoded) file position, which was obtained from
a prior getPos() call.
ZFileException
- if the native call failspublic long tell() throws ZFileException
This method calls the ftello() C-library routine.
ZFileException
- if the native call failspublic int update(byte[] buf) throws ZFileException
Prerequisite: The native file was opened in record mode on a VSAM dataset.
This method calls the fupdate() C-library routine.
buf
- the byte array to use to update the current record with
ZFileException
- if the native call failsupdate(byte[], int, int)
public int update(byte[] buf, int offset, int length) throws ZFileException
Prerequisite: The native file was opened in record mode on a VSAM dataset.
This method calls the fupdate() C-library routine.
buf
- the byte array to use to update the current record withoffset
- the offset into buf to the start of the recordlength
- the length of the record to update
ZFileException
- if the native call failsupdate(byte[])
public void delrec() throws ZFileException
Prerequisite: The native VSAM file was opened in record mode
This method calls the fdelrec() C-library routine.
ZFileException
- if the native call failspublic void write(byte[] buf) throws ZFileException
Prerequisite: The native file was opened in record mode.
This method calls the fwrite() C-library routine.
buf
- the byte array to write to the native file
ZFileException
- if the native call failspublic void write(byte[] buf, int offset, int len) throws ZFileException
This method calls the fwrite() C-library routine.
buf
- the byte array to writeoffset
- the offset, inclusive in buf to start writing bytes fromlen
- the number of bytes to write
ZFileException
- if the native call fails
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |