The following sections describe the operation
of the major ACP functions. Each section describes the required and
optional parameters for a particular function, as well as the sequence
in which the function is performed. For clarity, when a major function
invokes a subfunction, the input parameters used by the subfunction
are omitted.
1.6.1 Create File
Create file is a virtual I/O function that creates a directory
entry or a file on a disk device, or a file on a magnetic tape device.
The following is the function code:
IO$_CREATE
The following are the function modifiers:
IO$M_CREATE—Creates
a file.
IO$M_ACCESS—Opens
the file on your channel.
IO$M_DELETE—Marks
the file for deletion (applicable only to disk devices).
1.6.1.1 Input Parameters
The following are the device- or function-dependent
arguments for IO$_CREATE:
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).
P5—The address
of a list of attribute descriptors (optional).
Table 1-11 lists fields in the FIB that are applicable to the IO$_CREATE operation.
Table 1-11 IO$_CREATE and the FIB
Field
Subfields
Meaning
FIB$L_ACCTL
Specifies field values that control access
to the file. The following bits are applicable to the IO$_CREATE function:
FIB$V_REWIND
Set to rewind magnetic tape before
creating the file. Any data currently on the tape is overwritten.
FIB$V_CURPOS
Set to create magnetic tape file
at the current tape position. (Note: a magnetic tape file is created
at the end of the volume set if neither FIB$V_REWIND nor FIB$V_CURPOS
is set.) If the tape is not positioned at the end of a file, FIB$V_CURPOS
creates a file at the next file position. Any data currently on the
tape past the current file position is overwritten.
FIB$V_WRITETHRU
Specifies that the file header
is to be written back to the disk. If not specified and the file is
opened, writing of the file header can be deferred to some later time.
FIB$W_CNTRLFUNC
Specifies the following value, which allows you to
control actions subsequent to EOT detection on a magnetic tape file.
FIB$W_FID
Contains the file ID of the file created
or entered.
FIB$W_DID
Contains the file identifier of the directory
file.
FIB$W_NMCTL
Controls the processing of the file name
in a directory operation. The following bits are applicable to the
IO$_CREATE function:
FIB$V_NEWVER
Set to create a file of the same
name with the next higher version number. Only for disk devices.
FIB$V_SUPERSEDE
Set to supersede an existing file
of the same name, type, and version. Only for disk devices.
FIB$V_LOWVER
Set on return if a lower numbered
version of the file exists. Only for disk devices.
FIB$V_HIGHVER
Set on return if a higher numbered
version of the file exists. Only for disk devices.
FIB$W_VERLIMIT
Specifies the version limit for the directory
entry created. Used only for disk devices and only when the first
version of a new file is created. If 0, the directory default is used.
If a directory operation was performed, FIB$W_VERLIMIT always contains
the actual version limit of the file.
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. Programmers can control the security information
being propagated as well as the source of this information by setting
the following bits.
1.6.1.2 Disk ACP Operation
If the modifier IO$M_CREATE is specified, a file
is created. The file ID of the file created is returned in FIB$W_FID. If the
modifier IO$M_DELETE is specified, the file is marked for deletion.
If a non-zero directory ID is specified in FIB$W_DID,
a directory entry is created. The file name specified by parameter
P2 is entered in the directory, together with the file ID in FIB$W_FID.
(Table 1-2 describes the format
for the file name string.) Wildcards are not permitted. Negative version
numbers are treated as equivalent to a 0 version number. If a result
string buffer and length are specified by P3 and P4, the actual file
name entered, and its length, are returned.
The version number of the file receives the following
treatment:
If the version number
in the specified file name is 0 or negative, the directory entry created
gets a version number one greater than the highest previously existing
version of that file (or version 1 if the file did not previously
exist).
If the version number
in the specified file name is a nonzero number and FIB$V_NEWVER is
set, the directory entry created gets a version number one greater
than the highest previously existing version of that file, or the
specified version number, whichever is greater.
If the version number
in the specified file name is a nonzero number and the directory already
contains a file of the same name, type, and version, the previously
existing file is set aside for deletion if FIB$V_SUPERSEDE is specified.
If FIB$V_SUPERSEDE is not specified, the create operation fails with
a SS$_DUPFILNAM status.
If, after creating the
new directory entry, the number of versions of the file exceeds the
version limit, the lowest numbered version is set aside for deletion.
If the file did not previously
exist, the new directory entry is given a version limit as follows:
the version limit is taken from FIB$W_VERLIMIT if it is a nonzero
number; if it is 0, the version limit is taken from the default version
limit of the directory file; if the default version limit of the directory
file is 0, the version limit is set to 32,767 (the highest possible
number).
The file name string entered in the directory
is returned using the P3 and P4 result string parameters, if present.
The file name string is also written into the header. If no directory
operation is requested (FIB$W_DID is 0), the file name string specified
by P2, if any, is written into the file header.
If an attribute list is specified by P5, a write
attributes subfunction is performed (see “Read/Write Attributes”).
If the modifier IO$M_ACCESS is specified, the
file is opened (see “Access”).
If the extend enable bit FIB$V_EXTEND
is specified in the FIB, an extend subfunction is performed (see “Extend”).
Finally, if a file was set aside for deletion
(IO$M_DELETE is specified), that file is deleted. If the file is deleted
because the FIB$V_SUPERSEDE bit was set, the alternate success status
SS$_SUPERSEDE is returned in the I/O status block. If the file is
deleted because the version limit was exceeded, the alternate success
status SS$_FILEPURGED is returned.
If an error occurs in the operation
of an IO$_CREATE function, all actions performed to that point are
reversed (the file is neither created nor changed), and the error
status is returned to the user in the I/O status block.
1.6.1.3 Directory Entry Creation
Creating a new version of
a file eliminates default access to the previously highest version
of the file. For example, creating RESUME.TXT;4 masks RESUME.TXT;3
so the DCL command TYPE RESUME.TXT yields the contents of version
4, not version 3. To protect the contents of the earlier version of
a file, the creator of a file must have write access to the previous
version of a file of the same name.
1.6.1.4 Magnetic Tape ACP Operation
No operation is performed unless the IO$M_CREATE
modifier is specified. The magnetic tape is positioned as specified by FIB$V_REWIND
and FIB$V_CURPOS, and the file is created. The name specified by the
P2 parameter is written into the file header label.
If P5 specifies an attribute list, a write attributes
subfunction is performed (see “Read/Write Attributes”).
If the modifier IO$M_ACCESS is specified, the
file is opened (see “Access”).
1.6.2 Access File
This virtual I/O function searches a directory on a disk
device or a magnetic tape for a specified file and accesses that file
if found.
The following is the function code:
IO$_ACCESS
The following are the function modifiers:
IO$M_CREATE—Creates
a file.
IO$M_ACCESS—Opens
the file on your channel.
1.6.2.1 Input Parameters
The following are the device- or function-dependent
arguments for IO$_ACCESS:
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).
P5—The address
of a list of attribute descriptors (optional).
Table 1-12 lists FIB fields that are applicable to the IO$_ACCESS operation.
Table 1-12 IO$_ACCESS and the File Information Block
Field
Subfields
Meaning
FIB$W_
CNTRLFUNC
Specifies the value that allows
the user to control actions subsequent to EOT detection on a magnetic
tape file.
FIB$W_VERLIMIT
Receives the version limit for the file.
Applicable only if FIB$W_DID is a nonzero number (if a directory lookup
is done). Used only for disk devices.
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. The mask has the same configuration as
the standard protection mask.
1.6.2.2 Operation
If a nonzero directory file ID is specified in
FIB$W_DID, a lookup subfunction is performed (see “Directory Lookup”.) The version
limit of the file found is returned in FIB$W_VERLIMIT.
If the directory search fails with a “file
not found” condition and the IO$M_CREATE function modifier
is specified, the function is reexecuted as a CREATE. In that case,
the argument interpretations for IO$_CREATE, rather than those for
IO$_ACCESS, apply.
If IO$M_ACCESS is specified, an access subfunction
is performed to open the file (see “Access”).
If P5 specifies an attribute list, a read attributes
subfunction is performed (see “Read/Write Attributes”).
1.6.3 Deaccess File
Deaccess file is a virtual I/O function that deaccesses
a file and, if specified, writes final attributes in the file header.
The following is the function code:
IO$_DEACCESS
IO$_DEACCESS takes no function modifiers.
1.6.3.1 Input Parameters
The following are the device- or function-dependent
arguments for IO$_DEACCESS:
P1—The address
of the file information block (FIB) descriptor.
P5—The address
of a list of attribute descriptors (optional).
The following FIB fields are applicable to the
IO$_DEACCESS function:
Field
Meaning
FIB$W_FID
File ID of the file being
deaccessed. This field can contain a value of 0. If it does not, it
must match the file identifier of the accessed file.
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.)
1.6.3.2 Operation
For disk files, if P5 specifies an attribute control
list and the file was accessed for a write operation, a write attributes
subfunction is performed (see “Read/Write Attributes”). If the file was opened for write,
no attributes were specified, and FIB$V_DLOCK was set when the file
was accessed, the deaccess lock bit is set in the file header, inhibiting
further access to that file.
For disk files, if the truncate enable bit FIB$V_TRUNC
is specified in the FIB, a truncate subfunction is performed (see “Truncate”).
Finally, the file is closed. Trailer labels are
written for a magnetic tape file that was opened for write.
1.6.4 Modify File
Modify file is a virtual I/O function
that modifies the file attributes or allocation of a disk file. The
IO$_MODIFY function is not applicable to magnetic tape; that is, the
function returns success, but no action is performed.
The following is the function code:
IO$_MODIFY
The following is the function modifier:
IO$M_MOVEFILE
1.6.4.1 Input Parameters
The following are the device- or function-dependent
arguments for IO$_MODIFY:
P1—The address
of the file information block (FIB) descriptor.
P2—The address
of the file name string descriptor (optional). If specified, the directory
is searched for the name.
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).
P5—The address
of a list of attribute descriptors (optional).
The following FIB fields are applicable to the
IO$_MODIFY function:
Field
Subfields
Meaning
FIB$L_ACCTL
Specifies field values that control access to the file.
The following bit is applicable to the IO$_MODIFY function:
FIB$V_WRITETHRU
Specifies that the file header is to be written
back to the disk. If not specified and the file is currently open,
writing of the file header can be deferred to some later time.
FIB$W_VERLIMIT
If a nonzero number, specifies the version limit for the
file.
FIB$L_ACL_STATUS
Status of
the requested ACL attribute operation. The ACL attributes are listed
in Table 1-7. If no ACL attributes
are given, SS$_NORMAL is returned here.
1.6.4.2 Operation
If a nonzero directory ID is specified in FIB$W_DID,
a lookup subfunction is executed (see “Directory Lookup”). If a nonzero version limit is specified
in FIB$W_VERLIMIT and the directory entry found is the latest version
of that file, the version limit is set to the value specified.
If P5 specifies an attribute list, a write attributes
subfunction is performed (see “Read/Write Attributes”).
The file can be either extended or truncated.
If FIB$V_EXTEND is specified in the FIB, an extend subfunction is
performed (see “Extend”). If FIB$V_TRUNC is specified in
the FIB, a truncate subfunction is performed (see “Truncate”). Extend
and truncate operations cannot be performed at the same time.
1.6.5 Delete File
Delete file is a virtual I/O function that removes a directory
entry or file header from a disk volume.
The following is the function code:
IO$_DELETE
The following is the function modifier:
IO$M_DELETE—Deletes
the file (or marks it for deletion).
The following are the device- or function-dependent
arguments for IO$_DELETE:
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).
The following FIB fields are applicable to the
IO$_DELETE function:
Field
Subfields
Meaning
FIB$L_ACCTL
Specifies field values that control access
to the file. The following bits are applicable to the IO$_DELETE function:
FIB$V_NOLOCK (Alpha only)
Allows the caller to
mark a file for delete that is currently open for write access. When
the file is closed, it is automatically deleted. The file cannot be
accessed by new callers after it has been marked for delete.
FIB$V_WRITETHRU
Specifies that the file header
is to be written back to the disk. If not specified and the file is
currently open, writing of the file header can be deferred to some
later time.
FIB$W_DID
Contains the file identifier of the directory
file. This field must be a nonzero number.
FIB$W_FID
Specifies the file identification to be deleted.
1.6.5.1 Operation
If a nonzero directory ID is specified in FIB$W_DID,
a lookup subfunction is performed (see “Directory Lookup”). 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.1.1 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
flag applies 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
is not 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 is not 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 flag is 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 0,
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.1.1.1 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 Alpha and Integrity server 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 ancillary 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.
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.
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-15 lists the 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 “Create File” and “Access File”). 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 “Directory Lookup”). 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-7 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 nonuser 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 the following 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 “Miscellaneous Disk Control Functions”). 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-7 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.
