Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## 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 (`?`).

> #### Syntax

>     SEARCH ( opsys-file )

> ``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.

> Example

> 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 FORMAT "x(55)".
>     DEFINE VARIABLE filename AS CHARACTER 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.

> #### Notes

> - 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`.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095