Retrieve Directory Information (RTVDIRINF)

Where allowed to run: All environments (*ALL)
Threadsafe: No

The Retrieve Directory Information (RTVDIRINF) command is used to collect attributes for directories and files in the integrated file system. The collected information is stored in database files that are named using the information file prefix specified by the INFFILEPFX parameter. The files are created in the library specified by the INFLIB parameter.

You can run the Print Directory Information (PRTDIRINF) command to print reports using the retrieved directory information.

To get the most accurate results, this command should be run at a time when there is very little activity for files in the specified directory. If SUBTREE(*ALL) is specified, try to run this command when there is very little activity for files in all subdirectories of the specified directory.

Note: If there is more than one member in the files, the results of running this command can be unpredictable.

Restrictions:

Directory information can be retrieved only for mounted file systems.
Directory information can be retrieved only for local file systems.
You must have all object (*ALLOBJ) special authority to run this command.

Top

Parameters

Keyword	Description	Choices	Notes
DIR	Directory	Path name	Required, Positional 1
SUBTREE	Directory subtree	ALL, NONE	Optional
INFFILEPFX	Information file prefix	Simple name, *GEN	Optional
INFLIB	Information library	Name, QUSRSYS	Optional
OMIT	Omit	Values (up to 300 repetitions): Path name	Optional

Top

Directory (DIR)

Specifies the path name of the integrated file system object for which information will be collected.

For more information on specifying path names, refer to "Object naming rules" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

This is a required parameter.

directory-path-name: Specify the path name of the integrated file system object.

Top

Directory subtree (SUBTREE)

Specifies whether or not to collect directory information for subdirectories of the directory specified by the DIR parameter.

*ALL: Directory information for subdirectories of the specified directory will be collected.
*NONE: Directory information will only be collected for the files in the specified directory. No directory information will be collected for subdirectories.

Top

Information file prefix (INFFILEPFX)

Specifies the file name prefix of the database files where the retrieved directory information is to be stored.

*GEN: The database files will be created with a unique prefix generated by this command. The prefix will begin with QAEZD followed by four digits. The files created to store the collected information will be named using this prefix followed by either the letter 'D' (for the file which contains directory information) or the letter 'O' (for the file that contains information about objects in directories). For example, the first time the command is run with *GEN specified, files QAEZD0001D and QAEZD0001O will be created in the library specified by the INFLIB parameter. Informational message CPI1E30 will be sent to the job log and will contain the names of the files created.
information-file-prefix: Specify the file prefix to use for creating the database files used to store the collected directory information. The prefix can be up to nine letters. The files created to store the collected information will be named using this prefix followed by either the letter 'D' (for the file which contains directory information) or the letter 'O' (for the file that contains information about objects in directories). For example, if the prefix specified is MYDIR, database files MYDIRD and MYDIRO will be created in the library specified by the INFLIB parameter.

Top

Information library (INFLIB)

Specifies the library where the database files used to store the directory information will be created.

QUSRSYS: The files will be created in library QUSRSYS.
library-name: Specify the name of the library to create the database files.

Top

Omit (OMIT)

Specifies a maximum of 300 integrated file system directories for which information will not be gathered.

path-name

Specify the name of the object that is to be omitted from the gathered information.

A pattern can be specified in the last part of the path name. An asterisk (*) matches any number of characters and a question mark (?) matches a single character. If the path name is qualified or contains a pattern, it must be enclosed in apostrophes. Symbolic links within the path name will not be followed. If the path name begins with the tilde character, then the path is assumed to be relative to the appropriate home directory. Note that in determining whether a name matches a pattern, relative name patterns are always treated as relative to the current working directory.

Additional information about path name patterns is in the Integrated file system topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Note: This parameter is Unicode-enabled. See "Unicode support in CL" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ for additional information.

Top

Examples

Example 1: Retrieve Information, Including Subdirectories

RTVDIRINF   DIR('/MYDIR/MYDOCS')  SUBTREE(*ALL)
            INFFILEPFX(*GEN) INFLIB(QUSRSYS)

This command retrieves directory information about directory /MYLIB/MYDOCS, including information for all nested subdirectories, and stores it the database files created in library QUSRSYS. The database files will be created with unique names that begin with 'QAEZD' followed by four digits. If this is the first time the RTVDIRINF command is run, the file names will be QAEZD0001O and QAEZD0001D.

Example 2: Retrieve Information for Specified Directory Only

RTVDIRINF   DIR('/')  SUBTREE(*NO)  INFFILEPFX(MYROOTDIR)
            INFLIB(MYLIB)

This command retrieves directory information about the root directory without inspecting nested subdirectories and stores it in the database files MYROOTDIRO and MYROOTDIRD in library MYLIB. If database files with either of those names already exist in library MYLIB, an error message will be sent and no directory information will be retrieved.

Example 3: Retrieve Information, Including Subdirectories, and Omitting Some Directories

RTVDIRINF   DIR('/')  SUBTREE(*ALL)  INFFILEPFX(MYROOTDIR)
            INFLIB(MYLIB)  OMIT('/QSYS.LIB' '/QDLS' '/QOPT')

This command retrieves directory information about the root directory, including information for all nested subdirectories, but not including any information for the '/QSYS.LIB', '/QDLS', and '/QOPT' directories and any of their subdirectories. The command stores the information in the database files MYROOTDIRO and MYROOTDIRD in library MYLIB. If database files with either of those names already exist in library MYLIB, an error message will be sent and no directory information will be retrieved.

Top

Error messages

*ESCAPE Messages

CPFA08E: More than one name matches pattern.
CPFA093: Name matching pattern not found.
CPFA09C: Not authorized to object. Object is &1.
CPFA0A1: An input or output error occurred.
CPFA0A3: Path name resolution causes looping.
CPFA0A6: Number of links exceeds maximum allowed for the file system.
CPFA0A7: Path name too long.
CPFA0A9: Object not found. Object is &1.
CPFA0AA: Error occurred while attempting to obtain space.
CPFA0AB: Operation failed for object. Object is &1.
CPFA0AD: Function not supported by file system.
CPFA0B2: No objects satisfy request.
CPF1ED2: File &1 is in use and cannot be accessed.
CPF1ED4: Not authorized to collect directory information.
CPF1E99: Unexpected error occurred.

Top