# MX\_GETOFD

> [HTML Version](mx_getofd.htm)

_Updated February 2021; see History_

**xcall MIAMEX, MX\_GETOFD, path, filter, title, flags \{,defext, fname, type\}**

(Windows/ATE only) MX\_GETOFD (MIAMEX 95) displays the standard Windows open file or save file dialog. It can only take place on a GUI-enabled client, either ATE or A-Shell/Windows. Note that the routine can be called with just two parameters; see History.

This function has both a [subroutine and a print tab implementation](subroutine-print-pairs.htm.md).

**Parameters**

_path_  ([String](string.htm.md), up to a maximum of 4096 bytes)  \[in/out\]

On input, must contain the default filespec or the default directory, fully qualified, in AMOS or Windows notation. See Comments.

On return, it will contain the full filespec (in Windows notation) of the selected file(s). If more than one file was selected (see OFN\_ALLOWMULTISELECT in _flags_), the individual filespecs will be separated by chr(10) characters, and all but the first filespec will be stripped down to just the file name and extension, since they will all be in the same directory.

_filter_  \[in\]

is a set of pairs of strings, concatenated all together using pipes ("|") for delimiters, determining which files will display in the dialog box. The first string in each pair is descriptive, and will display in the "Files of Type" area of the dialog box. The second string in each pair is a wildcard specification for that kind of file. If you have more than one wildcard spec for a particular descriptive name, then separate them with semicolons. For example:

FILTER="Data files|\*.DAT|Text files|\*.TXT; \*.LST"

Note that the "Files of Type" control is actually a drop-down box and that "Data files" will show as the initial choice, and "Text Files" will be the next choice in the list. If you want them all appear together, then just specify one pair of strings, such as:

FILTER="Image Files (\*.pcx, \*.jpg, \*.bmp)|\*.pcx; \*.jpg; \*.bmp"

Also note: do not include any spaces on either side of the | delimiter characters lest they be confused with the pattern, causing a failure to match any files.

_title_  ([String](string.htm.md))  \[in\]

may be set to the desired title of the dialog box. The default is "Open". This is the main difference between the File Open and File Save versions of the dialog box. See _type_ parameter.

_flags_  ([Num](num.htm.md))  \[in/out\]

May be set to any combination of the options shown below. 

Note that since the parameter may be updated on return from the function (see OFN\_EXTENSIONDIFFERENT and OFN\_NOREADONLYRETURN), you will have to use an actual variable for the _flags_ parameter if you want to be so advised. Otherwise you can just specify an expression consisting of the literal flags, e.g. OFN\_PATHMUSTEXIST+OFN\_FILEMUSTEXIST.

Note also that MX\_GETOFD is primarily a wrapper for the Windows API Function GetOpenFileName() which seems to support additional _flags_ with each new version of Windows. Consult the Microsoft documentation for more complete and up-to-date information on available _flags_.

| **Symbol** | **Value** | **Description** |
|------|------|------|
| OFN\_HIDEREADONLY | \&h00000004 | Hides the read-only checkbox |
| OFN\_NOCHANGEDIR | \&h00000008 | This function is no longer supported. |
| OFN\_FOLDERONLY | \&h00000080 | Select folder only |
| OFN\_NOVALIDATE | \&h00000100 | Do not force filename entered to contain only valid characters. |
| OFN\_ALLOWMULTI­SELECT | \&h00000200 | Allow the selection of multiple files. (OFN\_­EXPLORER flag should be set along with this.) Successive names will appear, null delimited, in the returned PATH variable. |
| OFN\_EXTENSION­DIFFERENT | \&h00000400 | Set on return if the extension entered differs from _defext_ |
| OFN\_PATHMUSTEXIST | \&h00000800 | Specified directory must exist |
| OFN\_FILEMUSTEXIST | \&h00001000 | Specified file must exist. (Implies that OFN\_­PATHMUSTEXIST) |
| OFN\_CREATEPROMPT | \&h00002000 | Prompt for permission to create the file if the file does not already exist |
| OFN\_NOREADONLY­RETURN | \&h00008000 | Set on return if file not read-only, directory writeable |
| OFN\_NONETWORK­BUTTON | \&h00020000 | Disables the network button |
| OFN\_EXPLORER | \&h00080000 | Forces the dialog box to be in the new Explorer-style. This is the default in most cases, except when OFN\_ALLOWMULTISELECT is set. |
| OFN\_DONTADDTO­RECENT | \&h02000000 | Do not add file to the user’s most recently used document list |
| OFN\_FORCESHOWHIDDEN | \&h10000000 | Force showing hidden \& system files |
| OFN\_FORCEPREVIEWPANEON | \&h40000000 | Forces Preview pane on |
| **Definition file: [ashell.def](ashell_def.htm.md)** | | 

[Hex-Decimal Values](hex-decimalvalues.htm.md)



_defext_  ([String](string.htm.md))  \[in\]

may specify the default file extension. Do not include the period. If specified and the user types a filename with no extension, this will be appended to the returned _path_ and _fname_ parameters.

_fname_  ([String](string.htm.md))  \[out\]

is an optional convenience that will return just the filename and extension, without the rest of the path, saving you from having to parse it out of the _path_ string. Note, however, that it is not guaranteed to be in the directory you initially specified. Parameter is ignored if OFN\_ALLOWMULTISELECT is set. Maximum length is approximately 256.

_type_  ([Num](num.htm.md))  \[in\]

If specified and set to 1, the main button will say "Save" rather than "Open". This and the title are the main differences between an Open dialog and a Save dialog.

**Comments**

Note that if the initial path or directory is in the form of a drive letter and colon with no trailing slash (e.g. "C:"), MX\_GETOFD automatically appends "\\" to avoid confusion. Such ambiguous specs are otherwise likely to be misinterpreted by A-Shell and/or Windows.

If there is an error in the format of the parameters, such that the dialog fails to display, A-Shell will open the System Messages window and display a short message with the internal Windows error number; see descriptions in the following table.



| **Error Num** | **Error Type** | **Description** |
|------|------|------|
| 0x0001-   <br>0x000C | System errors | These suggest low level problems in Windows (lack of resources, inability to lock memory, etc. |
| 0x3001 | Subclass failure | Suggests lack of PC memory |
| 0x3002 | Invalid filename | File spec in path parameter is invalid |
| 0x3003 | Buffer too small | Selected file name is too long to fit in the provided return buffer |




**See Also**

•	[MX\_BROWSEFOLDER](mx_browsefolder.htm.md)

•	[MX\_GETSHELLPATH](mx_getshellpath.htm.md)

•	[Display Open/Save File Dialog](ag_getofd.htm.md)

•	[AG\_GETOFD](ag_getofd.htm.md)

**History**

2021 February A-Shell 6.5.1699:  Support SBR=GETOFD\_NOCOM to revert to old implementation

2021 February, A-Shell 6.5.1698:  add new flag OFN\_FORCEPREVIEWPANEON as part of update to File Open / File Save dialog. The OFN\_EXPLORER option is now essentially meaningless—i.e., it is always on.

2016 March, A-Shell 6.2.1425:  minimum number of parameters has been reduced from five to two, allowing you to call it with just xcall MIAMEX, MX\_GETOFD, PATH\$

2013 July, A-Shell 6.1.1355:  filenames containing commas are now quoted; previously they were not, which almost certainly led to incorrect parsing of the response