HP OpenVMS Systems Documentation
OpenVMS I/O User's Reference Manual
1.3 ACP Subfunctions
The operations that the ACP performs can be organized into twocategories: major ACP functions and subfunctions. Each ACP operationperforms one major function. That function is specified by an I/Ofunction code, such as IO$_ACCESS, IO$_CREATE, or IO$_MODIFY. Whileexecuting the major function, one or more subfunctions can beperformed. A subfunction is an operation such as looking up, accessing,or extending a file. Most subfunctions can be executed by more than oneof the major functions. Sections 1.3.1 through 1.3.5describe the following subfunctions in detail:
The directory lookup subfunction is used to search for a file in a diskdirectory or on a magnetic tape. This subfunction can be invoked usingthe major functions IO$_ACCESS, IO$_MODIFY, IO$_DELETE, andIO$_ACPCONTROL. A directory lookup occurs if thedirectory file ID field in the FIB (FIB$W_DID) is a nonzero number.
Table 1-2 lists the FIB fields that control the processing of alookup subfunction.
QIO arguments P2 through P6 (see Figure 1-2) are passed as values. The second argument, P2, specifies the address of the descriptor for the file name string to be searched for in the directory.
The file name string must have one of the following two formats:
The name and type can be any combination of alphanumeric characters, and the dollar sign ($), asterisk (*), and percent (%) characters. The version must consist of numeric characters optionally preceded by a minus sign (--) (only for disk devices) or a single asterisk. The total number of alphanumeric and percent characters in the name field and in the type field must not exceed 39. Any number of additional asterisks can be present.
If any of the bits FIB$V_ALLNAM, FIB$V_ALLTYP, and FIB$V_ALLVER are set, then the contents of the corresponding field in the name string are ignored and the contents are assumed to be an asterisk.
Note that the file name string cannot contain a directory string. The directory is specified by the FIB$W_DID field (see Table 1-1). Only RMS can process directory strings.
Argument P3 is the address of a word to receive the resultant file name string length. Argument P4 is the address of a descriptor for a buffer to receive the resultant file name string. The resultant string is not padded. The P3 and P4 arguments are optional.
The system searches either the directory file specified by FIB$W_DID or the magnetic tape for the file name specified in the P2 file name parameter. The actual file name found and its length are returned in the P3 and P4 length and result string buffers. The file ID of the file found is returned in FIB$W_FID and can be used in subsequent operations as the major function is processed.
Zero and negative version numbers have special significance in a disk lookup operation. Specifying 0 as a version number causes the latest version of the file to be found. Specifying --1 locates the second most recent version, --2 the third most recent, and so forth. Specifying a version of --0 locates the lowest numbered version of the file. For magnetic tape lookups, a version number of 0 locates the first occurrence of the file encountered; negative version numbers are not allowed.
Wildcard lookups are performed by specifying the appropriate wildcard characters in the name string and setting FIB$V_WILD. (The name control bits FIB$V_ALLNAM, FIB$V_ALLTYP, and FIB$V_ALLVER can also be used in searching for wildcard entries, but they are intended primarily for compatibility mode use.) On the first lookup, FIB$L_WCC should contain zero entries. On each lookup, the ACP returns a nonzero value in FIB$L_WCC, which must be passed back on the next lookup call. In addition, you must pass the resultant name string returned by the previous lookup using the P4 result string buffer, and its length in the P3 result length word. This string is used together with FIB$L_WCC to continue the wildcard search at the correct position in the directory.
Perform a lookup by file ID by setting the name control bit FIB$V_FINDFID. When this bit is set, the system searches the directory for an entry containing the file ID specified in FIB$W_FID, and the name of the entry found is returned in the P3 and P4 result parameters. Note that if a directory contains multiple entries with the same file ID, only the first entry can be located with this technique.
Lookups by file ID should be done only when the file name is not available, because lookups by this method are often significantly slower than lookups by file name.
A directory entry is protected with the same protection code as thefile itself. For example, if a directory file is protected againstdelete access, then the file name has the same protection.Consequently, a nonprivileged user cannot rename a file becauserenaming a file is essentially the same as deleting the file name. Thisprotection is applied regardless of the protection on the directoryfile.
Nonprivileged users can neither write directly into a .DIR;1 directory file nor turn off the directory bit in a directory file header.
The access subfunction is used to open a file so that virtual read orwrite operations can be performed. This subfunction can be invokedusing the major functions IO$_CREATE and IO$_ACCESS (see Sections1.6.1 and 1.6.2). An access subfunction is performed ifthe IO$M_ACCESS modifier is specifiedin the I/O function code.
Table 1-3 lists the FIB fields that control the processing of anaccess subfunction.
The extend subfunction is used to allocate space to a disk file. Thissubfunction can be invoked using the major I/O functions IO$_CREATE andIO$_MODIFY (see Sections 1.6.1 and 1.6.4). The extendsubfunction is performed if the bit FIB$V_EXTEND is set in the extendcontrol word FIB$W_EXCTL.
Table 1-4 lists the FIB fields that control the processing of anextend subfunction.
The specified number of blocks are allocated and appended to the file. The virtual block number assigned to the first block allocated is returned in FIB$L_EXVBN. The actual number of blocks allocated is returned in FIB$L_EXSZ.
The actual number of blocks allocated is also returned in the second longword of the user's I/O status block. If a contiguous allocation (FIB$V_ALCON) fails, the size of the largest contiguous space available on the disk is returned in the second longword of the user's I/O status block.
The truncate subfunction is used to remove space from a disk file. Thissubfunction can be invoked by the major I/O functions IO$_DEACCESS andIO$_MODIFY (see Sections 1.6.3 and 1.6.4). The truncatesubfunction is performed if the bit FIB$V_TRUNC is set in the extendcontrol word FIB$W_EXCTL.
Table 1-5 lists the FIB fields that control the processing of atruncate subfunction.
Blocks are deallocated from the file, starting with the virtual blockspecified in FIB$L_EXVBN and continuing through the end of the file.The actual number of blocks deallocated is returned in FIB$L_EXSZ. Thevirtual block number of the first block actually deallocated isreturned in FIB$L_EXVBN. Because of cluster round-up, this value mightbe greater than the value specified. If FIB$V_MARKBAD is specified, thetruncation VBN is rounded down instead of up, and the value returned inFIB$L_EXVBN might be less than that specified.
The number of blocks by which FIB$L_EXVBN was rounded up is returned inthe second longword of the I/O status block.
The truncate subfunction normally requires exclusive access to the fileat run time. This means, for example, that a file cannot be truncatedwhile multiple writers have access to it.
An exception occurs when a truncate subfunction is requested for awrite-accessed file that allows other readers. Although the truncatesubfunction returns success status in this instance, the actual filetruncation (the return of the truncated blocks to free storage) isdeferred until the last reader deaccesses the file. If a new writeraccesses the file after the truncate subfunction is requested, butbefore the last deaccess, the deferred truncation is ignored.
Once the truncate operation has started, the file is locked from otherwriters for the duration of the truncate operation. Attempts to accessthe file for shared write access during this time will result in anSS$_ACCONFLICT error.