WriteTapemark
The WriteTapemark
function writes a specified number of filemarks, setmarks, short filemarks, or
long filemarks to a tape device. These tapemarks divide a tape partition into
smaller areas.
DWORD WriteTapemark(
|
HANDLE hDevice, |
// handle to open
device |
|
DWORD dwTapemarkType, |
// type of
tapemarks to write |
|
DWORD dwTapemarkCount, |
// number of
tapemarks to write |
|
BOOL bImmediate |
// return after
write begins |
|
); |
|
Parameters
hDevice
Identifies
the device on which to write tapemarks. This handle is created by using the CreateFile function.
dwTapemarkType
Specifies the
type of tapemarks to write. This parameter can be one of the following values:
|
Value |
Description |
|
TAPE_FILEMARKS |
Writes the
number of filemarks specified by the dwTapemarkCount parameter. |
|
TAPE_LONG_FILEMARKS |
Writes the
number of long filemarks specified by dwTapemarkCount. |
|
TAPE_SETMARKS |
Writes the
number of setmarks specified by dwTapemarkCount. |
|
TAPE_SHORT_FILEMARKS |
Writes the
number of short filemarks specified by dwTapemarkCount. |
dwTapemarkCount
Specifies the
number of tapemarks to write.
bImmediate
Specifies
whether to return as soon as the operation 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
Filemarks,
setmarks, short filemarks, and long filemarks are special recorded elements
that denote the linear organization of the tape. None of these marks contain
user data. Filemarks are the most general marks; setmarks provide a hierarchy
not available with filemarks.
A short
filemark contains a short erase gap that cannot be overwritten unless the write
operation is performed from the beginning of the partition or from an earlier
long filemark.
A long
filemark contains a long erase gap that allows an application to position the
tape at the beginning of the filemark and to overwrite the filemark and the
erase gap.
See Also