User Guide

Ampex 1308911-02 5-55
libdd2 API Functions dst_setpos
dst_setpos() determines whether the tape drive is already positioned at the desired location
prior to issuing any positioning commands. If the data buffer contains write data, dst_setpos()
flushes the buffer to tape before setting the new position. Therefore, dst_setpos() can fail if
there is a problem flushing the buffer.
When the position specification is provided in structure form, you can specify a partial
position by indicating that only certain members of the structure are valid. dst_setpos()
applies defaults derived from the current position to any unspecified position elements.
• If only a file section number (fsn) is supplied in a DD-2 or DIS position structure, the
position is set to the beginning of the specified file in the current partition unless the
fsn
value is -1. An fsn value of -1 sets tape drive position to the end of data (EOD) location
in the current partition.
The
fsn member is not valid for a DST600 position structure. To set tape drive position
to EOD, specify -1 for the
cdbn member.
• If only a data block address (ldbn or timecode) is supplied in a DD-2 or DIS position
structure, tape drive position is set to the specified block in the current file unless the value
is -1. A data block address of -1 sets tape drive position to the end of the current file (EOF)
location.
RETURN VALUES
The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See “DST API Overview” on
page 5-1 for information on
errno failure messages and associated DST result codes.
1. If there is no tape cartridge in the drive, dst_setpos() returns -1 with
errno set to EIO
(5) and the DST result code set to DstCodeNoTapeInstalled.
2. If no tape is installed, dst_setpos() returns -1 with errno set to EIO (5) and the DST
result code set to
DstCodeNoTapeInstalled.
3. If the tape is installed but the Ready/Not Ready button on the front panel of the drive is
Not Ready, dst_setpos() returns -1 with
errno set to EIO (5) and the DST result code
set to
DstCodeNoEstablishedPos.
4. If the position specification is provided in token form, the volume ID of the current tape
is compared to the value in the token. If the values differ, dst_setpos() returns -1 with
errno set to EINVAL (22) and the DST result code set to DstCodeInvalidArg. If
the values are the same, the position token is converted into the relevant position structure
before being processed further.
5. If the desired tape position cannot be found (i.e., doesn’t exist on the current tape),
dst_setpos() returns -1 with
errno set to EIO (5) and the DST result code set to
DstCodeSetPosError. If the tape is unformatted, hence the reason for an unestablished
position,
errno is set to EIO (5) and the DST result code is set to
DstCodeUnknownFmt.