Document revision date: 30 March 2001

## OpenVMS I/O User's Reference Manual

Previous | Contents | Index

## 1.3 ACP Subfunctions

The operations that the ACP performs can be organized into two categories: major ACP functions and subfunctions. Each ACP operation performs one major function. That function is specified by an I/O function code, such as IO$_ACCESS, IO$_CREATE, or IO$_MODIFY. While executing the major function, one or more subfunctions can be performed. A subfunction is an operation such as looking up, accessing, or extending a file. Most subfunctions can be executed by more than one of the major functions. Sections 1.3.1 through 1.3.5 describe 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 disk directory or on a magnetic tape. This subfunction can be invoked using the major functions IO$_ACCESS, IO$_MODIFY, IO$_DELETE, and IO$_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 a lookup 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 the file itself. For example, if a directory file is protected against delete access, then the file name has the same protection. Consequently, a nonprivileged user cannot rename a file because renaming a file is essentially the same as deleting the file name. This protection is applied regardless of the protection on the directory file.

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 or write operations can be performed. This subfunction can be invoked using the major functions IO$_CREATE and IO$_ACCESS (see Sections 1.6.1 and 1.6.2). An access subfunction is performed if the 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 an access 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. This subfunction can be invoked using the major I/O functions IO$_CREATE and IO$_MODIFY (see Sections 1.6.1 and 1.6.4). The extend subfunction is performed if the bit FIB$V_EXTEND is set in the extend control word FIB$W_EXCTL.

#### 1.3.3.1 Input Parameters

Table 1-4 lists the FIB fields that control the processing of an extend 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. This subfunction can be invoked by the major I/O functions IO$_DEACCESS and IO$_MODIFY (see Sections 1.6.3 and 1.6.4). The truncate subfunction is performed if the bit FIB$V_TRUNC is set in the extend control word FIB$W_EXCTL.

#### 1.3.4.1 Input Parameters

Table 1-5 lists the FIB fields that control the processing of a truncate 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 block specified in FIB$L_EXVBN and continuing through the end of the file. The actual number of blocks deallocated is returned in FIB$L_EXSZ. The virtual block number of the first block actually deallocated is returned in FIB$L_EXVBN. Because of cluster round-up, this value might be greater than the value specified. If FIB$V_MARKBAD is specified, the truncation VBN is rounded down instead of up, and the value returned in FIB$L_EXVBN might be less than that specified.

The number of blocks by which FIB$L_EXVBN was rounded up is returned in the second longword of the I/O status block.

The truncate subfunction normally requires exclusive access to the file at run time. This means, for example, that a file cannot be truncated while multiple writers have access to it.

An exception occurs when a truncate subfunction is requested for a write-accessed file that allows other readers. Although the truncate subfunction returns success status in this instance, the actual file truncation (the return of the truncated blocks to free storage) is deferred until the last reader deaccesses the file. If a new writer accesses the file after the truncate subfunction is requested, but before the last deaccess, the deferred truncation is ignored.

Once the truncate operation has started, the file is locked from other writers for the duration of the truncate operation. Attempts to access the file for shared write access during this time will result in an SS$_ACCONFLICT error.

Previous | Next | Contents | Index

| privacy and legal statement |
6136PRO_001.HTML