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.

    For more efficient z/OS sequential dataset record read and write, please refer to RecordReader and RecordWriter.

    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"), and 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, it is used to check that a given dataset or ddname can be read or written.

    See Also:
    ZFile(String, String) for usage examples, RecordReader, RecordWriter

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

        Note: If a Java security manager is active, it is used to check that a given dataset or ddname can be read or written using the security name: "/DATASET/HLQ.X.Y" or "/DATASET/DD:DDNAME"

        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");

        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.

      • ZFile

        public ZFile(java.lang.String name,
             java.lang.String options,
             int flags)
      throws ZFileException,
             RcException,
             EnqueueException
        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 format: "/DATASET/HLQ.X.Y" or "/DATASET/DD:DDNAME"

        The following examples illustrate how to open various types of z/OS files: 

        ZFile dsn = new ZFile("//'SYS1.HELP(ACCOUNT)'", "rt", FLAG_DISP_SHR);

        Opens the member ACCOUNT from the PDS SYS1.HELP for reading text records, with DISP=SHR 

        ZFile dsn = new ZFile("//SEQ", "wb,type=record,recfm=fb,lrecl=80,noseek", FLAG_DISP_SHR);

        Opens the data set {MVS_USER}.SEQ for sequential binary writing, opened with DISP=SHR Note that ",noseek" should be specified with "type=record" if access is sequential, since performance is greatly improved. 

        ZFile dsn = new ZFile("//MY.PDS(MEM1)", "wt", FLAG_DISP_SHR+FLAG_PDS_ENQ);

        Opens the PDS member {MVS_USER}.MY.PDS(MEM1) for writing sequential text records, opened with DISP=SHR. ISPF compatible ENQs are use to serialize access to the dataset and member.

        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
        flags -
        • If FLAG_DISP_SHR, the dataset will be allocated with DISP=SHR.
        • If FLAG_DISP_SHR + FLAG_PDS_ENQ and opening a PDS member in write mode, the dataset must refer to an existing PDS which will be allocated with DISP=SHR and access to the PDS and member will be serialized using ISPF compatible enqueues.
        • If FLAG_DISP_SHR + FLAG_PDS_ENQ and opening a file in write mode that is not a PDS member, then both flags will be ignored and the file will be opened with DISP=OLD.
        • If FLAG_DISP_SHR + FLAG_PDS_ENQ and opening in read mode, then FLAG_PDS_ENQ will be ignored and the dataset will be opened with DISP=SHR.
        Throws:
        ZFileException - if the file could not be opened
        RcException - if an error occurs when attempting to allocate the dataset for FLAG_DISP_SHR
        EnqueueException - if an error occurs when attempting to enqueue the dataset or member for FLAG_PDS_ENQ. Note: EnqueueException is a subclass of RcException
        java.lang.SecurityException - if a SecurityManager is active and the required permission is not granted based on the policy in effect.
        Since:
        2.4.0

    • 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);

        The caller is responsible for releasing the allocated DDName to the system. Use ZFile.bpxwdyn("free fi(" + 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 - the string passed to the BPXWDYN service
        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.

      • dsExists

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

        Note: Only datasets with FB or VB record format are supported prior to version 2.4.0.

        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. //DD:ddname(mem) is also supported, but concatenated PDSs are not supported. If the name is a GDG relative reference, the reference is relative to the current/latest catalog information for the GDG.
        Returns:
        true if the dataset exists, false otherwise. If a dataset(member) name is given, the PDS member must exist.
        Throws:
        ZFileException - if dsn is invalid or if there is an unexpected exception determining if the file exists.
        See Also:
        exists(String) as a preferred API which will call this method or ddExists() as appropriate

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

        If a //dataset(member) name, the dataset and specified member must exist.

        If a //gdg(0) or //gdg(-n) relative reference, it must refer to a cataloged GDS entry. The latest catalog information will be used to resolve relative GDS references.

        If a //DD:name, the DDname must exist (but not necessarily refer to an existing dataset).

        If a //DD:name(member), the DDname must refer to a PDS and the member must exist, although concatenated PDSs are not supported.

        Note: Posix files (HFS/ZFS) are not support by ZFile; use java.io for these.

        Note: Only datasets with FB or VB record format are supported prior to version 2.4.0.

        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 or if there is an unexpected error in an underlying system service; POSIX/HFS filepaths are not supported by ZFile

      • getFullyQualifiedDSN

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

        The name is converted to capital letters 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 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 and the dsn is not already enclosed in single quotes).
          • isFullyQualified is true, the name is returned with no prefix added.
        • If the dataset name is a DD:ddname or &TEMP file reference, then return this name.

        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.

        Note: If a syntactically illegal dsn is given, then the result will also be invalid.

        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
        Since:
        2.2.1
        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 "//".

        Rules for adding a high-level qualifier prefix to the dataset name are the same as getFullyQualifiedDSN(String).

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

        Rules for adding a high-level qualifier prefix to the dataset name are the same as getFullyQualifiedDSN(String, boolean).

        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 "//"
        Since:
        2.2.1
        See Also:
        getFullyQualifiedDSN(String), getDefaultHLQ()

      • getDefaultHLQ

        public static java.lang.String getDefaultHLQ()
        Returns the default datasetname high-level qualifier 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:
        com.ibm.os390.security.PlatformThread#getUserName() 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 should be opened in stream mode, and must not be opened for sequential record I/O, meaning no type=record.

        Returns:
        a stream to be used for reading the native file.
        Throws:
        java.lang.IllegalStateException - if the file was not opened in read mode.

      • 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 should be opened in stream mode, and must not be opened for sequential record I/O, meaning no type=record.

        Returns:
        a stream to be used for writing to the native file.
        Throws:
        java.lang.IllegalStateException - if the file was not opened in write mode.

      • 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. This method returns 0 if the file is not opened in record mode.
        Throws:
        ZFileException - if the native call fails

      • getVsamKeyLength

        public int getVsamKeyLength()
                     throws ZFileException
        Gets the __vsamkeylen from the C-library fldata structure. This value is undefined if the file is not VSAM.
        Throws:
        ZFileException

      • getVsamType

        public int getVsamType()
                throws ZFileException
        Return the VSAM type from the __vsamtype fieldof the C-library fldata structure.

        VSAM_TYPE_* constants define values. This value is undefined if the file is not VSAM.

        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,
                  RcException
        Close the file. Regardless of the success of the native operation, set the handle to 0 (null) so that the file is rendered invalid.

        If a DISP=SHR allocation was done for FLAG_DISP_SHR or Enqueues are held for FLAG_PDS_ENQ, these are released/freed after closing the DD.

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

        Throws:
        ZFileException - if the native call fails
        RcException

      • doDeqAndUnalloc

        public void doDeqAndUnalloc()
                     throws RcException
        Dequeue the PDS and member if enqueued. Deallocate if allocated.

        Throws:
        RcException - (actually an EnqueueException) if an error occurs when attempting to dequeue

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

        Prerequisite: The native file is VSAM; result is undefined otherwise

        This method calls the flocate() C-library routine, using a either a 4 or 8 byte unsigned integer 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; result is undefined otherwise

        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; result is undefined otherwise

        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

      • locate_unlocked

        public boolean locate_unlocked(long recordNumberOrRBA,
                               int options)
                        throws ZFileException
        Locate a record, without locking, using its record number or RBA. The method does not set locks or test for the presence of locks by others prior to the locate operation.

        Prerequisite: The native file is VSAM; result is undefined otherwise

        This method calls the flocate_unlocked() C-library routine, using a either a 4 or 8 byte unsigned integer key constructed from the given long int (the length is dependent on whether running in 31 or 64 bit mode).

        Note: This method has the same behavior as its counterpart, flocate without the "_unlocked" suffix, except that it does not use the file descriptor's mutex and is not thread safe. Multi-threaded applications should implement their own locking mechanisms to ensure thread safety.

        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
        Since:
        2.4.9

      • locate_unlocked

        public boolean locate_unlocked(byte[] key,
                               int options)
                        throws ZFileException
        Locate a record, without locking, given a key. The method does not set locks or test for the presence of locks by others prior to the locate operation.

        Prerequisite: The native file is VSAM; result is undefined otherwise

        This method calls the flocate_unlocked() C-library routine

        Note: This method has the same behavior as its counterpart, flocate without the "_unlocked" suffix, except that it does not use the file descriptor's mutex and is not thread safe. Multi-threaded applications should implement their own locking mechanisms to ensure thread safety.

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

      • locate_unlocked

        public boolean locate_unlocked(byte[] key,
                               int offset,
                               int length,
                               int options)
                        throws ZFileException
        Locate a record, without locking, given a key. The method does not set locks or test for the presence of locks by others prior to the locate operation.

        Prerequisite: The native file is VSAM; result is undefined otherwise

        This method calls the flocate_unlocked() C-library routine

        Note: This method has the same behavior as its counterpart, flocate without the "_unlocked" suffix, except that it does not use the file descriptor's mutex and is not thread safe. Multi-threaded applications should implement their own locking mechanisms to ensure thread safety.

        Parameters:
        key - the VSAM key to use for the flocate_unlocked() 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
        Since:
        2.4.9

      • locateDSN

        public static java.lang.String[] locateDSN(java.lang.String dsn)
                                    throws RcException
        Lookup a dataset 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 contain the cataloged datasets. Throws a 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 dataset name, 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.
        Since:
        2.1.0
        See Also:
        locateDSN(String, DatasetVolumeList), getFullyQualifiedDSN(String)

      • locateDSN

        public static void locateDSN(java.lang.String dsn,
                             DatasetVolumeList dsvl)
                      throws RcException
        Lookup a dataset name entry in the catalog using the operating system LOCATE CAMLST. Throws a 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 returned by the LOCATE macro, and also contains the DSN returned by LOCATE.

        Parameters:
        dsn - a dataset name, 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.
        Since:
        2.1.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
        Since:
        2.1.0

      • 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-7400.

        This method will return null if the dsn refers to a VSAM cluster.

        Note: This method cannot be used to obtain the DSCB for an extended address volume (EAV) dataset (introduced in z/OS release 10). The more general method readDSCBChain(String, String) can be used to obtain the DSCB structure in all cases. This method will return null if the dsn is on an EAV VTOC.

        Parameters:
        dsn - a dataset name, 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. Return null if dsn is on an EAV VTOC, or if the DSCB is not on the VTOC.
        Throws:
        RcException - containing the OBTAIN return code if not 0.
        Since:
        2.1.0
        See Also:
        Format1DSCB, getFullyQualifiedDSN(String)

      • readDSCBChain

        public static DSCB[] readDSCBChain(java.lang.String dsn,
                                   java.lang.String volume)
                            throws RcException
        Read the entire DSCB structure 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-7400.

        In addition to supporting traditional Format-1 and Format-3 DSCBs, this method also supports the extended address volume Format-8 and Format-9 DSCBs.

        Parameters:
        dsn - a dataset name, 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:
        DSCB[] the array of DSCBs for the dsn volume pair. If no DSCBs are found on the VTOC for the DSN/volume, a zero length array is returned.
        Throws:
        RcException - containing the OBTAIN return code if not 0, or there was an allocation failure in the native code.
        Since:
        2.3.4
        See Also:
        DSCB, Format1DSCB, Format3DSCB, Format3DSCB, Format9DSCB

      • readJFCB

        public static JFCB readJFCB(java.lang.String ddname)
                     throws ZFileException
        A static method for issuing RDJFCB for a given DDNAME.
        Parameters:
        ddname - the DD
        Returns:
        a JFCB object which provides a read-only bean interface to the natve JFCB bytes
        Throws:
        ZFileException - if the DD is missing
        See Also:
        JFCB

      • 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_unlocked

        public int read_unlocked(byte[] buf)
                  throws ZFileException
        Read a record, without locking, from the file into a buffer. The method does not set locks or test for the presence of locks by others prior to the read operation.

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

        Note: This method has the same behavior as its counterpart, fread without the "_unlocked" suffix, except that it does not use the file descriptor's mutex and is not thread safe. Multi-threaded applications should implement their own locking mechanisms to ensure thread safety.

        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
        Since:
        2.4.9

      • 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

      • read_unlocked

        public int read_unlocked(byte[] buf,
                         int offset,
                         int len)
                  throws ZFileException
        Read from the native file, without locking, into the supplied buffer. The method does not set locks or test for the presence of locks by others prior to the read operation.

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

        Note: This method has the same behavior as its counterpart, fread without the "_unlocked" suffix, except that it does not use the file descriptor's mutex and is not thread safe. Multi-threaded applications should implement their own locking mechanisms to ensure thread safety.

        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
        Since:
        2.4.9

      • 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 fremove() 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 frename() 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
Skip navigation links
� Copyright IBM Corporation 2005, 2022.