SEARCH function

Searches the directories and libraries defined in the PROPATH environment variable for a file. The SEARCH function returns the full pathname of the file unless it is found in your current working directory. If SEARCH does not find the file, it returns the Unknown value (?).

SEARCH ( `opsys-file` )

A character expression whose value is the name of the file you want to find. The name can include a complete or partial directory path. If opsys-file is a constant string, you must enclose it in quotation marks (" "). The value of opsys-file must be no more than 255 characters long.

In this procedure, the SEARCH function returns the fully qualified pathname of the filename entered if it is not in the current working directory. If SEARCH cannot find the file, it returns the Unknown value (?). The procedure displays the fully qualified pathname or a message indicating that the file could not be found.

r-search.p
DEFINE VARIABLE fullname AS CHARACTER NO-UNDO FORMAT "x(55)". DEFINE VARIABLE filename AS CHARACTER NO-UNDO FORMAT "x(20)". REPEAT: UPDATE filename HELP "Try entering ’help.r’ or ’dict.r’" WITH FRAME a SIDE-LABELS CENTERED. fullname = SEARCH(filename). IF fullname = ? THEN DISPLAY "UNABLE TO FIND FILE " filename WITH FRAME b ROW 6 CENTERED NO-LABELS. ELSE DISPLAY "Fully Qualified Path Name Of:" filename SKIP(2) "is:" fullname WITH FRAME c ROW 6 NO-LABELS CENTERED. END.

The SEARCH function is double-byte enabled. You can specify a filename with the opsys-file argument that contains double-byte characters.

Use the SEARCH function to ensure that procedures that get input from external data files are independent of specific directory paths. The files must be in one of the directories or libraries defined in the PROPATH environment variable.

Typically, the PROPATH includes a nil entry representing the current working directory. If the SEARCH function finds the file when searching this entry, it returns only the simple name of the file rather than the full pathname. If the PROPATH does not include a nil entry or another entry that specifies the current working directory, the SEARCH function does not search the current working directory.

If you provide a fully qualified pathname, SEARCH checks if the file exists. In this case, SEARCH does not search directories on the PROPATH.

When you search for a file that is in a library, SEARCH returns the file’s pathname in the form path-name<<member-name>>, where path-name is the pathname of the library and member-name is the name of the file. The double angle brackets indicate that the file is a member of a library. For example, in the path /usr/apps.pl<<proc1.r>>, proc1.r is the name of the file in the library apps.pl.

The LIBRARY function and MEMBER function use the special syntax to return, respectively, the library name and member-name of the file in the library.

If an application repeatedly runs a procedure, you can improve performance by using the SEARCH function once to build a full pathname for that procedure. Use this value in the RUN statement to avoid repeated searches of the PROPATH.

In Windows, you can specify URL pathnames on the PROPATH. If the file is found in a directory specified by a URL, SEARCH returns the full URL pathname of the file which includes the filename appended to the URL PROPATH entry. If you provide a fully-qualified URL, SEARCH checks if the file exists. In this case, SEARCH does not search URLs on the PROPATH. Valid URL protocols include HTTP and HTTPS.

Note: URL pathnames cannot contain the percent symbol (%). If an error exists in a URL specified on the PROPATH, the SEARCH function continues searching with the next PROPATH entry.

If you specify URL pathnames on the PROPATH and your application repeatedly uses the LOAD-ICON( ), LOAD-SMALL-ICON( ), LOAD-IMAGE( ), LOAD-IMAGE-DOWN( ), LOAD-IMAGE-UP( ), LOAD-IMAGE-INSENSITIVE( ), or LOAD-MOUSE-POINTER( ) methods with a URL pathname, you can improve performance by using the SEARCH function once to determine the full URL pathname to the directory containing the image files. Use this value with the load methods to avoid repeated searches of the PROPATH.