HP OpenVMS Systems Documentation
OpenVMS Record Management Services Reference Manual
4.4 FAB$B_BID Field
The block identifier (BID) field is a static field that identifies a
control block as a FAB. Once set, this field should not be altered
unless the control block is no longer needed. This field must be
initialized to the symbolic value FAB$C_BID (this is done by the $FAB
The bucket size (BKS) field is used only for relative or indexed files to specify the number of blocks in each bucket of the file.
This field contains a numeric value in the range of 0 to 63. If you do not specify a value or specify a value of 0, RMS uses a default of the minimum number of blocks needed to contain a single record, or a minimum of two records for indexed files. If the file will be processed by RMS-11, the bucket size must be less than or equal to 32 blocks.
When calculating the bucket size, you must consider the control information (overhead) associated with each bucket. Also, certain record types contain control bytes; thus, the number of records per bucket multiplied by the number of control bytes per record equals the number of record overhead bytes per bucket. See the Guide to OpenVMS File Applications for more information.
Before specifying a bucket size, you must be aware of the relationship between bucket size and record size. You must also consider any record control bytes (overhead) required for the type of record chosen. Because RMS does not allow records to cross bucket boundaries, you must ensure that the number of blocks per bucket conforms to formulas designed to handle one of the following:
You can use the Edit/FDL utility to determine the optimum bucket size. Note that if an allocation control XAB is specified, the value specified in the XAB$B_BKZ field supersedes the value specified in the FAB$B_BKS field. When multiple allocation control XABs are specified, the largest value in any XAB$B_BKZ field supersedes the value in the FAB$B_BKS field. Refer to Section 9.6 for information about the XAB$B_BKZ field.
When you open an existing relative or indexed file, RMS sets the FAB$B_BKS field to the defined size of the largest bucket size in the file. However, when you create a new relative or indexed file, set the FAB$B_BKS field before you invoke the Create service rather than use the default.
With indexed files, note that if the FAB$B_BKS field is not specified and a maximum record size (FAB$W_MRS field) is specified, then RMS selects a bucket size that allows at least one maximum size record to fit. Generally, performance for record insertion and sequential retrieval on the primary key improves if at least six or seven data records fit into a primary data bucket. If either the bucket size or the disk cluster size is other than one block, use a default extension quantity (FAB$W_DEQ) that is the least common multiple of the bucket size and cluster size to avoid allocated but unused blocks within the file.
This field corresponds to the FDL attribute FILE BUCKET_SIZE.
The block length (BLN) field is a static field that defines the length
of the FAB. Once set, this field should not be altered unless the
control block is no longer needed. This field must be initialized to
the symbolic value FAB$C_BLN (this is done by the $FAB macro).
RMS uses the block size (BLS) field as input for nondisk files. The BLS field usually defines the size, in bytes, of the blocks on a magnetic tape. Note that for some devices, this value must be an even number. This field corresponds to the FDL attribute FILE MT_BLOCK_SIZE.
The FAB$W_BLS field contains a numeric value in the range of 20 through 65,535 for ANSI-formatted tapes and 14 through 65,532 for foreign tapes. (Foreign tapes are those that are not in the standard ANSI format used by OpenVMS operating systems, and must be mounted using the DCL command MOUNT/FOREIGN.) If no value or a value of 0 is specified, the default selected when the volume was mounted is used.
When you create a magnetic tape file, you can set the FAB$W_BLS field before you invoke the Create service. In all other cases, RMS ignores this field. When you open an existing sequential file with an Open service, RMS returns the device buffer size. For terminals, this field defines the WIDTH setting; for mailboxes, this field defines the maximum message size.
For compatibility with RMS-11, RMS rounds off the block size for an ANSI-formatted tape to the next highest multiple of 4. For example, if you set the block length to 38, RMS sets it to 40. The block size of a foreign tape is not rounded off by RMS.
To create a magnetic tape for interchange with Compaq operating systems
other than OpenVMS systems, consult the documentation for the recipient
system to identify possible limitations on block size. ANSI standards
require that the block size be less than or equal to 2048 bytes.
The channel access mode protection (FAB$V_CHAN_MODE) subfield is part of the FAB$B_ACMODES field. The 2-bit FAB$V_CHAN_MODE subfield provides one of two functions:
4.8.1 Override Value
The access-mode protected files function ensures that accessors who are operating in an outer access mode cannot access files opened or created by inner-mode accessors. Access-mode protection includes memory and data structures that are interrelated to access-mode protected files.
When the user program seeks to override access-mode protection, it must
specify the value PSL$C_USER in the FAB$V_FAB$V_CHAN_MODE subfield.
There is no corresponding FDL equivalent for this field. The FAB$V_CHAN_MODE subfield is used locally for channel to DECnet for OpenVMS communications but is ignored on the remote system.
To set this field from MACRO level, you include the appropriate expression as an argument to the $FAB macro. For example, to specify supervisor channel access mode, you might include a statement in this format:
If you are using a high-level language, refer to your documentation as
to how (and whether) you can directly access RMS fields and then
incorporate the appropriate channel access mode expression into the
appropriate language statement.
The user context (CTX) field allows you to convey user information to a completion routine in your program. This field contains a user-specified value, up to four bytes long, and is intended solely for your use. RMS never uses it for record management activities.
This field corresponds to the FDL attribute FILE CONTEXT.
The default file extension quantity (DEQ) field specifies the number of blocks to be added when RMS automatically extends the file. Automatic extension only applies to files that reside on disk devices and occurs whenever your process invokes a Put or Write service and the currently allocated file space is exhausted. When you invoke a Put service, automatic file extension occurs when needed, regardless of the file organization. When you invoke the Write service, automatic extension occurs only for sequential files (indexed and relative files require the Extend service to extend file allocation).
This field corresponds to the FDL attribute FILE EXTENSION.
This field contains a numeric value in the range 0 through 65,535, which is rounded up to the next cluster boundary. A large value results in fewer file extensions over the life of a file; a small value results in numerous file extensions over the life of a file. When a file has numerous file extensions that may be noncontiguous, this slows record access.
If you do not specify a value or specify the value 0 when you create a file, RMS uses the default specified by the DCL command SET RMS_DEFAULT/EXTEND_QUANTITY. If this value is 0, RMS uses the system default extension quantity specified by the system parameter RMS_EXTEND_SIZE. If this value is 0, RMS computes the default value.
If the value in the FAB$W_DEQ field, the value set by the SET RMS_DEFAULT/EXTEND_QUANTITY command, and the value of the system parameter RMS_EXTEND_SIZE are all 0, RMS may provide an overly large value to minimize the number of extend operations that it must perform. At times, this value can exceed the available disk quota even though there is actually enough space for the file if only the required amount is used. You can use the DCL command SET RMS_DEFAULT/EXTEND_QUANTITY to limit (explicitly specify) the extension size to the recommended number of blocks. An appropriate size is the number of blocks specified as the cluster size for the device (set by the DCL command INITIALIZE/CLUSTER_SIZE). For large files on a volume where there is sufficient disk space, consider using a multiple of the cluster size to improve subsequent performance.
When creating a new file, you can specify the extension quantity for the file by setting the desired value in the FAB$W_DEQ field before or after invoking the Create service. This value becomes a permanent attribute for the file.
When processing an existing file, you can temporarily override the default extension quantity specified when the file was created. To do this, set the desired value before or after invoking the Open service. When you subsequently close the file, the default extension quantity reverts to the value set when the file was created.
See the discussion under FAB$B_BKS for indexed files.
The device characteristics (DEV) field allows your program to obtain the generic characteristics of the device containing the file. You can locate and test the various bits in the field using symbolic offsets. RMS returns a value in this binary options field when you invoke an Open, Create, or Display Service. RMS also returns a value in this field for the Parse service unless you take the syntax check option (NAM$V_SYNCHK in the NAM$B_NOP field is clear).
Table 4-2 describes the bits in the device characteristics field. Each bit has its own symbolic bit offset and mask value. These definitions are made available to your program by referring to the $DEVDEF macro in SYS$LIBRARY:STARLET.MLB. The symbolic bit offset is formed by prefixing the characteristic name with DEV$V_. The mask value is formed by prefixing the characteristic name with DEV$M_. For example, the DEV$V_REC bit has a mask value of DEV$M_REC.
For DECnet for OpenVMS operations, this field represents the actual
characteristics of the target device when a Create, Open, or Display
service is invoked. It is not filled in when a Parse service is invoked
using a file specification that contains a node name.
The default file specification string address (DNA) field provides the address of a file specification string RMS uses to apply defaults for any missing components of the file specification. This field works with the FAB$B_DNS field, which initializes the default file specification string size, to provide a default file specification string. Defaults are applied after RMS examines the primary file specification string to which the FAB$L_FNA field (described in Section 4.15) points.
This field and the FAB$B_DNS field correspond to the FDL attribute FILE DEFAULT_NAME.
The FAB$L_DNA field contains the symbolic address of a default file specification string, which is an ASCII string containing one or more components of a file specification. The components in the string must be in the order in which they would occur in a complete file specification.
The FAB$L_DNA (input only) field is equivalent to the NAML$L_LONG_DEFNAME field of the long name (NAML) block. See Chapter 6 for more information.
The default file specification string is used primarily when a process accepts file specifications interactively; normally, file specifications known to a user program are specified completely in the FAB$L_FNA and FAB$B_FNS fields. You can specify defaults for one or more of the following file specification components:
The default file specification string is used only if components are
missing from the string whose address is stored in the FAB$L_FNA field
and those components are present in the default file specification
The default file specification string size (DNS) field indicates the size, in bytes, of the string whose address is contained in the FAB$L_DNA field. This field contains a numeric value in the range 0 to 255.
This field and the FAB$L_DNA field correspond to the FDL attribute FILE
The file access (FAC) field specifies the operations and services a process is seeking to use in accessing a file. RMS uses this field, together with the share field (SHR) in each potential accessor's FAB, to determine whether to permit a process to access a file. The FAC field corresponds to the FDL primary attribute ACCESS.
Within the FAC field, each bit position corresponds to an operation or service option that the process intends to use when accessing the file. In this manner, a process may specify several options, assuming they are compatible, by setting the appropriate bits. Each option has its own symbolic bit offset and mask value. For example, the GET service option has a symbolic bit offset of FAB$V_GET and a mask value of FAB$M_GET.
RMS determines whether or not the process seeking access to the file intends to use operations and services that are compatible with the sharing options permitted by processes currently accessing the file. It checks the FAC field of the requesting process to determine whether it requires read or write access to the file. It then checks the SHR field of the requesting process to determine whether it will share read or write access with other processes that are accessing the file. A read (GET) implies read access. Delete (DEL), write (PUT), truncate (TRN), and update (UPD) all imply write access.
For example, assume that Process A opens the file for GET access (FAC=GET) and is willing to share the file with processes that are doing GET and PUT accesses (SHR=GET,PUT). Since this is the only process accessing the file, RMS permits it to read access the file.
Assume that a second process, Process B, wants to access the same file doing PUT accesses (FAC=PUT) and is willing to share the file with processes doing GET accesses and PUT accesses (SHR=GET,PUT). Because Process B is compatible with Process A (they both agree to share the file with any process that is doing either GET accesses or PUT accesses), RMS permits the second process to access the file.
Now assume that a third process, Process C, wants GET access (FAC=GET) to the same file but will share the file only with processes doing GET accesses (SHR=GET). Although Process C is compatible with Process A (FAC=GET), it is not compatible with Process B (FAC=PUT), so RMS denies Process C access to the file. Conversely, if C tries to access the file before B, C gets access and B is denied access.
RMS always grants file access to the first process accessing a file, assuming no security access restrictions exist. When a process acquires access to a file, RMS rejects any attempt to use a service not included in the initial access request.