GUI ScreenIO for Windows

 ScreenIO.com


GetOpenFileName

This API displays the standard Windows Open dialog used to select the drive, directory, and name of a file (or set of files) to open.

To select folders (directories) instead of files see BrowseForFolder.  See the CAUTION at the bottom of this page.

Client/Server issues

No issues; this API will behave as if it were running locally on the client.

Files

Files available to copy to your system:

Usage

     COPY WIN32API.
     COPY OPENSAVE.

* ------------------------: Call the API.

     SET API-GETOPENFILENAME TO TRUE.

     CALL 'GSWINAPI' USING WIN32API-PARMS
                           OPENSAVE-PARMS
                           OPENSAVE-INITIALDIR
                           OPENSAVE-FILTER
                           OPENSAVE-CUSTOMFILTER
                           OPENSAVE-FILESPEC
                           OPENSAVE-FILENAME.

Parameters specific to this function

OPENSAVE-WINDOW-TITLE

Specifies the text that will be displayed in the title bar of the open dialog when it is displayed.

OPENSAVE-DEFAULT-EXTENSION

Null-terminated default file extension to use, for example:

     STRING 'INI'
            LOW-VALUE DELIMITED SIZE
       INTO OPENSAVE-DEFAULT-EXTENSION.

OPENSAVE-FLAGS

A combination of bit flags that specify various options used to initialize the common dialog.  The most useful ones are:

You OR these values to specify the bit values used for OPENSAVE-FLAGS.  You can ADD them together, but you must be certain that the addition does not result in a carry, which would not set the desired bits.

You assign these values like this:

 OFN-EXPLORER  PIC 9(9) COMP-5 VALUE H'080000'.     

Flag Value Description
OFN-ALLOWMULTISELECT 000200h Allows the user to select more than one file.
OFN-CREATEPROMPT 002000h If the user specifies a file that doesn't exist, prompt the user for permission to create the file.
OFN-EXPLORER 080000h Specifies the use of new Explorer-style customization methods.  Required if you specify OFN-ALLOWMULTISELECT.
OFN-EXTENSIONDIFFERENT 000400h Allows the user to specify a file extension other than the default extension.
OFN-FILEMUSTEXIST 001000h Specifies the user can only type names of existing files in the File Name field. 

Requires OFN-PATHMUSTEXIST.

OFN-HIDEREADONLY 000004h Hides the Read Only checkbox.
OFN-LONGNAMES 200000h Not used
OFN-NOCHANGEDIR 000008h Restores the current directory to its original value if the user changed it while searching for a file.
OFN-NODEREFERENCELINKS 100000h Directs the API to return the path and file name of the selected shortcut (.LNK) file.  Otherwise, it will return the path and filename of the file referenced by the shortcut.
OFN-NOLONGNAMES 040000h Not used
OFN-NONETWORKBUTTON 020000h Hides and disables the Network button.
OFN-NOREADONLYRETURN 008000h Prevents selection of read-only files, or files in a read-only subdirectory.
OFN-NOTESTFILECREATE 010000h Specifies that the file is not created before the dialog is closed.  Not recommended, because then your application must ensure that the file selected is not read-only.
OFN-NOVALIDATE 000100h Allows invalid characters in the filename.
OFN-OVERWRITEPROMPT 000002h Causes the SaveAs dialog to generate a message box if the selected file already exists, and allows the user to confirm whether to overwrite the file.
OFN-PATHMUSTEXIST 000800h Restricts the user to valid paths and filenames.
OFN-READONLY 000001h Causes the Read Only checkbox to be selected when the dialog is initially displayed.
OFN-SHAREAWARE 004000h Ignore sharing violations when returning a filename. 

OPENSAVE-HWNDOWNER

Handle of the owner window; panel-HWND.

OPENSAVE-LENGTH-CUSTFILTER

Specifies the length of the custom filter.

OPENSAVE-FILTER-INDEX

Specifies the index of the current filter in OPENSAVE-FILTER:

     MOVE 1 TO OPENSAVE-FILTER-INDEX.

OPENSAVE-LENGTH-FILESPEC

Specifies the length of OPENSAVE-FILESPEC:

     MOVE LENGTH OF OPENSAVE-FILESPEC
       TO OPENSAVE-LENGTH-FILESPEC.

OPENSAVE-LENGTH-FILENAME

Specifies the length of OPENSAVE-FILENAME:

     MOVE LENGTH OF OPENSAVE-FILENAME
       TO OPENSAVE-LENGTH-FILENAME.

OPENSAVE-OFFSET-FILENAME

Specifies the zero-based offset from the beginning of the path to the filename in OPENSAVE-FILESPEC.  For example, if the filespec is the string:

     "C:\dir1\dir2\file.ext"

this variable will contain the value 13.

OPENSAVE-OFFSET-FILEEXT

Specifies the zero-based offset from the beginning of the path to the file extension OPENSAVE-FILESPEC.  For example, if the filespec is the string:

"C:\dir1\dir2\file.ext"

this variable will contain the value 18.

OPENSAVE-INITIALDIR

Initial directory that is displayed:

     STRING 'C:\'
            LOW-VALUE DELIMITED SIZE
       INTO OPENSAVE-INITIALDIR.

OPENSAVE-FILTER

Contains pairs of null-terminated strings specifying the available filters.  The first element is the name of the filter, and the second element is the filter pattern. 

The filter is terminated with two nulls:

     STRING 'Application Profiles (*.INI)'
            LOW-VALUE
            '*.ini'
            LOW-VALUE
            'All Files (*.*)'
            LOW-VALUE
            '*.*'
            LOW-VALUE
            LOW-VALUE DELIMITED SIZE
       INTO OPENSAVE-FILTER.

OPENSAVE-CUSTFILTER

Not used; must be LOW-VALUE.

OPENSAVE-FILESPEC

Upon return, contains the full path and filespec, followed by a LOW-VALUE. 

If multiple files were selected, the null-terminated filenames follow the first one. 

Note:  The path is omitted for files other than the first. 

OPENSAVE-FILENAME

Filename and extension, less the path, used to initialize the File Name edit control.  This must be LOW-VALUE if initialization is unnecessary.

Upon return, contains the full path and filespec of the selected file.

WIN32API-PARMS - Used in all GSWINAPI calls

This argument is standard for all CALLs to GSWINAPI. It is used to select the desired API or function, and to return the status of the operation.

WIN32API-RC

Used to return the status of a call to GSWINAPI.  A value of zero is a failure, any other value indicates success.

Recommended usage is to test the 88-level value WIN32API to see if it worked, then to use the text error message to see why it failed.

* ------------------------: If function failed,
*                         :   display the error in a message box.
*
     IF WIN32API-FAILED
       MOVE WIN32API-ERROR-TEXT TO panel-MESSAGE-TEXT
       SET panel-MESSAGE-IN-MESSAGEBOX TO TRUE.

WIN32API-ERROR-CODE

Error code that was returned by Windows.  This is not generally useful unless you have the Windows Platform SDK documentation available to you.

WIN32API-ERROR-TEXT

Plain-text error message that describes why the operation failed.

WIN32API-A through WIN32API-F

The number of these present varies depending on how many arguments are used by the desired function.  These are not used, but must be present because this CALL requires seven arguments.

CAUTION

This API simply calls the Windows Open Dialog.  That dialog will, on some versions of Windows, change the default working directory.  This means that files you expect to be in the working directory may not appear because your application has changed to a different working directory.  

This can affect image controls.  If you use a simple file name (as opposed to a complete path spec), the image may not be found after windows navigates away from the prior working directory.

Also affected are other files that you reference via your SELECT statements unless you use a full path specification in your ASSIGN TO phrase.  If already open, these files will continue to work, but if not opened at the time you use this API, the default directory may not be what you expect.

Always use a complete path specification for files (and images) such as C:\my-data\image.bmp instead of simple image.bmp.


2000-2006 Norcom, all rights reserved 

TOC

Send feedback to Norcom