Path name rules for CL commands and displays

The following is a summary of rules to keep in mind when specifying these path names. The term object in these rules refers to any directory, file, link, or other object:

• Normally, all characters in the path name must be valid characters in the job’s coded character set identifier (CCSID) or, if the job CCSID is 65535, the job default CCSID. Some commands are “Unicode-enabled”, meaning you can specify the command and path name information in a Unicode CCSID through interfaces such as the QCAPCMD API. See Unicode support in control language in the IBM i information center for more information.
• Path names are specified in hierarchical order, beginning with the highest-level directory and ending with the name of the object to be operated on by the command. A delimiter character separates each component of the path name; for example:

  Dir1/Dir2/Dir3/UsrFile

• All commands and displays allow the slash (/) character to be used as the delimiter. Most commands and displays also allow the backslash (\) character to be used as the delimiter. However, some commands and displays may treat the backslash (\) no differently than any other character. Therefore, the backslash (\) character must be used with caution.
• An absolute path name begins with a delimiter. Path name resolution starts at the "root" (/) directory; for example:

  /Dir1/Dir2/Dir3/UsrFile

  where Dir1 is a subdirectory of the “root” (/) directory.

• If a path name begins with a tilde (~) character followed by a delimiter, then path name resolution will start at the home directory of the user entering the command; for example:

  '~user-profile-name/UsrDir/UsrObj'

• A tilde (~) character appearing anywhere other than the very beginning of a specified path name has no special significance.
• A relative path name does not begin with a delimiter or a tilde (~) character. Path name resolution starts at the current directory; for example:

  ‘MyDir/MyFile’

  where MyDir is a subdirectory of the current directory. When using relative path names you must be very careful to ensure that the current directory is set correctly.

• Path names containing delimiters, tildes, or other special characters (see below) must be enclosed in single quotation marks (') when entered on a command line. These quotation marks are optional when path names are entered on displays.
• The slash (/) character and the null character can not be used in the individual components of a path name. The backslash (\) character can not be used in a component for commands and displays that treat the backslash (\) as a delimiter.
• Characters with code points below hexadecimal 40 can be specified on the commands, but only if the entire path name is specified in hexadecimal format; for example:

  CRTDIR DIR(X’02F0F1F3’)

  Use of such characters is not recommended.

• Object names must be unique within each directory.
• The commands accept component names up to 255 characters long and path names up to 5000 characters long. However, some file systems only allow much smaller component and path names. They may also limit the characters that are allowed in component names or require a particular component name format. Also, the path name will not normally be converted to uppercase by the commands or displays themselves, but the file system may do so before creating or searching for the specified object. See the individual file system descriptions in the "File systems" topic of the IBM i Information Center for more information about these considerations.
• Some commands allow you to specify a pattern that allows a single command to operate on multiple objects that match the specified pattern. One or more asterisks (*) or question marks (?) can be used in the last component of a path name. An asterisk (*) matches any number of characters. A question mark (?) matches any single character. The following example searches for all objects in ‘/Dir1/Dir2/Dir3’ whose names begin with ‘d’ and end with ‘txt’. It could find objects named ‘dshorttxt’, ‘d1234.txt’, and even ‘dtxt’:

  '/Dir1/Dir2/Dir3/d*txt'

  The following example searches for objects whose names begin with ‘d’ followed by any single character and end with ‘txt’. It could find objects named ‘d1txt’ or ‘d.txt’, but not ‘d12txt’ or ‘dtxt’:

  '/Dir1/Dir2/Dir3/d?txt'

  More complex patterns can be specified with multiple asterisks, multiple question marks, or combinations of the two. However, to avoid confusion with i5/OS special values, path names can not start with a single asterisk (*) character. To perform a pattern match at the very beginning of a path name (as in a relative path name), use two asterisks (*); for example:

  '**.file'

• The path name must be enclosed in additional sets of single quotation marks (') or double quotation marks (") if any of the following characters is used in an actual component name:
  • Asterisk (*)
  • Question mark (?)
  • Single quotation mark (')
  • Double quotation mark (")
  • Tilde (~), if used as the first character in the first component name of the path name. If used in any other position, the tilde is interpreted as just another character.

  For example, if a component contains an asterisk, the name must be specified within additional quotation marks so that the asterisk is not interpreted as part of a pattern:

       '"/Dir1/Dir/A*Smith"'

  or

       '''/Dir1/Dir/A*Smith'''

  If the component name itself contains single quotation marks or double quotation marks, you must specify two such marks in a row to represent them; for example:

       ‘”/Dir1/Dir/Smith’’s Directory”’

  or

       ‘”/Dir1/Dir/This is an “”example”””’

• Even though the various file systems, commands, and displays may allow certain special characters in component names, you should avoid using those characters because they make it difficult or impossible to work with objects using other interfaces. The slash (/), backslash (\), asterisk (*), question mark (?), single quotation mark ('), double quotation mark ("), tilde (~), and colon (:) all have special significance to certain interfaces. For example, the CL commands treat both the slash (/) and backslash (\) as delimiters and can not properly interpret a path where component names contain either of those characters. Similarly, the presence of backslash (\) or colon (:) characters may make some objects unusable from PC client interfaces.