PreviousUsing Panels Version 2 On-line Help SystemNext"

Chapter 21: Directory Facility V2

Directory Facility V2 provides you with extensive file management facilities for use with Graphical User Interface (GUI) applications. Directory Facility V2 is supplied with a program interface, called Mfdir2, which can be called from your program.

UNIX:
Directory Facility V2 is not available in UNIX environments.

21.1 Overview

This section provides an overview of Directory Facility V2.

Directory Facility V2

Directory Facility V2 enables you to manipulate files and directories using a graphical interface. The window displays a directory listing so that you can select a file, or change the directory by simply pointing with the cursor.

You can incorporate this facility in your GUI applications using the Mfdir2 call interface, described later in this chapter.

21.2 Operation

This section describes the call interface for invoking the Directory Facility, Mfdir2, the parameter description in mfdir2link.cpy, an example program demonstrating the interface to Mfdir2, and the parameters that you can specify when calling Mfdir2.

21.2.1 Including the Directory Facility in Your Application

To include the Directory Facility in your application, you need to:

  1. Invoke Mfdir2 within your application using the call interface described in the section Mfdir2 Program Call Interface.

  2. Force the library mfdir2.lbr to be opened when the application starts up. To do this, add the following line to the [application-PROGRAMS] section of the application's configuration file. For example:
    [myapp-PROGRAMS] 
    mfdir2.lbr

  3. Ship the file, mfdir2.lbr, with your application.

21.3 Mfdir2 Program Call Interface

Before calling Mfdir2, you must first initialize Panels V2. See the chapter Panels Version 2 for details.

You use the following call interface to invoke Mfdir2.

Syntax:
call "mfdir2" using nm-parameter-block title-text
Parameters:

nm-parameter-block Parameter block to pass information between your GUI application and Mfdir2. The definition of this parameter is contained within the copyfile mfd2link.cpy, which you can copy into your program. See the section The mfd2link.cpy Parameter Block for details.
title-text pic x(n).

On Entry:

title-text Title of the dialog box you create.
nm-function-code Type of operation Mfdir2 is to perform.
nm-file-spec File specification of the file or file mask to be searched for.
nm-extension-list Extension(s) of the files to be searched for.
nm-ancestor Handle identifier of the parent window or parent dialog box from which the Mfdir2 dialog box is invoked.
nm-text-length Length of the buffer title text.
nm-style-flags Style of the dialog box.
nm-mf-reserved Panels2 ID for your application. Assigned when Panels V2 is initialized.

On Exit:

nm-file-spec File returned.
nm-return-code Flag indicating an event has occurred.

21.3.1 The mfd2link.cpy Parameter Block

The following parameter description is held in the file mfd2link.cpy:

 01 nm-parameter-block.
 78 nm-pblck-start                value next.
    03 nm-function-code           pic 9(02) comp-5.
       78 nm-preload              value 0.
       78 nm-save                 value 1.
       78 nm-open                 value 2.
       78 nm-browse               value 3.
    03 nm-file-spec               pic x(255).
    03 nm-extension-list.
       05 nm-ext-item             pic x(03) occurs 10
                                         value spaces.
    03 nm-ancestor                pic 9(09) comp-5.
    03 nm-text-length             pic 9(04) comp-5.
    03 nm-style-flags             pic 9(8)  comp-5.
       78 nmf-standard            value h"00000000".
       78 nmf-extended            value h"00000001".
       78 nmf-filemgr             value h"00000002".
       78 nmf-library             value h"00000004".
       78 nmf-nohelp              value h"00000010".
       78 nmf-preserve-dir        value h"00000100".
       78 nmf-unsort              value h"00007000".
       78 nmf-sort-name-ascnd     value h"00008000".
       78 nmf-sort-name-dscnd     value h"00009000".
       78 nmf-sort-size-ascnd     value h"0000A000".
       78 nmf-sort-size-dscnd     value h"0000B000".
       78 nmf-sort-date-ascnd     value h"0000C000".
       78 nmf-sort-date-dscnd     value h"0000D000".
       78 nmf-sort-ext-ascnd      value h"0000E000".
       78 nmf-sort-ext-dscnd      value h"0000F000".
      *----------------------------------------------------*
* Flags allowing calls to the native file dialogs on
* Microsoft Windows and IBM OS/2 Presentation
* Manager.
* Note : OS/2 native dialog dynamic link libraries
* shipped with Micro Focus products cannot be shipped
* with your applications unless you have purchased
* the following : 
* IBM Program    - IBM SAA CUA Controls Library/2
* Program Number - 5621-332
* Part Number    - 20G0400
*
       78 nmf-native-dialog-pm16  value h"01000000".
       78 nmf-native-dialog-win   value h"02000000".
       78 nmf-native-dialog-pm32  value h"04000000".
       78 nmf-native-dialog-nt    value h"08000000".
       78 nmf-native-dialog-motif value h"10000000".
       78 nmf-native-dialog-all   value h"FF000000".
      *----------------------------------------------------*
    03 nm-return-code             pic 9(02) comp-5.
       78 nm-ok                   value 1.
       78 nm-cancel               value 2.
       78 nm-invalid-file         value 3.
       78 nm-valid-file           value 4.
    03 nm-mf-reserved             pic 9(09) comp-5.
 78 nm-pblck-length               value next 
                                       nm-pblck-start.

21.3.1.1 Example Program

The example program, mfd2demo.cbl is supplied in the following locations:

$COBDIR\demo\mfd2demo.cbl

The program demonstrates the interface to Mfdir2, where Mfd2demo invokes the Micro Focus file dialog. You can access the native file dialogs by using the flags described in mfd2link.cpy.

 working-storage section.
 78 ok-button                         value 1001.
 78 cancel-button                     value 1002.
 78 panels2                           value "PANELS2".
 78 maxbufferlength                   value 255.
 01 dialogbox-handle            pic 9(9) comp-5.

 copy "pan2link.cpy".

 01 text-buffer                 pic x(maxbufferlength)
                                         value spaces.
 copy "mfd2link.cpy".

 01 title-text                  pic x(maxbufferlength)
                                         value spaces.
 procedure division.
 main section.
    perform initialize-panels2
    move p2-mf-reserved          to nm-mf-reserved
    perform create-dialogbox
    move dialogbox-handle        to nm-ancestor
    move nm-open                 to nm-function-code
    move "*.*"                   to nm-file-spec
    move spaces                  to nm-extension-list
    move nmf-standard            to nm-style-flags
    move 6                       to nm-text-length
    move "Browse"                to title-text
    perform process-events
    .                     
                 
 initialize-panels2 section.
    move pf-initialize           to p2-function
    move p2i-generic-coordinates to p2i-environment
    add p2i-baseline-positioning to p2i-environment
    move zero                    to p2i-name-length
    call panels2 using p2-parameter-block
                       p2i-initialization-record
    .        
                                
 create-dialogbox section.
     move pf-get-environment-info to p2-function
     call panels2 using p2-parameter-block
                        p2i-initialization-record
     move p2i-font-height         to p2d-dialog-box-x
     add p2i-font-height          to p2d-dialog-box-y
     add p2i-font-width           to p2d-dialog-box-y
     multiply p2i-font-height by 05 giving
                                 p2d-dialog-box-height
     multiply p2i-font-width by  30 giving
                                 p2d-dialog-box-width
     move dbf-titlebar          to p2d-dialog-box-flags
     move 16            to p2d-dialog-box-title-length
     move "CALL FILE DIALOG"      to text-buffer
     add pfl-visible            to p2d-dialog-box-flags
     move pf-create-dialog-box    to p2-function
     call panels2 using p2-parameter-block
                        p2d-dialog-box-record
                        text-buffer
     move p2-descendant           to dialogbox-handle
     perform create-buttons
    .                     
                             
 create-buttons section.
     move dialogbox-handle        to p2-ancestor
     move ok-button               to p2g-button-id
     subtract p2i-font-height from
              p2d-dialog-box-height giving p2g-button-y
     move p2i-font-width          to p2g-button-x
     move bf-fit-text             to p2g-button-flags
     move zero                    to p2g-button-state
     move 02                      to p2g-button-text-length
     move "OK"                    to text-buffer
     move bt-push-button          to p2g-button-type
     perform add-button
     move cancel-button           to p2g-button-id
     add  p2g-button-width        to p2g-button-x
     add  p2i-font-width          to p2g-button-x
     move 06                      to p2g-button-text-length
     move "CANCEL"                to text-buffer
     move bt-push-button          to p2g-button-type
     perform add-button
    .                 
                          
 add-button section.
     move pf-create-button        to p2-function
     call panels2 using p2-parameter-block
                        p2g-button-record
                        text-buffer
     .       
                      
 process-events section.
     move pf-get-event-with-wait  to p2-function
     move zero                    to p2e-event-time-out
     call panels2 using p2-parameter-block
                        p2e-parameter-block
     evaluate p2e-event-type
      when p2e-gadget-event
         evaluate p2e-gadget-type
          when p2e-button
             if p2e-gadget-command = p2e-bn-clicked
                 evaluate p2e-gadget-id
                  when ok-button
                     perform call-file-dialog
                  when cancel-button
                     perform shutdown
                  when other continue
                 end-evaluate
             end-if
          when other continue
         end-evaluate
      when other continue
     end-evaluate
     go to process-events
     .                   

     call-file-dialog section.
     call 'mfdir2' using nm-parameter-block 
                       title-text
    .
                             
 shutdown section.
     move pf-delete-dialog-box    to p2-function
     call panels2 using p2-parameter-block end-call
     move pf-terminate            to p2-function
     call panels2 using p2-parameter-block end-call
     exit program
     stop run
     .

21.3.1.2 Parameter Block

The following sections describe the parameters that can be specified when calling Mfdir2. The parameter block is provided in the file mfd2link.cpy.

21.3.1.2.1 nm-function-code

The nm-function-code parameter defines the type of operation that you want to perform using Mfdir2. A value must be specified for this parameter.

nm-preload Value 0

The nm-preload function causes the programs to be loaded and initialized. All programs using Mfdir2 should use this function.

nm-save Value 1

The nm-save function is used as a "Save As" operation for files. Mfdir2 will prompt you if the filename you want to save as already exists.

nm-open Value 2

The nm-open function is used to open a file. Mfdir2 prompts you if the file does not exist.

nm-browse Value 3

The nm-browse function is used when you only want to look at a file.

21.3.1.2.2 nm-file-spec

The nm-file-spec parameter contains the file specification. If it is spaces, extensions from the extension list provided are used. If no extension list is provided, nm-file-spec defaults to "*.*".

21.3.1.2.3 nm-extension-list

The nm-extension-list parameter holds the required extension. If you want to navigate around directories using the extension list, call Mfdir2 with a file specification of spaces.

21.3.1.2.4 nm-ancestor

The nm-ancestor parameter indicates the handle of the parent window or parent dialog box from which the Mfdir2 dialog box is invoked. A value must be specified for this parameter (this is the value assigned when you created your initial application window or dialog box).

21.3.1.2.5 nm-text-length

The nm-text-length parameter specifies the length, in characters, of the title used for title-text. A value in the range 1 through 255 must be specified for this parameter.

21.3.1.2.6 nm-style-flags

The nm-style-flags parameter determines the appearance of the Mfdir2 file selection dialog box. A value must be specified for this parameter.

nmf-standard Value h"00000000"

The nmf-standard function specifies a selection dialog box containing: a filename entry field, Directory label, Files list box, Directory list box, and a Sort facility, as well as the standard OK and Help pushbuttons.

nmf-extended Value h"00000001"

This function is reserved for future use.

nmf-filemgr Value h"00000002"

This function is reserved for future use.

nmf-library Value h"00000004"

This function is reserved for future use.

nmf-nohelp Value h"00000010"

The nmf-nohelp function specifies that the help button is disabled.

nmf-preserve-dir Value h"00000100"

The nmf-preserve-dir function specifies that the last directory a user was in is maintained.

nmf-unsort Value h"00007000"

The nmf-unsort function specifies that the default is not to sort files (normally files are sorted acsending by name).

nmf-sort-name-ascnd Value h"00008000"

The nmf-sort-name-ascnd function specifies that the default is to sort files ascending by name.

nmf-sort-name-dscnd Value h"00009000"

The nmf-sort-name-dscnd function specifies that the default is to sort files descending by name (normally files are sorted ascending by name).

nmf-sort-name-dscnd Value h"00009000"

The nmf-sort-name-dscnd function specifies that the default is to sort files descending by name (normally files are sorted ascending by name).

nmf-sort-size-ascnd Value h"0000A000"

The nmf-sort-size-ascnd function specifies that the default is to sort files ascending by size (normally files are sorted ascending by name).

nmf-sort-size-dscnd Value h"0000B000"

The nmf-sort-size-dscnd function specifies that the default is to sort files descending by size (normally files are sorted ascending by name).

nmf-sort-date-ascnd Value h"0000C000"

The nmf-sort-date-ascnd function specifies that the default is to sort files ascending by date (normally files are sorted ascending by name).

nmf-sort-date-dscnd Value h"0000D000"

The nmf-sort-date-dscnd function specifies that the default is to sort files descending by date (normally files are sorted ascending by name).

nmf-sort-ext-ascnd Value h"0000E000"

The nmf-sort-ext-ascnd function specifies that the default is to sort files ascending by extension (normally files are sorted ascending by name).

nmf-sort-ext-dscnd Value h"0000F000"

The nmf-sort-ext-dscnd function specifies that the default is to sort files descending by extension (normally files are sorted ascending by name).

nmf-native-dialog-pm16 Value h"01000000"

The nmf-native-dialog-pm16 function specifies that native dialog on 16 bit OS/2 V2.0 and later is created.

nmf-native-dialog-win Value h"02000000"

The nmf-native-dialog-win function specifies that native dialog on Windows V3.1 and later is created.

nmf-native-dialog-pm32 Value h"04000000"

The nmf-native-dialog-pm32 function specifies that native dialog on 32 bit OS/2 V2.0 and later is created.

nmf-native-dialog-nt Value h"08000000"

The nmf-native-dialog-nt function specifies that native dialog on Windows NT is created.

nmf-native-dialog-all Value h"FF000000"

The nmf-native-dialog-pm16 function specifies that native dialog on all the environments listed above is created.

nmf-native-dialog-pm16 Value h"01000000"

The nmf-native-dialog-pm16 function specifies that native dialog on 16 bit OS/2 V2.0 and later is created.

21.3.1.2.7 nm-return-code

The nm-return-code parameter returns various flags, indicating that an event has occurred in the Mfdir2 file selection dialog box.

nm-ok Value 1

The OK button has been pressed.

nm-cancel Value 2

The Cancel button has been pressed.

nm-invalid-file Value 3

An invalid filename has been entered. This nm-invalid-file function is only used if you are using the nm-browse function.

nm-valid-file Value 4

A valid filename has been selected. This nm-valid-file function is only used if you are using the nm-browse function.

21.3.1.2.8 nm-mf-reserved

p2-mf-reserved (in pan2link.cpy) is a unique ID for your application assigned when Panels V2 is initialized. nm-mf-reserved must be set to the same value as p2-mf-reserved. See the chapter Panels Version 2 for complete details on this Panels V2 parameter.


Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousUsing Panels Version 2 On-line Help SystemNext"