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
Erase regardless of lock
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.
Erase regardless of lock; allows a file open for write access to be
marked for delete by the $ERASE service. The erase operation will
complete once the file's reference count reaches zero.
This option can only be specified for the Erase service.
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.
Local File Accesses
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. This option is
restricted to sequential files and is ignored for all other file
organizations. The FAB$V_SQO option is input to the Create and Open
Remote DECnet Accesses
For OpenVMS DECnet operations, this option has an added meaning. When
set for a remote file access, it indicates that file transfer mode
(FTM) should be used 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 sequential access file transfers.
While the file transfer mode (FTM) feature for the SQO option is
applied regardless of file organization to remote accesses, FTM has
restrictions to make it consistent with the sequential only meaning
applied to local accesses. For a remote file access, FTM is restricted
to sequential access; if FTM is requested (FAB$V_SQO option set), a
keyed or RFA record access will fail with an RMS-F-FTM error (network
file transfer mode precludes operation (SQO set)). For record I/O, FTM
is also restricted to Gets or Puts; Updates or Deletes, if attempted,
will fail with the RMS-F-FTM error.
The transmitting of records as a block of data, of course, results in
performance improvement; what is not as obvious is that some of the
improvement is due to the fact that the Data Access Protocol (DAP)
eliminates much of its messaging for the FTM feature. Messages are not
sent between the local and remote systems on a record-by-record basis
but rather for the whole block of records transferred. This can result
in apparent inconsistencies in what a reader sees when FTM is used.
While the RMS default locking behavior does not change when FTM is
used, by the time the record is in your buffer on the local system, the
record may have already been updated or deleted by another process that
is not using FTM. If a locking collision happens on the remote system
when the records are being loaded into the message buffer, then the
locking error will not be returned until the end of the transfer. When
using the file transfer mode (SQO) feature with shared write access to
a remote file, you should expect to see the same kind of
inconsistencies in reading data as you see when the read-regardless
(RRL) option is set. To avoid the possibility of a hang that may be
induced by retrying remote accesses after a record lock error, you are
advised to set both the no-lock (NLK) and read-regardless (RRL) options
in the RAB$L_ROP in applications that use the file transfer mode (SQO)
feature for remote file accesses. (The no query locking (NQL) option is
not supported by the DAP protocol for remote files.)
This option corresponds to the FDL attribute FILE SEQUENTIAL_ONLY.
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.