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

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 NO-UNDO 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.

r-fildlg.p

DEFINE VARIABLE procname  AS CHARACTER NO-UNDO. 
DEFINE VARIABLE OKpressed AS LOGICAL   NO-UNDO 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.