Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## SYSTEM-DIALOG GET-FILE statement

> ##
> (Windows only)

> Displays a dialog box that allows the user to enter a filename that is assigned to a character variable. The SYSTEM-DIALOG GET-FILE statement provides a dialog box appropriate to the environment in which it runs.

> Note: Does not apply to SpeedScript programming.

> #### Syntax

>     SYSTEM-DIALOG GET-FILE character-field
>       [   FILTERS name filespec
>           [ , name filespec ] ...
>           [ INITIAL-FILTER filter-num ]
>       ]
>       [ ASK-OVERWRITE ]
>       [ CREATE-TEST-FILE ]
>       [ DEFAULT-EXTENSION extension-string ]
>       [ INITIAL-DIR directory-string ]
>       [ MUST-EXIST ]
>       [ RETURN-TO-START-DIR ]
>       [ SAVE-AS ]
>       [ TITLE title-string ]
>       [ USE-FILENAME ]
>       [ UPDATE logical-variable ]
>       [ IN WINDOW window ]

> ``character-field``

> The character field or variable that contains the filename the user enters. The user can enter the filename by typing it or selecting it from a list of files in the common dialog directory. The user confirms the entry and completes the dialog by choosing the OK button. The user can interrupt the dialog without any selection by choosing the Cancel button.

> You can also use `character-field` to pass a default filename entry to the dialog. See the USE-FILENAME option for more information.

> `FILTERS `name` `filespec``

> Defines one or more filters for the filename dialog. Each filter selects a subset of the available files in the common dialog directory to build the dialog file selection-list. A filter consists of two parts: a label (`name`) and file specification (`filespec`).

> The `name` is a character expression used as a label for your filter. Windows uses the label to identify the filter in a filter selection-list. The user can select the label to view the list of files selected by the filter.

> The `filespec` is a character expression that evaluates to a file specification string. This string can consist of any wild cards or regular expressions used to generate valid file specifications in your environment. In Windows, `filespec` can also consist of multiple file specifications, separating each one with a comma, for example: *.p,*.i,*.r.

> If you do not specify any filters, the dialog builds the selection-list with all files in the directory.

> `INITIAL-FILTER `filter-num``

> Specifies the initial filter list defined by the FILTERS option, where `filter-num` is an integer expression that evaluates to the position of the filter in the list, starting from 1.

> If you do not specify the INITIAL-FILTER option, the dialog uses the first filter in the list as the initial filter.

> `ASK-OVERWRITE`

> Causes a the dialog to prompt for confirmation if the user enters the name of a file that already exists. By default, the dialog does not prompt for confirmation if the user enters an existing filename. In Windows, this option is ignored unless SAVE-AS is also specified.

> `CREATE-TEST-FILE`

> Causes the filename dialog to create a temporary file before it completes in order to verify that the user has write access to the directory path specified for the filename entry. If the dialog cannot write the file, it displays an error message and prompts for another filename entry. The dialog does not complete until the user enters a filename associated with a writable directory or chooses the Cancel button to interrupt the dialog. After successful completion, the dialog deletes the temporary file.

> This option is especially appropriate with the SAVE-AS option to verify the ability to save a file.

> `DEFAULT-EXTENSION `extension-string``

> Specifies a default extension (or suffix) to be appended to the user’s filename entry after completing the filename dialog, where `extension-string` is a character expression that evaluates to a valid file extension in your environment, including all required punctuation. In Windows, the extension must start with a period.

> The Windows dialog appends the specified extension to the user’s filename entry only if the entry does not already contain an extension.

> `INITIAL-DIR `directory-string``

> Sets the starting directory for this invocation of SYSTEM-DIALOG GET-FILE to the pathname specified in `directory-string` before starting the dialog. The `directory-string` is a character expression that must evaluate to a valid pathname in your environment. The default starting directory is either the current working directory or the directory left from the last invocation of SYSTEM-DIALOG GET-FILE.

> `MUST-EXIST`

> Requires that the user’s filename entry, complete with any specified default extension, must exist in the directory specified for the filename entry before the dialog completes. If it does not exist, the dialog displays an error message and prompts for another filename entry. The dialog does not complete until the user enters the name of an existing file or chooses the Cancel button to interrupt the dialog.

> `RETURN-TO-START-DIR`

> This option resets the current directory to the starting directory when the common dialog ends. This is the directory specified by the INITIAL-DIR option or the default starting directory.

> If you do not specify this option, the directory remains set at the last directory referenced by the user. This directory becomes the default initial directory for subsequent invocations of SYSTEM-DIALOG GET-FILE. This option also has no effect on subsequent invocations that specify the INITIAL-DIR option.

> `SAVE-AS`

> Causes the dialog box to become a Save As dialog box. For a Save As dialog box, the default box title is “Save As”. You can use the ASK-OVERWRITE option with SAVE-AS to get confirmation before accepting an existing file from the dialog.

> `TITLE `title-string``

> Specifies a title for the dialog box. The value `title-string` can be any character expression. If you do not specify a title, the dialog uses the system default for your environment.

> `USE-FILENAME`

> Specifies the contents of `character-field` as the default filename entry for the dialog.

> During the dialog, the user can accept the default entry or override it by entering or selecting another filename.

> `UPDATE `logical-variable``

> Specifies a logical variable to return the status of the user’s filename dialog interaction. If the user chooses the OK button, the dialog sets `logical-variable` to TRUE. If the user chooses the Cancel button, the dialog sets `logical-variable` to FALSE.

> `IN WINDOW `window``

> Specifies the window from which the dialog box is displayed. The value `window` must be the handle of a window.

> Example

> The following example uses the filename dialog box to run procedures. It allows the user to select and run procedure files until they choose the Cancel button:

> r-fildlg.p
>     DEFINE VARIABLE procname AS CHARACTER NO-UNDO.
>     DEFINE VARIABLE OKpressed AS LOGICAL INITIAL TRUE.

>     Main:
>     REPEAT:
>         SYSTEM-DIALOG GET-FILE procname
>             TITLE      "Choose Procedure to Run ..."
>             FILTERS    "Source Files (*.p)"   "*.p",
>                        "R-code Files (*.r)"   "*.r"
>             MUST-EXIST
>             USE-FILENAME
>             UPDATE OKpressed.

>         IF OKpressed = TRUE THEN
>             RUN VALUE(procname).
>         ELSE
>             LEAVE Main.
>     END.

> #### Notes

> - The default common dialog directory for the initial invocation of SYSTEM-DIALOG GET-FILE is the current working directory. You can specify a different starting common dialog directory with the INITIAL-DIR option and the user can change the common dialog directory by referencing a different directory in the common dialog.

> - The Windows common dialog never searches the `PROPATH`, and always returns the full pathname of the entered relative pathname appended to the current common dialog directory.

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