|
HP OpenVMS Systems Documentation |
|
OpenVMS Record Management Services Reference Manual
4.28 FAB$B_RFM FieldThe 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
If you intend to use stream record format, then specify the FAB$V_CR
record attribute (see FAB$B_RAT).
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.
The secondary device characteristics (SDC) field is equivalent to the
FAB$L_DEV field, except that secondary device characteristics refer to
the intermediate device used for spooling or the logical link for
DECnet for OpenVMS operations. Within the FAB$L_SDC field, the bit
definitions are the same as those defined for the FAB$L_DEV field (see
Table 4-2). Like the FAB$L_DEV field, the bit definitions must first
be made available to your process referring to the $DEVDEF system macro
definition; the values are set by certain record management services
(see FAB$L_DEV for additional information).
The file sharing (SHR) field defines the record operations that the opening process allows sharing processes to perform. RMS supports file sharing for all file organizations. Within the FAB$B_SHR field, each record operation that sharing processes are permitted to do has a corresponding bit assignment. You can specify multiple record operations (multiple bits may be set). Options are identified by symbolic bit offsets. Note that conflicts between the names of symbolic offsets in the FAB$B_SHR field and the names of symbolic offsets in the FAB$B_FAC field are resolved by prefixing the letters SHR to the symbolic offset in the FAB$B_SHR field. For example, both the FAB$B_FAC and FAB$B_SHR fields have a bit that specifies the get record option. In the FAB$B_FAC field, this bit offset is assigned the symbol FAB$V_GET; in the FAB$B_SHR field, this bit is assigned the symbol FAB$V_SHRGET. Note that the letters SHR in the mnemonic part of the bit offset symbol may be omitted by VAX MACRO programs. Thus, the GET option, which is common to the FAB$B_FAC and FAB$B_SHR fields, has a symbolic bit offset of FAB$V_SHRGET and a mask value of FAB$M_SHRGET, but VAX MACRO programs may use the synonyms FAB$V_GET and FAB$M_GET. This rule applies to the FAB$V_SHRPUT, FAB$V_SHRGET, FAB$V_SHRDEL, and FAB$V_SHRUPD options. The way in which RMS uses the file access (FAB$B_FAC) field and file sharing (FAB$B_SHR) field is described in greater detail in the FAB$B_FAC field discussion. Note that if you do not specify a value in the FAB$B_SHR field, the following defaults apply:
The following list includes descriptions of the sharing options. Options
4.32 FAB$L_STS Field
RMS sets the completion status code (STS) field with success or failure
codes before it returns control to your program (except for a subset of
errors, as detailed in Section 2.4). Register 0 contains the same
status as the STS field. Potential error codes for specific services
are listed under their descriptions.
RMS sets the status value (STV) field on the basis of the operation
performed and the contents of the completion status code (FAB$L_STS)
field, communicates additional completion information to your program.
The extended attribute block address (XAB) field specifies the XAB, or first of a series of XABs, that you want to use for file operations. This field contains the symbolic address of a XAB control block. A value of 0 (the default) indicates no XABs for the file. For some operations, you must associate extended attribute blocks with a FAB to convey additional attributes about a file. (See Section 1.2.2 for a description of a XAB.) The FAB$L_XAB field can contain the symbolic address of the first associated block (of a potential chained list of such blocks) for the file. RMS uses XAB values as follows:
Chapter 5
|
| Field Offset | Size (Bytes) |
Description |
|---|---|---|
| NAM$B_BID 1 | 1 | Block identifier |
| NAM$B_BLN 1 | 1 | Block length |
| NAM$B_DEV 2 | 1 | Device string length |
| NAM$L_DEV 2 | 4 | Device string address |
| NAM$W_DID 2 | 6 | Directory identification |
| NAM$B_DIR 2 | 1 | Directory string length |
| NAM$L_DIR 2 | 4 | Directory string address |
| NAM$T_DVI 2 | 16 | Device identification |
| NAM$L_ESA | 4 | Expanded string area address |
| NAM$B_ESL 2 | 1 | Expanded string length |
| NAM$B_ESS | 1 | Expanded string area size |
| NAM$W_FID 2 | 6 | File identification |
| NAM$W_FIRST_WILD_DIR | 2 | The topmost directory level to contain a wildcard. |
| NAM$L_FNB 2 | 4 | File name status bits |
| NAM$W_LONG_DIR_LEVELS | 2 | Total number directories |
| NAM$B_NAME 2 | 1 | File name string length |
| NAM$L_NAME 2 | 4 | File name string address |
| NAM$B_NMC | 1 | Name characteristics |
| NAM$B_NODE 2 | 1 | Node name string length |
| NAM$L_NODE 2 | 4 | Node name string address |
| NAM$B_NOP | 1 | Name block options |
| NAM$L_RLF 3 | 4 | Related file NAM or NAML block address |
| NAM$L_RSA | 4 | Resultant string area address |
| NAM$B_RSL 2 | 1 | Resultant string length |
| NAM$B_RSS | 1 | Resultant string area size |
| NAM$B_TYPE 2 | 1 | File type string length |
| NAM$L_TYPE 2 | 4 | File type string address |
| NAM$B_VER 2 | 1 | File version string length |
| NAM$L_VER 2 | 4 | File version string address |
| NAM$L_WCC 2 | 4 | Wildcard context |
The NAM block fields have no corresponding FDL equivalents. However, if your application requires the presence of a NAM block, consider using the $NAM macro (or equivalent) in a USEROPEN or a USERACTION routine.
Unless otherwise indicated, each field is supported for DECnet for OpenVMS operations on files at remote OpenVMS systems. For information about the support of RMS options for remote file access to other systems, see the DECnet for OpenVMS Networking Manual.
Depending on the services to be used, the user may need to allocate program storage for the expanded string and the resultant string. The Parse service uses the expanded string to pass information related to wildcards (or search lists) to the Search service. When it creates a resultant string for other file services, RMS uses the expanded string as a work area to apply defaults. You can use the resultant string with file services to provide the file specification that results from the translation of logical names and the application of defaults. Typical uses of the resultant string include showing the resulting file specification after a partial file specification is entered by a terminal user, reporting errors, and logging the progress of a program.
To request use of the expanded or resultant strings, you must indicate the address and size of the user-allocated buffer to receive the string. The expanded string is indicated by the NAM$L_ESA and NAM$B_ESS fields; the resultant string is indicated by the NAM$L_RSA and NAM$B_RSS fields. When it fills in the expanded or resultant strings, RMS returns the actual length of the returned string in the NAM$B_ESL or NAM$B_RSL fields.
5.2 File Specification Component Descriptors
For each element of the fully qualified file specification returned in
the expanded-string field or the resultant-string field in the NAM
block, RMS returns a descriptor in the NAM block made up of a 1-byte
size field and a 4-byte (longword) address field. The fields of these
descriptors are described as one of the following:
| NAM$B_xxx | (size field of xxx) |
| NAM$L_xxx | (address field of xxx) |
NAM$B_NODE, NAM$L_NODE
Node name descriptor, including access control string and double colon (::) delimiter.NAM$B_DEV, NAM$L_DEV
Device name descriptor, including colon (:) delimiter.NAM$B_DIR, NAM$L_DIR
Directory name descriptor, including brackets ([] or <>).NAM$B_NAME, NAM$L_NAME
File name descriptor or, if the file specification following a node name is within quotation marks ("file"), a quoted string descriptor.NAM$B_TYPE, NAM$L_TYPE
File type descriptor, including period (.) delimiter.NAM$B_VER, NAM$L_VER
File version number descriptor, including semicolon (;) or period (.) delimiter.
These descriptors are returned, enabling the program to extract a particular component from the resultant string without having to parse the resultant or expanded string. The entire resultant or expanded string, including delimiters, is described by the various component descriptors. If the value in the NAM$B_RSL field is nonzero, then the descriptors point to the NAM$L_RSA field. If the value in the NAM$B_RSL field is 0 and the value in the NAM$B_ESL field is nonzero, then the descriptors point to the NAM$L_ESA field. In all other cases, they are undefined.
This is an example of a resultant file specification and its file specification component descriptors:
NODE"TEST password"::WORK_DISK:[TEST.TEMP]FILE.DAT;3 NODE NODE"TEST password":: DEV WORK_DISK: DIR [TEST.TEMP] NAME FILE TYPE .DAT VER ;3 |
You can use the file component descriptors individually or collectively
to describe sections of the resultant or expanded string. For example,
if you want to use the file name and file type fields, use NAM$L_NAME
for the starting address and NAM$B_NAME+NAM$B_TYPE for the total length.
5.3 NAM$B_BID Field
The block identifier (BID) field is a static field that identifies this
control block as a NAM block. Once set, this field must not be altered
unless the control block is no longer needed. This field must be
initialized to the symbolic value NAM$C_BID (this is done by the $NAM
macro).
5.4 NAM$B_BLN Field
The block length (BLN) field is a static field that defines the length of the NAM block, in bytes. Once set, this field must not be altered unless the control block is no longer needed. This field must be initialized to the symbolic value NAM$C_BLN (this is done by the $NAM macro).
| Previous | Next | Contents | Index |