$ZSEARCH = $ZSEARCH

Returns the full file specification, pathname, and filename of the specified file.

The outline

$ZSEARCH(target)
$ZSE(target)
Copy the code

parameter

• Target File name, pathname, or empty string. It may contain one or more*or?Wildcards.

describe

$ZSEARCH returns the full file specification (pathname and filename) for the specified target file or directory. The file name can include wildcards so that $ZSEARCH can return a standard list of pathnames that satisfy wildcards.

Note: Some operating systems use the slash (/) character as a directory path separator. Other operating systems use the backslash (\) character. In this note, the word “slash” means a slash or backslash (as the case may be).

If the target parameter does not specify a pathname, $ZSEARCH searches the current working directory. $ZSEARCH applies the rules in the following order during its matching:

1. $ZSEARCHScans the target to see if there are percentage characters around it (%). if$ZSEARCHFinding such text, it treats the string as an environment variable.$ZSEARCHPerforms name conversions on strings.
2. $ZSEARCHScan the string generated in the previous step to find the last slash. if$ZSEARCHFinds the last slash, which uses the string up to (but not including) the last slash as the path or directory to search. if$ZSEARCHIf the last slash is not found, it searches for the current working directory determined by the current namespace.
3. if$ZSEARCHThe last slash was found in the previous step, and it uses the part of the target string after the last slash as the file name search pattern. if$ZSEARCHThe last slash was not found in the previous step, which uses the entire string generated in Step 1 as the file name search pattern.

The filename search mode can be any valid filename string or filename wildcard expression. The first file name that matches the search pattern is returned as the value of the $ZSEARCH function. Which file is the first to match is platform dependent (as described in the comments section).

If the empty string is specified as the target the next time $ZSEARCH is called, $ZSEARCH continues with the previous target and returns the next filename that matches the search pattern. When no other files match the search pattern, $ZSEARCH returns an empty string.

The NormalizeDirectory() method of the % library.file class can also be used to return the full pathname of a specified File or directory, as shown in the following example:

DHC-APP>WRITE ##class(%Library.File).NormalizeDirectory("CACHE.DAT"),!
E: \DtHealth\db\dthis\data\CACHE.DAT\
 
DHC-APP>ZNSPACE "USER"
 
USER>WRITE# #class(%Library.File).NormalizeDirectory("CACHE.DAT")
C: \InterSystems\Cache\mgr\user\CACHE.DAT\
Copy the code

However, NormalizeDirectory() cannot use wildcards.

The wildcard

$ZSEARCH allows the following wildcard expressions to be used in quoted target strings.

These wildcards follow the rules of use for the host platform. On Windows, $ZSEARCH performs a case-independent search and then returns the actual case of the file or directory found. For example, “j*” can match “Journal”, “Journal”, or “Journal”; The actual directory name is “Journal”, which is the name returned.

On Windows and UNIX® systems, the following standard pathname symbols can also be used: single point (.) . Specify current directory or double dot (..) . To specify the parent directory, do the following. These symbols can be combined with wildcards.

parameter

target

Here are the available value types for the target parameters:

The sample

The following Windows example looks for all files with “.dat “as a file extension in the Samples namespace.

/// d ##class(PHA.TEST.Function).ZSEARCH()
ClassMethod ZSEARCH(a)
{
	NEW $NAMESPACE
	SET $NAMESPACE="Samples"
	SET file=$ZSEARCH("*.DAT")
	WHILE file'="" { WRITE ! ,file SET file=$ZSEARCH("") } WRITE ! ," This is all the files that match "QUIT}Copy the code

DHC-APP>d ##class(PHA.TEST.Function).ZSEARCH(a)C: \InterSystems\Cache\mgr\samples\CACHE.DATThis is all the files that matchCopy the code

The following Windows example looks for all files starting with the letter “C” in the Samples namespace.

/// d ##class(PHA.TEST.Function).ZSEARCH1()
ClassMethod ZSEARCH1(a)
{
	NEW $NAMESPACE
	SET $NAMESPACE="dhc-app"
	SET file=$ZSEARCH("c*")
	WHILE file'="" { WRITE ! ,file SET file=$ZSEARCH("") } WRITE ! ," This is all the files that match "QUIT}Copy the code

DHC-APP>d ##class(PHA.TEST.Function).ZSEARCH1(a)E: \DtHealth\db\dthis\data\CACHE.DAT
E: \DtHealth\db\dthis\data\cache.lckThis is all the files that matchCopy the code

Pay attention to

Directory to lock

To provide accurate results, this procedure keeps the directory open until $ZSEARCH returns all the files in the directory (that is, until $ZSEARCH returns an empty string or starts a new $ZSEARCH). This may prevent other operations, such as directory deletion. When you start $ZSEARCH, you should always repeat $ZSEARCH(” “) until it returns an empty string. If you do not want to retrieve all the files, you can also issue $ZSEARCH with a filename that is known not to exist, such as $ZSEARCH(-1).

Windows support

For Windows, the target parameters are standard file specifications and may contain wildcards (* and?). .

• The wildcard*Can be used to match points, but?The wildcard cannot. As a result,"MYFILE *"withMYFILEFOLDER,MYFILE.DOCandMYFILEBACKUP.DOCMatching;"MYFILE? DOC"withMYFILE.DOCDon’t match.
• ?Wildcards do not match zero characters in the name element. As a result,"My? FILE. The DOC"withMY2FILE.DOCMatch, but withMYFILE.DOCDon’t match.
• ?Wildcards match zero characters at the end of the name element. Extra trailing?Wildcard characters are ignored. As a result,"MYFILE? .doc"At the same time matchingMYFILE2.DOCandMYFILE.DOC.

If no directory is specified, the current working directory is used. $ZSEARCH returns the first matching entry in the directory in alphabetical order. It returns either the full file specification or the fully qualified pathname. Regardless of how specified, the drive letter is always returned in uppercase.

By default, the window only checks the first three characters of the file extension suffix. Therefore, $ZSEARCH(“*. Doc) will not only return all strings. File suffixes, but also include all carries. Docx suffix. If you want to limit your search. For docx files, you must specify a four-character suffix :$ZSEARCH(*).

UNIX ® support

For UNIX, the target parameters are standard UNIX file specifications and may contain wildcards (* and?). . If no directory is specified, the current working directory is used.

For UNIX®, $ZSEARCH returns the first active entry in the directory. Because UNIX® does not save directory entries alphabetically, the return values are not alphabetically ordered. Unlike the Windows platform, the $ZSEARCH function does not return the full file specification or fully qualified pathname unless the current working directory is used.