UDM - IBM i File Specification Rules

Overview

File specifications can appear in a variety of UDM commands, from copy to forfiles.

On IBM i, a simple set of rules governs how the full file specification used in an operation is constructed.

Since there are still subtle differences between source and destination side file specifications, in terms of how they are derived, separate rules are provided for each type of specification:

  • Source File Specification
  • Destination File Specification
    • Source and Destination in LIB
    • Destination (only) in LIB

IBM i Source File Specification Rules

The following rules apply to file specifications that are in the source position in a copy command.

(In all examples, CURLIB is the current library.)

  1. If the file specification contains only the file portion, the current library is pre-pended to the name to refer directly to a file with no member component.
    Example:
     

    COPY SRC=MYFILE

    The absolute path derived would be CURLIB/MYFILE.
     

  2. If the file specification contains only file and member portions, the current library is pre-pended to the name to refer to a specific member in a file.
    Example:
     

    COPY SRC=MYFILE(MYMBR)

    The absolute path derived would be CURLIB/MYFILE(MYMBR).
     

  3. If the file specification contains only library and file portions, an absolute path without a member component is used.
    Example:
     

    COPY SRC=MYLIB/MYFILE

    The absolute path would be exactly as given: MYLIB/MYFILE.
     

  4. If a file specification contains library, file, and member portions, all of those components are used explicitly in the absolute path.
    Example:
     

    COPY SRC=MYLIB/MYFILE(MYMBR)

    The absolute path would be MYLIB/MYFILE(MYMBR).

IBM i Destination File Specification Rules

Destination path names follow many of the same rules as source path names, with one big exception: all or part of the destination path name may be derived using a name (or names, in the case of IBM i to IBM i LIB file system copies) coming from the source side of a transfer operation.

Source and Destination in LIB File System

The following rules apply for IBM i to IBM i transfers where both the source and destination are operating in the LIB file system.

In these example, the current destination library is DSTLIB and the absolute path of the source file being copied is MYLIB/MYFILE(MYMBR).

  1. If the destination file specification contains an empty path (no library, file, or member portions), the file and member portions are derived from the source path. If the destination file is to be a save file, the absolute path in this case would be DSTLIB/MYFILE. If the destination file is to be a physical file, the absolute path would be DSTLIB/MYFILE(MYMBR).
    Examples:
     

    COPY SRC=MYLIB/MYFILE(MYMBR)

    The result is a destination name of DSTLIB/MYFILE(MYMBR) if the destination file type is a physical file.
     

    COPY SRC=MYLIB/MYFILE

    The result is a destination name of DSTLIB/MYFILE if the destination file type is a save file.
     

  2. If the destination file specification contains only a file portion, the current library is pre-pended to the absolute path. In this case, if the destination file is to be a save file, the absolute path would be DSTLIB/YOURFILE. If the destination file is to be a physical file, the absolute path would be DSTLIB/YOURFILE(MYMBR).
    Examples:
     

    COPY SRC=MYLIB/MYFILE(MYMBR) DST=YOURFILE

    The result is a destination name of DSTLIB/YOURFILE(MYMBR) if the destination file type is a physical file.
     

    COPY SRC=MYLIB/MYFILE DST=YOURFILE

    The result is a destination name of DSTLIB/YOURFILE if the destination file type is a save file.
     

  3. If the destination file specification contains only a file portion (with an empty member), the result is exactly the same as when just a destination file name is given.
    Example:
     

    COPY SRC=MYLIB/MYFILE(MYMBR) DST=YOURFILE()

    The result is a destination name of DSTLIB/YOURFILE(MYMBR) if the destination file type is a physical file.
     

  4. If the destination file specification contains only file and member portions, the resulting absolute path is DSTLIB/YOURFILE(YOURMBR) if a physical file is wanted.
    Example:
     

    COPY SRC=MYLIB/MYFILE(MYMBR) DST=YOUFILE(YOURMBR)

    The result is a destination name of DSTLIB/YOURFILE(YOURMBR) if the destination file type is a physical file.
     

  5. If the destination file specification contains only a library portion, that library is used instead of the current library. In this case, an absolute path of YOURLIB/MYFILE is used if a save file is wanted. If a physical file is wanted, an absolute path of YOURLIB/MYFILE(MYMBR) is used.
    Examples:
     

    COPY SRC=MYLIB/MYFILE(MYMBR) DST=YOURLIB/

    The result is a destination name of YOURLIB/MYFILE(MYMBR) if the destination file type is a physical file.
     

    COPY SRC=MYLIB/MYFILE DST=YOURLIB/

    The result is a destination name of YOURLIB/MYFILE if the destination file type is a save file.
     

  6. If the destination file specification contains only library and file portions, an absolute path of YOURLIB/YOURFILE is derived if a save file is wanted. If a physical file is wanted, YOURLIB/YOURFILE(MYMBR) is used.
    Examples:
     

    COPY SRC=MYLIB/MYFILE(MYMBR) DST=YOURLIB/YOURFILE

    The result is a destination name of YOURLIB/YOURFILE(MYMBR) if the destination file type is a physical file.
     

    COPY SRC=MYLIB/MYFILE DST=YOURLIB/YOURFILE

    The result is a destination name of YOURLIB/YOURFILE if the destination file type is a save file.
     

  7. If the destination file specification contains library and file portions, as well as an empty member name, the result is exactly the same as when the file specification contains only library and file portions.
    Example:
     

    COPY SRC=MYLIB/MYFILE(MYMBR) DST=YOURLIB/YOURFILE()

    The result is a destination name of YOURLIB/YOURFILE(MYMBR) if the destination file type is a physical file.
     

  8. If the destination file specification contains a complete absolute path (library, file, and member portions), the source file name has no effect on the destination path in any way. In this case, if the destination file type is a save file, YOURLIB/YOURFILE is used. If the destination file type is a physical file, YOURLIB/YOURFILE(YOURMBR) is used.
    Examples:
     

    COPY SRC=MYLIB/MYFILE(MYMBR)DST=YOURLIB/YOURFILE(YOURMBR)

    The result is a destination name of YOURLIB/YOURFILE(YOURMBR) if the destination file type is a physical file.
     

    COPY SRC=MYLIB/MYFILE DST=YOURLIB/YOURFILE

    The result is a destination name of YOURLIB/YOURFILE if the destination file type is a save file.
     

  9. In cases where a member is specified explicitly in the destination file name and the destination file type is a save file, an error is issued.
     

    Note

    If the user issues a cd dst-logical-name=.. command to blank out the current library on the destination side, the library name in the absolute path of the source file is used in the destination absolute path in cases where no library is specified explicitly.

     
    This works only for IBM i to IBM i copies where both operating systems are operating in the LIB file system.
    Example:
     

    CD DST=..
    COPY SRC=MYLIB/MYFILE(MYMBR)

    The result is a destination of MYLIB/MYFILE(MYMBR), using the source's library, file, and member names, because none are supplied explicitly in the copy command. The current directory on the destination side is empty because the command cd DST=.. was issued.

Destination (only) in LIB File System

Transfers where only the destination is operating in the LIB file system produce slightly different results.

The following rules apply for:

  • Copies from non-IBM i machines to an IBM i machine operating in the LIB file system
  • Copies from IBM i machines working in the HFS file system to an IBM i machine operating in the LIB file system,

These operations do not make use of source attributes describing all the library and file portions of the source file specification.

(In the following example, the source file being copied is MYFILE and the current library on the destination side is MYDSTLIB.)

  1. If the destination file specification contains an empty path (no library, file, or member portions), the source file name is used for the file and member names on the destination side. If the destination file is to be a save file, the absolute path in this case would be DSTLIB/MYFILE. If the destination file is to be a physical file, the absolute path would be DSTLIB/MYFILE(MYFILE).
    Example:
     

    COPY SRC=MYFILE

    DSTLIB/MYFILE(MYFILE) will be used as the destination name if the destination file type is a physical file and DSTLIB/MYFILE will be used if the destination file type is a save file.
     

  2. If the destination file specification contains only a file portion, the current library is pre-pended to the absolute path and the source file name is used for the member (if it applies). In this case, if the destination file is to be a save file, the absolute path would be DSTLIB/YOURFILE. If the destination file is to be a physical file, the absolute path would be DSTLIB/YOURFILE(MYFILE).
    Example:
     

    COPY SRC=MYFILE DST=YOURFILE

    DSTLIB/YOURFILE(MYFILE) will be used as the destination name if the destination file type is a physical file and DSTLIB/YOURFILE will be used if the destination file type is a save file.
     

  3. If the destination file specification contains only a file portion and an empty member portion, the result is exactly the same as when the file specification contains only file portion.
    Example:
     

    COPY SRC=MYFILE DST=YOURFILE()

    DSTLIB/YOURFILE(MYFILE) will be used as the destination name if the destination file type is a physical file.
     

  4. If the destination file specification contains only file and member portions, the resulting absolute path is DSTLIB/YOURFILE(YOURMBR) if a physical file is wanted.
    Example:
     

    COPY SRC=MYFILE DST=YOURFILE(YOURMBR)

    DSTLIB/YOURFILE(YOURMBR) will be used as the destination name if the destination file type is a physical file.
     

  5. If the destination file specification contains only a library portion, that library is used instead of the current library. In this case, an absolute path of YOURLIB/MYFILE is used if a save file is wanted. If a physical file is wanted, an absolute path of YOURLIB/MYFILE(MYFILE) is used.
    Example:
     

    COPY SRC=MYFILE DST=YOURLIB/

    YOURLIB/MYFILE(MYFILE) is used as the destination name if the destination file type is a physical file or YOURLIB/MYFILE if the destination file type is a save file.
     

  6. If the destination file specification contains only library and file portions, an absolute path of YOURLIB/YOURFILE is derived if a save file is wanted. If an absolute path of YOURLIB/YOURFILE(MYFILE) is used if a physical file is wanted,
    Example:
     

    COPY SRC=MYFILE DST=YOURLIB/YOURFILE

    YOURLIB/YOURFILE(MYFILE) is the destination name if a physical file is wanted and YOURLIB/YOURFILE is used if a save file is wanted.
     

  7. If the destination file specification contains library and file portions, as well as an empty member portion, the result is exactly the same as when the specification contains only a library and file portions.
    Example:
     

    COPY SRC=MYFILE DST=YOURLIB/YOURFILE

    YOURLIB/YOURFILE(MYFILE) is the destination name if a physical file is wanted.
     

  8. If the destination file specification contains a complete absolute path (library, file, and member portions), the source file name has no effect on the destination path in any way. In this case, if the destination file type is a physical file, YOURLIB/YOURFILE(YOURMBR) is used.
    Example:
     

    COPY SRC=MYFILE DST=YOURLIB/YOURFILE(YOURMBR)

    YOURLIB/YOURFILE(YOURMBR) is the destination if the destination file type is a physical file.
     

  9. In cases where a member is specified explicitly in the destination file name and the destination file type is a save file, an error is issued.