HP OpenVMS Systems Documentation
OpenVMS I/O User's Reference Manual
Order Number: AA--PV6SD--TK
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
© 2001 Compaq Computer Corporation
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.
The Compaq OpenVMS documentation set is available on CD-ROM.
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.
This manual is organized into the following chapters and appendixes:
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.
The following manuals provide additional information that relates tothe topics covered in this book:
For additional information about the Compaq OpenVMS productsand services, access the Compaq website at the following location:
Compaq welcomes your comments on this manual. Please send comments toeither of the following addresses:
How To Order Additional Documentation
Visit the following World Wide Web address for information about how toorder additional documentation:
If you need help deciding which documentation best meets your needs,call 800-282-6672.
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:
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
The following macros are available in SYS$LIBRARY:STARLET.MLB:
The following macros are available in SYS$LIBRARY:LIB.MLB:
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
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
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
|FIB$L_ACCTL||Contains flag bits that control the access to the file. Sections 22.214.171.124, 126.96.36.199, 188.8.131.52, 184.108.40.206, 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_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_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 220.127.116.11 and 18.104.22.168 describe the FIB$W_NMCTL field flag bits.|
|FIB$W_EXCTL||Contains flag bits that specify extend control for disk devices. Sections 22.214.171.124 and 126.96.36.199 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 188.8.131.52 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.|