Display the standard file Open or Save As dialog with customized File Filter
subroutine OS_Common_Dialog ( string : Primary_Window_Name,
string : Dialog_Title,
string : File_Name,
integer : Filter_Handle,
integer : Filter_Index,
boolean : Open,
integer : Error_Level) is
Primary_Window_Name must contain the name of the program's primary region.
The Title string contains the text to appear in the dialog's title bar.
The path and name of the selected file is returned in File_Name.
The Filter Handle is the pointer to the customized file filter structure. The filter structure must be initialized before this routine is called.
The Filter Index should be set to the number of the file filter to be used when the dialog is initially displayed. This parameter will contain the number of the file filter used when the file is selected.
The "Open" boolean is used to determine whether the Open or Save As dialog is displayed.
Error_Levels are:
0 Normal completion; File_Name is valid.
1 User cancelled the dialog.
-1 Primary Window Name is invalid.
The file filter structure to be used with this routine, must contain a series of string fields. Each file filter requires 2 string fields; the first contains the narrative text (e.g. "All Files (*.*)") and the second contains the filter to be used (e.g. "*.*"). Each field must be defined as a length one greater than the content so there is a NULL separator at the end of each field. The final field must have a length defined as 2 greater than the content so there are 2 NULLs to indicate the end of the list of file filters.
Note. This routine merely returns the fully qualified file name, it does not actually read or save the file, although if the file exists and the file is to be saved, then it will issue a warning to caution that a file is about to be overwritten.
