Document revision date: 19 July 1999

OpenVMS Record Management Services (RMS) has been modified to support Extended File Specifications. The following sections describe syntax and semantics changes and RMS data structure changes.

B.2.1 Overview of Record Management Services Changes

• Support for a wider range of characters in a file name, extension, and directory
• Access to file specifications with extended characters
• Support for directory structures deeper than eight levels
• Access to file specifications longer than 255 bytes through the NAM block with some restrictions in functionality
• Access and complete specification of file specifications longer than 255 bytes by callers who are aware of the new naming characteristics through a new interface (NAML block)

On ODS-5 volumes, RMS can manipulate filenames and subdirectory specifications of up to 255 8-bit or 16-bit characters in length. RMS can handle a total path name 512 8-bit or 16-bit characters in length.

Prior to OpenVMS Alpha Version 7.2, the NAM block interface could pass file specifications of up to 255 bytes each (including the resultant file specification). The following sections describe the changes that allow for passing longer file specifications and that provide compatibility with applications using the NAM block interface prior to this release.

B.2.1.2 Additional Characters

On ODS-5 volumes, RMS supports access to files and directories with names that contain arbitrary 8-bit characters, except for the C0 control set (hexadecimal 00 through 1F) and the following characters:

• Double quotation marks (")
• Asterisk (*)
• Backslash (\)
• Colon (:)
• Left and right angle brackets (< >)
• Slash (/)
• Question mark (?)
• Vertical bar (|)

Note that this explicitly includes both the C1 character set (hex 80-9F) as well as graphical and other characters between 9F and FF. This allows the entire ISO Latin-1 character set (with the 7-bit character exclusions noted above) and any defined Unicode character.

B.2.1.3 Deeply Nested Directory Support

Under Extended File Specifications on Alpha, RMS supports deep nesting of up to 255 directories, with the restriction that the total directory specification must be no longer than 512 8-bit or 16-bit characters. The deep nesting of directories is also supported on ODS-2 disks.

B.2.2 Syntax and Semantics Changes

The following sections describe new RMS file specification syntax and semantics features. See the Guide to OpenVMS File Applications for more information about using RMS with Extended File Specifications.

B.2.2.1 Use of Hyphen as First File Name Character

Prior to OpenVMS Version 7.2, RMS documentation recommended against creating files with names that begin with a hyphen (minus sign).

On Alpha systems, the Extended File Specifications changes to RMS allow you to use a hyphen anywhere in a file name or a directory name. If a directory name containing a hyphen is ambiguous, that is, if it could be interpreted as referring to a parent directory, you must prefix the hyphen with the escape character (^) to accurately specify the file or directory.

B.2.2.2 Characters Accepted Directly

The set of characters valid through the RMS interface in a file specification (without any special escape character) is extended according to the following list. Note that these characters must not be preceded by the escape character circumflex (^).

• Upper and lowercase alphanumeric characters:

  A - Z, a - z, 0 - 9

• Special ASCII (7-bit) characters:

  $ - ` _ ~

• ISO Latin-1 characters in the range (hex) A0 to FF.

• Escape (^) followed by a hexadecimal digit requires a second hexadecimal digit. The two following characters represent a hexadecimal value for an arbitrary 8-bit character.
  For example, ^20 represents a space.
• Escape followed by underscore (^_) or by a space represents one space.
• Escape followed by uppercase U (^U) indicates that the next four characters represent a hexadecimal value for an arbitrary 16-bit character.
• Each 2-byte Unicode character must be represented as a ^Uxxxx sequence.
• The following characters require an escape character when they are used as part of a file name on input to RMS and DCL:
  • Exclamation point (!)
  • Pound sign (#)
  • Ampersand (&)
  • Apostrophe (')
  • Left parenthesis (()
  • Right parenthesis ())
  • Plus sign (+)
  • Atsign (@)
  • Left brace ({)
  • Right brace (})
  • Period (.)¹
  • Comma (,)
  • Grave accent (`)
  • Semicolon (;)
  • Left bracket ([)
  • Right bracket (])
  • Percent sign (%)
  • Circumflex (^)
  • Equal sign (=)

The following characters can be preceded by the escape character (^) on input to RMS or DCL, but need not be.

• Dollar sign ($)
• Minus sign (-)
• Tilde (~)²
• Period (.)¹

Sequences consisting of the escape character followed by any character not mentioned previously are reserved.

B.2.2.6 Canonical Form of File Specifications

In some cases, there are multiple ways to write the same characters. For example, ^20, ^ , and ^_ are all equivalent. When RMS outputs a file specification (as a resultant name, for example), it follows these rules to determine which form to use:

• Any character that cannot be represented with eight bits is represented as ^Uxxxx, where xxxx is four hexadecimal digits.
• Space is represented as the escape character followed by an underscore (^_).
• Other ISO Latin-1 8-bit characters that have no graphical representation or which are used for control functions by other OpenVMS software or by terminals is represented by an escape character followed by two hexadecimal digits (^xx). Otherwise, it is represented by its own character. The following 8-bit values are output as an escape character followed by two hexadecimal digits.
  • 7F (rubout)
  • 80-9F (C1 control characters)
  • A0 (nonbreaking space)
  • FF (Latin small letter y diaeresis)
• If the file specification is longer than 255 bytes and must be output through a NAM block, a DID or FID abbreviation is used.
• The following characters are output preceded by the escape character (^):
  • Exclamation point (!)
  • Pound sign (#)
  • Ampersand (&)
  • Apostrophe (')
  • Grave accent (`)
  • Left parenthesis (()
  • Right parenthesis ())
  • Plus sign (+)
  • Atsign (@)
  • Left brace ({)
  • Right brace (})
  • Period (.)
  • Comma (,)
  • Semicolon (;)
  • Left bracket ([)
  • Right bracket (])
  • Percent sign (%)
  • Circumflex (^)
  • Equal sign (=)

With extended file names, some legal names will be too long for unmodified RMS applications or for DCL to handle, either because of many levels of long directory names or because of a long file name with escape characters in it. To maintain compatibility with applications using the traditional (or pre-Version 7.2) interfaces, shorter names that RMS can output to the application and that an application can input to RMS through the traditional interface will be generated.

DID abbreviation is the first step that RMS uses to create a generated name if the file specification is longer than 255 bytes. RMS attempts to generate a short enough name by abbreviating the directory with its directory ID (DID). For example:

DKA100:[5953,9,0]FOO.TXT;1.

Restrictions on DID Abbreviations

When RMS is processing a file specification that does not fit into a traditional (pre-Version 7.2) short output buffer, RMS can attempt to abbreviate the root or directory component by replacing the component with the directory ID of the lowest-level subdirectory in the component.

There are circumstances in which RMS will not be able to generate a DID-abbreviated root or directory component. For example, if the path to the lowest-level subdirectory includes a wildcard, RMS does not have a particular directory ID to use. (And RMS does not attempt to replace a portion of a root or directory component with a DID.)

When RMS is unable to sufficiently shorten a file specification by generating a DID-abbreviated root or directory, it proceeds to the next step, FID abbreviation.

B.2.2.8 FID Abbreviation

If the file specification is still too long after DID abbreviation, RMS next attempts to generate a short enough name by abbreviating the file with its File ID (a comma-separated sequence of decimal digit strings, surrounded by brackets) in the file name field.

In cases where the extension field is normally presented, a generated name includes the complete extension or drops the extension (including the period (.)), depending on whether there is space.

In cases where the version number is normally presented, a FID abbreviated file name includes the version. As a human-readable aid in recognizing files, when a FID abbreviation is generated, the name field also contains an initial subset of the actual file name. The subset consists of the first 38 characters of the file name (where escape counts as a character) followed by the tilde (~). No attempt is made to resolve ambiguities for files that differ only after the first 38 characters of their names.

Here is an example of a FID abbreviation:

LookAtWhatWeHave^!ThisIsAVery_long^.fi~[7254,30,0].txt;1

Restrictions on FID Abbreviations and DID Abbreviations

A FID abbreviated file name can be used for input to RMS, but only the FID abbreviation itself is significant to RMS. The subset file name, the type field, and the version are all ignored on input.

A FID cannot be used as input to the CREATE command (or any other file creation command or API) when creating a file. A DID cannot be used to create a directory. When a FID is used in a file specification, the file specification either initially contains a device and directory or it acquires them from defaults processing in RMS. If a file with the specified FID exists on the volume, it must exist within the specified directory; otherwise, RMS acts as though the file were not found.

B.2.3 RMS Data Structure Changes (Alpha Only)

This section lists the changes to the name (NAM) block. It also describes the new name (NAML) block that is used to specify file specifications longer than 255 bytes.

B.2.3.1 NAM Block

The file name block options field, NAM$B_NOP, has the following new flag:

Flag	Meaning
NAM$V_NO_SHORT_UPCASE	Set by the user to tell RMS not to convert the directory and file specification in the NAM$L_ESA buffer to uppercase.

The file name status bits field, NAM$L_FNB, has the following new flags:

Flag	Meaning
NAM$V_DIR_LVLS_G7	Indicates that the number of directory levels are greater than 7. If this is set, NAM$V_DIR_LVLS is set to 7.
NAM$V_WILD_SFDG7	Indicates that a subdirectory greater than 7 contains a wildcard character. This field offset is summarized in the NAM$V_WILDCARD field offset.

The NAM has three new fields: NAM$B_NMC, NAM$W_FIRST_WILD_DIR, and NAM$W_LONG_DIR_LEVELS. The NAM$B_NMC field returns the following flags:

Flag	Meaning
NAM$V_DID	Set by RMS if it found a DID-abbreviated directory in the root or directory name component of an input directory.
NAM$V_FID	Set by RMS if it found a FID-abbreviated file name in an input file specification.
NAM$V_RES_DID	Set by RMS if there is a DID-abbreviated directory in the short resultant or expanded buffer.
NAM$V_RES_FID	Set by RMS if there is a FID-abbreviated name in the short resultant or expanded buffer.
NAM$V_RES_ESCAPE	Set by RMS if there are any escape characters (^) in the short resultant or expanded buffer.
NAM$V_RES_UNICODE	Set by RMS if there is one or more ^U sequences in the short resultant or expanded buffer.

B.2.3.2 NAML Block

The NAML is a new block that can optionally take the place of a NAM block. The NAML has all the fields of the NAM, and additionally contains new fields to allow filespecs to be specified that are longer than 255 bytes.

The new fields for the NAML are as follows:

Extended Field Name	Size (bytes)	Meaning
NAML$L_FILESYS_NAME	4	File system name buffer address specified by the user. If RMS sets the NAML$V_FILESYS_NAME_UCS2 output flag, the output filename is in 2-byte characters, and everything that is in the file name including ASCII characters and delimiters are 2-byte characters. Otherwise, they are single byte characters.
NAML$L_FILESYS_NAME_ALLOC	4	File system name buffer allocated size specified by the user.
NAML$L_FILESYS_NAME_SIZE	4	File system name length returned by RMS.
NAML$L_LONG_DEFNAME_SIZE	4	Long default file specification string size specified as input. Equivalent to FAB$B_DNS (input only). Used only if FAB$L_DNA is set to -1, and FAB$B_DNS is set to 0.
NAML$L_LONG_DEFNAME	4	Long default file specification string address specified as input. Equivalent to FAB$L_DNA (input only). Used only if FAB$L_DNA is set to -1, and FAB$B_DNS is set to 0.
NAML$L_LONG_FILENAME_SIZE	4	Long file specification string size. Equivalent to FAB$B_FNS (input only). Used only if FAB$L_FNA is set to -1, and FAB$B_FNS is set to 0.
NAML$L_LONG_FILENAME	4	Long file specification string address. Equivalent to FAB$L_FNA (input only). Used only if FAB$L_FNA is set to -1, and FAB$B_FNS is set to 0.
NAML$L_LONG_NODE_SIZE	4	Long node name string length.
NAML$L_LONG_NODE	4	Long node name string address.
NAML$L_LONG_DEV_SIZE	4	Long device string length.
NAML$L_LONG_DEV	4	Long device string address.
NAML$L_LONG_DIR_SIZE	4	Long directory string length.
NAML$L_LONG_DIR	4	Long directory string address.
NAML$L_LONG_NAME_SIZE	4	Long file name string length.
NAML$L_LONG_NAME	4	Long file name string address.
NAML$L_LONG_TYPE_SIZE	4	Long file type string length.
NAML$L_LONG_TYPE	4	Long file type string address.
NAML$L_LONG_VER_SIZE	4	Long file version string length.
NAML$L_LONG_VER	4	Long file version string address.
NAML$L_LONG_EXPAND_ALLOC	4	Long expanded string area size. Set by the caller to specify the size of the long expanded buffer.
NAML$L_LONG_EXPAND_SIZE	4	Long expanded string length. Set by RMS to show the length of the long expanded string.
NAML$L_LONG_EXPAND	4	Long expanded string area address. Set by the caller to point to the long expanded buffer.
NAML$L_LONG_RESULT_ALLOC	4	Long resultant string area size. Set by the caller to specify the size of the long resultant buffer.
NAML$L_LONG_RESULT_SIZE	4	Long resultant string length. Set by RMS to show the length of the long resultant string.
NAML$L_LONG RESULT	4	Long resultant string area address. Set by the caller to point to the long resultant buffer.
NAML$L_INPUT_FLAGS	4	Additional flags specified as input to RMS, including NAML$V_NO_SHORT_OUTPUT, which is defined the table below.
NAML$L_OUTPUT_FLAGS	4	Additional status bits passed as output by RMS, including NAML$V_LONG_RESULT_ESCAPE and NAML$V_FILESYS_NAME_UCS2, which are defined in the table below.
NAML$Q_USER_CONTEXT	8	Caller can use this for any purpose. Will not be read or modified by RMS.

RMS reads the following flag from the NAML$L_INPUT_FLAGS field:

Flag	Meaning
NAML$V_NO_SHORT_OUTPUT	Set by the user to tell RMS not to fill in the NAM$L_ESA or NAM$L_RSA buffer.

RMS writes the following flags to the NAML$L_OUTPUT_FLAGS field:

Flag	Meaning
NAML$V_FILESYS_NAME_UCS2	Set by RMS if name pointed to by NAML$L_FILESYS_NAME consists of 6 2-byte Unicode characters.
NAML$V_LONG_RESULT_DID	Set by RMS if there is a DID-abbreviated directory in the long resultant or expanded buffer.
NAML$V_LONG_RESULT_ESCAPE	Set by RMS if there are any escape characters (^) in the long resultant or expanded buffer.
NAML$V_LONG_RESULT_FID	Set by RMS if there is a FID-abbreviated name in the long resultant or expanded buffer.
NAML$V_LONG_RESULT_UNICODE	Set by RMS if there is one or more ^U sequences in the long resultant or expanded buffer.

B.2.3.2.1 Validating the NAML Block

If the name block passed to RMS (see FAB$L_NAM) contains a block identifier (see NAML$B_BID) equal to NAML$C_BID, RMS performs the following validation checks:

1. NAML$B_BLN field is exactly equal to NAML$C_BLN.
2. NAML$L_LONG_RESULT_ALLOC and NAML$L_LONG_EXPAND_ALLOC are less than or equal to NAML$C_MAXRSS.
3. All unused fields (which have a symbolic name containing MBZ) contain zero. You can clear the entire structure before initializing any fields to meet this requirement.

If any of these validation checks fail, a RMS$_NAML error status is returned.

B.2.3.2.2 Using the NAM and NAML Block

The NAML has fields that are equivalent to all the NAM fields, plus 28 additional fields to accommodate longer file specifications. There are no FDL attributes for the NAML fields.

Many of the additional fields in the NAML correspond to NAM fields but allow longer names. For example, the fields NAML$L_LONG_EXPAND, NAML$L_LONG_EXPAND_ALLOC, and NAML$L_LONG_EXPAND_SIZE correspond to NAM$L_ESA, NAM$B_ESS, and NAM$B_ESL, but allow names that are longer than 255 bytes. When there are fields that correspond this way, the original field is referred to as a "short field." The corresponding field is referred to as a "long field."

When RMS is writing information into fields in a NAML that have both a short and long version, RMS normally writes the equivalent information into both fields. If either the short field or the long field is too small to contain the information, RMS returns an error, though RMS first attempts to abbreviate specifications to allow them to fit in the short fields. You can prevent the error on the short fields by setting the flag NAML$V_NO_SHORT_OUTPUT, which instructs RMS not to write into the short fields. However, if you are using a NAML, RMS always uses the long fields. If you do not want RMS to use the long fields, you must use a NAM rather than a NAML.

When RMS is reading information from fields in a NAML that has both a short and a long version, RMS always reads from the long version. To cause RMS to read from the short fields, use a NAM rather than a NAML. The most common time that RMS reads from these fields is during a $SEARCH operation following a $PARSE, when RMS reads from the buffer pointed to by NAML$L_LONG_EXPAND for a NAML and NAM$L_ESA for a NAM. In addition, if a NAM or NAML is used as a related name block, RMS reads information from the buffer pointed to by NAML$L_LONG_RESULT for a NAML, or NAM$L_RSA for a NAM.

Because of these differences in the way RMS processes a NAM and a NAML, it is important that any code that might come in contact with the NAML be aware that it is a NAML and not a NAM. Several operations that a routine might do on a NAM will not work as expected on a NAML. For example, if a routine makes a copy of a NAML but uses the NAM$C_BLN constant as the length to copy, the result is an illegal NAML. If a routine replaces the buffers pointed to by NAM$L_ESA and NAM$L_RSA with the expectation that it can use the NAM without affecting the calling routine, it misses the buffers pointed to by NAML$L_LONG_EXPAND and NAML$L_LONG_RESULT.

For this reason, any API supplied by OpenVMS adheres to the rule that if it returned a NAM (either directly or indirectly through a FAB) in previous versions, it will not now start returning a NAML without some explicit action by the caller (usually setting a flag bit). We recommend that other APIs use the same rule. Further, if a NAML-aware application passes a NAML to an API, it must be prepared for that API to use only the NAM section (for example, it should not set the NAML$V_NO_SHORT_OUTPUT bit).

If you are writing a routine that is to accept either a NAM or a NAML, you should check the NAM$B_BID field to determine whether you have a NAM or a NAML; if you have a NAML, and you wish to read information that RMS has left in the NAML, look at the information in the long fields. In addition, if you wish to copy that NAM or NAML block to another location, you must be careful to use the length that is stored in the structure itself to determine how much to copy. You should use the NAM$B_BLN field in the structure you are copying rather than the NAM$C_BLN constant, because NAM$B_BLN contains the actual length of the structure. If you use the symbol NAM$C_BLN, which is the length of a NAM, it would be too short for a NAML.

	privacy and legal statement
6536PRO_006.HTML