HP OpenVMS Systems Documentation

OpenVMS Record Management Services Reference Manual

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 NAME.

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 NAME.

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:

FOP=SPL

As detailed in the appropriate descriptions, the only file-processing option 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.

Allocation and Extension Options

FAB$V_CBT

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 indexed file.

This option corresponds to the FDL attribute FILE BEST_TRY_CONTIGUOUS.

FAB$V_CTG

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 FAB$V_CTG option.

This option corresponds to the FDL attribute FILE CONTIGUOUS.

FAB$V_TEF

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

FAB$V_CIF

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.

FAB$V_MXV

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 "YES").

FAB$V_NAM

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.

FAB$V_OFP

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.

FAB$V_SUP

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 option.

This option corresponds to the FDL attribute FILE SUPERSEDE.

File Disposition Options

FAB$V_DLT

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 option.

This option corresponds to the FDL attribute FILE DELETE_ON_CLOSE.

FAB$V_ERL

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.

FAB$V_SCF

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 service.

The FAB$V_SCF option applies to sequential files only and it corresponds to the FDL attribute FILE SUBMIT_ON_CLOSE.

FAB$V_SPL

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.

FAB$V_TMD

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.

FAB$V_TMP

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

FAB$V_NEF

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.

FAB$V_POS

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 tape position.

The FAB$V_POS option corresponds to the FDL attribute FILE MT_CURRENT_POSITION and is superseded by the FAB$V_RWO option, where applicable.

FAB$V_RWC

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.

FAB$V_RWO

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 FAB$V_POS option.

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

FAB$V_NFS

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 operations.

FAB$V_UFO

User file open; indicates that RMS operations for this file are limited to opening it or creating it. To perform additional processing of the file, 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 FAB$V_CHAN_MODE bits.

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.

Performance Options

FAB$V_ASY

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.

FAB$V_DFW

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.

FAB$V_SQO

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 services.

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.

FAB$V_SYNCSTS

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 option.

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.

Reliability Options

FAB$V_RCK

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 MOUNT/FOREIGN.

This option corresponds to the FDL attribute FILE READ_CHECK.

FAB$V_WCK

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 MOUNT/FOREIGN.

This option corresponds to the FDL attribute FILE WRITE_CHECK.

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.