HP OpenVMS I/O User's Reference Manual |
ACP-QIO Interface |
|
|
| |
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:
The following are the function modifiers:
Input Parameters ![]()
The following are the device- or function-dependent arguments
for IO$_CREATE:
IO$_CREATE and the FIB lists fields in the FIB that are applicable to the IO$_CREATE operation.
| 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
ACP-QIO Attributes. 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.
|
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 nonzero 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. ( FIB Fields (Lookup Control) 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:
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 was 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.
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.
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).
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:
The following are the function modifiers:
Input Parameters ![]()
The following are the device- or function-dependent arguments
for IO$_ACCESS:
IO$_ACCESS and the File Information Block lists FIB fields that are applicable to the IO$_ACCESS operation.
| 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
ACP-QIO Attributes. 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.
|
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).
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 takes no function modifiers.
Input Parameters ![]()
The following are the device- or function-dependent arguments
for IO$_DEACCESS:
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
ACP-QIO Attributes. If no ACL attributes are given,
SS$_NORMAL is returned here. (For Files-11 C/D, this field is always
set to SS$_NORMAL.)
|
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.
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:
The following is the function modifier:
Input Parameters ![]()
The following are the device- or function-dependent arguments
for IO$_MODIFY:
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
ACP-QIO Attributes. If no ACL attributes are given, SS$_NORMAL is returned
here. |
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.
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:
The following is the function modifier:
The following are the device- or function-dependent arguments for IO$_DELETE:
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.
|
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.
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.
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.
Input Parameters FIB Fields (Movefile) lists the FIB fields that control the processing of a movefile subfunction.
A program can perform a movefile operation on a file if the
following conditions are met: 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. ![]()
![]()
![]()
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. ![]()
![]()
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.
Mount ![]()
On VAX, Alpha, and I64
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.
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:
The following is the function modifier:
Input Parameters ![]()
The following are the device- or function-dependent arguments
for IO$_ACPCONTROL:
IO$_ACPCONTROL and the FIB lists FIB fields that control the processing of the IO$_ACPCONTROL function.
| Field | Subfields | Meaning |
|---|---|---|
|
FIB$W_CNTRLFUNC
|
|
Specifies the control function
to be performed. This field overlays FIB$W_EXCTL.
|
|
FIB$L_CNTRLVAL1
|
|
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
ACP-QIO Attributes. 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.
|
Magnetic Tape Control Functions ![]()
Magnetic Tape Operations and the FIB lists the FIB
field applicable to magnetic tape operations.
| 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.
|
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:
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.
|
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.
Disk Quota Functions (Enable/Disable) lists the enable and disable quota control functions.
| 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.
|
Disk Quota Functions (Individual Entries) 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. Quota File Transfer Block shows the format of this block.
| 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 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:
1 Not supported or valid for Files-11 C/D.
( Number takes you back )
|
|