Document revision date: 30 March 2001

## OpenVMS Guide to Extended File Specifications

Previous | Contents | Index

### B.1.3 $GETJPI System Service

There are two new item codes for this system service. They are:

JPI$_PARSE_STYLE_PERM
JPI$_PARSE_STYLE_IMAGE

These return the values that were set by $SET_PROCESS_PROPERTIES, that can be either PARSE_STYLE$C_TRADITIONAL or PARSE_STYLE$C_EXTENDED. Return length is one byte for each one.

### B.1.4 $CREPRC System Service

There is a new flag allowed in the stsflg parameter:

PRC$M_PARSE_EXPANDED

This sets the PARSE_STYLE_PERM and the PARSE_STYLE_IMAGE properties for the new process to EXPANDED.

### B.1.5 $SETDDIR System Service

The following text has been added to the system service description:

On Alpha systems, the Set Default Directory service attempts to replace the default directory string with a DID if the length of the resulting default directory exceeds 255 bytes. If this happens, then in addition to the normal syntax check, the entire path to that specification, including the device, is verified and must exist for the call to succeed.

## B.2 Record Management Services (RMS) Changes

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

To support Extended File Specifications, the Record Management Services (RMS) have been enhanced to provide the following functions through existing interfaces:

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

#### B.2.1.1 Extended File Specification Support

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.

#### B.2.2.3 Characters That Require an Escape Character

- 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. For the period (.)1 and tilde (~)2, the escape character is only required under some circumstances, detailed in their respective footnotes.

      Exclamation point (!)
      Pound sign (#)
      Ampersand (&)
      Apostrophe (')
      Left parenthesis (()
      Right parenthesis ())
      Plus sign (+)
      Atsign (@)
      Left brace ({)
      Right brace (})
      Period (.)1
      Comma (,)
      Grave accent (`)
      Semicolon (;)
      Left bracket ([)
      Right bracket (])
      Percent sign (%)
      Circumflex (^)
      Equal sign (=)
      Tilde (~)2

#### B.2.2.4 Characters That Can Have an Escape Character

The following characters can be preceded by the escape character (^) on input to RMS or DCL, but need not be. For the period (.)1 and tilde (~)2 the escape character is only required under some circumstances, detailed in their respective footnotes.

    Dollar sign ($)
    Minus sign (-)
    Period (.)1
    Tilde (~)2

#### B.2.2.5 Reserved Escape Sequences

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 (=)

#### B.2.2.7 DID Abbreviation

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 a new flag as shown in Table B-3.

Table B-3 New NAM$B_NOP 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 new flags as described in Table B-4.

Table B-4 New NAM$L_FNB 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 flags described in Table B-5.

Table B-5 NAM$B_NMC Flag
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.

Table B-6 describes the new fields for the NAML Block.

Table B-6 New Fields for the NAML Block
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.

Note ##### 1 The escape character is required before a period in a directory name, is optional before a period in a file name, and must not be used for the period that delimits the file type. A period is not permitted in a file type. ##### 2 The tilde that is the leading character in a file name or directory may require an escape character.

Previous | Next | Contents | Index

| privacy and legal statement |
6536PRO_006.HTML