Updated April 2010

xcall MIAMEX, MX_GETOFD, path, filter, title, flags {,defext, fname, type}

(Windows/ATE only) This function displays the standard Windows open file or save file dialog. It can only take place on a GUI-enabled client, either ATE or some form of A-Shell/Windows.

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

Parameters

path  (String, 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). On return, it will contain the full filespec (in Windows notation) of the selected file. If the OFN_ALLOWMULTISELECT flag is specified, then on return it will contain the directory (where the selected files are located), followed by a chr(10), follow by one or more filenames (name.ext) each separated by chr(10) characters.

filter  (String)  [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"

title  (String)  [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)  [in]

may be set to any combination of the flags shown on the table below. The table also indicates the Windows name for the flag, which might be of use to programmers who are familiar with the GetOpenFileName and GetSaveFileName functions, or who have access to the Windows API documentation. The symbol names are not defined to A-Shell, but if you use this function, you may want to use correspondingly named variables to make your code understandable. flags may be updated by the function on return.

Symbol	Value	Description
OFN_HIDEREADONLY	&h00000004	Hides the read-only checkbox
OFN_NOCHANGEDIR	&h00000008	This function is no longer supported (as of  Windows NT4 / 2000 / XP).
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	(Win2000/XP) Do not add file to the user’s most recently used document list

Hex-Decimal Values

 

defext  (String)  [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)  [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 the OFN_ALLOWMULTISELECT flag is set. Maximum length is approximately 256.

type  (Num)  [in]

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

Comments

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

 

Error Number	Error Type	Description
0x0001- 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 invalid
0x3003	Buffer too small	Selected file name is too long to fit in the provided return buffer

 

 

Compatibility

 

OS	A-Shell	ATE	Latest	ATE	AMOS	See Also
Win, UNIX/ATE	5.0.983	5.0.983	5.0.998	Auto	Use ?Tab(-10,AG_SHLEXC) instead.	?Tab (-10,AG_WINEXEC),HOSTEX

 

See Compatibility Table Glossary for explanation of headings, abbreviations, terms, etc.

History

2009 October, A-Shell 5.1.164: Append "\" when needed