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:

Directory Lookup
Access
Extend
Truncate
Read/Write Attributes

Section 1.6, which contains the descriptions of the major functions,lists the subfunctions available to each major function.

1.3.1 Directory Lookup

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 the directory file ID field in the FIB (FIB$W_DID) is a nonzero number.

1.3.1.1 Input Parameters

Table 1-2 lists the FIB fields that control the processing of alookup subfunction.

**Table 1-2 FIB Fields (Lookup Control)**
Field	Subfields	Meaning
FIB$W_NMCTL		Name string control. The following name control bits are applicable to a lookup operation:
	FIB$V_WILD	Set if name string contains wildcards. Setting this bit causes wildcard context to be returned in FIB$L_WCC.
	FIB$V_ALLNAM	Set to match all name field values.
	FIB$V_ALLTYP	Set to match all field type values.
	FIB$V_ALLVER	Set to match all version field values.
	FIB$V_FINDFID	Set to search a directory for the file ID in FIB$W_FID.
FIB$W_FID		File identification. The file ID of the file found is returned in this field.
FIB$W_DID		Contains the file identifier of the directory file. This field must be a nonzero number.
FIB$L_WCC		Maintains position context when processing wildcard directory operations.
FIB$L_ACCTL		The following access control flag is applicable to a lookup subfunction:
	FIB$V_REWIND	Set to rewind magnetic tape before lookup. If not set, a magnetic tape is searched from its current position.

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:

name.type;version
name.type.version

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.

1.3.1.2 Operation

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.

1.3.1.3 Directory Entry Protection

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.

1.3.2 Access

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 specified in the I/O function code.

1.3.2.1 Input Parameters

Table 1-3 lists the FIB fields that control the processing of anaccess subfunction.

**Table 1-3 FIB Fields (Access Control)**
Field	Subfields	Meaning
FIB$L_ACCTL		Specifies field values that control access to the file. The following access control bits are applicable to the access subfunction:
	FIB$V_WRITE	Set for write access; clear for read-only access.
	FIB$V_NOREAD	Set to deny read access to others. (You must have write privilege to the file to use this option.)
	FIB$V_NOWRITE	Set to deny write access to others.
	FIB$V_NOTRUNC	Set to prevent the file from being truncated; clear to allow truncation.
	FIB$V_DLOCK	Set to enable deaccess lock (close check). Used only for disk devices.
		Used to flag a file as inconsistent if the program currently modifying the file terminates abnormally. If the program deaccesses the file without performing a write attributes operation, the file is marked as locked and cannot be accessed until it is unlocked.
	FIB$V_UPDATE	Set to position at the start of a magnetic tape file when opening a file for write; clear to position at end-of-file.
	FIB$V_READCK	Set to enable read checking of the file. Virtual reads to the file are performed using a data check operation.
	FIB$V_WRITECK	Set to enable write checking of the file. Virtual writes to the file are performed using a data check operation.
	FIB$V_EXECUTE	Set to access the file in execute mode. The protection check is made against the EXECUTE bit instead of the READ bit. Valid only for requests issued from SUPERVISOR, EXEC, or KERNEL mode.
	FIB$V_NOLOCK	Set to override exclusive access to the file, allowing you to access the file when another user has the file open with FIB$V_NOREAD specified. You must have SYSPRV privilege to use this option. FIB$V_NOREAD and FIB$V_NOWRITE must be clear for this option to work.
	FIB$V_NORECORD	Set to inhibit recording of the file's modification and expiration dates. If not set, the file's expiration date can be modified, depending on the file retention parameters of the volume.
	FIB$V_SEQONLY	Set to inform the file system that the file is to be processed sequentially only.
FIB$B_WSIZE		Controls the size of the file window used to map a disk file. The ACP uses the volume default if FIB$B_WSIZE is 0. A value of 1 to 127 indicates the number of retrieval pointers to be allocated to the window. A value of --1 indicates that the window should be as large as necessary to map the entire file. Note that the window is charged to the user's BYTELIM quota.
FIB$W_FID		Specifies the file identification of the file to be accessed.

1.3.2.2 Operation

The file is opened according to the access control specified (see Table 1-3).

1.3.3 Extend

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.

1.3.3.1 Input Parameters

Table 1-4 lists the FIB fields that control the processing of anextend subfunction.

**Table 1-4 FIB Fields (Extend Control)**
Field	Subfields	Meaning
FIB$W_EXCTL		Extend control flags. The following flags are applicable to the extend subfunction:
	FIB$V_EXTEND	Set to enable extension.
	FIB$V_NOHDREXT	Set to inhibit generation of extension file headers.
	FIB$V_ALCON	Allocates contiguous space. The extend operation fails if the necessary contiguous space is not available.
	FIB$V_ALCONB	Allocates the maximum amount of contiguous space.
		If both FIB$V_ALCON and FIB$V_ALCONB are set, a single contiguous area, whose size is the largest available but not greater than the size requested, is allocated.
	FIB$V_FILCON	Marks the file as contiguous. This bit can only be set if the file does not have space already allocated to it.
	FIB$V_ALDEF	Allocates the extend size (FIB$L_EXSZ) or the system default, whichever is greater.
FIB$L_EXSZ		Specifies the number of blocks to allocate to the file.
		The number of blocks actually allocated for this operation is returned in this longword. More blocks than requested can be allocated to meet cluster boundaries.
FIB$L_EXVBN		Returns the starting virtual block number of the blocks allocated. FIB$L_EXVBN must initially contain 0 blocks.
FIB$B_ALOPTS		Contains option bits that control the placement of allocated blocks. The following bits are defined:
	FIB$V_EXACT	Set to require exact placement; clear to specify approximate placement. If this bit is set and the specified blocks are not available, the extend operation fails.
	FIB$V_ONCYL	Set to locate allocated space within a cylinder. This option functions correctly only when FIB$V_ALCON or FIB$V_ALCONB is specified.
FIB$B_ALALIGN		Contains the interpretation mode of the allocation (FIB$W_ALLOC) field. One of the following values can be specified:
	(zero)	No placement data. The remainder of the allocation field is ignored.
	FIB$C_CYL	Location is specified as a byte relative volume number (RVN) in FIB$B_LOC_RVN and a cylinder number in FIB$L_LOC_ADDR.
	FIB$C_LBN	Location is specified as a byte RVN in FIB$B_LOC_RVN, followed by a longword logical block number (LBN) in FIB$L_LOC_ADDR.
	FIB$C_VBN	Location is specified as a longword virtual block number (VBN) of the file being extended in FIB$L_LOC_ADDR. A 0 VBN or one that fails to map indicates the end of the file.
	FIB$C_RFI	Location is specified as a three-word file ID in FIB$W_LOC_FID, followed by a longword VBN of that file in FIB$L_LOC_ADDR. A 0 file ID indicates the file being extended. A 0 VBN or one that fails to map indicates the end of that file.
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 RVN or placement RVN.
	FIB$B_LOC_NMX	Related file number extension.
	FIB$L_LOC_ADDR	Placement LBN, cylinder, or VBN.

1.3.3.2 Operation

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.

1.3.4 Truncate

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.

1.3.4.1 Input Parameters

Table 1-5 lists the FIB fields that control the processing of atruncate subfunction.

**Table 1-5 FIB Fields (Truncate Control)**
Field	Subfields	Meaning
FIB$W_EXCTL		Extend control flags. The following flags are applicable to the truncate subfunction:
	FIB$V_TRUNC	Must be set to enable truncation.
	FIB$V_MARKBAD	Set to append the truncated blocks to the bad block file, instead of returning them to the free storage pool. Only one cluster can be deallocated. This is most easily accomplished by specifying the last VBN of the file in FIB$L_EXVBN. SYSPRV privilege or ownership of the volume is required to deallocate blocks to the bad block file.
FIB$L_EXSZ		Returns the actual number of blocks deallocated. FIB$L_EXSZ must initially contain a value of 0.
FIB$L_EXVBN		Specifies the first virtual block number to be removed from the file. The actual starting virtual block number of the truncate operation is returned in this field.

1.3.4.2 Operation

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.

Contents

Index