Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.ibm.jzos
Class ZFile

    java.lang.Object
      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.

- z/OS XLC/C++ Library Reference SA22-7821
- z/OS XLC/C++ Programming Guide SC09-4765

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:

  - The name is first converted to upper case and the leading "//" (if present) is removed.
  - If the dataset name is enclosed in single quotes, then it is already fully qualified. The name is returned with the quotes removed.
  - If the dataset name is not enclosed in single quotes and:
  - `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.

  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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD