![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
| Updated: 11 December 1998 |
|
|
|
|
| Updated: 11 December 1998 |
OpenVMS I/O User's Reference Manual
| Previous | Contents | Index |
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:
The function-dependent argument for IO$_SKIPFILE and IO$_SKIPRECORD is:
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
|
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:
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 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:
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:
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 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.
3.4.5.1 Logical End-of-Volume (EOV) Detection
A skip file or skip record operation that uses the standard space-by-records algorithm is terminated when two consecutive tape marks are encountered when the tape moves in the forward direction. After the operation terminates, the tape remains positioned between the two tape marks that were detected. The I/O status block (IOSB) returns the status SS$_ENDOFVOLUME and the actual number of files (or records) skipped during the operation prior to the detection of the second tape mark. The skip count is returned in the high-order word of the first longword of the IOSB.
An optimized skip file that uses the IO$M_ALLOWFAST modifier is terminated when the end-of-data position is encountered. If two consecutive tape marks immediately precede the end-of-data position on the tape, the tape is positioned between these two tape marks. The SS$_ENDOFVOLUME status and the skip count are returned in the IOSB.
Subsequent skip record (or skip file) requests terminate immediately when the tape is positioned between the two tape marks, producing no net tape movement and returning the SS$_ENDOFVOLUME status with a skip count of zero.
To move the tape beyond the second tape mark, you must employ another I/O function. For example, the IO$_READLBLK function, if issued after receipt of the SS$_ENDOFVOLUME status return, terminates with an SS$_ENDOFFILE status and with the tape positioned just past the second tape mark. From this new position, other skip functions could be issued to produce forward tape motion (assuming there is additional data on the tape).
If three consecutive tape marks are encountered during a skip file
function, you must issue two IO$_READLBLK functions, the first to get
the SS$_ENDOFFILE return and the second to position the tape past the
third tape mark.
3.4.6 Write End-of-File
The write end-of-file (EOF) function writes an extended interrecord gap (of approximately 3 inches for non-return-to-zero-inverted (NRZI) recording and 1.5 inches for phase-encoded (PE) recording) followed by a tape mark. No device- or function-dependent arguments are used with IO$_WRITEOF.
An end-of-tape (EOT) status is returned in the I/O status block if either of the following conditions is present and no other error conditions occur:
The rewind offline function rewinds and unloads the tape on the selected drive.
The I/O operation is completed as soon as the tape movement is initiated. The actual finish of the mechanical rewind or unload operation may occur long after the I/O operation completes.
If the IO$M_RETENSION function modifier is specified and the device supports the retension operation, the rewind offline function positions the tape to the physical end-of-tape (EOT) marker and rewinds the tape to the beginning-of-tape (BOT) marker. If the tape does not support the IO$M_RETENSION modifer, a SS$_ILLIOFUNC error is returned.
No device- or function-dependent arguments are used with IO$_REWINDOFF.
3.4.8 Unload
The unload function rewinds and unloads the tape
on the selected drive. The unload function is functionally the same as
the rewind offline function. If the IO$M_NOWAIT function modifier is
specified, the I/O operation is completed as soon as the rewind
operation is initiated. No device- or function-dependent arguments are
used with IO$_UNLOAD.
3.4.9 Sense Tape Mode
The sense tape mode function senses the current device-dependent and extended device characteristics (see Tables 3-2 and 3-3).
The operating system provides the following function codes:
Sense mode requires logical I/O privilege. Sense characteristics requires physical I/O privilege. For TMSCP drives, the sense mode function returns magnetic tape information in a user-supplied buffer, which is specified by the following function-dependent arguments:
If P1 is not zero, the sense mode buffer returns the tape characteristics. (If P2=8, the second longword of the buffer contains the device-dependent characteristics. If P2=12, the second longword contains the device-dependent characteristics and the third longword contains the tape densities that the drive supports and the extended tape characteristics.) The extended characteristics are identical to the information returned by DVI$_DEVDEPEND2 (see Table 3-3). Figure 3-3 shows the contents of the P1 buffer.
Regardless of whether the P1 buffer is specified, the I/O status block returns the device-dependent characteristics in the second longword (see Figure 3-6). These characteristics are identical to the information returned by DVI$_DEVDEPEND (see Table 3-2 in Section 3.3).
Figure 3-3 Sense Mode P1 Buffer
Set mode operations affect the operation and characteristics of the associated magnetic tape device. The operating system defines two types of set mode functions: set mode and set characteristics.
Set mode requires logical I/O privilege. Set characteristics requires physical I/O privilege. The following function codes are provided:
These functions take the following device- or function-dependent arguments (other arguments are ignored):
Figure 3-4 shows the P1 characteristics buffer for IO$_SETMODE. Figure 3-5 shows the same buffer for IO$_SETCHAR.
Figure 3-4 Set Mode Characteristics Buffer for IO$_SETMODE
Figure 3-5 Set Mode Characteristics Buffer for IO$_SETCHAR
The first longword of the P1 buffer for the set characteristics function contains information on device class and type, and the buffer size. The device class for tapes is DC$_TAPE.
The $DCDEF macro defines the device type and class names. The buffer size is the default to be used for tape transfers (this default is normally 2048 bytes).
The second longword of the P1 buffer for both the set mode and set characteristics functions contains the tape characteristics. Table 3-5 lists the tape characteristics and their meanings. The $MTDEF macro defines the symbols listed. If P2=12, the third longword contains the extended tape characteristics for TMSCP drives, which are listed in Table 3-6. The extended tape characteristics are defined by the $MT2DEF macro and are identical to the information returned by DVI$_DEVDEPEND2.
| Characteristic1 | Meaning | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| MT$M_PARITY | If set, all data transfers are performed with even parity. If clear (normal case), all data transfers are performed with odd parity. Even parity can be selected only for non-return-to-zero-inverted recording at 800 bits/inch. Even parity cannot be selected for phase-encoded recording (tape density is MT$K_PE_1600) or group-coded recording (tape density is MT$K_GCR_6250) and is ignored. | ||||||||||
|
MT$V_DENSITY
MT$S_DENSITY |
Specifies the density at which all data transfers are performed. Tape
density can be set only when the selected drive's tape position is at
the BOT marker. Possible density values are as follows:
|
||||||||||
|
MT$V_FORMAT
MT$S_FORMAT |
Specifies the format in which all data transfers are performed.
Possible format values are as follows:
|
| Characteristic1 | Meaning |
|---|---|
| MT2$V_WBC_ENABLE | Enable write-back caching on a per-unit basis. |
| MT2$V_RDC_DISABLE | Disable read caching on a per-unit basis. |
Application programs that change specific magnetic tape characteristics should perform the following steps, as shown in Example 3-2 in Section 3.6:
Failure to follow this sequence will result in clearing any previously set characteristic.
| Previous | Next | Contents | Index |
|
|
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif) |
|
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
6136PRO_011.HTML
|