dc_lblcreate()

Create a .LBL label file from a label form array

Syntax:

Arguments:

    (cFileName) is the name of the file to create.
   

   
 (aLabelInfo) is a multi-dimensional array with information
   
 about the label form.  See DC_LBLSTRU() for a description of a
   
 label form array.
   

   

Returns:

    A logical .TRUE. if the form is created with no errors, .FALSE.
   
 otherwise.
   

   

Description:

Examples:

    aLabel := dc_lblstru( 'CUSTOMER.LBL' )  // Create label array
   
 do while .t.
   
   @ 10,10 prompt 'Edit form layout'
   
   @ 11,10 prompt 'Save label form'
   
   menu to nChoice
   
   do case
   
     case nChoice = 1
   
       dc_lbllayout( aLabel, 'CUSTOMER.LBM' )  // edit layout
   
     case nChoice = 2
   
       DC_LBLCREATE( 'CUSTOMER.LBL', aLabel )  // save form
   
       exit
   
   endcase
   
 enddo
   

   

Source/Library:

See Also:

dc_lbledit()

Edit a label form array

Syntax:

Arguments:

    (aLabelInfo) is a multi-dimensional array with the label form
   
 information.  See DC_LBLSTRU() for a description of this array.
   

   
 (cFileName) is an optional parameter.  This is the name of the
   
 label file which will be created to use as a reference on the
   
 editor screen.
   

   

Returns:

    A multi-dimensional array containing the modified contents of
   
 the original array.
   

   

Description:

Examples:

    aLabel := dc_lblstru( 'CUSTOMER.LBL' )  // Create label array
   
 do while .t.
   
   @ 10,10 prompt 'Edit form layout'
   
   @ 11,10 prompt 'Save Label form'
   
   menu to nChoice
   
   do case
   
     case nChoice = 1
   
       DC_LBLEDIT( aLabel, 'CUSTOMER.LBL' )  // edit layout
   
     case nChoice = 2
   
       dc_lblcreate( 'CUSTOMER.LBL', aLabel )  // save form
   
       exit
   
   endcase
   
 enddo
   

   

Source/Library:

See Also:

dc_lblform()

Front-End to Clipper Label form function - displays odometer

Syntax:

Arguments:

    Arguments are the same as __LabelForm().  See STD.CH - LABEL
   
 FORM command.
   

   
 (cFormFile)  - Report form file name
   
 (lPrint)     - Output to Printer
   
 (cToFile)    - Output to a file (cToFile)
   
 (lNoConsole) - Don't display output on console
   
 (bFor)       - FOR condition code block
   
 (bWhile)     - WHILE condition code block
   
 (nNext)      - Number of records to print
   
 (nRec)       - A single record number to print
   
 (lRest)      - Print only from current record to the end
   
 (lSample)    - Print a sample label
   

   

Returns:

    NIL
   

   

Description:

Examples:

    // Pre-process LABEL FORM command to call DC_LBLFORM()
   
 #include "DCLFORM.CH"
   

   
 LABEL FORM CUSTOMER TO PRINT SAMPLE
   

   

Source/Library:

See Also:

dc_lblmodify()

Edit or Create a Label Form file

Syntax:

Arguments:

    (cLabelFile) is the name of the Label Form (.LBL) file to edit.
   
 If no argument is given, then the menu will provide a
   
 user-prompt for entering a file name.
   

   

Returns:

    NIL
   

   

Description:

Examples:

    @ 12,10 prompt "Modify a Label Form"
   
 @ 13,10 prompt "Output a Label Form"
   
 menu to nChoice
   
 do case
   
   case nChoice = 1
   
     DC_LBLMODIFY()
   
   case nChoice = 2
   
     dc_lblout()
   
 endcase
   

   

Source/Library:

See Also:

dc_lblout()

Output a label form to screen, printer or file

Syntax:

Arguments:

    (cFormFile) is the name of the label form file (.LBL) to output
   
 to the screen, file or printer.  If no argument is given, then
   
 the name of the last label form to be printed will appear in
   
 the display for the user to modify.
   

   

Description:

Examples:

    @ 12,10 prompt "Modify a Label Form"
   
 @ 13,10 prompt "Output a Label Form"
   
 menu to nChoice
   
 do case
   
   case nChoice = 1
   
     dc_lblmodify()
   
   case nChoice = 2
   
     DC_LBLOUT()
   
 endcase
   

   

Source/Library:

See Also:

dc_lblstru()

Create a label form array from a .LBL label file

Syntax:

Arguments:

    (cLabelFile) is the name of a label form (.LBL) file.
   

   

Returns:

    A multi-dimensional array of two sub-arrays:
   

   
 The first sub-array (1) is 7 elements and defines general
   
 information about  the labels.
   

   
 Element  Type        Description
   
 -------  --------   ---------------------------------
   
  [1,1]   Character  Remarks
   
  [1,2]   Numeric    Label Width
   
  [1,3]   Numeric    Label Height
   
  [1,4]   Numeric    Labels Across
   
  [1,5]   Numeric    Lines between labels down
   
  [1,6]   Numeric    Spaces between labels across
   
  [1,7]   Numeric    Left margin
   

   
 The second sub-array (2) is 16 elements.  Each element represents
   
 a line in the label (up to 16 lines).
   

   
 Element     Type       Description
   
 --------   ---------- ------------------------------
   
 [2,1]      Character   Expression
   

   
   |          |            |
   

   
 [2,16]     Character   Expression
   

   

   

Description:

Examples:

    aLabel := DC_LBLSTRU( 'CUSTOMER.LBL' )  // Create label array
   
 aLabel := dc_lbledit( aLabel )          // Edit label layout
   
 dc_lblcreate( 'CUSTOMER.LBL', aLabel )  // Create label file
   

   

Source/Library:

See Also:

dc_lbltype()

Pop up a pick-list of Standard label formats

Syntax:

Arguments:

    NONE
   

   

Returns:

    An array of 7 elements.
   

   
 Element  Type        Description
   
 -------  ---------- -----------------------------------
   
  [1,1]   Character  Remarks
   
  [1,2]   Numeric    Label Width
   
  [1,3]   Numeric    Label Height
   
  [1,4]   Numeric    Labels Across
   
  [1,5]   Numeric    Lines between labels down
   
  [1,6]   Numeric    Spaces between labels across
   
  [1,7]   Numeric    Left margin
   

   

Description:

Examples:

    aLabel := dc_lblstru( 'CUSTOMER.LBL' )  // Create label array
   
 do while .t.
   
   @ 10,10 prompt 'Edit form layout'
   
   @ 11,10 prompt 'Select a default label format'
   
   @ 12,10 prompt 'Save Label form'
   
   menu to nChoice
   
   do case
   
     case nChoice = 1
   
       dc_lbledit( aLabel, 'CUSTOMER.LBL' )  // edit layout
   
     case nChoice = 2
   
       aType := DC_LBLTYPE()
   
       IF LASTKEY()#27
   
         aLabel[1] := aType
   
       ENDIF
   
     case nChoice = 2
   
       dc_lblcreate( 'CUSTOMER.LBL', aLabel )  // save form
   
       exit
   
   endcase
   
 enddo
   

   

Source/Library:

See Also:

dc_libload()

Load a dynamic library

Syntax:

Arguments:

    (cDlibName) is the name of the dynamic library to load.  Name
   
 may be preceded by a disk drive letter and/or directory.  Do
   
 not include the .DLB extension.
   

   
 If the name does not include a drive and/or directory, the
   
 dynamic library file    must be located in the current DOS
   
 directory or in the directory identified by the SET DCLIP
   
 parameter in your DOS environment.
   

   
 (cRunProc) is an optional name of a procedure or function to
   
 run loading the dynamic library.
   

   
 (lLibUnload) is an optional parameter that is used only if
   
 (cRunProc) is used.  If .TRUE., the dynamic library will be
   
 unloaded after the (cRunProc) is executed.  If .FALSE., the
   
 dynamic library will remain loaded in memory.
   

   

Description:

Notes:

Examples:

    -- Example 1 --
   

   
 calc()           // Creates error "Undefined Function CALC"
   
 DC_LIBLOAD( 'MYFUNCS' )  // MYFUNCS.DLB contains Calc()
   
 calc()                 // Calc() runs ok now
   

   

   
 -- Example 2 --
   

   
 do while .t.
   
   dc_objrelese('ALL')
   
   nChoice : = 1
   
   cls
   
   @10,10 say 'Run Sales Program'
   
   @11,10 say 'Run Inventory Program'
   
   @12,10 say 'Run  General Ledger'
   
   menu to nChoice
   
   do case
   
     case nChoice = 1
   
       DC_LIBLOAD( 'SALES', 'Sales_main()', .t. )
   
     case nChoice = 2
   
       DC_LIBLOAD( 'INVEN', 'Inven_main()', .t. )
   
     case nChoice = 3
   
       DC_LIBLOAD( 'GLEDGER', 'Gled_main()', .t. )
   
   endcase
   
 enddo
   

   

Source/Library:

See Also:

dc_libunld()

Unload a dynamic library

Syntax:

Arguments:

    (cDlbName) is the name of the dynamic library to unload. You do
   
 not need to include the drive and/or directory name.
   

   
 If (cDlbName) is "ALL", the all dynamic libraries will be
   
 unloaded.
   

   
 If no argument is passed, DC_LIBUNLD() will unload the last
   
 loaded library.
   

   

Returns:

    A logical .TRUE. if the dynamic library is successfully unloaded,
   
 .FALSE. otherwise.
   

   

Description:

Examples:

    dc_linkinit()
   
 dc_libload( 'MYAPPS' )
   
 do main
   
 dc_libunld()
   

   

Source/Library:

See Also:

dc_like()

Returns a "Sounds-Like" argument

Syntax:

Arguments:

    (cString1) and (cString2) are the strings to compare.
   

   

Description:

Examples:

    use customer
   
 locate for DC_LIKE( trim(last), 'rose' )
   

   

Source/Library:

dc_linkauto()

Automatically dynamic-link all new .OBJ's

Syntax:

Arguments:

    (cOBJdirectory) is the directory to search for .OBJ files.  If
   
 no directory is given, then the directory path pre-established
   
 by the SET OBJ=(cPath) environment command.
   

   
 (cWildCard) is the sub-group of .OBJ files to search.  If no
   
 argument is given, then "*" (all) is default.
   

   
 (lVerbose) if .TRUE. (default) will display the name of each
   
 .OBJ before it is loaded into memory.
   

   
 (lLinkAll) if .TRUE. will link all Clipper-compiled .OBJ files
   
 that are newer than the running .EXE.  If .FALSE. (default),
   
 only the .OBJ files that contain functions which were previously
   
 linked into the .EXE will be dynamic-linked.
   

   

Returns:

    A logical .TRUE. if any new .OBJ's were laoded into memory, .FALSE.
   
 otherwise.
   

   

Description:

Notes:

Examples:

    -- Example 1 --
   

   
 This example demonstrates how to use DC_LINKAUTO() to
   
 automatically load newer .OBJs into memory each time an .EXE
   
 program is run.
   

   
 procedure main()
   
 dc_linkinit( 50 )  // Initialize dynamic link pool to 50k
   
 DC_LINKAUTO()      // Load .OBJ's that are newer than .EXE
   
 mainmenu()
   
 return
   

   
  -- Example 2 --
   

   
 This example demonstrates how to use DC_LINKAUTO() to
   
 automatically load newer .OBJ's after (1) shelling to DOS
   
 within a live Clipper application, (2) editing and compiling
   
 changes to the source code, and (3) returning to the
   
 application.
   

   
 procedure main()
   
 set key -1 to gateway
   
 dc_linkinit(100)
   
 mainmenu()
   
 return
   

   
 proc gateway
   
 dc_gateway()  // shell to dos, edit and compile source, then
   
 EXIT          // back to application
   

   
 DC_LINKAUTO() // Load .OBJ's that are newer than .EXE
   
 return
   

   
 -- Adding the dynamic-link library to your link script --
   

   
 Blinker: @DCLIPNL.BL
   
 Rtlink : @DCLIPNL.RT
   

   

Source/Library:

See Also:

dc_linkinit()

Initialize the dynamic-link system

Syntax:

Arguments:

    (nObjMemory) is the amount of dynamic-link memory pool to
   
 allocate.  This number must be equal to or less than the amount
   
 of memory reserved by the SET CLIPPER=X(memory) option.  If the
   
 X parameter is not specified in your SET CLIPPER environment,
   
 then DC_LINKINIT() cannot allocate the memory.  NOTE: some
   
 linkers provide the option of "burning in" the SET CLIPPER
   
 environment into the executable program.  You must make sure
   
 that (nObjMemory) does not exceed the X value.  If (nObjMemory)
   
 is 0 or is not passed then the full amount of memory reserved
   
 by SET CLIPPER=X(memory) will be allocated.
   

   
 (lSpeed) if .TRUE. will disable the automatic feature of the
   
 dynamic link system that checks the date/time stamp of the
   
 modules in dynamic libraries and links an .OBJ of a later
   
 date/time.  This process of checking the disk for a newer .OBJ
   
 can slow down the dynamic-link process.  If you are certain
   
 that there are no .OBJ files that have been updated, then a
   
 .TRUE. value for (lSpeed) can improve performance.
   

   

Description:

Examples:

    // main startup procedure
   

   
 DC_LINKINIT( 80 )   // allocate 80k to the dynamic-link pool.
   
 do main
   

   

Source/Library:

dc_locate()

Get value of last LOCATE expression for current work area

Syntax:

Arguments:

    Sorry but this function no longer works with 5.2 so is no longer
   
 supported.
   

   

Source/Library:

See Also:

dc_locaterec()

Pop-up a user dialogue for locating a record

Syntax:

Arguments:

    (nRow) is the starting display row of the dialogue box.
   
 Default is Row 10.
   

   
 (aArray) is an array of character strings which are
   
 expressions to be evaluated for locating the desired value.
   
 This array may have a maximum length of 5.
   

   
 (xValue) is the default value to place in the dialogue
   
 box.  This will usually be an empty string if the value being
   
 located is a character value or a number 0 if the value being
   
 located is a numeric value.
   

   
 (cPrompt) is a message to prompt the operator.
   

   
 (lContinue) if .TRUE. will continue the last locate and will
   
 not prompt the operator, otherwise the operator will be
   
 prompted for input and the locate will start at the top of
   
 file.
   

   

   

Returns:

    A logical .TRUE. if a record was found that matches
   
 the conditions.
   

   

Description:

Examples:

    aLocateArray := { ;
   
   'UPPER(appt_text)',;
   
   'UPPER(cal_memo),';
   
   'UPPER(agenda)' }
   
 cLocate := PAD(cLocateText,40)
   
 IF DC_LOCATEREC( 10, aLocateArray, @cLocate, "Text to Locate" )
   
   // Edit record
   
 ENDIF
   

   

Source/Library:

See Also:

dc_lockedrec()

Reports the number of the current locked record

Syntax:

Arguments:

    (nArea) is the work area.  If no argument is given, then the
   
 currently selected work area will be used.
   

   

Returns:

    The record number (numeric value) of the currently locked record.
   
 If no record is currently locked then 0 is returned.
   

   

Description:

Examples:

    nLockedRec := DC_LOCKEDREC()
   
 do something
   
 if nLockedRec ) 0
   
   goto nLockedRec
   
   dc_reclock()
   
 endif
   

   

Source/Library:

dc_lockmaint()

Maintain the "Lock" definition database

Syntax:

Arguments:

    (lPickList) if .TRUE. will return the lock number from the
   
 selected record when the (ENTER) key is pressed.  If .FALSE.,
   
 (default) then the (ENTER) key will be used to edit the
   
 current record.
   

   

Returns:

    A character string of three (3) characters representing the
   
 "lock" selected from the pick-list.
   

   

   

Description:

Examples:

    DC_LOCKMAINT()
   

   

Source/Library:

See Also:

dc_log()

Write status of work areas, environment, etc. to Log file

Syntax:

Arguments:

    (cProcName) is the current procedure name.
   

   
 (nLineNmbr) is the current line number.
   

   
 (cInfo) is an information string.
   

   
 (cFileName) is the name of the file to write.
   

   
 (lOverWrite) if .TRUE. will overwrite (cFileName), if .FALSE.
   
 will append the information.
   

   
 (nLastKey) is the last key hit value to include in the logged
   
 data. If no argument is given then LASTKEY() is default.
   

   
 (cCurrScreen) is the Screen contents you want to include in the
   
 logged data.  If no argument is given then the current screen
   
 contents is default.
   

   

Returns:

    NIL
   

   

Description:

Examples:

    FUNCTION error ( cMessage )
   

   
 save screen to cCurrScreen
   
 cProc := procname(1)  // proc name of calling procedure
   
 nLine := procline(1)  // line number of calling procedure
   

   
 DC_LOG( cProc, nLine, cMessage, "MYERR.LOG", .F., LASTKEY(),;
   
         cCurrScreen )
   

   

Source/Library:

See Also:

dc_mapadd()

Add an .OBJect to a Map file

Syntax:

Arguments:

    (cMapFileName)  is the name of Map file to modify or create.
   
 If no extension given then .LST will be appended.
   

   
 (cProcName) is the name of Source (.PRG) file which contains
   
 the functions or procedures.
   

   
 (cFunction1) - (cFunctionN) is a list of functions which exist
   
 in (cProcName).PRG.
   

   

Returns:

    NIL
   

   

Description:

Examples:

    If the file TEST.LST exists with the following map information:
   

   
  JUNK1 JUNK2 #junk
   

   
 Then the following code:
   

   
  DC_MAPADD('junk','morejunk','morejunk1','morejunk2')
   

   
 will create the new contents:
   

   
  JUNK1 JUNK2 #junk
   
  MOREJUNK1 MOREJUNK2 #morejunk
   

   

Source/Library:

dc_mapbuild()

Pop-up a user-menu for creating a new Map (.LST) file

Syntax:

Arguments:

    NONE
   

   

Description:

Source/Library:

dc_mapcreate()

Create a Map (.LST) file by scanning .PRG/.OBJ files

Syntax:

Arguments:

    (cMapFile) is the name of the map file to create.  If no
   
 extension is given, then .LST is assumed.
   

   
 (cWildcard) will define a subset of files in the current
   
 directory to scan.   If neither a (list file) or (wildcard)
   
 argument is given, then all .OBJs in the current directory or
   
 directory identified by the SET ODIR command will be scanned,
   
 or all .PRGs in the current directory or directory identified
   
 by the SET PDIR command will be scanned.
   

   
 (cListFile) specifies the name of an ASCII text file with a
   
 listing of the files to scan.  The list file is constructed as
   
 follows:
   

   
   MAIN.OBJ
   
   MYFUNCS.OBJ
   
   MYPROCS.OBJ
   

   
   or
   

   
   MAIN.PRG
   
   MYFUNCS.PRG
   
   MYPROCS.PRG
   

   
 (lTypeObj) if .TRUE. (default) specifies that the files to scan
   
 are clipper-compiled .OBJ files.  If .FALSE. specifies that the
   
 files to scan are clipper source code .PRG files.
   

   

Description:

Examples:

    DC_MAPCREATE( 'demo.lst','*.OBJ',,.t. )
   
 dc_mapload( 'demo.lst' )
   
 where calc
   
 demo1
   

   

Source/Library:

dc_maplist()

Display a listing of open map files

Syntax:

Arguments:

     NONE
   

   

Description:

Source/Library:

dc_mapload()

Load a Map (.LST) cross-reference file into memory

Syntax:

Arguments:

    (cMapFileName) is the name of the map file to load.  If no
   
 extension is used, then .LST is assumed.
   

   
 A map file is an ASCII text file that can be created with the
   
 DC_MAPCREATE() function, MAP CREATE command, or any text editor.
   
 A map file has the following structure:
   

   
 (func1) (func2) (func3) .... (funcN) #(source1)
   
 (proc1) (proc2) (proc3) .... (proc4) #(source2)
   

   
 Example of a map file:
   

   
 CALC GRAPH __GRSUBTOT #DEMO1
   
 MAINMENU CUSTOMERS INVOICES SALES #APPS
   
 POP_MENU SUB_MENU EXPL_MENU #MENUS
   

   

Description:

Source/Library:

dc_mapstring()

Return all Map (.LST) files loaded as a string

Syntax:

Arguments:

    NONE
   

   

Description:

Examples:

    dc_mapunld('ALL')
   
 ? DC_MAPSTRING()
   

   
 dc_mapload('DEMO')
   
 ? DC_MAPSTRING()
   
 $$$DEMO.LST
   
 DEMO SCRN  #DEMO
   
 DEMO1 CALC GRAPH GRSUBTOT  #DEMO1
   
 DEMO2 PAUSE CLEAR _QDOT  #DEMO2
   

   

Source/Library:

dc_mapunld()

Unload a map file from memory

Syntax:

Arguments:

    (cMapFileName) is the name of the map file to unload.
   

   
 "ALL" will unload all map files.
   

   

Returns:

    A logical .TRUE. if the map file was successfully unloaded.  If
   
 the map file had not been previously loaded, then .FALSE. is
   
 returned.
   

   

Description:

Source/Library:

dc_memcache()

Set the size of the cache used for Data-Dictionary arrays

Syntax:

Arguments:

    (nSize) is the amount of items to cache.
   

   
 IF (nSize) is -1, it will disable the feature of the data-dictionary
   
 system that checks for a function linked into the program and uses
   
 the function rather than the database.  For example, if a menu
   
 named TEST is requested with DC_MenuLoad(), a function named TEST_M()
   
 will be run to return the menu if it has been linked into the program.
   
 To disable this feature, call DC_MEMCACHE(-1) to override.  This
   
 can be put into DCLIP.SYS as !DC_MEMCACHE(-1).
   

   

Returns:

    A numeric value with the previous setting.
   

   

Description:

Source/Library:

dc_memmeter()

Display memory status on screen every second

Syntax:

Arguments:

    (lInstall) if .TRUE. will install the memory meter.  If
   
 .FALSE. the memory meter will be un-installed.
   

   
 (nStRow) and (nStCol) are the screen display coordinates.
   
 The default coordinates are 0,0.
   

   

Returns:

    nil
   

   

Description:

Source/Library:

dc_memo() *

Edit a string/memo field with text editor

Syntax:

Arguments:

    (cMName) is the Memo database field or variable name (in
   
 quotes).
   

   
 (nStrow) is the Top row of text area.
   

   
 (nStcol) is the Left column of text area.
   

   
 (nEnrow) is the Bottom row of text area.
   

   
 (nEncol) is the Right column of text area.
   

   
 (lEditMemo) if .TRUE. will Edit the text with Clipper
   
 MEMOEDIT() .FALSE. will View the text.  Operator is allowed to
   
 scroll through the text with the Up/Down arrow and PgUp/PgDn
   
 keys.
   

   
 (lSaveScreen) if .TRUE. will Save screen and restore after
   
 exiting view/edit.  .FALSE. will leave box and text on screen
   
 after exiting.
   

   
 (lDispHelp) if .TRUE. will display a one-line help line below
   
 the box to prompt operator of his options:
   

   
       Up Down PgUp PgDn Edit Print
   

   
 .FALSE. will display no help
   

   
 (cBoxCode) is a Box Code to identify type of box to draw around
   
 text:
   
          D = Double line
   
          S = Single line
   
          C = Special Character
   
      SPACE = No box
   

   
 (cBoxChar) is a Box Character to be drawn around text. Used
   
 only if (cBoxCode) is code C.  Valid box characters are 1-255.
   

   
 (cBoxColor) is the Box Color.  Must be valid Clipper Color
   
 String.
   

   
 (cTextColor) is the Text Color.  Must be valid Clipper Color
   
 String.
   

   
 (lMemv) if .TRUE. specifies that (cMName) is a memory variable
   
 name. .FALSE. specifies that (cMName) is a memo field name.
   
 This is required to update the current memo file in the event
   
 that the text is modified by the operator.
   

   
 (lProtect) if .TRUE. will protect the text from editing by
   
 operator.  .FALSE. will allow the operator to edit the text.
   

   
 (cMemoHeading is the title to display above the memo.
   

   
 (lWW) if .TRUE. will set WORD WRAP ON, .FALSE. will set WORD
   
 WRAP OFF
   

   
 (nLnNmbr) is the start line number to edit.
   

   

Returns:

    A logical .TRUE. if the memo was modified, .FALSE. otherwise.
   

   

Description:

Notes:

Source/Library:

dc_memoarray()

Return contents of memo array from last call to DC_MEMOBASE()

Syntax:

Arguments:

    (aMemo) if passed will store the contents of (aMemo)
   
 to the memo array.
   

   

   

   

Returns:

    (aOptions) is an array defining the memo window and options.
   

   
  Element  Type   Description
   
  -------  ----   -----------------------------------
   
   [1]      N     Top row of window
   
   [2]      N     Left column of window
   
   [3]      N     Bottom row of window
   
   [4]      N     Right column window
   
   [5]      L     .t. - Edit the text.
   
                  .f. - View the text only.  Operator is allowed to
   
                        scroll through the text with the Up/Down arrow
   
                        and PgUp/PgDn keys.
   
   [6]      L     .t. - Save screen and restore after exiting view/edit
   
                  .f. - Leave box and text on screen after exiting.
   
   [7]      L     .t. - Display a one-line help line below the box to
   
                        prompt operator of his options:
   
                        Up Down PgUp PgDn Edit Print
   
                  .f. - display no help
   
   [8]      C     Box Code to identify type of box to draw around text.
   
               "D" = Double line
   
                  "S" = Single line
   
                  "C" = Special Character
   
                  SPACE = No box
   
   [9]      N     Box Character to be drawn around text. Used only if
   
                  [2] is code "C".  Valid box characters are 1-255.
   
  [10]      C     Box Color.  Must be valid Clipper Color String.
   
  [11]      C     Text Color.  Must be valid Clipper Color String.
   
  [12]            Reserved
   
  [13]      L     .t. - If text is to be protected from editing by
   
                        operator.
   
                  .f. - If it is ok for operator to edit text.
   
  [14]      C     Memo heading
   
  [15]      L     .f. - If no word wrap
   
                  .t. - If word wrap
   

   

   

Description:

Examples:

    static aOptions
   
 local cSaveField
   
 if Valtype(aOptions) # 'M'
   
   aOptions := { ,,,,.t.,.t.,.t.,'S',0,;
   
                 'GR+','W/B',.f.,.f.,'Memo field:'+memo_field}
   
 endif
   
 cSaveField := dc_memobase( memo_field, aOptions )
   
 aOptions := DC_MEMOARRAY()
   
 if dc_memoupdate() .and. dc_reclock()
   
   replace memo_field with cSaveField
   
 endif
   

   

Source/Library:

See Also:

dc_memobase()

Edit a memo string with text editor

Syntax:

Arguments:

    (cMemo) is any character string.
   

   
 (aOptions) is an array defining the memo window and options.
   

   
  Element  Type   Description
   
  -------  ----   -----------------------------------
   
   [1]      N     Top row of window
   
   [2]      N     Left column of window
   
   [3]      N     Bottom row of window
   
   [4]      N     Right column window
   
   [5]      L     .t. - Edit the text.
   
                  .f. - View the text only.  User is allowed
   
                        to scroll through the text with the
   
                        Up/Down arrow and PgUp/PgDn keys.
   
   [6]      L     .t. - Save screen and restore after exiting
   
                        view/edit
   
                  .f. - Leave box and text on screen after
   
                        exiting.
   
   [7]      L     .t. - Display a one-line help line below the
   
                        box to prompt user of options:
   
                        Up Down PgUp PgDn Edit Print
   
                  .f. - display no help
   
   [8]      C     Box Code to identify type of box to draw
   
                  around text.                        "D" = Double line
   
                  "S" = Single line
   
                  "C" = Special Character
   
                  SPACE = No box
   
   [9]      N     Box Character to be drawn around text. Used
   
                  only if Element [2] is code "C".  Valid box
   
                  characters are 1-255.
   
  [10]      C     Box Color.  Must be valid Clipper Color
   
                  String.
   
  [11]      C     Text Color.  Must be valid Clipper Color
   
                  String.
   
  [12]            Reserved
   
  [13]      L     .t. - If text is to be protected from editing
   
                  by user.
   
                  .f. - If it is ok for user to edit text.
   
  [14]      C     Memo heading
   
  [15]      L     .f. - If no word wrap
   
                  .t. - If word wrap
   
  [16]      C     Menu Color.  Must be valid Clipper color
   
                  string.
   
  [17]      C     Menu Hotkey Color.  Must be valid Clipper color
   
                  string.
   
  [18]      N     Text buffer row
   
  [19]      N     Text buffer column
   
  [20]      N     Window buffer row
   
  [21]      N     Window buffer column
   
  [22]      L     Menu Option - .TRUE.= menu on top,
   
                                .FALSE. = menu on bottom
   
  [23]      L     Updated flag (read only)
   
  [24]      L     If .TRUE. will exit after displaying memo, if
   
                  .FALSE. will wait for a key or mouse click.
   
  [25]      N     Abort key number to stuff into keyboard buffer
   
                  if mouse clicked outside window area.  0 if none.
   
                  Default is K_ESC.
   
  [26]      L     If .TRUE. will start in full screen (zoom) mode.
   
                  Default is .false.
   
  [27]      L     If .TRUE. will paint scroll-bars.  Default is
   
                  .false.
   
  [28]      L     If .TRUE. will paint a ruler.  Default is .false.
   
  [29]      L     If .TRUE. will start in INSERT mode (default),
   
                  otherwise will start in whichever mode was set by
   
                  system.
   

   
 (nLineNmbr) is the line number to place the cursor.
   

   
 (lClearKeys) if .TRUE. (default) will clear all set keys and
   
 restore them after exiting.
   

   

Returns:

    A character string containing the modified text.
   

   

Description:

Notes:

Examples:

    static aOptions
   
 local cSaveField
   
 if Valtype(aOptions) # 'M'
   
   aOptions := { ,,,,.t.,.t.,.t.,'S',0,;
   
                 'GR+','W/B',.f.,.f.,'Memo field:'+memo_field}
   
 endif
   
 cSaveField := DC_MEMOBASE( memo_field, aOptions )
   
 aOptions := dc_memoarray()
   
 if dc_memoupdate() .and. dc_reclock()
   
   replace memo_field with cSaveField
   
 endif
   

   

Source/Library:

See Also:

dc_memocopy()

Copy a memo field from one database to another

Syntax:

Arguments:

    (cToField) - The name of the memo field in the currently selected
   
 database to copy to.
   

   
 (cFromField) - The name of the memo field in the import database
   
 to copy from.
   

   
 (cFromRef) - The name of any other field in the import database to
   
 use as a reference in the browse-screen that is displayed to choose
   
 the memo to copy.
   

   
 (cWorkGroup) - The name of the file group in DCFILES to use to select
   
 or open a file for importing from.
   

   
 (nRecord) - The record number of the import file containing the memo
   
 to copy.
   

   
 (cAppMode) - The append mode.  A - Append (default), I - Insert,
   
 R - Replace.
   

   
 (cInsertText) - Optional text to insert at the beginning of the
   
 memo being copied.
   

   
 (cAppendText) - Optional text to insert at the end of the memo
   
 being copied.
   

   
 If any of the first four parameters are not passed, then a dialog
   
 screen will appear allowing the user to enter this information.
   

   

Returns:

    A logical .TRUE. if the copy was successful.
   

   

Description:

Source/Library:

See Also:

dc_memoedit()

A mouseable replacement for MEMOEDIT()

Syntax:

Arguments:

    The first thirteen (13) arguments are identical to the thirteen
   
 (13) arguments passed to MEMOEDIT().  See the Clipper
   
 documentation for information on using MEMOEDIT().
   

   
 (aButtons) is a multi-dimensional array with coordinates and
   
 Keyboard Codes, Inkey values or Code Blocks for establishing
   
 mouse buttons.  Each button in the main array is a sub-array of
   
 5 elements:
   

   
 Element   Type   Description
   
 -------   ----   ---------------------------------
   
   1        N     Top Row of button
   
   2        N     Left Column of button
   
   3        N     Bottom Row of button   (optional)
   
   4        N     Right Column of button (optional)
   
   5        C     Keyboard character to stuff
   
          or N    Keyboard Inkey value to stuff
   
          or B    Code block to evaluate
   

   
 If Element 3 is a NIL, then the value of Element 1 will be
   
 used.
   

   
 IF Element 4 is a NIL, then the value of Element 2 will be
   
 used.
   

   
 (lStuff) if .TRUE. (default) will stuff the keyboard character
   
 into the keyboard buffer if the mouse was clicked in the button
   
 coordinate area defined by elements 1-4.  If .FALSE. the value
   
 of element 5 will be returned only, not stuffed in the
   
 keyboard.
   

   
 (nAbort) is the inkey value to stuff in the keyboard buffer
   
 if the mouse is clicked outside the memo editing area.
   

   
 (nClick) is the inkey value to stuff in the keyboard buffer
   
 if the mouse is double-clicked.
   

   

Returns:

    The modified text ( a Character value ).
   

   

Description:

Examples:

    func myedit (cText)
   

   
 local aButtons := { { 21,14,21,21,K_ALT_I},;
   
                     { 21,23,21,28,K_ALT_B},;
   
                     { 21,30,21,40,K_ALT_U} }
   
 set key K_ALT_I to myfunc
   
 set key K_ALT_B to myfunc
   
 set key K_ALT_U to myfunc
   
 cls
   
 @ 2,10 TO 21,70
   
 @21,13 say '| Insert | Bold | Underline |'
   
 cText := DC_MEMOEDIT( cText,3,11,20,69,.t.,,,,,,,,aButtons )
   
 set key K_ALT_I to
   
 set key K_ALT_B to
   
 set key K_ALT_U to
   
 return cText
   

   
 function myfunc
   

   
 do case
   
   case lastkey() = K_ALT_I
   
     keyboard chr(K_INSERT)
   
   case lastkey() = K_ALT_B
   
     keyboard '~B'
   
   case lastkey() = K_ALT_U
   
     keyboard '~U'
   
 endcase
   
 return nil
   

   

Source/Library:

See Also:

dc_memoeval()

Post a code block to be evaluated while in memo editor

Syntax:

Arguments:

    (bKeyEval) is a code block to evaluate.
   

   

Returns:

    The last code block that was posted.
   

   

Description:

Examples:

    DC_MEMOEVAL( {||DevPos(0,0),DevOut(TIME()) } )
   
 cMemo := dc_memobase( cMemo )
   

   

Source/Library:

See Also:

dc_memoformat()

Format a memo to a specified text width

Syntax:

Arguments:

    (cMemo) is the character string or memo to format.
   

   
 (nLength) is the new length of the text.
   

   

Returns:

    A character string memo reformatted with CR/LF's at the end of
   
 each line.
   

   

Description:

Examples:

    use myhelp
   
 // format MEMO field to 60 columns
   
 do while !eof()
   
   replace memo with dc_memoformat(memo,60)
   
 enddo
   

   

Source/Library:

dc_memoimp()

Import/Export text file(s) to memo field(s)

Syntax:

Arguments:

    NONE
   

   

Returns:

    A logical .TRUE. if exited normally, .FALSE. if aborted by user.
   

   

Description:

Source/Library:

See Also:

dc_memoin()

Import a text file into a character/memo field

Syntax:

Arguments:

    (cFieldName) is the name of the memo field of the currently
   
 selected work area to import to.
   

   
 (cTextFile) is the name of the text file to import.  If left
   
 blank, then a window will pop up to prompt for the name of the
   
 file.
   

   
 (cImportMode) is a  single character which will designate how
   
 the import is to be accomplished.
   

   
   "R" -  REPLACE:  will replace the current contents of the
   
          memo field with the contents of the text file.
   

   
   "I" -  INSERT:   will insert the contents of the text file
   
          ahead of the current contents of the memo field.
   

   
   "A" -  APPEND:   will append the contents of the text file to
   
          the current contents of the memo field.  (Default).
   

   
 (cMessage) is a one-line message to display in the window.  If
   
 no parameter is passed, then a default message will be displayed.
   

   

Description:

Examples:

    use dchelp
   
 dc_memoin( 'EXAMPLES', 'EXAMPLES.PRG','A' )
   

   

Source/Library:

See Also:

dc_memoout()

Export a memo/character field to a text file

Syntax:

Arguments:

    (cFieldName) is the name of the memo field of the currently
   
 selected work area to export.
   

   
 (cTextFile) is the name of the text file to export to.  If left
   
 blank, then a window will pop up to prompt for the name of the
   
 file.
   

   
 (cExportMode) is a  single character which will designate how
   
 the export is to be accomplished.
   

   
   "R" -  REPLACE:  will replace the current contents of the
   
          text file with the contents of the memo field.
   

   
   "I" -  INSERT:   will insert the contents of the memo field
   
          ahead of the current contents of the text file.
   

   
   "A" -  APPEND:   will append the contents of the memo field
   
          to the current contents of the text file.  (Default).
   

   
 (cMessage) is a one-line message to display in the window.  If
   
 no parameter is passed, then a default message will be displayed.
   

   

Description:

Examples:

    use dchelp
   
 dc_memoout( EXAMPLES, 'EXAMPLES.PRG','I' )
   

   

Source/Library:

See Also:

dc_memoprnt()

Print a memo field and optionally merge data

Syntax:

Arguments:

    (cMemoField) is any character string or database memo field.
   

   
 (nLeft), (nRight), (nTop), (nBottom) are the left, right, top
   
 and bottom print margins respectively.
   

   
 (nLines) is the number of lines to print per page.
   

   
 (nStart) is the line number to start printing.
   

   
 (nTab) is the number of spaces for a TAB character.
   

   
 (cHeader) is a heading to print at the top of each page.
   

   
 (cFooter) is a footing to print at the bottom of each page.
   

   
 (cOutFile) is the name of a file to output to.  To output to
   
 the printer enter "PRN" or "LPT".  If no argument is given, the
   
 output will go to the screen.
   

   
 (lEjectPaper) if .TRUE. (default) will eject the paper after
   
 printing.
   

   
 (lDataMerge) if .TRUE. will replace all occurrences of merge
   
 codes with the information defined by the codes.  If .FALSE.
   
 (default), the text will be printed as entered.
   

   
 (lAllRecords) if .TRUE. will print for all records in the
   
 database starting at the current record, otherwise only the
   
 current record will be printed. NOTE: This parameter is
   
 intended to be used for skipping through the database that is
   
 being "merged" with the memo text, NOT the database that
   
 contains the memo text.
   

   

Description:

Notes:

Examples:

    do while !Eof() .AND. dc_pready() .AND. lastkey()#27
   
   DC_MEMOPRNT( memo, 0, 79, 0, 0, 55, 0,
   
                4, '', '', 'PRN', .t., .t., .f. )
   
   skip
   
 enddo
   

   

Source/Library:

See Also:

dc_memotrim()

Trim all trailing spaces and trailing blank lines from a memo

Syntax:

Arguments:

    (cMemo) is any character string.
   

   

Returns:

    A character string containing the modified text.
   

   

Description:

Source/Library:

dc_memoupdated()

Was memo text modified by DC_MEMOBASE()?

Syntax:

Arguments:

    NONE
   

   

Returns:

    A logical .TRUE. if the text was modified.
   

   

Description:

Examples:

    local cSaveField
   
 local aOptions := { ,,,,.t.,.t.,.t.,'S',0,;
   
                 'GR+','W/B',.f.,.f.,'Memo field:'+memo_field}
   
 cSaveField := dc_memobase( memo_field, aOptions )
   
 if dc_memoupdated() .and. dc_reclock()
   
   replace memo_field with cSaveField
   
 endif
   

   

Source/Library:

See Also:

dc_menu_p()

A nested, moused pull-down menu-system

Syntax:

Arguments:

    (nRow) is the upper-left row (for pull-downs), or lower-left
   
 row (for pop-up menus).
   

   
 (nCol) is the upper-left column (for pull-downs), or lower-left
   
 column for pop-up menus).
   

   
 (cTitle) is an Optional title to be displayed centered on the
   
 top or bottom line of the box (depending on if it's a pull-down
   
 or a pop-up box.)  If no title is desired use a null string
   
 ("").
   

   
 (cColor) is a single string of 5 colors (separated by
   
 commas) to be used for the frame, menu items, hi-lited letters,
   
 select bar, grayed items respectively.  If no argument is
   
 passed, then the dCLIP default colors will be used.
   

   
 (cType) is a single character defining the type of menu:
   

   
    A - Pull-down menu
   
    B - Pop-up menu
   
    C - Plain menu, no borders (default)
   

   
 (lBar)  if .TRUE. (default) will make the menu resemble a
   
 MENU TO, with a select bar.  If you do not want a select bar,
   
 and just want the items to be chosen by pressing the hot-key
   
 letter only, set this to .FALSE.
   

   
 (lRetVal) if .FALSE. (default) will return the hot-key
   
 character of the selected menu item.  If .TRUE., the CHR()
   
 value of the menu choice will be returned.   For example, if
   
 the 4th menu item is selected, then CHR(4) will be returned.
   
 This parameter should also be set to .TRUE. if you are
   
 passing code-blocks to be evaluated and want to return from
   
 the menu after evaluating the code-block.
   

   
 (nStart) is a numeric or character value to determine which
   
 element to start on.  If the type is numeric, then the starting
   
 element is the number, if the type is character then the
   
 starting element is the first item whose highlighted character
   
 matches the (nStart) character.  The number of the menu item
   
 selected will be stored in the value referenced by @(nStart).
   

   
 (aPrompt) is an array of menu prompts to be displayed.  The
   
 first letter of each menu item will be hilited and will be
   
 designated as that menu item's "hot-key".  If a different
   
 hot-key letter is desired for a item, precede the desired
   
 hot-key letter with a tilde (~).   If the item is a
   
 "gray-scale" item (i.e. it displays only but is not
   
 selectable), it must be preceded by an "*" character.  If the
   
 item is a separator line, it must be passed as an "@"
   
 character.  If the item is a separator line with a sub-title,
   
 then it must be passed as a "@" character plus the sub-title
   
 string. "Nesting" of sub-menus is accomplished by passing an
   
 array of sub-menu information rather than a character string.
   
 (aPrompt) may contain any mixture of character strings
   
 (single items) or arrays (nested items).  Selection of a
   
 nested item will pop-up a sub-menu.  To create nested items
   
 pass an array with the following structure:
   

   
  Element  Type   Description
   
  -------  ----   ---------------------------------
   
    [1]   C     Menu prompt
   
    [2]   A     Array of sub-menu items
   
    [3]   A     Array of sub-menu code-blocks (optional)
   
    [4]     A     Array of sub-menu messages (optional)
   
    [5]     A     Array of sub-menu help-codes (optional)
   

   
 (aBlocks) is an optional array of code blocks.  Must be one
   
 code block for each item in (aPrompt).  If a code block array
   
 is passed then the code block will be evaluated when the item
   
 is selected and the user presses enter.
   

   
 (aCoord) is an optional ragged array of Row/Column positions
   
 for each item in (aPrompts).  If a Row/Column array is not
   
 passed then the prompts will be placed vertically starting at
   
 (nRow) and (nCol).
   

   
 (aMsg) is an optional array of messages to be displayed for
   
 each item in (aPrompt).  Each item in this array is a
   
 character string which will be displayed in a box or a single
   
 line depending on the values in (aMsgOpt).
   

   
 (aMsgOpt) is an array of options on how to display the
   
 message for the selected prompt.
   

   
 Element Type  Description
   
 ------- ----- -----------------------------------------------
   
   [1]    N    Display Row if TYPE 0
   
   [2]    N    Display Column if TYPE 0 (-1 to center message)
   
   [3]    N    Message TYPE (0-Line, 1-Box, 2-Add to Pull-Down
   
   [4]    N    Start Row if TYPE 0,1 or Height if TYPE 2
   
   [5]    N    Start Column if TYPE 0,1 (-1 to center message)
   
               or Width if TYPE 2
   
   [6]    N    End Row if TYPE 1
   
   [7]    N    End Column if TYPE 1
   

   
 (cExit) is a string containing the character value of any
   
 keys that will exit the menu and return the pressed key value.
   
 The ESCape key always exits.  If any "exit key" is pressed that
   
 is not a menu item "hot key", then the key character value will
   
 be returned.
   

   
 (lRestScrn) if .TRUE. (default) will restore the previous
   
 screen after exiting the menu.  If .FALSE. the menu and
   
 highlighted selection will remain on the screen.
   

   
 (lShadow) if .TRUE. (default only if (cType) is "A") will
   
 display a shadow on the menu.
   

   
 (aMouse) is a multi-dimensional array of mouse-buttons
   
 to active outside the menu area.  See DC_MOUSEKEY() for
   
 specifications.
   

   
 (lSticky) is used to modify the behavior of DC_MENU_P() only
   
 when a selected item has an associated code-block.  If
   
 (lSticky) is true, the code-block will be evaluated while the
   
 menu is still displayed on the screen. If .FALSE., then the
   
 screen will be restored (only if (lRestoreScreen) is .TRUE.)
   
 followed by the evaluation of the code-block.
   

   
 (aHelp) is an optional array of Help-Codes for each prompt
   
 item in (aPrompts).  Each help-code is a character string
   
 of up to 15 characters in length which matches the value in
   
 the PROC_NAME field of the DCHELP.DBF database. The
   
 concatenated values in the DCHELP.DBF memo fields will be
   
 displayed in a memo window whenever the F1 key is pressed
   
 after selecting a prompt.  See the function DC_HELPF1() for
   
 more information on setting up context-specific help.
   

   

Returns:

    If (lReturnVal) is .FALSE. (default) the hot-key character of the
   
 selected menu item will be returned.  If (lReturnVal) is .TRUE.,
   
 the CHR() value of the menu choice will be returned.   For example,
   
 if the 4th menu item is selected, then CHR(4) will be returned.
   

   
 A null string is returned if the ESCape key is pressed.
   

   

Description:

Notes:

Examples:

    -- Example 1 --
   

   
 // This example demonstrates using DC_MENU_P() to return a
   
 // code letter based on a user menu selection
   

   
 local aPrompts, cMenuCode
   

   
 aPrompts :=  { 'Open File',;
   
                'Close File',;
   
                'Edit File',;
   
                'Save File',;
   
                'View File',;
   
                'Print File',;
   
                'Run Program',;
   
                'DOS ~Shell'  }
   

   
 cMenuCode := ;
   
   DC_MENU_P( 24, 28, ' File Options ', ;
   
     'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'B', .t., .f., 'O', ;
   
     aPrompts )
   

   
 do case
   
   case cMenuCode = 'O'
   
     openfile()
   
   case cMenuCode = 'C'
   
     closefile()
   
   case cMenuCode = 'E'
   
     editfile()
   
   case cMenuCode = 'S'
   
     savefile()
   
   case cMenuCode = 'S'
   
     viewfile()
   
   case cMenuCode = 'P'
   
     printfile()
   
   case cMenuCode = 'R'
   
     runexe()
   
   case cMenuCode = 'S'
   
     rundos()
   
 endcase
   
 return
   

   

   
 -- Example 2 --
   

   
 // This example demonstrates using DC_MENU_P() to execute a
   
 // code block  based on a user menu selection
   

   
 local aPrompts, aBlocks
   

   
 aPrompts :=  { 'Open File',;
   
                'Close File',;
   
                'Edit File',;
   
                'Save File',;
   
                'View File',;
   
                'Print File',;
   
                'Run Program',;
   
                'DOS ~Shell'  }
   

   
 aBlocks := { {||openfile()},;
   
              {||closefile()},;
   
              {||editfile()},;
   
              {||savefile()},;
   
              {||viewfile()},;
   
              {||printfile()},;
   
              {||runexe()},;
   
              {||rundos()}     }
   

   
 DC_MENU_P( 24, 28, ' File Options ', ;
   
   'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'B', .t., .f., 'O', ;
   
   aPrompts, aBlocks )
   

   
 return
   

   

   
 -- Example 3 --
   

   
 // This example shows how to "nest" sub-menus.
   
 // In the below example, selecting item 2 (File Options) of
   
 // the main menu will pop-up a sub-menu.  Selecting Item 1
   
 // (Delete a File) will pop-up another sub-menu.  Selecting
   
 // Item 2 (Binary File) will return "FDB".
   

   
 LOCAL aSubPrompt, aSubBlock, aMainPrompt, aSubSubPrompt
   

   
 aSubSubPrompt := {'ASCII File','Binary File','EXE File'}
   

   
 aSubPrompt := { ;
   
     {'Delete a file',aDelPrompt},;
   
      'Copy a file', ;
   
      'Move a file' }
   

   
 aSubBlock  := { , {||copyafile()}, {||moveafile()} }
   

   
 aMainPrompt := { ;
   
    'Edit Options',;
   
   {'File Options', aSubPrompt, aSubBlock },;
   
    'Search Options',;
   
    'Print Options' }
   

   
 cSelection := ;
   
  DC_Menu_P ( 10, 10, , , 'B', , , , aPrompt, , , , , , , , ,  )
   

   

Source/Library:

See Also:

dc_menu_to()

A moused replacement for MENU TO (__menuto())

Syntax:

Arguments:

    (nChoice) is the initial prompt to be highlighted.
   

   
 (nMsgRow) is the optional screen row to display messages when a
   
 prompt is selected.  If no argument is passed, then the row
   
 established by the SET MESSAGE environment variable will be
   
 used.
   

   
 (nMsgCol) is the optional screen column to display messages
   
 when a prompt is selected.  If no argument is passed, then the
   
 message will be displayed at column 0 unless the SET MESSAGE
   
 CENTER environment variable is active, then it will be centered
   
 in the message row.  If -1 is passed the message will be
   
 centered in the message row.
   

   
 (cColor) is an optional color string of two colors separated
   
 by commas.  The first color is the color of the unhighlighted
   
 items and the second color is the color of the highlighted
   
 item.  If no parameter is passed, then the current system color
   
 setting will be used.
   

   

Returns:

    The letter corresponding to the Hot-Key assigned to the menu item
   
 that was selected, a ( sign if the left arrow was pressed, a ) if
   
 the right arrow was pressed, or a null string if an error occured.
   

   

Description:

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:

See Also:

dc_menuaccel()

Process a menu Accelerator key

Syntax:

Arguments:

    (aAccelKeys) is a multi-dimensional array of Accelerator
   
 key data.  There is one sub-array for each accelerator key.
   
 This sub-array has the following structure:
   

   
 Element   Type   Description
   
 -------  -----  ----------------------------------------
   
   [1]       N    Inkey() value of Accelerator key
   
   [2]       B    Code block to evaluate.  Pass as a NIL
   
                  if NONE.
   
   [3]       N    Numeric value to post as the value
   
                  returned by DC_MENURETURN() if the
   
                  accelerator key is hit.
   

   

Returns:

    A logical value.
   

   

Description:

Examples:

    local aMenus, aSubMenus, aMainMenu, aMouseKeys, nMenu,;
   
       aAccelKeys
   

   
 aMenus :=  { 'File','Edit','View','Run' }
   

   
 aSubMenus :=  { { 'Open File    (Alt-N)',;
   
                   'Close File   (Alt-C)',;
   
                   'e~Xit to Dos (Alt-X)' },;
   
                 { 'Edit File    (Alt-D)',;
   
                   'Save File    (Alt-S)' },;
   
                 { 'View File    (Alt-Z)',;
   
                   'Print File   (Alt-P)' },;
   
                 { 'Run Program  (Alt-O)',;
   
                   'DOS ~Shell   (Alt-L)'},;
   
                 nil,nil,nil,nil,;
   
               { 101, 102, 103, 104, 105, ;
   
                 106, 107, 108, 109 } }
   

   
 aAccelKeys := { { K_ALT_N,,101 },;
   
                 { K_ALT_C,,102 },;
   
                 { K_ALT_X,,103 },;
   
                 { K_ALT_D,,104 },;
   
                 { K_ALT_S,,105 },;
   
                 { K_ALT_Z,,106 },;
   
                 { K_ALT_P,,107 },;
   
                 { K_ALT_O,,108 },;
   
                 { K_ALT_L,,109 } }
   

   
 aMainMenu := { 1, 3, 'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'BAD', ;
   
                .t., 'FO', { aMenus }, { aSubMenus }, 'X' }
   

   
 /* -- Paint the menu bar and get the mouse coordinates -- */
   
 DC_MENUMAIN( aMainMenu,.t.,@aMouseKeys )
   

   
 do while .t.
   

   
   nInkey := DC_Inkey(0)  /* -- Get  a key -- */
   
   cCode  := UPPER(CHR(nInkey))
   

   
   do case
   

   
     case nInkey = K_ESC
   
       exit
   

   
     /* -- mouse click -- */
   
     case nInkey (= -101  .AND. !Empty(DC_MouseKeys(aMouseKeys))
   

   
     /* -- Menu key was hit -- */
   
     case cCode $ 'FEVR' .OR. DC_MENUACCEL( aAccelKeys, nInkey )
   

   
       IF DC_MenuReturn() = 0  /* -- Not an Accelerator -- */
   
         DC_MENUMAIN( aMainMenu,,,cCode )
   
       ENDIF
   
       nMenu := DC_MenuReturn(0)
   

   
       do case
   

   
         case nMenu = 101
   
           openfile()
   
         case nMenu = 102
   
           closefile()
   
         case nMenu = 103
   
           __Quit()
   
         case nMenu = 104
   
           editfile()
   
         case nMenu = 105
   
           savefile()
   
         case nMenu = 106
   
           viewfile()
   
         case nMenu = 107
   
           printfile()
   
         case nMenu = 108
   
           runexe()
   
         case nMenu = 109
   
           rundos()
   

   
       endcase
   

   
    endcase
   

   
 enddo
   
 return
   

   

   

Source/Library:

See Also:

dc_menuarray()

Create an array of mouse buttons for a single-line menu bar

Syntax:

Arguments:

    (nStartRow) is the display row to paint the menu bar and
   
 mouse buttons.
   

   
 (nStartCol) is the start display column to paint the menu bar
   
 and mouse buttons.
   

   
 (nEndCol) is the end display column.
   

   
 (cNormColor) is the normal color of the menu bar.
   

   
 (cHiliteColor) is the highlight color of menu items hot key
   
 letter for each item.
   

   
 (aItems) is an array of menu items to display
   

   
 (lDisplay) if .true. (default) will paint the menu bar on the
   
 screen.  If .false., then the items menu bar will not be
   
 displayed but the mouse-button array and menu string will still
   
 be returned.
   

   
 @(cMenuBar) is the name of the variable to store the string value
   
 of the menu.
   

   

Description:

Examples:

    local aMenus, cMenuBar, aMouseKeys
   

   
 aMenus := { ;
   
    'File ',;
   
    'Edit ',;
   
    'View ',;
   
    'Search ',;
   
    'Print ',;
   
    'Maint }
   

   
  aMouseKeys := ;
   
     DC_MENUARRAY( 0, 0, 79, , , aMenus, .f., @cMenuBar )
   

   

Source/Library:

See Also:

dc_menubar()

Paint a menu bar with key characters highlighted

Syntax:

Arguments:

    (nRow) and (nCol) are the screen coordinates to display the
   
 menu bar.
   

   
 (cColors) is a Normal and Highlight color string, separated by
   
 a comma.
   

   
 (cBarText) is the text which is to appear in the menu.
   
 Separate each menu item in Menu_String with a space.  By
   
 default, the first letter of each word in (cBarText) will be in
   
 the Highlight color unless another letter in that word is
   
 preceded by a tilde (~). Any letter in a word preceded by a
   
 tilde will be highlighted instead of the first letter.
   

   
 (lHide) if .TRUE. will hide the menubar from being displayed
   
 on the screen and will only return the screen contents.  If
   
 .FALSE. (default), then the menu bar will be displayed.
   

   

   

Returns:

    A character string which contains the screen contents of
   
 the menubar for later restoring the screen with RESTSCREEN().
   

   

Description:

Examples:

    DC_MENUBAR( 24, 0, "b/w,w+/w", " One Two T~hree Four F~ive " )
   

   

Source/Library:

See Also:

dc_menucompile()

Compile a Menu Array

Syntax:

Arguments:

    (aPreMenu) is a menu array that conforms to the
   
 specifications of the array returned by DC_MENUEDIT().
   

   
 (cCompileKeys) is an optional list of keys (3-digit
   
 character strings separated by commas).  Compile Keys are
   
 used for conditional compiling of menu items.  Conditional
   
 compiling allows for optionally excluding items from a
   
 menu that don't match one of the keys in the list.
   
 This allows for designing of menus that are similar but may
   
 have minor changes.  Conditional compiling reduces redundancy
   
 and keeps the DCMENU.DBF dictionary from growing too large.
   
 See DC_MENUEDIT() for more information.  If this parameter
   
 is not used, then all menu items will be compiled and
   
 included in the menu, otherwise, only the items in which
   
 the "Compile Key" is EMPTY or matches one of the keys in the
   
 list will be compiled.
   

   
 @(aAccelKeys) is a reference to store an array of Accelerator
   
 key data.  Accelerator keys are hot-keys that perform the
   
 same function as selecting the item from the menu, except
   
 that the menu is not painted.  This array is passed to
   
 DC_MENUACCEL() along with the value of the key that was hit.
   
 See DC_MENUACCEL() for a specification of this array.
   

   

Returns:

    A multi-dimensional array containing all information
   
 about a menu including prompts, sub-menus, message-text,
   
 help-codes, code-blocks, access codes, and return values.
   

   
 If the menu type is a Top-Bar Menu (Type A,B,C) then the
   
 array returned conforms to the specification for the array
   
 passed to DC_MENUMAIN().
   

   
 If the menu type is a Pull-Down Menu (Type P) then the
   
 array returned conforms to the specification for the array
   
 passed to DC_MENUPULL().
   

   

   

Description:

Examples:

    /* --- Load menu from menu-dictionary --- */
   
 aPreMenu := DC_MenuLoad( 'MAINMENU' )
   

   
 /* --- Compile menu --- */
   
 aMenuMain := DC_MENUCOMPILE( aPreMenu )
   

   
 /* --- Run Menu --- */
   
 cMenuString := DC_MenuRun( aMenuMain )
   

   
 /* -- Compile menu and include Conditional Items -- */
   
 aMenuMain := DC_MENUCOMPILE( aPreMenu, 'A**,B2*' )
   

   

   

Source/Library:

See Also:

dc_menudel()

Delete a menu in the Menu Dictionary

Syntax:

Arguments:

    (cMenuName) is the name of the menu.  This is a name of
   
 up to eight (8) digits.  If a menu name is passed then
   
 the DCMENU.DBF database will be searched and all menu
   
 items that match the menu name be deleted.
   

   
 If no name is passed, then a pick-list of all menus stored in
   
 the DCMENU.DBF database will be displayed.
   

   

   

   

   

Returns:

    A logical .TRUE. if the menu was successfully deleted.
   

   

Description:

Notes:

Source/Library:

See Also:

dc_menuedit()

A Complex Pull-Down-Menu Designer/Builder

Syntax:

Arguments:

    (cMenuName) is the name of the menu.  This is a name of
   
 up to eight (8) digits.  If a menu name is passed then
   
 the DCMENU.DBF database will be searched and all menu
   
 items that match the menu name be loaded into an array
   
 for editing. If no name is passed, then a pick-list of
   
 all menus stored in the DCMENU.DBF database will be
   
 displayed.  If none is chosen, then it will be assumed
   
 that you wish to create a new menu.
   

   

   

   

   

Returns:

    A multi-dimensional array consisting of 2 sub-arrays.
   
 This array is formatted in such a way to ease the
   
 process of browsing, storage and retreival.  Since
   
 code-blocks cannot be saved and restored a character
   
 string equivalent is included in this array for compiling
   
 by the DC_MENUCOMPILE() function.
   

   
 Element [1] Contains all global information about the menu:
   

   
 Element  Type   Contents
   
 ------- ----   -------------------------------------
   
  [1]      C     Name of the menu - Up to 8 digits
   
  [2]      C     A description of this menu
   
  [3]      C     Type of menu - 4 characters
   
                 Char 1 : A - Bar Menu (standard)
   
                          B - Bar Menu (boxed)
   
                          C - Bar Menu (underlined)
   
                          P - PullDown Menu
   
                 Char 2 : A - Size bar to Item Width
   
                          B - Size bar to Screen Width
   
                 Char 3 : U - Attached menus are Pull-Up
   
                          D - Attached menus are Pull-Down
   
                 Char 4 : M - MainLevel Heirarchy
   
                              (no nesting)
   
                          S - SubLevel Heirarchy (nested)
   
  [4]      N     Spaces between items on top menu bar
   
  [5]      C     A string of characters designating keys
   
                 which will exit the menu
   
  [6]      N     Start Top-Bar display row if Bar menu or
   
                 start display row if Pull-Down menu
   
  [7]      N     Start Top-Bar display column if Bar menu or
   
                 start display column if Pull-Down menu
   
  [8]      C     A string containing menu colors separated
   
                 by commas.  See DC_MENUMAIN() for specs.
   
  [9]      L     .T. - Sticky Menus (menu will stay on screen
   
                       when code-block evaluated.  Will return
   
                       to menu after evaluating code-block.
   
                 .F. - Normal Menus (screen will be restored
   
                       before evaluating code-block.
   
 [10]      L     Re-Display menu after evaluating code-block
   
 [11]      N     Message Display Option:
   
                 0 - 1 line of the display
   
                 1 - A boxed area of the display
   
                 2 - A box under each pull-down
   
 [12]      N     Start Row (Message Display Option 1) or
   
                 Box Height (Message Display Option 2)
   
 [13]      N     Start Column (Message Display Option 1) or
   
                 Box Width (Message Display Option 2)
   
 [14]      N     End Row (Message Display Option 1 only)
   
 [15]      N     End Column (Message Display Option 2 only)
   
 [16]      A     An optional array of Mouse Keys (see
   
                 DC_MOUSEKEY() for specs.
   

   
 Element [2] contains all the items in the menu:
   
 Each Item in Element [2] is a sub-array of 12 elements:
   

   
 Element  Type   Contents
   
 -------  ----   ----------------------------------------
   
  [1]      C     Level - This is a character string that
   
                 establishes the heirarchal level of the
   
                 menu or sub-menu.
   
  [2]      C     The title of the menu item.  Enter a
   
                 tilde (~) character in front of the hot-key
   
                 character to be high-lighted.
   
  [3]      C     A character-string representation of any
   
                 code-block to be compiled and evaluated.
   
                 The menu item will be "grayed" and
   
                 unselectable if the evaluated code block
   
                 returns a .FALSE.  The menu item will be
   
                 selectable if this element is left blank
   
                 or the evaluated code block returns a .TRUE.
   
  [4]      B     The code-block that has been compiled from
   
                 element 3.
   
  [5]      C     A character string containing the message
   
                 or long description to be displayed in the
   
                 message area of the selected menu item.
   
  [6]            (reserved)
   
  [7]      C     A character-string representation of any
   
                 code-block to be compiled and evaluated.
   
                 The code block will be evaluated when the
   
                 menu item is selected.  If this element is
   
                 left blank, then no code block will be
   
                 executed and the selected menu(s) will be
   
                 returned as a string.
   
  [8]      B     The code-block that has been compiled from
   
                 element 7.
   
  [9]      C     A string that is passed to the HELP procedure
   
                 as the fourth (4th) parameter when the F1
   
                 key is pressed.  This can be used as a help
   
                 code to pop-up additional help for this
   
                 menu item.
   
  [10]     C     Access key for this menu.  Access key list
   
                 assigned to logged on user() must contain this
   
                 key or a wildcard to access this menu. If
   
                 element is left blank then menu item is
   
                 accessible by everyone.
   
  [11]     N     Return value to save to a static value when
   
                 this item is selected.  See DC_MenuReturn().
   
  [12]     C     Compile key for this menu.  Compile key list
   
                 passed to DC_MENUCOMPILE() must contain this
   
                 key or a wildcard to compile this item. If
   
                 element is left blank then the menu item will
   
                 be compiled regardless of the key list that is
   
                 passed.
   

   

Description:

Notes:

Examples:

    /* -- Edit the Main Menu -- */
   
 aPreMenu := DC_MENUEDIT( 'MAINMENU' )
   

   
 /* -- Compile the menu -- */
   
 aMenuMain := DC_MenuCompile( aPreMenu )
   

   
 /* -- Run the menu -- */
   
 DC_MenuMain( aMenuMain )
   

   

Source/Library:

See Also:

dc_menuimp()

Import Menu(s) from the Import Menu-Dictionary

Syntax:

Arguments:

    (cMenuName) is the name of the menu.  This is a name of
   
 up to eight (8) digits.  If a menu name is passed then
   
 the DXMENU.DBF database will be searched and all menu
   
 items that match the menu name be imported into DCMENU.DBF.
   
 If no name is passed, then a pick-list of all menus stored
   
 in the DXMENU.DBF database will be displayed.
   

   
 If "ALL" is passed as the menu name, then all menus in the
   
 DXMENU.DBF will be imported into DCMENU.DBF.
   

   

Returns:

    A logical .TRUE. if the menu was imported successfully.
   

   

   

   

Description:

Notes:

Source/Library:

See Also:

dc_menuload()

Load a Menu from the Menu-Dictionary

Syntax:

Arguments:

    (cMenuName) is the name of the menu.  This is a name of
   
 up to eight (8) digits.  If a menu name is passed then
   
 the DCMENU.DBF database will be searched and all menu
   
 items that match the menu name be loaded into an array.
   
 If no name is passed, then a pick-list of all menus stored
   
 in the DCMENU.DBF database will be displayed.
   

   
 (cMenuName) is the name of the menu configuration to
   
 load (up to 8 characters).  If no parameter is passed, then
   
 a pick-list of all Menus in the DCMENU.DBF dictionary will
   
 be displayed.
   

   
 (cMode) is a single character designating the source:
   
   A - From an Array File.  If this option is chosen then
   
       the file named (cMenuName).DCM will be used to load the
   
       array (if it exists).
   
   F - From a Function.  If this option is chosen then the
   
       function (cMenuName)_M() will be called to get the
   
       array (if it exists).
   
   D - From the DCMENU.DBF dictionary.  A Menu Configuration
   
       with the Tag Name (cMenuName) will be loaded into the
   
       array (if it exists).
   
   NONE - If no parameter is passed, then the array will be
   
   loaded first from the function (cMenuName)_M(), if it
   
   exists, and secondly from the file (cMenuName).DCM if it
   
   exists, and thirdly from the DCMENU.DBF dictionary.
   

   
 (lCache) if .TRUE. (default) will save the menu to a static
   
 cache so the next time it is requested it will be reloaded
   
 from the cache for faster speed.  If .FALSE. or if the
   
 DC_MEMCACHE() setting is 0, then it will not be saved to the
   
 static array.
   

   
 (cType) is a character string designating the types of menus
   
 to display in the pick-list of menus that will be displayed
   
 (if no (cMenuName) is passed, or if the menu does not exist).
   
 The default it all types (ABCP).
   

   
 (cTitle) is the title to display on the pick-list of menus
   
 to display (if no (cMenuName) is passed, or if the menu does
   
 not exist).  The default is "Pick a Menu to Load".
   

   
 (lImport) if .TRUE. will attempt to load the menu from a
   
 dictionary file named DXMENU.DBF rather than the standard
   
 dictionary named DCMENU.DBF.
   

   

Returns:

    A multi-dimensional array that conforms to the
   
 specification of the array returned by DC_MENUEDIT().
   

   

   

   

Description:

Notes:

Examples:

    /* -- Load the Main Menu -- */
   
 aPreMenu := DC_MENULOAD( 'MAINMENU' )
   

   
 /* -- Compile the menu -- */
   
 aMenuMain := DC_MenuCompile( aPreMenu )
   

   
 /* -- Run the menu -- */
   
 DC_MenuMain( aMenuMain )
   

   

Source/Library:

See Also:

dc_menulock()

Lock all Menu items

Syntax:

Arguments:

    (lMenuLock) if .TRUE. will lock all menu items.  .FALSE. (default)
   
 will unlock all menu items unless a lock has been placed on the
   
 individual item.
   

   

Returns:

    A logical value containing the previous setting.
   

   

Description:

Notes:

Examples:

    /* -- Lock all Menus -- */
   
 DC_MENULOCK(.t.)
   

   

Source/Library:

See Also:

dc_menumain()

An "integrated" menu system with a bar and pull-downs

Syntax:

Arguments:

    Parameters may be passed separately or in an array.  If
   
 the first element is a Numeric value, then it is assumed
   
 that all data will be passed as separate parameters and
   
 the two optional parameters ( (lMenuBar) and (aMouseKeys) )
   
 are not supported.  This is provided for compatability with
   
 previous versions of dCLIP so existing applications will
   
 run without requiring source-code modifications.  It is
   
 recmmended that all parameters be passed in an array
   
 (aMenu) with the following structure:
   

   
 ---------------------------------------------------------
   

   
 Specification of (aMenu):
   

   
 Element  Type   Description (see below)
   
 ------- ----   -----------------------------------
   
   [1]     N     (nRow)
   
   [2]     N     (nCol)
   
   [3]     C     (cMenuColor)
   
   [4]     C     (cType)
   
   [5]     L     (lSelectBar)
   
   [6]     C     (cStart)
   
   [7]     A     (aMenus)
   
   [8]     A     (aSubMenus)
   
   [9]     C     (cExitKeys)
   
  [10]     L     (lReturnVal)
   
  [11]     N     (nSubMenu)
   
  [12]     N     (nSubSubMenu)
   
  [13]     A     (aMouseKeys)
   
  [14]     L     (lSticky)
   
  [15]     A     (aMsgOptions)
   
  [16]     L     (lReMenu)
   
  [17]     C     (cHeirArchy)
   

   

   
 (nRow) is the start display row
   

   
 (nCol) is the start display column
   

   
 (cMenuColor) is a single string of 5 colors (separated by
   
 commas) to be used for the frame, menu prompts, hi-lited
   
 letters, select bar, and "grayed" items respectively.
   

   
 (cType) is a 3-character string defining the type of menu bar:
   

   
    Char 1:  A - no box around menu bar (default)
   
             B - Single line box around menu bar
   
             C - Single line below menu bar
   
                 Double line above menu bar
   

   
    Char 2:  A - Size box to size of menu items (default)
   
             B - Size box to full screen width
   

   
    Char 3:  D - Pull-down menus
   
             U - Pop-up menus
   

   
 (lSelectBar) if .TRUE. (default) will make the menu resemble a
   
 MENU TO, with a select bar.  If you do not want a select bar,
   
 and just want the items to be chosen by pressing the hot-key
   
 letter only, set this to .FALSE.
   

   
 (cStart) is a 2-character string defining which menu item to
   
 pre-select.  The first character is the "high-lighted"
   
 character of the main menu.  The second character is the
   
 "high-lighted" character of the sub-menu.
   

   
 (aMenus) is a 2-dimensional array of top-bar menu prompts and
   
 optional code blocks.  The first letter of each menu item will
   
 be hilited and will be designated as that menu item's "hot-key".
   
 If a different hot-key letter is desired for a item, precede
   
 the desired hot-key letter with a tilde (~).   If the item is a
   
 "gray-scale" item (i.e. it displays only but is not
   
 selectable), it must be preceded by an "*" character. If the
   
 secondary array of code blocks is passed there must be one code
   
 block for each menu item in sub array 1.  If a code block array
   
 is passed then the code block will be evaluated before
   
 returning.
   

   
 (aSubMenus) is an array of two sub-arrays. There must
   
 be one sub-menu array for each (aMenu) prompt. The first
   
 sub-array consists of up to 6 parallel arrays:
   

   
  [1] - Prompts
   
  [2] - Code-Blocks
   
  [3] - Messages
   
  [4] - Help Codes
   
  [5] - Access Codes
   
  [6] - Return Values
   

   
 These arrays must conform to the specification for (aPrompts)
   
 in DC_MENUPULL(). The second (parallel) sub-array is an optional
   
 array of code-blocks which conforms to the specification for
   
 code blocks (aBlocks) in DC_MENUPULL().  Nesting sub-sub-menus
   
 from any one of the sub-menus is accomplished in the same
   
 manner as described in the documentation for DC_MENUPULL().
   

   
 (cExitKeys) is a string containing the character value of any
   
 keys that will exit the menu and return the pressed key value.
   
 The ESCape key always exits.  If any "exit key" is pressed that
   
 is not a menu item "hot key", then the key character value will
   
 be returned.
   

   
 (lReturnVal) if .FALSE. (default) will return the hot-key
   
 character of the selected menu item.  If .TRUE., the CHR()
   
 value of the menu choice will be returned.   For example, if
   
 the 4th menu item is selected, then CHR(4) will be returned.
   

   
 (nSubMenu) is the number of Pull down menu to select as the
   
 default.
   

   
 (nSubSubMenu) is the number of the SubMenu to select as the
   
 default)
   

   
 (aMouseKeys) is a multi-dimensional array of mouse-buttons
   
 to active outside the menu area.  See DC_MOUSEKEY() for
   
 specifications.
   

   
 (lSticky) is used to modify the behavior of DC_MENUMAIN() only
   
 when a selected item has an associated code-block.  If
   
 (lSticky) is true, the code-block will be evaluated while the
   
 menu is still displayed on the screen. If .FALSE. (default),
   
 then the screen will be restored followed by the evaluation of
   
 the code-block.
   

   
 (aMsgOptions) is an array of options on how to display the
   
 message for the selected prompt.
   

   
 Element Type  Description
   
 ------- ----- -----------------------------------------------
   
   [1]    N    Display Row if TYPE 0
   
   [2]    N    Display Column if TYPE 0 (-1 to center message)
   
   [3]    N    Message TYPE (0-Line, 1-Box, 2-Add to Pull-Down
   
   [4]    N    Start Row if TYPE 0,1 or Height if TYPE 2
   
   [5]    N    Start Column if TYPE 0,1 (-1 to center message)
   
               or Width if TYPE 2
   
   [6]    N    End Row if TYPE 1
   
   [7]    N    End Column if TYPE 1
   

   
 (lReMenu) is used to re-paint the menu after evaluating the
   
 code-block when a menu item is selected.  If .FALSE. and if
   
 (lSticky) is not .TRUE. then the menu will be exited after
   
 the code-block is evaluated.  Use this parameter in place of
   
 (lSticky) to restore the screen before evaluating the code
   
 block and then to repaint the menu after returning from the
   
 code block.
   

   
 (cHeirArchy) is a single character designating the heirarchal
   
 characteristics of the menu.
   

   
 ------------------------------------------------------------
   

   
 (lPaintBar) if .TRUE. will only paint the bar items on the
   
 screen and then return.  If .FALSE. (default), then the
   
 menu will be executed.
   

   
 (aMouseKeys) is a reference to store an array of mouse keys
   
 that match the items on the bar menu.  This parameter is
   
 used in conjunction with (lPaintBar) as a .TRUE. value to
   
 paint the menu-bar, store the coordinates to an array and
   
 then use that array to determine if the mouse was clicked
   
 on the menu bar area.
   

   

   

Returns:

    A character string with the "hot-key" value of the main menu
   
 and all sub-menus selected.  For example, if the "A" key was
   
 pressed to select an item in a sub-sub-menu that was selected
   
 from a sub-menu with the 'G' key that was selected from the
   
 top-bar menu with the "F" key, then "FGA" will be returned.
   

   

Description:

Notes:

Examples:

     -- Example 1 --
   

   
 /* This example demonstrates using DC_MENUMAIN() to return a
   
    code letter based on a user menu selection */
   

   
 local aMenus, aSubMenus, cMenuCode
   

   
 aMenus :=  { 'File','Edit','View','Run' }
   

   
 aSubMenus :=  { { 'Open File','Close File','e~Xit to Dos' },;
   
                 { 'Edit File','Save File' },;
   
                 { 'View File','Print File' },;
   
                 { 'Run Program','DOS ~Shell'} }
   

   
 cMenuCode := ;
   
   DC_MENUMAIN( { 1, 3, 'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'BAD', ;
   
                .t., 'FO', { aMenus }, { aSubMenus }, 'X' } )
   
 do case
   
   case cMenuCode = 'FX' .OR. lastkey()=K_ESC
   
     quit
   
   case cMenuCode = 'FO'
   
     openfile()
   
   case cMenuCode = 'FC'
   
     closefile()
   
   case cMenuCode = 'EE'
   
     editfile()
   
   case cMenuCode = 'ES'
   
     savefile()
   
   case cMenuCode = 'VS'
   
     viewfile()
   
   case cMenuCode = 'VP'
   
     printfile()
   
   case cMenuCode = 'RR'
   
     runexe()
   
   case cMenuCode = 'RS'
   
     rundos()
   
 endcase
   
 return
   

   

   
 -- Example 2 --
   

   
 /* This example demonstrates using DC_MENUMAIN() to execute a
   
    code block based on a user menu selection */
   

   

   
 local aMenus, aSubMenus, aSubBlocks
   

   
 aMenus :=  { 'File','Edit','View','Run' }
   

   
 aSubMenus :=  { { 'Open File','Close File','e~Xit to Dos' },;
   
                 { 'Edit File','Save File' },;
   
                 { 'View File','Print File' },;
   
                 { 'Run Program','DOS ~Shell'} }
   

   
 aSubBlocks := { { {||openfile()}, {||closefile()}, ;
   
                 { ||__quit()} },;
   
                 { {||editfile()}, {||savefile()} },;
   
                 { {||viewfile()}, {||printfile()} },;
   
                 { {||runexe()}, {||rundos()} } }
   

   
 do while .t.
   
   DC_MENUMAIN( { 1, 3, 'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'CAD', ;
   
                  .t., 'FO', ;
   
                  { aMenus }, { aSubMenus, aSubBlocks }, 'X' } )
   
 enddo
   
 return
   

   

   
 -- Example 3 --
   

   
 /* This example demonstrates loading a menu from the Menu
   
    Dictionary file and passing it to DC_MENUMAIN() for
   
    execution */
   

   
 local aPreMenu, aMenuMain, cMenuCodes
   

   
 aPreMenu := DC_MenuLoad( 'MAINMENU' )
   
 aMainMenu := DC_MenuCompile( aPreMenu )
   
 cMenuCodes := DC_MENUMAIN( aMainMenu )
   

   

   
 -- Example 4 --
   

   
 /* See the _DCBROW3.PRG source code file for an example of
   
    building a complex menu using source-code */
   

   

   
 -- Example 5 --
   

   
 /* This examples demonstrates using DC_MENUMAIN() in a
   
    loop, where the menu is attached to the top of a window */
   

   

   
 local aMenus, aSubMenus, cMenuCode, aMainMenu, aMouseKeys
   

   
 aMenus :=  { 'File','Edit','View','Run' }
   

   
 aSubMenus :=  { { 'Open File','Close File','e~Xit to Dos' },;
   
                 { 'Edit File','Save File' },;
   
                 { 'View File','Print File' },;
   
                 { 'Run Program','DOS ~Shell'} }
   

   
 aMainMenu := { 1, 3, 'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'BAD', ;
   
                .t., 'FO', { aMenus }, { aSubMenus }, 'X' }
   

   
 /* -- Paint the menu bar and get the mouse coordinates -- */
   
 DC_MENUMAIN( aMainMenu,.t.,@aMouseKeys )
   

   
 do while .t.
   

   
   nInkey := DC_Inkey(0)  /* -- Get  a key -- */
   
   cCode  := UPPER(CHR(nInkey))
   

   
   do case
   

   
     case nInkey = K_ESC
   
       exit
   

   
     /* -- mouse click -- */
   
     case nInkey (= -101  .AND. !Empty(DC_MouseKeys(aMouseKeys))
   

   
     /* -- Menu key was hit -- */
   
     case cCode $ 'FEVR'
   

   
       cMenuCode := DC_MENUMAIN( aMainMenu,,,cCode )
   

   
       do case
   

   
         case cMenuCode = 'FO'
   
           openfile()
   
         case cMenuCode = 'FC'
   
           closefile()
   
         case cMenuCode = 'EE'
   
           editfile()
   
         case cMenuCode = 'ES'
   
           savefile()
   
         case cMenuCode = 'VS'
   
           viewfile()
   
         case cMenuCode = 'VP'
   
           printfile()
   
         case cMenuCode = 'RR'
   
           runexe()
   
         case cMenuCode = 'RS'
   
           rundos()
   

   
       endcase
   

   
    endcase
   

   
 enddo
   

   
 -- Example 6 --
   

   
 /* -- See DC_MENUACCEL() example for an example of using
   
    DC_MENUMAIN() with accelerator keys and an array of
   
    numeric return values -- */
   

   

Source/Library:

See Also:

dc_menupick()

Pop-up a pick-list of all Menus in Menu Dictionary

Syntax:

Arguments:

    None.
   

   

Returns:

    A character string of up to 8 characters.
   

   

   

Description:

Examples:

    /* This example demonstrates how to use DC_MENUPICK()
   
    to pop-up a pick-list of Menus in a GET */
   

   
 #include 'dcget.ch'
   

   
 LOCAL cMenuName := SPACE(8)
   
 @ 10,10 say 'Enter Menu Name ' GET cMenuName ;
   
   VALID DC_ReadClick( cMenuName, {|k|DC_KEYPICK()} ) ;
   
   PICKLIST
   

   

Source/Library:

See Also:

dc_menupull()

A nested, moused pull-down menu-system

Syntax:

Arguments:

    (aMenus) is a multidimensional array of information about
   
 the pull-down menu.
   

   
 Element  Type  Description (See below)
   
 ------- ----  ----------------------------------
   
   [1]     N    (nRow)
   
   [2]     N    (nCol)
   
   [3]     C    (cTitle)
   
   [4]     C    (cColors)
   
   [5]     C    (cType)
   
   [6]     L    (lBar)
   
   [7]     L    (lRetVal)
   
   [8]     C    (cExitKey)
   
   [9]     L    (lRestScreen)
   
  [10]     L    (lShadow)
   
  [11]     L    (lSticky)
   
  [12]     L    (lReMenu)
   
  [13]     C    (cHeirArchy)
   
  [14]     A    (aMouseKeys)
   
  [15]     A    (aMsgOptions)
   
  [16]     A    (aRowCol)
   
  [17]     A    (aPrompts)
   
  [18]     A    (aPromptBlock)
   
  [19]     A    (aEvalBlocks)
   
  [20]     A    (aMessage)
   
  [21]     A    (aHelp)
   
  [22]     A    (aAccess)
   
  [23]     A    (aReturns)
   

   

   
 (nRow) is the upper-left row (for pull-downs), or lower-left
   
 row (for pop-up menus).
   

   
 (nCol) is the upper-left column (for pull-downs), or lower-left
   
 column for pop-up menus).
   

   
 (cTitle) is an Optional title to be displayed centered on the
   
 top or bottom line of the box (depending on if it's a pull-down
   
 or a pop-up box.)  If no title is desired use a null string
   
 ("").
   

   
 (cColors) is a single string of 5 colors (separated by
   
 commas) to be used for the frame, menu items, hi-lited letters,
   
 select bar, grayed items respectively.  If no argument is
   
 passed, then the dCLIP default colors will be used.
   

   
 (cType) is a single character defining the type of menu:
   

   
    A - Pull-down menu
   
    B - Pop-up menu
   
    C - Plain menu, no borders (default)
   

   
 (lBar)  if .TRUE. (default) will make the menu resemble a
   
 MENU TO, with a select bar.  If you do not want a select bar,
   
 and just want the items to be chosen by pressing the hot-key
   
 letter only, set this to .FALSE.
   

   
 (lRetVal) if .FALSE. (default) will return the hot-key
   
 character of the selected menu item.  If .TRUE., the CHR()
   
 value of the menu choice will be returned.   For example, if
   
 the 4th menu item is selected, then CHR(4) will be returned.
   
 This parameter should also be set to .TRUE. if you are
   
 passing code-blocks to be evaluated and want to return from
   
 the menu after evaluating the code-block.
   

   
 (cExitKey) is a string containing the character value of any
   
 keys that will exit the menu and return the pressed key value.
   
 The ESCape key always exits.  If any "exit key" is pressed that
   
 is not a menu item "hot key", then the key character value will
   
 be returned.
   

   
 (lRestScreen) if .TRUE. (default) will restore the previous
   
 screen after exiting the menu.  If .FALSE. the menu and
   
 highlighted selection will remain on the screen.
   

   
 (lShadow) if .TRUE. (default only if (cType) is "A") will
   
 display a shadow on the menu.
   

   
 (lSticky) is used to modify the behavior of DC_MENU_P() only
   
 when a selected item has an associated code-block.  If
   
 (lSticky) is true, the code-block will be evaluated while the
   
 menu is still displayed on the screen. If .FALSE., then the
   
 screen will be restored (only if (lRestoreScreen) is .TRUE.)
   
 followed by the evaluation of the code-block.
   

   
 (lReMenu) is used to re-paint the menu after evaluating the
   
 code-block when a menu item is selected.  If .FALSE. and if
   
 (lSticky) is not .TRUE. then the menu will be exited after
   
 the code-block is evaluated.  Use this parameter in place of
   
 (lSticky) to restore the screen before evaluating the code
   
 block and then to repaint the menu after returning from the
   
 code block.
   

   
 (cHeirArchy) is a single character designating the heirarchal
   
 characteristics of the menu.
   

   
   M - Main Level heirarchy.  This kind of menu will be
   
       executed at the same level as the calling menu rather
   
       than calling it as a sub-menu.  Use this option to
   
       prevent the user from blowing up the call stack.
   

   
   S - Sub Level heirarchy (Default).  This kind of menu will
   
       be called as a sub-level menu and will return to the
   
       previously called menu.
   

   
 (aMouseKeys) is a multi-dimensional array of mouse-buttons
   
 to active outside the menu area.  See DC_MOUSEKEY() for
   
 specifications.
   

   
 (aMsgOptions) is an optional array of options for determining
   
 where and how the message will be displayed.
   

   
 Element Type  Description
   
 ------- ----- -----------------------------------------------
   
   [1]    N    Display Row if TYPE 0
   
   [2]    N    Display Column if TYPE 0 (-1 to center message)
   
   [3]    N    Message TYPE (0-Line, 1-Box, 2-Add to Pull-Down
   
   [4]    N    Start Row if TYPE 0,1 or Height if TYPE 2
   
   [5]    N    Start Column if TYPE 0,1 (-1 to center message)
   
               or Width if TYPE 2
   
   [6]    N    End Row if TYPE 1
   
   [7]    N    End Column if TYPE 1
   

   
 (aRowCol) is an optional ragged array of Row/Column positions
   
 for each item in (aPrompts).  If a Row/Column array is not
   
 passed then the prompts will be placed vertically starting at
   
 (nRow) and (nCol).
   

   
 (aPrompts) is an array of menu prompts to be displayed.  The
   
 first letter of each menu item will be hilited and will be
   
 designated as that menu item's "hot-key".  If a different
   
 hot-key letter is desired for a item, precede the desired
   
 hot-key letter with a tilde (~).   If the item is a
   
 "gray-scale" item (i.e. it displays only but is not
   
 selectable), it must be preceded by an "*" character.  If the
   
 item is a separator line, it must be passed as an "@"
   
 character.  If the item is a separator line with a sub-title,
   
 then it must be passed as a "@" character plus the sub-title
   
 string. "Nesting" of sub-menus is accomplished by passing an
   
 array of sub-menu information rather than a character string.
   
 (aPrompts) may contain any mixture of character strings
   
 (single items) or arrays (nested items).  Selection of a
   
 nested item will pop-up a sub-menu.  To create nested items
   
 pass an array with the following structure:
   

   
  Element  Type   Description
   
  -------  ----   ---------------------------------
   
    [1]   C     Menu prompt
   
    [2]   A     Array of sub-menu items
   
    [3]   A     Array of sub-menu code-blocks (optional)
   
    [4]     A     Array of sub-menu messages
   
    [5]     A     Array of sub-menu help codes
   

   

   
 (aPromptBlocks) is an optional array of code blocks.  Must be
   
 one code block for each item in (aPrompts).  If a prompt block
   
 array is passed then the code block will be evaluated when the
   
 item is being painted in the menu and the item will be "grayed"
   
 (non-selectable) if the evaluated code block returns a .FALSE.
   
 If the code block returns a .TRUE. or the array item is a NIL,
   
 then the prompt item is selectable.
   

   
 (aEvalBlocks) is an optional array of code blocks.  Must be one
   
 code block for each item in (aPrompts).  If a code block array
   
 is passed then the code block will be evaluated when the item
   
 is selected and the user presses enter.
   

   
 (aCoord) is an optional ragged array of Row/Column positions
   
 for each item in (aPrompts).  If a Row/Column array is not
   
 passed then the prompts will be placed vertically starting at
   
 (nRow) and (nCol).
   

   
 (aMessage) is an optional array of character-string messages to
   
 be displayed for each item in (aPrompts).  The message will be
   
 displayed in accordance with the message options defined in
   
 (aMsgOptions).
   

   
 (aHelp) is an optional array of character-strings for each item
   
 in (aPrompts).  The string will be passed as the fourth (4th)
   
 parameter to the HELP procedure if the F1 key is pressed when
   
 an item is selected.  See DC_HELPF1() for more information.
   

   
 (aAccess) is an optional array of character string access level
   
 codes for each item in (aPrompts).   The logged on user will not
   
 be allowed access to this item if the DC_USERACCESS() function
   
 returns a logical .FALSE. when passed this access code.  If
   
 the access code is a nil or an empty null-string, or if the
   
 menu is being run with no specific user logged onto the system
   
 or if the user has access to all menus and items, then this
   
 item will be accessible.
   

   
 (aReturns) is an optional array of numerical return values for
   
 each item in (aPrompts).  This value will be posted to a
   
 static memory variable (when the menu item is selected ) which
   
 is accessed by the function DC_MENURETURN().
   

   

Returns:

    If (lReturnVal) is .FALSE. (default) the hot-key character of the
   
 selected menu item will be returned.  If (lReturnVal) is .TRUE.,
   
 the CHR() value of the menu choice will be returned.   For example,
   
 if the 4th menu item is selected, then CHR(4) will be returned.
   

   
 A null string is returned if the ESCape key is pressed.
   

   

Description:

Notes:

Examples:

    -- Example 1 --
   

   
 /* This example demonstrates using DC_MENUPULL() to return a
   
    code letter based on a user menu selection */
   

   
 local aPrompts, cMenuCode
   

   
 aPrompts :=  { 'Open File',;
   
                'Close File',;
   
                'Edit File',;
   
                'Save File',;
   
                'View File',;
   
                'Print File',;
   
                'Run Program',;
   
                'DOS ~Shell'  }
   

   
 cMenuCode := ;
   
   DC_MENUPULL( { 24, 28, ' File Options ', ;
   
     'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'B',,,,,,,,,,,, ;
   
      aPrompts } )
   

   
 do case
   
   case cMenuCode = 'O'
   
     openfile()
   
   case cMenuCode = 'C'
   
     closefile()
   
   case cMenuCode = 'E'
   
     editfile()
   
   case cMenuCode = 'S'
   
     savefile()
   
   case cMenuCode = 'S'
   
     viewfile()
   
   case cMenuCode = 'P'
   
     printfile()
   
   case cMenuCode = 'R'
   
     runexe()
   
   case cMenuCode = 'S'
   
     rundos()
   
 endcase
   
 return
   

   

   
 -- Example 2 --
   

   
 /* This example demonstrates using DC_MENU_P() to execute a
   
    code block  based on a user menu selection */
   

   
 local aPrompts, aBlocks
   

   
 aPrompts :=  { 'Open File',;
   
                'Close File',;
   
                'Edit File',;
   
                'Save File',;
   
                'View File',;
   
                'Print File',;
   
                'Run Program',;
   
                'DOS ~Shell'  }
   

   
 aBlocks := { {||openfile()},;
   
              {||closefile()},;
   
              {||editfile()},;
   
              {||savefile()},;
   
              {||viewfile()},;
   
              {||printfile()},;
   
              {||runexe()},;
   
              {||rundos()}     }
   

   
 DC_MENUPULL( { 24, 28, ' File Options ', ;
   
   'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'B',,,,,,,,,,,, ;
   
    aPrompts,, aBlocks } )
   

   
 return
   

   

   
 -- Example 3 --
   

   
 // This example shows how to "nest" sub-menus.
   
 // In the below example, selecting item 2 (File Options) of
   
 // the main menu will pop-up a sub-menu.  Selecting Item 1
   
 // (Delete a File) will pop-up another sub-menu.  Selecting
   
 // Item 2 (Binary File) will return "FDB".
   

   
 LOCAL aSubPrompt, aSubBlock, aMainPrompt, aSubSubPrompt
   

   
 aSubSubPrompt := {'ASCII File','Binary File','EXE File'}
   

   
 aSubPrompt := { ;
   
     {'Delete a file',aDelPrompt},;
   
      'Copy a file', ;
   
      'Move a file' }
   

   
 aSubBlock  := { , {||copyafile()}, {||moveafile()} }
   

   
 aMainPrompt := { ;
   
    'Edit Options',;
   
   {'File Options', aSubPrompt, aSubBlock },;
   
    'Search Options',;
   
    'Print Options' }
   

   
 cSelection := ;
   
   DC_MENUPULL( { 10, 10,,,'B',,,,,,,,,,,, aMainPrompt } )
   

   

   

Source/Library:

See Also:

dc_menureturn()

Get the Return value from the last menu selection

Syntax:

Arguments:

    None.
   

   

Returns:

    A numeric value
   

   

Description:

Examples:

    DO While .t.
   

   
   DC_MenuRun()  // Pick a menu and execute it
   
   nSelect := DC_HELPRETURN()
   

   
   IF nSelect == 750
   
     DC_DbfSel()
   
   ELSEIF nSelect == 820
   
     DC_Util()
   
   ELSEIF nSelect == 130
   
     DC_Browsedb()
   
   ELSEIF nSelect == 100
   
     QUIT
   

   
 ENDDO
   

   

Source/Library:

See Also:

dc_menurun()

Run a Menu

Syntax:

Arguments:

    (cMenuName) is the name of the menu to load and run.  If
   
 the menu exists in the menu dictionary it will be loaded
   
 and executed.  If the menu does not exist in the
   
 dictionary then an error message will be displayed.  If no
   
 parameter is passed then, a pick-list of menus will be
   
 displayed for the operator to choose.
   

   
 (aMenu) is a menu array that conforms to the specification
   
 of the array passed to DC_MENUPULL() or DC_MENUMAIN().
   

   
 (cCompileKeys) is an optional list of keys (3-digit
   
 character strings separated by commas).  Compile Keys are
   
 used for conditional compiling of menu items.  See
   
 DC_MENUCOMPILE() for more information.
   

   

Returns:

    A multi-dimensional array containing all information
   
 about a menu including prompts, sub-menus, message-text,
   
 help-codes, code-blocks, access codes, and return values.
   

   
 If the menu type is a Top-Bar Menu (Type A,B,C) then the
   
 array returned conforms to the specification for the array
   
 passed to DC_MENUMAIN().
   

   
 If the menu type is a Pull-Down Menu (Type P) then the
   
 array returned conforms to the specification for the array
   
 passed to DC_MENUPULL().
   

   

   

Description:

Examples:

    -- Example 1 --
   

   
 /* --- Run Main Menu from menu-dictionary --- */
   
 DC_MENURUN( 'MAINMENU' )
   

   

   
 -- Example 2 --
   

   
 /* --- Pick a Menu and run it --- */
   
 DC_MENURUN()
   

   

   
 -- Example 3 --
   

   
 /* -- Load a menu, compile and run it -- */
   

   
 aPreMenu := DC_MenuLoad('BROWSE')
   
 aMenu := DC_MenuCompile(aPreMenu)
   
 DC_MENRUN( aMenu )
   

   

Source/Library:

See Also:

dc_menusave()

Save a Menu to the Menu-Dictionary

Syntax:

Arguments:

    (aMenu) is a multi-dimensional array that conforms to
   
 the specification of the array returned by DC_MENUEDIT().
   

   

   

   

Returns:

    A logical .TRUE. if the menu was save successfully,
   
 .FALSE. otherwise.
   

   

   

Description:

Notes:

Examples:

    /* -- Edit and return the Main Menu -- */
   
 aPreMenu := DC_MenuEdit( 'MAINMENU' )
   

   
 /* -- Save it to the dictionary -- */
   
 DC_MENUSAVE( aPreMenu )
   

   
 /* -- Load it from the dictionary -- */
   
 aPreMenu := DC_MenuLoad( 'MAINMENU' )
   

   
 /* -- Compile the menu -- */
   
 aMenuMain := DC_MenuCompile( aPreMenu )
   

   
 /* -- Run the menu -- */
   
 DC_MenuMain( aMenuMain )
   

   

Source/Library:

See Also:

dc_menuto() *

A replacement for MENU TO that highlights key characters

Syntax:

Arguments:

    (nRow) is the upper-left row (for pull-downs), or lower-left
   
 row (for pop-up menus).
   

   
 (nCol) is the upper-left column (for pull-downs), or lower-left
   
 column (for pop-up menus).
   

   
 (cTitle) is an Optional title to be displayed centered on the
   
 top line of the box.  If no title is desired use a null string
   
 ("").
   

   
 (cBoxColor) is a single string of four colors to be used for
   
 the frame, menu items, highlighted letters, and select bar,
   
 respectively.
   

   
 (lType) is .t. for pull-down menu, .f. for pop-up menu
   

   
 (lBar) - If this is true (.t.) it will make the menu resemble a
   
 MENU TO, with a select bar.  If you do not want a select bar,
   
 and just want the items to be chosen by pressing the hot-key
   
 letter only, set this to false (.f.).
   

   
 (lReturnVal) - If this is false (.f.), only the hot-key letter
   
 is returned. If this is true (.t.), the entire menu item is
   
 returned.
   

   
 (nStart) is the number for which menu item to start on.
   

   
 (aItems) is an array of up to 23 menu items to be displayed.
   
 Each item is a character string.  By default, the first letter
   
 of each menu item will be highlighted and will be designated as
   
 that menu item's "hot-key".  If a different hot-key letter is
   
 desired for a item, precede the desired hot-key letter with a
   
 tilde (~).
   

   
 If the item is a "gray-scale" item (i.e. it displays only but
   
 is not selectable), it must be preceded by an "*" character.
   
 If the item is a separator line, it must be passed as an "@"
   
 character.  If the item is a separator line with a sub-title,
   
 then it must be passed as a "@" character plus the sub-title
   
 string.
   

   
 (aBlocks) is an optional parallel array of up to 23 code blocks
   
 to be evaluated.  The code block evaluated will be the one
   
 corresponding to the menu item selected from (aItems).
   

   
 (nExitKey) is the INKEY() number of the key to exit the menu
   
 after evaluating the code block.  Default is ESCape key (27).
   

   

Returns:

    The letter corresponding to the Hot-Key assigned to the menu item
   
 that was selected, a ( sign if the left arrow was pressed, a ) if
   
 the right arrow was pressed, or a null string if an error occured.
   

   

Description:

Notes:

Examples:

    // This example returns a code letter equal to the Hot Key of
   
 // the selected item
   

   
 code := DC_MENUTO( 23, 10,' FILE OPTIONS ', '', .f., .t., ;
   
         .f., 1, ;
   
   { 'Select/Open ~Data File',;
   
     'Select/Open ~Index File',;
   
     'Open New Data File',;
   
     '@',;
   
     'IIF(!EMPTY(ALIAS()),'','*')+'Close Data File',;
   
     'IIF(!EMPTY(INDEXKEY(0)),'','*')+'Close Index ~File(s)',;
   
     'Set Default Directory',;
   
     'Set ~Path Directories' } )
   

   

   
 // This example executes a code block for the selected item.
   
 // and exits the menu only if ESCape is pressed.
   

   
 DC_MENUTO( 23,10, ' UTILITIES ', '', .f., .t., .f., 1,
   
   { 'Select/Open ~Data File',
   
     'Select/Open ~Index File',
   
     'Open New Data File',
   
     '@',
   
     'IIF(!EMPTY(ALIAS()),'','*')+'Close Data File',
   
     'IIF(!EMPTY(INDEXKEY(0)),'','*')+'Close Index ~File(s)' } ,;
   
      { {||DC_DBFSEL()},;
   
       {||DC_DBISEL()},;
   
       {||DC_DBFOPEN()},;
   
       {||dbCloseArea()},;
   
       {||dbClearIndex()} }, K_ESC )
   

   

Source/Library:

See Also:

dc_merge()

Merge data and string or text

Syntax:

Arguments:

    (cString) is a character string that contains text and any of
   
 the following codes:
   

   
 ^_DATE:1^       - Today's date in system date format
   
 ^_DATE:2^       - Today's date in Month, Day, Year format
   
 ^_PAGE:^        - Page Number
   
 ^_TOP:(n)^      - Top margin
   
 ^_BOTTOM:(n)^   - Bottom margin
   
 ^_LEFT:(n)^     - Left margin
   
 ^_RIGHT:(n)^    - Right margin
   
 ^_TAB:(n)^      - Tab spaces
   
 ^_HEADING:(c)^  - Page Heading
   
 ^_FOOTING:(c)^  - Page Footing
   
 ^_PRINTER:(n)^  - Printer record
   
 ^_DATAFILE:(c)^ - Database file name
   
 ^(c)^           - Any field name or expression
   
 ~(c)            - Printer code letter
   

   
 Any of the above codes that are imbedded in the text will be
   
 converted to the proper output.
   

   

Returns:

    A character string converted with the "merged" information.
   

   

Description:

Examples:

    In the following example, the text in MERGE.TXT is as follows:
   

   
   ^^_DATE:2^^
   

   
   ^^trim(first)^^ ^^trim(last)^^
   
   ^^dc_capfirst(company)^^
   
   ^^dc_capfirst(street)^^
   
   ^^dc_capfirst(trim(city))^^, ^^state^^ ^^zip^^
   

   
   Dear ^^salutation^^ ^^last^^,
   

   
   Please pay your balance of ~g^^balance:$99999.99^^~h as soon
   
   as possible.
   

   
   Thank you,
   

   
   The management
   

   

   
 The data in current record of CUSTOMER.DBF is a follows:
   

   
   customer-)first  -      BILL
   
   customer-)last   -      CLINTON
   
   customer-)salutation  - Mr.
   
   customer-)company     - WHITE HOUSE
   
   customer-)street      - 2000 PENNSYLVANIA AVE.
   
   customer-)city        - WASHINGTON D.C.
   
   customer-)state       -
   
   customer-)zip         - 30001
   
   customer-)balance     -  6789.54
   

   

   
 The output text after running passing MERGE.TXT through
   
 DC_MERGE() is as follows:
   

   
   July 14, 1992
   

   
   Bill Clinton
   
   White House
   
   2000 Pennsylvania Ave.
   
   Washington D.C. 30001
   

   
   Dear Mr. Clinton,
   

   
   Please pay your balance of $ 6789.54 as soon as
   
   possible.                    ---------
   
                                   |
   
   Thank you,                     bold
   

   
   The management
   

   

Source/Library:

See Also:

dc_modstru()

Modify the structure of selected database

Syntax:

Arguments:

    (cNewFileName) is the name to assign to the new modified file.
   
 If no argument is given, then the new file name will be the
   
 same as the original and the original file will be renamed to
   
 BAK_DATA.*.
   

   

Returns:

    A logical .TRUE. if the file structure is modified, .FALSE.
   
 if aborted by user.
   

   

Description:

Examples:

    do while .t.
   
   @ 10,10 prompt "open a database"
   
   @ 11,10 prompt "browse database"
   
   @ 12,10 prompt "modify structure"
   
   menu to nChoice
   
   do case
   
     case nChoice = 1
   
       dc_dbfopen()
   
     case nChoice = 2
   
       dc_browsedb()
   
     case nChoice = 3
   
       DC_MODSTRU()
   
   endcase
   
 enddo
   

   

Source/Library:

See Also:

dc_moubutton()

Test the status of the mouse buttons

Syntax:

Arguments:

    None
   

   

Returns:

    A numeric value.
   

   
  0 - All buttons up
   
  1 - Left button down
   
  2 - Right button down
   
  3 - Left and Right button down
   
  4 - Right button released
   

   

Description:

Examples:

    FUNCTION key_mouse ( nMouseRow, nMouseCol )
   

   
 // Get a key or mouse event
   
 // returns -100 is left button down, 13 if right button
   
 // released
   
 do while .t.
   
   nInkey := inkey()
   
   nMouseStatus := DC_MOUBUTTON()
   
   do case
   
     case nMouseStatus = 1
   
       dc_mougetposition( @nMouseRow, @nMouseCol )
   
       nInkey := -100
   
       exit
   
     case nMouseStatus = 4
   
       nInkey := 13
   
       exit
   
     case nInkey # 0
   
       exit
   
   endcase
   
 enddo
   
 return nInkey
   

   

Source/Library:

See Also:

dc_mouclick()

Set the mouse button double-click delay

Syntax:

Arguments:

    (nDelay) is a number representing tenths of a second to wait
   
 for successive depressions of the left button.  Default is 4.
   
 If nDelay is set to 0, then the double-click action will be
   
 disabled.
   

   

Returns:

    A numeric value.
   

   
  0 - All buttons up
   
  1 - Left button down
   
  2 - Right button down
   
  3 - Left and Right button down
   
  4 - Right button released
   

   

Description:

Examples:

    // Set double-click delay to 3. seconds.
   
 DC_MOUCLICK( .3 )
   

   

Source/Library:

See Also:

dc_moucol()

Get current screen column of mouse cursor

Syntax:

Arguments:

    None
   

   

Returns:

    A numeric value
   

   

Description:

Examples:

    nRow := nil
   
 nCol := nil
   
 GetMouse( @nRow, @nCol )
   
 ? 'Mouse position is:', nRow, nCol
   
 return
   

   
 function GetMouse ( @nRow, @nCol )
   
 nRow := dc_mourow()
   
 nCol := DC_MOUCOL()
   
 return nil
   

   

Source/Library:

See Also:

dc_moudisable()

Disable the mouse functions

Syntax:

Arguments:

    None.
   

   

Returns:

    A logical .TRUE. if the mouse driver is installed and initialized,
   
 .FALSE. otherwise.
   

   

Description:

Examples:

    dc_moudisable()   // shut off the mouse
   
 do myapp
   
 DC_MOUENABLE()    // turn the mouse back on whenever mouse
   
                   // functions are called
   

   

Source/Library:

See Also:

dc_mouenable()

Enable the mouse functions

Syntax:

Arguments:

    None.
   

   

Returns:

    A logical .TRUE. if the mouse driver is installed and initialized,
   
 .FALSE. otherwise.
   

   

Description:

Examples:

    dc_moudisable()   // shut off the mouse
   
 do myapp
   
 DC_MOUENABLE()    // turn the mouse back on whenever mouse
   
                   // functions are called
   

   

Source/Library:

See Also:

dc_mougetevent()

Get a mouse event from the Mouse Click buffer

Syntax:

Arguments:

    None
   

   

Returns:

    nil
   

   

Description:

Notes:

Examples:

    dc_mouinitialize()
   
 dc_moustart( -29 )  // Key CTRL-F10 is reserved for the mouse
   
 dc_moushow()
   
 set key -29 to myfunc
   

   
 memo = memoread('dclip.sys')
   
 memo := memoedit( memo, 5,5,20,75 )
   

   
 dc_moustop()
   
 dc_mouhide()
   
 set key -29 to
   
 return
   

   

   
 function myfunc
   

   
 local nStatus := DC_MOUGETEVENT()
   
 @ 23, 0 say ''
   
 do case
   
   case nStatus = 2
   
     ?? '  left button pressed'
   
   case nStatus = 4
   
     ?? ' left button released'
   
   case nStatus = 8
   
     ?? ' right button pressed'
   
   case nStatus = 16
   
     ?? 'right button released'
   
 endcase
   
 ?? ' at row', dc_mourow(), ', col', dc_moucol()
   
 return nil
   

   

Source/Library:

See Also:

dc_mougetpos()

Get the current row and column of the mouse

Syntax:

Arguments:

    (nRow) is an integer variable to store the mouse row
   

   
 (nCol) is an integer variable to store the mouse column
   

   

Returns:

    nil
   

   

Description:

Examples:

    FUNCTION key_mouse ( nMouseRow, nMouseCol )
   

   
 // Get a key or mouse event
   
 // returns -100 is left button down, 13 if right button
   
 // released
   
 do while .t.
   
   nInkey := inkey()
   
   nMouseStatus := dc_moubutton()
   
   do case
   
     case nMouseStatus = 1
   
       DC_MOUGETPOS( @nMouseRow, @nMouseCol )
   
       nInkey := -100
   
       exit
   
     case nMouseStatus = 4
   
       nInkey := 13
   
       exit
   
     case nInkey # 0
   
       exit
   
   endcase
   
 enddo
   
 return nInkey
   

   

Source/Library:

See Also:

dc_mouhide()

Hide the mouse cursor

Syntax:

Arguments:

    None
   

   

Returns:

    nil
   

   

Description:

Examples:

    nRow := nil
   
 nCol := nil
   
 DC_MOUHIDE()
   
 // hide the mouse and track it with the screen cursor instead
   
 set cursor on
   
 do while .t.
   
   dc_mougetpos( @nRow, @nCol )
   
   @ nRow, nCol SAY ''
   
 endif
   
 return
   

   

Source/Library:

See Also:

dc_mouinitialize()

Initialize the mouse functions

Syntax:

Arguments:

    None
   

   

Description:

Source/Library:

dc_moupresent()

Is a mouse present?

Syntax:

Arguments:

    None
   

   

Description:

Examples:

    if DC_MOUPRESENT()
   
    dc_mougetpos( @nRow, @nCol )
   
    ? 'mouse is at ', nRow, nCol
   
 else
   
    ? 'No mouse found..  Make sure driver is loaded'
   
 endif
   

   

Source/Library:

dc_mourow()

Get current screen row of mouse cursor

Syntax:

Arguments:

    None
   

   

Returns:

    A numeric value
   

   

Description:

Examples:

    nRow := nil
   
 nCol := nil
   
 GetMouse( @nRow, @nCol )
   
 ? 'Mouse position is:', nRow, nCol
   
 return
   

   
 function GetMouse ( @nRow, @nCol )
   
 nRow := DC_MOUROW()
   
 nCol := dc_moucol()
   
 return nil
   

   

Source/Library:

See Also:

dc_mousebutton()

Paint a mouse button on the screen

Syntax:

Arguments:

    (aButtons) is a the multi-dimensional array that will hold
   
 the mouse button information.  This array must conform to
   
 the specifications for DC_MOUSEKEY().
   

   
 (nStRow), (nStCol), (nEnRow), (nEnCol) are the screen
   
 coordinates of the mouse button.
   

   
 (aText) is an array of character strings to display in the
   
 box.  The first line of text will display in the first open
   
 row of the box, etc.
   

   
 (xKeys) may be a Type C, N, or B.
   

   
 If type C, then this is a string to stuff into the keyboard
   
 buffer.  If type N, then this is an INKEY() value to stuff
   
 into the keyboard buffer.  If type B, then this is a code
   
 block to evaluate.
   

   
 (nAltKey) is an Alternate INKEY() value to stuff in the
   
 keyboard buffer after evaluating the code block.
   

   
 (nWait) is the number of seconds to pause (optional).  Use
   
 this parameter to specify the amount of delay between key
   
 stuffings when the operator holds down the mouse button.
   

   
 (cColor) is the color of the button.  This must be a
   
 standard Clipper color string.  If no parameter is passed,
   
 the currently selected system color will be used.
   

   
 (lBox) if .TRUE. (default) will paint a box around the button
   
 and the text will be inserted within the box.  If .FALSE., then
   
 the text will be painted at the starting coordinate and no box
   
 will be painted.
   

   

Returns:

    A pointer to the array passed as (aButtons).
   

   

Description:

Examples:

    //paint some calculator buttons
   
 aMouseKeys := {}
   
 DC_MOUSEBUTTON( @aMouseKeys, nStRow+4, nStCol+2, nStRow+6,;
   
                 nStCol+5, {'AC'}, 'AC' )
   
 DC_MOUSEBUTTON( @aMouseKeys, nStRow+4, nStCol+7, nStRow+6,;
   
                 nStCol+10, {' 7'}, '7' )
   
 DC_MOUSEBUTTON( @aMouseKeys, nStRow+4, nStCol+11, nStRow+6,;
   
                 nStCol+14, {' 8'}, '8' )
   
 DC_MOUSEBUTTON( @aMouseKeys, nStRow+4, nStCol+15, nStRow+6,;
   
                 nStCol+18, {' 9'}, '9' )
   
 DC_MOUSEBUTTON( @aMouseKeys, nStRow+4, nStCol+20, nStRow+6,;
   
                 nStCol+23, {' /'}, '/' )
   

   

Source/Library:

See Also:

dc_mousekey()

Scan array of mouse buttons and stuff keyboard or evaluate

Syntax:

Arguments:

    (aButtons) is a multi-dimensional array with coordinates and
   
 Keyboard Codes, Inkey values or Code Blocks for establishing
   
 mouse buttons.  Each button in the main array is a sub-array of
   
 7 elements:
   

   
 Element   Type   Description
   
 -------   ----   ---------------------------------
   
   1        N     Top Row of button
   
   2        N     Left Column of button
   
   3        N     Bottom Row of button   (optional)
   
   4        N     Right Column of button (optional)
   
   5        C     Keyboard character to stuff
   
           or N   Keyboard INKEY value to stuff
   
           or B   Code block to evaluate
   
   6        N     Secondary INKEY value to stuff (optional)
   
   7        N     Number of seconds to pause (optional).  Use
   
                  this parameter to specify the amount of
   
                  delay between key stuffings when the
   
                  operator holds down the mouse.
   

   
 If Element 3 is a NIL, then the value of Element 1 will be
   
 used.
   

   
 IF Element 4 is a NIL, then the value of Element 2 will be
   
 used.
   

   
 (lStuff) if .TRUE. (default) will stuff the keyboard character
   
 into the keyboard buffer if the mouse was clicked in the button
   
 coordinate area defined by elements 1-4.  If .FALSE. the value
   
 of element 5 will be returned only, not stuffed in the
   
 keyboard.
   

   

Returns:

    The CHR() value in element 5 of the (aButtons) array if
   
 the mouse was clicked in the coordinate area.  If the mouse
   
 was not clicked in an area designated by one of the sub-
   
 arrays, a null "" string will be returned.
   

   

Description:

Examples:

    @ 10,0 to 12,6
   
 @ 11,2 SAY CHR(24)+' '+CHR(25)
   
 @ 10,20 to 12,25
   
 @ 11,21 say 'Kill'
   
 @ 10,40 to 12,45
   
 @ 11,41 say 'Add'
   
 @ 10,60 to 12,65
   
 @ 11,61 say 'Quit'
   

   
 aButtons := { { 10,20,12,25,'K' },;
   
               { 10,40,12,45,'A' },;
   
               { 10,60,12,65,K_ESC },;
   
               { 10,2,,,K_UP,,.5 },;
   
               { 10,4,,,K_DOWN,,.5 } }
   

   
 do while .t.
   
   nInkey := dc_inkey(0)
   
   do case
   
     case nInkey = -101 .AND !empty(DC_MOUSEKEY(aButtons))
   
     case nInkey = 'K'
   
       do kill
   
     case nInkey = 'A'
   
       do add
   
     case nInkey = K_UP
   
       skip -1
   
     case nInkey = K_DOWN
   
       skip
   
     case nInkey = K_ESC
   
       exit
   
   endcase
   
 enddo
   

   

   

   

   

Source/Library:

dc_mousetpos()

Set the current row and column of the mouse

Syntax:

Arguments:

    (nRow) is an integer variable to set the mouse row
   

   
 (nCol) is an integer variable to set the mouse column
   

   

Returns:

    nil
   

   

Description:

Examples:

    // make sure the mouse is at the upper left corner when
   
 // starting the drag
   
 DC_MOUSETPOSITION( 10, 20 )
   
 dc_drag ( 10, 20, 22, 70 )
   

   

Source/Library:

See Also:

dc_moushow()

Show the mouse at it's current screen position

Syntax:

Arguments:

    None
   

   

Returns:

    nil
   

   

Description:

Examples:

    if dc_moupresent()
   
   dc_mouinitialize()
   
   MOU_SHOW()
   
 else
   
   ? 'Mouse not present'
   
 endif
   

   

Source/Library:

See Also:

dc_moustart()

Enable automatic keyboard stuffing on a Mouse Click

Syntax:

Arguments:

    (nInkey) is the INKEY value of the key to be placed into the
   
 keyboard buffer when a mouse event occurs.
   

   

Returns:

    nil
   

   

Description:

Examples:

    dc_mouinitialize()
   
 DC_MOUSTART( -29 )  // Key CTRL-F10 is reserved for the mouse
   
 dc_moushow()
   
 set key -29 to myfunc
   

   
 memo = memoread('dclip.sys')
   
 memo := memoedit( memo, 5,5,20,75 )
   

   
 dc_moustop()
   
 dc_mouhide()
   
 set key -29 to
   
 return
   

   

   
 function myfunc
   

   
 local nStatus := dc_mougetevent()
   
 @ 23, 0 say ''
   
 do case
   
   case nStatus = 2
   
     ?? '  left button pressed'
   
   case nStatus = 4
   
     ?? ' left button released'
   
   case nStatus = 8
   
     ?? ' right button pressed'
   
   case nStatus = 16
   
     ?? 'right button released'
   
 endcase
   
 ?? ' at row', dc_mourow(), ', col', dc_moucol()
   
 return nil
   

   

Source/Library:

See Also:

dc_moustop()

Turn off the Mouse Event driver

Syntax:

Arguments:

    None.
   

   

Returns:

    Nil
   

   

Description:

Examples:

    dc_mouinitialize()
   
 dc_moustart( -29 )  // Key CTRL-F10 is reserved for the
   
                     // mouse
   
 dc_moushow()
   
 set key -29 to myfunc
   

   
 memo = memoread('dclip.sys')
   
 memo := memoedit( memo, 5,5,20,75 )
   

   
 DC_MOUSTOP()
   
 dc_mouhide()
   
 set key -29 to
   
 return
   

   

   
 function myfunc
   

   
 local nStatus := dc_mougetevent()
   
 @ 23, 0 say ''
   
 do case
   
   case nStatus = 2
   
     ?? '  left button pressed'
   
   case nStatus = 4
   
     ?? ' left button released'
   
   case nStatus = 8
   
     ?? ' right button pressed'
   
   case nStatus = 16
   
     ?? 'right button released'
   
 endcase
   
 ?? ' at row', dc_mourow(), ', col', dc_moucol()
   
 return nil
   

   

Source/Library:

See Also:

dc_mouvisible()

Is the mouse cursor visible?

Syntax:

Arguments:

    None
   

   

Returns:

    A logical .TRUE. if the mouse is visible, .FALSE. otherwise.
   

   

Description:

Source/Library:

dc_move()

Pop-up a user-prompt menu for moving files

Syntax:

Returns:

    A logical .TRUE. if the file was moved successfully.
   

   

Description:

Examples:

    @ 12,10 prompt "Move a File"
   
 @ 13,10 prompt "Copy a File"
   
 menu to nChoice
   
 do case
   
   case nChoice = 1
   
     DC_MOVE()
   
   case nChoice = 2
   
     dc_copyfile()
   
 endcase
   

   

Source/Library:

See Also:

dc_mprint() *

Print a memo field with page-breaks, margins, etc.

Syntax:

Arguments:

    (cMemo) is the name of memo field or string varible to print in
   
 quotes.
   

   
 (nMargin) is the number of spaces of left margin
   

   
 (nLines)  is the number of lines to print per page
   

   
 (lPrintHeading) if .TRUE. will print heading on each page with
   
 page numbers.
   

   
 (cHeading) is the Heading to print on top of each page
   

   
 (cOutFile) is the name of file to output to.  If "" null, then
   
 output is to printer (default).
   

   
 (lEject) if .TRUE. (default) with eject the page after print.
   

   

Description:

Notes:

Examples:

    use source.dbf
   
 do while !eof()
   
   DC_MPRINT( 'source-)memo', 8, 55, .t., source-)file_name )
   
   eject
   
 enddo
   

   

Source/Library:

dc_msgbox()

Display an array of messages in a window

Syntax:

Arguments:

    (nStartRow) is the starting screen row.
   
 (nStartCol) is the starting screen column.
   
 If no coordinates are given, then the message box will be
   
 displayed in the middle of the screen.
   

   
 (aMessages) is an array of character strings.
   

   
 (cTitle) is the title to place at the top of the message box.
   

   
 (lWait) will add an additional line to the message box - "Press
   
 any key to continue..." and wait for the user to press a key.
   

   
 (nSeconds) will display the box for a specified number of
   
 seconds or until a key is hit.
   

   
 (lYesNo) if .t. will display YES / NO menu items below the
   
 message text.  .F. (default) will behave normally.
   

   
 (nChoice) : 1 will default to YES (default),  2 will default
   
 to NO.  If passed by reference and an array of (aItems) is
   
 also passed, then the value returned will be equivalent to
   
 the menu item selected.
   

   
 (aItems) - An array of menu items to choose from.  The number
   
 of the selected item will be returned in the (@nChoice)
   
 variable.
   

   
 (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.
   

   
 (cHotKey) - An optional parameter to return the value of the
   
 high-lighted letter in the selected menu item when using
   
 DC_MSGBOX() with an array of menu items.  This must be a variable,
   
 passed by reference, in which to store a character value.
   

   

Returns:

    A logical .TRUE. if the last key pressed by the user is a "Y",
   
 .FALSE. otherwise.
   

   

Description:

Notes:

Examples:

    -- Example 1 --
   

   
 DC_MSGBOX( 10,5 { 'Must open a data file first' },,.t. )
   

   

   
 -- Example 2 --
   

   
 IF DC_MSGBOX( ,, { 'Delete '+cFileName+'? ' },
   
            ' Delete a File ',,,,.t. )
   
   ERASE (cFileName)
   
 ENDIF
   

   

   

Source/Library:

See Also:

dc_netuse()

Attempt to open a database for shared use on a network

Syntax:

Arguments:

    (cFileName) is the name of the .DBF file to open
   

   
 (lExclusive) - mode of open (exclusive/.NOT. exclusive)
   

   
 (nWaitTime) - seconds to wait (0 = wait forever)
   

   

Description:

Source/Library:

See Also:

dc_ntxext()

Return default extension of an index based on RDD selection

Syntax:

Arguments:

    (cRdd) is the name of the replaceable data driver.  If no
   
 argument is given, then the currently selected RDD will be
   
 used.
   

   
 (cFileName) is an optional parameter provided for
   
 convenience only.  If the file name contains an extension,
   
 then the extension in the file name will be returned.
   

   

Returns:

    A character string.
   

   

Description:

Examples:

    -- Example 1 --
   

   
 set rdd to DBFNTX
   
 ? DC_NTXEXT()
   
 .NTX
   
 ? DC_NTXEXT('DBFSIX')
   
 .IDX
   

   

   
 -- Example 2 --
   

   
 set rdd to DBFSIX
   
 accept 'Enter new index to create' to cIndex
   
 if file( trim( cIndex ) + DC_NTXEXT() )
   
   ? "File already exists"
   
 else
   
   dc_crindex( cIndex )
   
 endif
   

   

Source/Library:

See Also:

dc_ntxhandle()

Return the handle of an open index file

Syntax:

Arguments:

    (nArea) is the work area.  If no argument is given, then the
   
 current selected work area is default.
   

   
 (nOrder) is the order number of the index file.  If no argument
   
 is given, then the currently selected index is default.
   

   

Returns:

    The DOS file handle number of the index file in the designated
   
 order of the designated work area.  If no file is open in the
   
 specified work area, returns -1.
   

   

Description:

Examples:

    . select 3
   
 . use customer index custname, custnmbr
   
 . nHandle := DC_NTXHANDLE(3,2)
   

   
 . nSavePos := fseek( nHandle, 0, 1 ) // save file pointer
   

   
 . ? 'Custnmbr.ntx is ' + ;
   
      STR( fseek ( nHandle, 0, 2 ) ) + ' bytes long'
   

   
 . fseek( nHandle, nSavePos, 0 )      // restore file pointer
   

   

Source/Library:

See Also:

dc_num2array()

Create an array and fill it with numbers

Syntax:

Arguments:

    (nStart) is the start number.
   

   
 (nEnd) is the end number.
   

   
 (nIncrement) is the step increment between numbers.
   

   

Returns:

    An array of numbers.
   

   

Description:

Examples:

    // This example pops un a pick-list of numbers ranging
   
 // from 10 to 90 in increments of 5 when the mouse
   
 // is double-clicked on the get
   

   
 @ 6,5 SAY Enter Number GET nNumber PICT '99' ;
   
 valid dc_readapick( @nNumber, DC_NUM2ARRAY(10,90,5)) ;
   
 PICKLIST
   

   

Source/Library:

dc_num2bin()

Convert a number to a binary character string

Syntax:

Arguments:

    (nInteger) is any integer number.
   

   

Description:

Examples:

    ? DC_Num2Bin( 0 )
   
 00000000
   

   
 ? DC_Num2Bin( 255 )
   
 11111111
   

   

Source/Library:

See Also:

dc_num2word()

Convert a number to a 2-byte word

Syntax:

Arguments:

    (nInteger) is any integer number.
   

   

Description:

Examples:

    The following example shows how to use DC_NUM2WORD() and
   
 DC_WORD2NUM() to save numeric values to a file and restore
   
 them.
   

   
 FUNCTION savenumbers ( aNumbers )
   

   
 // aNumbers := { 10, 45, 134, 678, 3, 200 }
   
 nHandle := fcreate( 'numbers.bin' )
   
 for i := 1 to len(aNumbers)
   
   fwrite( nHandle, DC_NUM2WORD( aNumbers[i] )
   
 next
   
 fclose( nHandle )
   
 return
   

   

   
 FUNCTION restnumbers
   

   
 local nHandle := fopen( 'numbers.bin' )
   
 local aNumbers := {}
   
 aadd( aNumbers, DC_WORD2NUM( freadstr( nHandle, 2 ) ) )
   
 fclose( nHandle )
   
 return aNumbers
   

   

Source/Library:

See Also:

dc_numincr()

Increment the "numeric" portion of a string

Syntax:

Arguments:

    (cString) is a character string.
   

   
 (cLoVal) and (cHiVal) are optional parameters for setting a low
   
 and high value.  If the number increments past (cHiVal) it will
   
 automatically be set to (cLoVal).
   

   

Description:

Examples:

    // print 100 serial number labels
   
 cSerial := 'DON-4567-A'
   
 set print on
   
 for i := 1 to 100
   
   ? '   '+cSerial
   
   ?
   
   ?
   
   cSerial := DC_NUMINCR( cSerial )
   
 next
   
 set print off
   

   

Source/Library:

See Also:

dc_objexternal()

List all .OBJ files that contain call to specified function

Syntax:

Arguments:

    (cProc) is the name of the procedure or function to locate.
   

   
 (cFileName) is the name of an output file to write the list of
   
 .OBJs in which a call to the (cProc) is found.  If no list file
   
 argument is given then the file name(s) in which the external
   
 references are found will be displayed on the screen.
   

   
 (lDisplayWindow) if .TRUE. (default) will display the names of
   
 the .OBJ's found.
   

   

Description:

Examples:

    accept "enter procedure external to list" to cProc
   
 DC_OBJEXTERNAL( cProc, "EXTLIST.TXT" )
   

   

Source/Library:

See Also:

dc_objfind()

Find the location of a publicly defined function

Syntax:

Arguments:

    (cFunction) is the name of the function or procedure to locate.
   

   

Returns:

    A character string with the name of the source module in which
   
 (cFunction) is publicly defined.
   

   
 If no maps or dynamic libraries are loaded or if the (procedure)
   
 cannot be found in a map or dynamic library, then the passed
   
 argument ((cFunction)) will    be returned.
   

   

Description:

Examples:

    dc_mapload( 'demo' )
   
 cSource := DC_OBJFIND( 'CALC' )
   
 dc_editprg( cSource )
   
 dc_compile( cSource )
   
 calc()
   

   

Source/Library:

See Also:

dc_objlink()

Load and "dynamic-link" a module from a dynamic library

Syntax:

Arguments:

    (cDlbName) - The name of the library containing the object.
   

   
 (cObjName) - The name of the object to link.  This must be the
   
 object (.OBJ) name, NOT the name of a procedure or function
   
 imbedded within the object.
   

   
 (lLoadPerm) if .TRUE. will load the .OBJ permanently in memory.
   
 The .OBJ will not be automatically released if memory is needed
   
 but can still be released with DC_OBJRELEASE((cObjName),.t.).
   
 .FALSE. is the default.
   

   
 (lRelink) if .TRUE. will relink the .OBJ even if it exists in
   
 memory.  IF .FALSE. (default), the .OBJ will be linked only
   
 if it is not in memory.
   

   

Description:

Source/Library:

See Also:

dc_objload()

Load and "dynamic-link" a Clipper-compiled .OBJect file

Syntax:

Arguments:

    (cObjName) is the name of the .OBJ file to link.  If no drive/
   
 directory is included in the file name, then the .OBJ must
   
 exist in the directory specified by the SET ODIR command, ODIR=
   
 in DCLIP.SYS, or DC_SETT('ODIR',(path)).
   

   
 (lLoadPerm) if .TRUE. will load the object into memory
   
 "permanently".  This option will prevent the object from being
   
 released with the DC_OBJRELEASE() function or OBJ RELEASE
   
 command.
   

   
 If a (cRunProc) argument is passed, the (cRunProc) procedure or
   
 function will be automatically executed.
   

   
 (lObjRelease) will release the .OBJ from memory after executing
   
 the (cRunProc) function.
   

   

Description:

Notes:

Examples:

    -- Example 1 --
   

   
 do while .t.
   
   @ 10,10 prompt "Calculator"
   
   @ 11,10 prompt "Calendar"
   
   @ 12,10 prompt "Note Book"
   
   menu to nChoice
   
   do case
   
     case nChoice = 1
   
       DC_OBJLOAD( "calc",, "pop_calc(.t.)", .t. )
   
     case nChoice = 2
   
       DC_OBJLOAD( "calendar",, "time_chart()", .t. )
   
     case nChoice = 3
   
       DC_OBJLOAD( "notebook",, "notebook()", .t. )
   
   endcase
   
 enddo
   

   
 -- Example 2 --
   

   
 accept "enter a function to execute" to cFunction
   
 cObjName := dc_objfind( cFunction )
   
 DC_OBJLOAD( cObjName )
   
 dc_do( cFunction )
   

   

Source/Library:

See Also:

dc_objmem()

Report the amount of available memory for "dynamic-linking"

Syntax:

Arguments:

    NONE
   

   

Description:

Examples:

    dc_linkinit( 100 )
   
 ? DC_OBJMEM()
   
 100
   
 dc_objload( 'demo' )
   
 ? DC_OBJMEM()
   
 92
   
 dc_objrelease( 'demo' )
   
 ? DC_OBJMEM()
   
 100
   

   

Source/Library:

See Also:

dc_objpublic()

Locate .OBJ file that contains a public function/procedure

Syntax:

Arguments:

    (cProc) is the name of the procedure to find.
   

   
 (lDisplayWindow) if .TRUE. will display a window with the names
   
 of files being scanned.
   

   

Returns:

    A character string containing the name of the .OBJ that contains
   
 the procedure.  A null ("") string if the procedure is not found.
   

   

Description:

Examples:

    accept "enter public procedure to find" to cProc
   
 DC_OBJPUBLIC( cProc )
   

   

Source/Library:

See Also:

dc_objrelease()

Release a "dynamic-linked" object file from memory

Syntax:

Arguments:

    (cObjName) is the name of the .OBJ file to release from memory.
   
 If "ALL" is entered, then all objects not currently active
   
 which have not been loaded as "permanent" will be released.
   

   
 (lReleaseIfPerm) if .TRUE. will release the object even if it
   
 was loaded "permanent".  If .FALSE., then the object will be
   
 released only if it is not permanent and not currently active.
   

   

Description:

Notes:

Examples:

    accept "enter a function to execute" to cFunction
   
 cObjName := dc_objfind( cFunction )
   
 dc_objload( cObjName )
   
 dc_do( cFunction )
   
 DC_OBJRELEASE( cObjName )
   

   

Source/Library:

See Also:

dc_odblock()

Get a Progress indicator code block to pass to dbeval()

Syntax:

Arguments:

    (bWhileCondition) is the same code block that would be passed
   
 to dbeval() as the WHILE condition.
   

   
 (bForCondition) is a code block which will be evaluated for
   
 each record.  If the code block evaluates .TRUE. then the tally
   
 count in the progress indicator will be incremented by 1.
   

   
 (nStep) is an optional parameter which is used to specify how
   
 often the odometer function will be called.  (nStep) is a
   
 numeric value representing the number of records that will be
   
 processed before the odometer function will be called.
   
 Increasing the (nStep) number will improve speed performance,
   
 however the progress indicator resolution will be lowered.
   

   
 (cMessage) is the the message to be displayed in the progress
   
 box. For example, if you are deleting records, then the message
   
 may be "deleted", or if you are copying records the message may
   
 be "copied".
   

   
 (lForExit) if .TRUE. will display the progress indicator until
   
 the (bForCondition) evaluates .TRUE.  Use this option when
   
 performing an operation such as a LOCATE, where the FOR
   
 condition terminates the operation as soon as it evaluates
   
 .TRUE.
   

   
 (lWait) if .TRUE. will leave the odometer status on the screen
   
 after all records are evaluated until a key is pressed.
   
 Default is .FALSE.
   

   
 (nRecords) is used only when working with an index that contains
   
 a subset of the total records in the database.  An example would
   
 be using a filter on the database, a conditional index, or
   
 features like SCOPETOP and SCOPEBOTTOM.  If your RDD supports
   
 a function that returns the amount of keys in the index then
   
 use this value, otherwise you may need to calculate the value.
   
 If no argument is given or the value of (nRecords) doesn't
   
 exactly match the number of valid records in the database then
   
 the progress indicator may not be accurate when reporting
   
 percentage.
   

   
 (lRest) should be the same value as the (lRest) parameter in
   
 your DBEVAL() function that uses DC_ODBLOCK().
   

   
 (cTitle) is the title you wish to appear at the top of the
   
 progress window.
   

   

   

Returns:

    A code block that usess the DC_ODOMETER() function.
   

   

Description:

Examples:

    lOdometer := .t.
   
 cFor := space(40)
   
 @ 10,10 say "Enter FOR condition " get cFor
   
 @ 11,10 say "Do you want a progress odometer? " get lOdometer
   
 bFor := {||&cFor}
   
 if lOdometer
   
   bWhile := DC_ODBLOCK( ,bFor,,,"Deleted",,.t.,,,;
   
             'Deleting Records' )
   
 else
   
   bWhile := { || .t. }
   
 endif
   
 dbeval( { || dbDelete() }, bFor, bWhile )
   

   

   

Source/Library:

See Also:

dc_odometer()

Display a progress indicator for database/index operations

Syntax:

Arguments:

    (bForCondition) is a code block which will be evaluated for
   
 each record.  If the code block evaluates .TRUE. then the tally
   
 count in the progress indicator will be incremented by 1.
   

   
 (nStep) is an optional parameter which is used to specify how
   
 often the odometer function will be called.  (nStep) is a
   
 numeric value representing the number of records that will be
   
 processed before the odometer function will be called.
   
 Increasing the (nStep) number will improve speed performance,
   
 however the progress indicator resolution will be lowered.
   

   
 (cMessage) is the the message to be displayed in the progress
   
 box. For example, if you are deleting records, then the message
   
 may be "deleted", or if you are copying records the message may
   
 be "copied".
   

   
 (lForExit) if .TRUE. will display the progress indicator until
   
 the (bForCondition) evaluates .TRUE.  Use this option when
   
 performing an operation such as a LOCATE, where the FOR
   
 condition terminates the operation as soon as it evaluates
   
 .TRUE.
   

   
 (lWait) if .TRUE. will leave the odometer status on the screen
   
 after all records are evaluated until a key is pressed.
   
 Default is .FALSE.
   

   

Returns:

    A logical .T. until the end-of-file is reached or until the
   
 ESCape key is pressed.
   

   

Description:

Notes:

Examples:

    lOdometer := .t.
   
 cFor := space(40)
   
 @ 10,10 say "Enter FOR condition " get cFor
   
 @ 11,10 say "Do you want a progress odometer? " get lOdometer
   
 bFor := {||&cFor}
   
 if lOdometer
   
   bWhile := { || DC_ODOMETER( bFor,1,"Deleted",.f.,.t. ) }
   
 else
   
   bWhile := { || .t. }
   
 endif
   
 dbeval( { || dbDelete() }, bFor, bWhile )
   

   

   

Source/Library:

See Also:

dc_odpercent()

Set numeric value for progress indicator percentage of update

Syntax:

Arguments:

    (nPercent) is a numeric value for the percentage of update
   
 you want on the progress odometer.  If you have very large
   
 files and want to see progress more often, then it is
   
 recommended you lower this number from the default of 5
   
 percent.
   

   

Description:

Examples:

    DC_ODPERCENT( 1 )  // 1 percent
   
 index on cust_nmbr to custnmbr
   

   

Source/Library:

See Also:

dc_ontick()

Evaluate a User Function on a clock tick

Syntax:

Arguments:

    (cUDF) is the name of a user-defined function or procedure
   
 to call.
   

   
 (nClockTicks) is the number of system clock ticks between
   
 calls.  Each tick is 1/18 second.
   

   

Returns:

    nil
   

   

Description:

Examples:

    DC_ONTICK('myfunc',1)  // call Myfunc() every 1/18 second
   
 DC_ONTICK('myfunc',18) // call Myfunc() every second
   
 DC_ONTICK()            // disable call to Myfunc()
   

   

   

Source/Library:

dc_openindex()

Open/Create an array of index files using any RDD

Syntax:

Arguments:

    (cDirectory) is the directory to search for the index.  If no
   
 parameter is passed then the current SET_DEFAULT followed by
   
 SET_PATH will be searched.
   

   
 (cCombName) is the name of a "combined index" file name to
   
 create if (lCombined) is .TRUE. and if the current RDD supports
   
 combined indexes. If the current RDD does not support combined
   
 indexes, then these parameters are ignored.
   

   
 (aTagInfo) is a multi-dimensional array containing the
   
 information about each index to open (or create if it does not
   
 exist).  Each sub-array consists of 6 elements:
   

   
 Element   Type   Description
   
 -------   ----   ----------------------------------------------
   
   [1]      C     FileName of Index (ignored if combined index)
   
   [2]      C     Tag Name
   
   [3]      C     Index Key expression
   
   [4]      C     "For" condition expression
   
   [5]      L     .True. if index is UNIQUE, .False. otherwise
   
   [6]      L     .True. if index is DESCENDING, .False.
   
                  otherwise
   
   [7]      C     Description of this index
   

   
 (lCreate) if .TRUE. will re-create the indexes even if they
   
 already exist.  If .FALSE. (default) then the indexes will
   
 be created only if they don't exist.
   

   
 (lNoProgress) if .TRUE. will not display the progress bar
   
 while indexing.  If .FALSE. (default) then a progress bar
   
 is displayed showing the percentage of progress during the
   
 index creation.  Some replaceable data drivers (i.e. DBFNTX)
   
 create larger index files when a progress bar is displayed
   
 via the EVAL option.  The progress bar may also slow the
   
 indexing by approximately 20%.
   

   

   

Returns:

    A logical .TRUE. if the file is opened or created, .FALSE.
   
 otherwise.
   

   

Description:

Examples:

    // In this example, if the DBFNTX driver is active then three
   
 // index files named DCHELP1.NTX, DCHELP2.NTX and DCHELP3.NTX
   
 // will be created.  If the DBFCDX driver is active then 1
   
 // combined index named DCHELP.CDX will be created with 3
   
 // tags: COMMAND, SORT and CATEGORY. In either case,
   
 // SET ORDER TO 1,2 or 3 will select the same index.
   

   
 DC_OPENINDEX( , 'DCHELP',;
   
       {{ 'DCHELP1','COMMAND','COMMAND',,.t. }, ;
   
        { 'DCHELP2','SORT','SORT+COMMAND'},     ;
   
        { 'DCHELP3','CATEGORY','CATEGORY+COMMAND'} }, .t. )
   

   

Source/Library:

See Also:

dc_pack()

Pack the database with the proper operator prompts

Syntax:

Arguments:

    (lUserPrompt) if .TRUE. will prompt the user to continue or
   
 abort the packing process, if .FALSE. the pack will be
   
 performed with no user input.
   

   
 (cPackMethod) is a single character designating the type
   
 of pack to perform.
   

   
  cPackMethod
   
  -----------
   
 "F" - Fast (default)
   
 "S" - Slow (removes dead-space from memo file)
   

   

Description:

Examples:

    do while .t.
   
   @ 10,10 prompt "open a database"
   
   @ 11,10 prompt "browse database"
   
   @ 12,10 prompt "pack database"
   
   menu to nChoice
   
   do case
   
     case nChoice = 1
   
       dc_dbfopen()
   
     case nChoice = 2
   
       dc_browsedb()
   
     case nChoice = 3
   
       DC_PACK()
   
   endcase
   
 enddo
   

   

Source/Library:

See Also:

dc_parent()

Return the Alias name of the Parent database

Syntax:

Arguments:

    (lSelect) if .TRUE. will also select the parent database's
   
 work area.  .FALSE. is the default.
   

   

Returns:

    A character string.
   

   

Description:

Examples:

    USE invoices INDEX invcust
   
 USE customer NEW
   
 SET RELATION TO cust_nmbr INTO invoice
   
 SELECT invoice
   
 ? DC_PARENT()
   
 CUSTOMER
   

   

   

Source/Library:

See Also:

dc_parentval()

Get the value of the relational data from the Parent

Syntax:

Arguments:

    (@cParent) is a variable, passed by reference, to store the
   
 name of the Parent Alias.
   

   

Returns:

    A value equivalent to the relational expression based on the
   
 currently selected record of the Parent Database.
   

   

Description:

Examples:

    USE invoices INDEX invcust
   
 USE customer NEW
   
 SET RELATION TO cust_nmbr INTO invoice
   
 SKIP 10
   

   
 ? cust_nmbr
   
 23876
   

   
 SELECT invoice
   

   
 ? DC_PARENTVAL()
   
 23876
   

   

   

Source/Library:

See Also:

dc_path()

Return the path or file name from a file specification string

Syntax:

Arguments:

    (cFileSpec) is a string containing a directory and file name.
   

   
 (lFileName) if .False. (default) will return the path from the
   
 string.  If .True. then the file name will be returned.
   

   

Returns:

    A character string.
   

   

Description:

Examples:

    set default to g:\customer\data
   
 use customer
   
 cFileSpec := dc_dbfname()
   
 ? cFileSpec
   
  G:\CUSTOMER\DATA\CUSTOMER.DBF
   
 ? DC_PATH(cFileSpec)
   
  G:\CUSTOMER\DATA\
   
 ? DC_PATH(cFileSpec,.t.)
   
  CUSTOMER.DBF
   

   

Source/Library:

See Also:

dc_pathfound()

Return the directory name in which a file is found

Syntax:

Arguments:

    (cFileName) is the name of the file to find.
   

   

Returns:

    A character string.
   

   

Description:

Examples:

    SET DEFAULT TO \customer\data
   
 SET PATH TO \mytools;\dclip
   
 ? DC_PATHFOUND('CUSTOMER.DBF')
   
 \customer\data\
   
 ? DC_PATHFOUND('MYTOOLS.DBF')
   
 \mytools\
   
 ? DC_PATHFOUND('DCPRINT.DBF')
   
 \dclip
   

   

Source/Library:

See Also:

dc_pause()

Pause program execution for a specified amount of time

Syntax:

Arguments:

    (nSeconds) is the amount of time to pause.
   

   
 (lAbort) if .TRUE. will abort the pause if any key is
   
 pressed or if a mouse button is pressed.  If .FALSE.
   
 (default), then the pause will continue regardless of
   
 the keyboard or mouse activity.
   

   

Returns:

    nil
   

   

Description:

Examples:

    DC_PAUSE(.05)  // pause .05 seconds
   

   

Source/Library:

See Also:

dc_pchoice()

Pop-up a menu to direct output to Screen, Printer or File

Syntax:

Arguments:

    (cHeading) is the title to place at the top of the selection
   
 menu.
   

   

Returns:

    A character string.
   

   
 If the user selects PRINTER the output will be a string equal
   
 to the value of SET(_SET_PRINTFILE).  If no printer output file
   
 has been set, then the ouptut will be "PRN".
   

   
 If the user selects SCREEN the output will be "SCREEN".
   

   
 If the user selects DOS FILE, the user will be prompted to
   
 enter the name of the file and the name entered will be returned.
   

   
 If the user presses the ESCape key then a null ("") will be
   
 returned.
   

   

Description:

Examples:

    use customer
   
 cPrintMode := DC_PCHOICE(' Select Output Mode for Report ' )
   
 if empty(cPrintMode)
   
   return .f.
   
 endif
   
 if cPrintMode # 'SCREEN'
   
   set printer to (cPrintMode) additive
   
   set print on
   
   set console off
   
 endif
   
 report form customer
   
 set print on
   
 set console on
   

   

Source/Library:

See Also:

dc_pickcase()

A function that replaces CASE..ENDCASE statements

Syntax:

Arguments:

    (xValue) is any value of the same TYPE as the values in
   
 (aValues).  For example, if (aValues) is a set of character
   
 strings, then (xValue) must be a character string.
   

   
 (cOperator) is the operator to use when performing the CASE
   
 evaluation.  Only the following operators are valid:
   

   
 Operator    Description
   
 --------   --------------------------
   
   =         Equal to
   
   ==        Exactly equal to
   
   )         Greater than
   
   (         Less than
   
   )=        Greater than or Equal to
   
   (=        Less than or Equal to
   
   ()        Not Equal to
   
   $         Contains
   

   
 (aValues) is an array of values to match to (xValue) based
   
 on (cOperator).  The position in the array (element number) of
   
 the first CASE that matches will become a pointer the the
   
 value in (aReturns) to return.
   

   
 (aReturns) is an array of the same length as (aValues).  This
   
 array may contain data elements of any type.
   

   

Returns:

    An element from (aReturns).
   

   

Description:

Source/Library:

dc_popcalc()

A "moused", full-function calculator

Syntax:

Arguments:

    (nCurVal) is the starting value to display in the calculator
   
 accumulator.  If no value or 0 is passed then the old STATIC
   
 value will be retained.
   

   
 (nStRow) and (nStCol) are the start display coordinates.  If
   
 no values are passed then the calculator will be displayed
   
 relative to the current cursor position.
   

   

   

Returns:

    The value of the calculator accumulator.
   

   

   

Description:

Examples:

    @ 12,10 say 'Sales Tax' get nTax ;
   
   VALID dc_readclick( @nTax, { |n| n:=DC_POPCALC(),.t.} ) ;
   
   PICKLIST
   

   

   

Source/Library:

See Also:

dc_popdate()

A "moused" calendar for selecting a date

Syntax:

Arguments:

    (dCurDate) is the starting date to highlight in the calendar.
   
 If no value is passed then the current system date will be
   
 the default.
   

   
 (nStRow) and (nStCol) are the start display coordinates.  If
   
 no values are passed then the calendar will be displayed
   
 relative to the current cursor position.
   

   

   

Returns:

    The date selected.
   

   

   

Description:

Examples:

    @ 13,10 say 'Date' get dDate ;
   
  VALID dc_readclick( @dDate, { |d| d:=DC_POPDATE(),.t.} ) ;
   
  PICKLIST
   

   

   

   

   

Source/Library:

See Also:

dc_popscrn()

Restore a screen area from the screen stack

Syntax:

Arguments:

    (aScrnStack) is an array that contains screens created by
   
 DC_PUSHSCRN().
   

   

Returns:

    An array containing the new contents of the screen stack.
   

   

Description:

Examples:

    aStack := {}
   
 aStack := dc_pushscrn(aStack)  // save current screen
   
 cls   // clear the screen
   
 aStack := dc_pushscrn(aStack,4,10,8,70,.T.,,,,;
   
          ' Enter a Command ',10)
   
 cCommand := space(50)
   
 @ 6,12 get cCommand
   
 read
   
 aStack := DC_POPSCRN(aStack)
   
 aStack := DC_POPSCRN(aStack)
   

   

Source/Library:

See Also:

dc_pready()

Test printer status in a loop and prompt operator

Syntax:

Arguments:

    (lPrint) if .TRUE. will output is to printer (default).  Use
   
 this option to restore device to print after error messages are
   
 displayed. .FALSE. will output is to display.  Use this option
   
 to restore device to screen after error messages are displayed.
   

   
 (lDispMsg) if .TRUE. will display message in a window : "press
   
 escape to abort print" .FALSE. will display no message
   
 (default)
   

   

Returns:

    .t. - if escape key not pressed or escape is pressed and user
   
       selects "Resume" print, and printer is ready.
   
 .t. - if printer is not ready and user has chosen to route printed
   
       output to a file.
   
 .f. - if ESCape key pressed and operator selects "Quit".
   
 .f. - if printer not ready
   

   
 NOTES :
   

   
 If printer is not ready, operator is given the option to route
   
 printout to another print device or to a file or abort the printout.
   

   

Description:

Examples:

    REPORT FORM custlist WHILE DC_PREADY(.t.,.t.) TO PRINT
   
 REPORT FORM custlist WHILE DC_PREADY(.f.,.f.)
   

   

   

   

Source/Library:

See Also:

dc_predefadd()

Add #define statement to the pre-processor translate array

Syntax:

Arguments:

    (cParam) is the define statement to add to the preprocessor
   
 array.
   

   

Description:

Examples:

    DC_PREDEFADD( 'BR_COL  dc_browvalue(50)' )
   
 DC_PREDEFADD( 'BR_ROW  dc_browvalue(51)' )
   
 dc_qdot()
   
 . ? BR_COL, BR_ROW
   
    10,     21
   

   

Source/Library:

See Also:

dc_predefine()

Translate all manifest constants in command string

Syntax:

Arguments:

    (cCommand) is a command string.
   

   
 (nRecurs) is a number used for handling recursion calls.
   
 DC_PreDefine() allows a maximum of 10 recursions.
   

   
 (lPickList) if .TRUE. will display a pick-list of all
   
 currently defined manifest constants and all standard
   
 manifest constants included in the complete set of Clipper
   
 *.CH files.  The character-string equivalent of the
   
 selected item in the list will be returned.
   

   

   

Returns:

    A character string.
   

   

Description:

Examples:

    -- Example 1 --
   

   
 dc_predefadd( 'BR_COL  dc_browvalue(50)' )
   
 dc_predefadd( 'BR_ROW  dc_browvalue(51)' )
   
 ? DC_PREDEFINE( 'QOUT( BR_ROW, BR_COL )' )
   
 QOUT( dc_browvalue(50), dc_browvalue(51) )
   

   
 -- Example 2 --
   

   
 accept "enter a command" to cCommandLine
   
 // - Convert any #defines in Pre-processor array
   
 cCommandLine := DC_PREDEFINE( cCommandLine )
   
 // - Translate any #commands in Pre-processor array
   
 cFunction := dc_pretranslate( cCommandLine )
   
 IF !empty( cFunction )
   
   dc_do( cFunction )
   
 ENDIF
   

   

Source/Library:

See Also:

dc_predisable()

Disable or "deactivate" a command set

Syntax:

Arguments:

    (cCommandSet) is the name of the command set to enable.  This
   
 is the same name as the pre-processor file name that was
   
 previously loaded with the DC_PREINCLUDE() function.
   

   

Returns:

    A logical .TRUE. if the command set is disabled, .FALSE. if
   
 the command set does not exist.
   

   

Description:

Examples:

    dc_preinclude( 'MENUS_1.CH' )
   
 dc_preinclude( 'MENUS_2.CH' )
   
 do while .t.
   
   @ 10,10 prompt "run a command"
   
   @ 11,10 prompt "disable a command set"
   
   @ 12,10 prompt "enable a command set"
   
   menu to nChoice
   
   do case
   
     case nChoice = 1
   
       accept "enter a command" to cCommand
   
       aFunctions := dc_translate( cCommand )
   
       for i := 1 to len(aFunctions)
   
         dc_do( aFunctions[i] )
   
       next
   
     case nChoice = 2
   
       accept "enter command set to disable" to cSet
   
       DC_PREDISABLE( cSet )
   
     case nChoice = 3
   
       accept "enter command set to enable" to cSet
   
       dc_preenable( cSet )
   
   endcase
   
 enddo
   

   

Source/Library:

See Also:

dc_preenable()

Enable or "activate" a command set

Syntax:

Arguments:

    (cCommandSet) is the name of the command set to enable.  This
   
 is the same name as the pre-processor file name that was
   
 previously loaded with the DC_PREINCLUDE() function.
   

   
 (cExpression) is an optional expression that will be evaluated
   
 each time a command is interpreted and will enable the command
   
 set only if the expression evaluates .TRUE.
   

   

Returns:

    A logical .TRUE. if the command set is enabled, .FALSE. if
   
 the command set does not exist.
   

   

Description:

Examples:

    -- Example 1 --
   

   
 . dc_include('MYBROWSE.CH')
   
 . DC_PREENABLE( 'MYBROWSE','ALIAS() = "MYMAIL"' )
   

   

   
 -- Example 2 --
   

   
 dc_preinclude( 'MENUS_1.CH' )
   
 dc_preinclude( 'MENUS_2.CH' )
   
 do while .t.
   
   @ 10,10 prompt "run a command"
   
   @ 11,10 prompt "disable a command set"
   
   @ 12,10 prompt "enable a command set"
   
   menu to nChoice
   
   do case
   
     case nChoice = 1
   
       accept "enter a command" to cCommand
   
       aFunctions := dc_translate( cCommand )
   
       for i := 1 to len(aFunctions)
   
         dc_do( aFunctions[i] )
   
       next
   
     case nChoice = 2
   
       accept "enter command set to disable" to cSet
   
       dc_predisable( cSet )
   
     case nChoice = 3
   
       accept "enter command set to enable" to cSet
   
       DC_PREENABLE( cSet )
   
   endcase
   
 enddo
   

   

Source/Library:

See Also:

dc_preexclude()

Unload a .CH file from the pre-processor translate table

Syntax:

Arguments:

    (cFileName) is the name of the pre-processor directive file to
   
 unload.
   

   
 (lClearAll) if .TRUE. will unload ALL pre-processor directive
   
 files.
   

   

Returns:

    A logical .TRUE. if the pre-processor file directives were
   
 unloaded, .FALSE. otherwise.
   

   

Description:

Examples:

    dc_preinclude( 'MYCMDS.CH' )
   
 accept "enter a command" to cCommand
   
 aFunctions := dc_translate( cCommand )
   
 for i := 1 to len(aFunctions)
   
   dc_do( aFunctions[i] )
   
 next
   
 DC_PREEXCLUDE( 'MYCMDS.CH' )
   

   

Source/Library:

See Also:

dc_prehelp()

Display status of pre-processor directives in memory

Syntax:

Arguments:

    (cVerb) is the name of the starting verb for each set of
   
 directives to display.  If this argument is not given, then all
   
 #translate commands in the pre-processor array will be
   
 displayed.
   

   

Description:

Source/Library:

dc_preinclude()

Load a .CH file into the pre-processor translate table

Syntax:

Arguments:

    (cFileName) is the name of the file that contains pre-processor
   
 directives.  If no drive and directory is included in the
   
 argument, then the search path in the SET INCLUDE dos
   
 environment statement will be searched for the file.  If no
   
 extension is given then .CH is assumed.
   

   

Description:

Examples:

    DC_PREINCLUDE( 'MYCMDS.CH' )
   
 accept "enter a command" to cCommand
   
 aFunctions := dc_translate( cCommand )
   
 for i := 1 to len(aFunctions)
   
   dc_do( aFunctions[i] )
   
 next
   

   

   

Source/Library:

See Also:

dc_preinit()

Initialize or Clear the pre-processor translation table

Syntax:

Arguments:

    (lClear) will clear all command sets from the pre-processor
   
 array.
   

   

Description:

Source/Library:

dc_preload()

Load a *.CH file into memory for translating commands

Syntax:

Arguments:

    (cFileName) is the name of the file that contains pre-processor
   
 directives.  If no drive and directory is included in the
   
 argument, then the search path in the SET INCLUDE dos
   
 environment statement will be searched for the file.  If no
   
 extension is given then .CH is assumed.
   

   

Returns:

    A multi-dimensional array of seven (7) elements.  Elements
   
 1-3 are parallel sub-arrays equal in length to the total number
   
 of #translate/#xtranslate directives.  Elements 4 and 5 are
   
 parallel sub-arrays equal in length to the total number of
   
 #define directives.
   

   
 Element    Type               Description
   
 --------  -----------------  ----------------------------------------
   
  -- translate arrays --
   

   
  [1]      Array (Character)     (matchPattern)
   
  [2]      Array (Character)  (resultPattern)
   
  [3]      Array (Logical)   .t. if #xtranslate, .f. if #translate
   

   
  -- define arrays --
   

   
  [4]      Array (Character)  (idConstant)
   
  [5]      Array (Character)  (resultText)
   

   
  -- miscellaneous --
   

   
  [6]      Character         Name of source file
   
  [7]      Logical            .t. if enabled, .f. if disabled
   

   

Description:

Examples:

    aPrePros := DC_PRELOAD('MYCMDS.CH')
   
 accept 'enter a command' to cCommand
   
 cVerb := dc_txtword(upper(cCommand),1)
   
 nFound := 1
   
 cFunction := ''
   
 do while nFound ) 0
   
   nFound := ascan( aPrePros[1], ALLTRIM(cVerb), nVerbFound )
   
   if nFound=0
   
     exit
   
   endif
   
   cFunction := dc_prepros(cCommand, aPrePros[1,nFound],;
   
                aPrePros[2,nFound],  aPrePros[3,nFound])
   
   if empty(cFunction)
   
     nFound++
   
   else
   
     exit
   
   endif
   
 enddo
   
 if !empty(cFunction)
   
   dc_do(cFunction)
   
 endif
   

   

Source/Library:

See Also:

dc_prepros()

Translate a command line using passed templates

Syntax:

Arguments:

    (cCmdLine) is the command line to pre-process.
   

   
 (cTmpLine) contains the (matchPattern) in the same form as
   
 supported by the #translate/#xtranslate command.  This is the
   
 portion of the directive preceding the =) characters.
   

   
 (cResultLine) contains the (resultPattern) in the same form as
   
 supported by the #translate/#xtranslate command.  This is the
   
 portion of the directive following the =) characters.
   

   

Returns:

    A character string.  If the translation is successful, then
   
 the string will contain a set of expressions, separated by commas.
   

   
 If the translation is unsuccessful, then the string will be a
   
 null (""))
   

   

Description:

Examples:

    if cVerb='COPY'
   
    cFunction := DC_PREPROS(cCommandLine,                     ;
   
         'COPY [TO ((file))] [DELIMITED [WITH (*delim*)]] '+  ;
   
         '[FIELD (fields,...)] [FOR (for)] [WHILE (while)] '+ ;
   
         '[NEXT (next)] [RECORD (rec)] [(rest:REST)] [ALL]',  ;
   
         '__dbCopyDelim(((file)),((delim)),{((fields))},'+    ;
   
         '({for}), ({while}),(next),(rec),(.rest.))')
   
    if empty(cFunction)
   
       cFunction := DC_PREPROS(cCommandLine,               ;
   
         'COPY [TO ((file))] [SDF][FIELD (fields,...)]'+       ;
   
         '[FOR (for)][WHILE (while)][NEXT (next)]'+         ;
   
         '[RECORD (rec)][(rest:REST)][ALL]',                ;
   
         '__dbCopySDF(((file)), {((fields))},'+            ;
   
         '({for}), ({while}), (next),(rec),(.rest.))')
   
    endif
   
    if empty(cFunction)
   
       cFunction := DC_PREPROS(cCommandLine,               ;
   
         'COPY [TO ((file))][FIELD (fields,...)]'+            ;
   
         '[FOR (for)][WHILE (while)][NEXT (next)]'+           ;
   
         '[RECORD (rec)][(rest:REST)][ALL]',                  ;
   
         '__dbCopy(((file)),{((fields))},({for}),'+           ;
   
         'DC_ODBLOCK(({while}),({for}),(next),,"Copied"),'+   ;
   
         '(next),(rec),(.rest.))')
   
    endif
   
    if !empty(cFunction)
   
      dc_do(cFunction)
   
    endif
   
 endif
   

   

Source/Library:

See Also:

dc_pretradd()

Add a new command to the pre-processor translate table

Syntax:

Arguments:

    (cParam) is the #translate directive to add to the preprocessor
   
 array in the form:  (matchpattern) =) (resultpattern).
   

   
 (lXtran) if .TRUE. will establish the directive as an
   
 #xtranslate type directive which requires that all command
   
 verbs be entered in full-length words rather than allowing them
   
 to be truncated to four characters.  Default is .FALSE.
   

   

Description:

Examples:

    DC_PRETRADD( 'DIAL (n)  =)  DIALOUT(((n)))' )
   
 DC_PRETRADD( 'BYEBYE =) __QUIT()' )
   
 dc_qdot()
   
 . DIAL 555-1212
   
 . BYEBYE
   

   

Source/Library:

See Also:

dc_pretranslate()

Translate a command using directives in pre-processor array

Syntax:

Arguments:

    (cCommand) is the command line to translate.
   

   
 (cVerb) is the first word in the command line (in upper case).
   
 This argument, if provided, will speed up the search.  If no
   
 argument is passed, then DC_PRETRANSLATE() will extract the
   
 verb from the (cCommand) argument.
   

   

Returns:

    A character string containing a list of functions separated by
   
 semicolons.
   

   

Description:

Examples:

    -- Example 1 --
   

   
 dc_pretradd( 'DIAL (n)  =) DIALOUT(((n))' )
   
 ? DC_PRETRANSLATE( 'DIAL 555-1212')
   
 DIALOUT("555-1212")
   

   
 -- Example 2 --
   

   
 accept "enter a command" to cCommandLine
   
 // - Convert any #defines in Pre-processor array
   
 cCommandLine := dc_predefine( cCommandLine )
   
 // - Translate any #commands in Pre-processor array
   
 cFunction := DC_PRETRANSLATE( cCommandLine )
   
 IF !empty( cFunction )
   
   dc_do( cFunction )
   
 ENDIF
   

   

Source/Library:

See Also:

dc_print()

Invoke the printer manager menu system

Syntax:

Arguments:

    NONE
   

   

Returns:

    NIL
   

   

Description:

Source/Library:

See Also:

dc_printcnv()

Convert printer pseudo codes to escape sequence

Syntax:

Arguments:

    (cPseudoCodes) is a string of characters.  Each character in
   
 the string is a pointer to an escape sequence in the currently
   
 selected printer driver or designated driver.
   

   
 Code   Description
   
 -----  ------------------------------------------------
   
   F    FORM FEED - Page eject.
   
   P    PICA.  10 Characters per inch.
   
   E    ELITE.  12 Characters per inch.
   
   C    COMPRESSED.  17 Characters per inch.
   
   Q    QUALITY.  Letter Quality mode
   
   N    NORMAL.  Data Processing Character Mode
   
   D    DOUBLE WIDE ON - Elongated characters
   
   S    SET DOUBLE WIDE OFF - Elongated characters off
   
   M    MARGINS ON - Set left and right margins
   
   O    OFF MARGINS - Turn off left and right margins
   
   A    Set UNDERLINE ON
   
   B    Set UNDERLINE OFF
   
   G    Set BOLD ON
   
   H    Set BOLD OFF
   
   U    6 Lines Per Inch
   
   V    8 Lines Per Inch
   
   X    Set ITALICIZED ON
   
   Y    Set ITALICIZED OFF
   
   I    INITIALIZE - Printer initialization code sequence
   
   R    RESET - Printer reset to default settings sequence
   
   J    Send START SPOOL COMMAND to DOS
   
   K    Send END SPOOL COMMAND to DOS
   
   0-9   User-defined psuedo-codes
   

   
 (nRecord) is the database record number of the printer driver
   
 to select.  If no argument is passed, or 0 is passed, then the
   
 "tagged" printer driver ( see DC_PRINTSEL() ) will be used.
   

   

Description:

Examples:

    // select a printer driver
   
 nPrinter := dc_printsel()
   
 // get the escape sequence for Compressed/8 lines per inch
   
 cPrintString := DC_PRINTCNV( 'CU', nPrinter )
   
 set print on
   
 ?? cPrintString
   
 report form customer to print
   

   

Source/Library:

See Also:

dc_printcode()

Pop-Up a pick-list of Printer Pseudo-Codes

Syntax:

Arguments:

    (cMask) is an optional list of codes to include in the
   
 pick-list.  If this argument is not passed then all codes will
   
 be included.
   

   

Description:

Examples:

    -- Example 1 --
   

   
 cPrintCodes := ''
   
 /* -- Select a printer driver -- */
   
 dc_printsel()
   
 do while lastkey()#27
   
   // build a list of printer psuedo-codes
   
   cPrintCodes += DC_PRINTCODE()
   
 enddo
   
 /* -- Convert pseudo-codes to codes to send to printer -- */
   
 cPrintString := dc_setp( cPrintCodes )
   
 set print on
   
 ?? cPrintString
   
 report form customer to print
   

   

   
 -- Example 2 --
   

   
 /* -- Only allow Underline, Bold, and Italics -- */
   
 cCodes := DC_PRINTCODE( "AGX" )
   

   

Source/Library:

See Also:

dc_printrec()

Output the current record to the printer

Syntax:

Arguments:

    (nRow) is the starting printer or screen row.
   

   
 (aFields) is an array of field names to print.  If this
   
 argument is not passed then all fields of the current work area
   
 will be used.
   

   
 (lRelation) if .TRUE. will also include all fields in all child
   
 relations.  This argument is needed only if (aFields) is not
   
 passed. If .FALSE. then only the fields in the current work
   
 area will be printed.
   

   
 (lPrint) if .TRUE. (default) will output the data to the
   
 printer. If .FALSE., then the output will go to the screen.
   

   

Description:

Examples:

    go top
   
 nRow := 1
   
 do while !Eof() .and. dc_pready()
   
   nRow := DC_PRINTREC( nRow+2 ,,, .t. )
   
   skip
   
   if nRow ) 55 - fcount()
   
     nRow := 1
   
   endif
   
 enddo
   

   

Source/Library:

dc_printsel()

Select the system printer from the printer database

Syntax:

Arguments:

    (nRecord) is the printer record to select.  If no argument is
   
 passed or (nRecord) is 0 then a pick-list of printers will be
   
 displayed for the user to choose from.
   

   

Returns:

    A numeric value equal to the record number of the printer
   
 selected.
   

   

Description:

Examples:

    // select a printer driver
   
 DC_PRINTSEL()
   
 // get the escape sequence for Compressed/8 lines per inch
   
 cPrintString := dc_printcnv( 'CU' )
   
 set print on
   
 ?? cPrintString
   
 report form customer to print
   

   

Source/Library:

See Also:

dc_proc()

Load / clear a procedure to / from Procedure-exclusion table

Syntax:

Arguments:

    (cProc) is the name of the procedure or function to bypass.
   

   
 (nNumber) is used only with the (lClear) option to clear a
   
 specified procedure name from the procedure table.  If (number)
   
 is 0 then all procedures will be cleared.
   

   
 (lClear) is used only with the (nNumber) option.
   

   

Returns:

    nil
   

   

Description:

Examples:

    // Bypass functions MAINMENU(), GRAPH(), CALC()
   
 DC_PROC( 'MAINMENU' )
   
 DC_PROC( 'GRAPH' )
   
 DC_PROC( 'CALC' )
   

   
 // Clear item 2 from procedure table
   
 DC_PROC( , 2, .t. )
   

   
 // Clear all items from procedure table
   
 DC_PROC( , 0, .t. )
   

   
 // Display all items in procedure table
   
 DC_PROC()
   

   

Source/Library:

dc_progload()

Load a program from the Program Catalog to an array

Syntax:

Arguments:

    (cProgName) is the Tag Name of the program in the DCPROG.DBF
   
 Program Catalog file.  If no parameter is passed, then a pick-
   
 list of available programs will be displayed.
   

   
 (lMessage) if .TRUE. (default) will display an error message
   
 if the program could not be found in the DCPROG.DBF
   
 dictionary.  If .FALSE., then no message will be displayed.
   

   
 (cProgram) is an optional character string (memo text )
   
 containing the program to convert to an array.  If this
   
 parameter is passed, then the Program Catalog will not be
   
 searched and (cProgName) will be ignored.
   

   
 (lCache) if .TRUE. (default) will store the output array into
   
 a cache memory for faster loading of the program if it is
   
 called again.  If (lCache) is .FALSE. or if DC_MEMCACHE()
   
 is set to 0, then the program will be loaded each time from
   
 the dictionary file.
   

   

   

   

   

   

   

Returns:

    A multi-dimensional array containing the program commands,
   
 compiler pointers, etc.
   

   

Description:

Examples:

    -- Example 1 --
   

   
 /* Program stored in 'TEST' record of DCPROG.DBF :
   

   
 PARAMETERS a,b,c,d
   
 CLS
   
 USE CUSTOMER
   
 nReceivables := 0
   
 DO WHILE !EOF()
   
   ? 'Record',RecNo()
   
   ?? FieldGet(a)
   
   ?? FieldGet(b)
   
   ?? FieldGet(c)
   
   ?? FieldGet(d)
   
   IF !EMPTY(phone1)
   
     ?? phone1
   
   ELSEIF !EMPTY(phone2)
   
     ?? phone2
   
   ENDIF
   
   nReceivables += balance
   
 ENDDO
   
 RETURN nReceivables
   
 */
   

   
 aProgram := DC_PROGLOAD('TEST')
   
 nMoneyDue := DC_Interpret( aProgram, { 3, 5, 6, 9 } )
   
 ? nMoneyDue
   
 wait
   

   

   

Source/Library:

See Also:

dc_progmaint()

Maintain the DCPROG.DBF Program Catalog File

Syntax:

Arguments:

    None.
   

   

Returns:

    Nil.
   

   

   

Description:

Source/Library:

See Also:

dc_program()

Run an "Interpreted" program from Program Catalog or Array

Syntax:

Arguments:

    (cProgName) is the Tag Name of the program in the DCPROG.DBF
   
 Program Catalog file.  If no parameter is passed, then a pick-
   
 list of available programs will be displayed.  If an array
   
 (aProgram) is passed then it must conform to the structure
   
 of the array returned by DC_PROGLOAD().
   

   
 (aParams) is a single-dimensional array of parameters to pass
   
 to the program being interpreted.  There should be one element
   
 in the array for each parameter included in the PARAMETERS
   
 statement in the interpreted program.  If less parameters are
   
 passed than specified in the PARAMETERS statement, the unpassed
   
 parameters will be initialized to NIL.
   

   
 (cProgram) is an optional character string (memo text )
   
 containing the program to convert to an array.  If this
   
 parameter is passed, then the Program Catalog will not be
   
 searched and (cProgName) will be ignored.
   

   

Returns:

    The value returned by the RETURN (xValue) statement in the
   
 intrepreted program.  If no RETURN value is entered into the
   
 program, then a NIL is returned.
   

   

   

Description:

Examples:

    -- Example 1 --
   

   
 /* Program stored in 'TEST' record of DCPROG.DBF :
   

   
 PARAMETERS a,b,c,d
   
 CLS
   
 USE CUSTOMER
   
 nReceivables := 0
   
 DO WHILE !EOF()
   
   ? 'Record',RecNo()
   
   ?? FieldGet(a)
   
   ?? FieldGet(b)
   
   ?? FieldGet(c)
   
   ?? FieldGet(d)
   
   IF !EMPTY(phone1)
   
     ?? phone1
   
   ELSEIF !EMPTY(phone2)
   
     ?? phone2
   
   ENDIF
   
   nReceivables += balance
   
 ENDDO
   
 RETURN nReceivables
   
 */
   

   
 nMoneyDue := DC_PROGRAM('TEST',{3,5,6,9})
   
 ? nMoneyDue
   
 wait
   

   

   

Source/Library:

See Also:

dc_progress()

Display a Progress bar

Syntax:

Arguments:

    (nMode) is a number 0,1, or 2 depending on the function
   
 desired:
   

   
  0 - Initialize Static values and display starting bar
   
  1 - Refresh bar with current value
   
  2 - Terminate and restore screen
   

   
 (nValue) is the "start" value to evaluate if (nMode) is 0 and
   
 the "current" value to evaluate if (nMode) is 1.  This must be
   
 less than or equal to (nMaxValue).  If this parameter is not
   
 passed then a static value will automatically be incremented
   
 by a value of 1.
   

   
 (nStRow) is the start display row.  This parameter is used
   
 only if (nMode) is 0.
   

   
 (nStCol) is the start display column.  This parameter is used
   
 only if (nMode) is 0.
   

   
 (nEnCol) is the end display column.  This parameter is used
   
 only if (nMode) is 0.
   

   
 (lBox) if .TRUE. (default) will paint a box around the progress
   
 bar starting at the passed coordinates, otherwise the progress
   
 bar only will be painted starting at the passed coordinates.
   

   
 (cColors) is a character string containing 2 color specfications
   
 separated by a comma.  The first color is the color of the box,
   
 the second is the color of the progress bar.  If no parameter
   
 is passed, then the current system color will be used for both
   
 colors.
   

   

Returns:

    Nil
   

   

Description:

Examples:

    ? 'Recalling all records'
   
 DC_PROGRESS( 0,,RecCount() )
   
 dbSetOrder(0)
   
 go top
   
 do while !Eof()
   
   DC_PROGRESS( 1, RecNo() )
   
   dbRecall()
   
   SKIP
   
 enddo
   
 DC_PROGRESS( 2 )
   

   

   

   

Source/Library:

See Also:

dc_prtest()

Test if the printer is ready and prompt operator

Syntax:

Arguments:

    NONE
   

   

Returns:

    .t. - if printer online and ready or operator has chosen to
   
       reroute  printout to another device or a file.
   

   
 .f. - if printer is not ready and operator desires to abort.
   

   

Description:

Examples:

    if .not. DC_PRTEST()
   
   return .f.
   
 endif
   
 report form custlist to print while dc_pready()
   

   

Source/Library:

See Also:

dc_prtsc()

Print any area of the screen

Syntax:

Arguments:

    (nStrow), (nStcol), (nEnrow), (nEncol) are the screen
   
 coordinates.
   

   
 (cFileName) is an optional file name to write the screen
   
 contents rather than outputting the screen to the printer.
   

   
 (cCurrScreen) is the contents of the screen to be printed or
   
 output to the printer.   If no argument is passed, then the
   
 current screen contents will be printed.
   

   
 (lAppend) if .TRUE. will append the contents of the screen to
   
 the current contents of (cFileName), otherwise the file will be
   
 overwritten.
   

   

Returns:

    .t. - if output OK
   

   
 .f. - if output not OK, ie, printer is not ready, or file cannot
   
       be created.
   

   

Description:

Examples:

    -- Example 1 --
   
 * Print screen if key F3 is hit
   
 setkey(-2, DC_PRTSC() )
   

   
 -- Example 2 --
   
 * Send contents of screen to SCREEN.TXT
   
 DC_PRTSC(,,,,'SCREEN.TXT')
   

   
 -- Example 3 --
   
 * Print only lines 12-20 of the screen
   
 DC_PRTSC(12,0,20,79)
   

   

Source/Library:

dc_purge()

Purge duplicate records from a database

Syntax:

Arguments:

    (cIndexExpr) is an expression of field names to use in determining
   
 how to determine the duplication of records.  For example, if
   
 you want to purge records that have duplication of information
   
 in which LAST_NAME, FIRST_NAME and STREET are identical, then
   
 use "UPPER(LAST_NAME+FIRST_NAME+STREET)" as    the expression.
   

   
 If (cIndex) expression is not given then a window will appear
   
 with a user prompt to enter an expression or to press ALT-F for
   
 the index builder.  If ALT-F is pressed, a pick-list of fields
   
 will appear to aid in building the expression.
   

   
 (cFileName) is an optional parameter that is the name of a new
   
 database which will contain the purged records.  If no argument
   
 is given, then no database will be created, instead the delete
   
 flag of the purged records will be set.
   

   
 (cRetainExpr) is an expression that determines which record of
   
 the set of duplicate records to retain (not mark for deletion).
   
 The default is "RECNO()".
   

   
 (lMax) if .TRUE. will retain the maximum value.  If .FALSE.
   
 (default) will retain the minimum value.
   

   
 (cFieldName) is the name of an optional numeric field in the
   
 database being purged.  This field is used to write a number
   
 from 0 to N.  If there are no duplicates, then a 0 will be written
   
 to the record.  If there ARE   duplicates then a 1 will be written
   
 to the RETAINED record and a number from 2 to N will be written to
   
 each duplicate.
   

   

Returns:

    NIL
   

   

Description:

Examples:

    /* Purge all duplicate records that have an exact match
   
    for Last Name, First Name, Phone Number and Street.
   
    Retain the record that has the latest Mail Date */
   

   
 . USE MAILLIST
   
 . DC_PURGE("LAST+FIRST+PHONE+STREET",,"MAIL_DATE",.t.)
   
 . dc_browsedb()
   
 . dc_pack()
   

   

Source/Library:

See Also:

dc_pushscrn()

Save a screen area and push onto the screen stack

Syntax:

Arguments:

    (aScrnStack) is an array to push the screen contents.
   

   
 (nSrow), (nScol), (nErow), (nEcol) are the screen coordinates.
   
 If no parameters are passed then the entire screen will be
   
 saved.
   

   
 (lExplode) if .TRUE. will explode a box within the passed
   
 coordinates.  If .FALSE. (default), no box will be painted.
   

   
 The following parameters are used only if (lExplode) is
   
 .TRUE. :
   

   
 (cColor1) is the color of the window frame. If none is
   
 passed, then the default color from the DCCOLOR array will
   
 be used.
   

   
 (cColor2) is the color of the window contents.  If none is
   
 passed, then the default color from the DCCOLOR array will
   
 be used.
   

   
 (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:

    An array containing the new contents of the screen stack.
   

   

Description:

Examples:

    aStack := {}
   
 aStack := DC_PUSHSCRN(aStack)  // save current screen
   
 cls   // clear the screen
   
 aStack := DC_PUSHSCRN(aStack,4,10,8,70,.T.,'B/W','N/W',,;
   
          ' Enter a Command ',10)
   
 cCommand := space(50)
   
 @ 6,12 get cCommand
   
 read
   
 aStack := dc_popscrn(aStack)
   
 aStack := dc_popscrn(aStack)
   

   

Source/Library:

See Also:

dc_putkey()

Stuff any keyboard value into Keyboard Buffer

Syntax:

Arguments:

    (nKey) is the INKEY() value of the key to stuff in the
   
 keyboard buffer.  This must be a value between -39
   
 and 320.
   

   
 (cKey) is a character string value to stuff in the keyboard
   
 buffer.
   

   
 (aKeys) is a single dimensional array consisting of elements
   
 that are single characters or Inkey() values or both.
   

   

   

Returns:

    nil
   

   

Description:

Examples:

    -- Example 1 --
   

   
 #include 'inkey.ch'
   
 DC_PUTKEY( K_ESC )
   

   

   
 -- Example 2 --
   

   
 // Add a set of keys to keyboard buffer
   
 DC_PutKey( { K_ALT_F, K_F10, K_ALT_K } )
   

   

   
 -- Example 3 --
   

   
 // Stuff a character string in the keyboard buffer
   
 DC_Putkey( 'USE JUNK' + CHR(13) )
   

   

   

Source/Library:

See Also:

dc_qdot()

Quick Dot-prompt interpreter

Syntax:

Arguments:

    (lDebug) if .TRUE. will display a double-dot prompt.
   
 .FALSE. is default.
   

   
 (lReturn) if .TRUE. will return to the calling program after
   
 each command is entered at the dot prompt.  If .FALSE., then
   
 DC_QDOT() will return to the calling program only if an empty
   
 command line is entered or the ESCape key is pressed.
   

   

   

Returns:

    A logical .TRUE. if the function was exited with a blank line
   
 or the ESCape key, .FALSE. otherwise.
   

   

Description: