home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / dos / prg / builder / libc5x.doc < prev    next >
Text File  |  1994-10-26  |  175KB  |  5,530 lines
  1.                                                Page: 1
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                            Aeolus Software
  9.                   FUNCTION LIBRARY REFERENCE GUIDE
  10.  
  11.  
  12.  
  13.  
  14.                              COPYRIGHT
  15.                c 1992, 1993, 1994 by Aeolus Software
  16.                        All rights reserved.
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.   Aeolus Software
  29.   P.O. Box 11915
  30.   St. Paul, MN  55111-0915
  31.   (612) 730-4135
  32.  
  33.   Mark H. Kania, CIS# 76270,2436
  34.                                              Page: 2
  35.  
  36.   Contents
  37.  
  38. INTRODUCTION . . . . . . . . . . . . . . . . . 5
  39. Conventions: . . . . . . . . . . . . . . . . . 6
  40. Alphabetical Proc/Func summary . . . . . . . . 7
  41. @..ABPROMPT ... / @..WINPROMPT ... . . . . . .16
  42. @..GET / @..WINGET . . . . . . . . . . . . . .17
  43. @..WINSAY .... . . . . . . . . . . . . . . . .19
  44. @....WINDOW .... . . . . . . . . . . . . . . .20
  45. ABGOBOTTOM() . . . . . . . . . . . . . . . . .21
  46. ABGOTOP(). . . . . . . . . . . . . . . . . . .22
  47. ABTBSKIP() . . . . . . . . . . . . . . . . . .23
  48. ADD_REC(). . . . . . . . . . . . . . . . . . .24
  49. ADDGET() . . . . . . . . . . . . . . . . . . .25
  50. ADDMPAD(). . . . . . . . . . . . . . . . . . .26
  51. *ADDPROMPT() . . . . . . . . . . . . . . . . .27
  52. APOP() . . . . . . . . . . . . . . . . . . . .28
  53. ASC2BIN(). . . . . . . . . . . . . . . . . . .30
  54. ASK(). . . . . . . . . . . . . . . . . . . . .31
  55. ASKMENU(). . . . . . . . . . . . . . . . . . .33
  56. BCHOICE(). . . . . . . . . . . . . . . . . . .35
  57. BETWEEN(). . . . . . . . . . . . . . . . . . .36
  58. BLDRERR(). . . . . . . . . . . . . . . . . . .37
  59. BROWSEDB() . . . . . . . . . . . . . . . . . .38
  60. BROWSER(). . . . . . . . . . . . . . . . . . .39
  61. BRWMOUSE() . . . . . . . . . . . . . . . . . .40
  62. CENTER() . . . . . . . . . . . . . . . . . . .41
  63. CHGDIR() . . . . . . . . . . . . . . . . . . .42
  64. CHGDSK() . . . . . . . . . . . . . . . . . . .43
  65. CHKCHR() . . . . . . . . . . . . . . . . . . .44
  66. CKPRTR() . . . . . . . . . . . . . . . . . . .46
  67. CRTMNUARRY() . . . . . . . . . . . . . . . . .47
  68. DBCHANGED(). . . . . . . . . . . . . . . . . .48
  69. DBREPL() . . . . . . . . . . . . . . . . . . .49
  70. DBSTATE(). . . . . . . . . . . . . . . . . . .50
  71. DBSTOR() . . . . . . . . . . . . . . . . . . .51
  72. DEC2HEX(). . . . . . . . . . . . . . . . . . .53
  73. DELCOLPUT(). . . . . . . . . . . . . . . . . .54
  74. DICTGET(). . . . . . . . . . . . . . . . . . .55
  75. DICTPUT(). . . . . . . . . . . . . . . . . . .56
  76. DELMPAD(). . . . . . . . . . . . . . . . . . .58
  77. DRVTST() . . . . . . . . . . . . . . . . . . .59
  78. DUPCHK() . . . . . . . . . . . . . . . . . . .60
  79.                                                  . Page: 3
  80.  
  81. EDT_MEMO() . . . . . . . . . . . . . . . . . .62
  82. ERRTONE(). . . . . . . . . . . . . . . . . . .63
  83. ETC(). . . . . . . . . . . . . . . . . . . . .64
  84. FEOF() . . . . . . . . . . . . . . . . . . . .65
  85. FGETS(). . . . . . . . . . . . . . . . . . . .66
  86. FGETSR() . . . . . . . . . . . . . . . . . . .67
  87. FIL_LOCK() . . . . . . . . . . . . . . . . . .68
  88. FLD_REPL() . . . . . . . . . . . . . . . . . .69
  89. GEN_MAINT(). . . . . . . . . . . . . . . . . .70
  90. GENVLD() . . . . . . . . . . . . . . . . . . .74
  91. GETEDIT(). . . . . . . . . . . . . . . . . . .76
  92. GOT(). . . . . . . . . . . . . . . . . . . . .78
  93. HEX2DEC(). . . . . . . . . . . . . . . . . . .79
  94. HNDLS(). . . . . . . . . . . . . . . . . . . .80
  95. IN_CANADA(). . . . . . . . . . . . . . . . . .81
  96. IN_USA() . . . . . . . . . . . . . . . . . . .82
  97. INFILE() . . . . . . . . . . . . . . . . . . .83
  98. INPATH() . . . . . . . . . . . . . . . . . . .85
  99. IOCTL(). . . . . . . . . . . . . . . . . . . .86
  100. ISEEK(). . . . . . . . . . . . . . . . . . . .88
  101. KYBD() . . . . . . . . . . . . . . . . . . . .90
  102. MAKE_EMPTY() . . . . . . . . . . . . . . . . .91
  103. MAKDIR() . . . . . . . . . . . . . . . . . . .92
  104. MAXHNDLS() . . . . . . . . . . . . . . . . . .93
  105. MENU() . . . . . . . . . . . . . . . . . . . .94
  106. MESSAGE(). . . . . . . . . . . . . . . . . . .97
  107. MGETROWCOL() . . . . . . . . . . . . . . . . .98
  108. MOUSCRS(). . . . . . . . . . . . . . . . . . .99
  109. MOUSEINIT(). . . . . . . . . . . . . . . . . 100
  110. MOUSEINT() . . . . . . . . . . . . . . . . . 101
  111. MSETROWCOL() . . . . . . . . . . . . . . . . 103
  112. MSGBOX() . . . . . . . . . . . . . . . . . . 104
  113. NET_USE(). . . . . . . . . . . . . . . . . . 106
  114. NOT_REQ(). . . . . . . . . . . . . . . . . . 107
  115. NUMERIC(). . . . . . . . . . . . . . . . . . 109
  116. OPEN_FIL() . . . . . . . . . . . . . . . . . 110
  117. PCKVLD() . . . . . . . . . . . . . . . . . . 112
  118. PLIST(). . . . . . . . . . . . . . . . . . . 115
  119. PUTKEY() . . . . . . . . . . . . . . . . . . 120
  120. READGETS() . . . . . . . . . . . . . . . . . 121
  121. REC_LOCK() . . . . . . . . . . . . . . . . . 122
  122. REL_MAINT(). . . . . . . . . . . . . . . . . 123
  123.    . . . . . . . . . . . . . . . . . . . Page: 4
  124.  
  125. REQ(). . . . . . . . . . . . . . . . . . . . 126
  126. RGHT_JST() . . . . . . . . . . . . . . . . . 127
  127. SAVE_IT(). . . . . . . . . . . . . . . . . . 128
  128. SETMOUSE() . . . . . . . . . . . . . . . . . 130
  129. SETMSGLIN(). . . . . . . . . . . . . . . . . 133
  130. SHADOW() . . . . . . . . . . . . . . . . . . 134
  131. SHOW_MEMO(). . . . . . . . . . . . . . . . . 135
  132. SHOW_TXT() . . . . . . . . . . . . . . . . . 136
  133. TEXTVIEW() . . . . . . . . . . . . . . . . . 138
  134. THERMOMETR() . . . . . . . . . . . . . . . . 142
  135. TIMEOUT(). . . . . . . . . . . . . . . . . . 144
  136. VAR(). . . . . . . . . . . . . . . . . . . . 148
  137. VARINIT(). . . . . . . . . . . . . . . . . . 150
  138. WAITKEY(). . . . . . . . . . . . . . . . . . 151
  139. WINBOTT(). . . . . . . . . . . . . . . . . . 152
  140. WINLEFT(). . . . . . . . . . . . . . . . . . 153
  141. WINPOP() . . . . . . . . . . . . . . . . . . 154
  142. WINPUSH(). . . . . . . . . . . . . . . . . . 155
  143. WINRIGHT() . . . . . . . . . . . . . . . . . 157
  144. WINSTYLE() . . . . . . . . . . . . . . . . . 158
  145. WINTOP() . . . . . . . . . . . . . . . . . . 159
  146.                                            Page: 5
  147.   INTRODUCTION
  148.  
  149.   The Aeolus Builder Clipper(tm) function library contains
  150.   many varied and useful functions that make programming in
  151.   Clipper faster and easier than ever before.  Thank you for
  152.   trying this shareware library.  Mark H. Kania: Owner Aeolus
  153.   Software: ASP Member.
  154.  
  155.   The functions in this document do not contain the real
  156.   function names as they appear in the library.  The library
  157.   function names are spelled exactly the same as this document
  158.   suggests except that they are prefixed by the letters "Ab"
  159.   (Aeolus Builder).  The source code you write and that is
  160.   generated by the Aeolus Code Generators does not need to use
  161.   the prefix characters.  The prefix characters are added by
  162.   the Clipper preprocessor, the file "Builder.ch" contains a
  163.   "#xtranslate" preprocessor directive for every function as
  164.   it is named in this document and prefixes it with the
  165.   letters "Ab".  This makes the source code (and the library
  166.   documentation) much more readable and at the same time makes
  167.   it so that the function names are unique.
  168.  
  169.   If you write programs that access these library functions
  170.   and do not "#include" the "Builder.ch" header file, you will
  171.   have to enter the "Ab" function name prefix every time you
  172.   call a Builder library function.
  173.  
  174.   Examples of many of these functions can be seen in the
  175.   Builder demonstration companion program.  Look for
  176.   BDEM22.ZIP on CompuServe or any ASP approved BBS.
  177.  
  178.   * These functions are located in BLDRASM.LIB.
  179.  
  180.   WARNING: Do NOT link BLDRASM.LIB into an overlay because
  181.   some of the routines take over system interrupts.  If these
  182.   routines are in an overlay, your computer WILL lockup!  That
  183.   is why it is a separate library.
  184.  
  185.   ++    These functions are new to BUILDER.LIB v2.2.
  186.   ^^    These functions are obsolete with Builder version 2.2.
  187.   ||    These functions are copied from the book "Programming
  188.   in Clipper" 2nd Edition by Stephen J. Straley (use by
  189.   permission)
  190.  
  191.   I would also like to highly recommend Steves's new book
  192.   "Clipper Power Tools" from Sirius Software it comes with a
  193.   diskette of indispensable Clipper routines.
  194.                                                 Page: 6
  195.   Conventions:
  196.   <expC>:    A character expression
  197.   <expL>:    A logical expression (i.e. .t. or .f.)
  198.   <expD>:    A date expression
  199.   <expN>:    A numeric expression, a number or calculation
  200.   <expA>:    An array
  201.   <exp>:     An expression that may be of different types
  202.   <expB>:    A Code Block
  203.   <expO>:    A Clipper Object
  204.  
  205.   Parameters notated inside square brackets ([]) are optional
  206.   parameters, defaults will be given where applicable.
  207.                                                 Page: 7
  208.   Alphabetical Proc/Func summary
  209.  
  210.   @ <row>, <col> ABPROMPT <expC> TO <expA>
  211.    [EXECUTE <exp>]
  212.    [WHEN <expL>]
  213.    [MESSAGE <expC> AT <expN1>, <expN2>]
  214.  
  215.   @ <row>, <col> GET <var> [normal getclauses]
  216.    [VALIDBLOCK <expB> | VALID <expL>]
  217.  
  218.   -OR-
  219.  
  220.   @ <row>,<col> GET <var> USING MENU <expA>
  221.  
  222.   -OR-
  223.  
  224.   @ <row>,<col> GET <var> USING DROPDOWN <expA>
  225.  
  226.   @ <winrow>, <wincol> WINGET <var> [normal getclauses]
  227.    [VALIDBLOCLK <expB> | VALID <expL>]
  228.  
  229.   -OR-
  230.  
  231.   @ <winrow>,<wincol> WINGET <var> USING MENU <expA>
  232.  
  233.   -OR-
  234.  
  235.   @ <winrow>,<wincol> WINGET <var> USING DROPDOWN <expA>
  236.  
  237.   @ <winrow>, <wincol> WINPROMPT  <expC> TO <expA>
  238.    [EXECUTE <exp>]
  239.    [WHEN <expL>]
  240.    [MESSAGE <expC> [AT <expN1>, <expN2>]]
  241.  
  242.   @ <winrow>, <wincol> WINSAY [say clauses]
  243.  
  244.   @ <top>,<left>,<bottom>,<right> WINDOW
  245.    [NOSAVE]  [NOCLEAR]  [NOSHADOW]
  246.    [NOBORDER]  [STYLE <expC>]
  247.    [COLOR <expC>]
  248.  
  249.   *ABGOBOTTOM( <expO> )
  250.    TBrowse go bottom procedure.
  251.  
  252.   *ABGOTOP( <expO> )
  253.    TBrowse go top procedure.
  254.  
  255.   *ABTBSKIP( <expN>, <expO> )
  256.    TBrowse database movement procedure.
  257.  
  258.  
  259.                                         Page: 8
  260.   *ADD_REC(<expN>)
  261.    Adds a blank .DBF record.
  262.  
  263. ADDMPAD(<expN1>,<expN2>,<expN3>,<expN4>,<expN5>,<expB>)
  264.    Add mouse pad.
  265.  
  266. *ADDPROMPT(<expA>,<expN1>,<expN2>,<expC1>[,<expB>][,<expN3>]
  267.      ;
  268.      [,<expN4>][,<expC2>])
  269.    Add a prompt to a menu array.
  270.  
  271. ASC2BIN(<expC>)
  272.    Converts ASCII control indicators to control characters.
  273.  
  274. ASK(<expC1>,<expC2>,<expN1>,<expN2>[,<expN3>][,<expC3>] ;
  275.      [,<expC4>])
  276.    Prompt and response function.
  277.  
  278. ASKMENU(<expC1>,<expA>,<expN1>,<expN2>[,<expN3>][,<expC2>] ;
  279.      [,<expC3>])
  280.    Prompt and response function.
  281.  
  282.  
  283.      APOP(<expN1>,<expN2>,<expN3>,<expN4>,<expA>,<expN5>[,<ex
  284.      pC2>][,<expC3>])
  285.    Choose multiple menu items from array.
  286.  
  287. BCHOICE( <expN1>, <expN2>, <expN3>,  <expN4>, <expA>[,
  288.      <expN2>][, <expL>] )
  289.    Similar to ACHOICE() but will accept mouse input.
  290.  
  291. BETWEEN(<exp1>,<exp2>,<exp3>)
  292.    Evaluates if expression 1 is greater than and equal to
  293.      expression 2 and less than and equal to expression 3.
  294.  
  295. *BLDRERR( <expO>, <expC> )
  296.    Builder error system.
  297.  
  298. BROWSEDB( <expA>[, <expL>] )
  299.    Operate a TBrowse object or and array of TBrowse
  300.      objects.
  301.  
  302. ++BROWSER(
  303.  
  304.      <expN1>,<expN2>,<expN3>,<expN4>[,<expC>][,<expN5>][,<exp
  305.      N6>])
  306.    Sets up window to browse a database.
  307.  
  308. *BRWMOUSE(<expN1>,<expN2>,<expN3>,<expN4>,<expO>)
  309.    Set up or remove mouse pads for a TBrowse object.
  310.  
  311.                                         Page: 9
  312.  
  313. CENTER(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>])
  314.    Centers text on the screen or within a window.
  315.  
  316. CHGDIR(<expC>)
  317.    Changes the DOS default directory.
  318.  
  319. CHGDSK(<expC>)
  320.    Changes the DOS default drive.
  321.  
  322. *CHKCHR(<expC1>,<expC2>,<expN1>,<expN2>,<expN3>[,<expC3>])
  323.    VALID, tests if keyed input is in <expC1>.
  324.  
  325. CKPRTR(<expN>)
  326.    Checks if parallel printer is available.
  327.  
  328. CRTMNUARRY(<expN1>,<expN2>,<expA>)
  329.    Create an 'across' type menu array.
  330.  
  331. DBCHANGED(<expA>)
  332.    Returns true if database fields do not exactly match
  333.      memory variables.
  334.  
  335. *DBREPL(<expA>)
  336.    Replaces database field variables with memory variables.
  337.  
  338. DBSTATE([<expC1>])
  339.    Returns all relevant database info in a string and, sets
  340.      back to a previous DBSTATE() also.
  341.  
  342. DBSTOR(<expA>)
  343.    Stores database field variables to memory variables.
  344.  
  345. DEC2HEX(<expN>)
  346.    Returns a Hexadecimal string of the passed integer.
  347.  
  348. DELCOLPUT( <expO>, <expN> )
  349.    Remove a column from a TBrowse object an place in the
  350.      the 'recoverable' columns list.
  351.  
  352. DELMPAD(<expN>)
  353.    Delete a mouse pad.
  354.  
  355. DICTGET( <expA>, <expC>, <exp> )
  356.    Get a value from a dictionary array.
  357.  
  358. DICTPUT( <expA>, <expC>, <exp> )
  359.    Put a value in a dictionary array.
  360.  
  361. DRVTST(<expC>)
  362.                               Page: 10
  363.   Test for floppy drive ready.
  364.  
  365. *DUPCHK(<expC1>,<expC2>,<expN1>,<expC3>,<expN2>,<expN3>, ;
  366.      <expN4>,
  367.      <expL>, <expC4>)
  368.    VALID function to test for a duplicate condition for the
  369.      keyed input.
  370.  
  371.  
  372.      EDT_MEMO(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2>
  373.      ,<expC3>, ;
  374.      <expC5>,<expC6>[,<expN5>][,<expL>]
  375.    Either stand alone or VALID function to display/edit a
  376.      Memo field inside a border.
  377.  
  378. ERRTONE([<expN>])
  379.    Beep speaker with optional sounds.
  380.  
  381. ETC(<expC>,<expN1>,<expN2>,<expN3>)
  382.    Calculate estimated time to complete an iterative
  383.      process.
  384.  
  385. FEOF([<expL>])
  386.    EOF detection  when reading a .SDF file using FGETS().
  387.  
  388. FGETS(<expN>)
  389.    Returns next record in a .SDF type file.
  390.  
  391. FGETSR(<expN>)
  392.    Returns the previous record in a .SDF type file.
  393.  
  394. FIL_LOCK(<expN>)
  395.    Locks a file for exclusive type activity.
  396.  
  397. FLD_REPL(<expC1>,<expC2>)
  398.    Replace one database field in a shared or single user
  399.      environment.
  400.  
  401. GETEDIT(<expC2>,<expN1>,<expN2>)
  402.    Save GETs to a database record.
  403.  
  404. *GEN_MAINT( ;
  405.  
  406.      <expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expA>[,<expN5>]
  407.      ;
  408.      [,<expL>][,<expC2>][,<expB>])
  409.    Generic file maintenance.
  410.  
  411.      *GENVLD(<expL1>,<expC1>,<expN1>,<expN2>,<expN3>,<expL2>[
  412.      ,<expC2>])
  413.  
  414.                                         Page: 11
  415.  
  416.    VALID generic function to test a user defined condition
  417.      on a GET.
  418.  
  419. *GOT(<expC>,<expN1>,<expN2>)
  420.    Get field data from a database record number and field
  421.      number.
  422.  
  423. HEX2DEC(<expC>)
  424.    Converts a string of Hexadecimal characters to a numeric
  425.      integer.
  426.  
  427. HNDLS()
  428.    Returns the maximum number of files handles configured
  429.      for the computer.
  430.  
  431. IN_CANADA(<expC>)
  432.    Returns true if the passed two byte string is a valid
  433.      Canadian province code.
  434.  
  435. IN_USA(<expC>)
  436.    Returns true if the passed two byte string is a valid
  437.      U.S. state code.
  438.  
  439.  
  440.      *INFILE(<expC1>,<expN1>,<expC2>,<expN2>,<expN3>,<expN4>,
  441.      <expL> [,<expC3>])
  442.    VALID function to only force data entered into a GET
  443.      field to be found in another file.
  444.  
  445. INPATH(<expC1>[,<expC2>])
  446.    Returns the pathname where the file <expC1> is located.
  447.    Checks directories listed in DOS environment variable
  448.      "PATH" or <expC2> environment variable if passed.
  449.  
  450. IOCTL( <expN1>, <expN2> )
  451.    Allows binary IO on files opened using low-level file
  452.      IO.
  453.  
  454. ++ISEEK(<exp>,<expC>,<expN>,<expL>)
  455.    Locate a record in a database via an index.
  456.  
  457. KYBD( <expC> )
  458.    Stuff the keyboard buffer.
  459.  
  460. MAKDIR(<expC>)
  461.    Creates a DOS directory.
  462.  
  463. MAKE_EMPTY(<expC>)
  464.    Create an empty memory variable based on the passed
  465.                                         Page: 12
  466.  
  467.    variable.
  468. MAXHNDLS(<expN>)
  469.    Tests system configuration for number of file handles.
  470.  
  471. MENU(<expA>[,<exp>][,<expO>][,<expL>])
  472.    Process a menu array.
  473.  
  474. MESSAGE(<expC1>,<expN1>,<expN2>[,<expN3>][,<expC2>])
  475.    Display a screen message.
  476.  
  477. MGETROWCOL(@<expN1>,@<expN2>)
  478.    Returns mouse row, column, and button state.
  479.  
  480. MOUSCRS(<expL>)
  481.    Turns the mouse cursor on and off.
  482.  
  483. MOUSEINIT()
  484.    Initialize mouse for a BUILDER application.
  485.  
  486. MOUSEINT(<expN1>,<expN2>,<expN3>,<expN4>)
  487.    Call the mouse driver interrupt.
  488.  
  489. MSETROWCOL(<expN1>,<expN2>)
  490.    Sets mouse rows and column position.
  491.  
  492. MSGBOX(<expC1>[,<expC2>][,<expC3>][,<expC4>][,<expN1>] ;
  493.      [,<expN2>][,<expN3>][,<expN4>])
  494.    Display a message box on the screen, optionally ask a
  495.      question.
  496.  
  497. *NET_USE(<expC1>,<expL>,<expN>,<expC2>[,<expC3>])
  498.    Network file open function.
  499.  
  500. NOT_REQ(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>])
  501.    VALID function to force a GET field to be empty.
  502.  
  503. NUMERIC(<expC>)
  504.    Check a character string for any non-numeric characters.
  505.  
  506. ++OPEN_FIL(<expC1>[,<expL1>][,<expC2>][,<expL2>][,<expC3>])
  507.    All purpose file open routine.
  508.  
  509. PCKVLD(<expC1>,<expN1>,<expN2>,<expL1>,<expC2>,<expL2> ;
  510.      [,<expC3>][,<expC4>])
  511.    VALID function to force entry into a GET field to be in
  512.      another database.  Gives user a pick list of the nearest
  513.      data to what was keyed.
  514.  
  515.  
  516.  
  517.                                         Page: 13
  518.  
  519.   PLIST(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expN5>,<expC1
  520.   >, ;
  521.  
  522.      <expC2>[,<expL1>][,<expC3>][,<expC4>][,<expB1>][,<expB2>
  523.      ]
  524.      [,<expL2>][,<expL3>][,<expC5>]
  525.    Picklist window function.
  526.  
  527. PUTKEY( <expN> )
  528.    Places a keystroke in the BIOS keyboard buffer.
  529.  
  530. READGETS( <expA>, <expL>, <expN> )
  531.    READs a getlist.  Provides cursor change on insert mode.
  532.  
  533. *REC_LOCK(<expN>)
  534.    Record lock function.
  535.  
  536. *REL_MAINT(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ;
  537.      <expB1>,<expC2>,<expA>,<expN5>[,<expC3>][,<expB2>])
  538.    Child relation file maintenance.
  539.  
  540. *REQ(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>])
  541.    VALID function to force a GET field to not be empty.
  542.  
  543. *RGHT_JST([<expC>])
  544.    VALID function to right justify input to a GET field.
  545.  
  546. SAVE_IT(<expC>,<expA>,<expN>,<expL>)
  547.    All purpose file I/O routine.
  548.  
  549. SETMOUSE([<expN1>][,<expN2>])
  550.    Get/Set mouse button status.  Set up mouse for 'closed'
  551.      functions.
  552.  
  553. SETMSGLIN([<expC>])
  554.    Function to Get/Set the application message line.
  555.  
  556. *SHADOW(<expN1>,<expN2>,<expN3>,<expN4>)
  557.    Puts a shadow on a box.
  558.  
  559. SHOW_MEMO(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ;
  560.      <expL>[,<expC2>][,<expN5>])
  561.    Display/Edit a Memo field without a border or message
  562.      line or title.
  563.  
  564. SHOW_TXT(<exp>,<expN1>,<expN2>,<expN3>[,<expC>])
  565.    VALID function to display data after input from a GET.
  566.  
  567. TEXTVIEW(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>[,<expC2>])
  568.  
  569.                                         Page: 14
  570.  
  571.    Display a text file.
  572.  
  573. THERMOMETR(<expN1>,<expN2>,<expN3>,<expN4>)
  574.    Creates a thermometer to show the progress of a routine.
  575.  
  576. TIMEOUT(<expN1>,<expN2>)
  577.    Set up an application timeout if idle for a passed
  578.      length of time.
  579.  
  580. *TOTALKEYON()/TOTALKEYOFF()
  581.    Enables/Disables drop down menu right and left
  582.      scrolling.
  583.  
  584. VAR(<expN>[,<exp>])
  585.    Get and optionally set Aeolus Builder system variables.
  586.  
  587. *VARINIT()
  588.    Initialize Aeolus Builder system variables.
  589.  
  590. WAITKEY([<expN>])
  591.    Works like INKEY(0) but allows SET KEY TO ...'s to be
  592.      processed.
  593.  
  594. WINBOTT()
  595.    Returns the top row value for the current window.
  596.  
  597. WINLEFT()
  598.    Returns the left column value for the current window.
  599.  
  600. *WINPOP()
  601.    Remove a window from the screen that was created using
  602.      WINPUSH.
  603.  
  604. *WINPUSH(<expN1>,<expN2>,<expN3>,<expN4>[,<expL1>] ;
  605.      [,<expL2>][,<expL3>][<expL4>])
  606.    Put a window on the screen, may be saved for later
  607.      removal.
  608.  
  609.   WINRIGHT()
  610.    Returns the right column value of the current window.
  611.  
  612.   WINSTYLE(0
  613.    Returns the window style string for the current window.
  614.  
  615.   WINTOP()
  616.    Returns the top row value for the current window.
  617.  
  618.   * Functions preceded by an asterisk (*) are either dealt
  619.  
  620.                                            Page: 15
  621.  
  622.   with entirely by BUILDER generated code or are called by
  623.   another library function.  You will probably never need to
  624.   use these and are included  for the sake of completeness.
  625.  
  626.   ++ Functions preceded by this symbol are obsolete when
  627.   except for Summer '87 style code.
  628.                                                 Page: 16
  629.   @..ABPROMPT ... / @..WINPROMPT ...
  630.  
  631. Syntax:
  632.      @ <row1>,<col1> ABPROMPT <expC1> TO <expA> ;
  633.         [EXECUTE <exp>] ;
  634.         [WHEN <expL>] ;
  635.         [MESSAGE <expC2> AT <row2>,<co2l>]
  636.  
  637. Description:
  638.      The ABPROMPT and WINPROMPT work identically except for
  639.           the screen row and column coordinates.  ABPROMPT
  640.           takes actual screen coordinates and WINPROMPT uses
  641.           window offsets.  A window offset is a screen
  642.           coordinate that positions the menu prompt as if the
  643.           upper left corner of the window were screen
  644.           coordinate 0,0.  Therefore positioning a menu pad,
  645.           using WINPROMPT, at coordinate 01,01 would place in
  646.           on the top left of the current window.
  647.  
  648.      In both places where they appear the <row> and <col>
  649.           symbols mean screen row and column.  Use this
  650.           command instead of the Builder AddPrompt() function.
  651.           The command is preprocessed to call AddPrompt().
  652.  
  653.      <expC1> will be displayed/used as a menu pad at <row1>,
  654.           <col1>.  The menu array will be stored in <expA>.
  655.  
  656.      <exp> will be executed whenever the menu pad <expC1> is
  657.           selected.  The menu pad will only be selectable when
  658.           <expL> returns .T..
  659.  
  660.      When the menu pad is highlighted <expC2> will be
  661.           displayed at <row2>, <col2>.
  662.  
  663.      See AddPrompt(), Menu()
  664.                                                   Page: 17
  665.   @..GET / @..WINGET
  666.  
  667. Syntax:
  668.      @ <row>, <col> GET <var> [normal getclauses] ;
  669.         [VALIDBLOCK <expB>]
  670.  
  671.      -OR-
  672.  
  673.      @ <row>,<col> GET <var> USING MENU <expA>
  674.  
  675.      -OR-
  676.  
  677.      @ <row>,<col> GET <var> USING DROPDOWN <expA>
  678.  
  679. Description:
  680.      The @..GET and @..WINGET work identically except for
  681.           the screen row and column coordinates.  @..GET takes
  682.           actual screen coordinates and @..WINGET uses window
  683.           offsets.  A window offset is a screen coordinate
  684.           that positions the GET as if the upper left corner
  685.           of the window were screen coordinate 0,0.  Therefore
  686.           positioning a GET, using WINGET, at coordinate 01,01
  687.           would place in on the top left of the current
  688.           window.
  689.  
  690.      The differences between a Clipper GET and a Builder
  691.           GET/WINGET are very small.  Besides using @..WINGET
  692.           window offsets there are only two differences.  You
  693.           may use the VALIDBLOCK clause instead of the VALID
  694.           to pass a codeblock as a valid condition for a
  695.           GET/WINGET.  And you may use the USING MENU or USING
  696.           DROPDOWN clauses.  Note, however, if either USING
  697.           MENU or USING DROPDOWN is used it is the only GET
  698.           clause allowed.  In other words, if you use one of
  699.           them, you may not use VALID, COLOR or any other GET
  700.           clause.
  701.  
  702.      The USING MENU clause is unique to Builder.  Simply
  703.           pass a one dimensional array of character strings as
  704.           the argument to this clause to create a 'Menu GET'.
  705.           The USING MENU mechanism will read the data type of
  706.           the GET variable (must be Character or Numeric) and
  707.           set the GET variable accordingly.
  708.  
  709.      The USING DROPDOWN clause works similarly to USING MENU
  710.           in that you pass a one dimensional array of
  711.           character strings to use as prompt values.  The
  712.           difference is that the USING DROPDOWN will create a
  713.           drop down listbox and the <var> MUST be a numeric
  714.           value.  The up/down arrow keys will not move the
  715.  
  716.                                         Page: 18
  717.  
  718.   focus from this type of GET but instead will move among the
  719.   array elements, display each as up and down arrows are
  720.   entered.  Also the alt+down arrow key combination will
  721.   display the available options in a list format.
  722.                                                   Page: 19
  723.   @..WINSAY ...
  724.  
  725. Syntax:
  726.      @ <row>, <col> SAY [sayclauses]
  727.  
  728. Description:
  729.      The @..WINSAY works exactly like the Clipper @..SAY
  730.           command except for the screen row and column
  731.           coordinates.  @..SAY takes actual screen coordinates
  732.           and @..WINSAY uses window offsets.  A window offset
  733.           is a screen coordinate that positions the SAY as if
  734.           the upper left corner of the window were screen
  735.           coordinate 0,0.  Therefore positioning a SAY, using
  736.           WINSAY, at coordinate 01,01 would place in on the
  737.           top left of the current window.
  738.                                                   Page: 20
  739.   @....WINDOW ...
  740.  
  741. Syntax:
  742.      @ <top>,<left>,<bottom>,<right> WINDOW ;
  743.         [NOSAVE] [NOCLEAR] [NOSHADOW]
  744.         [NOBORDER] [STYLE <expC1>]
  745.         [COLOR <expC>]
  746.  
  747. Description:
  748.      The Builder @....WINDOW command places a new window on
  749.           the screen at the <top>,<left>,<bottom>,<right>
  750.           screen coordinates.  The screen area used is saved
  751.           so that the next WINDOW REMOVE command will restore
  752.           the screen unless the NOSAVE clause is used.  The
  753.           interior of the window is cleared (spaces displayed)
  754.           unless the NOCLEAR clause is used.  A shadow will be
  755.           placed on the bottom and right edges of the window
  756.           unless the NOSHADOW clause is used.  A border is
  757.           placed on the window unless the NOBORDER clause is
  758.           used. The window border style will be the current
  759.           default [Var( WNDW_STYLE ) ] unless the STYLE clause
  760.           is used.  The color of the window will be the
  761.           current default unless the COLOR clause is used.
  762.           Pass a Clipper color string as an argument to this
  763.           clause.
  764.  
  765.      STYLE clause values should be passed as the manifest
  766.           constants located at the beginning of the Builder.ch
  767.           include file.  These are:
  768.  
  769.      W_DOUBLE -          Double border
  770.      W_SINGLE -          Single border
  771.      W_DOUBLE_SINGLE -   Double horizontal, single vertical
  772.      W_SINGLE_DOUBLE -   Single horizontal, double vertical
  773.      W_3D_PLUS -         3d pulling out of screen
  774.      W_3D_MINUS -        3d pushing into screen
  775.  
  776.      Or any two characters, the first character will be used
  777.           as the horizontal window edge, and the second the
  778.           vertical.
  779.  
  780.      See WinPush()
  781.                                                   Page: 21
  782.   ABGOBOTTOM()
  783.  
  784. Syntax:
  785.      AbGoBottom(<expO>)
  786.  
  787. Pass:
  788.      <exp> -   a TBrowse object.
  789.  
  790. Returns:
  791.      NIL always.
  792.  
  793. Description:
  794.      This functions should be used as the :goBottomBlock
  795.           code block on a Builder TBrowse.  It will use the
  796.           "BOUNDS" and "BNDKEYS" dictionary elements, if
  797.           needed, when executing a :goBottom() method.
  798.                                                   Page: 22
  799.   ABGOTOP()
  800.  
  801. Syntax:
  802.      AbGoTop( <expO>)
  803.  
  804. Pass:
  805.      <expO> -  a TBrowse object.
  806.  
  807. Returns:
  808.      NIL always.
  809.  
  810. Description:
  811.      This functions should be used as the :goTopBlock code
  812.           block on a Builder TBrowse.  It will use the
  813.           "BOUNDS" and "BNDKEYS" dictionary elements, if
  814.           needed, when executing a :goTop() method.
  815.                                                   Page: 23
  816.   ABTBSKIP()
  817.  
  818. Syntax:
  819.      AbTbSkip(<expN>,<expO>)
  820.  
  821. Pass:
  822.      <expN> -  Number of records to skip, pass as a negative
  823.           number to skip backwards.
  824.      <expO> -  TBrowse object whose :cargo dictionary should
  825.           be used.
  826.  
  827. Returns:
  828.      A numeric value of the number of records actually
  829.           moved.  The return value will be negative if
  830.           backward movement occurred.
  831.  
  832. Description:
  833.      This function should be used as the :skipBlock code
  834.           block for Builder TBrowses.  It will use the
  835.           "BOUNDS" and "BNDKEYS" dictionary elements, if
  836.           needed, for all database movement.
  837.                                                   Page: 24
  838.   ADD_REC()
  839.  
  840.   Syntax:
  841.      add_rec(<expN>)
  842.  
  843. Pass:
  844.      <expN> seconds until timeout, zero for no timeout.
  845.  
  846. Returns:
  847.      a logical expression.
  848.  
  849. Description:
  850.      Attempts to add a blank record to the currently
  851.           selected database for timeout period of <expN>
  852.           seconds.  If a record cannot be added after the
  853.           timeout period an error box is presented to try
  854.           again, if No is selected, a logical false is
  855.           returned.  If <expN> is zero or not passed to the
  856.           function, ADD_REC() will wait indefinitely.
  857.  
  858. Comment:
  859.      This function is called by the SAVE_IT() function
  860.           therefore it should never need to be used by you in
  861.           a program, use the SAVE_IT() function to do file I/O
  862.           instead.  It is  included here only for complete
  863.           ness.
  864.                                                   Page: 25
  865.   ADDGET()
  866.  
  867. Syntax:
  868.  
  869.           ADDGET(<expN1>,<expN2>,<expB1>,<expC1>[,<expC2>][,<e
  870.           xpB2>] ;
  871.      [,<expB3>][,<expB4>])
  872.  
  873. Pass:
  874.         <expN1> -  Screen row for GET.
  875.         <expN2> -  Screen column for GET.
  876.         <expB1> -  Code block to return value of GET var and
  877.                 set GET var, you may use the MemVarBlock()
  878.                 function here.
  879.         <expC1> -  GET variable name.
  880.         <expC2> -  PICTURE string.
  881.         <expB2> -  Code block to perform VALID for GET.
  882.         <expB3> -  Code block to perform WHEN for GET.
  883.         <expB4> -  Code block of alternate GET reader.
  884.  
  885. Returns:
  886.      NIL always
  887.  
  888. Description:
  889.      The BUILDER ADDGET() function does exactly the same
  890.           thing as the Clipper @...GET statement with the
  891.           addition of allowing the alternate GET reader code
  892.           block.
  893.  
  894.      Note that BUILDER will create ADDGET()'s instead of
  895.           @...GETs when generating non-Summer '87 code.
  896.                                                   Page: 26
  897.   ADDMPAD()
  898.  
  899.   Syntax:
  900.      ADDMPAD(<expN1>,<expN2>,<expN3>,<expN4>,<expN5>,<expB>)
  901.  
  902. Pass:
  903.         <expN1> -  Upper left row screen coordinate.
  904.         <expN2> -  Upper left column screen coordinate.
  905.         <expN3> -  Bottom right row screen coordinate.
  906.         <expN4> -  Bottom right column screen coordinate.
  907.         <expN5> -  1 or 0, for left mouse button press or
  908.                 release.
  909.         <expB>  -  Code block to execute.
  910.  
  911. Returns:
  912.      A numeric expression indicating the Mouse Pad Index
  913.           number.
  914.  
  915. Description:
  916.      The ADDMPAD() function add a mouse 'hot spot' to the
  917.           screen.  If the left mouse button is activated
  918.           within the passed screen coordinates, <expB> is
  919.           evaluated.
  920.  
  921.      If <expN5> is passed as 0 (zero), <expB> is evaluated
  922.           when the left mouse button is released.  If <expN5>
  923.           is passed as 1 (one), <expB> is evaluated repeatedly
  924.           while the left mouse button is pressed.
  925.  
  926.      Be sure to save the return value, without it you cannot
  927.           deactivate the mouse 'hot spot'!
  928.  
  929.      See:  DELMPAD(),MOUSEINIT(),SETMOUSE()
  930.                                                   Page: 27
  931.   *ADDPROMPT()
  932.  
  933.   Syntax:
  934.  
  935.           ADDPROMPT(<expA>,<expN1>,<expN2>,<expC1>[,<expB>][,<
  936.           expN3>] ;
  937.      [,<expN4>][,<expC2>])
  938.  
  939. Pass:
  940.         <expA>  -  Array to append.
  941.         <expN1> -  Screen row to display prompt.
  942.         <expN2> -  Screen column to display prompt.
  943.         <expC1> -  Prompt text.
  944.         <expB>  -  Code block to execute when this menu prompt
  945.                 is  selected.
  946.         <expN3> -  Screen row to display prompt message.
  947.         <expN4> -  Screen column to display prompt message.
  948.         <expC2> -  Message text to display when prompt is
  949.                 highlighted.
  950.  
  951. Returns:
  952.      NIL always.
  953.  
  954. Description:
  955.      The ADDPROMPT() function is similar to the Clipper
  956.           @...PROMPT command.  See any BUILDER generated
  957.           source for ADDPROMPT() examples.
  958.  
  959.      See:  MENU(),CRTMNUARRY()
  960.                                                   Page: 28
  961.   APOP()
  962.  
  963. Syntax:
  964.      apop(<expN1>,<expN2>,<expN3>,<expN4>,<expA>,<expN5> ;
  965.      [,<expC1][,<expC2>])
  966.  
  967. Pass:
  968.         <expN1>    top left row.
  969.         <expN2>    top left column.
  970.         <expN3>    bottom right row.
  971.         <expN4>    bottom right column.
  972.         <expA>     array name (prefixed with @).
  973.         <expN5>    max element to show.
  974.         <expC1>    alternate color choice.
  975.         <expC2>    alternate reverse color choice.
  976.  
  977. Returns:
  978.      Nothing.
  979.  
  980. Description:
  981.      The APOP() function will put a box on the screen using
  982.           <expN1> through <expN4> as screen coordinates and
  983.           allow you to scroll through elements 1 to <expN5> of
  984.           the array <expA>.  When a selection is made by
  985.           pressing the 'T' or ENTER key.  That element will be
  986.           tagged and displayed with a check mark in front (û).
  987.           <expC1> is an optional color value, <expC2> is an
  988.           alternate reverse color option.  Defaults for
  989.           <expC1> and <expC2> are the current colors.
  990.  
  991.      Upon return from APOP() check the first character of
  992.           each array element for Chr(251) for tagged elements.
  993.  
  994. Sample:
  995.         ** APOP() example code to allow the selection of
  996.                 multiple
  997.         ** names from a list and then display the selected
  998.                 items.
  999.         **
  1000.         Names := {"Rosa
  1001.                 lind","Mark","John","Lisa","Amy","Jeff","Cathy
  1002.                 ", ;
  1003.               "Jordan"}
  1004.  
  1005.         ** call APOP()
  1006.         Apop(05,05,13,18,@Names,10)
  1007.  
  1008.         ** the check character -Chr(251)- is left on the
  1009.                 array elements that have
  1010.         ** been selected, so if it is in the first character
  1011.  
  1012.   Page: 29
  1013.  
  1014.  
  1015.    position, that element was
  1016.  
  1017.         ** selected by the user.
  1018.  
  1019.         For j := 1 to Len(Names)
  1020.           If Left(Names[j],1) == Chr(251)
  1021.             ? Substr(Names[j],2)+" Was Selected."
  1022.           Endif
  1023.         Next
  1024.                                                   Page: 30
  1025.   ASC2BIN()
  1026.  
  1027. Syntax:
  1028.      ASC2BIN(<expC>)
  1029.  
  1030. Pass:
  1031.         <expC>     string with control character expressions
  1032.                 embedded.
  1033.  
  1034. Returns:
  1035.      Character expression.  The converted string.
  1036.  
  1037.      Description:
  1038.      The ASC2BIN() function converts a character expression
  1039.           that contains one or more caret (^) symbols followed
  1040.           by a character to it's 'control' or binary value.
  1041.           Use this function for creating printer control
  1042.           strings.  For example :
  1043.               c := ASC2BIN("^A")  // caps important !]
  1044.               ? asc(c)            // would display the number 1
  1045.  
  1046. Sample:
  1047.         ***********************************************
  1048.         ** print a message on a laser printer in
  1049.         ** landscape using HP escape sequence
  1050.  
  1051.         prtrt := "^[&l0O"    // caret, left bracket (escape),
  1052.                              // ampersand, lower case L, zero,
  1053.                              // upper case O
  1054.         lndscp := "^[&l1O"   // caret, left bracket (escape),
  1055.                              // ampersand, lower case L, one,
  1056.                              // upper case O
  1057.         set print on
  1058.         ?? asc2bin(lndscp)   // set printer to landscape
  1059.         ? "This text printed using landscape."
  1060.         ?? asc2bin(prtrt)    // set printer back to portrait
  1061.         set print off
  1062.                                                   Page: 31
  1063.   ASK()
  1064.  
  1065. Syntax:
  1066.           ASK(<expC1>,<expC2>,<expN1>,<expN2>[,<expN3>][,expC3
  1067.           ][,<expC4>])
  1068.  
  1069. Pass:
  1070.         <expC1>    prompt text.
  1071.         <expC2>    list of acceptable input characters.
  1072.         <expN1>    row for prompt.
  1073.         <expN2>    column for prompt.
  1074.         <expN3>    pad prompt to length.
  1075.         <expC3>    alternate color.
  1076.         <expC4>    "ESC" to allow ESC key.
  1077.  
  1078. Returns:
  1079.      Character expression.  The keyboard character pressed.
  1080.  
  1081. Description:
  1082.      <expC1> will be displayed at row <expN1> and column
  1083.           <expN2>.  ASK() will wait until any keyboard
  1084.           character contained in the list <expC2> is pressed.
  1085.  
  1086.      <expC2> may be passed in upper or lower case, ASK()
  1087.           does not distinguish.  If you pass "YN" either a
  1088.           lower or upper case 'Y' key press will return an
  1089.           upper case "Y" from ASK().  Also if you pass "yn"
  1090.           either a lower or upper case 'Y'key press will
  1091.           return an upper case "Y".
  1092.  
  1093.      <expN3> spaces will be displayed before the message in
  1094.           <expC1> to clear previous text, optional.  default
  1095.           is the length of <expC1>.
  1096.  
  1097.      <expC3> is color to display <expC1>.  Default is
  1098.           current color.
  1099.  
  1100.      If <expC4> is equal to "ESC" then ASK() can be exited
  1101.           using the ESC key.  If the ESC key is used to exit
  1102.           ASK() a null string will be the return value.  The
  1103.           default is to not allow ESCaping.
  1104.  
  1105. Sample:
  1106.  
  1107.                 **********************************************
  1108.                 *******
  1109.         **  display the question on line 24 column 0 and pad
  1110.         **  the text to 80 characters.  Wait until a Y or N
  1111.         **  is pressed on the keyboard.
  1112.  
  1113.  
  1114.   Page: 32
  1115.  
  1116.         cAnswer := Ask("Do You Wish to Continue?
  1117.   (Y/N)","YN",24,0,80)
  1118.  
  1119.         IF cAnswer == "Y"
  1120.               ? "You do wish to continue"
  1121.         ELSE
  1122.               ? "You do not wish to continue"
  1123.         ENDIF
  1124.         ** the character variable "answer" will equal either
  1125.                 "Y"
  1126.         ** or "N" depending on what the key is pressed.
  1127.                                                   Page: 33
  1128.   ASKMENU()
  1129.  
  1130. Syntax:
  1131.  
  1132.           ASKMENU(<expC1>,<expA>,<expN1>,<expN2>[,<expN3>][,ex
  1133.           pC3] ;
  1134.      [,<expC4>])
  1135.  
  1136. Pass:
  1137.         <expC1>    prompt text.
  1138.         <expA>     array of menu prompts.
  1139.         <expN1>    row for prompt.
  1140.         <expN2>    column for prompt.
  1141.         <expN3>    pad prompt to length
  1142.         <expC3>    alternate color.
  1143.         <expC4>    "ESC" to allow ESC key.
  1144.  
  1145. Returns:
  1146.      Character expression.  The unique (highlighted)
  1147.           character of the menu prompt selected.  The returned
  1148.           character will always be in upper case.  A space
  1149.           character is return if ESC is pressed.
  1150.  
  1151. Description:
  1152.      <expC1> will be displayed at row <expN1> and column
  1153.           <expN2> immediately followed by each of the menu
  1154.           prompts contained in <expA>. ASKMENU() will wait
  1155.           until a prompt is selected by a press of the ENTER
  1156.           key or a click of the left mouse button.
  1157.  
  1158.      <expN3> spaces will be displayed before the message in
  1159.           <expC1> to clear previous text, optional.  default
  1160.           is the length of <expC1>.
  1161.  
  1162.      <expC3> is the color to display <expC1> and the menu.
  1163.           The default is the current color.
  1164.  
  1165.      If <expC4> is equal to "ESC" (case important) then
  1166.           ASKMENU() can be exited using the ESC key.  If the
  1167.           ESC key is used to exit ASKMENU() a space character
  1168.           will be the return value.  The default is to not
  1169.           allow ESCaping.
  1170.  
  1171. Sample:
  1172.  
  1173.                 **********************************************
  1174.                 *******
  1175.         **  display the question on line 24 column 0.  Wait
  1176.         **  until an answer is selected.
  1177.         LOCAL cAnswer
  1178.  
  1179.   Page: 34
  1180.  
  1181.         cAnswer := AskMenu("Do You Wish to Continue?", ;
  1182.                    {"Yes,"No"},24,0)
  1183.  
  1184.         ** the character variable "Answer" will equal either
  1185.                 "Y"
  1186.         ** or "N" depending on what option is selected.
  1187.                                                   Page: 35
  1188.   BCHOICE()
  1189.  
  1190. Syntax:
  1191.  
  1192.                 BChoice(<expN1>,<expN2>,<expN3>,<expN4>,<expA>
  1193.                 [,<expC>][,<expN5>][,<expL>])
  1194.  
  1195. Pass:
  1196.         <expN1> -  Top screen row.
  1197.         <expN2> -  Left screen column.
  1198.         <expN3> -  Bottom screen row.
  1199.         <expN4> -  Right screen column.
  1200.         <expA> -   Array of choices.
  1201.         <expC> -   Title to display.  Default none.
  1202.         <expN5> -  Initial element to highlight.  Default 1.
  1203.         <expL> -   Remove window on function exit..  Default
  1204.                 true.
  1205.  
  1206. Returns:
  1207.         A numeric value of the element selected.  Returns
  1208.                 zero if ESC was pressed.
  1209.  
  1210. Description:
  1211.         The Builder BChoice() function works very similar to
  1212.                 the Clipper AChoice() function.  The differ
  1213.                 ence is that BChoice() will accept mouse input
  1214.                 and AChoice() will not.
  1215.                                                   Page: 36
  1216.   BETWEEN()
  1217.  
  1218. Syntax:
  1219.      between(<exp1>,<exp2>,<exp3>)
  1220.  
  1221. Pass:
  1222.         <exp1>     value to test.
  1223.         <exp2>     minimum value.
  1224.         <exp3>     maximum value.
  1225.  
  1226. Returns:
  1227.      A logical expression.
  1228.  
  1229. Description:
  1230.      A logical true will be returned if <exp1> is greater
  1231.           than and equal to <exp2> and less than and equal to
  1232.           <exp3>.  The arguments passed to the BETWEEN()
  1233.           function may be of type Character, Numeric or Date;
  1234.           however all three arguments must be the same data
  1235.           type.
  1236.                                                   Page: 37
  1237.   BLDRERR()
  1238.  
  1239. Syntax:
  1240.      BldrErr( <expO>, <expC> )
  1241.  
  1242. Pass:
  1243.      <expO> -  Clipper error object.
  1244.      <expC> -  Determines where error output goes.
  1245.  
  1246. Returns:
  1247.      A logical false always.
  1248.  
  1249. Description:
  1250.      The BldrErr() function can be posted using the Clipper
  1251.           ErrorBlock() function.  The Builder error system can
  1252.           post error information to a database file
  1253.           (BLDRERR.DBF) or the screen.  In both instances the
  1254.           message box where the original error message appears
  1255.           can be cleared by mouse input, using the Clipper
  1256.           error system will not allow mouse inputs.  Pass
  1257.           <expC> as the literal value "FILE" to send output to
  1258.           the BLDRERR.DBF database or as "SCREEN" to send
  1259.           error output to the screen.  In either case more
  1260.           information is provided than the Clipper error
  1261.           system and it is displayed in a more presentable
  1262.           manner.
  1263.                                                   Page: 38
  1264.   BROWSEDB()
  1265.  
  1266. Syntax:
  1267.      BrowseDb(<expO>/<expA>[, <expL>] )
  1268.  
  1269. Pass:
  1270.      <expO>/<expA> -     a TBrowse object or an array of
  1271.           TBrowse objects to execute.
  1272.      <expL> -  TRUE (default) to hilight the browse window
  1273.           with input focus.
  1274.  
  1275. Returns:
  1276.      a logical value.  True is returned if Ctrl+Enter is
  1277.           used to exit the TBrowse.  False is returned if ESC
  1278.           is pressed to exit the TBrowse.
  1279.  
  1280. Description:
  1281.      Calls to the BrowseDb() function are normally created
  1282.           by Builder.  These calls can be modified by passing
  1283.           an array of TBrowse objects.  Passing more than one
  1284.           browse object will cause all the TBrowse objects to
  1285.           be stabilized and active at once.  The Alt+PgDn and
  1286.           Alt+PgUp keys will be activated to move from one
  1287.           browse to the next.  Inactive browses can also be
  1288.           selected with a mouse click.  Use caution when doing
  1289.           this so that the browse windows tile onto the
  1290.           screen, if they overlap they will mess up the
  1291.           screen.  In using the multi-browse you will probably
  1292.           want to issue a SET RELATION ... Clipper command
  1293.           before the BrowseDb() call.
  1294.                                                   Page: 39
  1295.   BROWSER()
  1296.  
  1297. Syntax:
  1298.      browser(<expN1>,<expN2>,<expN3>,<expN4>[,<expC>] ;
  1299.      [,<expN5>][,<expN6>]
  1300.  
  1301. Pass:
  1302.         <expN1>    top left row.
  1303.         <expN2>    top left column.
  1304.         <expN3>    bottom right row.
  1305.         <expN4>    bottom right column.
  1306.         <expC>     key exception function name.
  1307.         <expN5>    start field number.
  1308.         <expN6>    end field number.
  1309.  
  1310. Description:
  1311.      The BROWSER function will "browse" the currently
  1312.           selected database using the Clipper DBEDIT()
  1313.           function.  <expN1> through <expN4> define the
  1314.           coordinates of the box that will be displayed,
  1315.           <expC> is the user defined function executed on each
  1316.           key press.  <expN5> and <expN6> are the start and
  1317.           end field numbers (i.e. the FCOUNT() number) to
  1318.           browse.  If <expN5> is not passed the first field
  1319.           will be browsed.  If <expN6> is not passed the
  1320.           <expN5>th through FCOUNT() fields will be browsed.
  1321.  
  1322.      For more information on using the <expC> user defined
  1323.           function consult your Clipper manual on the DBEDIT()
  1324.           function.  <expC> is merely passed to DBEDIT() as
  1325.           the UDF for each key press.
  1326.  
  1327. Sample:
  1328.  
  1329.                 **********************************************
  1330.                 ********
  1331.         ** BROWSER sample call
  1332.         **
  1333.         USE Customer NEW
  1334.         Browser(5,3,17,73)
  1335.  
  1336.         ** this will put a box on the screen from row 5
  1337.                 column 3 to row
  1338.         ** 17 column 73 and browse all the fields in the
  1339.                 database
  1340.         ** CUSTOMER.
  1341.  
  1342.      Note that this function is obsolete and you should
  1343.           create TBrowse windows in Builder instead
  1344.                                                   Page: 40
  1345.   BRWMOUSE()
  1346.  
  1347. Syntax:
  1348.      BrwMouse( <expN1>, <expN2>, <expN3>, <expN4>, <expO> )
  1349.  
  1350. Pass:
  1351.      Either:
  1352.      <expN1> - Top screen row.
  1353.      <expN2> - Left screen column.
  1354.      <expN3> - Bottom screen row.
  1355.      <expN4> - Right screen column.
  1356.      <expO> -  a TBrowse object.
  1357.      Or nothing
  1358.  
  1359. Returns:
  1360.      NIL always.
  1361.  
  1362. Description:
  1363.      The BrwMouse() function adds and removes the mouse pads
  1364.           to a Builder TBrowse.  Builder normally creates the
  1365.           call to this function.  The first four parameters
  1366.           are the window window border coordinates, and the
  1367.           last parameter is the TBrowse object.  If no
  1368.           parameters are passed, the last set of mouse pads
  1369.           are removed.
  1370.                                                   Page: 41
  1371.   CENTER()
  1372.  
  1373. Syntax:
  1374.      center(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2])
  1375.  
  1376. Pass:
  1377.         <expC1>    message to display.
  1378.         <expN1>    row to begin centering computation.
  1379.         <expN2>    column to begin centering computation.
  1380.         <expN3>    length for centering computation.
  1381.         <expC2>    alternate color.
  1382.  
  1383. Returns:
  1384.      Start column of centered text.
  1385.  
  1386. Description:
  1387.      The CENTER() function displays <expC1> on row <expN1>
  1388.           column <expN2> centered within a width <expN3> wide.
  1389.           <expC2> is an alternate color choice.  The default
  1390.           color is the current from the last SET COLOR TO . .
  1391.           . statement.
  1392.  
  1393. Sample:
  1394.         ****************************************************
  1395.         ** CENTER() function example
  1396.         **
  1397.         ** put a box on the screen
  1398.         @ 5, 5, 15, 45 WINDOW STYLE "3+"
  1399.  
  1400.         ** center text in the box
  1401.         Center("Yoo Hoo, I'm Centered",
  1402.                 WinTop()+2,WinLeft()+1,29)
  1403.  
  1404.         Waitkey()
  1405.         ** remove box
  1406.         WINDOW REMOVE
  1407.                                                   Page: 42
  1408.   CHGDIR()
  1409.  
  1410. Syntax:
  1411.      chgdir(<expC>)
  1412.  
  1413. Pass:
  1414.         <expC> -   a DOS subdirectory name on the current
  1415.                 drive.
  1416.  
  1417. Returns:
  1418.      A numeric value indicating a DOS error code.
  1419.  
  1420. Description:
  1421.      The CHGDIR assembly subroutine simply attempts to
  1422.           change to the subdirectory named in the passed
  1423.           parameter <expC>.
  1424.  
  1425.      One of the following will be returned:
  1426.  
  1427.      0 - No error occured
  1428.      1 - Invalid function number
  1429.      2 - File not found
  1430.      3 - Path not found
  1431.      4 - Too many open files (no handles left)
  1432.      5 - Access denied
  1433.      6 - Invalid handle
  1434.      7 - Memory control blocks destroyed
  1435.      8 - Insufficient memory
  1436.      9 - Invalid memory block address
  1437.      10 - Invalid environment
  1438.      11 - Invalid format
  1439.      12 - Invalid access mode (open mode is invalid)
  1440.      13 - Invalid data
  1441.      14 - Reserved
  1442.      15 - Invalid drive specified
  1443.      16 - Attempt to remove current directory
  1444.      17 - Not same device
  1445.      18 - No more files
  1446.                                                   Page: 43
  1447.   CHGDSK()
  1448.  
  1449. Syntax:
  1450.      chgdsk(<expC>)
  1451.  
  1452. Pass:
  1453.         <expC> -   A single byte indicating the disk drive
  1454.                 letter to set as the new default drive.
  1455.  
  1456. Returns:
  1457.      A numeric value indicating a DOS error code.
  1458.  
  1459. Description:
  1460.      The CHGDSK assembly subroutine simply attempts to
  1461.           change the default DOS disk drive to the passed
  1462.           drive letter parameter <expC>.  If a number greater
  1463.           than zero is returned, then a DOS error has occured.
  1464.           See the CHGDIR() function in this manual for  a list
  1465.           of possible DOS error codes.
  1466.                                                   Page: 44
  1467.   CHKCHR()
  1468.  
  1469. Syntax:
  1470.  
  1471.        chkchr(<expC1>,<expC2>,<expN1>,<expN2>,<expN3>,[<exp
  1472.        C3>])
  1473.  
  1474. Pass:
  1475.   <expC1> -     A list of allowable entry data into the
  1476.           GET.
  1477.   <expC2> -     Error message on entry of non-allowable
  1478.           data.
  1479.   <expN1> -     Row for error message to display.
  1480.   <expN2> -     Column for error message display.
  1481.   <expN3> -     Rightmost column for error message display.
  1482.   <expC3> -     Optional color for error message.  default
  1483.           WERR_CLR.
  1484.  
  1485. Returns:
  1486.   A logical expression.
  1487.  
  1488. Description:
  1489.   This function is designed to be use as a VALID function
  1490.        to a GET only.  It will test if the data keyed into
  1491.        the GET is embedded in the <expC1> string.  If it
  1492.        is, the GET is allowed otherwise an error beep is
  1493.        sounded and the error message <expC2> is displayed
  1494.        at screen row <expN1> column <expN2> and will be
  1495.        padded or truncated to screen column <expN3>.  If
  1496.        <expC3> is passed as a parameter the error message
  1497.        will be displayed using it as the color value,
  1498.        otherwise the color contained in the public memory
  1499.        variable WERR_CLR will be used.
  1500.  
  1501. Samples:
  1502.   ** cType is a one byte variable with allowable
  1503.           values of 1, 2, or 3
  1504.   ** only.  Use ChkChr() to force a 1, 2, or 3 into
  1505.           this field like this ...
  1506.   cType := " "
  1507.   @ 02,21 WINGET cType PICTURE "9" VALID ;
  1508.           ChkChr("123","1, 2, 3 Only Allowed",WinBott()-
  1509.           1,WinLeft()+2,WinRight()-2)
  1510.   SET CURSOR ON
  1511.   READ
  1512.   SET CURSOR OFF
  1513.  
  1514.   ** Same example, but allow cType to be blank.  Just
  1515.           add a
  1516.   ** space as an allowable character in the list!
  1517.  
  1518. Page: 45
  1519.  
  1520.   cType := " "
  1521.  
  1522.   @ 02,21 WINGET cType PICTURE "9" VALID ;
  1523.           ChkChr(" 123","1, 2, 3 or Blank
  1524.           Only",WinBott()-1,WinLeft()+2,WinRight()-2)
  1525.   SET CUROSR ON
  1526.   READ
  1527.   SET CURSOR OFF
  1528.   If QTYPE (or whatever field) is more than one character
  1529.        long, be sure to use a separator between allowable
  1530.        field values.
  1531.  
  1532.   ** cType2 allowable values are "EA" for Each,  "PK"
  1533.           for
  1534.   ** Package, or "WT" for Weight.
  1535.   ** You can use ChkChr() in the following manner to
  1536.   ** force the field cType2 to be one of these
  1537.           values...
  1538.   cType2 := "  "
  1539.   @ 02,21 WINGET cType2 PICTURE "!!" VALID ;
  1540.           ChkChr("EA~PK~WT","Enter EA-Each, PK-Package,
  1541.           or WT-Weight", ;
  1542.           WinBott()-1,WinLeft()+2,WinRight()-2)
  1543.  
  1544.   Note though that if the user entered "A~" or "~P"
  1545.        ChkChr() would allow it. You may choose to use a
  1546.        separator that cannot be entered from the keyboard,
  1547.        however, I cannot foresee a user accidentally
  1548.        stumbling onto the tilde condition.
  1549.                                           Page: 46
  1550. CKPRTR()
  1551.  
  1552. Syntax:
  1553.   ckprtr([<expN>])
  1554.  
  1555. Pass:
  1556.   nothing or 1, 1 if ESCaping is allowed.
  1557.  
  1558. Returns:
  1559.   a logical expression.
  1560.  
  1561. Description:
  1562.   The CKPRTR() function returns a logical true if the
  1563.        Clipper ISPRINTER() function returns a logical true.
  1564.        CKPRTR() displays an error box if ISPRINTER()
  1565.        returns false and checks the ISPRINTER() function
  1566.        again after a key is pressed.
  1567.  
  1568.   You can see that an infinite loop will be created if
  1569.        the printer cannot be brought on-line, if <expN> is
  1570.        a value of one (1) then the ESC key will allow an
  1571.        exit from CKPRTR() when the printer is not operating
  1572.        and if ESCaped CKPRTR() will return false (.f.).
  1573.  
  1574. Sample:
  1575.   *************************************************
  1576.   ** CKPRTR() function example
  1577.  
  1578.   PROCEDURE a_report()
  1579.  
  1580.   SET DEVICE TO PRINTER
  1581.   DO WHILE !EOF()
  1582.           IF !CkPrtr(1)     && check printer on each
  1583.           print line
  1584.                EXIT
  1585.           ENDIF
  1586.  
  1587.           .
  1588.           print report commands .
  1589.           .
  1590.  
  1591.   ENDDO
  1592.  
  1593.   >>COMMENT:
  1594.   The CKPRTR() function will only work with parallel
  1595.        printers.
  1596.                                           Page: 47
  1597. CRTMNUARRY()
  1598.  
  1599. Syntax:
  1600.   CRTMNUARRY(<expN1>,<expN2>,<expA>)
  1601.  
  1602. Pass:
  1603.   <expN1> -     Screen row to display menu.
  1604.   <expN2> -     Starting screen column to display menu.
  1605.   <expA>  -     Array of menu prompts.
  1606.  
  1607. Returns:
  1608.   An array that can be passed to the ABMENU() function.
  1609.  
  1610. Description:
  1611.   This can be used instead of several ADDPROMPT()'s.  It
  1612.        only creates menus on one screen row where the menu
  1613.        highlight moves left and right.  It is used
  1614.        primarily when creating menus within a GET stream.
  1615.  
  1616.   See the BUILDER manual section on entering the @MENU
  1617.        Picture clause.
  1618.  
  1619.   See:  ADDPROMPT(), ABMENU()
  1620.                                           Page: 48
  1621. DBCHANGED()
  1622.  
  1623. Syntax:
  1624.   dbchanged(<expA>)
  1625.  
  1626. Pass:
  1627.   <expA> -      Array of values to compare to database
  1628.           fields.
  1629.  
  1630. Returns:
  1631.   A logical value.
  1632.  
  1633. Description:
  1634.   The DBCHANGED() function returns true (.T.) if any of
  1635.        the database field values are different from the
  1636.        memory variables, otherwise false (.F.) is returned.
  1637.  
  1638.   See DBSTOR
  1639.                                           Page: 49
  1640. DBREPL()
  1641.  
  1642. Syntax:
  1643.   dbrepl(<expA>)
  1644.  
  1645. Pass:
  1646.   Array of values to be entered into database fields.
  1647.  
  1648. Description:
  1649.   DBREPL replaces all the field variables in a record
  1650.        using array elements from <expA> that have exactly
  1651.        the same ordinal position as the field variables.
  1652.  
  1653.   See DBSTOR and SAVE_IT().
  1654.  
  1655. Sample:
  1656.   ***************************************************
  1657.   ** DBREPL example
  1658.   **
  1659.   ** a database with the following structure is
  1660.           assumed
  1661.   **
  1662.   **  FNAME     Character   15
  1663.   **  LNAME     Character   20
  1664.   **  ADDRESS   Character   35
  1665.   **  PHONE     Character   10
  1666.   **
  1667.   Local aAddrBook := {}
  1668.  
  1669.   Use AddrBook New
  1670.   DbStor( aAddrBook, "EMPTY" )
  1671.  
  1672.   ** declares mfname,mlname,maddress,mphone as memory
  1673.           vars
  1674.   aAddrBook[1] := "DENISE"
  1675.   aAddrBook[2] := "JOHNSON"
  1676.   aAddrBook[3] := "123 MAPLE ST"
  1677.   aAddrBook[4] := "6125551234"
  1678.  
  1679.   Append Blank  // add a blank record
  1680.   DbRepl( aAddrBook )     // replace all field vars.
  1681.                                           Page: 50
  1682. DBSTATE()
  1683.  
  1684. Syntax:
  1685.   dbstate([<expC>])
  1686.  
  1687. Pass:
  1688.   Nothing or a string returned from a previous DBSTATE()
  1689.        function call.
  1690.  
  1691. Returns:
  1692.   A string of the complete state of the currently
  1693.        selected database.  Select area, record number,
  1694.        index order number, filter expression, and all
  1695.        relation information.
  1696.  
  1697. Description:
  1698.   DBSTATE() saves all the information possible for the
  1699.        currently selected work and returns it to the
  1700.        program in a single character string.  Passing a
  1701.        string saved from a previous DBSTATE() call as
  1702.        <expC> will set the work area of that DBSTATE()
  1703.        string to the state it was in.
  1704.  
  1705.   This function is very useful when you want to preserve
  1706.        the current database conditions exactly but you also
  1707.        need to use the same database for another purpose.
  1708.  
  1709.   WARNING:  DBSTATE() CANNOT be used on a database using
  1710.        the "DBFMDX" or "DBPX" RDDs!!
  1711.  
  1712. Sample:
  1713.   SELECT A_Database
  1714.   cDbState := DbState()   // save state of A_DATABASE
  1715.  
  1716.   ** change state of A_DATABASE
  1717.  
  1718.   A_Database->( DBSETORDER( 3 ) )
  1719.   SET FILTER TO The_Field == "A"
  1720.   SET RELATION TO
  1721.   A_Database->( DBGOTOP() )
  1722.  
  1723.   SELECT Another
  1724.  
  1725.   DbState( cDbState )     // selects A_DATABASE and puts it
  1726.           in the
  1727.           // state it was in on the first DBSTATE()
  1728.           // call.
  1729.                                           Page: 51
  1730. DBSTOR()
  1731.  
  1732. Syntax:
  1733.   dbstor(<expA>[,<expC>])
  1734.  
  1735. Pass:
  1736.   <expA>  Array with the same length as fCount() would
  1737.           return in the current work area.
  1738.   <expC>  nothing for data or "EMPTY" for empty values.
  1739.  
  1740. Description:
  1741.   DBSTOR stores all the field variables in a record to
  1742.        array elements with exactly the same ordinal
  1743.        position as the field variables in the current work
  1744.        area.
  1745.  
  1746.   If <expC> is passed as "EMPTY" then all memory
  1747.        variables will be assigned as if the record were
  1748.        blank.
  1749.  
  1750.   See DBREPL and SAVE_IT().
  1751.  
  1752. Sample:
  1753.   ***************************************************
  1754.   ** DBSTOR example
  1755.   **
  1756.   ** a database with the following structure is
  1757.           assumed
  1758.   **
  1759.   **  FNAME     Character   15
  1760.   **  LNAME     Character   20
  1761.   **  ADDRESS   Character   35
  1762.   **  PHONE     Character   10
  1763.   LOCAL aAddrBook := {}
  1764.  
  1765.   USE AddrBook NEW
  1766.  
  1767.   ** declares mfname,mlname,maddress,mphone as public,
  1768.           you must
  1769.   ** do this in order to use DBSTOR
  1770.   DbStor( aAddrBook, "EMPTY" )     // create 'blank'
  1771.           vars
  1772.  
  1773.   CLS
  1774.   @ 0,0 SAY "First Name" GET aAddrBook[1] PICTURE "@!
  1775.   @ 1,0 SAY "Last Name" GET aAddrBook[2] PICTURE "@!"
  1776.   @ 2,0 SAY  "Address" GET aAddrBook[3] PICTURE "@!
  1777.   @ 3,0 SAY "Phone" GET aAddrBook[4] PICTURE "@R (999)
  1778.           999-9999"
  1779.   READ
  1780.  
  1781. Page: 52
  1782.  
  1783.  
  1784.   Append Blank       // add a blank record
  1785.   DbRepl( aAddrBook )     // replace all field vars.
  1786.  
  1787. Comment:
  1788.   <expC> should be kept as short as possible otherwise
  1789.        the uniqueness to your field variables can be lost,
  1790.        I suggest a length of one, two as an absolute
  1791.        maximum.
  1792.                                           Page: 53
  1793. DEC2HEX()
  1794.  
  1795. Syntax:
  1796.   dec2hex(<expN>)
  1797.  
  1798. Pass:
  1799.   A numeric integer value.
  1800.  
  1801. Returns:
  1802.   A character string of the hexadecimal value of the
  1803.        passed integer.
  1804.  
  1805. Description:
  1806.   This function is the compliment to the HEX2DEC()
  1807.        function. If you have a need to convert numbers to
  1808.        hexadecimal, you will find this function useful.
  1809.                                           Page: 54
  1810. DELCOLPUT()
  1811.  
  1812. Syntax:
  1813.   DelColPut(<expO>,<expN>)
  1814.  
  1815. Pass:
  1816.   <expO> -  a TBrowse object.
  1817.   <expN> -  the TBrowse column number to remove.
  1818.  
  1819. Returns:
  1820.   NIL always.
  1821.  
  1822. Description:
  1823.   Use this function in a Builder TBrowse procedure after
  1824.        the TBrowse object has be completely created but
  1825.        before the BrowseDb() function is called.  Use it to
  1826.        remove columns from the TBrowse and place them in
  1827.        the 'recoverable' columns list.  That way you can
  1828.        have columns available to users of your TBrowse but
  1829.        not have them cluttering up the initial set of
  1830.        available columns.
  1831.                                           Page: 55
  1832. DICTGET()
  1833.  
  1834. Syntax:
  1835.   DictGet(<expA>,<expC>,<exp>)
  1836.  
  1837. Pass:
  1838.   <expA> -  a two dimensional dictionary array created by
  1839.        the DictPut() function.
  1840.   <expC> -  a dictionary identifier.
  1841.   <exp> -   the reutrn return value to use if <expC>
  1842.        is not found.
  1843.  
  1844. Returns:
  1845.   The value found in the dictionary that corresponds with
  1846.        <expC> or <exp> if <expC> cannot be found.
  1847.  
  1848. Description:
  1849.   The DictGet() function is used by BrowseDb() to get
  1850.        additional information about Builder TBrowses placed
  1851.        there by the DictPut() function.  A two dimensional
  1852.        dictionary array is placed on every Builder TBrowse
  1853.        and TBColumn object :cargo instance variable and
  1854.        contains the information needed for the added
  1855.        functionality of Builder TBrowses.
  1856.                                           Page: 56
  1857. DICTPUT()
  1858.  
  1859. Syntax:
  1860.   DictPut(<expA>,<expC>,<exp>)
  1861.  
  1862. Pass:
  1863.   <expA> -  An empty array or a two dimensional
  1864.        dictionary array already seeded by DictPut().
  1865.   <expC> -  an element key or index value.
  1866.   <exp> -   the value to associate with <expC>.
  1867.  
  1868. Returns:
  1869.   An updated dictionary array.
  1870.  
  1871. Description:
  1872.   Dictput adds <expC> and <exp> to <expA> if <expC> was
  1873.        not located in the input array otherwise <exp> is
  1874.        updated in the array.
  1875.  
  1876.   A dictionary array can be used for many purposes,
  1877.        Builder creates dictionary arrays and places them in
  1878.        the :cargo instance variable of TBrowse and TBColumn
  1879.        objects for adding to their functionality.
  1880.  
  1881.   The Builder BrowseDb() function reads the following
  1882.        dictionary elements from TBrowse and TBColumn
  1883.        objects:
  1884.  
  1885.   These are initialized by Builder and will probably not
  1886.        require any change on your part:
  1887.   FREEZE  DELETE AWIDTH
  1888.   CHGORD  IDXSRC APPEND
  1889.   APPVAL  RECNBR RECTGL
  1890.   DELREC  BNDFLD HGLTBAR
  1891.   BNDKEYS ALIAS       ORDER
  1892.   DELINDX
  1893.  
  1894.   These are added with a NIL value and are only set by
  1895.        making changes to the generated source code:
  1896.  
  1897.   BNDPFX  ORDEXCPT    KYHNDLR
  1898.  
  1899.   BNDPFX - Used if the TBrowse is a bounded list.  The
  1900.        BNDPFX value should be set to that portion of the
  1901.        index key that preceeds the bounded by field
  1902.        (BNDFLD).  This is only needed when the index search
  1903.        option is turned on.
  1904.  
  1905.   ORDEXCPT - Array - This is used to exclude items from
  1906.        the index change menu.  When the index change menu
  1907.  
  1908.                                      Page: 57
  1909.  
  1910. is selected from a Builder TBrowse, all indexes are
  1911.        displayed for selection except those in the one
  1912. dimensional array set as this dictionary element.
  1913.  
  1914.   KYHNDLR - Codeblock - If used the codeblock will be
  1915.        executed after a keyboard key has been pressed but
  1916.        before the keystroke has been applied to the browse.
  1917.        Two parameters are passed to the user defined key
  1918.        handler: the browse object, and the INKEY() value of
  1919.        the keypress.  The key handler must return a numeric
  1920.        value.  If zero (0) is returned, the Builder key
  1921.        handler will be called to process the key, return
  1922.        one (1) and the Builder key handler will be
  1923.        bypassed, return two (2) to exit the TBrowse.
  1924.                                           Page: 58
  1925. DELMPAD()
  1926.  
  1927. Syntax:
  1928.   DELMPAD(<expN>)
  1929.  
  1930. Pass:
  1931.   Mouse pad index (return value of ADDMPAD())
  1932.  
  1933. Returns:
  1934.   Logical true if successful, false if failed.
  1935.  
  1936. Description:
  1937.   Use DELMPAD() to deactivate a mouse 'hot spot'.
  1938.  
  1939.   See:  ADDMPAD()
  1940.                                           Page: 59
  1941. DRVTST()
  1942.  
  1943. Syntax:
  1944.   DRVTST(<expC>)
  1945.  
  1946. Pass:
  1947.   <expC> -      Floppy drive letter to test.
  1948.  
  1949. Returns:
  1950.   Numeric indicator of disk error.
  1951.  
  1952. Description:
  1953.   DrvTst() tests a floppy drive to see if it is available
  1954.        and ready.  Only floppy drives can be tested with
  1955.        this function.  The BIOS error code returned is as
  1956.        follows:
  1957.  
  1958.   0 -  No error
  1959.   1 -  Invalid drive or hard drive
  1960.   2 -  Bad sector
  1961.   3 -  Diskette write protected
  1962.   4 -  Sector not found
  1963.   8 -  DMA overrun
  1964.   9 -  DMA access across 64k boundary
  1965.   12 - Invalid media
  1966.   16 - ECC/CRC error on disk read
  1967.   32 - Controller error
  1968.   64 - Seek failure
  1969.   128 -   Time out, drive not ready
  1970.   255 -   Sense operation failed
  1971.  
  1972.   Note to OS/2 users, this function will not operate in
  1973.        an OS/2 VDM.  It will cause your system to crash,
  1974.        the DOS session AND OS/2!
  1975.                                           Page: 60
  1976. DUPCHK()
  1977.  
  1978. Syntax:
  1979.  
  1980.        dupchk(<expC1>,<exp>,<expN1>,<expC2>,<expN2>,<expN3>
  1981.        ,<expN4>, ;
  1982.   <expL>[,<expC3>])
  1983.  
  1984. Pass:
  1985.   <expC1> -     either "A" to check if the Addition of a
  1986.           record will cause a
  1987.           duplicate, or "C" to check if Changing the
  1988.           record will cause a
  1989.           duplicate.
  1990.   <exp>     -   Key value to duplicate check.
  1991.   <expN1> -     Index order number for duplicate check.
  1992.   <expC2> -     Error message to display.
  1993.   <expN2> -     Screen row to display error message.
  1994.   <expN3> -     Screen column to display error message.
  1995.   <expN4> -     Rightmost screen column to display error
  1996.           message.
  1997.   <expL>  -     GET is required (.T.) or may be blank
  1998.           (.F.).
  1999.   <expC3> -     Color to display error message, default is
  2000.           WERR_CLR.
  2001.  
  2002. Returns:
  2003.   A logical value, this function is to be used as a VALID
  2004.        for a GET only.
  2005.  
  2006. Description:
  2007.   The DUPCHK() valid function tests the value entered
  2008.        into a GET field to see if it will cause a duplicate
  2009.        record when saved.
  2010.  
  2011.   This function is useful when two indexes are maintained
  2012.        on a single database and both keys must not contain
  2013.        duplicates.
  2014.  
  2015.   If you are using GEN_MAINT or REL_MAINT pass G_FUNC as
  2016.        <expC1> as it will contain "A" on Adds and "C" on
  2017.        changes.
  2018.  
  2019.   The 2nd parameter (<exp>) should (almost has to)
  2020.        include the GET memvar somewhere within it.
  2021.  
  2022. Sample:
  2023.   Let's say you have a file maintenance routine of
  2024.        customer information.  This file has a primary key
  2025.        of customer number which is a unique number your
  2026.  
  2027.                                      Page: 61
  2028.  
  2029. company assigns to each customer.  One of the fields in your
  2030. customer information file is a serial number which is the
  2031. serial number of the product your company sold them.  Since
  2032. no two customers can possess the same product at the same
  2033. time you would like to make sure all the product serial
  2034. numbers entered into the database are unique.
  2035.  
  2036.   This is a situation where DUPCHK() could be used
  2037.        effectively.
  2038.   Let's now assume the system you designed contains a
  2039.        file called CUSTOMER containing the customer
  2040.        information and index order number three (3) is on
  2041.        the a field called SERIAL_NBR.
  2042.  
  2043.   You could program DUPCHK() to make sure inventory items
  2044.        are never keyed duplicated in the customer file as
  2045.        follows:
  2046.  
  2047.  
  2048.   Other file maintenance GETs.
  2049.   .
  2050.   .
  2051.   .
  2052.  
  2053.   @ WinTop()+05,WinLeft()+22 GET cSerial_Nbr VALID ;
  2054.           DupChk(cG_Func, "CUSTOMER",cSerial_Nbr,3, ;
  2055.           "ERROR: Serial Number Already in
  2056.           Use",WinBott()-1,WinLeft()+2,WinRight()-2,.t.)
  2057.  
  2058.  
  2059.   The DUPCHK() Valid above would force entry into the
  2060.        SERIAL_NBR field to be unique.  The error message
  2061.        would be displayed if the field were or would create
  2062.        a duplicate.  Because the ninth parameter is set to
  2063.        true (.T.) the error message would display if the
  2064.        user attempted to leave the field blank.  An error
  2065.        beep accompanies the error message display and the
  2066.        user is not allowed to proceed to the next field in
  2067.        the GET stream.
  2068.  
  2069.   Note that BUILDER is able to generate DupChk() Valid
  2070.        function calls.
  2071.                                           Page: 62
  2072. EDT_MEMO()
  2073.  
  2074. Syntax:
  2075.  
  2076.        edt_memo(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<ex
  2077.        pC2>, ;
  2078.        <expC3>,<expC4>,<expC5>[,<expN5>][,<expL1>][,<expL2>
  2079.        ]
  2080.  
  2081. Pass:
  2082.   <expN1> -     Top row screen coordinate.
  2083.   <expN2> -     Left column screen coordinate.
  2084.   <expN3> -     Bottom row screen coordinate.
  2085.   <expN4> -     Right column screen coordinate.
  2086.   <expC1> -     Memo field memvar.
  2087.   <expC2> -     Memo field database field name.
  2088.   <expC3> -     Memo title.
  2089.   <expC4> -     Color for memo data.
  2090.   <expC5> -     Color for title display.
  2091.   <expN5> -     Maximum lines memo may contain.  Default
  2092.           unlimited.
  2093.   <expL1> -     .F. view only, .T. allow editing.  Default
  2094.           .T.
  2095.   <expL2> -     .F. does nothing, .T. starts editing at the
  2096.           end of the memo text.  Default .F.
  2097.  
  2098. Returns:
  2099.   Nothing.
  2100.  
  2101. Description:
  2102.   EDT_MEMO() Puts a border on the screen, a title on the
  2103.        top line of the border, Displays an appropriate
  2104.        message line, and Saves the memo data if Ctrl+W is
  2105.        pressed.  This function may be used as a Valid
  2106.        function (BUILDER can create the call) or as a stand
  2107.        alone command.
  2108.  
  2109.   If used as a Valid function, DO NOT try to GET the memo
  2110.        field.  Issue a GET on a one byte character memvar
  2111.        and EDT_MEMO() will force the user to press "Y" to
  2112.        edit the memo data or "N" to bypass the field.
  2113.                                           Page: 63
  2114. ERRTONE()
  2115.  
  2116. Syntax:
  2117.   errtone([<expN>])
  2118.  
  2119. Pass:
  2120.   Nothing or zero (0) through four (4).
  2121.  
  2122. Returns:
  2123.   Nothing.
  2124.  
  2125. Description:
  2126.   The ERRTONE() function beeps the speaker in one of five
  2127.        ways, a two tone error beep if no parameters (or
  2128.        zero) are passed, a short high pitched single tone
  2129.        if one (1) is passed.  Passing a two (2) will make a
  2130.        two-tone ON indication sound, three (3) will make
  2131.        the opposite or a two-tone OFF sound.  Passing a
  2132.        four (4) makes a long low error tone.
  2133.                                           Page: 64
  2134. ETC()
  2135.  
  2136. Syntax:
  2137.   etc(<expC>,<expN1>,<expN2>,<expN3>)
  2138.  
  2139. Pass:
  2140.   <expC>  start time of process
  2141.   <expN1> start value of operation
  2142.   <expN2> maximum value of operation
  2143.   <expN3> current value, must be between <expN1> and
  2144.           <expN2>
  2145.  
  2146. Returns:
  2147.   A character expression.
  2148.  
  2149. Description:
  2150.   The ETC() function will calculate the estimated time to
  2151.        completion of an iterative process.  In order to be
  2152.        accurate, be sure to use this only in loops that
  2153.        occur at regular intervals.  Looping where some
  2154.        iterations are longer than others will cause some
  2155.        very unusual time estimates.
  2156.  
  2157.   See THERMOMETR()
  2158.  
  2159. Sample:
  2160.  
  2161.           **********************************************
  2162.           *****************
  2163.   ** ETC() function example to display current
  2164.           estimated time
  2165.   **       to compete a process.
  2166.  
  2167.   cStartTime := time()
  2168.   cOldTime := time()
  2169.   FOR J := 1 TO 500
  2170.           IF time() < > cOldTime       // Should only
  2171.           recalculate on time change
  2172.                 @ 1,0 SAY etc(cStartTime,1,500,j)
  2173.                 cOldTime := time()
  2174.           ENDIF
  2175.           Waitkey( .25 )
  2176.   NEXT
  2177.                                           Page: 65
  2178. FEOF()
  2179.  
  2180. Syntax:
  2181.   feof([<expL>])
  2182.  
  2183. Pass:
  2184.   A Logical Expression or Nothing
  2185.  
  2186. Returns:
  2187.   A logical expression
  2188.  
  2189. Description:
  2190.   The FEOF() function is designed only to be used in
  2191.        conjunction with the FGETS() function.  FEOF()
  2192.        Returns .T. when end of file is encountered while
  2193.        reading a file using the FGETS() function.
  2194.  
  2195.   Before using FEOF() you must first initialize its
  2196.        internal variables by issuing FEOF(.F.).  See the
  2197.        example code in the description for FGETS().
  2198.                                           Page: 66
  2199. FGETS()
  2200.  
  2201. Syntax:
  2202.   fgets(<expN>)
  2203.  
  2204. Pass:
  2205.   A file handle of a previously FOPEN()'d or FCREATE()'d
  2206.        file.
  2207.  
  2208. Returns:
  2209.   Next logical record in a CR/LF delimited file.
  2210.  
  2211. Description:
  2212.   The FGETS() function will attempt to read the next
  2213.        logical record in a CR/LF delimited file.
  2214.  
  2215. Sample:
  2216.  
  2217.           **********************************************
  2218.           ********
  2219.   ** Sample code to read the AUTOEXEC.BAT file using
  2220.           the   **
  2221.   ** Aeolus FGETS() function.                 **
  2222.           **********************************************
  2223.           ********
  2224.  
  2225.   ** Open the AUTOEXEC.BAT file
  2226.   nHandle := Fopen("C:\AUTOEXEC.BAT")
  2227.  
  2228.   FEof(.f.)                    // initialize FEOF()
  2229.   DO WHILE !FEof()
  2230.           ? FGets( nHandle )   // read next AUTOEXEC record
  2231.   ENDDO
  2232.   FClose( nHandle )
  2233.                                           Page: 67
  2234. FGETSR()
  2235.  
  2236. Syntax:
  2237.   fgetsr(<expN>)
  2238.  
  2239. Pass:
  2240.   A file handle of a previously FOPEN()'d or FCREATE()'d
  2241.        file.
  2242.  
  2243. Returns:
  2244.   The previous logical record in a CR/LF delimited file.
  2245.  
  2246. Description:
  2247.   The FGETSR() function will attempt to read the previous
  2248.        logical record in a CR/LF delimited file.
  2249.  
  2250. Sample:
  2251.  
  2252.           **********************************************
  2253.           ********
  2254.   ** Sample code to read the AUTOEXEC.BAT file using
  2255.           the   **
  2256.   ** Aeolus FGETS and FGETSR() functions.               **
  2257.  
  2258.           **********************************************
  2259.           ********
  2260.  
  2261.   ** Open the AUTOEXEC.BAT file
  2262.   nHandle := Fopen( "C:\AUTOEXEC.BAT" )
  2263.  
  2264.   FEof( .f. )                            // initialize FEOF()
  2265.   DO WHILE !FEof()
  2266.           ? FGets( nHandle )             // read next AUTOEXEC record
  2267.   ENDDO
  2268.  
  2269.   ** file pointer is at the end of file, let's use
  2270.           FGETSR()
  2271.   ** to read and display AUTOEXEC.BAT backwards.
  2272.  
  2273.   FEof(.f.)                              // reinitialize FEOF()
  2274.   DO WHILE !FEof()
  2275.           ? FGetsR( nHandle )
  2276.   ENDDO
  2277.   FClose( nHandle )
  2278.                                           Page: 68
  2279. FIL_LOCK()
  2280.  
  2281. Syntax:
  2282.   fil_lock(<expN>)
  2283.  
  2284. Pass:
  2285.   <expN>  seconds to wait before returning false, zero
  2286.           will not return false.
  2287.  
  2288. Returns:
  2289.   A logical expression.
  2290.  
  2291. Description:
  2292.   The FIL_LOCK() function will attempt to lock a
  2293.        previously opened .DBF database, if it fails in
  2294.        <expN> seconds an error box is displayed allowing
  2295.        the user to try again or abort the operation.  If
  2296.        <expN> is passed as a value of zero then FIL_LOCK()
  2297.        will wait indefinitely to attempt the lock.
  2298.  
  2299.   FIL_LOCK returns true if the lock is successful and
  2300.        false if the lock is unsuccessful.
  2301.  
  2302.   Note that all other file or record locks will be
  2303.        rejected while you have a successful FIL_LOCK(), be
  2304.        sure to UNLOCK the file or close the database so
  2305.        others on the LAN can use it.
  2306.  
  2307. Sample:
  2308.  
  2309.           **********************************************
  2310.           ********
  2311.   ** Attempt to lock a database previously opened in
  2312.           shared mode.
  2313.   **
  2314.   USE AddrBook SHARED NEW
  2315.   IF Fil_Lock( 5 )
  2316.           .
  2317.           .
  2318.           .
  2319.   ENDIF
  2320.   UNLOCK
  2321.                                           Page: 69
  2322. FLD_REPL()
  2323.  
  2324. Syntax:
  2325.   fld_repl(<expC>,<exp>[,<expN>])
  2326.  
  2327. Pass:
  2328.   <expC>  The name of the field in the currently
  2329.           selected database to be replaced.
  2330.   <exp>   The value to place in the database field
  2331.           <expC>
  2332.   <expN>  Timeout seconds if record cannot be locked.
  2333.  
  2334. Description:
  2335.   Use FLD_REPL whenever you need to REPLACE a single
  2336.        database field.  This function will work in a shared
  2337.        or single user application.  Using this function on
  2338.        single field REPLACEs will allow your application to
  2339.        be changed from a single to multi-user program
  2340.        simply by changing the NETWORK system variable from
  2341.        .F. to .T.!
  2342.  
  2343. Sample:
  2344.   ** replace a date field in the currently selected
  2345.           database
  2346.   ** with today's date - will work if single or multi
  2347.           user
  2348.  
  2349.   Fld_Repl( "CURRNT_DT", DATE() )
  2350.                                           Page: 70
  2351. GEN_MAINT()
  2352.  
  2353. Syntax:
  2354.   gen_maint(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ;
  2355.   <expA>[,<expN5>][,<expN6>][,<expL>][,<expC2>][,<expB>])
  2356.  
  2357. Pass:
  2358.   <expN1> top left row
  2359.   <expN2> top left column
  2360.   <expN3> bottom right row
  2361.   <expN4> bottom right column
  2362.   <expC1> procedure name suffix
  2363.   <expA>  DbStor() array name
  2364.   <expN5> fast delete index order number
  2365.   <expL>  .T. to allow duplicates in file
  2366.   <expC2> menu options to use
  2367.   <expB1> codeblock to execute after file writes and
  2368.           just before exit.  default none.
  2369.   <expB2> codeblock to execute when Ctrl+Enter is
  2370.           pressed.  default none.
  2371.  
  2372. Description:
  2373.   The GEN_MAINT function is one of two generic file
  2374.        maintenance functions included with the function
  2375.        library and is designed to be used as an all purpose
  2376.        file maintenance routine.
  2377.  
  2378.   Before you can call the GEN_MAINT function you must
  2379.        first code four procedures yourself, GSAYS_????,
  2380.        GGETS_????, GEDIT_???? and GKEY_????.  Where ???? is
  2381.        the value passed as <expC1>. The GSAYS_????
  2382.        procedure must contain the screen displays,
  2383.        GGETS_???? the get's, and GEDIT_???? additional code
  2384.        performed after a READ command.
  2385.  
  2386.   Call GEN_MAINT with <expN1> through <expN4> equal to
  2387.        the screen coordinates required.  <expC1> must equal
  2388.        the suffix portion of the three procedures you
  2389.        write.  <expA> is the array name that contains the
  2390.        data for each database record to be edited.
  2391.  
  2392.   Optionally pass <expN5> as the 'fast delete' index
  2393.        order number.  A fast delete index is created by
  2394.        issuing the following Clipper command:
  2395.  
  2396.   INDE ON IF(DELE(),"*"," ") TO ...
  2397.  
  2398.   If <expN5> is not passed or passed with a value of zero
  2399.        deleted records will accumulate in your database.
  2400.        Using the fast delete, records marked for deletion
  2401.  
  2402.                                      Page: 71
  2403.  
  2404. are used as 'add space' so your database doesn't grow
  2405. indefinitely.  Note that you must use either SET DELETED ON
  2406. or SET FILTER TO !DELE() for fast delete to work correctly.
  2407.   <expL> may be passed as true if duplicate records are
  2408.        to be  allowed.  The default is false.
  2409.   <expC2> is used to tell GEN_MAINT which of the three
  2410.        basic menu options to use,    Add-Change- and/or
  2411.        Delete.  Pass a character string with the first
  2412.        letter of each of the menu options to allow during
  2413.        the GEN_MAINT.  Passing "AC" for example  will only
  2414.        put "Add", and "Change" on the file maintenance
  2415.        menu, skipping "Delete" and "Find".  Passing a null
  2416.        string ("") will only allow "Find". The default is
  2417.        "ACD" if this is parameter is not passed.
  2418.  
  2419.   <expB> is a code block function to be executed on every
  2420.        file "Add", "Change", or "Delete" and before the
  2421.        File Maintenance isexited.  A character parameter is
  2422.        passed to this function indicating the action that
  2423.        has taken place "A" for Add, "C" for Change, "D" for
  2424.        Delete and "E" for Exit.  You must return a logical
  2425.        value from this function.  The return value is NOT
  2426.        checkedfor Adds, Changes, or Deletes.  However, on
  2427.        Exit if the return value is false (.F.) then the
  2428.        user will not be allowed to exit the file mainte
  2429.        nance.
  2430.  
  2431.   You can create your own sample calls to GEN_MAINT by
  2432.        creating file maintenance windows in BUILDER.
  2433.  
  2434. Sample:
  2435.   #Define ASLS_NBR   aTcsReps[1]
  2436.   #Define ALNAME     aTcsReps[2]
  2437.   #Define AFNAME     aTcsReps[3]
  2438.   #Define APHONE     aTcsReps[4]
  2439.   Func Fmnt_Exmpl()
  2440.           Local aTcsReps := {}
  2441.           LOCAL nTop, nLeft, nBott, nRight
  2442.  
  2443.           ** func to call a generic maintenance routine
  2444.           **
  2445.  
  2446.           nTop := 04
  2447.           nLeft := 30
  2448.           nBott := 12
  2449.           nRight := 67
  2450.           SELECTY TCSREPS
  2451.  
  2452.           aTcsReps := Array(FCount())
  2453.  
  2454. Page: 72
  2455.  
  2456.           Gen_Maint(nTop,nLeft,nBott,nRight,"REPS",aTcsR
  2457.           eps,.f., ;
  2458.           "AC",{|x|TestFunc(x)})
  2459.  
  2460.           ** since the 8th parm is "AC" only Adds and
  2461.           Changes will be allowed
  2462.   ** screen SAY's for generic maint of sales rep file
  2463.   **
  2464.   FUNCTION GSays_Reps( cG_Func )
  2465.           @ 2,2 WINSAY "Sales Rep #:"
  2466.           @ 4,2 WINSAY "Last Name:"
  2467.           @ 5,2 WINSAY "First Name:"
  2468.           @ 7,2 WINSAY "Phone:"
  2469.  
  2470.           IF cG_Func $ "AC"
  2471.                 SET CURSOR ON
  2472.                 READ
  2473.                 SET CURSOR OFF
  2474.           ENDIF
  2475.  
  2476.   ** screen GET's for generic maint of sales rep file
  2477.   **
  2478.   FUNCTION GGets_Reps( cG_Func )
  2479.                      // A-Add, C-Change, D-Delete or null if
  2480.                      // display only.
  2481.  
  2482.           @ 2,15 WINGET ASLS_NBR PICTURE "9999"
  2483.           CLEAR GETS
  2484.           @ 4,15 WINGET ALAST PICTURE "@!"
  2485.           @ 5,15 WINGET AFIRST PICTURE "@!"
  2486.           @ 7,15 WINGET APHONE PICTURE "@R (999) 999-
  2487.           9999"
  2488.  
  2489.   ** Function to edit data called after a screen is
  2490.           keyed but
  2491.   ** before the disk write
  2492.   **
  2493.   FUNCTION GEdit_Reps(cG_Func)
  2494.           RETURN( .t. )
  2495.  
  2496.   ** key GET's for generic maint of division file
  2497.   **
  2498.   FUNCTION GKey_Reps( cGk_Func )
  2499.                      // A-Add, D-Del, C-Change
  2500.  
  2501.           @ WinBott()-2, WinRight()-15, WinBott()+3,
  2502.           WinRight()+09 WINDOW
  2503.  
  2504.           SetMsgLin("Enter Sales Rep Number or Press ESC
  2505. Page: 73
  2506.           to Abort")
  2507.           cKey := Space( 4 )
  2508.           @ WinBott()-1,WinRight()-13 SAY "Sales Rep #:"
  2509.           GET cKey PICTURE "9999"
  2510.           @ WinBott()+1,WinRight()-13 SAY "Enter Sales
  2511.           Rep # Code"
  2512.           IF cGk_Func < > "A"
  2513.               @ WinBott()+2,WinRight()-13 SAY "Blank for
  2514.           Current Rec"
  2515.           ELSE
  2516.               @ WinBott()+2,WinRight()-13 SAY "to Add or
  2517.           ESC to Exit"
  2518.           ENDIF
  2519.           READ
  2520.           SetMsgLin( "" )
  2521.           WINDOW REMOVE
  2522.  
  2523.           ASLS_NBR := IF(empty(cKey .or. ;
  2524.           lastkey()==27, ;  ASLS_NBR,cKey)
  2525.           RETURN( cKey )
  2526.  
  2527.   FUNCTION TestFunc( cFunction )
  2528.                      // "A"-Add, "C"-Change, "D"-Delete, "E"-Exit.
  2529.  
  2530.           DO CASE
  2531.           CASE cFunction == "A"
  2532.               ** Record was added to database, do
  2533.           whatever we need to after that
  2534.               ** activity.
  2535.           CASE cFunction == "C"
  2536.               ** Current database record was Changed, do
  2537.           whatever is needed in
  2538.               ** that case.
  2539.           CASE cFunction == "D"
  2540.               ** Current database record is now a
  2541.           Deleted record, do whatever is
  2542.               ** needed (usually delete child relation
  2543.           records).
  2544.           CASE cFunction == "E"
  2545.               ** User is trying to exit the file
  2546.           maintenance, make sure it is ok for
  2547.               ** them to do so at this time.  If it is
  2548.           then return true (.T.) otherwise
  2549.               ** return false (.F.) to keep them in the
  2550.           file maintenance.
  2551.           ENDCASE
  2552.           RETURN( .T. )     // gotta return a logical
  2553.                                           Page: 74
  2554. GENVLD()
  2555.  
  2556. Syntax:
  2557.   genvld(<expL1>,<expC1>,<expN1>,<expN2>,<expN3>,<expL2>
  2558.        [,<expC2>])
  2559.  
  2560. Pass:
  2561.   <expL1> -     The validation test expression.
  2562.   <expC1> -     The error message on incorrect GET input.
  2563.   <expN1> -     The screen row number to display the error
  2564.           message.
  2565.   <expN2> -     The screen column number to display the
  2566.           error message.
  2567.   <expN3> -     The screen rightmost column number to
  2568.           pad/allow the error message to display.
  2569.   <expL2> -     Required indicator.  True (.T.) if field
  2570.           cannot be empty or false (.F.) if field is
  2571.           allowed to be empty.
  2572.   <expC2> -     Color string for error message to display,
  2573.           default is WERR_CLR.
  2574.  
  2575. Returns:
  2576.   A logical value.
  2577.  
  2578. Description:
  2579.   The GENVLD() function is a generic valid function used
  2580.        to validate a GET for any logical expression and
  2581.        display an error message on invalid input.
  2582.  
  2583. Sample:
  2584.   You have a two byte character GET for the U.S. state
  2585.        code and you would like to make sure what is keyed
  2586.        is legitimate code.  The following GENVLD() would do
  2587.        this:
  2588.  
  2589.   @ 05,22 WINGET cState PICTURE "!!" VALID ;
  2590.           GenVld( in_usa( cState ), ;
  2591.           "ERROR: Not a Valid U.S. State
  2592.           Code",WinBotT()-1,WinLeft()+2,WinRight()-
  2593.           2,.t.)
  2594.  
  2595.   See the IN_USA() function in this text also.
  2596.  
  2597.   In the above sample code the user would be forced to
  2598.        enter a valid U.S. state code into the STATE field.
  2599.        Attempting to leave the field blank would produce an
  2600.        error beep and the error message due to the sixth
  2601.        parameter being set to true.
  2602.  
  2603.   Any expression that returns a logical value (including
  2604.                                                Page: 75
  2605.  
  2606. your own UDFs) may be used in place of the IN_USA()
  2607.   function in the example.
  2608.                                           Page: 76
  2609. GETEDIT()
  2610.  
  2611. Syntax:
  2612.   GETEDIT(<expC1>,<expN1>,<expN2>)
  2613.  
  2614. Pass:
  2615.   <expC1> -     Database alias name.
  2616.   <expN1> -     Screen row coordinate to display "Save
  2617.           Changes?" prompt.
  2618.   <expN2> -     Screen column coordinate to display "Save
  2619.           Changes?" prompt.
  2620.  
  2621. Returns:
  2622.   NIL always.
  2623.  
  2624. Description:
  2625.   The GetEdit() function is placed immediately after a
  2626.        series of @..GET statements.  It will execute a READ
  2627.        for the GETs.  When the GETs are exited, if any
  2628.        changes were made, the user is prompted "Save
  2629.        Changes?" which requires a yes or no response.  If
  2630.        the no option is selected, the cursor is placed at
  2631.        the first GET again.  If yes, the memory variables
  2632.        are saved to like field variables in the database
  2633.        <expC1> and the function is exited.  If ESC is
  2634.        pressed while editing the GETs, the function is
  2635.        exited.
  2636.  
  2637.   The field variable names are determined by removing the
  2638.        first character of the memory variable named in each
  2639.        GET.
  2640.  
  2641. Sample:
  2642.   You have modified your OPTIONS.DBF database by adding
  2643.        three fields to contain printer control information.
  2644.        The fields you added are:  PCMPRS-C-40, PBOLD-C-40,
  2645.        PRESET-C-40.  You want to allow the users of your
  2646.        system to edit the printer control strings.  This is
  2647.        easily accomplished by converting a Builder dialog
  2648.        box as follows:
  2649.  
  2650.   Note that adding the three fields to OPTIONS.DBF and
  2651.        then generating source code from Builder, will
  2652.        create these three memory variables QPCMPRS, QPBOLD,
  2653.        and QPRESET automatically.
  2654.  
  2655.   Then in Builder, create a dialog box to edit these
  2656.        three memory variables.
  2657.  
  2658.   Next, in your dialog box to edit the printer control
  2659.  
  2660.                                      Page: 77
  2661.  
  2662. strings, delete the following source that Builder
  2663. creates:
  2664.  
  2665.   ReadGets( @GetList )
  2666.  
  2667.   IF LASTKEY() == K_ESC
  2668.           EXIT
  2669.   ENDIF
  2670.  
  2671.  
  2672.   Replace the deleted lines of code with these:
  2673.  
  2674.   GetEdit("OPTIONS",WinBott()-1,WinLeft()+2)
  2675.   EXIT
  2676.  
  2677.   Thats all there is to it, delete seven and add two!
  2678.                                           Page: 78
  2679. GOT()
  2680.  
  2681. Syntax:
  2682.   got(<expC>,<expN1>,<expN2>)
  2683.  
  2684. Pass:
  2685.   <expC>  database alias name
  2686.   <expN1> field number in database
  2687.   <expN2> record number of database
  2688.  
  2689. Returns:
  2690.   An expression determined by FIELDGET(<expN1>).
  2691.  
  2692. Description:
  2693.   Normally used in a valid function to pop up a scroll
  2694.        box and put the selected item in the READ field.
  2695.  
  2696.   <expC> is the database alias used for the look up,
  2697.        <expN1> is <expN1>th field in the database whose
  2698.        alias is <expC>.  <expN2> is the record number in
  2699.        that database, usually a call to the PLIST()
  2700.        function.
  2701.  
  2702.   The return value is whatever is the value of the
  2703.        databases <expN1>th field at record <expN2>.
  2704.  
  2705.   Note that this function is called by the BUILDER
  2706.        PckVld() function, and it is recommended that you
  2707.        use PckVld() instead of Got().  PckVld() is easier
  2708.        to use and can be created by BUILDER generated code.
  2709.                                           Page: 79
  2710. HEX2DEC()
  2711.  
  2712. Syntax:
  2713.   HEX2DEC(<expC>)
  2714.  
  2715. Pass:
  2716.   <expC> -      A string of hexadecimal digits.
  2717.  
  2718. Returns:
  2719.   A numeric decimal integer of the passed hexadecimal
  2720.        number.
  2721.  
  2722. Description:
  2723.   HEX2DEC() converts a hexadecimal character string to a
  2724.        numeric integer value.  This function is useful when
  2725.        calling some of the assembly routines in the BLDRASM
  2726.        library.
  2727.  
  2728.   See the TIMEOUT assembly routine also.
  2729.                                           Page: 80
  2730. HNDLS()
  2731.  
  2732. Syntax:
  2733.   HNDLS()
  2734.  
  2735. Pass:
  2736.   Nothing.
  2737.  
  2738. Returns:
  2739.   number of file handles.
  2740.  
  2741. Description:
  2742.   This function locates the DOS System File Table (SFT)
  2743.        and returns the number of file descriptor tables
  2744.        configured for the computer.  The number returned is
  2745.        five minus the actual value to account for the DOS
  2746.        used handles for the standard input, standard
  2747.        output, standard error, starndard auxilary, and
  2748.        standard print devices.
  2749.  
  2750.   This number will be the CONFIG.SYS FILE= number minus
  2751.        five in most instances.
  2752.                                           Page: 81
  2753. IN_CANADA()
  2754.  
  2755. Syntax:
  2756.   in_canada(<expC>)
  2757.  
  2758. Pass:
  2759.   <expC> -      A two byte character string
  2760.  
  2761. Returns:
  2762.   A logical expression.
  2763.  
  2764. Description:
  2765.   The IN_CANADA() function tests the passed parameter and
  2766.        returns true (.T.) if the value is a valid Canadian
  2767.        province code (see list below), otherwise false
  2768.        (.F.) is returned.  This function is useful when
  2769.        building VALID functions.  See the GENVLD() sample
  2770.        code also.
  2771.  
  2772. Notes:
  2773.   Canadian provinces tested in IN_CANADA():
  2774.  
  2775.   AB - Alberta   NS  -     Nova Scotia
  2776.   BC - British Columbia    ON - Ontario
  2777.   MB - Manitoba  PQ - Quebec
  2778.   NB - New Brunswick  SK - Saskatchewan
  2779.   NF - Newfoundland
  2780.                                           Page: 82
  2781. IN_USA()
  2782.  
  2783. Syntax:
  2784.   in_usa(<expC>)
  2785.  
  2786. Pass:
  2787.   <expC> -      A two byte character string
  2788.  
  2789. Returns:
  2790.   A logical expression.
  2791.  
  2792. Description:
  2793.   The IN_USA() function tests the passed parameter and
  2794.        returns true (.T.) if the value is a valid U.S.
  2795.        State code (see list below), otherwise false (.F.)
  2796.        is returned.  This function is useful when building
  2797.        VALID functions.  See the GENVLD() sample code also.
  2798.  
  2799. Notes:
  2800.   U.S. State codes tested by IN_USA():
  2801.  
  2802.   AL - Alabama   KY - Kentucky  ND - North Dakota
  2803.   AK - Alaska    LA - Louisiana OH - Ohio
  2804.   AZ - Arizona   ME - Maine     OK - Oklahoma
  2805.   AR - Arkansas  MD - Maryland  OR - Oregon
  2806.   CA - California     MA - Massachusetts  PA - Pennsylva
  2807.        nia
  2808.   CO - Colorado  MI - Michigan  RI - Rhode Island
  2809.   CT - Connecticut    MN - Minnesota SC - South Carolina
  2810.   DE - Delaware  MS - Mississippi    SD - South Dakota
  2811.   DC - Washington D.C.     MO - Missouri  TN - Tennessee
  2812.   FL - Florida   MT - Montana   TX - Texas
  2813.   GA - Georgia   NE - Nebraska  UT - Utah
  2814.   HI - Hawaii    NV - Nevada    VT - Vermont
  2815.   ID - Idaho     NH - New Hampshire  VA - Virginia
  2816.   IL - Illinois  NJ - New Jersey     WA - Washington
  2817.   IN - Indiana   NM - New Mexico     WV - West Virginia
  2818.   IA - Iowa NY - New York  WI - Wisconsin
  2819.   KS - Kansas    NC - North Carolina WY - Wyoming
  2820.  
  2821. Note:  The codes for Puerto Rico (PR) and the U.S. Virgin
  2822.        Islands (VI) are not tested.
  2823.                                           Page: 83
  2824. INFILE()
  2825.  
  2826. Syntax:
  2827.   infile(<expC1>,<expN1>,<expC2>,<expN2>,<expN3>,<expN4>,
  2828.        ;
  2829.        <expL>[,<expC3>])
  2830.  
  2831. Pass:
  2832.   <expC1> -     File alias name of look up table.
  2833.   <expN1> -     Index order number for SEEK.
  2834.   <expC2> -     The error message on incorrect GET input.
  2835.   <expN2> -     The screen row number to display the error
  2836.           message.
  2837.   <expN3> -     The screen column number to display the
  2838.           error message.
  2839.   <expN4> -     The screen rightmost column number to
  2840.           pad/allow the error message to display.
  2841.   <expL>  -     Required indicator.  True (.T.) if field
  2842.           cannot be empty or false (.F.) if field is
  2843.           allowed to be empty.
  2844.   <expC3> -     Color string for error message to display,
  2845.           default is WERR_CLR.
  2846.  
  2847. Returns:
  2848.   A logical value.
  2849.  
  2850. Description:
  2851.   The INFILE() function tests the input of the @...GET
  2852.        and displays an error message if the value entered
  2853.        is not FOUND() in a database.  The programmer may
  2854.        allow or disallow the entry of a blank into the
  2855.        field with <expL>
  2856.  
  2857. Sample:
  2858.   You have a four byte character GET for an employee
  2859.        number and you would like to make sure what is keyed
  2860.        is a legitimate code.  Further there is an employee
  2861.        file with index order one (1) on the four digit
  2862.        employee code.  The following GET will force the
  2863.        entry of a valid employee code based on the look up
  2864.        table (called EMPLYEE).
  2865.  
  2866.   @ 05,22 WINGET cEmpNbr PICTURE "!!" VALID ;
  2867.           InFile("EMPLYEE",1, ;
  2868.           "ERROR: Not a Valid Employee Code",WinBott()-
  2869.           1,WinLeft()+2,WinRight()-2,.t.)
  2870.  
  2871.   In the above sample code the user would be forced to
  2872.        enter a valid employee code into the EMP_NBR field.
  2873.        Attempting to leave the field blank would produce an
  2874.                                                Page: 84
  2875.  
  2876. error beep and the error message due to the seventh
  2877. parameter being set to true.
  2878.  
  2879.   The INFILE() function is only useful if you specifi
  2880.        cally do not want to help your users find the
  2881.        required field entry from the look up table.
  2882.        Sometimes this is necessary, however, I believe you
  2883.        will find the PCKVLD() function will be useful in
  2884.        more situations.
  2885.                                           Page: 85
  2886. INPATH()
  2887.  
  2888. Syntax:
  2889.   inpath(<expC1>[,<expC2>])
  2890.  
  2891. Pass:
  2892.   <expC1> -     DOS filename to locate.
  2893.   <expC2> -     environment variable with pathnames
  2894.           separated by semicolons of paths to search for
  2895.           <expC1>.  Default value is "PATH".
  2896.  
  2897. Returns:
  2898.   A character value of the path where <expC1> is located.
  2899.        A null string is returned if it was not found.  A
  2900.        "." (period character) is returned if it was found
  2901.        in the current directory.
  2902.  
  2903. Description:
  2904.   The INPATH() function first searches the current DOS
  2905.        directory for the file <expC1> and returns "." if it
  2906.        is found.  It then searches each directory in the
  2907.        DOS PATH environment variable or if <expC2> is
  2908.        passed that environment variable is used instead.
  2909.        If <expC2> is passed it must contain directory names
  2910.        separated by semicolons just like the DOS PATH.
  2911.                                           Page: 86
  2912. IOCTL()
  2913.  
  2914. Syntax:
  2915.   ioctl( <expN1>,<expN2>)
  2916.  
  2917. Pass:
  2918.   <expN1> The file handle of a currently opened file.
  2919.   <expN2> a 1 (one) to change the IO from text to
  2920.           binary, or 0 (zero) to change the IO to
  2921.           text.
  2922.  
  2923. Returns:
  2924.   A DOS error code from the following table:
  2925.  
  2926.   000  No error
  2927.   001  Invalid function number
  2928.   002  File not found
  2929.   003  Path not found
  2930.   004  Too many open files (no handles left)
  2931.   005  Access denied
  2932.   006  Invalid handle
  2933.   007  Memory control blocks destroyed
  2934.   008  Insufficient memory
  2935.   009  Invalid memory block address
  2936.   010  Invalid environment
  2937.   011  Invalid format
  2938.   012  Invalid access mode (open mode is invalid)
  2939.   013  Invalid data
  2940.   014  Reserved
  2941.   015  Invalid drive specified
  2942.   016  Attempt to remove current directory
  2943.   017  Not same device
  2944.   018  No more files
  2945.   019  Attmept to write on a write-protected diskette
  2946.   020  Unknown unit
  2947.   021  Drive not ready
  2948.   022  Unknown command
  2949.   023  CRC error
  2950.   024  Bad request structure length
  2951.   025  Seek error
  2952.   026  Unknown media type
  2953.   027  Sector not found
  2954.   028  Printer out of paper
  2955.   029  Write fault
  2956.   030  Read fault
  2957.   031  General failure
  2958.   032  Sharing violation
  2959.   033  Lock violation
  2960.   034  Invalid disk change
  2961.   035  FCB unavailable
  2962.  
  2963.                                      Page: 87
  2964.  
  2965.   036  Sharing buffer overflow
  2966.   037  Reserved
  2967.   038  Unable to complete file operation
  2968.   039 - 049 Reserved
  2969.   050  Network request not supported
  2970.   051  Remote computer not listening
  2971.   052  Duplicate name on network
  2972.   053  Network name not found
  2973.   054  Network busy
  2974.   055  Network device no longer exists
  2975.   056  NetBIOS command limit exceeded
  2976.   057  Network adapter error
  2977.   058  Incorrect network response
  2978.   059  Unexpected network error
  2979.   060  Incompatible remove adapter
  2980.   061  Print queue full
  2981.   062  No space for print file
  2982.   063  Print file deleted
  2983.   064  Network name deleted
  2984.   065  Access denied
  2985.   066  Network device type incorrect
  2986.   067  Network name not found
  2987.   068  Network name limit exceeded
  2988.   069  NetBiOS session limit exceeded
  2989.   070  Temporarily paused
  2990.   071  Network request not accepted
  2991.   072  Print or disk redirection is paused
  2992.   073 - 080 Reserved
  2993.   080  File already exists
  2994.   081  Reserved
  2995.   082  Cannot make directory entry
  2996.   083  Fail on INT 24
  2997.   084  Too many redirections
  2998.   085  Duplicate redirections
  2999.   086  Invalid password
  3000.   087  Invalid parameter
  3001.   088  Network device fault
  3002.   089  Function not supported by network
  3003.   090  Required system component not installed
  3004.  
  3005. Description:
  3006.   This function is useful when you need to read a
  3007.        graphics file or want to write a function to
  3008.        download printer fonts.  These types of files cannot
  3009.        be read properly with the default DOS IO control
  3010.        setting for reading text files.
  3011.                                           Page: 88
  3012. ISEEK()
  3013.  
  3014. Syntax:
  3015.   iseek(<exp>[,<expC>][,<expN>][,<expL>])
  3016.  
  3017. Pass:
  3018.   <exp>   expression to SEEK
  3019.   <expC>  database alias name, default is current select
  3020.           alias.
  3021.   <expN>  index order number to use for SEEK command,
  3022.           default used is the current index order.
  3023.   <expL>  .T. to use SOFTSEEK ON, .F. for SOFTSEEK OFF,
  3024.           default is the current SOFTSEEK setting.
  3025.  
  3026. Returns:
  3027.   a logical expression.
  3028.  
  3029. Description:
  3030.   The ISEEK() function does an indexed search of a
  3031.        database and returns the FOUND() condition.
  3032.  
  3033.   <exp> is the key value to search for, <expC> is the
  3034.        database alias to SELECT for the indexed search.
  3035.        <expN> is the index order number to use in the
  3036.        search, if zero or not supplied the current index
  3037.        order is used.  Set <expL> to true to use 'softseek
  3038.        on' or false for 'softseek off', if <expL> is not
  3039.        passed the current SOFTSEEK setting is used.
  3040.  
  3041. Sample:
  3042.  
  3043.           **********************************************
  3044.           ********
  3045.   ** ISEEK() function example
  3046.   **
  3047.   USE Customer NEW
  3048.   INDEX ON Cust_Nbr TO Cstmr1
  3049.   INDEX ON TRIM( LName ) + " " + FName TO Cstmr2
  3050.   SET INDEX TO Cstmr1,Cstmr2
  3051.  
  3052.   CLS
  3053.   cCust_Nbr := Space( 9 )
  3054.   @ 1,1 SAY "Enter Customer Number" GET cCust_Nbr
  3055.   READ
  3056.  
  3057.   IF ISeek( cCust_Nbr, "CUSTOMER", 1, .F. )
  3058.           @ 2,1 SAY "Customer Number Found."
  3059.   ENDIF
  3060.  
  3061.   Note that with Clipper version 5.01 and above you
  3062.  
  3063.                                      Page: 89
  3064.  
  3065. should use the Clipper DBSEEK() function instead of ISeek().
  3066. Consider ISeek() obsolete for use with Clipper 5.01 and up.
  3067.                                           Page: 90
  3068. KYBD()
  3069.  
  3070. Syntax:
  3071.   Kybd( <expC> )
  3072.  
  3073. Pass:
  3074.   <expC>    a character string of keys to place in
  3075.        the keyboard buffer.
  3076.  
  3077. Returns:
  3078.   NIL always.
  3079.  
  3080. Description:
  3081.   The Kybd() function simply executes a Clipper KEYBOARD
  3082.        command using <expC> as the parameter.  The
  3083.        advantage Kybd() offers is that it can be executed
  3084.        from a codeblock.  This is useful when setting up
  3085.        mouse pads.
  3086.  
  3087.   See AddMPad()
  3088.                                           Page: 91
  3089. MAKE_EMPTY()
  3090.  
  3091. Syntax:
  3092.   make_empty(<expC>)
  3093.  
  3094. Pass:
  3095.   <expC> existing memory variable name
  3096.  
  3097. Returns:
  3098.   The same data type as the variable named in <expC>.
  3099.  
  3100. Description:
  3101.   The memory variable name <expC> is returned in its
  3102.        empty form. A character variable is spaces the
  3103.        length of the passed variable, a numeric is returned
  3104.        as zero, etc.
  3105.  
  3106. Sample:
  3107.  
  3108.           **********************************************
  3109.           ********
  3110.   *** Make empty function example
  3111.   ***
  3112.  
  3113.   dTestDate := DATE()
  3114.   ? Make_Empty("TST_DAT") // same as ctod("  /  /  ")
  3115.   nTestNumber := 998
  3116.   ? Make_eEpty("TST_NBR")      // same as 0 (zero)
  3117.   cTestCharacter := "Software Can be Groovy"
  3118.   ? Make_Empty("TST_CHR") // same as space(22)
  3119.                                           Page: 92
  3120. MAKDIR()
  3121.  
  3122. Syntax:
  3123.   makdir(<expC>)
  3124.  
  3125. Pass:
  3126.   <expC> -      Name of new DOS subdirectory to create.
  3127.  
  3128. Returns:
  3129.   DOS error code.
  3130.  
  3131. Description:
  3132.   The MAKDIR assembly subroutine attempts to create the
  3133.        DOS subdirectory passed as <expC>.
  3134.  
  3135.   This routine is useful when writing installation
  3136.        programs or end of year archiving and any other
  3137.        reason you may have to create a DOS subdirectory
  3138.        from your Clipper program.  You can test the results
  3139.        of MAKDIR using CHGDIR, CHGDSK and CURDIR()
  3140.  
  3141.   See CHGDIR(), CHGDSK()
  3142.                                           Page: 93
  3143. MAXHNDLS()
  3144.  
  3145. Syntax:
  3146.   maxhndls([<expN>])
  3147.  
  3148. Pass:
  3149.   Zero/nothing or a numeric expression
  3150.  
  3151. Returns:
  3152.   If zero or nothing is passed MAXHNDLS() returns the
  3153.        maximum number of DOS file handles available to the
  3154.        computer.  This number does not mean your program
  3155.        will be able to open that number of files.  The
  3156.        CLIPPER environment variable or the program command
  3157.        line MUST set the file handles also.  If BOTH the
  3158.        DOS and Clipper configuration settings for file
  3159.        handles are not set, you may get DOS ERROR 4's.
  3160.  
  3161.   If a number is passed, MAXHNDLS returns true if the
  3162.        number of DOS file handles available is equal or
  3163.        greater, otherwise MAXHNDLS() returns false.  If
  3164.        false is to be returned MAXHNDLS() will display an
  3165.        error box before returning.
  3166.  
  3167. Description:
  3168.   Allows a Clipper program to determine the maximum
  3169.        number of available DOS file handles in the current
  3170.        system configuration.
  3171.  
  3172.   Also displays errors if fewer than <expN> file handles
  3173.        are present in the current configuration.
  3174.                                           Page: 94
  3175. MENU()
  3176.  
  3177. Syntax:
  3178.   MENU(<expA>[,<exp>][,<expO>][,<expL>])
  3179.  
  3180. Pass:
  3181.   <expA>  -     Array created by ADDPROMPT() or
  3182.           CRTMNUARRY().
  3183.   <exp>    -    Default menu option to highlight.
  3184.   <expO>  -     Current GET object.  Only use when MENU()
  3185.           is being used as a GET reader.
  3186.   <expL>  -     Display only if .T..  Default .F..
  3187.  
  3188. Returns:
  3189.   Indicator of selected menu option.
  3190.  
  3191. Description:
  3192.   To use the MENU() function, first create a menu array
  3193.        using either the @..ABPROMPT or @..WINPROMPT Builder
  3194.        command or using the CRTMNUARRY() Builder function.
  3195.        You can look at Builder generated code to see
  3196.        samples.
  3197.  
  3198.   Once a menu array is established, the MENU() function
  3199.        will display the menu options and return an
  3200.        indicator of which prompt, if any, was selected.
  3201.  
  3202.   Pass <exp> to set the default menu option.  <exp> can
  3203.        be passed as either a Numeric or Character data
  3204.        type.  If passed as a Numeric, MENU() will return a
  3205.        Numeric value.  If passed as a Character, MENU()
  3206.        will return a Character value.
  3207.  
  3208.   If <exp> is Numeric or not passed as a parameter,
  3209.        MENU() will return the array element number of the
  3210.        user menu selection.  Zero (0) is returned if the
  3211.        ESC key or right mouse button are pressed.
  3212.  
  3213.   If <exp> is Character, MENU() will return the unique
  3214.        character highlighted within the menu prompt when
  3215.        selected or a space character if the ESC key or
  3216.        right mouse button are pressed.
  3217.  
  3218.   Note that if ALL menu prompts have a code block to
  3219.        execute upon selection, MENU() can only return a
  3220.        zero (0) or space, only menu prompts added without a
  3221.        code block will return a value greater than zero or
  3222.        space.
  3223.  
  3224.   <expO> and <expL> are used only when MENU() is being
  3225.  
  3226.                                      Page: 95
  3227.  
  3228. used as a GET reader.  With <expO> as the value of the
  3229. current GET object, and <expL> used to initially display a
  3230. menu in a GET stream. See the example below on how this is
  3231. accomplished.  Note that Builder is capable of generating
  3232. all the needed code to create menus in a GET stream, see the
  3233. @MENU picture option.
  3234.  
  3235.   // First a 'normal' menu
  3236.  
  3237.   LOCAL aMenuArray := {}
  3238.   LOCAL xOpt
  3239.  
  3240.   // set up all the menu prompts and have each execute
  3241.           a code block.
  3242.   @ 05, 10 ABPROMPT " First  " TO aMenuArray EXECUTE
  3243.           FuncOne()
  3244.   @ 06,10 ABPROMPT " Second " TO aMenuArray EXECUTE
  3245.           FuncTwo()
  3246.   @ 07,10 ABPROMPT " Third  " TO aMenuArray EXECUTE
  3247.           FuncThr()
  3248.   @ 08,10 ABPROMPT " Fourth " TO aMenuArray EXECUTE
  3249.           FuncFor()
  3250.  
  3251.   // xOpt := " "  // uncomment this line and ABMENU()
  3252.           will return
  3253.           // "F", "S", "T", or "O" instead of 1, 2, 3,
  3254.           or 4
  3255.  
  3256.   xOpt := Menu(aMenuArray)         // execute the menu
  3257.  
  3258.   // Of course this is a 'trick' menu, Opt can ONLY
  3259.           get set to zero.  After a
  3260.   // code block executes, it returns to MENU(), since
  3261.           each prompt has a code
  3262.   // block the only way to return from MENU() is to
  3263.           ESC.
  3264.  
  3265.   RETURN( NIL )
  3266.  
  3267.   FUNCTION FuncOne()
  3268.           MsgBox("First Menu Option")
  3269.           RETURN( NIL )
  3270.  
  3271.   FUNCTION FuncTwo()
  3272.           MsgBox("Second Menu Option")
  3273.           RETURN( NIL )
  3274.  
  3275.   FUNCTION FuncThr()
  3276.           MsgBox("Third Menu Option")
  3277.  
  3278. Page: 96
  3279.  
  3280.           RETURN( NIL )
  3281.  
  3282.   FUNCTION FuncFor()
  3283.           MsgBox("Fourth Menu Option")
  3284.           RETURN( NIL )
  3285.  
  3286. Sample 2:
  3287.   // the same as the previous example with a different
  3288.           programming style
  3289.  
  3290.   LOCAL aMenuArray := {}
  3291.   LOCAL xOpt
  3292.  
  3293.   // set up menu prompts
  3294.   @ 05,10 ABPROMPT " First  " TO aMenuArray
  3295.   @ 06,10 ABPROMPT " Second  " TO  aMenuArray
  3296.   @ 07,10 ABPROMPT " Third  "  TO aMenuArray
  3297.   @ 08,10 ABPROMPT " Fourth " TO aMenuArray
  3298.  
  3299.   xOpt := " "
  3300.  
  3301.   DO WHILE .T.
  3302.           xOpt := Menu( aMenuArray, xOpt )
  3303.  
  3304.           DO CASE
  3305.           CASE xOpt == " "
  3306.                 EXIT
  3307.           CASE xOpt == "F"
  3308.                 FuncOne()
  3309.           CASE xOpt == "S"
  3310.                 FuncTwo()
  3311.           CASE xOpt == "T"
  3312.                 FuncThr()
  3313.           CASE xOpt == "O"
  3314.                 FuncFor()
  3315.           ENDCASE
  3316.   ENDDO
  3317.  
  3318.   RETURN( NIL )
  3319.  
  3320. Note:
  3321.   Sample 1 above is easily created by the BUILDER
  3322.        program, there is no need to learn ALL the syntax.
  3323.        Also see the @MEMO and @MENU Picture functions in
  3324.        the BUILDER manual.
  3325.                                           Page: 97
  3326. MESSAGE()
  3327.  
  3328. Syntax:
  3329.   message(<expC1>,<expN1>,<expN2>[,<expN3>][,<expC2>])
  3330.  
  3331. Pass:
  3332.   <expC1> text to display on the screen
  3333.   <expN1> row to display
  3334.   <expN2> column to display
  3335.   <expN3> length to pad/truncate message text
  3336.   <expC2> alternate color choice
  3337.  
  3338. Returns:
  3339.   Nothing.
  3340.  
  3341. Description:
  3342.   The MESSAGE() function places <expC1> on the screen at
  3343.        row <expN1> column <expN2> and pads <expC1> (or
  3344.        trims it) to a length of <expN3>.  <expC2> may be
  3345.        used as an alternate color choice.  If <expN3> is
  3346.        not passed, the LEN(<expC1>) is used instead.  If
  3347.        <expC2> is not passed, the current color is used.
  3348.  
  3349. Sample:
  3350.  
  3351.           **********************************************
  3352.           *************
  3353.   *** MESSAGE function example.
  3354.   ***
  3355.  
  3356.   Message( "Test Message 1", 01, 00, 80, "+w/b" )
  3357.   Waitkey()
  3358.                                           Page: 98
  3359. MGETROWCOL()
  3360.  
  3361. Syntax:
  3362.   MGETROWCOL(@<expN1>,@<expN2>)
  3363.  
  3364. Pass:
  3365.   <expN1> -     A numeric variable passed by reference.
  3366.   <expN2> -     A numeric variable passed by reference.
  3367.  
  3368. Returns:
  3369.   Integer indicating mouse button status and sets <expN1>
  3370.        and <expN2> with the current mouse cursor row and
  3371.        column.
  3372.  
  3373.   0 - No button pressed.
  3374.   1 - Left button pressed.
  3375.   2 - Right button pressed.
  3376.   3 - Left and right button pressed.
  3377.   4 - Middle button pressed.
  3378.   5 - Left and middle buttons pressed.
  3379.   6 - Right and middle buttons pressed.
  3380.   7 - All three buttons pressed.
  3381.  
  3382. Description:
  3383. <indent 3/4 inch>     Use when adding mouse capability to a
  3384.        pre-existing routine.  Do not use the mouse button
  3385.        return information from this function, only use the
  3386.        row and column information.  The Builder SETMOUSE()
  3387.        function should be used to check mouse button
  3388.        status.
  3389.  
  3390.   See: MSETROWCOL(),ADDMPAD(),DELMPAD(),MOUSEINIT(),
  3391.        SETMOUSE(),MOUSCRS()
  3392.                                           Page: 99
  3393. MOUSCRS()
  3394.  
  3395. Syntax:
  3396.   MOUSCRS(<expL>)
  3397.  
  3398. Pass:
  3399.   <expL> -      Set to true to turn mouse cursor on, false
  3400.           to turn it off.
  3401.  
  3402. Returns:
  3403.   NIL always.
  3404.  
  3405. Description:
  3406.   This function simply turns the mouse cursor off and on.
  3407.        Every time a call is made to turn the mouse cursor
  3408.        off, the mouse driver saves the screen byte and
  3409.        attribute at the current mouse cursor location.  The
  3410.        driver also increments an internal counter for use
  3411.        when trying to turn the cursor back on.  The mouse
  3412.        cursor will only be turned on by the mouse driver
  3413.        when it's internal counter is set to zero.  Each
  3414.        call to turn the cursor back on will decrement the
  3415.        mouse driver counter; except when the counter is
  3416.        zero, it will remain zero.
  3417.  
  3418.   What this all means is that every call to MousCrs(.f.)
  3419.        will have to have a matching MousCrs(.t.).  If you
  3420.        make two calls to AbMousCrs(.f.), it will take two
  3421.        calls to MousCrs(.t.) to put the mouse cursor back
  3422.        on the screen.
  3423.  
  3424.   See: MGETROWCOL(),ADDMPAD(),DELMPAD(),MOUSEINIT(),
  3425.        SETMOUSE(),MSETROWCOL()
  3426.                                           Page: 100
  3427. MOUSEINIT()
  3428.  
  3429. Syntax:
  3430.   MOUSEINIT([<expN>])
  3431.  
  3432. Pass:
  3433.   <expN> - An INKEY() value.
  3434.  
  3435. Returns:
  3436.   NIL always.
  3437.  
  3438. Description:
  3439.   This function initializes the Builder mouse routines.
  3440.        <expN> is the INKEY() value for the hot key used
  3441.        when configuring mouse action in a Clipper or 3rd
  3442.        party 'closed' function.  Clipper 'closed' functions
  3443.        are ACHOICE(), MEMOEDIT() and the like, where the
  3444.        keyboard loop is not accessible.
  3445.  
  3446.   When first executed in a program MOUSEINIT() turns the
  3447.        mouse cursor on at screen row 24 column 79 and
  3448.        executes the function SETMOUSE().  The SETMOUSE()
  3449.        function monitors mouse activity at ALL times, even
  3450.        inside 'closed' functions.
  3451.  
  3452.   See the SETMOUSE() function for more information.
  3453.  
  3454.   Builder enters the MOUSEINIT() function in the source
  3455.        code for you, and sets the default 'hot key' to
  3456.        KP_ALT_MINUS.  The Builder function EDT_MEMO() and
  3457.        the Builder help system require this 'hot key' if
  3458.        mouse functionality is to be used in these areas. It
  3459.        is strongly reccomended this is not changed.
  3460.                                           Page: 101
  3461. MOUSEINT()
  3462.  
  3463. Syntax:
  3464.   MouseInt(<expN1>,<expN2>,<expN3>,<expN4>)
  3465.  
  3466. Pass:
  3467.   <expN1> -     Value to pass for AX register.
  3468.   <expN2> -     Value to pass for BX register.
  3469.   <expN3> -     Value to pass for CX register.
  3470.   <expN4> -     Value to pass for DX register.
  3471.  
  3472. Returns:
  3473.   NIL always.  You can obtain register value after the
  3474.        mouse driver interrupt is called by passing any
  3475.        argument by reference.
  3476.  
  3477. Description:
  3478.   This function simply executes the calls to the mouse
  3479.        driver interrupt.
  3480.  
  3481.   Example 1:
  3482.  
  3483.   // Source code for the AbMGetRowCol() function
  3484.   FUNCTION AbMGetRowCol( nRow, nCol )
  3485.           LOCAL AX,BX,CX,DX
  3486.  
  3487.           nRow := If( nRow==NIL, 0, nRow )
  3488.           nCol := If( nCol==NIL, 0, nCol )
  3489.  
  3490.           AX := 3         // mouse driver call to get cursor
  3491.           screen
  3492.                      // location
  3493.  
  3494.           // I don't need to know AX, but do need BX,
  3495.           CX, and DX values
  3496.           // after the interrupt
  3497.           MouseInt( AX, @BX, @CX, @DX )  // execute
  3498.           mouse interrupt
  3499.  
  3500.           nRow := Int( DX / 8 )          // convert to rows
  3501.           nCol := Int( CX / 8 )          // convert to columns
  3502.  
  3503.           RETURN( BX )              // return button status
  3504.  
  3505.   Example 2:
  3506.  
  3507.   // Source code for function AbMSetRowCol()
  3508.   FUNCTION AbMSetRowCol( nRow, nCol )
  3509.           LOCAL AX,BX,CX,DX
  3510.  
  3511.  
  3512. Page: 102
  3513.  
  3514.           AX := 4              // mouse driver call to set screen
  3515.                                // cursor location
  3516.           CX := nCol * 8       // assign converted columns
  3517.           DX := nRow * 8       // assign converted rows
  3518.           MouseInt( AX, BX, CX, DX )     // execute mouse
  3519.           interrupt
  3520.  
  3521.           // All agruments passed by value, no informa
  3522.           tion is returned by this call
  3523.  
  3524.           // Note that BX value was passed as NIL.  This
  3525.           is OK for the function.
  3526.  
  3527.           RETURN( NIL )
  3528.                                           Page: 103
  3529. MSETROWCOL()
  3530.  
  3531. Syntax:
  3532.   MSETROWCOL(<expN1>,<expN2>)
  3533.  
  3534. Pass:
  3535.   <expN1> -     Screen row coordinate to place mouse
  3536.           cursor.
  3537.   <expN2> -     Screen column corrdinate to place mouse
  3538.           cursor.
  3539.  
  3540. Returns:
  3541.   NIL always.
  3542.  
  3543. Description:
  3544.   This function is used to change the mouse cursor
  3545.        position. Note: you will most likely never need to
  3546.        use this function.
  3547.  
  3548.  
  3549.   See: MGETROWCOL(),ADDMPAD(),DELMPAD(),MOUSEINIT(),
  3550.        SETMOUSE(),MOUSCRS()
  3551.                                           Page: 104
  3552. MSGBOX()
  3553.  
  3554. Syntax:
  3555.   msgbox(<expC1>[,<expC2>][,<expC3>][,<expC4>][,<expN1>]
  3556.   [,<expN2>][,<expN3>][,<expN4>])
  3557.  
  3558. Pass:
  3559.   <expC1>/<expA1>  message for line one or array name
  3560.           to display.
  3561.   <expC2> alternate color choice
  3562.   <expC3> message for line two - input prompt
  3563.   <expC4>/<expA2>  character list for allowable input
  3564.           (null ("") for any key) or array of menu
  3565.           prompts.
  3566.   <expN1> top left row
  3567.   <expN2> top left column
  3568.   <expN3> bottom right row
  3569.   <expN4> bottom right column
  3570.  
  3571. Returns:
  3572.   nothing or a character expression depending on the
  3573.        value of <expC4>.
  3574.  
  3575. Description:
  3576.   This function puts a message box on the screen and
  3577.        waits for an acknowledgment.
  3578.  
  3579.   If only <expC1> is passed as an argument a box is
  3580.        centered on the screen sized to fit <expC1> inside.
  3581.        The message is displayed in bright yellow with a red
  3582.        background by default, useful for error messages.
  3583.  
  3584.   Pass <expC2> as an alternate color choice.
  3585.  
  3586.   <expC3> and <expC4> usually work together, <expC3> is a
  3587.        prompt and <expC4> is a list of characters that,
  3588.        when entered from the keyboard, will remove the box
  3589.        from the screen.
  3590.  
  3591.   <expC4> need only contain one of each alphabetic
  3592.        character as it is converted to upper case before
  3593.        being used by MSGBOX().
  3594.  
  3595.   <expN1> and <expN2> are optional row and column screen
  3596.        positions for the box.
  3597.  
  3598.   <expN3> and <expN4> may be passed to optionally size
  3599.        the box.
  3600.  
  3601. Sample:
  3602.  
  3603.                                      Page: 105
  3604.  
  3605.  
  3606.           **********************************************
  3607.           ***********
  3608.   *** MSGBOX function example
  3609.   ***
  3610.  
  3611.   MsgBox( "Error Message" )
  3612.   MsgBox( "Information Message", "+w/b" )
  3613.   IF MsgBox( "Do You Play the Piano?", "+w/b", "Press
  3614.           Y or N", ;
  3615.   "YN", 10, 5 ) == "Y"
  3616.           MsgBox( "You Pressed Yes", "+w/b" )
  3617.   ELSE
  3618.           MsgNox( "You Pressed No", "+w/b" )
  3619.   ENDIF
  3620.  
  3621.   **  ONLY FOR ARRAYs:  Each element may (optionally)
  3622.           be prefixed with
  3623.   **   "@L" to left justify, "@R" to right justify or
  3624.           "@C" to center that
  3625.   **   element inside the box.  If not used the
  3626.           default is "@L".
  3627.  
  3628.   MsgBox( {"An ARRAY message", ;
  3629.           "for the MsgBox() function to", ;
  3630.           "Display", ;
  3631.           "@CI'm Centered !", ;
  3632.           "@RRight Justified" })
  3633.  
  3634.                                           Page: 106
  3635. NET_USE()
  3636.  
  3637. Syntax:
  3638.   net_use(<expC1>,<expL>,<expN>,<expC2>[,<expC3>])
  3639.  
  3640. Pass:
  3641.   <expC1> database alias name
  3642.   <expL>  .T. for exclusive open, .F. for shared
  3643.   <expN>  error timeout seconds if cannot be opened
  3644.   <expC2> alias to use when file is opened
  3645.   <expC3> RDD driver name.
  3646.  
  3647. Returns:
  3648.   a logical expression.
  3649.  
  3650. Description:
  3651.   Opens the database <expC1> in exclusive mode if <expL>
  3652.        is true or non-exclusive if <expL> is false.  If
  3653.        <expN> is greater than zero in a network environment
  3654.        and the database cannot be opened in <expN> seconds
  3655.        a timeout error will be displayed.  <expC2> is the
  3656.        alias that will be used.  If <expC3> is passed, that
  3657.        RDD driver will be used.
  3658.  
  3659. Comment:
  3660.   It is suggested that you use the OPEN_FIL function
  3661.        instead of the NET_USE() function, as it automati
  3662.        cally handles error conditions and parameter passing
  3663.        is more convenient.
  3664.                                           Page: 107
  3665. NOT_REQ()
  3666.  
  3667. Syntax:
  3668.   not_req(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>])
  3669.  
  3670. Pass:
  3671.   <expC1> -     Error message if field is not blank.
  3672.   <expN1> -     Screen row coordinate to display error
  3673.           message.
  3674.   <expN2> -     Screen column coordinate to display error
  3675.           message.
  3676.   <expN3> -     Rightmost screen column to display error
  3677.           message.
  3678.   <expC2> -     Color to display error message.  Default is
  3679.           WERR_CLR.
  3680.  
  3681. Returns:
  3682.   A logical value.
  3683.  
  3684. Description:
  3685.   There are times when you may want to force a user to
  3686.        enter an @...GET as a blank.  The NOT_REQ() valid
  3687.        function is used in these (rare) cases.  Usually
  3688.        conditionally executed.
  3689.  
  3690. Sample:
  3691.   In the following sample @...GETs the user is required
  3692.        to enter a state code and a country name.  If the
  3693.        state code is a validU.S. state then the country
  3694.        name must be blank otherwise the country name field
  3695.        is required.
  3696.  
  3697.   Program this using BUILDER valids as follows:
  3698.  
  3699.   ** Force a valid U.S. State or Canadian Province or
  3700.           blank
  3701.   **
  3702.   @ 07, 17 WINGET cState PICTURE "!!" VALID ;
  3703.           GenVld( In_USA( cState ) .OR. In_Canada(
  3704.           cState ), ;
  3705.           "ERROR: Not a Valid State or Province",
  3706.           WinBott() - 1, WinLeft() + 2, WinRight() - 2,
  3707.           .F. )
  3708.  
  3709.   ** if the state code is valid U.S. state then the
  3710.           country name
  3711.   ** must be blank, otherwise the country name is
  3712.           required.
  3713.   @ 08, 17 WINGET cCountry VALID ;
  3714.           IF( In_USA( cState ), ;
  3715.  
  3716. Page: 108
  3717.  
  3718.                 Not_Req( "Leave Country Blank", WinBott() - 1,
  3719.           WinLeft() + 2, WinRight() - 2), ;
  3720.                 Req( "Country Name is Required", WinBott() -
  3721.           1, WinLeft() + 2, WinRight() - 2 ) )
  3722.                                           Page: 109
  3723. NUMERIC()
  3724.  
  3725. Syntax:
  3726.   numeric(<expC>)
  3727.  
  3728. Pass:
  3729.   <expC> a string that may or may not contain all
  3730.        numerics
  3731.  
  3732. Returns:
  3733.   a logical expression.
  3734.  
  3735. Description:
  3736.   This function scans every character in <expC> and if
  3737.        every character is between '0' and '9' then it
  3738.        returns true, otherwise false is returned.
  3739.                                           Page: 110
  3740. OPEN_FIL()
  3741.  
  3742. Syntax:
  3743.  
  3744.        open_fil(<expC1>[,<expL1>][,<expC2>][,<expC3>][,<exp
  3745.        L2>])
  3746.  
  3747. Returns:
  3748.   a logical expression.
  3749.  
  3750. Pass:
  3751.   <expC1> database name to open.
  3752.   <expL1>       .T. for shared open, nothing or .F. for
  3753.           exclusive open.  Default
  3754.           value is .F.
  3755.   <expC2> alias name when open, if other than database
  3756.           name.  Default is the database name.
  3757.   <expC3> RDD driver name.  Default is the default RDD.
  3758.   <expL2> .T. to exit to DOS on open errors, .F. to
  3759.           return false on open errors.  Default is .T.
  3760.  
  3761. Description:
  3762.   The OPEN_FIL function will attempt to open the file
  3763.        <expC1> in exclusive mode-even if SET EXCLUSIVE OFF
  3764.        is in effect-unless the second parameter is sent as
  3765.        true.  Use the third parameter to set the alias if
  3766.        you want the alias other than the default of
  3767.        <expC1>.  <expL2> determines how the OPEN_FIL
  3768.        function will react when it cannot open a .DBF file,
  3769.        passing .T. (or not passing this parameter) will
  3770.        cause OPEN_FIL to exit to DOS on error conditions.
  3771.        Passing <expL2> as .F. will cause OPEN_FIL to return
  3772.        a logical false if it fails to open the file.
  3773.  
  3774.   The OPEN_FIL function tests for three (3) error
  3775.        conditions.  If an error is detected, an error box
  3776.        is displayed and OPEN_FIL either exits to DOS or
  3777.        returns false to the application depending on the
  3778.        value of <expL2>.  The errors tested for are as
  3779.        follows:
  3780.  
  3781.   If <expC3> is passed, that RDD driver will be used for
  3782.        the database being opened.
  3783.  
  3784.   1.  Invalid Alias Name.  If no specific alias name is
  3785.        sent to the OPEN_FIL function the file name
  3786.        (<expC1>) is used.  A valid alias name must contain
  3787.        the letter 'A' through 'Z' in the first character
  3788.        position.  The second through tenth character
  3789.        positions can contain 'A' through 'Z', '0' through
  3790.  
  3791.                                      Page: 111
  3792.  
  3793.  '9' or '_'.
  3794.  
  3795.   2.  File not found.  Before a database is USEd OPEN_FIL
  3796.        tests the Clipper FILE() function to determine if
  3797.        the file exists.
  3798.  
  3799.   3.  Already in Use.  The database is already USEd in
  3800.        EXCLUSIVE mode or the file has been locked.
  3801.  
  3802.   Note that the Open_Fil() function is obsolete with
  3803.        Clipper version 5.0 and above.  The extra error
  3804.        trapping that is done in Open_Fil() is also done in
  3805.        the Clipper 5.x error system.
  3806.                                           Page: 112
  3807. PCKVLD()
  3808.  
  3809. Syntax:
  3810.   pckvld(<expC1>,<expN1>,<expN2>,<expL1>,<expC2>,<expL2>
  3811.        ;
  3812.        [,<expC3>][,<expC4>])
  3813.  
  3814. Pass:
  3815.   <expC1> -     File alias name for picklist.
  3816.   <expN1> -     Field ordinal number in database to place
  3817.           in GET field on pick list selection.
  3818.   <expN2> -     Index order number to use with <expC1> to
  3819.           find the GET input data.
  3820.   <expL1> -     .T. = Use QWERTY scroll.  .F. = Do not use
  3821.           QWERTY scroll.
  3822.   <expC2> -     Display expression for picklist.
  3823.   <expL2> -     .T. = Required, do not accept blank for GET
  3824.           input, .F. = blank ok.
  3825.   <expC3> -     Key value SEEK prefix.  Default nothing.
  3826.   <expC4> -     STAY AT field name for a bounded by
  3827.           picklist.  Default is no bounded by field.
  3828.  
  3829. Returns:
  3830.   A logical expression.
  3831.  
  3832. Description:
  3833.   The PCKVLD() function can only be used in the VALID of
  3834.        a GET.  PCKVLD() will SEEK on the <expC1> database
  3835.        using index order <expN2> and if value of
  3836.        FIELD(<expN1>) is equal to the value entered into
  3837.        the GET the cursor will move to the next field in
  3838.        the GET stream.  If there is not an exact match a
  3839.        pick list is given to the user with the highlight
  3840.        bar positioned to the nearest record to the GET
  3841.        input.  The user may then move to the desired
  3842.        record, and press ENTER to put that data into the
  3843.        GET field and move to the next field in the GET
  3844.        stream.
  3845.  
  3846.   See PLIST().
  3847.  
  3848. Sample:
  3849.   You are building an order entry system and one of the
  3850.        fields on the order is 'Sales Person'.  This field
  3851.        is a three character field of the persons initials.
  3852.        You want to verify that what is entered into this
  3853.        field is a valid employee, but also that the
  3854.        employee is a sales person.  PCKVLD() can be used to
  3855.        do this in the following manner.
  3856.  
  3857.                                      Page: 113
  3858.  
  3859.   Technical assumptions:
  3860.        Employee file is called "EMPLYEE".
  3861.  
  3862.        The field EMPLYEE->TYPE is a one byte character
  3863.        field indicating the
  3864.        department the employee works in.
  3865.  
  3866.        That EMPLYEE->TYPE="S" is the sales department.
  3867.  
  3868.        The field EMPLYEE->INITIALS is a three byte
  3869.        character field of the
  3870.        employees initials.
  3871.  
  3872.        Index order number one has the index key
  3873.        TYPE+INITIALS on the
  3874.        EMPLYEE file.
  3875.  
  3876.        The field EMPLYEE->INITIALS is the second field in
  3877.        the database.
  3878.  
  3879.  
  3880.           ** The following PCKVLD() will not allow
  3881.           QINV_SLSMAN to be
  3882.           ** blank. Will only allow entry if these
  3883.           Clipper program statements ...
  3884.           **
  3885.           ** SELECT EMPLYEE
  3886.           ** SET ORDER TO 1
  3887.           ** SEEK "S"+QINV_SLSMAN
  3888.           **
  3889.           ** ... set FOUND() to .T.
  3890.           **
  3891.           ** If the entry is not FOUND() then a pick
  3892.           list is presented displaying
  3893.           ** the initials, first, and last name.  The
  3894.           picklist will only display
  3895.           ** EMPLYEE->TYPE="S" records because of the
  3896.           index key
  3897.           ** expression, the key prefix passed, and the
  3898.           bounded by being set.
  3899.           **
  3900.           @ 11,23 WINGET cInv_Slsman PICTURE "!!!" VALID
  3901.           ;
  3902.                 PckVld( "EMPLYEE", 2, 1, .F., ;
  3903.                 'initials " "+fname+" "+lname', .T., "S",
  3904.           "TYPE" )
  3905.  
  3906.   The PCKVLD() function is easier to digest if you
  3907.        understand the PLIST() function.  The source code to
  3908.  
  3909.                                      Page: 114
  3910.  
  3911.  call this function can be automatically generated by
  3912. BUILDER.
  3913.                                           Page: 115
  3914. PLIST()
  3915.  
  3916. Syntax:
  3917.  
  3918.        plist(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expN5
  3919.        >,<expC2> ;
  3920.   [,<expL1>][,<expC3>][,<expC4>][,<expB1>][,<expB2>] ;
  3921.   [,<expL2>][,<expL3>][,<expC5>]
  3922.  
  3923. Pass:
  3924.   <expN1> top row for picklist box.
  3925.   <expN2> left column for picklist box.
  3926.   <expN3> bottom row for picklist box.
  3927.   <expN4> right column for picklist box.
  3928.   <expC1> database alias name.
  3929.   <expN5> index order number to use for picklist.
  3930.   <expC2> expression to display on each picklist line.
  3931.   <expL1> enable QWERTY scroll function, default false.
  3932.   <expC3> memvar for QWERTY scroll initialization
  3933.           (prefix with @) default none.
  3934.   <expC4> color for pointer bar, default is WREV_CLR.
  3935.   <expB1> execute on ENTER key.  Default, nothing.
  3936.   <expB2> condition expression for bounded picklist.
  3937.           Default, no bounds.
  3938.   <expL2> PLIST() to display message line?  Default is
  3939.           .T.
  3940.   <expL3> PLIST() to display border?  Default is .T.
  3941.   <expC5> Seek prefix when QWERTY scroll is used.
  3942.           Default nothing.
  3943.  
  3944. Returns:
  3945.   A numeric expression.  The record number selected.
  3946.  
  3947. Description:
  3948.   The PLIST() function creates a scrollable pick list box
  3949.        to be presented on the screen.  This function is a
  3950.        replacement for the POP() function of BUILDER ver
  3951.        1.0.
  3952.  
  3953.   <expN1> and <expN2> are the row and column of the upper
  3954.        left corner of the pick list box.
  3955.  
  3956.   <expN3> and <expN4> are the height and width of the box
  3957.        respectively
  3958.  
  3959.   <expC1> is the database alias to 'browse'.
  3960.  
  3961.   <expN5> is the index order number to use when this
  3962.        picklist is being viewed.
  3963.  
  3964.  
  3965.                                      Page: 116
  3966.  
  3967.   When <expC2> is evaluated as a macro it is displayed on
  3968.        each line in the box.
  3969.  
  3970.   If <expL1> is passed as true then a field delimited
  3971.        with square brackets will be placed on the top of
  3972.        the box.  Any QWERTY text entered will be displayed
  3973.        between the brackets and that text will be used as a
  3974.        SEEK key and the PLIST() box will be refilled using
  3975.        that value.  If <expC5> was passed the SEEK value
  3976.        will be <expC5> + QWERTY value before refilling the
  3977.        PLIST() box.
  3978.  
  3979.   <expC3> is used in conjunction with <expL1> and
  3980.        contains the name of the memory variable that
  3981.        contains the starting key value to be placed between
  3982.        the square brackets.  If you choose to set <expL1>
  3983.        to true and not use this argument the QWERTY area
  3984.        will be sized according to the length of the
  3985.        INDEXKEY(0) function.
  3986.  
  3987.   <expC4> is an optional color for the pointer bar.
  3988.  
  3989.   <expB1> is an optional (strongly recommended) code
  3990.        block to be executed on selection of an element.
  3991.  
  3992.   <expB2> is an optional code block that returns a
  3993.        logical expression that will restrict scrolling only
  3994.        while the expression returns true (.T.).  This
  3995.        expression must return true (.T.) when PLIST() is
  3996.        initially called.
  3997.  
  3998.   Warning:  if you use <expB2> to set database bounds AND
  3999.        <expL1> is set to true, you will need to also use
  4000.        <expC5> (SEEK prefix)!
  4001.  
  4002.   Use <expL2> and <expL3> to optionally turn off some
  4003.        PLIST() default display items.  Both <expL2> and
  4004.        <expL3> default to true (.T.).  Pass false (.F.) in
  4005.        <expL2> and PLIST() will not display it's default
  4006.        message line.  Pass false (.F.) in <expL3> and
  4007.        PLIST() will not display a window border around the
  4008.        PLIST() data.
  4009.  
  4010. Sample 1:
  4011.  
  4012.           **********************************************
  4013.           *******
  4014.   * This example displays a pick list box at row 2
  4015.           column 40, it is 9 rows tall
  4016.  
  4017. Page: 117
  4018.  
  4019.   * and 23 columns wide.  It displays the field
  4020. COUNTRY from the database
  4021.   * INTRNTNL and provides the user a field to enter
  4022.           QWERTY text to move
  4023.   * to different parts of the database.  If a record
  4024.           is selected the function
  4025.   * INTL_DTL is executed.
  4026.  
  4027.   SELECT Intrntnl
  4028.   Intrntnl->( DBGOTOP() )
  4029.  
  4030.   ** display international
  4031.   **
  4032.   cKeyField  := Space( 20 )
  4033.  
  4034.   nRecord := Plist( 02, 40, 9, 23, "INTRNTNL", 1,
  4035.           "country", .T., ;
  4036.           @cKeyField,, {|| intl_dtl() })
  4037.  
  4038. Sample2:
  4039.  
  4040.           **********************************************
  4041.           *******
  4042.   * This example displays a pick list box at row 2
  4043.           column 19, it is 9 rows tall
  4044.   * and 20 columns wide.  It displays the fields
  4045.           PART_NBR and
  4046.   * PART_END from the database MSPART.
  4047.   * If a record is selected the function MS_DETAIL is
  4048.           executed.
  4049.  
  4050.   SELECT MsPart
  4051.   MsPart->( DBGOTOP() )
  4052.  
  4053.   ** display part list
  4054.   **
  4055.   cDisplay := 'part_nbr+"-"+part_end'
  4056.  
  4057.   nRecord := Plist( 02, 19, 11, 39, "MSPART", 1,
  4058.           cDisplay, .T.,,,, ;
  4059.   {|| ms_detail() })
  4060.  
  4061. Sample 3:
  4062.  
  4063.           **********************************************
  4064.           ***************
  4065.   ** This example will display a picklist box on the
  4066.           screen and combine both
  4067.   ** the Bounded by AND the QWERTY scroll features.
  4068.  
  4069. Page: 118
  4070.  
  4071. The last parameter
  4072.   ** passed allows this, however, careful consider
  4073.           ation must also be given to
  4074.   ** the index and database being used.
  4075.   **
  4076.   ** We will browse the database PARTS which is a very
  4077.           large database with
  4078.   ** part numbers and names we want to display.  This
  4079.           database also has a
  4080.   ** code to indicate what type of part the record
  4081.           contains.  There are three
  4082.   ** part type codes "P"-Plumbing, "H"-Heating, and
  4083.           "E"-Electrical.
  4084.   **
  4085.   ** Before reaching this point in the program the
  4086.           user has already selected
  4087.   ** the part type to be viewed.  So the picklist
  4088.           should be bounded by the
  4089.   ** PART_TYP field.  The only part type to be
  4090.           displayed in this pick list is
  4091.   ** indicated in the memvar cPartType which is equal
  4092.           to "P", "H", or "E" before
  4093.   ** this area of the program is executed.
  4094.   **
  4095.   ** Since there are so many parts of each type, we
  4096.           will also provide a
  4097.   ** QWERTY scroll field to allow faster locating.
  4098.   **
  4099.   ** Index order one has the index key expression of:
  4100.   **      PART_TYP+PART_NBR
  4101.   **
  4102.   **      PART_TYP is Character 1 byte long
  4103.   **      PART_NBR is Character 12 bytes long
  4104.   **
  4105.   ** If a part number is selected, proceed to the
  4106.           order entry screen, procedure
  4107.   ** ORD_ENTRY
  4108.  
  4109.   cPartType := Parts->Part_Typ
  4110.   bCondition := {| |cPART_TYP==BPART_TYP}
  4111.  
  4112.   cKeyField:= Space( 12 ) // length of part number for
  4113.           qwerty
  4114.                           // scroll default would be length of
  4115.                           // index expression, in this case 13.
  4116.  
  4117.   ** set up the display expression
  4118.   cDisplay := 'TRANSFORM( Part_Nbr, "@R 99-999999-999-
  4119.           !" ) + " " + Desc'
  4120.  
  4121. Page: 119
  4122.  
  4123.   ** display the picklist
  4124.   Plist( 02, 01, 14, 66, "PARTS", 1, cDisplay, .T.,
  4125.           @cKeyField,, {|| Ord_Entry() }, ;
  4126.           bCondition, .T., .T., cPartType )
  4127.  
  4128.  
  4129.   ** Parms 1-4 set the screen coordinates.
  4130.   ** Parms 5 and 6 are the database alias name and
  4131.           index order used during
  4132.   ** picklist operation.
  4133.   ** Parm 7 (cDisplay) is the display expression
  4134.           defined above.
  4135.   ** Parm 8 (.T.) turns on the QWERTY scroll feature.
  4136.   ** Parm 9 (@cKeyField) passes the QWERTY scroll
  4137.           initialization value.  This could
  4138.   ** also have been initialized like:
  4139.   **            cKeyField := Parts->Part_Nbr
  4140.   ** to put something IN the picklist entry field.
  4141.   ** Parm 10, nothing, use the default color for the
  4142.           highlight bar.
  4143.   ** Parm 11 ({|| Ord_Entry() }) the funciton named
  4144.           ORD_ENTRY will get
  4145.   ** executed after the ENTER key is pressed.  i.e. a
  4146.           part is selected.
  4147.   ** Parm 12 (bCondition) passes the Bounds condition
  4148.           variable.
  4149.   ** This memvar is set above and if Eval'd returns
  4150.           true, all contigious
  4151.   ** records where this returns false will not be
  4152.           visible in this picklist.
  4153.   ** Parms 13 and 14 tell PLIST() to display a window
  4154.           border and a default
  4155.   ** message line.
  4156.   ** Parm 15 (cPartType) Required for Bounded QWERTY
  4157.           picklists.  When a
  4158.   ** QWERTY key is pressed, the SEEK will be on
  4159.           cPartType + {Current-
  4160.   ** QWERTY-Text}.
  4161.                                           Page: 120
  4162. PUTKEY()
  4163.  
  4164. Syntax:
  4165.   Putkey( <expN> )
  4166.  
  4167. Pass:
  4168.   <expN>  A keyboard scan code to place in the keyboard
  4169.        buffer
  4170.  
  4171. Returns:
  4172.   A logical value.  True if the key was successfully
  4173.        placed in the keyboard buffer, false if the keyboard
  4174.        buffer was full.
  4175.  
  4176. Description:
  4177.   Many keys cannot be placed in the keyboard buffer using
  4178.        the Clipper KEYBOARD command.  Specifically any key
  4179.        with an INKEY() value greater than 255 will not
  4180.        work.  The Builder PUTKEY() function will work on
  4181.        any key, simply use the table from the TIMEOUT()
  4182.        function in this manual for the complete list when
  4183.        needed.
  4184.  
  4185. Sample:
  4186.      // Place the key Shift - TAB in the keyboard buffer
  4187.      // Note that it cannot be done using the KEYBOARD
  4188.      // command.
  4189.      Putkey( Hex2Dec( "0F00" ) )
  4190.                                           Page: 121
  4191. READGETS()
  4192.  
  4193. Syntax:
  4194.   ReadGets( @<expA>[, <expL>][, <expN>] )
  4195.  
  4196. Pass:
  4197.   <expA>    a GetList array.
  4198.   <expL>    Set to .F. to preserve the GetList on
  4199.        exit.  Default .T.
  4200.   <expN>    GetList array to initially place the
  4201.        cursor.  Default one.
  4202.  
  4203. Description:
  4204.   The Builder ReadGets() function is a replacement for
  4205.        the Clipper READ command.  The advantage of the
  4206.        ReadGets() function is that it will turn on the
  4207.        cursor, change the cursor size according to the
  4208.        insert state, and turn the cursor off on exit.
  4209.                                           Page: 122
  4210. REC_LOCK()
  4211.  
  4212. Syntax:
  4213.   rec_lock(<expN>)
  4214.  
  4215. Pass:
  4216.   <expN> seconds before error timeout, pass zero to never
  4217.        timeout.
  4218.  
  4219. Returns:
  4220.   A logical expression.
  4221.  
  4222. Description:
  4223.   Attempts to lock the current record of the currently
  4224.        selected database for timeout period of <expN>
  4225.        seconds.  If the record cannot be locked after the
  4226.        timeout period an error box is presented to try
  4227.        again, if No is selected, a logical false is
  4228.        returned.  If <expN> is zero or not passed to the
  4229.        function, REC_LOCK() will wait indefinitely.
  4230.  
  4231. Comment:
  4232.   The SAVE_IT() function performs all record locking
  4233.        before any file I/O and you should not have to use
  4234.        this function.
  4235.  
  4236.   However...
  4237.   some shops require that a record is locked during
  4238.        editing and all the functions and procedures in
  4239.        BUILDER only lock a record immediately before any
  4240.        file I/O so you may need to use this function after
  4241.        all.
  4242.                                           Page: 123
  4243. REL_MAINT()
  4244.  
  4245. Syntax:
  4246.   REL_MAINT(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ;
  4247.  
  4248.        <expB1>,<expC2>,<expA>,<expN5>,<expN6>[,<expC3>][,<e
  4249.        xpB2>][,<expB3>])
  4250.  
  4251. Pass:
  4252.   <expN1> The upper left corner screen row where the
  4253.           Rel_Maint() is being
  4254.           displayed.
  4255.   <expN2> The upper left corner screen column where the
  4256.           Rel_Maint() is
  4257.           being displayed.
  4258.   <expN3> The lower right corner screen row where the
  4259.           Rel_Maint() is being displayed.
  4260.   <expN4> The lower right corner screen column where
  4261.           the Rel_Maint() is
  4262.           being displayed.
  4263.   <expC1> You must declare a function that contains the
  4264.           GETs for the
  4265.           maintenance the first three letters of which
  4266.           must be 'GET'.  Pass in <expC1> the characters
  4267.           you add to make the procedure unique.
  4268.   <expB1> The condition that relates the file to be
  4269.           edited, this must be a
  4270.           logical true when evaluated.  All contigous
  4271.           records where the condition remains true will
  4272.           be available for editing.
  4273.  
  4274.           Note: The SET RELATION TO ... command does NOT
  4275.           need to be in effect to use this function, the
  4276.           databases merely need to have a one to many
  4277.           relationship.
  4278.   <expC2> Database alias name to be edited.
  4279.   <expA>  Memory variable prefix character(s).
  4280.   <expN5> The 'delete index' order number, zero (0) if
  4281.           a 'delete index' is not used.
  4282.   <expC3> The first character of each menu pad to use.
  4283.           Default "ACD"
  4284.   <expB2> codeblock executed on file I/O and before
  4285.           exit.  Default none.
  4286.   <expB3> codeblock executed when Ctrl+Enter is
  4287.           pressed.  Default none.
  4288.  
  4289.   <expC3> and <expB2> work identically to the last two
  4290.        parameters passed to GEN_MAINT.  See the documenta
  4291.        tion on that function for more information on these
  4292.        parameters.
  4293.                                      Page: 124
  4294.  
  4295. Description:
  4296.   The REL_MAINT function is used to edit the 'many'
  4297.        records in the child database when a one-to-many
  4298.        database relationship exists.
  4299.  
  4300.   Rel_Maint() calls can easily be constructed by Builder.
  4301.        See the Rel_Maint() section in the Builder manual
  4302.        for more information on automatically creating
  4303.        Rel_Maint()'s.
  4304.  
  4305.   If you are unsure what a 'delete index' is refer to the
  4306.        GEN_MAINT function for clarification.
  4307.  
  4308.   Look carefully at the following sample to see how to
  4309.        set up a  REL_MAINT call.
  4310.  
  4311. Sample:
  4312.   **********************************************
  4313.   ** CALLED BY: Pick List Window Proc:  PLST003    **
  4314.   **   Comment: Model Maint Dialog                      **
  4315.   **********************************************
  4316.   PPRCEDURE Dlog004()
  4317.           LOCAL cPartNo
  4318.           LOCAL aRPartNo
  4319.  
  4320.           ** save key to a memory variable
  4321.           ** important you code something like this!
  4322.           cPartNo := Model->PartNo
  4323.  
  4324.           SETCOLOR( Var( WNDW_CLR_ ) )
  4325.           @ 15, 45, 19, 77 WINDOW STYLE "3+"
  4326.  
  4327.           @ 02, 04 WINSAY "Model Number"
  4328.  
  4329.           ** call rel_maint to edit all contiguous
  4330.           records in the MODEL
  4331.           ** database with the field Model->PartNo equal
  4332.           to the memory
  4333.           ** variable cPartNo.
  4334.           SELECT RPartNo
  4335.           aRpartNo := ARRAY( FCOUNT() )
  4336.           cPartNo := Model->PartNo
  4337.  
  4338.           RPartNo->( DBSETORDER( 1 ) )
  4339.           RPartNo->( DBSEEK( Model->PartNo ) )
  4340.  
  4341.           Rel_Maint( ;
  4342.                WinTop(), WinLeft(), WinBott(),
  4343.           WinRight(), "004", {||Model->PartNo =
  4344.  
  4345. Page: 125
  4346.  
  4347.           cPartNo};
  4348.                 "MODEL", aRpartNo, 2 )
  4349.  
  4350.  
  4351.           WINDOW REMOVE
  4352.  
  4353.  
  4354.   ** this func created by moving the GETs created by
  4355.           BUILDER to a proc
  4356.   ** with the first three characters equal to "GET", I
  4357.           arbitrarily chose "004"
  4358.   ** as the second part of the name (because it
  4359.           matches DLOG004)
  4360.   ** and pass "004" as the fifth parameter above.
  4361.   FUNCTION Get004( cG_Func )
  4362.           LOCAL GetList := {}
  4363.  
  4364.           ** absolutely IMPERATIVE the key variables get
  4365.           set from
  4366.           ** previously saved memory variables here!!
  4367.           aRpartNo[1] := Model->RPartNo
  4368.  
  4369.           @ 02,18 WINGET aRpartNo[2] PICTURE "@!"
  4370.  
  4371.           IF cG_Func $ "AC"
  4372.                 ReadGets( @GetList )
  4373.           ENDIF
  4374.  
  4375.  
  4376.   Not including the comments only four lines of code were
  4377.        added to a BUILDER dialog box to create this (many
  4378.        more were deleted).
  4379.  
  4380.   This is a small example, but should clearly show how to
  4381.        set up a REL_MAINT of your own.
  4382.                                           Page: 126
  4383. REQ()
  4384.  
  4385. Syntax:
  4386.   req(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>])
  4387.  
  4388. Pass:
  4389.   <expC1> -     Error message if field is blank.
  4390.   <expN1> -     Screen row coordinate to display error
  4391.           message.
  4392.   <expN2> -     Screen column coordinate to display error
  4393.           message.
  4394.   <expN3> -     Rightmost screen column to display error
  4395.           message.
  4396.   <expC2> -     Color to display error message.  Default is
  4397.           WERR_CLR.
  4398.  
  4399. Returns:
  4400.   A logical value.
  4401.  
  4402. Description:
  4403.   This VALID function forces entry of an @...GET field to
  4404.        be non-blank.  It simply checks if the GET value is
  4405.        EMPTY() and only allows the cursor past the GET is
  4406.        it is not EMPTY().
  4407.  
  4408. Sample:
  4409.   In this example the system you are building has a date
  4410.        field on a screen and the field must be entered, it
  4411.        cannot be blank.  That is all the validation that
  4412.        can be performed. The following REQ() function will
  4413.        accomplish this.
  4414.  
  4415.   @ 05,11 WINGET dTestDate VALID ;
  4416.           Req( "A Date is Required", WinBott()-1,
  4417.           WinLeft()+2,WinRight()-2)
  4418.                                           Page: 127
  4419. RGHT_JST()
  4420.  
  4421. Syntax:
  4422.   rght_jst([<expC>])
  4423.  
  4424. Returns:
  4425.   A logical true (.T.)
  4426.  
  4427. Pass:
  4428.   <expC> - Fill character after field is right justified.
  4429.        Default space.
  4430.  
  4431. Description:
  4432.   The RGHT_JST() VALID function will right justify and
  4433.        fill a character field with <expC> or spaces if
  4434.        <expC> is not passed.
  4435.  
  4436. Sample:
  4437.   Suppose you have a field to be keyed by a user and for
  4438.        whatever reason it makes sense to make it a
  4439.        character field.  You also want to right justify and
  4440.        zero fill the field because the field will be used
  4441.        as the key value to look up something in another
  4442.        database.  Use the RGHT_JST() function to accomplish
  4443.        this in the following manner:
  4444.  
  4445.  
  4446.   cKeyVal := Space( 07 )
  4447.   @ 01,14 WINGET cKeyVal PICTURE "9999999" VALID ;
  4448.        Rght_jJt( "0" )
  4449.  
  4450.   If the user keys one (1) and then presses ENTER then
  4451.        cKeyVal will equal "0000001".  If twenty-one (21) is
  4452.        entered then cKeyVal will equal "0000021"
  4453.  
  4454.   The field will be right justified.
  4455.                                           Page: 128
  4456. SAVE_IT()
  4457.  
  4458. Syntax:
  4459.   save_it(<expC1>,<expA>,<expN>,<expC2>)
  4460.  
  4461. Pass:
  4462.   <expC1> "ADD", "CHG", "DEL", or "RCL" only.
  4463.   <expA>  name of array containing database field data
  4464.   <expN>  fast delete index order number
  4465.   <expC2> database alias name
  4466.  
  4467. Returns:
  4468.   A logical expression.
  4469.  
  4470. Description:
  4471.   The SAVE_IT() function will add, change, delete, or
  4472.        recall the current record from the database <expC2>.
  4473.        The SAVE_IT() function uses record locking if the
  4474.        memory variable NETWORK is set to true.  The <expC1>
  4475.        argument must be equal to "ADD", "CHG", "DEL", or
  4476.        "RCL" to tell SAVE_IT() to add, change, delete, or
  4477.        recall a record.  <expA> is the array name which
  4478.        contains the data to be placed in the database
  4479.        fields with matching ordinal positions (See the
  4480.        DBSTOR function).  Use <expN> to pass the order
  4481.        number of the "fast delete" index created like:
  4482.  
  4483.   INDEX ON IF(DELE(),"*"," ") TO ...
  4484.  
  4485.   Send <expN> as zero (0) if you are not using a "fast
  4486.        delete".
  4487.  
  4488.   If the NETWORK memory variable is set to true and the
  4489.        SAVE_IT() function cannot lock the requested record
  4490.        and the user replies "No" to try the lock again,
  4491.        then the SAVE_IT() function will return false.
  4492.  
  4493. Sample:
  4494.  
  4495.           **********************************************
  4496.           ************
  4497.   *** SAVE_IT() function example
  4498.   ***
  4499.   LOCAL aCustomer := {}
  4500.  
  4501.   USE Customer NEW INDEX Cust1, Cust2
  4502.   aCustomer := ARRAY( FCOUNT() )
  4503.   DbStor( aCustomer, "EMPTY" )  // set original values
  4504.  
  4505.   ** cust1 indexed on cust_nbr
  4506.  
  4507. Page: 129
  4508.  
  4509.   ** cust2 indexed on if(dele(),"*"," ")
  4510.  
  4511.   .
  4512.   . program statements to
  4513.   . change array elements to values for new record
  4514.   .
  4515.  
  4516.  
  4517.   IF !Save_It( "ADD", aCustomer, 2, "CUSTOMER" )
  4518.           MsgBox( "ERROR_RECORD NOT ADDED !" )
  4519.           RETURN
  4520.   ENDIF
  4521.                                           Page: 130
  4522. SETMOUSE()
  4523.  
  4524. Syntax:
  4525.   SETMOUSE(<expN1>,<expN2>)
  4526.  
  4527. Pass:
  4528.   <expN1> -     Initialize or re-initialize mouse button
  4529.           status.
  4530.   <expN2> -     Decimal value of keyboard scan code to
  4531.           place in keyboard buffer on mouse button
  4532.           action.
  4533.  
  4534. Returns:
  4535.   A numeric integer in the range 0 - 4 inidicating the
  4536.        mouse button status.
  4537.  
  4538. Description:
  4539.   The SETMOUSE() function should be used to set and set
  4540.        remove the keyboard scan code only.  This function
  4541.        can most effectively be use in conjunction with the
  4542.        ADDMPAD() mouse 'hot pad' function.  The ADDMPAD()
  4543.        function will work without SETMOUSE() in most
  4544.        instances.  SETMOUSE() will be needed when adding
  4545.        mouse functionality to a 'closed' function.  A
  4546.        'closed' function is defined as one where access to
  4547.        the keyboard loop is not available.  Examples of
  4548.        'closed' functions are MEMOEDIT() and ACHOICE().
  4549.        Many third part libraries also have non-mouseable
  4550.        'closed' functions.  SETMOUSE() will allow mouse
  4551.        control of these functions.
  4552.  
  4553.   The SETMOUSE() returns the last mouse button action
  4554.        until either reset to zero (0) or another mouse
  4555.        button is press or released.
  4556.  
  4557.   0 - Nothing has happened yet.
  4558.   1 - The left mouse button is currently pressed.
  4559.   2 - The left mouse button was released.
  4560.   3 - The right mouse button is currently pressed.
  4561.   4 - The right mouse button was released.
  4562.  
  4563. Example:
  4564.  
  4565.   // Example of setting up an ACHOICE() with ability
  4566.           to use the mouse.
  4567.   // Pressing and holding the left mouse button on the
  4568.           top or bottom border
  4569.   // will move the highlight bar up and down just as
  4570.           if the up and down arrow
  4571.                 // keys were used.
  4572.  
  4573. Page: 131
  4574.  
  4575.  
  4576.   // Also, by releasing the left mouse button inside
  4577.           the ACHOICE() screen
  4578.   // area, the option with the mouse cursor on it will
  4579.           be selected.
  4580.  
  4581.   LOCAL aCars, nUpIdx, nDnIdx, nEnIdx, nSelect
  4582.  
  4583.   aCars :=      {"Bu
  4584.           ick","Chevrolet","Chrysler","Dodge","Nissan",
  4585.           ; "Toy
  4586.           ota","Mazda","Volkswagon","Volvo","Ferrari", ;
  4587.           "Lamborghini","Jaguar"}
  4588.  
  4589.   // Set up mouse 'hot pads'
  4590.   nUpIdx :=
  4591.           AddMPad(10,10,10,23,1,{||__KeyBoard(K_UP)})
  4592.   nDnIdx :=
  4593.           AddMPad(16,10,16,23,1,{||__KeyBoard(K_DOWN)})
  4594.   nEnIdx := AddMPad(11,11,15,22,0,{||MouseEnter()})
  4595.  
  4596.   // This will activate mouse checking during
  4597.           ACHOICE()
  4598.   // Note that 4A00 Hex is the Numeric Keypad Alt
  4599.           Minus key, whenever
  4600.   // that key is used, all the mouse 'hot pads' are
  4601.           checked.
  4602.   SetMouse( 0, Hex2Dec( "4A00" ) )
  4603.  
  4604.   WinPush(10,10,16,23)
  4605.   @ 10, 10, 16, 23 WINDOW STYLE "3+"
  4606.  
  4607.   nSelect := Achoice( 11, 11, 15, 22, aCars )
  4608.  
  4609.   IF nSelect > 0
  4610.           MsgBox(aCars[nSelect]+" Was Selected")
  4611.   ENDIF
  4612.   // Be sure to turn it off when not in use.
  4613.   SetMouse( 0, 0 )
  4614.   DelMPad( nUpIdx )
  4615.   DelMPad( nDnIdx )
  4616.   DelMPad( nEnIdx )
  4617.  
  4618.   WINDOW REMOVE
  4619.  
  4620.   // This function executed whenever the left mouse
  4621.           button is
  4622.   // released inside the ACHOICE() area
  4623.   //
  4624.  
  4625. Page: 132
  4626.  
  4627.   FUNCTION MouseEnter()
  4628.           LOCAL nMouseRow, nMouseCol, nKey
  4629.  
  4630.           AbMGetRowCol( @nMouseRow, @nMouseCol )   // get
  4631.           mouse cursor position
  4632.  
  4633.           IF nMouseRow < Row()                     // Row() is current
  4634.           highlight bar row
  4635.                 nKey := K_UP
  4636.           ELSE
  4637.                 nKey := K_DOWN
  4638.           ENDIF
  4639.  
  4640.           KEYBOARD Replicate( Chr( nKey ), Abs(
  4641.           nMouseRow - Row() ) ) + ;
  4642.           Chr( K_ENTER )
  4643.           RETURN( NIL )
  4644.                                           Page: 133
  4645. SETMSGLIN()
  4646.  
  4647. Syntax:
  4648.   setmsglin([<expC>] | [<expN>])
  4649.  
  4650. Pass:
  4651.   Either a character expression or a numeric expression
  4652.        only.
  4653.  
  4654. Returns:
  4655.   The text on the screen line set as the message line.
  4656.  
  4657. Description:
  4658.   The SETMSGLIN() function returns the screen text on the
  4659.        message line.  If <expC> is passed then <expC> is
  4660.        displayed on the message line using the value of
  4661.        Var(MSG_CLR_ ) as the color value.
  4662.  
  4663.   The message line defaults to screen line 24.  Pass a
  4664.        numeric value to change the message line to another
  4665.        screen line.  If the message line is set to a value
  4666.        that is not between zero (0) and MAXROW() then
  4667.        character expressions subsequently sent to this
  4668.        function will not display.
  4669.  
  4670.   SetMsgLin() will return a character value of the
  4671.        contents of the message line.
  4672.  
  4673. Example:
  4674.   LOCAL cMsgLin
  4675.  
  4676.   SetMsgLin( 23 )  // Change the message line to
  4677.           screen row 23
  4678.  
  4679.   // save what's on line 23 and display a message
  4680.           there
  4681.   cMsgLin := SetMsgLin( "Display this on line 23!" )
  4682.  
  4683.   // redisplay the previous message on line 23
  4684.   SetMsgLin( cMsgLin )
  4685.  
  4686.   // Turn the message line off
  4687.   SetMsgLin( -1 )
  4688.  
  4689.   SetMsgLin( "This Won't Display" )
  4690.                                           Page: 134
  4691. SHADOW()
  4692.  
  4693. Syntax:
  4694.   shadow(<expN1>,<expN2>,<expN3>,<expN4>)
  4695.  
  4696. Pass:
  4697.   <expN1> top left row
  4698.   <expN2> top left column
  4699.   <expN3> bottom right row
  4700.   <expN4> bottom right column
  4701.  
  4702. Description:
  4703.   Places a shadow on the area bounded by the four passed
  4704.        coordinates, where <expN1> and <expN2> are the upper
  4705.        left row and column coordinates and <expN3> and
  4706.        <expN4> are the lower right.
  4707.  
  4708. Comment:
  4709.   The BUILDER WinPush() function uses this function to
  4710.        place a shadow on windows it creates.  You,
  4711.        therefore, should not have to use this function.
  4712.                                           Page: 135
  4713. SHOW_MEMO()
  4714.  
  4715. Syntax:
  4716.   show_memo(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ;
  4717.           <expL1>[,<expC2>][,<expN5>][,<expL2>])
  4718.  
  4719. Pass:
  4720.   <expN1> -     Top row screen coordinate.
  4721.   <expN2> -     Left column screen coordinate.
  4722.   <expN3> -     Bottom row screen coordinate.
  4723.   <expN4> -     Right column screen coordinate.
  4724.   <expC1> -     Memo field database field name.
  4725.   <expL1> -     .F. view only, .T. allow editing.
  4726.   <expC2> -     Color for memo data.
  4727.   <expN5> -     Maximum lines memo may contain.  Default
  4728.           unlimited.
  4729.   <expL2> -     .F. does nothing, .T. starts editing at the
  4730.           end of the memo text.  Default .F.
  4731.  
  4732. Description:
  4733.   The SHOW_MEMO function calls the Clipper MEMOEDIT()
  4734.        function and provides a few small additional
  4735.        functions.  It does not put a border or title on the
  4736.        screen.  This function is called by the EDT_MEMO()
  4737.        function.  If you want to use your own screen border
  4738.        and message line use this instead of EDT_MEMO().
  4739.  
  4740.   The additional functionality is provided by the last
  4741.        three parameters and are self explanatory.
  4742.  
  4743.   See EDT_MEMO(), MEMFUNC()
  4744.                                           Page: 136
  4745. SHOW_TXT()
  4746.  
  4747. Syntax:
  4748.   show_txt(<expC1>,<expN1>,<exp>,<expC2>,<expN2>,<expN3>,
  4749.        ;
  4750.           <expN4>[,<expC3>])
  4751.  
  4752. Pass:
  4753.   <expC1> -     Alias name of database for SEEK.
  4754.   <expN1> -     Index order number of <expC1> for SEEK.
  4755.   <exp>   -     Key expression for SEEK.
  4756.   <expC2> -     Screen display expression.
  4757.   <expN2> -     Screen row coordinate for display.
  4758.   <expN3> -     Screen column coordinate for display.
  4759.   <expN4> -     Rightmost screen column to display.
  4760.   <expC3> -     Alternate color choice for display, default
  4761.           is WMSG_CLR
  4762.  
  4763. Returns:
  4764.   A logical true (.T.).
  4765.  
  4766. Description:
  4767.   The SHOW_TXT() function is a very useful VALID function
  4768.        that simply puts text on the screen after a user
  4769.        moves past the field where the SHOW_TXT() VALID is
  4770.        located.
  4771.  
  4772. Sample:
  4773.   Suppose you have a database for customer purchases and
  4774.        one of the fields in this database is a Part Number.
  4775.        This represents the item your customer has
  4776.        purchased. When the Part Number is keyed you would
  4777.        like to display the Part Description that corre
  4778.        sponds to the Part Number. The SHOW_TXT() VALID
  4779.        function can do this in the following manner:
  4780.  
  4781.   Technical assumptions:
  4782.  
  4783.   The customer database is called CUSTOMER and contains a
  4784.        five byte character field called PART_NBR which
  4785.        contains the Part Number the customer purchased.
  4786.  
  4787.   The look up table database with the part descriptions
  4788.        is called PARTS and index order one (1) is on the
  4789.        PART_NBR field.
  4790.  
  4791.   The PARTS database part description field is called
  4792.        PART_DESC.
  4793.   .
  4794.   .
  4795.  
  4796. Page: 137
  4797.  
  4798.   .
  4799.  
  4800.   ** add the DBSEEK()/Message() to have the display of
  4801.           the
  4802.   ** Part Description on PgUp's and PgDn's
  4803.   **
  4804.   Parts->( DBSEEK( cPart_Nbr, .F. ) )
  4805.   Message( Parts->Part_Desc, WinTop()+10, WinLeft()+2,
  4806.           WinRight()-2, Var( WMSG_CLR_ ) )
  4807.   **
  4808.  
  4809.   @ 09,16 WINGET cPart_Nbr PICTURE "!!!!!" VALID ;
  4810.           Show_Txt( "PARTS", 1, cPart_Nbr, Parts-
  4811.           >Part_Desc, ;
  4812.                 WinTop()+10,WinLeft()+2,WinRight()-2)
  4813.   .
  4814.   .
  4815.                                           Page: 138
  4816. TEXTVIEW()
  4817.  
  4818. Syntax:
  4819.   textview(<expN1>,<expN2>,<expN3>,<expN4>,<expC1> ;
  4820.           [,<expL>][,<expC2>])
  4821.  
  4822. Pass:
  4823.   <expN1> -     Top row screen coordinate.
  4824.   <expN2> -     Left column screen coordinate.
  4825.   <expN3> -     Bottom row screen coordinate.
  4826.   <expN4> -     Right column screen coordinate.
  4827.   <expC1> -     Name of a CR/LF delimited text file,
  4828.           include the extension.
  4829.   <expL>  -     Print key enable/disable.  Pass .T. to
  4830.           enable or .F. to disable.  Default is
  4831.           disabled.
  4832.   <expC2> -     Name of a user defined function to program
  4833.           alternate keystrokes and use TEXTVIEW passed
  4834.           parameters.
  4835.  
  4836. Description:
  4837.   The TEXTVIEW function simply displays a CR/LF (carriage
  4838.        return/line feed) delimited text file within the
  4839.        passed screen coordinates, <expN1> through <expN4>.
  4840.        The advantage of this function over the MEMOEDIT()
  4841.        function provided by Clipper is that TEXTVIEW can
  4842.        view any size file whereas MEMOEDIT() is restricted
  4843.        to a maximum of 64K (If you can spare the memory!).
  4844.        TEXTVIEW does not read the whole file into memory,
  4845.        only the portion of the file currently displayed is
  4846.        in memory, so TEXTVIEW uses very little of the
  4847.        programs available memory.
  4848.  
  4849.   Passing <expC2> the programmer can customize TEXTVIEW
  4850.        by examining the parameters passed and writing
  4851.        custom routines for viewing text files.
  4852.  
  4853.   The parameters passed to the UDF are:
  4854.  
  4855.   <expN1> -     The leftmost column of the file currently
  4856.           being displayed.
  4857.   <expC>  -     The status of TEXTVIEW when the UDF was
  4858.           called:
  4859.           "BF" - Beginning of File.
  4860.           "EF" - End of File.
  4861.           "BP" - Beginning to Print.
  4862.           "EP" - End of Print.
  4863.   <expN2> - Length of the longest record in the
  4864.           current display window.
  4865.   <expN3> - INKEY() value of the last key pressed.
  4866.  
  4867. Page: 139
  4868.  
  4869.   <expN4> - The file handle of the text file being
  4870.           viewed.
  4871.  
  4872.   The return value from the UDF MUST be a logical value,
  4873.        if your function returns true (.T.) then the screen
  4874.        will be refreshed. If your function returns false
  4875.        (.F.) then the screen will not be changed.
  4876.  
  4877. Sample:
  4878.   A TEXTVIEW call with a UDF to display a report file.
  4879.  
  4880.   .
  4881.   .
  4882.   .
  4883.   SETCOLOR( Var( WNDW_CLR_ ) )
  4884.   @ 05, 05, 20, 75 WINDOW STYLE "3+"
  4885.   SetMsgLin( "²
  4886.           "+chr(27)+chr(26)+"/TAB/Shft+TAB/"+chr(24)+chr
  4887.           (25)+ ;
  4888.                 "/PgUp/PgDn/Home/End-Scroll ² Alt+P-Print ²
  4889.           ESC-Exit ²" )
  4890.  
  4891.   @ WinTop(), WinRight()-12 SAY Chr( 181 ) +
  4892.           "REPORT.TXT" + Chr( 198 )
  4893.   SETCOLOR( Var( WMSG_CLR_ ) )
  4894.   TextView( WinTop()+1, WinLeft()+1, WinBott()-1,
  4895.           WinRight()-1, "REPORT.TXT", .T., "TEXTFUNC" )
  4896.   SETCOLOR( Var( WNDW_CLR_ ) )
  4897.   WINDOW REMOVE
  4898.  
  4899.  
  4900.           **********************************************
  4901.           ***************
  4902.   ** Example function called by TEXTVIEW text file
  4903.           viewer with examples
  4904.   ** of how to use the passed parameters.
  4905.  
  4906.           **********************************************
  4907.           ***************
  4908.   FUNCTION TextFunc(  nLeft, cStatus, nMaxWidth, nKey,
  4909.           nHandle )
  4910.           LOCAL cOldColor
  4911.  
  4912.           **********************************************
  4913.           ***********
  4914.   ** nLeft           -    Leftmost column position in the current
  4915.           display window.
  4916.   ** cStatus    -    BF-Beginning of File; EF-End of File; BP-
  4917.           Begin of Print;
  4918.  
  4919. Page: 140
  4920.  
  4921.   **            EP-End of Print; or nul if no status to
  4922.           report.
  4923.  
  4924.   ** nWidth     -    Character width of the widest record in
  4925.           the current
  4926.   **            display window.
  4927.   ** nKey -     INKEY() value of the last key pressed.  Use
  4928.           nKey to
  4929.   **            program your own keystrokes during a TEXTVIEW.
  4930.   ** nHandle    -    File handle of file being viewed.
  4931.           **********************************************
  4932.           ***********
  4933.  
  4934.           ** check all status conditions and display
  4935.           result
  4936.           SETCOLOR( Var( WNDW_CLR_ ) )
  4937.           DO CASE
  4938.            CASE cStatus == "BF"
  4939.                 @ 0,1 WINSAY Chr( 181 ) + "TOP" + Chr(198)
  4940.           CASE cStatus == "EF"
  4941.                 @ 0, 1 WINSAY Chr( 181 ) + "BOT" + Chr(198)
  4942.           CASE cStatus == "BP"
  4943.                 cOldColor := SETCOLOR( )
  4944.                 SETCOLOR( "*" + cOldColor )
  4945.                 @ 0,2 WINSAY "PRT"
  4946.                 SETCOLOR(  cOldColor )
  4947.           CASE cStatus == "EP"
  4948.                 @ 0, 1 WINSAY Chr( 181 ) + "   " + Chr( 198 )
  4949.           OTHERWISE
  4950.                 @ 0, 1 WINSAY Chr( 181 ) + "   " + Chr( 198 )
  4951.           ENDCASE
  4952.  
  4953.           ** display left/right helper arrows if needed
  4954.           IF nLeft > 1
  4955.                 @ WinBott(), WinLeft() SAY Chr( 27 )
  4956.           ELSE
  4957.                 @ WinBott(), WinLeft() SAY Chr( 200 )
  4958.           ENDIF
  4959.  
  4960.           IF nLeft + ( WinRight() - WinLeft() ) - 2 <
  4961.           nWidth
  4962.                 @ WinBott(), WinRight() SAY Chr( 26 )
  4963.           ELSE
  4964.                 @ WinBott(), WinRight() SAY Chr( 188 )
  4965.           ENDIF
  4966.  
  4967.           SETCOLOR( Var( WMSG_CLR_ ) )
  4968.  
  4969.           ** Trap CTRL+HOME key and make it do the same
  4970.  
  4971. Page: 141
  4972.  
  4973.           thing as
  4974.           ** the HOME key.
  4975.           IF nKey = K_CTRL_HOME
  4976.                 FSeek( nHandle, 0, 0 )   // go to the beginning
  4977.           of the file
  4978.  
  4979.                 RETURN( .T. )                 // make TEXTVIEW redisplay window
  4980.           ENDIF
  4981.  
  4982.           RETURN (.F. )                       // no need to redisplay the
  4983.           window
  4984.                                           Page: 142
  4985. THERMOMETR()
  4986.  
  4987. Syntax:
  4988.   thermometr(<expN1>,<expN2>,<expN3>,<expN4>)
  4989.  
  4990. Pass:
  4991.   <expN1> thermometer length
  4992.   <expN2> start value of operation (i.e. 0%)
  4993.   <expN3> maximum value of operation (i.e. 100%)
  4994.   <expN4> current value, must be between <expN2> and
  4995.           <expN3>
  4996.  
  4997. Returns:
  4998.   A character expression.
  4999.  
  5000. Description:
  5001.   The THERMOMETR() function is used to display the
  5002.        progress of iterative program activity graphically.
  5003.        The <expN1> argument is the length you want your
  5004.        thermometer, <expN2> is the number of the starting
  5005.        position of your process, <expN3> is the ending
  5006.        position and <expN4> is the current position.
  5007.  
  5008. Sample:
  5009.  
  5010.           **********************************************
  5011.           **************
  5012.   ** THERMOMETR() function example
  5013.   **
  5014.  
  5015.   Trnsactn->( DBGOTOP() )
  5016.  
  5017.   nStart := 1
  5018.   nEnd := LASTREC()
  5019.   nWidth := 40
  5020.   cOldThm := " "     // old thermometer for comparison
  5021.  
  5022.   DO WHILE !EOF()
  5023.           cThm := Thermometr( nwidth, nStart, nEnd,
  5024.           RECNO() )
  5025.           IF cThm < > cOldThm  // only display changes
  5026.                 @ 1,0 SAY cThm
  5027.                 cOldThm := cThm
  5028.           ENDIF
  5029.  
  5030.           .
  5031.           .
  5032.           .
  5033.  
  5034.           Trnsactn->( DBSKIP() )
  5035.  
  5036. Page: 143
  5037.  
  5038.   ENDDO
  5039.                                           Page: 144
  5040. TIMEOUT()
  5041.  
  5042. Syntax:
  5043.   timeout(<expN1>,<expN2>)
  5044.  
  5045. Pass:
  5046.   <expN1> -     Computer idle time in seconds.
  5047.   <expN2> -     Keyboard scan code to put in keyboard
  5048.           buffer on a timeout condition.
  5049.  
  5050. Returns:
  5051.   "Y" if timeout occured or "N" if not a timeout.
  5052.  
  5053. Description:
  5054.   The TIMEOUT assembly subroutine tests the computer's
  5055.        keyboard,  disk(s), serial port, video interface,
  5056.        and printer port(s) for activity.  If no activity
  5057.        has occurred and one (1) second has passed, an
  5058.        internal variable is incremented.  If any activity
  5059.        whatsoever occurs on the computer the internal
  5060.        variable is set to zero.  If the subroutine's
  5061.        internal variable counter reaches the value passed
  5062.        as <expN1> then <expN2> is put in the keyboard
  5063.        buffer as if the key was pressed on the keyboard and
  5064.        any subsequent calls to TIMEOUT() will be returned a
  5065.        value of "Y".
  5066.  
  5067.   So if the computer is completely idle (i.e. NO ACTIVITY
  5068.        AT ALL) for <expN1> seconds then <expN2> is put in
  5069.        the keyboard buffer.
  5070.  
  5071.   WARNING * WARNING * WARNING * WARNING * WARNING
  5072.   TIMEOUT CANNOT (!) BE USED IN AN OVERLAY.  IT TAKES
  5073.        OVER SYSTEM  INTERRUPTS.  IF PUT IN AN OVERLAY, YOUR
  5074.        PROGRAM WILL (WILL !!) CRASH.
  5075.   WARNING * WARNING * WARNING * WARNING * WARNING
  5076.  
  5077.   It is up the Clipper program to be set up to deal with
  5078.        these conditions.  See the following example and
  5079.        also see the program source for DEMO.PRG included in
  5080.        the BUILDER Demo package.
  5081.  
  5082.   .
  5083.   .
  5084.   .
  5085.   SET KEY 259 TO TmOut_Xit     // Ctrl+2 INKEY() value
  5086.  
  5087.   ** Clipper program to time out after one hour (3600
  5088.           seconds)
  5089.   **
  5090.  
  5091. Page: 145
  5092.  
  5093.   ** Hex 0300 is the keyboard scan code for Ctrl+2
  5094.   **
  5095.   TimeOut( 3600, Hex2Dec( "0300" ) )
  5096.  
  5097.   .
  5098.   .
  5099.   .
  5100.   ** Proc executed on every press of Ctrl+2
  5101.   ** if cIDLE_VAR="Y" then the program timed out, so
  5102.           set errorlevel and exit.
  5103.   **
  5104.   PROCEDURE TmOut_Xit( cPrc, nLin, cVar )
  5105.  
  5106.           IF TimeOut() != "Y"
  5107.                 RETURN
  5108.           ENDIF
  5109.  
  5110.           SET CURSOR ON
  5111.           SET COLOR TO w/n
  5112.           ERRORLEVEL( 1 )
  5113.           CLS
  5114.           QUIT
  5115.  
  5116.   Use the following table to find keyboard scan codes:
  5117.  
  5118. TIMEOUT Keyboard Scan Codes
  5119.  
  5120.   Key  Normal    Shifted   w/Ctrl    w/Alt
  5121.  
  5122.   A    1E61 1E41 1E01 1E00
  5123.   B    3062 3042 3002 3000
  5124.   C    2E63 2E42 2E03 2E00
  5125.   D    2064 2044 2004 2000
  5126.   E    1265 1245 1205 1200
  5127.   F    2166 2146 2106 2100
  5128.   G    2267 2247 2207 2200
  5129.   H    2368 2348 2308 2300
  5130.   I    1769 1749 1709 1700
  5131.   J    246A 244A 240A 2400
  5132.   K    256B 254B 250B 2500
  5133.   L    266C 264C 260C 2600
  5134.   M    326D 324D 320D 3200
  5135.   N    316E 314E 310E 3100
  5136.   O    186F 184F 180F 1800
  5137.   P    1970 1950 1910 1900
  5138.   Q    1071 1051 1011 1000
  5139.   R    1372 1352 1312 1300
  5140.   S    1F73 1F53 1F13 1F00
  5141.   T    1474 1454 1414 1400
  5142.  
  5143.                                      Page: 146
  5144.  
  5145.   U    1675 1655 1615 1600
  5146.   V    2F76 2F56 2F16 2F00
  5147.  
  5148.   W    1177 1157 1117 1100
  5149.   X    2D78 2D58 2D18 2D00
  5150.   Y    1579 1559 1519 1500
  5151.   Z    2C7A 2C5A 2C1A 2C00
  5152.   1    0231 0221      7800
  5153.   2    0332 0340 0300 7900
  5154.   3    0433 0423      7A00
  5155.   4    0534 0524      7B00
  5156.   5    0635 0625      7C00
  5157.   6    0736 075E 071E 7D00
  5158.   7    0837 0826      7E00
  5159.   8    0938 092A      7F00
  5160.   9    0A39 0A28      8000
  5161.   0    0B30 0B29      8100
  5162.   -    0C2D 0C5F 0C1F 8200
  5163.   =    0D3D 0D2B      8300
  5164.   [    1A5B 1A7B 1A1B 1A00
  5165.   ]    1B5D 1B7D 1B1D 1B00
  5166.        273B 273A      2700
  5167.   '    2827 2822
  5168.   '    2960 297E
  5169.   \    2B5C 2B7C 2B1C 2600 (same as Alt L)
  5170.   ,    332C 333C
  5171.   .    342E 343E
  5172.   /    352F 353F
  5173.  
  5174.  
  5175.   F1   3B00 5400 5E00 6800
  5176.   F2   3C00 5500 5F00 6900
  5177.   F3   3D00 5600 6000 6A00
  5178.   F4   3E00 5700 6100 6B00
  5179.   F5   3F00 5800 6200 6C00
  5180.   F6   4000 5900 6300 6D00
  5181.   F7   4100 5A00 6400 6E00
  5182.   F8   4200 5B00 6500 6F00
  5183.   F9   4300 5C00 6600 7000
  5184.   F10  4400 5D00 6700  7100
  5185.   F11  8500 8700 8900 8B00
  5186.   F12  8600 8800 8A00 8C00
  5187.   BackSpace 0E08 0E08 0E7F 0E00
  5188.   Del  5300 532E 9300 A300
  5189.   Down Arrow     5000 5032 9100 A000
  5190.   End  4F00 4F31 7500 9F00
  5191.   Enter   1C0D   1C0D 1C0A A600
  5192.   Esc  011B 011B 011B 0100
  5193.   Home 4700 4737 7700 9700
  5194.  
  5195.                                      Page: 147
  5196.  
  5197.   Ins  5200 5230 9200 A200
  5198.  
  5199.   Keypad 5       4C35 8F00
  5200.   Keypad *  372A      9600 3700
  5201.   Keypad -  4A2D 4A2D 8E00 4A00
  5202.   Keypad +  4E2B 4E2B      4E00
  5203.   Keypad /  352F 352F 9500 A400
  5204.   Left Arrow     4B00 4B34 7300 9B00
  5205.   PgDn 5100 5133 7600 A100
  5206.   PgUp 4900 4939 8400 9900
  5207.   PrtSc          7200
  5208.   Right Arrow    4D00 4D36 7400 9D00
  5209.   SpaceBar  3920 3920 3920 3920
  5210.   Tab  0F09 0F00 9400 A500
  5211.   Up Arrow  4800 4838 8D00 9800
  5212.  
  5213.   Some key combinations are not available on all systems.
  5214.        The PS/2 includes many that aren't available on the
  5215.        PC, XT and AT.
  5216.                                           Page: 148
  5217. VAR()
  5218.  
  5219. Syntax:
  5220.   Var(<expN>[,<exp>])
  5221.  
  5222. Pass:
  5223.   <expN> (use one of the manifest constants located in
  5224.        the file BUILDER.CH instead of a literal) for the
  5225.        Aeolus Builder system variable to retrieve.
  5226.        Optionally pass <exp> to set system variable <expN>.
  5227.        Not passing <exp> will cause system variable  <expN>
  5228.        to be unchanged.
  5229.  
  5230. Returns:
  5231.   The Aeolus Builder system variable requested.  This can
  5232.        be any data type.
  5233.  
  5234. Description:
  5235.   Use this function to get and set the Aeolus Builder
  5236.        system variables.  The following list shows the
  5237.        manifest constants and their associated meaning:
  5238.  
  5239.   NETWORK logical     Defines whether record locking
  5240.        should be used.
  5241.   XPLODE  logical     Defines whether to pop or explode
  5242.        windows onto the screen.
  5243.   WREV_CLR_ character Window Reverse color.
  5244.   WGET_CLR_ character Window GET color.
  5245.   WMSG_CLR_ character Window message or enhanced color.
  5246.   WERR_CLR_      character Window error color.
  5247.   WNDW_CLR_ character Window color.
  5248.   HDR_CLR_  character Screen header border color.
  5249.   HDR_MSG_  character Screen header message color.
  5250.   BREV_CLR_ character Background reverse color.
  5251.   BGET_CLR_ character Background GET color.
  5252.   BKGD_CLR_ character Background color.
  5253.   BMSG_CLR_ character Background message color.
  5254.   BERR_CLR_ character Background error color.
  5255.   WNDW2_CLR_     character Window "2" color.
  5256.   WMSG2_CLR_     character Window "2" message color.
  5257.   SHDW_CLR_ character Shadow color.
  5258.   ERR_CLR_  character Error color.
  5259.   MSG_CLR_  character Message line color.
  5260.   HELP_CLR_ character Help color.
  5261.  
  5262.   BRWS_CLR_ character Browse color.
  5263.   BRWS_REV_ character Browse pointer color.
  5264.   BRWS_HL1_ character Browse highlight one color.
  5265.   BRWS_HR1_ character Browse pointer for highlight one.
  5266.   BRWS_HL2_ character Browse highlight two color.
  5267.  
  5268.                                      Page: 149
  5269.  
  5270.   BRWS_HR2_ character Browse pointer for highlight two.
  5271.  
  5272.   MENU_CLR_ character Menu color.
  5273.   MENU_REV_ character Menu pointer color.
  5274.   HLGT_CLR_ character Menu speed key color.
  5275.  
  5276. Sample:
  5277.   For example, to set the color to "WNDW_CLR_" you would
  5278.        write the following line of code:
  5279.  
  5280.           SETCOLOR( Var( WNDW_CLR_ ) )
  5281.  
  5282.   Remember that to use these manifest constants you must
  5283.        have a '#Include "Builder.Ch"' pre-processor
  5284.        directive at the beginning of your program.
  5285.                                           Page: 150
  5286. VARINIT()
  5287.  
  5288. Syntax:
  5289.   VARINIT()
  5290.  
  5291. Pass:
  5292.   Nothing.
  5293.  
  5294. Returns:
  5295.   Nothing
  5296.  
  5297. Description:
  5298.   This function is intended to be used only once during
  5299.        the initialization of an Aeolus Builder program.  It
  5300.        simply sets the Aeolus Builder system variables to
  5301.        their default values.
  5302.  
  5303.   See: VAR()
  5304.                                           Page: 151
  5305. WAITKEY()
  5306.  
  5307. Syntax:
  5308.   waitkey([<expN>])
  5309.  
  5310. Pass:
  5311.   <expN> timeout seconds
  5312.  
  5313. Returns:
  5314.   A numeric expression.
  5315.  
  5316. Description:
  5317.   Use WAITKEY() as a substitute for the Clipper
  5318.        INKEY([<expN>]) function.  The difference between
  5319.        the two is that WAITKEY() will react to SET KEY TO
  5320.        ... 's you have set and WAITKEY() will react to
  5321.        mouse inputs using the BUILDER mouse routines.  Not
  5322.        passing the parameter or passing zero (the default)
  5323.        will cause WAITKEY() to wait until a key is pressed
  5324.        with no timeout.
  5325.                                           Page: 152
  5326. WINBOTT()
  5327.  
  5328. Syntax:
  5329.   WinBott()
  5330.  
  5331. Pass:
  5332.   Nothing.
  5333.  
  5334. Returns:
  5335.   The current window bottom border screen row number.
  5336.  
  5337. Description:
  5338.   The WinBott() function is useful when positioning
  5339.        display items inside Builder windows.  This function
  5340.        is used extensively to create the WINDOW, WINSAY,
  5341.        WINGET, and WINPROMPT commands.  See the Builder.ch
  5342.        file for how this is used.
  5343.                                           Page: 153
  5344. WINLEFT()
  5345. Syntax:
  5346.   WinLeft()
  5347.  
  5348. Pass:
  5349.   Nothing.
  5350.  
  5351. Returns:
  5352.   The current window left border screen column number.
  5353.  
  5354. Description:
  5355.   The WinLeft() function is useful when positioning
  5356.        display items inside Builder windows.  This function
  5357.        is used extensively to create the WINDOW, WINSAY,
  5358.        WINGET, and WINPROMPT commands.  See the Builder.ch
  5359.        file for how this is used.
  5360.                                           Page: 154
  5361. WINPOP()
  5362.  
  5363. Syntax:
  5364.   winpop()
  5365.  
  5366. Pass:
  5367.   Nothing
  5368.  
  5369. Returns:
  5370.   A logical value, true if there was something removed
  5371.        from the screen.
  5372.  
  5373. Description:
  5374.   The WINPOP() function removes the last window on the
  5375.        screen that was created by the WINPUSH function.
  5376.  
  5377.   See WINPUSH() for examples.
  5378.                                           Page: 155
  5379. WINPUSH()
  5380.  
  5381. Syntax:
  5382.   winpush(<expN1>,<expN2>,<expN3>,<expN4>[,<expL1>] ;
  5383.   [,<expL2>][,<expL3>][,<expL4>][,<expC1>][,<expC2>])
  5384.  
  5385. Pass:
  5386.   <expN1> top left row
  5387.   <expN2> top left column
  5388.   <expN3> bottom right row
  5389.   <expN4> bottom right column
  5390.   <expL1> save the screen area before displaying,
  5391.           default true
  5392.   <expL2> clear the interior of the box, default true
  5393.   <expL3> display the box with a border, default true
  5394.   <expL4> display the box with a shadow, default true
  5395.   <expC1> border style for window.  Default is Var(
  5396.           WNDW_STYLE )
  5397.   <expC2> Alternate window color.
  5398.  
  5399. Returns:
  5400.   A logical value, if the window was successfully
  5401.        displayed, true is returned.
  5402.  
  5403. Description:
  5404.   The WINPUSH function saves the portion of the screen
  5405.        bounded the coordinates <expN1> through <expN4> with
  5406.        <expN1> and <expN2> being the upper left row and
  5407.        column positions and <expN3> and <expN4> the lower
  5408.        right corner positions and draws a box on the screen
  5409.        in the default color.
  5410.  
  5411.   All four of the logical expressions that can optionally
  5412.        be passed have a default value of true.
  5413.  
  5414.   If <expL1> is true the screen area bounded by the
  5415.        passed screen coordinates is saved to the screen
  5416.        array otherwise if set to false and it cannot be
  5417.        WINPOPed.
  5418.  
  5419.   <expL2> if set to true will clear the box interior
  5420.        otherwise only the border, if any, is displayed.
  5421.        The default it true.
  5422.  
  5423.   <expL3> if set to true will display a double border on
  5424.        the box.
  5425.  
  5426.   <expL4> controls the shadow on the box, if set to true
  5427.        a shadow is displayed otherwise the shadow is not
  5428.        displayed.
  5429.                                      Page: 156
  5430.  
  5431.   <expC1> Border style to use on the window.  Use the
  5432.        Builder manifest constants located in the Builder.ch
  5433.        header file or any two characters and the first
  5434.        character will be used as the horizontal border
  5435.        character and the second the vertical border.  In
  5436.        the beginning of the Builder.ch header file are six
  5437.        manifiest constants that begin with W_, these will
  5438.        tell WinPush() to use the high ASCII screen
  5439.        graphics.
  5440.  
  5441.   W_DOUBLE -          Double border
  5442.   W_SINGLE -          Single border
  5443.   W_DOUBLE_SINGLE -   Double horizontal, single vertical
  5444.   W_SINGLE_DOUBLE -   Single horizontal, double vertical
  5445.   W_3D_PLUS -         3d pulling out of screen
  5446.   W_3D_MINUS -        3d pushing into screen
  5447.  
  5448.   Note:  If the system variable Var(XPLODE) is a logical
  5449.        variable set to true the WINPUSH function will
  5450.        explode the window onto the screen.
  5451.  
  5452. Sample:
  5453.  
  5454.           **********************************************
  5455.           ************
  5456.   *** WINPUSH/WINPOP sample code
  5457.   ***
  5458.  
  5459.   ** put a window on the screen saving the area so it
  5460.           can be WINPOPed,
  5461.   ** clearing the inside of the window when displayed,
  5462.           put double border
  5463.   ** characters on the window, and put a shadow on the
  5464.           window.
  5465.  
  5466.   WinPush( 05, 10, 17, 60 )
  5467.   @ 07,12 SAY "My Window to the World."
  5468.   Waitkey()
  5469.  
  5470.   ** remove window, and shadow.
  5471.   WinPop()
  5472.                                           Page: 157
  5473. WINRIGHT()
  5474.  
  5475. Syntax:
  5476.   WinRight()
  5477.  
  5478. Pass:
  5479. <indent 3/4 inch>     Nothing.
  5480.  
  5481. Returns:
  5482.   The current window right border screen column number.
  5483.  
  5484. Description:
  5485.   The WinRight() function is useful when positioning
  5486.        display items inside Builder windows.  This function
  5487.        is used extensively to create the WINDOW, WINSAY,
  5488.        WINGET, and WINPROMPT commands.  See the Builder.ch
  5489.        file for how this is used.
  5490.                                           Page: 158
  5491. WINSTYLE()
  5492.  
  5493. Syntax:
  5494.   WinStyle()
  5495.  
  5496. Pass:
  5497.   Nothing.
  5498.  
  5499. Returns:
  5500.   The two byte character string of the current window's
  5501.        border style.
  5502.  
  5503. Description:
  5504.   This function is useful when placing other border
  5505.        characters on a window.  By using the return value,
  5506.        you can know what characters to use that will look
  5507.        right on a window.  See the Builder.ch header file,
  5508.        near the beginning are six manifest constants that
  5509.        begin with W_.  These are the main border styles
  5510.        that would be returned by a call to WinStyle().
  5511.                                           Page: 159
  5512. WINTOP()
  5513.  
  5514. Syntax:
  5515.   WinTop()
  5516.  
  5517. Pass:
  5518.   Nothing.
  5519.  
  5520. Returns:
  5521.   The current window top border screen row number.
  5522.  
  5523. Description:
  5524.   The WinTop() function is useful when positioning
  5525.        display items inside Builder windows.  This function
  5526.        is used extensively to create the WINDOW, WINSAY,
  5527.        WINGET, and WINPROMPT commands.  See the Builder.ch
  5528.        file for how this is used.
  5529.  
  5530.