Updated: 11 December 1998

OpenVMS Record Management Services Reference Manual

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 macro).

4.5 FAB$B_BKS Field

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:

• Relative files with fixed-length records
• Relative files with variable-length records
• Relative files with VFC (variable with fixed control) records
• Indexed files with fixed-length records
• Indexed files with variable-length records

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.

4.6 FAB$B_BLN Field

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

4.7 FAB$W_BLS Field

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.

4.8 FAB$V_CHAN_MODE Subfield

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:

• For standard processing, where neither the FAB$V_NFS nor FAB$V_UFO option is selected in the FAB$L_FOP field, the user program can use the FAB$V_CHAN_MODE subfield to override the access-mode protected files function.
• When the user program specifies a nonstandard processing option by selecting either non-file-structured operations (FAB$V_NFS) or a user-file-open operation (FAB$V_UFO), RMS uses the FAB$V_CHAN_MODE subfield to assign the calling program's access mode to the I/O channel.

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.

4.8.2 Channel Access Mode Function

When used to specify the channel access mode, the FAB$V_CHAN_MODE subfield can contain one of the following 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 is interpreted by RMS as executive mode.

If the access mode requested is more privileged than the access mode of the calling process, RMS uses the access mode of the caller and does not return an error.

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:

$FAB ...,CHAN_MODE = PSL$C_SUPER,...

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.

4.9 FAB$L_CTX Field

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.

4.10 FAB$W_DEQ Field

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.

Note that the use of an allocation control XAB overrides the value in this field. See Chapter 9 for a detailed description of allocation control XABs.

4.11 FAB$L_DEV Field

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.

Table 4-2 Device Characteristics

Bit Offset	Description
DEV$V_ALL	Device is allocated.
DEV$V_AVL	Device is available for use.
DEV$V_CCL	Carriage control device.
DEV$V_CDP	Device has dual access paths, one of which is a remote node using an MSCP server.
DEV$V_CLU	Device is available on an OpenVMS Cluster.
DEV$V_DET	Terminal device is detached.
DEV$V_DIR	Directory-structured device.
DEV$V_DMT	Device is marked for dismount.
DEV$V_DUA	Device has dual access paths, both of which use a disk class driver.
DEV$V_ELG	Device is error log enabled.
DEV$V_FOD	File-oriented device (disk and magnetic tape).
DEV$V_FOR	Device is mounted foreign (non-file-structured).
DEV$V_GEN	Device is a generic device.
DEV$V_IDV	Device can provide input.
DEV$V_MBX	Device is a mailbox.
DEV$V_MNT	Device is currently mounted.
DEV$V_NET	Network device.
DEV$V_ODV	Device can accept output.
DEV$V_OPR	Device has been enabled as an operator console terminal.
DEV$V_RCK	Device has read-check enabled.
DEV$V_RCT	Device includes a Replacement and Caching Table. See the OpenVMS I/O User's Reference Manual for more information about RCTs.
DEV$V_REC	Record-oriented device (terminal, mailbox, line printer, for example). If field is 0, device is assumed to be block-oriented (disk device or magnetic tape device). All record-oriented devices are considered sequential in nature.
DEV$V_RND	Device is random access in nature (disk).
DEV$V_RTM	Device is real-time in nature; not suitable for use by RMS.
DEV$V_RTT	Terminal device is a remote terminal (DCL command SET HOST).
DEV$V_SDI	Single directory device (master file directory only).
DEV$V_SHR	Shareable device.
DEV$V_SPL	Device is being spooled.
DEV$V_SQD	Sequential block-oriented device (magnetic tape).
DEV$V_SWL	Device is currently software write-locked.
DEV$V_TRM	Terminal device.
DEV$V_WCK	Device has write-check enabled.

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.

4.12 FAB$L_DNA Field

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:

• Node
• Device
• Directory
• File name
• File type
• File version number

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

4.13 FAB$B_DNS Field

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

4.14 FAB$B_FAC Field

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.

When RMS attempts to open a file for a process, it examines the process's FAB$B_FAC field to determine what operations or services the process is seeking to use in conjunction with the file access.

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.

Options

FAB$V_BIO

Requests file access for doing block I/O operations that use Read (FAB$V_GET), Write (FAB$V_PUT), or the Space services. Specifying block I/O prohibits the use of record I/O operations (such as the Get, Put, Update, Delete, or Truncate services).

This option corresponds to the FDL attribute ACCESS BLOCK_IO.

FAB$V_BRO

Requests file access for doing either block I/O or record I/O as determined by the state of the RAB$V_BIO bit in the RAB at connect time. Mixed block and record I/O operations are restricted to sequential files. For additional information, see Section 7.19 and Section B.3.10.

This option corresponds to the FDL attribute ACCESS RECORD_IO.

FAB$V_DEL

Requests file access for invoking the Delete service (or the equivalent language statement that deletes a record). This option applies only to relative and indexed files.

This option corresponds to the FDL attribute ACCESS DELETE.

FAB$V_GET

Requests file access for invoking either the Get or Find service (or equivalent language statement that reads a record). This is the default if a process requests access to a file without including FAB$B_FAC field information. If the process takes the FAB$V_GET option together with either the FAB$V_BIO option or the FAB$V_BRO option, it can invoke the Read service.

This option corresponds to the FDL attribute ACCESS GET.

FAB$V_PUT

Requests file access for invoking either the Put or Extend service (or the equivalent language statement that writes a record or extends a file). This is the default when a process creates a file. If the process takes the FAB$V_PUT option together with either the FAB$V_BIO option or the FAB$V_BRO option, it can invoke the Write service.

This option corresponds to the FDL attribute ACCESS PUT.

FAB$V_TRN

Requests file access for invoking the Truncate service (or the equivalent language statement that truncates a file). Also allows use of the RAB$L_ROP truncate-on-put (RAB$V_TPT) option with the Put and Write service. This option applies only to sequential files.

This option corresponds to the FDL attribute ACCESS TRUNCATE.

FAB$V_UPD

Requests file access for invoking either an Update or Extend service (or the equivalent language statement that rewrites a record or extends a file). Also allows use of the RAB$L_ROP update-if (RAB$V_UIF) option for the Put service.

This option corresponds to the FDL attribute ACCESS UPDATE.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4523PRO_004.HTML