GetFileOpenName

PowerScript function

Description

Displays the system’s Open File dialog box and allows the user to
select a file or enter a file name.

Syntax

GetFileOpenName ( title, pathname, filename {, extension {, filter { , initdir { , aFlag } } } } )
GetFileOpenName ( title, pathname, filename[ ] {, extension {, filter { , initdir { , aFlag } } } } )

1 2	GetFileOpenName ( title, pathname, filename {, extension {, filter { , initdir { , aFlag } } } } ) GetFileOpenName ( title, pathname, filename[ ] {, extension {, filter { , initdir { , aFlag } } } } )

Argument

Description

title

A string whose value is the title of the dialog
box.

pathname

A string variable in which you want to store the returned
path. If the user selects a single file, the pathname variable
contains the path name and file name.

filename, filename[ ]

A string variable in which the returned file name is
stored or an array of string variables in which multiple
selected file names are stored. Specifying an array of string
variables enables multiple selection in the dialog box.

extension (optional)

A string whose value is a 1- to 3-character default file
extension. The default is no extension.

filter (optional)

A string whose value is a text description of the files to
include in the list box and the file mask that you want to use
to select the displayed files (for example, *.* or *.exe). The
format for filter is:

description,*. ext

1	description,*. ext

To specify multiple filter patterns for a single display
string, use a semicolon to separate the patterns, for
example:

"Graphic Files (*.bmp;*.gif;*.jpg;*.jpeg),
*.bmp;*.gif;*.jpg;*.jpeg"

1 2	"Graphic Files (.bmp;.gif;.jpg;.jpeg), .bmp;.gif;.jpg;.jpeg"

The default is:

"All Files (*.*),*.*"

1	"All Files (.),."

initdir (optional)

A string whose value is the initial directory name. The
default is the current directory.

aFlag (optional)

An unsigned long whose value determines which options are
enabled in the dialog box. The value of each option’s flag is
calculated as 2 to the power of (index -1), where index is the
integer associated with the option. The value of the aggregate
flag passed to GetFileOpenName is the sum of the individual
option flags. See the table in the Usage section for a list of
options, the index associated with each option, and the option’s
meaning.

Return value

Integer.

Returns 1 if it succeeds, 0 if the user clicks the Cancel button or
Windows cancels the display, and -1 if an error occurs. If any argument’s
value is null, GetFileOpenName returns null.

Usage

If you specify a DOS-style file extension and the user enters a file
name with no extension, PowerBuilder appends the default extension to the
file name. If you specify a file mask to act as a filter, PowerBuilder
displays only files that match the mask.

If you specify a string for the filename argument, the user can
select only one file. The pathname argument contains the path name and the
file name, for example C: emp est.txt.

If you specify a string array for the filename argument, the user
can select more than one file. If the user selects multiple files, the
pathname argument contains the path only, for example C: emp. If the user
selects a single file, its name is appended to the pathname argument, for
example C: emp est.txt.

You use the filter argument to limit the types of files displayed in
the list box and to let the user know what those limits are. For example,
to display the description Text Files (*.TXT) and only files with the
extension .TXT, specify the following for filter:

"Text Files (*.TXT),*.TXT"

1	"Text Files (.TXT),.TXT"

To specify more than one file extension in filter, enter multiple
descriptions and extension combinations and separate them with commas. For
example:

"PIF files, *.PIF, Batch files, *.BAT"

1	"PIF files, .PIF, Batch files, .BAT"

The dialog boxes presented by GetFileOpenName and GetFileSaveName
are system dialog boxes. They provide standard system behavior, including
control over the current directory. When users change the drive,
directory, or folder in the dialog box, they change the current directory
or folder. The newly selected directory or folder becomes the default for
file operations until they exit the application, unless the optional
initdir argument is passed.

The aFlag argument is used to pass one or more options that
determine the appearance of the dialog box. For each option, the value of
the flag is 2^(index -1), where index is an integer associated with each
option as shown in the following table. You can pass multiple options by
passing an aggregate flag, calculated by adding the values of the
individual flags.

If you do not pass an aFlag, the Explorer-style open file dialog box
is used. If you do pass a flag, the old-style dialog box is used by
default. Some options do not apply when the Explorer-style dialog box is
used. For those that do apply, add the option value for using the
Explorer-style dialog box (2) to the value of the option if you want to
display an Explorer-style dialog box.

For example, passing the flag 32768 (2^15) to the GetFileSaveName
function opens the old-style dialog box with the Read Only check box
selected by default. Passing the flag 32770 opens the Explorer-style
dialog box with the Read Only check box selected by default.

Index	Constant name	Description
1	OFN_CREATEPROMPT	If the specified file does not exist, prompt for permission to create the file. If the user chooses to create the file, the dialog box closes; otherwise the dialog box remains open.
2	OFN_EXPLORER	Use an Explorer-style dialog box.
3	OFN_EXTENSIONDIFFERENT	The file extension entered differed from the extensions specified in extension.
4	OFN_FILEMUSTEXIST	Only the names of existing files can be entered.
5	OFN_HIDEREADONLY	Hide the Read Only check box.
6	OFN_LONGNAMES	Use long file names. Ignored for Explorer-style dialog boxes.
7	OFN_NOCHANGEDIR	Restore the current directory to its original value if the user changed the directory while searching for files. This option has no effect for GetFileOpenName on Windows NT.
8	OFN_NODEREFERENCELINKS	Return the path and file name of the selected shortcut (.lnk file); otherwise the path and file name pointed to by the shortcut are returned.
9	OFN_NOLONGNAMES	Use short file names (8.3 format). Ignored for Explorer-style dialog boxes.
10	OFN_NONETWORKBUTTON	Hide the Network button. Ignored for Explorer-style dialog boxes.
11	OFN_NOREADONLYRETURN	The file returned is not read only and is not in a write-protected directory.
12	OFN_NOTESTFILECREATE	Do not create the file before the dialog box is closed. This option should be specified if the application saves the file on a network share where files can be created but not modified. No check is made for write protection, a full disk, an open drive door, or network protection. A file cannot be reopened once it is closed.
13	OFN_NOVALIDATE	Invalid characters are allowed in file names.
14	OFN_OVERWRITEPROMPT	Used in Save As dialog boxes. Generates a message box if the selected file already exists.
15	OFN_PATHMUSTEXIST	Only valid paths and file names can be entered.
16	OFN_READONLY	Select the Read Only check box when the Save dialog box is created.

Opening a file

Use the FileOpen function to open a selected file.

Examples

The following example displays a Select File dialog box that allows
multiple selection. The file types are TXT, DOC, and all files, and the
initial directory is C:Program FilesAppeon. The option flag 18 specifies
that the Explorer-style dialog box is used (2^1 = 2), and the Read Only
check box is hidden (2^4 = 16). The selected filenames are displayed in a
MultiLineEdit control.

If the user selects a single file, the docpath variable contains
both the path and the file name. The example contains an IF clause to
allow for this.

string docpath, docname[]
integer i, li_cnt, li_rtn, li_filenum


li_rtn = GetFileOpenName("Select File", &amp;
   docpath, docname[], "DOC", &amp;
   + "Text Files (*.TXT),*.TXT," &amp;
   + "Doc Files (*.DOC),*.DOC," &amp;
   + "All Files (*.*), *.*", &amp;
   "C:Program FilesAppeon", 18)

mle_selected.text = ""
IF li_rtn &lt; 1 THEN return
li_cnt = Upperbound(docname)

// if only one file is picked, docpath contains the 
// path and file name
if li_cnt = 1 then
   mle_selected.text = string(docpath)
else

// if multiple files are picked, docpath contains the 
// path only - concatenate docpath and docname
   for i=1 to li_cnt
      mle_selected.text += string(docpath) &amp;
         + "" +(string(docname[i]))+"~r~n"
   next
end if

string docpath, docname[]

integer i, li_cnt, li_rtn, li_filenum

li_rtn = GetFileOpenName("Select File", &

docpath, docname[], "DOC", &

+ "Text Files (*.TXT),*.TXT," &

+ "Doc Files (*.DOC),*.DOC," &

+ "All Files (*.*), *.*", &

"C:Program FilesAppeon", 18)

mle_selected.text = ""

IF li_rtn < 1 THEN return

li_cnt = Upperbound(docname)

// if only one file is picked, docpath contains the

// path and file name

if li_cnt = 1 then

mle_selected.text = string(docpath)

else

// if multiple files are picked, docpath contains the

// path only - concatenate docpath and docname

for i=1 to li_cnt

mle_selected.text += string(docpath) &

+ "" +(string(docname[i]))+"~r~n"

end if

In the following example, the dialog box has the title Open and
displays text files, batch files, and INI files in the Files of Type
drop-down list. The initial directory is d: emp. The option flag 512
specifies that the old-style dialog box is used and the Network button is
hidden (2^9 = 512).

// instance variables
// string is_filename, is_fullname
int   li_fileid

if GetFileOpenName ("Open", is_fullname, is_filename, &amp;
   "txt", "Text Files (*.txt),*.txt,INI Files " &amp;
   + "(*.ini), *.ini,Batch Files (*.bat),*.bat", &amp;
   "d:	emp", 512) &lt; 1 then return

li_fileid = FileOpen (is_fullname, StreamMode!)
FileRead (li_fileid, mle_notepad.text)
FileClose (li_fileid)

// instance variables

// string is_filename, is_fullname

int li_fileid

if GetFileOpenName ("Open", is_fullname, is_filename, &

"txt", "Text Files (*.txt),*.txt,INI Files " &

+ "(*.ini), *.ini,Batch Files (*.bat),*.bat", &

"d: emp", 512) < 1 then return

li_fileid = FileOpen (is_fullname, StreamMode!)

FileRead (li_fileid, mle_notepad.text)

FileClose (li_fileid)

See also

Document get from Powerbuilder help

Thank you for watching.

Powerbuilder Documentation 2021

August 21, 2023

Was this article helpful?

Connection Information

GetFileOpenName – PB Docs 2021