com.ibm.jzos
Class ZFile

java.lang.Object
  extended by com.ibm.jzos.ZFile
All Implemented Interfaces:
ZFileConstants

public class ZFile
extends java.lang.Object
implements ZFileConstants

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.

See Also:
ZFile(String, String) for usage examples.

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, 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
 
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

ZFile

public ZFile(java.lang.String name,
             java.lang.String options)
      throws ZFileException
Constructor that creates a wrapper around a z/OS file based on the supplied name and options.

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.

Parameters:
name - the name of the native file to open
options - the options to use on the fopen() call
Throws:
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

allocDummyDDName

public static java.lang.String allocDummyDDName()
                                         throws RcException
Allocates and returns a new DDName, allocated to "DUMMY". This name is commonly used as a ddname to construct a dynamic allocation command using bpxwdyn(), and subsequently opened using ZFile("//DD:" + ddname);

Returns:
String the ddname
Throws:
RcException
See Also:
bpxwdyn(String)

bpxwdyn

public static void bpxwdyn(java.lang.String command)
                    throws RcException
Calls the BPXWDYN service, which is a text-based interface to dynamic allocation.

Parameters:
command -
Throws:
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.


ddExists

public static boolean ddExists(java.lang.String ddname)
                        throws ZFileException
Answer true if the given DD name exists.

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.

Parameters:
ddname - the ddname May optionally be preceded by "//DD:" or "DD:".
Returns:
true if the DDNAME exists, false otherwise.
Throws:
ZFileException

dsExists

public static boolean dsExists(java.lang.String dsn)
                        throws ZFileException
Answer true if the given dataset name exists.

Parameters:
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.
Returns:
true if the dataset exists, false otherwise. If a dataset(member) name is given, the PDS member must exist.
Throws:
ZFileException

exists

public static boolean exists(java.lang.String filename)
                      throws ZFileException
Answer whether the given filename exists. If a //dataset name, the dataset must be cataloged and exist on disk.

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.

Parameters:
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.

Returns:
true if the dataset/member/ddname exists, false otherwise.
Throws:
ZFileException - if the given filename is not a //dataset or //dd:name; POSIX/HFS filepaths are not supported by ZFile
See Also:
ddExists(String), dsExists(String)

getFullyQualifiedDSN

public static java.lang.String getFullyQualifiedDSN(java.lang.String dsn)
Returns a fully qualified dataset name.

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.

Parameters:
dsn - a candidate dataset name
Returns:
the fully qualified dataset name, without "//" or single quotes
See Also:
getDefaultHLQ()

getFullyQualifiedDSN

public static java.lang.String getFullyQualifiedDSN(java.lang.String dsn,
                                                    boolean isFullyQualified)
Returns a fully qualified dataset name.

Processing is as follows:

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.

Parameters:
dsn - a candidate dataset name
isFullyQualified - if true, assumes that the dsn is fully qualified even if it is not wrapped in single quotes.
Returns:
the fully qualified dataset name, without "//" or single quotes
See Also:
getDefaultHLQ()

getSlashSlashQuotedDSN

public 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 "//".

Parameters:
dsn - a candidate dataset name
Returns:
the fully qualified dataset name, enclosed in single quotes and preceded by "//"
See Also:
getFullyQualifiedDSN(String), getDefaultHLQ()

getSlashSlashQuotedDSN

public 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 "//".

Parameters:
dsn - a candidate dataset name
isFullyQualified - if true, assumes that the dsn is fully qualified even if it is not wrapped in single quotes.
Returns:
the fully qualified dataset name, enclosed in single quotes and preceded by "//"
See Also:
getFullyQualifiedDSN(String), getDefaultHLQ()

getDefaultHLQ

public static java.lang.String getDefaultHLQ()
Returns the default datasetname high-level qualifer for the user/job.

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.

See Also:
which is used for getting the current MVS userid, ZUtil.getCurrentTsoPrefix()

getBlksize

public int getBlksize()
               throws ZFileException
Get the native file's blocksize.

This information is obtained from the C-Library filedata.__blksize.

Returns:
the blocksize
Throws:
ZFileException - if the native call fails

getByteCount

public long getByteCount()
                  throws ZFileException
Get the number of bytes read or written to the native file.

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.

Returns:
the number of bytes read or written
Throws:
ZFileException - if the native call fails

getDsorg

public int getDsorg()
             throws ZFileException
Get the native file's dataset organization.

This information is obtained via the fldata() C-Library routine's fldata._dsorg* values. See DSORG_* constants for possible values.

Returns:
the native file's DSORG value
Throws:
ZFileException - if the native call fails

getPos

public byte[] getPos()
              throws ZFileException
Gets the encoded position of the native file.

This method calls the fgetpos() C-library routine.

Returns:
byte[] - the native (encoded) file position
Throws:
ZFileException - if the native call fails

getActualFilename

public java.lang.String getActualFilename()
                                   throws ZFileException
Get the actual name of the opened file as returned by the fldata() C library function in the fldata_t.__dsname field.

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.

Returns:
the actual name of the native file
Throws:
ZFileException

getFilename

public java.lang.String getFilename()
Get the name used to open the file.

Returns:
the name of the native file

getOptions

public java.lang.String getOptions()
Get the file options.

Returns:
the options used to open the native file

getOpenMode

public int getOpenMode()
                throws ZFileException
Gets the __openmode flags from the C-library fldata structure. The ZFile.OPEN_MODE_* constants can be used as values.

Throws:
ZFileException - if the native call fails

getModeFlags

public int getModeFlags()
                 throws ZFileException
Gets the __modeflags from the C-library fldata structure. The ZFile.MODE_FLAG_* constants can be used as bit values of this flag.

Throws:
ZFileException - if the native call fails

getDevice

public int getDevice()
              throws ZFileException
Gets the __device value from the C-library fldata structure. The ZFile.DEVICE_* constants can be used as values.

Throws:
ZFileException - if the native call fails

getInputStream

public java.io.InputStream getInputStream()
Get an InputStream that can be used to read the native file.

Prerequisite: The native file was opened in text/stream mode (not binary).

Returns:
a stream to be used for reading the native file

getLrecl

public int getLrecl()
             throws ZFileException
Get the native file's logical record length.

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".

Returns:
the native file's LRECL
Throws:
ZFileException - if the native call fails

getOutputStream

public java.io.OutputStream getOutputStream()
Return an OutputStream that can be used to write the native file.

Prerequisite: The native file was opened in text/stream mode (not binary).

Returns:
a stream to be used for writing to the native file

getRecfm

public java.lang.String getRecfm()
                          throws ZFileException
Get the native file's record format.

This information is obtained via the fldata() C-Library routine

The first character of the returned string will be one of the following:

  • F - Fixed length records
  • V - Variable length records
  • U - Undefined length records

Subsequent characters may also be present in the returned String:

  • A - The file has ASA print control characters
  • B - The file has Blocked records
  • M - The file has Machine print control characters
  • S - The file has Standard (if Fixed) or Spanned (if Variable) records

Returns:
the native file's RECFM
Throws:
ZFileException - if the native call fails
See Also:
getRecfmBits()

getRecfmBits

public int getRecfmBits()
                 throws ZFileException
Get the native file's record format.

This information is obtained via the fldata() C-Library routine's fldata.__recfm* values. See the ZFileConstants.RECFM_* constants for bit mask values.

Returns:
the native file's RECFM
Throws:
ZFileException - if the native call fails
See Also:
getRecfm()

getRecordCount

public long getRecordCount()
                    throws ZFileException
Get the number of records read/written.

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.

Returns:
the number of records read or written
Throws:
ZFileException - if the native call fails

getVsamKeyLength

public int getVsamKeyLength()
                     throws ZFileException
Gets the __vsamkeylen from the C-library fldata structure.

Throws:
ZFileException

getVsamType

public int getVsamType()
                throws ZFileException
Return the VSAM type.

VSAM_TYPE_* constants define values.

Throws:
ZFileException - if the native call fails

getVsamRBA

public long getVsamRBA()
                throws ZFileException
Returns the RBA of the last VSAM record inserted or updated.

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.

Throws:
ZFileException - if the native call fails

close

public void close()
           throws ZFileException
Close the file. Regardless of the success of the native operation, set the handle to 0 (null) so that the file is rendered invalid.

This method calls the fclose() C-Library routine.

Throws:
ZFileException - if the native call fails

flush

public void flush()
           throws ZFileException
Flush the native file.

This method calls the fflush() C-library routine.

Throws:
ZFileException - if the native call fails

locate

public boolean locate(long recordNumberOrRBA,
                      int options)
               throws ZFileException
Locate a record using its record number or RBA.

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).

Parameters:
recordNumberOrRBA - the VSAM record number(for RRDS) or RBA to locate
options - the locate options to use; see ZFileConstants.LOCATE_* constants
Returns:
true if the locate was successful, false otherwise
Throws:
java.lang.IllegalArgumentException - if the long is not a valid 4 byte unsigned integer
ZFileException

locate

public boolean locate(byte[] key,
                      int options)
               throws ZFileException
Locate a record given a key.

Prerequisite: The native file is VSAM.

This method calls the flocate() C-library routine

Parameters:
key - the VSAM key to use for the flocate() call
options - the locate options to use; see ZFileConstants.LOCATE_* constants
Returns:
true if the locate was successful, false otherwise
Throws:
ZFileException

locate

public boolean locate(byte[] key,
                      int offset,
                      int length,
                      int options)
               throws ZFileException
Locate a record given a key.

Prerequisite: The native file is VSAM.

This method calls the flocate() C-library routine

Parameters:
key - the VSAM key to use for the flocate() call
offset - the offset into the key buffer to the start of the key
length - the length of the key
options - the locate options to use; see ZFileConstants.LOCATE_* constants
Returns:
true if the locate was successful, false otherwise
Throws:
ZFileException

locateDSN

public static java.lang.String[] locateDSN(java.lang.String dsn)
                                    throws RcException
Lookup a datataset name entry in the catalog using the operating system LOCATE CAMLST. Return an array of Strings containing the names of the MVS volumes (up to the first 20) that that contain the cataloged datasets. Throws an RcException containing the return code from the LOCATE macro if not zero.

The function and return codes for the LOCATE macro are described in the IBM publication "DFSMSdfp Advanced Services - SC26-4700".

Parameters:
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.
Returns:
String[] an array of up to the first 20 volumes containing the dataset
Throws:
RcException - containing the LOCATE return code if not 0.
See Also:
locateDSN(String, DatasetVolumeList), getFullyQualifiedDSN(String)

locateDSN

public static void locateDSN(java.lang.String dsn,
                             DatasetVolumeList dsvl)
                      throws RcException
Lookup a datataset name entry in the catalog using the operating system LOCATE CAMLST. Throws an RcException containing the return code from the LOCATE macro if not zero.

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.

Parameters:
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
Throws:
RcException - containing the LOCATE return code if not 0.
See Also:
getFullyQualifiedDSN(String)

makeFifo

public static void makeFifo(java.lang.String path,
                            int mode)
                     throws ZFileException
Makes a named pipe (fifo).

This method calls the mkfifo() C-library routine.

Parameters:
path - the path of the HFS file to create as a FIFO
mode - the permission bits to use; see ZFileConstants.S_* constants
Throws:
ZFileExceptionException - if the native call fails
java.lang.SecurityException - if there is a SecurityManager and access is disallowed.
ZFileException

obtainDSN

public static Format1DSCB obtainDSN(java.lang.String dsn,
                                    java.lang.String volume)
                             throws RcException
Read the Format-1 DSCB for a DSN/volume using the OBTAIN/CAMLST SEARCH macro.

The function and return codes for the OBTAIN / CAMLST-SEARCH macro are described in the IBM publication "DFSMSdfp Advanced Services - SC26-4700".

Parameters:
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
Returns:
Format1DSCB an object which maps the fields in the Format1 VTOC entry for the dataset.
Throws:
RcException - containing the OBTAIN return code if not 0.
See Also:
Format1DSCB, getFullyQualifiedDSN(String)

read

public int read(byte[] buf)
         throws ZFileException
Read a record from the file into a buffer.

This method calls the fread() C-library routine, but return code is made to be compatible with Stream.read().

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 int read(byte[] buf,
                int offset,
                int len)
         throws ZFileException
Read from the native file into the supplied buffer.

This method calls the fread() C-library routine, but return code is made to be compatible with Stream.read().

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

reopen

public void reopen(java.lang.String options)
            throws ZFileException
Reopen the file with different mode options.

This method calls the freopen() C-library routine.

Parameters:
options - the new options to reopen the file with
Throws:
ZFileException - if the native call fails

remove

public static void remove(java.lang.String fileName)
                   throws ZFileException
Removes (deletes) a file (a dataset)

This method calls the remove() C-library routine. To delete a dataset, use "//my.dataset" or "//'fully.qualified.dataset'".

Throws:
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.

rename

public static void rename(java.lang.String oldName,
                          java.lang.String newName)
                   throws ZFileException
Renames a file (a dataset)

This method calls the rename() C-library routine. Dataset names may be specified as "//my.dataset" or "//'fully.qualified.dataset'".

Throws:
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.

rewind

public void rewind()
            throws ZFileException
Seeks the file to the beginning and resets the counts.

This method calls the rewind() C-library routine. After successful execution getByteCount() and getRecordCount() will return 0.

Throws:
ZFileException - if the native call fails

seek

public void seek(long offset,
                 int origin)
          throws ZFileException
Seek the file to the specified offset from origin.

This method calls the fseeko() C-library routine.

Parameters:
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
Throws:
ZFileException - if the native call fails

setPos

public void setPos(byte[] position)
            throws ZFileException
Sets the position of the native file.

This method calls the fsetpos() C-library routine.

Parameters:
position - the native (encoded) file position, which was obtained from a prior getPos() call.
Throws:
ZFileException - if the native call fails

tell

public long tell()
          throws ZFileException
Returns the position of the file.

This method calls the ftello() C-library routine.

Returns:
The file position. Refer to the C documentation for details regarding record based files.
Throws:
ZFileException - if the native call fails

update

public int update(byte[] buf)
           throws ZFileException
Update a VSAM record.

Prerequisite: The native file was opened in record mode on a VSAM dataset.

This method calls the fupdate() C-library routine.

Parameters:
buf - the byte array to use to update the current record with
Returns:
the number of bytes updated (the input record length).
Throws:
ZFileException - if the native call fails
See Also:
update(byte[], int, int)

update

public int update(byte[] buf,
                  int offset,
                  int length)
           throws ZFileException
Update a VSAM record.

Prerequisite: The native file was opened in record mode on a VSAM dataset.

This method calls the fupdate() C-library routine.

Parameters:
buf - the byte array to use to update the current record with
offset - the offset into buf to the start of the record
length - the length of the record to update
Returns:
the number of bytes updated (the input record length)
Throws:
ZFileException - if the native call fails
See Also:
update(byte[])

delrec

public void delrec()
            throws ZFileException
Delete the current VSAM record.

Prerequisite: The native VSAM file was opened in record mode

This method calls the fdelrec() C-library routine.

Throws:
ZFileException - if the native call fails

write

public void write(byte[] buf)
           throws ZFileException
Write a record to the native file.

Prerequisite: The native file was opened in record mode.

This method calls the fwrite() C-library routine.

Parameters:
buf - the byte array to write to the native file
Throws:
ZFileException - if the native call fails

write

public void write(byte[] buf,
                  int offset,
                  int len)
           throws ZFileException
Write the buffer to the native file.

This method calls the fwrite() C-library routine.

Parameters:
buf - the byte array to write
offset - the offset, inclusive in buf to start writing bytes from
len - the number of bytes to write
Throws:
ZFileException - if the native call fails