HP OpenVMS Systems Documentation

OpenVMS Record Management Services Reference Manual

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:

If you want to permanently clear the default global buffer count for a file, use the following command syntax:

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.

4.20 FAB$W_IFI Field

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

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

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:

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 Concepts Manual, Volume II.

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.

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.