















                          CDD 1.03 PROGRAMMER'S GUIDE

                       Copyright 1993 Phoenix Systems, Inc.
                             1700 N. Moore Street
                             Arlington, VA 22209

                                 March, 1993




































                              TABLE OF CONTENTS



           Section                 Description                Page
           ----------  -------------------------------------- ----

            1.0        Introduction..........................  3
            2.0        Installation..........................  4
            2.1           Installing CDD.EXE and CDDLIB.LIB..  4
            2.2           Installing a CDD application.......  4
            2.3           Creating the application PRG file..  5
            2.4           Creating the link file.............  5
            2.5           Creating the data dictionary files.  6
            2.6           Using CDD.EXE......................  6
            2.7           Typical development steps..........  7
            2.8           General CDD Concepts...............  8
            3.0        CDD Main Menu.........................  9
            4.0        Startup and Configuration............. 10
            4.1           System Colors...................... 12
            4.2           System Sounds, Others.............. 13
            5.0        Menu Definitions...................... 14
            5.1           Defining Menu Items................ 16
            6.0        Browse Definitions.................... 18
            6.1           Defining Browse Columns............ 21
            6.2           Defining Browse Keys............... 22
            7.0        Screen Definitions.................... 24
            7.1           Defining Screen Fields............. 28
            7.2           Defining Screen Keys............... 31
            7.3           Screen Designer.................... 33
            8.0        Find Definitions...................... 36
            8.1           Defining Find Items................ 36
            9.0        Sequence Definitions.................. 38
           10.0        DBF, Field, NTX Definitions........... 40
           10.1           Defining Fields.................... 41
           10.2           Defining Index Files............... 42
           11.0        Utilities............................. 43
           12.0        Tips and Traps........................ 44
           A-1         CDDLIB Internal Variables............. 47
           A-2         CDD Error Handler..................... 51
           A-3         Recompiling CDDLIB Source............. 52
           A-4         Warranty / Licensing.................. 53
           A-5         Trademarks Referenced................. 55
           A-6         Thanks................................ 56







                                 --- Page 2 ---


    1.0   INTRODUCTION
    ------------------

    CDD version 1.03 is an application development system for CA-Clipper
    5.01a.  An application built using CDD is controlled by a runtime
    data dictionary.  Within the data dictionary, you define the menus,
    browses, edit screens, etc. for your CA-Clipper program.  CDD
    applications are almost completely data-driven, resulting in very
    rapid development, fast changes, and easy maintenance.

         Some features of CDD are:

         - CDD uses a runtime data dictionary to define and control
           menus, browses, edit screens, data structures, indexes,
           lookup tables, colors, etc.

         - An easy to use WYSIWYG screen designer.

         - A fully integrated help system, including field-level help.

         - CDD reduces your compile/link cycle time by up to 90%. Since
           most development is done via the data dictionary, your
           program changes are immediate.

         - CDD can handle very large, very complex Clipper
           applications.

         - Fully multiuser/network compatible (as well as stand alone).

         - A powerful data driven "sequencer" allows a programmer to
           define and run simple code sequences WITHOUT recompiling and
           linking.

         - The CDDLIB.LIB library provides a full set of functions to
           support relational integrity, validation, table maintenance,
           indexing/packing, filtered browses, etc.

         - A custom CDD ERRORSYS replacement with extensive diagnostics
           and error log is included.

         - Much of the CDDLIB.LIB source code is provided.  The entire
           CDDLIB.LIB source can be purchased, subject to certain
           licensing requirements.

         - CDD is compatible with commonly used 3rd party libraries such
           as Funcky and FlexFile.

         - CDD is ideal for a programming team environment.  Built-in
           import, clone, and merge utilities are specially designed for
           team programming, telecommuting, and concurrent development.


                                 --- Page 3 ---


    2.0  INSTALLATION
    -----------------

    CDD.EXE, CDDLIB.LIB, and other files require a total of about
    one Mbyte of disk space to install.

    Since a CDD application is mostly data-driven, the data dictionary
    is open at all times during operation.  As a result, the number of
    file handles in your CONFIG.SYS and network config file (SHELL.CFG
    for Novell) should be set to 65 or higher.  The actual CDD data
    dictionary requires 36 file handles at runtime, 21 dbf/dbt and 15
    indexes.

    Also remember to either SET CLIPPER=F65 or burn in the max file
    handles setting into your EXE file via the linker.


    2.1  INSTALLING CDD.EXE AND CDDLIB.LIB
    --------------------------------------


         CDD.EXE      - The data dictionary editor and screen designer.
                        Usually located in the same directory as
                        CLIPPER.EXE or elsewhere on your path.
                        CDD.EXE is always run from your data dictionary
                        directory.

         CDDLIB.LIB   - The CDDLIB.LIB runtime library is linked into
                        your application.  CDDLIB.LIB is always located
                        in the root, not in the overlay. Place this
                        library into your Clipper library directory.


         CDDLIB.LIB ALWAYS RESIDES IN THE ROOT, NOT THE OVERLAY !!!!


    2.2  INSTALLING A CDD APPLICATION
    ---------------------------------

    Most CDD programs are installed into a parent directory for the
    application EXE and application data and index files. The data
    dictionary may be installed into a "DD" subdirectory below the
    parent application directory.  E.g. :


         ...\TEST         - Contains application EXE, DBFs and NTXs

         ...\TEST\DD      - Contains the data dictionary.  CDD.EXE is
                            run while in this directory.  Creating a
                            separate data dictionary directory is
                            optional.

                                 --- Page 4 ---




    2.3  CREATING THE APPLICATION PRG FILE
    --------------------------------------

    The main prg file consists of three sections:

    1. A call to v_init() to initialize the CDD data dictionary

    2. Declaration of external functions for the compiler and linker. If
       you call third party functions via the data dictionary that are
       contained in an overlay, you will need to list those functions
       here.

    3. Installation of the CDDLIB alternate error handler.  The
       alternate error handler provides CDDLIB specific debugging
       information upon an error.

    A typical main prg is:

         * TEST.EXE main module
         v_init("test","\test\dd\")   // See v_init() for more info.

         * put any necessary EXTERNAL definitions here

         * install alternate error handler
         procedure errorsys
            errorblock({|e| v_e_alt(e)} )
         return


    2.4  CREATING THE LINK FILE
    ---------------------------

    A typical CDD application link file for BLINKER or RTLINK is:

         # main module
         file test.obj

         # other root modules below

         overlay code
         begin
            # your objs below

            # overlayable libs
            library extend
         end

         library Clipper, cddlib


                                 --- Page 5 ---



    2.5  CREATING THE DATA DICTIONARY FILES
    ----------------------------------------

    CDD.EXE is used to create a new set of data dictionary files.
    CDD.EXE is ALWAYS run from the data dictionary subdirectory.  The
    first screen of CDD prompts for a system name.  This is generally
    the same name as your application EXE file (Up to 6 characters).

    If you enter an unknown or non-existent system name, you will be
    given the opportunity to create a new set of data dictionary files.

    CDD.EXE also accepts the system name as a command line parameter.
    E.g. "cdd demo" will automatically load the data dictionary for the
    "demo" application.  The DOS environment variable CDDNAME may also
    be used to preload the system name when running CDD.EXE. E.g. SET
    CDDNAME=TEST


    2.6 USING CDD.EXE
    -----------------

    The commonly used CDD action and navigation keys are:

       Browse lists:

          <Ins>    -  Add a record
          <Del>    -  Add a record
          <Enter>  -  View a record
          <Arrows> -  Navigation
          <F10>    -  Change viewing order and find prompt

       Screens:

          <Arrows> -  Navigation, moves the floating pointer between fields

          <Enter>  -  Edit the current field

       Special Keys !!!!!:

          <F5> in browse definition screen - copy keys from another
          browse.

          <F5> in screen definition screen - copy keys/fields from
          another screen.

          <ALT-L> in screen field def - load condition for valid
          or initialization expression into a buffer.  This key is
          paired with the <ALT-K> key.

          <ALT-K> in screen field def screen during active GET - dump

                                 --- Page 6 ---


          buffer (stuff the keyboard).  This feature is often to copy
          complicated table lookup expressions from one screen field to
          another.

       NOTES: Lookup tables and pick lists are available for the data
              dictionary fields marked with an asterisk.

              The <ALT-L> and <ALT-K> keys are VERY useful when is
              necessary to copy and revise table lookup validations and
              initializations from one screen field to another.  The
              keys save much tedious typing.


    2.7 TYPICAL DEVELOPMENT STEPS
    -----------------------------

    The typical development steps for a simple application
    consisting of two files (one main data file and a table
    lookup file) are:

    - Create, compile, and link the application PRG file.

    - Create the CDD data dictionary for the application.

    - Define a main menu consisting of a main browse item and a table
      maintenance item.  The function IDs called by the menu items
      will be created in the next few steps.

    - Define and create the main data file and its associated
      indexes.

    - Create a browse for the main data file.

    - Create a screen for the main data file.  At this point the
      field that must be validated against the table lookup file has
      no validation expression entered.

    - Define and create the table lookup file and its associated
      indexes.

    - Create a table maintenance browse for the table lookup file.

    - Create a table maintenance screen for the table lookup file.

    - Create a table lookup browse for the table lookup file.  This
      lookup browse will be called by the screen field validation
      function.

    - In the screen for the main data file, add the validation
      statement (uses the table lookup browse).


                                 --- Page 7 ---


    - Add any relational integrity and update processes to the table
      maintenance routines.  Most relational integrity functionality is
      wired last, after all other application files, indexes, and table
      lookups files are in place.


    2.8 GENERAL CDD CONCEPTS
    ------------------------

    Each major function in the data dictionary is identified with a 10
    character unique identifier.  Different types of functions may have
    the same function ID, but IDs within the same function type must be
    unique.  E.g. The browse and the screen IDs for data file "Customer"
    may both have "Customer" as their respective function IDs.

    Each Function ID is paired with a type designator.  "B" = Browse,
    "F" = Find, "M" = Menu, "S" = Screen, "U" =  UDF or external
    function.

    When calling a CDDLIB function from within your own code - ALWAYS
    use v_load() to call a menu, browse, screen, or find.  NEVER call
    v_menu(), v_browse(), v_screen(), or v_find() directly!  V_load()
    maintains an internal stack that provides the error handler with
    debugging information.  All other CDDLIB functions may be directly
    called.

    Public variables used as "index aliases" are created when v_open()
    opens an application data files and indexes.  The index alias
    contains the numeric index order.  Use index aliases in v_vieword()
    and v_order().

    To enter a high ASCII (graphic) character into a field, type the
    desired number on the numeric keypad while holding down the <Alt>
    key.

    Lines 23 and 24 of all screens are RESERVED for use by CDDLIB
    functions.

    Data Dictionary fields labeled as "condition...." are used to
    control program branching.  The return value of an expression in a
    "condition...." field must be a Boolean.

    Data dictionary fields labeled as "proc..." or "process" are simply
    evaluated as is.  Any return value is ignored.

    When ANDing together expressions (in "condition" or "process"
    fields) boolean short circuit logic is always active.  I.e. If the
    first expression of several returns false, then NO other expressions
    in the series get evaluated.  To facilitate "chaining" together of
    expressions, most CDDLIB functions return true.


                                 --- Page 8 ---


    3.0 CDD MAIN MENU
    -----------------

Ŀ
                           CDD Maintenance Program                        



Main Menuͻ
 1. Screen Definitions       
 2. Browse Definitions       
 3. Menu Definitions         
 4. Find Definitions         
 5. Sequence Definitions     
 6. DBFs, NTXs, and Fields   
 7. Startup and Configuration
 8. Utilities                
ͼ










    1. Screen Definition - Design the screen, define screen fields, and
       define the screen action keys.

    2. Browse Definitions - Define the browse, the browse action keys,
       and browse columns.

    3. Menu Definitions - Define menus and menu items.

    4. Find Definitions - Define finds and find items.

    5. Sequence Definitions - Define sequence of events to
       execute.

    6. DBFs, NTXs, and Fields - Define and create data files and
       indexes.

    7. Startup and configuration - Define the startup function and
       various default box types, default colors, etc.

    8. Utilities - CDD and application file reindexing, CDD clone and
       import functions, CDD data dictionary string search utility, etc.



                                 --- Page 9 ---


    4.0 STARTUP AND CONFIGURATION
    -----------------------------

Ŀ
                          Startup and Configuration                 V_SYS (S) 
Ĵ
 Path to data files......:                                                 
 Path to index files.....:                                                    
 Start function ID.......:    MAINMENU                                        
 Start function type.....:    M                                               
 Show backdrop?..........:    Y                                               
 Backdrop line 1 title...:    CDD Demonstration Program                       
 Backdrop line 2 title...:                                                    
 Backdrop fill char......:                                                   
 Browse box string.......:   *Ŀ                                        
 Browse column separator.:             <- Chr 255 to preserve whitespace     
 Browse header separator.:               "   "  "      "        "          
 Menu box string.........:   *ͻȺ                                        
 Screen box string.......:   *ͻȺ                                        
 Key list box string.....:   *                                        
 Key list title..........:    ~ AVAILABLE COMMAND KEYS ~                      
 Prompt for exit?........:    N                                               
 Lock record on edit?....:    Y  Y=Lock before edit, N=Lock before replace    
 Color defaults..........:    [Screen]                                        
 Sound, other defaults...:    [Screen]                                        



    Path to data files - The location of the application data files. The
    path must end with  ":" or "\".  If empty the current directory is
    the path.

    Path to Index Files - The location of the application index files.
    The path must end with ":" or "\".  If empty the current directory
    is the path.

    Start Function ID - The CDD function ID that will be called first
    after initialization.  See the "General CDD Concepts" section for
    information about function IDs.  If needed, instead of calling a CDD
    function here, your own UDF function can be called here.

    Start Function Type - The type of CDD Function (M,B,S,F,U) selected
    via a lookup.

    Show backdrop? - Flag indicating whether to paint the title and
    backdrop on the screen.

    Backdrop Line 1 title - The first line of the backdrop title.
    If lines 1 and 2 are empty, no title box will display.

    Backdrop Line 2 title - The second line of the backdrop title.

                                --- Page 10 ---



    Backdrop Fill Character - The fill character for the backdrop.

    Browse Box String - The default browse box type, selected via a
    lookup.

    Browse Column Separator - The default browse column separator. Since
    this field is trimmed of white space at runtime, character 255 can
    be used to preserve the spacing.  Character 255 appears as a blank
    or a space, but is not trimmable.

    Browse Header Separator - The default data\header separator.  Use
    Character 255 (entered via the Alt-Numeric keypad) to preserve white
    space.

    Menu Box String, Screen Box String, Key List Box String - Default
    box types that are selectable via a lookup.

    Key List Title - The default key list title, use a tilde "~" or
    character 255 to preserve whitespace. The tilde will be converted to
    a space at runtime.

    Prompt for Exit? - Set "Y" to prompt the user "Do you wish to exit
    the program?".

    Lock record on edit - Set "Y" to cause the record to be locked as
    soon as the user begins editing.  Set "N" to lock the record only
    for the brief moment during the saving of the record.

    Color defaults - Pressing <Enter> on this field will call the color
    setup screen.

    Sound, other defaults - Pressing <Enter> on this field will call the
    sound and other defaults setup screen.


















                                --- Page 11 ---


    4.1 SYSTEM COLORS
    -----------------

Ŀ
                               System Colors                        V_SYS (C) 
Ĵ
    Video Mode...............:  A  A=Autodetect, C=Color, M=Mono           
    System/backdrop colors...:     W+/B                                       
    Backdrop title color.....:     W+/B                                       
    Status lines color.......:     BG+/N                                      
    Help color...............:     R+/N                                       
    Browse colors............:     W+/B,B/W,,,BG+/B                           
    Browse fade color........:     BG/B                                       
    Menu colors..............:     W+/B,B/W,,,BG+/B                           
    Menu fade color..........:     BG/B                                       
    Find colors..............:     BG+/N,N/W,,,BG+/B                          
    Screen colors............:     W+/B,B/W,,,BG+/B                           
    Screen fade color........:     BG/B                                       
    Message function colors..:     B/W,B/BG,,,B/W                             
    Key List colors..........:     W+/B,N/W,,,W/B                             
                                                                              
                                                                              
                                                                              
                                                                              
    Note: Mono mode colors are fixed.                                         


    Video Mode - Select the mode of operation.

    Colors - The various sets of default colors.

    NOTE: "Colors" (plural) requires a full and complete Clipper color
          string.  "Color" (singular) is a single foreground/background
          color pair.

          If the video mode is "M" (mono), the colors are hardcoded and
          are not configurable in the data dictionary.















                                --- Page 12 ---


    4.2 SYSTEM SOUNDS, OTHERS
    -------------------------

Ŀ
                            System Sounds, Others                   V_SYS (S) 
Ĵ
    Menu sounds..............: N                                           
    Browse sounds............:    N                                           
    Screen sounds............:    N                                           
    CDDLIB warning sounds....:    N                                           
                                                                              
                                                                              
    Information key..........:    -34 Calls V_INFO(), 0 = No key, -34=Alt-F5  
    Shadow quadrant..........:    0   0..3                                    
                                                                              
                                                                              
                                                                              
                                                                              
                                                                              
                                                                              
                                                                              
                                                                              
                                                                              
                                                                              
                                                                              


    Menu Sounds, Browse Sounds, Screen Sounds, CDDLIB Warning Sounds -
    Miscellaneous hittop/hitbottom/warning sounds.

    Information Key - The inkey value of the hotkey that calls v_info().
    V_INFO() is a programmers tool (a CDDLIB function) that can display
    the CDD call stack, any current record in a workarea, etc.

    Shadow Quadrant - 0...3 select intersection corner for the shadow.

















                                --- Page 13 ---


    5.0 MENU DEFINITIONS
    --------------------

Ŀ
                               Menu Definition                      V_MEN (M) 
Ĵ
   Menu Function ID......: MAINMENU                                        
   Title.................:    [ CDD Demo Main Menu ]                          
   Coordinates (t,l).....:     5     5                                        
   Condition for access..:    v_sequence("init")                              
   Condition for exit....:                                                    
   Post process..........:                                                    
   Auto. execute on key?.:    Y                                               
   Save Scrn/Area/Ord/Rec:    Y    Y    N    N                                
   Center menu prompts?..:    Y                                               
   Alt. menu colors......:                                                    
   Alt. menu fade color..:                                                    
   Alt. menu box chars...:   *                                                
                                                                              
                                                                              
                                                                              
                                                                              
                                                                              
   Help Text.............:    Memo                                            
   Menu Item Definitions.:    [Browse]                                        


    Menu Function ID - Unique menu identifier.

    Title - Menu title string.  Use a tilde "~" to preserve white space.
    E.g. "~ My Menu Title ~".

    Coordinate (t,l) - The top and left corner position.  The menu will
    adjust the length and the width.  The menu will items scroll if more
    items exist than the menu can display.

    Condition for Access - Boolean expression or expressions controlling
    access to the menu.  If the expression returns false, the menu will
    not be displayed.  The condition for access is also an ideal place
    to do initializations if necessary.  It may also be used to limit
    access based on a security level.

    Condition for Exit - Boolean expression controlling whether the user
    may exit the menu.  Often used for cleanup or restore operations.

    Post Process - A function executed after the menu is terminated.
    The post process is always executed even if the condition for access
    failed.  The return value of any post process functions are ignored.

    Auto. Execute on Key? - If "Y", pressing a key that matches the
    first character of a menu item will execute that item function.  If

                                --- Page 14 ---


    "N", pressing a matching key will move the highlighted bar down to
    the first match, then pressing <Enter> is required to execute an
    item.

    Save Scrn/Area/Ord/Rec - Flags to indicate it is saving the original
    environment.  The original environment is the environment BEFORE the
    menu is loaded.  Environment settings that can be saved are screen,
    work area, index order, and record no.

    Center Menu Prompts? - Flag indicating whether to center the menu
    item prompts that appear on line 23 and 24.

    Alt. Menu colors - Complete color string.

    Alt. Menu Fade Color - Single fore/back color pair.

    Alt. Menu Box Chars - Selectable by lookup.

    Help Text - Memo for help.

    Menu Item Definitions - Goto the menu item browse for this menu.































                                --- Page 15 ---


    5.1 DEFINING MENU ITEMS
    -----------------------

Ŀ
                       Menu Item Definition for MAINMENU            V_MNK (N) 
Ĵ
    Menu item position....:   10                                           
    Description...........:     1. Browse Parent Data File                    
                                                                              
    Call Function ID......:     PARENT                                        
     "       "    Type....:     B                                             
     "       "    Param...:                                                   
     "       "    Extern..:                                                   
                                                                              
    Cond. for item select.:                                                   
    Condition for access..:                                                   
    Post execution proc...:                                                   
    Post key proc.........:                                                   
    Condition to show.....:                                                   
    Fade Menu?............:     Y                                             
                                                                              
    Line 23 message.......:     Browse PARENT.DBF (unfiltered browse)         
    Line 24 message.......:                                                   
                                                                              
                                                                              



    Menu Item Position - The position in the menu where this item will
    appear.  The position is often numbered by tens to allow for easy
    insertion of menu items in the future.

    Description - The menu item text as it will appear in the menu.

    Call Function ID - ID of CDD function to call upon item selection.
    ID should be empty if ID type is "U".

    Call Function Type -  Type of function ID.
                          "B" = Browse
                          "F" = Find
                          "M" = Menu
                          "S" = Screen
                          "U" = UDF, CDDLIB function, or other
                                external function.

    Call Function Param - Currently this is only used for "S" - (screen)
    function ID's.
                          "A" = Start screen in add mode.
                          "E" = Start screen in edit mode.
                          ""  = Start screen in view mode.


                                --- Page 16 ---


    Call Function Extern - Only available for "U"-type function types.
    Call any external or CDDLIB function.

    Cond. for Item Select - Boolean.  Determines whether item is
    selectable.  It is often used as a security check. E.g. "level ==
    99" (no quotes).  If false is returned by this expression, this item
    will appear as unselected (grayed out).

    Condition for Access - Boolean.  Determines whether the function
    associated with the item/key will be executed.  This is the last
    code insertion point before calling the key function.

    Post Execution Process - Executed upon returning from the function
    if the condition for access was true.  It is often used for cleanup
    and restore operations.

    Post Key Process - Executed just before exiting the item/key
    regardless of whether the condition for access was true.

    Condition to Show - Boolean.  At runtime, determines whether the item
    is shown on the menu.

    Fade Menu - Flag indicating that the menu is faded upon selecting
    the menu item.

    Line 23 Message - Menu item prompt for line 23.

    Line 24 Message - Menu item prompt for line 24.
























                                --- Page 17 ---


    6.0 BROWSE DEFINITIONS
    ----------------------

Ŀ
                       Browse Definition (Pg. 1 of 2)               V_BRO (B) 
Ĵ
   Browse Function ID...:    PARENT                                           
   Datafile Alias.......:   *PARENT                                           
   Init. Index Alias....:   *PARENT1  upper(string1)                          
   Index Filter Expr....:                                                     
   Title................:    Unfiltered Browse of PARENT.DBF                  
   Coordinates (t,l,b,r):     5     4    21    75                             
   Condition for access.:                                                     
   Condition for exit...:                                                     
   Post process.........:                                                     
   Post keystroke proc..:                                                     
   Frozen columns.......:     0                                               
   Save Scr/Area/Ord/Rec:    Y    Y    N    N                                 
   Initial GOTOP?.......:    Y                                                
   Use std. nav. keys?..:    Y                                                
                                                                              
   Browse Def. Pg. 2....:    [Screen]                                         
                                                                              
   Column Definitions...:    [Browse]                                         
   Key Definitions......: [Browse]                                         



    A browse definition consists of three parts:

         1. The browse screen and the format defines the data file,
            index order, filter, coordinates, etc.

         2. The browse column definitions to designate the fields,
            functions, or expressions used for the column.

         3. The browse key definitions to define action (command) keys
            and their calls to other functions.  During the browse, a
            pick list of available action keys is displayed when the
            user presses <F10>.

    Browse Function ID - Unique browse identifier.

    Data File Alias - The alias of the data file to browse.  If blank,
    the current work area is used.

    Init. Index Alias - The index alias of the index to initially use
    while browsing.  If blank, the current order for the work area is
    left unchanged.

    Index Filter Expr - The string expression used for index-based

                                --- Page 18 ---


    filtering.  The index filter expression should match (by string
    value) the first part of the active index.  If a filter expression
    is used, then matching index or indexes MUST be available at all
    times during the browse.  If blank, no filtering is done and the
    entire data file is browsable.

       Example: If the index is "type + company_no" and you wish to
                browse only companies that are type = "A", then the
                filter expression is "A" (since the filter expression is
                evaluated, surround straight text strings with quotes).
                The filter expression may be a memvar, an aliased field
                from a parent data file, a function or other expression.
                The filter expression must match the first (leftmost)
                portion of the available index or indexes.

       Note:    When changing index order (via one of the browse action
                keys) insure that ONLY indexes that correspond to the
                filter expression can be chosen by the user.


    Title - The title string for the browse.  The string will be
    centered in the browse header when displayed.

    Coordinates - The browse window coordinates.

    Condition for Access - The Boolean expression controlling access to
    browse.  May be used for initialization, file opening, security
    checking.

    Condition for Exit - Boolean expression controlling whether the
    browse may be exited.  Often used to cleanup or restore settings
    after a browse.

    Post Process - Process executed immediately prior to exiting from
    browse.  Used for cleaning up and restoring.

    Post Keystroke Proc - Process executed after each keypress
    regardless of whether the key is defined as a browse action key.
    This procedure is often used to update record dependent displays on
    the screen after the record pointer has been moved.

    Frozen Columns - Number of lefthand columns to freeze. 0 = No frozen
    columns.

    Save Scr\Area\Ord\Rec - Flags to save original (pre-browse)
    environment.  Environment settings that can be saved here are:
    screen, work area, index order, record number.

    Initial Gotop? - Flag indicating that the browse will attempt to
    position the record pointer to the logical top.  If the browse
    cannot position to the logical top, (no records found), the record

                                --- Page 19 ---


    pointer is moved to the end of the file.

                      ***** IMPORTANT NOTE *****

    Note: For browses used as lookup tables ( via v_look1() ), the
          initial GOTOP should be "N" because v_look1() pre-positions
          the record pointer.  If you wish to pre-position the record
          pointer externally, set Initial GOTOP = N and position the
          record pointer in the condition for access via a function.

    Use Std. Nav. Keys? - Flag indicating that the browse will use a
    predefined set of navigation keys.  If you wish to remap a one or
    several standard navigation keys, list the appropriate key(s) in the
    browse action key list.

    Note: The actual tbrowse object is available to the programmer as
          the object variable "v_bro".  The tbrowse methods for
          navigation, etc.., may be directly called by browse keys.
          E.g. "v_bro:gotop()" will move the record pointer to the
          logical top.

    Browse Def. Pg. 2 - Go to the second page of the browse definition.

    Column Definitions - Go to the list of column definitions.

    Key Definitions - Go to the list of browse action key definitions.

    Line 23 Message - Prompt to appear on line 23.

    Line 24 Message - Prompt to appear on line 24.

    Center Status Lines - Y = Center line 23 and 24 prompts.
                          N = Line 23 and 24 prompts start at column 0.

    Full Width Highlight Bar - Y = Highlight bar extends fully from left
                                   to right of the browse.

                               N = Highlight bar is contained within a
                                   single browse cell.

    Alt Browse Colors - Complete Color String.

    Alt Browse Fade Color - Single fore/back color pair.

    Alt Browse Column Sep - Column separator.

    Alt Browse Header Sep - Header/date separator.

    Alt Key List Title - Alternate action key list title.

    Help Text - Memo for browse help.

                                --- Page 20 ---


    6.1 DEFINING BROWSE COLUMNS
    ---------------------------

Ŀ
                Browse Column Definitions for PARENT                V_COL (C) 
Ĵ
   Column position.......:   10                                            
   Field/Memvar/Expr.....:    *STRING1                                        
   Column header.........:     String 1                                       
   Picture clause........:                                                    
   Condition to show?....:                                                    
   Alt. column separator.:            <- Chr 255 to preserve whitespace       
   Alt header separator..:                "   "  "      "        "            
                                                                              
                                                                              
                                                                              
                                                                              
                                                                              
                                                                              
                                                                              
   Notes:  Column width is determined by the larger length - the              
           field or the rtrim(header) length                                  
                                                                              
           Multiple line headers are possible by using semicolons             
           to delimit separate lines.                                         



    Column Position - Numeric position for column display order.

    Field/Memvar/Expr - Name of field to show in column.  This may also
    be a memvar or a function.  E.g. Field1 or Alias->Field1 or
    myfunc(), etc.

    Picture Clause - Optional picture formatting clause.

    Condition to Show - Condition to determine whether column is
    displayed.

    Alt. Column Sep - Alternate column separator appearing to the left
    of the column.

    Alt. Header Sep - Alternate header/data separator.









                                --- Page 21 ---


    6.2 DEFINING BROWSE KEYS
    ------------------------

Ŀ
                       Browse Key Definition for PARENT             V_KEY (K) 
Ĵ
    Key list position.....:   10                                           
    Char. or "K"+Inkey....:     A       e.g.  D or K276 or K-9                
    Description...........:     A - Add                                       
                                                                              
    Call Function ID......:     PARENT                                        
     "       "    Type....:     S                                             
     "       "    Param...:     A                                             
     "       "    Extern..:                                                   
                                                                              
    Cond. for key select..:                                                   
    Condition for access..:                                                   
    Post execution proc...:                                                   
    Post key proc.........:                                                   
    Condition to show.....:                                                   
    Fade browse?..........:     Y                                             
    RefreshAll after key?.:     Y                                             
    RefreshCurrent after?.:     N                                             
                                                                              
                                                                              


    Key List Position - The numeric position by which the key list will
    be ordered.  Number by tens to allow easy insertion of new keys.

    Char. or "K" + Inkey - The character value or the inkey value for
    the key.  For a character, type the actual character.  E.g. For the
    "A" key, enter "A".  For an inkey value, type "K", then the actual
    inkey number.  E.g. <Alt_0> -> K280, <F9> -> K-9.

    Call Function ID - ID of CDD function to call upon key selection.
    ID should be empty if ID type is "U".

    Call Function Type -  Type of function ID.
                          "B" = Browse
                          "F" = Find
                          "M" = Menu
                          "S" = Screen
                          "U" = UDF, CDDLIB function, or other
                                external function.

    Call Function Param - Currently this is only used for "S"-type
    (screen) function ID's.

                          "A" = Start screen in add mode.
                          "E" = Start screen in edit mode.

                                --- Page 22 ---


                          ""  = Start screen in view mode.


    Call Function Extern - Only available for "U"-type function types.
    Calls any external or CDDLIB function.

    Cond. for Key Select - Boolean expression to determine whether the
    key can be selected or not.  If the key select condition returns
    false, the key will be "grayed out" in the key list.

    Cond. for Access -  Boolean expression.  Determines whether key
    function will be executed.

    Post Exec. Process - Process executed immediately after executing
    the key function.

    Condition to Show - Flag indicating whether this key will be visible
    in F10 key list.  Condition to show does NOT control whether this
    key may be executed or not.

    Fade Browse? - Flag indicating whether to fade the browse before
    executing the key function.

    RefreshAll After Key - Flag indicating whether the browse object
    should refresh itself upon returning from the key function.  This
    should always be true (Y) if the key function moves the record
    pointer, changes the index, etc.  RefreshAll reloads all data
    currently displayed in the browse.

    RefreshCurrent After Key - Flag to signal a refresh of the current
    record only.





















                                --- Page 23 ---


    7.0 SCREEN DEFINITIONS
    ----------------------

Ŀ
                        Screen Definition (Pg. 1 of 3)              V_SCR (T) 
Ĵ
   Screen Function ID...: PARENT                                           
   Datafile Alias.......:   *PARENT                                           
   Init. Index Alias....:   *                                                 
   Index Filter Expr....:                                                     
   Condition for access.:                                                     
   Condition for exit...:                                                     
   Post process.........:                                                     
   Post keystroke proc..:                                                     
   Save Scr/Area/Ord/Rec:    Y    Y    N    N                                 
   Initial GOTOP?.......:    N                                                
   Use std. nav. keys?..:    Y                                                
   Exit screen if eof?..:    Y                                                
                                                                              
   Screen def. page 2...:    [Screen]      (Add/Edit Conditions, Procs)       
   Screen def. page 3...:    [Screen]      (Alt colors, etc.)                 
                                                                              
   Field/Get definitions:    [Browse]                                         
   Key definitions......:    [Browse]                                         
   Screen designer......:    Process                                          


    Screen Functions ID - Unique screen identifier.

    Datafile Alias - The alias of the data file to browse.  If blank
    then the current work area is used.

    Initial Index Alias - The index alias of the index to use initially
    while viewing.  If blank, the current index order for the work area
    is left unchanged.  Index alias is often left blank because the
    index order can be selected in a preceding browse at runtime.

    Index Filter Expr - The expression used for index-based filtering.
    The index filter expression should match (by value) at least the
    first part of the active index.  If a filter expression is used,
    then matching index or indexes MUST be available at all times during
    the browse.  If blank, no filtering is active and the entire data
    file range is viewable.

       Example: If the index is "type + company_no" and you wish to
                browse only companies that are type = "A", then the
                filter expression is "A" (since the filter expression is
                macro evaluated, use quotes for straight text strings).
                The filter expression may be a memvar, an aliased field
                or fields from a parent data file, a function or other
                expression.  The filter expression usually matches the

                                --- Page 24 ---


                first (leftmost) portion of a character index or
                indexes.

       Note:    When changing index order (via one of the screen action
                keys) insure that ONLY indexes can be chosen by the
                user.

    Condition for Access - The Boolean expression controlling access to
    the screen.  Often used for initialization.

    Condition for Exit - Logical expression to control exiting from the
    screen.  It can also be used to call cleanup functions.

    Post Process - Process executed immediately before exiting the
    screen.

    Post Keystroke Proc - Process executed after EVERY keypress
    regardless of whether the key is defined as a screen action key.
    Often used for updating record dependent information on the screen.

    Save Scr/Area/Ord/Rec - Flags to save original (pre-screen)
    environment.  Save options are screen, work area, index order,
    record position.

    Initial Gotop - If "Y" the screen will attempt to initially position
    the record pointer to the logical top.

    Use Std. Nav. Keys? - If "Y" then a set of standard navigation keys
    are activated.  The standard navigation keys may be remapped via the
    screen action keys.

    Exit Screen if eof? - If "Y" and in view mode, the screen will
    automatically terminate if the current workarea is at eof.  If you
    are defining a screen that contains nothing but screen memvars and
    no actual dbf fields, then this should be set to "N".

    Screen Def. Page 2 - Goto page 2.  Page 2 contains the definitions
    relating to adding and editing.

    Screen Def. Page 3 - Goto page 3.  Alternate color definitions.

    Field/Get Definitions - Goto screen field definitions.

    Key Definitions - Goto screen action keys definitions.

    Screen Designer - Goto the screen designer utility.






                                --- Page 25 ---


Ŀ
                        Screen Definition (Pg. 2 of 3)              V_SCR (T) 
Ĵ
  Cond. for Add/Edit.........:                                                
  Cond. for Add/Edit Exit....:                                             
  Before Add/Edit Update proc:     v_sequence("touch") .and. if(s_mode=="A"   
  After Add/Edit Update proc.:                                                
  Post Add/Edit proc.........:                                                
  Set CONFIRM ON?............:     N                                          
  Prompt for accept?.........:     Y                                          
  Accept Prompt if Esc?......:     Y                                          


    Cond. for Add/Edit - Condition controlling access to add/edit.

    Cond. for Add/Edit Exit - Condition to allow exiting from add/exit
    mode.

    Before Add/Edit Update Process - Function called before saving.
    Generally used to alter the selected screen memvar prior to saving
    it to its dbf field.  Use this definition to assign values to
    non-editable screen memvars.

    After Add/Edit Update Process - Function called immediately after
    saving a record.  Used for cleanup, unlocking other work areas, etc.

    Post Add/Edit Proc. -  Process executed after add/editing regardless
    if the screen was actually edited.

    Set CONFIRM ON? - If "Y" then the user is prompted for "Accept",
    "Retry", or "Cancel". If "N" then the record is automatically saved
    upon exiting (unless the user escapes).

    Accept prompt if Esc. - If "Y" the user is prompted whenever the
    screen has been changed and <Esc> is pressed.

















                                --- Page 26 ---


Ŀ
                       Screen Definition (pg. 3 of 3)               V_SCR (T) 
Ĵ
   Line 23 message.........:  Press F10 for available commands             
   Line 24 message.........:                                                  
   Center status lines?....:     N                                            
   Alt. screen colors......:                                                  
   Alt. screen fade color..:                                                  
   Alt screen box chars....:    *                                             
   F-Key for keylist.......:     F10 (F2 - F10)                               
   Alt. keylist colors.....:                                                  
   Alt. keylist box chars..:    *                                             
   Alt. keylist title......:                                                  
                                                                              
                                                                              
                                                                              
                                                                              
                                                                              
   Help Text...............:     Memo                                         


    Line 23 Message - Status Prompt on line 23.

    Line 24 Message - Status Prompt on line 23.

    Center Status Line? - If "Y" then the status prompts on lines 23 and
    24 are centered.

    Alt. Screen Colors - Complete color string.

    Alt. Screen Fade Color - Single fore/back color pair.

    Alt Screen Box Chars - Box character set.

    F-key for keylist - Function key to popup list of available action
    keys.

    Alt. Key List Colors - Complete color string.

    Alt. Key List Box Chars - Box character set.

    Alt. Key List Title - New key list title.

    Help Text - Help for the screen (available only during view mode).








                                --- Page 27 ---


    7.1 DEFINING SCREEN FIELDS
    --------------------------

Ŀ
                  Screen Field/Get Definition for PARENT            V_GET (U) 
Ĵ
 Position (Get sequence):  10                                              
 DBF alias->field.......:   *PARENT    ->   *STRING1                          
 Int. variable name.....:    mstring1                                         
 Int. var. declaration..:    P                                                
 Get prompt (line 23)...:    Enter string 1                                   
  "  type/length/dec....:    C       10     0                                 
  "  PICTURE............:    @!                                               
  "  init. expression...:                                                     
  "  VALID (cond).......:    v_getempty("String 1") .and. v_getljust(         
  "  WHEN (is editable?):                                                     
                                                                              
 Full screen valid cond.:    !empty(mstring1)                                 
 Full screen valid msg..:    Full screen valid - STRING1 cannot be em         
                                                                              
 Alt. colors (2 colors).:    W+/R,W+/R                      (Unsel / Select)  
 Alt. color operation...:    N   Y = Add/Edit/View mode, N = Add/Edit mode    
                                                                              
                                                                              
 Help memo..............:    Memo                                             


    Position (Get Sequence) - Order by which the screen memvars will be
    edited.

    DBF alias->field - The alias and field associated with the screen
    memvar.  If either alias or field are blank, then this screen variable
    is simply a memvar that can be initialized and edited, but the
    memvar is not associated with an actual dbf field.  With an actual
    dbf field, both alias and field are required because a set-get block
    is created for the dbf field using fieldwblock().

    Int. Variable Name - The name of the internal screen memvar to be
    created, initialized, and edited.  No automatic naming occurs here -
    you must enter the name of the variable.

    Int. Var. Declaration - P = Private, U = Public, N = None

       If the declaration type is "N", then it is assumed that a variable
       of this name was created at a higher level.  An "N" type declared
       variable will not be initialized by the screen function unless an
       initialization expression is specified.

    Get Prompt (line 23) - Edit prompt for the screen memvar.

    Type/Length/dec. - Screen memvar descriptors.

                                --- Page 28 ---



    Picture - Picture clause.

    Init. Expression - Initialization expression or value.  If an
    alias->field is specified, the initialization differs according to
    the screen mode.  The "s_mode" screen variable indicates screen
    mode.

       If screen memvar is associated with a dbf field:

          Add mode - the screen memvar is initialized to an empty value
          or from the initialization expression.

          Edit mode - the screen memvar is initialized from the actual
          dbf field or from the initialization expression.

       If screen memvar is NOT associated with a dbf field:

          Add mode - the screen memvar is initialized to an empty value
          or from the initialization expression.

          Edit mode - same as add mode.


    VALID (cond) - The condition for validation during the edit of the
    screen variable.  Also used to format, justify, or to call a lookup
    function.  Since the memvar is visible during the validation, it may
    be altered, trimmed justified, etc....

    WHEN (is editable) - The WHEN condition determines whether the memvar
    is editable.  Set WHEN to .f. if the memvar is view only.  I.e. ".f."
    (with no quotes) in the WHEN field.

    Full screen valid cond - The condition for validation evaluated upon
    completion of the READ for the entire screen.  If false, the user
    will be given the option to "Re-Try" or "Cancel" the add or edit.
    If "Re-Try" is chosen, the errant screen variable will become the
    active get.  The full screen valid should never require user action.
    It should be a simple condition such as "!empty( myvar )", etc.

    Full screen valid msg -  The error message for the full screen valid
    when it fails.

    Alt Colors (2 colors)- The alternate get colors.  The get colors
    consist of 2 fore/back pairs for the unselected and selected colors.
    E.g. W+/R, W+/R for red on white.

    Alternate Color Separation - "Y" for the alternate colors to be in
    effect during view, add, and edits.  "N" for add and edit modes
    only.


                                --- Page 29 ---


    Help Memo - Help for the screen memvar during its GET.


    NOTES ABOUT SCREENS: The record locking/unlocking only takes place
    in the current work area.  If you are editing fields from another
    work area you are responsible for locking/unlocking the other work
    areas.  Data fields are not edited directly, screen memvars are
    initialized from the record, then edited, and then the contents of
    the memvars are saved back to the record.  If no fields are
    associated with any of the screen memvars, then no record locking or
    adding will take place.  I.e. A screen containing only memvars.









































                                --- Page 30 ---


    7.2 DEFINING SCREEN KEYS
    ------------------------

Ŀ
                       Screen Key Definition for PARENT                       
Ĵ
    Key list position.....:   10                                           
    Char. or "K"+Inkey....:     A       e.g.  D or K276 or K-9                
    Description...........:     A - Add                                       
                                                                              
    Call Function ID......:                                                   
     "       "    Type....:     U                                             
     "       "    Param...:                                                   
     "       "    Extern..:     s_add()                                       
                                                                              
    Cond. for key select..:                                                   
    Condition for access..:                                                   
    Post execution proc...:                                                   
    Post key proc.........:                                                   
    Condition to show.....:                                                   
    Fade screen?..........:     N                                             
    Reload after key?.....:     Y                                             
    Redisplay after key?..:     Y                                             
                                                                              
                                                                              


    Key List Position - Order of appearance on the key list.

    Character or "K" + Inkey - The character or inkey value for the key.
    Inkey values are entered as "K" + Inkey value. E.g.  <Alt-O> = K280.

    Description - The item description in the keylist.

    Call Function ID - ID of CDD function to call upon key selection.
    ID should be empty if ID type is "U".

    Call Function Type -  Type of function ID.
                          "B" = Browse
                          "F" = Find
                          "M" = Menu
                          "S" = Screen
                          "U" = UDF, CDDLIB function, or other
                                external function.

    Call Function Param - Currently this is only used for "S"-type
    (screen) function ID's.

                          "A" = Start screen in add mode.
                          "E" = Start screen in edit mode.
                          ""  = Start screen in view mode.

                                --- Page 31 ---




    Call Function Extern - Only available for "U"-type function types.
    Calls any external or CDDLIB function.

    NOTE: Use the functions s_add() and s_edit() to trigger add and edit
    modes while in a screen.  Do not call the same screen ID with a Call
    Function Param of "A" or "E" - this will simply reload a new copy of
    the same screen on top of the current screen.

    Cond. for Key Select - Condition to determine whether the action key
    is eligible for selection.   The condition for key select controls
    the "graying out" of items in the key list.  This condition is
    evaluated just before the key list is displayed.

    Condition for Access - Condition to determine whether the key
    function can be executed.

    Post Execution Proc - Process executed after the key function has
    been run, and only if condition for access returned true.

    Post Key Proc - Process executed regardless whether condition for
    access returned true or false.

    Condition to Show - Condition determining whether the key is shown
    in the key list.  The key is still selectable, even though is not
    shown.

    Fade Screen - "Y" to fade screen before key function is executed.
    Usually fade screen is set to "N" when the key function displays
    another menu, browse, or screen.

    Reload After Key - "Y" to reinitialize screen memvars after
    executing the action key function.

    Redisplay After Key? - "Y" to redisplay screen memvars after
    executing the action key function.















                                --- Page 32 ---


    7.3 SCREEN DESIGNER
    -------------------

    
        Help <F1>     Edit <F3>     Vars <F4>     Other <F8>    Win <F10>         
    
       E - Edit help   
       V - Vars help   
       O - Other help  
       K - Keys        
       W - Window help 
      

   ͻ
                       Parent Record                    
   ĺ
     String 1.: MSTRING1                                
     String 2.: MSTRING2                                
     Number...: MNUM                                    
     Logical..: M                                       
     Date.....: MDATE                                   
     Code 1...: M MC1DESC              Single-use table 
     Code 2...: M MC2DESC              Multi-use table  
     Memo.....: T     <Enter> to edit/view memo         
     Link.....: MLIN  System generated link to CHILDA   
   ͼ

    Ovw@11,19   (Ovw - Overwrite, Ins = Insert mode)


    Editing
    -------

    Move area    - Mark and move a screen area by using the arrow
                   keys to sweep out a highlighted area, pressing
                   <Enter> to stop marking, moving the marked
                   block via the arrow keys, and dropping the block
                   into place with the <Enter> key.  The contents
                   of a block cannot be dropped into an area already
                   occupied by a field.

    Copy text    - Mark and move screen text by using the arrow
                   keys to sweep out a highlighted area, pressing
                   <Enter> to stop marking, moving the marked
                   block via the arrow keys, and dropping the block
                   into place with the <Enter> key.  The contents
                   of a block cannot be dropped into an area already
                   occupied by a field.  Fields cannot be copied.

    Erase area   - Mark and erase a screen area by using the arrow
                   keys to sweep out a highlighted area, and pressing

                                --- Page 33 ---


                   <Enter> to erase the marked block.


    Variables
    ---------

    Add field   - From a pick list, add a field at the current cursor
                  location.

    Move field  - Move a field to another location.

    Erase field - Remove a field from the screen.

    Field info  - List information about the field under the cursor.


    Other
    -----

    Draw Single line - Continuous draw of a single line. <Esc> to
                       stop line drawing and return to text mode.

    Draw Double line - Continuous draw of a double line. <Esc> to
                       stop line drawing and return to text mode.


    Window
    ------

    Move window - Move the entire window and its contents to another
                  location. Press <Enter> to drop the window in the new
                  location. <Esc> to abort without changes.

    Size window - Resize the window.  If text or fields are hidden
                  during resizing they will be lost when the new size is
                  saved.  Press <Enter> to save the resized window.
                  <Esc> to abort without changes.


    Keys
    ----
    (#=Shift, ^-Ctrl, @=Alt)

    <Esc>            - Exit screen designer (with prompt to save)
    Arrow keys       - Move the cursor one space in a direction
    <Enter, Return>  - Move to left window side of next line
    <PgUp, PgDn>     - Goto top / bottom of window
    <^Home, ^End>    - Goto right / left of window
    <Home, End>      - Goto upper-left / bottom-right of window
    <^Rt,^Lt Arrows> - Jump left / right to next word or field
    <Tab, #Tab>      - Move 5 spaces left / right

                                --- Page 34 ---


    <Ins>            - Toggle between Insert and Overwrite
    <Del>            - Delete character under cursor
    <Bs>             - Delete character to the left of cursor
    <F1>             - Main menu
    <F3, @E>         - Edit submenu
    <F4, @V>         - Vars submenu
    <F8, @V>         - Other submenu
    <F10, @W>        - Window submenu
    Graphics         - High-ASCII entered via <Alt>+numeric keypad











































                                --- Page 35 ---


    8.0 FIND DEFINITIONS
    --------------------

    A find definition is a find routine that is associated with a
    specific data file and index.  For every user selectable index order
    in a browse or a screen, there should be a corresponding find item
    definition.

Ŀ
                             Find Definition                        V_FID (O) 
Ĵ
    Find function ID.......:    PARENT                                        
    Data alias.............:   *PARENT                                        
                                                                              
    Find Item Definitions..: [Browse]                                      
                                                                              
                                                                              
                                                                              


    Find Functions ID - Unique screen identifier.

    Data alias - The alias of the data file for the find definition.

    Find Item Definitions - Go to the individual find items.


    8.1 DEFINING FIND ITEMS
    -----------------------

    A find item is a memory variable into which the user inputs a value
    and then seeks for the value in the data file using the designated
    index.  If the seek returns true, the record pointer is moved to the
    new location. If the seek fails, the record pointer is restored to
    its original location.

Ŀ
                     Find Item Definition for PARENT                V_FID (O) 
Ĵ
 DBF alias..............:   *PARENT                                           
 Index alias............:*PARENT1 upper(string1)                           
 Get title..............:    String 1                                         
  "  type/length/dec....:    C       10     0                                 
  "  picture............:    @!                                               
  "  init. expression...:                                                     
  "  cond. for valid....:                                                     
  "  cleanup expression.:    ltrim(v_findget)                                 
  Append expression.....:                                                     
  Set confirm ON?.......:    N                                                
  Softseek ON?..........:    N                                                
                                                                              

                                --- Page 36 ---


                                                                              
                                                                              
  Help memo.............:    Memo                                             
                                                                              
    NOTE: Cleanup expression can manipulate input using var "v_findget"       
          Append expression adds value to front of user input                 
                                                                              


    Data alias - The alias of the data file for the find definition.

    Index alias - The index alias for this find

    Get title - The prompt that appears at the bottom of the screen.

    Type/length/dec - The find memvar descriptors.  The actual find variable
    that is created is named "v_findget".  V_findget may be altered during
    the condition for validation.

    Picture - The picture used for the get of v_findget.

    Init. expression - The initialization expression for v_findget.

    Cond. for valid - The validation expression for v_findget.

    Cleanup expression - The cleanup (post valid) expression for v_findget.

    Append expression - The value returned by this expression is added
    to the beginning of the current v_findget value.  Generally if the
    find is to be called during a filtered browse or screen, the append
    expression is the same as the index filter expression for the browse
    or screen.

    Set confirm ON? - Environment setting for the get.

    Softseek ON? - Environment setting for the seek.
















                                --- Page 37 ---


    9.0 SEQUENCE DEFINITIONS
    ------------------------

Ŀ
                            Sequence Definition                     V_SEQ (X) 
Ĵ
   Sequence ID..........: INIT                                             
   Sequence Description.:    Initialization. Get USERID from DOS              
   Sequence Listing.....:    Memo                                             
                                                                              
                                                                              
                                                                              
   Note: A sequence is a list of functions or expressions to evaluate         
         in a sequential manner.  The return value of each expression         
         is ignored by the sequencer itself; however, a primitive             
         method of branching is possible by setting and checking              
         variables within the sequence.  A sequence is called via             
         v_sequence() and the private variable SEQ is the return              
         value.  SEQ may be changed inside the sequence.  Another             
         private variable inside v_sequence() STOP_SEQ will, if set           
         false, terminate the sequencer after the current line.               
         The sequencer is not a substitute for real compiled source           
         code.  The sequencer's best use is for setup and cleanup             
         processes and NOT for complex code modules.                          
                                                                              


    Example of a Sequence:

    * program initialization
    * create global variables, get user ID, etc.

    * get the userid from DOS
    v_make_pub("p_userid",upper(getenv("userid")))

    * if no userid - give error message, else login
    if(empty(p_userid),v_alert('USERID is not set'),.t.)

    * set v_sequence() return value
    v_assign("seq",!empty(p_userid))

    * End of sequence

    A sequence definition is a list of functions that are executed
    sequentially.  Sequences are run via the v_sequence() function.
    Sequences are typically simple "one time" initialization routines.
    Because of their relatively slow execution speed, a sequence should
    not be called from within a loop structure.  Some primitive program
    branching is possible within a sequence; however, looping within the
    sequence is not available.


                                --- Page 38 ---


    Comment lines in a sequence begin with an asterisk "*".

    CDDLIB functions commonly used within sequences are:

    v_make_pub() - create a public variable.
    v_rel_pub() - release a public variable.
    v_assign() - assign a value to a variable.
    if(myvar, myfunc(), .t.) - Inline IF function

    The private variable SEQ is created at the beginning of each new
    sequence.  The return value from v_sequence() is the value of SEQ
    when the sequence is completed.

    Another private variable STOP_SEQ, if set to true, terminates the
    sequence after the current line is executed.





































                                --- Page 39 ---


    10.0 DBF, FIELD, NTX DEFINITIONS
    --------------------------------

Ŀ
                           Data File Information                    V_DBF (D) 
Ĵ
   Alias................: PARENT                                           
   Filename.............:    PARENT                                           
   Description..........:    Parent DBF                                       
   Alternate Path.......:                                                     
   Open at startup?.....:    Y                                                
   Show in V_REINDEX()?.:    Y                                                
                                                                              
   Fields...............:    [Browse]                                         
   Indexes..............:    [Browse]                                         
                                                                              
   Create DBF now?......:    Process                                          
   Index now?...........:    Process                                          


    Alias - The data file alias.  The alias can differ from the actual
    filename.  In most cases, the alias and the filename will be
    identical.  Data file aliases must not conflict with user defined
    memory variables or index aliases.

    Filename - The name of the data file.  This filename must be a legal
    DOS filename with no extension.

    Description - For reporting purposes only, not used by CDDLIB.

    Alternate Path - This is used to override the default data file
    path. The alternate path MUST end with ":" or "/".

    Show in v_reindex()? - "Y" to include this file in the reindexing
    pick list.  Temporary files or files that belong to another program
    are often excluded.

    Fields - Browse of the fields associated with this data file.

    Indexes - Browse of the indexes associated with this data file.

    Create DBF Now? - Option to create the data file.

    Index Now? - Option to create indexes for this data file.








                                --- Page 40 ---


    10.1 DEFINING FIELDS
    --------------------

Ŀ
                        Field Information for PARENT.DBF            V_FLD (F) 
Ĵ
Pos.........:  10                                                          
   Fieldname...: STRING1                                                      
   Type........: C                                                            
   Length......:    10                                                        
   Decimals....:  0                                                           
   Description.: String type field                                            
                                                                              
                                                                              


    Position - The numeric position by which the fields will be ordered
    in the actual data file.  Numbering by tens will facilitate insertion
    of new fields at a later time.

    Fieldname - The name of the field.  The name must be a legal Clipper
    fieldname.

    Type - The field type.  C = character, N = Numeric, D = Date,
    L = Logical, and M = Memo.

    Length - The field length.

    Decimals - The decimals for a numeric field type.

    Description - For reporting purposes only.





















                                --- Page 41 ---


    10.2 DEFINING INDEX FILES
    -------------------------

Ŀ
                        Index Information for PARENT.DBF            V_IDX (I) 
Ĵ
Index Alias....: PARENT1                                                   
   Index Name.....: PARENT1                                                   
   Key Expression.: upper(string1)                                            
   Unique Index?..: N                                                         
   Description....:                                                           
   Alternate Path.:                                                           
                                                                              
                                                                              
                                                                              
   WARNING: When the index is opened, the index "alias" is created as a       
            PUBLIC variable containing the numeric index order.  You          
            must insure that this index alias does NOT conflict with          
            another dbf alias, index alias, or memory variable.               



    Index Alias - The index file alias.  The index alias is a PUBLIC
    variable containing the numeric index order created when the index
    is opened.  You must insure that this index alias variable does NOT
    conflict with another DBF alias, index alias, or memory variable.
    Generally the index alias and the index filename are identically
    named with sequential numbering of the last character. For example:

                        Index Alias    Index Name
                        -----------    -----------
                        COMPANY1       COMPANY1
                        COMPANY2       COMPANY2
                           .              .
                           .              .
                        COMPANYF       COMPANYF

    NOTE: V_vieword() and v_order() use index aliases.

    Key Expression - The index key expression.  Please note that if your
    index key contains a user-defined function, the function will not
    exist in CDD.EXE.  Indexing via v_reindex() from within your
    application will index correctly (assuming that all of the index
    functions are linked).

    Unique Index? - Index unique switch.

    Description - A description for reporting/viewing only.

    Alternate Path - Optional alternate path for index.  Must end in ":"
    or "\".

                                --- Page 42 ---


    11.0 UTILITIES
    --------------

    1. Reindex CDD data dictionary - Reindex/pack all of the current
       data dictionary files.

    2. Reindex Application Files - Via a tagable pick list, select
       the application data file to reindex/pack.

    3. Clone Definitions - Utility to clone an entire browse screen,
       find, menu, or sequence definition.

    4. Import Definition - Utility to import CDD functions from an
       external CDD data dictionary.  This utility is often used to
       merge the work from several programmers into one central data
       dictionary.

       WARNING - If the function imported has the same ID as an existing
       function, the existing function will be first deleted entirely
       and replaced with the imported function.

    5. Import Dbf/Fld/Ntx Defs. - Utility to import CDD data file, field
       and index definitions from an external CDD data dictionary.
       Any existing definition is deleted first and replaced entirely.

    6. String Search - Utility to search for strings in every character
       field in the current data dictionary.  Often used when making
       global changes to the data dictionary or to locate and eliminate
       "dead code".























                                --- Page 43 ---


    12.0 TIPS AND TRAPS
    -------------------

    File handles -  The CDD runtime data dictionary requires 36 file
    handles to operate.  Make sure that your CONFIG.SYS and network
    configuration file (SHELL.CFG) sets about 65 or greater file
    handles.  Either burn-in the max file handles into your EXE (via
    your linker) or SET CLIPPER=F65 or greater.

    A "Condition for key select" in a browse or screen determines
    whether a key can be selected.  The "Condition for access"
    determines whether the item, once selected, will be executed. This
    is a subtle but VERY important difference.

    If a "condition for ..." field is left blank, it defaults to true.

    For any "Post Proc" or "Post Process" or "... Proc" field, the
    function return value is ignored.

    If you are running under Windows with one window for CDD.EXE and the
    other window for the application - exit and restart your application
    every time a change is made to the data dictionary.  By restarting
    the app, the field and index buffers will be refreshed.  Loading DOS
    SHARE will also insure that file sharing is properly managed.

    A few screen tips:

       Mark non-editable fields on the screen as WHEN =.f.

       Mark non-visible fields as WHEN = .f. (These are often calculated
       fields)

       All defined screen memvars are loaded into get objects.


    For menu and key list box titles - since the titles are trimmed, you
    can force whitespace on either side of the title by using the tilde
    "~" character. E.g. "~ Main Menu ~" displays as " Main Menu ".

    For table maintenance relational integrity routines, wait until the
    application is nearly finished because:  1. All files that are going
    to use a table lookup field will be identified.  2. The full
    complement of indexes for viewing and reports will have been
    designated, therefore any remaining slots can be used for indexed
    sweep routines.

    Be consistent in naming dbf fields and screen memvars across data
    files and screens.  Consistency increases your development speed
    because files, browses, screens, and lookups are more easily cloned
    and reused.


                                --- Page 44 ---


    Do not use S_REFRESHALL() in the initialization expression for a
    screen field.  Some of the screen fields may be uninitialized at the
    time S_REFRESHALL() is called.

    CDD.EXE uses the data dictionary files exclusively.  This is the
    result of a hard lesson learned by a team of our programmers.  When
    multiple programmers are working on a single project - make copies
    of the data dictionary, work on them in separate locations, and then
    merge the changes into a master data dictionary.

    Do not use user-defined functions in an index key.  CDD.EXE will not
    have your external UDFs linked and will bomb whenever that
    particular index is created.  Be creative.

    In condition and process fields, do not incorrectly nest quotes when
    constructing your expressions - a macro syntax error will result.
    In the event nested quotes are needed, use different quote symbols
    ", ', and [.

    In the dbf alias and filename fields, any files beginning with "V_"
    are prohibited.  "V_" may conflict with the data dictionary aliases
    used by CDDLIB.LIB

    Pseudo-functions created via TRANSLATE and COMMAND directives in
    header files CANNOT be directly called from the data dictionary
    because they don't really exist as compiled code.

    CDDLIB requires SET DELETED ON during loading of the menus, browses,
    screens, find, and sequences.  If you must change SET DELETED
    status, change it back before executing any data dictionary or
    CDDLIB functions.  The programmer is responsible for saving and
    restoring the SET DELETED state when necessary.

    If you want for help to be active for browses and screens, then
    v_help() must be defined as one of the action keys.

    For browses used as lookup tables (via v_look1()) the initial GOTOP
    should be "N" because the lookup function pre-positions the record
    pointer.

    To override a standard navigation key (in this example the UpArrow)
    call the appropriate TBrowse method via the object variable "v_bro":

          Key list position.....:   90
          Char. or "K"+Inkey....:     K5
          Description...........:     UpArrow

          Call Function ID......:
           "       "    Type....:     U
           "       "    Param...:
           "       "    Extern..:     v_bro:up()

                                --- Page 45 ---



          Cond. for key select..:
          Condition for access..:
          Post execution proc...:
          Post key proc.........:
          Condition to show.....:     .f.
          Fade browse?..........:     N
          RefreshAll after key?.:     Y
          RefreshCurrent after?.:     N

       NOTE: As typical with all navigation keys, the condition to show
             is normally set to false so that the key is not visible
             from the keylist, although it may be selected.

    In a screen to initialize and save a non-editable dbf field - define
    the field as a screen memvar just like any editable field.

    If you wish to display only the first part of a memo or character
    field as a browse column, your expression MUST return a fixed length
    string. E.g. "padr( memofld, 30)" not "left( memofld, 30)".
































                                --- Page 46 ---


    A-1 CDDLIB INTERNAL VARIABLES
    -----------------------------

    THE DATA DICTIONARY FILES:
    --------------------------

    The CDD data dictionary files are named using the system name plus a
    one character suffix.  The contents of these files are:

    S-file - System defaults and configuration
    D-file - Data files, aliases information
    F-file - Fields (structure)
    I-file - Indexes, index aliases, index keys
    B-file - Browses
    C-file - Browse columns
    K-file - Browse action keys
    M-file - Menus
    N-file - Menu items
    O-file - Finds
    P-file - Find items
    T-file - Screens and screen layouts
    U-file - Screen action keys
    V-file - Screen fields (gets)
    X-file - Sequences


    SYSTEM-WIDE (PUBLIC) VARIABLES AVAILABLE TO THE PROGRAMMER:
    -----------------------------------------------------------
    V_EXITFLAG  - Flag to signal a menu, browse, or screen to terminate,
                  boolean.

    V_SHADOW    - Flag to indicate that shadows are to be painted, color
                  only, boolean.

    V_STACK_    - Internal CDD call stack array, used by error handler
                  and help system, array of strings.

    V_SYSNAME   - Name of the CDD system files, char.

    V_DDPATH    - Location of CDD data dictionary files and indexes,
                  char.

    V_DATAPATH  - Location of application data files, char.

    V_IDXPATH   - Location of application index files, char.

    V_HEADER0   - Backdrop header line 1, char.

    V_HEADER1   - Backdrop header line 2, char.

    V_BACKCHAR  - Backdrop fill character, char.

                                --- Page 47 ---



    V_BROBOX    - Default browse box type, char.

    V_BROSEPC   - Default browse column separator, char.

    V_BROSEPH   - Default browse data/header separator, char.

    V_MENBOX    - Default menu box type, char.

    V_SCRBOX    - Default screen box type, char.

    V_LSTBOX    - Default list box type, char.

    V_LSTTITLE  - Default list box title, char.

    V_VIDCODE   - Video mode "A"=Autodetection, "C"=Color, "M"=Mono,
                  char.

    V_SYSCOLOR  - Default backdrop color string, char.

    V_TITCOLOR  - Default header title color string, char.

    V_STATCOLOR - Default status line color pair, char.

    V_BROCOLOR  - Default browse color string, char.

    V_BROFADE   - Default browse fade color pair, char.

    V_HLPCOLOR  - Default help color string, char.

    V_MENCOLOR  - Default menu color string, char.

    V_MENFADE   - Default menu fade color pair, char.

    V_FINDCOLOR - Default find color string, char.

    V_SCRCOLOR  - Default screen color string, char.

    V_SCRFADE   - Default screen fade color pair, char.

    V_MSGCOLOR  - Default message/V_ALERT() color string, char.

    V_LSTCOLOR  - Default key list color string, char.

    V_SOUND_M   - Flag to toggle menu sounds

    V_SOUND_B   - Flag to toggle browse sounds

    V_SOUND_S   - Flag to toggle screen sounds

    V_SOUND_Z   - Flag to toggle system warning sounds

                                --- Page 48 ---



    V_LOCK_ED   - Flag to lock when editing (false=lock on replace)

    V_INFOKEY   - Hotkey to call V_INFO() information function

    V_INFO      - True if v_infokey <> 0


    BROWSE PRIVATE VARIABLES AVAILABLE TO THE PROGRAMMER:
    -----------------------------------------------------

    Use the cond. for access to modify any of these variables.

    V_BRO       - TBrowse object

    V_BROTITLE  - Browse title variable, may be changed by Cond. for
                  Access function for multi-use browses.

    V_BROFILTER - Filter expression variable

    V_BROTOP    - Window coordinate top

    V_BROLEFT   -    "       "      left

    V_BROBOT    -    "       "      bottom

    V_BRORT     -    "       "      right


    SCREEN PRIVATE VARIABLES AVAILABLE TO THE PROGRAMMER:
    -----------------------------------------------------

    Use the cond. for access to modify any of these variables.

    FLDS_       -  Array containing screen field information, position,
                   validation, etc.  See CDD.CH and CDDLIB.PRG.

    S_MODE      - Current screen mode "V"=View mode, "A"=Add mode,
                  "E"=Edit mode.

    S_BINDEX    - Code block of current index expression.

    S_FILTER_EXP- Filter expression (macroed to create s_limit).

    S_LIMIT     - Filter limit string or value (not a condition),
                  derived from macro of filter expression at screen
                  startup.

    S_SCREEN    - Screen help text memo.

    S_TOP       - Screen coordinates.

                                --- Page 49 ---



    S_LEFT      -    "        "

    S_BOT       -    "        "

    S_RT        -    "        "

    S_SCRBOX    - Screen box string.

    S_CONFIRM   - Set CONFIRM ON/OFF flag.


    MENU PRIVATE VARIABLES AVAILABLE TO THE PROGRAMMER:
    ---------------------------------------------------

    V_CHOICE    -  Allows initial positioning of menu item at start via
                   the menu cond. for access or during runtime.



































                                --- Page 50 ---


    A-2 CDD ERROR HANDLER
    ---------------------

    Function : V_E_ALT()

    Purpose  : Error handler for CDD functions.  Error messages
               are displayed and written to the ERROR.TXT text file.
               The DOS SET USERID=???? command will optionally provide
               user identification.

    Syntax   : V_E_ALT(<objErr>) --> recover value

    Arguments: <objErr> - The current error object

    Returns  : A recovery value.  The data type for the recovery is
               dependent upon the type of error.  V_E_ALT() will
               terminate the program if no recovery is possible.
               "Printer not ready" errors are treated as non-recoverable
               - they should be handled in the printing code.

    Author   : Vick Perry,   Tue  04-23-1991

    Notes    : V_E_ALT() handles all standard Clipper and DOS errors.
               V_E_ALT() can replace the standard ERRORSYS error handler
               built into Clipper 5.  To substitute V_E_ALT() for ERRORSYS,
               link the following code into your application:

                  Procedure Errorsys
                     Errorblock( {|e| V_E_ALT(e)} )
                  Return

               If you modify v_e_alt() insure that any system-wide
               variables that you use are defined early in v_init(), so
               that if the failure occurs within v_init() (i.e.
               insufficient file handles when opening the DD), no
               recursive errors will occur. Use the type() function (not
               valtype()) to detect whether a CDD system exists before
               using it.














                                --- Page 51 ---


    A-3 RECOMPILING CDDLIB SOURCE
    -----------------------------

    The standard edition of CDD contains the source code for the CDD
    supporting functions in CDDFUNCS.PRG.  The professional edition also
    contains the source for CDDCORE.PRG and VATTR.ASM, a tiny assembler
    routine.

    CDDLIB.LIB consists of four modules:

       CDDCORE.OBJ   - CDD master functions v_menu(), v_browse(), and
                       v_screen()
       CDDFUNCS.OBJ  - CDD supporting functions
       CDDERR.OBJ    - CDD alternate error handler
       VATTR.OBJ     - Screen shadow assembler routine

    To recompile CDDCORE.PRG or CDDFUNCS.PRG use the CLIPPER command
    without any parameters.  E.g. CLIPPER CDDFUNCS

    To recompile VATTR.ASM, use Microsoft's MASM.EXE.
    E.g. MASM VATTR,,,,

    To update a CDD module in CDDLIB.LIB, use Microsoft's LIB.EXE
    library utility.  E.g. LIB CDDLIB -+CDDFUNCS ,, CDDLIB




























                                --- Page 52 ---


    A-4 WARRANTY / LICENSING
    ------------------------

    Warranty:

       UNDER NO CIRCUMSTANCES SHALL PHOENIX SYSTEMS BE LIABLE TO YOU FOR
       ANY DAMAGES, CLAIMS, OR LOSSES WHATSOEVER, INCLUDING BUT NOT
       LIMITED TO ANY CLAIMS FOR LOST PROFITS, LOST SAVINGS, OR OTHER
       SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
       USE OR INABILITY TO USE THE PROGRAM REGARDLESS OF THE
       CIRCUMSTANCES.


    License:

       There is no licensing for the CDD 1.03 Demonstration Edition. The
       CDD 1.03 Demonstration Edition may not be used for commercial
       purposes.

       For purchasers of the CDD 1.03 Standard or Professional Editions,
       the license agreement permits you to use one copy of the CDD
       software and associated files on a single computer.  The CDD
       software is in "use" on a computer when it is loaded into
       temporary memory (i.e. RAM) or installed into permanent memory
       (e.g. hard disk, CD-ROM, or other storage device) of that
       computer.  However, installation on a network server for the sole
       purpose of internal distribution shall not constitute "use" for
       which a separate license is required, provided you have a
       separate license for each computer to which the CDD software is
       distributed.


    Distribution:

       The CDD 1.03 Demonstration Edition may be freely distributed in
       its original form.

       The programs, source code, documentation, and associated files
       contained in the CDD 1.03 Standard or Professional Editions may
       not be distributed without the written authorization of Phoenix
       Systems.  Modified versions of CDDLIB.LIB, CDDLIB.LIB source
       code, or other associated files may not be distributed without
       the written authorization of Phoenix Systems.

       You have a royalty-free right to reproduce and distribute
       executable files created using the CDD 1.03 Standard or
       Professional Editions.


    Copyright:


                                --- Page 53 ---


       The CDD.EXE software program, CDDLIB.LIB, CDDCORE.PRG,
       CDDFUNCS.PRG, and associated files and programs are copyrighted
       by Phoenix Systems and is protected by United States copyright
       laws and international treaty provisions.
















































                                --- Page 54 ---


    A-5 TRADEMARKS REFERENCED
    -------------------------

    Trademarks:

       CA-Clipper -  Computer Associates International, Inc.
       Funcky     -  dLESKO Associates
       FlexFile   -  Ganahl Software
       Novell     -  Novell, Inc.
       Zachary    -  Zachary Software, Inc.
       Blinker    -  Blink, Inc.
       Microsoft  -  Microsoft Corporation

    The CDD.EXE program is written in Clipper 5.01a using the Zachary
    application generator.  Zachary is a good development tool and was
    available at the time when I needed it (pre-CDD, or course). The
    main difference between Zachary and CDD is that Zachary is a source
    code generator and CDD is a runtime data dictionary engine.


































                                --- Page 55 ---


    A-6 THANKS
    ----------

    I wish to offer my thanks to Peter Savery, Caesar Samsi, Rob Heyman,
    and Mark McWilliams for their ideas, support, testing, and patience
    during the evolution of CDD.  Of course, thanks also to Phoenix
    Systems for helping to make CDD possible.

    Rev. 3/4/93
