GETFNAME

8.1, PLBCMP GUI Only

The GETFNAME instruction invokes a standard file open dialog or file prep dialog, and returns the selected file name. The instruction uses the following format:

Where:

label

Optional. A Program Execution Label.

window

Optional. A previously created WINDOW object variable.

mode

Required. One of the keywords defining the mode of operations as described below.

prompt

Required. A previously defined Character String Variable or Literal that contains the user prompt string displayed in the file dialog.

name

Required. A previously defined Character String Variable that contains the default file name and returns the selected name or a list of comma-delimited names.

path

Required. A previously defined Character String Variable that contains the default file path and returns the selected file path.

type

Optional. A previously defined Character String Variable or Literal containing the file type for which to look.

Flags Affected: EOS, OVER

Note the following:

1. If the optional {window} is not specified, the currently active window is used.

2. The {mode} parameter describes the type of operation:

 

Mode	Dialog Type
OPEN	Standard open dialog
PREP	Standard prepare dialog
TYPE={value}	An extended dialog type as follows:
	1 - Standard open dialog.
	2 - Standard prep dialog.
	17 - Open dialog with user filter
	18 - Prep dialog with user filter.
	33 - Open dialog with multiselect feature.
	34 - Prep dialog with multiselect feature.
	49 - Open dialog with filter and multiselect.
	50 - Prep dialog with filter and multiselect.

3. When {mode} identifies employment of a user filter, the string format requires {info} and {filter} pairs to follow the extension that are then passed to the Open or Prep dialogs. The {type} string format is as follows:
   
   {ext}[,{info1},{filter1}[,{info2},{filter2}]...]

Where:

{ext}

Identifies the default extension used when no name filtering is provided.

{info1}

First information/comment string presented and associated with the file filter that follows it.

{filter1}

First file filter that can be one or more files separated by the semicolon character. The file names can be specific or partial names and include wildcard characters. When a user selects the {info1} identifier, only those files that conform to the {filter1} appear in the dialog presentation window.
 

A. When a default file {name} is specified, the extension of the {name} parameter is used/compared to the extensions specified by the {type} user filter data. If an extension match is found, the appropriate filter index is set to allow the matching file filter to be presented in the open/prep dialog. If no match is found, the first user filter appears in the open/prep dialog.

 

B. If the default file {name} parameter is NULL and the {ext} field is specified in the {type} user filter string, the {ext} extension is matched to the user filters. If the {ext} matches a user filter extension, the filter index is set to allow that user filter to appear in the open/prep dialog. If no match is found, the first user filter appears in the open/prep dialog.

 

4. If {type} is not provided, all file types are made available.

5. The instruction allows a value offset of 100 for the TYPE={value} {mode} parameter. When an offset value of one hundred (100) is added to the TYPE {value}, a semicolon character is the delimiting character when multiple file selections are being returned. This change provides a solution to a problem where file names included a comma character as part of the file names.

6. GETFNAME supports file extensions up to four bytes in length.

7. If the file dialog is canceled, the OVER flag is set.

8. If the file name or file path is truncated when placed in the respective variables, the EOS flag is set.

9. The OVER flag is set and a message 'OS buffer overflow!' is returned when the OS API can not return any file name data because there is more than 40960 bytes to be returned. This buffer overflow situation can only happen when the GETFNAME is setup to allow multiple file names to be selected and there is a very large number of file names that have been selected by an end user.

10. If the {mode} parameter is one of the multiselect values, {name} is a list of comma-delimited file names.

11. If a FILEPI is active, the FILEPI is terminated.

12. When run from a PL/B Client, the GETFNAME instruction retrieves information from the client file system.

13. This instruction is not supported by the PLB Web Server.

See Also: Example Code, PREPDEFAULT, Disk I/O Instructions