HP OpenVMS Systems Documentation

OpenVMS I/O User's Reference Manual

Order Number: AA--PV6SD--TK

April 2001

This manual contains the information necessary to interface directlywith the I/O device drivers supplied as part of the Compaq OpenVMSoperating system. Several examples of programming techniques areincluded. This document does not contain information on I/O operationsusing the OpenVMS Record Management Services.

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

Software Version:OpenVMS Alpha Version 7.3 OpenVMS VAX Version 7.3

Compaq Computer Corporation
Houston, Texas

Compaq, VAX, VMS, and the Compaq logo Registered in U.S. Patent andTrademark Office.

OpenVMS and Tru64 are trademarks of Compaq Information TechnologiesGroup, L.P in the United States and other countries.

Microsoft, MS-DOS, Visual C++, Windows, and Windows NT are trademarksof Microsoft Corporation in the United States and other countries.

Intel, Intel Inside, and Pentium are trademarks of Intel Corporation inthe United States and other countries.

Motif, OSF/1, and UNIX are trademarks of The Open Group in the UnitedStates and other countries.

All other product names mentioned herein may be trademarks of theirrespective companies.

Confidential computer software. Valid license from Compaq required forpossession, use, or copying. Consistent with FAR 12.211 and 12.212,Commercial Computer Software, Computer Software Documentation, andTechnical Data for Commercial Items are licensed to the U.S. Governmentunder vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors oromissions contained herein. The information in this document isprovided "as is" without warranty of any kind and is subject to changewithout notice. The warranties for Compaq products are set forth in theexpress limited warranty statements accompanying such products. Nothingherein should be construed as constituting an additional warranty.

ZK6136

The Compaq OpenVMS documentation set is available on CD-ROM.

Contents

Index

Preface

Intended Audience

This manual is intended for system programmers who want to takeadvantage of the time and space savings that result from direct use ofI/O drivers. OpenVMS users who do not require such detailed knowledgeof I/O drivers can use the device-independent services described in theOpenVMS 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.

Device Driver Support for OpenVMS Alpha 64-BitAddressing

The OpenVMS Alpha operating system provides support for 64-bit virtualmemory addressing, which makes the 64-bit virtual address space definedby the Alpha architecture available to the OpenVMS Alpha operatingsystem and to application programs. In the 64-bit virtual addressspace, both process-private and system virtual address space extendbeyond 2 GB. By using 64-bit addressing features, programmers cancreate images that map and access data beyond the limits of 32-bitvirtual addresses.

Input and output operations can be performed directly to and from the64-bit addressable space by means of RMS services, the $QIO systemservice, and most of the device drivers supplied with OpenVMS Alphasystems. A device driver declares support for 64-bit addressesindividually by I/O function code. Disk and tape device drivers support64-bit addresses for data transfers to and from disk and tape deviceson the virtual, logical, and physical read and write functions. Forexample, the OpenVMS SCSI disk class driver, SYS$DKDRIVER, supports64-bit addresses on the IO$_READVBLK and IO$_WRITEVBLK functions, butnot on the IO$_AUDIO function. The device drivers, function codes, and$QIO arguments that support 64-bit addressing are indicated in theappropriate chapters of this manual.

For more information about the OpenVMS Alpha device drivers thatsupport 64-bit addressing, refer to the OpenVMS Programming Concepts Manual. To find out howto modify a customer-written device driver to support 64-bitaddressing, see the OpenVMS Alpha Guide to Upgrading Privileged-Code Applications.

Reader's Comments

Compaq welcomes your comments on this manual. Please send comments toeither of the following addresses:

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

How To Order Additional Documentation

Visit the following World Wide Web address for information about how toorder additional documentation:

http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs,call 800-282-6672.

Conventions

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

In this manual, every use of DECwindows and DECwindows Motif refers toDECwindows 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 thatinterfaces between the user process and the driver, and performsfunctions that supplement the driver's functions. Virtual I/Ooperations involving file-structured devices (disks and magnetic tapes)often require ACP intervention. In most cases, ACP intervention isrequested by OpenVMS Record Management Services (RMS) and istransparent to the user process. However, user processes can requestACP functions directly by issuing a Queue I/O (QIO) request andspecifying 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 Level2) disks as the base file system, and an ACP is provided for ANSIstandard 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-5support, refer to the OpenVMS Guide to Extended File Specifications.

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

Figure 1-1 ACP--QIO Interface

This section also describes a number of structures and field names oftheform xxx$name. A MACRO program can define symbols of this formby 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 fourfunction 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 directoryoperations. It specifies the address of the descriptor for the filename 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 addressof the attribute control block. Section 1.3.5 describes the attributecontrol 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 isthe length in bytes of the item described.

Figure 1-3 ACP Device/Function Argument DescriptorFormat

1.2 File Information Block (FIB)

The file information block (FIB) contains much of the information thatis exchanged between the user process and the ACP. Figure 1-4 showsthe format of the FIB. The FIB must be writable. Because the FIB ispassed by a descriptor (see Figure 1-3), its length can vary. Thus, ashort FIB can be used in ACP calls that do not need arguments near theend of the FIB. The ACP treats the omitted portion of the FIB as if itwere 0. Figure 1-5 shows the format of a typical short FIB that wouldbe used to open an existing file. Table 1-1 gives a briefdescription of each of the FIB fields. More detailed descriptions areprovided 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.