Document revision date: 30 March 2001

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.

Table 4-3 File Processing Options

Option	Symbolic Offset
Allocation and Extension Options
Contiguous best try	FAB$V_CBT
Contiguous allocation	FAB$V_CTG
Truncate at end of file	FAB$V_TEF
File Name Parsing Modifier Options
Create-if	FAB$V_CIF
Maximum version number	FAB$V_MXV
Use NAM or NAML block inputs	FAB$V_NAM
Output file parse	FAB$V_OFP
Supersede existing file	FAB$V_SUP
File Disposition Options
Delete on close	FAB$V_DLT
Submit command file on close	FAB$V_SCF
Spool file on close	FAB$V_SPL
Temporary marked for delete	FAB$V_TMD
Temporary file	FAB$V_TMP
Magnetic Tape Processing Options
Do not set to EOF	FAB$V_NEF
Current position	FAB$V_POS
Rewind file on close	FAB$V_RWC
Rewind file on open	FAB$V_RWO
Nonstandard Processing Options
Non-file-structured	FAB$V_NFS
User file open	FAB$V_UFO
Performance Options
Asynchronous operation	FAB$V_ASY
Deferred write	FAB$V_DFW
Sequential only	FAB$V_SQO
Synchronous status	FAB$V_SYNCSTS
Reliability Options
Read-check	FAB$V_RCK
Write-check	FAB$V_WCK

This field corresponds to the FDL primary attribute FILE.

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_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

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.

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

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.

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

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

	privacy and legal statement
4523PRO_005.HTML