OpenVMS I/O User's Reference Manual

Document revision date: 30 March 2001

OpenVMS I/O User's Reference Manual

Contents

Index

3.4 Magnetic Tape Function Codes

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

Logical and physical I/O functions to magnetic tape devices allow sequential access to volume storage and require only that the requesting process have direct access to the device. The results of logical and physical I/O operations are unpredictable if an ACP is present.

Virtual I/O functions require intervention by an ACP and must be executed in a prescribed order. The normal order is to create and access a file, write information to that file, and deaccess the file. Subsequently, when you access the file, you read the information and then deaccess the file. You can write over the file when the information 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) can be read from or written into a single block by a single request. The number of bytes itself has no effect on the applicable quotas (direct I/O, buffered I/O, and AST). Reading or writing any number of bytes subtracts the same amount from a quota.

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

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

Table 3-4 Magnetic Tape I/O Functions
Function Code Arguments Type¹ Function Modifiers Function

IO$_ACCESS P1,[P2],[P3],[P4],[P5] V IO$M_CREATE
IO$M_ACCESS Search a tape for a specified file and access the file if found and IO$M_ACCESS is set. If the file is not found and IO$M_CREATE is set, create a file at end-of-tape (EOT) marker.

IO$_ACPCONTROL P1,[P2],[P3],[P4], [P5] V IO$M_DMOUNT Perform miscellaneous control functions. ²

IO$_AVAILABLE P Clear volume valid bit.

IO$_CREATE P1,[P2][,[P3],[P4],[P5] V IO$M_CREATE
IO$M_ACCESS Create a file.

IO$_DEACCESS P1,[P2],[P3],[P4],[P5] V Deaccess a file and, if the file has been written, write out trailer records.

IO$_DSE ³ P IO$M_NOWAIT Erase a prescribed section of the tape.

IO$_FLUSH L Flush the controller cache to tape.

IO$_MODIFY P1,[P2],[P3],[P4],[P5] V Write user labels.

IO$_PACKACK P Initialize volume valid bit.

IO$_READLBLK ¹⁰ P1,P2 L IO$M_DATACHECK ⁴
IO$M_INHRETRY
IO$M_REVERSE ⁵ Read logical block.

IO$_READPBLK ¹⁰ P1,P2 P IO$M_DATACHECK ⁴
IO$M_INHRETRY
IO$M_REVERSE ⁵ Read physical block.

IO$_READVBLK ¹⁰ P1,P2 V IO$M_DATACHECK ⁴
IO$M_INHRETRY
IO$M_REVERSE ⁵ Read virtual block.

IO$_REWIND L IO$M_INHRETRY
IO$M_NOWAIT
IO$M_RETENSION Reposition tape to the beginning-of-tape (BOT) marker.

IO$_REWINDOFF L IO$M_INHRETRY
IO$M_NOWAIT
IO$M_RETENSION Rewind and unload the tape on the selected drive.

IO$_SENSECHAR [P1],[P2] ⁶ P IO$M_INHRETRY Sense the tape characteristics and return them in the I/O status block.

IO$_SENSEMODE [P1],[P2] ⁶ L IO$M_INHRETRY Sense the tape characteristics and return them in the I/O status block.

IO$_SETCHAR P1,[P2] ⁶ P Set tape characteristics for subsequent operations.

IO$_SETMODE P1,[P2] ⁶ L Set tape characteristics for subsequent operations.

IO$_SKIPFILE P1 L IO$M_INHRETRY
IO$M_NOWAIT ⁷
IO$M_ALLOWFAST Skip past a specified number of tape marks in either a forward or reverse direction.

IO$_SKIPRECORD P1 L IO$M_INHRETRY
IO$M_NOWAIT ⁷ Skip past a specified number of blocks in either a forward or reverse direction.

IO$_UNLOAD L IO$M_INHRETRY
IO$M_NOWAIT Rewind and unload the tape on the selected drive.

IO$_WRITELBLK ¹⁰ P1,P2 L IO$M_ERASE ⁸
IO$M_DATACHECK ⁴
IO$M_INHRETRY
IO$M_INHEXTGAP ⁹
IO$M_NOWAIT ⁷ Write logical block.

IO$_WRITEOF ¹⁰ L IO$M_INHRETRY
IO$M_INHEXTGAP ⁹
IO$M_NOWAIT ⁷ Write an extended interrecord gap followed by a tape mark.

IO$_WRITEPBLK ¹⁰ P1,P2 P IO$M_ERASE ⁸
IO$M_DATACHECK ⁴
IO$M_INHRETRY
IO$M_INHEXTGAP ⁹
IO$M_NOWAIT ⁷ Write physical block.

IO$_WRITEVBLK ¹⁰ P1,P2 V IO$M_DATACHECK ⁴
IO$M_INHRETRY
IO$M_INHEXTGAP ⁹
IO$M_NOWAIT ⁷ Write virtual block.

**Table 3-4 Magnetic Tape I/O Functions**
Function Code	Arguments	Type¹	Function Modifiers	Function
IO$_ACCESS	P1,[P2],[P3],[P4],[P5]	V	IO$M_CREATE IO$M_ACCESS	Search a tape for a specified file and access the file if found and IO$M_ACCESS is set. If the file is not found and IO$M_CREATE is set, create a file at end-of-tape (EOT) marker.
IO$_ACPCONTROL	P1,[P2],[P3],[P4], [P5]	V	IO$M_DMOUNT	Perform miscellaneous control functions. ²
IO$_AVAILABLE		P		Clear volume valid bit.
IO$_CREATE	P1,[P2][,[P3],[P4],[P5]	V	IO$M_CREATE IO$M_ACCESS	Create a file.
IO$_DEACCESS	P1,[P2],[P3],[P4],[P5]	V		Deaccess a file and, if the file has been written, write out trailer records.
IO$_DSE ³		P	IO$M_NOWAIT	Erase a prescribed section of the tape.
IO$_FLUSH		L		Flush the controller cache to tape.
IO$_MODIFY	P1,[P2],[P3],[P4],[P5]	V		Write user labels.
IO$_PACKACK		P		Initialize volume valid bit.
IO$_READLBLK ¹⁰	P1,P2	L	IO$M_DATACHECK ⁴ IO$M_INHRETRY IO$M_REVERSE ⁵	Read logical block.
IO$_READPBLK ¹⁰	P1,P2	P	IO$M_DATACHECK ⁴ IO$M_INHRETRY IO$M_REVERSE ⁵	Read physical block.
IO$_READVBLK ¹⁰	P1,P2	V	IO$M_DATACHECK ⁴ IO$M_INHRETRY IO$M_REVERSE ⁵	Read virtual block.
IO$_REWIND		L	IO$M_INHRETRY IO$M_NOWAIT IO$M_RETENSION	Reposition tape to the beginning-of-tape (BOT) marker.
IO$_REWINDOFF		L	IO$M_INHRETRY IO$M_NOWAIT IO$M_RETENSION	Rewind and unload the tape on the selected drive.
IO$_SENSECHAR	[P1],[P2] ⁶	P	IO$M_INHRETRY	Sense the tape characteristics and return them in the I/O status block.
IO$_SENSEMODE	[P1],[P2] ⁶	L	IO$M_INHRETRY	Sense the tape characteristics and return them in the I/O status block.
IO$_SETCHAR	P1,[P2] ⁶	P		Set tape characteristics for subsequent operations.
IO$_SETMODE	P1,[P2] ⁶	L		Set tape characteristics for subsequent operations.
IO$_SKIPFILE	P1	L	IO$M_INHRETRY IO$M_NOWAIT ⁷ IO$M_ALLOWFAST	Skip past a specified number of tape marks in either a forward or reverse direction.
IO$_SKIPRECORD	P1	L	IO$M_INHRETRY IO$M_NOWAIT ⁷	Skip past a specified number of blocks in either a forward or reverse direction.
IO$_UNLOAD		L	IO$M_INHRETRY IO$M_NOWAIT	Rewind and unload the tape on the selected drive.
IO$_WRITELBLK ¹⁰	P1,P2	L	IO$M_ERASE ⁸ IO$M_DATACHECK ⁴ IO$M_INHRETRY IO$M_INHEXTGAP ⁹ IO$M_NOWAIT ⁷	Write logical block.
IO$_WRITEOF ¹⁰		L	IO$M_INHRETRY IO$M_INHEXTGAP ⁹ IO$M_NOWAIT ⁷	Write an extended interrecord gap followed by a tape mark.
IO$_WRITEPBLK ¹⁰	P1,P2	P	IO$M_ERASE ⁸ IO$M_DATACHECK ⁴ IO$M_INHRETRY IO$M_INHEXTGAP ⁹ IO$M_NOWAIT ⁷	Write physical block.
IO$_WRITEVBLK ¹⁰	P1,P2	V	IO$M_DATACHECK ⁴ IO$M_INHRETRY IO$M_INHEXTGAP ⁹ IO$M_NOWAIT ⁷	Write virtual block.

¹V = virtual; L = logical; P = physical.
²See Section 1.6.8 for more information.
³Only for TMSCP drives, and TZK50, and TZ30 tape devices.
⁴Not for TS04 and TU80 tape devices.
⁵Not for TUK50 and TQK50 tape devices.
⁶The P1 and P2 arguments for IO$_SENSEMODE and IO$_SENSECHAR and the P2 argument for IO$_SETMODE and IO$_SETCHAR are for TMSCP drives only.
⁷Only for RV20, TA90, TK70, and TU81-Plus drives.
⁸Takes no arguments; valid only for TMSCP drives, and TZK50 and TZ30 tape devices.
⁹Only for TE16, TU45, and TU77 tape drives.
¹⁰On OpenVMS Alpha, P1 supports a 64-bit address.

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 as follows:

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 in an IO$_SKIPRECORD QIO.

Example 3-1 Defining the P1 Parameter in a IO$_SKIPRECORD QIO

. . . TAPE_CHAN: .WORD 0 IOSB: .WORD 0 .WORD 0 .LONG 0 DEVICE: .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

3.4.1 Read

The read function reads data into a specified buffer in the forward or reverse 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 is mounted foreign, it is converted to a read logical block function. If a read virtual block function is directed to a volume that is mounted structured, the volume is handled the same way as a file-structured device.

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 direction instead of the forward direction. IO$M_REVERSE cannot be specified for the TUK50 and TQK50 devices.

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

For read physical block and read logical block functions, the drive returns the status SS$_NORMAL (not end-of-tape status) if either of the following 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 read operation in either the forward or reverse direction, any of the following 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 operation in the reverse direction when the tape is positioned at the beginning-of-tape (BOT) marker. All conditions that cause an EOF status result in a transferred byte count of zero.

If the drive attempts to read a block that is larger than the specified memory buffer during a logical or physical read operation, a data overrun status is returned. The buffer receives only the first part of the block. On a read in the reverse direction (on drives other than the TK50 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 of the block is at P1 plus P2 minus the length read. The TUK50 and TZ30 cannot actually perform read reverse operations; they must be simulated by the driver. Therefore, the data returned are those that would have been returned had the block been read in the forward direction.

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

3.4.2 Write

The write function writes data from a specified buffer to tape in the forward 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 is mounted foreign, the function is converted to a write logical block. If a write virtual block function is directed to a volume that is mounted structured, the volume is handled the same way as a file-structured device.

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 and IO$_WRITEPBLK function codes to erase a user-selected part of a tape. This modifier propagates an erase pattern of all zeros from the current tape position to 10 feet past the EOT position and then rewinds to the BOT marker.

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

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

If the drive performs a write physical block or a write logical block operation, an EOT status is returned if either of the following conditions 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. It is not possible to write a block less than 14 bytes in length. An attempt to do so results in the return of a bad parameter status for the 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 is completed when the rewind is initiated. Otherwise, I/O completion does not occur until the tape is positioned at the BOT marker.

If the IO$M_RETENSION function modifier is specified and the device supports the retension operation, the rewind function positions the tape to the physical-end-of-tape (EOT) marker and rewinds the tape to the BOT marker. If the tape does not support the IO$M_RETENSION modifer, 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 of tape marks in either a forward or reverse direction. A function-dependent argument (P1) is provided to specify the number of tape marks to be skipped, as shown in Figure 3-1. If a positive file count is specified, the tape moves forward; if a negative file count is specified, the tape moves in reverse. (The actual number of files skipped 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 BOT marker (when the tape moves in reverse) are counted during a skip file operation. The BOT marker terminates a skip file function in the reverse direction. The end-of-tape (EOT) marker does not terminate a skip file function in either the forward or reverse direction. A negative skip file function leaves the tape positioned just before a tape mark (at the end of a file) unless the BOT marker is encountered, whereas a positive skip file function leaves the tape positioned just past the tape mark.

A skip file function in the forward direction can also be terminated if two consecutive tape marks are encountered. Section 3.4.5.1 describes this feature.

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

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

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

3.4.5 Skip Record

The skip record function skips past a specified number of physical tape blocks in either a forward or reverse direction. A device- or function-dependent argument (P1) specifies the number of blocks to skip, as shown in Figure 3-2. If a positive block count is specified, the tape moves forward; if a negative block count is specified, the tape moves in reverse. The actual number of blocks skipped is returned as an unsigned number in the I/O status block. If a tape mark is detected, the count is the number of blocks skipped, plus 1 (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) marker when the tape moves in either direction, by the BOT marker when the tape moves in reverse, and by the EOT marker when the tape moves forward.

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

Contents

Index

privacy and legal statement

6136PRO_011.HTML