OpenVMS Record Management Services Reference
4.15 FAB$L_FNA Field
The file specification string address (FNA) field works with the
FAB$B_FNS field to specify the primary file specification of the file
to be processed. If this string does not contain all the components of
a full file specification, RMS uses the defaults supplied in the
default file specification string (see FAB$L_DNA and FAB$B_DNS). If no
default string is present, or if the file specification is still
incomplete, RMS provides additional defaults.
This field contains the symbolic address of a file specification
string, which is an ASCII string containing one or more components of a
file specification. This field is used as input by many file-processing
services. To obtain the file specification returned by RMS after it
translates any logical names and applies defaults, a NAM or NAML block
must be present (see FAB$L_NAM).
This field and the FAB$B_FNS field correspond to the FDL attribute FILE
The FAB$L_FNA field is equivalent to the NAML$L_LONG_FILENAME field of
the long name block (NAML). See Chapter 6 for more information.
4.16 FAB$B_FNS Field
The file specification string size (FNS) field specifies the size, in
bytes, of the ASCII file specification string, whose address is
contained in the FAB$L_FNA field. This field contains a numeric value
in the range of 0 through 255.
This field and the FAB$L_FNA field correspond to the FDL attribute FILE
4.17 FAB$L_FOP Field
FAB$L_FOP is the symbolic offset value for the FAB's file-processing
options (FOP) field. This field specifies which of the various optional
file operations are to be implemented for the process.
The FOP is a 32-bit field in which each file-processing option has a
corresponding bit assignment to let you specify multiple options
(multiple bits can be set), when applicable. Each option has a unique
symbolic offset value and mask value, but you need only specify the
appropriate 3-letter mnemonic when coding a function. For example, the
spool-file-on-close option has a symbolic offset value of FAB$V_SPL,
but to specify the option, you use the following MACRO statement:
As detailed in the appropriate descriptions, the only file-processing
bits that may be affected by record management services are the
FAB$V_CBT, FAB$V_CTG, FAB$V_RCK, and FAB$V_WCK bits.
This section presents the seven types of file-processing options
alphabetically by functional category:
- Allocation and extension options
- File name parsing modifiers
- File disposition options
- Magnetic tape processing options
- Nonstandard processing options
- Performance options
- Reliability options
Table 4-3 lists each of the options alphabetically by category.
Table 4-3 File Processing Options
This field corresponds to the FDL primary attribute FILE.
|Allocation and Extension Options
Contiguous best try
Truncate at end of file
|File Name Parsing Modifier Options
Maximum version number
Use NAM or NAML block inputs
Output file parse
Supersede existing file
|File Disposition Options
Delete on close
Submit command file on close
Spool file on close
Temporary marked for delete
|Magnetic Tape Processing Options
Do not set to EOF
Rewind file on close
Rewind file on open
|Nonstandard Processing Options
User file open
Allocation and Extension Options
Contiguous best try; indicates that the file is to be allocated
contiguously on a "best effort" basis. It is input to the
Create service and output from the Open service to indicate the file
status. The FAB$V_CBT option overrides the FAB$V_CTG option. Note that
this option is ignored if multiple areas are defined for an
This option corresponds to the FDL attribute FILE BEST_TRY_CONTIGUOUS.
Contiguous; indicates that the space for the file is to be allocated
contiguously. If this cannot be done, the operation fails. It is input
to the Create service and is output by the Open service to indicate the
status of the file. Note that this option is ignored if multiple areas
are defined for an indexed file. The FAB$V_CBT option overrides the
This option corresponds to the FDL attribute FILE CONTIGUOUS.
Truncate at end of file; indicates that unused space allocated to a
file is to be deallocated on a Close service. This option is tested
only at $CLOSE time. When a writer requests this option at close, if
other readers are still accessing the file, the file systems defers the
actual file truncation until the last reader closes the file. The
system still returns a success status. The last truncation request made
by a writer before the last close has precedence over any previous
deferred truncation. Once the file system starts the truncate
operation, the file is locked from other writers until the truncate
operation is done.
The FAB$V_TEF option applies only to sequential files.
This option corresponds to the FDL attribute FILE TRUNCATE_ON_CLOSE.
File Name Parsing Modifiers
Create if nonexistent; creates and opens a file and returns the
alternate success status RMS$_CREATED, assuming the file does not
exist. If you specify an existing file, RMS opens it. Note that if you
specify the CIF option for an indexed file, you need to provide a key
XAB. If you do not provide a key XAB, RMS returns an RMS$_NPK error.
The FAB$V_CIF option is input only to the Create service and overrides
the FAB$V_SUP option. When the create-if option is used with a search
list logical name and the file is not found in any of the file
specifications supplied using the search list, the file is created
using the file specification from the first element of the search list.
This option corresponds to the FDL attribute FILE CREATE_IF.
Maximize version number; indicates that the version number of the file
should be the maximum of the explicit version number given in the file
specification, or one greater than the highest version number for an
existing file in the same directory with the same file name and file
type. This option enables you to create a file with a specific version
number (if the requested version number is greater than that of the
existing file) or a file with a version number that is one higher than
the existing file's version number.
This option is used as input to the Create service only and it
corresponds to the FDL attribute FILE MAXIMIZE_VERSION (default is
Use NAM or NAML block inputs; indicates that the NAM or NAML block
whose address is contained in the FAB$L_NAM (name block address) field
provides the device, file, and/or the directory identification when a
file is being opened, closed, or erased (deleted). If a file is being
created, the field specifies the device and directory identification.
This option has no corresponding FDL attribute and it is not supported
for DECnet for OpenVMS operations.
Output file parse; specifies that related file resultant file
specification strings, if used, are to provide directory, file name,
and file type defaults only (requires NAM or NAML block).
This option corresponds to the FDL attribute FILE OUTPUT_FILE_PARSE.
Supersede existing file; allows an existing file to be superseded on a
Create service by a new file of the same name, type, and version. The
FAB$V_CIF and the FAB$V_MXV option take precedence over the FAB$V_SUP
This option corresponds to the FDL attribute FILE SUPERSEDE.
File Disposition Options
Delete file on Close; indicates that the file is to be deleted when
closed. This option may be specified for the Create, Open, or Close
services. However, if you set the bit when you create or open a file,
RMS deletes the file when you close it, regardless of the state of the
bit when you invoke the Close service.
You can specify the FAB$V_DLT option with the FAB$V_SCF or FAB$V_SPL
This option corresponds to the FDL attribute FILE DELETE_ON_CLOSE.
Submit command file on Close; indicates that the file is to be
submitted as a batch-command file to the process-default batch queue
(SYS$BATCH) when the file is closed. This option can be specified for
the Create, Open, and Close services. However, if you set the bit when
you create or open a file, RMS submits the file to SYS$BATCH when you
close it, regardless of the state of the bit when you invoke the Close
The FAB$V_SCF option applies to sequential files only and it
corresponds to the FDL attribute FILE SUBMIT_ON_CLOSE.
Spool file on Close; indicates that the file is to be spooled to the
process-default print queue (SYS$PRINT) when the file is closed. This
option can be specified for the Create, Open, or Close services.
However, if you set the bit when you create or open a file, RMS spools
the file to SYS$PRINT when you close it, regardless of the state of the
bit when you invoke the Close service.
The FAB$V_SPL option applies to sequential files only and it
corresponds to the FDL attribute FILE PRINT_ON_CLOSE.
Temporary file marked for delete; indicates that a temporary file is to
be created but is to be deleted when the file is closed. This option is
input only to the Create service. The FAB$V_TMD option takes precedence
over the FAB$V_TMP option.
This option corresponds to the FDL attribute FILE TEMPORARY.
Temporary file; indicates that a temporary file is to be created and
retained, but that no directory entry is to be made for it. This option
is used solely as input to the Create service. If you have a NAM or
NAML block, you are given the file identification (FID) of the file,
which you can use to reopen the file. If you do not have a NAM or NAML
block or if you do not save the FID, the file becomes inaccessible once
it is closed. The FAB$V_TMD option overrides the FAB$V_TMP option.
This option corresponds to the FDL attribute FILE DIRECTORY_ENTRY
("NO" means this bit is set).
Magnetic Tape Processing Options
Do not position to end of file; inhibits positioning to the end of a
file when a tape file is opened and the FAB$B_FAC (file access) field
indicates a Put service.
This option corresponds to the FDL attribute FILE MT_NOT_EOF.
Current position; directs RMS to position the magnetic tape volume set
immediately after the most recently closed file (the current position)
when it opens the next file. If you use this option when you invoke the
Create service, RMS begins overwriting data beginning with the current
The FAB$V_POS option corresponds to the FDL attribute FILE
MT_CURRENT_POSITION and is superseded by the FAB$V_RWO option, where
Rewind file on Close; specifies that the magnetic tape volume is to be
rewound when the file is closed. This option can be specified for the
Close, Create, or Open services.
This option corresponds to the FDL FILE attribute MT_CLOSE_REWIND.
Rewind on Open; specifies that the magnetic tape volume is to be
rewound before the file is opened or created. If you use this option
when you invoke the Create service, RMS overwrites the tape beginning
with the first file. The FAB$V_RWO option takes precedence over the
This option corresponds to the FDL FILE attribute MT_OPEN_REWIND and
takes precedence over the FAB$V_POS option, where applicable.
Nonstandard Processing Options
Non-file-structured; indicates (on an Open or Create service) that the
volume is to be processed in a non-file-structured manner. This option
allows the use of volumes created on non Compaq systems.
The FAB$V_NFS option corresponds to the FDL attribute FILE
NON_FILE_STRUCTURED and it is not supported for DECnet for OpenVMS
User file open; indicates that RMS operations for this file are limited
to opening it or creating it. To perform additional processing of the
invoke the $QIO system service using the channel number returned by RMS
in the status value field (FAB$L_STV). This channel is assigned the
access mode of the caller unless otherwise specified by the
If you specify this option, you must set the FAB$B_SHR field
FAB$V_UPI bit option unless the file is not shared (FAB$B_SHR field
FAB$V_NIL option is set). For the Create service, the end-of-file mark
is set to the end of the block specified in the FAB$L_ALQ field on
input. For either the Open or Create services, the FAB$W_IFI field is
set to 0 on return to indicate that RMS cannot perform any more
operations (including the Close service) on the file. If you set the
FAB$V_UFO option with the Open or Create service, the channel needs
only to be deassigned when you finish with the file.
This option corresponds to the FDL attribute FILE USER_FILE_OPEN and it
is not supported for DECnet for OpenVMS operations.
Asynchronous; indicates that the specified task is to be done
asynchronously. The FAB$V_ASY option is relevant only to file tasks
that involve I/O operations. The asynchronous I/O option is typically
used with success/error ASTs, or in conjunction with the $WAIT service,
to synchronize the program with task completion. When you specify
FAB$V_ASY, you pass the address of the FAB as an argument to the AST
routine and RMS returns control to your program immediately.
This option corresponds to the FDL attribute FILE ASYNCHRONOUS.
Deferred write; indicates that writing back to the file of modified I/O
buffers is to be deferred until the buffer must be used for other
purposes. This option applies to relative files, indexed files, and
sequential files opened for shared access.
This option corresponds to the FDL attribute FILE DEFERRED_WRITE and is
not supported for DECnet for OpenVMS operations.
Sequential only; indicates that the file can be processed only in a
sequential manner, permitting certain processing optimizations. Any
attempt to perform random access results in an error. The FAB$V_SQO
option is input to the Create and Open services.
This option corresponds to the FDL attribute FILE SEQUENTIAL_ONLY.
For DECnet for OpenVMS operations, this option enables file transfer
mode for Get, Put, Read, and Write services. File transfer mode is a
Data Access Protocol (DAP) feature that allows several records to be
transferred in a single-network I/O operation to maximize throughput
for single-direction, sequential access file transfer.
Synchronous status; returns the success status RMS$_SYNCH if the
requested service completes its task immediately. The most common
reason for not completing a task immediately is that the task involves
I/O operations. If the service completes synchronously (that is, it has
not returned to caller's execution mode prior to completion), RMS
returns RMS$_SYNCH as the completion status in R0, stores the true
completion status (success or failure) in FAB$L_STS, and does not
deliver an AST.
The FAB$V_SYNCSTS option is best used in conjunction with the FAB$V_ASY
The system returns RMS$_SYNCH status in R0. Refer to the FAB$L_STS
field for the actual success status or failure status of the task.
Read-check; specifies that transfers from disk volumes are to be
checked by a read-compare operation, which effectively doubles the
amount of disk I/O at some increase in reliability. This option is an
input to the Open and Create services. If FAB$V_RCK is set, then
checking is performed for the duration of the access. The FAB$V_RCK
option is also an output of the Open service, which indicates the
default for the file. This option is not available for RX01 and RX02
devices, or for any device that has been mounted using the DCL command
This option corresponds to the FDL attribute FILE READ_CHECK.
Write-check; indicates that transfers to disk volumes are to be checked
by a read-compare operation. The FAB$V_WCK option is similar to the
FAB$V_RCK option. This option is not available for RX01 and RX02
devices, or for any device that has been mounted using the DCL command
This option corresponds to the FDL attribute FILE WRITE_CHECK.
4.18 FAB$B_FSZ Field
The fixed-length control area size (FSZ) field is used only for
variable with fixed-length control (VFC) records. When you create a
file with this record type, you must set the value for the
fixed-control area before you issue the Create service. When you open
an existing file that contains
variable with fixed control records, RMS sets this field equal to the
value specified when the file was created. The FAB$B_FSZ field is not
applicable to indexed files.
This field corresponds to the FDL attribute RECORD CONTROL_FIELD_SIZE.
This field contains a numeric value in the range of 1 to 255 that
indicates, in bytes, the size of the fixed control area; the default
size is 2 bytes. If you do not specify a value or specify 0, then the
default size is used.
4.19 FAB$W_GBC Field
The global buffer count (GBC) field indicates the requested number of
global buffers for a file. This field contains a numeric value in the
range of 0 to 32,767; the default is 0.
Global buffers support sharing of I/O buffers by more than one process.
The use of global buffers can minimize I/O operations for a shared
file, thus reducing record access time at the cost of using additional
system resources. RMS is able to locate requested records (or blocks)
in the global buffers associated with this file, which it can read
directly from memory, eliminating much I/O. However, since global
buffers use global sections, the value contained in FAB$W_GBC is
limited by systemwide restrictions on resources determined by the
system parameters GBLSECTIONS (number of global sections), GBLPAGES
(number of global page table entries), and GBLPAGFIL (number of
systemwide pages allowed for global page-file sections, or scratch
global sections). For a complete description of these parameters, see
the OpenVMS System Management Utilities Reference Manual.
If global buffers are specified for a file, global buffers are used
instead of local (process) buffers, with the exception of deferred
write operations (FAB$L_FOP field FAB$V_DFW option).
The value that is specified when the file is created is returned in the
FAB$W_GBC field as output from the Open service. This value is then
used as input to the Connect service.
If you want to override the default value specified when the file was
created, you can set a different value in the FAB$W_GBC field after
opening the file but before invoking the Connect service. If you do not
want to use global buffers, you can clear the field before issuing the
Connect service if the default value is not 0.
If you modify the value in the FAB$W_GBC field that is returned from
the Open service prior to the Connect service, this action determines
whether or not global buffers are assigned to your process.
If you want to permanently change the default global buffer count value
for the file, use the following command syntax:
SET FILE file-spec /GLOBAL_BUFFERS=buffer-count
If you want to permanently clear the default global buffer count for a
file, use the following command syntax:
SET FILE file-spec /GLOBAL_BUFFERS=0
You can also vary the number of global buffers used each time you
process the file. If you choose this method, you change (or clear) the
FAB$W_GBC field after you open the file, but before you invoke the
Connect service. In this case, the specified value is assigned to the
FAB$W_GBC field, or the FAB$W_GBC field remains clear only for the
current processing of the file; that is, you do not permanently alter
the FAB$W_GBC field in the FAB. If no value is specified in the
FAB$W_GBC field when the file is created, the default value is 0.
The number of global buffers for a file is determined by the first
record stream to connect to the file (systemwide). If the file is
already open and connected, then the number of global buffers is
already set and modifications made before the Connect service are
useful only to request that this process use (or not use) global
To specify a read-only global buffer cache, the initial accessor must
set the FAB$B_SHR field FAB$V_SHRGET and FAB$V_MSE bits on. Selecting
the FAB$V_MSE option turns on locking to coordinate access to the
global buffer cache.
You can use global buffers for all file organizations opened for shared
record access. If the global buffer count is nonzero for the first
process that connects to the file, then a temporary global section that
is large enough to contain the specified number of buffers (as well as
internal RMS data structures) is created and mapped. This section is
mapped by processes that subsequently connect to the file, thus
allowing multiple processes to reference a single set of one or more
buffers without performing additional I/O operations. Thus, the first
user to open the file requesting global buffers determines the number
of the global buffers.
For shared sequential file operations, the value stored in the
RAB$B_MBC field establishes the global buffer size. See Section 7.11
for more information.
The FAB$W_GBC field corresponds to the FDL attribute FILE
GLOBAL_BUFFER_COUNT and it is not supported for DECnet for OpenVMS