dc_csv2array()

Export an array to a comma-delimted CSV file

Syntax:

   DC_Csv2Array( < cCsvFileName > ) - > aArray
   

Arguments:

   < cCsvFileName > is the name of the file to import.
   

Returns:

   A 2-dimensional array.
   

Description:

   DC_Csv2Array() imports a comma-delimited CSV file into a
   2-dimensional array.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_array2csv()

OVERVIEW_DUAL_FUNC

Dual-Mode Functions

Description:

    DUAL-Mode functions have been designed to work in either
    TEXT mode or GUI mode.  Text mode is selected by calling
    DC_GUI(.f.) and GUI mode is selected by calling DC_GUI(.t.).
   
    Functions in the DCLIPX.DLL dynamic-link library all start
    with the prefix DC_.  The DCLIPX.DLL file is one of the
    libraries that are included with the dCLIP++ Application
    Development System, and your eXPress++ system is fully
    compatible with dCLIP++ in the event that at some time you
    wish to upgrade and utilize the dCLIP++ design tools.
   

OVERVIEW_GENERAL

General Functions

Description:

    General functions are those which have been designed to work
    identically in either TEXT mode or GUI mode.  These functions
    do not create any output to the screen in either mode,
    therefore they can be used freely without regard to the
    screen mode, DC_GUI().
   
    Functions in the DCLIPX.DLL dynamic-link library all start
    with the prefix DC_.  The DCLIPX.DLL file is one of the
    libraries that are included with the dCLIP++ Application
    Development System, and your eXPress++ system is fully
    compatible with dCLIP++ in the event that at some time you
    wish to upgrade and utilize the dCLIP++ design tools.
   

OVERVIEW_GUI_FUNC

GUI Functions/Classes

Description:

    GUI functions are designed to work only in GUI mode.  When any of
    these functions are used they ignore the setting of the DC_Gui()
    flag.
   

OVERVIEW_TEXT_FUNC

Text Mode Functions/Classes

Description:

    Text-Mode functions are designed to work only in TEXT mode.
    When any of these functions are used they ignore the setting of
    the DC_Gui() flag and require that the SetAppWindow() be a CRT
    window (XbpCrt Class).
   

dc_dbrecord()

Create a Database Record Object

Syntax:

   DC_DbRecord():new() - > < oRecord >
   

Arguments:

   None.
   

Returns:

   A record object created from the currently used database.
   

Description:

   DC_DbRecord() is a class that is used to create a data object
   for storing a database record.
   
   The record object is created from a dynamic class which will have
   the name DATA_<þaliasþ>.
   
   Each field name in <þaliasþ> will be added to the object as an
   iVar.
   
   Two additional iVars are created:
   
   RECORD_NUMBER - A numeric container for the current record number that
    is set when DC_DbScatter() is used.
   
   RECORD_DELETED - A logical container for the Deleted() flag is
    set when DC_DbScatter() is used.
   

Examples:

   FUNCTION XTest()
   
   LOCAL oRecord
   
   USE COLLECT
   
   oRecord := COLLECT->(DC_DbRecord():new())
   COLLECT->(DC_DbScatter(oRecord))
   
   @ 1,1 DCSAY 'Description' GET oRecord:descript
   @ 2,1 DCSAY 'Type' GET oRecord:type
   @ 3,1 DCSAY 'Sub-Type' GET oRecord:subtype
   
   DCREAD GUI
   
   COLLECT->(DC_DbGather(oRecord))
   
   RETURN nil
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbscatter()
   dc_dbgather()
   dc_dbrecordcompare()
   dc_dbrecordcopy()

dc_abigelem()

Return element of longest string in an array

Syntax:

    DC_ABigElem ( < aArray >, ;
                  [@< nLength >] ) - > nElement
   

Arguments:

   < aArray > is the name of any single-dimensional array that is
   fill with character strings.
   
   @< nLength > is the name of a variable to place the length
   of the item returned.
   

Returns:

    A number equivalent to the element of the array with the
    longest string.
   

Description:

    DC_ABIGELEM() will return the element number of the longest
    string in a single-dimensional array.
   

Examples:

    . nLength := 0
    . aTest := { 'abc','abcdef','abcde','abcd' }
    . ? DC_ABIGELEM( aTest, @nLength )
    2
    . ? nLength
    6
   

Source/Library:

  _DCARRAY.PRG, DCLIP1.DLL

dc_achoice()

A Dual-Mode replacement for ACHOICE()

Syntax:

   DC_AChoice ( < nTop >, < nLeft >, < nBottom >,
   < nRight >, ;
                < aMenuItems >, ;
                [< aSelItems >], ;
                [< cUserFunc > | < bUserFunc >], ;
                [< nInitialItem >], ;
                [< nWindowRow >], ;
                [< aButtons >], ;
                [< aOptions >], ;
                [< aHelpCodes >], ;
                [< aMenu >], ;
                [< lAttachMenu >] ) - > nPosition
   

Arguments:

   < nTop >, < nLeft >, < nBottom >, < nRight >
   are the screen
   coordinates.
   
   < aMenuItems > is an array of character strings to include
   in the pick-list.
   
   < aSelItems > is an array of logical values.  There is one
   element in this optional array for each element in
   < aMenuItems >.  Each element in < aSelItems > that is a
   .TRUE. will make the item in the window a "selectable"
   item, otherwise it will be a non-selectable item and will
   be displayed in "grayed" form.
   
   < cUserFunc > | < bUserFunc > is the name of an optional
   User-Defined
   function to call on exception keystrokes.  See the Clipper
   documentation of ACHOICE() for more information on how to use
   a UDF.  If the parameter is passed as a character string then
   the function must be a PUBLIC, not STATIC function.
   
   < nInitialItem > is the item to high-light in the window on
   startup.
   
   < nWindowRow > is the item to display as the first item in
   the pick-list.
   
   < aButtons > is an array of mouse-keys that conforms to the
   specification for DC_MOUSEKEY().   See DC_MOUSEKEY() for
   more information.
   
   < aOptions > is a multi-dimensional array of the following
   options:
   
   Element  Type   Description
   -------  ----   ----------------------------------------------
     [1]     L     If .TRUE. will display a scrollbar and box
                   around the menu items.
     [2]     A     A sub-array of colors to use if element [1] is
                   .FALSE.  If passed as a NIL then the Clipper
                   default colors will be used.
   
                   Element  Type  Description
                  -------  ----  ----------------------------
                    [1]       C   Menu items color
                    [2]       C   Select bar color
                    [3]       C   Frame/scrollbar color
                    [4]       C   Spare
                    [5]       C   Unselectable items color
   
     [3]     C     Title on top of box.  Default is none.
     [4]     L     If .TRUE. then the operator will be allowed to
                   drag the box with the mouse. Default is .FALSE.
     [5]     L     If .TRUE. then the display will be restored
                   upon exit, otherwise it will remain.
     [6]     L     If .TRUE. then the frame, scroll-bar and title
                   will be painted, otherwise only the items will
                   be painted.
     [7]     L     If .TRUE. then after painting the scroll-bar,
                   items and frame, DC_ACHOICE() will exit without
                   waiting for a key or mouse-click.
   
   < aHelpCodes > is an array of character string HELP CODES.
   There is one element in this optional array for each element in
   < aMenuItems >.  The HELP CODE will be passed on to the
   DC_HelpF1() function for context-specific help if the operator
   presses F1 on a selected item.
   
   < aMenu > is an array defining a Top-Bar/Pull-Down menu. This
   array must conform to the specification for the array passed
   to the DC_MENUMAIN() function.   This Top-Bar menu will be
   painted at the screen coordinates defined in the menu if
   < lAttachMenu > is .FALSE. or directly attached to the top of
   the pick-list window if < lAttachMenu > is .FALSE. (default).
   The menu will be energized if the operator presses a key
   matching one of the hightlighted characters in the menu, or
   if the mouse is clicked on one of the top-bar menu items.
   The menu array must contain code-blocks for each menu item
   to execute functions based on the menu selection.  See
   DC_MENUMAIN() for more information.
   

Description:

    DC_ACHOICE() is a Dual-mode replacement for AChoice().  When
    the GUI flag is ON, DC_ACHOICE() functions similiar to
    AChoice() except that it is displayed in GUI mode.  When the
    GUI flag is OFF, DC_ACHOICE() functions identical to ACHOICE()
    except it is also activated by a mouse.  The left button of the
    mouse is used to select the item in the window.  The right button
    or double-clicking works  identical to the ENTER key.
   
    In TEXT mode, Hot keys can be activated by passing an array of
    screen coordinates (mouse-buttons) and key definitions.
   
    In TEXT mode, an options array is used to define scroll-bars,
    colors, exit options, title, drag options, etc.
   
    An optional array of Help-Codes may be passed for context-
    specific help on any selected item with the F1 key.
   

Examples:

    local nChoice
    local aButtons := { { 17,13,17,18,'C'},;
                        { 18,13,18,18,'D'},;
                        { 19,13,19,18,'M'} }
    local aDir := directory()
    set key asc('C') to myfunc
    set key asc('D') to myfunc
    set key asc('M') to myfunc
    cls
    @5,10 to 20,30
    @16,11 to 16,29
    @17,13 say 'Copy'
    @18,13 say 'Delete'
    @19,13 say 'Move'
    aDir := dc_aconvert( aDir )
    nChoice := DC_ACHOICE( 6,11,15,29,aDir[1],,,,,aButtons )
    set key asc('C') to
    set key asc('D') to
    set key asc('M') to
    return
   
    function myfunc
   
    @ 22,10 say ''
    do case
      case lastkey() = asc('C')
        ?? 'C button pressed'
      case lastkey() = asc('D')
        ?? 'D button pressed'
      case lastkey() = asc('M')
        ?? 'M button pressed'
    endcase
    return nil
   

Source/Library:

  _DCACHOI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dbchoice()
   dc_readapick()
   dc_apick()

dc_acompare()

Compare two arrays

Syntax:

   DC_ACompare ( < aArray1 >, ;
                 < aArray2 > ) - > lStatus
   

Arguments:

   < aArray1 > and < aArray2 > are the arrays to compare.
   

Returns:

    A logical .TRUE. if the arrays are identical, .FALSE. otherwise.
   

Description:

    DC_ACOMPARE() is used to test the contents of two arrays to
    determine if they are identical.
   

Examples:

     PROCEDURE Xtest()
   
     LOCAL aArray1, aArray2, aArray3
   
     aArray1 := { 1,2,3 }
     aArray2 := { '1',2,3, }
     aArray3 := { 1,2,3 }
   
     DC_Gui(.t.)
   
     DC_MsgBox( { 'Is aArray1 equal to aArray2?', ;
                  '',;
                  DC_ACOMPARE(aArray1,aArray2) } )
   
     DC_MsgBox( { 'Is aArray1 equal to aArray3?', ;
                  '',;
                  DC_ACOMPARE(aArray1,aArray3) } )
   
   
     RETURN
   

Source/Library:

  _DCARRAY.PRG/.OBJ, DCLIPX.LIB

dc_aconvert()

Convert a Ragged array to a Parallel array and vice-versa

Syntax:

   DC_AConvert ( < aInput > ) - > aOutput
   

Arguments:

   < aInput > is a Parallel Symmetrical array or Ragged Symmetrical
   array.
   
   Example of a "Parallel Symmetrical array":
   
                     Type  Contents
   
        aStru[1]       A
          aStru[1,1]   C   CUST_NAME
          aStru[1,2]   C   SHIP_DATE
          aStru[1,3]   C   BALANCE
          aStru[1,4]   C   PRINT_FLAG
        aStru[2]       A
          aStru[2,1]   C   C
          aStru[2,2]   C   D
          aStru[2,3]   C   N
          aStru[2,4]   C   L
        aStru[3]       A
          aStru[3,1]   C   25
          aStru[3,2]   C   8
          aStru[3,3]   C   9
          aStru[3,4]   C   1
        aStru[4]       A
          aStru[4,1]   N   0
          aStru[4,2]   N   0
          aStru[4,3]   N   2
          aStru[4,4]   N   0
   
   
    Example of a "Ragged Symmetrical array":
   
                              Type  Contents
   
        aStru[1]       A
          aStru[1,1]   C   CUST_NAME
          aStru[1,2]   C   C
          aStru[1,3]   C   25
          aStru[1,4]   N   0
        aStru[2]       A
          aStru[2,1]   C   SHIP_DATE
          aStru[2,2]   C   D
          aStru[2,3]   C   8
          aStru[2,4]   N   0
        aStru[3]       A
          aStru[3,1]   C   BALANCE
          aStru[3,2]   C   N
          aStru[3,3]   C   9
          aStru[3,4]   N   2
        aStru[4]       A
          aStru[4,1]   C   PRINT_FLAG
          aStru[4,2]   C   L
          aStru[4,3]   C   1
          aStru[4, ]   N   0
   

Returns:

    An array whose elements contain the same information as the
    input array but are in "inverted" order.
   

Description:

    DC_ACONVERT() is used to changed the format of a symmetrical
    array from "Ragged" to "Parallel" or vice-versa.  This function
    is handy when information in an array may not be stored in a
    required format. For example, it is not easy to perform
    "pick-list" operations from "Ragged" arrays or to AEVAL()
    "Parallel" arrays.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aRaggedDir, aParallelDir, nChoice
   
    // Converting a Ragged array to a Parallel array
   
    aRaggedDir := Directory()
    aParallelDir := DC_ACONVERT( aRaggedDir )
   
    DC_Gui(.t.)
   
    nChoice := DC_Achoice( 10,10,20,40, aParallelDir[1] )
   
    DC_MsgBox( 'The size of ' + aParallelDir[1,nChoice] + ' is ' + ;
                Str( aParallelDir[2,nChoice] ) )
   
    RETURN
   

Source/Library:

  _DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_areverse()

dc_addbuttonconfig()

Configure buttons added to dialogs by DCREAD GUI

Syntax:

   DC_AddButtonConfig( < nButton > | < aConfig >, ;
                       [< xCaption >], ;
                       [< nWidth >], ;
                       [< nHeight >], ;
                       [< oBitmap >], ;
                       [< cFont >] ) - > aConfig
   

Arguments:

   < nButton > is the button to configure.  This is a manifest constant
   from the DCGUI_BUTTON_* definitions in DCDIALOG.CH.
   
     DCGUI_BUTTON_OK - Configures the OK button
     DCGUI_BUTTON_CANCEL - Configures the CANCEL button
     DCGUI_BUTTON_EXIT - Configures the EXIT button
     DCGUI_BUTTON_HELP - Configures the HELP button
     DCGUI_BUTTON_YES - Configures the YES button
     DCGUI_BUTTON_NO - Configures the NO button
   
   or < aConfig > is a 4 element array containing the numeric value
   of the button to configure, the caption, the width and the height.
   
   < xCaption > is the caption of the button.  This may be a character
   string, a numeric resource value that has been linked into the
   application, an XbpBitMap() object, or a string containing the
   name of a .BMP, .JPG or .GIF file.  It may also be a code block
   that returns one of the above values.
   
   < nWidth > is the width of the button in pixels.
   
   < nHeight > is the height of the button in pixels.
   
   < oBitmap > is an XbpBitMap() object to use on the button.
   
   < cFont > is the font compound name.
   

Returns:

   An array of 4 elements containing the previous configuration of
   the button.
   
   Element  Type   Description
   -------  ----- -----------------------------------------------
     [1]      N    Numeric value of button (DCGUI_BUTTON_*)
     [2]      X    Caption of button
     [3]      N    Width of button in pixels
     [4]      N    Height of button in pixels
   

Description:

   DC_AddButtonConfig() is a Get-Set function which is used to
   configure the caption and size of buttons which are added to
   a dialog by the ADDBUTTONS or BUTTONS clause of DCREAD GUI.
   

Examples:

   #include "dcdialog.ch"
   #include "dcbitmap.ch"
   
   FUNCTION XTest()
   
   LOCAL GetList[0], GetOptions, cUserID, cPassword, aOkConfig, aCancelConfig
   
   cUserId := Space(10)
   cPassword := Space(10)
   
   aOkConfig := DC_AddButtonConfig(DCGUI_BUTTON_OK,BITMAP_OK_1,80,30)
   aCancelConfig := DC_AddButtonConfig(DCGUI_BUTTON_CANCEL,BITMAP_CANCEL_1,80,30)
   
   @ 1,1 DCSAY ' User ID' GET cUserID
   @ 3,1 DCSAY 'Password' GET cPassword PASSWORD
   
   DCGETOPTIONS ;
      BUTTONALIGN DCGUI_BUTTONALIGN_CENTER
   
   DCREAD GUI FIT ADDBUTTONS TITLE 'Please Login' ;
      OPTIONS GetOptions
   
   DC_AddButtonConfig(aOkConfig) // restore old configuration
   DC_AddButtonConfig(aCancelConfig) // restore old configuration
   
   RETURN nil
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.DLL

See Also:

   DCREAD GUI
   DCGETOPTIONS

dc_addcargo()

Add cargo to the GetList

Syntax:

   DC_AddCargo ( < GetList >, ;
                 < xCargo > ) - > GetList
   

Arguments:

   < GetList > is the GetList array.
   
   < xCargo > can be one of several numeric values or an array.
   
     xCargo        Description
     ------       ----------------------------------------
      101          Force this GET to validate
      102          Display Pick-list pointer icon (arrow)
     {103,bBlock}  Pre-Evaluate Code-Block
     {104,bBlock}  Post-Evaluate Code-Block
     {105,aMsg}    Message to display on screen
      106          Protect this GET from editing
      107          Capitalize first character of each word
     {108,aData}   SAY prompt and coordinates
   

Returns:

    A pointer to the <þGetListþ> passed to DC_ADDCARGO().
   

Description:

    DC_ADDCARGO() is used to add cargo to the an array that
    is contained in the CARGO instance variable of the last
    GET in a GetList array.
   
    DC_READMODAL() automatically looks at the information in
    CARGO to give added functionality to the GET system.
    CARGO is used to store array pointers, screen SAY
    information and other GET options.
   

Examples:

    #include "dcget.ch"
   
    LOCAL GetList := {}, aData, i
   
    use <cDataFile>
    aData := Array(Fcount())
    FOR i := 1 TO LEN( aData )
      aData[i] := FieldGet(i)
    NEXT
    DC_ReadWindow( { 10, 10, 20, 60 } )
    FOR i := 1 TO LEN(aData)
   
      DC_GetDevOut( i, 12, PadL(Field(i),10), )
      SetPos( Row(), Col()+1 )
      AAdd( GetList,_GET_(aData[i],"aData[i]",,,) )
      DC_GetDisplay( GetList )
   
      /* -- Add array element pointer -- */
      GetList := DC_ADDCARGO(GetList,-1*i)
   
      /* -- Add SAY Prompt and location -- */
      GetList := ;
         DC_ADDCARGO(GetList,{ 108, { i, 12, PadL(Field(i),10) }})
   
      /* -- Add CAPFIRST flag -- */
      GetList := DC_ADDCARGO(GetList,107)
   
    NEXT
    DC_ReadModal( GetList,,aReadArea )
    RETURN nil
   

Source/Library:

  _DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readbox()

dc_addrec()

Append a new record and lock the record

Syntax:

    DC_AddRec ( [< nWaitTime >], ;
                [< lDisplayError >], ;
                [< nAppendMode >] ) - > lStatus
   

Arguments:

   < nWaitTime > is the number of seconds to wait for the system to
   return a lock before returning the status or the error message.
   (0 = wait forever).
   
   < lDisplayError > if .true. will display an operator error
   message if the record cannot be locked. (default) or if .false.
   will not display an error message to the operator.
   
   < nAppendMode > is a number from 0 to 2 (0 is the default) to
   establish the mode for reusing deleted or blank records, if
   they exist, or appending a new record.  See DC_APPENDMODE().
   

Returns:

    A logical .TRUE. if the record is successfully locked.
   

Description:

    The function of DC_ADDREC() is dependent on the APPEND MODE of
    operation that was previously selected by the DC_APPENDMODE()
    function.
   
    If the Append Mode is 0 (default), then DC_ADDREC() will always
    append a Blank record.
   
    If the Append Mode is 1, then DC_ADDREC() will first try to
    locate any existing Blank record in the database.  If a Blank
    record is found, the record pointer will be set to the found
    record and the record will be locked.  This mode functions
    differently based on whether or not the current work area
    has an index selected.  If an index is selected, then it is
    assumed that blank records will always appear at the TOP of
    the database so only the first record is tested, otherwise
    the entire database will be search for a blank record.
   
    If the Append Mode is 2, then DC_ADDREC() will first try to
    locate any existing record that is marked for deletion.  If
    a deleted record is found, the record pointer will be set
    to the found record, the record will be recalled (undeleted),
    all fields will be blanked, and the record will be locked.
   

Examples:

    dc_appendmode(1)  // reuse blank records
    use sales
    if DC_ADDREC()
      replace date with date()
    else
      break
    endif
   

Source/Library:

  _DCLOCK.PRG, DCLIPX.DLL

See Also:

   dc_reclock()
   dc_filock()
   dc_appendmode()
   APPEND
   UNLOCK

dc_addsetkeys()

Convert all SET KEYS to DCHOTKEY commands

Syntax:

    DC_AddSetKeys( < aGetList > ) - > aGetList
   

Arguments:

   < aGetList > is the GetList array that will be passed to DC_ReadGUI().
   

Returns:

    A GetList array with all hotkeys added.
   

Description:

    DC_ADDSETKEYS is used to read the current SET KEYS and add them
    to the GetList as DCHOTKEY commands.
   

Examples:

   FUNCTION XTest()
   
   LOCAL GetList := {}, dDate := Date(), nNumber := 0
   
   SET KEY -2 TO DC_PopDate()
   SET KEY -3 TO DC_PopCalc()
   
   @ 1,1 DCSAY '  Enter a Date' GET dDate
   @ 3,1 DCSAY 'Enter a Number' Get nNumber
   
   @ 5,1 DCSAY 'Press F3 for a Calendar' SAYSIZE 30
   @ 6,1 DCSAY 'Press F4 for a Calculator' SAYSIZE 30
   
   DC_ADDSETKEYS(GetList)
   
   DCREAD GUI FIT ADDBUTTONS
   
   RETURN nil
   

Source/Library:

  _DCFUNCT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   DCHOTKEY

DC_AdsCursor2Excel()

Create Excel spread sheet from an Ads Cursor handle

Syntax:

   DC_AdsCursor2Excel( < nCursorHandle >, ;
                       [< cExcelFile >], ;
                       [< nOrientation >], ;
                       [< lDisplayAlerts >], ;
                       [< lVisible >], ;
                       [< lAutoFit >] ) - > nil
   

Arguments:

   < cExcelFile > is the name of the excel file (*.XLS) to be created.
   If this parameter is not passed, the file will be created in the
   same directory as the application .exe and will be named WORKSHEET.XLS.
   
   < nOrientation > is the orientation of the spreadsheet.  A value of
   1 creates a "portrait" orientation.  A value of 2 creates a
   "landscape" orientation (default).
   
   < lDisplayAlerts > will prompt the user if the file being created
   will be overwritten.  The default is .f.
   
   < lVisible > will display the spreadsheet while the cells are being
   filled.  Default is .f.
   
   < lAutoFit > will optimize the columns of the spreadsheet to fit
   the data to it's optimum width, otherwise the columns will be
   the width of the database field.  Default is .t.
   

Description:

   DC_AdsCursor2Excel() is used to create an Excel spread sheet from
   an Ads Cursor handle.
   

Examples:

   FUNCTION Xtest()
   
   LOCAL nHandle, cServer := CurDrive()+':', nStatementHandle, ;
         cStatement
   
   cStatement := "SELECT PART_NO, ON_HAND, COST FROM PARTS WHERE ON_HAND >
   100"
   
   AdsConnect( cServer, @nHandle )
   
   nStatementHandle := 0
   AdsCreateSQLStatement( nHandle, @nStatementHandle )
   
   nCursorHandle := 0
   AdsExecuteSQLDirect( nStatementHandle, cSelect, @nCursorHandle )
   
   DC_AdsCursor2Excel( nCursorHandle )
   
   RETURN nil
   

Source/Library:

  _DCADS.PRG

See Also:

   DC_WorkArea2Excel()
   DC_Array2Excel()

dc_adscursor2xml()

Export an ADS cursor to an XML file or string

Description:

   DC_AdsCursor2Xml() will export an ADS cursor to an XML file,
   or string, that will contain structure and data.  Look at the
   example in .\samples\xml.
   

Source/Library:

  _dcfunct.prg, dclipx.dll

See Also:

   dc_adscursor2excel()

dc_adsfieldblock()

Create a Get/Set code block for an ADS SQL cursor field

Syntax:

   DC_AdsFieldBlock( < nCursor > , ;
                     < cFieldName >, ;
                     [< bFormat >] ) - > bGetSet
   

Arguments:

   < nCursor > is a numeric cursor returned by an ADS SQL statement.
   
   < cFieldName > is a name of a field in the ADS SQL cursor.
   
   < bFormat > is a code block to format the returned data. The code
   block receives the data in for form of a string.
   

Returns:

   A code block.
   

Description:

   DC_AdsFieldBlock() is used to create a Get/Set code block for
   a field in an ADS SQL cursor.
   

Examples:

   nCursorHandle := 0
   AdsExecuteSQLDirect( nStatementHandle, cSelect, @nCursorHandle )
   
   nNumFields := 0
   AdsGetNumFields( nCursorHandle, @nNumFields )
   
   bDataSource := {||nCursorHandle}
   @ 0,0 DCBROWSE oBrowse ;
         DATA bDataSource ;
         SIZE 100,20 ;
         PRESENTATION DC_BrowPres()
   
   FOR i := 1 TO nNumFields
   
     cFieldName := Space(20)
     nLength := 20
     AdsGetFieldName( nCursorHandle, i, @cFieldName, @nLength )
     cFieldName := Pad(cFieldName,nLength)
   
     bGetSet := Adsfieldblock( nCursorHandle, cFieldname )
     DCBROWSECOL DATA bGetSet PARENT oBrowse HEADER cFieldName ;
        WIDTH 20
   
   NEXT
   

Source/Library:

  _DCADS.PRG, DCLIPX.DLL

See Also:

   DC_AdsSQLQuery()

dc_adsgoposition()

Moves the row pointer to a percent position in a ADS SQL cursor

Syntax:

   DC_AdsSkipper( < nAdsSQLcursor >, ;
                  < nPercent > ) - > Nil
   

Arguments:

   < nAdsSQLcursor > is an ADS SQL cursor.
   
   < nPercent > is a numeric value in the range between 0 and 100.
   Zero is equivalent to the first row and 100 indicates the last
   row in a SQL cursor.
   

Returns:

   A numeric value equal to the actual number of rows skipped.
   

Description:

   DC_AdsGoPosition() moves the row pointer in an ADS SQL cursor
   based on a percent value.
   

Examples:

   oBrowse:GoPosBlock := {|n|DC_AdsGoPosition(nAdsSQLcursor,n)}
   

Source/Library:

  _DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsfieldblock()
   dc_adsskipper()

dc_adsposition()

Returns the position of the ADS SQL cursor row as a percent value

Syntax:

   DC_AdsSkipper( < nAdsSQLcursor > ) - > nPercent
   

Arguments:

   < nAdsSQLcursor > is an ADS SQL cursor.
   

Returns:

   A numeric value equal to the position of the row in percent.
   

Description:

   DC_AdsPosition() returns a numeric value in the range between
   0 and 100. It indicates the position of the row pointer of an
   ADS SQL cursor in percent.
   

Examples:

   oBrowse:PosBlock := {|n|DC_AdsPosition(nAdsSQLcursor)}
   

Source/Library:

  _DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsfieldblock()
   dc_adsskipper()

dc_adsrunsql()

Execute a SQL statement in a new work area

Syntax:

   DC_AdsRunSQL( < cSQLStatement >, ;
                 [< cAlias >] ) - > lStatus
   

Arguments:

   < cSQLstatement > is an SQL SELECT statement that references tables
   in an ADS data-dictionary.
   

Returns:

   A logical .TRUE. if the statement executed successfully, .FALSE.
   otherwise.
   

Description:

   DC_AdsRunSql() will execute a SQL SELECT statement and return the
   results in a work area which can be navigated with standard
   Xbase++ navigation functions such as dbSkip(), dbGoTop(), etc.
   
   This requires Xbase++ 1.9 or later and ADSDBE 1.9 or later.
   
   Before using this function, a connection must be made to ADS server
   and a data-dictionary file.  See DC_AdsSession().
   

Examples:

   cServer := DC_Path(AppName(.t.)) + 'sample.add'
   
   oSession := DC_AdsSession( cServer )
   
   TEXT INTO cStatement
   SELECT * FROM XTEST
   ENDTEXT
   
   DC_AdsRunSql( cStatement, 'XTEST' )
   
   Browse()
   

Source/Library:

  _DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsstatement()
   dc_adssession()

dc_adssession()

Create or return Ads DacSession for current thread

Syntax:

   DC_AdsSession( [< ocSession >], ;
                  [< nWhich >], ;
                  [< lReturnAll >] ) - > oDacSession
   

Arguments:

   < ocSession > may be a connect string or a DacSession() object.
   
   If it is a character string then it must be a valid connection
   string to send to ADS.  It may be the drive/path where the databases
   reside or the drive path of an ADS data-dictionary file.  A connect
   string will cause a new ADS connect to be created.
   
   If it is a DacSession() object, then no new connection will be
   created and the passed object will be stored in the connection
   array.
   
   < nWhich > is the number of the session to store for the current
   thread.  The default is 1.  For example, each thread could have
   2 Ads Session objects stored, 1 for Free Table connections, and
   another for Data-Dictionary connections.
   
   < lReturnAll > if .TRUE. will return the entire multi-dimensional
   array.
   

Returns:

   A DacSession() object.
   

Description:

   DC_AdsSession is used to create an ADSDBE DacSession for the
   current thread to be later used by DC_AdsStatement() or a
   regular dbUseArea().
   
   All sessions for all threads are stored in a static multi-dimensional
   array.
   

Notes:

   The ADSDBE must be loaded before calling this function.
   

Examples:

   FUNCTION Xtest()
   
   LoadDbes()
   
   cServer := DC_Path(AppName(.t.)) + 'sample.add'
   
   oSession := DC_AdsSession( cServer )
   
   TEXT INTO cStatement
   SELECT * FROM XTEST
   ENDTEXT
   
   oStatement := DC_AdsStatement():new(cStatement)
   cAlias := oStatement:execute()
   Browse()
   
   oStatement:close()
   oSession:disConnect()
   
   
   RETURN nil
   
   * -----------------
   
   FUNCTION LoadDbes()
   
   LOCAL cSession, aDbeList := dbeList()
   
   IF ! DbeLoad( "ADSDBE" )
     DC_WinAlert( "Unable to load ADSDBE", "ADS Server",, ;
           XBPMB_WARNING + XBPMB_APPMODAL )
   ELSE
   
     DbeSetDefault( "ADSDBE" )
   
     DbeInfo( COMPONENT_DATA, ADSDBE_TBL_MODE, ADSDBE_CDX )
     DbeInfo( COMPONENT_ORDER, ADSDBE_TBL_MODE, ADSDBE_CDX )
     DbeInfo( COMPONENT_DATA, ADSDBE_LOCK_MODE, ADSDBE_PROPRIETARY_LOCKING  )
   
     cSession := "DBE=ADSDBE;SERVER=" + scDictServer
     soAdsSessionDict := DacSession():new(cSession)
     IF !soAdsSessionDict:isConnected()
       MsgBox( "Unable to establish DICTIONARY connection to ADS Server" + Chr(13)
   + ;
                cSession + Chr(13) + ;
                "Error Code: " + Alltrim(Str(soAdsSessionDict:getLastError())) +
   Chr(13) + ;
                 soAdsSessionDict:getLastMessage() )
     ELSE
       DC_AdsSession( soAdsSessionDict,1 )
     ENDIF
   
     cSession := "DBE=ADSDBE;SERVER=" + scFreeServer
     soAdsSessionFree := DacSession():new(cSession)
     IF !soAdsSessionFree:isConnected()
       MsgBox( "Unable to establish FREE connection to ADS Server" + Chr(13) + ;
               cSession + Chr(13) + ;
               "Error Code: " + Alltrim(Str(soAdsSessionFree:getLastError())) +
   Chr(13) + ;
                soAdsSessionFree:getLastMessage() )
     ELSE
       DC_AdsSession( soAdsSessionFree, 2 )
     ENDIF
   
   ENDIF
   
   RETURN nil
   

Source/Library:

  _DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsstatement()

dc_adsskipper()

A skipper for ADS SQL cursors

Syntax:

   DC_AdsSkipper( < nAdsSQLcursor >, ;
                  < nWantSkip > ) - > nDidSkip
   

Arguments:

   < nAdsSQLcursor > is an ADS SQL cursor.
   
   < nWantSkip > is the number of rows to skip.
   

Returns:

   A numeric value equal to the actual number of rows skipped.
   

Description:

   DC_AdsSkipper() is a Skipper function to be used in navigation
   code blocks for a browse.
   

Examples:

   oBrowse:skipBlock := {|n|DC_AdsSkipper(nAdsSQLcursor,n)}
   

Source/Library:

  _DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsfieldblock()

dc_adssqlquery()

A SQL Query window for ADS

Syntax:

   DC_AdsSQLQuery( [< cServer >], ;
                   [< cUserName >], ;
                   [< cPassword >], ;
                   [< cDataPath >], ;
                   [@< cBrowseObjectName >], ;
                   [< oParent >], ;
                   [< nIndexMode >, ;
                   [< nLockingMode >, ;
                   [< cDbe >] ) - > nil
   

Arguments:

   < cServer > is either a path to a set of .DBF / .CDX databases or
   the name of an ADS data-dictionary file.  If this parameter is
   not passed then it will default to < cDataPath >.
   
   < cUserName > and < cPassword > are used only if
   < cServer > is a
   data-dictionary file.  This is a valid user and password to allow
   access to the data-dictionary.
   
   < cDataPath > is the directory where the ADSSQL.DBF file is to
   be opened or created.  ADSSQL.DBF is used to save SQL queries.
   
   < oParent > is a pointer to a parent object for the new dialog.
   If < oParent > is empty, then the parent will be the AppDeskTop().
   
   < nIndexMode > is the type of index files to be used with the DBF
   databases.  The default is ADS_CDX (defined in DCADS.CH).
   
   < nLockingMode > is the type of record locking scheme to use.
   The default is ADS_COMPATIBLE_LOCKING (defined in DCADS.CH).
   
   < cDbe > is the DBE to use for the ADSSQL.DBF database.  The default
   is 'DBFNTX'.
   

Returns:

   Nil.
   

Description:

   DC_AdsSQLQuery() is a SQL query system based on the SQL functions
   in ACE32.DLL.
   
   SQL statements are entered in a text window and then executed
   with the push of a button.  A SQL cursor is returned and the
   results are displayed in a columnar browse window.
   
   SQL statements may be saved to a database named ADSSQL.DBF for
   later retrieval.
   

Source/Library:

  _DCADS.PRG, DCLIPX.DLL

dc_alert()

A Dual-Mode replacement for Clipper's ALERT() function

Syntax:

   DC_Alert ( < cText >, ;
              < aMenuItems >, ;
              [< cColorString >], ;
              [< lJustify >], ;
              [< aMenuId >], ;
              [< cMenuName >], ;
              [< nChoice >], ;
              [@< aDlgPos >], ;
              [< aFonts >] ) - > nChoice
   

Arguments:

   < cText > is the message to place in the alert box.  Use
   semicolons in the text to separate lines of text.
   
   < aMenuItems > is an array of menu choices.  The character
   following the '~' character will be highlighted.
   
   < cColorString > is an optional color string containing
   exactly 4 colors separated by commas:
   
    (1) box and message.
    (2) unselected menu items.
    (3) hot-key character of each unselected menu item
    (4) selected menu item
   
   < lJustify > if .TRUE. will left-justify the message items.
   Default is .FALSE.
   
   < aMenuId > - An optional array of unique Menu ID codes (up to 8
   characters) for each menu item in < aItems >.  This array is
   needed to enable the PERSISTENT MENU SELECTION feature.  See
   DC_MenuPull() for more information.
   
   < cMenuName > - An optional parameter with a "unique" name for
   this menu.  This name is needed to enable the PERSISTENT MENU
   SELECTION feature.  See DC_MenuPull() for more information.
   
   < nChoice > is the default menu selection.
   
   @< aDlgPos > is a numeric variable to store a two-element array
   of coordinates which will be returned when the user exists the
   alert window.  These coordinates are the screen coordinates of
   the dialog before it was destroyed.  These coordinates may be
   passed to DG_GUIALERT() again later to paint the dialog window
   in the same location.
   
   < aFonts > is a 2-element array containing the Font Compound Name
   for the buttons and the text.  Element 1 is the button font and
   element 2 is the text font.  This parameter is used in GUI mode
   only.
   

Returns:

    A number equal to the menu choice.  Returns 0 if user
    presses ESCape.
   

Description:

    DC_ALERT() is a Dual-mode replacement for Alert().  When
    the GUI flag is ON, DC_ALERT() functions similiar to
    Alert() except that it is displayed in GUI mode.  When the
    GUI flag is OFF, DC_ALERT() functions identical to Alert()
    except it is also activated by a mouse.  The left button of the
    mouse is used to select the item in the window.
   

Notes:

   The foreground and background color of the GUI alert box is
   preset by the function DC_AlertColor().
   

Examples:

    PROCEDURE XTest()
   
    LOCAL nChoice
   
    DC_Gui(.t.)
   
    nChoice := DC_ALERT( "The printer is not ready",;
              { 'Retry','Abort','Output to a file' } )
   
    DC_MsgBox( 'You chose ' + Str(nChoice) )
   
    RETURN
   

Source/Library:

  _DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_msgbox()
   dc_guialert()

dc_andbits()

A logical AND of two bytes

Syntax:

   DC_AndBits( < nNum1 >, ;
               < nNum2 > ) - >nResult
   

Arguments:

   < nNum1 > and < nNum2 > are numeric values from 0 to 255.
   

Returns:

    A numeric value from 0 - 255
   

Description:

   DC_ANDBITS() will produce the result of logically ANDing two bytes.
   

Source/Library:

  _DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_bittest()
   dc_xorbits()

dc_apick()

A dialogue for choosing a item from an array pick list.

Syntax:

   DC_APick ( [< nTop >], [< nLeft >], < nWidth >,
   < nHeight >, ;
              < aMenuItems >, ;
              [< acHeader >], ;
              [< anWidth >], ;
              [< cTitle >], ;
              [< anTag >], ;
              [< aTagColor >], ;
              [< bHandler >], ;
              [< nStart >], ;
              [< cFontName >], ;
              [< oParent >], ;
              [< oOwner >], ;
              [< lCenter >], ;
              [< lMenu >], ;
              [< lNoVScroll >], ;
              [< lNoHScroll >], ;
              [< aPres >], ;
              [< cHelpCode >], ;
              [< cAutoSeekPicture >], ;
              [< lNoRestore >] ) - > nChoice
   

Arguments:

   < nTop >, < nLeft > are the starting coordinates.  These are
   text-
   base coordinates.  These parameters are not required if the
   < lCenter > parameter is used.
   
   < nWidth > and < nHeight > are the width and height of the
   window
   in text-based coordinates.
   
   < aMenuItems > is an array of character strings to include
   in the pick-list.  This may be a single-dimension array or a
   multi-dimension array.
   
   < acHeader > is the heading to place above each column.  If
   < aMenuItems > is a single-dimension array, then there is only 1
   header, so < acHeader > is a character string.  If
   < aMenuItems >
   is a multi-dimension array, then < acHeader > is an array of
   character strings, 1 for each column.
   
   < anWidth > is the width of the column(s).  If aMenuItems > is a
   single-dimension array, then there is only 1 width, so < anWidth >
   is a numeric value.  If < aMenuItems > is a multi-dimension array,
   then < anWidth > is an array of numeric values, 1 for each column.
   
   < cTitle > is the title to place at the top of the window.
   
   < anTag > is an array of logical elements or a single numeric
   value.  If < anTag > is an array, it must be the same length as
   the array being browsed and must contain logical values.  When
   the user double-clicks a browse row, the corresponding element
   of < anTag > will be toggled.  If < anTag > is a numeric value,
   then
   it is a pointer to the column of < aMenuItems > that contains
   logical tags.
   
   < aTagColor > is used in conjunction with < anTag > to select
   the
   color for the rows that are tagged.  This is a 2-element array
   consisting of a foreground and background color.  The default
   is { GRA_CLR_WHITE, GRA_CLR_BLUE }.
   
   < bHandler > is a SPARE.
   
   < nStart > is the starting element in the browse.
   
   < cFontName > is the font to use for the browse.
   
   < oParent > is the parent object to create the browse.  If no
   parameter is passed, a dialog window will be created.
   
   < oOwner > is the owner object of the browse.  If no parameter is
   passed, the owner will be the same as the parent.
   
   < lCenter > if .TRUE. will center the browse dialog on the desktop.
   
   < lMenu > if .TRUE. will enable "menu mode".  This allows the
   operator to press keyboard keys that match the first letter of
   each array item to select the item.
   
   < lNoVScroll > if .TRUE. will suppress the vertical scroll bar.
   The default is .FALSE.
   
   < lNoHScroll > if .TRUE. will suppress the horizontal scroll bar.
   The default is .FALSE.
   
   < aPres > is an array of presentation parameters that must conform
   to the presParam specifications for the XbpBrowse() class.
   
   < cHelpCode > is a help code.
   
   < cAutoSeekPicture > if passed will cause an autoseek GET to be
   created above the browse window.  The value entered into the
   get will be passed to DC_BrowseAutoSeek() to seek to a value.
   < cAutoSeekPicture > establishes the picture clause for the Get.
   
   < lNoRestore > if .TRUE.  will override DC_AutoRestoreWindow() and
   insure that the window coordinates and size are never saved and
   restored.  The default is .FALSE.
   

Returns:

   A Numeric Value equivalent to the selected row.
   

Description:

   DC_APick() is used to display a browse-style picklist of an
   array.
   

Examples:

   FUNCTION XTest()
   
   LOCAL aDir := Directory(), i, aHeaders, aWidths
   
   FOR i := 1 TO Len(aDir)
     ASize(aDir[i],5)
     aDir[i,5] := .f.
   NEXT
   
   aHeaders := { 'File Name', 'File Size', 'File Date', 'File Time' }
   
   aWidths := { 10,10,10,10 }
   
   nChoice := DC_APick ( , , 50, 10, aDir, ;
              aHeaders, aWidths, 'Disk Directory', 5, ;
              { GRA_CLR_WHITE, GRA_CLR_RED }, ;
              nil, nil, '8.Terminal', nil, nil, .t. )
   
   RETURN nChoice
   

Source/Library:

  _DCACHOI.PRG/.OBJ, DCLIPX.LIB

See Also:

   DCAPICK
   dc_achoice()

dc_appendmode()

Set the default mode of operation for DC_AddRec()

Syntax:

    DC_AppendMode ( < nMode > ) - > nOldMode
   

Arguments:

   < nMode > is a number designating the desired append mode.
   
   If the Append Mode is 0 (default), then DC_ADDREC() will always
   append a Blank record.
   
   If the Append Mode is 1, then DC_ADDREC() will first try to
   locate any existing Blank record in the database.  If a Blank
   record is found, the record pointer will be set to the found
   record and the record will be locked.  This mode functions
   differently based on whether or not the current work area
   has an index selected.  If an index is selected, then it is
   assumed that blank records will always appear at the TOP of
   the database so only the first record is tested, otherwise
   the entire database will be search for a blank record.
   
   If the Append Mode is 2, then DC_ADDREC() will first try to
   locate any existing record that is marked for deletion.  If
   a deleted record is found, the record pointer will be set
   to the found record, the record will be recalled (undeleted),
   all fields will be blanked, and the record will be locked.
   

Returns:

    A numeric value representing the current append mode.
   

Description:

    DC_APPENDMODE() is used to establish the default operation of
    the DC_ADDREC() function.  Depending on the mode selected
    DC_ADDREC() will attempt to reuse blank records or deleted
    before appending a new, blank record.
   

Examples:

    use sales
    set index to month
    DC_APPENDMODE(1)  // re-use blank records
    if dc_addrec()
      replace date with date()
    else
      break
    endif
   

Source/Library:

  _DCLOCK.PRG, DCLIP1.DLL

See Also:

   dc_addrec()

dc_appevent()

Post an Event Loop

Syntax:

    DC_AppEvent( @< lOk >, ;
                  < nExitEvent >, ;
                  < nDelay > ) - > nLastEvent
   

Arguments:

   @< lOk > is an optional logical value (passed by reference).
   DC_AppEvent() will exit and return when this value is set to
   .FALSE.
   
   < nExitEvent > is an optional numeric value.  DC_AppEvent() will
   exit and return when the next event in the event queue is
   equal to this value.  < nExitEvent > defaults to 0, meaning that
   the loop will exit when no more events are in the event queue.
   
   < nDelay > is the amount of delay to use when DC_AppEvent() calls
   the AppEvent() function.  This defaults to 0, meaning that
   event loop will not exit until an event occurs.  If < nDelay >
   is any value greater than 0, then this is amount of delay before
   the AppEvent() function exits.  < nDelay > should usually be set
   to a value of .01 when using DC_AppEvent() to process events
   while still processing other code.  See the example.
   

Returns:

    A numeric value equal to the last event processed in the loop.
   

Description:

    DC_APPEVENT() is a handy function that creates an event loop for
    processing events.  Unlike the Xbase++ AppEvent() function,
    DC_APPEVENT() contains a DO..WHILE loop that processes events as
    a single function call.
   

Examples:

   /*
   This example uses DC_APPEVENT() to abort a COPY TO process.
   */
   
   #include 'dcdialog.ch'
   
   FUNCTION XTest()
   
   LOCAL Getlist := {}, oProgress, oDialog, lOk := .t., oButton, ;
         nEvent, mp1, mp2, oXbp
   
   USE COLLECT VIA DBFNTX NEW SHARED
   
   @ 2,5 DCSAY 'Exporting Data to JUNK.DBF'
   
   @ 4,5 DCPROGRESS oProgress ;
          SIZE 55,1.5 ;
          MAXCOUNT RecCount() COLOR GRA_CLR_BLUE
   
   @ 4,65 DCPUSHBUTTON  CAPTION '&Cancel' ;
     ACTION {||lOk:=.f.} OBJECT oButton ;
     SIZE 8,1.5
   
   DCREAD GUI TITLE 'My Test Dialog' ;
      PARENT @oDialog ;
      FIT ;
      EXIT
   
   oDialog:show()
   
   COPY TO junk WHILE _Progress( oProgress, @lOk )
   
   oButton:SetCaption('&Ok')
   DC_APPEVENT( @lOk )
   
   oDialog:Destroy()
   CLOSE ALL
   
   RETURN nil
   
   /* ----------------- */
   
   STATIC FUNCTION _Progress ( oProgress, lOk )
   
   DC_GetProgress( oProgress, COLLECT->(RecNo()) )
   DC_Pause(.3)
   DC_APPEVENT( @lOk, 0, .01 )
   
   RETURN lOk
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

dc_appeventdefine()

Translate AppEvent() value to DEFINE value

Syntax:

   DC_AppEventDefine( < nEvent > ) - > cDefinition
   

Arguments:

   < nEvent > is the AppEvent() to translate.
   

Returns:

    A Character string.
   

Description:

    DC_APPEVENTDEFINE() returns a character string that contains
    the DEFINITION name for the AppEvent() value.  These defines are
    contained in APPEVENT.CH.
   
    This is a handy debugging function that can be used in event
    loops to display events as they are occurring like so:
   
    DO WHILE nEvent # xbeP_None
      nEvent := AppEvent( @mp1, @mp2, @oXbp )
      ? DC_APPEVENTDEFINE( nEvent )
      oXbp:HandleEvent( nEvent, mp1, mp2 )
    ENDDO
   

Examples:

    #include 'appevent.ch'
   
    PROCEDURE XTest()
   
    DC_Gui(.t.)
   
    DC_MsgBox( { DC_APPEVENTDEFINE( xbeP_Close ), ;
                 DC_APPEVENTDEFINE( xbeP_Resize ), ;
                 DC_APPEVENTDEFINE( xbeP_Activate ) } )
   
    RETURN
   

Source/Library:

  _DCPUTK.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_keytran()
   dc_appkeydefine()

dc_appkeydefine()

Translate AppEvent() keyboard value to DEFINE value

Syntax:

   DC_AppKeyDefine( < nKey > ) - > cDefinition
   

Arguments:

   < nKey > is the AppEvent() value of the key to translate.
   

Returns:

    A Character string.
   

Description:

    DC_APPKEYDEFINE() returns a character string that contains the
    DEFINITION name for the AppEvent() a keyboard value.  These
    defines are contained in APPEVENT.CH.
   
    This is a handy debugging function that can be used in event
    loops to display events as they are occurring like so:
   
    DO WHILE nEvent # xbeP_None
      nEvent := AppEvent( @mp1, @mp2, @oXbp )
      IF nEvent = xbeP_Keyboard
        ? DC_APPKEYDEFINE( mp1 )
      ENDIF
      oXbp:HandleEvent( nEvent, mp1, mp2 )
    ENDDO
   

Examples:

    #include 'appevent.ch'
   
    PROCEDURE XTest()
   
    DC_Gui(.t.)
   
    DC_MsgBox( { DC_APPKEYDEFINE( xbeK_ALT_M ), ;
                 DC_APPKEYDEFINE( xbeK_ENTER ), ;
                 DC_APPKEYDEFINE( xbeK_INS ) } )
   
    RETURN
   

Source/Library:

  _DCPUTK.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_keytran()
   dc_appeventdefine()

dc_applysqlparams()

Apply SQL parameters to a SQL statement.

Syntax:

   DC_ApplySQLparams( < cSQLstatement >, ;
                      < aParams > ) - > < cSQLstatement >
   

Arguments:

   < cSQLstatement > is a SQL statement that contains one ? character
   for each parameter in < aParams >.
   
   < aParams > is an array of values to plug into the SQL statement.
   
   If a parameter is enclosed in brackets, then the value in the
   brackets is considered "literal" and is stuffed into the SQL command
   as is without the brackets.
   

Returns:

   A character string.
   

Description:

   DC_ApplySQLParams() is use to pass parameters into a SQL statement.
   The parameters may be type C, L, M, N, or D.  Each ? in the
   statement will be replaced by each passed parameter, sequentially,
   Each parameter is converted to a character string value which is
   compatible with SQL.
   

Examples:

   cSQL := 'SELECT * FROM customers WHERE name=? AND zip=?'
   
   cSQL := DC_ApplySQLParams( cSQL, {'Donnay', '83706'})
   

Source/Library:

  _DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsstatement()
   dc_var2sql()

dc_ar2str()

Convert a multidimensional array to a string

Syntax:

   DC_Ar2Str ( < aArray > ) - > cString
   

Arguments:

   < aArray > is any multidimenstional array.
   

Returns:

    A character string.
   

Description:

    DC_Ar2Str() will convert the contents of any multi-dimensional
    array to a string for later restoring with DC_Str2Ar().  The
    string may then be saved to a file or to a character or memo
    type database field.  This set of functions is an alternative
    to using the Xbase++ functions Var2Bin() and Bin2Var() because
    they will create a runtime error if the array contains code
    blocks with non-persistent data.
   
    If the array contains code blocks, the code blocks will be
    saved and restored provide that they contain persistent data.
    Any code block that contains non-persistent data will be
    saved as a NIL.
   
    If the array contains pointers to objects, they pointers will
    be saved as a NIL.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aDir
   
    aDir := Directory()
   
    USE dirs
    APPEND BLANK
    REPL DIRS->array WITH DC_Ar2Str(aDir)
   
    aDir := DC_Str2Ar(DIRS->array)
    DC_ArrayView(aDir)
   
    RETURN
   

Source/Library:

  _DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_str2ar()
   dc_asave()

dc_arestore()

Restore a multidimensional array from a binary file

Syntax:

   DC_ARestore ( < cFileName > ) - > aArray
   

Arguments:

   < cFileName > is the name of the binary file that was previously
   created with DC_ASAVE().
   

Returns:

    A multidimensional array if the array file was a valid file,
    otherwise returns a NIL.
   

Description:

    DC_ARESTORE() will create an multidimensional array from the
    contents of a binary file that was created with DC_ASAVE().
   
    If the array contains code blocks, the code blocks will be
    saved and restored provide that they contain persistent data.
    Any code block that contains non-persistent data will be
    restored as a NIL.
   
    If the array contains pointers to objects, they pointers will
    be restored as a NIL.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aDir1, aDir2
   
    DC_Gui(.t.)
   
    aDir1 := Directory()
    dc_asave( aDir1, 'ADIR.ARX' )
    aDir2 := DC_ARESTORE( 'ADIR.ARX' )
   
    DC_Achoice( 5,10,20,30, DC_AConvert( aDir2 )[1] )
   
    RETURN
   

Source/Library:

  _DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_asave()

dc_areverse()

Reverse all elements in an array

Syntax:

    DC_AReverse ( < aArray > ) - > aNewArray
   

Arguments:

   < aArray > is the name of the array to reverse.
   

Returns:

    An array of the same length as the original array.
   

Description:

    DC_AREVERSE() is used to sort all the elements of an array
    in reverse order from the original array.
   

Examples:

    myArray :=  { 1, 2, 'test', .t. }
   
    outArray := DC_AREVERSE( myArray )
   
    // contents of outArray :  { .t., 'test', 2, 1 }
   

Source/Library:

  _DCARRAY.PRG, DCLIP1.DLL

See Also:

   dc_aconvert()

dc_array_r()

Create a multi-dimensional array from an array text file

Syntax:

   DC_Array_Read ( < cArrayFile > ) - > aArray
   

Arguments:

   < cArrayFile > is the name of the array text file to read.
   

Returns:

    A multi-dimensional array built from the contents of <þcArrayFileþ>.
   

Description:

    DC_ARRAY_R() is used to create a multi-dimensional array
    from the contents of an array text file.  Only elements of the
    type L (logical), N (numeric), C (character), D (date), A
    (array) can be saved and restored.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aDir1, aDir2, cScrn
   
    DC_Gui(.t.)
   
    cScrn := DC_WaitOn()
    aDir1 := directory()
    dc_array_w( aDir1, "DIR.AR" )
    aDir2 := DC_ARRAY_R( "DIR.AR" )
    DC_Impl(cScrn)
   
    DC_Achoice( 5,10,20,30, DC_AConvert( aDir2 )[1] )
   
    RETURN
   

Source/Library:

  _DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_array_w()

dc_array_w()

Write contents of a multi-dimensional array to file

Syntax:

   DC_Array_Write ( < aArray >, ;
                    < cArrayFile > ) - > lStatus
   

Arguments:

   < aArray > is the name of the multi-dimensional array to save.
   
   < cArrayFile > is the name of the array text file to write.
   

Returns:

    .TRUE. if the array file was created, .FALSE. otherwise.
   

Description:

    DC_ARRAY_W() is used to save a multi-dimensional array to
    an array text file for later restoring with the DC_ARRAY_R()
    function for RESTORE ARRAY command.  Only elements of the type
    L (logical), N (numeric), C (character), D (date), A (array)
    can be saved and restored.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aDir1, aDir2, cScrn
   
    DC_Gui(.t.)
   
    cScrn := DC_WaitOn()
    aDir1 := directory()
    DC_ARRAY_W( aDir1, "DIR.AR" )
    aDir2 := dc_array_r( "DIR.AR" )
    DC_Impl(cScrn)
   
    DC_Achoice( 5,10,20,30, DC_AConvert( aDir2 )[1] )
   
    RETURN
   

Source/Library:

  _DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_array_r()

dc_array2csv()

Create a comma-delimeted CSV file from data in an array

Syntax:

   DC_Array2CSV( < cCsvFile >, ;
                 < aData >, ;
                 [< aHeader >] ) - > lStatus
   

Arguments:

   < cCsvFile > is the name of the comma-delimted file (*.CSV) to be
   created.
   
   < aData > is a 2-dimensional array containing the data.
   
   < aHeader > is a 1-dimensional array with header information.
   

Returns:

   A logical .true. if the file could be created, .false. otherwise.
   

Description:

   DC_Array2CSV() is use to create a comma-delimited (*.CSV)
   file from the data in a 2-dimensional array.
   

Examples:

   aDir := Directory()
   
   aHeader := { 'File Name', 'File Size', 'File Date' ,'File Time' }
   
   DC_Array2CSV('DIRECTORY.CSV',aHeader)
   
   DC_SpawnUrl('DIRECTORY.CSV')
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL, DCLIPX.LIB

dc_array2excel()

Create an Excel Spreadsheet from data in an array

Syntax:

   DC_Array2Excel( [< cExcelFile >], ;
                   < aData >, ;
                   [< nOrientation >], ;
                   [< lDisplayAlerts >], ;
                   [< lVisible >], ;
                   [< lAutoFit >], ;
                   [< lTrimNilColumns >], ;
                   [< lCombineSheets >], ;
                   [< cPassWord >], ;
                   [< lFreezeRow1 >], ;
                   [< lCSVFallBack >] ) - > lStatus
   

Arguments:

   < cExcelFile > is the name of the excel file (*.XLS) to be created.
   If this parameter is not passed, the file will be created in the
   same directory as the application .exe and will be named WORKSHEET.XLS.
   
   < aData > is the array containing the data.  This must be an array
   of 2-dimensional sub-arrays (one for each Excel sheet).
   
   < nOrientation > is the orientation of the spreadsheet.  A value of
   1 creates a "portrait" orientation.  A value of 2 creates a
   "landscape" orientation (default).
   
   < lDisplayAlerts > will prompt the user if the file being created
   will be overwritten.  The default is .f.
   
   < lVisible > will display the spreadsheet while the cells are being
   filled.  Default is .f.
   
   < lAutoFit > will optimize the columns of the spreadsheet to fit
   the data to it's optimum width, otherwise the columns will be
   the width of the database field.  Default is .t.
   
   < lTrimArray > will remove all columns and rows from the array that
   contain all NIL values to optimize the resultant spreadsheet. The
   default is .f.
   
   < lCombineSheets > will create a single Excel sheet from the data
   in all subarrays.  Instead of writing the data to separate sheets
   the data from each sheet will be added as additional rows to
   the first sheet.  The default is .f.
   
   < cPassWord > is an optional password to assign to the file.
   
   < lFreezeRow1 > if .TRUE. causes the first row of the Excel sheet to
   be
   bold font and locked from scrolling.  The default is .FALSE.
   
   < lCsvFallBack > if .TRUE. will cause the output to be a .CSV file in
   the event that the Excel ActiveX control is not installed.
   

Returns:

   A logical .true. if the spreadsheet could be created, .false.
   otherwise.
   

Description:

   DC_Array2Excel() is use to create an Excel spreadsheet (*.XLS)
   file from the data in a 2-dimensional array.
   

Examples:

   aDir := Directory()
   
   aDir := { aDir }
   
   DC_Array2Excel('DIRECTORY.XLS',aDir)
   
   DC_SpawnUrl('DIRECTORY.XLS')
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL, DCLIPX.LIB

dc_array2hexstring()

Convert a multidimensional array to a hex string

Syntax:

   DC_Array2HexString ( < aArray > ) - > cString
   

Arguments:

   < aArray > is any multidimensional array that contains variables of
   type
   C, M, D, L, or N.
   

Returns:

    A character string.
   

Description:

   DC_Array2HexString() will convert the contents of any multi-dimensional
   array to a string for later restoring with DC_HexString2Array().  The
   string may then be saved to a file or to a character or memo type
   database field.
   
   This function is mainly intended for use on the internet when an array
   of information must be passed in an XML stream.
   

Source/Library:

  _DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_hexstring2array()
   dc_ar2str()
   dc_asave()

dc_array2js()

Convert an array to JSON

Syntax:

   DC_Array2JS( < aArray > ) - > cJson
   

Arguments:

   < aArray > is any multi-dimensional array.
   

Returns:

   A character string.
   

Description:

   DC_Array2JS() is used to convert an array to JSON (Javascript Object
   Notation). The array may contain any Xbase++ value including
   subarrays and objects.  Only the iVars in the objects will be
   converted.
   

See Also:

   dc_object2js()
   dc_array2xml()
   dc_object2xml()

dc_array2prg()

Save the contents of a multidimensional array to source code

Syntax:

    DC_Array2Prg ( < aArray >, ;
                   < cFileName >, ;
                  [< cFunction >], ;
                  [< cComments >], ;
                  [< cCode >] ) - > lStatus
   

Arguments:

   < aArray > is the name of the array to write.
   
   < cFileName > is the name of the file to create.
   
   < cFunction > is the name of the function to call that will
   return the array contents.  If this parameter is not passed
   then the function will be given the same name as the file.
   
   < cComments > is any comment heading to place at the top of
   the file.
   
   < cCode > is any source code that should be executed at the
   beginning of the function before returning the array
   contents.
   

Returns:

    A logical .t. if the file was created.
   

Description:

    DC_ARRAY2PRG() is used to create a .PRG file from the contents
    of a multi-dimensional array.   This allows the programmer
    to capture the contents of any array to a source code file
    that can be compiled and run to rebuild the array.
   

Notes:

    If the file being created already exists, then the user
    will be prompted to Append, Overwrite or Abort the
    operation.
   

Examples:

    -- Example 1 --
   
    . aMyArray := directory()
    . DC_ARRAY2PRG( aMyArray, "MYDIR" )
    . clip mydir  // compile mydir.prg
    . obj mydir   // load mydir.obj
    . aNewArray := MYDIR()
   
   
    -- Example 2 --
   
    . use all like cust*
    . browse tile       // configure browse windows
    . DC_ARRAY2PRG( DCBROWSE, 'MYBROWSE' )
    . clip mybrowse     // compile mbrowse.prg
    . obj mybrowse      // load mybrowse.obj
    . release dcbrowse  // kill old browse array
    . dcbrowse := MYBROWSE()
   

Source/Library:

  _DCARRAY.PRG, DCLIP1.DLL

See Also:

   dc_asave()

dc_array2sqlinsert()

Create SQL statement for inserting records

Syntax:

   DC_Array2SQLInsert( < aData >, < cTable > ) - >
   cSQLStatement
   

Arguments:

   < aData > is a 2-dimensional array of values to write to the database
   or a 1-dimensiona array of record objects to write to the database.
   

Returns:

   A character string.
   

Description:

   DC_Array2SQLInsert() is used to create a SQL statement for inserting
   records into a database.  This accepts an 2-dimensional array
   that matches the order of fields or a 1-dimensional array of
   record objects.
   

Notes:

   This function is handy when processing a lot of transactions that
   require adding many records to a database at one time.  Normal
   append() require locking and unlocking and also take a considerable
   amount of time.  SQL INSERT, on the other hand, is very fast
   because everything is being done on the server.  In addition
   a BEGIN TRANSACTION is put into the SQL at the beginning and a
   COMMIT WORK at the end.  This insures that no other task or
   workstation can write to the database until all records are
   inserted.
   

Examples:

   USE TRANS
   
   aRecords := {}
   
   oRecord := DC_DBRecord():new()
   TRANS->(dbGoTo(0))
   
   oRecord:date := Date()
   ...
   oRecord:tran_type := 'LOGIN'
   
   AAdd(aRecords,oRecord)
   
   cSQL := DC_Array2SqlInsert(aRecords)
   

Source/Library:

  _DCSQL.PRG, DCLIPX.DLL

See Also:

   dc_adsstatement()

dc_array2xml()

Convert an array to XML

Syntax:

   DC_Array2Xml( < aArray > ) - > cXML
   

Arguments:

   < aArray > is any multi=dimensional array that includes any Xbase++
   value including subarrays and objects.  Only the iVars of objects
   are included in the XML.
   

Returns:

   A character string.
   

Description:

   DC_Array2XML() converts an array to an XML string.
   

Source/Library:

  _DCFUNCT.PRG

See Also:

   dc_object2xml()
   dc_array2js()
   dc_object2js()

dc_arrayview()

A Tree style array/object browser

Syntax:

   DC_ArrayView( < aArray > | < oObject >, ;
                [< lExpand >] ) - > nil
   

Arguments:

   < aArray > is any type of array.
   
   < oObject > is any type of object.
   
   < lExpand > if .TRUE. will expand the tree.  The default is .FALSE.
   

Returns:

    NIL.
   

Description:

    DC_ARRAYVIEW() is used to browse multidimensional arrays
    and/or objects using a Tree-View style browser.
   
    The array can be any type of array with any dimensions and may
    contain any type of data. When expanding the array tree, the
    user has the option of opening a new window to display the
    contents of the sub-tree.  When expanding an object, the user
    has the option of displaying the properties of the object
    using DC_InspectObject().
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aDir
   
    aDir := directory()
    DC_ArrayView( aDir )
   
    RETURN
   

Source/Library:

  _DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_inspectobject()

dc_asave()

Save a multidimensional array to a binary file

Syntax:

   DC_ASave ( < aArray >, ;
              < cFileName > ) - > lStatus
   

Arguments:

   < aArray > is any multidimenstional array.
   
   < cFileName > is the name of the binary file to create with
   the array contents.
   

Returns:

    A logical .TRUE. if the array file was created, .FALSE.
    otherwise.
   

Description:

    DC_ASAVE() will save the contents of any multi-dimensional
    array to a binary file for later restoring with DC_ARESTORE().
   
    If the array contains code blocks, the code blocks will be
    saved and restored provide that they contain persistent data.
    Any code block that contains non-persistent data will be
    saved as a NIL.
   
    If the array contains pointers to objects, they pointers will
    be saved as a NIL.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aDir1, aDir2
   
    DC_Gui(.t.)
   
    aDir1 := Directory()
    DC_ASAVE( aDir1, 'ADIR.ARX' )
    aDir2 := DC_Arestore( 'ADIR.ARX' )
   
    DC_Achoice( 5,10,20,30, DC_AConvert( aDir2 )[1] )
   
    RETURN
   

Source/Library:

  _DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_arestore()
   SAVE ARRAY

dc_at_clear()

Clear all prompts added by DC_At_Prompt()

Syntax:

   DC_At_Clear() - > nil
   

Arguments:

    None
   

Returns:

    NIL
   

Description:

    DC_AT_CLEAR() is used to clear the array that holds the
    menu prompts created with DC_AT_PROMPT().  This array
    is automatically cleared after calling DC_MENU_TO() so
    it is not necessary to call this function unless you
    wish to simply display menu prompts and not call the
    DC_MENU_TO() function to get a user selection.
   

Examples:

    dc_at_prompt( 10, 10, "Open a File", "Use a new database" )
    DC_AT_CLEAR() // changed my mind
   

Source/Library:

  _DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_at_prompt()
   dc_menu_to()

dc_at_prompt()

A moused replacement for AT..PROMPT

Syntax:

   DC_At_Prompt( < nRow >, ;
                 < nCol >, ;
                 < cPrompt >, ;
                 [< cMessage >] ) - > nil
   

Arguments:

   < nRow > is the screen row to display the prompt.
   
   < nCol > is the screen column to display the prompt.
   
   < cPrompt > is the prompt to display on the screen.
   
   < cMessage > is an optional message to display at the coordinates
   defined by the SET MESSAGE environment variable or by the
   message coordinates passed to DC_MENU_TO().
   

Returns:

    NIL
   

Description:

    DC_AT_PROMPT() is used with DC_MENU_TO() to replace Clipper
    @..PROMPT / MENU TO commands with a "mouseable" menu prompt
    system. The prompts and menu will behave exactly like the
    Clipper MENU TO system except the left button of the mouse will
    high-light the selected prompt, and the right button performs
    the same function as the <þENTERþ> key.
   

Examples:

    // display prompts
    DC_AT_PROMPT( 10, 10, "Open a File", "Use a new database" )
    DC_AT_PROMPT( 12, 10, "Open an Index", "Use an Index file" )
    DC_AT_PROMPT( 14, 10, "Edit database", "Browse all records" )
   
    // get a user selection and display message at row 20, col 25
    nChoice := dc_menu_to( 1, 20, 25 )
   

Source/Library:

  _DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_at_clear()
   dc_menu_to()

dc_atnext()

Find the next occurrence of a string in another string

Syntax:

   DC_AtNext ( < cCharacter >, ;
               < cString >, ;
               < nOccurrence > ) - > nPosition
   

Arguments:

   < cCharacter > is the character or substring to search.
   
   < cString > is the string to search.
   
   < nOccurrence > is the occurrence of < cCharacter > in
   < cString > to
   find.
   

Returns:

    The numeric location of the <þnOccurenceþ> of <þcCharacterþ>
   in
    <þcStringþ>.  If not found then 0 is returned.
   

Description:

    DC_ATNEXT() is used to return the location of the nth occurence
    of a substring within a string.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL cString
   
    DC_Gui(.t.)
   
    cString := 'this is a test'
   
    DC_MsgBox( { cString, ;
                 DC_ATNEXT( 'is', cString, 1 ), ;
                 DC_ATNEXT( 'is', cString, 2 ) } )
   
    RETURN
   

Source/Library:

  _DCATNXT.PRG/.OBJ, DCLIPX.LIB

dc_atoattr()

Convert a Clipper color string to a screen color attribute

Syntax:

   DC_AtoAttr ( < cColorString > ) - > nColor
   

Arguments:

   < cColorString > is a valid Clipper color string.
   

Returns:

    A character string.
   

Description:

    DC_ATOATTR() is used to convert a Clipper color string to
    a numeric screen attribute. Screen attributes are represented
    as a number from 0 to 255 for a total of 256 colors.  Clipper
    functions require that a color string be used for setting
    colors rather than a number.
   

Examples:

    PROCEDURE XTest()
   
    DC_Gui(.t.)
   
    DC_MsgBox( { DC_ATOATTR( 'R/GR' ), ;
                 DC_ATOATTR( 'N/N' ), ;
                 DC_ATOATTR( 'W+*/W' ) } )
   
    RETURN
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_attrtoa()

dc_attrtoa()

Convert a screen color attribute to a color string

Syntax:

   DC_AttrtoA ( < nColor > ) - > cColorString
   

Arguments:

   < nColor > is a number from 0 to 256.
   

Returns:

    A character string.
   

Description:

    DC_ATTRTOA() is used to convert a screen attribute to a
    color string.  Screen attributes are represented as a
    number from 0 to 255 for a total of 256 colors.  Clipper
    functions require that a color string be used for setting
    colors rather than a number.
   

Examples:

    PROCEDURE XTest()
   
    DC_Gui(.t.)
   
    DC_MsgBox( { DC_ATOATTR( 'R/GR' ), ;
                 DC_ATOATTR( 'N/N' ), ;
                 DC_ATOATTR( 'W+*/W' ) } )
   
    RETURN
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_atoattr()

dc_autoresize()

Resize all objects to fit on the resized parent

Syntax:

   DC_AutoReSize( < aOldSize >, ;
                  < aNewSize >, ;
                  < oParent >, ;
                  < aGetList >, ;
                  < lToolBars > ) - > nil
   

Arguments:

   < aOldSize > is a 2 element array containing the width and height
   in pixels of the dialog window before resize.
   
   < aNewSize > is a 2 element array containing the widht and height
   in pixels of the dialog window after resize.
   
   < oParent > is the parent object.
   
   < aGetList > is the GetList array that was passed to DC_ReadGui().
   
   < lToolBars > if .FALSE. will not resize DCTOOLBAR or XbpPushButton
   objects.  These objects, if using bitmaps can truncate the image
   when resized.  The position of the ToolBar or PushButton will
   change accordingly but the size will not change.  The default
   is .TRUE. (resize all toolbars and pushbuttons).
   

Returns:

    NIL.
   

Description:

   DC_AutoReSize() is used to automatically resize and reposition
   all child objects so they use the real estate of the parent in
   the same proportions as the child objects before the parent was
   resized.
   
   DC_AutoReSize() is designed to be placed in a code block that is
   attached to the :resize callback slot of the parent object.
   
   The complete childlist tree is resized.
   

Notes:

   DC_AutoReSize() will not resize or reposition anything on a
   dialog that was painted with a Gra*() function or a DCGRA*
   command.
   
   Due to a bug in Xbase++ 1.3 make sure to add o:hide() and o:show()
   to your resize code block or the screen may leave some undesirable
   side effects after resizing objects.
   

Examples:

   FUNCTION XTest()
   
   LOCAL GetList := {}, oDesc, oBrowse
   
   USE COLLECT VIA DBFNTX
   
   @ 12,0 DCSAY COLLECT->descrip SAYSIZE 50 ;
      SAYOBJECT oDesc COLOR GRA_CLR_BLUE FONT '12.Courier Bold'
   
   @ .5,.5 DCBROWSE oBrowse ALIAS 'COLLECT' SIZE 49,9 ;
         EVAL {|o|o:itemMarked := {||oDesc:setCaption(COLLECT->descrip)} } ;
         HEADLINES 2 DELIMITER CHR(13)+CHR(10)
   
   DCBROWSECOL FIELD COLLECT->descrip HEADER
   "Description"+CHR(13)+CHR(10)+"Line 2" ;
      PARENT oBrowse WIDTH 50
   
   DCREAD GUI FIT ADDBUTTONS ;
      EVAL {|o| o:resize := ;
          {|a,b,o|DC_AUTORESIZE(a,b,o,GetList),o:hide(),o:show()} }
   
   RETURN nil
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   DCGETOPTIONS

DC_AutoRestoreBrowse()

Automatically Save/Restore Browse Configurations.

Syntax:

   DC_AutoRestoreBrowse( [< aParams >] ) - > aOldParams
   

Arguments:

   
   < aParams > is a 2-element array.
   
   Element Type Description
   ------- ---- ------------------------------------------------------
    [1]    N/B  The key value of the registry item to write.  The
                default is HKEY_LOCAL_MACHINE.
   
                The available options are defined in DCREG.CH.
   
                HKEY_NO_KEY
                HKEY_CLASSES_ROOT
                HKEY_CURRENT_USER
                HKEY_LOCAL_MACHINE
                HKEY_USERS
   
                Optionally, this element may contain a codeblock to evaluate.
                If this is a codeblock, then the registry will not be used.
                Instead, the codeblock is evaluated when saving or restoring
                the coordinate array.  When writing, 2 parameters are passed
                to the codeblock: (1) the window title and (2) the array of
                coordinates.  When reading, 1 parameter is passed to the
                codeblock () the window title.
   
    [2]    C    The entry name in the registry to store the information.
                This element is not used if Element 1 is a codeblock.
   
    [3]    L    Default Restore / NoRestore mode. If .TRUE. then the
                default for restoring windows is ON and the override clause
                of DCREAD GUI is NOAUTORESTORE.  If .FALSE., then the
                default for restoring windows will be OFF, and the override
                clause of DCREAD GUI is AUTORESTORE.
   

Returns:

   An array of 2 elements.
   

Description:

   DC_AutoRestoreBrowse() is a Get-Set function that is used to
   Get/Set the Registry directory to be used for storing Browse
   column sizes and positions.  Data is saved to the registry when a
   browse is destroyed and is restored from the registry when a browse
   is created.
   
   If the user resizes columns and/or moves columns using the
   DC_XbpBrowse:moveColumn() method, then the information will be
   automatically saved to the registry for restoring later.
   
   The name assigned to the item saved in the registry is the
   function name that contains the DCREAD GUI command concatenated
   with the ID of the DCBROWSE.  This will insure that each name
   is unique (required).
   
   Optionally, the window sizes and coordinates can be written to
   a file or a database by using a custom codeblock.
   

Notes:

   The browse configuration will not be restored unless the
   DCBROWSE command is immediately followed by a set of DCBROWSECOL
   commands in the GetList.
   
   DCBROWSE commands must have a unique ID for this feature to be
   activated.  The ID must only be unique if there are multiple
   DCBROWSE windows in the same procedure or function.
   

Examples:

   aParams := { HKEY_LOCAL_MACHINE, ;
                '\Software\Donnay Software\Xdemo\Browses' }
   
   DC_AutoRestoreBrowse(aParams)
   
   
   For more samples see \exp19\samples\autorestore.
   

Source/Library:

  _DCGETBX.PRG

See Also:

   @ DCBROWSE
   DC_AutoRestoreWindow()
   DC_RegWrite()
   DC_RegQuery()

DC_AutoRestoreWindow()

Automatically Save/Restore window coordinates

Syntax:

   DC_AutoRestoreWindow( [< aParams >] ) - > aOldParams
   

Arguments:

   < aParams > is a 3-element array.
   
   Element Type Description
   ------- ---- ------------------------------------------------------
    [1]    N/B  The key value of the registry item to write.  The
                default is HKEY_LOCAL_MACHINE.
   
                The available options are defined in DCREG.CH.
   
                HKEY_NO_KEY
                HKEY_CLASSES_ROOT
                HKEY_CURRENT_USER
                HKEY_LOCAL_MACHINE
                HKEY_USERS
   
                Optionally, this element may contain a codeblock to evaluate.
                If this is a codeblock, then the registry will not be used.
                Instead, the codeblock is evaluated when saving or restoring
                the coordinate array.  When writing, 2 parameters are passed
                to the codeblock: (1) the window title and (2) the array of
                coordinates.  When reading, 1 parameter is passed to the
                codeblock () the window title.
   
    [2]    C    The entry name in the registry to store the information.
                This element is not used if Element 1 is a codeblock.
   
    [3]    L    Default Restore / NoRestore mode. If .TRUE. then the
                default for restoring windows is ON and the override clause
                of DCREAD GUI is NOAUTORESTORE.  If .FALSE., then the
                default for restoring windows will be OFF, and the override
                clause of DCREAD GUI is AUTORESTORE.
   

Returns:

   An array of 2 elements.
   

Description:

   DC_AutoRestoreWindow() is a Get-Set function that is used to
   Get/Set the Registry directory to be used for storing window
   sizes and coordinates.  Data is saved to the registry when a
   window is closed and is restored from the registry when a window
   is created.
   
   The name assigned to the item saved in the registry is the
   function name that contains the DCREAD GUI command concatenated
   with the title of the window.  This will insure that each name
   is unique (required).
   
   Optionally, the window sizes and coordinates can be written to
   a file or a database by using a custom codeblock.
   

Notes:

   The window size will not be restored if the NORESIZE clause of
   DCGETOPTIONS was used when creating the window.  Only the position
   of the window will be restored.
   

Examples:

   aParams := { HKEY_LOCAL_MACHINE, ;
                '\Software\Donnay Software\Xdemo\Windows' }
   
   DC_AutoRestoreWindow(aParams)
   
   For more samples see \exp19\samples\autorestore.
   

Source/Library:

  _DCGETBX.PRG

See Also:

   DC_AutoRestoreBrowse()
   DC_RegWrite()
   DC_RegQuery()

dc_average()

Average numeric fields in selected database

Syntax:

    DC_Average() - > lStatus
   

Arguments:

    None.
   

Returns:

    A logical .TRUE. if the average was not aborted.
   

Description:

    DC_Average() is used to average numeric fields from the currently
    selected database based on a set of conditions.  As GUI dialog
    window is displayed for the user to select the conditions.
   

Examples:

    . USE COLLECT
    . DC_Average()
   

Source/Library:

  _DCSUM.PRG, DCLIP2.DLL

See Also:

   SUM

dc_basefont()

A Get-Set function for setting the Base Font for dialog objects

Syntax:

   DC_BaseFont( [< nPointSize >], ;
                [< cFontName >], ;
                [< lBold >] ) - > < cFontCompoundName >
   

Arguments:

   < nPointSize > is the point size.
   
   < cFontName > is the font family name.
   
   < lBold > if .TRUE. will set the font to bold.
   

Description:

   DC_BaseFont() is a Get-Set function that is used to set the base font for
   dialog items.
   
   The default is 8.MS Sans Serif
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

dc_batch()

Process a Batch file with Dot-Prompt commands

Syntax:

   dc_batch ( < cFileName >, ;
              [< c1 >], ;
              [< c2 >], ;
              [< c3 >], ;
              [< c4 >], ;
              [< c5 >] ) - > nil
   

Arguments:

   < cFileName > is the name of the batch file to run.  If the
   extension is not given then .DCB is assumed.
   
   < c1 > , < c2 >, < c3 >, < c4 >, < c5 >
   are optional parameters that are
   received in the batch file via the PARAMETERS command.
   

Returns:

    Nil.
   

Description:

    DC_Batch() will execute all commands in a .DCB batch file in
    sequential order.   A batch file can include any commands which
    can be entered at the dot-prompt and executed by the eXPress++
    interpreter other than structural commands, like DO WHILE, DO CASE
    IF..ENDIF or FOR..NEXT.  All commands in DCSTD.CH, DCDIALOG.CH,
    or DCCUSTOM.CH may be used in batch files.DC_BATCH() is used to open and
   execute a .DCB batch file. A
    "batch" file can contain any commands that can be interpreted
    at the dot prompt, including commands in .CH files which
    have been included in DCCUSTOM.CH.
   

Notes:

    DC_Dot() will automatically execute an AUTOEXEC.DCB batch file
    found in the directory containing the executable program or
    the or the directory named by the dos SET DCLIP=<þdirectoryþ>
    environment setting.
   

Examples:

   DC_BATCH('test.dcb',Date(),Time())    // run TEST.DCB file
   
   * TEST.DCB
   
   PARAMETERS dDate, cTime
   
   FOR i := 1 TO 10
     DCQDEBUG dDate + i
   NEXT
   
   DCQDEBUG cTime
   

Source/Library:

  _dcbatch.prg, DCLIP1.DLL

See Also:

   BATCH
   dc_batchnewthread()

dc_batchnewthread()

Process a Batch file in a new thread

Syntax:

   DC_BatchNewThread ( < cFileName >, ;
                       [< c1 >], ;
                       [< c2 >], ;
                       [< c3 >], ;
                       [< c4 >], ;
                       [< c5 >] ) - > nil
   

Arguments:

   < cFileName > is the name of the batch file to run.  If the
   extension is not given then .DCB is assumed.
   
   < c1 > , < c2 >, < c3 >, < c4 >, < c5 >
   are optional parameters that are
   subsituted by  %1 - %5 respectively in the batch file commands.
   

Returns:

    Nil.
   

Description:

    DC_BatchNewThread() functions identically to DC_Batch() except
    it will execute in a new thread.
   

Notes:

    DC_Dot() will automatically execute an AUTOEXEC.DCB batch file
    found in the directory containing the executable program or
    the or the directory named by the dos SET DCLIP=<þdirectoryþ>
    environment setting.
   

Examples:

   . DC_BatchNewThread('test.dcb')    // run TEST.DCB file
   

Source/Library:

  _dcbatch.prg, DCLIP1.DLL

See Also:

   BATCH
   dc_batch()

dc_bin2num()

Converts a Binary String to a Number

Syntax:

   DC_Bin2Num( < cBinary > ) - > nDecimal
   

Arguments:

   < cBinary > is a string of up to eight 1's and 0's.
   

Returns:

    A numeric value from 0 - 255
   

Description:

   DC_BIN2NUM() will convert a binary string to a numeric value.
   

Source/Library:

  _DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_bittest()
   dc_xorbits()

dc_bitmapdraw()

Redraw a Bitmap Object on a GUI dialog screen

Syntax:

   DC_BitMapDraw ( < oParent >, ;
                   < ncbResource > ) - > nil
   

Arguments:

   < oParent > is the Static object that contains the presentation
   space for the bitmap.
   
   < ncbResource > may be any of the following:
   
   1. The number of a resource that has been linked to the .EXE
   
   2. A character string with the name of a *.BMP file, a *.JPG file,
      a *.GIF file or a *.PNG file.
   
   
   3. An XbpBitMap() object.
   
   4. A code block which, when evaluated, returns a number, character
      string or XbpBitMap() object.
   

Returns:

    Nil.
   

Description:

    DC_BITMAPDRAW() is used to redraw a Bitmap object that was created
    with the DCBITMAP command and painted on a dialog screen with
    DC_READGUI().
   
    This function is used to load a new *.BMP file into the
    presentation space previously created from the DCBITMAP object
    in the GetList.
   

Examples:

    #include 'dcdialog.ch'
   
    PROCEDURE XTest()
   
    LOCAL GetList := {}, cBitMap1, cBitMap2, oPhoto1, oPhoto2
   
    USE COLLECT NEW SHARED
    SKIP 2
   
    cBitMap1 := COLLECT->bitmap1
    cBitMap2 := COLLECT->bitmap2
   
    @  2,2 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 33,10 ;
       OBJECT oPhoto1
   
    @  2,37 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 33,10 ;
       OBJECT oPhoto2
   
    DCBITMAP cBitMap1 PARENT oPhoto1 AUTOSCALE
   
    DCBITMAP cBitMap2 PARENT oPhoto2 AUTOSCALE
   
    @  1,3  DCSAY 'Photo 1' GET cBitMap1 ;
       SAYRIGHT SAYSIZE 10 ;
       DATALINK {||DC_BitMapDraw(oPhoto1,cBitMap1)}
   
    @  1,38 DCSAY 'Photo 2' GET cBitMap2 ;
       SAYRIGHT SAYSIZE 10 ;
       DATALINK {||DC_BitMapDraw(oPhoto2,cBitMap2)}
   
    DCREAD GUI ;
       FIT ;
       ADDBUTTONS
   
    RETURN
   

Source/Library:

  _DCFUNCT.PRG/.OBJ, DCLIPX.LIB

See Also:

   DCBITMAP
   dc_readgui()
   DIALOG GETLIST

dc_bitmapresourcefile()

Get-Set function used to set a list of resource DLLs for bitmaps

Syntax:

   DC_BitmapResourceFile( [< aDllList >] ) - > aOldDllList
   

Arguments:

   < aDllList > is an array of numeric DLL handles.
   

Returns:

   An array.
   

Description:

   DC_BitmapResourceFile() is a Get-Set function that is used to
   establish a list of resource DLLs for finding bitmaps.  All
   bitmaps in eXpress++ are loaded via the function DC_GetBitmap().
   This function always returns a bitmap object of type XbpBitmap().
   This function now runs through a loop to try to load resources
   from Dlls set with DC_BitmapResourceFile() if the named resource
   is not linked to the EXE, therefore bitmaps with a numeric resource
   ID can now be in multiple DLLs and do not need to be linked to the
   .EXE.
   

Examples:

   nResDll1 := LoadDll('MYBITMAPS.DLL') // load my custom bitmaps
   nResDll2 := LoadDll('DCRES.DLL')     // load eXpress++ bitmaps
   
   DC_BitmapResourceFile( { nResDll1, nResDll2 } )
   
   DCADDBUTTON CAPTION MYBITMAP_PERSON // defined in MYBITMAPS.DLL
   DCADDBUTTON CAPTION BITMAP_HELP_M   // defined in DCRES.DLL
   
   This eliminates the need to use the RESFILE clause when defined
   bitmap captions.  Also, if the RESTYPE clause is not used, then
   the resources must be of type BITMAP, GIF, JPEG, BMP or PNG in
   your resource DLLs.
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_getbitmap()

dc_bitmaptransparentcolor()

Set RGB transparent color for pushbutton bitmaps

Syntax:

   DC_BitmapTransparentColor( [< anColor >] ) - > nOldColor
   

Arguments:

   < anColor > is a 3-element array containing numeric RGB values or
   an numeric equivalent of an RGB color.
   

Returns:

   A numeric value.
   

Description:

   DC_BitmapTransparentColor() is a Get-Set function that is used
   to set the RGB value of the transparent color used with Bitmaps
   that are placed on DCPUSHBUTTON objects.
   

Examples:

   // set the transparent color to medium gray (the background
   // color of the bitmaps)
   
   aColor := { 192, 192, 192 }
   DC_BitmapTransparentColor( aColor )
   
   @ 0,0 DCPUSHBUTTON CAPTION DCBITMAP_FIND_1 SIZE 10,2
   DCREAD GUI FIT
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.DLL

See Also:

   @ DCPUSHBUTTON
   dc_getbitmap()

dc_bittest()

Tests if a bit is set to 1 or 0 in a number

Syntax:

   DC_BitTest( < nDecimal >, ;
               < nBit > ) - > lStatus
   

Arguments:

   < nDecimal > is a numeric value from 0 to 255.
   
   < nBit > is the bit to test.  This is a value from 1 to 8.
   

Returns:

    A logical .TRUE. if the bit is a 1 and a logical .FALSE. if
    the bit is a 0.
   

Description:

   DC_BITTEST() will test for a specified bit in a number.
   

Source/Library:

  _DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_andbits()

dc_blank()

Blank all fields in the current record

Syntax:

    DC_Blank( [< lCommit >] ) - > lStatus
   

Arguments:

   < lCommit > if .TRUE. (default) will commit the changes to disk.
   

Returns:

    A logical .TRUE. if the record was blanked.
   

Description:

    DC_BLANK() is used to blank the contents of all fields in the
    current record of the current work area.  It is not necessary
    to lock the record because DC_BLANK() will also lock and unlock
    the record before blanking the contents.
   

Examples:

    . USE COLLECT
    . GO 5
    . DC_Blank()
   

Source/Library:

  _dcblank.prg, DCLIP1.DLL

See Also:

   BLANK
   dc_isblank()

dc_bof()

Is the record pointer at the beginning of the file?

Syntax:

    DC_Bof() - > lStatus
   

Arguments:

    None.
   

Returns:

    A logical value.
   

Description:

    DC_BOF() is used to test whether or not DC_DbSkip() attempted
    to move the record pointer past the top record in a "scoped"
    set of records when using a negative skip value.  If no scope
    is set or the ADSDBE is being used as the data driver for the
    current work area this function simply calls Bof() therefore
    it can be used as a replacement for Bof().
   

Notes:

Examples:

    DC_SetScope(0,'12001')
    DC_SetScope(1,'12001')
   
    DC_DbGoBottom()
   
    DO WHILE !DC_Bof()
      DC_DbSkip(-1)
    ENDDO
   

Source/Library:

  _DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()
   dc_eof()
   dc_dbskip()
   dc_dbgotop()
   dc_dbgobottom()

dc_browcelledit()

Edit Cells of a Browse Object

Syntax:

   DC_BrowCellEdit( < oBrowse >, ;
                    [< nRow >],  ;
                    [< nCol >],  ;
                    [< nEditMode >],  ;
                    [< lArray >],  ;
                    [< abDefault >],  ;
                    [< bEval >]  ) - > nil
   

Arguments:

   < oBrowse > is the browse object to edit, insert or delete.  This
   must be an object of the XbpBrowse class.
   
   < nRow > is the starting row.  If this argument is not passed,
   then the currently selected row is the default.  < nRow > must
   be a numeric value within the currently visible number of rows.
   
   < nCol > is the starting column.  If this argument is not passed,
   then the currently selected column is the default.  < nCol > must
   be a numeric value between 1 and the total number of columns in
   the browse object.
   
   < nEditMode > is the editing and/or navigation mode.
   
    < nEditMode >             Description
    -----------             ---------------------------------------
    DCGUI_BROWSE_EDITEXIT   Edit - Exit cell editing after ENTER key
    DCGUI_BROWSE_EDITACROSS Edit - Move to next column after ENTER key
    DCGUI_BROWSE_EDITDOWN   Edit - Move to next row after ENTER key
    DCGUI_BROWSE_INSERT     Insert an element or a record
    DCGUI_BROWSE_DELETE     Delete current element or record
   
   < lArray > is a logical value determining if the browsed data is an
   array or a database.  If .TRUE., then it is an array.  If this
   argument is not passed and the browse object was created via the
   DCBROWSE command then this is determined automatically.  If an
   array is being browsed, then the :cargo iVar of the browse object
   must contain an array of at least 5 elements.  Element 5 is a
   pointer to the array being browsed.  Element 4 is a numeric
   value containing a pointer to the currently selected array
   element.
   
   < abDefault > is used only when inserting an array element, ie
   < nMode > is DCGUI_BROWSE_INSERT.  This parameter contains either
   an array or a code block which returns an array.  The array
   contains the default data for the inserted element.  Note: array
   browsers always browse multi-dimensional, symmetrical arrays, so
   this array must contain the same number of sub-elements as each
   array element.
   
   < bEval > is an optional code block to evaluate before inserting,
   deleting, or editing a cell row.
   

Description:

    DC_BrowCellEdit() is used to edit the cells of any browse object.
    Navigation modes allow for moving up and down within the browse
    via the UP, DOWN keys or automatically moving DOWN or ACROSS
    with the ENTER key.
   
    DC_BrowCellEdit() supports WHEN code blocks for each column to
    prevent the editing of a cell and VALID code blocks for each
    column to validate user input.
   
    DC_BrowCellEdit() also is used to delete an element from the
    array being browsed or to insert and edit a new element.
   

Notes:

    The :dataLink iVar of each XbpColumn object in the XbpBrowse
    object is used to store the GET/SET code block for editing the
    cell.  If the XbpColumn objects were created by the DCBROWSECOL
    command using the FIELD <þcFieldþ> clause, then it will automatically
    be created as a GET/SET code block.
   
    The :cargo iVar of each XbpColumn object in the XbpBrowse object
    may be used to store WHEN clause and VALID clause information.
    If the column objects were created by the DCBROWSECOL command
    then the code blocks for these clauses are automatically stored
    in XbpColumn:cargo.  If the XbpColumn objects are NOT created by
    DCBROWSECOL, then you must store an array at least 7 elements in
    length into the XbpColumn:cargo instance variable.
   
    XbpColumn:cargo[6] is used to store the VALID codeblock.  This
    code block is used to validate the input for each column object.
    The value in the editing buffer of the cell is passed to the
    code block, therefore the code block should look like so:
   
     { |c| !Empty(c) }
   
    The value passed is always the same type as the value of the
    field.  The code block must return a logical value.  If a .TRUE.
    is returned or the value  stored in XbpColumn:cargo is not an
    array or the value stored in XbpColumn:cargo[6] is not a code
    block, then the value entered will be stored.  If a .FALSE. is
    returned, then the editing window cannot be exited until a
    .TRUE. is returned or the ESCape key is pressed.
   
    XbpColumn:cargo[7] is used to store the WHEN codeblock.  This
    code block is used to prevent editing of a cell.  It must always
    return a logical value.  If a .TRUE. is returned or the value
    stored in XbpColumn:cargo is not an array or the value stored
    in XbpColumn:cargo[7] is not a code block, then the cell can be
    edited.  If a .FALSE. is returned, then the cell will be skipped.
   

Examples:

    #include 'dcdialog.ch'
   
    PROCEDURE XTest()
   
    LOCAL GetList := {}, oBrowBox, oBrowse, oToolBar, GetOptions
   
    USE COLLECT NEW SHARED
   
    @  3,0 DCSTATIC XBPSTATIC_TYPE_RECESSEDBOX SIZE 78,12 ;
       OBJECT oBrowBox
   
    @ .1,.5 DCBROWSE oBrowse PARENT oBrowBox ALIAS 'COLLECT' ;
      SIZE 77,11.8
   
    DCBROWSECOL FIELD COLLECT->descrip ;
     HEADER "Description" PARENT oBrowse
   
    DCBROWSECOL FIELD COLLECT->type ;
     HEADER "Type" PARENT oBrowse
   
    DCBROWSECOL FIELD COLLECT->sub_type ;
     HEADER "SubType" PARENT oBrowse
   
    DCBROWSECOL FIELD COLLECT->location ;
     HEADER "Location" PARENT oBrowse
   
    DCBROWSECOL FIELD COLLECT->date_orig ;
     HEADER "Orig Date" PARENT oBrowse
   
    DCBROWSECOL FIELD COLLECT->date_acqu ;
     HEADER "Acqu Date" PARENT oBrowse
   
    DCTOOLBAR oToolBar
   
    DCADDBUTTON CAPTION 'Edit Down' ;
      SIZE 10 ;
      PARENT oToolBar ;
      ACTION {||DC_BrowCellEdit( oBrowse,,,DCGUI_BROWSE_EDITDOWN ) }
   
    DCADDBUTTON CAPTION 'Edit Across' ;
      PARENT oToolBar ;
      SIZE 10 ;
      ACTION {||DC_BrowCellEdit( oBrowse,,1,DCGUI_BROWSE_EDITACROSS ) }
   
    DCGETOPTIONS ;
      WINDOW WIDTH 560 ;
      WINDOW HEIGHT 350
   
    DCREAD GUI ;
      OPTIONS GetOptions ;
      ADDBUTTONS ;
      EVAL {||oBrowse:hide(), oBrowse:show()}
   
    RETURN
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.LIB

See Also:

   @ DCBROWSE

dc_browcelleditexit()

Force an exit of the Browse Cell Editor

Syntax:

    DC_BrowCellEditExit( [< nMode >] ) - > nOldMode
   

Arguments:

   < nMode > is the value to return from the Cell Editor event handler.
   This should be either DCGUI_EXIT_ABORT or DCGUI_EXIT_OK.
   
   DCGUI_EXIT_ABORT is the same as pressing the ESCAPE key.
   DCGUI_EXIT_OK is the same as pressing the ENTER key.
   

Returns:

    A numeric value.
   

Description:

    DC_BrowCellEditExit() is used in a cell editor validation clause
    to force an exit of the cell editor.
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.LIB

See Also:

   @ DCBROWSE
   dc_browcelledit()

dc_browpres()

A Get/Set function for browse presentation parameters.

Syntax:

   DC_BrowPres([< aPres >, ;
               [< nFrame >]) - > aPres
   

Arguments:

   < aPres > is an array of browse presentation parameters that
   conforms to the specification of parameters described in the
   Xbase++ documentation for XbpBrowse().
   
   < nFrame > is used to set the frame type for the hilighlight bar.
   Each frame type is defined in DCDIALOG.CH as a DCGUI_BROWSEFRAME_*
   constant.
   
   Example: @ DCBROWSE .. PRESENTATION ;
              DC_BrowPres(,DCGUI_BROWSEFRAME_THICK_RECESSED)
   

Returns:

   A presentation parameters array.
   

Description:

   DC_BrowPres() is a Get/Set function that is used to Get or Set
   a presentation parameters array for browse windows.
   
   DC_BrowPres() returns a default set of browse paramaters if a
   user-defined set of parameters is not set.
   

Examples:

   aBrowPres := ;
     { { XBP_PP_COL_HA_FGCLR, GRA_CLR_WHITE },            /* Header FG Color  */
   ;
       { XBP_PP_COL_HA_BGCLR, GRA_CLR_DARKGRAY },         /* Header BG Color  */
   ;
       { XBP_PP_COL_DA_ROWSEPARATOR, XBPCOL_SEP_DOTTED }, /* Row Sep          */
   ;
       { XBP_PP_COL_DA_COLSEPARATOR, XBPCOL_SEP_DOTTED }, /* Col Sep          */
   ;
       { XBP_PP_COL_DA_FGCLR, GRA_CLR_BLACK },            /* Row FG Color     */
   ;
       { XBP_PP_COL_DA_BGCLR, GRA_CLR_WHITE },            /* Row BG Color     */
   ;
       { XBP_PP_COL_DA_ROWHEIGHT, 16 },                   /* Row Height       */
   ;
       { XBP_PP_COL_HA_HEIGHT, 10 },                      /* Header Height    */
   ;
       { XBP_PP_HILITE_FGCLR, GRA_CLR_WHITE },            /* Hilite FG color  */
   ;
       { XBP_PP_HILITE_BGCLR, GRA_CLR_DARKBLUE },         /* Hilite BG color  */
   ;
       { XBP_PP_COL_FA_FGCLR, GRA_CLR_WHITE },            /* Footer FG Color  */
   ;
       { XBP_PP_COL_FA_BGCLR, GRA_CLR_DARKGRAY },         /* Footer BG Color  */
   ;
       { XBP_PP_COL_FA_HEIGHT, 10 }                       /* Footer Height    */
   ;
     }
   
   DC_BrowPres(aBrowPres)
   
   @ 1,1 DCBROWSE oBrowse PRESENTATION DC_BrowPres()
   

Source/Library:

  _dcpres.prg

See Also:

   @ DCBROWSE

dc_browseautoseek()

Seek a record/array element based on a data entered into a GET

Syntax:

   DC_BrowseAutoSeek( < nKey >, ;
                      < oGET >, ;
                      < oBrowse >, ;
                      [< aData >], ;
                      [< nColumn >], ;
                      [< bcPrefix >], ;
                      [< bFormat >], ;
                      [< nSeekDelay >], ;
                      [< bSeek >], ;
                      [@< nPointer >] ) - > NIL
   

Arguments:

   < nKey > is the numeric value of the key pressed.
   
   < oGET > is the DCGET object that is being used to enter the seek
   string.
   
   < oBrowse > is the @..DCBROWSE object that will be refreshed.
   
   < aData > is the array being browsed.  If this parameter is not
   used then it is assumed that a database is being browsed.
   
   < nColumn > is the column element of the array to scan for a
   match.  This parameter is used only with < aData > and is a
   required parameter when browsing an array.
   
   < bcPrefix > is the a value to insert at the beginning of the
   seek string.  If a code block, then it must return a string.
   
   < bFormat > is a seek string code block. The user input buffer
   passed to this code block and the return value of code block
   is used for the seek.
   
   ex: {|c|Right(Space(7)+Alltrim(cString),7)}
   
   < nSeekDelay > is the number of seconds after a key is pressed to
   wait before performing the seek.  This allows a string to be
   typed without performing a seek everytime a key is pressed.
   The default is .1 seconds.
   
   < bSeek > is a code block to use to do the actual seek.  If this
   argument is not used then the function DC_DbSeek() will be used.
   The code block will receive the keyboard buffer as an argument.
   The code block must return a logical value - .TRUE. if record
   was found, .FALSE. if not found.
   
   @< nPointer > is a numeric variable (passed by reference) to store
   the array element selected when the user double-clicks on the
   browse or presses ENTER.  This value will be stored only when
   using an array.
   

Returns:

    NIL.
   

Description:

   When browsing a database, DC_BrowseAutoSeek() is used to
   automatically seek to a record in a database that matches the
   text entered into a GET and refresh an associated browse object.
   
   When browsing an array, DC_BrowseAutoSeek() is used to
   automatically seek to an element of the array that matches the
   text entered into a GET and refresh an associated browse object.
   
   DC_BrowseAutoSeek() is intended to be used in a codeblock that
   is assigned to the :keyboard callback slot of a DCGET object or
   the GET portion of an @..DCSAY..GET object.  It is also intended
   to be used with an @..DCBROWSE object.
   

Notes:

   When browsing a database, an index must be in focus and the
   key of the index must match whatever is being entered by the
   user into the GET.
   
   The seek is a SOFTSEEK, meaning that the record that closely
   matches the entered data will be selected.
   
   When browsing an array the <þnColumnþ> element of the array must
   match whatever is being entered by the user into the GET.
   

Examples:

   FUNCTION XTest
   
   LOCAL GetList := {}, cSeek := Space(20), oBrowse
   
   SET DEFA TO ..\XDOC
   USE EXPRESS VIA FOXCDX EXCLUSIVE ALIAS 'XDOC'
   SET INDEX TO EXPRESS.CDX
   OrdSetFocus('COMMAND')
   SET DEFA TO
   
   @ 1,1 DCSAY 'Seek' GET cSeek SAYRIGHT PICT '@!' ;
         KEYBLOCK {|a,b,o|DC_BrowseAutoSeek(a,o,oBrowse)}
   
   @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' SIZE 77,11.8
   
   DCBROWSECOL FIELD XDOC->command HEADER "Command" PARENT oBrowse ;
     WIDTH 7
   
   DCBROWSECOL FIELD XDOC->type  HEADER "Type" PARENT oBrowse ;
     WIDTH 6
   
   DCBROWSECOL FIELD XDOC->category HEADER "Category" PARENT oBrowse ;
     WIDTH 6
   
   DCBROWSECOL FIELD XDOC->short HEADER "Short Description" PARENT oBrowse
   
   DCBROWSECOL FIELD XDOC->module HEADER "Module" PARENT oBrowse ;
   
   DCBROWSECOL FIELD XDOC->see_also HEADER "See Also" PARENT oBrowse
   
   DCBROWSECOL DATA {||XDOC->(recno())} HEADER "Record" PARENT oBrowse ;
     WIDTH 4
   
   DCREAD GUI ;
       TITLE 'DC_BrowseAutoSeek() Demo' ;
       FIT ;
       ADDBUTTONS
   
   RETURN nil
   

Source/Library:

  _DCFINDX.PRG, DCLIPX.DLL

See Also:

   @ DCBROWSE
   dc_findbrowse()

dc_browsecolor()

Set the default color for alternate rows of a DCBROWSE

Syntax:

   DC_BrowseColor( [< aColors >] ) - > aOldColors
   

Arguments:

   < aColors > is an array of 4 colors.
   
   Each color may be defined as a numeric value or a 3-element
   array of RGB colors.
   
   Element  Type  Description
   -------  ----  -----------------------------------------------
      1      A/N  Odd row foreground color
      2      A/N  Odd row background color
      3      A/N  Even row foreground color
      4      A/N  Even row background color
   

Returns:

   An array.
   

Description:

   DC_BrowseColor() is used to establish the default colors for
   alternate rows of all DCBROWSE objects.  These colors will be
   invoked only if the COLOR clause of DCBROWSE is not used.
   

Examples:

   DC_BrowseColor( { nil, GRA_CLR_WHITE, nil, GRA_CLR_CYAN } )
   

Source/Library:

  _DCXBROW.PRG

See Also:

   @ DCBROWSE

dc_browsedb()

A text-based Database browsing system

Syntax:

   DC_BrowseDb ( [< aOptions >], ;
                 [< aFields >], ;
                 [< cUdfName >], ;
                 [< lExit >], ;
                 [< lReSize >], ;
                 [< lRestoreScreen >], ;
                 [< cConfigFile >], ;
                 [< lEditDb >], ;
                 [< lProtect >], ;
                 [< aMenu >], ;
                 [< aKeys >], ;
                 [< aMouse >], ;
                 [< lBackGround >] ) - > Nil
   

Arguments:

   < aOptions > is an array of parameters to define the size and
   style of the browse window.
   
   Element Type  Description
   ------- ---- ---------------------------------------------
   
    [ 1]    L   .t. - Pick-list operation.  Will only display
                      menu options for window configuration and
                      searching for a record.  Use this mode
                      when you want the user to choose a field
                      and/or record and exit with the RETURN key.
                .f. - Normal operation. (default).
   
    [ 2]    L   .t. - Protect data from being changed by user
                .f. - Allow data modification ( Default )
   
    [ 3]    N   Start Display Row  ( 0 is default )
   
    [ 4]    N   Start Display Column  ( 0 is default )
   
    [ 5]    N   End Display Row  ( 24 is default )
   
    [ 6]    N   End Display Column  ( 79 is default )
   
    [ 7]    L  .t. - Display File Data at bottom of window
               .f. - Don't Display File Data ( Default )
   
    [ 8]    L  .t. - Don't display a shadow around the window
               .f. - Display a shadow around window ( Default )
   
    [ 9]    L  .t. - Display a record number column ( Default )
               .f. - Don't display record numbers
   
    [10]    L  .t. - Set the TAB for this window ( Default )
               .f. - Don't set the TAB
   
    [11]    L  .t. - Automatic update of Relational Windows
               .f. - Don't update Relational Windows ( Default )
   
    [12]    L  .t. - One-To-Many Browse configuration
               .f. - Standard configuration ( Default )
   
    [13]    L  .t. - Sticky-Browse mode ON
               .f. - Sticky-Browse mode OFF ( Default )
   
    [14]    L  .t. - Display all child relational fields (Default)
               .f. - Don't display child fields
   
    [15]    L  .t. - Automatic update of Full-screen edit window
               .f. - Don't update Edit window (Default)
   
    [16]    L  .t. - Display a Record Tagging Column.
   
    [17]    N  Inkey value of keyboard key to use for record
               tagging with [16] is .TRUE.  Default is SPACE BAR
               (32)
   
    [18]    L  .t. - Fast Paint option.  Paints browse screens
                     faster if they contain long memo fields.  This
                     option will not display memo fields with the
                     capitalized "MEMO" when they are not empty.
               .f. - Display "MEMO" when memo fields are not empty
                     otherwise display "memo".  (Default)
   
    [19]    L  .t. - Display totals at the bottom of all numeric
                     columns.  This option can take a long time to
                     start-up the browse while totals are being
                     calculated.
               .f. - Don't display totals. (Default)
   
    [20]    L  .t. - Display menu bar at the top of the physical
                     screen (Row 0, Column 0)
               .f. - Display menu bar at the top of the browse
                     window (Default).
   
    [21]    L  .t. - PICK-EDIT mode.  In this mode, pressing the
                     ENTER key will exit the browse with the record
                     pointer at the selected record.  This is
                     different than PICK-LIST mode above, however,
                     because this option still allows editing by
                     selecting ADD or EDIT from the menus.
               .f. - ENTER key will edit currently selected field.
   
    [22]    L  .t. - AUTOSEEK mode. Overrides setting of Autoseek
                     that was saved in Browse configuration.
   
    [23]    C  Description of the Browse
   
    [24]    C  A list of relational browse windows separated by
               commas.
   
   < aFields > is a 2-dimensional array of field names and headings.
   If this argument is not passed, then all fields will appear in
   the display with the field name used as the heading. There
   should be one element in the second array for each element in
   the first array.
   
    Example:
   
    { { 'CUST_NAME','CUST_NMBR','STREET1','CITY','STATE','ZIP' }, ;
      { 'Customer;Name','Number','Street','City','State','Zip' } }
   
    Note: Use semicolon (;) character(s) in the heading to break the
          heading display into multiple rows.
   
   
   < cUdfName > is the name of a User-Defined Function to call
   after each keystroke.
   
   < lExit > if .TRUE. will paint the display and items on the
   screen then return. .FALSE. is Default.
   
   < lReSize > if .TRUE. will simply resize the browse window to
   the new coordinates passed in < aOptions > and not affect the
   previous browse configuration.
   
   < lRestoreScreen > if .TRUE. (default) will restore the screen
   upon exiting the browse, otherwise all the browse screens
   will remain on the display.
   
   < cConfigFile > is the name of a *.DBR file to use as the
   browse configuration.  A *.DBR file is created by the
   "Save Configuration to a File" selection from the FILES
   menu after configuring the browse screen as desired.  If no
   path is included in the file name, then the file must exist
   in the same directory as the currently selected database.
   
   < lEditDb > if .TRUE. will automatically paint a full-screen
   EDIT window and update it every time the record pointer
   changes in the browse window.  Use this parameter when you
   want to see both a full-screen edit view and a browse view
   at the same time.  Using this parameter is the same as
   selecting "Automatic Update of Edit Window ON" from the
   VIEW menu.  The default is .FALSE. or OFF.
   
   < lProtect > if .TRUE. will protect the database from being
   modified by the user.  The default is .FALSE.
   
   < aMenu > is an optional array which is used to replace the
   default Browse pull-down menus.  The menu array must conform
   to the specification of the array returned by the
   function DC_MENUEDIT() or DC_MENULOAD().  If < aMenu > is
   a character string, then the string must contain the
   NAME of the menu as contained in the menu dictionary file
   (DCMENU.DBF).
   
   < aKeys > is an optional array which is used to replace, add
   or delete hot-keys from the Browse defaults.  The key array
   must conform to the specification of the array returned by
   the function DC_KEYEDIT() or DC_KEYLOAD().  If < aKeys > is
   a character string, then the string must contain the
   NAME of the key-set as contained in the key dictionary file
   (DCKEY.DBF).
   
   < aMouse > is an optional array which is used to add to the
   default mouse-actions.  The mouse array must conform
   to the specification of the array defined for use by the
   function DC_MOUSEKEYS() or returned by the function
   DC_MOUSEEDIT() or DC_MOUSELOAD().  If < aMouse > is a
   character string, then the string must contain the
   NAME of the mouse-set as contained in the mouse dictionary
   file (DCMOUSE.DBF).
   
   < lBackGround > if .TRUE. (default) will paint a default
   background and all browse screens for all work areas.  If
   .FALSE., then only the browse screen for the current work
   area will be displayed over the existing screen.
   

Returns:

    Nil
   

Description:

    DC_BROWSEDB() is a Multi-Window database browsing system that
    can be used as a complete menu-driven DBMS.  DC_BROWSEDB() is
    the base system for all Text-Based browsing features.  This is an
    array-driven system, ie, a multi-dimensional array ( DCBROWSE )
    object is used to store all the parameters for all work areas.
   
    DC_BROWSEDB() supports a complete set of menus and options:
    Edit, View, File, Search, Print, Utilities, etc.  The text-based
    browse system supports the following features:
   
    1. Cut and Paste
    2. Keyboard Macros
    3. User-configuration
    4. Multi-window browsing
    5. Relational browsing
    6. Sticky browsing
    7. Pick-list operation
   
    See the section titled BROWSE for a complete description of how
    to use the DC_BROWSEDB() function.
   

Examples:

    use customer
    DC_BROWSEDB()
    use invoice new
    DC_BROWSEDB( { , , 0, 0, 24, 39 } )
    use invitems new
    set relation to inv_nmbr into invoice
    DC_BROWSEDB( { , , 0, 40, 24, 79, , , .t., .f., , .t., .t. } )
   

Source/Library:

  _DCBROW.PRG

See Also:

   BROWSE

dc_browsegetlist()

A Browse-view of a GetList array (for debugging)

Syntax:

   DC_BrowseGetList( < aGetList > ) - > nil
   

Returns:

   Nil.
   

Description:

   DC_BrowseGetList() is used to browse an entire GetList array
   in a Multi-dimensional view.  This utility helps in debugging
   dialogs.
   

Examples:

   FUNCTION XTest()
   
   LOCAL GetList[0], dDate := Date()
   
   @ 0,0 DCSAY 'Enter Date' GET dDate
   
   DCREAD GUI FIT ;
     EVAL {||DC_BrowseGetList(GetList)}
   
   RETURN nil
   

Source/Library:

  DCLIP1.LIB, DCLIP1.DLL

dc_browserow()

Set or return the row (element) of a browse

Syntax:

    DC_BrowseRow( < oBrowse >, ;
                  [< nRow >] ) - > nRow
   

Arguments:

   < oBrowse > is the browse object.
   
   < nRow > is the element in the browse to select.
   

Returns:

    The numeric value of the current row (array element).
   

Description:

   DC_BrowseRow() is used to Get or Set the row of a browse object
   which was created by the @ DCBROWSE command.  This function is
   used only when browsing arrays.
   
   DC_BrowseRow() is used when it is necessary to seek an element
   of the array being browsed, then update the row pointer and
   refresh the browse.
   

Examples:

   #include 'dcdialog.ch'
   
   FUNCTION XTest()
   
   LOCAL GetList := {}, aDir := Directory(), oBrowse, aRef[2]
   
   @ 0,0 DCBROWSE oBrowse SIZE 50,10 DATA aDir ;
      PRESENTATION DC_BrowPres() NOHSCROLL
   DCBROWSECOL ELEMENT 1 HEADER 'File Name' WIDTH 15 PARENT oBrowse
   DCBROWSECOL ELEMENT 2 HEADER 'File Size' WIDTH 13 PARENT oBrowse
   
   DCREAD GUI FIT ADDBUTTONS ;
      HANDLER MyHandler REFERENCE aRef ;
      EVAL {|| aRef[1]:=oBrowse, aRef[2]:=aDir, ;
               SetAppFocus(oBrowse:getColumn(1)) }
   
   RETURN nil
   
   * -----------------
   
   STATIC FUNCTION MyHandler( nEvent, mp1, mp2, oXbp, ;
                              oDlg, GetList, aRef )
   
   LOCAL oBrowse := aRef[1], aDir := aRef[2], nFound
   
   IF nEvent == xbeP_Keyboard
     nFound := ;
       AScan( aDir, {|a|Upper(Substr(a[1],1,1))==Upper(Chr(mp1))} )
     IF nFound > 0
       DC_BrowseRow( oBrowse, nFound )
       oBrowse:refreshAll()
     ENDIF
   ENDIF
   
   RETURN DCGUI_NONE
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.LIB

See Also:

   @ DCBROWSE
   dc_getcolarray()

dc_browsesort()

Set Sort Header options for @..DCBROWSE

Syntax:

    DC_BrowseSort( [< aSortOptions >] ) - > aOldOptions
   

Arguments:

   < aSortOptions > is an array of 6 elements.
   
   Element    Description
   ------- -------------------------------------------------------
    1 / 2  Used to set the foreground and background color of the
           column heading that is chosen as the controlling sort
           order when clicking the mouse in the column heading.
           See the SORT clause of DCBROWSECOL.
   
    3 / 4  Used to set the foreground and background color of the
           column headings that are not the controlling sort order
           and are not selectable.  These columns will not change
           the sort order when the mouse is clicked in the header.
   
    5 / 6  Use to set the UP arrow and DOWN arrow bitmaps that are
           used in the column header of the sorted column when
           the order is "ascending" or "descending" respectively.
   
           NOTE: These are no longer used.  Instead, special Marlett
                 font characters are used.
   
    7 / 8  Used to set the foreground and background color of the
           column headings that are not the controlling sort order
           but are selectable.  These columns will change the sort
           order when the mouse is clicked in the header.
   

Returns:

   An array containing the old sort options.
   

Description:

   DC_BROWSESORT() is used to set the column heading options
   for @..DCBROWSE when using the sort feature that is activated
   by clicking in the header column.
   

Examples:

   aSort := Array(6)
   
   aSort[1] := GRA_CLR_WHITE // Sort Selected Color (Foreground)
   aSort[2] := GRA_CLR_RED   // Sort Selected Color (Background)
   aSort[3] := GRA_CLR_WHITE // Sort Non-Selectable Color (Foreground)
   aSort[4] := GRA_CLR_DARKGRAY // Sort Non-Selectable Color (Background)
   aSort[5] := nil
   aSort[6] := nil
   aSort[7] := GRA_CLR_WHITE // Sort Unselected Color (Foreground)
   aSort[8] := GRA_CLR_BLUE  // Sort Unselected Color (Background)
   aSaveSort := DC_BrowseSort(aSort)
   
   @ 10,1 DCBROWSE oBrowse
   
   DCREAD GUI
   
   DC_BrowseSort(aSaveSort)
   

Source/Library:

  _DCXBROW.PRG, DCLIPX.DLL

See Also:

   @ DCBROWSE

dc_busyoff()

Destroy a busy window created with DC_BusyOn()

Syntax:

   DC_BusyOff( < oBusyDlg > ) - > nil
   

Arguments:

   < oBusyDlg > is a pointer to a dialog window created by
   DC_BusyOn().
   

Description:

   DC_BusyOn() is used to embed a dialog window into another dialog
   window to provide a means to display a "busy" message and to
   temporarily disable the drawing area of the parent window
   during a process. DC_BusyOff() is used to destroy the temporary
   child window.
   

Examples:

   FUNCTION XTest()
   
   LOCAL lContinue := .t.
   
   oBusyDlg := DC_BusyOn( SetAppWindow(), ;
                          {||WaitDialog(@lContinue,@oStatus)} )
   
   DO WHILE !Eof() .AND. lContinue
   
     oStatus:setCaption('Processing Record ' + Alltrim(Str(n)))
     SKIP
     DC_CompleteEvents()
   
   ENDDO
   
   DC_BusyOff(oBusyDlg)
   
   RETURN nil
   
   * -------------------
   
   STATIC FUNCTION WaitDialog( lContinue, oStatus )
   
   LOCAL GetList[0], oBusyDlg, GetOptions
   
   @ 0,0 DCSAY "Processing" FONT '20.Arial Bold' SAYSIZE 0
   
   @ 2,0 DCSAY '' OBJECT oStatus COLOR GRA_CLR_BLUE FONT '12.Arial Bold' SIZE 30
   
   @ 4,8 DCPUSHBUTTON CAPTION 'Cancel' ACTION {||lContinue := .F. } SIZE 9, 1.2
   
   DCGETOPTIONS NOTITLEBAR HIDE
   
   DCREAD GUI FIT EXIT PARENT @oBusyDlg OPTIONS GetOptions
   
   RETURN oBusyDlg
   

Source/Library:

  _DCMSG.PRG, DCLIPX.DLL

See Also:

   dc_waiton()

dc_busyon()

Invoke a busy message window

Syntax:

   DC_BusyOn( < oParentDlg >, ;
              < bDialog > ) - > oBusyDlg
   

Arguments:

   < oParentDlg > is a pointer to any window derived from the
   XbpDialog() class.  This is the window who's drawing area will
   be disabled and which will be come the parent of the child
   window.
   
   < bDialog > is a code block to evaluate.  The code block must
   return a dialog window which will be embedded within < oParentDlg >.
   

Returns:

   A pointer to a dialog window object.
   

Description:

   DC_BusyOn() is used to embed a dialog window into another dialog
   window to provide a means to display a "busy" message and to
   temporarily disable the drawing area of the parent window
   during a process. DC_BusyOff() is used to destroy the temporary
   child window.
   

Examples:

   FUNCTION XTest()
   
   LOCAL lContinue := .t.
   
   oBusyDlg := DC_BusyOn( SetAppWindow(), ;
                          {||WaitDialog(@lContinue,@oStatus)} )
   
   DO WHILE !Eof() .AND. lContinue
   
     oStatus:setCaption('Processing Record ' + Alltrim(Str(n)))
     SKIP
     DC_CompleteEvents()
   
   ENDDO
   
   DC_BusyOff(oBusyDlg)
   
   RETURN nil
   
   * -------------------
   
   STATIC FUNCTION WaitDialog( lContinue, oStatus )
   
   LOCAL GetList[0], oBusyDlg, GetOptions
   
   @ 0,0 DCSAY "Processing" FONT '20.Arial Bold' SAYSIZE 0
   
   @ 2,0 DCSAY '' OBJECT oStatus COLOR GRA_CLR_BLUE FONT '12.Arial Bold' SIZE 30
   
   @ 4,8 DCPUSHBUTTON CAPTION 'Cancel' ACTION {||lContinue := .F. } SIZE 9, 1.2
   
   DCGETOPTIONS NOTITLEBAR HIDE
   
   DCREAD GUI FIT EXIT PARENT @oBusyDlg OPTIONS GetOptions
   
   RETURN oBusyDlg
   

Source/Library:

  _DCMSG.PRG, DCLIPX.DLL

See Also:

   dc_waiton()

dc_byteshift()

Shift a byte a specified number of bits

Syntax:

   DC_ByteShift( < cChar >, ;
                 [< nShift >] ) - > cChar
   

Arguments:

   < cChar > is any character (byte).
   
   < nShift > is the number of bits to shift from -7 to +7.
   

Returns:

    A character (byte).
   

Description:

   DC_ByteShift() is used to shift the bits in a byte a specified
   amount.
   

Source/Library:

  _DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_bin2num()
   dc_num2word()

dc_calcabsoluteposition()

Calculate desktop position from an objects coordinates

Syntax:

   DC_CalcAbsolutePosition( [< aPos >], < oXbp > ) - >
   aCoords
   

Arguments:

   < aPos > is a two-element array containing the offset from the
   object for the resultant output.  The default is {0,0}.
   
   < oXbp > is the object whose absolute coordinates are being
   calcualated.
   

Returns:

   A two element array containing two numeric values:
   
   1. The absolute COLUMN position.
   2. The absolute ROW position.
   

Description:

   DC_CalcAbsolutePosition() returns the coordinates of an object
   with respect to coordinate 0,0 of the desktop.  This is needed
   to get coordinates for tooltips and modal popup windows that
   must be displayed adjecent to another object.
   

Examples:

   // This function will center an object on the screen over any
   // relative object.
   
   FUNCTION DC_CenterObject( oXbp, oRel )
   
   LOCAL nRelWidth, nRelHeight, nWidth, nHeight, nCol, nRow, aPos
   
   DEFAULT oRel := oXbp:setParent()
   
   nWidth := oXbp:currentSize()[1]
   nHeight := oXbp:currentSize()[2]
   nRelWidth := oRel:currentSize()[1]
   nRelHeight := oRel:currentSize()[2]
   nCol := (nRelWidth-nWidth)/2
   nRow := (nRelHeight-nHeight)/2
   
   IF oRel == oXbp:setParent()
     oXbp:setPos( {nCol,nRow} )
   ELSE
     aPos := DC_CALCABSOLUTEPOSITION({0,0},oRel)
     oXbp:setPos( {aPos[1]+nCol,aPos[2]+nRow} )
   ENDIF
   
   RETURN nil
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

dc_callstack()

Display the callstack and optionally edit the source

Syntax:

    DC_CallStack() - > Nil
   

Arguments:

    None.
   

Returns:

    Nil.
   

Description:

    DC_CallStack() is used to display a GUI dialog listing the
    current call stack and line numbers.
   
    Clicking on an item in the list will scan the list of .OBJs
    in the ODIR path to find the source of the function.  If
    the same named function exists in more than one .OBJ, then
    all .OBJs will be listed.  Clicking on the selected .OBJ will
    call the default editor and pass the name and line number of
    the selected source file to editor for editing.
   

Examples:

    . DC_SetKeyActive(.t.)
    . SetKey( K_ALT_S, {||DC_CallStack()} )
   

Source/Library:

  _DCOFIND.PRG, DCLIP2.DLL

See Also:

   STACK
   dc_editprg()
   dc_objpublic()

dc_capfirst()

Capitalize the first character of each word.

Syntax:

   DC_CapFirst( < cString >, ;
                [< lLower >] ) - > cString
   

Arguments:

   < cString > is any string.
   
   < lLower > if .TRUE. will force all characters except the first
   character in each word to lower case.  The default is .FALSE.
   

Returns:

   A Character String.
   

Description:

   DC_CapFirst() capitalizes the first letter of all words in a
   string and leaves all other letters lowercase.
   

Examples:

   . ? DC_CapFirst('DONNAY SOFTWARE DESIGNS',.t.)
   Donnay Software Designs
   
   . ? DC_CapFirst('donnay SoftWare')
   Donnay SoftWare
   

Source/Library:

  _DCCAPF.PRG, DCLIP1.DLL

dc_cascadecoords()

Returns coordinates to cascade a window

Syntax:

   DC_CascadeCoords( [< oParent >], ;
                     [< lTextBased >], ;
                     [< aDefault >], ;
                     [< lTranslate >], ;
                     [< oExclude >] ) - > aCoords
   

Arguments:

   < oParent > is the dialog window to scan.  If no parameter is
   passed the AppDeskTop() is the default.
   
   < lTextBased > will return text-based coordinates if .TRUE.
   otherwise it will return pixel-based coordinates (default).
   
   < aDefault > is an array of two coordinates to return if no
   siblings were found.
   
   < lTranslate > if .TRUE. (default) will return coordinates
   translated with 0,0 at the top of the parent window.  If
   .FALSE. the coordinates will be relative to 0,0 at the bottom
   of the parent window.
   
   < oExclude > is a sibling object (an object in the childlist) to
   ignore when scanning the childlist.
   

Returns:

    An array of two numeric coordinates:
   
    Element 1 is the row.
    Element 2 is the column.
   

Description:

   DC_CASCADECOORD() returns an array of two coordinates.  These
   coordinates are calculated by scanning the childlist of an
   object and finding the object with the lowest coordinates.  This
   allows for cascading of dialog windows.
   

Examples:

   /*
   This example will set the coordinates of a dialog window to
   cascaded coordinates relative to the lowest sibling on the
   desktop.  If there are no siblings, the current coordinates
   will be used.
   */
   
   FUNCTION Xtest( oDlg )
   
   LOCAL aCoords, nRow, nCol
   
   nRow := oDlg:currentPos()[2]
   nCol := oDlg:currentPos()[1]
   
   aCoords := ;
     DC_CascadeCoords(AppDesktop(),.f.,{nRow,nCol},.f.,oDlg)
   
   oDlg:setPos( { nCol, nRow } )
   
   RETURN nil
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.LIB

dc_cdow()

Translated name of the Day of Week

Syntax:

   DC_CDow( < dDate > ) - > cDayOfWeek
   

Arguments:

   < dDate > is any valid date type.
   

Returns:

   A character string.
   

Description:

   DC_CDow() is used to get the name of the day of the week for a
   specified date.  The name is translated to the language
   previously selected by DC_LangSel().
   

Examples:

   DC_LangSet( DCLANG_GERMAN )
   ? DC_CDow( Date() )
   Mittwoch
   

Source/Library:

  _DCCALEN.PRG, DCLIPX.DLL

See Also:

   dc_cmonth()
   dc_langset()
   dc_langmsg()

dc_celledittimeout()

Set a timeout for the Cell-Editor

Syntax:

    DC_CellEditTimeOut( [< nSeconds >] ) - > nOldTimeOut
   

Arguments:

   < nSeconds > is the amount of time, in seconds, to allow cell-
   editing with no user activity.  The default is 0 (no time out).
   

Returns:

    A numerical value equivalent to the previous timeout setting.
   

Description:

    DC_CellEditTimeOut() is used to establish a timeout to exit the
    cell editor if there is no user activity after a specified amount
    of time.
   
    The Cell Editor automatically locks the record and holds the lock
    until it exits or until a new record is selected.  If the user
    enters the cell-editor and walks away from the computer, a lock
    on the record for a long period of time may be undesirable.
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.LIB

See Also:

   dc_browcelledit()

dc_centerobject()

Center an Object

Syntax:

   DC_CenterObject ( < oXbp >, ;
                     [< oReference >] ) - > nil
   

Arguments:

   < oXbp > is the object to center.
   
   < oReference > is the reference object to center < oXbp > in.
   If < oReference > is not passed, < oXbp > will be centered
   within it's
   parent.
   

Returns:

    nil
   

Description:

    DC_CENTEROBJECT() will center any object within the viewing area
    of it's parent object or any other object.
   

Examples:

    -- Example 1 --
   
    * Center the CRT window on the Desktop
   
    DC_CenterObject(SetAppWindow(),AppDeskTop())
   

Source/Library:

  _DCFUNCT.PRG/.OBJ, DCLIPX.LIB

dc_cgigetenvval()

Read an environment variable in a CGI program

Syntax:

    DC_CGIGetEnvVal( < nEnvName > ) - > cValue
   

Arguments:

   < nEnvName > is the numeric value defined in DCCGI.CH.  The
   following names are available.
   
   AUTH_TYPE
   CONTENT_LENGTH
   CONTENT_TYPE
   GATEWAY_INTERFACE
   HTTP_USER_AGENT
   HTTP_ACCEPT
   HTTP_FROM
   PATH_INFO
   PATH_TRANSLATED
   QUERY_STRING
   REFERER_URL
   REMOTE_ADDR
   REMOTE_HOST
   REMOTE_IDENT
   REMOTE_USER
   REQUEST_METHOD
   SCRIPT_NAME
   SERVER_NAME
   SERVER_PORT
   SERVER_PROTOCOL
   SERVER_SOFTWARE
   SERVER_ADMIN
   GMT_OFFSET
   HTTP_REFERRER
   HTTP_COOKIE
   _FROM
   AUTH_NAME
   DATE_LOCAL
   CONTENT_STRING
   REQUEST_PROTOCOL
   EXECUTABLE_PATH
   KEEP_ALIVE
   DOC_ROOT
   AUTH_PASSWORD
   AUTH_METHOD
   AUTH_REALM
   DEBUG_MODE
   X_SERIAL_NUMBER
   PRAGMA
   ACCEPT_LANGUAGE
   HOST
   UA_PIXELS
   UA_COLOR
   UA_OS
   UA_CPU
   EXTENSION
   CGI_VERSION
   NT_USERNAME
   OUTPUT_FILE
   CONTENT_FILE
   

Returns:

    A character string.
   

Description:

    DC_CGIGetEnvVal() is used to get the value of an environment
    variable that has been passed by an HTML form to a CGI
    application.  When a CGI application starts, DC_CGIInit()
    stores all the passed environment variables to a static array
    which is accessed by DC_CGIGetEnvVal().
   

Notes:

    DC_CGIInit() must be called before using this function.
   
    Variables passed to a CGI program are always character strings.
   

Examples:

   <form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">
   
        Your Name <input NAME="Name" TYPE="TEXT" size="20">
          Company <input NAME="Company" TYPE="TEXT" size="20">
          Street1 <input NAME="Street1" TYPE="TEXT" size="20">
          Street2 <input NAME="Street2" TYPE="TEXT" size="20">
             City <input NAME="City" TYPE="TEXT" size="20">
            State <input NAME="State" SIZE="10" TYPE="TEXT">
              Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
          Country <input NAME="Country" TYPE="TEXT" size="20">
   E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
            Phone <input NAME="Phone" TYPE="TEXT" size="20">
              Fax <input NAME="Fax" TYPE="TEXT" size="20">
   
   <input type=hidden name="WAA_PACKAGE" value="DS">
   <input type=hidden name="WAA_FORM" value="FreeDownload">
   <input type=SUBMIT name="FreeDownload" value="Download!"
   </form>
   
   
   FUNCTION _register( oPackage )
   
   oPackage:registerForm( 'FreeDownload' )
   
   RETURN .T.
   
   * -----------------
   
   FUNCTION FreeDownload( oHtml, oContext )
   
   IF !DC_CGIInit(oHtml, oContext)
     RETURN .f.
   ENDIF
   
   // send the environment back to the browser
   
   FOR i := 1 to 50
     DC_CGISend( DC_CGIGetEnvVal(i) )
   NEXT
   
   RETURN
   

Source/Library:

  _DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgigetparmval()
   dc_cgiinit()

dc_cgigetparmval()

Read a data variable in a CGI program

Syntax:

    DC_CGIGetParmVal( < cVarName >, ;
                      [@< cValue >], ;
                      [< oHtml >] ) - > cValue
   

Arguments:

   < cVarName > is the case sensitive name of the variable holding
   the value.
   
   @< cValue > is the name of a variable, passed by reference, to
   store the value.
   
   < oHtml > is the HTML3 object passed to the program.  If this
   parameter is not used then the HTML3 object posted by the
   DC_CGIInit() function will be used.  CAUTION: When running
   heavily loaded CGI programs that may receive simultaneous hits
   it is recommended that this parameter be used.
   

Returns:

    A character string.
   

Description:

    DC_CGIGetParmVal() is used to get the value of a data variable
    that has been passed by an HTML form to a CGI application.
    When a CGI application starts, DC_CGIInit() stores all the
    passed data variables to a static array which is accessed by
    DC_CGIGetParmVal().
   

Notes:

    DC_CGIInit() must be called before using this function.
   
    Variables passed to a CGI program are always character strings.
   

Examples:

   <form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">
   
        Your Name <input NAME="Name" TYPE="TEXT" size="20">
          Company <input NAME="Company" TYPE="TEXT" size="20">
          Street1 <input NAME="Street1" TYPE="TEXT" size="20">
          Street2 <input NAME="Street2" TYPE="TEXT" size="20">
             City <input NAME="City" TYPE="TEXT" size="20">
            State <input NAME="State" SIZE="10" TYPE="TEXT">
              Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
          Country <input NAME="Country" TYPE="TEXT" size="20">
   E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
            Phone <input NAME="Phone" TYPE="TEXT" size="20">
              Fax <input NAME="Fax" TYPE="TEXT" size="20">
   
   <input type=hidden name="WAA_PACKAGE" value="DS">
   <input type=hidden name="WAA_FORM" value="FreeDownload">
   <input type=SUBMIT name="FreeDownload" value="Download!"
   </form>
   
   
   FUNCTION _register( oPackage )
   
   oPackage:registerForm( 'FreeDownload' )
   
   RETURN .T.
   
   * -----------------
   
   FUNCTION FreeDownload( oHtml, oContext )
   
   LOCAL cName, cStreet1, cStreet2, cCompany, ;
         cEmail, cState, cZip, cPhone, cFax, cCountry, cCity
   
   IF !DC_CGIInit(oHtml, oContext)
     RETURN .f.
   ENDIF
   
   dbeSetDefault('DBFCDX')
   
   cName := DC_CGIGetParmVal('Name')
   cCompany := DC_CGIGetParmVal('Company')
   cStreet1 := DC_CGIGetParmVal('Street1')
   cStreet2 := DC_CGIGetParmVal('Street2')
   cState := DC_CGIGetParmVal('State')
   cZip := DC_CGIGetParmVal('Zip')
   cEmail := DC_CGIGetParmVal('Email')
   cCountry := DC_CGIGetParmVal('Country')
   cCity := DC_CGIGetParmVal('City')
   cPhone := DC_CGIGetParmVal('Phone')
   cFax := DC_CGIGetParmVal('Fax')
   
   IF Empty(cName) .OR. !'@'$cEmail
   
     oHTML:message( "Error", ;
     'Please provide a Name and E-mail Address.<p>' + ;
     'Click on your Back Button to return to the download page.<p>')
     DC_CGIQuit()
     RETURN .t.
   
   ELSE
   
     USE register INDEX register.cdx
     OrdSetFocus('EMAIL')
     SEEK Upper(Alltrim(cEmail))
     IF Eof() .AND. DC_AddRec(10)
       REPL REGISTER->name WITH cName,;
            REGISTER->company WITH cCompany,;
            REGISTER->street1 WITH cStreet1,;
            REGISTER->street2 WITH cStreet2,;
            REGISTER->city WITH cCity,;
            REGISTER->country WITH cCountry,;
            REGISTER->state WITH cState,;
            REGISTER->zip WITH cZip,;
            REGISTER->phone WITH cPhone,;
            REGISTER->fax WITH cFax,;
            REGISTER->email WITH cEmail,;
            REGISTER->filename WITH cVariable,;
            REGISTER->date WITH Date(),;
            REGISTER->time WITH Time()
        UNLOCK
      ENDIF
   
      RunShell('/C C:\spimail\sm.exe /t:' + Alltrim(cEmail) + ;
               ' /s:"File Download Instructions"' + ;
               ' /m:' + MemoRead('download.txt',,.t.,.t. )
   
      cHtml += 'An email message has been sent to <em><b>' +
   Alltrim(cEmail) + ;
               ' </b></em>with download
   instructions<br><br>'
   
     DC_CGISend(cHtml)
   
   ENDIF
   
   RETURN
   

Source/Library:

  _DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgiinit()

dc_cgiinit()

Initialize CGI environment

Syntax:

    DC_CGIInit( < oHtml >, ;
                < oContext > ) - > lStatus
   

Arguments:

   < oHtml > is the HTML3 object passed by the WAA adapter to the
   application.
   
   < oContext > is the Context object passed by the WAA adapter to
   the application.
   

Returns:

    A logical .TRUE. if the environment was properly initialized,
    .FALSE. otherwise.
   

Description:

    DC_CGIInit() is used in Web applications designed for use with
    the WAA (Web Application Adapter).  This function reads all
    the passed environment variables and data variables into static
    arrays for later access with DC_CGIGetParmVal().
   
    DC_CGIInit() also creates (an overwrites) two text files:
   
    CGIVARS.TXT - Contains a list of all data variables.
    CGIENVIR.TXT - Contaisn a list of all environment variables.
   
    Note:  These files are overwritten each time DC_CGIInit() is
    run in a program.  They are intended to be used for debugging
    problems immediately after they occur.
   

Notes:

    This must be the first DC_CGI*() function called in a WAA
    program.
   

Examples:

   <form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">
   
        Your Name <input NAME="Name" TYPE="TEXT" size="20">
          Company <input NAME="Company" TYPE="TEXT" size="20">
          Street1 <input NAME="Street1" TYPE="TEXT" size="20">
          Street2 <input NAME="Street2" TYPE="TEXT" size="20">
             City <input NAME="City" TYPE="TEXT" size="20">
            State <input NAME="State" SIZE="10" TYPE="TEXT">
              Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
          Country <input NAME="Country" TYPE="TEXT" size="20">
   E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
            Phone <input NAME="Phone" TYPE="TEXT" size="20">
              Fax <input NAME="Fax" TYPE="TEXT" size="20">
   
   <input type=hidden name="WAA_PACKAGE" value="DS">
   <input type=hidden name="WAA_FORM" value="FreeDownload">
   <input type=SUBMIT name="FreeDownload" value="Download!"
   </form>
   
   
   FUNCTION _register( oPackage )
   
   oPackage:registerForm( 'FreeDownload' )
   
   RETURN .T.
   
   * -----------------
   
   FUNCTION FreeDownload( oHtml, oContext )
   
   LOCAL cName, cStreet1, cStreet2, cCompany, ;
         cEmail, cState, cZip, cPhone, cFax, cCountry, cCity
   
   IF !DC_CGIInit(oHtml, oContext)
     RETURN .f.
   ENDIF
   
   dbeSetDefault('DBFCDX')
   
   cName := DC_CGIGetParmVal('Name')
   cCompany := DC_CGIGetParmVal('Company')
   cStreet1 := DC_CGIGetParmVal('Street1')
   cStreet2 := DC_CGIGetParmVal('Street2')
   cState := DC_CGIGetParmVal('State')
   cZip := DC_CGIGetParmVal('Zip')
   cEmail := DC_CGIGetParmVal('Email')
   cCountry := DC_CGIGetParmVal('Country')
   cCity := DC_CGIGetParmVal('City')
   cPhone := DC_CGIGetParmVal('Phone')
   cFax := DC_CGIGetParmVal('Fax')
   
   IF Empty(cName) .OR. !'@'$cEmail
   
     oHTML:message( "Error", ;
     'Please provide a Name and E-mail Address.<p>' + ;
     'Click on your Back Button to return to the download page.<p>')
     DC_CGIQuit()
     RETURN .t.
   
   ELSE
   
     USE register INDEX register.cdx
     OrdSetFocus('EMAIL')
     SEEK Upper(Alltrim(cEmail))
     IF Eof() .AND. DC_AddRec(10)
       REPL REGISTER->name WITH cName,;
            REGISTER->company WITH cCompany,;
            REGISTER->street1 WITH cStreet1,;
            REGISTER->street2 WITH cStreet2,;
            REGISTER->city WITH cCity,;
            REGISTER->country WITH cCountry,;
            REGISTER->state WITH cState,;
            REGISTER->zip WITH cZip,;
            REGISTER->phone WITH cPhone,;
            REGISTER->fax WITH cFax,;
            REGISTER->email WITH cEmail,;
            REGISTER->filename WITH cVariable,;
            REGISTER->date WITH Date(),;
            REGISTER->time WITH Time()
        UNLOCK
      ENDIF
   
      RunShell('/C C:\spimail\sm.exe /t:' + Alltrim(cEmail) + ;
               ' /s:"File Download Instructions"' + ;
               ' /m:' + MemoRead('download.txt',,.t.,.t. )
   
      cHtml += 'An email message has been sent to <em><b>' +
   Alltrim(cEmail) + ;
               ' </b></em>with download
   instructions<br><br>'
   
     DC_CGISend(cHtml)
   
   ENDIF
   
   RETURN
   

Source/Library:

  _DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgigetparmval()
   dc_cgigetenvval()

dc_cginocrsend()

Send data to the web browser without a CR

Syntax:

    DC_CGINoCrSend( < cHTML >, [< oHtml >] ) - > nil
   

Arguments:

   < cHTML > is any HTML response.  The text will be added to any
   previous calls to DC_CGISend() in the program and all text
   will be sent when the program terminates.
   
   < oHtml > is the HTML3 object passed to the program.  If this
   parameter is not used then the HTML3 object posted by the
   DC_CGIInit() function will be used.  CAUTION: When running
   heavily loaded CGI programs that may receive simultaneous hits
   it is recommended that this parameter be used.
   

Returns:

    Nil.
   

Description:

    DC_CGINoCrSend() is used to send HTML data to the web browser
    without adding a CR (Chr(13)) to the response.
   

Notes:

    This must be the first DC_CGI*() function called in a WAA
    program.
   

Examples:

   <form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">
   
        Your Name <input NAME="Name" TYPE="TEXT" size="20">
          Company <input NAME="Company" TYPE="TEXT" size="20">
          Street1 <input NAME="Street1" TYPE="TEXT" size="20">
          Street2 <input NAME="Street2" TYPE="TEXT" size="20">
             City <input NAME="City" TYPE="TEXT" size="20">
            State <input NAME="State" SIZE="10" TYPE="TEXT">
              Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
          Country <input NAME="Country" TYPE="TEXT" size="20">
   E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
            Phone <input NAME="Phone" TYPE="TEXT" size="20">
              Fax <input NAME="Fax" TYPE="TEXT" size="20">
   
   <input type=hidden name="WAA_PACKAGE" value="DS">
   <input type=hidden name="WAA_FORM" value="FreeDownload">
   <input type=SUBMIT name="FreeDownload" value="Download!"
   </form>
   
   
   FUNCTION _register( oPackage )
   
   oPackage:registerForm( 'FreeDownload' )
   
   RETURN .T.
   
   * -----------------
   
   FUNCTION FreeDownload( oHtml, oContext )
   
   LOCAL cName, cStreet1, cStreet2, cCompany, ;
         cEmail, cState, cZip, cPhone, cFax, cCountry, cCity
   
   IF !DC_CGIInit(oHtml, oContext)
     RETURN .f.
   ENDIF
   
   dbeSetDefault('DBFCDX')
   
   cName := DC_CGIGetParmVal('Name')
   cCompany := DC_CGIGetParmVal('Company')
   cStreet1 := DC_CGIGetParmVal('Street1')
   cStreet2 := DC_CGIGetParmVal('Street2')
   cState := DC_CGIGetParmVal('State')
   cZip := DC_CGIGetParmVal('Zip')
   cEmail := DC_CGIGetParmVal('Email')
   cCountry := DC_CGIGetParmVal('Country')
   cCity := DC_CGIGetParmVal('City')
   cPhone := DC_CGIGetParmVal('Phone')
   cFax := DC_CGIGetParmVal('Fax')
   
   IF Empty(cName) .OR. !'@'$cEmail
   
     oHTML:message( "Error", ;
     'Please provide a Name and E-mail Address.<p>' + ;
     'Click on your Back Button to return to the download page.<p>')
     DC_CGIQuit()
     RETURN .t.
   
   ELSE
   
     USE register INDEX register.cdx
     OrdSetFocus('EMAIL')
     SEEK Upper(Alltrim(cEmail))
     IF Eof() .AND. DC_AddRec(10)
       REPL REGISTER->name WITH cName,;
            REGISTER->company WITH cCompany,;
            REGISTER->street1 WITH cStreet1,;
            REGISTER->street2 WITH cStreet2,;
            REGISTER->city WITH cCity,;
            REGISTER->country WITH cCountry,;
            REGISTER->state WITH cState,;
            REGISTER->zip WITH cZip,;
            REGISTER->phone WITH cPhone,;
            REGISTER->fax WITH cFax,;
            REGISTER->email WITH cEmail,;
            REGISTER->filename WITH cVariable,;
            REGISTER->date WITH Date(),;
            REGISTER->time WITH Time()
        UNLOCK
      ENDIF
   
      RunShell('/C C:\spimail\sm.exe /t:' + Alltrim(cEmail) + ;
               ' /s:"File Download Instructions"' + ;
               ' /m:' + MemoRead('download.txt',,.t.,.t. )
   
      cHtml += 'An email message has been sent to <em><b>' +
   Alltrim(cEmail) + ;
               ' </b></em>with download
   instructions<br><br>'
   
     DC_CGINoCrSend(cHtml)
   
   ENDIF
   
   RETURN
   

Source/Library:

  _DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgisend()

dc_cgiparamarray()

Return an array of all Data Variables

Syntax:

    DC_CGIParamArray( [< oHtml >] ) - > aVars
   

Arguments:

   < oHtml > is the HTML3 object passed to the program.  If this
   parameter is not used then the HTML3 object posted by the
   DC_CGIInit() function will be used.  CAUTION: When running
   heavily loaded CGI programs that may receive simultaneous hits
   it is recommended that this parameter be used.
   

Returns:

    A two-dimensional array.  The first element contains the case
    sensitive variable name.  The second element contains the
    character string value.
   

Description:

    DC_CGIParmArray() returns a two-dimensional array with the
    case-sensitive name and the character string value of each
    variable passed to the CGI Program.  This array is created
    by DC_CGIInit().
   

Examples:

   <form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">
   
        Your Name <input NAME="Name" TYPE="TEXT" size="20">
          Company <input NAME="Company" TYPE="TEXT" size="20">
          Street1 <input NAME="Street1" TYPE="TEXT" size="20">
          Street2 <input NAME="Street2" TYPE="TEXT" size="20">
             City <input NAME="City" TYPE="TEXT" size="20">
            State <input NAME="State" SIZE="10" TYPE="TEXT">
              Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
          Country <input NAME="Country" TYPE="TEXT" size="20">
   E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
            Phone <input NAME="Phone" TYPE="TEXT" size="20">
              Fax <input NAME="Fax" TYPE="TEXT" size="20">
   
   <input type=hidden name="WAA_PACKAGE" value="DS">
   <input type=hidden name="WAA_FORM" value="FreeDownload">
   <input type=SUBMIT name="FreeDownload" value="Download!"
   </form>
   
   
   FUNCTION _register( oPackage )
   
   oPackage:registerForm( 'FreeDownload' )
   
   RETURN .T.
   
   * -----------------
   
   FUNCTION FreeDownload( oHtml, oContext )
   
   LOCAL cName, cStreet1, cStreet2, cCompany, ;
         cEmail, cState, cZip, cPhone, cFax, cCountry, cCity
   
   IF !DC_CGIInit(oHtml, oContext)
     RETURN .f.
   ENDIF
   
   aVars := DC_CGIParamArray()
   DC_ASave(aVars,'VARS.TXT')
   
   RETURN nil
   

Source/Library:

  _DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgiinit()

dc_cgisend()

Send data to the web browser

Syntax:

    DC_CGISend( < cHTML >, [< oHtml >] ) - > nil
   

Arguments:

   < cHTML > is any HTML response.  The text will be added to any
   previous calls to DC_CGISend() in the program and all text
   will be sent when the program terminates.
   
   < oHtml > is the HTML3 object passed to the program.  If this
   parameter is not used then the HTML3 object posted by the
   DC_CGIInit() function will be used.  CAUTION: When running
   heavily loaded CGI programs that may receive simultaneous hits
   it is recommended that this parameter be used.
   

Returns:

    Nil.
   

Description:

    DC_CGISend() is used to send HTML data to the web browser.
   

Notes:

    This must be the first DC_CGI*() function called in a WAA
    program.
   

Examples:

   <form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">
   
        Your Name <input NAME="Name" TYPE="TEXT" size="20">
          Company <input NAME="Company" TYPE="TEXT" size="20">
          Street1 <input NAME="Street1" TYPE="TEXT" size="20">
          Street2 <input NAME="Street2" TYPE="TEXT" size="20">
             City <input NAME="City" TYPE="TEXT" size="20">
            State <input NAME="State" SIZE="10" TYPE="TEXT">
              Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
          Country <input NAME="Country" TYPE="TEXT" size="20">
   E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
            Phone <input NAME="Phone" TYPE="TEXT" size="20">
              Fax <input NAME="Fax" TYPE="TEXT" size="20">
   
   <input type=hidden name="WAA_PACKAGE" value="DS">
   <input type=hidden name="WAA_FORM" value="FreeDownload">
   <input type=SUBMIT name="FreeDownload" value="Download!"
   </form>
   
   
   FUNCTION _register( oPackage )
   
   oPackage:registerForm( 'FreeDownload' )
   
   RETURN .T.
   
   * -----------------
   
   FUNCTION FreeDownload( oHtml, oContext )
   
   LOCAL cName, cStreet1, cStreet2, cCompany, ;
         cEmail, cState, cZip, cPhone, cFax, cCountry, cCity
   
   IF !DC_CGIInit(oHtml, oContext)
     RETURN .f.
   ENDIF
   
   dbeSetDefault('DBFCDX')
   
   cName := DC_CGIGetParmVal('Name')
   cCompany := DC_CGIGetParmVal('Company')
   cStreet1 := DC_CGIGetParmVal('Street1')
   cStreet2 := DC_CGIGetParmVal('Street2')
   cState := DC_CGIGetParmVal('State')
   cZip := DC_CGIGetParmVal('Zip')
   cEmail := DC_CGIGetParmVal('Email')
   cCountry := DC_CGIGetParmVal('Country')
   cCity := DC_CGIGetParmVal('City')
   cPhone := DC_CGIGetParmVal('Phone')
   cFax := DC_CGIGetParmVal('Fax')
   
   IF Empty(cName) .OR. !'@'$cEmail
   
     oHTML:message( "Error", ;
     'Please provide a Name and E-mail Address.<p>' + ;
     'Click on your Back Button to return to the download page.<p>')
     DC_CGIQuit()
     RETURN .t.
   
   ELSE
   
     USE register INDEX register.cdx
     OrdSetFocus('EMAIL')
     SEEK Upper(Alltrim(cEmail))
     IF Eof() .AND. DC_AddRec(10)
       REPL REGISTER->name WITH cName,;
            REGISTER->company WITH cCompany,;
            REGISTER->street1 WITH cStreet1,;
            REGISTER->street2 WITH cStreet2,;
            REGISTER->city WITH cCity,;
            REGISTER->country WITH cCountry,;
            REGISTER->state WITH cState,;
            REGISTER->zip WITH cZip,;
            REGISTER->phone WITH cPhone,;
            REGISTER->fax WITH cFax,;
            REGISTER->email WITH cEmail,;
            REGISTER->filename WITH cVariable,;
            REGISTER->date WITH Date(),;
            REGISTER->time WITH Time()
        UNLOCK
      ENDIF
   
      RunShell('/C C:\spimail\sm.exe /t:' + Alltrim(cEmail) + ;
               ' /s:"File Download Instructions"' + ;
               ' /m:' + MemoRead('download.txt',,.t.,.t. )
   
      cHtml += 'An email message has been sent to <em><b>' +
   Alltrim(cEmail) + ;
               ' </b></em>with download
   instructions<br><br>'
   
     DC_CGISend(cHtml)
   
   ENDIF
   
   RETURN
   

Source/Library:

  _DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgiinit()

dc_cgisetparmval()

Set a data variable in a CGI program

Syntax:

    DC_CGISetParmVal( < cVarName >, ;
                      < cValue >, ;
                      [< oHtml >] ) - > cValue
   

Arguments:

   < cVarName > is the case sensitive name of the variable holding
   the value.
   
   < cValue > is the value to set.
   
   < oHtml > is the HTML3 object passed to the program.  If this
   parameter is not used then the HTML3 object posted by the
   DC_CGIInit() function will be used.  CAUTION: When running
   heavily loaded CGI programs that may receive simultaneous hits
   it is recommended that this parameter be used.
   

Returns:

    A character string.
   

Description:

    DC_CGISetParmVal() is used to set the value of a data variable
    to be later passed back to the browser as a hidden variable.
   

Notes:

    DC_CGIInit() must be called before using this function.
   
    Variables passed to a CGI program are always character strings.
   

Examples:

   
   TEXT TO FILE wishedit.txt
   
   <div align="center">
   <center>
   <table border="4" cellpadding="5" width="100%" colspan="1"
     BORDERCOLOR="#7D7D7D">
     <tr>
       <td bgcolor="#9C6995">
         <font color=#FFFFFF>
         Editing WISHLIST<br> <font
   size=+1>Record:</font>
          <font size=5>
          <bold>"DCCGI_Record"</font></bold>
         <FONT SIZE=+1> "DCCGI_TitleMsg"</FONT>
       </td>
     </tr>
     <tr>
       <td bgcolor="#008080">
         <input type=submit value="First" name="DbEditAction">
         <input type=submit value="Prev" name="DbEditAction">
         <input type=submit value="Next" name="DbEditAction">
         <input type=submit value="Last" name="DbEditAction">
         <input type=submit value="Abort" name="DbEditAction">
         <input type=submit value="Commit" name="DbEditAction">
         <input type=submit value="New" name="DbEditAction">
         <input type=submit value="Browse" name="DbEditAction">
       </td>
     </tr>
     <tr>
       <td valign="top" bgcolor="#FFFFCC">
         <table width=500>
           <tr>
             <td><b><em>Name of
   WishMaker:</b></em></td>
             <td><b><em>Date of
   Wish:</em></b></td>
   
   <td><b><em>Status:</em></b></td
   2
           </tr>
           <tr>
             <td><b><font
   color="#0000FF">"DCCGI_UserName"
               </font></b></td>
             <td><b>"dCGI_WishDate"</b></td>
             <td><b>"nCGI_WishStatus"</b></td>
           </tr>
           <tr>
             <td colspan=3><b><em>Short
   Description:</em></b></td>
           </tr>
           <tr>
             <td colspan=3><input type=text name="cCGI_Description"
                size=75 maxlength=75></td>
           </tr>
         </table>
         <b><em>Explanation of
   Wish:</em></b><br>
         <TEXTAREA name="mCGI_Memo" rows=7 cols=80></TEXTAREA>
         <br>
         <b><em>Donnay Software
   Reply:</em></b><br>
         <TEXTAREA name="mCGI_Reply" rows=7 cols=80></TEXTAREA>
       </td>
     </tr>
   </table>
   </center>
   </div>
   
   ENDTEXT
   
   cForm := DC_CGIStuff( WishEditFieldMap( .t., .t. ), ;
                         MemoRead( 'wishedit.txt' )
   
   DC_CGISetParmVal('HiddenData','this is some data')
   DC_CGISend(cForm)
   
   RETURN nil
   
   * --------------------
   
   FUNCTION WishEditFieldMap( lEditMode )
   
   RETURN  { ;
       { 'DCCGI_UserName', ;
          IIF(Empty(WISHLIST->user_name), ;
          DC_CGIGetParmVal('DCCGI_UserName'),WISHLIST->user_name), ;
          0 }, ;
       { 'dCGI_WishDate', ;
          IIF(Eof(),Date(),WISHLIST->date), ;
          0 }, ;
       { 'cCGI_Description', ;
          WISHLIST->descrip, ;
          IIF(lEditMode,1,0) }, ;
       { 'nCGI_WishStatus', ;
          WISHLIST->status, ;
          0 }, ;
       { 'sCGI_Version', ;
          WISHLIST->version, ;
          7 }, ;
       { 'mCGI_Memo', ;
          IIF(lEditMode,WISHLIST->memo, ;
          Strtran(WISHLIST->memo,Chr(13),'<BR>')), ;
          IIF(lEditMode,6,0) }, ;
       { 'mCGI_Reply', ;
          IIF(lEditMode,WISHLIST->reply, ;
          Strtran(WISHLIST->reply,Chr(13),'<BR>')), ;
          IIF(lEditMode .AND. lMasterPassWord,6,0) }, ;
       { 'DCCGI_Record', ;
          IIF( Eof(),0, RecNo()), ;
          0 }, ;
       { 'DCCGI_TitleMsg', ;
          TitleMessage(), ;
          0 } }
   

Source/Library:

  _DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgigetparmval()
   dc_cgiinit()

dc_cgistuff()

Stuff an HTML response template with data

Syntax:

    DC_CGIStuff( < aStuff >, ;
                 < cForm >, ;
                 [< cDelim >], ;
                 [< lMacro >] ) - > lStatus
   

Arguments:

   < aStuff > is a multi-dimensional array consisting of 3 sub
   elements per item to stuff:
   
   Element  Type    Description
   -------  ------  --------------------------------------------
     [1]      C     The name of the variable in the HTML form
     [2]    CNDLM   Value to stuff into the form
     [3]      N     The type of variable (See below table)
   
   
   Type [3]  Description
   --------  ---------------------------------------------------
      0      ANYTHING (value may be any value)
      1      TEXT     (value must be character string) DEFAULT
      2      RADIO    (value must be character string)
      3      TEXT     (value must be date)
      4      TEXT     (value must be numeric)
      5      CHECKBOX (value must be logical)
      6      TEXTAREA (value must be character string)
      7      OPTION   (value must be character string)
   
   < cForm > is the HTML form template
   
   < cDelim > is the delimeter that is used around variables in the
   form.  The default is ".
   
   < lMacro > if .TRUE. specifies that element 2 of the stuff array
   is an expression which will return a value.  The default is
   .FALSE.
   

Returns:

    A logical .TRUE. if the processed was completed successfully.
   

Description:

    DC_CGIStuff() is used to merge data with an HTML form.  This
    function is handy when is it desired to read a "template"
    HTML form, insert data in the template and then send this to
    the web browser.
   

Examples:

   FUNCTION XTest
   
   TEXT TO FILE wishedit.txt
   
   <div align="center">
   <center>
   <table border="4" cellpadding="5" width="100%" colspan="1"
     BORDERCOLOR="#7D7D7D">
     <tr>
       <td bgcolor="#9C6995">
         <font color=#FFFFFF>
         Editing WISHLIST<br> <font
   size=+1>Record:</font>
          <font size=5>
          <bold>"DCCGI_Record"</font></bold>
         <FONT SIZE=+1> "DCCGI_TitleMsg"</FONT>
       </td>
     </tr>
     <tr>
       <td bgcolor="#008080">
         <input type=submit value="First" name="DbEditAction">
         <input type=submit value="Prev" name="DbEditAction">
         <input type=submit value="Next" name="DbEditAction">
         <input type=submit value="Last" name="DbEditAction">
         <input type=submit value="Abort" name="DbEditAction">
         <input type=submit value="Commit" name="DbEditAction">
         <input type=submit value="New" name="DbEditAction">
         <input type=submit value="Browse" name="DbEditAction">
       </td>
     </tr>
     <tr>
       <td valign="top" bgcolor="#FFFFCC">
         <table width=500>
           <tr>
             <td><b><em>Name of
   WishMaker:</b></em></td>
             <td><b><em>Date of
   Wish:</em></b></td>
   
   <td><b><em>Status:</em></b></td
   2
           </tr>
           <tr>
             <td><b><font
   color="#0000FF">"DCCGI_UserName"
               </font></b></td>
             <td><b>"dCGI_WishDate"</b></td>
             <td><b>"nCGI_WishStatus"</b></td>
           </tr>
           <tr>
             <td colspan=3><b><em>Short
   Description:</em></b></td>
           </tr>
           <tr>
             <td colspan=3><input type=text name="cCGI_Description"
                size=75 maxlength=75></td>
           </tr>
         </table>
         <b><em>Explanation of
   Wish:</em></b><br>
         <TEXTAREA name="mCGI_Memo" rows=7 cols=80></TEXTAREA>
         <br>
         <b><em>Donnay Software
   Reply:</em></b><br>
         <TEXTAREA name="mCGI_Reply" rows=7 cols=80></TEXTAREA>
       </td>
     </tr>
   </table>
   </center>
   </div>
   
   ENDTEXT
   
   cForm := DC_CGIStuff( WishEditFieldMap( .t., .t. ), ;
                         MemoRead( 'wishedit.txt' )
   
   
   RETURN cForm
   
   * --------------------
   
   FUNCTION WishEditFieldMap( lEditMode )
   
   RETURN  { ;
       { 'DCCGI_UserName', ;
          IIF(Empty(WISHLIST->user_name), ;
          DC_CGIGetParmVal('DCCGI_UserName'),WISHLIST->user_name), ;
          0 }, ;
       { 'dCGI_WishDate', ;
          IIF(Eof(),Date(),WISHLIST->date), ;
          0 }, ;
       { 'cCGI_Description', ;
          WISHLIST->descrip, ;
          IIF(lEditMode,1,0) }, ;
       { 'nCGI_WishStatus', ;
          WISHLIST->status, ;
          0 }, ;
       { 'sCGI_Version', ;
          WISHLIST->version, ;
          7 }, ;
       { 'mCGI_Memo', ;
          IIF(lEditMode,WISHLIST->memo, ;
          Strtran(WISHLIST->memo,Chr(13),'<BR>')), ;
          IIF(lEditMode,6,0) }, ;
       { 'mCGI_Reply', ;
          IIF(lEditMode,WISHLIST->reply, ;
          Strtran(WISHLIST->reply,Chr(13),'<BR>')), ;
          IIF(lEditMode .AND. lMasterPassWord,6,0) }, ;
       { 'DCCGI_Record', ;
          IIF( Eof(),0, RecNo()), ;
          0 }, ;
       { 'DCCGI_TitleMsg', ;
          TitleMessage(), ;
          0 } }
   

Source/Library:

  _DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgiupdate()

dc_cgitrans()

Write a transacation to log file

Syntax:

    DC_CGITrans() - > lStatus
   

Arguments:

    None.
   

Returns:

    A logical .TRUE. if the transaction record was written, .FALSE.
    otherwise.
   

Description:

    DC_CGITrans() is used to write a transaction record to a
    database log named DCCGI.DBF. The record will contain the date
    and time, the names and values of all passed data variables
    (in array format) and the names and values of all passed
    environment variables (in array format).
   
    A call to DC_CGITrans() is recommended right after the call to
    DC_CGIInit() in a CGI program.  This will insure that all
    information passed to the program is permanently captured in
    the event of an error in the program.  It can also be used
    as a history log to monitor all activity by the program.
   

Notes:

    The function DC_CGIInit() must be called before using this
    function.
   

Examples:

   <form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">
   
        Your Name <input NAME="Name" TYPE="TEXT" size="20">
          Company <input NAME="Company" TYPE="TEXT" size="20">
          Street1 <input NAME="Street1" TYPE="TEXT" size="20">
          Street2 <input NAME="Street2" TYPE="TEXT" size="20">
             City <input NAME="City" TYPE="TEXT" size="20">
            State <input NAME="State" SIZE="10" TYPE="TEXT">
              Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
          Country <input NAME="Country" TYPE="TEXT" size="20">
   E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
            Phone <input NAME="Phone" TYPE="TEXT" size="20">
              Fax <input NAME="Fax" TYPE="TEXT" size="20">
   
   <input type=hidden name="WAA_PACKAGE" value="DS">
   <input type=hidden name="WAA_FORM" value="FreeDownload">
   <input type=SUBMIT name="FreeDownload" value="Download!"
   </form>
   
   
   FUNCTION _register( oPackage )
   
   oPackage:registerForm( 'FreeDownload' )
   
   RETURN .T.
   
   * -----------------
   
   FUNCTION FreeDownload( oHtml, oContext )
   
   LOCAL cName, cStreet1, cStreet2, cCompany, ;
         cEmail, cState, cZip, cPhone, cFax, cCountry, cCity
   
   IF !DC_CGIInit(oHtml, oContext)
     RETURN .f.
   ENDIF
   
   DC_CGITrans()
   
   dbeSetDefault('DBFCDX')
   
   cName := DC_CGIGetParmVal('Name')
   cCompany := DC_CGIGetParmVal('Company')
   cStreet1 := DC_CGIGetParmVal('Street1')
   cStreet2 := DC_CGIGetParmVal('Street2')
   cState := DC_CGIGetParmVal('State')
   cZip := DC_CGIGetParmVal('Zip')
   cEmail := DC_CGIGetParmVal('Email')
   cCountry := DC_CGIGetParmVal('Country')
   cCity := DC_CGIGetParmVal('City')
   cPhone := DC_CGIGetParmVal('Phone')
   cFax := DC_CGIGetParmVal('Fax')
   
   IF Empty(cName) .OR. !'@'$cEmail
   
     oHTML:message( "Error", ;
     'Please provide a Name and E-mail Address.<p>' + ;
     'Click on your Back Button to return to the download page.<p>')
     DC_CGIQuit()
     RETURN .t.
   
   ELSE
   
     USE register INDEX register.cdx
     OrdSetFocus('EMAIL')
     SEEK Upper(Alltrim(cEmail))
     IF Eof() .AND. DC_AddRec(10)
       REPL REGISTER->name WITH cName,;
            REGISTER->company WITH cCompany,;
            REGISTER->street1 WITH cStreet1,;
            REGISTER->street2 WITH cStreet2,;
            REGISTER->city WITH cCity,;
            REGISTER->country WITH cCountry,;
            REGISTER->state WITH cState,;
            REGISTER->zip WITH cZip,;
            REGISTER->phone WITH cPhone,;
            REGISTER->fax WITH cFax,;
            REGISTER->email WITH cEmail,;
            REGISTER->filename WITH cVariable,;
            REGISTER->date WITH Date(),;
            REGISTER->time WITH Time()
        UNLOCK
      ENDIF
   
      RunShell('/C C:\spimail\sm.exe /t:' + Alltrim(cEmail) + ;
               ' /s:"File Download Instructions"' + ;
               ' /m:' + MemoRead('download.txt',,.t.,.t. )
   
      cHtml += 'An email message has been sent to <em><b>' +
   Alltrim(cEmail) + ;
               ' </b></em>with download
   instructions<br><br>'
   
     DC_CGISend(cHtml)
   
   ENDIF
   
   RETURN
   

Source/Library:

  _DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgiinit()

dc_cgiupdate()

Update a database from an array of information

Syntax:

    DC_CGIUpdate( < aStuff >, ;
                  [< cAlias >] ) - > lStatus
   

Arguments:

   < aStuff > is a multi-dimensional array consisting of 3 sub
   elements per item to update:
   
   Element  Type    Description
   -------  ------  --------------------------------------------
     [1]    CNLMDB  A value, code block, macro expression, or
                    name of variable.
     [2]      C     Name of field to update (fully aliased)
     [3]      N     The type of update to perform (default is 0)
                    See below table
   
     Type [3]       Description
   --------------   --------------------------------------------
         0          Direct replacement (no translation) DEFAULT
       1,2,6        Character string [1] must be name of variable
         3          Date             [1] must be name of variable
         4          Numeric          [1] must be name of variable
         5          Logical          [1] must be name of variable
         7          Reserved
         8          Macro substitution
   
   
   < cAlias > is the Alias of the database to update.  If this
   argument is not passed then the current alias is the default.
   

Returns:

    A logical .TRUE. if the update was performed successfully.
   

Description:

    DC_CGIUpdate() can be used in both web and non-web programs
    however it was designed for CGI programs to simplify the
    process of writing passed in data to a database because data
    is always received as character strings but it often must be
    saved to a database in another format like a date, numeric,
    logical, or memo.
   

Examples:

   <form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">
   
        Your Name <input NAME="Name" TYPE="TEXT" size="20">
          Company <input NAME="Company" TYPE="TEXT" size="20">
          Street1 <input NAME="Street1" TYPE="TEXT" size="20">
          Street2 <input NAME="Street2" TYPE="TEXT" size="20">
             City <input NAME="City" TYPE="TEXT" size="20">
            State <input NAME="State" SIZE="10" TYPE="TEXT">
              Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
          Country <input NAME="Country" TYPE="TEXT" size="20">
   E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
            Phone <input NAME="Phone" TYPE="TEXT" size="20">
              Fax <input NAME="Fax" TYPE="TEXT" size="20">
   
   <input type=hidden name="WAA_PACKAGE" value="DS">
   <input type=hidden name="WAA_FORM" value="FreeDownload">
   <input type=SUBMIT name="FreeDownload" value="Download!"
   </form>
   
   
   FUNCTION _register( oPackage )
   
   oPackage:registerForm( 'FreeDownload' )
   
   RETURN .T.
   
   * -----------------
   
   FUNCTION FreeDownload( oHtml, oContext )
   
   LOCAL cName, cStreet1, cStreet2, cCompany, ;
         cEmail, cState, cZip, cPhone, cFax, cCountry, cCity
   
   IF !DC_CGIInit(oHtml, oContext)
     RETURN .f.
   ENDIF
   
   aUpdate := { ;
     { "Name",      "REGISTER->name",    1 }, ;
       "Company",   "REGISTER->company", 1 }, ;
       "Street1",   "REGISTER->street2", 1 }, ;
       "Street2",   "REGISTER->street2", 1 }, ;
       "City",      "REGISTER->city",    1 }, ;
       "State",     "REGISTER->state",   1 }, ;
       "Zip",       "REGISTER->zip",     1 }, ;
       "Country",   "REGISTER->country", 1 }, ;
       "Email",     "REGISTER->email,    1 }, ;
       "Phone",     "REGISTER->phone,    1 }, ;
       "Fax",       "REGISTER->fax,      1 }, ;
       "Date()",    "REGISTER->date,     8 }, ;
       {||Time()},  "REGISTER->time,     0 } }
   
   USE REGISTER
   
   DC_CGIUpdate( aUpdate, "REGISTER" )
   
   RETURN nil
   

Source/Library:

  _DCCGI.PRG, DCLIPX.DLL

dc_chdir()

Change dos directory

Syntax:

   DC_ChDir ( < cDirectory > ) - > lStatus
   

Arguments:

   < cDirectory > is the drive and directory to select.
   

Returns:

    .TRUE. if the drive and/or directory exists and is selected.
    .FALSE. if the drive and/or directory does not exist.
   

Description:

    DC_CHDIR() is used to select a new dos drive and directory.
   

Examples:

    DC_CHDIR('A:')
    DC_CHDIR('C:\DCLIP')
    DC_CHDIR('\DCLIP\DATA')
   

Source/Library:

  _DCCHDIR.PRG/.OBJ, DCLIPX.LIB

dc_childcount()

Report the number of child work areas

Syntax:

    DC_ChildCount ( [< nArea >] ) - > nChildren
   

Arguments:

   < nArea > is the work area.  If argument is not passed, then the
   current work area is default.
   

Description:

    DC_CHILDCOUNT() is used to report the total number of
    parent-child relations for a specified work area.
   

Examples:

    . use customer
    . use invoice new
    . use sales new
    . sele customer
    . set rela to cust_nmbr into invoice, to so_nmbr into sales
    . ? DC_CHILDCOUNT()
    2
   

Source/Library:

  _DCAREA.PRG, DCLIP1.DLL

See Also:

   dc_setrelation()

dc_chrsel()

Choose a character from an ASCII Character Chart

Syntax:

    CHR
   

Arguments:

    None.
   

Returns:

    The numeric value of the character selected.
   

Description:

    DC_ChrSel() will display a chart of the 256 ASCII text-mode
    characters and return the numeric value of the selected character.
   

Notes:

    CAUTION: This is a text-mode function so the SetAppWindow()
    must be a CRT window.
   

Examples:

    . ? dc_chrsel()
   

Source/Library:

  _DCCHR.PRG, DCLIP1.DLL

See Also:

   CHR

dc_clearevents()

Clear all events out of the Event Queue

Syntax:

    DC_ClearEvents() - > nil
   

Returns:

    nil
   

Description:

    DC_CLEAREVENTS() will clear all pending events from the event
    Queue.  This is handy when calling a dialog function to insure
    that no mouse or keyboard events are in the queue thus adversely
    affecting the operation of the dialog window.
   

Source/Library:

  _DCFUNCT.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_completeevents()
   dc_saveevents()
   dc_restoreevents()

dc_closearea()

Close the database that is open in the current work area

Syntax:

    DC_CloseArea() - > nil
   

Arguments:

    None.
   

Returns:

    Nil.
   

Description:

    DC_CLOSEAREA() is a front-end to the Xbase++ function dbCloseArea().
    Before calling dbCloseArea(), DC_CLOSEaREA() tests the function
    DC_UseDBFProtect().  If this  function returns a logical .TRUE.
    then DC_CLOSEAREA() first modifies the header of the database
    before the database is closed to prevent other utility programs
    from being able to open the database.  If a file header is
    modified by DC_CLOSEAREA(), then it can only be restored again
    by DC_USEAREA().
   

Examples:

    . DC_UseDBFProtect(.t.)
   
    // open TEST.DBF
    . DC_UseArea( .t., 'DBFNTX', 'TEST' )
   
    // close TEST.DBF but first modify header to protect the data
    . DC_CloseArea()
   

Source/Library:

  _DCUSE.PRG, DCLIP2.DLL

See Also:

   dc_usedbfprotect()
   dc_usearea()

dc_clrarr()

Initialize or modify the Color Array

Syntax:

   DC_ClrArr ( ) - > lStatus
   

Arguments:

    NONE
   

Description:

    DC_CLRARR() is used to initalize or the dCLIP system color
    array. The color array is a PUBLIC array named DCCOLOR and is
    automatically initialized by any dCLIP function that uses the
    array.  This function is normally not needed unless you are
    using the dCLIP color system in your own functions.
   
    The first time the color array is initialized in an application
    using dCLIP functions, if a file named DCCOLOR.AR is found in
    the SET DCLIP directory, then the contents of the file will be
    used to intialize the array, otherwise the default colors will
    be used.
   
    dCLIP also provides multiple "palettes" of colors which can be
    saved to DCCOLOR.AR and modified or selected via DC_CLRSETUP().
   

Notes:

    dCLIP Color Manifest Constants from DCCOLOR.CH
   
    Manifest
    constant      Element                 Description
    ------------ -----------------------  ----------------------------
    cC_DOTPROMPT dCCOLOR[dCCOLOR[1]+1,1]  Main dot-prompt
    cC_BRMENUF   dCCOLOR[dCCOLOR[1]+1,2]  Browse menus frame
    cC_BRMENUD   dCCOLOR[dCCOLOR[1]+1,3]  Browse menus data
    cC_BRMENUH   dCCOLOR[dCCOLOR[1]+1,4]  Browse menus header
    cC_BRMENUB   dCCOLOR[dCCOLOR[1]+1,5]  Browse menus menu bar
    cC_BRMENUS   dCCOLOR[dCCOLOR[1]+1,6]  Browse menus select bar
    cC_POPMENF   dCCOLOR[dCCOLOR[1]+1,7]  Popup / pulldown menu frames
    cC_POPMENI   dCCOLOR[dCCOLOR[1]+1,8]  Popup / pulldown menu items
    cC_POPMENS   dCCOLOR[dCCOLOR[1]+1,9]  Popup / pulldown menu select bars
    cC_MEMOBOX   dCCOLOR[dCCOLOR[1]+1,10] All memos box
    cC_MEMOTXT   dCCOLOR[dCCOLOR[1]+1,11] All memos contents
    cC_EXPBOXF   dCCOLOR[dCCOLOR[1]+1,12] Exploding boxes frame
    cC_EXPBOXC   dCCOLOR[dCCOLOR[1]+1,13] Exploding boxes contents
    cC_DBUGGER   dCCOLOR[dCCOLOR[1]+1,14] DBUGGER main screen
    cC_WARNBOX   dCCOLOR[dCCOLOR[1]+1,15] Warning boxes frame
    cC_WARNTXT   dCCOLOR[dCCOLOR[1]+1,16] Warning boxes contents
    cC_DBUGBOX   dCCOLOR[dCCOLOR[1]+1,17] Debug boxes frames
    cC_DBUGTXT   dCCOLOR[dCCOLOR[1]+1,18] Debug boxes contents
    cC_DBUGBAR   dCCOLOR[dCCOLOR[1]+1,19] Debug boxes select bar
    cC_SPECIAL   dCCOLOR[dCCOLOR[1]+1,20] Special codes
    cC_SAY       dCCOLOR[dCCOLOR[1]+1,21] SAYs
    cC_PENDGET   dCCOLOR[dCCOLOR[1]+1,22] Pending GETs
    cC_CURRGET   dCCOLOR[dCCOLOR[1]+1,23] Current GET
    cC_STAT1     dCCOLOR[dCCOLOR[1]+1,24] Dot-prompt status line / lines
    cC_STAT2     dCCOLOR[dCCOLOR[1]+1,25] Dot-prompt status line / data
    lC_BLINKBIT  dCCOLOR[dCCOLOR[1]+1,34] Blink-bit or High Intensity
    cC_SETNAME   dCCOLOR[dCCOLOR[1]+1,35] Name of this color set
    cC_COLORNAME 35                       Numeric value of cC_SETNAME
    nC_COLORPAL  dCCOLOR[1]   Default color palette
   

Examples:

    #include "dccolor.ch"
   
    FUNCTION main
   
    DC_CLRARR()           // initalize array
    dc_expl(10,10,15,70)  // explode a box
    setcolor(cC_EXPBOXC)  // set color to box contents
    @ 12,12 say 'Enter something below'
    something := space(10)
    @ 14,12 get something
    read
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

dc_clrscope()

Clear scoping values for the current work area

Syntax:

   dc_clrscope ( ) - > Nil
   

Arguments:

    None.
   

Returns:

    Nil
   

Description:

    DC_CLRSCOPE() is used to clear both the SCOPE TOP and
    SCOPE BOTTOM "scoping range" values that were previously set
    by DC_SETSCOPE().
   

Notes:

    DC_SETSCOPE() does not establish the scoping range at the
    RDD-layer level, but instead is just a handy way of storing
    the SCOPE TOP and SCOPE BOTTOM to be retrieved by programs
    that can use this information such as data-entry systems and
    browse systems.  It does not affect the behavior of the
    data-driver nor does it set any filters on the data.
   

Examples:

    #include 'dcdialog.ch'
    #include 'appevent.ch'
   
    PROCEDURE XTest()
   
    LOCAL GetList := {}, oBrowse, aPres, cScopeTop, cScopeBot
   
    USE ..\XDOC\EXPRESS INDEX ..\XDOC\EXPRESS.CDX ;
        VIA FOXCDX ALIAS XDOC
   
    OrdSetFocus('COMMAND')
    DC_KeyStat(.t.)
    DC_SETSCOPE(0,'DC_G')
    DC_SETSCOPE(1,'DC_K')
    DC_DbGoTop()
   
    aPres := ;
     { { XBP_PP_COL_HA_FGCLR, GRA_CLR_WHITE },    /*  Header FG Color  */ ;
       { XBP_PP_COL_HA_BGCLR, GRA_CLR_DARKGRAY }, /*  Header BG Color  */ ;
       { XBP_PP_COL_DA_ROWSEPARATOR, XBPCOL_SEP_DOTTED }, /* Row Sep  */  ;
       { XBP_PP_COL_DA_COLSEPARATOR, XBPCOL_SEP_DOTTED }  /* Col Sep  */  ;
     }
   
    cScopeTop := Pad('DC_G',10)
    cScopeBot := Pad('DC_K',10)
   
    @ 1,1 DCSAY 'Scope Top' GET cScopeTop PICT '@!' SAYRIGHT ;
      VALID {||DC_SetScope(0,Alltrim(cScopeTop)),;
               oBrowse:RefreshAll(),;
               SetAppFocus(oBrowse),.t.}
   
    @ 1,25 DCSAY 'Scope Bottom' GET cScopeBot PICT '@!'  SAYRIGHT ;
      VALID {||DC_SetScope(1,Alltrim(cScopeBot)),;
               oBrowse:RefreshAll(),;
               SetAppFocus(oBrowse),.t.}
   
    @ 1, 65 DCPUSHBUTTON CAPTION 'Clear ~Scope' SIZE 10,1.5 ;
      ACCELKEY xbeK_ALT_S ;
      ACTION {||DC_CLRSCOPE(),oBrowse:RefreshAll(),;
                SetAppFocus(oBrowse)}
   
    @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' ;
      SIZE 77,11.8 ;
      FREEZELEFT {1} ;
      PRESENTATION aPres ;
      SCOPE
   
    DCBROWSECOL FIELD XDOC->command ;
      HEADER "Command" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->type  ;
      HEADER "Type" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->short ;
      HEADER "Short Description" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->module ;
      HEADER "Module" PARENT oBrowse ;
   
    DCBROWSECOL FIELD XDOC->category ;
      HEADER "Category" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->see_also ;
      HEADER "See Also" PARENT oBrowse
   
    DCREAD GUI ;
      FIT ;
      ADDBUTTONS ;
      TITLE 'Scoping Demo: DC_G thru DC_K'
   
    RETURN
   

Source/Library:

  _DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()

dc_cls()

Perform a clear screen of a window created by DC_EXPL()

Syntax:

   DC_Cls ( [< aSaveScreen >] ) - > nil
   

Arguments:

   < aSaveScreen > is an array of screen information that was
   originally returned by DC_EXPL().  If no parameter is
   passed, then the static array posted by the last usage of
   DC_EXPL() or the DCEXPLODE command will be used for the
   screen information.  If no call to DC_EXPL() or DCEXPLODE
   is made since the last call to DC_IMPL() or DCIMPLODE,
   then the text is written to the CRT window and treated as
   a normal @..SAY.
   

Returns:

    NIL
   

Description:

    DC_CLS() is a Dual-Mode function which is used to clear all the
    text in a TEXT window or GUI dialogue that was created by
    DC_EXPL().
   

Examples:

    aText := { "Enter a name to search.",;
              "The name must start with",;
              "an alphabet character" }
    disp_msg( 10,10,15,40,aText )
    return
   
    /* --------- */
   
    FUNC disp_msg ( nSrow, nScol, nErow, nEcol, aText )
   
    DC_Gui(.t.)  // display a gui dialogue
    cScreen := dc_expl( nSrow, nScol, nErow, nEcol )
    for i := 1 to len(aText)
      DC_SAY( i+1, 2, aText[i] )
    next
   

Source/Library:

  _DCEXPL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_expl()

dc_cmonth()

Translated name of the Month

Syntax:

   DC_CMonth( < dDate > ) - > cMonth
   

Arguments:

   < dDate > is any valid date type.
   

Returns:

   A character string.
   

Description:

   DC_Cmonth() is used to get the name of the month for a specified
   date.  The name is translated to the language previously selected
   by DC_LangSel().
   

Examples:

   DC_LangSet( DCLANG_GERMAN )
   ? DC_CMonth( Date() )
   Oktober
   

Source/Library:

  _DCCALEN.PRG, DCLIPX.DLL

See Also:

   dc_cdow()
   dc_langset()
   dc_langmsg()

dc_codedelete()

Delete a code table

Syntax:

   dc_codedelete ( [< cTableName >] ) - > lStatus
   

Arguments:

   < cTableName > is the name of the code table.  This is a name of
   up to eight (8) digits.  If no argument is passed, then a pick
   list of all code tables in the code table file will be displayed.
   

Description:

    DC_CODEDELETE() is used to delete a code table from the code
    table file.
   

Notes:

    The DCCODES.DBF file and its indexes will be created by
    the DC_CodeOpen() function if it they do not already exist.
   

Examples:

    DC_CODEELETE('POSITION')
   

Source/Library:

  _DCCODES.PRG, DCLIP1.DLL

See Also:

   dc_codeedit()
   dc_codeget()
   dc_codeload()

dc_codeedit()

Edit a Code Table

Syntax:

   dc_codeedit ( [ < cCodeTable > | < aCodeTable > ] ) - >
   aCodeTable
   

Arguments:

   < cCodeTable > is the name of the code table in DCCODES.DBF
   to load and edit (up to 8 characters) or < aCodeTable > is a
   Code Table array.  See RETURNS for a specification of this
   array.  If no parameter is passed, a pick-list of all Code
   Tables in DCCODES.DBF will be displayed.
   

Returns:

    A 2-dimensional array of two sub-arrays.
   
    The first array contains general information about the
    screen group.
   
     Element  Type   Description
     -------  ----  --------------------------------------
       [1]     C    Code Table Name (up to 8 characters)
       [2]     C    Code Table Description
   
    The second array contains one sub-array for each code
    table item.
   
     Element  Type   Description
     -------  ----  ---------------------------------------
       [1]     C    Code Table Name (up to 8 chars)
       [2]     C    Code Name (up to 10 chars)
       [3]     C    Code Description (up to 50 chars)
       [4]     C    Code Sequence (used for indexing file)
       [5]     C    Code UR (reserved)
   

Description:

    DC_CodeEdit() is an editor that is used to maintain the DCCODES.DBF
    dictionary file.  Code Tables are groups of records that are
    loaded into an array pick-list and used in validations when
    using the eXPress++ data-driven Browse and Edit (data-entry)
    system.  When a "T" validation is used in a field-array, this
    pops-up a code table pick-list for the operator to choose
    possible values.  Code tables can also be used in custom
    applications where validations and/or choice boxes are required.
   
    For example a code table named "POSITION" can be added to
    provide a picklist of available entries for a field of
    baseball player positions.  They would be entered in a code
    table as follows:
   
     1B  -  First Base
     2B  -  Second Base
     3B  -  Third Base
     P   -  Pitcher
     SS  -  Short Stop
     RF  -  Right Field
     LF  -  Left Field
     CF  -  Center Field
     C   -  Catcher
   
    A choice from this table can then be selected by calling
    DC_CodeGet() in a validation or popup routine.
   

Notes:

    The DCCODES.DBF file and its indexes will be created by
    the DC_CodeOpen() function if it they do not already exist.
   

Examples:

    -- Example 1 --
    // Load a code table from the dictionary and edit it //
    DC_CODEDIT()
   
    -- Example 2 --
    // Edit code table "POSITION"
    DC_CODEEDIT("POSITION")
   
    -- Example 3 --
    // Edit a code table array and save it to dictionary //
    aCodeTable := DC_CodePick()
    aCodeTable := DC_CODEDIT( aCodeTable )
    DC_CodeSave( aCodeTable )
   

Source/Library:

  _DCCODES.PRG, DCLIP1.DLL

See Also:

   CODE EDIT

dc_codeget()

Get a choice from a code table

Syntax:

   DC_CodeGet ( < cTableName >, ;
                [@< cCode >], ;
                [< cTitle >], ;
                [< lForcePick >], ;
                [@< cDesc >], ;
                [@< aCode >], ;
                [< lNoPick >], ;
                [< lCurrPos >], ;
                [< lValidate >] ) - > cCode
   

Arguments:

   < cTableName > is the name of the code table in DCCODES.DBF.
   to load (up to 8 characters).
   
   @< cCode > is an optional value to seek in the code table. If
   the value is found and < lPickList > is .FALSE. then the
   full value will be returned and the description will be
   placed into the @< cDesc > variable.  If the value is not
   found or < lForcePick > is .TRUE., a pick list will be
   displayed for the user to choose a code.
   
   < cTitle > is the title to place at the top of the picklist.
   If no parameter is passed, then a default title is displayed.
   
   @< cDesc > is a variable to be passed by reference.  The value
   in the description field (CODE_DESC) will be placed into
   this variable.
   
   @< aCode > is a variable to be passed by reference.  The value
   of all database fields for the selected code will be placed
   into an array of 6 elements and placed into this variable.
   
     Element       Field Name
     -------       ------------
        1          CODE_NAME
        2          CODE_DESC
        3          CODE_SEQ
        4          CODE_UR
        5          CODE_UDF1
        6          CODE_UDF2
   
   < lNoPick > if .TRUE. will not display a pick-list if the code
   cannot be found.
   
   < lCurrPos > if .TRUE. (default) will display the window at the
   current mouse position.
   
   < lValidate > if .TRUE. will return a logical value rather than
   the selected code table value.  See RETURNS.
   

Returns:

    The value of the code chosen (a Character string) if <þlValidateþ>
    is .FALSE.
   
    IF <þlValidateþ> is .TRUE. then the returned value is a logical
    .TRUE. if the user selected a code from the table, otherwise a
    logical .FALSE. is returned.  Also, the selected value is returned
    in the variable @<þcCodeþ> when it is passed by reference.
   

Description:

    DC_CODEGET() is used to allow the operator to select a code
    from a designated code table.  All codes are stored in the
    DCCODES.DBF database in separate tables.
   
    "User defined fields" allow data to easily be extracted from a code
    table via the DC_CODEGET() function.
   
    The "definition" of the three fields is established under the "options"
    for the code table.  Each of the fields is a character type field with
    a length of 50.  For example, let's establish a code table named
    "REPORTS" with the following data:
   
    Code  Description         User Field 1      User Field 2
   
    ----  ------------------  ----------------  -----------------
    R001  Inventory Report    INVREPT.EXE       Executable Program
    R002  Sales Report        {||SlsRept()}     Code-Block
    R003  End-of-Month        EOF.RP1           R&R Report
   
    Now, you can use DC_CODEGET() to place  "virtual" fields on the screen
    so you can display the Description, User Field 1 and User Field 2
    based on the code entered into another field.
   

Notes:

    The DCCODES.DBF file and its indexes will be created by
    the DC_CodeOpen() function if it they do not already exist.
   

Examples:

   --- Example 1 ---
   
    LOCAL GetList := {}, cTreatment
   
    cTreatment := Space(10)
    @ 12,12 DCSAY "Enter Treatment Plan Code" GET cTreatment ;
      PICT '@!' POPUP {|c|DC_CODEGET('TRTMENT',c,,.t.)} )
   
    DCREAD GUI FIT ADDBUTTONS MODAL TITLE 'Treatment'
   
    RETURN cTreatMent
   
   
    --- Example 2 ---
   
    To display the description:
     Eval({|a|DC_CodeGet('REPORTS',repttype,,,,@a,.t.),a[2]})
   
    To display user field 1:
     Eval({|a|DCC_odeGet('REPORTS',repttype,,,,@a,.t.),a[3]})
   
    To display user field 2:
     Eval({|a|DC_CodeGet('REPORTS',repttype,,,,@a,.t.),a[4]})
   

Source/Library:

  _DCCODES.PRG, DCLIP1.DLL

See Also:

   dc_codeedit()
   dc_codeload()

dc_codeimp()

Import a code table

Syntax:

   dc_codeimp ( [< cTableName > | "ALL"] ) - > lStatus
   

Arguments:

   < cTableName > is the name of the code table.  This is a name of
   up to eight (8) digits.  If a code table name is passed then
   the DXCODES.DBF database will be searched and all code table
   items that match the code table name will be imported into
   DCCODES.DBF.  If no name is passed, then a pick-list of all tables
   stored in the DXCODES.DBF database will be displayed.
   
   If "ALL" is passed as the table name, then all tables in the
   DXCODES.DBF will be imported into DCCODES.DBF.
   

Returns:

    A logical .TRUE. if the files were imported successfully.
   

Description:

    DC_CODEIMP() is used to import a code table from the DXCODES.DBF
    import/export file to the DCCODES.DBF file.
   

Notes:

    The DCCODES.DBF file is the data-dictionary database that
    contains all code tables.  If this file does not exist in your
    default directory or path then it will be created.   The
    DXCODES.DBF file is the data-dictionary database that contains
    all code tables that were exported from another system.
   

Examples:

    DC_CODEIMP( "ALL" )
   

Source/Library:

  _DCCODES.PRG, DCLIP1.DLL

See Also:

   dc_codeedit()
   dc_codeget()
   dc_codeload()

dc_codeload()

Load a code table into an array

Syntax:

   dc_codeload ( [< cCodeTable >], ;
                 [< lCache >], ;
                 [< lExport >] ) - > aCodeTable
   

Arguments:

   < cCodeTable > is the name of the code table in DCCODES.DBF
   to load (up to 8 characters).  If no parameter is passed, a
   pick-list of all Code Tables in the DCCODES.DBF dictionary
   will be displayed.
   
   < lCache > if .TRUE. (default) will save the table to a static
   cache array so the next time it is requested it will be
    reloaded from the static array for faster speed.  If .FALSE.
   then it will not be saved to the cache.
   
   < lExport > if .TRUE. will open the DXCODES.DBF (import/export)
   file rather than the DCCODES.DBF file.
   

Returns:

    A 2-dimensional array of two sub-arrays.
   
    The first array contains general information about the
    screen group.
   
     Element  Type   Description
     -------  ----  --------------------------------------
       [1]     C    Code Table Name (up to 8 characters)
       [2]     C    Code Table Description
   
    The second array contains one sub-array for each code
    table item.
   
     Element  Type   Description
     -------  ----  ---------------------------------------
       [1]     C    Code Table Name (up to 8 chars)
       [2]     C    Code Name (up to 10 chars)
       [3]     C    Code Description (up to 50 chars)
       [4]     C    Code Sequence (used for indexing file)
       [5]     C    Code UR (reserved)
   

Description:

    DC_CODELOAD() is used to load a code table array from the
    DCCODES.DBF dictionary file.
   

Notes:

    The DCCODES.DBF file and its indexes will be created by
    the DC_CodeOpen() function if it they do not already exist.
   

Examples:

    . aCodeTable := DC_CODELOAD( 'POSITION' )
    . aCodeTable := DC_CodeEdit( aCodeTable )
    . DC_CodeSave( aCodeTable )
   

Source/Library:

  _DCCODES.PRG, DCLIP1.DLL

See Also:

   dc_codeedit()
   dc_codeget()

dc_codepick()

Pick a code table from the Code Table File

Syntax:

   dc_codepick ( [< cTitle >], ;
                 [< lExport >], ;
                 [@< cTableDesc >], ;
                 [< aCodeList >], ;
                 [< lNoPick >] ) - > cTableName
   

Arguments:

   < cTitle > is the title to display on the pick-list box.
   
   < lExport > if .TRUE. will open the DXCODES.DBF (import/export)
   file rather than the DCCODES.DBF file.
   
   @< cTableDesc > is the name of a variable (passed by reference)
   to store the description of the table that was chosen.
   
   @< aCodeList > is the name of a variable (passed by reference)
   to store a single-dimensional array containing the names of
   all code tables in the code table file.
   
   < lNoPick > if .TRUE. will not pop up the list of code tables
   to choose.  This option is intended to be used only when
   @< aCodeList > is also passed.
   

Returns:

    A character string containing the name of the code table
    selected by the user.
   

Description:

    DC_CODEPICK() is used to pick the name of a code table
    from the DCCODES.DBF Code Table dictionary.
   

Notes:

    The DCCODES.DBF file and its indexes will be created by
    the DC_CodeOpen() function if it they do not already exist.
   

Examples:

    cCodeTable := DC_CODEPICK()
    IF !Empty(cCodeTable)
      aCodeTable := DC_CodeEdit( cCodeTable )
    ENDIF
   

Source/Library:

  _DCCODES.PRG, DCLIP1.DLL

See Also:

   dc_codeedit()
   dc_codeget()

dc_coderename()

Rename a Code Table

Syntax:

   DC_CodeRename( [< cTableName >], ;
                  [< cNewName >], ;
                  [< cNewDesc >] ) - > lStatus
   

Arguments:

   < cTableName > is the name of the table to rename.  This is a
   name of up to 10 characters.  If no name is given, then a pick
   list of all code tables will be displayed.
   
   < cNewName > is the new name.  If no name is given, then a
   dialog window will be displayed to enter a new name.
   
   < cNewDesc > is the new description.  If no description is given,
   the old description will be used.
   

Returns:

    A logical .TRUE. if the rename was successful.
   

Description:

    DC_CodeRename() is used to rename a Code Table.
   

Examples:

    DC_CodeRename( 'BULLET', 'BULLETS' )
   

Source/Library:

  _DCCODES.PRG, DCLIP1.DLL

See Also:

   CODE RENAME
   dc_codeedit()

dc_codesave()

Save a code table array to the Code Table file

Syntax:

   dc_codesave ( < aCodeTable >, ;
                 [< lExport >] ) - > lStatus
   

Arguments:

   < aCodeTable > is a code table array that conforms to the
   specification of the array documented in RETURNS for the
   function DC_CODEEDIT().
   
   < lExport > if .TRUE. will save to the DXCODES.DBF (import/export)
   file rather than DCCODES.DBF.
   

Returns:

    A logical .TRUE. if the code table was saved, .FALSE. otherwise.
   

Description:

    DC_CODESAVE() is used to save a code table array to the
    DCCODES.DBF dictionary file.
   

Notes:

    The DCCODES.DBF file and its indexes will be created by
    the DC_CodeOpen() function if it they do not already exist.
   

Examples:

    aCodeTable := DC_CodePick()
    aCodeTable := DC_CodeEdit( aCodeTable )
    DC_CODESAVE( aCodeTable )
   

Source/Library:

  _DCCODES.PRG, DCLIP1.DLL

See Also:

   dc_codeedit()
   dc_codeget()
   dc_codeload()

dc_color()

Set the current screen color value

Syntax:

   DC_Color ( < cColorString > | < nColorElement >,  ;
              [< lSelectBar >], ;
              [< lReverseVideo >] ) - > cColorString
   

Arguments:

   < cColorString > is the color string value to set.  See the
   color definitions in DCCOLOR.CH.  String definitions start
   with cC_*.
   
     or
   
   < nColorElement > is the number of the color based on the table
   of Numeric color definitions in DCCOLOR.CH.  Numeric definitions
   start with nC_*.
   
   < lSelectBar > if .TRUE. will set the color to "highlight" if
   application is being run on a monochrome monitor or COLOR_MON
   is .FALSE.
   
   < lReverseVideo > is used only if < lSelectBar > is .TRUE.  If
   .TRUE., this argument will set highlight to "reverse video".
   

Returns:

    A numeric value equal to the palette number of the new color palette.
   

Description:

    DC_COLOR() is a replacement for SETCOLOR().  DC_COLOR()
    automatically tests the status of ISCOLOR() and a STATIC
    variable named COLOR_MON to determine if the application is
    being run on a color monitor. This allows the programmer or
    user to enable all color output dynamically by simply turning
    color on or off with the DC_COLORSET() function.
   

Examples:

    #include "dccolor.ch"
   
    // Set color to Browse menus frame color
    // Use numeric value - nC_BRMENUF is defined as 2
    // This is the preferred method for speed and code size
    // Use this method if you are using dCLIP colors
    DC_COLOR( nC_BRMENUF )
   
    // Set color to Browse menus frame color
    // Use Character string value
    // cC_BRMENUF is defined as DCCOLOR[DCCOLOR[1]+1,2]
    // This method is provided only for backward compatability
    DC_COLOR( cC_BRMENUF )
   
    // Set color to 'BG+/W'
    // Use Character string value
    DC_COLOR( 'BG+/W' )
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

dc_color2array()

Convert a color string to an array

Syntax:

   DC_Color2Array( [< cColorString >] ) - > aColor
   

Arguments:

   < cColorString > is a valid Clipper color string.  If no
   parameter is passed, then the current SETCOLOR() will be
   used.
   

Returns:

    An array of 5 elements;
   
    Element  Type  Color
    -------  ----  -------------------------
      [1]     C    Standard (screen output)
      [2]     C    Enhanced (GETS, hilites)
      [3]     C    Border
      [4]     C    Background (unsupported)
      [5]     C    Unselected GETS
   

Description:

    DC_COLOR2ARRAY() is a handy function which is used to convert
    a standard "complex" Clipper color string to an array of
    individual colors.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL cColorString := 'W+/B,,N/BG'
   
    DC_Gui(.t.)
   
    DC_MsgBox( DC_COLOR2ARRAY() )
   
    DC_MsgBox( DC_COLOR2ARRAY( cColorString ) )
   
    RETURN
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_color()

dc_color2gra()

Convert a color string to a GUI compatible color

Syntax:

   DC_Color2Gra( [< cColorString >] ) - > aColor
   

Arguments:

   < cColorString > is a valid Clipper color string.  If no
   parameter is passed, then the first color in the current
   SETCOLOR() will be used.
   

Returns:

    An array of 2 elements;
   
    Element  Type  Description
    -------  ----  -------------------------
      [1]     N    ForeGround Color
      [2]     N    BackGround Color
   

Description:

    DC_COLOR2GRA() is used to convert a Text-Based color string
    to a 2 element array containing a foreground and background
    color which is compatible with GUI objects.
   

Examples:

    #include 'dcdialog.ch'
   
    PROCEDURE XTest()
   
    LOCAL GetList := {}, cColor := 'GR+/R', aPres, aColor
   
    aColor := DC_Color2Gra(cColor)
   
    aPres := { {XBP_PP_FGCLR, aColor[1]},;
               {XBP_PP_BGCLR, aColor[2]} }
   
    @ 0,0 DCSAY 'This should be yellow on red' SAYSIZE 40,2 ;
      FONT 'Helv.32' COLOR aColor[1], aColor[2]
   
    DCREAD GUI ;
      FIT ;
      ADDBUTTONS
   
    RETURN
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_say()
   dc_gra2color()

dc_coloradd()

Add a new color set to the Color Array

Syntax:

   DC_ColorAdd ( ) - > nPalette
   

Arguments:

    NONE
   

Description:

    DC_COLORADD() will add a new color palette set to the color
    array and save the contents to DCCOLOR.AR for restoring with
    the DC_CLRARR() initialize function.
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

dc_colordel()

Delete a color set from the Color Array

Syntax:

   DC_ColorDel ( [< nPalette >] ) - > lStatus
   

Arguments:

   < nPalette > is the number of the color palette to delete.  You
   cannot delete color palette number 0 or 1, so this number must
   be greater than 1.  If no argument is given, then a pick-list
   of palette descriptors will be displayed.
   

Description:

    DC_COLORDEL() is used to delete a color palette that was
    created with DC_COLORADD().
   

Examples:

    . nPalette := dc_coloradd()
    . DC_COLORDEL( nPalette )
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_coloradd()

dc_colorlist()

Convert a GRA_CLR_* numeric index to a description array

Syntax:

   DC_ColorList( < nColor >,  ;
                 [@< aColorTypes >], ;
                 [@< aColors >] ) - > cColor
   

Arguments:

   < nColor > is an index from -5 to 15.
   
   @< aColorTypes > is an optional memory variable to store a
   single-dimensional array of 21 characters representing the
   colors for index values from -5 to 15.
   
   @< aColors > is an optional memory variable to store a
   multi-dimensional array of 21 sub-elements representing the
   colors for index values from -5 to 15.
   

Returns:

    A Character String
   

Description:

    DC_COLORLIST() is used create an array of character strings that
    represent a conversion of standard GRA_CLR_* numeric values.
    This is a handy function which is used to create a picklist of
    colors by color name.
   

Examples:

    #include 'gra.ch'
   
    PROCEDURE XTest()
   
    LOCAL nColor := GRA_CLR_GREEN, aColorList, aColors, cColor
   
    cColor := DC_ColorList( nColor, @aColorList, @aColors )
   
    DC_Gui(.t.)
   
    DC_MsgBox( { cColor, ;
                 aColorList[GRA_CLR_DARKGRAY], ;
                 aColors[GRA_CLR_YELLOW] } )
   
    DC_MsgBox( aColorList )
   
    RETURN
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

dc_colormode()

Enable or Disable Color / Monochrome display mode

Syntax:

   DC_ColorMode ( [< lColorOn >] ) - > lStatus
   

Arguments:

   < lColorOn > if .TRUE. will enable the color display, if .FALSE.
   will enable monochrome display.
   

Description:

    DC_COLORMODE() is used to enable or disable the color display.
    Use this function to disable color mode when using dCLIP
    functions in an application that is running on a monochrome
    display with a color driver board that returns an ISCOLOR() of
    .true.
   

Examples:

    . DC_COLORMODE(.f.)  // disable color display
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_color()

dc_colorrest()

Restore a color set

Syntax:

   DC_ColorRest( < nPalette > ) - > nil
   

Arguments:

   < nPalette > is the number of the palette that was saved with the
   DC_SAVECOLOR() function.
   

Description:

    DC_COLORREST() is used to restore a color palette that was
    previously saved with DC_COLORSAVE().
   

Examples:

    . nPalette := dc_colorsave()  // save color palette
    . do something
    . DC_COLORREST( nPalette )    // restore old color palette
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_colorsave()

dc_colorsave()

Save the current color set

Syntax:

   DC_ColorSave() - > nPalette
   

Arguments:

    NONE
   

Description:

    DC_COLORSAVE() is used to save the number of the currently
    selected color palette for later restoring with DC_COLORREST().
    Use DC_COLORSAVE() and DC_COLORREST() if you are calling a
    function that might select a different color palette such as
    DC_BROWSEDB().
   

Examples:

    . nPalette := DC_COLORSAVE()  // save selected palette number
    . do something
    . dc_colorrest( nPalette )    // restore old color palette
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_colorrest()

dc_colorsel()

Select a color set from the Color Array

Syntax:

   DC_ColorSel( [< nPalette >] ) - > nPalette
   

Arguments:

   < nPalette > is the number of the color palette to select.  If no
   argument is passed then the number of the currently selected
   palette will be returned.  If a 0 is passed or if the number is
   not a valid palette number then a pick-list of available palette
   descriptions will be displayed.
   

Description:

    DC_COLORSEL() is used to select a color palette.  The default
    number of palettes in the dCLIP color system is one (1), so
    this function is useful only after creating extra color
    palettes with the DC_COLORADD() function.
   
    Multiple color palettes are provided in the dCLIP system for
    the following purpose:
   
    1. To allow the user to select a different color set when using
       dCLIP functions in applications that must be run on multiple
       display systems.  For example, if you work with dCLIP part
       time on a color monitor and part time on an LCD display, you
       can create color palettes that are "optimized" for you
       display type.
   
    2. To allow the user to select different color sets for
       different windows in an application.
   

Examples:

    . nPalette := dc_colorsave()
    . DC_COLORSEL(0)            // select a color palette
    . do something
    . dc_colorrest( nPalette )  // restore the old palette
   

Source/Library:

  _DCCLR2.PRG/.OBJ, DCLIPX.LIB

dc_compile()

Compile a source .PRG or all changed .PRGs

Syntax:

    DC_Compile ( [< cFileName >], ;
                 [< cCompOpt >], ;
                 [< lQuiet >], ;
                 [< lWindow >], ;
                 [< lReCompile >] ) - > lStatus
   

Arguments:

   < cFileName > is the name of the file to compile.  If this
   argument is left blank, then all .PRG files which have a later
   date stamp than the associated .OBJ file will be compiled.
   
   < cCompOpt > is a string of compiler options.  If no argument is
   given, then the options established by DC_SETT('XPPOPT',< cOptions >),
   SET XPPOPT TO < cOptions > or XPPOPT=< cOptions > (DCLIP.SYS)
   are
   used as the default.
   
   < lQuiet > if .TRUE. will prevent displaying the status after
   compiling. If .FALSE. (default), then all errors will be
   displayed.
   
   < lWindow > if .TRUE. (default) will display a window showing the
   compiled results.
   
   < lReCompile > if .TRUE. will force a recompile of
   < cFileName >
   regardless of the date/time of < cFileName >.  If FALSE. (default),
   then < cFileName > will be compiled only if it's date/time stamp
   is later than the date/time stamp of it's associated. .OBJ file.
   

Description:

    DC_COMPILE() compiles a specified .PRG file into an .OBJ file
    or recompiles all .PRG files which have been modified and
    have a later date/time stamp than their associated .OBJ file.
   
    Use DC_COMPILE() after editing your source files.  DC_COMPILE()
    checks the date and time stamp on .PRG files and compares them
    to the date and time on any corresponding .OBJ files.  If the
    date and/or time on a .PRG is later than the corresponding
    .OBJ, the .PRG will be compiled with the /m option.
   

Notes:

    If <þcFileNameþ> contains a full-path specification of a .PRG
    file, then the compiled .OBJ will be created in the same
    directory as the .PRG file unless the /o compiler switch is
    used to direct the output.
   
    If <þcFileNameþ> does not contain a full path then the .PRG file
    must exist in the current directory or the directory
    established by DC_SETT('PDIR',<þcPathþ>),  SET PDIR TO
   <þcPathþ>
    or PDIR=<þcPathþ> (DCLIP.SYS).
   
    If <þcFileNameþ> does not contain a full path or the /o compiler
    switch is not used, then the compiled .OBJ will be created in
    the directory established by DC_SETT('ODIR',<þcPathþ>),  SET ODIR
    TO <þcPathþ> or ODIR=<þcPathþ> (DCLIP.SYS).
   

Examples:

    accept 'Enter a file to edit and compile' TO cFile
    dc_editprg(cFile)
    DC_COMPILE(cFile,'/n/m/w/l')
   

Source/Library:

  _DCMAKE.PRG

See Also:

   COMPILE
   dc_objload()

dc_completeevents()

Process all events in the event queue

Syntax:

   DC_CompleteEvents() - > nil
   

Arguments:

   None.
   

Returns:

   Nil
   

Description:

   DC_CompleteEvents() is used to process all events in the event
   queue.  Use this function in processing loops when it is
   necessary to react to window events to move the window or to
   affect the processing.
   

Examples:

   FUNCTION XTest()
   
   LOCAL lContinue := .t.
   
   oBusyDlg := DC_BusyOn( SetAppWindow(), ;
                          {||WaitDialog(@lContinue,@oStatus)} )
   
   DO WHILE !Eof() .AND. lContinue
   
     oStatus:setCaption('Processing Record ' + Alltrim(Str(n)))
     SKIP
     DC_CompleteEvents()
   
   ENDDO
   
   DC_BusyOff(oBusyDlg)
   
   RETURN nil
   
   * -------------------
   
   STATIC FUNCTION WaitDialog( lContinue, oStatus )
   
   LOCAL GetList[0], oBusyDlg, GetOptions
   
   @ 0,0 DCSAY "Processing" FONT '20.Arial Bold' SAYSIZE 0
   
   @ 2,0 DCSAY '' OBJECT oStatus COLOR GRA_CLR_BLUE FONT '12.Arial Bold' SIZE 30
   
   @ 4,8 DCPUSHBUTTON CAPTION 'Cancel' ACTION {||lContinue := .F. } SIZE 9, 1.2
   
   DCGETOPTIONS NOTITLEBAR HIDE
   
   DCREAD GUI FIT EXIT PARENT @oBusyDlg OPTIONS GetOptions
   
   RETURN oBusyDlg
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_clearevents()
   dc_saveevents()
   dc_restoreevents()

dc_configdialogbuttons()

Configure buttons in title bar area of dialog window

Syntax:

   DC_ConfigDialogButtons( < oDlg >, ;
                           < nOption > ) - > nil
   

Arguments:

   < oDlg > is the Dialog object to configure.
   
   < nOption > is an option, defined in DCDIALOG.CH:
   
    DLG_BUTTON_HELP_NOMINMAX
    DLG_BUTTON_NONE
    DLG_BUTTON_DISABLEMAX
   

Description:

   DC_ConfigDialogButtons() is used to configure the buttons in
   the titlebar area of a dialog window.
   
   For example, the buttons can be configured to disable the
   Maximize button in a child window.
   

Examples:

   DCREAD GUI EVAL ;
         {|o|DC_ConfigDialogButtons(o,DLG_BUTTON_DISABLEMAX)}
   

Source/Library:

  DCLIPX.LIB, DCLIPX.DLL

dc_copynew()

Copy only new files to another directory

Syntax:

    DC_CopyNew( [< cFromSpec >], ;
                [< cToSpec >] ) - > lStatus
   

Arguments:

   < cFromSpec > is the specification of the file(s) to copy from.
   If this argument is not given, then a dialog will be displayed
   prompting the user for the file specification.
   
   < cToSpec > is the specification of the directory to copy to.
   If this argument is not given, then a dialog will be displayed
   prompting the user for the directory specification.
   

Returns:

    A logical .TRUE. if any files were copied.
   

Description:

    DC_CopyNew() is used to copy a file or set of files to another
    directory only if they are newer than the sames files in the
    destination directory.
   
    A dialog window will display the status of all files copied.
   

Examples:

    DC_CopyNew('*.TXT','C:\express\sample')
   

Source/Library:

  _DCCOPYN.PRG, DCLIP1.DLL

See Also:

   COPYNEW

dc_count()

Count records in selected database

Syntax:

    DC_Count() - > lStatus
   

Arguments:

    None.
   

Returns:

    A logical .TRUE. if the count was not aborted.
   

Description:

    DC_Count() is used to count records from the currently selected
    database based on a set of conditions.  As GUI dialog window
    is displayed for the user to select the conditions.
   

Examples:

    . USE COLLECT
    . DC_Count()
   

Source/Library:

  _DCSUM.PRG, DCLIP2.DLL

See Also:

   COUNT

dc_create()

Create a new database

Syntax:

    DC_Create( < cDataBase > ) - > lStatus
   

Arguments:

   < cDataBase > is the name of the new database to create.  If you
   do not include an extension, then the default extension for the
   currently selected database driver will be used.
   

Returns:

    A logical .TRUE. if the database was successfully created.
   

Description:

    DC_Create() is used to create a new database from a menu in which
    the user is prompted for entering field names, types, lengths,
    etc.
   
    The currently selected default DBE is used when the new database
    is created.
   

Examples:

    . SET DBE TO FOXCDX
    . DC_Create('JUNK')
   

Source/Library:

  _DCFCSTR.PRG, DCLIP1.DLL

See Also:

   CREATE

dc_crindex()

Create an index file

Syntax:

    DC_CrIndex() - > lStatus
   

Arguments:

    None.
   

Returns:

    A logical .TRUE. if the index was created successfully, .FALSE.
    otherwise.
   

Description:

    DC_CRINDEX() is a high-level function that provides a
    user-interface menu for creating a new index file.
   

Examples:

    . USE COLLECT
    . DC_CrIndex()
   

Source/Library:

  _DCDBIND.PRG, DCLIP1.DLL

See Also:

   INDEX ON

dc_crtrun()

Run a text-based procedure in a new CRT Window

Syntax:

    DC_CrtRun( < bBlock >, ;
               [< cTitle >], ;
               [< cColorString >], ;
               [< oParent >], ;
               [< oOwner >], ;
               [< lUnique >], ;
               [< aOptions >], ;
               [< lModal >], ;
               [@< oCrt >], ;
               [< lSuspend >], ;
               [< lGui >] ) - > lStatus
   

Arguments:

   < bBlock > is the code block to evaluate after the CRT window
   is created or selected.
   
   < cTitle > is the title to place into the title bar of the CRT
   window.
   
   < cColorString > is the color to clear the CRT window.
   
   < oParent > is the parent of the CRT window.  If this parameter is
   not passed, then the parent will be AppDeskTop().
   
   < oOwner > is the owner of the CRT window.  If this argument is
   not passed, then the owner is the parent.
   
   < lUnique > if .TRUE. will create the CRT window and run the
   code block only if there is not a window already running with the
   same code block.  The default is .FALSE.
   
   < aOptions > is an array of display options:
   
      Element Type Description
      ------- ---- -----------------------------------------------
        [1]     N  Font Width (Default is 8)
        [2]     N  Font Height (Default is 12)
        [3]     C  Font Name (Default is Alaska Crt)
        [4]     N  Window Icon (Default is DC_IconDefault())
        [5]     N  Text Rows
        [6]     N  Text Columns
   
   < lModal > if .TRUE. will make the CRT window MODAL if it is not
   a child window.
   
   @< oCrt > is the name of a variable to store a pointer to the
   Crt Window object that is created.
   
   < lSuspend > is RESERVED.
   
   < lGui > is used to set the DC_Gui() flag.
   

Returns:

    A logical .TRUE. if the text procedure was executed successfully.
   

Description:

    DC_CrtRun() is used to run a text-based procedure in a new
    CRT Window.
   
    The function DC_CrtRunWindow() is used to store a pointer to
    any existing XbpCrt() class window to use.  If this function
    returns anything other than an XbpCrt() object, then a new
    CRT window is created before the code block is evaluated and
    then destroyed after returning from the code block.
   

Examples:

    . DC_CrtRun( {||DC_ChrSel()}, 'ASCII Chart', 'N/W' )
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_crtrunwindow()
   dc_crtwindow()
   dc_qout()
   dc_gui()

dc_crtrunwindow()

Set the CRT Window for DC_CrtRun()

Syntax:

    DC_CrtRunWindow( [< oCrt >] ) - > oCrtWindow
   

Arguments:

   < oCrt > is a pointer to an XbpCrt() class CRT window.
   

Returns:

    A pointer to the previous CRT window.
   

Description:

    DC_CrtRunWindow() is used to store a pointer to any existing
    XbpCrt() class window to use later with DC_CrtRun().  If this
    function returns anything other than an XbpCrt() object, then
    DC_CrtRun() will create a new window before the code block is
    evaluated and then destroyed after returning from the code
    block.
   

Examples:

    . oCrt := DC_CrtWindow()
    . DC_CrtRunWindow(oCrt)
    . DC_CrtRun( {||DC_ChrSel()}, 'ASCII Chart', 'N/W' )
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_crtrun()
   dc_crtwindow()
   dc_qout()

dc_crtwindow()

Create a Crt Window to be used later with DC_CrtRun()

Syntax:

    DC_CrtWindow( [< cTitle >], ;
                  [< cColorString >] ) - > oCrtWindow
   

Arguments:

   < cTitle > is the title to place into the title bar of the CRT
   window.
   
   < cColorString > is the color to clear the CRT window.
   

Returns:

    A pointer to the newly created CRT Window (an XbpCrt object).
   

Description:

    DC_CrtWindow() is used to create a CRT Window which will be
    used later with DC_CrtRun().
   
    The function DC_CrtRunWindow() is used to store a pointer to
    any existing XbpCrt() class window to use.  If this function
    returns anything other than an XbpCrt() object, then a new
    CRT window is created before the code block is evaluated and
    then destroyed after returning from the code block.
   

Examples:

    . oCrt := DC_CrtWindow()
    . DC_CrtRunWindow(oCrt)
    . DC_CrtRun( {||DC_ChrSel()}, 'ASCII Chart', 'N/W' )
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_crtrunwindow()
   dc_qout()

dc_csv2workarea()

Import a CSV file to an open work area

Syntax:

   DC_Csv2WorkArea() - > < lStatus >
   

Returns:

   A logical .TRUE. if file was successfully imported, .FALSE. otherwise.
   

Description:

   DC_Csv2WorkArea() loads a CSV file into a work area.
   
   The top line of the CSV file must contain the field names that
   match the work area.
   

Examples:

   See the example in \exp19\samples\csv\csvimp2.prg.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

dc_curpath()

Get the current dos directory

Syntax:

   DC_CurPath ( [< cDrive >] ) - > cDirectory
   

Arguments:

   < cDrive > is the drive to report the currently selected
   directory. If no argument is given, then the currently selected
   drive is the default.
   

Returns:

    A character string representing the selected drive and directory.
   

Description:

    DC_CURPATH() reports the currently selected DOS directory for
    any specified drive.
   

Examples:

    PROCEDURE XTest()
   
    DC_Gui(.t.)
   
    dc_chdir('C:\ALASKA\XPPW32')
    DC_MsgBox( DC_CURPATH() )
   
    dc_chdir('\EXPRESS\SAMPLE')
    DC_MsgBox( DC_CURPATH('C:') )
   
    RETURN
   

Source/Library:

  _DCPATH.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setdclip()
   dc_setdefault()

dc_dataconvert()

Convert a database to a different DBE driver

Syntax:

    DC_DataConvert( [< cFileName >], ;
                    [< cFromDBE >], ;
                    [< cToDBE >], ;
                    [< cExtension >] ) - > lStatus
   

Arguments:

   < cFileName > is the name of the database to convert.  If this
   argument is not passed a GUI dialog window will be displayed to
   enter information required.  Enter ALL to convert all databases
   with a specified extension.
   
   < cFromDBE > is the DBE to use to open < cFileName >.
   
   < cToDBE > is the DBE to use to create the converted file.
   
   < cExtension > is the extension to use when using ALL as the
   file name
   

Returns:

    A logical .TRUE. if the conversion was successful.
   

Description:

    DC_DataConvert() is used to convert a database to use another
    DBE driver.
   

Examples:

    // convert all files that have a .DBT memo file.
    . DC_DataConvert('COLLECT','DBFNTX','FOXCDX','.DBT')
   
    // convert all files that have a .DBF extension
    . DC_DataConvert('ALL','DBFNTX','DBFCDX','.DBF')
   

Source/Library:

  _DCRDD.PRG, DCLIP2.DLL

See Also:

   DATACONVERT

dc_datarest()

Restore work areas

Syntax:

    DC_DataRest( < aWorkArea > ) - > lStatus
   

Arguments:

   < aWorkArea > is a multidimensional array created by the SAVE DATA
   command or DC_DataSave() function.
   

Returns:

    A logical .TRUE. if workareas were successfully restored.
   

Description:

    DC_DATAREST(aWork) will reopen all databases, indexes and relations
    from the array created by DC_DATASAVE().  This function is handy
    when it is necessary to insure that database work areas are restored
    to their original condition after calling a routine that may close
    files, open files, select different indexes or clobber relations.
   

Examples:

    . USE EXPRESS ALIAS XDOC VIA FOXCDX INDEX EXPRESS
    . SET TAG TO COMMAND
    . aWorkArea := DC_DataSave()
    . CLOSE ALL
    . DC_DataRest(aWorkArea)
   

Source/Library:

  _DCRDD.PRG, DCLIP2.DLL

See Also:

   dc_datasave()

dc_datasave()

Save info about all open workareas to an array

Syntax:

    DC_DataSave() - > aWorkArea
   

Arguments:

    None.
   

Returns:

    A multidimensional array.
   

Description:

    DC_DATASAVE() will store all work area info to an array.
   
    DC_DATAREST(aWork) will reopen all databases, indexes and relations
    from the array created by DC_DATASAVE().  This function is handy
    when it is necessary to insure that database work areas are restored
    to their original condition after calling a routine that may close
    files, open files, select different indexes or clobber relations.
   

Examples:

    . USE EXPRESS ALIAS XDOC VIA FOXCDX INDEX EXPRESS
    . SET TAG TO COMMAND
    . aWorkArea := DC_DataSave()
    . CLOSE ALL
    . DC_DataRest(aWorkArea)
   

Source/Library:

  _DCRDD.PRG, DCLIP2.DLL

See Also:

   dc_datarest()

dc_dbchcreate()

Create a database or array pick-list object

Syntax:

   DC_DbChCreate ( < aOptions >, ;
                   < aColumns >, ;
                   [< aTags >], ;
                   [< aData >] ) - > aObject
   

Arguments:

   < aOptions > is an array defining the pick-list window size,
   color, function, and array data when browsing an array.
   
   Element Type   Description
   ------- ----  -----------------------------------------------
      1     N     Start display row
      2     N     Start display column
      3     N     End display row
      4     N     End display column
      5     C     Heading at top of window
      6     C     Menubar at top or bottom of window.  The first
                  character in each word will be highlighted
                  or the first character after any tilde ~
                  character will be highlighted.
      7     C     A color string for the box and lines
      8     C     A color string for the data items
      9     C     A color string for the data select bar
     10     C     A color string for column headings
     11     C     A color string for the menu bar at the bottom
                  of the window.  This is a two-color string
                  (separated by a comma).  The first color is
                  the bar and words, the second is the highlight
                  color.
     12     L     If .TRUE. then "Auto-Seek" mode will be enabled.
                  Auto-Seek will cause the pick-list to
                  automatically seek to the item whose index key
                  matches the sequence of keys pressed.
     13  C/N/D/L  A value to include in a "One-To-Many" style
                  pick-list.  The type of this value must match
                  the index key of the database.  Only database
                  items that match this value will be included
                  in the display.  This is provided for compatability
                  with previous versions.  Parameters 19/20 are
                  recommended for one-to-many browses.
     14     L     If .TRUE. then a "Tagging" Column will be
                  displayed.  All records or array elements which
                  have been tagged will contain a check mark.  The
                  operator may tag/untag records with the SPACE bar
                  key, TAG records with the LEFT mouse key, or UNTAG
                  records with the RIGHT mouse key.
     15     N     The INKEY() value of the key to assign as the
                  Record Tagging key.  The default is 32 (Space bar).
     16     L     If .FALSE. will display menu at bottom.
                  If .TRUE. will display menu at top (default).
     17     N     Starting array element to browse
     18     N     Subscript number of data array that is used for
                  holding tags.  This is required if Tag Mode is
                  enabled and you are browsing an array rather than
                  a database.  The tags must all be initialized to
                  a logical value.
     19  C/D/N/L  A value that defines the SCOPE TOP of the database
                  for one-to-many browses.
     20  C/D/N/L  A value that defines the SCOPE BOTTOM of the
                  database for one-to-many browses.
     21     A     An optional array of 10 elements.  Each element
                  is a character string to display as the mouse
                  "prompt" message when the mouse is placed over
                  one of the 10 mouse buttons at the bottom of
                  the window.  The 10 default messages are defined
                  in the _DCDBCHO.PRG source code.
   
   Note:  If color elements are not passed, then the system
          default colors will be used.
   
   < aColumns > is a multi-dimensional array that defines the
   columns in the pick-list window.  One sub-array is required
   for each column in the window.
   
   Element   Type    Description
   -------  ------- --------------------------------------
      1       C      Expression to evaluate
          or  B      Code-Block to evaluate
          or  N      Array sub-element number (array browse mode)
   
      2       C      Column title
   
      3       N      Column width.  If 0, then column will
                     automatically size to expression output
                     width.
   
      4       C      Code Block to pass to SETCOLOR()
                     For example, this could be the name of a color
                     field in a database and would be passed as
                     follows: {||APPT_COLOR} .OR. {||'W+/B'}.
   
   < aTags > is an optional array of record numbers which will
   may be modified by the operator.  If no valid array name is
   passed and the Tag Mode option was enabled in < aOptions >
   then the DCTAGS public array will be used for storing the
   record tags. If browsing an array, then the tags are handled
   by including a sub-element in the array being browsed.
   
   < aData > is an optional multi-dimensional array to browse.
   If any value other than an array is passed then the current
   database workarea will be browsed.  If tagging is enabled,
   then one of the elements of each sub-array is used to hold
   the logical tag value.
   

Returns:

    A multi-dimensional array to be passed to DC_DBCHOICE() for
    pick-list operations.
   

Description:

    DC_DBCHCREATE() is used to create a database pick-list object
    or an array pick-list object to be used with DC_DBCHOICE().
   
    This function is used to create "fully-moused" database or
    array pick-lists.
   

Examples:

    -- Example 1 --
   
    // Using DC_DBCHCREATE() / DC_DBCHOICE() as a main menu for
    // help database
   
    local aObject := ;
       DC_DBCHCREATE( { 0, 0, MaxRow(), 79, ' Help Menu ',;
                     ' Edit     View     Search     Print' },;
                      { { 'TYPE','Function Type', 15 } ,;
                        { 'COMMAND','Command Syntax' },;
                        { 'SHORT','Description' } } )
    local nInkey, lPaintScrn := lExplode := .t.
   
    do while  .t.
   
      select dchelp
      aObject := ;
          dc_dbchoice( aObject, @nInkey,, lPaintScrn, lExplode )
      cCode := chr(nInkey)
      store .f. TO lPaintScrn, lExplode
   
      do case
   
        case nInkey=27
          exit
   
        case nInkey <= -101
          dc_mousekey( { {MaxRow(),0,MaxRow(),9,'E'},;
                         {MaxRow(),11,MaxRow(),20,'V'},;
                         {MaxRow(),22,MaxRow(),29,'S'},;
                         {MaxRow(),31,MaxRow(),37,'P'} } )
   
        case cCode='E'
          do editmenu
        case cCode='V'
          do viewmenu
        case cCode='S'
          do searchmenu
        case cCode='P'
          do printmenu
   
      endcase
   
    enddo
   
   
    -- Example 2 --
   
    // Using DC_DBCHCREATE() / DC_DBCHOICE() to pick a printer
    // record.
   
    local nInkey
    local aObject := ;
      DC_DBCHCREATE( { 2,15,MAXROW()-1, 65, 'Select a Printer' } ,;
                             { {'PTR_DESC','Description'} ,;
                               {'STR(RECNO(),6)','Number' } } )
    DC_DBCHOICE( aObject, @nInkey )
    IF nInkey = K_ENTER
      RETURN RECNO()
    ELSE
      RETURN 0
    ENDIF
   
   
    -- Example 3 --
   
    // Using DC_DBCHCREATE() / DC_DBCHOICE() to create a
    // directory pick-list with an array for tagging files.
   
    local aObject, aDirectory := Directory('*.*'), nInkey, nChoice
    local i
   
    for i := 1 TO len(aDirectory)
      aadd( aDirectory[i], .f. )  // add element for tag
    next
   
    aObject := ;
      DC_DBCHCREATE( {2,7,20,73, ' Tag file(s) ',,,,,,,,,.t.,,.t.,,6},;
        { { 1,'Name',12 } ,;
          { 2,'Size',10 } ,;
          { 3,'Date',8 } ,;
          { 4,'Time',8 } ,;
          { 5,'Attr',5 } } ,, aDirectory )
   
    aObject := DC_DBCHOICE( aObject, @nInkey,, .f., .f. )
    for i := 1 to len(aDirectory)
      if aDirectory[i,6]  // tagged element
        if dc_msgbox(,,{aDirectory[i,1],'Delete File?'},,,,.t.)
          Ferase( aDirectory[i,1] )
        endif
      endif
    next
   

Source/Library:

  _DCDBCHOI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dbchoice()
   dc_readdpick()

dc_dbchoice()

A browse-style, moused, database/array pick-list

Syntax:

   DC_DbChoice ( < aObject >, ;
                 @< nInkey >, ;
                 [< cUdfName >], ;
                 [< lPaintItems >], ;
                 [< lPaintWindow >], ;
                 [< lExit >], ;
                 [< nStartRow >], ;
                 [< aTags >] ) - > aObject
   

Arguments:

   < aObject > is an array of window and field information created
   by DC_DBCHCREATE().
   
   @< nInkey > is a memory variable (passed by reference) to store
   the value of the key hit or mouse-event used to exit the
   pick-list.
   
   < cUdfName > is a User defined function to call between
   keystrokes.
   
   < lPaintItems > if .TRUE. will repaint all items in the display.
   
   < lPaintWindow > if .TRUE. will repaint the entire display window
   and all items.
   
   < lExit > if .TRUE. will exit after painting the window and/or
   items. If .FALSE. then DC_DBCHOICE() will exit only if a key is
   hit that is a non-navigation key.
   
   < nStartRow > is the display row to place the select bar.
   
   < aTags > is an optional array of record numbers which will
   may be modified by the operator.  If no valid array name is
   passed and the Tag Mode option was enabled in the < aObject >
   then the DCTAGS public array will be used for storing the
   record tags.
   

Description:

    DC_DBCHOICE() is a database pick-list function that supports
    one-to-many style picklists, Auto-seeking operation, record
    tagging, and mouse.
   
    DC_DBCHOICE() is used with an array object created by
    DC_DBCHCREATE().
   

Examples:

    -- Example 1 --
   
    // Using DC_DBCHCREATE() / DC_DBCHOICE() as a main menu for
    // help database
   
     local aObject := ;
       dc_dbchcreate( { 0, 0, MaxRow(), 79, ' Help Menu ',;
                     ' Edit     View     Search     Print' },;
                      { { 'TYPE','Function Type' } ,;
                        { 'COMMAND','Command Syntax' },;
                        { 'SHORT','Description' } } )
    local nInkey, lPaintScrn := lExplode := .t.
   
    do while  .t.
   
      select dchelp
      aObject := ;
         DC_DBCHOICE( aObject, @nInkey,, lPaintScrn, lExplode )
      cCode := chr(nInkey)
      store .f. TO lPaintScrn, lExplode
   
      do case
   
        case nInkey=27
          exit
   
        case nInkey <= -101
          dc_mousekey( { {MaxRow(),0,MaxRow(),9,'E'},;
                         {MaxRow(),11,MaxRow(),20,'V'},;
                         {MaxRow(),22,MaxRow(),29,'S'},;
                         {MaxRow(),31,MaxRow(),37,'P'} } )
   
        case cCode='E'
          do editmenu
        case cCode='V'
          do viewmenu
        case cCode='S'
          do searchmenu
        case cCode='P'
          do printmenu
   
      endcase
   
    enddo
   
   
    -- Example 2 --
   
    // Using DC_DBCHCREATE() / DC_DBCHOICE() to pick a printer
    // record.
   
    local nInkey
    local aObject := ;
       DC_DBCHCREATE( { 2,15,MAXROW()-1, 65, 'Select a Printer' } ,;
                              { {'PTR_DESC','Description'} ,;
                                {'STR(RECNO(),6)','Number' } } )
    DC_DBCHOICE( aObject, @nInkey )
    IF nInkey = K_ENTER
      RETURN RECNO()
    ELSE
      RETURN 0
    ENDIF
   

Source/Library:

  _DCDBCHO.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dbchcreate()

dc_dbcontinue()

Continue Locating a record in a set of Scoped Records

Syntax:

    DC_DbLocate( < bForCondition >, ;
                [< bWhileCondition >], ;
                [< nCount >], ;
                [< xRecordID >], ;
                [< lRest >] ) -- > lFound
   

Arguments:

   < bForCondition > is a code block which contains the search
   condition as a logical expression. The record pointer is moved
   to the next data record until < bForCondition > provides the
   value .T. (true) or until the end of the file is reached.
   
   < bWhileCondition > is an optional code block containing a
   condition as a logical expression. As long as this code block
   provides the value .T. (true), the search continues. The
   operation terminates as soon as < bWhileCondition > returns .F.
   (false).
   
   The optional argument < nCount > specifies the number of records
   searched beginning with the current record.
   
   < xRecordID > is a record ID (for DBF files it is the record
   number) which can be optionally specified. If specified, only
   this record is searched.
   
   The optional logical value < lRest > specifies whether all data
   records of a work area are searched (< lRest >==.F. ), or only
   the records from the current to the last record (< lRest >==.T. ).
   The default value is .F. (false), meaning all data records are
   searched.
   

Returns:

    A logical value.
   

Description:

   The function DC_DbLocate() defines a search condition for each
   work area that is the subject of a sequential search for matching
   records in that work area. The search is also initiated by
   DC_DbLocate() and continued using DC_DbContinue(). In this way
   all records in a work area matching a search condition can be
   found.
   
   The function DC_DbContinue() moves the record pointer in the
   work area until a matching record is found. The matching record
   becomes the current record and DbContinue() returns the
   value.T. (true). The function Found() can also be used to test
   the result of a DbContinue(). If no matching record is found,
   the return value is .F. (false) and the record pointer is
   positioned after the last record. In this case, the function
   Eof() returns the value .T. (true).
   

Notes:

    DC_DbLocate() can be used as a direct replacement for dbLocate()
    because all the parameters are simply passed on to dbLocate()
    if no scope is set.
   

Examples:

    . USE EXPRESS VIA FOXCDX INDEX EXPRESS
    . SET SCOPE TOP TO 'DC_F'
    . SET SCOPE BOTTOM TO 'DC_H'
    . ? DC_DbLocate({||syntax$'DC_G'})
   .T.
    . ? DC_DbContinue()
   .T.
   

Source/Library:

  _DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()
   CONTINUE
   dc_dblocate()

dc_dbcreate()

Create a database from structure in parallel-array format

Syntax:

   DC_DbCreate( < cFileName >, ;
                < aFields >, ;
                < aTypes >, ;
                < aLengths >, ;
                < aDecimals >, ;
                [< cDbe >] ) - > lStatus
   

Arguments:

   < cFileName > is the name of the database to create.
   
   < aFields > is an array of field names.  Each must be a character
   value of no more than 10 characters and must start with an
   Alphabet character.
   
   < aTypes >  is a parallel array of field types.   Each must be a
   character value with a length of 1.  Valid Types are:
   
    "C" - Character
    "D" - Date
    "L" - Logical
    "N" - Numeric
    "M" - Memo
   
   < aLengths > is a parallel array of field lengths.  Each must be
   a numeric value.
   
   < aDecimals > is a parallel array of field decimals.  Each must
   be a numeric value.
   
   
   
    < cDbe > is the name of the DBE to use to create the database.
    If no parameter is passed, then the default DBE will be used.
   

Returns:

    .TRUE. if database is successfully created, .FALSE. otherwise.
   

Description:

    DC_DBCREATE() will create a .DBF style database from a set of
    parallel arrays.  This function is provided in lieu of the
    Xbase++ DBCREATE() function which builds a database from a
    ragged array.  Sometimes it is more convenient to provide the
    data in four "parallel" arrays or four "sub" arrays that in
    "ragged" format.
   

Examples:

    DC_DBCREATE( "CUSTOMER.DBF",;
                 { "CUST_NAME","CUST_NMBR", "BALANCE" },;
                 { "C", "C", "N" },;
                 { 25, 5, 9 },;
                 { 0, 0, 2 } )
   

Source/Library:

  _DCAREA.PRG, DCLIP1.DLL

See Also:

   dc_dbstruct()

dc_dbedit()

A Dual-Mode replacement for DBEDIT()

Syntax:

   DC_DbEdit ( [< nTop >], ;
               [< nLeft >], ;
               [< nBottom >], ;
               [< nRight >], ;
               [< aColumns >], ;
               [< cUserFunc > | < bUserFunc >], ;
               [< acPicture >], ;
               [< acHeading >], ;
               [< acHeadSep >], ;
               [< acColSep >], ;
               [< acFootSep >], ;
               [< acFooting >] ) - > nil
   

Arguments:

   < nTop >, < nLeft >, < nBottom >, < nRight >
   are the screen
   text-based coordinates.
   
   < cUserFunc > | < bUserFunc > is the name of an optional
   User-Defined
   function to call on exception keystrokes.  See the Xbase++
   documentation of ACHOICE() for more information on how to use
   a UDF.  If the parameter is passed as a character string then
   the function must be a PUBLIC, not STATIC function.
   
   < aColumns > is an array whose elements may contain only
   character strings. The character strings contain field names
   or expressions which can be macro expanded to determine the
   value displayed in each column.  DbEdit() displays a column
   on screen for each element in < aColumns >.  If < aColumns > is
   missing, all fields of the work area are displayed.
   
   < acPicture > contains either a parallel array with PICTURE
   formats for formatting values in each individual column or a
   character string containing a PICTURE format for all columns.
   
   < acHeading > contains either a parallel array of character
   strings specifying the column headings for each individual
   column or a character string to be used as the heading for
   all columns.  Multiple row column headings are created when a
   character string contains a semicolon. Where the semicolon
   appears, the column heading is wrapped. When < acHeading > is
   not included, the column headings are created from the
   elements of < aColumns > .  If < aColumns > is also missing,
   the
   field names in the work area are displayed as column headings.
   
   < acHeadSep > contains either a parallel array of heading
   separators to appear between the heading and data area for
   each individual column, or a character expression which
   defines the heading separator for all columns.  Chr(205) is
   used as the default character and displays a double line.
   
   < acColSep > contains either a parallel array of characters used
   to create a separator between each column or a character
   expression defining the heading separator for all columns.
   Chr(179) is used as the default character displays a single
   line.
   
   < acFootSep > contains either a parallel array of footing
   separators to appear between the data area and footer line
   for each individual column or a character expression defining
   the footer separator for all columns. If < acFootSep > is missing,
   no footing separators are displayed.
   
   < acFooting > contains either a parallel array of character
   strings specifying the footer lines for each individual column
   or a character string specifying the footer line for all
   columns.   Multiple footer lines are created when a character
   string contains a semicolon.   Where this semicolon appears,
   the footer line is wrapped.   When < acFooting > is not included,
   no footer lines are displayed.
   

Description:

    DC_DBEDIT() is a Dual-mode replacement for Dbedit().  When
    the GUI flag is ON, DC_DBEDIT() functions similiar to
    DbEdit() except that it is displayed in GUI mode.  When the
    GUI flag is OFF, DC_DBEDIT() functions identical to DbEdit()
    except it is also activated by a mouse.  The left button of the
    mouse is used to select the item in the window.  The right button
    or double-clicking works identical to the ENTER key.
   

Examples:

    PROCEDURE XTest()
   
    DC_Gui(.t.)
   
    USE collect NEW SHARED
    DC_DBEDIT( 5,10,20,75,,{||MyFunc()} )
    RETURN
   
   
    STATIC FUNCTION myfunc
   
    do case
      case lastkey() = asc('C')
        DC_MsgBox('C button pressed')
      case lastkey() = asc('D')
        DC_MsgBox('D button pressed')
      case lastkey() = asc('M')
        DC_MsgBox('M button pressed')
    endcase
    return nil
   

Source/Library:

  _DCDBED.PRG/.OBJ, DCLIPX.LIB

dc_dbeval()

Evaluate set of expression for a database with active Escape

Syntax:

   DC_DbEval ( < bBlock >, ;
               [< bForCondition >], ;
               [< bWhileCondition >], ;
               [< nCount >], ;
               [< xRecordID >], ;
               [< lRest >], ;
               [< lAutoLock >], ;
               [< lEscapeKey >] ) - > NIL
   

Arguments:

    < bBlock > contains a code block which is executed for each data
    record.
   
    < bForCondition > is an optional code block containing a condition
    as a logical expression. < bBlock > is only executed for the data
    records where < bForCondition > returns the value .T. (true).
   
    < bWhileCondition > is an optional code block containing a condition
    as a logical expression. DbEval() terminates as soon as
    < bWhileCondition > returns the value .F. (false).
   
    The optional argument < nCount > specifies the number of records
    for which < bBlock > is evaluated beginning with the current data
    record.
   
    The optional argument < xRecordID > specifies a record ID (for
    DBF files it is the record number). If < xRecordID > is specified,
    the evaluation of < bBlock > begins with the specified record.
   
    The logical value < lRest > optionally specifies whether
   < bBlock >
    is evaluated for all records of a work area (< lRest >==.F. ),
    or only for the records from the current to the last record
    (< lRest >==.T. ). The default value is .F. (false), indicating
     that < bBlock > is evaluated for all data records.
   
    < lAutoLock > if .TRUE. will lock the record before evaluating
    < bBlock >.  The default is .FALSE.
   
    < lEscapeKey > if .TRUE. will terminate the operation if the
    user presses the ESCape key.
   

Returns:

   NIL.
   

Description:

   The database function DC_DbEval() evaluates a code block and
   increments the record pointer of a work area after each execution
   of the code block. When the function is used without the alias
   operator, it moves the record pointer in the current work area.
   By default, DC_DbEval() begins with the first logical record
   and evaluates the code block <þbBlockþ> for each record until the
   last logical record is reached. The number of records for which
   the code block is evaluated can be influenced by the optional
   arguments and the setting of the TOP/BOTTOM scope by the
   DC_SetScope() function.
   
   By specifying code blocks for <þbForConditionþ> or
   <þbWhileConditionþ>,
   a logical condition can be defined which must return the value
   .T. (true) for the code block <þbBlockþ> to be evaluated. The
   <þbForConditionþ> code block is evaluated for all data records.
   When it returns .T. (true), <þbBlockþ> is executed. When
   <þbWhileConditionþ> is specified, <þbBlockþ> is only executed
   until
   <þbWhileConditionþ> returns .F. (false), causing DbEval() to
   terminate.
   
   Alternatively the number of records can be explicitly determined
   with <þnCountþ> or <þlRestþ> . Specifying <þxRecordIDþ>
   positions the
   record pointer on this record and the code block <þbBlockþ> is
   evaluated for this and following records.
   
   DC_DbEval() passes no arguments to the code blocks.
   

Examples:

   #command CLEAN ;
            [FOR <for>] ;
            [WHILE <while>] ;
            [<autolock:AUTOLOCK>] ;
            [<escapekey:ESCAPEKEY>]
     => ;
            DC_DBEVAL( {||clean()}, <{for}>, <{while}>,,, ;
                        <.autolock.>,<.escapekey.> )
   
   DC_SetScope(0,'SMITH')
   DC_SetScope(1,'ROGERS')
   
   CLEAN FOR SHIP_DATE < DATE() AUTOLOCK ESCAPEKEY
   

Source/Library:

  _DCEVAL.PRG/.OBJ, DCLIPX.LIB

dc_dbfile()

Open a database file in a work area

Syntax:

   DC_DbFile( [< cDirectory >], ;
               < cDataFile >, ;
              [< lUserPrompt >], ;
              [< lExclusive >], ;
              [< nWait >], ;
              [< cDbe >], ;
              [< lReOpen >], ;
              [< aStructure >], ;
              [< cAlias >], ;
              [< lNoErrorDisp >], ;
              [< lCreateDbf >], ;
              [@< lStruUpdated >], ;
              [< lStruMessage >] ) - > lStatus
   

Arguments:

   < cDirectory > is the directory to search for the database file.
   If no argument is given or a null ("") argument is passed, then
   the current default directory (SET DEFAULT) will be search,
   followed by the current path directory (SET PATH).
   
   < cDataFile > is the name of the database to open.  If the file
   extension is not included, then the default extension for the
   designated DBE is used.
   
   < lUserPrompt > will pop-up a menu to prompt the user if the file
   cannot be found.
   
   If < lExclusive > is .TRUE., the file will be opened in
   EXCLUSIVE, mode, if .FALSE. it will be opened in SHARED mode.
   If no argument is given the file will be opened in the default
   system mode.
   
   < nWait > is the number of seconds to wait if a SHARED file
   cannot be opened until the user is notified of the error.  ( 0
   - wait forever ).
   
   < cDbe > is the Database Driver to use.  If no argument is given,
   then the currently selected DBE will be used.
   
   < lReOpen > if .TRUE. will reopen the file in the current work
   area even if it is already opened in another work area.
   
   < aStructure > multi-dimensional array that contains the
   structure of the data base.  This array is only required in
   the event that the database could not be found or if you
   want to update any existing database to the new structure.
   A new database will be created from the information in the
   array.  If a code block is passed instead of an array, then it
   will be evaluated.  The code block must return an array of the
   same structure as < aStructure >. If a fifth element is included
   in each sub-array, then a single-record will be appended to
   the newly created database with the default information in
   element 5.
   
   Element   Type    Length   Description
   -------   ----    ------   ----------------------------
     [1]      C         1     Field Name
     [2]      C         1     Field Type (C,D,N,L,M)
     [3]      N         4     Field Length
     [4]      N         2     Field Decimals
     [5]     Any       Any    Field Default value.  Must be
                              same type as Field Type.
   
   < cAlias > is the alias to assign to the work area.  If no
   argument is given, then the name of the database (less the
   extension) will be used as the alias.
   
   < lNoErrorDisp > if .TRUE. will suppress any error window output
   in the event that the file cannot be opened.  If .FALSE.
   (default) then errors will be displayed.
   
   < lCreateDbf > if .TRUE. (default) will create the database
   from the contents of < aStructure > if the database does not
   exist, otherwise if .FALSE., the database will not be
   created.
   
   @< lStruUpdated > is a logical variable (passed by reference).
   If the database structure was updated, this variable will be
   set to .TRUE., otherwise it will be set to .FALSE.
   
   < lStruMessage > if .TRUE. will prompt the user before updating
   the structure.  IF .FALSE. the structure will be updated with
   no prompt.
   

Returns:

    Logical .TRUE. if the file is opened, .FALSE. otherwise.
   

Description:

    DC_DBFILE() is used to open a database file in a manner that
    will prevent runtime errors.  If the file can't be found, the
    user will be prompted to enter a directory path to search, or
    to abort.
   
    If a structure array is passed then the behavior of DC_DBFILE()
    is as follows:
   
    1. If the database is not found in the specified or default
       directory, it will be created from the contents of the
       array.
   
    2. If the database is opened but any of the fields do not
       match the structure of the passed array, then the
       database structure will be updated to the array structure
       and the old data will be retained.
   

Examples:

   local aStructure := ;
     {{'DBF_NAME','C',8,0},;
      {'DESC','C',30,0},
      {'QUERY','C',1000,0}}
   if !DC_DBFILE( DC_SETDCLIP(),'DCQUERY.DBF',.t.,,,'DBFNTX',,;
       aStructure)
     return .F.
   endif
   

Source/Library:

  _DCDBFIL.PRG, DCLIP1.DLL

See Also:

   dc_usearea()
   USE

dc_dbfile2record()

Copy a file to a record object.

Syntax:

   DC_DbFile2Record( < cFileName > ) - > oRecord
   

Arguments:

   < cFileName > is the full path name of the file.
   

Returns:

   A record object.
   

Description:

   DC_DbFile2Record() is used to create a record object from a
   file that was saved by DC_DbRecord2File().
   

Notes:

   A work area must be opened and the structure of the database in
   the work area must be the same as the structure of the database
   record that was saved.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbrecord2file()

dc_dbfname()

Get the full path database name of an open work area

Syntax:

    DC_DbfName ( [< nArea >] ) - > cDbfFileName
   

Arguments:

   < nArea > is the work area.  If no argument is given, then the
   current selected work area is default.
   

Returns:

    A character string.
   

Description:

    DC_DBFNAME() returns the full file name of the database file
    for any work area.
   

Examples:

    . select 2
    . use C:\DCLIP3\DCPRINT
    . select 4
    . use F:\CUSTOMER\INVOICE
    . ? DC_DBFNAME(2)
    C:\DCLIP3\DCPRINT.DBF
    . ? DC_DBFNAME(4)
    F:\CUSTOMER\INVOICE.DBF
   

Source/Library:

  _DCAREA.PRG, DCLIP1.DLL

See Also:

   dc_dbfile()
   dc_usearea()
   USE

dc_dbfsel()

Select a database from a picklist of open files

Syntax:

    DC_DbfSel() - > nWorkArea
   

Arguments:

    None.
   

Returns:

    The numeric value of the work area selected.
   

Description:

    DC_DBFSEL() will pop-up a picklist of all work areas and
    display the alias and database file name open in each work
    area.  It will also allow the user to select an unused work
    area to open a new database.
   

Examples:

    . DC_DbfSel()
   

Source/Library:

  _DCDBFIL.PRG, DCLIP1.DLL

dc_dbgather()

Gather data from a Record Object to the current data record

Syntax:

   DC_DbGather( < oRecord >, ;
                [< lNew >], ;
                [< lCommit >], ;
                [< bLock >], ;
                [< cRecNoField > ) - > < lStatus >
   

Arguments:

   < oRecord > is a record object.
   
   < lNew > if .TRUE. will append a new record.  The default is .FALSE.
   
   < lCommit > if .TRUE. will dbCommit() the change to disk. The
   default is .FALSE.
   
   < bLock > is an optional code block which is called to determine
   how a new record is added.  The default is to append a new record
   to the database.  < bLock > can be used to override the default
   behavior.  This can be used to reuse deleted or blank records
   instead of always appending a new record.
   
   < cRecNoField > isTthe name of a numeric field that contains the
   current record number.  It will be updated with the RecNo().
   This is handy when a record number field is required in SQL
   queries and it needs to be maintained.
   

Returns:

   An array.
   

Description:

   DC_DbGather() is used to gather the data in the iVars of a
   record object into the current record of the currently used
   database, or to create a new record.
   

Examples:

   FUNCTION XTest()
   
   LOCAL oRecord
   
   USE COLLECT
   
   oRecord := COLLECT->(DC_DbRecord():new())
   COLLECT->(DC_DbScatter(oRecord))
   
   @ 1,1 DCSAY 'Description' GET oRecord:descript
   @ 2,1 DCSAY 'Type' GET oRecord:type
   @ 3,1 DCSAY 'Sub-Type' GET oRecord:subtype
   
   DCREAD GUI
   
   COLLECT->(DC_DbGather(oRecord))
   
   RETURN nil
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbscatter()
   dc_dbgatherlog()

dc_dbgatherlock()

Get-Set function to set default lock behavior for DC_DbGather()

Syntax:

   DC_DbGatherLock( [< bLock >] - > bOldLock
   

Arguments:

   < bLock > is an optional code block which is called to determine
   how a new record is added.  The default is to append a new record
   to the database.  < bLock > can be used to override the default
   behavior.  This can be used to reuse deleted or blank records
   instead of always appending a new record.
   

Returns:

   A code block or a NIL.
   

Description:

   DC_DbGatherLock() is a Get-Set function that is used to post a
   code block which is read by DC_DbGather().  This is the default
   value for the <þbLockþ> parameter that is passed to DC_DbGather().
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbgather()

dc_dbgatherlog()

Establish logging data for dc_dbgather()

Syntax:

   DC_DbGatherLog( < aParams > ) - > < aParams >
   

Arguments:

   < aParams > is an array of 6 elements.
   
   Element  Type  Description
   -------  ----  --------------------------------------------------------
     [1]     C    The name of the logging database  Default is 'DATALOG.DBF'
   
     [2]     C    The alias of the logging database. Default is 'DATALOG'
   
     [3]     C    The DBE of the logging database. Defaultis dbeSetDefault().
   
     [4]     A    An array of database aliases to exclude or include from
   logging.
                  This may be a single dimensional array of only aliases (for
                  logging if any field changed) or a multi dimensional array
                  of aliases and field names (for logging if only one or more of
                  specified fields changed).
   
     [5]     B    A code block to evaluate.  This code block must return a
                  character string to store in the "LOGIN" field of the
                  logging file.
   
     [6]     L    Array (element 4) is list of included aliases, otherwise it
                  is a list of excluded databases. Default is .FALSE.
   

Returns:

   An array.
   

Description:

   DC_DbGatherLog() is used to establish the name, alias and dbe of the
   log file when wishing to log all DC_DbGather() transactions.
   
   DC_DbGatherLogBrowse() will browse the log file and display 2
   windows that are used to show the contents of the record before and
   after the write operation.
   

Examples:

   Look at the sample program in \exp19\samples\dbrecord\logging.prg.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbgather()
   dc_dbrecord()
   dc_dbscatter()

dc_dbgatherlogbrowse()

Browse the dc_dbgatherlog() database

Syntax:

   DC_DbGatherLogBrowse() - > nil
   

Arguments:

   None.
   

Returns:

   Nil
   

Description:

   DC_DbGatherLogBrowse() will browse the log file and display 2
   windows that are used to show the contents of the record before and
   after the write operation.
   

Examples:

   See the sample program in \exp19\samples\dbrecord.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbgatherlog()
   dc_dbgather()
   dc_dbrecord()
   dc_dbscatter()

dc_dbgobottom()

Go to the Bottom of a set of Scoped Records

Syntax:

   DC_DbGoBottom () - > nil
   

Arguments:

    None.
   

Returns:

    Nil.
   

Description:

    DC_DBGOBOTTOM() is used to go to the first record in a group of
    "scoped" records.  Scopes are set via the DC_SetScope() function.
    If a scope is not set or the ADSDBE is being used as the data
    driver for the current workarea, then DC_DBGOBOTTOM() simply
    calls dbGoBottom() therefore it can be used as a replacement
    for dbGoBottom().
   

Notes:

Examples:

    #include 'dcdialog.ch'
    #include 'appevent.ch'
   
    PROCEDURE XTest()
   
    LOCAL GetList := {}, oBrowse, aPres, cScopeTop, cScopeBot
   
    USE ..\XDOC\EXPRESS INDEX ..\XDOC\EXPRESS.CDX ;
        VIA FOXCDX ALIAS XDOC
   
    OrdSetFocus('COMMAND')
    DC_KeyStat(.t.)
   
    @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' ;
      SIZE 77,11.8 ;
      FREEZELEFT {1}
   
   
    DCBROWSECOL FIELD XDOC->command ;
      HEADER "Command" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->type  ;
      HEADER "Type" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->short ;
      HEADER "Short Description" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->module ;
      HEADER "Module" PARENT oBrowse ;
   
    DCBROWSECOL FIELD XDOC->category ;
      HEADER "Category" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->see_also ;
      HEADER "See Also" PARENT oBrowse
   
    DCREAD GUI ;
      FIT ;
      ADDBUTTONS ;
      TITLE 'Browse Scoping Demo' ;
      EVAL {||_SetNavBlocks(oBrowse),;
              DC_SetScope(0,'DC_G'),;
              DC_SetScope(1,'DC_K'),;
              DC_DbGoTop(),;
              oBrowse:RefreshAll() }
   
    RETURN
   
    /* -------------------- */
   
    STATIC PROCEDURE _SetNavBlocks( oBrowse )
   
    oBrowse:skipBlock     := {|n| DC_DbSkip(n)    }
    oBrowse:goTopBlock    := {| | DC_DBGoTop()    }
    oBrowse:goBottomBlock := {| | DC_DBGOBOTTOM() }
    oBrowse:phyPosBlock   := {| | Recno()         }
    oBrowse:posBlock      := {| | DC_KeyNo()      }
    oBrowse:lastPosBlock  := {| | DC_KeyCount()   }
    oBrowse:firstPosBlock := {| | 1               }
   
    RETURN
   

Source/Library:

  _DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()

dc_dbgoposition()

Moves the record pointer to a percent position in a work area

Syntax:

   DC_DbGoPosition( < nPercent > ) - > nil
   

Arguments:

   < nPercent > is a numeric value in the range between 0 and 100.
   Zero is equivalent to the first record and 100 indicates the
   last record in a work area.
   

Returns:

    NIL
   

Description:

    DC_DBGOPOSITION() is a replacement (wrapper) for the Xbase++
    function dbGoPosition().  This corrects a problem in
    dbGoPosition() in which the record pointer can be moved to a
    deleted or filtered record thereby causing deleted or filtered
    records to appear in a browse when the vertical scroll thumb
    is used.
   

Notes:

Examples:

    #include 'dcdialog.ch'
    #include 'appevent.ch'
   
    PROCEDURE XTest()
   
    LOCAL GetList := {}, oBrowse, aPres
   
    USE ..\XDOC\EXPRESS INDEX ..\XDOC\EXPRESS.CDX ;
        VIA FOXCDX ALIAS XDOC
   
    OrdSetFocus('COMMAND')
   
    @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' ;
      SIZE 77,11.8 ;
      FREEZELEFT {1}
   
   
    DCBROWSECOL FIELD XDOC->command ;
      HEADER "Command" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->type  ;
      HEADER "Type" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->short ;
      HEADER "Short Description" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->module ;
      HEADER "Module" PARENT oBrowse ;
   
    DCBROWSECOL FIELD XDOC->category ;
      HEADER "Category" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->see_also ;
      HEADER "See Also" PARENT oBrowse
   
    DCREAD GUI ;
      FIT ;
      ADDBUTTONS ;
      EVAL {||_SetNavBlocks(oBrowse),;
              DC_DbGoTop(),;
              oBrowse:RefreshAll() }
   
    RETURN
   
    /* -------------------- */
   
    STATIC PROCEDURE _SetNavBlocks( oBrowse )
   
    oXbp:firstPosBlock := {| | 1 }
    oXbp:lastPosBlock  := {| | 100 }
    oXbp:PosBlock      := {| |DC_DbPosition()   }
    oXbp:GoPosBlock    := {|n|DC_DbGoPosition(n)}
    oXbp:skipBlock     := {|n|DC_DbSkipper(n)   }
    oXbp:goTopBlock    := {| |DC_DbGoTop()      }
    oXbp:goBottomBlock := {| |DC_DbGoBottom()   }
    oXbp:phyPosBlock   := {| |Recno()           }
   
    RETURN
   

Source/Library:

  _DCSCOPE.PRG/.OBJ, DCLIPX.LIB

dc_dbgotop()

Go to the Top of a set of Scoped Records

Syntax:

   DC_DbGoTop () - > nil
   

Arguments:

    None.
   

Returns:

    Nil.
   

Description:

    DC_DBGOTOP() is used to go to the first record in a group of
    "scoped" records.  Scopes are set via the DC_SetScope() function.
    If a scope is not set or the ADSDBE is the data driver in the
    current workarea, then DC_DBGOTOP() simply calls dbGoTop()
    therefore it can be used as a replacement for dbGoTop().
   

Notes:

Examples:

    #include 'dcdialog.ch'
    #include 'appevent.ch'
   
    PROCEDURE XTest()
   
    LOCAL GetList := {}, oBrowse, aPres, cScopeTop, cScopeBot
   
    USE ..\XDOC\EXPRESS INDEX ..\XDOC\EXPRESS.CDX ;
        VIA FOXCDX ALIAS XDOC
   
    OrdSetFocus('COMMAND')
    DC_KeyStat(.t.)
   
    @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' ;
      SIZE 77,11.8 ;
      FREEZELEFT {1}
   
   
    DCBROWSECOL FIELD XDOC->command ;
      HEADER "Command" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->type  ;
      HEADER "Type" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->short ;
      HEADER "Short Description" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->module ;
      HEADER "Module" PARENT oBrowse ;
   
    DCBROWSECOL FIELD XDOC->category ;
      HEADER "Category" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->see_also ;
      HEADER "See Also" PARENT oBrowse
   
    DCREAD GUI ;
      FIT ;
      ADDBUTTONS ;
      TITLE 'Browse Scoping Demo' ;
      EVAL {||_SetNavBlocks(oBrowse),;
              DC_SetScope(0,'DC_G'),;
              DC_SetScope(1,'DC_K'),;
              DC_DbGoTop(),;
              oBrowse:RefreshAll() }
   
    RETURN
   
    /* -------------------- */
   
    STATIC PROCEDURE _SetNavBlocks( oBrowse )
   
    oBrowse:skipBlock     := {|n| DC_DbSkip(n)    }
    oBrowse:goTopBlock    := {| | DC_DBGOTOP()    }
    oBrowse:goBottomBlock := {| | DC_DbGoBottom() }
    oBrowse:phyPosBlock   := {| | Recno()         }
    oBrowse:posBlock      := {| | DC_KeyNo()      }
    oBrowse:lastPosBlock  := {| | DC_KeyCount()   }
    oBrowse:firstPosBlock := {| | 1               }
   
    RETURN
   

Source/Library:

  _DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()

dc_dblocate()

Locate a record in a set of Scoped Records

Syntax:

    DC_DbLocate( < bForCondition >, ;
                [< bWhileCondition >], ;
                [< nCount >], ;
                [< xRecordID >], ;
                [< lRest >] ) -- > lFound
   

Arguments:

   < bForCondition > is a code block which contains the search
   condition as a logical expression. The record pointer is moved
   to the next data record until < bForCondition > provides the
   value .T. (true) or until the end of the file is reached.
   
   < bWhileCondition > is an optional code block containing a
   condition as a logical expression. As long as this code block
   provides the value .T. (true), the search continues. The
   operation terminates as soon as < bWhileCondition > returns .F.
   (false).
   
   The optional argument < nCount > specifies the number of records
   searched beginning with the current record.
   
   < xRecordID > is a record ID (for DBF files it is the record
   number) which can be optionally specified. If specified, only
   this record is searched.
   
   The optional logical value < lRest > specifies whether all data
   records of a work area are searched (< lRest >==.F. ), or only
   the records from the current to the last record (< lRest >==.T. ).
   The default value is .F. (false), meaning all data records are
   searched.
   

Returns:

    A logical value.
   

Description:

    DC_DBLOCATE() is used to LOCATE a record in a group of "scoped"
    records.  Scopes are set via the DC_SetScope() function.  This
    functions identical to the Xbase++ dbLocate() function except
    the locate is accomplished only within the set of scoped
    records.  If no scope is set, then the parameters are passed
    on to dbLocate().
   

Notes:

    DC_DbLocate() can be used as a direct replacement for dbLocate()
    because all the parameters are simply passed on to dbLocate()
    if no scope is set.
   

Examples:

    . USE EXPRESS VIA FOXCDX INDEX EXPRESS
    . SET SCOPE TOP TO 'DC_F'
    . SET SCOPE BOTTOM TO 'DC_H'
    . ? DC_DbLocate({||syntax$'DC_G'})
   .T.
   

Source/Library:

  _DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()
   dc_dbcontinue()

dc_dbrecord2file()

Copy a record object to a file

Syntax:

   DC_DbRecordCompare( < oRecord1 >, < oRecord2 > ) - >
   lStatus
   

Arguments:

   < oRecord > is an object created by DC_DbRecord().
   

Returns:

   A TRUE if the contents of the record objects are exactly equal,
   otherwise FALSE.
   

Description:

   DC_DbRecord2File() is used to copy a record object that was
   created by DC_DbRecord() to a file.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbfile2record()

dc_dbrecordclone()

Clone a Database Record Object

Syntax:

   DC_DbRecordClone(oRecord) - > < oNewRecord >
   

Arguments:

   < oRecord > is a record object created by DC_DbRecord().
   

Returns:

   A record object.
   

Description:

   DC_DbRecordClone() will create a clone of a record object.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()

dc_dbrecordcompare()

Compare two record objects created by DC_DbRecord()

Syntax:

   DC_DbRecordCompare( < oRecord1 >, < oRecord2 > ) - >
   lStatus
   

Arguments:

   < oRecord1 > and < oRecord2 > are record objects created by
   DC_DbRecord().
   

Returns:

   A TRUE if the contents of the record objects are exactly equal,
   otherwise FALSE.
   

Description:

   DC_DbRecordCompare() is used to compare the contents of two
   record objects created by DC_DbRecord().
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()

dc_dbrecordcopy()

Copy a Database Record Object

Syntax:

   DC_DbRecordCopy( < oRecordFrom >, < oRecordTo > ) - > nil
   

Arguments:

   < oRecordFrom > is a record object created by DC_DbRecord().
   
   < oRecordTo > is a record object that contains fields of the same
   names as < oRecordFrom >.  Only field names of the same name and
   type will be copied, all others will be ignored.
   

Returns:

   Nil.
   

Description:

   DC_DbRecordCopy() will copy the contents of a record object that
   was created by DC_DbRecord() into another record object.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbscatter()
   dc_dbgather()
   dc_dbrecordcompare()

dc_dbrecordedit()

An editor for a record object

Syntax:

   DC_DbRecordEdit( < oRecord > ) - > lUpdated
   

Arguments:

   < oRecord > is a record object created by DC_DbRecord().
   

Returns:

   A logical .T. if the record was updated.
   

Description:

   DC_DbRecordEdit() is a gui editor for modifying the contents of
   a record object.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()

dc_dbrecordisempty()

Test if a record object is empty

Syntax:

   DC_DbRecordIsEmpty(oRecord) - > < lStatus >
   

Arguments:

   A record object that was created with DC_DbRecord().
   

Returns:

   A logical .TRUE. if all fields are empty, .FALSE. otherwise.
   

Description:

   DC_DbRecordIsEmpty() will test if all fields of a record object
   are empty.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()

dc_dbrecordtrim()

Trims all character string values in a record object

Syntax:

   DC_DbRecordTrim( < oRecord > ) - > nil
   

Arguments:

   < oRecord > is a record object that was created with DC_DbRecord()
   and filled with DC_DbScatter().
   

Returns:

   Nil
   

Description:

   DC_DbRecordTrim() is used to trim the trailing spaces off all
   character string values in a record object created with DC_DbRecord().
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbscatter()

dc_dbscatter()

Scatter data from current record to a Record Object

Syntax:

   DC_DbScatter( < oRecord > ) - > < oRecord >
   

Arguments:

   < oRecord > is a record object.
   

Returns:

   A pointer to the passed in record object.
   

Description:

   DC_DbScatter() is used to scatter the data in all fields of the
   currently selected record into the iVars of a record object
   previously created by DC_DbRecord().
   
   Two additional iVars are added to the record object:
   
   RECORD_NUMBER - A numeric container for the current record number that
    is set when DC_DbScatter() is used.
   
   RECORD_DELETED - A logical container for the Deleted() flag is
    set when DC_DbScatter() is used.
   

Examples:

   FUNCTION XTest()
   
   LOCAL oRecord
   
   USE COLLECT
   
   oRecord := COLLECT->(DC_DbRecord():new())
   COLLECT->(DC_DbScatter(oRecord))
   
   @ 1,1 DCSAY 'Description' GET oRecord:descript
   @ 2,1 DCSAY 'Type' GET oRecord:type
   @ 3,1 DCSAY 'Sub-Type' GET oRecord:subtype
   
   DCREAD GUI
   
   COLLECT->(DC_DbGather(oRecord))
   
   RETURN nil
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbgather()

dc_dbseek()

Seek a record in a set of Scoped Records

Syntax:

    DC_DbSeek ( [< xValue >], ;
                [< lSoftSeek >], ;
                [< cIndexTag >], ;
                [< lSeekLast >] ) - > lStatus
   

Arguments:

   < xValue > is any value of the same type as the index key for
   the selected order.
   
   < lSoftSeek > if .TRUE. will perform a softseek. .FALSE. is default.
   
   < cIndexTag > is the Index Tag to select for the seek.  The default
   is the current order.
   
   < lSeekLast > if .TRUE. will seek the last record that matches
   < xValue >.
   The default is .FALSE.
   

Returns:

    A logical value.
   

Description:

    DC_DBSEEK() is used to SEEK a record in a group of "scoped"
    records.  Scopes are set via the DC_SetScope() function.  This
    functions identical to the Xbase++ dbSeek() function except if
    the record is not found or is outside the range of the scope,
    it behaves as follows:
   
    1. If the record is not found the record pointer is placed at
       Eof() and a .FALSE. is returned.
   
    2. If the record is found but the indexkey() value is less
       than the top scope, the record pointer is placed at the
       beginning record of the scope and a .FALSE. is returned.
   
    3. If the record is found but the indexkey() value is greater
       than the bottom scope, the record pointer is placed at the
       last record of the scope and a .FALSE. is returned.
   
    4. If the record is found and the indexkey() value is within
       the range of the top and bottom scope, the record pointer
       is placed at the found record and a .TRUE. is returned.
   
    If no scope is set or the ADSDBE is used as the data driver for
    the current workarea DC_DbSeek() simply calls dbSeek() therefore
    it can be used as a replacment for dbSeek().
   

Examples:

    . USE EXPRESS VIA FOXCDX INDEX EXPRESS
    . SET SCOPE TOP TO 'DC_F'
    . SET SCOPE BOTTOM TO 'DC_H'
    . ? DC_DbSeek('DC_G')
   .T.
    . ? DC_DbSeek('DC_R')
   .F.
   

Source/Library:

  _DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()

dc_dbskip()

Skip records in a set of Scoped Records

Syntax:

   DC_DbSkip ( [< nRecords >] ) - > nil
   

Arguments:

   < nRecords > is any positive or negative value.
   

Returns:

    The actual number of records that were skipped.  This number may
    be less than the number of records requested in the event that
    the first or last record in the scoped group was encountered.
   
    DC_DBSKIP() will not skip past the bottom record or previous
    the top record in a scoped group.
   

Description:

    DC_DBSKIP() is used to SKIP <þnþ> records in a group of
    "scoped" records.  Scopes are set via the DC_SetScope() function.
    If a scope is not set, then DC_DBSKIP() simply calls dbSkip()
    therefore it can be used as a replacement for dbSkip().
   

Notes:

Examples:

    #include 'dcdialog.ch'
    #include 'appevent.ch'
   
    PROCEDURE XTest()
   
    LOCAL GetList := {}, oBrowse, aPres, cScopeTop, cScopeBot
   
    USE ..\XDOC\EXPRESS INDEX ..\XDOC\EXPRESS.CDX ;
        VIA FOXCDX ALIAS XDOC
   
    OrdSetFocus('COMMAND')
    DC_KeyStat(.t.)
   
    @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' ;
      SIZE 77,11.8 ;
      FREEZELEFT {1}
   
   
    DCBROWSECOL FIELD XDOC->command ;
      HEADER "Command" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->type  ;
      HEADER "Type" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->short ;
      HEADER "Short Description" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->module ;
      HEADER "Module" PARENT oBrowse ;
   
    DCBROWSECOL FIELD XDOC->category ;
      HEADER "Category" PARENT oBrowse
   
    DCBROWSECOL FIELD XDOC->see_also ;
      HEADER "See Also" PARENT oBrowse
   
    DCREAD GUI ;
      FIT ;
      ADDBUTTONS ;
      TITLE 'Browse Scoping Demo' ;
      EVAL {||_SetNavBlocks(oBrowse),;
              DC_SetScope(0,'DC_G'),;
              DC_SetScope(1,'DC_K'),;
              DC_DbGoTop(),;
              oBrowse:RefreshAll() }
   
    RETURN
   
    /* -------------------- */
   
    STATIC PROCEDURE _SetNavBlocks( oBrowse )
   
    oBrowse:skipBlock     := {|n| DC_DBSKIP(n)    }
    oBrowse:goTopBlock    := {| | DC_DbGoTop()    }
    oBrowse:goBottomBlock := {| | DC_DbGoBottom() }
    oBrowse:phyPosBlock   := {| | Recno()         }
    oBrowse:posBlock      := {| | DC_KeyNo()      }
    oBrowse:lastPosBlock  := {| | DC_KeyCount()   }
    oBrowse:firstPosBlock := {| | 1               }
   
    RETURN
   

Source/Library:

  _DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()
   dc_bof()
   dc_eof()

dc_dbskipunique()

Skip to the next unique record

Syntax:

   DC_DbSkip () - > nil
   

Arguments:

   None.
   

Returns:

    Nil.
   

Description:

    DC_DBSKIPUNIQUE() is used to SKIP to the next record in the
    database that is unique within the controlling index.
   

Examples:

    /* This example will load an array with every city in
       the database */
   
    PROCEDURE XTest()
   
    LOCAL aCity[0]
   
    dbeSetDefault('FOXCDX')
    USE xtest INDEX xtest
    OrdSetFocus('CITY')
   
    DO WHILE !Eof()
      AAdd( aCity, XTEST->city )
      DC_DbSkipUnique()
    ENDDO
   
    RETURN aCity
   

Source/Library:

  _DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dbskip()
   dc_bof()
   dc_eof()

dc_dbstru()

Display the structure of the selected database

Syntax:

    DC_DbStru() - > cFieldName
   

Arguments:

    None.
   

Returns:

    The name of the field selected by the user, a character string.
   

Description:

    DC_DbStru() is used to display the structure of the selected
    database file.  A GUI dialog window displays the structure in
    a scrollable window with options to Print or save to a File.
   

Examples:

    . USE COLLECT
    . DC_DbStru()
   

Source/Library:

  _DCDBSTR.PRG, DCLIP1.DLL

See Also:

   DISPLAY STRUCTURE
   dc_dbstruw()

dc_dbstruct()

Get the structure of a database in various formats

Syntax:

    DC_DbStruct ( [< nMode >] ) - > aStructure
   

Arguments:

   < nMode > is used to select the style of structure to be returned:
   
    < nMode >      Description
    ---------- ------------------------------------------------
     0 DEFAULT  Returns four (4) parallel sub-arrays rather than
                ragged arrays.
   
     1          Returns a ragged array similar to dbStruct()
                except each sub-array consists of 7 elements
                instead of 4 elements:
   
                Element   Type  Description
                -------  ------ -------------------------------
                   1        C    Field Name
                   2        C    Field Type
                   3        N    Field Length
                   4        N    Field Decimals
                   5        C    Field Name
                   6        C    Field Type
                   7        X    Default value (the value in the
                                 field of the current record)
   

Returns:

    A Multi-dimensional array.
   

Description:

    DC_DBSTRUCT() is similar to the Xbase++ DBSTRUCT() function,
    except that it returns the structure in an arrays of various
    formats.
   

Examples:

    -- Example 1 --
   
    // use a Database
    . use express via foxcdx
   
    // save the structure
    aStru := DC_DBSTRUCT(0)
   
    // create a .DBF of the same structure
    dc_dbcreate( 'express2.dbf', ;
                 aStru[1], aStru[2], aStru[3], aStru[4] )
   
   
    -- Example 2 --
   
    // use a Database with a new structure
    . use newdata
   
    // save the structure
    . aStru := DC_DBSTRUCT(1)
   
    // close the database
    . CLOSE
   
    // use the Database with structure to be updated from new
    // structure
    . use olddata
   
    // update the structure with new fields and default data
    . DC_StruUpdate( aStru,, .t. )
   

Source/Library:

  _DCAREA.PRG, DCLIP1.DLL

See Also:

   dc_dbcreate()
   dc_struupdate()
   dc_isstru()

dc_dbstruw()

Display the structure of the selected database (wide format)

Syntax:

    DC_DbStruW() - > cFieldName
   

Arguments:

    None.
   

Returns:

    The name of the field selected by the user, a character string.
   

Description:

    DC_DbStruW() is used to display the structure of the selected
    database file in a Wide format.  A GUI dialog window displays
    the structure in a scrollable window with three columns of
    fields.
   

Examples:

    . USE COLLECT
    . DC_DbStruW()
   

Source/Library:

  _DCDBSTR.PRG, DCLIP1.DLL

See Also:

   DISPLAY STRUCTURE
   dc_dbstru()

dc_dbu()

A Gui Database Management Utility

Syntax:

   DC_Dbu( [< cParm1 >],... [< cParm15 >] ) - > nil.
   

Arguments:

   < cParm1 > thru < cParm15 > may be any of the following
   arguments:
   
   /an - Load ADSDBE driver (.NTX/.DBT support)
   /ac - Load ADSDBE driver (.CDX/.IDX/.FPT support)
   /dbe:< default dbe name >
   /tbl:< database name >
   /ind:< index list (separated by commas)
   /odbc - Load ODBC driver
   /dsn:< data source name > - ODBC (use a + for each space in name)
   /uid:< user id > - ODBC
   /pwd:< password > - ODBC
   /dbq:< database name > - ODBC
   /dll:< dllname > - Load a dynamic link library
   /srv:< server name or drive letter > - ADSDBE
   /obj:< objfilename > - Load an .OBJ file
   /proc:< procedure > - Run a procedure ( with parameters)
   

Description:

   DC_Dbu() is a database management utility that can be used to
   edit databases using any DBE including ADSDBE and ODBCDBE.
   DC_Dbu() is an MDI-based dialog that contains a status window at
   the top of the dialog.  This status window displays information
   about the currently selected work area and also contain some
   pushbuttons to popup further status windows.
   
   A menu at the top of the dialog provides a complete set of
   database utilities, searching features and printing features.
   It also allows for an MDI child browse/edit window to be created
   for each open work area.  When a browse/edit window is given
   focus with the mouse, the work area of that window is selected
   and the status of the selected work area is displayed at the
   top of the dialog window.
   
   All MDI child windows are opened in the same thread as the
   parent window.
   

Examples:

   DC_Dbu('/odbc','/dsn:dBASE Files','/adsntx','/obj:TEST.OBJ', ;
          '/proc:MyMenu()' )
   

Source/Library:

  _DCDBU.PRG,DCLIP1.DLL

See Also:

   dc_dot()
   dbu

dc_debugbrowse()

Send debug information to a browse-style debugging window

Syntax:

   DC_DebugBrowse ( { < xExpr1,...xExprN >}, ;
                    [< aExprTitle >], ;
                    [< nWindow >], ;
                    [< nbFgColor >], ;
                    [< nBgColor >], ;
                    [< lbPause >] ) - > NIL
   

Arguments:

   < xExpr1 > through < xExprN > is any expression.
   The return value of each expression will be displayed in column
   1 of the browse.
   
   < aExprTitle > is an optional array of character strings to display
   in column 2 of the browse.  There should be 1 item for each exprX
   item.  These may be used as descriptors of the data being displayed.
   
   < nWindow > is the debug window to send the information.
   If this clause is not used then the information is sent to debug
   window # 1.
   
   < nbFgColor > and < nBgColor > are the foreground and
   background
   colors of the information to display in the window.  If < nbFgColor >
   is a code block, then < nBgColor > is ignored.  The code block must
   return an array of two numeric elements, ie a foreground color
   and a background color.
   
   < lbPause > may be a logical variable or a code block.  If
   < lbPause >
   is a logical .TRUE. then the program execution will be stopped until
   the "Continue" button on the debug window is activated.  If
   < lbPause >
   is a codeblock then the program execution will be stopped if the
   codeblock returns a .TRUE. when evaluated.
   

Description:

    DC_DebugBrowse() is used to send data to a browse-style debugging
    window when debugging GUI applications.
   
    A list of expressions may be included and the output of each
    expression will be displayed in a new row in the browse window.
   
    This is a major improvement over DC_DebugQout() because it uses an array
    browse rather than a memo to show debug information.  Improvements:
   
    a. Updating the window is much faster therefore does not slow
       down application.
   
    b. Data is in resizeable and moveable columns
   
    c. Each debug line may have its own color.
   
    d. Supports multiple windows.
   
    e. Double-Clicking on debug item in window displays more info
       about that item, such as array browsing, object inspecting,
       etc.
   
    f. Information doesn't scroll off the window.  No limit to amount
       of debugging information.
   

Notes:

   DC_DebugQoutAppendBlock() is a get-set function used to setup
   additional information to append to each debug line.
   

Examples:

    #include "dcdialog.ch"
   
    USE COLLECT NEW SHARED
   
    DC_DebugBrowse( { Alias(), RecNo(), {'Alias','Record #'}, ;
                    2, {||IIF(RecNo()==3,;
                           {GRA_CLR_RED,GRA_CLR_WHITE}
                           {GRA_CLR_BLACK,GRA_CLR_WHITE})} )
   
    DC_DebugBrowse( { SetAppWindow() } )
   
    DC_DebugBrowse( { Directory() } )
   

Source/Library:

  _DCQOUT.PRG, DCLIPX.DLL

See Also:

   DCBDEBUG

dc_debugbrowseenable()

Enable debugging with an environment variable

Syntax:

   DC_DebugBrowseEnable ( < aEnvirVars > ) - > nil
   

Arguments:

   < aEnvirVars > is an array of character strings which are the names
   of environment variables to test.  If any of the environment
   variables contains a YES, ON, HO or JA, then DCBDEBUG commands
   will be enabled, otherwise they will be disabled.
   

Returns:

   Nil.
   

Description:

   DC_DebugBrowseEnable() is used to disable all DCBDEBUG commands
   unless a specified environment variable exists.
   

Examples:

   
    IF lRunningAsService
      // No environment variable named ABCDEFGHI exists, so disable debug
      DC_DebugBrowseEnable( {"ABCDEFGHI"} )
    ELSE
      // Disable debug if there is no env var named DEBUG=YES
      DC_DebugBrowseEnable( {"DEBUG"} )
    ENDIF
   

Source/Library:

  _DCQOUT.PRG, DCLIPX.DLL

See Also:

   DCBDEBUG
   dc_debugbrowse()

dc_debuglogfile()

Set the name of the Debug Log file.

Syntax:

   DC_DebugLogFile( [< cFileName >] ) - > cOldFileName
   

Arguments:

   < cFileName > is the name of the log file.
   

Returns:

   A character string.
   

Description:

   DC_DebugLogFile() is a Get-Set function that is used to
   set the name of the log file when using the DC_DebugLog()
   function or DCLDEBUG* commands.
   

Examples:

   DC_DebugLogFile('E:\temp\debug.log')
   
   DCLDEBUG Date(), Time()
   

Source/Library:

  _DCQOUT.PRG

See Also:

   DCLDEBUG

dc_debuglogout()

Send debug information to a debugging log file

Syntax:

    DC_DebugLogOut( < xExpr1 > ) - > NIL
   

Arguments:

   < xExpr1 > through < xExprN > is any expression.
   

Description:

    DC_DebugLogOut() is used to send data to a log file when
    debugging GUI applications.
   
    A list of expressions may be included and the output of each
    expression will be displayed on a new line in the file.
   

Notes:

   DC_DebugQoutAppendBlock() is a get-set function used to setup
   additional information to append to each debug line.
   

Examples:

    #include "dcdialog.ch"
   
    USE COLLECT NEW SHARED
   
    DC_DebugLogOut( { Alias(), IndexOrd() } )
   

Source/Library:

  DCDIALOG.CH

See Also:

   DCQDEBUG
   DCLDEBUG

dc_debugqout()

Send debug information to a debugging window

Syntax:

    DC_DebugQout( {< xExpr1 >,...< xExprN >} ) - > NIL
   

Arguments:

   < xExpr1 > through < xExprN > is any expression.
   

Description:

    DC_DebugQout() is used to send data to a debugging window when
    debugging GUI applications.
   
    A list of expressions may be included and the output of each
    expression will be displayed on a new line in the window.
   

Notes:

   DC_DebugQoutAppendBlock() is a get-set function used to setup
   additional information to append to each debug line.
   

Examples:

    #include "dcdialog.ch"
   
    USE COLLECT NEW SHARED
   
    DC_DebugQout( { Alias(), IndexOrd() } )
   

Source/Library:

  DCDIALOG.CH

See Also:

   DCQDEBUG
   dc_debugqoutappendblock()
   dc_qout()
   DCQOUT

dc_debugqoutappendblock()

Post a codeblock for information to append to debug window

Syntax:

    DC_DebugQoutAppendBlock( < bExpr > ) - > bOldExpr
   

Arguments:

   < bExpr > is a code block that returns a character string.
   

Returns:

   A Code Block.
   

Description:

   DC_DebugQoutAppendBlock() is a get-set function used to setup
   additional information to append to each debug line.
   
   The default code block returns the call stack.
   
   {||' <þ- Called From: ' + ;
      ProcName(2) + '('+Alltrim(Str(ProcLine(2)))+'), ' + ;
      ProcName(3) + '('+Alltrim(Str(ProcLine(3)))+'), ' + ;
      ProcName(4) + '('+Alltrim(Str(ProcLine(4)))+')' }
   

Examples:

    #include "dcdialog.ch"
   
    DC_DebugQoutAppendBlock( {||' <- Called From: ' + ;
      ProcName(2) + '('+Alltrim(Str(ProcLine(2)))+')' }
   
    USE COLLECT NEW SHARED
   
    DC_DebugQout( { Alias(), IndexOrd() } )
   

Source/Library:

  DCDIALOG.CH

See Also:

   DCQDEBUG
   dc_debugqout()
   dc_qout()
   DCQOUT

dc_debugwindowbrowsefont()

Sets font for the debug window

Description:

   DC_DebugWindowBrowseFont() is a Get-Set function that is used to
   set the font for the debug window created by the WTF command.
   

Source/Library:

  _DCQOUT.PRG, DCLIPX.DLL

See Also:

   WTF
   dc_debugbrowse()

dc_dec2hex()

Returns a hexidecimal number from a numeric value

Syntax:

   DC_Dec2Hex( < nDecimal > ) - > cHexidecimal
   

Arguments:

   < nDecimal > is a numeric value from 0 to 255.
   

Returns:

    A character string.  Example: 5D
   

Description:

   DC_DEC2HEX() will convert a numeric value to Hexidecimal.
   

Source/Library:

  _DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_bittest()
   dc_andbits()

dc_dec2longint()

Converts Long Integer (32 bits) to binary character

Syntax:

   DC_Dec2LongInt( < nDecimal > ) - > cBinaryString
   

Arguments:

   < nDecimal > is a numeric value from 0 to 4294967295.
   

Returns:

    A character string that is the binary equivalent of the passed
    argument (32 characters).
   

Description:

   DC_Dec2LongInt() converts a Long Integer (32 bits) TO binary character
   representation
   

Source/Library:

  _DCFUNCT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dec2hex()
   dc_xorbitslong()

dc_delete()

Mark record(s) for deletion

Syntax:

    DC_Delete() - > lStatus
   

Arguments:

    None.
   

Returns:

    A logical .TRUE. if records were deleted successfully, .FALSE.
    otherwise.
   

Description:

    DC_Delete() is used to mark records for deletion based on a set
    of conditions.  A GUI dialog is displayed for the user to select
    the conditions.
   

Examples:

    . USE EXPRESS INDEX EXPRESS.CDX SHARED
    . DC_Delete()
   

Source/Library:

  _DCDELE.PRG, DCLIP1.DLL

See Also:

   DELETE
   dc_recall()

dc_dimscreen()

Dim and disable a screen or the entire desktop.

Syntax:

   DC_DimScreen( < oDialog >, ;
                 [< nColor >], ;
                 [< nTransparency >], ;
                 [< bGets >] ) - > < oDialog2 >
   

Arguments:

   < oDialog > is the dialog window to dim.  To dim the entire
   desktop, this should be AppDeskTop().
   
   < nColor > is the color to use for the dimming. Default is
   GRA_CLR_BLACK.
   
   < nTransparency > is the amount of transparency to use.
   Default is 50.
   
   < bGets > is a code block to evaluate that will add items
   to the overlaying static.  The code block will receive 2
   parameters: (1) The Getlist array, (2) the Static object.
   

Returns:

   A pointer to the overlaying window.
   This window must be destroyed with the :destroy() method.
   

Description:

   DC_DimScreen() will dim and disable a gui screen or the entire desktop.
   Use this function fo force the user to focus on a new window or
   process.
   
   This function creates a new window with a DCSTATIC child object
   to overlay the target screen.  The new window is set to a specified
   color and transparency to give the illusion that the target screen is
   being changed, but it is only being overlayed.
   

Examples:

   See the sample program in .\samples\dimmer\dimmer.prg.
   

Source/Library:

  _DCFUNCT.PRG

dc_dir()

Display a directory of files or databases

Syntax:

    DC_Dir( [< cFileSpec >] ) - > lStatus
   

Arguments:

   < cFileSpec > is the specification of the files to display including
   path and extension.  The file dialog shows the file name, date,
   size and time.
   
   If no argument is passed, then only .DBF database files will be
   displayed.  This dialog allows for the file to be automatically
   opened when the item is selected.  The database dialog shows the
   file name, date, size, number of records, and type of database.
   

Returns:

    A logical .TRUE. if any files were displayed, .FALSE. otherwise.
   

Description:

    DC_Dir() is used to display a directory of files or databases.
   

Examples:

    . DC_Dir()   // display all database files
    . DC_Dir('*.TXT') // display all text files
   

Source/Library:

  _DCDIR.PRG, DCLIP1.DLL

dc_dispbegin()

Begin buffering screen output

Syntax:

   DC_DispBegin () - > nil
   

Arguments:

    None
   

Returns:

    nil
   

Description:

    Clipper's DISPBEGIN() and DISPEND() functions will not behave
    properly if they are not nested properly, i.e. the same number
    of DISPBEGIN() calls and DISPEND() calls.  DC_DISPBEGIN()
    and DC_DISPEND() are simply front-end calls to the associated
    Clipper functions that keep a static counter ensuring that
    DC_DISPCLEAR() can properly clear out the buffers in the error
    handler.
   

Notes:

    Use DC_DISPBEGIN() and DC_DISPEND() in place of Clipper's
    DISPBEGIN() and DISPEND() when using DC_DISPCLEAR() to
    clear the display buffers.
   

Examples:

    See Clipper 5.x Guides DISPBEGIN(), DISPEND()
   

Source/Library:

  _DCDISP.PRG/.OBJ, DCLIPX.LIB

dc_dispclear()

Clear the screen output buffers

Syntax:

   DC_DispClear () - > nil
   

Arguments:

    None
   

Returns:

    Nil
   

Description:

    DC_DISPCLEAR() is used in your error handler to clear the
    display buffers during an error.  This function is needed
    only if you use Clipper's DISPBEGIN() and DISPEND() in your
    application.
   
    Clipper's DISPBEGIN() and DISPEND() functions will not behave
    properly if they are not nested properly, i.e. the same number
    of DISPBEGIN() calls and DISPEND() calls.  DC_DISPBEGIN()
    and DC_DISPEND() are simply front-end calls to the associated
    Clipper functions that keep a static counter ensuring that
    DC_DISPCLEAR() can properly clear out the buffers in the error
    handler.
   

Notes:

    Use DC_DISPBEGIN() and DC_DISPEND() in place of Clipper's
    DISPBEGIN() and DISPEND() when using DC_DISPCLEAR() to
    clear the display buffers.
   

Examples:

    See Clipper 5.x Guides DISPBEGIN(), DISPEND()
   

Source/Library:

  _DCDISP.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dispbegin()
   dc_dispend()

dc_dispend()

End buffering screen output

Syntax:

   DC_DispEnd () - > nil
   

Arguments:

    None
   

Returns:

    Nil
   

Description:

    Clipper's DISPBEGIN() and DISPEND() functions will not behave
    properly if they are not nested properly, i.e. the same number
    of DISPBEGIN() calls and DISPEND() calls.  DC_DISPBEGIN()
    and DC_DISPEND() are simply front-end calls to the associated
    Clipper functions that keep a static counter ensuring that
    DC_DISPCLEAR() can properly clear out the buffers in the error
    handler.
   

Notes:

    Use DC_DISPBEGIN() and DC_DISPEND() in place of Clipper's
    DISPBEGIN() and DISPEND() when using DC_DISPCLEAR() to
    clear the display buffers.
   

Examples:

    See Clipper 5.x Guides DISPBEGIN(), DISPEND()
   

Source/Library:

  _DCDISP.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dispbegin()

dc_dispmem()

Display the contents of a memory file or current memory

Syntax:

    DC_DispMem( [< cMemFileName >] ) - > lStatus
   

Arguments:

   < cMemFileName > is the name of the memory file.  If no extension
   is given then .XPF is assumed.
   
   If no argument is passed then the current contents of memory
   are saved to a file named EXPRESS.XPF and the contents of
   EXPRESS.XPF are displayed.  NOTE: If any PUBLIC or PRIVATE
   memory variables exist containing non-persistent data such as
   objects or some type of code blocks, a runtime error will
   result and the contents of memory cannot be displayed.
   

Returns:

    A logical .TRUE. if successful.
   

Description:

    DC_DispMem() is used to display the contents of an .XPF
    (memory) file or the current contents of memory
    (PUBLICS/PRIVATES only) in a GUI scrolling browse window.
   

Examples:

    . custname := 'Donnay Software'
    . product := 'eXPress++ 2.0'
    . DC_DispMem()
    . DC_DispMem('PRODUCT.XPF')
   

Source/Library:

  _DCMEM.PRG, DCLIP2.DLL

See Also:

   dc_xpftoarray()
   DISPLAY MEMORY

dc_dlllist()

List all loaded dynamic .DLLs

Syntax:

    DC_DllList() - > nil
   

Arguments:

   < cDllName > is the name of the .DLL to load.  If this argument
   is not passed a GUI dialog will be displayed prompting for the
   name.
   
   < lMessage > if .TRUE. (default) will display a GUI message box
   if the .DLL could not be loaded.
   

Returns:

    Nil.
   

Description:

    DC_DllList() is used to list all the dynamic .DLLs that are
    currently loaded.  These .DLLs must have been loaded with
    DC_DllLoad() or DLL LOAD.
   

Examples:

    . DC_DllLoad('MYTEST')
    . DC_DllLoad('MYFUNCS')
    . DC_DllList()
   

Source/Library:

  _DCDLL.PRG, DCLIP1.DLL

See Also:

   DLL LIST

dc_dllload()

Load a dynamic .DLL

Syntax:

   DC_DllLoad( [< cDllName >], ;
               [< lMessage >] ) - > lStatus
   

Arguments:

   < cDllName > is the name of the .DLL to load.  If this argument
   is not passed a GUI dialog will be displayed prompting for the
   name.
   
   < lMessage > if .TRUE. (default) will display a GUI message box
   if the .DLL could not be loaded.
   

Returns:

    A logical .TRUE. if the .DLL was successfully loaded, .FALSE.
    otherwise.
   

Description:

    DC_DllLoad() is used to load a dynamic .DLL and save away
    information about the .DLL in a static array to be used later
    with DC_DllUnload().
   

Examples:

    . DC_DllLoad('MYTEST')
    . DO test
    . DC_DllUnload('MYTEST')
   

Source/Library:

  _DCDLL.PRG, DCLIP1.DLL

See Also:

   DLL LOAD
   dc_dllunload()
   dc_dlllist()

dc_dllunload()

UnLoad a dynamic .DLL

Syntax:

   DC_DllUnload( < cDllName > ) - > lStatus
   

Arguments:

   < cDllName > is the name of the .DLL to unload.
   

Returns:

    A logical .TRUE. if the .DLL was successfully unloaded.
   

Description:

    DC_DllUnload() is used to unload a dynamic .DLL that was previously
    loaded with DLL LOAD or DC_DllLoad().
   

Examples:

    . DC_DllLoad( 'MYTEST' )
    . DO test
    . DC_DllUnload( 'MYTEST' )
   

Source/Library:

  _DCDLL.PRG, DCLIP1.DLL

See Also:

   dc_dllload()
   DLL UNLOAD

dc_do()

A handy method of creating a late-binding call to a function

Syntax:

   DC_Do ( < cProgToDo >, ;
           [< cProgToCall >] ) - > xValue
   

Arguments:

   < cProgToDo > is the name of the procedure or function to execute
   in "quotes".
   
   < cProgToCall > is the name of any additional procedure or
   function to execute in the event that DC_DO() cannot find
   procedure < cProgToDo > in the .EXE or in a dynamic library.
   

Returns:

    The value returned by the function called.
   

Description:

    DC_DO() is used to run any program or function.  DC_DO() is
    used in place of DO <þprocþ> or <þfunctionþ> in applications
   where
    the developer wishes to control which procedures or functions
    get linked into an application by simple EXTERNAL tables.
   
    DC_DO() runs procedures or functions, but does not force the
    linker to link  them into   the .EXE program.  For example, the
    command: DO ACCTSPAY in an application would always force the
    module or object ACCTSPAY to be linked into the .EXE by your
    linker.  If however, you replace DO ACCTSPAY with
    DC_DO('ACCTSPAY'), then the ACCTSPAY module will only be linked
    in to the .EXE with an EXTERNAL ACCTSPAY command or by the
    dCLIP "dynamic-linker". DC_DO() should be used when calling
    procedures or functions which are in dynamic libraries (.DLBs).
   
    With DC_DO() the developer can create an application with many
    OPTIONS yet use common  source code.  The options for a
    specific customer or product configuration can be controlled
    through EXTERNAL tables.
   

Examples:

    . ? DC_DO( "dc_assist()" )
   

Source/Library:

  _DCDO.PRG/.OBJ, DCLIPX.LIB

dc_docase()

Evaluate a list of expressions based on a CASE condition

Syntax:

   DC_DoCase ( < aCase >, ;
               < aEval > ) - > Nil
   

Arguments:

   < aCase > is an array of code blocks to evaluate.
   
   < aEval > is an array of code blocks to execute.  The first code
   block in array < aCase > that evaluates true will force the
   corresponding code block in the parallel array < aeval > to be
   evaluated.
   

Returns:

    Nil.
   

Description:

    DC_DOCASE() is a "function" replacement for DO CASE...ENDCASE
    when a function is needed, i.e. for calling via macro, code
    blocks, etc.
   

Notes:

    Only one (1) code block in the <þaEvalþ> array will be evaluated.
   

Examples:

    aCase := { { || lastkey()=27 }, { || lastkey()=13 } }
    aEval := { { || abort() }, { || accept() } }
   
    inkey(0)
    DC_DOCASE(  aCase, aEval )
   

Source/Library:

  _DCEVAL.PRG, DCLIP1.DLL

See Also:

   dc_ifelse()
   dc_dowhile()

dc_dot()

A Dot-Prompt Interpreter

Syntax:

    DC_Dot( [< lModal >], ;
            [< nTimerRefresh >] ) - > NIL
   

Arguments:

   < lModal > runs the Dot-Prompt in "Psuedo-Modal" mode. It is not
   actually modal but instead disables the SetAppWindow().  When
   the EXIT button is pressed or the EXIT command is entered at the
   dot-prompt, the user is given the option of closing the window
   or exiting and returning control to the calling program.
   
   < nTimerRefresh > is the refresh interval, in 1/100 of a second,
   to refresh the status area at the top of the window.
   

Description:

   DC_Dot() is a dot-prompt interpreter that is used to execute any
   Xbase++ command, eXPress++ command or User-Defined command.
   DC_Dot() will open a new Dialog Window and allow the user to enter
   and interpret commands.
   
   The standard eXPress++ command set is DCSTD.CH.  This file must
   exist in your INCLUDE path or no commands can be interpreted.
   When DCSTD.CH is loaded, it also loads the most common Xbase++
   include files like STD.CH, INKEY.CH, etc, the dialog command set,
   DCDIALOG.CH and file named DCCUSTOM.CH.
   
   DCCUSTOM.CH is where all custom user-defined commands are entered,
   including references to other .CH files, thus allowing virtually
   an unlimited command set.
   
   Commands entered at the dot-prompt may reference any manifest
   constant that has also been defined in one of the files that are
   part of the INCLUDE set.
   
   To return from DC_Dot() type EXIT at the dot-prompt.
   
   To quit the application type QUIT at the dot-prompt.
   
   DC_Dot() is an interpreter which provides similar functionality
   to the dBASE/FoxPro/dCLIP dot-prompt.  The heart of the
   interpreter is the runtime pre-processor and the DCSTD.CH/STD.CH
   command sets.
   
   If you grew up with dBASE-II or dBASE-III and graduated to
   Clipper, you will find yourself in familiar territory when you
   use DC_Dot(). The dot prompt is similar to the dBASE interactive
   programming environment that allows any of the built-in command
   set to be invoked from the dot prompt.  DC_Dot() is slightly
   different however, because it combines the best of 3 worlds.
   This "integration" of a pre-processor, intepreter, compiler and
   robust library allows unsurpassed speed and compatability in
   accomplishing Xbase++/eXPress++ development tasks.
   
   When a command is entered at the dot-prompt, it's first passed
   through the Xbase++ pre-processor to convert it to a set of
   expressions.  The expression list is then "macro-compiled" and
   evaluated.
   
   The eXpress++ dot prompt is fully-interactive, meaning that you get
   an instant response to the command at the moment you enter it
   from the keyboard.
   
   EXAMPLE:
   
    Assume that your client wants to get a quick average of all
    sales within a specified date period.  Then he wants to
    replace the sales representative for all his CALIFORNIA
    customers.  If you did not accomodate this capability in your
    executable program, your client is out of luck or must
    accomplish the task without the aid of your program.   With
    the DC_DOT() function linked into your program, this task can
    be accomplished in seconds by entering the following commands
    at the dot:
   
    . USE \ACCTSPAY\CUSTOMER VIA FOXCDX
    . AVER SALES TO TOTSALES FOR SHIPDATE þ> DATE()-30
    . ? TOTSALES             12677.52
    . REPL SALESREP WITH 'JONES' FOR STATE='CA'
   
   If you like working from a command-line, then the DOT is the
   starting place or "home" for just about everything you need to
   do in an Integrated Development Environment.  You can run any
   other executable program (regardless of size), run any DOS command,
   run any Xbase++ or user-defined command, evaluate any Xbase++
   expression, execute any batch file, edit source files, even compile
   and run object code without ever leaving the interactive environment
   of the dot prompt.  When you run an application program, you will
   return to the DOT.  When you run another executable program such as
   your own editor, word- processor, spread-sheet, calendar, etc.
   you will return to the DOT. When you compile your source code,
   you will return to the DOT.
   
   The dot-prompt is also a medium for experimenting with commands,
   functions, classes and language elements by allowing the user or
   programmer to create memory variables, arrays or objects
   "on-the-fly".
   

Examples:

   /* -- Example 1 Calling the dot-prompt from in-line code -- */
   
   IF lDebugOn
     DC_Dot()
   ENDIF
   
   /* -- Example 2 Calling the dot-prompt from a Hot-Key -- */
   
   SET KEY K_ALT_D TO DC_DOT
   @ 1,1 SAY 'Enter Name' GET cName
   READ
   SET KEY K_ALT_D TO nil
   
   /* -- Example 3 Calling the dot-prompt from eXPress++ dialog -- */
   
   DCHOTKEY xbeK_ALT_D ACTION {||DC_Dot(.f.)}
   DCREAD GUI FIT ADDBUTTONS
   

Source/Library:

  _DCDOT.PRG,DCLIP1.DLL

See Also:

   dc_interpret()
   dc_dotsize()

dc_dotdoskey()

Set DC_Dot() command stack operation to Dos-Key emulation

Syntax:

   DC_DotDosKey ( < lMode > ) - > nSize
   

Arguments:

   < lMode > if .TRUE. will set the Dos-Key emulation on.  If
   .FALSE. the command stack operation will be restored to
   the normal (default) operation.
   

Returns:

    A logical value equivalent to the last setting of the value.
   

Description:

    DC_DOTDOSKEY() is used to set the behavior of the dot-prompt
    command stack navigator to emulate that of DOS command stack
    navigators like Dos-Key or OS/2.
   
    The normal behavior allows commands to be reissued in
    sequence and expedite processes that are used again and
    again.  Dos-Key emulation automatically copies the selected
    command to the bottom of the stack after execution and
    creates a blank command line for input.
   

Source/Library:

  _DCDOT.PRG

See Also:

   dc_dot()

dc_dothotkey()

Set the Dot-Prompt hot key

Syntax:

   DC_DotHotKey ( [< nHotKey >] ) - > nOldHotKey
   

Arguments:

   < nHotKey > is any keyboard key defined in APPEVENT.CH.
   

Returns:

    A numeric value.
   

Description:

    DC_DOTHOTKEY() is used to establish the hot key to use to
    call up the dot prompt when in the GUI reader or in the standard
    event loop function: DC_ReadGuiEventLoop().  The default key
    is ALT-D.
   
    If the DCLIP1.DLL and DCLIP2.DLL libraries (eXPress++ 2.0) are
    statically linked to your application using DCLIP1.LIB and
    DCLIP2.LIB then the DC_Dot() function will be called directly,
    otherwise an attempt will be made to dynamically load DCLIP1.DLL
    and DCLIP2.DLL before calling DC_Dot().
   

Examples:

    DC_DotHotKey(xbeK_F12)
   

Source/Library:

  _DCGETBX.PRG

See Also:

   dc_readguieventloop()

dc_dotsize()

Set the size of the Dot-Prompt command stack

Syntax:

   DC_DotSize ( [< nSize >] ) - > nSize
   

Arguments:

   < nSize > is a number from 100 to 4000
   

Returns:

    A numeric value equal to the previous setting of the command
    stack size.
   

Description:

    DC_DOTSIZE() is used to increase the length of the Dot-Prompt
    command stack array to a value greater than the default value
    of 100 commands.  This is desirable in the event that it is
    necessary to save and restore more than the last 100 commands
    with the HISTORY=<þfileþ> command in your DCLIP.SYS.
   

Examples:

   DC_DOTSIZE(500)
   

Source/Library:

  _DCDOT.PRG

See Also:

   dc_dot()

dc_dotvar()

Returns a pointer to an array of passed info to DC_Dot()

Syntax:

   DC_DotVar() - > aArray
   

Returns:

   An array of 3 elements:
   
   1. A pointer to the DC_XbpDialog1() object.
   2. A pointer to the GetList array.
   3. A pointer to the DC_GetList() object.
   

Description:

   DC_DotVar() returns an array of info about the dialog window and Getlist
   for the dialog that invokes the dot-prompt when using DC_DotHotKey().
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.DLL

See Also:

   dc_dothotkey()
   dc_dot()

dc_dowhile()

Evaluate a list of expressions based on a CASE condition

Syntax:

    DC_DoWhile ( < bWhile >, ;
                 < bEval > ) - > nil
   

Arguments:

   < bWhile > is a code-block to evaluate in each iteration of the
   WHILE loop.  The loop will be terminated when < bWhile >
   evaluates .FALSE. or when the ESCape key is pressed.
   
   < bEval > is a code-block to evaluate in each iteration of the
   WHILE loop.
   

Returns:

    Nil.
   

Description:

    DC_DOWHILE() is a "function" replacement for DO WHILE..ENDDO
    loops to be used when a function is needed, i.e. for calling
    via macro, code blocks, etc.
   

Examples:

    bWhile := { || !EOF() }
    bEval := { || dbskip(1), qout( recno(), &(field(1)) ) }
    setkey( -1, { || DC_DOWHILE( bWhile, bEval } )
   

Source/Library:

  _DCEVAL.PRG, DCLIP1.DLL

See Also:

   dc_ifelse()
   dc_docase()

dc_drag()

Drag window coordinates and return a coordinate array

Syntax:

   DC_Drag ( < nStRow >, ;
             < nStCol >, ;
             < nEnRow >, ;
             < nEnCol >, ;
             < nDragMode >, ;
             [< nMinWidth >],
             [< nMinHeight >] ) - > aCoordinates
   

Arguments:

   < nStRow >, < nStCol >, < nEnRow >, < nEnCol >
   are the screen
   coordinates that you want to start the drag or window sizing
   from.   If no coordinates are passed then the dragging will
   start from the extreme coordinates of the display.
   
   < nDragMode >  :  DRAG_UPPER_LEFT    1
                   DRAG_UPPER_RIGHT   2
                   DRAG_LOWER_LEFT    3
                   DRAG_LOWER_RIGHT   4
                   DRAG_LEFT          5
                   DRAG_RIGHT         6
                   DRAG_UPPER         7
                   DRAG_LOWER         8
                   DRAG_ENTIRE_BOX    9
   
   < nMinWidth > is the minimum width of the new box.
   
   < nMinHeight > is the minimum height of the new box.
   

Returns:

    An array of four (4) elements with the coordinates selected by
    the user.
   

Description:

    DC_DRAG()  is used to designate an area of the screen you want
    to use by giving the operator a box to drag around with the
    cursor keys or the mouse.  After the operator has chosen the
    screen coordinates, pressing the <þenterþ> key or releasing the
    mouse button will return the 4 coordinates in an array.
   
    During the dragging process if the drag was not invoked by
    the mouse, then the TAB key will switch between the 9
    dragging modes.
   

Examples:

    // get a set of screen coordinates from the operator.
    aCoord := DC_DRAG( aCoord )
   
    // Explode a window to the passed coordinates.
    DC_EXPL( aCoord[1], aCoord[2], aCoord[3], aCoord[4] )
   

Source/Library:

  _DCDRAG.PRG/.OBJ, DCLIPX.LIB

dc_drive2unc()

Returns a UNC from a mapped drive letter

Syntax:

   DC_Drive2UNC( < cDrive > ) - > cUNC
   

Arguments:

   < cDrive > is the drive letter.
   

Returns:

   A Character String.
   

Description:

   DC_Drive2UNC() returns the UNC from a mapped drive letter.
   

Source/Library:

  _dcfunct.prg, dclipx.lib, dclipx.dll

See Also:

   dc_unc2drive()

dc_editconfig()

Edit a source file

Syntax:

    DC_EditConfig( [< cEditorFileName >] ) - > cEditorFileName
   

Arguments:

   < cEditorFileName > is the full-path file name of your editor
   or the name of a .BAT file that calls your editor.  This
   file name is passed the name of the file to edit and the line
   number.
   

Returns:

    The name of the editor previously stored in memory.
   

Description:

    DC_EDITCONFIG() is used to configure the name of your editor.
    Functions like DC_CallStack() and DC_EditPrg() will call your
    editor if it has been properly configured.  When the dot prompt
    is called for the first time in a program or a call to DC_Init()
    is made, a file named DCLIP.SYS is read to configure the
    environment.  An EDITOR=<þeditor file nameþ> statement in DCLIP.SYS
    will pass the <þeditor file nameþ> to DC_EditConfig() to set up
    your default editor.
   

Notes:

    If the drive and directory is not included in the <þcFileNameþ>
    argument, then DC_EDITPRG() will search for the file first in
    the SET DCLIP directory followed by the SET PDIR directory (if
    file is a .PRG).
   

Examples:

    . DC_EDITCONFIG( 'C:\mew\mew.bat' )
    . DC_EDITPRG( 'test' )
   
    Contents of me.bat (used to call Multi-Edit for Windows):
   
    @ECHO OFF
    @IF '%2'=='' C:\mew\mew32 %1
    @IF NOT '%2'=='' C:\mew\mew32 %1 /l%2
   

Source/Library:

  _DCEDPRG.PRG, DCLIP1.DLL

See Also:

   dc_editprg()
   dc_callstack()

dc_editcontrollastfocus()

Returns last edit control that had focus

Syntax:

   DC_EditControlLastFocus() - > oLastFocus
   

Arguments:

   None
   

Returns:

   An object.
   

Description:

   DC_EditControlLastFocus(). will return a pointer to the last
   edit control that had focus.  Handy for returning to a Get after
   hitting a hot key or clicking a pushbutton.
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.DLL

dc_editprg()

Edit a source file

Syntax:

    DC_EditPrg( < cFileName >, ;
               [< nLineNmbr >], ;
               [< cParameters >] - > lStatus
   

Arguments:

   < cFileName > is the name of the ascii file to edit.  If no
   argument is given, then the user will be prompted for the name
   of the file. If no extension is included, then .PRG is
   assumed.
   
   < nLineNmbr > is the line number to go to.  If no parameter is
   passed then the editing will start at line 1.
   
   < cParameters > is an optional set of parameters to pass to the
   editor.
   

Returns:

    A logical .TRUE. if editor was called successfully.
   

Description:

    DC_EDITPRG() is used to edit a source code file.  This function
    will use the editor defined as the "system" editor via the
    EDITOR= command in DCLIP.SYS or the DC_EDITCONFIG() function.
   
    If no external editor is defined, then an imbedded GUI text
    editor will be used.
   

Notes:

    If the drive and directory is not included in the <þcFileNameþ>
    argument, then DC_EDITPRG() will search for the file first in
    the SET DCLIP directory followed by the SET PDIR directory (if
    file is a .PRG).
   

Examples:

    . dc_editconfig( 'ME.BAT' )
    . DC_EDITPRG( 'test' )
   

Source/Library:

  _DCEDPRG.PRG, DCLIP1.DLL

See Also:

   EDIT FILE

dc_enabletabpagecolors()

Get-Set function for enabling/disabling tab page colors

Syntax:

   DC_EnableTabPageColors( < lEnable > ) - > lOldEnable
   

Arguments:

   < lEnable > if .TRUE. will enable tab page colors (default).  If
   .FALSE. will disable tab page colors.
   

Description:

   DC_EnableTabPageColors() is a Get-Set function that is used to
   enable or disable the painting of Tabpage colors when tabpages
   are created with the @ DCTABPAGE command.
   
   By default, tab page colors are always enabled.
   
   All tabpage colors may be disabled throughout the application
   by call DC_EnableTabPageColors(.F.).  This would be desirable
   when using the CodeJock SkinFramework system when tab colors from
   the skin are preferable.
   

Source/Library:

  _dcclass.prg, dclipx.dll

See Also:

   @ DCTABPAGE

dc_enterexitmode()

Get/Set behavior of ENTEREXIT clause

Syntax:

   DC_EnterExitMode( [< nMode >] ) - > nOldMode
   

Arguments:

   < nMode > sets the new mode in accordance with the below table.
   
   * - Default
   
   < nMode >   Description
   -------  -----------------------------------------------------
     0  *    Standard Enter-Exit (exits if ENTER is pressed on last Get)
     1       ENTER pressed on last Get gives focus to OK button.
     2       Exits if ENTER is pressed any time.
   

Returns:

   A numeric value.
   

Description:

   DC_EnterExitMode() is a Get/Set function used to establish the
   behavior of the ENTEREXIT clause of DCREAD GUI.
   

Examples:

   DC_EnterExitMode(1) // Pressing enter in last get gives focus to OK button.
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.DLL

See Also:

   DCREAD GUI

dc_envirrest()

Restore the environment from an array or file

Syntax:

   DC_EnvirRestore ( < aEnvir > | < cEnvirFile > ) - > NIL
   

Arguments:

   < aEnvir > is an array of environment variables that was saved by
   DC_ENVIRSAVE().
   
   < cEnvirSave > is an array file containing the contents of the
   environment that was saved by DC_ENVIRSAVE( < cEnvirSave > ).
   

Returns:

    NIL
   

Description:

    DC_ENVIRREST() is used to restore all 38 Clipper environment
    variables from an array or a file created by DC_ENVIRSAVE().
   
    The Clipper environment consists of everything from SET CURSOR,
    SET DEFAULT, to SET ALTERNATE, etc.
   
    Use this function to restore the Clipper environment after
    running a task that may have altered the environment.
   

Examples:

    -- EXAMPLE 1 --
   
    aEnvir := dc_envirsave()
    do something
    DC_ENVIRREST( aEnvir )
   
    -- EXAMPLE 2 --
   
    dc_envirsave( 'ENVIR.AR' )
    do something
    DC_ENVIRREST( 'ENVIR.AR' )
   

Source/Library:

  _DCENVIR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_envirsave()

dc_envirsave()

Save the entire environment to an array or file

Syntax:

   DC_EnvirSave ( < cFileName > ) - > nil
   

Arguments:

   < cFileName > the name of the file to save the Clipper
   environment to.
   
   If no argument is passed then no file will be created, however
   the current Clipper environment will still be returned in an
   array.
   

Returns:

    The 38 Clipper environment variables in an array.  See ARRAY.CH
    (included in Clipper distribution) for the values.
   

Description:

    DC_ENVIRSAVE() is used to save all 38 Clipper environment
    variables to an array or a file for later restoring by
    DC_ENVIRREST().
   
    The Clipper environment consists of everything from SET CURSOR,
    SET DEFAULT, to SET ALTERNATE, etc.
   

Examples:

    -- Example 1 --
   
    aEnvir := DC_ENVIRSAVE()
    do something
    dc_envirrest( aEnvir )
   
    -- Example 2 --
   
    DC_ENVIRSAVE( 'ENVIR.AR' )
    do something
    dc_envirrest( 'ENVIR.AR' )
   

Source/Library:

  _DCENVIR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_envirrest()

dc_eof()

Is the record pointer at the end of the file?

Syntax:

    DC_Eof() - > lStatus
   

Arguments:

    None.
   

Returns:

    A logical value.
   

Description:

    DC_EOF() is used to test whether or not DC_DbSkip() attempted
    to move the record pointer past the bottom record in a "scoped"
    set of records when using a positive skip value.  If no scope
    is set or the ADSDBE is being used as the data driver for the
    current work area this function simply calls Eof() therefore
    it can be used as a replacement for Eof().
   

Notes:

Examples:

    DC_SetScope(0,'12001')
    DC_SetScope(1,'12001')
   
    DC_DbGoTop()
   
    DO WHILE !DC_Eof()
      DC_DbSkip(1)
    ENDDO
   

Source/Library:

  _DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()
   dc_bof()
   dc_dbskip()
   dc_dbgotop()
   dc_dbgobottom()

dc_erase()

Delete a file

Syntax:

    DC_Erase()
   

Arguments:

    None.
   

Returns:

    A logical .TRUE. if the file was successfully deleted, .FALSE.
    otherwise.
   

Description:

    DC_Erase() is used to delete a file from the disk.  A GUI user
    dialog is displayed to choose a file name to delete.
   

Examples:

    . DC_Erase()
   

Source/Library:

  _DCERASE.PRG, DCLIP1.DLL

See Also:

   DELETE FILE

dc_error2string()

Converts an Error() object to a string

Description:

   DC_Error2String() will generate a string of error information from
   the info in an Error() object.
   
   The string will also contain stack info, environment info and
   status of all open workareas.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

dc_errormsg()

Display an array of error messages in a window

Syntax:

   DC_ErrorMsg ( < aMessage >, ;
                 [< lSound >], ;
                 [< cTitle >] ) - > nil
   

Arguments:

   < aMessage > is an array of messages to display in the popup
   box.
   
   < lSound > - if .FALSE. don't sound error beep; default is
   .TRUE.
   
   < cTitle > is the title displayed in top line center of popup
   box; defaults to 'ERROR'
   

Returns:

    nil
   

Description:

    DC_ERRORMSG() is used to display a popup error box onscreen.
    You can override the defaults for sound and title as optional
    params. The box is self centering onscreen; the text array
    is centered inside the box.  Pressing any key or mouse
    button will remove the popup box.
   

Notes:

   dc_errormsg ( <þaMessageþ>, [lSound], [cTitle] ) -þ> Nil
   

Examples:

    if !isprinter()
      DC_ERRORMSG( {'Printer Is Offline - Please Ensure Power',;
                    'Is On And Paper Is Inserted Properly'},;
                    '',;
                    ' Printer Error ')
    else
      ...
      ...
    endif
   

Source/Library:

  _DCMSG.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_msgbox()
   dc_alert()

dc_excel2array()

Create a 2-dimensional array from an Excel file

Syntax:

   DC_Excel2Array( < cFileName >, [< bEval >] ) - > aData
   

Arguments:

   < cFileName > is the name of the Excel XLS file including the full
   path.
   
   < bEval > is a code block to evaluate after the Excel file is opened.
   The Excel object and book automation object are passed to the code
   block.  This can be used for formatting cells before the array is
   created.
   

Returns:

   A 2-dimensional array.
   

Description:

   DC_Excel2Array() will create a 2-dimensional array from the
   contents of an Excel file.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_array2excel()
   dc_workarea2excel()
   dc_excel2workarea()

dc_expandtree()

Expand all nodes of a TreeView branch

Syntax:

   DC_ExpandTree( < oTreeItem > | < oTreeRoot >, ;
                  [< lExpand >] ) - > nil
   

Arguments:

   < oTreeItem > is any tree view branch object that is derived from
   XbpTreeViewItem() or < oTreeRoot > is an object that is derived
   from XbpTreeView().
   
   If < lExpand > is .TRUE. (default) then the tree branch will be
   expanded otherwise it will be collapsed.
   

Returns:

   Nil.
   

Description:

   DC_ExpandTree() will expand or collapse all sub branches of a
   specified tree branch in an XbpTreeView.
   

Source/Library:

  _DCARRAY.PRG, DCLIPX.DLL

dc_expl()

Explode a Text or GUI dialogue window

Syntax:

   DC_Expl( < nStartRow >, ;
            < nStartCol >, ;
            < nEndRow >, ;
            < nEndCol >, ;
            [< cTitle >], ;
            [< lNoShadow >], ;
            [< lPaintOnly >], ;
            [< lCenter >], ;
            [< lRelative >], ;
            [< cFont >], ;
            [< lGui >] ) - > aObject
   

Arguments:

   < nStartRow >, < nStartCol >, < nEndRow >,
   < nEndCol > are the screen
   coordinates, relative to 0,0 of the physical screen.
   
   < cTitle > is the title heading on the top of the dialogue box.
   If no argument is given, then there will be no title area.
   
   < lNoShadow > if .TRUE. will prevent the shadow from being
   created. Default is .FALSE. (shadow enabled).  This parameter
   is used in TEXT mode only.
   
   < lPaintOnly > if .TRUE. will paint the box on the screen but not
   perform the "exploding" process.  Default is .FALSE. (explode).
   This parameter is used in TEXT mode only.
   
   < lCenter > will center the dialogue box on the screen and use
   the coordinates only for determining the height and width
   of the window.
   
   < lRelative > if .TRUE. (default) assumes that coordinates
   passed by DC_SAY() to this window are relative to location
   0,0 of the window, otherwise they are relative to 0,0 of
   the screen.
   
   < cFont > is a valid font name for this window.  This font will
   be used as the default for all Says in this window via DC_SAY().
   If no font parameter is passed, the default it 10.Courier.
   This parameter is used in GUI mode only.
   
   < lGui > is used to override the setting of DC_GUI().  If
   < lGui >
   is .TRUE. then this will be a GUI dialogue.  IF < lGui > is
   .FALSE. it will be a TEXT dialogue, otherwise it will follow
   the setting of DC_GUI().
   

Returns:

    An array of information about the screen object that is used
    with DC_Say(), DC_Cls() and DC_Impl().
   

Description:

    DC_EXPL() is a Dual-Mode function that is used to explode a
    dialogue box on the screen.  In TEXT mode, this function is
    a front-end to DC_EXPLODE() that uses pre-defined system
    colors which are part of the DCCOLOR color array.  See
    DCCOLOR.CH for a definition of the color manifest constants.
    In GUI mode, it creates a GUI dialogue window.  In both
    modes, it returns an array of information that is passed to
    compatible Dual-Mode functions like DC_Say(), DC_Cls(), and
    DC_Impl().
   
    DC_EXPL() also stores the array of screen information in a
    static array so the functions DC_Say(), DC_Cls() and DC_Impl()
    can be called without passing the screen array.
   

Notes:

    Use DC_EXPLMODE(.f.) to disable the exploding process when you
    want screens to display "instantly" instead of "explode".
   
    This is particularly useful when running the application on a
    slower computer.
   
    Use DC_ALTSHADOW(.t.) to display the shadow on the right
    side of the box.
   

Examples:

    -- Example 1 --
   
    aSaveScreen := DC_EXPL( 10,10,12,70, ' Enter a command ' )
    cCommand := SPACE(50)
    @ 11,12 get cCommand
    read
    dc_impl( aSaveScreen )
   
    -- Example 2 --
   
    aSaveScreen :=  ;
        DC_EXPL( 10,10,15,70,'A Gui SAY Window',,,,,,.t. )
    dc_say(aSaveScreen,2,5,'This is 3/5')
    dc_say(aSaveScreen,4,10,'This is 4/10')
    dc_impl(aSaveScreen)
   

Source/Library:

  _DCEXPL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_say()
   dc_cls()
   dc_impl()
   dc_explode()
   dc_implode()

dc_explmode()

Enable/Disable exploding windows

Syntax:

   DC_ExplMode ( < lExplode > ) - > lMode
   

Arguments:

   < lExplode > if .TRUE. will force all windows created with
   DC_EXPL() and DC_EXPLODE() to "explode" (default).  If .FALSE.
   then all windows will be painted in "instant on" mode.
   

Returns:

    A logical value.  .T. - Instant On Mode, .F. - Explode Mode.
   

Description:

    Use DC_EXPLMODE(.f.) to disable the exploding process when you
    want screens to display "instantly" instead of "explode".
   
    This is particularly useful when running the application on a
    slower computer.  DC_EXPLMODE() affects the operation of the
    following functions:
   
      DC_EXPL(), DC_EXPLODE(), DC_IMPL(), DC_IMPLODE()
   

Examples:

    DC_EXPLMODE( .t. )  // Set instant on mode
    dc_browtile()       // Paint all the browse windows
    DC_EXPLMODE( .f. )  // Set explode mode
   

Source/Library:

  _DCEXPL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_expl()
   dc_explode()

dc_explode()

Explode a window

Syntax:

   DC_Explode( < nSrow >, ;
               < nScol >, ;
               < nErow >, ;
               < nEcol >, ;
               < cColor1 >, ;
               < cColor2 >, ;
               [< lTone >], ;
               [< cTitle >], ;
               [< nSlideRate >], ;
               [< lShadow >], ;
               [< lPaintOnly >], ;
               [< lDouble >] ) - > cSaveScreen
   

Arguments:

   < nSrow >, < nScol >, < nErow >, < nEcol > are
   the screen coordinates.
   
   < cColor1 > is the color of the window frame.
   
   < cColor2 > is the color of the window contents.
   
   < lTone > if .TRUE. will create a warning tone.  .FALSE. is
   default.
   
   < cTitle > is the a title to display at the top of the box.
   
   < nSlideRate > is a number from 1 to 10 to determine the speed at
   which a small box starting at the current cursor location moves
   across the screen to start the explode process.  A value of 0
   (default) will disable the sliding box. The smaller the number
   the faster the sliding box will move.
   
   < lShadow > if .TRUE. (default) will paint a shadow on the
   screen.
   
   < lPaintOnly > if .TRUE. will override the setting of
   DC_EXPLMODE() and "instantly" paint the box on the screen
   rather than "exploding" the box.
   
   < lDouble > if .TRUE. will paint a double line border.  A single
   line border (.FALSE.) is default.
   

Returns:

    A character string that is a "composite" of the coordinates,
    colors, etc. to be used later to restore the screen with
    DC_IMPLODE().
   

Description:

    DC_EXPLODE() is used to explode a window on the screen with
    optional border, colors, tone, shadow, etc.
   

Examples:

    cSaveScrn := DC_EXPLODE(5,10,7,70,'B/W','N/W',.F.,;
                 ' Enter a Command ',10)
    cCommand := space(50)
    @ 6,12 get cCommand
    read
    dc_implode( cSaveScrn )
   

Source/Library:

  _DCEXPL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_implode

dc_expressbuttonstyle()

Get or Set the default style for eXpress++ push buttons

Syntax:

   DC_ExpressButtonStyle( [< oConfig >] ) - > oOldConfig
   

Arguments:

   < oConfig > is an object of the DC_XbpPushButtonXPConfig() class.
   

Description:

   DC_ExpressButtonStyle() is a Get-Set function that is used
   to Set or Get the default configuration object for pushbuttons
   that are automatically added to eXpress++ windows via the
   ADDBUTTONS clause of DCREAD GUI command or the BUTTONS clause
   of the DCGETOPTIONS command.
   

Examples:

   oConfig := DC_XbpPushButtonXPConfig():new()
   
   oConfig:radius := 20
   oConfig:bgColor := GRA_CLR_CYAN
   
   DC_ExpressButtonStyle( oConfig )
   

Source/Library:

  _dcxbutt.prg, dclipx.dll

See Also:

   dc_xbppushbuttonxpconfig()
   DCREAD
   DCGETOPTIONS

dc_fancybuttonmode()

Enable or disable FANCY pushbuttons

Syntax:

   DC_FancyButtonMode( < nMode > ) - > nOldMode
   

Arguments:

   < nMode > is a numerical value from 0 to 2.
   
   0 - Buttons behave the way they were defined in the DCTOOLBAR
       or @..DCPUSHBUTTON command.  If the FANCY clause was used,
       then the button will be FANCY otherwise it will be NORMAL.
   
   1 - Buttons are all NORMAL.
   
   2 - Buttons are all FANCY.
   

Returns:

   A numerical value from 0 to 2.
   

Description:

   DC_FancyButtonMode() is used to enable or disable FANCY buttons
   when using the @..DCPUSHBUTTON or DCTOOLBAR commands.
   
   FANCY buttons are "mouse-aware" pushbuttons that display when
   the mouse is moved over the static area of the pushbutton.
   

Examples:

   DC_FancyButtonMode(2) // make all buttons FANCY
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.DLL

See Also:

   DCADDBUTTON

dc_fielddel()

Delete a field group from the field group dictionary

Syntax:

   DC_FieldDel ( [< cFieldGroup >], ;
                 [< lImport >] ) - > lStatus
   

Arguments:

   < cFieldGroup > is the name of the field group to delete. If this
   parameter is empty, a picklist of all field groups will be
   displayed to choose the group to delete.
   
   < lImport > if .TRUE. will display the list of field groups in
   the DXFIELDS.DBF (import) dictionary, otherwise the list will
   come from the DCFIELDS.DBF dictionary.
   

Returns:

   A logical .TRUE. if the field group was successfully deleted,
   .FALSE. otherwise.
   

Description:

   DC_FieldDel() is used to delete a field group from the Field
   Group dictionary file.
   

Notes:

    The DCFIELDS.DBF database and its associated indexes will
    be created by DC_FieldOpen() if they do not already exist.
   

Examples:

    // delete a field group from the DXFIELDS.DBF import file.
    cFieldGroup := DC_FieldPick(.t.)
    DC_FieldDel(cFieldGroup,.t.)
   

Source/Library:

  _DCFLDS.PRG, DCLIP1.LIB

See Also:

   dc_fieldedit()
   dc_fieldload()
   dc_fieldsave()
   dc_fieldpick()

dc_fieldedit()

Field Dictionary Editor

Syntax:

   DC_FieldEdit ( [ < cFieldGroup > | < aFieldGroup > ] )
                   - > aFieldGroup
   

Arguments:

   < cFieldGroup > | < aFieldGroup > is the name of the field
   group
   in DCFIELDS.DBF to load and edit (up to 8 characters) or
   < aFieldGroup > is a Field Group array.  See RETURNS for a
   specification of this array.  If no parameter is passed, a
   pick-list of all Field Groups in DCFIELDS.DBF will be displayed.
   

Returns:

    An array consisting of 2 sub-arrays:
   
    Sub-array #1 contains general information about this field
    group.
   
    * - Maximum Length allowed, Minimum Length is 0
   
    Element         Type   Len   Description
    -------------   ----   --- -------------------------------
       1             C       8*  Field Group Name
       2             C      10*  File Alias
       3             C      50*  Field Group Description
   
   
    Sub-array #2 contains one sub-array for each field
    definition.
   
   
    See DCFIELDS.CH for the definitions of the array elements.
   
    Element         Type   Len   Description
    -------------   ----   ---   --------------------------------
    DCFLD_ALIAS      C      10*  Alias of database
   
    DCFLD_NAME       C      10*  Field Name
   
    DCFLD_TYPE       C       2*  Field Type ( C,D,L,N,M,CA,A,V )
   
    DCFLD_LEN        N           Field Length
   
    DCFLD_DEC        N           Field Decimals
   
    DCFLD_DESC       C      50*  Field Descriptor (used in browse
                                 column headings and edit screens)
                                 Use semi-colons (;) for multiple
                                 lines.
    DCFLD_PROMPT     C     200*  Field Prompt (used in message box)
   
    DCFLD_PICT       C     100*  Field Picture Clause
                                 See Xbase++ TRANSFORM() function
   
    DCFLD_VALTYPE    C       1   Field Validation Type
                                 See DC_FieldValidate() for more info
                                 N - None
                                 F - Calculated Field
                                 X - Logical Expression
                                 R - Range
                                 D - Database Look-Up
                                 T - Table Look-Up
                                 V - View (Browse) Look-Up
                                 A - Auto-Fill
                                 C - Choice
                                 E - Case
                                 M - Memo Window
   
    DCFLD_DEFAULT    C     150*  Field Default value code block.
                                 Code block must return a value that
                                 is the same type as the field.
   
    DCFLD_WHEN       C     100*  Field When code block.  Code block
                                 must return a logical value.  Used
                                 to enable/disable field editing based
                                 on condition.  Will gray out disabled
                                 items.
   
    DCFLD_PROTECT    C     100*  Field Protect code block.  Code block
                                 must return a logical value.  Used
                                 to enable/disable field editing based
                                 on condition.  Will not gray out
                                 disabled items.
   
    DCFLD_VALID      M      10*  Field Valid Clause or Formula.  This
                                 must be a code block that returns a
                                 logical value or a set of parameters
                                 separated by the | delimeter.  The
                                 parameters must conform to the type
                                 of validation.  See DCFLD_VALTYPE
                                 above.
   
    DCFLD_EMPTY      L           Empty Value Allowed
   
    DCFLD_EDIT       L           Editing Allowed
   
    DCFLD_ACCESS     C       5*  Access Key
   
    DCFLD_SORT       N           Sorting element (reserved)
   
    DCFLD_HELPCODE   C      22*  Help Code
   
    DCFLD_EDOPT      C      50*  Edit Option String
   
    DCFLD_VALUE      X           Place to store Old Field Value
   
    DCFLD_OLDNAME    C      10*  Old field name
   
    DCFLD_OLDTYPE    C       2*  Old field type
   
    DCFLD_ENCRYPT    C       8*  Encryption password
   
    DCFLD_PROGRAM    C           Program Validation (memo)
   
    DCFLD_FLAG       L       1   Logical flag (reserved)
   
    DCFLD_COMPILE    C     100*  Compile Code Block.  Must return
                                 a logical value.  Used to enable
                                 or disable inclusion of this
                                 field in data-entry screen based
                                 on a condition.
   
    DCFLD_FONT       C      50*  Default Font Compound Name
   
    DCFLD_TOOLTIP    C     100*  ToolTip.  Use semicolons for
                                 multiple lines.  May also be a
                                 code block.
   
    DCFLD_CARGO      A           Cargo Array
   
    DCFLD_ORDER      N           Field Order in Database
   
    DCFLD_POPUP      C     100*  PopUp Code Block.  Must return a
                                 value that is the same type as
                                 the field.  This code block
                                 receives the value of the GET as
                                 a parameter.  The code block is
                                 evaluated when the user clicks on
                                 the PopUp button next to the GET.
   

Description:

   DC_FieldEdit() is a field definition editor that maintains
   the definition of each database field and their browsing,
   editing and validation properties.  The field definitions
   are stored to an array and/or the DCFIELDS.DBF data-
   dictionary file.
   
   DC_FieldEdit() will also update the structure of a database
   if a field definition has been changed and retain all
   existing data even if a field type or name has been changed.
   

Notes:

    The DCFIELDS.DBF database and its associated indexes will
    be created by DC_FieldOpen() if they do not already exist.
   

Examples:

    -- Example 1 --
    // Load a field group from the dictionary and edit it //
    DC_FIELDEDIT()
   
    -- Example 2 --
    // Edit field group "CUSTOMER"
    DC_FIELDEDIT("CUSTOMER")
   
    -- Example 3 --
    // Edit a field group array //
    aFieldGroup := DC_FieldPick()
    aFieldGroup := DC_FIELDEDIT( aFieldGroup )
   

Source/Library:

  _DCFLDS.PRG, DCLIP1.LIB

See Also:

   dc_fieldload()
   dc_fieldvalidate()

dc_fieldload()

Load a field Group Array from the Field Dictionary

Syntax:

   DC_FieldLoad ( [< cGroupName >], ;
                  [< lCache >], ;
                  [< lMessage >], ;
                  [< lCreateDbf >], ;
                  [< lErrorOk >], ;
                  [< lImport >] ) - > aFieldGroup
   

Arguments:

   < cGroupName > is the name of the field group in DCFIELDS.DBF
   to load (up to 8 characters).  If no parameter is passed, a
   pick-list of all Field Groups in the DCFIELDS.DBF dictionary
   will be displayed.
   
   < lCache > if .TRUE. (default) will save the group to a static
   (cache) array so the next time it is requested it will
   be reloaded from the cache for faster speed.  If .FALSE. then
   it will not be saved to the static array.
   
   < lMessage > if .TRUE. (default) will display an error message
   if the Field Group could not be loaded or does not exist
   in the dictionary file.  If .FALSE, then no error message
   will be displayed.
   
   < lCreateDbf > if .TRUE. (default) will create any empty
   DCFIELDS.DBF if it cannot be found.  If .FALSE. the
   database will not be created.
   
   < lErrorOk > if .FALSE. (default) will return a NIL if the
   field array being loaded does not match the structure of the
   currently selected database.  If .TRUE. then the field array
   loaded from the dictionary will always be returned.
   
   < lImport > if .TRUE. will attempt to load the array from a
   an import file named DXFIELDS.DBF.  If .FALSE. (default) then
   the array will be loaded from the standard DCFIELDS.DBF
   dictionary.
   

Returns:

   An array consisting of 2 sub-arrays:
   
   See the RETURNS section of DC_FieldEdit() for a specification
   of this array.
   

Description:

   DC_FieldLoad() is used to retrieve a field group from the
   DCFIELDS.DBF field group dictionary and store it to an array.
   

Notes:

    The DCFIELDS.DBF database and its associated indexes will
    be created by DC_FieldOpen() if they do not already exist.
   

Examples:

    aFieldGroup := DC_FIELDLOAD()
    aFieldGroup := DC_FieldEdit( aFieldGroup )
    DC_FieldSave( aFieldGroup )
   

Source/Library:

  _DCFLDS.PRG, DCLIP1.LIB

See Also:

   dc_fieldedit()
   dc_fieldvalidate()
   dc_fieldsave()

dc_fieldpick()

Choose a field group or browse the field group dictionary

Syntax:

   DC_FieldPick ( [< cTitle >], ;
                  [< lImport >], ;
                  [@< aGroupList >], ;
                  [< lNoPick >] ) - > cGroupName
   

Arguments:

   < cTitle > is the title to display in the pick list window.
   
   < lImport > if .TRUE. will display the list of field groups in
   the DXFIELDS.DBF (import) dictionary, otherwise the list will
   come from the DCFIELDS.DBF dictionary.
   
   @< aGroupList > is a variable, passed by reference, to store an
   array of all group names and descriptions.
   
   < lNoPick > if .TRUE. is used in conjunction with
   < aGroupList >.
   This is used to only return the array of Group names and not
   display the picklist.
   

Returns:

   A Character string containing the name of the chosen group.
   This will contain a null string if <þlNoPickþ> is .TRUE. or if
   the operator aborts the choice.
   

Description:

   DC_FieldPick() is used to pop up a list of field groups in the
   field group dictionary.
   

Notes:

    The DCFIELDS.DBF database and its associated indexes will
    be created by DC_FieldOpen() if they do not already exist.
   

Examples:

    cFieldGroup := DC_FieldPick()
    aFieldGroup := DC_FieldLoad(cFieldGroup)
    aFieldGroup := DC_FieldEdit( aFieldGroup )
    DC_FIELDSAVE( aFieldGroup )
   

Source/Library:

  _DCFLDS.PRG, DCLIP1.LIB

See Also:

   dc_fieldedit()
   dc_fieldload()
   dc_fieldsave()

dc_fieldsave()

Save a Field Group Array to the Field Dictionary

Syntax:

   DC_FieldSave ( < aFieldGroup >, ;
                  [< lExport >] ) - > lStatus
   

Arguments:

   < aFieldGroup > is a field group array that conforms to the
   specification in the RETURNS section of DC_FieldEdit().
   
   < lExport > if .TRUE. will save the field group to a file named
   DXFIELDS.DBF, otherwise it will be save to DCFIELDS.DBF.
   

Returns:

   A logical .TRUE. if the field group was successfully saved,
   .FALSE. otherwise.
   

Description:

   DC_FieldSave() is used to save a field array to the DCFIELDS.DBF
   field group dictionary.
   

Notes:

    The DCFIELDS.DBF database and its associated indexes will
    be created by DC_FieldOpen() if they do not already exist.
   

Examples:

    aFieldGroup := DC_FieldLoad()
    aFieldGroup := DC_FieldEdit( aFieldGroup )
    DC_FIELDSAVE( aFieldGroup )
   

Source/Library:

  _DCFLDS.PRG, DCLIP1.LIB

See Also:

   dc_fieldedit()
   dc_fieldvalidate()
   dc_fieldload()

dc_fieldvalidate()

Validate a value in a field during data entry

Syntax:

   DC_FieldValidate ( < xFieldGet >, ;
                      < aFields >, ;
                      < nPos >, ;
                      [< lPopUp >] ) - > lValid
   

Arguments:

   < xFieldGet > is the value to validate.  This is the value from
   the data entry GET.
   
   < aFields > is a field array that conforms to the specification
   for a field array created by DC_FieldEdit().  The field array
   defines all the properties of all fields for the currently
   selected work area including validation types and formulas.
   
   < nPos > is the field position in the Field Array that points to
   the field being validated.
   
   < lPopUp > if .TRUE. will force picklists to be displayed even if
   the field validates correctly.
   

Returns:

   A logical .TRUE. if the field validates, otherwise a logical
   .FALSE.
   

Description:

   DC_FieldValidate() is used to validate the value entered into
   a field during data entry.  Validation types are entered in the
   field editor using DC_FieldEdit().
   

Notes:

   Validation Types:
   
   Validations are entered as formulas.  Each validation type
   requires a different formula.  A formula is simply a list of
   parameters separated by the vertical bar | character.  The
   Validation type and formula are entered into the Field Array
   by using the Field Editor : DC_FieldEdit() or the dot prompt
   command FIELD EDIT.
   
   An easier method of entering the formula and preventing mistakes
   is to use the FORMULA EDITOR by pressing CTRL-ENTER or clicking
   on the PopUp button after the formula field in the field editor.
   
   ==============================================================
   
   VALIDATION TYPE X - Expression
   
    Validation type "X" is used to evaluate an expression that
    returns a logical .TRUE. or .FALSE. based on the operator
    input and/or other field data. When entering the VALIDATION
    FORMULA, it must be a valid expression that when macro-expanded,
    returns a "logical" value of .TRUE. for a valid entry or a
    .FALSE. for an invalid entry.
   
    For example you may have a field named "HOURS" that is allowed
    to have a range of 0-4 when the DATE field has a week-end date
    or a range of 0-8 when the DATE field has a weekday date.
    The expression for creating this type of validation is:
   
    IIF(DOW(DATE)=1.OR.DOW(DATE)=7,HOURS<þ=4,HOURS<þ=8)
   
    If the operator attempts to enter more than 8 hours for a
    weekday or more than 4 hours for a weekend, a message similar
    to the following will appear:
   
    "Invalid Input. Must meet following Condition"
   
   ==============================================================
   
   VALIDATION TYPE V - Browse Lookup
   
    Validation type "V" is used to seek a value from another
    database based on a passed value and then optionally choose a
    value from a BROWSE pick-list whose configuration was previously
    created and stored in the DCBROWSE.DBF Browse Catalog using the
    BROWSE editor.
   
    If the entered value already matches a "seek" value in the
    target database, or if the "allow override" flag is "YES",
    then the database browse will not be displayed unless the
    operator clicks on the popup button at the end of the field
    when in data-entry mode or presses CTRL-ENTER when editing the
    field.  A "V" validation also provides for moving data between
    fields of different databases upon completion of the successful
    validation by referencing a previously created "Field Map".
   
    Param 1 - The TAG NAME of the "Look-Up" FILE GROUP that must be
              opened for performing this validation.  This must be a
              valid File Group Name in the DCFILES.DBF database that
              was assigned by the FILE EDITOR via the command
              "FILE EDIT" or the function "DC_FILEEDIT()".  A FILE
              GROUP is a set of database files, indexes and/or
              relations required to perform the validation.  If no
              TAG NAME is entered, then it is assumed that the
              "Look-Up" file is already opened.
   
    Param 2 - The TAG NAME of the "Look-Up" BROWSE CONFIGURATION to
              use for choosing a record from the target (Look-Up)
              database(s).  This must be a valid Browse Configuration
              in the DCBROWG.DBF database that was assigned by the
              BROWSE EDITOR from the command "BROWSE GUI" or the
              function "DC_BrowseGuiDb()".  If NO Tag Name is entered,
              then a DEFAULT BROWSE will be created for the target
              (Look-Up) database that will consist of all database
              fields.
   
    Param 3 - The FILE ALIAS of the "Look-Up" File to select for
              performing the validatiion.
   
    Param 4 - The SEARCH INDEX NUMBER of the controlling index to
              use when "seeking" to the record in the "Look-Up"
              database.  The key of this index must match the value
              of the Look-Up field or Expression to seek the value.
   
    Param 5 - The LOOK-UP FIELD OR EXPRESSION to use for extracting
              the value to "seek" in the "Look-Up" database.  This
              expression must return a value of the same type as
              the index key of the controlling index to seek the
              value.
   
    Param 6 - The RETURN FIELD OR EXPRESSION to use for extracting
              the value to return into the field being validated.
              This expression must return a value of the same type
              as the database field being validated.
   
    Param 7 - START SCOPE Expression or Code Block.  This is an
              optional expression or code block that when evaluated
              returns a value that matches the type of the selected
              index for the top scope value or first record to be
              displayed in the browse window.
   
    Param 8 - STOP SCOPE Expression or Code Block.  This is an
              optional expression or code block that when evaluated
              returns a value that matches the type of the selected
              index for the bottom scope value or last record to be
              displayed in the browse window.
   
    Param 9 - A Y for YES or N for NO to establish whether or not
              the operator is allowed to OVERRIDE the value returned
              from the browse.  If YES and the operator presses
              ESCAPE, then nothing is returned, otherwise if NO
              then the selected value is returned regardless of the
              method of exiting the browse by the operator.
   
    Param 10 - The 'optional' FIELD MAP TAG NAME to use for moving
              information from the Look-Up database to the current
              database or from any other open database to any other
              open database.  This must be a valid field map tag name
              that exists in the DCMAPS.DBF database which is
              maintained by the command "FMAP EDIT" or the function
              "DC_FMAPEDIT()".
   
    Param 11 - The 'optional' FIELD NAME to extract information to
              pass to the FIELD MAP as the FIELD MAP SUBGROUP.  Only
              the items in the Field Map that match the value in this
              field will be evaluated when performing the mapping
              process.  This parameter is ignored if parameter 9 is
              empty.
   
    NOTE: A type "V" validation will leave the Look-up database
          record pointer at the record selected by the operator
          or at the record automatically found that matches the
          data entered in the field. This record can then be used
          to transfer information from any set of fields in the
          Look-Up database to any set of fields in the current
          database by using a type "A" validation on each field.
   
    An easier method of entering the formula and preventing mistakes
    is to use the FORMULA EDITOR by pressing CTRL-ENTER, clicking
    the popup button or leaving the formula empty.  The FORMULA
    EDITOR reads the existing formula and provides a series of data-
    entry fields and pick-lists to simplify the creating of
    validations.
   
    Example:
   
     Look-up Files Tag :CUSTOMER  :
    Look-up Browse Tag :CUSTOMER1 :
    Look-up File Alias :CUSTOMER  :
       Look-up Index # : 2:
    Look-up Field/Expr :CUST_NMBR                :
     Return Field/Expr :CUST_NMBR                :
           Start Scope : {||INVOICE-þ>CUST_NMBR}
            Stop Scope : {||INVOICE-þ>CUST_NMBR}
       Allow Override? :N:
   
   ==============================================================
   
   VALIDATION TYPE T - Code Table Lookup
   
    Validation type "T" is used to choose a value from a code
    table in the DCCODES.DBF Code-Table dictionary and enter it
    into the field.  If the entered value already matches a
    value in the code table, or if the "allow override" flag is
    "YES", then the pick-list of codes will not be displayed
    unless the operator clicks on the popup button at the end of
    the field or presses CTRL-ENTER when editing the field.
   
    A "T" validation also provides for moving data between fields
    of different databases upon completion of the successful
    validation by referencing a previously created "Field Map".
   
    Example of a Code-Table table:
   
    1B  First Base
    2B  Second Base
    3B  Third Base
    P   Pitcher
    SS  Short Stop
    RF  Right Field
    LF  Left Field
    CF  Center Field
    C   Catcher
    DH  Designated Hitter
   
    When the operator chooses an item from the code-table pick-list,
    the value in the CODE field of the DCCODES.DBF database item
    selected will be returned into the data field.  Code-Tables
    are allowed only for validating character-type fields.
   
    Param 1 - The CODE TABLE name to open.
   
    Param 2 - A Y for YES or N for NO to establish whether or not
              the operator is allowed to OVERRIDE the value returned
              from the browse.  If YES and the operator presses
              ESCAPE, then nothing is returned, otherwise if NO
              then the selected value is returned regardless of the
              method of exiting the pick-list by the operator.
   
    Param 3 - An 'optional' FIELD MAP TAG NAME to use for moving
              information from the Code Table database to the current
              database or from any other open database to any other
              open database.  This must be a valid field map tag name
              that exists in the DCMAPS.DBF database which is
              maintained by the command "FMAP EDIT" or the function
              "DC_FMAPEDIT()".  The value returned by the code table
              will be passed to the Field Mapping routine to select
              a mapping "Sub-Group".  If the Map data does not
              include Sub-Groups, then all items in the map will be
              evaluated.
   
    Param 4 - TOKENIZED LIST. Enter a Y if you want each pick from
              the code table to be appended to the value in the GET
              as a list of tokens rather than replacing the value
              in the GET with the selected code.
   
    Param 5 - Enter the delimeter to use between the tokens.
   
   
    NOTE: A type "T" validation will leave the DCCODES.DBF database
          (code-table) record pointer at the selected code table
          record.  This record can then be use to transfer the
          value in CODE_DESC to any other field using a type "A"
          validation.
   
    Example:
   
      Code Table No. :BASEBALL  :
     Allow Override? :N:
       Field Map Tag :          :
     Tokenized List? : Y
     Token Delimiter : ,
   
   ==============================================================
   
   VALIDATION TYPE R - Range
   
    Validation type "R" is used to validate that the entered
    field value falls between a specified range of values.  If
    the operator fails to enter a proper value, an error message
    similar to "Entry must be in the Range between 100 and 500"
    will be displayed and the operator will not be allowed to
    exit the field other than by entering a correct value or
    pressing ESCape.
   
    Example :
   
    Starting Range :100           :
      Ending Range :500           :
   
   ==============================================================
   
   VALIDATION TYPE P - Program
   
    Validation type "P" is used to validate a field entry based
    on the results returned by executing a specified program.
    The program may be a function that is linked into the
    .EXEcutable engine or an "interpreted" program that exists
    in the DCPROG.DBF program catalog.  The program may return
    a value to place into the field or a logical value to validate
    proper data input.
   
    To create a type "P" validation, enter "P" as VALIDATION TYPE
    when using the FIELD EDITOR via the command "FIELD EDIT" or
    function "DC_FIELDEDIT()".  When entering the VALIDATION FORMULA,
    each formula item is separated by a vertical bar | character.
   
    Item 1 - The PROGRAM NAME.  This is a program name of up to
             10 characters.  This program must exist in the
             DCPROG.DBF Program Catalog.  To create or maintain
             this program use the command "PROGRAM MAINTENANCE"
             or the function "DC_PROGMAINT()".  If you wish to
             use a compiled and linked function rather than an
             interpreted program, then include parenthesis ()
             after the PROGRAM NAME.  If you wish to write a
             small program and save it in the memo field of the
             field dictionary enter "MEMO".
   
    Item 2 - Enter Y for YES or N for NO if this is a LOGICAL
             validation rather than a return value.  A LOGICAL
             validation returns a .TRUE. or .FALSE. to validate
             whether or not the data-entry was valid.  If a
             .FALSE. is returned, then the operator will not be
             allowed to move to the next field until a valid
             input is received.  If a NO is entered, then it is
             assumed that the program is returning a value that
             is the same type as the field being validated and
             that this value will be placed into the field.
   
    Items 3 thru 17 - Enter up to 15 PARAMETERS to pass to the
             program.  These may be literal values, functions,
             field names, or expressions.  Each value in each item
             will be macro-expanded before being passed on to the
             program.
   
   ==============================================================
   
   VALIDATION TYPE I - Increment on Append
   
    Validation type "I" is used to assign a default value to a
    field, when appending a new record to the database, that is
    equivalent to an "incremented" value extracted from another
    field in the same database or any other database.  For example,
    if you wish to automatically assign a new invoice number to
    a new record, a type "I" validation can be used to go to the
    last record of the file, extract the last invoice number,
    increment it by a value of 1 and store the new value in the
    field.  Type "I" validations will increment both character
    and numeric fields.
   
    Examples:
   
    Type    Last Value    Incremented Value
    ----    ----------    -----------------
     N      2345          2346
     C      56710         56711
     C      AX-389-BL     AX-390-BL
   
    Param 1 - The FILE ALIAS NAME of the "Look-Up" FILE that must be
              opened for extracting the last value.  This must be a
              valid ALIAS for a file that is already opened when the
              record is being added.  Leave this parameter empty
              if extracting a value from the last record in the
              current database.
   
    Param 2 - The LOOK-UP FIELD OR EXPRESSION to use for extracting
              the value to "seek" in the "Look-Up" database.  This
              expression must return a value of the same type as
              the index key of the controlling index to seek the
              value.  Leave this parameter empty if extracting a
              value from the last record in the current database
              or if the record is already at the correct location,
              such as a 1-record "SYSTEM.DBF".
   
    Param 3 - The RETURN FIELD OR EXPRESSION to use for extracting
              the value to return and increment into the field being
              initialized. This expression must return a value of the
              same type as the database field being validated.  Leave
              this parameter empty if extracting a value from the
              last record in the current database.  If not extracting
              a value from the current database, then the new value
              will be stored in the return field of the related
              database in addition to the storing in the validated
              field of the current database.
   
    Param 4 - The SEARCH INDEX NUMBER of the controlling index to
              use when "seeking" to the record in the "Look-Up"
              database.  The key of this index must match the value
              of the Look-Up field or Expression to seek the value.
              Leave this as 0 if the record in the Look-up database
              does not need to be seeked.
   
    Param 5 - The DEFAULT or STARTING value to enter into the
              database field in the event that an empty value is
              returned from the target (Look-Up) database.
   
    Example :
   
     Lookup File Alias :DCFILES   :
     Lookup Field/Expr :"INVOICE"                       :
     Return Field/Expr :REF_NO                          :
        Seek Index No. : 1:
           Start Value : IN-10001       :
   
   ==============================================================
   
   VALIDATION TYPE F - Calculate value from Expression
   
    Validation type "F" is used to calculate a value from an
    expression that includes references to other fields in the
    database and automatically insert the value returned by
    the expression.  Use a type "F" validation to update "non-
    entry" fields whenever the value in another field changes.
    When entering the VALIDATION FORMULA, it must be a valid
    expression that when macro-expanded, returns a value of the
    same "type" as the field being validated.
   
    For example you may have a field named "HOURS" that is
    automatically filled-in whenever the operator changes the value
    of another field named "MINUTES".  The expression for creating
    this type of calculation is: MINUTES/60.
   
    Example :
   
     Formula :MINUTES/60                               :
   
   ==============================================================
   
   VALIDATION TYPE C - Choice from Pick List
   
    Validation type "C" is used to choose a value from a pick-list
    table of up to 15 choices.  If more than 15 choices are
    required, then use Validation type "T".  If the entered value
    already matches a value in the choice pick-list, or if the
    "allow override" flag is "YES", then the pick-list of choices
    will not be displayed unless the operator clicks on the popup
    button at the end of the field or presses CTRL-ENTER when
    editing the field.
   
    When the operator chooses an item from the pick-list, the number
    of characters in the chosen item will be truncated (cut-off) to
    the length of the field.  Choice Pick-lists are allowed only for
    character-type fields.
   
    Example:
   
     Choice # 1 :1B - First Base                            :
     Choice # 2 :2B - Second Base                           :
     Choice # 3 :3B - Third Base                            :
     Choice # 4 :P  - Pitcher                               :
     Choice # 5 :SS - Short Stop                            :
     Choice # 6 :RF - Right Field                           :
     Choice # 7 :LF - Left Field                            :
     Choice # 8 :CF - Center Field                          :
     Choice # 9 :C  - Catcher                               :
     Choice #10 :DH - Designated Hitter                     :
     Choice #11 :                                           :
     Choice #12 :                                           :
     Choice #13 :                                           :
     Choice #14 :                                           :
     Choice #15 :                                           :
     Allow Override? :Y:
   
   ==============================================================
   
   VALIDATION TYPE A - AutoFill
   
    Validation type "A" is used to automatically fill the
    field with a value from a relational file after the
    operator entered data in an associated field in the field
    list.  A type "A" validation is also referred to as
    "AUTOFILL" and must also be associated with a type "V"
    "D", or "T" validation elsewhere in the data-field table.
    AUTOFILL validations are "triggered" by a "V", "D", or "T"
    validation in the following manner:
   
    1. The operator chooses a record from a relational file
       or a code table while validating a field that has a
       type "V" or "T" validation.  After the data record is
       selected from the relational file, a pointer to the
       relational file is stored away in a variable, the
       relational file remains open, and the record pointer in
       the relational file is pointing to the selected record.
   
    2. The field list is then scanned to see if there are any
       fields with type "A" validations that also have a
       reference to the field name that triggered the "V" or "T"
       validation.  For each field that has a reference, the
       data from the specified relational file field will be
       written to that field.
   
    Fields that have been filled by an AUTOFILL validation may
    be overwritten when the field is entered provided that it
    is an "editable" field.
   
    Param 1 - The name of the field in the field list that triggered
              the AUTOFILL with a type "V" or "T" validation.
   
    Param 2 - The name of the field in the relational file chosen
              by the type "V" or "T" validation that contains the
              data to be written to this field.  If the "V" or
              "T" validation uses only a single relational file
              then it is not necessary to use the alias in front
              of the field name, however, it is always a good
              idea.
   
    Example:
   
      Lookup Field/Expr :CUST_NMBR   :
      Return Field/Expr :CUSTOMER-þ>NAME                      :
   

Examples:

   FUNCTION XTest()
   
   /* This example shows how to use the field dictionary to
      display a data-driven browse and data-entry screen */
   
   LOCAL GetList := {}, i, aFieldGroup, oBrowse, cAlias, aFieldOpt, ;
         aFieldItems, oTabPage1, oTabPage2, oTabPage2Static, bGetSet, ;
         bKeyBlock, bPopUp, GetOptions, bCompile
   
   DC_FileRest('COLLECT')
   aFieldGroup := DC_FieldLoad('COLLECT')
   aFieldOpt := aFieldGroup[1]
   aFieldItems := aFieldGroup[2]
   cAlias := 'COLLECT'
   
   @ 0,0 DCTABPAGE oTabPage1 SIZE 84,18 CAPTION 'Browse' ;
         GOTFOCUS {||oBrowse:RefreshAll()}
   
   @ 0,0 DCTABPAGE oTabPage2 RELATIVE oTabPage1 CAPTION 'Edit' ;
         STATICAREA oTabPage2Static ;
         GOTFOCUS {||DC_RecLock(), ;
                     DC_GetRefresh(GetList)}
   
   @ 2,2 DCBROWSE oBrowse SIZE 80,15 ALIAS 'COLLECT' ;
      PRESENTATION DC_BrowPres() PARENT oTabPage1
   
   FOR i := 1 TO Len(aFieldItems)
   
     bCompile := DC_GetBlock(aFieldItems[i,DCFLD_COMPILE])
     IF Valtype(bCompile) = 'B' .AND. !Eval(bCompile)
       LOOP
     ENDIF
   
     DCBROWSECOL DATA &('{||' + cAlias + '->' + ;
          aFieldItems[i,DCFLD_NAME] + '}') ;
        PARENT oBrowse HEADER aFieldItems[i,DCFLD_DESC] ;
        MESSAGE aFieldItems[i,DCFLD_PROMPT] ;
        PROTECT aFieldItems[i,DCFLD_PROTECT] ;
        WHEN aFieldItems[i,DCFLD_WHEN] ;
        FONT aFieldItems[i,DCFLD_FONT] ;
        HELPCODE aFieldItems[i,DCFLD_HELPCODE]
   
     IF aFieldItems[i,DCFLD_TYPE] = 'M'
       bGetSet := 'MEMO'
       bKeyBlock := {|a,b,o|o:undo()}
       bPopUp := MemoBlock(i,cAlias,aFieldItems[i,DCFLD_DESC])
     ELSE
       bGetSet := DC_FieldWBlock(aFieldItems[i,DCFLD_NAME],cAlias)
       bKeyBlock := nil
       IF !Empty(aFieldItems[i,DCFLD_POPUP])
         bPopUp := aFieldItems[i,DCFLD_POPUP]
       ELSEIF aFieldItems[i,DCFLD_VALTYPE] $ 'TCVD' // table, choice, view,
   datapick
         bPopUp := PopupBlock(i,aFieldItems)
       ELSEIF aFieldItems[i,DCFLD_TYPE] = 'D'
         bPopUp := {|d|DC_PopDate()}
       ELSE
         bPopUp := nil
       ENDIF
     ENDIF
   
     @ i-.5,2 DCSAY aFieldItems[i,DCFLD_DESC] ;
        GET bGetSet ;
        POPUP bPopUp ;
        PARENT oTabPage2Static ;
        KEYBLOCK bKeyBlock ;
        PICTURE aFieldItems[i,DCFLD_PICT] ;
        MESSAGE aFieldItems[i,DCFLD_PROMPT] ;
        EDITPROTECT aFieldItems[i,DCFLD_PROTECT] ;
        WHEN aFieldItems[i,DCFLD_WHEN] ;
        VALID ValidBlock(i, aFieldItems, ;
           aFieldItems[i,DCFLD_VALTYPE],aFieldItems[i,DCFLD_VALID],cAlias) ;
        HELPCODE aFieldItems[i,DCFLD_HELPCODE] ;
        GETFONT aFieldItems[i,DCFLD_FONT]
   
   NEXT
   
   @ 18,0 DCMESSAGEBOX TYPE XBPSTATIC_TYPE_RECESSEDBOX ;
          FONT '12.Arial Bold' COLOR GRA_CLR_DARKBLUE ;
          SIZE 84,1.2
   
   DCGETOPTIONS SAYWIDTH 150 SAYRIGHT AUTORESIZE
   DCREAD GUI FIT ADDBUTTONS MODAL ;
      TITLE aFieldOpt[DCFLDGROUP_DESC] ;
      CLEAREVENTS ;
      OPTIONS GetOptions ;
      EVAL {|o|SetAppWindow(o)}
   
   RETURN nil
   
   * -----------------------------
   
   STATIC FUNCTION MemoBlock( i, cAlias, cDesc )
   
   RETURN {|c,x|x:=(cAlias)->(FieldGet(i)), ;
             x:=DC_MemoBase(x,{,,,,,,,,,,,,,'Editing Memo: ' + cDesc}), ;
             FieldPut(i,x),c}
   
   * -----------------------------
   
   STATIC FUNCTION PopUpBlock( i, aFieldItems )
   
   RETURN {|c|DC_FieldValidate(@c, aFieldItems, i, .t. ),c}
   
   * -----------------------------
   
   STATIC FUNCTION ValidBlock( i, aFieldItems, cValtype, cFormula, cAlias )
   
   IF Empty(cValtype)
     RETURN cFormula
   ENDIF
   
   RETURN {||DC_FieldValidate( (cAlias)->(FieldGet(i)),
             aFieldItems, i ) }
   *
   

Source/Library:

  _DCFLDSV.PRG, DCLIP1.LIB

See Also:

   dc_fieldload()

dc_fieldwblock()

A replacement for FieldWBlock() for debugging

Syntax:

   DC_FieldWBlock( < cFieldName >, ;
                   [< cAlias >] ) - > bGetSet
   

Arguments:

   < cFieldName > is a character string containing the name of the
   field whose data the code block will read or modify.
   
   < cAlias > is a character string containing the alias name for
   the work area holding the field which the code block will
   access.  If this parameter is NIL then the alias of the current
   work area will be used.
   

Description:

   DC_FieldWBlock() is a debugging replacement for the Xbase++
   function FieldWBlock().
   
   The code block function FieldWBlock() creates a code block
   providing (when it is evaluated) read and write access to a
   field in the specified work area. If no value is passed to the
   code block when it is evaluated, the current value from the
   field <þcFieldNameþ> is read and returned. Otherwise, the code
   block writes the passed value into the field and returns this
   new value.
   
   When FieldWBlock() is called, no file needs to be opened in the
   specified work area. However, when the code block is evaluated,
   the file containing the field the code block is accessing must
   be open. If the field <þcFieldNameþ> does not exist when the code
   block is evaluated, a runtime error occurs.
   
   The replacement function DC_FieldWBlock() includes a call to a
   debugging function which echoes call stack information and
   read/write information into a debug window whenever the codeblock
   is evaluated.  Debugging event driven programs that use Get/Set
   codeblocks can be cumbersome.  Often times a Get/Set codeblock
   may be called more times than desired thereby affecting performance.
   This is usually the case when refreshing systems are used. The
   display of debugging info is enabled and/or disabled by the
   DC_FieldWDebug() function.
   

Examples:

   /* In this example, every time the field COLLECT->TYPE
      is updated during cell-editing, information about
      the field will be echoed to the debug window */
   
   FUNCTION Xtest()
   
   LOCAL GetList := {}, oBrowse
   
   USE COLLECT VIA DBFNTX
   DC_FieldWDebug(.t.,'TYPE',.t.)
   
   @ 0,0 DCBROWSE oBrowse ALIAS 'COLLECT' SIZE 50,9 ;
      EDIT xbeBRW_ItemSelected
   
   DCBROWSECOL DATA DC_FieldWBlock( 'descrip', 'collect' ) ;
      PARENT oBrowse WIDTH 20 HEADER 'Description'
   
   DCBROWSECOL DATA DC_FieldWBlock( 'type', 'collect' ) ;
      PARENT oBrowse WIDTH 10 HEADER 'Type'
   
   DCREAD GUI FIT ADDBUTTONS
   
   RETURN nil
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_fieldwdebug()

dc_fieldwdebug()

Enable debug window for Get/Set field code blocks

Syntax:

   DC_FieldWDebug( < lDebugOn >, ;
                   [< cFieldName >], ;
                   [< lWriteOnly >] ) - > lStatus
   

Arguments:

   < lDebugOn > is a logical .TRUE. to turn the debug window ON, a
   logical .FALSE. to turn it OFF.
   
   < cFieldName > is an optional character string.  This is the name
   of a field to debug when there are many code blocks that all
   use DC_FieldWBlock() and you only want to see Get/Set transactions
   that relate to a specific field, otherwise all Get/Set transactions
   will be echoed to the debug window.
   
   < lWriteOnly > is an optional logical value.  Set this to .TRUE.
   if you want to only see Get/Set transactions that write to the
   field.
   

Returns:

   NIL.
   

Description:

   DC_FieldWDebug() is used to establish the debugging mode when
   using DC_FieldWBlock() for creating Get/Set code blocks.
   

Examples:

   /* In this example, every time the field COLLECT->TYPE
      is updated during cell-editing, information about
      the field will be echoed to the debug window */
   
   FUNCTION Xtest()
   
   LOCAL GetList := {}, oBrowse
   
   USE COLLECT VIA DBFNTX
   DC_FieldWDebug(.t.,'TYPE',.t.)
   
   @ 0,0 DCBROWSE oBrowse ALIAS 'COLLECT' SIZE 50,9 ;
      EDIT xbeBRW_ItemSelected
   
   DCBROWSECOL DATA DC_FieldWBlock( 'descrip', 'collect' ) ;
      PARENT oBrowse WIDTH 20 HEADER 'Description'
   
   DCBROWSECOL DATA DC_FieldWBlock( 'type', 'collect' ) ;
      PARENT oBrowse WIDTH 10 HEADER 'Type'
   
   DCREAD GUI FIT ADDBUTTONS
   
   RETURN nil
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_fieldwblock()

dc_filearray()

Capture work area(s) to a file definition array

Syntax:

   DC_FileArray ( [< lAllAreas >] ) - > aFileGroup
   

Arguments:

   < lAllAreas > if .TRUE. (default) will also include all the
   files in all open work areas, otherwise only the files in the
   currently selected area will be returned in the array.
   

Returns:

    An array consisting of three sub-arrays:
   
    Sub-array #1 is an array of two elements: Element #1
    contains the ALIAS() of the current work area and element
    #2 is a null string.
   
    Sub-array #2 is a 2-dimensional array consisting of one
    sub-array for each file, index or relation.  See RETURNS in
    the documentation of DC_FILEEDIT() for a definition of this
    array.
   
    Sub-array #3 is a set of 3 sub-arrays:
    Element #1 is an array containing the current Browse
    configuration of all work areas (DCBROWSE).
    Element #2 is an array containing the current Edit
    configuration of all work areas (DCEDIT).
    Element #3 is an array containing the current Import
    configuration of all work areas (DCIMPORT).
   

Description:

    DC_FILEARRAY() will return a file definition array of
    file information captured from the current work area.  A
    file definition array is used to define files, indexes and
    relations for later restoring the work areas from the
    contents of the array.
   

Examples:

    use customer shared readonly
    set index to custname, custnmbr
    aFileGroup := DC_FILEARRAY()
   

Source/Library:

  _DCFILES.PRG

See Also:

   dc_fileedit()
   dc_filerest()

dc_filecompare()

Compares the contents of two files

Syntax:

   DC_FileCompare( < cFile1 >, < cFile2 > ) - > lStatus
   

Arguments:

   < cFile1 > and < cFile2 > are the full path names of the two
   files
   to compare.
   

Returns:

   A logical .TRUE. if the files are identical, .FALSE. otherwise.
   

Description:

   DC_FileCompare() is used to do a byte by byte comparison of the
   contents of two files.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

dc_filecopy()

Copy or move a set of files to a common location

Syntax:

   DC_FileCopy( < aFile >, ;
                < cToPath >, ;
                < aMessage >, ;
                @< aErrors >, ;
                < lMove > ) - > lStatus
   

Arguments:

   < aFile > is a single-dimensional array of fully-pathed file names.
   
   < cToPath > is the full path of the directory that receives the files.
   
   < aMessage > is a single-dimensional array of message strings to
   display
   in the dialog window.
   
   @< aErrors > is an array that receives error information.
   
   < lMove > if .TRUE. will MOVE the files to the new location, otherwise
   they will be copied.
   

Returns:

   A logical .TRUE. if all files were successfully copied or moved, .FALSE.
   otherwise.
   

Description:

   DC_FileCopy() is used to copy or move a set of files to a common location.
   
   This function displays a dialog window with a progress bar and an option
   to cancel the copy or move.
   
   This function is handy when there are a set of very large files that
   could take a lot of time to copy or move across a network path.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

dc_filedel()

Delete a file group from the DCFILES.DBF dictionary

Syntax:

    DC_FileDel( [< cFileGroup >] ) - > lStatus
   

Arguments:

   < cFileGroup > is the name of the file group in DCFILES.DBF
   to delete (up to 8 characters).
   

Returns:

    A logical .TRUE. if the file group was successfully deleted.
   

Description:

    DC_FileDel() is used to delete a file group from the DCFILES.DBF
    file dictionary.
   

Examples:

    // Delete the file group named JUNK
    DC_FileDel('JUNK')
   

Source/Library:

  _DCFILES.PRG

See Also:

   FILE DELETE
   dc_fileedit()

dc_fileedit()

A Database File / Work area Definition editor

Syntax:

    DC_FileEdit( [< acFileGroup >] ) - > aFileGroup
   

Arguments:

   < acFileGroup > is the name of the file group in DCFILES.DBF
   to load and edit (up to 8 characters) or < acFileGroup > is a
   File Group array.  See RETURNS for a specification of this
   array.  If no parameter is passed, a pick-list of all File
   Groups in DCFILES.DBF will be displayed.
   

Returns:

    An array consisting of 2 sub-arrays:
   
    See DCFILES.CH for the definitions of the array elements.
   
    Sub-array #1 contains general information about this file
    group.
   
    * - Maximum Length allowed, Minimum Length is 0
   
    Element           Type   Len   Description
    -------------     ----   ---   ------------------------------
    DCFILE_GROUPNAME    C      8*  File Group Name
    DCFILE_GROUPDESC    C     50*  File Group Description
    DCFILE_GROUPDEFA    C    100*  Default Directory for files
   
   
   
    Sub-array #2 contains one sub-array for each file, index
    or relation definition.
   
    Element         Type   Len   Description
    -------------   ----   ---   --------------------------------
    DCFILE_TYPE      C       1   Item Type
                                 E - Open Database exclusive
                                 S - Open Database shared
                                 I - Open Index
                                 R - Set a relation
                                 F - Open a File Group
    DCFILE_NAME      C     150*  File Name
    DCFILE_DESC      C      50*  Description of File
    DCFILE_ALIAS     C      10*  Alias Name
    DCFILE_RELALIAS  C      10*  Relational Alias Name
    DCFILE_FIELD1    C      10*  Relational Field
    DCFILE_KEY       C     300*  Index Key Expression
    DCFILE_RECNO     N           Database record to select
    DCFILE_FILTER    C     500*  Database filter expression
    DCFILE_RDD       C      10*  Name of RDD (Data-Driver to use)
    DCFILE_SUPERRDD  C      10*  Name of SUPER RDD (Data-Driver)
    DCFILE_INDEXNO   N           Index Order to select
    DCFILE_TAGNAME   C      10*  Index Tag Name to select
    DCFILE_INDEXFOR  C     500*  Index Condition expression
    DCFILE_DESCEND   L           Descending Index - .T.
    DCFILE_UNIQUE    L           Unique Index - .T.
    DCFILE_ISCDX     L           Combined Index - .T.
    DCFILE_BROWSE    C      10*  Browse Configuration Name
    DCFILE_EDIT      C      10*  Edit (Data-Entry) Configuration
    DCFILE_IMPORT    C      10*  Import Configuration
    DCFILE_DICT      C           Unused (reserved)
   

Description:

    DC_FILEDEDIT() is an editor that maintains the definition of
    each database and it's indexes and relations.
   
    Each file group is stored in the DCFILES.DBF dictionary file.
   
    A file group contains all the information necessary to
    restore work areas for editing and browsing.  The data
    dictionary contains information for opening databases and
    indexes (or creating indexes that do not exist).
   

Examples:

    -- Example 1 --
    // Load a file group from the dictionary and edit it //
    DC_FILEEDIT()
   
    -- Example 2 --
    // Edit file group "CUSTOMER"
    DC_FILEEDIT("CUSTOMER")
   
    -- Example 3 --
    // Edit a file group array //
    aFileGroup := DC_FilePik()
    aFileGroup := DC_FILEEDIT( aFileGroup )
   

Source/Library:

  _DCFILES.PRG

See Also:

   dc_filerest()

dc_fileimp()

Import File Group(s) from the Import File Dictionary

Syntax:

    DC_FileImp ( [< cFileGroup > | "ALL"] ) - > lStatus
   

Arguments:

   < cFileGroup > is the name of the file group.  This is a name of
   up to eight (8) digits.  If a group name is passed then
   the DXFILES.DBF database will be searched and all group
   items that match the group name be imported into DCFILES.DBF.
   If no name is passed, then a pick-list of all file groups stored
   in the DXFILES.DBF database will be displayed.
   
   If "ALL" is passed as the group name, then all groups in the
   DXFILES.DBF will be imported into DCFILES.DBF.
   

Returns:

    A logical .TRUE. if the file group was imported successfully.
   

Description:

    DC_FILEIMP() is used to import file group configurations from a
    DXFILES.DBF file into the DCFILES.DBF file.
   

Notes:

    The DCFILES.DBF file is the data-dictionary database that
    contains all file group configurations.  If this file does not
    exist in your default directory or path then it will be created.
    The DXFILES.DBF file is the data-dictionary database that contains
    all file groups that were exported from another system.
   

Source/Library:

  _DCFILES.PRG

See Also:

   dc_fileedit()
   dc_filerest()

dc_fileload()

Load a file group array from the file dictionary

Syntax:

   DC_FileLoad ( [< cGroupName >], ;
                 [< lCache >], ;
                 [< lWorkFile >] ) - > aFileGroup
   

Arguments:

   < cGroupName > is the name of the file group in DCFILES.DBF
   to load.  If no parameter is passed, a pick-list of all
   file Groups in the DCFILES.DBF dictionary will be displayed.
   
   < lCache > if .TRUE. (default) will save the group to
   a static array so the next time it is requested it will
   be reloaded from the static array (cache) for faster speed.
   If .FALSE. then it will not be save to the cache.
   
   < lWorkFile > if .TRUE. will restore the file group from the
   currently open database rather than the DCFILES.DBF data
   dictionary.  The currently open database must have the same
   structure as DCFILES.DBF.  If .FALSE.(default) then the file
   group is restored from the DCFILES.DBF dictionary.
   

Returns:

    A file group array that conforms to the specifications in
    the RETURNS section of the function DC_FILEEDIT().
   

Description:

    DC_FILELOAD() is used to retrieve a file (work area) group
    from the DCFILES.DBF file group dictionary and store it to an
    array.
   

Examples:

    -- Example 1 --
    /* Restore Work areas from file dictionary */
    DC_FILELOAD( 'CUSTOMER' )
   
    -- Example 2 --
    /* Restore and Edit a file group array //
    cFileGroup := DC_FilePik()
    aFileGroup := DC_FILELOAD( cFileGroup )
    aFileGroup := DC_FileEdit( aFileGroup )
   

Source/Library:

  _DCFILES.PRG

See Also:

   dc_filerest()
   dc_fileedit()

dc_filenamedupe()

Returns the next file name in a series

Syntax:

   DC_FileNameDupe( < cFileName > ) - > cNewFileName
   

Arguments:

   < cFileName > is the fully-pathed file name.
   

Returns:

   A character string.
   

Description:

   DC_FileNameDupe() returns the next file name in a series so multiple
   files of the same name may be saved in the same directory.
   
   This function is used when saving a file name that may already exist.
   
   For example, if a file named C:\Download\test.prg already exists,
   DC_FileNameDupe( "C:\Download\test.prg" ) will return the string:
   "C:\Download\test (1).prg".
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

dc_filepik()

Pick a file (work-area) group from the file dictionary

Syntax:

   DC_FilePik ( [< cTitle >] ) - > cFileGroup
   

Arguments:

   < cTitle > is the title to display on the pick-list box.
   

Returns:

    A character string.
   

Description:

    DC_FILEPIK() is used to pick the name of a file group from
    the File Group (Work Area) dictionary.
   

Examples:

    cFileGroup := DC_FILEPIK()
    IF !Empty(cFileGroup)
      aFileGroup := DC_FileEdit( cFileGroup )
    ENDIF
   

Source/Library:

  _DCFILES.PRG

See Also:

   dc_fileload()
   dc_fileedit()
   dc_filerest()

dc_filerest()

Restore work areas, indexes, relations, from dictionary

Syntax:

   DC_FileRest ( < acFileGroup >, ;
                 [< lAdditive >], ;
                 [< lExclusive >], ;
                 [< cTagName >] ) - > lStatus
   

Arguments:

   < acFileGroup > is the name of a file group in the DCFILES.DBF
   dictionary or an array that conforms to the specifications of
   the array returned by DC_FileEdit().
   
   < lAdditive > is an optional clause which will insure that
   currently used work areas are not affected.  If a database is
   already opened in a work area, it will not be reopened in a new
   work area.  If the < lAdditive > parameter is not passed, then
   all work areas will be closed before restoring the old work.
   
   < lExclusive > if .TRUE. will override the settings in the DCFILES.DBF
   file for the file group and open the files EXCLUSIVE.  If the
   parameter is not passed or is .FALSE., then files will be
   opened in the default mode.
   
   < cTagName > if passed as a character string or numeric value will
   override the tag name or index order in the DCFILES.DBF file
   group.
   

Returns:

    A file group array that conforms to the specifications in
    the RETURNS section of the function DC_FILEEDIT().
   

Description:

    DC_FILEREST() is used to restore a complete work area
    environment from a the DCFILES.DBF data dictionary. This
    function will accomplish the following:
   
     * Re-open all databases, using the required RDD (Replaceable
       Data Driver).
   
     * Open all indexes or rebuild indexes that don't exist or have
       not been properly updated.
   
     * Set parent-child relations.
   
     * Restore record, index and tag pointers.
   
     * Restore browse windows. (optional)
   
     * Restore filters.
   
     * Restore Database environment such as PATH, DEFAULT, UNIQUE,
       etc.
   

Examples:

    use maillist via 'ADSDBE"
    index on zip tag zip
    index on phone tag phones
    use customer via 'ADSDBE' new index custnmbr
    use invoice via 'ADSDBE' new index invoice
    set relation to cust_nmbr into customer
    dc_filesave( nil, nil, .t., 'MYWORK' )
    close all
    DC_FILEREST( 'MYWORK' )
   

Source/Library:

  _DCFILES.PRG

See Also:

   dc_fileload()
   dc_fileedit()

dc_filesave()

Save Work area definition array to dictionary

Syntax:

   dc_filesave ( [< aFileGroup >], ;
                 [< lWorkFile >], ;
                 [< lWorkAreas >], ;
                 [< cFileGroup >] ) - > lStatus
   

Arguments:

   < aFileGroup > is a file group array that conforms to the
   specification of the array returned by DC_FILEEDIT().
   
   < lWorkFile > if .TRUE. will save the file group to the
   currently open database rather than the DCFILES.DBF data
   dictionary.  The currently open database must be empty and
   have the same structure as DCFILES.DBF.  If .FALSE. (default)
   then the file group is saved to the DCFILES.DBF dictionary and
   will overwrite any file group with the same name.
   
   < lWorkAreas > if .TRUE. will save the information about
   currently open workareas rather than a passed array. The
   < aFileGroup > parameter is not needed and will be ignored if
   < lWorkAreas > is .TRUE.  The default is .FALSE.
   
   < cFileGroup > is needed only if < lWorkAreas > is .TRUE. This
   is the name of the file group (up to 8 characters) to assign
   to the file group.
   

Returns:

    A logical .TRUE. if the file group was saved to the dictionary,
    .FALSE. otherwise.
   

Description:

    DC_FILESAVE() is used to save the contents of a file group
    array or the current workareas to the DCFILES.DBF
    data-dictionary.
   

Examples:

    -- Example 1 --
    /* Save Work areas to file dictionary */
    DC_FILESAVE( ,.f.,.t.,'CUSTOMER' )
   
    -- Example 2 --
    /* Edit and Save a file group array //
    cFileGroup := DC_FilePik()
    aFileGroup := DC_FileEdit( cFileGroup )
    DC_FILESAVE( aFileGroup )
   

Source/Library:

  _DCFILES.PRG

See Also:

   dc_fileload()
   dc_fileedit()
   dc_filerest()
   FILE RESTORE

dc_filock()

Lock the current file

Syntax:

    DC_FiLock ( [< nWaitTime >], ;
                [< lDisplayError >] ) - > lStatus
   

Arguments:

   < nWaitTime > is the number of seconds to wait for the system to
   return a lock before returning the status or the error message.
   (0 = wait forever).
   
   < lDisplayError > if .true. will display an operator error
   message if the file cannot be locked. (default) or if .false.
   will not display an error message to the operator.
   

Returns:

    A logical .TRUE. if the file was successfully locked.
   

Description:

    DC_FILOCK() is used to lock the currently selected file before
    attempting to perform database operations that modify the data
    in mulitiple records.
   

Examples:

    use customer
    if DC_FILOCK( 5 )
      replace print_flag with .F. for print_flag
      dc_unlock()
    endif
   

Source/Library:

  _DCLOCK.PRG, DCLIPX.DLL

See Also:

   dc_reclock()

dc_find()

GUI dialog for finding a record using an index

Syntax:

    DC_Find() - > lStatus
   

Arguments:

    None.
   

Returns:

    A logical .TRUE. if a new record was selected.
   

Description:

    DC_FIND() is a high-level function that scans all index keys
    and creates an input screen to allow the user to find
    information by simply typing in the value in the box next to
    the associated index key.  This is a quick method of finding
    information in a database that has multiple index files open or
    multiple index tags in a combined index.
   
    After the user enters in the value next to the referenced
    index, the database is checked to see if more than one record
    matches the entered value.  If duplicates are found, then a
    pick-list of records is displayed to allow the user to choose
    one.
   

Examples:

    . USE EXPRESS VIA FOXCDX INDEX EXPRESS.CDX
    . DC_Find()
   

Source/Library:

  _DCFINDX.PRG, DCLIPX.DLL

See Also:

   dc_hunt()
   FIND

dc_findbrowse()

A browse-window find utility that uses AutoSeek

Syntax:

    DC_FindBrowse( < aFields >, ;
                   [< oParent >], ;
                   [< nRow >], ;
                   [< nCol >], ;
                   [< nWidth >], ;
                   [< nHeight >], ;
                   [< cTitle >], ;
                   [< lAutoSeek >], ;
                   [< lHeaders >],;
                   [< lPixel >], ;
                   [< acbData >], ;
                   [@< nPointer >], ;
                   [< bEval >], ;
                   [< aPres >], ;
                   [< lHorizScroll >], ;
                   [< lVertScroll >], ;
                   [< lExit >], ;
                   [< nSeekDelay >], ;
                   [< cFont >], ;
                   [< lLeftButtonSort >], ;
                   [< bPopUp >], ;
                   [< cSayIndexFont >] ) - > lStatus
   

Arguments:

   
   < aFields > is a multidimensional array that defines the columns
   of data to browse.
   
   Element   Type   Description
   -------   ----- ---------------------------------------------
     [1]       B    Code Block (ex: {||CUSTOMER- >name})
   
     [2]       C    Header (ex: "Customer Name")
   
     [3]       N    Column Width (ex: 10)
   
     [4]       C    Index Name or Tag (ex: "CUSTNAME")
   
     [5]       C    Index Prompt (ex: "Customer Name")
   
     [6]      C/B   Prefix for AutoSeek
   
     [7]       B    Seek string code block. User input buffer
                    is passed to this code block and return
                    value of code block is used for the seek.
                    ex: {|c|Right(Space(7)+Alltrim(cString),7)}
   
     [8]       C    Picture clause.
   
   Note: Only elements 1 and 2 are required.
   
   < oParent > is the Parent window to paint the objects.  If no
   parameter is passed a  modal window will be created.
   
   < nRow > and < nCol > are the starting coordinates from the
   top
   left of the parent window to paint the objects. These are text
   based coordinates which may include decimals.  If no parent
   parameter is passed, these arguments are not needed.
   
   < nWidth > and < nHeight > are the width and height of the
   window
   in text-based coordinates.  The defaults are 65 columns and
   15 rows.
   
   < cTitle > is the title to display in the titlebar area of the
   dialog window.
   
   < lAutoSeek > if .TRUE. (default) will include a GET for the
   user to enter keys to seek automatically.  If .FALSE. then only
   a browse will be displayed.  The prefix value of the selected
   column is inserted before the seek string.  This may be a code
   block or a string.  If it is a code block it must return a string
   when evaluated.
   
   < lHeaders > if .TRUE. (default) will display headers and a
   horizontal scroll bar in the browse.  If .FALSE. no headers or
   horizontal scroll bar will be displayed.
   
   < lPixel > if .TRUE. assumes coordinates are pixel-based, otherwise
   they are text-based.
   
   < acbData > is the data source.  If it is a code block it must
   return an Alias() or an array when evaluated.  If it is an alias
   the database must already be opened.  If it is an array, the
   array must be two-dimensional.
   
   @< nPointer > is a numeric variable (passed by reference) to store
   the array element selected when the user double-clicks on the
   browse or presses ENTER.
   
   < bEval > is a code block to evaluate after the Browse object is
   created and just before invoking the event handler.  The parent
   dialog object and the browse object are passed as parameters:
   {|oDlg,oBrowse|...}
   
   < aPres > is a two-element array of two subarrays.  The first
   element is a Presentation Parameters array that follows the Xbase++
   specification for Browse Presentation parameters.  The second
   element is a two-element array :
   
   { aHeaderFG, aHeaderBG }
   
    < aHeaderFG > and < aHeaderBG > are the foreground and
   background
    colors of the selected column.  This is the column selected by
    the user for sorting or selecting an index.
   
   < lHorizScroll > if .TRUE. (default) will include a horizontal
   scrollbar and allow resizing of columns.
   
   < lVertScroll > if .TRUE. (default) will include a vertical scroll
   bar.
   
   < lExit > if .TRUE. will exit without destroying the dialog window.
   
   < nSeekDelay > is the number of seconds after a key is pressed to
   wait before performing the seek.  This allows a string to be
   typed without performing a seek everytime a key is pressed.
   The default is .1 seconds.
   
   < cFont > is the font compound name of the font to use for the
   browse columns.
   
   < lLeftButtonSort > if .TRUE. will allow the operator to use the
   left mouse button on the column headers to select the sort order,
   otherwise if .FALSE. (default), only the right button will be
   enabled for sorting and the left button will allow for sizing
   the columns.
   
   < bPopUp > is a code block to evaluate.  If this variable is a
   code block, a popup button will be placed to the right of the
   GET used for entering a seek value.  If the user clicks on this
   button or presses CTRL-ENTER while in the GET, the code block
   will be evaluated.  The value in the GET is passed to the code
   block and the value returned by the code block is stuffed back
   into the GET.
   
   < cSayIndexFont > is the font of the Index Name prompt to the right
   of the search window.
   

Description:

   DC_FINDBROWSE() is a utility program that paints a browse
   with user-defined columns and a entry GET for the user to
   enter keyboard characters.  The keys entered will automatically
   seek the selected index and refresh the browse.  The user can
   click the right mouse button on a column heading to select a
   different index.  The Up, Down, Page Up, Page Down, Ctrl Page Up,
   Ctrl Page Down and Enter keys are all enabled while the user
   is in the entry GET to allow the user to navigate the browse
   with keys or the mouse or enter keys for seeking.
   

Examples:

   // Example 1 - Popup a Browse with multiple columns and AutoSeek
   
   FUNCTION XTest()
   
   LOCAL aFields
   
   SET DEFA TO ..\XDOC
   USE EXPRESS VIA FOXCDX EXCLUSIVE ALIAS 'XDOC'
   SET INDEX TO EXPRESS.CDX
   OrdSetFocus('COMMAND')
   SET DEFA TO
   
   aFields := ;
      { ; // field          Header             Width  Index       Prompt
      { {||XDOC->type},     'Type',              8,   "TYPE",     'Type' } ,
   ;
      { {||XDOC->command},  'Command',           8,   'COMMAND',  'Command' },
   ;
      { {||XDOC->category}, 'Category',          8,   'CATEGORY', 'Category'
   }, ;
      { {||XDOC->module},   'Module',            8,   'MODULE',   'Module' },
   ;
      { {||XDOC->SHORT},    'Short Description', 25,   nil,        nil } ;
      }
   
   DC_FindBrowse( aFields, nil, nil, nil, 85, 20, ;
       'Find Record by AutoSeek (Click Right Mouse Button in Header to change
   Index)' )
   
   RETURN nil
   
   
   // Example 2 - Use DC_FindBrowse() for Combo-box style picklists
   
   LOCAL GetList := {}, cType, oType, cCommand, oCommand, cCategory, oCategory
   
   SET DEFA TO ..\XDOC
   USE EXPRESS VIA FOXCDX EXCLUSIVE ALIAS 'XDOC'
   SET INDEX TO EXPRESS.CDX
   OrdSetFocus('COMMAND')
   SET DEFA TO
   
   cType := Space(20)
   @ 1,0 DCSAY 'Type'
   @ 2,0 DCGET cType POPUP {|c|_XTest(1,oType,c)} GETSIZE 20
   @ 3,0 DCSTATIC XBPSTATIC_TYPE_RECESSEDBOX SIZE 20,6 ;
      OBJECT oType EVAL {|o|o:hide()}
   
   cCommand := Space(20)
   @ 1,25 DCSAY 'Command'
   @ 2,25 DCGET cCommand POPUP {|c|_XTest(2,oCommand,c)} GETSIZE 20
   @ 3,25 DCSTATIC XBPSTATIC_TYPE_RECESSEDBOX SIZE 20,6 ;
      OBJECT oCommand EVAL {|o|o:hide()}
   
   cCategory := Space(20)
   @ 1,50 DCSAY 'Category'
   @ 2,50 DCGET cCategory POPUP {|c|_XT est(3,oCategory,c)} GETSIZE 20
   @ 3,50 DCSTATIC XBPSTATIC_TYPE_RECESSEDBOX SIZE 20,6 ;
      OBJECT oCategory EVAL {|o|o:hide()}
   
   DCREAD GUI FIT ADDBUTTONS ;
      TITLE 'Using DC_FindBrowse() for a Database Pick-List (Pull-Down style)'
   
   RETURN nil
   
   /* ----------------------------- */
   
   STATIC FUNCTION _XTest( nMode, oXbp, c )
   
   LOCAL aFields
   
   oXbp:show()
   IF nMode = 1
     OrdSetFocus('TYPE')
     aFields := { { {||XDOC->type}, 'Type', 15, nil, nil } }
   ELSEIF nMode = 2
     OrdSetFocus('COMMAND')
     aFields := { { {||XDOC->command}, 'Command', 15, nil, nil } }
   ELSEIF nMode = 3
     OrdSetFocus('CATEGORY')
     aFields := { { {||XDOC->category}, 'Category', 15, nil, nil } }
   ENDIF
   IF DC_FindBrowse( aFields, oXbp, 0, 0, 20, 6, nil, .f., .f. )
      c := Eval(aFields[1,1])
   ENDIF
   
   oXbp:hide()
   
   RETURN c
   

Source/Library:

  _DCFINDX.PRG, DCLIPX.DLL

See Also:

   dc_browseautoseek()
   @ DCFINDBROWSE
   DCFINDADDCOL
   dc_findbrowsesort()

dc_findbrowsesort()

Set Sort Header options for DC_FindBrowse()

Syntax:

    DC_FindBrowseSort( [< aSortOptions >] ) - > aOldOptions
   

Arguments:

   < aSortOptions > is an array of 7 elements.
   
   Element    Description
   ------- -------------------------------------------------------
    1 / 2  Used to set the foreground and background color of the
           column heading that is chosen as the controlling sort
           order when clicking the mouse in the column heading.
           See the SORT clause of DCBROWSECOL.
   
    3 / 4  Used to set the foreground and background color of the
           column headings that are not the controlling sort order.
   
    5 / 6  Use to set the UP arrow and DOWN arrow bitmaps that are
           used in the column header of the sorted column when
           the order is "ascending" or "descending" respectively.
   
    7      Used to set the color of the box drawn around the SEEK
           Get (default is GRA_CLR_RED).
   

Returns:

   An array containing the old sort options.
   

Description:

   DC_FINDBROWSESORT() is used to set the column heading options
   for DC_FindBrowse() when using the sort feature that is activated
   by clicking in the header column.
   

Examples:

   aSort := Array(6)
   
   aSort[1] := GRA_CLR_WHITE // Sort Selected Color (Foreground)
   aSort[2] := GRA_CLR_RED   // Sort Selected Color (Background)
   aSort[3] := GRA_CLR_WHITE // Sort Unselected Color (Foreground)
   aSort[4] := GRA_CLR_DARKGRAY // Sort Unselected Color (Background)
   aSort[5] := BITMAP_RD_UP_RED  // Sort UP Bitmap
   aSort[6] := BITMAP_RD_DOWN_RED  // Sort DOWN Bitmap
   
   aSaveSort := DC_FindBrowseSort(aSort)
   
   DC_FindBrowse( aFields, nil, nil, nil, 85, 20, ;
       'Find Record by AutoSeek (Click Right Mouse Button in Header to change
   Index)', ;
       nil, nil, nil, nil, nil, nil, { aPres, { GRA_CLR_DARKGRAY, GRA_CLR_RED } },
   ;
       nil, nil, nil, .5 )
   

Source/Library:

  _DCFINDX.PRG, DCLIPX.DLL

See Also:

   dc_findbrowse()
   @ DCFINDBROWSE

dc_fontcompoundname()

Return the Font Compound name from a font object

Syntax:

   DC_FontCompoundName( < oFont > ) - > cCompoundName
   

Arguments:

   < oFont > is an XbpFont() object.
   

Returns:

   A character string.
   

Description:

   DC_FontCompoundName() will build a string containing the
   Compound Name of a font from it's XbpFont() object.
   

Examples:

   FUNCTION XTest()
   
   LOCAL oFont
   
   oFont := XbpFont():new()
   oFont:familyName := 'Arial'
   oFont:nominalPointSize := 12
   oFont:bold := .t.
   oFont:italic := .t.
   oFont:underScore := .t.
   oFont:create()
   
   ? DC_FontCompoundName( oFont )
   
   12.Arial Bold Italic Underscore
   
   oFont:destroy()
   
   RETURN nil
   

Source/Library:

  _DCFONT.PRG, DCLIPX.DLL

See Also:

   dc_fontconfigure()

dc_fontconfigure()

Configure a Font object from a Compound Name

Syntax:

   DC_FontConfigure( < oFont >, ;
                     < cFontCompoundName >, ;
                     [< nCodePage >] ) - > oFont
   

Arguments:

   < oFont > is an XbpFont() object.
   
   < cFontCompoundName > is a character string containing the
   compound name of the font.
   
   Examples:
   
   11.Arial
   12.Courier New
   14.Courier New Bold
   20.Lucida Console Italic Underscore
   
   < nCodePage > is the optional code page of the font to select.
   

Returns:

   The configured font object.
   

Description:

   DC_FontConfigure() will configure a font objects properties
   from a Font Compound name.
   

Examples:

   oFont := GraSetFont(oPS)
   cSaveFont := DC_FontCompoundName(oFont))
   DC_FontConfigure(oFont,'12.Arial Underscore')
   GraSetFont(oPS,oFont)
   GraStringAt('This is some text in "12.Arial Underscore" font')
   DC_FontConfigure(oFont,cSaveFont)
   GraSetFont(oPS,oFont)
   

Source/Library:

  _DCFONT.PRG, DCLIPX.DLl

See Also:

   dc_fontcompoundname()

dc_formatmemotowidth()

Format a memo to fit within a specified area

Syntax:

   DC_FormatMemoToWidth( < cString >, ;
                         < nWidth >, ;
                         < oPS | cFont > ) - > cString
   

Arguments:

   < cString > is the memo to format.
   
   < nWidth > is the width, in pixels.
   
   < oPS > is the presentation space object that contains the font,
   or alternately < cFont > is the font compound name.
   

Returns:

   A character string.
   

Description:

   DC_FormatMemoToWidth() is used to create a memo that fits
   perfectly within a specified area based on the font used.  CR
   characters will be removed and reinserted in the location required
   to format each line to the desired width.
   

Examples:

   Run XDEMO.EXE - Sample Group 6 - Memo Format
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.LIB, DCLIPX.DLL

dc_fornext()

Evaluate a list of expressions in a FOR..NEXT loop

Syntax:

    DC_ForNext ( < nStart >, ;
                 < nEnd >, ;
                [< nStep >], ;
                 < bEval >, ;
                [< bWhile >] ) - > NIL
   

Arguments:

   < nStart > is the starting value to be assigned to a variable
   which will be incremented for each iteration of a FOR...NEXT
   loop.
   
   < nEnd > is the ending value.
   
   The incremental value will be passed to the < bEval > code block
   for each iteration of the loop.
   
   < nStep > is the incremental value.  The default is 1.
   
   < bEval > is a code block to evaluate for each iteration of the
   loop.
   
   < bWhile > is an code block which must evaluate to .true. to
   continue the loop, otherwise the loop will be terminated.
   

Returns:

    Nil.
   

Description:

    DC_FORNEXT() is a "function" replacement for FOR...NEXT loops
    to be used when a function is needed, i.e. for calling via
    macro, code blocks, etc.
   

Examples:

    bEval := { | x | qout(x, sqrt(x) ) }
    bWhile := { || inkey()#27 }
    DC_FORNEXT( 100, 1000, 5, bEval, bWhile )
   

Source/Library:

  _DCEVAL.PRG, DCLIP1.DLL

See Also:

   dc_ifelse()
   dc_docase()
   dc_dowhile()

dc_getactive()

Return the currently active GET object

Syntax:

   DC_GetActive () - > oGet
   

Arguments:

    NONE
   

Returns:

    DC_GETACTIVE() returns the current active Get object within the
    current READ by DC_READMODAL().  If there is no READ active when
    DC_GETACTIVE() is called, it returns NIL.
   

Description:

    DC_GETACTIVE() is an environment function that provides access
    to the active GET object during a READ.  The current active Get
    object is the one with input focus at the time DC_GETACTIVE() is
    called.
   

Notes:

    DC_GETACTIVE() works with DC_READMODAL() in the same way that
    Clipper's GETACTIVE() works with READMODAL().
   

Examples:

    // This code uses a WHEN clause to force control to branch to a
    // special reader function.  Within this function, DC_GETACTIVE()
    // retrieves the active Get object:
   
    GetList := {}
    @ 10, 10 GET x
    @ 11, 10 GET y WHEN MyReader()
    @ 12, 10 GET z
    dc_readmodal( GetList )
   
    // Called just before second get (above)
    // becomes current
    FUNCTION MyReader
    LOCAL objGet               // Active Get holder
    objGet := DC_GETACTIVE()      // Retrieve current
                                  // active Get
    BarCodeRead( objGet )
    RETURN (.F.)               // Causes Get to be
                               // skipped in READ
   

Source/Library:

  _DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()

dc_getactiveinfo()

Return the currently active GET object

Syntax:

    DC_GetActiveInfo( [< oXbp >] ) - > aInfo
   

Arguments:

   < oXbp > is a pointer to any object.  If this parameter is not
   passed or is not an object, then the object in focus is the
   default.
   

Returns:

    A single dimensional array of 4 elements:
   
    Element  Type   Description
    -------  ----   ----------------------------------------
     [1]      C     Variable name associated with object
     [2]      C     Procedure name that object was defined
     [3]      N     Procedure line that object was defined
     [4]      O     A pointer to the object
   

Description:

    DC_GETACTIVEINFO() is an environment function that provides
    access to the active dialog object during a READ GUI.  The
    current active object is the one with input focus at the time
    DC_GETACTIVEINFO() is called.
   

Notes:

    DC_GETACTIVEINFO() works with DC_READGUI() in a similar way
    to the way Xbase++ GETACTIVE() works with READMODAL().
   

Examples:

    . STORE Space(10) TO cGet1, cGet2, cMemo1
    . @ 1,1 DCSAY 'Get 1' GET cGet1
    . @ 2,1 DCSAY 'Get 2' GET cGet2
    . @ 4,1 DCMULTILINE cMemo1 SIZE 30,10
    . DCHOTKEY xbeK_ALT_I ACTION {||DC_MsgBox(DC_GetActiveInfo()}
    . DCREAD GUI FIT ADDBUTTONS
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()

dc_getanchorcb()

Create a codeblock to anchor local variables to the GetList

Syntax:

   DC_GetAnchorCB ( < uVar >, ;
                    [< cType >], ;
                    [< xValue >], ;
                    [< cPicture >] ) - > bAnchor
   

Arguments:

   < uVar > is the local variable.  IF neither the < cType > or
   < xValue > parameters are used, then the code block converts
   a character string to the type of the variable.  This is
   needed by the GUI get system because XbpGet() objects can
   only work with character strings.
   
   < cType > is the type of value the codeblock is expecting
   when it is evaluated.
   
   < xValue > is the value of the variable to return when the
   code block is evaluated.
   
   < cPicture > is an optional picture clause to use with
   numeric or date variables.
   

Returns:

    A Code Block.
   

Description:

    DC_GETANCHORCB() is used to create a code-block that will
    anchor a local variable to a GetList array.  This allows
    a reference to a local variable to be passed to a text or
    GUI reader via a GetList array to be used as a :dataLink
    for Xbase Parts.
   

Examples:

    #command GET <uVar> =>  ;
        AAdd( myGetlist, DC_GETANCHORCB(@<uVar>) )
   
    #command GET <uVar> PICT <cPict> => ;
        AAdd( myGetlist, DC_GETANCHORCB(@<uVar>,,,<cPict>)
   
    #command CHECKBOX <lVar> => ;
        AAdd( myGetlist, DC_GETANCHORCB(@<uVar>,'L')
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()

dc_getbitmap()

Create a bitmap object from any source

Syntax:

   DC_GetBitMap( < xBitMap >, ;
                 [< nType >], ;
                 [< cResType >], ;
                 [< cResFile >], ;
                 [< anScale >], ;
                 [< aAllowIcons >], ;
                 [< aSize >] ) - > xBitMap
   

Arguments:

   < xBitMap > is any of the following variable types:
   
   C - Character.  This is a string that may contain a file name.
   The contents of the string is tested to see if it contains a
   valid .BMP, .JPG or .GIF file.  If it does and the file exists,
   it is loaded to an XbpBitMap() object and the object is returned.
   If it is not a valid .BMP, .JPG or .GIF file, the original string
   passed in (< xBitMap >) is returned.
   
   N - Numeric.  This is a numeric resource that has been linked
   into the executable program.  It is tested to insure that it is
   a valid bitmap resource and then is converted to an XbpBitMap()
   object.  If it is not a valid bitmap resource or < nType > is
   anything other than 0 or XBPSTATIC_TYPE_BITMAP (defined in XBP.CH)
   then the original numeric value passed in (< xBitMap >) is returned.
   
   O - Object.  If < xBitMap > is an XbpBitMap() object, it is returned
   without being modified.
   
   B - Code Block.  If < xBitMap > is a code block, then the code block
   will be evaluated.  The return value must be an objec of the
   XbpBitmap() class.
   
   < cResType > provides support for bitmap resources of type
   BMP, PNG, GIF and JPEG that have been linked into a .RES file to
   be used as the caption.
   
   Example:
   
   < cResType > = 'GIF'
   
   // myres.arc
   USERDEF GIF
   2000 = FILE ".\GIFChart.GIF"
   
   < cResFile > is the name of the .DLL that contains the resource
   stated in the RESTYPE < cResType > clause.  If this parameter
   is not used, then the resource must be in the .EXE.
   
   If < anScale > is a numeric value, then < anScale > is the
   scaling
   factor to use for the new bitmap, based on the original bitmap
   size.  For example, if the original bitmap size is 25x25 pixels
   and < anScale > is 2, then the new bitmap size is 50x50 pixels.
   
   If < anScale > is an array, then it must contain 2 numeric elements,
   the new X size and the new Y size of the bitmap.
   
   Note: For < anScale > to produce a bitmap with a proper color
   palette, it is recommended that the original bitmap be created
   using a 24-bit palette.
   
   < lAllowIcons >, if .T. will return an XbpIcon() object instead
   of an XbpBitmap() object if xBitmap is an icon resource.  The
   default is .F.
   
   < aSize > is a 2-dimensional array of 2 numeric values that will
   set the size of the icon, if < lAllowIcons > is .T.  If
   < aSize >
   is not used, then the size will be determined by the original
   resource size.
   

Returns:

   An XbpBitMap() object.
   

Description:

   DC_GetBitMap() returns an XbpBitMap() object from a variety of
   input sources.
   

Notes:

   If DC_BitMapTransparentColor() has been set to a value, it will
   be applied to the XbpBitMap() object that is returned.
   

Examples:

   DC_BitmapTransparentColor({192,192,192})
   
   @ 137,275 DCSTATIC XBPSTATIC_TYPE_BITMAP OBJECT oRedFlag ;
             ID "RedFlag" SIZE 19,19 PIXEL ;
             TOOLTIP {||IIF(empty(dc_getcargo(oRedFlag)),   ;
                    "No Flags","Flags exist: "+dc_getcargo(oRedFlag))};
             CAPTION {||IIF(empty(aName[cnAlerts]),;
                        DC_GetBitMap(BITMAP_FLAG_2),;
                        DC_GetBitMap(BITMAP_FLAG_1))}
   

Source/Library:

  _DCGETBX.PRG

See Also:

   dc_bitmaptransparentcolor()

dc_getbrowarray()

Get or Store an array pointer from/to Array Browse

Syntax:

    DC_GetBrowArray( < oBrowse >, ;
                     [< aArray >] ) - > aArray
   

Arguments:

   < oBrowse > is a pointer to the browse object created by the
   DCBROWSE command.
   
   < aArray > is a pointer to the new array to browse.
   

Returns:

    A pointer to the current array being browsed.
   

Description:

    DC_GetBrowArray() is used to store a new array pointer to an
    existing array browser when using DCBROWSE to browse an array.
   

Examples:

   FUNCTION XTest()
   
   LOCAL GetList := {}, aDirectory, aFiles, oBrowDirs, oBrowFiles, ;
         nPointer := 1, bItemMarked
   
   aDirectory := Directory('*.','D')
   aFiles := {}
   _Files( aDirectory, aFiles, 1 )
   bItemMarked := {||_Files(aDirectory,aFiles,nPointer,oBrowFiles)}
   
   @ 0,0 DCBROWSE oBrowDirs DATA aDirectory SIZE 30,10 ;
         EVAL {|o|o:itemMarked := DC_MergeBlocks(o:itemMarked,bItemMarked) } ;
         POINTER nPointer ;
         PRESENTATION DC_BrowPres()
   
   DCBROWSECOL DATA {||DC_GetColArray(nil,oBrowDirs)[1]} ;
      HEADER 'Directory' WIDTH 20 PARENT oBrowDirs
   
   @ 0,35 DCBROWSE oBrowFiles DATA aFiles SIZE 30,10 ;
          PRESENTATION DC_BrowPres()
   
   DCBROWSECOL ELEMENT 1 HEADER 'File Name' WIDTH 20 PARENT oBrowFiles
   
   DCREAD GUI FIT ADDBUTTONS TITLE 'One-to-Many Directory Browse'
   
   RETURN nil
   
   * -------------------
   
   STATIC FUNCTION _Files( aDirectory, aFiles, nPointer, oBrowFiles )
   
   LOCAL i, cDirectory, cCurPath := DC_CurPath()
   
   cDirectory := aDirectory[nPointer,1]
   DC_ChDir( cDirectory )
   
   aFiles := Directory( '*.*')
   DC_ChDir( cCurPath )
   
   IF Valtype(oBrowFiles) = 'O'
     DC_GetBrowArray( oBrowFiles, aFiles )
     oBrowFiles:refreshAll()
   ENDIF
   
   RETURN nil
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.DLL

See Also:

   DCBROWSE
   dc_getcolarray()

dc_getcargo()

Get and/or set the cargo of an object

Syntax:

   DC_GetCargo ( < oXbp >, ;
                 [< xCargo >] ) - > xOldCargo
   

Arguments:

   < oXbp > is any object created by a DC* command.
   
   < xCargo > is a variable of any type including multidimensional
   array or code block.
   

Returns:

    The previously store cargo variable.
   

Description:

    DC_GETCARGO() is used to store any type of variable in the :cargo
    container of objects created by DC* commands.
   

Notes:

    All DC* commands use the :cargo container of Xbp*() objects for
    miscellaneous data required for eXPress++ functions.  This
    cargo is always an array of at least 3 elements with element #3
    reserved for user cargo.  DC_GetCargo() is a handy function
    that stores and/or retrieves data from this element.
   

Examples:

    // Store the directory into the DCPUSHBUTTON identifed by
    // it's ID clause as 'OK_BUTTON'
   
    DC_GetCargo( DC_GetObject(GetList,'OK_BUTTON'), Directory() )
   
   
    // Return the cargo
   
    aDirectory := DC_GetCargo( DC_GetObject(GetList,'OK_BUTTON') )
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

dc_getcolarray()

Get Column array information from a DCBROWSE array browse

Syntax:

    DC_GetColArray( [< nElement >], ;
                     < oBrowse >, ;
                     < xValue > ) - > xInfo
   

Arguments:

   If < nElement > is a NIL, then the entire sub-array is returned.
   If < nElement > is a 0, then the numeric value of the sub-array
   is returned, ie the number of the currently selected sub-array
   element.  If < nElement > is a 1 or more, then the contents of
   the currently selected sub-array, element < nElement > is returned.
   
   < oBrowse > is a pointer to the Browse object.
   
   IF < xValue > is passed, then < nElement > must be a 1 or
   greater.
   The element < nElement > of the selected sub-array will be assigned
   the value of < xValue >.
   

Description:

    DC_GetColArray() returns information about the currently selected
    array element of a DCBROWSE object when browsing an array.
   
    This function is necessary when browsing an array and the
    information in a column must be specially formatted in a code
    block.
   

Examples:

   FUNCTION XTest()
   
   /*  ARRAY BROWSER WITH COLORS
   
    This example demonstrates how to control the color of cells in
    an array browser using DCBROWSE.  In this example, the color of
    the SIZE cells is dependent on the size of the file.  The
    function DC_GETCOLARRAY() is used as a pointer into the array
    being browsed.
   
   */
   
   LOCAL GetList := {}, cFileName, oFileName, oDirGroup, aDirectory, i, ;
         aFile, oDirectory, aColors, bColor
   
   cFileName := Space(30)
   
   @ 2,2 DCGET cFileName GETSIZE 43 GETOBJECT oFileName
   
   @ 3.5,2 DCSTATIC XBPSTATIC_TYPE_RECESSEDBOX SIZE 43,13 ;
         OBJECT oDirGroup
   
   aDirectory := Directory()
   FOR i := 1 TO Len(aDirectory)
     ASize(aDirectory[i],5)
     aDirectory[i,5] := .f.
   NEXT
   aFile := aDirectory[1]
   
   
   @ 2,2 DCBROWSE oDirectory PARENT oDirGroup DATA aDirectory ;
         SIZE 297,253 PIXEL ;
         FONT '10.Helv.Bold' ;
         INTO aFile ;
         DATALINK {||cFileName:=aFile[1],oFileName:SetData()} ;
         MARK 5 ;
         MKCOLOR 5, GRA_CLR_WHITE, GRA_CLR_BLUE
   
   aColors := { {GRA_CLR_WHITE,GRA_CLR_DARKRED}, ;
                {GRA_CLR_WHITE,GRA_CLR_DARKBLUE}, ;
                {GRA_CLR_BLACK,GRA_CLR_DARKGREEN}, ;
                {GRA_CLR_BLACK,GRA_CLR_YELLOW} }
   
   bColor := {| nSize, nCase | nSize := DC_GetColArray(2,oDirectory),;
                 nCase := DC_PickCase(nSize,'>=',;
                             {1000000,100000,10000,0}, ;
                             {      1,     2,    3,4} ), aColors[nCase] }
   
   DCBROWSECOL ELEMENT 1 WIDTH 8 HEADER "Name" PARENT oDirectory
   
   DCBROWSECOL ELEMENT 2 WIDTH 5 HEADER "Size" PARENT oDirectory ;
     EVAL { |o|o:colorBlock := bColor }
   
   DCBROWSECOL ELEMENT 3 WIDTH 5 HEADER "Date" PARENT oDirectory
   
   DCBROWSECOL ELEMENT 4 WIDTH 5 HEADER "Time" PARENT oDirectory
   
   DCBROWSECOL ELEMENT 5 WIDTH 4 HEADER "Marked" PARENT oDirectory
   
   DCREAD GUI ;
      FIT ;
      MODAL ;
      BUTTONS DCGUI_BUTTON_OK + DCGUI_BUTTON_CANCEL ;
      TITLE 'Array Browse of Directory'
   
   RETURN nil
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.DLL

See Also:

   @ DCBROWSE
   DCBROWSECOL
   dc_getbrowarray()
   dc_browserow()

dc_getcomboimmediate()

Changes behavior of @ DCGET .. COMBO

Syntax:

   DC_GetComboImmediate( < lSet > ) - > lPreviousSetting
   

Arguments:

   < lSet > is a logical value.
   

Returns:

   A logical value.
   

Description:

   DC_GetComboImmediate() is a Get/Set function that changes the
   behavior of @..DCGET..COMBO.  A .TRUE. setting will cause the
   GET to update every time a new item is selected in the dropdown
   browse.  A .FALSE. setting will cause the GET to update only
   after double-clicking in the browse.
   

Source/Library:

  _DCCLASS.PRG, DCLIPX.DLL

See Also:

   @ DCGET

dc_getcombomode()

Set mouse mode for @..DCGET..COMBO

Syntax:

   DC_GetComboMode( [< nMode >] ) - > nOldMode
   

Arguments:

   < nMode > is a numeric value from the below table:
   
   * - Default
   
    nMode  Description
    ----- ----------------------------------------------------
      0 *  A double click of the mouse selects the item from the
           dropdown picklist.
   
      1    A single click of the mouse selects the item from the
           dropdown picklist.
   

Returns:

   The previous mode setting.
   

Description:

   DC_GetComboMode() is used to set the mouse click mode for
   dropdown windows of the @..DCGET..COMBO  or @..DCSAY..GET..COMBO
   command.
   

Source/Library:

  _dcfindx.prg, dclipx.dll

See Also:

   @ DCSAY
   @ DCGET

dc_getdestroy()

Destroy all objects in the Dialog Getlist

Syntax:

   DC_GetDestroy ( < aGetList >, ;
                   [< acoGroup >], ;
                   [< lRemove >], ;
                   [< lChildrenOnly >] ) - > nil
   

Arguments:

   < aGetList > is an array containing a list of Get objects to
   destroy.  The GetList must a Gui-based Get List compatible
   with DC_ReadGets() or DC_ReadGui().
   
   < acoGroup > is the GetList group or parent object to destroy.
   Each item in the GetList may be assigned a group name via the
   GROUP < acGroup > clause.  If a character value is passed, then
   only the items in the GetList which match < acoGroup > will be
   destroyed.  < acoGroup > may consist of an array of character
   values so that more than one group may be destroyed. If
   < acoGroup > is a NIL then all items in the GetList will be
   destroyed.  If < acoGroup > is an object pointer, then all
   children items of the object will be destroyed.
   
   < lRemove > if .TRUE. will not only destroy objects, but will also
   remove them from the GetList.
   
   < lChildrenOnly > if .TRUE. will remove only the Child objects
   (and their children), of the parent object and not remove the
   parent object.
   

Returns:

    A logical value.
   

Description:

    DC_GETDESTROY() is used to destroy all objects in the Get List.
   
    This function is needed to destroy objects that were added to
    a parent dialog system by DC_READGUI() without destroying any
    current objects in the parent dialog.
   

Examples:

    -- Example 1 --
   
    See XSample_144() in XSAMPLE5.PRG for an example using
    DC_GetDestroy() in conjunction with DC_MergeGetLists().
   
   
    -- Example 2 --
   
    #include 'dcdialog.ch'
   
    PROCEDURE XTest()
   
    LOCAL GetList := {}, GetOptions, cFirst := Space(10), ;
          cLast := Space(10), cPhone := Space(15), oFirst, oDlg, ;
          oPhoneButton
   
    @ 0,0 DCSAY ' Last Name' GET cLast
    @ 2,0 DCSAY 'First Name' GET cFirst SAYOBJECT oFirst
   
    @ 7,0 DCPUSHBUTTON CAPTION 'Phone' ;
      OBJECT oPhoneButton ;
      SIZE 8,1.5 ;
      ACTION {||_GetPhone(oDlg,@cPhone,oFirst,oPhoneButton)}
   
    DCREAD GUI ;
      FIT ;
      PARENT @oDlg ;
      ADDBUTTONS
   
    RETURN
   
    /* --------------------- */
   
    STATIC FUNCTION _GetPhone( oDlg, cPhone, oFirst, oPhoneButton )
   
    LOCAL GetList := {}
   
    @ 2,0 DCSAY " Phone Num" GET cPhone RELATIVE oFirst ;
      PARENT oDlg PICT '999-999-9999'
   
    @ 0,10 DCPUSHBUTTON CAPTION 'Done' ;
      RELATIVE oPhoneButton ;
      SIZE 8,1.5 ;
      ACTION {||DC_GETDESTROY(GetList)}
   
    DCREAD GUI PARENT oDlg EXIT SAVE
   
    RETURN nil
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()

dc_getdevout()

A Replacement for DevPos()/DevOut() when writing @SAY..GETS

Syntax:

   DC_GetDevOut ( < nRow >, ;
                  < nCol >, ;
                  < cExpr >, ;
                  < cColor > ) - > nil
   

Arguments:

   < nRow > is the display row.
   
   < nCol > is the display column.
   
   < cExpr > is the string to display.
   
   < cColor > is the display color for the string.  If no argument
   is passed, the current system color will be used.
   

Returns:

    Nil
   

Description:

    DC_GETDEVOUT() is used in @SAY..GET translations contained
    in DCGET.CH in place of DevPos() and DevOut().  This
    function will not display the prompt on the screen if it
    has been positioned outside the scroll-region coordinates
    pre-set by DC_READBOX() or DC_READWINDOW() and will set
    appropriate static flags for DC_READMODAL() to allow for
    scrolling the prompt in the GET window area.
   

Notes:

    DC_READWINDOW() or DC_READBOX() must be called before
    displaying any SAYS with the @SAY..GET command or with
    DC_GETDEVOUT().
   

Examples:

    #include "dcget.ch"
   
    LOCAL GetList := {}, aData, i
   
    use <cDataFile>
    aData := Array(Fcount())
    FOR i := 1 TO LEN( aData )
      aData[i] := FieldGet(i)
    NEXT
    DC_ReadWindow( { 10, 10, 20, 60 } )
    FOR i := 1 TO LEN(aData)
      DC_GETDEVOUT( i, 12, PadL(Field(i),10), )
      SetPos( Row(), Col()+1 )
      AAdd( GetList,_GET_(aData[i],"aData[i]",,,) )
      DC_GetDisplay( GetList )
      GetList := DC_AddCargo(GetList,-1*i)
      GetList := ;
         DC_AddCargo(GetList,{ 108, { i, 12, PadL(Field(i),10) }})
    NEXT
    DC_ReadModal( GetList,,aReadArea )
    RETURN nil
   

Source/Library:

  _DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readbox()

dc_getdisplay()

Display a GET on the screen if it falls in scroll region

Syntax:

   DC_GetDisplay ( < GetList > ) - > nil
   

Arguments:

   < GetList > is the GET array containing a set of GETS.
   

Returns:

    Nil
   

Description:

    DC_GETDISPLAY() is used in @SAY..GET translations contained
    in DCGET.CH in place of the default display method.  This
    function will not display the GET on the screen if it
    has been positioned outside the scroll-region coordinates
    pre-set by DC_READBOX() or DC_READWINDOW() and will set
    appropriate static flags for DC_READMODAL() to allow for
    scrolling the GET in the pre-established window area.
   

Notes:

    DC_READWINDOW() or DC_READBOX() must be called before
    displaying any GETS with the @SAY..GET command or with
    DC_GETDISPLAY().
   

Examples:

    #include "dcget.ch"
   
    LOCAL GetList := {}, aData, i
   
    use <cDataFile>
    aData := Array(Fcount())
    FOR i := 1 TO LEN( aData )
      aData[i] := FieldGet(i)
    NEXT
    DC_ReadWindow( { 10, 10, 20, 60 } )
    FOR i := 1 TO LEN(aData)
      DC_GetDevOut( i, 12, PadL(Field(i),10), )
      SetPos( Row(), Col()+1 )
      AAdd( GetList,_GET_(aData[i],"aData[i]",,,) )
      DC_GETDISPLAY( GetList )
      GetList := DC_AddCargo(GetList,-1*i)
      GetList := ;
         DC_AddCargo(GetList,{ 108, { i, 12, PadL(Field(i),10) }})
    NEXT
    DC_ReadModal( GetList,,aReadArea )
    RETURN nil
   

Source/Library:

  _DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readbox()

dc_gethelpcode()

Return the Help Code of an object

Syntax:

   DC_GetHelpCode ( < oXbp >, ;
                    [@< aGetList >], ;
                    [@< aGetListItem >] ) - > cHelpCode
   

Arguments:

   < oXbp > is a pointer to any object that was created by DC_ReadGui().
   
   @< aGetList > is a variable, passed by reference, to store a pointer
   to the GetList that is associated with the object.
   
   @< aGetListItem > is a variable, passed by reference, to store a
   pointer to the GetList Item that is associated with the object.
   

Returns:

   A Character String.
   

Description:

    DC_GETHELPCODE() is used to return the Help Code from the
    GetList that is associated with a specified object.  Help Codes
    are associated with objects created by DC* commands by using
    the HELPCODE <þcHelpCodeþ> clause of the command.  Context-Sensitive
    Help systems require that when a Help Request for an object
    does not return a Help Code (because one has not been assigned),
    then the help code of the parent of that object should be
    returned.  DC_GetHelpCode() walks up the tree until it finds a
    Help Code.  If no Help Code is found then the returned value is
    a NIL.
   

Methods:

Examples:

    -- Example 1 --
   
   
    #include 'dcdialog.ch'
   
    PROCEDURE XTest()
   
    LOCAL oStatic, oDate, dDate := Date()
   
    @ 1,1 DCSTATIC TYPE XBPSTATIC_TYPE_RECESSEDBOX SIZE 30,5 ;
          OBJECT oStatic HELPCODE 'MYAPP.STATIC'
   
    @ 2,2 DCSAY 'Date' GET dDate GETOBJECT oDate
   
    @ 7,1 DCPUSHBUTTON CAPTION 'Get Help' SIZE 10 ;
          ACTION {||DC_DebugQout({DC_GetHelpCode(oDate)})}
   
    DCREAD GUI FIT
   
    RETURN nil
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_getproperty()

dc_gethotkeylist()

Retrieve a list of hotkeys that have been set

Syntax:

   DC_GetHotKeyList( [< aGetList >] ) - > aHotKeys
   

Arguments:

   < aGetList > is the GetList for the dialog window which contains
   DCHOTKEY commands or ACCELKEY clauses of DC* commands.  If
   < aGetList > is not passed then an array of information about
   hotkeys created with the SetKey() function is returned.
   

Returns:

    An array with information about the Hotkeys.  Each element of
    the array contains 3 sub-elements:
   
    Element  Type  Description
    -------  ----- ------------------------------------------
       1       C   The character-string definition of the hotkey
       2       N   The numeric value of the hotkey
       3       B   Tha action code block associated with the hotkey
   

Description:

    DC_GETHOTKEYLIST() is used to return an array of HotKeys that
    have been set either by using the DCHOTKEY command, the ACCELKEY
    clause of DC* commands or the SetKey() function.
   

Examples:

   #include "dcdialog.ch"
   #include "appevent.ch"
   #include "inkey.ch"
   
   -- Example 1 --
   
   FUNCTION XTest()
   
   LOCAL GetList[0]
   
   @ 1,1 DCPUSHBUTTON CAPTION 'Test' ACTION {||MsgBox('test T')} ;
         ACCELKEY xbeK_ALT_T
   
   DCHOTKEY xbeK_ALT_Z ACTION {||MsgBox('test Z')}
   
   DCREAD GUI FIT SAVE
   
   DC_ArrayView( DC_GetHotKeyList(GetList) )
   
   RETURN nil
   
   -- Example 2 --
   
   FUNCTION XTest()
   
   SetKey(K_ALT_T,{||MsgBox('test T')})
   SetKEy(K_ALT_Z,{||MsgBox('text Z')})
   
   DC_ArrayView( DC_GetHotKeyList() }
   
   RETURN nil
   

Source/Library:

  _DCPUTK.PRG/.OBJ, DCLIPX.LIB

dc_getiddefault()

Assign a default ID based on field/memvar name

Syntax:

   DC_GetIDDefault( [< cId >], ;
                    [< cVarName >], ;
                    [< cPrefix< ] ) - > cId
   

Arguments:

   < cId > if not empty will be returned as the return value.
   
   < cVarName > if empty will return < cId >.
   < cVarName > if not empty must include an alias - > pointer.
   example: "MYFILE- >MYFIELD"
   
   < cPrefix > is the prefix to put on the returned value.
   

Description:

   DC_GetIDDefault() will return an ID for an object based on the
   name of the variable passed.  It is used in DCDIALOG.CH to
   automatically assign a default ID when getting data that is an
   aliased field.
   
   Example 1 : @..DCGET MYFILE-þ>name
   
   This will assign an ID of GET_MYFILE_NAME
   
   Example 2 : DCBROWSECOL FIELD MYFILE-þ>name
   
   This will assign an ID of COL_MYFILE_NAME
   

Examples:

   DC_GetIDDefault( nil, 'MYFILE->MYFIELD', 'GET_' )
   
   Returns: GET_MYFILE_MYFIELD
   

Source/Library:

  DCLIPX.LIB, DCLIPX.DLL, DCDIALOG.CH

dc_getlistobject()

Return a pointer to the DC_GetList() object from a GetList Array

Syntax:

   DC_GetListObject( aGetList ) - > oGetList
   

Arguments:

   < aGetList > is a GetList array.
   

Returns:

   An object of the class DC_GetList.
   

Description:

   DC_GetListObject() is used to return a pointer to the DC_GetList()
   object.
   

Notes:

   The GetList array must first have been passed to the DCREAD GUI
   command.
   

Examples:

   #include "dcdialog.ch"
   
   FUNCTION Main()
   
   LOCAL GetList[0]
   
   @ 0,0 DCSAY 'Testing'
   
   DCREAD GUI FIT TITLE 'Testing' EVAL {||ShowTitle(GetList)}
   
   RETURN nil
   
   * -----------
   
   STATIC FUNCTION ShowTitle( GetList )
   
   LOCAL oGetList
   
   oGetList := DC_GetListObject( GetList )
   
   DCMSGBOX oGetList:parentDlg:title
   
   RETURN nil
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.DLL

dc_getlisttype()

Return the "define" name of a Get Object from it's type

Syntax:

   DC_GetListType ( < nType > ) - > cType
   

Arguments:

   < nType > is the numeric value stored in element nGETLIST_TYPE
   of each Getlist array object.
   

Returns:

    A Character String.
   

Description:

    DC_GETLISTTYPE() is a handy debugging function to determine
    the manifest name of the defined "type" of object.
   

Examples:

    #include "dcdialog.ch"
    #include "xbp.ch"
   
    FUNCTION XDemo_1 ()
   
    LOCAL GetList := {}, GetOptions, oTabPage1, oTabPage2, oTabPage3,;
          cPlayer, cTeam, cLeague, cPosition, cMemo, dDateAcq,;
          nOrigPrice, nPresValue, nCardNmbr, nYear, cComments, ;
          aLeague, aTeam, aPosition
   
    aLeague := { 'NL','AL','BL','BS' }
   
    aTeam   := { 'Dodgers','Yankees','Reds','Cardinals','Giants',;
                 'Twins','Red Sox','White Sox' }
   
    aPosition := { '1B','2B','3B','SS','P','C','LF','CF','RF','DH' }
   
    /* ---- Tab Page #1 ---- */
   
    @  3,3,15,62 DCTABPAGE oTabPage1 CAPTION 'Player Data'
   
    @  3,2  DCSAY "Player Name" GET cPlayer SAYRIGHT PARENT
            oTabPage1 SAYSIZE 10
   
    @  5,2  DCSAY "Team" SAYRIGHT PARENT oTabPage1 SAYSIZE 8
   
    @  5,11 DCCOMBOBOX cTeam LIST aTeam SIZE 10,6 PARENT oTabPage1
   
    @  5,23 DCSAY "Position" SAYRIGHT PARENT oTabPage1 SAYSIZE 8
   
    @  5,33 DCCOMBOBOX cPosition LIST aPosition SIZE 6,6 PARENT ;
       oTabPage1
   
    @  5,40 DCSAY "League" SAYRIGHT PARENT oTabPage1 SAYSIZE 8
   
    @  5,50 DCCOMBOBOX cLeague LIST aLeague SIZE 4,4 ;
       PARENT oTabPage1
   
   
    DCGETOPTIONS WINDOW HEIGHT 400 ;
                  WINDOW WIDTH 500 ;
                  SAYWIDTH 100
   
   
    /* ---- See output below ---- */
    FOR i := 1 TO LEN(GetList)
      ? i, DC_GETLISTTYPE( GetList[i,nGETLIST_TYPE] )
    NEXT
   
    DC_ReadGui( GetList, 'My BASEBALL CARD Inventory', ;
                GetOptions, .t. )
   
    RETURN nil
   
   
   
    /* ------------------- */
   
    Output Screen:
   
          1 GETLIST_TABPAGE
          2 GETLIST_SAY
          3 GETLIST_GET
          4 GETLIST_SAY
          5 GETLIST_COMBOBOX
          6 GETLIST_SAY
          7 GETLIST_COMBOBOX
          8 GETLIST_SAY
          9 GETLIST_COMBOBOX
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgets()

dc_getlistvalidate()

Validate all objects in GetList

Syntax:

    DC_GetListValidate( < aGetList > ) - > lStatus
   

Arguments:

   < aGetList > is a valid GetList array.
   

Description:

    DC_GETLISTVALIDATE() is used to test all VALID clauses in the
    GetList and set focus to the first object that fails validation.
   

Examples:

   #include 'dcdialog.ch'
   
   FUNCTION XTest()
   
   LOCAL GetList := {}, cFrom := Space(8), cTo := Space(8), ;
         dFrom := CTOD('  /  /    '), dTo := CTOD('  /  /    ')
   
   SET DATE FORMAT TO 'mm/dd/yyyy'
   
   @ 1,0 DCSAY 'From Time:' ;
      GET cFrom ;
      PICTURE '99:99:99' ;
      VALID {|| IIF(!EMPTY(Strtran(cFrom,':','')), .T., ;
                (DC_MsgBox({'From Time cannot be empty.'}), .F.))}
   
   @ 2,0 DCSAY '  To Time:' ;
      GET cTo ;
      PICTURE '99:99:99' ;
      VALID {|| IIF(!EMPTY(StrTran(cTo,':','')), .T., ;
                (DC_MsgBox({'To Time cannot be empty.'}), .F.))}
   
   @ 3,0 DCSAY 'From Date:' ;
      GET dFrom ;
      PICTURE '@D' ;
      VALID {|| IIF(!EMPTY(dFrom), .T., ;
                (DC_MsgBox({'From Date cannot be empty.'}), .F.))}
   
   @ 4,0 DCSAY '  To Date:' ;
      GET dTo ;
      PICTURE '@D' ;
      VALID {|| IIF(!EMPTY(dTo), .T., ;
                (DC_MsgBox({'To Date cannot be empty.'}), .F.))}
   
   @ 6,0 DCPUSHBUTTON CAPTION 'Validate' SIZE 10,2 ;
         ACTION {||DC_GetListValidate(GetList)}
   
   DCREAD GUI FIT ADDBUTTONS
   
   RETURN nil
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.DLL

See Also:

   dc_getvalidate()
   DCGETOPTIONS

dc_getnetname()

Returns the Network name of the workstation

Syntax:

   DC_GetNetName() - > cNetName
   

Arguments:

   None.
   

Returns:

   A character string.
   

Description:

   DC_GetNetName() returns the Network name of the current workstation.
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

dc_getobject()

Return a pointer to an object from an ID name

Syntax:

   DC_GetObject ( < aGetList >, ;
                  < cID > ) - > oObject
   

Arguments:

   < aGetList > is an array containing a list of Get objects to
   refresh.  The GetList may be Dual-Mode Getlist compatible
   with DC_ReadGets() or DC_ReadGui() or a text-based GetList
   compatible with DC_ReadModal().
   
   < cID > is a character string equivalent to the ID assigned to the
   item in the GetList.  This is case-sensitive.
   

Returns:

    A Pointer to the object created by DC_ReadGui() for the item
    in the GetList that matches <þcIdþ>.  IF <þcIdþ> is not found
   in the
    Getlist, then a NIL is returned.
   

Description:

    DC_GETOBJECT() is used to return a pointer to the actual object
    from a GetList ID tag.
   
    This function will scan the GetList array for the GetList item
    which matches the character string ID which was assigned to the
    GetList object.  An ID is assigned via the ID <þidþ> clause for
    each GetList command.  This function eliminates the need to
    assign a memory variable to an object to get a reference to the
    object.
   

Exported Instance Variables:

Methods:

Notes:

Examples:

    -- Example 1 --
   
   
    #include 'dcdialog.ch'
   
    PROCEDURE XTest()
   
    #define cDesc      aLocals[1]
    #define cType      aLocals[2]
    #define cSubType   aLocals[3]
    #define oToolBar   aLocals[4]
   
    LOCAL aLocals[4], GetList := {}, GetOptions
   
    USE COLLECT NEW EXCLUSIVE
   
    LoadFields( aLocals )
   
    @ 5,10 DCSAY 'Description' GET cDesc ;
      GETID 'GET_DESC'
   
    @ 6,10 DCSAY '       Type' GET cType ;
      GETID 'GET_TYPE'
   
    @ 7,10 DCSAY '   Sub-Type' GET cSubType ;
      GETID 'GET_SUBTYPE'
   
   
    DCTOOLBAR oToolBar
   
    DCADDBUTTON CAPTION "Next" PARENT oToolBar ;
      SIZE 9 ;
      ACTION {||TestUpdated(GetList,aLocals),;
                dbSkip(1), ;
                LoadFields(aLocals), ;
                DC_GetRefresh(GetList),;
                DC_GetOrigSet(GetList) }
   
    DCADDBUTTON CAPTION "Prev" PARENT oToolBar ;
      SIZE 9 ;
      ACTION {||TestUpdated(GetList,aLocals),;
                dbSkip(-1), ;
                LoadFields(aLocals), ;
                DC_GetRefresh(GetList),;
                DC_GetOrigSet(GetList) }
   
   
    DCADDBUTTON CAPTION 'Desc' PARENT oToolBar ;
     SIZE 9 ;
     ACTION {||SetAppFocus(DC_GETOBJECT(GetList,'GET_DESC'))}
   
    DCADDBUTTON CAPTION 'Type' PARENT oToolBar ;
     SIZE 9 ;
     ACTION {||SetAppFocus(DC_GETOBJECT(GetList,'GET_TYPE'))}
   
    DCADDBUTTON CAPTION 'SubType' PARENT oToolBar ;
     SIZE 9 ;
     ACTION {||SetAppFocus(DC_GETOBJECT(GetList,'GET_SUBTYPE'))}
   
    DCREAD GUI ;
      FIT ;
      ADDBUTTONS
   
    RETURN
   
    /* ------------- */
   
    STATIC function LoadFields( aLocals )
   
    cDesc    := COLLECT->descrip
    cType    := COLLECT->type
    cSubType := COLLECT->sub_type
   
    RETURN nil
   
    /* ------------- */
   
    STATIC FUNCTION SaveFields( aLocals )
   
    REPLACE COLLECT->descrip  WITH cDesc
    REPLACE COLLECT->type     WITH cType
    REPLACE COLLECT->sub_type WITH cSubType
   
    RETURN nil
   
    /* ------------- */
   
    STATIC FUNCTION TestUpdated ( GetList, aLocals )
   
    IF DC_GETORIGUPDATED( GetList )
      IF DC_MsgBox(,,{'Data has been modified. Save Changes?'},,,,.t.)
        SaveFields( aLocals )
      ENDIF
    ENDIF
    RETURN nil
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_getobjectid()

dc_getobjectid()

Return a the ID of an object

Syntax:

   DC_GetObject ( < oXbp >, ;
                  < aGetList > ) - > cID
   

Arguments:

   < oXbp > is any object that was created using DC* commands.
   
   < aGetList > is an array containing a list of Get objects.
   

Returns:

    A character string.
   

Description:

    DC_GETOBJECTID() is used to return a the ID of an object.
   
    An ID is assigned via the ID <þidþ> clause for  each GetList
    command.
   

Examples:

    -- Example 1 --
   
   
    #include 'dcdialog.ch'
   
    PROCEDURE XTest()
   
   
    @ 1,1 dcpushbutton caption "Test" id 'TEST' size 12,1 action ;
     {|a,b,o|DC_DebugQout(DC_GetObjectID(o,GetList))}
   
    DCREAD GUI FIT
   
    RETURN
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_getobject()

dc_getoptdefault()

Set the Default options for the GUI Reader

Syntax:

    DC_GetOptDefault( [< aGetOptions >] ) - > aDefaultOptions
   

Arguments:

   < aGetOptions > is an optional array of options default options
   to set for the GUI reader.
   
   Element   Type  Default   Description
   -------   ----  --------  ------------------------------------
      1       C     nil      Window Name
      2       C     nil      Window Title
      3       N     24*20    Window Height (pixels)
      4       N     80*7     Window Width (pixels)
      5       N     20       Row Spaces (pixels)
      6       N     nil      Say Width (pixels)
      7       C     nil      Say Font
      8       C     nil      Get Font
      9       N     nil      Get Height (pixels)
     10       A     nil      Added buttons
     11       N     nil      Window Start Row (pixels)
     12       N     nil      Window Start Column (pixels)
     13       N     0        Window Row Offset (pixels)
     14       N     0        Window Column Offset (pixels)
              /* nGETOPT_COLOFFSET */   ;
     15       L     .f.      Design Mode
     16       C     nil      Menu Name
     17       L     .f.      Pixel Mode
     18       X     nil      Spare
     19       N     1        Window Icon (resource number)
     20       L     .f.      Logical Gets are Checkboxes
     21       C     ''       Help File Name
     22       L     .f.      Objects are visible
     23       L     .t.      Translate text coordinates
     24       L     .t.      Says are Right Justified
     25       N     nil      Window BitMap (resource number)
     26       A     nil      Presentation Parameters
     27       N     nil      Background color of Window
     28       N     nil      Say Option (text justification)
     29       B     nil      Evaluation Code Block
     30       N     nil      Modal State
     31       N     nil      Says Height (pixels)
     32       L     nil      Minimize Button
     33       L     nil      Maximize Button
     34       L     .f.      Tab Stops
     35       A   {.f.,nil}  Abort Query Option
     36       N     20       Row Pixels
     37       N     7.0      Column Pixels
     38       L     .t.      Enable Escape Key
     39       C     ''       Source Code File
     40       A   { 1,0 }    ToolTip Color, ForeGround/BackGround
     41       N     nil      Border
     42       L     .f.      Validate on Exit
     43       A   {.f.,nil}  Close Query Option
     44       L    .f.       No Task List
     45       N     nil      Window Minimum Size
     46       N     nil      Window Maximum Size
     47       L     .f.      No Window Resize
     48       L     .f.      No Window Title bar
     49       L     .f.      No Window Move with owner
     50       N     0        Window Origin
     51       N     0        Hilite Gets Color
     52       L    .t.       Supervise Gets
     53       L    .f.       Hide Window
     54       L    .f.       No Busy Pointer
     55       C    ''        Busy Message
     56       N    327748    Dot Prompt Hot Key
     57       L    .f.       Cascade Windows
     58       L    .f.       AutoResize
     59       A    nil       Color Gets, ForeGround/BackGround
     60       L    .t.       Confirm
     61       N    10        Fitpad (pixels)
     62       N     0        Button Alignment
     63       A   {.f.,nil}  Exit Query
     64       N    nil       Disable Color (BackGround)
   

Returns:

    An array.
   

Description:

    DC_GetOptDefault() is used to set the default options for the
    GUI reader.  An array of information is passed to the function
    with the default values.
   

Notes:

   See DCGETOPTIONS for a description of each option.
   

Examples:

   FUNCTION X_test()
   
   LOCAL GetOptions
   
   DCGETOPTIONS ;
     ROWSPACE 15 ;
     ROWPIXELS 15 ;
     COLPIXELS 6.5 ;
     NOESCAPEKEY ;
     HILITEGETS GRA_CLR_RED ;
     TABSTOP
   
   DC_GetOptDefault( GetOptions )
   
   RETURN nil
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   DCGETOPTIONS

dc_getorigset()

Set the original values of the Dialog items in the Getlist

Syntax:

   DC_GetOrigSet ( < aGetList >, ;
                   [< ancGroup >] ) - > nil
   

Arguments:

   < aGetList > is an array containing a list of Get objects to
   refresh.  The GetList must a Gui-based Get List compatible
   with DC_ReadGets() or DC_ReadGui().
   
   < ancGroup > is the GetList group to set.  Each item in the
   GetList may be assigned a group name or number via the
   GROUP < ancGroup > clause.  If a numeric or character value is
   passed, then only the items in the GetList which match < ancGroup >
   will be set.  < ancGroup > may consist of an array of numeric values
   or character values so that more than one group may be set.
   If < ancGroup > is a nil then all items in the GetList will be
   set.
   

Returns:

    A logical value.
   

Description:

    DC_GETORIGSET() is used to store the current value of all
    the GETS in the GUI Getlist to the ORIGINAL value element of
    each Getlist array object.  The original value is then tested
    against the current value with DC_GETORIGUPDATED() to test
    whether or not any values referenced in the Getlist have
    changed or been updated.
   

Examples:

    #define cPlayer    aLocals[1]
    #define cTeam      aLocals[2]
    #define cLeague    aLocals[3]
    #define oToolBar   aLocals[4]
   
    LOCAL aLocals[4], GetList := {}
   
    USE BASEBALL
   
    LoadFields( aLocals )
   
    @ 10,10 SAY 'Player Name' GET cPlayer
    @ 12,10 SAY '  Team Name' GET cTeam
    @ 14,10 SAY 'League Name' GET cLeague
   
    DCTOOLBAR oToolBar
   
    DCADDBUTTON "Next" PARENT oToolBar ;
       ACTION {||TestUpdated(GetList,aLocals),;
                 dbSkip(1),
                 LoadFields(aLocals),
                 DC_GetRefresh(GetList),;
                 DC_GETORIGSET(GetList) }
   
    DCADDBUTTON "Prev" PARENT oToolBar ;
       ACTION {||TestUpdated(GetList,aLocals),;
                 dbSkip(-1),
                 LoadFields(aLocals),
                 DC_GetRefresh(GetList),;
                 DC_GETORIGSET(GetList) }
   
    DC_ReadGets(Getlist)
   
    /* ------------- */
   
    STATIC function LoadFields( aLocals )
   
    cPlayer := BASEBALL->player
    cTeam   := BASEBALL->team
    cLeague := BASEBALL->league
   
    RETURN nil
   
    /* ------------- */
   
    STATIC FUNCTION SaveFields( aLocals )
   
    REPLACE BASEBALL->player WITH cPlayer
    REPLACE BASEBALL->team   WITH cTeam
    REPLACE BASEBALL->league WITH cLeague
   
    RETURN nil
   
    /* ------------- */
   
    STATIC FUNCTION TestUpdated ( GetList, aLocals )
   
    IF DC_GetOrigUpdated( GetList )
      IF DC_MsgBox(,,{"Data has been modified. Save Changes?'},,,,.t.)
        SaveFields( aLocals )
      ENDIF
    ENDIF
    RETURN nil
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_getorigset()
   dc_getrefresh()

dc_getorigupdated()

Test the original values of the Dialog items in the Getlist

Syntax:

   DC_GetOrigUpdated ( < aGetList >,  ;
                       [< cID > | < nItem >], ;
                       [< ancGroup >], ;
                       [< lVerbose >] ) - > lStatus
   

Arguments:

   < aGetList > is an array containing a list of Get objects to
   refresh.  The GetList must a Gui-based Get List compatible
   with DC_ReadGets() or DC_ReadGui().
   
   < cID > is the ID of the GET object.  This is the ID that was
   assigned with the ID < cId > argument of the command that added
   the object to the GetList.
   
   < nItem > is the item number in the GetList.  If no < cId > or
   < nItem > argument is passed, then the entire GetList will be
   tested, otherwise only the specified ID or ITEM will be
   tested.
   
   < ancGroup > is the GetList group to test.  Each item in the
   GetList may be assigned a group name or number via the
   GROUP < ancGroup > clause.  If a numeric or character value is
   passed, then only the items in the GetList which match < ancGroup >
   will be tested.  < ancGroup > may consist of an array of numeric
   values or character values so that more than one group may be
   tested. If < ancGroup > is a nil then all items in the GetList will
   be tested.
   
   < lVerbose > if .TRUE. will display a message window about which
   item of the GetList has been updated.  This helps in debugging.
   The default is .FALSE.
   

Returns:

    A logical value.
   

Description:

    DC_GETORIGUPDATED() is used to test the current value of all
    the GETS or a specified GET in the GUI Getlist to the ORIGINAL
    value element of the Getlist array object.  If the current value
    of the GET is not equal to the original value, the function returns
    a .TRUE.   If the current value of the GET equals the original
    value, the function returns a .FALSE.
   

Examples:

    #include 'dcdialog.ch'
   
    PROCEDURE XTest()
   
    #define cDesc      aLocals[1]
    #define cType      aLocals[2]
    #define cSubType   aLocals[3]
    #define oToolBar   aLocals[4]
   
    LOCAL aLocals[4], GetList := {}, GetOptions
   
    USE COLLECT NEW EXCLUSIVE
   
    LoadFields( aLocals )
   
    @ 5,10 DCSAY 'Description' GET cDesc
    @ 6,10 DCSAY '       Type' GET cType
    @ 7,10 DCSAY '   Sub-Type' GET cSubType
   
    DCTOOLBAR oToolBar
   
    DCADDBUTTON CAPTION "Next" PARENT oToolBar ;
      SIZE 9 ;
      ACTION {||TestUpdated(GetList,aLocals),;
                dbSkip(1), ;
                LoadFields(aLocals), ;
                DC_GetRefresh(GetList),;
                DC_GetOrigSet(GetList) }
   
    DCADDBUTTON CAPTION "Prev" PARENT oToolBar ;
      SIZE 9 ;
      ACTION {||TestUpdated(GetList,aLocals),;
                dbSkip(-1), ;
                LoadFields(aLocals), ;
                DC_GetRefresh(GetList),;
                DC_GetOrigSet(GetList) }
   
    DCGETOPTIONS ;
      WINDOW WIDTH 300 ;
      WINDOW HEIGHT 300
   
    DCREAD GUI ;
      FIT ;
      OPTIONS GetOptions ;
      ADDBUTTONS
   
    RETURN
   
    /* ------------- */
   
    STATIC function LoadFields( aLocals )
   
    cDesc    := COLLECT->descrip
    cType    := COLLECT->type
    cSubType := COLLECT->sub_type
   
    RETURN nil
   
    /* ------------- */
   
    STATIC FUNCTION SaveFields( aLocals )
   
    REPLACE COLLECT->descrip  WITH cDesc
    REPLACE COLLECT->type     WITH cType
    REPLACE COLLECT->sub_type WITH cSubType
   
    RETURN nil
   
    /* ------------- */
   
    STATIC FUNCTION TestUpdated ( GetList, aLocals )
   
    IF DC_GETORIGUPDATED( GetList )
      IF DC_MsgBox(,,{'Data has been modified. Save Changes?'},,,,.t.)
        SaveFields( aLocals )
      ENDIF
    ENDIF
    RETURN nil
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_getorigset()
   dc_getrefresh()

dc_getpopupautohide()

A Get-Set function for hiding un-focused POPUP buttons

Syntax:

   DC_GetPopupAutoHide( [< lSetting >] ) - > lOldSetting
   

Arguments:

   < lSetting > if .TRUE. will cause POPUP buttons that are attached
   to @..DCSAY..GET objects via the POPUP clause, to be hidden
   whenever any associated EDITPROTECT codeblock evaluates .TRUE.
   The default is .FALSE.  The default behavior is to disable the
   button from activation.
   

Returns:

    The previous setting.
   

Description:

   DC_GetPopupAutoHide() is a Get-Set function used to hide
   @..DCSAY..GET..POPUP buttons until the associated GET receives
   focus.
   

Examples:

   For a functionality equivalent to Microsoft's Outlook Contact
   Manager, include the following at the start of your application:
   
   DC_GetPopupCaption({ '', BITMAP_PENCIL_S, 0 })
   DC_GetPopupAutoHide(.t.)
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   @ DCSAY GET

dc_getpopupcaption()

Set the default caption for the POPUP pushbutton

Syntax:

   DC_GetPopupCaption( [< aCaption >] ) - > aOldCaption
   

Arguments:

   < aCaption > is an array of six elements:
   
   1. The font of the caption.  This must be a standard compound
      font name.
   
   2. A character string or Bitmap resource for the caption.  If
      it is a numeric value, the resource must be linked into the
      .EXE.
   
   3. A numeric value defining the style of popup button.
   
      0 - Create the button on the same parent as the GET.  The
          height and width is the same as the height of the GET.
          The button is placed behind the GET. (DEFAULT).
   
      1 - Create the button within the GET object at the end of
          the GET.  This is visually identical to a button in
          a combobox.
   
   4. A numeric value (in pixels) equivalent to the default width
      of the button
   
   5. A numeric value (in pixels) equivalent to the default height
      of the button
   
   6. A numeric value for the Hot-Key to use to invoke the button
      when the associated GET has focus.  Keys are defined in
      APPEVENT.CH are are prefixed with xbeK_.
   

Returns:

    The previous setting of the font and caption.
   

Description:

    DC_GETPOPUPCAPTION() is used to change the default caption for
    the POPUP pushbutton which is used with the POPUP clause of
    the @ DCSAY..GET and @ DCGET commands.  The caption defaults
    to three dots.
   

Exported Instance Variables:

Notes:

Examples:

   #include "DCBITMAP.CH"
   
   FUNCTION XTest()
   
   LOCAL GetList := {}, dDate := Date(), xCaption
   
   DC_GETPOPUPCAPTION( { '10.Marlett', 'u' } ) // down arrow
   
   @ 1,1 DCSAY 'Enter Date ' GET dDate POPUP {|d|DC_PopDate(d)}
   
   DCREAD GUI FIT ADDBUTTONS
   
   RETURN dDate
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   @ DCSAY GET

dc_getpopupprotecthide()

A Get-Set function for hiding protected POPUP buttons

Syntax:

   DC_GetPopupProtectHide( [< lSetting >] ) - > lOldSetting
   

Arguments:

   < lSetting > if .TRUE. will cause POPUP buttons that are attached
   to @..DCSAY..GET objects via the POPUP clause, to be hidden
   whenever any associated EDITPROTECT codeblock evaluates .TRUE.
   The default is .FALSE.  The default behavior is to disable the
   button from activation.
   

Returns:

    The previous setting.
   

Description:

   DC_GetPopupProtectHide() is a Get-Set function used to hide
   @..DCSAY..GET..POPUP buttons when the EDITPROTECT codeblock
   evaluates .TRUE.
   

Examples:

   FUNCTION XTest()
   
   LOCAL GetList := {}, dDate := Date(), lEditMode := .f.
   
   DC_GETPOPUPPROTECTHIDE( .t. )
   
   @ 1,1 DCSAY 'Enter Date ' GET dDate POPUP {|d|DC_PopDate(d)} ;
     EDITPROTECT {||!lEditMode}
   
   DCREAD GUI FIT ADDBUTTONS
   
   RETURN dDate
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   @ DCSAY GET

dc_getprogress()

Update a Progress bar object

Syntax:

   DC_GetProgress ( < oProgress >, ;
                    < nCurrCount >, ;
                    < nMaxCount >, ;
                    < nEvery > ) - > .T.
   

Arguments:

   < oProgress > is the Progress bar object created by the
   @..DCPROGRESS command.
   
   < nCurrCount > is the current count.  For example, when updating
   a progress bar while copying records, this would be RecNo().
   
   < nMaxCount > is the maximum count.  For example, when updating a
   progress bar while copying records, this would be RecCount().
   
   < nEvery > is the number of records that are traversed before the
   progress bar is updated.
   

Returns:

    A logical .TRUE.
   

Description:

    DC_GETPROGRESS() is used in conjunction with @..DCPROGRESS to
    display a progress bar any type of operation.  The progress bar
    will fill in the specified area with a graphic progress bar.
   

Examples:

    #include 'dcdialog.ch'
    #include 'gra.ch'
   
    PROCEDURE XTest()
   
    LOCAL Getlist := {}, oProgress, oDialog
   
    USE customer
   
    DC_Gui(.t.)
   
    @ 2,5 DCSAY 'Exporting Data to JUNK.DBF'
   
    @ 4,5 DCPROGRESS oProgress ;
          SIZE 60,1.5 ;
          MAXCOUNT RecCount() COLOR GRA_CLR_BLUE
   
    DCREAD GUI TITLE 'My Test Dialog' ;
      PARENT @oDialog ;
      FIT ;
      EXIT
   
    oDialog:show()
   
    COPY TO junk WHILE DC_GetProgress( oProgress, RecNo() )
   
    DC_MsgBox('Done')
   
    oDialog:Destroy()
   
    RETURN
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   @ DCPROGRESS
   dc_progress
   dc_working

dc_getproperty()

Return the value of a Getlist property from an object

Syntax:

   DC_GetProperty ( < oXbp >, ;
                    < nProperty >, ;
                    [@< aGetList >], ;
                    [@< aGetListItem >], ;
                    [@< nPointer >] ) - > xValue
   

Arguments:

   < oXbp > is a pointer to any object that was created by DC_ReadGui().
   
   < nProperty > is a numeric value defined in DCDIALOG.CH.  See
   DIALOG GETLIST for a definition of these manifest constants.
   
   @< aGetList > is a variable, passed by reference, to store a pointer
   to the GetList that is associated with the object.
   
   @< aGetListItem > is a variable, passed by reference, to store a
   pointer to the GetList Item that is associated with the object.
   
   @< nPointer > is a variable, passed by reference, to store the
   numeric position (array element #) of this item in the GetList.
   

Returns:

   A value from the Getlist associated with the object and property
   index.
   

Description:

    DC_GETPROPERTY() is used to return a specified property from
    the GetList that is associated with a specified object.
   

Exported Instance Variables:

Methods:

Notes:

Examples:

    -- Example 1 --
   
   
    #include 'dcdialog.ch'
   
    PROCEDURE XTest()
   
    @ 1,1 DCPUSHBUTTON CAPTION 'Testing' SIZE 10,1 ;
          ACTION {|o|GetCaption(o)}
   
    DCREAD GUI FIT ADDBUTTONS
   
    RETURN nil
   
    * -------------
   
    STATIC FUNCTION GetCaption( oXbp )
   
    ? DC_GetProperty( oXbp, cGETLIST_CAPTION )
   
    RETURN nil
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setproperty()
   dc_getobject()
   DIALOG GETLIST

dc_getreadinsert()

a Get-Set function for establishing default Insert mode

Syntax:

   DC_GetReadInsert( [< nInsertMode >] ) - >
   < nOldInsertMode >
   

Arguments:

   < nInsertMode > will set the insert mode based on the following table:
   
   nMode   Description
   -----   -------------------------------------------
     2     Set Insert Mode ON
     1     Set Insert Mode OFF (Overstrike ON)
     0     Do not change Insert/Overstrike mode
     .T.   Set Insert Mode ON (compatability with build 232)
     .F.   Set Insert Mode OFF (compatability with build 232)
   

Returns:

   A logical value.
   

Description:

   DC_GetReadInsert() is a Get/Set function used to set the default
   Insert mode when entering a new dialog.
   

Examples:

   @ 1,1 DCGET dDate
   DC_GetReadInsertMode(.f.) // set overstrike mode
   DCREAD GUI FIT
   

Source/Library:

  _DCXBPGT.PRG

dc_getrefresh()

Refresh the display of all objects in the Get List

Syntax:

   DC_GetRefresh ( < aGetList|oXbp >, ;
                   [< nElement > | < cID > ], ;
                   [< nRefreshMode >], ;
                   [< aRefreshList >], ;
                   [< ancGroup >], ;
                   [< lDataLink >], ;
                   [< lInvisible >] ) - > nil
   

Arguments:

   < aGetList|oXbp > is an array containing a list of Get objects to
   refresh.  The GetList may be Dual-Mode Getlist compatible
   with DC_ReadGets() or DC_ReadGui() or a text-based GetList
   compatible with DC_ReadModal().  Alternatively, it may be a pointer
   to an Xbase++ object.  If it is an object, then the remaining
   parameters are ignored.  If it is an object, then all objects
   that are also descendents of < oXbp > will also be refreshed.
   
   The second parameter may be a numeric value, a character string,
   or a NIL.  If it is a numeric value, then < nElement > is a
   specific GetList element to refresh.  This must be a number from
   1 to the Length of < aGetList >. If it is a character string, then
   < cID > is a character string equal to the ID of the GetList element
   to refresh. If no parameter is passed then the entire Getlist will
   be refreshed.
   
   < nRefreshMode > and < aRefreshList > are used together to
   refresh
   the Getlist based on the Refresh Mode < nRefreshMode > and the
   contents of < aRefreshList >.  These parameters can be used to
   refresh all items in the Getlist "except" a specified list
   or only those in a specified list.  < aRefreshList > is an array
   of Character strings matching the cGETLIST_ID element of the
   GetList if < nRefreshMode > is DCGETREFRESH_ID_* -or-
   < aRefreshList >
   is an array of Numeric values matching the nGETLIST_TYPE of the
   GetList if < nRefreshMode > is DCGETREFRESH_TYPE_*.
   
   < nRefreshMode >               Description
   ---------------              ---------------------------------------
   DCGETREFRESH_ID_INCLUDE      Refresh only the items with IDs that
                                are included in < aRefreshList >.
   
   DCGETREFRESH_ID_EXCLUDE      Refresh all items with IDs that are
                                NOT included in < aRefreshList >.
   
   DCGETREFRESH_TYPE_INCLUDE    Refresh only the items with TYPEs that
                                are included in < aRefreshList >.
   
   DCGETREFRESH_TYPE_EXCLUDE    Refresh all items with TYPEs that are
                                NOT included in < aRefreshList >.
   
   < ancGroup > is the GetList group to refresh.  Each item in the
   GetList may be assigned a group name or number via the
   GROUP < ancGroup > clause.  If a numeric or character value is passed
   then only the items in the GetList which match < ancGroup > will be
   refreshed.  < ancGroup > may consist of an array of numeric values
   or character values so that more than one group may be refreshed.
   If < ancGroup > is a nil then all items in the GetList will be
   refreshed.
   
   If < lDataLink > is .TRUE. (default) any code blocks associated
   with the DATALINK clause of DC* commands will also be evaluated
   when the associated object is refreshed.  If < lDataLink > is
   .FALSE. then the DATALINK code block is ignored during refresh.
   
   If < lInvisible > is .TRUE. (default) any object that is not
   visible, ie, oXbp:isVisible() returns a false, will be refreshed.
   If < lInvisible > is .FALSE. invisible objects will not be refreshed.
   NOTE: Objects are considered invisible if they are hidden or if
   they are on tabpages that are minimimized.  Setting < lInvisible >
   to .FALSE. can improved performance on applications with many
   objects and many tabpages.
   

Returns:

    .TRUE. if any gets were updated, .FALSE. otherwise.
   

Description:

    DC_GETREFRESH() is used to refresh all the objects in the
    GetList array that have a datalink via a codeblock.  Use
    this function to update the dialogue screen after changing
    the value of one of the variables via a button action or
    in your custom event handler.
   
    DC_GetRefreshBlock() is a Get-Set function that is used to post
    a code block to call every time DC_GetRefresh() is called. This
    may be used to help debug problems with refreshing.
   

Notes:

   DC_GetRefresh() will not refresh DCGRA* items, such as @ DCGRABOX,
   @ DCGRASTRING or @ DCSAY..GRASTRING.  Use the function
   DC_PaintGraControls().
   

Examples:

    -- Example 1 --
   
    #include 'dcdialog.ch'
   
    PROCEDURE XTest()
   
    #define cDesc      aLocals[1]
    #define cType      aLocals[2]
    #define cSubType   aLocals[3]
    #define oToolBar   aLocals[4]
   
    LOCAL aLocals[4], GetList := {}, GetOptions
   
    USE COLLECT NEW EXCLUSIVE
   
    LoadFields( aLocals )
   
    @ 5,10 DCSAY 'Description' GET cDesc
    @ 6,10 DCSAY '       Type' GET cType
    @ 7,10 DCSAY '   Sub-Type' GET cSubType
   
    DCTOOLBAR oToolBar
   
    DCADDBUTTON CAPTION "Next" PARENT oToolBar ;
      SIZE 9 ;
      ACTION {||TestUpdated(GetList,aLocals),;
                dbSkip(1), ;
                LoadFields(aLocals), ;
                DC_GetRefresh(GetList),;
                DC_GetOrigSet(GetList) }
   
    DCADDBUTTON CAPTION "Prev" PARENT oToolBar ;
      SIZE 9 ;
      ACTION {||TestUpdated(GetList,aLocals),;
                dbSkip(-1), ;
                LoadFields(aLocals), ;
                DC_GetRefresh(GetList),;
                DC_GetOrigSet(GetList) }
   
    DCGETOPTIONS ;
      WINDOW WIDTH 300 ;
      WINDOW HEIGHT 300
   
    DCREAD GUI ;
      FIT ;
      OPTIONS GetOptions ;
      ADDBUTTONS
   
    RETURN
   
    /* ------------- */
   
    STATIC function LoadFields( aLocals )
   
    cDesc    := COLLECT->descrip
    cType    := COLLECT->type
    cSubType := COLLECT->sub_type
   
    RETURN nil
   
    /* ------------- */
   
    STATIC FUNCTION SaveFields( aLocals )
   
    REPLACE COLLECT->descrip  WITH cDesc
    REPLACE COLLECT->type     WITH cType
    REPLACE COLLECT->sub_type WITH cSubType
   
    RETURN nil
   
    /* ------------- */
   
    STATIC FUNCTION TestUpdated ( GetList, aLocals )
   
    IF DC_GETORIGUPDATED( GetList )
      IF DC_MsgBox(,,{'Data has been modified. Save Changes?'},,,,.t.)
        SaveFields( aLocals )
      ENDIF
    ENDIF
    RETURN nil
   
   
   
    -- Example 2 ---
   
    /* This example refreshes all items in the Getlist except
       GETLIST_BROWSE type objects.  It is not always necessary to
       refresh BROWSE objects and it can slow the system when
       refreshing Browses often. */
   
    #include 'dcdialog.ch'
   
    DC_GETREFRESH( aGetList, nil, ;
                   DCGETREFRESH_TYPE_EXCLUDE, ;
                   {GETLIST_BROWSE} )
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_getrefreshblock()
   dc_readgui()
   dc_getwhen()

dc_getrefreshblock()

Post a code block for debugging DC_GetRefresh() problems

Syntax:

   DC_GetRefreshBlock( < bBlock > ) - > bOldBlock
   

Arguments:

   < bBlock > is a code block to evaluate inside the DC_GetRefresh()
   function.
   
   The first 5 parameters that are passed to DC_GetRefresh() are
   also passed to the code block:
   
   
   < aGetList >, < nElement >, < nRefreshMode >,
   < aRefreshList >, < acGroup >
   

Description:

   DC_GetRefreshBlock() is used to help in debugging DC_GetRefresh()
   calls.
   
   This is a handy function to determine where in the application
   code, DC_GetRefresh() is being called.  Often times, it is
   called more often than needed, thereby causing unneedy screen
   flickering and/or slowness.
   

Examples:

   DC_GetRefreshBlock( {|a,b,c,d,e|(dcbdebug a,b,c,d,e)}
   

Source/Library:

  _DCGETBX.PRG

See Also:

   dc_getrefresh()

dc_gettitlebarheight()

Get the height of Dialog Title Bars

Syntax:

   DC_GetTitleBarHeight() - > nHeight
   

Arguments:

   None.
   

Returns:

   A numeric value.
   

Description:

   DC_GetTitleBarHeight() returns the height (in pixels) of the
   Dialog window title bar.  This height is normally set by the user
   after clicking on "Desktop Properties".
   

Examples:

   ? DC_GetTitleBarHeight()
   21
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

dc_getvalidate()

Run validation logic in the GetList

Syntax:

    DC_GetValidate( oXbp, ;
                   [< lPassBuffer >], ;
                   [< lTestForBlock >] ) - > lStatus
   

Arguments:

   < oXbp > is the Xbase Parts object to validate.  This is any
   object created by a DC* command in the GetList that also has
   an associated VALID clause.
   
   < lPassBuffer > if .TRUE. will pass the contents of the display
   buffer to the validation code block, otherwise if .FALSE.
   (default), a pointer to the object will be passed to the
   validation code block.
   
   < lTestForBlock > if .TRUE. will only test for the existence of a
   validation code block associated with an object but will not
   evaluate the code block.  If a code block exists, then the
   function will return .TRUE. otherwise it will return .FALSE.
   

Returns:

    The logical value returned by the VALID code block associated
    with the Xbase Parts object.
   

Description:

    DC_GetValidate() is used to test or run the validation code
    block associated with a specifed GET.
   
    DC_GetValidate() is called automatically in DC_ReadGuiEventLoop()
    after events that may change values referenced in a GET.
   

Examples:

   oXbp := SetAppFocus()
   ? DC_GetValidate( oXbp )
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_getrefresh()
   dc_getvalidblock()
   dc_getvalidateonchange()

dc_getvalidateonchange()

A Get-Set function to determine Validation rule

Syntax:

   DC_GetValidateOnChange( [< lSetting >] ) - > lOldSetting
   

Arguments:

   < lSetting > if .TRUE. will cause the validation code block
   only to be evaluated if the value of the Get has changed.  The
   default is .FALSE.
   

Description:

   DC_GetValidateOnChange() is a get-set function that is used to
   modify the behavior of GET validations.
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.DLL

See Also:

   dc_getvalidate()

dc_getvalidblock()

A Get-Set function for posting a default validation block

Syntax:

   DC_GetValidBlock( [< bValidate >] ) - > bOldValidate
   

Arguments:

   < bValidate > is a code block that will be evaluated when
   any DC_XbpGet() object loses focus.  The object will be
   passed to the code block.  The code block must return a
   logical value.  If it returns a .TRUE., then control will
   be passed to the validation routine that evaluates the
   specific validation block for the object.  If it returns
   a .FALSE., then the object cannot lose focus.
   

Returns:

   The previously posted code block.
   

Description:

   DC_GetValidBlock() is a Get-Set function that is used to
   post a "default" validation code block for @..DCSAY..GET
   and @..DCGET objects.  The default code block will be
   evaluated first before evaluating any code block posted
   with the VALID clause.  This is handy for special date
   validations.
   

Examples:

   FUNCTION XTest()
   
   LOCAL GetList[0], cTime := '  :  :  '
   
   DC_GetValidBlock({|o|MySpecialValidator(o)})
   
   @ 1,1 DCSAY 'Enter Time' GET cTime PICT '99:99:99'
   
   DCREAD GUI FIT ADDBUTTONS ENTEREXIT
   
   RETURN nil
   
   * -----------
   
   FUNCTION MySpecialValidator( oGet )
   
   LOCAL xValue := oGet:get:varget()
   
   IF Valtype(xValue) == 'C' .AND. Len(xValue) = 8 .AND. ;
      xValue[3] == ':' .AND. xValue[6] == ':'
     // this is a "Time" Get
     nHours := Min(Val(Substr(xValue,1,2)),23)
     nMinutes := Min(Val(Substr(xValue,4,2)),59)
     nSeconds := Min(Val(Substr(xValue,7,2)),59)
     xValue := DC_PadZero(Str(nHours,2)) + ':' + ;
               DC_PadZero(Str(nMinutes,2)) + ':' + ;
               DC_PadZero(Str(nSeconds))
     oGet:_assign(xValue)
   ENDIF
   
   RETURN .t.
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.DLL

See Also:

   @ DCSAY
   dc_getvalidate()
   dc_getvalidateonchange()

dc_getwhen()

Refresh the WHEN/HIDE status of object(s) in the GetList

Syntax:

   DC_GetWhen ( < aGetList | oXbp >, ;
                [< nElement >], ;
                [< lTestProtect >], ;
                [< acID >], ;
                [< acGroup > ) - > nil
   

Arguments:

   < aGetList > is an array containing a list of Get objects to
   refresh.  Alternatively, the first parameter may be an object
   of the DC_Xbp*() class.  If this paramter is an object, then
   the remaining parameters are not used.
   
   < nElement > is the element number of the GetList to test.  If
   this parameter is not passed, then all items in the GetList will
   be tested.
   
   < lTestProtect > is reserved for internal use.
   
   < acID > is an Object ID or array of ID's to evaluate. When this
   parameter is used, only this ID or list of ID's will be refreshed.
   
   < acGroup > is a Group ID or array of Group ID's to evaluate.  When
   this parameter is used, only this Group or list of Groups will
   be refreshed.
   

Returns:

    Nil.
   

Description:

    DC_GetWhen() is used to refresh the WHEN/HIDE status of objects
    in the GetList.  If the WHEN clause or HIDE clause is used with
    a DC* command, it is the function DC_GetWhen() that evaluates
    the code block associated with the WHEN or HIDE clauses and
    uses the :disable()/:enable and/or :hide()/:show() method of the
    Xbase Parts class dependent on the value returned by the
    associated code block.
   
    DC_GetWhen() is called automatically in DC_ReadGuiEventLoop()
    after events that may change values referenced in WHEN/HIDE
    code blocks.  DC_GetWhen() is also called from DC_GetRefresh().
   

Examples:

   -- Example 1 --
   
   oXbp := SetAppFocus()
   aGetList := oXbp:cargo[2]
   nElement := oXbp:cargo[1]
   DC_GetWhen( aGetList, nElement )
   
   -- Example 2 --
   
   DC_GetWhen( GetList,,,{'BUTTON1','BUTTON2'} )
   
   -- Example 3 --
   
   DC_GetWhen( GetList,,,,'GROUP1' )
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_getrefresh()
   dc_readguieventloop()

dc_getwhenonbrowseitemmarked()

Get-set function that enable DC_GetWhen() on item marked event

Syntax:

   DC_GetWhenOnBrowseItemMarked( [< lEnable > ] ) - > lOldEnable
   

Arguments:

   < lEnable > if .TRUE. will enable evaluation of HIDE and WHEN clauses.
   The default is .FALSE.
   

Description:

   DC_GetWhenOnBrowseItemMarked() is a Get-Set function that enables
   DC_GetWhen() calls when an xbeBRW_ItemMarked event occurs.
   
   This would be used in case it is needed to insure that all WHEN
   and HIDE clauses in a dialog are evaluated any time the row
   pointer is moved in the browse.  The default is .FALSE. for
   performance reasons.
   

Source/Library:

  _dcxbrow.prg, dclipx.dll

See Also:

   @ DCBROWSE

dc_getworkarea()

Get the actual working area of the Desktop

Syntax:

   DC_GetWorkArea() - > aCoords
   

Arguments:

   None.
   

Returns:

   An array of 4 elements:
   { left, top, right, bottom }
   
   left
   Specifies the x-coordinate of the upper-left corner of the
   rectangle.
   
   top
   Specifies the y-coordinate of the upper-left corner of the
   rectangle.
   
   right
   Specifies the x-coordinate of the lower-right corner of the
   rectangle.
   
   bottom
   Specifies the y-coordinate of the lower-right corner of the
   rectangle.
   

Description:

   DC_GetWorkArea() returns an array of 4 elements containing the
   usable work area of the AppDesktop().  AppDeskTop():currentSize()
   will return the full size of the desktop, however, the user may
   have limited the useful area by setting toolbars on the desktop
   as "always on top".  DC_GetWorkArea() is used to determine the
   useable area of the desktop.
   
   Retrieves the size of the work area on the primary display monitor.
   The work area is the portion of the screen not obscured by the
   system taskbar or by application desktop toolbars.
   

Examples:

   // This example will create a dialog window that is sized and
   positioned to fill the useable workarea of the desktop.
   
   aWorkArea := DC_GetWorkArea()
   
   nHeight := aWorkArea[4] - aWorkArea[2]
   nWidth  := aWorkArea[3] - aWorkArea[1]
   
   oDlg := XbpDialog():new( AppDeskTop(), , ;
         {aWorkArea[1],AppDeskTop():currentSize()[2]-aWorkArea[4]}, ;
         {nWidth,nHeight}, , .F.)
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

dc_gotoget()

Go directly to a desired GET

Syntax:

   DC_GoToGet () - > nil
   

Arguments:

    none.
   

Returns:

    NIL
   

Description:

    DC_GOTOGET() is handy if you have a large table of GETS on the
    screen and don't have a mouse, but want to give the operator
    an opportunity to go directly to a GET # by typing in the GET
    number.
   

Notes:

    This function only works with DC_ReadModal(), NOT ReadModal().
   

Examples:

    SetKey( -1, { || DC_GOTOGET() } )
    DC_ReadModal( GetList )
   

Source/Library:

  _DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()

dc_gra2color()

Convert GUI compatible color to a color string

Syntax:

   DC_Gra2Color( < aColor > ) - > cColorString
   

Arguments:

   < aColor > is an array of two numeric elements.  The first
   element is the foreground color.  The second element is the
   background color.
   

Returns:

    A character string.
   

Description:

    DC_GRA2COLOR() is used to convert an 2 element array containing
    a foreground and background color that are compatible with GUI
    objects to a color string that is compatible with text objects.
   

Examples:

    #include "gra.ch"
   
    PROCEDURE Xtest()
   
    LOCAL aColor := { GRA_CLR_RED, GRA_CLR_WHITE }
   
    DC_Gui(.t.)
   
    DC_MsgBox( DC_Gra2Color( aColor ) )
   
    RETURN
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_color2gra()

dc_graquerytextbox()

Get the width and height of a text string based on a font

Syntax:

   DC_GraQueryTextBox( < cString >, ;
                       < cFont > ) - > aSize
   

Arguments:

   < cString > is a text string.
   
   < cFont > is a character string containing the name of the font
   which conforms to a standard Xbase++ font definition, such as
   '12.Arial Bold'.
   

Returns:

   A two element array of numeric values.
   
   [1] - Width
   [2] - Height
   

Description:

   DC_GraQueryTextBox() is used to calculate the width and height,
   in pixels, of a text string based on a specified font.  This is
   basically a wrapper function for the Xbase++ function GraQueryTextBox()
   which is simpler to use.
   

Examples:

   PROCEDURE XTest( )
   
   LOCAL i, j, cFont, nRow, lOk, GetList := {}, nHeight
   
   FOR i := 8 TO 22 STEP 2
     cFont := Alltrim(Str(i)) + '.Arial'
     nHeight := DC_GraQueryTextBox( 'Text', cFont )[2]
     nRow := 1
     FOR j := 1 TO 10
       @ nRow, 0 DCSAY 'This is line ' + Alltrim(Str(j)) ;
               FONT cFont SAYSIZE 0 PIXEL
       nRow += nHeight
     NEXT
     DCREAD GUI FIT ADDBUTTONS TO lOk
     IF !lOk
       EXIT
     ENDIF
   NEXT
   
   RETURN
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

dc_groupboxfix()

A Get-Set function used to fix group box problem on XP

Syntax:

   DC_GroupBoxFix( [< lFix >] ) - > lOldFix
   

Arguments:

   < lFix > if .TRUE. will create two XbpStatic objects, if .FALSE.
   will function normally and create only one XbpStatic object.
   

Description:

   DC_GroupBoxFix() is a Get-Set function that is used to set the
   method in which DCGROUP static boxes will be created due to an
   Xbase++ anomoly that displays XbpRadioButton() objects incorrectly
   when the parent is a XbpStatic() type XBPSTATIC_TYPE_GROUPBOX
   and the application is using a MANIFEST file.
   
   Run the sample program in \exp18\samples\xp for more information
   about using manifest files to display XP style dialog objects.
   
   When set to .T., every DCGROUP command will create two XbpStatic()
   objects instead of one.  The parent of the groupbox will be a
   static of type text and will be the exact same size.  This
   eliminates the display problem under XP.
   

Examples:

   #INCLUDE "dcdialog.CH"
   
   FUNCTION main
   
   LOCAL GetList[0], GetOptions, d := Date(), nGroup := 3, i, oGroup, oStatic, ;
         lCheck := .F.
   
   IF 'Windows XP' $ Os() .AND. File('TEST.EXE.MANIFEST')
     DC_GroupBoxFix(.t.)
   ENDIF
   
   FOR i := 1 TO 10
     @ i,0 DCSAY 'Date ' + Alltrim(Str(i)) GET d POPUP {|d|DC_PopDate(d,,,,,,2)}
   NEXT
   
   @ 1,27 DCGROUP oGroup CAPTION 'Group Test' SIZE 20,10 PARENT oStatic
   
   FOR i := 1 TO 4
     @ i,1 DCRADIO nGroup VALUE i PROMPT 'Radio Button ' + Alltrim(Str(i)) PARENT
   oGroup
   NEXT
   
   FOR i := 1 TO 4
     @ i+4,1 DCCHECKBOX lCheck PROMPT 'Check Box ' + Alltrim(Str(i)) PARENT
   oGroup
   NEXT
   
   FOR i := 1 TO 10
     @ i,50 DCPUSHBUTTON CAPTION 'Button ' + Alltrim(Str(i)) ;
       SIZE 10,1 ACTION {||MsgBox('button test')}
   NEXT
   
   DCGETOPTIONS ;
      SAYWIDTH 50 ;
      SAYRIGHTBOTTOM ;
      HILITEGETS GRA_CLR_RED ;
      COLORGETS { {GRA_CLR_RED,GRA_CLR_YELLOW} } ;
      BUTTONALIGN DCGUI_BUTTONALIGN_CENTER
   
   DCREAD GUI ;
      FIT ;
      MODAL ;
      SETAPPWINDOW ;
      ADDBUTTONS ;
      OPTIONS GetOptions ;
      TITLE 'XP Manifest Sample'
   
   RETURN nil
   
   * -----------
   
   PROC appsys
   RETURN
   

Source/Library:

  _DCCLASS.PRG, DCLIPX.DLL

dc_gui()

Set the Dialogue mode to GUI or TEXT

Syntax:

    DC_Gui( [< lMode >] ) - > lOldMode
   

Arguments:

   < lMode > if .TRUE. sets GUI mode ON, if .FALSE. sets GUI mode OFF.
   If < lMode > is not passed, then the GUI mode is not changed.
   

Returns:

    Tha previous setting of GUI mode.
   

Description:

    DC_Gui() is used to set Text or Gui mode for Dual-Mode
    Functions.  The eXPress++ library contains a variety of
    functions which operate in "Dual-Mode".  When GUI mode is
    ON, the function uses a GUI dialogue based on Xbase Parts.  When
    the GUI mode is OFF the function works in standard text-mode.
   

Examples:

     /*
     In this example, DC_ReadBox() and DC_Impl() will only
     display and restore the window in Text-Mode.  They are
     ignored in GUI mode.
     */
   
     #include "dcdialog.ch"
   
     PROCEDURE Xtest( lGui )
   
     LOCAL GetList := {}, GetOptions, aReadArea, cLastName := Space(15), ;
           cFirstName := Space(15), cCompany := Space(25), ;
           cStreet := Space(25), cCity := Space(25), cState := Space(2), ;
           cCountry := Space(25), cPhone := Space(15), cScrn, lOk
   
     lGui := IIF( Valtype(lGui)='L',lGui,.t.)
   
     DC_Gui(lGui)   //  set GUI mode
   
     cScrn := DC_ReadBox(3,5,15,75,,@aReadArea)
   
     @ 5,10 DCSAY ' Last Name' GET cLastName
     @ 5,40 DCSAY 'First Name' GET cFirstName
     @ 7,10 DCSAY '   Company' GET cCompany
     @ 8,10 DCSAY '    Street' GET cStreet
     @ 9,10 DCSAY '      City' GET cCity
     @10,10 DCSAY '     State' GET cState
     @11,10 DCSAY '   Country' GET cCountry
     @13,10 DCSAY '     Phone' GET cPhone PICT '(999)-999-9999'
   
     DCGETOPTIONS SAYWIDTH 70 SAYRIGHTJUST
   
     lOk := DC_ReadGets( GetList,"Enter Data",aReadArea,;
                         GetOptions )
     DC_Impl(cScrn)
   
     RETURN
   

Source/Library:

  _DCGUI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readgui()
   GUI

dc_guiabrowse()

Browse a multi-dimensional array using Tree-View

Syntax:

   DC_GuiAbrowse( < aArray >, ;
                  [< aRef >], ;
                  [< oParent >], ;
                  [< aPos >], ;
                  [< aSize >], ;
                  [< cTitle >], ;
                  [< lHasButtons >], ;
                  [< lHasLines >] ) - > oArrayTree
   

Arguments:

   < aArray > is the multi-dimensional array to browse.
   
   < aRef > is an optional reference array that is used to format the
   data in the browse.  If < aRef > is a NIL then the tree view will
   display the exact contents of the array.  < aRef > is an array of
   5-element sub-arrays, 1 for each level of the array being browsed.
   The sub-arrays are defined as follows:
   
    Element Type Description
    ------- ---- ----------------------------------------------------
   
      [1]     B  Optional code block used to format the displayed
                 data.  The array item and it's ordinal position
                 within the array are passed as parameters.
                 examples: {|a,n|a[1]}
                           {|a,n|filedata(a,n)}
   
      [2]     N  The resource ID of a bitmap or icon image to
                 visualize the normal state of the array item
                 (not marked and not expanded).
   
      [3]     N  The resource ID of a bitmap or icon image to
                 visualize the marked state of the array item.
   
      [4]     N  The resource ID of a bitmap or icon image to
                 visualize the expanded state of the array item.
   
      [5]     A  An optional array of numeric values containing
                 the array elements to include in the expanded
                 view.
   
   < oParent > is the parent object for the tree-view.  This is usually
   an XbpStatic or XbpTabPage object.  If no parent object is passed,
   then an XbpDialog object will be created as the parent.
   
   < aPos > is a 2-element array containing the pixel coordinates
   of the starting location of the tree-view window.  Default is {0,0}
   
   < aSize > is a 2-element array containing the width and height (in
   pixels) of the tree-view window.  Default is {300,400}.
   
   < cTitle > is the title of the Dialog Window.  This parameter is
   ignored if < oParent > is a nil.
   
   If < lHasButtons > is set to .T. (default), the tree view displays a
   Plus or Minus sign at each node of the tree. This indicates whether
   the next level of the tree can be expanded or suppressed.
   
   If < lHasLines > is set to .T. (default), the tree view displays lines
   between the nodes of the tree and their leaves. This results in a
   more readable display.
   

Returns:

   A pointer to the tree-view object.
   

Description:

   DC_GUIABROWSE() is an array-browser that provides a tree-view
   style browse of any multi-dimensional array.
   

Examples:

   #INCLUDE "dcicon.ch"
   
   FUNCTION Xtest()
   
   LOCAL aDirectory, aDirOptions
   
   aDirectory := Directory( '*.*' )
   IF Len(aDirectory) > 50
     ASize(aDirectory,50)
   ENDIF
   
   aDirOptions := { { {|a,n|a[1]},         ;
                      ICON_CLOSEDFOLDER, ;
                      ICON_CLOSEDFOLDER, ;
                      ICON_OPENFOLDER }, ;
                    { {|a,n|FileData(a,n)}, ;
                      ICON_CLOSEDFOLDER, ;
                      ICON_CLOSEDFOLDER, ;
                      ICON_OPENFOLDER, ;
                      { 2,3,4,7,8 } } }
   
   DC_GuiABrowse( aDirectory, aDirOptions, nil, nil, nil, ;
                  'Directory of Files' )
   
   RETURN nil
   
   /* ------------------- */
   
   STATIC FUNCTION FileData ( xData, nElement )
   
   LOCAL cData := DC_XtoC( xData ), cPrefix
   
   DO CASE
     CASE nElement = 2
       cPrefix := 'File Size: '
     CASE nElement = 3
       cPrefix := 'File Date: '
     CASE nElement = 4
       cPrefix := 'File Time: '
     CASE nElement = 7
       cPrefix := 'Creation Date: '
     CASE nElement = 8
       cPrefix := 'Creation Time: '
     OTHERWISE
       cPrefix := ''
   ENDCASE
   
   RETURN cPrefix + cData
   

Source/Library:

  _DCABROW.PRG, DCLIPX.LIB

See Also:

   @ DCTREEARRAY

dc_guiachoice()

A GUI replacement for ACHOICE()

Syntax:

   DC_GuiAChoice ( < nTop >, ;
                   < nLeft >, ;
                   < nBottom >, ;
                   < nRight >, ;
                   < aMenuItems >, ;
                   [< aSelItems >], ;
                   [< cUserFunc > | < bUserFunc >], ;
                   [< nInitialItem >], ;
                   [< nWindowRow >], ;
                   [< cTitle >], ;
                   [< aHelpCodes >], ;
                   [< aMenu >], ;
                   [< cFontName >], ;
                   [@< oDlg >], ;
                   [< lDestroy >], ;
                   [< aMessage >], ;
                   [< cHeader >],;
                   [< lCenter >] ) - > nElement
   

Arguments:

   < nTop >, < nLeft >, < nBottom >, < nRight >
   are the screen
   coordinates in pixels.
   
   < aMenuItems > is an array of character strings to include
   in the pick-list.
   
   < aSelItems > is an array of logical values.  There is one
   element in this optional array for each element in
   < aMenuItems >.  Each element in < aSelItems > that is a
   .TRUE. will make the item in the window a "selectable"
   item, otherwise it will be a non-selectable item and will
   be displayed in "grayed" form.
   
   < cUserFunc > | < bUserFunc > is the name of an optional
   User-Defined
   function to call on exception keystrokes.  See the Clipper
   documentation of ACHOICE() for more information on how to use
   a UDF.  If the parameter is passed as a character string then
   the function must be a PUBLIC, not STATIC function.
   
   < nInitialItem > is the item to high-light in the window on
   startup.
   
   < nWindowRow > is the item to display as the first item in
   the pick-list.
   
   < cTitle > is the title of the window.
   
   < aHelpCodes > is an array of character string HELP CODES.
   There is one element in this optional array for each element in
   < aMenuItems >.  The HELP CODE will be passed on to the
   DC_HelpF1() function for context-specific help if the operator
   presses F1 on a selected item.
   
   < aMenu > is an array defining a Top-Bar/Pull-Down menu. This
   array must conform to the specification for the array passed
   to the DC_MENUMAIN() function.   This Top-Bar menu will be
   painted at the screen coordinates defined in the menu if
   < lAttachMenu > is .FALSE. or directly attached to the top of
   the pick-list window if < lAttachMenu > is .FALSE. (default).
   The menu will be energized if the operator presses a key
   matching one of the hightlighted characters in the menu, or
   if the mouse is clicked on one of the top-bar menu items.
   The menu array must contain code-blocks for each menu item
   to execute functions based on the menu selection.  See
   DC_MENUMAIN() for more information.
   
   < cFontName > is the name of an optional font.
   
   @< oDlg > is a variable to store the dialog object for the
   pick-list.
   
   < lDestroy > if .TRUE. (default) will destroy the dialog
   object for the browse.  If .FALSE., the dialog will remain
   active.  Set this to .FALSE. when using DC_GUIACHOICE() in
   a loop.
   
   < aMessage > is an optional array of character strings to use as a
   message to be displayed in the dialog window above the pick-list.
   
   < cHeader > is an optional heading.
   
   < lCenter > if .TRUE. will center the dialog in the display.
   

Description:

    DC_ACHOICE() is a Dual-mode replacement for AChoice().  When
    the GUI flag is ON, DC_ACHOICE() functions similiar to
    AChoice() except that it is displayed in GUI mode.  When the
    GUI flag is OFF, DC_ACHOICE() functions identical to ACHOICE()
    except it is also activated by a mouse.  The left button of the
    mouse is used to select the item in the window.  The right button
    or double-clicking works  identical to the ENTER key.
   
    In TEXT mode, Hot keys can be activated by passing an array of
    screen coordinates (mouse-buttons) and key definitions.
   
    In TEXT mode, an options array is used to define scroll-bars,
    colors, exit options, title, drag options, etc.
   
    An optional array of Help-Codes may be passed for context-
    specific help on any selected item with the F1 key.
   

Examples:

Source/Library:

  _DCACHOI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_achoice()

dc_guialert()

A GUI replacement for ALERT()

Syntax:

   DC_GuiAlert( [< oOwner >], ;
                [< acText >], ;
                [< aCaption >], ;
                [< nSysIcon >], ;
                [< cTitle >], ;
                [@< aDlgPos >], ;
                [< lModal >], ;
                [< aFonts >]  ) - > nChoice
   

Arguments:

   < oOwner > is the owner of the dialog.  The default is
   SetAppWindow().
   
   < acText > may be a character string of text-lines (separated by
   semi-colons) or an array of character strings for displaying
   within the alert dialog above the button selections.
   
   < aCaption > is an array of captions for buttons which will be
   displayed in the dialog.  A tilde (~) character within the
   caption text will underline the following character in the
   push-button and make it the hot-key.  For example, '~Ok' will
   underline the O in Ok and Alt-O will activate the button.
   
   < nSysIcon > is the icon to display in the dialog.  This is a
   numeric constant from XBP.CH.  The default is
   XBPSTATIC_SYSICON_ICONQUESTION.
   
   < cTitle > is the title to display in the title area of the dialog
   window.
   
   @< aDlgPos > is a numeric variable to store a two-element array
   of coordinates which will be returned when the user exists the
   alert window.  These coordinates are the screen coordinates of
   the dialog before it was destroyed.  These coordinates may be
   passed to DG_GUIALERT() again later to paint the dialog window
   in the same location.
   
   < lModal > if .TRUE. (default), will set the modal state of the
   dialog window to APPMODAL.
   
   < aFonts > is a 2-element array containing the Font Compound Name
   for the buttons and the text.  Element 1 is the button font and
   element 2 is the text font.
   

Returns:

    A numeric value equal to the button which was selected by the
    user.
   

Description:

    DC_GUIALERT() is a GUI replacement for Alert().
   

Notes:

   The foreground and background color of the GUI alert box is
   preset by the function DC_AlertColor().