HP OpenVMS Systems Documentation
OpenVMS Record Management Services Reference Manual
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 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.
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
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.
The journal field provides flags to identify whether a file is marked for journaling and to identify, where applicable, the type of journaling:
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:
There are no corresponding FDL attributes for the journaling flags because they cannot be set through the FDL interface.
4.22 FAB$V_LNM_MODE Subfield
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 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.
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.
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.
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.
1The FSZ represents the size, in bytes, of the fixed control area in a record having VFC record format. On a disk device, the length of the largest record in a sequential file using variable or VFC format is also maintained by RMS and is available through the longest record length field (XAB$W_LRL) in the file header characteristics XAB (XABFHC). See Chapter 11.
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.
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.
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.
4.27 FAB$B_RAT Field
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.