|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
status = %U_GETFILENAME(filename, title, [#filters], [filter_desc], [filters], [default_name], & [extension], [input_column], [select_column], [list_column], [help_id][, option, ...])
Return value
status
On Windows, the filter index (1-based) that is returned by the Microsoft Open or Save As dialog box, or false if the Cancel button is pressed on the dialog box or if the dialog box returns an error.
On Unix and OpenVMS, true if a filename is selected, or false if no filename is selected or an error occurred. (^VAL)
Arguments
filename
Returned with the entered or selected filename. (a)
title
The title for the input window or dialog box. (a)
#filters
(optional) The number of file filters for browsing. (n)
filter_desc
(required if #filters passed) The array of filter descriptions. (a)
filters
(required if #filters passed) The array of filters. (a)
default_name
(optional) The default filename. (a)
extension
(optional) The default extension. (a)
input_column
(optional) The ID of the input column. (Unix, OpenVMS only) (n)
select_column
(optional) The ID of the selection column. (Unix, OpenVMS only) (n)
list_column
(optional) The ID of the list column. (Unix, OpenVMS only) (n)
help_id
(optional) The help identifier. (Unix, OpenVMS only) (a)
option
(optional) One or more of the following flags for Windows platforms. For traditional Synergy, you can pass more than one option by combining them with .BOR. or the vertical bar ( | ) operator. For Synergy .NET, only D_OFN_SAVEAS is valid. (Windows only) (n)
Center dialog box over application window.
No Network button.
Save as, instead of Open.
Don’t translate logicals.
Discussion
%U_GETFILENAME pops up a dialog box or window that enables the user to select a file either by entering a filename in a field or by browsing and then selecting a filename from a list. Note that to actually open the selected file, your program must call U_OPEN.
If the user selects a filename, g_select is set to false. Otherwise, g_select is set as follows:
- If the user pressed the “Cancel” button, g_select will be false. (Windows only)
- If the user selected the “O_EXIT” or “O_ABANDON” menu entry, g_select will be false.
- If the user selected some other menu entry that is not recognized by %U_GETFILENAME, g_select will be true.
On Windows, %U_GETFILENAME calls the standard file “Open” or “Save as” dialog box, and users can change directories as they browse.
On Unix and OpenVMS, %U_GETFILENAME goes through two or three stages:
| 1. | It opens a window with the “File” input field. The user can either enter a filename into this field or “browse” files. To browse, the user presses Enter on the empty field or selects the menu entry “O_BROWSE.” (You must include “O_BROWSE” on one of your menus to make it available.) The browse is limited to the initial directory. |
|
|
| 2. | (optional) If you passed the filter arguments (#filters, filter_desc, and filters) and if #filters is greater than one, when the user requests a browse, %U_GETFILENAME will display a filter description box. The user can select one of the filters, or select either the “O_EXIT” or “O_ABANDON” menu entry to return to the “File” input field. (These menu entries must be included on one of your menus.) |
|
|
| 3. | %U_GETFILENAME removes the filter description box (if displayed) and displays a file browse box containing the filenames associated with the selected filter. The title of the browse box is the filter description. The user can select a file, or select “O_EXIT” or “O_ABANDON” to go back to the previous input point (which would be either the filter description box or the “File” input field). |
|
|
On Unix and OpenVMS, %U_GETFILENAME uses I_INPUT to process the “File” input field, S_SELECT to process filter selections, and L_SELECT for the file browser box. So you can use reserved menu entries for these routines when %U_GETFILENAME is using them. For example, you can use the reserved menu entries for S_SELECT while your program processes filter selections. To use reserved menu entries for these routines, pass input_column, select_column, or list_column with the name of the menu column that contains the entries.
%U_GETFILENAME does not time out on Windows. If a time-out occurs on Unix and OpenVMS, g_select is set to true and g_entnam is set to the entry name specified by g_time_entry (see g_time_entry).
Filename is returned with the name of the selected file—whether entered directly into the “File (Name)” field or selected from the file browse box. If the user entered the filename into the “File (Name)” field, the returned filename also will contain any path specification explicitly typed. Native path specification or standard Synergy DBL logical translation (in the form of LOGICAL:filename) is supported.
If the variable passed as filename is not big enough to hold the full path specification, %U_GETFILENAME returns false, and filename will be blank. We recommend a variable size of 256.
On Windows, if the user enters a filename but no path, the current path of the dialog box will be prefixed to the returned filename. When the user first enters the dialog box, the initial path will be the path contained in default_name. If no path is specified in default_name or if default_name is not passed, the path will be the current working directory. (Remember, however, that on Windows the user may change the directory of the dialog box.)
On Unix and OpenVMS, if the user doesn’t include a path when entering the filename into the “File” field, any path contained in default_name will be prefixed to the returned filename.
title
On Windows, title becomes the title for the “Open” or “Save as” dialog box.
On Unix and OpenVMS, title becomes the title for the input window containing the “File” input field.
#filters, filter_desc, and filters
If #filters is passed, the filter_desc and filters arguments are required. If you do not pass the #filters argument, filter_desc and filters are ignored if they are passed.
Filter_desc must be an alphanumeric array of at least #filters elements. Each element must contain the description for one of the filters.
Filters must also be an alphanumeric array of at least #filters elements. The elements in the filters array contain the filters themselves. Be sure to use the appropriate form for your application’s system when specifying the elements in filters. For example, if an application generates script files, one of the filter elements might be *.wsc.
If #filters is not passed, the file browse box will contain all files and the filter description box will contain only the “All files (*.*)” filter.
On Unix and OpenVMS, the file browse box is built as a list with the filter description as the title.
default_name
If default_name is passed, filename will be returned with the contents of default_name if the user doesn’t select a filename.
If default_name is not passed and the user doesn’t select a filename, the contents of filename will be blank.
Default_name can include a complete path name (directory and filename). If no path is specified, %U_GETFILENAME searches for the default filename in the current working directory. You can use native path specification or standard Synergy DBL logical translation (in the form of LOGICAL:filename) as the path specification in default_name. See filename above for ramifications of including a path name.
extension
If extension is passed, when the user enters a filename without an extension into the “File (Name)” field, %U_GETFILENAME will append a period (“.”) followed by extension to the returned filename. If the user selects a file from the file browse box, extension is ignored.
input_column, select_column, and list_column (Unix and OpenVMS)
If input_column is passed, that column is placed before and removed after performing input to the “File (Name)” field.
If select_column is passed, that column is placed before and removed after processing the filter description box.
If list_column is passed, that column is placed before and removed after processing the file browse box.
help_id (Unix and OpenVMS)
If you pass help_id, %U_GETFILENAME will pass it to the current input routine. The current input routine will be
- I_INPUT if the “File (Name)” field is active.
- S_SELECT if the filter description box is active.
- L_SELECT if the file browse box is active.
option (Windows)
D_OFN_CENTER centers the dialog box over the application window, which matches behavior on Unix and OpenVMS. Default positioning on Windows is determined by Windows Common Dialogs and is generally in the upper left-hand corner of the screen.
D_OFN_NONETWORK suppresses the inclusion of the “Network” button in the dialog box. This button is included by default. If included, it enables the user to browse other file systems connected to the current system.
D_OFN_SAVEAS indicates that the standard “Save as” dialog box should be used instead of the “Open” dialog box. %U_GETFILENAME uses the “Open” dialog box by default.
D_OFN_NOTRANS indicates that any logicals entered by the user should not be translated in the filename that is returned.
