HP OpenVMS Systems Documentation

The file SYS$EXAMPLES:CDROM_AUDIO.C contains an example of an application program that performs the following tasks:

• Defines standard symbolic names for the audio function codes representing SCSI audio commands.
• Defines representative AUCBs for each audio function code supported by the SCSI disk class driver.
• Issues a series of $QIO system service requests, each specifying the IO$_AUDIO function, that exercise the SCSI disk class driver to test its support for CD-ROM drives with audio capabilities.
• Converts LBA data returned by a GET_STATUS command in big-endian byte-ordering form to VAX little-ending byte-ordering form.

You can obtain information on all disk device characteristics by usingthe Get Device/Volume Information ($GETDVI) system service (refer tothe OpenVMS System Services Reference Manual).

$GETDVI returns disk characteristics when you specify the item codesDVI$_DEVCHAR and DVI$_DEVCHAR2. Table 2-4 lists the possiblecharacteristics for disk devices.

DVI$_DEVBUFSIZ returns the buffer size. The buffer size is the defaultto be used for disk transfers (this default is normally 512 bytes).DVI$_DEVTYPE and DVI$_DEVCLASS return the device type and class names,which are defined by the $DCDEF macro. The disk model determines thedevice type. For example, the device type for the RA81 is DT$_RA81.(Foreign device types take the form DT$_FD1 through DT$_FD8.) Thedevice class for disks is DC$_DISK.

DVI$_CYLINDERS returns the number of cylinders per volume (that is, perdisk), DVI$_TRACKS returns the number of tracks per cylinder, andDVI$_SECTORS returns the number of sectors per track. Values arereturned as 4-byte decimal numbers.

DVI$_MAXBLOCK returns the maximum number of blocks (1 block = 512bytes) that can be contained on the volume (that is, on the disk).Values are returned as 4-byte decimal numbers. This information can beused, for example, to determine the density of an RX02 diskette (singledensity = 494 blocks, double density = 988 blocks).

2.4 Disk Function Codes

Disk drivers can perform logical, virtual, and physical I/O functions.Foreign-mounted devices do not require privilege to perform logical andvirtual I/O requests.

Logical and physical I/O functions allow access to volume storage andrequire only that the issuing process have access to the volume.However, DSA disks and the disk class driver (DUDRIVER) do not acceptphysical QIO data transfers or seek operations.

Virtual I/O functions require an ACP for Files-11 On-Disk StructureLevel 1 files or an XQP for Files-11 On-Disk Structure Level 2 files.Virtual I/O functions must be executed in a prescribed order. First,you create and access a file, then you write information to that file,and lastly you deaccess the file. Subsequently, when you access thefile, you read the information and then deaccess the file. Delete thefile when the information is no longer useful.

Non-DSA disk devices can read or write up to 65,535 bytes in a singlerequest. DSA devices connected to an HSC50 can transfer up to 4 billionbytes in a single request. In all cases, the maximum size of thetransfer is limited by the number of pages that can be faulted into theprocess's working set, and then locked into physical memory. (The diskdriver is responsible for any memory management functions of thistype.) The size of the transfer does not affect the applicable quotas(direct I/O count, buffered I/O count, and asynchronous system trap(AST) count limit). These quotas refer to the number of outstanding I/Ooperations of each type, not the size of the I/O operation beingperformed.

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

Table 2-5 lists the logical, virtual, and physical disk I/Ofunctions and their function codes. Chapter 1 describes the QIOlevel interface to the disk device ACP.

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

• P1---The address of the file information block (FIB) descriptor.
• P2---The address of the file name string descriptor (optional). If specified, the name is entered in the directory specified by the FIB.
• P3---The address of the word that is to receive the length of the resulting file name string (optional).
• P4---The address of a descriptor for a buffer that is to receive the resulting file name string (optional).
• P5---The address of a list of attribute descriptors (optional). If specified, the indicated attributes are read (IO$_ACCESS) or written (IO$_CREATE, IO$_DEACCESS, and IO$_MODIFY).

See Chapter 1 for more information on these functions.

The function-dependent arguments for IO$_READVBLK, IO$_READLBLK,IO$_WRITEVBLK, and IO$_WRITELBLK are as follows:

• P1---The starting virtual address of the buffer that is to receive the data from a read operation; or, in the case of a write operation, the virtual address of the buffer that is to be written on the disk. On OpenVMS Alpha, P1 can be a 64-bit address.
• P2---The number of bytes that are to be read from the disk, or written from memory to the disk. An even number must be specified if the controller is an RK611, RL11, RX211, or UDA50.
• P3---The starting virtual/logical disk address of the data to be transferred in a read operation; or, in a write operation, the disk address of the area that is to receive the data.
  In a virtual read or write operation, the address is expressed as a block number within the file, that is, block 1 of the file is virtual block 1. (Virtual block numbers are converted to logical block numbers using mapping windows that are set up by the file system ACP process.)
  In a logical read or write operation, the address is expressed as a block number relative to the start of the disk. For example, the first sector on the disk contains block 0 (or at least the beginning of block 0).

The function-dependent arguments for IO$_WRITEVBLK, IO$_WRITELBLK, andIO$_WRITEPBLK functions that include the IO$M_ERASE function modifierare as follows:

• P1---The starting virtual address of the buffer that contains a 4-byte, user-specified erase pattern. If the P1 address is 0, a longword of 0 will be used for the erase pattern. If the P1 address is nonzero, the contents of the 4 bytes starting at that address will be used as the erase pattern. Compaq recommends that the user specify a P1 address of 0 to lower system overhead. On OpenVMS Alpha, P1 can be a 64-bit address.

  Note DSA disk controllers provide controlled, assisted erasing for theIO$M_ERASE modifier (with virtual and logical write functions) onlywhen the erase pattern is all zeros. If a nonzero erase pattern isused, there is a significant performance degradation with these disks.DSA disks do not accept physical QIO transfers.

• P2---The number of bytes of erase pattern to write to the disk. The number specified is rounded up to the next highest block boundary (512 bytes).
• P3---The starting virtual, logical, or physical disk address of the data to be erased.

The function-dependent arguments for IO$_WRITECHECK, IO$_READPBLK, andIO$_WRITEPBLK are as follows:

• P1---The starting virtual address of the buffer that is to receive the data in a read operation; or, in a write operation, the starting virtual address of the buffer that is to be written on the disk. Passed by reference. On OpenVMS Alpha, P1 can be a 64-bit address.
• P2---The number of bytes that are to be read from the disk, or written from memory to the disk. Passed by value. An even number must be specified if the controller is an RK611, RL11, or UDA50.
• P3---The starting physical disk address of the data to be read in a read operation; or, in a write operation, the starting physical address of the disk area that is to receive the data. Passed by value. The address is expressed as sector, track, and cylinder in the format shown in Figure 2-5. (On the RX01 and RX02, the high word specifies the track number rather than the cylinder number.) Check the UCB of a currently mounted device to determine the maximum physical address value for that type of device.

  Note On the RB80 and RM80, do not address cylinders 560 and 561. These twocylinders are used for diagnostic testing only.

The function-dependent argument for IO$_SEARCH is as follows:

P1---The physical disk address where the tape is positioned. The address is expressed as sector, track, and cylinder in the format shown in Figure 2-5.

Figure 2-5 Starting Physical Address

The function-dependent argument for IO$_SEEK is as follows:

P1---The physical cylinder number where the disk heads are positioned. The address is expressed in the format shown in Figure 2-6.

Figure 2-6 Physical Cylinder Number Format

The function-dependent argument for IO$_FORMAT is as follows:

P1---The density at which an RX02 diskette is reformatted (see Section 2.4.4).

The read function reads data into a specified buffer from disk startingat a specified disk address.

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, that function is converted to read logical block. If aread virtual block function is directed to a volume that is mountedstructured, the volume is handled in the same way as for afile-structured device.

Three function-dependent arguments are used with these codes: P1, P2,and P3. These arguments are described in Section 2.4.

The data check function modifier (IO$M_DATACHECK) can be used with allread functions.If this modifier is specified, a data check operation is performedafter the read operation completes. A data check operation is alsoperformed if the volume that has been read, or the volume on which thefile resides (virtual read) has the characteristic "data check allreads." Furthermore, a data check is performed after a virtualread if the file has the attribute "data check on read." TheRX01 and RX02 drivers do not support the data check function.

If IO$M_DATACHECK is specified with a read function code to a TU58, orifthe volume read has the characteristic "data check allreads," a read check operation is performed. This alters certainTU58 hardware parameters when the tape is read. (The read threshold inthe data recovery circuit is increased; if the tape has any weak spots,errors are detected.)

The data check function modifier to a disk or tape can return fiveerror codes in the I/O status block:

If no errors are detected, the disk or tape data is considered reliable.

The inhibit retry function modifier (IO$M_INHRETRY) can be used withall read functions.If this modifier is specified, all error recovery attempts areinhibited. IO$M_INHRETRY takes precedence over IO$M_DATACHECK. If bothare specified and an error occurs, there is no attempt at errorrecovery and no data check operation is performed. If an error does notoccur, the data check operation is performed.

2.4.2 Write

The write function writes data from a specified buffer to disk startingat a specified disk address.

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 write logical block. If awrite virtual block function is directed to a volume that is mountedstructured, the volume is handled in the same way as for afile-structured device.

Three function-dependent arguments are used with these codes: P1, P2,and P3. These arguments are described in Section 2.4.

The data check function modifier (IO$M_DATACHECK) can be used with allwrite operations.If this modifier is specified, a data check operation is performedafter the write operation completes. A data check operation is alsoperformed if the volume written, or the volume on which the fileresides (virtual write), has the characteristic "data check allwrites." Furthermore, a data check is performed after a virtualwrite if the file has the attribute "data check on write."The RX01 and RX02 drivers do not support the data check function.

If IO$M_DATACHECK is specified with a write function code to a TU58, orif thevolume written has the characteristic "data check allwrites," a write check operation is performed. The write checkverifies data written on the tape. First, the specified data is writtenon the tape. Then the tape is reversed and the TU58 controller readsthe data internally to perform a checksum verification. If the checksumverification is unsuccessful after eight attempts, the write checkoperation is aborted and an error status is returned.

The inhibit retry function modifier (IO$M_INHRETRY) can be used withall write functions.If that modifier is specified, all error recovery attempts areinhibited. IO$M_INHRETRY takes precedence over IO$M_DATACHECK. If bothIO$M_INHRETRY and IO$M_DATACHECK are specified and an error occurs,there is no attempt at error recovery, and no data check operation isperformed. If an error does not occur, the data check operation isperformed. IO$M_INHRETRY has no effect on DSA disks.

The write deleted data function modifier (IO$M_DELDATA) can be used withthe write physical block (IO$_WRITEPBLK) function to the RX02. If thismodifier is specified, a deleted data address mark instead of thestandard data address mark is written preceding the data. Otherwise,the operation of the IO$_WRITEPBLK function is the same; write data istransferred to the disk. When a successful read operation is performedon this data, the status code SS$_RDDELDATA is returned in the I/Ostatus block rather than the usual SS$_NORMAL status code.

The IO$M_ERASE function modifier can be used with all write functioncodes toerase a user-selected part of a disk. This modifier propagates an erasepattern through the specified range. Section 2.4 describes the writefunction arguments to be used with IO$M_ERASE.