C$OPENSAVEBOX

C$OPENSAVEBOX provides a facility for creating an Open or Save As dialog box. These dialogs allow the user to browse the system's file directories and select a file or folder.

This routine can be used by applications that are deployed in Acucorp's Thin Client environment. In this scenario, C$OPENSAVEBOX allows the user to choose a directory or file on the client (Windows) machine.

Not all systems support C$OPENSAVEBOX. However, you can determine at runtime whether the host system supports it.

Usage

CALL "C$OPENSAVEBOX" 
    USING OP-CODE, OPENSAVE-DATA
    GIVING OPENSAVE-STATUS

Parameters

OP-CODE Numeric value

Selects which C$OPENSAVEBOX function to perform. The values are described below.

OPENSAVE-DATA Group item as follows:

01  OPENSAVE-DATA.
    03  OPNSAV-FILENAME         PIC X(256).
    03  OPNSAV-FLAGS            PIC 9(4) COMP-X.
    03  OPNSAV-DEFAULT-EXT      PIC X(12).
    03  OPNSAV-TITLE            PIC X(80).
    03  OPNSAV-FILTERS          PIC X(512).
    03  OPNSAV-DEFAULT-FILTER   PIC 9(4) COMP-X.
    03  OPNSAV-DEFAULT-DIR      PIC X(128).
    03  OPNSAV-BASENAME         PIC X(128).

This item holds the results of a C$OPENSAVEBOX routine call. The values are described below.

OPENSAVE-STATUS Signed numeric data item

This item returns the status of the operation. A value of 1 indicates that the operation completed successfully. A zero or negative value indicates that the operation failed.

Description

C$OPENSAVEBOX performs a variety of operations depending on the operation passed. All of the data items and definitions required by this routine can be found in "opensave.def". The operations are as follows:

OPENSAVE-SUPPORTED (op-code 1)

This operation returns a value that indicates whether the host system supports C$OPENSAVEBOX. If the system supports it, OPENSAVE-STATUS is set to 1. Otherwise, it is set to OPNSAVERR-UNSUPPORTED (value 0). The OPENSAVE-DATA parameter is not used with this op-code and should be omitted. (Note that Microsoft Windows hosts support C$OPENSAVEBOX.)

OPENSAVE-OPEN-BOX (op-code 2)

This operation initiates an Open File dialog with the user. The OPENSAVE-DATA structure initializes the dialog box and returns the results.

OPENSAVE-SAVE-BOX (op-code 3)

This operation initiates a Save As dialog with the user. The OPENSAVE-DATA structure initializes the dialog box and returns the results. On some systems, there is no difference between an Open and Save As dialog box. On other systems, there are some differences.

OPENSAVE-BROWSE-FOLDER (op-code 4)

This operation initiates a Browse for Folder dialog with the user. The OPENSAV-TITLE and OPENSAV-FILENAME fields in the OPENSAVE-DATA structure initialize the dialog box and return the result, respectively. When C$OPENSAVE BOX is called, the Browse for Folder dialog box displays the contents of OPENSAV-FILENAME as the root folder to be browsed. Only folders which are descendants of this folder are shown in the dialog box. If OPENSAV-FILENAME is blank when the routine is called, the dialog shows all folders in the user's default working folder, and a number of other items, such as the Recycle Bin. You may select an empty folder, however, if the folder specified as a root does not exist or is inaccessible, the dialog shows all folders in the user's default working folder, just as though no root was specified. The OK button is disabled if any item other than a folder is selected.

OPENSAVE-DATA

You should use the INITIALIZE verb on OPENSAVE-DATA before you fill in the data fields. This ensures that you have set all the fields to the default values and protects you from possible future changes to the OPENSAVE-DATA structure.

The OPENSAVE-DATA item is fairly large (1120 bytes). You can conserve memory by using C$OPENSAVEBOX from a utility subprogram that you write. This subprogram would include OPENSAVE-DATA. After using the subprogram, you can free the memory with the CANCEL verb. In this way, you need to keep OPENSAVE-DATA in memory only while you are using it. Alternatively, you can use the M$ALLOC library routine to allocate memory to hold OPENSAVE-DATA, and then free that memory after you are done.

The fields contained in the OPENSAVE-DATA structure are used as follows:

OPNSAV-FILENAME

On input to the routine, this item contains the default file name to use as the initial prompt. Set OPNSAV-FILENAME to spaces if there should be no default name. When the routine returns, this item contains the name of the file selected by the user. When used with the OPENSAVE-BROWSE-FOLDER operation, this item returns the file specifications of the selected folder, if any. If the user selects a folder which is not accessible, this item is blank.

OPNSAV-FLAGS

This item is used to pass information to the OPENSAVE-OPEN-BOX, OPENSAVE-SAVE-BOX, and OPENSAVE-BROWSE-FOLDER operations to modify the behavior of the associated dialog boxes. Constants for these flags are defined in opensave.def.

The following flags can be used with the OPENSAVE-OPEN-BOX and OPENSAVE-SAVE-BOX operations:

OPENSAVE-OVERWRITEPROMPT	This flag causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file.
OPENSAVE-PATHMUSTEXIST	This flag specifies that the user can type only valid paths and file names. If this flag is used and the user types an invalid path and file name in the File Name entry field, the dialog box function displays a warning in a message box.
OPENSAVE-FILEMUSTEXIST	This flag specifies that the user can type only names of existing files in the File Name entry field. If this flag is specified and the user enters an invalid name, the dialog box procedure displays a warning in a message box. If this flag is specified, the OPENSAVE-PATHMUSTEXIST flag is also used.
OPENSAVE-CREATEPROMPT	If the user specifies a file that does not exist, this flag causes the dialog box to prompt the user for permission to create the file. If the user chooses to create the file, the dialog box closes and the function returns the specified name.
OPENSAVE-NOREADONLYRETURN	This flag specifies that the returned file does not have the Read Only check box selected and is not in a write-protected directory.

The following flags can be used with the OPENSAVE-BROWSE-FOLDER operation:

OP-CODE Numeric value	Selects which C$OPENSAVEBOX function to perform. The values are described below.
OPENSAVE-DATA Group item as follows:	01 OPENSAVE-DATA. 03 OPNSAV-FILENAME PIC X(256). 03 OPNSAV-FLAGS PIC 9(4) COMP-X. 03 OPNSAV-DEFAULT-EXT PIC X(12). 03 OPNSAV-TITLE PIC X(80). 03 OPNSAV-FILTERS PIC X(512). 03 OPNSAV-DEFAULT-FILTER PIC 9(4) COMP-X. 03 OPNSAV-DEFAULT-DIR PIC X(128). 03 OPNSAV-BASENAME PIC X(128). This item holds the results of a C$OPENSAVEBOX routine call. The values are described below.
OPENSAVE-STATUS Signed numeric data item	This item returns the status of the operation. A value of "1" indicates that the operation completed successfully. A zero or negative value indicates that the operation failed.
OPNSAV-FILENAME	On input to the routine, this item contains the default file name to use as the initial prompt. Set OPNSAV-FILENAME to spaces if there should be no default name. When the routine returns, this item contains the name of the file selected by the user. When used with the OPENSAVE-BROWSE-FOLDER operation, this item returns the file specifications of the selected folder, if any. If the user selects a folder which is not accessible, this item is blank.
OPNSAV-FLAGS	This item is used to pass information to the OPENSAVE-OPEN-BOX, OPENSAVE-SAVE-BOX, and OPENSAVE-BROWSE-FOLDER operations to modify the behavior of the associated dialog boxes. Constants for these flags are defined in "opensave.def".
OPENSAVE-OVERWRITEPROMPT	This flag causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file.
OPENSAVE-PATHMUSTEXIST	This flag specifies that the user can type only valid paths and file names. If this flag is used and the user types an invalid path and file name in the File Name entry field, the dialog box function displays a warning in a message box.
OPENSAVE-FILEMUSTEXIST	This flag specifies that the user can type only names of existing files in the File Name entry field. If this flag is specified and the user enters an invalid name, the dialog box procedure displays a warning in a message box. If this flag is specified, the OPENSAVE-PATHMUSTEXIST flag is also used.
OPENSAVE-CREATEPROMPT	If the user specifies a file that does not exist, this flag causes the dialog box to prompt the user for permission to create the file. If the user chooses to create the file, the dialog box closes and the function returns the specified name.
OPENSAVE-NOREADONLYRETURN	This flag specifies that the returned file does not have the Read Only check box selected and is not in a write-protected directory.
OPENSAVE-BROWSE-DONTGOBELOWDOMAIN	When this flag is set, network folders below the domain level in the dialog box's tree view control are not included.
OPENSAVE-BROWSE-RETURNFSANCESTORS	When this flag is set, only file system ancestors are returned. An ancestor is a subfolder that is beneath the root folder in the namespace hierarchy. If the user selects an ancestor of the root folder that is not part of the file system, the OK button is disabled.
OPENSAVE-BROWSE-EDITBOX	This flag includes an edit control in the browse dialog box allowing the user to type the name of an item.
OPENSAVE-BROWSE-NEWDIALOGSTYLE	This flag provides the user with a larger dialog box that can be resized. The dialog box has several new capabilities including: drag and drop capability within the dialog box, reordering, shortcut menus, new folders, delete, and other shortcut menu commands.
OPENSAVE-BROWSE-BROWSEINCLUDEURLS	When this flag is set, the OPENSAVE-BROWSE-NEWDIALOGSTYLE, OPENSAVE-BROWSE-EDITBOX, and OPENSAVE-BROWSE-BROWSEINCLUDEFILES flags must also be set. Otherwise, the browser dialog box rejects URLs. Even when these flags are set, the browse dialog box displays URLs only if the folder containing the selected item supports them. When the folder's "IShellFolder::GetAttributesOf" method is called, the folder must set the SFGAO_FOLDER flag. If this is not set, the browse dialog box does not display the URL.
OPENSAVE-BROWSE-UAHINT	When combined with OPENSAVE-BROWSE-NEWDIALOGSTYLE, this flag adds a usage hint to the dialog box in place of the edit box. OPENSAVE-BROWSE-EDITBOX overrides this flag.
OPENSAVE-BROWSE-NONEWFOLDERBUTTON	When this flag is set, the New Folder button in the browse dialog box is not included.
OPENSAVE-BROWSE-BROWSEFORCOMPUTER	When this flag is set, if the user selects anything other than a computer, the OK button is disabled.
OPENSAVE-BROWSE-BROWSEFORPRINTER	When this flag is set, if the user selects anything other than a printer, the OK button is disabled.
OPENSAVE-BROWSE-BROWSEINCLUDEFILES	When this flag is set, the browse dialog box displays files as well as folders. OPNSAV-DEFAULT-EXT - This item holds the default file name extension. The extension is the string of characters that appear after the "." in the file name. The value of OPNSAV-DEFAULT-EXT is added to the file name typed by the user, if the user does not type an extension. The default extension should not include the period ".". Set this item to spaces to avoid having a default extension. OPNSAV-TITLE - This item holds the title of the dialog box. If it is set to spaces, a generic title is applied. The generic title is host-specific. When used with the OPENSAVE-BROWSE-FOLDER operation, the title of the Browse for Folder dialog is always Browse for Folder. The OPENSAV-TITLE item is displayed inside the Browse for Folder dialog box below the title bar and above the tree view control. OPNSAV-FILTERS - The value of OPNSAV-FILTERS describes the set of filters that the dialog box uses to restrict the set of files shown to the user. Filters make it easier for a user to navigate through a large directory by limiting the files shown at once. Each filter consists of a pair of descriptors. These descriptors are separated by a vertical bar character ("\|"). The first descriptor in the pair is displayed in the file type selection box of the Open or Save As dialog box. In Windows, it appears in the List of File Types drop-down box (see the illustration below). The second descriptor is the file name pattern that defines the filter. The file name pattern is formatted as "A [ . B ]" where "A" and "B" are optional text followed by an optional asterisk. An asterisk matches any sequence of characters excluding periods. This descriptor is what the system uses to look for matching files. Here is a sample OPNSAV-FILTERS setting that contains two filters: "COBOL source files (.cbl)\|.cbl\|All files (.)\|." The first filter in the example shows only ".cbl" files to the user. The second filter shows all files. The user selects which filter to use based on the descriptions supplied. Filters do not restrict the user from entering names that do not match the supplied pattern. Filters do not limit the user's choices, they only simplify the process of choosing. Set OPNSAV-FILTERS to spaces if you don't want any filters. Some systems do not support multiple filters. In this case, only the initial filter is used. See OPNSAV-DEFAULT-FILTER to determine how to select the initial filter. OPNSAV-DEFAULT-FILTER - This item is used in conjunction with OPNSAV-FILTERS. The value of OPNSAV-DEFAULT-FILTER determines which of the given filters to use as the initial filter. A value of `1` selects the first filter pair, `2` selects the second pair, and so on. A value of zero also selects the first pair. This setting is not used if no filters are defined. OPNSAV-DEFAULT-DIR - This item holds the default directory to use for the selected file. The dialog box initially displays the files found in this directory. If this item is set to spaces, the current directory is used. Note that the value of this item only defines the default directory. It does not prevent the user from selecting files in a different directory. OPNSAV-BASENAME - When the routine returns, this item contains the base file name of the file chosen by the user. This differs from the value of OPNSAV-FILENAME in that all directory information is removed, leaving only the file name.

Error Handling

C$OPENSAVEBOX returns a value of 1 when successful. Otherwise, it returns one of the following values (found in opensave.def):

OPNSAVERR-UNSUPPORTED	This error indicates that the C$OPENSAVEBOX routine is not supported by the current host system.
OPNSAVERR-CANCELLED	This error indicates that the user clicked the "Cancel" button or typed the Escape key while using the dialog box.
OPNSAVERR-NO-MEMORY	This error indicates that not enough memory could be allocated to load the dialog box.
OPNSAVERR-NAME-TOO-LARGE	This error indicates that the name entered by the user does not fit in OPNSAV-FILENAME.

Example

This example uses C$OPENSAVEBOX to prompt for a text file name, and uses M$ALLOC to dynamically allocate OPENSAVE-DATA, freeing it after it is no longer needed.

WORKING-STORAGE SECTION.
77  OPENSAVE-DATA-SIZE    PIC 9(4) BINARY.
77  OPENSAVE-DATA-ADDR    POINTER.
77  OPENSAVE-STATUS       PIC S99.
    88  OPENSAVE-OK       VALUE 1.
77  FILE-NAME             PIC X(256).

LINKAGE SECTION.
COPY "opensave.def".

PROCEDURE DIVISION.
MAIN-LOGIC.
   SET OPENSAVE-DATA-SIZE TO SIZE OF OPENSAVE-DATA.
   CALL "M$ALLOC" 
      USING OPENSAVE-DATA-SIZE, OPENSAVE-DATA-ADDR.
   IF OPENSAVE-DATA-ADDR = NULL
      {error handling here}
   ELSE
      SET ADDRESS OF OPENSAVE-DATA
          TO OPENSAVE-DATA-ADDR
      INITIALIZE OPENSAVE-DATA
      MOVE 
          "Text files (*.txt)|*.txt|All files (*.*)|*.*" 
          TO OPNSAV-FILTERS
      MOVE "txt" TO OPNSAV-DEFAULT-EXT
      CALL "C$OPENSAVEBOX" USING OPENSAVE-SAVE-BOX, 
                                 OPENSAVE-DATA
                           GIVING OPENSAVE-STATUS

      IF OPENSAVE-OK
          MOVE OPNSAV-FILENAME TO FILE-NAME
      END-IF
      CALL "M$FREE" USING OPENSAVE-DATA-ADDR
   END-IF.