HP OpenVMS Systems Documentation

The magnetic tape driver can perform logical, virtual, and physical I/Ofunctions. Foreign-mounted devices do not require privileges to performlogical and virtual I/O requests.

Logical and physical I/O functions to magnetic tape devices allowsequential access to volume storage and require only that therequesting process have direct access to the device. The results oflogical and physical I/O operations are unpredictable if an ACP ispresent.

Virtual I/O functions require intervention by an ACP and must beexecuted in a prescribed order. The normal order is to create andaccess a file, write information to that file, and deaccess the file.Subsequently, when you access the file, you read the information andthen deaccess the file. You can write over the file when theinformation it contains is no longer useful and the file has expired.

Any number of bytes (from a minimum of 14 to a maximum of 65,535) canbe read from or written into a single block by a single request. Thenumber of bytes itself has no effect on the applicable quotas (directI/O,buffered I/O, and AST). Reading or writing any number of bytessubtracts the same amount from a quota.

The volume to which a logical or virtual function is directed must bemounted for the function actually to be executed. If it is not, eithera "device not mounted" or "invalid volume" statusis returned in the I/O status block.

Table 3-4 lists the logical, virtual, and physical magnetic tapeI/O functions and their function codes. These functions are describedin more detail in the following paragraphs. Chapter 1 describes theQIO level interface to the magnetic tape device ACP. Chapter 10describes features to improve performance for larger file transfers.

The function-dependent arguments for IO$_CREATE, IO$_ACCESS,IO$_DEACCESS, IO$_MODIFY, IO$_ACPCONTROL are as follows:

• P1---The address of the file information block (FIB) descriptor.
• P2---Optional. The address of the file name string descriptor. If specified with IO$_ACCESS, the name identifies the file being sought. If specified with IO$_CREATE, the name is the name of the created file.
• P3---Optional. The address of the word that is to receive the length of the resultant file name string.
• P4---Optional. The address of a descriptor for a buffer that is to receive the resultant file name string.
• P5---Optional. The address of a list of attribute descriptors. If specified with IO$_ACCESS, the attributes of the file are returned to the user. If specified with IO$_CREATE, P5 is the address of the attribute descriptor list for the new file. All file attributes for IO$_MODIFY are ignored.

See Chapter 1 for more information on these functions.

The function-dependent arguments for IO$_READVBLK, IO$_READLBLK,IO$_READPBLK, IO$_WRITEVBLK, IO$_WRITELBLK, and IO$_WRITEPBLK are asfollows:

• P1---The starting virtual address of the buffer that is to receive the data in the case of a read operation; or, in the case of a write operation, the virtual address of the buffer that is to be written on the tape. On OpenVMS Alpha, P1 can be a 64-bit address.
• P2---The length of the buffer specified by P1.

The function-dependent argument for IO$_SKIPFILE and IO$_SKIPRECORD is:

P1---The number of tape marks to skip over in the case of a skip file operation; or, in the case of a skip record operation, the number of blocks to skip over. If a positive number is specified, the tape moves forward; if a negative number is specified, the tape moves in reverse. (The maximum number of tape marks or records that P1 can specify is 32,767.)

Example 3-1 shows the correct method of defining the P1 parameter inan IO$_SKIPRECORD QIO.

   .   .   .TAPE_CHAN:        .WORD    0IOSB:   .WORD    0        .WORD    0        .LONG    0DEVICE: .ASCID   /$127$MUA0:/RECORD: .LONG    2000;        .PSECT   CODE,EXE,NOWRT;        .ENTRY   MT_IO,^M<>;        $ASSIGN_S    CHAN=TAPE_CHAN,-                 DEVNAM=DEVICE        BLBC     R0,EXIT_ERROR;        $QIOW_S  CHAN=TAPE_CHAN,-                 FUNC=#IO$_SKIPRECORD,-                 IOSB=IOSB,-                 P1=RECORD        BLBC     R0,EXIT_ERROR        $EXIT_S  R0   .   .   .EXIT_ERROR:        $EXIT_S  R0        .END     MT_IO

The read function reads data into a specified buffer in the forward orreverse direction starting at the next block position.

The operating system provides the following read function codes:

• IO$_READVBLK---Read virtual block
• IO$_READLBLK---Read logical block
• IO$_READPBLK---Read physical block

If a read virtual block function is directed to a volume that ismounted foreign, it is converted to a read logical block function. If aread virtual block function is directed to a volume that is mountedstructured, the volume is handled the same way as a file-structureddevice.

Two function-dependent arguments are used with these codes: P1 and P2.These arguments are described in Section 3.4.

If the read function code includes the reverse function modifier(IO$M_REVERSE), the drive reads the tape in the reverse directioninstead of the forward direction. IO$M_REVERSE cannot be specified forthe TUK50 and TQK50 devices.

The data check function modifier (IO$M_DATACHECK) can be used with allreadfunctions. If this modifier is specified, a data check operation isperformed after the read operation completes. (The drive performs aspace reverse or space forward between the read and data checkoperations.) A data check operation is also performed if the volumethat was read, or the volume on which the file resides (virtual read),has the characteristic data check all reads. Furthermore, a data checkis performed after a virtual read if the file has the attribute datacheck on read. The TS04 and TU80 tape drives do not support the datacheck function.

For read physical block and read logical block functions, the drivereturns the status SS$_NORMAL (not end-of-tape status) if either of thefollowing conditions occurs and no other error condition exists:

• The tape is positioned past the end-of-tape (EOT) position at the start of the read (forward or reverse) operation.
• The tape enters the EOT region as a result of the read (forward) operation.

The transferred byte count reflects the actual number of bytes read.

If the drive reads a tape mark during a logical or physical readoperation in either the forward or reverse direction, any of thefollowing conditions can return an end-of-file (EOF) status:

• The tape is positioned past the EOT position at the start of the read operation.
• The tape enters the EOT region as a result of the read operation.
• The drive reads a tape mark as a result of a read operation but the tape does not enter the EOT region.

An EOF status is also returned if the drive attempts a read operationin the reverse direction when the tape is positioned at thebeginning-of-tape (BOT) marker. All conditions that cause an EOF statusresult in a transferred byte count of zero.

If the drive attempts to read a block that is larger than the specifiedmemory buffer during a logical or physical read operation, a dataoverrun status is returned. The buffer receives only the first part ofthe block. On a read in the reverse direction (on drives other than theTK50 and TZ30) the buffer receives only the latter part of the block.The transferred byte count is equal to the actual size of the block.Read reverse starts at the top of the buffer. Therefore, the start ofthe block is at P1 plus P2 minus the length read. The TUK50 and TZ30cannot actually perform read reverse operations; they must be simulatedby the driver. Therefore, the data returned are those that would havebeen returned had the block been read in the forward direction.

It is not possible to read a block that is less than 14 bytes inlength. Records that contain less than 14 bytes are termed "noiseblocks" and are completely ignored by the driver.

3.4.2 Write

The write function writes data from a specified buffer to tape in theforward direction starting at the next block position.

The operating system provides the following write function codes:

• IO$_WRITEVBLK---Write virtual block
• IO$_WRITELBLK---Write logical block
• IO$_WRITEPBLK---Write physical block

If a write virtual block function is directed to a volume that ismounted foreign, the function is converted to a write logical block. Ifa write virtual block function is directed to a volume that is mountedstructured, the volume is handled the same way as a file-structureddevice.

Two function-dependent arguments are used with these codes: P1 and P2.These arguments are described in Section 3.4.

The IO$M_ERASE function modifier can be used with the IO$_WRITELBLK andIO$_WRITEPBLK function codes to erase a user-selected part of a tape.This modifier propagates an erase pattern of all zeros from the currenttape position to 10 feet past the EOT position and then rewinds to theBOT marker.

The data check function modifier (IO$M_DATACHECK) can be used with allwrite functions. If this modifier is specified, a data check operationis performed after the write operation completes. (The drive performs aspace reverse between the write and the data check operations.) Thedriver forces a data check operation when an error occurs during awrite operation. This ensures that the data can be reread. A data checkoperation is also performed if the volume written, or the volume onwhich the file resides (virtual write), has the characteristic"data check all writes." Furthermore, a data check isperformed after a virtual write if the file has the attribute"data check on write." The TS04 and TU80 tape drives do notsupport the data check function.

If the IO$M_NOWAIT function modifier is specified, write-back cachingis enabled on a per-command basis. IO$M_NOWAIT is applicable only toTU81-Plus drives.

If the drive performs a write physical block or a write logical blockoperation, an EOT status is returned if either of the followingconditions occurs and no other error condition exists:

• The tape is positioned past the EOT position at the start of the write operation.
• The tape enters the EOT region as a result of the write operation.

The transferred byte count reflects the size of the block written. Itis not possible to write a block less than 14 bytes in length. Anattempt to do so results in the return of a bad parameter status forthe QIO request.

3.4.3 Rewind

The rewind function repositions the tape to the beginning-of-tape (BOT)marker.

If the IO$M_NOWAIT function modifier is specified, the I/O operation iscompleted when the rewind is initiated. Otherwise, I/O completion doesnot occur until the tape is positioned at the BOT marker.

If the IO$M_RETENSION function modifier is specified and the devicesupports the retension operation, the rewind function positions thetape to the physical-end-of-tape (EOT) marker and rewinds the tape tothe BOT marker. If the tape does not support the IO$M_RETENSIONmodifer, a SS$_ILLIOFUNC error is returned.

IO$_REWIND has no function-dependent arguments.

3.4.4 Skip File

The skip file function (IO$_SKIPFILE) skips past a specified number oftape marks in either a forward or reverse direction. Afunction-dependent argument (P1) is provided to specify the number oftape marks to be skipped, as shown in Figure 3-1. If a positive filecount is specified, the tape moves forward; if a negative file count isspecified, the tape moves in reverse. (The actual number of filesskipped is returned as an unsigned number in the I/O status block.)

Figure 3-1 IO$_SKIPFILE Argument

Only tape marks (when the tape moves in either direction) and the BOTmarker (when the tape moves in reverse) are counted during a skip fileoperation. The BOT marker terminates a skip file function in thereverse direction.The end-of-tape (EOT) marker does not terminate a skip file function ineither the forward or reverse direction. A negative skip file functionleaves the tape positioned just before a tape mark (at the end of afile) unless the BOT marker is encountered, whereas a positive skipfile function leaves the tape positioned just past the tape mark.

A skip file function in the forward direction can also be terminated iftwo consecutive tape marks are encountered. Section 3.4.5.1 describesthis feature.

The IO$M_ALLOWFAST modifier can be used with the IO$_SKIPFILE functionto provide better performance on SCSI tape drives that support the SCSIspace-by-file-marks command and the SCSI read position command.

When the IO$M_ALLOWFAST modifier is specified, a tape operation skipsover consecutive tape marks that are not immediately before theend-of-data position on the medium. However, if two consecutive tapemarks are detected immediately before the end-of-data position on thetape, the tape is positioned between these two tape marks and theSS$_ENDOFVOLUME status is returned.

The IO$M_ALLOWFAST modifier allows a SCSI tape subsystem to use theoptimized IO$_SKIPFILE if it is capabable. If a specific tape devicedoes not adequately support the optimized IO$_SKIPFILE that uses theSCSI space-by-file-marks command, the tape subsystem will use thestandard space-by-records algorithm.

3.4.5 Skip Record

The skip record function skips past a specified number of physical tapeblocks in either a forward or reverse direction. A device- orfunction-dependent argument (P1) specifies the number of blocks toskip, as shown in Figure 3-2. If a positive block count isspecified, the tape moves forward; if a negative block count isspecified, the tape moves in reverse. The actual number of blocksskipped is returned as an unsigned number in the I/O status block. If atape mark is detected, the count is the number of blocks skipped, plus1 (forward tape motion) or minus 1 (reverse tape motion).

Figure 3-2 IO$_SKIPRECORD Argument

A skip record operation is terminated by the end-of-file (EOF) markerwhen the tape moves in either direction, by the BOT marker when thetape moves in reverse, and by the EOT marker when the tape movesforward.

A skip record function in the forward direction can also be terminatedif the tape was originally positioned between two tape marks.Section 3.4.5.1 describes this feature.