PrepareTape
The PrepareTape
function prepares the tape to be accessed or removed.
DWORD PrepareTape(
|
HANDLE hDevice, |
// handle of open
device |
|
DWORD dwOperation, |
// preparation
method |
|
BOOL bImmediate |
// return after
operation begins |
|
); |
|
Parameters
hDevice
Identifies
the device preparing the tape. This handle is created by using the CreateFile function.
dwOperation
Specifies how
the tape device is to be prepared. This parameter can be one of the following
values:
|
Value |
Meaning |
|
TAPE_FORMAT |
Performs a
low-level format of the tape. Currently, only the QIC117 device supports this
feature. |
|
TAPE_LOAD |
Loads the
tape and moves the tape to the beginning. |
|
TAPE_LOCK |
Locks the
tape ejection mechanism so that the tape is not ejected accidentally. |
|
TAPE_TENSION |
Adjusts the
tension by moving the tape to the end of the tape and back to the beginning.
This option is not supported by all devices. This value is ignored if it is
not supported. |
|
TAPE_UNLOAD |
Moves the
tape to the beginning for removal from the device. After a successful unload
operation, the device returns errors to applications that attempt to access
the tape, until the tape is loaded again. |
|
TAPE_UNLOCK |
Unlocks the
tape ejection mechanism. |
bImmediate
Specifies
whether to return as soon as the preparation begins. If this parameter is TRUE,
the function returns immediately. If it is FALSE, the function does not return
until the operation has been completed.
Return Values
If the
function succeeds, the return value is NO_ERROR.
If the
function fails, the return value is one of the following error codes:
|
Error |
Description |
|
ERROR_BEGINNING_OF_MEDIA |
An attempt
to access data before the beginning-of-medium marker failed. |
|
ERROR_BUS_RESET |
A reset
condition was detected on the bus. |
|
ERROR_END_OF_MEDIA |
The
end-of-tape marker was reached during an operation. |
|
ERROR_FILEMARK_DETECTED |
A filemark
was reached during an operation. |
|
ERROR_SETMARK_DETECTED |
A setmark
was reached during an operation. |
|
ERROR_NO_DATA_DETECTED |
The
end-of-data marker was reached during an operation. |
|
ERROR_PARTITION_FAILURE |
The tape
could not be partitioned. |
|
ERROR_INVALID_BLOCK_LENGTH |
The block
size is incorrect on a new tape in a multivolume partition. |
|
ERROR_DEVICE_NOT_PARTITIONED |
The
partition information could not be found when a tape was being loaded. |
|
ERROR_MEDIA_CHANGED |
The tape
that was in the drive has been replaced or removed. |
|
ERROR_NO_MEDIA_IN_DRIVE |
There is no
media in the drive. |
|
ERROR_NOT_SUPPORTED |
The tape
driver does not support a requested function. |
|
ERROR_UNABLE_TO_LOCK_MEDIA |
An attempt
to lock the ejection mechanism failed. |
|
ERROR_UNABLE_TO_UNLOAD_MEDIA |
An attempt
to unload the tape failed. |
|
ERROR_WRITE_PROTECT |
The media
is write protected. |
Remarks
Some tape
devices do not support certain tape operations. See your tape device
documentation and use the GetTapeParameters function to determine your tape device s
capabilities.
See Also