OpenVMS I/O User's Reference Manual

Document revision date: 30 March 2001

OpenVMS I/O User's Reference Manual

Contents

Index

1.6.5.1 Operation

If a nonzero directory ID is specified in FIB$W_DID, a lookup subfunction is performed (see Section 1.3.1). The file name located is removed from the directory.

If the function modifier IO$M_DELETE is specified, the file is marked for deletion. If the file is not currently open, it is deleted immediately. If the file is open, it is deleted when the last accessor closes it.

1.6.6 Movefile Subfunction

The movefile subfunction permits you to move the contents of a file, or part of the contents of a file, to a new disk location. This subfunction can, for example, form the basis of a disk defragmentation application.

You can disable movefile operations on specific user files by specifying the /NOMOVE qualifier on the SET FILE command. Use the DIRECTORY/FULL and the DUMP/HEADER commands to find out if movefile operations are disabled on a file.

1.6.6.1 Calling the Movefile Subfunction

A program can invoke a movefile subfunction by issuing a QIO request using the function code IO$_MODIFY and the function modifier IO$M_MOVEFILE. This section describes the various input parameters that control the processing of movefile operations together with an operational description.

1.6.6.2 Input Parameters

Table 1-13 lists the FIB fields that control the processing of a movefile subfunction.

Table 1-13 FIB Fields (Movefile)
Field Subfields Meaning

FIB$L_ACCTL Movefile control flag. The following flags are applicable:

FIB$V_NOVERIFY Inhibits comparison of the moved blocks. If this flag is clear, the movefile operation verifies that the operation was carried out correctly by comparing the moved blocks to the original blocks.

FIB$V_CHANGE_VOL Enables the movefile operation to move blocks from one volume to another within a volume set.
The movefile operation clears this flag if the specified file is a directory.

FIB$W_FID Specifies the file identification of the file to be moved.

FIB$W_EXCTL Movefile control flags. The following flags apply to the movefile operation. All other FIB$W_EXCTL flags must be clear.

FIB$V_ALCON Specifies that the movefile operation must allocate contiguous disk space to the moved blocks. If the necessary contiguous space is not available, the movefile operation fails.
The movefile operation sets this flag if the file was previously marked as contiguous.

FIB$V_ALCONB Specifies that the movefile operation should attempt to allocate contiguous disk space to the moved blocks. That is, if the movefile operation cannot allocate contiguous space to all the moved blocks, it allocates contiguous space to as many of the blocks as possible.
The movefile operation sets this flag if the file was previously marked as contiguous best try.

FIB$V_FILCON Specifies that the entire file must be made contiguous. Do not set this flag without also setting the FIB$V_ALCON flag.
If the FIB$V_FILCON flag is set, and either the FIB$V_ALCON flag is clear or the file would not be made contiguous by moving the specified virtual blocks, the movefile operation fails.
The movefile operation sets this flag if the file was previously marked as contiguous.

FIB$V_NOPLACE Specifies that placement information will not be recorded in the file header.
If this flag is clear and you specify exact placement for the moved blocks, placement information for those blocks will be recorded in the file header. If this flag is set, the placement information will not be recorded.
You specify exact placement through the FIB$V_EXACT, FIB$C_LBN, and FIB$L_LOC_ADDR fields.

FIB$B_ALOPTS Flags that control the placement of the allocated blocks. Currently, only the FIB$V_EXACT flag applies to the movefile operation. All other FIB$B_ALOPTS flags must be clear. The following flags are applicable:

FIB$V_EXACT Set to require exact placement. If this flag is set and the specified blocks are not available, the movefile operation fails.

FIB$B_ALALIGN Contains the interpretation mode of the allocation field (FIB$W_ALLOC). You can specify a field value of 0 or you can specify the symbolic value FIB$C_LBN. If you specify zero, the allocation field is ignored.

FIB$W_ALLOC Contains the desired location of the blocks being allocated. Interpretation of the field is controlled by the FIB$B_ALALIGN field. The following subfields are defined:

FIB$B_LOC_RVN Specifies the relative volume number (RVN) of the volume to which the blocks are moved. Do not specify a value for this field unless you have set the FIB$V_CHANGE_VOL flag.

FIB$L_LOC_ADDR If the FIB$C_LBN and FIB$V_EXACT flags are set, specifies the starting logical address to which the blocks are moved.

FIB$L_MOV_SVBN Specifies the virtual block number (VBN) of the first block to be moved.
The starting VBN must correspond to the first block of a disk cluster. The value must be greater than 0 and it must not exceed the number of virtual blocks allocated to the file. If you specify an invalid value, the movefile operation fails.

FIB$L_MOV_VBNCNT Specifies the number of consecutive virtual blocks to be moved.
This value must be a multiple of the disk cluster size, and it must not exceed the difference between the greatest VBN allocated to the file and the FIB$L_MOV_SVBN value. If you specify a value of 0, the movefile operation moves all the virtual blocks between the FIB$L_MOV_SVBN value and the greatest VBN.
If you specify an invalid value, the movefile operation fails.

**Table 1-13 FIB Fields (Movefile)**
Field	Subfields	Meaning
FIB$L_ACCTL		Movefile control flag. The following flags are applicable:
	FIB$V_NOVERIFY	Inhibits comparison of the moved blocks. If this flag is clear, the movefile operation verifies that the operation was carried out correctly by comparing the moved blocks to the original blocks.
	FIB$V_CHANGE_VOL	Enables the movefile operation to move blocks from one volume to another within a volume set. The movefile operation clears this flag if the specified file is a directory.
FIB$W_FID		Specifies the file identification of the file to be moved.
FIB$W_EXCTL		Movefile control flags. The following flags apply to the movefile operation. All other FIB$W_EXCTL flags must be clear.
	FIB$V_ALCON	Specifies that the movefile operation must allocate contiguous disk space to the moved blocks. If the necessary contiguous space is not available, the movefile operation fails. The movefile operation sets this flag if the file was previously marked as contiguous.
	FIB$V_ALCONB	Specifies that the movefile operation should attempt to allocate contiguous disk space to the moved blocks. That is, if the movefile operation cannot allocate contiguous space to all the moved blocks, it allocates contiguous space to as many of the blocks as possible. The movefile operation sets this flag if the file was previously marked as contiguous best try.
	FIB$V_FILCON	Specifies that the entire file must be made contiguous. Do not set this flag without also setting the FIB$V_ALCON flag. If the FIB$V_FILCON flag is set, and either the FIB$V_ALCON flag is clear or the file would not be made contiguous by moving the specified virtual blocks, the movefile operation fails. The movefile operation sets this flag if the file was previously marked as contiguous.
	FIB$V_NOPLACE	Specifies that placement information will not be recorded in the file header. If this flag is clear and you specify exact placement for the moved blocks, placement information for those blocks will be recorded in the file header. If this flag is set, the placement information will not be recorded. You specify exact placement through the FIB$V_EXACT, FIB$C_LBN, and FIB$L_LOC_ADDR fields.
FIB$B_ALOPTS		Flags that control the placement of the allocated blocks. Currently, only the FIB$V_EXACT flag applies to the movefile operation. All other FIB$B_ALOPTS flags must be clear. The following flags are applicable:
	FIB$V_EXACT	Set to require exact placement. If this flag is set and the specified blocks are not available, the movefile operation fails.
FIB$B_ALALIGN		Contains the interpretation mode of the allocation field (FIB$W_ALLOC). You can specify a field value of 0 or you can specify the symbolic value FIB$C_LBN. If you specify zero, the allocation field is ignored.
FIB$W_ALLOC		Contains the desired location of the blocks being allocated. Interpretation of the field is controlled by the FIB$B_ALALIGN field. The following subfields are defined:
	FIB$B_LOC_RVN	Specifies the relative volume number (RVN) of the volume to which the blocks are moved. Do not specify a value for this field unless you have set the FIB$V_CHANGE_VOL flag.
	FIB$L_LOC_ADDR	If the FIB$C_LBN and FIB$V_EXACT flags are set, specifies the starting logical address to which the blocks are moved.
FIB$L_MOV_SVBN		Specifies the virtual block number (VBN) of the first block to be moved. The starting VBN must correspond to the first block of a disk cluster. The value must be greater than 0 and it must not exceed the number of virtual blocks allocated to the file. If you specify an invalid value, the movefile operation fails.
FIB$L_MOV_VBNCNT		Specifies the number of consecutive virtual blocks to be moved. This value must be a multiple of the disk cluster size, and it must not exceed the difference between the greatest VBN allocated to the file and the FIB$L_MOV_SVBN value. If you specify a value of 0, the movefile operation moves all the virtual blocks between the FIB$L_MOV_SVBN value and the greatest VBN. If you specify an invalid value, the movefile operation fails.

1.6.6.3 Operation

A program can perform a movefile operation on a file if the following conditions are met:

The program has write and control access to the file.
The file is closed.
Movefile operations are not disabled on the file.
Movefile operations are automatically disabled on critical system files. You can disable movefile operations on specific user files by specifying the /NOMOVE qualifier with the SET FILE command.
The operation is not interrupted.
If the movefile operation is interrupted by any other operation, such as a read or write operation, the movefile operation aborts and the file remains in its original position.

The movefile operation moves a specified number of consecutive virtual blocks to new logical blocks on disk, beginning with the virtual block specified in the FIB$L_SVBN field.

The number of blocks moved is specified in the FIB$L_VBNCNT field. To move an entire file, specify FIB$L_VBNCNT as 0 and FIB$L_SVBN as 1.

To specify a starting logical block for the moved blocks, specify the logical block address in the FIB$L_LOC_ADDR subfield and set the FIB$C_LBN and the FIB$V_EXACT flags.

To move the blocks to another volume, or move blocks that span more than one volume, set the FIB$V_CHANGE_VOL flag of the FIB$L_ACCTL field. Use the FIB$B_LOC_RVN subfield of the FIB$W_ALLOC field to specify the volume to which the blocks are moved. If you do not specify a volume, the blocks are moved to the volume containing the first virtual block. Note that you cannot move blocks of a directory file to another volume.

If the file was previously marked as contiguous, the movefile operation sets the FIB$V_ALCON, FIB$V_ALCONB, and FIB$V_FILCON flags. This ensures that a contiguous file is not fragmented by a movefile operation.

For virtual blocks beyond the file's highwater mark, the movefile operation allocates new logical blocks but does not copy the contents. The position of the file's highwater mark remains unchanged.

1.6.7 Mount

On VAX and Alpha systems, mount is a virtual I/O function that informs the ACP when a disk or magnetic tape volume is mounted. MOUNT privilege is required.

IO$_MOUNT takes no arguments or function modifiers. This function is part of the volume mounting operation only, and it is not meant for general use. Most of the actual processing is performed by the MOUNT command or the Mount Volume ($MOUNT) system service.

1.6.8 ACP Control

ACP Control is a virtual I/O function that performs miscellaneous control functions, depending on the arguments specified.

The following is the function code:

IO$_ACPCONTROL

The following is the function modifier:

IO$M_DMOUNT---Dismounts a volume.

1.6.8.1 Input Parameters

The following are the device- or function-dependent arguments for IO$_ACPCONTROL:

P1---The address of the file information block (FIB) descriptor.
P2---The address of the file name string descriptor (optional).
P3---The address of the word that is to receive the length of the resultant file name string (optional).
P4---The address of a descriptor for a buffer that is to receive the resultant file name string (optional).

Table 1-14 lists FIB fields that control the processing of the IO$_ACPCONTROL function.

Table 1-14 IO$_ACPCONTROL and the FIB
Field Subfields Meaning

FIB$W_CNTRLFUNC Specifies the control function to be performed. This field overlays FIB$W_EXCTL.

FIB$L_CNTRLVAL ¹ Specifies additional function-dependent data. This field overlays FIB$L_EXSZ.

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. For Files-11 C/D, this field is always set to SS$_NORMAL.

FIB$L_STATUS ¹ Alternate access status. 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 and the alternate access check succeeded, the FIB bit returned from the file system is set.

FIB$L_ALT_ACCESS ¹ A 32-bit mask that represents an access mask to check against file protection; for example, to open a file for read and to check whether it can be deleted or not. The mask has the same configuration as the standard protection mask.

**Table 1-14 IO$_ACPCONTROL and the FIB**
Field	Subfields	Meaning
FIB$W_CNTRLFUNC		Specifies the control function to be performed. This field overlays FIB$W_EXCTL.
FIB$L_CNTRLVAL ¹		Specifies additional function-dependent data. This field overlays FIB$L_EXSZ.
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. For Files-11 C/D, this field is always set to SS$_NORMAL.
FIB$L_STATUS ¹		Alternate access status. 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 and the alternate access check succeeded, the FIB bit returned from the file system is set.
FIB$L_ALT_ACCESS ¹		A 32-bit mask that represents an access mask to check against file protection; for example, to open a file for read and to check whether it can be deleted or not. The mask has the same configuration as the standard protection mask.

¹Not supported or invalid for Files-11 C/D.

1.6.8.2 Magnetic Tape Control Functions

Table 1-15 the lists FIB field applicable to magnetic tape operations.

Table 1-15 Magnetic Tape Operations and the FIB
Field Subfields Meaning

FIB$W_CNTRLFUNC Several ACP control functions are used for magnetic tape positioning. These functions are specified by supplying a FIB with P1 containing the FIB descriptor address. Modifiers and parameters P2, P3, and P4 are not allowed. These functions clear serious exceptions in magnetic tape drivers. The following control functions can be specified to control magnetic tape positioning:

FIB$C_REWINDFIL Rewind to beginning-of-file.

FIB$C_REWINDVOL Rewind to beginning-of-volume set.

FIB$C_POSEND Position to end-of-volume set.

FIB$C_NEXTVOL Force next volume.

FIB$C_SPACE Space n blocks forward or backward. The FIB$L_CNTRLVAL field specifies the number of magnetic tape blocks to space forward if positive or to space backward if negative.

FIB$C_CLSEREXCP If set, clears the serious exception in the magnetic tape driver (see FIB$C_USEREOT in Section 1.6.1 and Section 1.6.2). If writing, allows you to write data blocks beyond the EOT marker, which can result in the magnetic tape not conforming to the ANSI standard for magnetic tapes (see ANSI Standard X3.27--1978). If reading, allows you to handle the move to the next volume or to stop reading the tape. Do not attempt to read past EOV.

**Table 1-15 Magnetic Tape Operations and the FIB**
Field	Subfields	Meaning
FIB$W_CNTRLFUNC		Several ACP control functions are used for magnetic tape positioning. These functions are specified by supplying a FIB with P1 containing the FIB descriptor address. Modifiers and parameters P2, P3, and P4 are not allowed. These functions clear serious exceptions in magnetic tape drivers. The following control functions can be specified to control magnetic tape positioning:
	FIB$C_REWINDFIL	Rewind to beginning-of-file.
	FIB$C_REWINDVOL	Rewind to beginning-of-volume set.
	FIB$C_POSEND	Position to end-of-volume set.
	FIB$C_NEXTVOL	Force next volume.
	FIB$C_SPACE	Space n blocks forward or backward. The FIB$L_CNTRLVAL field specifies the number of magnetic tape blocks to space forward if positive or to space backward if negative.
	FIB$C_CLSEREXCP	If set, clears the serious exception in the magnetic tape driver (see FIB$C_USEREOT in Section 1.6.1 and Section 1.6.2). If writing, allows you to write data blocks beyond the EOT marker, which can result in the magnetic tape not conforming to the ANSI standard for magnetic tapes (see ANSI Standard X3.27--1978). If reading, allows you to handle the move to the next volume or to stop reading the tape. Do not attempt to read past EOV.

1.6.8.3 Miscellaneous Disk Control Functions

Several ACP control functions are available for disk volume control. The following function does not use parameters P2, P3, and P4:

IO$M_DMOUNT Specifying the dismount modifier on the IO$_ACPCNTRL function executes a dismount QIO. No parameters in the FIB are used; the FIB can be omitted. This function does not perform a dismount by itself, but is used to synchronize the ACP with the DISMOUNT command and the Dismount Volume ($DISMOUNT) system service.

The FIB$W_CNTRLFUNC field of the FIB specifies the following miscellaneous control functions (with no modifier on the IO$_ACPCONTROL function code). These functions use no other parameters.

FIB$C_REMAP Remap a file. The file window for the file open on the user's channel is remapped so that it maps the entire file.

FIB$C_LOCK_VOL Allocation lock the volume. Operations that change the file structure, such as file creation, deletion, extension, and deaccess, are not permitted. If such requests are queued to the file system for an allocation-locked volume, they are not processed until the FIB$C_UNLK_VOL function is issued to unlock the volume.
To issue the FIB$C_LOCK_VOL function, you must have either a system UIC or SYSPRV privilege, or be the owner of the volume.

FIB$C_UNLK_VOL Unlock the volume. Cancels FIB$C_LOCK_VOL. To issue this function, you must have either a system UIC or SYSPRV privilege, or be the owner of the volume.

1.6.8.4 Disk Quotas

Disk quota enforcement is enabled by a quota file on the volume, or relative volume 1 if the file is on a volume set. The quota file appears in the volume's master file directory (MFD) under the name QUOTA.SYS;1. This section describes the control functions that operate on the quota file.

Table 1-16 lists the enable and disable quota control functions.

Table 1-16 Disk Quota Functions (Enable/Disable)
Value Meaning

FIB$C_ENA_QUOTA Enable the disk quota file. If a nonzero directory file ID is specified in FIB$W_DID, a lookup subfunction is performed to locate the quota file (see Section 1.3.1). To issue this function, you must have either a system UIC or SYSPRV privilege, or be the owner of the volume.
The quota file specified by FIB$W_FID, if present, is accessed by the ACP, and quota enforcement is turned on. By convention, the quota file is named [0,0]QUOTA.SYS;1. Therefore, FIB$W_DID should contain the value 4,4,0 and the name string specified with P2 should be "QUOTA.SYS;1".

FIB$C_DSA_QUOTA Disable the disk quota file. The quota file is deaccessed and quota enforcement is turned off. To issue this function, you must have either a system UIC or SYSPRV privilege, or be the owner of the volume.

**Table 1-16 Disk Quota Functions (Enable/Disable)**
Value	Meaning
FIB$C_ENA_QUOTA	Enable the disk quota file. If a nonzero directory file ID is specified in FIB$W_DID, a lookup subfunction is performed to locate the quota file (see Section 1.3.1). To issue this function, you must have either a system UIC or SYSPRV privilege, or be the owner of the volume. The quota file specified by FIB$W_FID, if present, is accessed by the ACP, and quota enforcement is turned on. By convention, the quota file is named [0,0]QUOTA.SYS;1. Therefore, FIB$W_DID should contain the value 4,4,0 and the name string specified with P2 should be "QUOTA.SYS;1".
FIB$C_DSA_QUOTA	Disable the disk quota file. The quota file is deaccessed and quota enforcement is turned off. To issue this function, you must have either a system UIC or SYSPRV privilege, or be the owner of the volume.

Table 1-17 lists the quota control functions that operate on individual entries in the quota file. Each operation transfers quota file data to and from the ACP using a quota data block. This block has the same format as a record in the quota file. Figure 1-9 shows the format of this block.

Table 1-17 Disk Quota Functions (Individual Entries)
Value Meaning

FIB$C_ADD_QUOTA Add an entry to the disk quota file, using the UIC and quota specified in the P2 argument block. FIB$C_ADD_QUOTA requires write access to the quota file.

FIB$C_EXA_QUOTA Examine a disk quota file entry. The entry whose UIC is specified in the P2 argument block is returned in the P4 argument block, and its length is returned in the P3 argument word. Using two flags in FIB$L_CNTRLVAL, it is possible to search through the quota file using wildcards. The two flags are:

FIB$V_ALL_MEM Match all UIC members

FIB$V_ALL_GRP Match all UIC groups

The ACP maintains position context in FIB$L_WCC. On the first examine call, you specify 0 in FIB$L_WCC; the ACP returns a nonzero value so that each succeeding examine call returns the next matching entry.
Read access to the quota file is required to examine all non-user entries.

FIB$C_MOD_QUOTA Modify a disk quota file entry. The quota file entry specified by the UIC in the P2 argument block is modified according to the values in the block, as controlled by three flags in FIB$L_CNTRLVAL.

FIB$V_MOD_PERM Change the permanent quota

FIB$V_MOD_OVER Change the overdraft quota

FIB$V_MOD_USE Change the usage data

The usage data can be changed only if the volume is locked by FIB$C_LOCK_VOL (see Section 1.6.8.3). FIB$C_MOD_QUOTA requires write access to the quota file.
The P3 and P4 arguments return the modified quota entry to you.
By using the flags FIB$V_ALL_MEM and FIB$V_ALL_GRP, you can search through the quota file using wildcards just as you would with the FIB$C_EXA_QUOTA function.

FIB$C_REM_QUOTA Remove a disk quota file entry whose UIC is specified in the P2 argument block. FIB$C_REM_QUOTA requires write access to the quota file.
The P3 and P4 arguments return the removed quota file entry to you.
By using the flags FIB$V_ALL_MEM and FIB$V_ALL_GRP, you can search through the quota file using wildcards just as you would with the FIB$C_EXAQUOTA function.

Figure 1-9 Quota File Transfer Block

IO$_ACPCONTROL functions that transfer quota file data between the caller and the ACP use the following device- or function-dependent arguments:

P2---The address of a descriptor for the quota data block being sent to the ACP.
P3---The address of a word that returns the data length.
P4---The address of a descriptor for a buffer to receive the quota data block returned from the ACP.

1.7 I/O Status Block

Figure 1-10 shows the I/O status block (IOSB) for ACP--QIO functions. Appendix A lists the status returns for these functions. (The OpenVMS system messages documentation provides explanations and suggested user actions for these returns.)

The file ACP returns a completion status in the first longword of the IOSB. In an extend operation, the second longword is used to return the number of blocks allocated to the file. If a contiguous extend operation (FIB$V_ALCON) fails, the second longword is used to return the size of the file after truncation.

Values returned in the IOSB are most useful during operations in compatibility mode. When executing programs in the native mode, use the values returned in FIB locations.

Figure 1-10 IOSB Contents---ACP-QIO Functions

If an extend operation (including CREATE) was performed, IOSB+4 contains the number of blocks allocated, or the largest available contiguous space if a contiguous extend operation failed. If a truncate operation was performed, IOSB+4 contains the number of blocks added to the file size to reach the next cluster boundary.

Contents

Index

privacy and legal statement

6136PRO_004.HTML

FIB$C_REMAP	Remap a file. The file window for the file open on the user's channel is remapped so that it maps the entire file.
FIB$C_LOCK_VOL	Allocation lock the volume. Operations that change the file structure, such as file creation, deletion, extension, and deaccess, are not permitted. If such requests are queued to the file system for an allocation-locked volume, they are not processed until the FIB$C_UNLK_VOL function is issued to unlock the volume. To issue the FIB$C_LOCK_VOL function, you must have either a system UIC or SYSPRV privilege, or be the owner of the volume.
FIB$C_UNLK_VOL	Unlock the volume. Cancels FIB$C_LOCK_VOL. To issue this function, you must have either a system UIC or SYSPRV privilege, or be the owner of the volume.