---------------------------------------------------------------------
CLASS: hpACDev --JKH
PUBLIC METHODS:
hpACDev()
Constructor and copy constructor.
~hpACDev()
Destructor.
numSectors()
Returns the number of sectors on the specified surface.
sectorSize()
Returns the sector size of the specified surface.
read()
Reads the specified number of byte from a surface at a given
sector offset into the user's buffer.
write()
Writes the specified number of bytes to a surface at a given
sector offset from the user's buffer.
writeWOE()
Writes the specified number of bytes to a surface at a given
sector offset from the user's buffer in write-without-erase mode.
erase()
Erases the specified number of sectors on a surface at a given
sector offset.
verifyMode()
Sets and gets the verify mode for a given surface (whether the
surface is in write-with-verify mode).
allocDrive()
Allocates a drive resource for a surface and places the surface
in the drive.
freeDrive()
Frees a drive resource allocated by a call to allocDrive() .
error()
Returns the current error state of the hpACDev object.
flush()
Flushes any cached information. (This is a nop)
errorClear()
Clears the error state of the hpACDev object. (This is a nop)
mediaType()
Returns the media type (MO or WORM) for the specified surface.
verifyBlank()
Verifies that the specified range of sectors on a surface are
blank (i.e., erased, or unwritten for WORM).
addSurface()
Maps a slot/side address of a surface in the jukebox to an sid_t.
removeSurface()
Removes a slot/side <-> sid_t mapping from the hpACDev.
sleepMode()
Gets or sets the sleep mode for a surface. (Not implemented fully)
addDriveMap()
Maps a device file to one of the drives in the jukebox.
elementAddresses()
Gets element addresses (mode sense) information from the jukebox.
elementStatus()
Gets element status information from the jukebox.
senseData()
Gets SCSI request sense data from the jukebox.
USAGE NOTES:
-----------------------------------------------------------------------------
---------------------------------------------------------------------
METHOD: hpACDev::acCommand --JKH
Sends a command to the autochanger using the passthru driver.
ARGS:
struct sctl_io *sctl_io IN Pointer to a formatted sctl_io struct to
specify the passthru command
RETURNS:
Returns 0 on success, -1 on failure.
PRE-CONDS:
--hpACDev has been successfully constructed
POST-CONDS:
ERRORS:
error_None: Function completed successfully.
-----------------------------------------------------------------------------
---------------------------------------------------------------------
METHOD: hpACDev::~hpACDev --JKH
The destructor for the hpACDev object.
ARGUMENTS: None.
PRECONDITIONS: None.
POSTCONDITIONS:
--The file descriptor corresponding to the autochanger device bound to this
object, if open, will be closed.
--Any surfaces still in drives, allocated or not, will be put away to their
home slots.
NOTES: It is expected that when the hpACDev goes out of scope, the user
will have freed all drives allocated by the object. This method does NOT
automatically free the SSDevice objects created by allocDrive().
ERRORS: None.
-----------------------------------------------------------------------------
hpACDev::~hpACDev( void )
---------------------------------------------------------------------
METHOD: hpACDev::numSectors --JKH
Returns the number of sectors on the specified surface.
ARGUMENTS:
sid_t sid IN surface identifier
RETURNS:
Returns the number of sectors on the specified surface. Returns 0 if the
argument sid is invalid.
PRECONDITIONS:
--The hpACDev was successfully constructed.
POSTCONDITIONS: see return values.
ERRORS:
error_None: Operation completed successfully.
-----------------------------------------------------------------------------
NSR::UINT32
hpACDev::numSectors( NSR::sid_t sid )
---------------------------------------------------------------------
METHOD: hpACDev::sectorSize --JKH
Returns the size, in bytes, of the specified surface.
ARGUMENTS:
sid_t sid IN surface identifier
RETURNS:
Returns the size, in bytes, of a sector of the specified surface. Returns
0 if the argument sid is invalid.
PRECONDITIONS:
--The hpACDev was successfully constructed.
POSTCONDITIONS: see return values
ERRORS: see return values.
-----------------------------------------------------------------------------
NSR::UINT32
hpACDev::sectorSize( NSR::sid_t sid )
---------------------------------------------------------------------
METHOD: hpACDev::read --JKH
Reads the specified number of sectors into the buffer barr from the argument
surface sid. Buffering will be performed if the request length is not
equal to a sector multiple.
ARGUMENTS:
sid_t sid IN Surface identifier
UINT32 startsector IN Starting sector for the read
UINT32 nbytes IN Number of bytes to read
BYTE * buf IN/OUT Buffer for read data
RETURNS:
Returns the number of bytes read. If -1 is returned, then an actual I/O
error (not a blank check) occurred. If a blank check or read past EOM
condition occurred, a "short count" will be returned.
PRE-CONDS:
--The hpACDev object was successfully constructed
--The argument sid corresponds to surface within the autochanger
--The start sector/nbytes parameters are within physical media boundaries
POST-CONDS:
--The number of bytes specified by the nbytes parameter will be read from
disk and stored in the user's buffer.
ERRORS:
error_None: function completed successfully
error_Invalid_sid: Invalid sid
error_No_free_store: Could not allocate memory for buffering.
error_Empty_path_element: Argument buffer is invalid.
error_Drive_blank_check: A blank sector was encountered during the read.
error_Read_EOM: Attempted to read past physical EOM
error_Drive_read: Generic I/O failure on read
----------------------------------------------------------------------------
---------------------------------------------------------------------
METHOD: hpACDev::write --JKH
Writes the specified number of bytes from the buffer barr to argument
surface and starting sector.
ARGS:
sid_t sid IN Surface identifier
UINT32 startsector IN Starting sector for write
UINT32 nbytes IN Number of bytes to write
BYTE * buf IN Buffer of data to write
RETURNS:
The function returns the number of bytes written. If -1 is returned, then
an actual I/O error occurred. If a write past EOM condition occurred,
a "short count" will be returned. NOTE: if the hpACDev is in verify
mode, and the hpACDev cannot successfully put itself in verify mode
for the write, the write call will fail, returning -1 and setting error
to error_Set_verify_failed.
PRE-CONDS:
--The hpACDev object was successfully constructed and contains media
--The start parameter is in the range [0,number sectors)
--The device is writable (e.g., not write-protected, and if WORM, the
sectors are unwritten.
POST-CONDS:
--The number of bytes specified by nbytes will be written to disk.
ERRORS:
error_None: Function completed successfully.
error_No_free_store: Could not allocate memory for buffering.
error_Empty_path_element: Argument buffer is invalid.
error_Write_EOM: Attempted to write past physical EOM
error_Drive_write: Generic I/O failure on write
error_Set_verify_failed: Cannot set verify mode.
-----------------------------------------------------------------------------
---------------------------------------------------------------------
METHOD: hpACDev::writeWOE --JKH
This method writes the specified sectors to disk from the buffer using
write-without-erase mode.
NOTE: if the sectors to be written without erase are NOT in fact already
erased, they will be garbaged and henceforth unreadable, and no error will
be detected during the write! It is very important that users using this
method are sure that the sectors in question are actually erased.
NOTE: if the underlying drive cannot be placed into write-without-erase
mode, the write will be attempted in write-with-erase mode and no special
error will be flagged.
ARGS:
sid_t IN surface identifier
UINT32 startsector IN starting sector for the write
UINT32 nbytes IN number of bytes to write
BYTE *barr IN buffer to supply data for the write
RETURNS:
The function returns the number of bytes written. If -1 is returned, then
an actual I/O error occurred. If a write past EOM condition occurred,
a "short count" will be returned. If the SSDevice cannot be put into
write-without-erase mode successfully, the call will proceed in normal
write-with-erase mode, and will not flag an error.
PRE-CONDS:
--The hpACDev object was successfully constructed.
--The startsector and nbytes parameters specify a valid address range
--The device is writable (e.g., not write-protected and, if WORM, the
sectors are unwritten.
--The sectors to be written are erased.
POST-CONDS:
--The specified bytes will be written to disk.
ERRORS:
error_None: Function completed successfully.
error_No_free_store: Could not allocate memory for buffering.
error_Empty_path_element: Argument buffer is invalid.
error_Write_EOM: Attempted to write past physical EOM
error_Drive_write: Generic I/O failure on write
-----------------------------------------------------------------------------
---------------------------------------------------------------------
METHOD: hpACDev::erase --JKH
Erases the specified sectors.
ARGS:
sid_t sid IN Surface identifier
UINT32 startsector IN Starting sector for erase
UINT32 numsectors IN Number of sectors to erase
RETURNS:
Returns 0 on success, -1 on failure.
PRE-CONDS:
--The hpACDev object was successfully created and contains media
--The executing process is the only process that has the drive open
--The arguments specify a range of sectors physically accessible on the
media
--The media is erasable (e.g., not a hard disk, not WORM)
POST-CONDS:
--The specified sectors will be erased.
ERRORS:
error_None Function completed successfully.
error_Erase_failed The erase failed due to an I/O error, or inability
to put the drive in exclusive mode.
-----------------------------------------------------------------------------
---------------------------------------------------------------------
METHOD: hpACDev::verifyMode --JKH
Returns the verify mode of the specified surface. A mode of 0 indicates
write-without-verify (the default); a nonzero value indiicates all
subsequent writes to that surface will be performed with verify.
ARGS:
sid_t sid IN Surface identifier
RETURNS:
Returns the current value of the verify mode for that surface. If an
invalid sid_t was specified, the function returns -1.
PRE-CONDS:
--The hpACDev was successfully constructed.
POST-CONDS:
--See above
ERRORS:
error_None: Function completed successfully
error_Invalid_sid: Invalid sid specified
-----------------------------------------------------------------------------
NSR::INT32
hpACDev::verifyMode( NSR::sid_t sid,NSR::INT32 newmode )
NSR::INT32
hpACDev::verifyMode( NSR::sid_t sid )
---------------------------------------------------------------------
METHOD: hpACDev::allocDrive --JKH
Allocates an SSDevice object for the specified surface. This allocation
implies that I/O may be performed to the surface through the returned
SSDevice object pointer. Generally this requires that the surface be
placed in a drive and kept there until the resource is freed, which
consequently may cause that drive to be unavailable for I/O for the
allocating hpACDev object.
NOTE: The user must NOT delete the returned SSDevice object! When the
user no longer needs it, the user must call freeDrive().
The algorithm used here is that when a drive is allocated, the requested
surface is moved into a drive (if it is not already in one). When
the drive is freed, the SSDevice is deleted but the surface is left
in the drive, to prevent unnecessary swaps between read calls, for instance,
to the same surface.
ARGS:
sid_t sid IN Surface identifier
RETURNS:
Upon success, returns a pointer to an SSDevice object. On failure (no
drives available, or an invalid sid_t), returns NULL.
PRE-CONDS:
--The hpACDev was successfully constructed.
POST-CONDS: See above
-----------------------------------------------------------------------------
NSR::SSDevice *
hpACDev::allocDrive(NSR::sid_t sid)
---------------------------------------------------------------------
METHOD: hpACDev::freeDrive --JKH
Frees a drive allocated by a previous call to allocDrive().
ARGS:
SSDevice *drive IN Drive to be freed.
RETURN VALUES:
Returns 0 on success, -1 on failure (invalid drive pointer)
PRE-CONDS:
--The argument SSDevice was allocated by a call to allocDrive()
POST-CONDS:
--The drive resource will be freed and made available for further allocation.
--This method does NOT move the surface back to its home slot.
ERRORS:
error_None: Function completed successfully
error_Null_pointer: Null pointer passed as argument
-----------------------------------------------------------------------------
NSR::INT32
hpACDev::freeDrive(NSR::SSDevice *drivep)
---------------------------------------------------------------------
METHOD: hpACDev::mediaType --JKH
Determines whether the specified surface is WORM media.
ARGUMENTS: None.
RETURNS:
Returns the type of the media (NSR::media_Rewritable or NSR::media_Worm)
PRE-CONDS:
--The hpACDev object was successfully constructed
--The argument sid corresponds to surface within the autochanger
POST-CONDS: See Returns.
----------------------------------------------------------------------------
---------------------------------------------------------------------
METHOD: hpACDev::verifyBlank() --JKH
Verifies that the given sectors are blank (erased).
ARGUMENTS:
sid_t sid IN Surface identifier
UINT32 start IN Starting sector to verify
UINT32 nsectors IN Number of sectors to verify
UINT32 *where OUT If a written sector is encountered, this variable
is filled in with the written sector address.
RETURNS:
Returns True if all of the sectors are blank, False otherwise.
PRECONDITIONS:
--The hpACDev object was successfully constructed.
POSTCONDITIONS: see returns.
-----------------------------------------------------------------------------
---------------------------------------------------------------------
METHOD: hpACDev::addSurface --JKH
Creates a mapping between an sid_t and specified surface given by slot
position in the autochanger and side.
ARGS:
INT32 slot IN Which slot in the autochanger the cartridge resides in.
Slots are numbered from 1 to increasing values.
INT32 side IN Which side of the cartridge. 0 = A side, 1 = B side.
RETURNS:
Returns an allocated sid_t on success. If the specified surface device
file does not exist or is otherwise invalid, the call returns and sid_t
value SID_T_INVALID.
PRE-CONDS:
--The hpACDev was successfully constructed.
--The specified slot in the autochanger is occupied.
POST-CONDS: see return values
-----------------------------------------------------------------------------
---------------------------------------------------------------------
METHOD: hpACDev::removeSurface --JKH
Removes a mapping between an sid_t and (slot,side) surface specification.
ARGS:
sid_t sid IN Surface identifier to be removed from the internal mapping
RETURNS:
returns 0 on success, -1 on failure (invalid sid_t)
PRE-CONDS:
--The hpACDev was successfully constructed.
--The sid_t was allocated by a previous call to addSurface().
POST-CONDS: see return values
-----------------------------------------------------------------------------
---------------------------------------------------------------------
METHOD: hpACDev::sleepMode --JKH
Returns the sleep mode for the autochanger. If nonzero, sleeping is allowed
on any operation that requires a drive resource. The hpACDev will go into
a polling loop to wait for a drive resource. If zero, the default, any
operation that requires a drive resource that cannot be allocated one will
fail immediately with an error_Drive_not_available.
ARGS: None
RETURNS:
Returns the previous value of the sleep mode.
PRE-CONDS:
--The hpACDev was successfully constructed.
POST-CONDS:
--See above
ERRORS:
error_None: Function completed successfully
-----------------------------------------------------------------------------
NSR::INT32
hpACDev::sleepMode( void ) const
---------------------------------------------------------------------
METHOD: hpACDev::addDriveMap --JKH
Creates a mapping between a drive device file and its hardware address.
ARGS:
INT32 id IN SCSI target ID of the drive
INT32 lun IN SCSI LUN ID of the drive
const String& IN Pathname for the disk character device file
RETURNS:
0 on success, -1 on failure (invalid hardware address specified.)
PRE-CONDS:
--The hpACDev was successfully constructed.
--The specified drive is in the autochanger.
POST-CONDS: see return values
-----------------------------------------------------------------------------
---------------------------------------------------------------------
METHOD: hpACDev::elementAddresses
Returns element addresses (mode sense) information.
ARGS:
struct element_addresses& el OUT Struct to hold element addresses info.
RETURNS:
Returns 0 on success, -1 on failure
PRE-CONDS:
--The autochanger was successfully constructed
POST-CONDS: See return values
-----------------------------------------------------------------------------
NSR::INT32
hpACDev::elementAddresses( struct element_addresses& eltaddr )
---------------------------------------------------------------------
METHOD: hpACDev::elementStatus
Returns status information about an element in the autochanger
ARGS:
INT32 element IN Element to get status for
struct element_status& eltstat OUT Status information
RETURNS:
Returns 0 on success, -1 on failure
PRE-CONDS:
--The autochanger was successfully constructed
POST-CONDS: See return values
-----------------------------------------------------------------------------
---------------------------------------------------------------------
METHOD: hpACDev::senseData
Returns the sense data from the last SCSI command if any.
ARGS:
struct sense_2_aligned& sense OUT Struct for the sense data
RETURNS:
Returns the number of bytes of sense data available. If 0, the last SCSI
command executed succeeed.
PRE-CONDS:
--The autochanger was successfully constructed.
POST-CONDS: see return values
-----------------------------------------------------------------------------