SYSTEM/PDIR is a program that searches for files that match the file specification. You can specify the attributes to be reported. You can specify the reported attributes, however, if you do not make a specification, PDIR reports,

You can base the search on a wild-card match of file names and on the values of file attributes. You can also specify sort preferences. By default, the output is directed back to the initiating user at the system console or datacomm terminal that initiated the command. You can also direct the output to a printer file, a disk file with a specified name, or the TASKSTRING task attribute.

You can run the PDIR utility from a Work Flow Language (WFL) job, from CANDE, or by using the PDIR (Process Directory) system command.

PDIR Request

The PDIR request syntax is explained as follows:

<PDIR request>

                       ┌◄───────────────────────────┐
──<file specification>─┴─┬────────────────────────┬─┴──────────────────►
                         ├─<SHOW specification>───┤
                         ├─<SELECT specification>─┤
                         └─<SORT specification>───┘
►─┬─────────────────────────────┬──────────────────────────────────────┤
  └─ : ──<output specification>─┘

<file specification>

──<wild-card directory>─┬────────────────────┬─────────────────────────┤
                        └─ ON ──<familyname>─┘

──<wild-card string>─┬────────────────────┬────────────────────────────┤
                     └─ ON ──<familyname>─┘

<wild-card directory>

──┬─<file name>────────┬───────────────────────────────────────────────┤
  ├─<directory name>───┤
  └─<wild-card string>─┘

A specification can be any current MCP file name, directory name, or wild-card string.

<wild-card string>

A wild-card string is a string of characters used to search for a file name. The string can include the following special characters, which can be used when only part of the file name is known:

Values for string attributes can be enclosed within quotation marks or apostrophes. These characters affect how a value is parsed. The following rules apply:

For example, if the following files are present

IC/"SECURITY.CON" 

IC/"security.con"

then the following command finds both files:

U *SYSTEM/PDIR IC/"~.~" 

The following command finds the first file:

U *SYSTEM/PDIR IC/"S~.CON"

The following command finds the second file:

U *SYSTEM/PDIR IC/"s~.con"

A “/=” suffix can be used to denote a directory (in which case a file matching the prefix is returned) or can be considered part of the wild-card string (in which case a file matching the prefix is not returned). The suffix is interpreted as a directory unless a wild-card character (=, ?, or ~) is present in the prefix.

For example, the following PDIR command interprets the “/=” suffix as denoting a directory, and if present, the file XXX is included in the response.

PDIR XXX/=

The following PDIR command interprets the “/=” suffix as part of the wild-card string and does not return the file XXX because the file name does not contain a “/” character.

PDIR X~/=         

<attribute name>

The attribute names that can be specified are those that are valid for the files scope of ASERIES_INFO. For more information, refer to "ASERIES_INFO Procedures" in the MCP System Interfaces Programming Reference Manual.

Most of the values correspond to attributes associated with the physical file or are derived from the physical file. Where the description indicates mnemonic name, the value is a string that corresponds to the value—such as IN, OUT, and IO for SECURITYUSE—that is returned by the corresponding value attribute such as 1, 2, and 3 respectively for IN, OUT, and IO.

Most attribute values for nonresident files do not exist.

In a SHOW specification, an attribute name can also be one of the following:

If you specify ALL, most of the attributes are displayed in the output report. Among the attributes that are not shown are those for which both a mnemonic and a value exist. For example, ALL reports the mnemonic values of FILEKIND and SECURITYTYPE but does not report the values for FILEKINDVALUE and SECURITYTYPEVALUE.

If you specify ALLP, the attributes that indicate the code file privileges are displayed on the output report.

The timestamp attributes (those attributes that end in “TIME” or “DATE”, and the TIMESTAMP attribute) are stored internally as EBCDIC strings in the format YYYYMMDDHHMMSSDDDD, where YYYYMMDD represents the 4-digit year, month, and day, and HHMMSSDDDD represents the time of day with two digits each for hour, minute, and second, and four digits of fractions of a second. This format allows selection expressions and wild-card strings to be used with these attributes. For example, a selection expression to find files created in January 1992 would be SELECT CREATIONTIME =199201=. To find all files accessed after this date, the selection expression would be SELECT LASTACCESSTIME> 199201310000000000. This format also enables you to use a SORT specification to return the file list in a time-sorted order. Notice that these attributes are not presented in the output records in this format, but this internal format is being documented to facilitate such types of searches and sorts. However, if you enter SELECT CREATIONTIME = 1992, with the intent to return files with that creation year, the program modifies the request by making it a request for CREATIONTIME =1992= —that is, by adding the wild-card at the end. A request for SELECT CREATIONTIME < 1992 would fail to return a file with a CREATIONTIME of 19910606080151111 unless the supplied date of 1992 is padded with trailing zeros. In cases like these, where a partial timestamp is specified, the program pads out the length of the supplied value to enable the comparison. If the requested timestamp value contains any non-digit, non-wild-card characters, or if it exceeds the maximum timestamp length—that is, 18 characters—the program reports an error message and terminates.

Notice also that any string attribute can be used in a wild-card match search. For example, a search can specify SELECT FILEKIND = NEWP=, which would return both NEWPSYMBOL and NEWPCODE files. Or, alternatively, SELECT FILEKIND = =CODE would return all code files. Similarly, RELEASEID is a string attribute, so a search could specify SELECT RELEASEID <> MARK41= to report files that do not start with a RELEASEID value of MARK41.

Examples

Example 1

This request examines all the files on disk that have no usercode and returns a list of files that are using more than 5000 sectors of disk space. The returned file list is to be sorted in decreasing number of sectors occupied—that is, from largest to smallest.

PDIR *= SELECT SECTORS > 5000 SORT - SECTORS

Example 2

This example lists all usercoded files on PACK that have a FILEKIND of MCPCODEFILE

PDIR (=)= ON PACK SELECT FILEKIND = MCPCODEFILE

Example 3

This example retrieves all nonusercoded files and puts the output in a JOBSYMBOL file named LARGE/FILES.

PDIR *= SORT - SECTORS SELECT SECTORS > 100000: FILE LARGE/FILES

Example 4

This example opens a remote file and routes it to a particular station.

PDIR MYFILES/=:REM MYSTATION/1

Example 5

This example shows the use of the TASKSTRING keyword. It displays the file name and size in sectors of the first file that matches the selection criteria.

 BEGIN JOB JOB/PDIR;
 STRING PARAM;
 TASK PDIR;
 PARAM := "*SYSTEM/MA= :TASKSTRING (NAME, SECTORS)";
 RUN SYSTEM/PDIR (PARAM) [PDIR];
 IF NOT PDIR (SW1) THEN
     DISPLAY (HEAD (PDIR (TASKSTRING), NOT ";"));
 END JOB 

Example 6

This example finds files with four nodes on their names in the WIN/STORAGE/TEMP directory, where the last node is quoted and ends in a common Windows TXT extension. The results are stored in a comma-separated value filed named, WIN/ANALYSIS/TEXT/FILES.

PDIR WIN/STORAGE/TEMP/˜ SELECT
  SHORTNAME = '"=.TXT"' OR SHORTNAME = '"=.txt"'
  SHORTNAME = '"=.DOC"' OR SHORTNAME = '"=.doc"'
  SHORTNAME = '"=.DOCX"' OR SHORTNAME = '"=.docx"'
  :CSV WIN/ANALYSIS/TEXT/FILES 

Error Messages

SYSTEM/PDIR displays the following error message if an input file name was not properly formatted:

No files were found

The most common cause of this error message is the use of quotation marks instead of (or without) apostrophes when the file name contains spaces. For example, using the following input

U SYSTEM/PDIR NODE1/= SELECT SHORTNAME = "NODE 2"      

to find the NODE1/"NODE 2" file would result in the “No files were found” error message, because double-quotes are part of the requested file name. The proper format is, as follows:

U SYSTEM/PDIR NODE1/= SELECT SHORTNAME = '"NODE 2"'

The following message indicates the the MCP interface ASERIES_INFO faulted while processing the input. A PROGRAMDUMP is taken automatically.

A fault was detected processing the request.

SYSTEM/PDIR displays the following error message if the request resulted in too many files to be reported:

Too many files to report them all. Use selection to limit files.

This means that the request returned too many files to report. Additional selection expressions can be added to reduce the number of files returned.

SYSTEM/PDIR displays error messages (instead of writing them to the output device) when run from WFL. You can suppress these error messages by setting the task attribute SW1 to TRUE. For example, the "No files were found" message will not be displayed by the following job:

BEGIN JOB JOB/PDIR/TASKSTRING;
STRING PDIR;
TASK TPDIR;

PDIR := "SYSTEM/MISSING/DIRECTORY/=: " &
        "TASKSTRING (NAME, SECTORS)";
TPDIR (SW1 = TRUE);
RUN SYSTEM/PDIR (PDIR) [TPDIR]; 
END JOB