| DWORD SetTapePosition(hDevice, dwPositionMethod, dwPartition, dwOffset, lpdwOffsetHigh, lpo) | |||||
| HANDLE hDevice; | /* open device handle | */ | |||
| DWORD dwPositionMethod; | /* move type, position, and offset | */ | |||
| DWORD dwPartition; | /* partition to set position in | */ | |||
| DWORD dwOffset; | /* low 32 bits of offset | */ | |||
| LPDWORD lpdwOffsetHigh; | /* high 32 bits of offset | */ | |||
| LPOVERLAPPED lpo; | /* overlapped structure | */ | |||
The SetTapePosition sets the tape position on the specified device.
hDevice
Specifies an open handle to the device to set information for.
dwPositionMethod
Supplies a flag that specifies the type of positioning to be performed (absolute blocks, relative blocks, setmarks, short filemarks, long filemarks, or sequential filemarks). Additionally, TAPE_REWIND, TAPE_REWIND_IMMED, and TAPE_END_OF_DATA will position to either beginning or end of partition. This parameter can specify one move type or one offset description.
The dwPositionMethod parameter can specify one move type from the following list:
| Value | Move |
| TAPE_REWIND | ||
| Move to the beginning of the partition specified by dwPartition. | ||
| TAPE_REWIND_IMMED | ||
| Move to the beginning of the partition specified by dwPartition. Return status as soon as the operation is initiated. | ||
| TAPE_END_OF_DATA | ||
| Move to the end of the data on the partition specified by dwPartition. | ||
The dwPositionMethod parameter can specify one offset description from the following list:
| Value | Offset Description |
| TAPE_ABSOLUTE_BLOCKS | ||
| Indicates that dwOffset is expressed in absolute blocks from the beginning of the partition. | ||
| TAPE_RELATIVE_BLOCKS | ||
| Indicates that dwOffset is expressed in relative blocks from the current tape position. | ||
| TAPE_SETMARKS | ||
| Indicates that dwOffset is expressed in setmarks. | ||
| TAPE_SHORT_FILEMARKS | ||
| Indicates that dwOffset is expressed in short filemarks. | ||
| TAPE_LONG_FILEMARKS | ||
| Indicates that dwOffset is expressed in long filemarks. | ||
| TAPE_SEQUENTIAL_FILEMARKS | ||
| Indicates that dwOffset is expressed in sequential filemarks. | ||
dwPartition
Specifies the partition to position within. If dwPartition is zero, the current partition is used.
dwOffset
Specifies the position offset in blocks or tapemarks. If dwPositionMethod specified TAPE_RELATIVE_BLOCKS, TAPE_SETMARKS, TAPE_SHORT_FILEMARKS, TAPE_LONG_FILEMARKS, or TAPE_SEQUENTIAL_FILEMARKS, a positive dwOffset value indicates forward direction, and a negative value indicates reverse direction.
lpdwOffsetHigh
Points to a variable that specifies the high 32 bits of the 64-bit offset. This parameter can be NULL if the offset can be specified by a 32-bit number.
When the function returns, the variable at lpdwOffset contains the high order 32-bits of the new tape block position.
If an error occurs, the function sets both the return value and the variable at lpdwOffsetHigh to 0xFFFFFFFF.
lpo
Points to an OVERLAPPED structure. The OVERLAPPED structure has the following form:
typedef struct _OVERLAPPED { /* o */
DWORD Internal;
DWORD InternalHigh;
DWORD Offset;
DWORD OffsetHigh;
HANDLE hEvent;
} OVERLAPPED;
typedef OVERLAPPED *LPOVERLAPPED;
If the function is successful, the return value is the low order 32-bits of the new tape block position.
If an error occurs, the return value is 0xFFFFFFFF. Use the GetLastError function to obtain extended error information.
If both dwOffset and lpdwOffsetHigh are used to provide a 64-bit offset, then an error is indicated only when both the return value and the variable at lpdwOffsetHigh are set to 0xFFFFFFFF.
If lpdwOffsetHigh is NULL, this function can operate only on tapes with fewer than 232-2 blocks.
GetTapePosition