OpenVMS I/O User's Reference Manual

Updated: 24 May 2001

Order Number: AA--PV6SC--TK

January 1999

This manual contains the information necessary to interface directly with the I/O device drivers supplied as part of the OpenVMS operating system. Several examples of programming techniques are included. This document does not contain information on I/O operations using the OpenVMS Record Management Services.

Revision/Update Information: This manual supersedes the OpenVMS I/O User's Reference Manual, OpenVMS Alpha Version 7.1, OpenVMS VAX Version 7.1

Software Version: OpenVMS Alpha Version 7.2 OpenVMS VAX Version 7.2

Compaq Computer Corporation
Houston, Texas

January 1999

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Compaq Computer Corporation: Alpha, AlphaServer, Compaq, DECnet, DELUA, DEQNA, DEUNA, DIGITAL, FDDI, HSC40, HSC50, HSC70, KDA, LAT, MicroVAX, OpenVMS, PATHWORKS, RA, RC25, RK, RL, RM, RP, RQDX3, RRD50, RV20, RX01, RX02, RX23, RX33, RX50, RZ, TA, TK, TM03, TM78, TS11, TU, TURBOchannel, UDA, UNIBUS, VAX, VAX DOCUMENT, VAXcluster, VAXstation, VMS, and the Compaq logo.

The following are third-party trademarks:

IEEE is a registered trademark of The Institute of Electrical and Electronics Engineers, Inc.

All other trademarks and registered trademarks are the property of their respective holders.

ZK6136

The OpenVMS documentation set is available on CD-ROM.

Contents Index

Preface

Intended Audience

This manual is intended for system programmers who want to take advantage of the time and space savings that result from direct use of I/O drivers. OpenVMS users who do not require such detailed knowledge of I/O drivers can use the device-independent services described in the OpenVMS Record Management Services Reference Manual.

Document Structure

This manual is organized into the following chapters and appendixes:

Chapter 1 describes the Queue I/O (QIO) interface to file system ancillary control processes (ACPs).
Chapters 2 through 9 describe the use of file-structured and real-time I/O device drivers, the drivers for storage devices such as disks and magnetic tapes, and supported terminal devices:
- Chapter 2 discusses the disk drivers.
- Chapter 3 discusses the magnetic tape drivers.
- Chapter 4 discusses the mailbox driver.
- Chapter 5 discusses the terminal driver.
- Chapter 6 discusses the pseudoterminal driver.
- Chapter 7 discusses the shadow-set virtual unit driver.
- Chapter 8 discusses the Generic Small Computer System Interface (SCSI) class driver.
- Chapter 9 discusses the local area network (LAN) device drivers.
Chapter 10 describes optional features to improve OpenVMS Alpha I/O performance.
Appendix A summarizes the QIO function codes, arguments, and function modifiers used by the drivers listed previously.
Appendix B describes the enhanced IO$_DIAGNOSE function for SCSI class drivers.
Appendix C lists the DEC Multinational character set and the ANSI and DIGITAL private escape sequences for terminals.
Appendix D describes the calling conventions for the pseudoterminal driver's control connection routines.

Chatpers 3, 9, and 10 and Appendix A include updated information for OpenVMS Version 7.2 and Appendix B is a new appendix.

Device Driver Support for OpenVMS Alpha 64-Bit Addressing

The OpenVMS Alpha operating system provides support for 64-bit virtual memory addressing, which makes the 64-bit virtual address space defined by the Alpha architecture available to the OpenVMS Alpha operating system and to application programs. In the 64-bit virtual address space, both process-private and system virtual address space extend beyond 2 GB. By using 64-bit addressing features, programmers can create images that map and access data beyond the limits of 32-bit virtual addresses.

Input and output operations can be performed directly to and from the 64-bit addressable space by means of RMS services, the $QIO system service, and most of the device drivers supplied with OpenVMS Alpha systems. A device driver declares support for 64-bit addresses individually by I/O function code. Disk and tape device drivers support 64-bit addresses for data transfers to and from disk and tape devices on the virtual, logical, and physical read and write functions. For example, the OpenVMS SCSI disk class driver, SYS$DKDRIVER, supports 64-bit addresses on the IO$_READVBLK and IO$_WRITEVBLK functions, but not on the IO$_AUDIO function. The device drivers, function codes, and $QIO arguments that support 64-bit addressing are indicated in the appropriate chapters of this manual.

For more information about the OpenVMS Alpha device drivers that support 64-bit addressing, see the OpenVMS Alpha Guide to 64-Bit Addressing and VLM Features. To find out how to modify a customer-written device driver to support 64-bit addressing, see the OpenVMS Alpha Guide to Upgrading Privileged-Code Applications.

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08

Mail Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.digital.com:81/

If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Clusters or clusters in this document are synonymous with VMSclusters.

In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.

The following conventions are also used in this manual:

Ctrl/ x A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.

PF1 x A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.

[Return] In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as brackets, rather than a box.

... A horizontal ellipsis in examples indicate one of the following possibilities:

Additional optional arguments in a statement have been omitted.
The preceding item or items can be repeated one or more times.
Additional parameters, values, or other information can be entered.

.
.
. A vertical ellipsis indicate the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

( ) In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.

[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)

[|] In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.

{ } In command format descriptions, braces indicate required elements; you must choose one of the options listed.

bold text This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.

italic text Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace text Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Chapter 1
ACP--QIO Interface

An ancillary control process (ACP) is a process that interfaces between the user process and the driver, and performs functions that supplement the driver's functions. Virtual I/O operations involving file-structured devices (disks and magnetic tapes) often require ACP intervention. In most cases, ACP intervention is requested by OpenVMS Record Management Services (RMS) and is transparent to the user process. However, user processes can request ACP functions directly by issuing a Queue I/O (QIO) request and specifying an ACP function code, as shown in Figure 1-1.

Executing physical and logical input/output (I/O) operations on a device that is managed by a file ACP interferes with the operation of the ACP, and can result in such unpredictable consequences as system failure.

In addition to the ACP, the XQP (extended QIO processor) facility supplements the QIO driver's functions when performing virtual I/O operations on file-structured devices. However, rather than being a separate process, the XQP executes as a kernel-mode thread in the process of its caller.

An XQP is provided to support Files-11 ODS-2 (On-Disk Structure Level 2) disks as the base file system, and an ACP is provided for ANSI standard X3.27 magnetic tapes.

On VAX systems, an ACP is provided for supporting Files-11 ODS-1 (On-Disk Structure Level 1) disks.

There are also ACPs to support the ISO 9660 CD-ROM disk structure (Files-11 C) and High Sierra CD-ROM disk structure (Files-11 D). Collectively, these ACPs are called Files-11 C/D.

Note

On Alpha systems using OpenVMS Version 7.2, there is support for ODS-5 (On-Disk Structure Level 5) disks. For more information about ODS-5 support, refer to the OpenVMS Guide to Extended File Specifications.

This chapter describes the QIO interface to ACPs for disk and magnetic tape devices (file system ACPs). The sample program in Chapter 3 performs QIO operations to the magnetic tape ACP.

Figure 1-1 ACP--QIO Interface

This section also describes a number of structures and field names of the form xxx$name. A MACRO program can define symbols of this form by invoking the $xxxDEF macro.

The following macros are available in SYS$LIBRARY:STARLET.MLB:

$IODEF
$FIBDEF
$ATRDEF
$SBKDEF

The following macros are available in SYS$LIBRARY:LIB.MLB:

$FATDEF
$DQFDEF
$FCHDEF

Programs written in BLISS-32 can use these symbols by referencing them and including the correct library, SYS$LIBRARY:STARLET.L32 (for the macros listed under SYS$LIBRARY:STARLET.MLB), and SYS$LIBRARY:LIB.L32 (for the macros listed under SYS$LIBRARY:LIB.MLB).

References to ANSI refer to the American National Standard Magnetic Tape Labels and File Structures for Information Interchange, ANSI X3.27--1978.

1.1 ACP Functions and Encoding

ACP functions can be expressed using seven function codes and four function modifiers. The function codes are:

IO$_CREATE---Creates a directory entry or file
IO$_ACCESS---Searches a directory for a specified file and accesses the file, if found
IO$_DEACCESS---Deaccesses a file and, if specified, writes the final attributes in the file header
IO$_MODIFY---Modifies the file attributes and file allocation
IO$_DELETE---Deletes a directory entry and file header
IO$_MOUNT---Informs the ACP when a volume is mounted; requires MOUNT privilege
IO$_ACPCONTROL---Performs miscellaneous control functions

The function modifiers are:

IO$M_ACCESS---Opens a file on the user's channel
IO$M_CREATE---Creates a file
IO$M_DELETE---Deletes a file or marks it for deletion
IO$M_DMOUNT---Dismounts a volume

In addition to the function codes and modifiers, ACPs take five device- or function-dependent arguments, as shown in Figure 1-2. The first argument, P1, is the address of the file information block (FIB) descriptor. Section 1.2 describes the FIB in detail.

The second argument, P2, is an optional argument used in directory operations. It specifies the address of the descriptor for the file name string to be entered in the directory.

Argument P3 is the address of a word to receive the resultant file name string length. The resultant string is not padded. The actual length is returned in P3. Argument P4 is the address of a descriptor for a buffer to receive the resultant file name string. Both of these arguments are optional.

Figure 1-2 ACP Device- or Function-Dependent Arguments

The fifth argument, P5, is an optional argument containing the address of the attribute control block. Section 1.3.5 describes the attribute control block in detail.

All areas of memory specified by the descriptors must be capable of being read or written to.

Figure 1-3 shows the format for the descriptors. The count field is the length in bytes of the item described.

Figure 1-3 ACP Device/Function Argument Descriptor Format

1.2 File Information Block (FIB)

The file information block (FIB) contains much of the information that is exchanged between the user process and the ACP. Figure 1-4 shows the format of the FIB. The FIB must be writable. Because the FIB is passed by a descriptor (see Figure 1-3), its length can vary. Thus, a short FIB can be used in ACP calls that do not need arguments near the end of the FIB. The ACP treats the omitted portion of the FIB as if it were 0. Figure 1-5 shows the format of a typical short FIB that would be used to open an existing file. Table 1-1 gives a brief description of each of the FIB fields. More detailed descriptions are provided in Sections 1.3 and 1.6.

Figure 1-4 FIB Format

Figure 1-5 Typical Short FIB

Table 1-1 Contents of the FIB
Field Subfields Meaning

FIB$L_ACCTL Contains flag bits that control the access to the file. Sections 1.3.1.1, 1.3.2.1, 1.6.1.1, 1.6.4.1, and 1.6.5 describe the FIB$L_ACCTL field flag bits.

FIB$B_WSIZE Controls the size of the file window used to map a disk file. If a window size of 255 is specified, the file is completely mapped by using segmented windows.

FIB$W_FID Specifies the file identification. You supply the file identifier when it is known; the ACP returns the file identifier when it becomes known; for example, as a result of a create or directory lookup. A 0 file identifier can be specified when an operation is performed on a file that is already open on a particular channel. The ACP returns the file identifier of the open file.
For Files-11 On-Disk Structure Level 1 and Level 2, the following subfields are defined:

FIB$W_FID_NUM File number.

FIB$W_FID_SEQ File sequence number.

FIB$W_FID_RVN Relative volume number (only for magnetic tape devices).

FIB$B_FID_RVN Relative volume number (only for disk devices).

FIB$B_FID_NMX File number extension (only for disk devices).

FIB$W_DID Contains the file identifier of the directory file.
For Files-11 On-Disk Structure Level 1 and Level 2, the following subfields are defined:

FIB$W_DID_NUM File number.

FIB$W_DID_SEQ File sequence number.

FIB$W_DID_RVN Relative volume number (only for magnetic tape devices).

FIB$B_DID_RVN Relative volume number (only for disk devices).

FIB$B_DID_NMX File number extension (only for disk devices).

FIB$L_WCC Maintains position context when processing wildcard directory operations.

FIB$W_NMCTL Contains flag bits that control the processing of a name string in a directory operation. Sections 1.3.1.1 and 1.6.1.1 describe the FIB$W_NMCTL field flag bits.

FIB$W_EXCTL Contains flag bits that specify extend control for disk devices. Sections 1.3.3.1 and 1.3.4.1 describe the FIB$W_EXCTL field flag bits.

FIB$W_CNTRLFUNC In an IO$_ACPCONTROL function, this field contains the code that specifies which ACP control function is to be performed (see Section 1.6.8). This field overlays FIB$W_EXCTL.

FIB$L_EXSZ Specifies the number of blocks to be allocated in an extend operation on a disk file.

FIB$L_CNTRLVAL Contains a control function value used in an IO$_ACPCONTROL function (see Section 1.6.8). The interpretation of the value depends on the control function specified in FIB$W_CNTRLFUNC. This field overlays FIB$L_EXSZ.

FIB$L_EXVBN Specifies the starting disk file virtual block number at which a file is to be truncated.

FIB$B_ALOPTS Contains option bits that control the placement of allocated blocks. Section 1.3.3.1 describes the FIB$B_ALOPTS field flag bits.

FIB$B_ALALIGN Contains the interpretation mode of the allocation (FIB$W_ALLOC) field.

FIB$W_ALLOC Contains the desired physical location of the blocks being allocated. Interpretation of the field is controlled by the FIB$B_ALALIGN field. The following subfields are defined:

FIB$W_LOC_FID Three-word related file ID for RFI placement.

FIB$W_LOC_NUM Related file number.

FIB$W_LOC_SEQ Related file sequence number.

FIB$B_LOC_RVN Related file relative volume number (RVN) or placement RVN.

FIB$B_LOC_NMX Related file number extension.

FIB$L_LOC_ADDR Placement logical block number (LBN), cylinder, or virtual block number (VBN).

FIB$W_VERLIMIT Contains the version limit of the directory entry.

FIB$L_ACLCTX Maintains position context when processing ACL attributes from the attribute (P5) list.

FIB$L_ACL_STATUS Status of the requested ACL attribute operation, if any. The ACL attributes are included in Table 1-7. If no ACL attributes are given, SS$_NORMAL is returned here.

FIB$L_STATUS Access status. Applies to all major functions. The following bits are supported:

FIB$V_ALT_REQ Set to indicate whether the alternate access bit is required for the current operation. If not set, the alternate access bit is optional.

FIB$V_ALT_GRANTED If FIB$V_ALT_REQ = 0, the FIB bit returned from the file system is set if the alternate access check succeeded.

FIB$L_ALT_ACCESS A 32-bit mask that represents an access mask to check against file protection; for example, opens a file for read access and checks whether it can be deleted. The mask has the same configuration as the standard protection mask.