



       NSR DriveDevice Class                                      1


                              Public Methods

       DriveDevice(const String &devfile)
            The constructor.  This method expects as argument a
            String reference containing the pathname of the
            character device file to which the DriveDevice object
            is to be bound.  It assumes that the specified device
            file exists, is accessible (i.e., all components along
            the path have appropriate permissions), and that the
            device file itself corresponds to the disk device that
            the DriveDevice object is to access.

            The constructor performs two primary tasks:  it opens
            the device file for reading and writing (O_RDWR), and
            attempts to get capacity information from the drive
            using appropriate ioctls through the disk driver.  If
            any action during construction fails, then any
            subsequent calls to the read(), write(), or erase()
            methods of the object will fail immediately.

            Return Values:

            None.  The internal error state variable will be set to
            one of the following values, and may be accessed by
            calling the error() method:

            error_None          The method completed successfully.

            error_Empty_path_element The devfile char * argument
                                was NULL.

            error_File_not_found The constructor could not open the
                                argument device file.  The open
                                failure could be the result of
                                access permissions or a nonexistent
                                device file.

            error_Capacity_failed The driver ioctl to get drive
                                capacity information failed.  This
                                failure could result from a
                                nonresponsive disk drive or a bad
                                device file, such as an incorrect
                                major or minor number (these
                                possibilites are not exhaustive).

       ~DriveDevice()
            The destructor.  This method simply closes the file
            descriptor associated with the drive device accessed by
            the DriveDevice object.














       2                                      NSR DriveDevice Class


       UINT32 numSectors()
            This method returns the number of sectors on the disk
            device accessed by the DriveDevice object.

       UINT32 sectorSize()
            This method returns the size, in bytes, of a sector on
            the disk device accessed by the DriveDevice object.

       INT32 read(const PhysExtent& extent, ByteArray& arr)
            The read() method takes a PhysExtent and reads data
            from disk into the user ByteArray arr.  The size of arr
            dictates the number of bytes read from disk:  if the
            number of bytes referenced by extent is greater than
            the size of arr, then the user array will be filled
            with data read from the Extent list.  If extent is
            smaller than arr, then as many bytes as possible will
            be read from disk, and an error will be flagged (see
            Return Values, below).

            This method will fail immediately if construction of
            the DriveDevice object failed in any way.

            Return Values:

            read() returns the number of bytes actually read from
            disk.  -1 is returned in the case of an actual I/O
            error.  Additionally, the internal error state of the
            DriveDevice object will be set to one of the following
            values:

            error_None     The read completed successfully.

            error_Blank_check An erased sector was encountered
                           somewhere on the media during the read.
                           A "short count" will be returned--
                           reading immediately halts upon a blank
                           check condition.  Any data that was read
                           up to the blank check will be copied
                           into the argument ByteArray.

            error_Read_EOM The read request attempted to read past
                           the physical end of media.  Partial data
                           will be read into the user's ByteArray,
                           and a "short count" will be returned.

            error_Read_EOLM The read request attempted to read past
                           the logical end of media--the argument
                           ExtList did not provide enough data to
                           satisfy the read request.  A "short
                           count" will be returned.













       NSR DriveDevice Class                                      3


            error_Drive_read This error code is generic for an I/O
                           failure of some kind during the read.
                           No valid partial data will be read into
                           the user's ByteArray, and -1 will be
                           returned.

       INT32 write(const PhysExtent& extent, const ByteArray& arr)
            The write() method takes a PhysExtent and writes data
            to disk from the user ByteArray arr.  The size of arr
            dictates the number of bytes written to disk:  if the
            number of bytes referenced by extent is greater than
            the size of arr, then the contents of the user array
            will be written to disk locations specified by the
            Extent list.  If extent is smaller than arr, then as
            many bytes as possible will be written to disk, and an
            error will be flagged (see Return Values, below).

            This method will fail immediately if construction of
            the DriveDevice object failed in any way.

            Return Values:

            write() returns the number of bytes actually written to
            disk.  -1 is returned in the case of an actual I/O
            error.  Additionally, the internal error state of the
            DriveDevice object will be set to one of the following
            values:

            error_None     The write completed successfully.

            error_Write_EOM The write request attempted to write
                           past the physical end of media.  Partial
                           data will be written to disk, and a
                           "short count" will be returned.

            error_Write_EOLM The write request attempted to write
                           past the logical end of media--the
                           argument ExtList did not provide enough
                           data space to satisfy the write request.
                           A "short count" will be returned.

            error_Drive_write This error code is generic for an I/O
                           failure of some kind during the write.
                           Partial data may have been written to
                           disk but is not in any way guaranteed.
                           -1 will be returned.

       INT32 write(UINT32 startsector,UINT32 numsectors,const
       ByteArray& arr)
            This method is identical to the
            write(PhysExtent&,ByteArray&) method listed above in












       4                                      NSR DriveDevice Class


            all respects except for the form in which its arguments
            are given.  This version of write takes a starting
            sector and the number of sectors in place of a
            PhysExtent.  In all other respects this write method is
            identical to the other form.

       INT32 erase(const PhysExtent& extent)
            The erase() method takes a PhysExtent and attempts to
            erase all of the sectors within the PhysExtent.
            Important:  in order to do an erase on MO media, the
            disk drive must be opened in exclusive mode.  The
            DriveDevice object automatically attempts to put the
            device in LUN exclusive mode; if any other process has
            the drive open, this method will fail.

            This method will fail immediately if construction of
            the DriveDevice object failed in any way.

            Return Values:

            erase() returns -1 on failure, 0 on success.
            Additionally, the internal error state of the
            DriveDevice object will be set to one of the following
            values:

            error_None       The function completed successfully.

            error_Bad_erase_size The size of the argument Extent
                             was not an exact multiple of the
                             sector size.

            error_Erase_failed An I/O error occurred during the
                             erase operation.  There is no
                             guarantee about how many of the
                             sectors, if any, were actually erased.

       Error error()
            This method returns an Error object describing the
            results of the most recent call to the read(), write(),
            or erase() methods.  The constructor also sets the
            internal error state of the DriveDevice object.  This
            method does not reset the error state, so repeated
            calls to error() will return identical Error objects.

       Error checkValidity()
            This method returns an Error object describing the
            validity of the DriveDevice object.  It should return
            Error(error_None) if the object is valid; if the Error
            value is anything else, the object must be considered
            invalid, and the value of the Error will indicate
            specifically why the object is invalid (see the












       NSR DriveDevice Class                                      5


            DriveDevice() constructor method, above, for error
            codes related to invalid objects).

























































