Document revision date: 19 July 1999

The internal file identifier (IFI) field associates the FAB with the corresponding internal file access block. RMS sets this field on successful Create or Open services. It is then an input for subsequent Close, Connect, Display, and Extend services. The Close service deallocates the internal control structures and clears the FAB$W_IFI field. When the user file open (FAB$V_UFO) option in the FAB$L_FOP field is specified, no internal structures are allocated on Create or Open services. Therefore, the FAB$W_IFI field remains cleared.

There is no FDL equivalent for this field.

4.21 FAB$B_JOURNAL Field (VAX Only)

On VAX systems, the journal field provides flags to identify whether a file is marked for journaling and to identify, where applicable, the type of journaling:

• After-image (AI) journaling
• Before-image (BI) journaling
• Recovery unit (RU) journaling

You can obtain additional information about a file marked for journaling using the journaling XAB. For example, you can obtain the name of the after-image journal file, and so forth.

Here is a code example showing how you might use the Open service to determine if a file is marked for RU journaling. In the example, the program opens a file and branches to a label FILE_MARKED_FOR_RU if the file is marked for RU journaling:

$OPEN FAB = MY_FAB BLBC R0,ERROR BBS #FAB$V_RU,FAB$B_JOURNAL+MY_FAB,- FILE_MARKED_FOR_RU

Each journaling flag in the field has a unique symbolic bit offset and mask value. For example, the after-image journaling flag has the symbolic bit offset FAB$V_AI and the constant value FAB$M_AI. If a flag is set, the logical value is 1; if it is reset, the logical value is 0.

There are no corresponding FDL attributes for the journaling flags because they cannot be set through the FDL interface.

A listing of symbolic offsets for each of the journaling flags follows:

Flags

FAB$V_AI

The file is marked for after-image journaling.

FAB$V_BI

The file is marked for before-image journaling.

FAB$V_RU

The file is marked for recovery unit journaling.

The logical name translation access mode (LNM_MODE) subfield is the part of the FAB$B_ACMODES field that specifies the RMS access mode used to translate logical names during parsing.

The FAB$V_LNM_MODE subfield may contain one of these four values, with the related constant value for each shown in parentheses:

0	None
1	Executive mode (PSL$C_EXEC)
2	Supervisor mode (PSL$C_SUPER)
3	User mode (PSL$C_USER)

The default value is 0 (none), which RMS interprets as user mode.

The FAB$V_LNM_MODE field is not supported for DECnet for OpenVMS operations, and it is ignored during remote file access.

There is no corresponding FDL equivalent for this field. For more information about logical name concepts, see the OpenVMS Programming Interfaces: Calling a System Routine.

4.23 FAB$L_MRN Field

The maximum record number (MRN) field applies only to relative files and indicates the highest record number that can be written to a file.

This field contains a numeric value of the highest numbered record allowed in the file, in the range of 0 to 2,147,483,647, although the maximum value depends on the number of blocks on the device to be used. The default for this field is 0.

If you attempt to write (put) or retrieve (get) a record with a relative record number higher than the specified limit, an error occurs and RMS returns a message indicating an invalid record number. Checking is suppressed if you specify 0 for the FAB$L_MRN field.

Note that RMS does not maintain the relative record number of the highest existing record in the file.

This field corresponds to the FDL attribute FILE MAX_RECORD_NUMBER.

4.24 FAB$W_MRS Field

The maximum record size (MRS) field defines the size of all records in a file with fixed-length records, the maximum size of variable-length records, the maximum size of the data area for variable with fixed-length control records, and the cell size (minus overhead) for relative files.

This field contains a numeric value in the range applicable to the file type and record format (see Table 4-4) that indicates the size of the records in the file, in bytes. This value specifies the number of bytes of data and does not include any control bytes associated with each record.

For fixed-length records, the value represents the actual size of each record in the file. You must specify a size when you create a file with fixed-length records.

For variable-length records, the value represents the size of the largest record that can be written into the file. If the file is not a relative file, a value of 0 is used to suppress record size checking, thus indicating that there is no user limit on record size, except for the limitations listed in Table 4-4 and certain physical limitations. For magnetic tape files, a value of 0 sets an effective maximum record size that is equal to the block size minus 4.

The size of variable-length records must conform to physical limitations. With indexed and relative files, for example, records may not cross bucket boundaries. If both the FAB$B_BKS and FAB$W_MRS fields are 0 (not specified) for an indexed file, RMS attempts to calculate a reasonable bucket size, usually 2. Thus, if any record requires more than two buckets, you must explicitly specify the required value for the FAB$B_BKS or the FAB$W_MRS field. If the FAB$B_BKS field is specified, the value should specify a bucket size large enough to exceed the longest possible record.

For variable with fixed-length control records, the value includes only the data portion; it does not include the size of the fixed control area.

For all relative files, the size is used in conjunction with the FAB$B_BKS field to determine the size of the record cell. You must specify the FAB$W_MRS field when you create a relative file.

You specify a value when you invoke a Create service. RMS returns the maximum record size when you invoke an Open service.

Table 4-4 summarizes the maximum record size allowed for the various file and record formats.

Table 4-4 Maximum Record Size for File Organizations and Record Formats

File Organization	Record Format	Maximum Record Size
Sequential	Fixed length	32,767
Sequential (disk)	Variable length	32,767
Sequential (disk)	VFC	32,767-FSZ 1
Sequential (disk)	Stream	32,767
Sequential (disk)	Stream-CR	32,767
Sequential (disk)	Stream-LF	32,767
Sequential (ANSI tape)	Variable length	9,995
Sequential (ANSI tape)	VFC	9,995-FSZ 1
Relative	Fixed length	32,255
Relative	Variable length	32,253
Relative	VFC	32,253-FSZ 1
Indexed, Prolog 1 or 2	Fixed length	32,234
Indexed, Prolog 1 or 2	Variable length	32,232
Indexed, Prolog 3	Fixed length	32,224
Indexed, Prolog 3	Variable length	32,224

For DECnet for OpenVMS remote file access, the maximum record size may be set by the /NETWORK_BLOCK_COUNT=n qualifier to the SET RMS_DEFAULT command or by a $XABITM parameter. DECnet for OpenVMS remote file access can support record sizes as large as the record sizes that RMS supports. The default number of blocks is equal to the system parameter RMS_DFNBC, the default for which is 8 blocks (4096 bytes). For more information about the SET RMS_DEFAULT command, see the OpenVMS DCL Dictionary. The system parameters are detailed in the OpenVMS System Management Utilities Reference Manual.

This field corresponds to the FDL attribute RECORD SIZE.

4.25 FAB$L_NAM Field

The name block field specifies the address of either the name (NAM) block (see Chapter 5) or the long name (NAML) block (see Chapter 6) used to invoke a file service, such as an Open or Create. On Alpha systems, the NAML block can optionally take the place of a NAM block. The NAML allows OpenVMS Alpha users to locate and use file specifications that are longer than 255 bytes.

The NAM or NAML block is required only in conjunction with the file specification processing services. Both can also be used with other services, typically to obtain a file specification string after all logical name translation is completed and all defaults applied.

To allow for appropriate type checking of a NAML block, FAB$L_NAML is available as an alternative definition for C programmers who are using a NAML block.

For further information, see Section 4.17 and Chapter 6.

4.26 FAB$B_ORG Field

The file organization (ORG) field assigns the organization of the file.

The FAB$B_ORG field is a keyword value field in which each file organization has a symbolic value. Options are identified using 3-letter mnemonics. Each option in the FAB$B_ORG field has its own symbolic constant value. For example, the relative (REL) file organization has a constant value of FAB$C_REL.

You must set this field before you invoke a Create service. RMS returns the contents of this field when you invoke an Open service. The options are described in the following list:

• FAB$C_IDX --- Indexed file organization
• FAB$C_REL --- Relative file organization
• FAB$C_SEQ --- Sequential file organization (default)

The record attributes (RAT) field specifies control information associated with each record in a file, including carriage control information, block boundary control, and count byte formatting for variable-length records. Within the FAB$B_RAT field, each control bit has a unique symbolic offset and constant value. For example, the CR (carriage return) control bit has a symbolic offset of FAB$V_CR and a mask value of FAB$M_CR.

For most programs, the default value for the carriage control is FAB$V_CR (carriage return). When you create your own file, however, the default value is 0. When you want to create a stream format file or a file containing ASCII text, specify the FAB$V_CR option for the Create service. RMS sets this field when you invoke an Open service.

When a process-permanent file is accessed indirectly for output, the value in this field is always an input value. Therefore, RMS automatically uses the process-permanent file's record attributes.

This field corresponds to the FDL primary attribute RECORD.

Options

FAB$V_CR

Indicates that each record is to be preceded by a line feed and followed by a carriage return when the record is written to a carriage control device such as a line printer or terminal.

This option corresponds to the FDL attribute RECORD CARRIAGE_CONTROL CARRIAGE_RETURN. It cannot be used with either the FAB$V_FTN option or the FAB$V_PRN option.

FAB$V_FTN

Indicates that the first byte of each record contains a FORTRAN (ASA) carriage control character.

This option corresponds to the FDL attribute RECORD CARRIAGE_CONTROL FORTRAN. Records are defined as follows:

Byte 0 Value (Hex)	ASCII Character	Meaning
0	(null)	Null carriage control (sequence: print buffer contents).
20	(space)	Single-space carriage control (sequence: line feed, print buffer contents, carriage return).
30	0	Double-space carriage control (sequence: line feed, line feed, print buffer contents, carriage return).
31	1	Page eject carriage control (sequence: form feed, print buffer contents, carriage return).
2B	+	Overprint carriage control (sequence: print buffer contents, carriage return). Allows double printing for emphasis.
24	$	Prompt carriage control (sequence: line feed, print buffer contents).
Other values		Same as ASCII space character: single-space carriage control.

The FAB$V_FTN option cannot be used with either the FAB$V_CR option or the FAB$V_PRN option.

FAB$V_PRN

Indicates print file format for variable-length records having 2-byte fixed-length control fields, where the fixed-length control area contains the carriage control specification. The first byte of the control area constitutes a "prefix" area, that is, action to be taken before printing the record. The second byte constitutes a "suffix" area, that is, action to be taken after printing the record.

The following table shows the coding scheme for both control bytes (even though they are interpreted separately):

Bit 7	Bit 6	Bit 5	Bit 4	Meaning
0	0	0	0	To specify no carriage control (NULL), set bits 3 through 0 at 0.
0	x	x	x	Use bits 6 through 0 to specify a count of new lines (line feed followed by carriage return).
1	0	0	x	Output the ASCII C0 control character specified by the configuration of bits 4 through 0.
1	0	1	x	Reserved.
1	1	0	0	Skip to the vertical format unit (VFU) channel (1--16) specified by bits 3 through 0. Devices that do not have hardware VFUs translate these codes as a 1-line advance.
1	1	0	1	Reserved.
1	1	1	0	Reserved.

This option corresponds to the FDL attribute RECORD CARRIAGE_CONTROL PRINT. It cannot be used with either the FAB$V_CR option or the FAB$V_FTN option.

FAB$V_BLK

Applicable to sequential files only; indicates that records are not permitted to cross block boundaries. The FAB$V_BLK record attribute option may be used with any one of the other record attribute options (FAB$V_CR, FAB$V_FTN, or FAB$V_PRN), but it cannot be used with files that use the STREAM record format.

This option corresponds to the FDL attribute RECORD BLOCK_SPAN.

FAB$V_MSB

The state of this control bit determines whether the format for the 2-byte count field that is prefixed to each variable-length record is formatted as LSB or MSB. If the bit is set, RMS reads the contents of the 2-byte count field using the most significant byte as the high-order byte. The 2-byte count field contains the number of bytes in the associated variable-length record.

This option corresponds to the FDL attribute RECORD MSB_RECORD_LENGTH.

The record format (RFM) field specifies the format for all the records in a file.

The FAB$B_RFM field is a keyword value field where each record format has a symbolic value. Options are identified by mnemonics. Each option has its own symbolic constant value. For example, the FIX (fixed) record format has a symbolic constant value of FAB$C_FIX; the STMCR (stream with carriage return) record format has a symbolic constant value of FAB$C_STMCR.

When you create the file, you must set this field before you invoke the Create service. RMS returns the record format when you invoke an Open service. The record format options are described under Options.

This field corresponds to the FDL attribute RECORD FORMAT.

Options

FAB$C_FIX

Indicates fixed-length record format.

This option corresponds to the FDL attribute RECORD FORMAT FIXED.

FAB$C_STM

Indicates stream record format. Records are delimited by FF, VT, LF, or CR LF, and all leading zeros are ignored. This format applies to sequential files only and cannot be used with the block spanning option.

This option corresponds to the FDL attribute RECORD FORMAT STREAM.

FAB$C_STMCR

Indicates stream record format. Records are delimited by CR. This format is supported for sequential files only.

This option corresponds to the FDL attribute RECORD FORMAT STREAM_CR.

FAB$C_STMLF

Indicates stream record format. Records are delimited by LF. This format is supported for sequential files only.

This option corresponds to the FDL attribute RECORD FORMAT STREAM_LF.

FAB$C_UDF

Indicates undefined record format. The undefined record format is valid for sequential files only. This is the default value if the FAB is not initialized with a $FAB macro.

This option corresponds to the FDL attribute RECORD FORMAT UNDEFINED.

FAB$C_VAR

Indicates variable-length record format. For the $FAB macro, this is the default value.

This option corresponds to the FDL attribute RECORD FORMAT VARIABLE.

FAB$C_VFC

Indicates variable-length with fixed-length control record format. This format is not supported for indexed files.

This option corresponds to the FDL attribute RECORD FORMAT VFC.

If you intend to use stream record format, then specify the FAB$V_CR record attribute (see FAB$B_RAT).

4.29 FAB$B_RTV Field

The retrieval window size (RTV) field specifies the number of retrieval pointers RMS is to maintain in memory for the file. Retrieval pointers are stored in the file header and indicate the beginning of each extent associated with the file. If a file has been extended repeatedly, the extents may be scattered noncontiguously on the disk, requiring numerous retrieval pointers. When RMS needs to access a new extent, it must obtain the retrieval pointer for that extent. RMS first looks for the retrieval pointer in the retrieval window, which contains the number of retrieval pointers specified by this field. If the retrieval pointer is not in the retrieval window, RMS reads the file header, thereby requiring an additional I/O operation.

This field contains a numeric value in the range of 0 through 127, or 255. A value of 0 directs RMS to use the system default number of retrieval pointers. A value of 255 means to map the entire file, if possible. If you specify a value of 255 when creating a file, the initial number of retrieval pointers is minimal; as records are added, however, the number of retrieval pointers increases as the number of extents increases. The system resources required for retrieval windows are subtracted from the buffered I/O quota of the process. Values from 128 to 254 (inclusive) are reserved for future use.

This field corresponds to the FDL attribute FILE WINDOW_SIZE and it is not supported for DECnet for OpenVMS operations.

	privacy and legal statement
4523PRO_006.HTML