home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / progmisc / bldr10b.zip / LIBRARY.DOC < prev    next >
Text File  |  1993-03-19  |  75KB  |  3,423 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.                                 Aeolus Software
  22.                             Clipper Function Library
  23.  
  24.  
  25.                                    COPYRIGHT
  26.  
  27.  
  28.                           (c) 1992 by Aeolus Software
  29.                               All rights reserved.
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.                         FUNCTION LIBRARY REFERENCE GUIDE
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.                                TABLE OF CONTENTS
  66.  
  67.  
  68.  
  69.         Conventions...............................................1
  70.         Procedure and Function Summary............................2
  71.         ASC2BIN...................................................5
  72.         ADD_REC...................................................6
  73.         ASK.......................................................7
  74.         APOP......................................................8
  75.         BETWEEN...................................................10
  76.         BROWSER...................................................11
  77.         CENTER....................................................12
  78.         CKPRTR....................................................13
  79.         DBPUBL....................................................14
  80.         DBREPL....................................................15
  81.         DBSTOR....................................................16
  82.         ERRTONE...................................................17
  83.         FEOF......................................................18
  84.         FGETS.....................................................19
  85.         FIL_LOCK..................................................20
  86.         FLD_REPL..................................................21
  87.         GEN_MAINT.................................................22
  88.         GOT.......................................................25
  89.         ISEEK.....................................................27
  90.         LSIDE.....................................................28
  91.         MAKE_EMPTY................................................29
  92.         MAXHNDLS..................................................30
  93.         MESSAGE...................................................31
  94.         MSGBOX....................................................32
  95.         NET_USE...................................................34
  96.         NUMERIC...................................................35
  97.         OPEN_FIL..................................................36
  98.         PADC......................................................37
  99.         PADL......................................................38
  100.         PADR......................................................39
  101.         POP.......................................................40
  102.         POP_KEY...................................................43
  103.         PUBL_COLO.................................................44
  104.         REC_LOCK..................................................45
  105.         REL_MAINT.................................................46
  106.         RSIDE.....................................................48
  107.         SAVE_IT...................................................49
  108.         SHADOW....................................................50
  109.         THERMOMETR................................................51
  110.         TOTALKEYON/TOTALKEYOFF....................................52
  111.         WAITKEY...................................................53
  112.         WINPOP....................................................54
  113.         WINPUSH...................................................55
  114.  
  115.  
  116.  
  117.  
  118.  
  119.                   The Aeolus Procedure and Function Library
  120.                                 Reference Manual
  121.  
  122.  
  123.  
  124.         Conventions used in this guide:
  125.         <expC>:  A characer expression
  126.         <expL>:  A logical expression (i.e. .t. or .f.)
  127.         <expD>:  A date expression
  128.         <expN>:  A numeric expression, a number or calculation
  129.         <expA>:  An array name
  130.         <exp>:   An expression that may be of any type
  131.  
  132.  
  133.         Parameters notated inside square brackets ([]) are optional par-
  134.         ameters, defaults will be given where applicable.
  135.  
  136.  
  137.  
  138.         Many BUILDER library procedures and functions use one or more
  139.         system wide memory variables.  These variables must be declared
  140.         in the initialization of ALL programs which use this library.
  141.         Fortunately the BUILDER code generator does this for you, but if
  142.         you would like to code from scratch and use the library be sure
  143.         these variables exist before using any library procedures/func-
  144.         tions:
  145.  
  146.         SYSDEL   - Logical if set to true tells the library that SET
  147.                    DELETED is ON.  If false OFF.
  148.         XPLODE   - Logical if set to true tells the WINPUSH() function
  149.                    to explode your windows onto the screen.  If false
  150.                    windows 'pop' onto screen.
  151.         MSG_LN   - Numeric, the line number where messages are displayed,
  152.                    should always be set to 24.
  153.         NETWORK  - Logical if set to true opens files in shared mode and
  154.                    locks records before writing to files.  If false
  155.                    files are opened EXCLUSIVE.
  156.  
  157.         The 15 color variables - See the PUBL_COLO procedure for their
  158.         names.
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.                                       <1>
  178.                   The Aeolus Procedure and Function Library
  179.                                 Reference Manual
  180.  
  181.  
  182.  
  183.         Alphabetical Proc/Func summary
  184.  
  185.         ASC2BIN(<expC>)
  186.           Converts ASCII control indicators to control characters.
  187.  
  188.         *ADD_REC(<expN>) 
  189.           Adds a blank .DBF record.
  190.  
  191.         ASK(<expC1>,<expC2>,<expN1>,<expN2>[,<expN3>][,<expC3>] ;
  192.         [,<expC4>])
  193.           Prompt function.
  194.  
  195.         APOP(<expN1>,<expN2>,<expN3>,<expN4>,<expA>,<expN5>,<expC1>[<exp-
  196.         C2>][,<expC3>])
  197.           Choose multiple menu items from array.
  198.  
  199.         BETWEEN(<exp1>,<exp2>,<exp3>)
  200.           Evaluates if expression 1 is greater than and equal to expres-
  201.           sion 2 and less than and equal to expression 3
  202.  
  203.         BROWSER WITH
  204.         <expN1>,<expN2>,<expN3>,<expN4>[,<expC>][,<expN5>][,<expN6>]
  205.           Sets up window to browse a database
  206.  
  207.         CENTER(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>])
  208.           Centers text on the screen or within a window.
  209.  
  210.         CKPRTR(<expN>)
  211.           Checks if parallel printer is available.
  212.  
  213.         DBPUBL WITH <expC>
  214.           Creates public memory variables from database field variables.
  215.  
  216.         DBREPL WITH <expC>
  217.           Replaces database field variables with memory variables.
  218.  
  219.         DBSTOR WITH <expC>
  220.           Stores database field variables to memory variables.
  221.  
  222.         ERRTONE([<expN>])
  223.           Beep speaker with optional sounds.
  224.  
  225.         FEOF()
  226.           Use when reading a .SDF file with FGETS().
  227.  
  228.         FGETS(<expN>)
  229.           Returns next record in a .SDF type file.
  230.  
  231.         FIL_LOCK(<expN>)
  232.           Locks a file for exclusive type activity.
  233.  
  234.         FLD_REPL WITH <expC1>,<expC2>
  235.  
  236.                                       <2>
  237.                   The Aeolus Procedure and Function Library
  238.                                 Reference Manual
  239.  
  240.  
  241.  
  242.           Replace one database field in a shared or single user
  243.           environment.
  244.  
  245.         GEN_ADDTO WITH ;
  246.         <expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2>,<exp>,<expC3> ;
  247.         [,<expL>][,<expC4>][,<expC5>]
  248.           Generic maintenance for the many database of a one to many
  249.           relationship, or a database with very few records.  This rou-
  250.           tine is used extensively in the BUILDER program.
  251.  
  252.         GEN_MAINT WITH ;
  253.         <expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2>[,<expN5>] ;
  254.         [,<expN6>][,<expL>]
  255.           Generic file maintenance.
  256.  
  257.         GOT(<expC>,<expN1>,<expN2>)
  258.           Get field data from a database record number and field number.
  259.  
  260.         ISEEK(<exp>,<expC>,<expN>,<expL>)
  261.           Locate a record in a database via an index.
  262.  
  263.         *LSIDE
  264.           left arrow logic for drop down menu scrolling.
  265.  
  266.         MAKE_EMPTY(<expC>)
  267.           Create an empty memory variable based on the passed variable.
  268.  
  269.         MAXHNDLS(<expN>)
  270.           Tests system configuration for number of file handles.
  271.  
  272.         MESSAGE(<expC1>,<expN1>,<expN2>[,<expN3>][,<expC2>])
  273.           Display a screen message.
  274.  
  275.         MSGBOX(<expC1>[,<expC2>][,<expC3>][,<expC4>][,<expN1>] ;
  276.         [,<expN2>][,<expN3>][,<expN4>])
  277.           Display a message box on the screen, optionally ask a ques-
  278.           tion.
  279.  
  280.         *NET_USE(<expC1>,<expL>,<expN>,<expC2>)
  281.           Network file open function.
  282.  
  283.         NUMERIC(<expC>)
  284.           Check a character string for any non-numeric characters.
  285.  
  286.         OPEN_FIL(<expC1>[,<expL1>][,<expC2>][,<expL2>])
  287.           All purpose file open routine.
  288.  
  289.         PADC(<expC1>,<expN>[,<expC2>])
  290.           Pad a character string to the middle, centering it.
  291.  
  292.         PADL(<expC1>,<expN>[,<expC2>])
  293.           Pad a character string to the left, right justify it.
  294.  
  295.                                       <3>
  296.                   The Aeolus Procedure and Function Library
  297.                                 Reference Manual
  298.  
  299.  
  300.  
  301.  
  302.         PADR(<expC1>,<expN>[,<expC2>])
  303.           Pad a character string to the right, left justifiy it.
  304.  
  305.         POP(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2>[,<expL1>] ;
  306.         [,<expC3>][,<expC4>][,<expC5>][,<expC6>])
  307.           Pick list window function.
  308.  
  309.         PUBL_COLO
  310.           Sets default color variables.
  311.  
  312.  
  313.         *REC_LOCK(<expN>)
  314.           Record lock function.
  315.  
  316.          REL_MAINT WITH <expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ;
  317.                <expC2>,<expC3>,<expC4>,<expN5>,<expN6>
  318.  
  319.         *RSIDE
  320.           right arrow logic for drop down menu scrolling.
  321.  
  322.         SAVE_IT(<expC1>,<expC2>,<expN>,<expC3>)
  323.           All purpose file I/O routine.
  324.  
  325.         *SHADOW(<expN1>,<expN2>,<expN3>,<expN4>)
  326.           Puts a shadow on a box.
  327.  
  328.         THERMOMETR(<expN1>,<expN2>,<expN3>,<expN4>)
  329.           Creates a thermometer to show the progress of a routine.
  330.  
  331.         *TOTALKEYON/TOTALKEYOFF
  332.           Enalbles/Disables drop down menu right and left scrolling.
  333.  
  334.         WAITKEY([<expN>])
  335.           Works like INKEY(0) but allows SET KEY TO ...'s to be pro-
  336.           cessed.
  337.  
  338.         WINPOP()
  339.           Remove a window from the screen create with WINPUSH.
  340.  
  341.         WINPUSH(<expN1>,<expN2>,<expN3>,<expN4>[,<expL1>] ;
  342.         [,<expL2>][,<expL3>][<expL4>])
  343.           Put a window on the screen, may be saved for later removal.
  344.  
  345.         * Procedures and functions preceded by an asterisk (*) are
  346.         either dealt with entirely by BUILDER generated code or are
  347.         called by another library function.  You will probably never
  348.         need to use these and are included only for the sake of complet-
  349.         ness.
  350.  
  351.  
  352.  
  353.  
  354.                                       <4>
  355.                   The Aeolus Procedure and Function Library
  356.                                 Reference Manual
  357.  
  358.  
  359.  
  360.         ASC2BIN()
  361.  
  362. Syntax:
  363.         ASC2BIN(<expC>)
  364.  
  365. Pass:
  366.         <expC> string with control character expressions embedded.
  367.  
  368. Returns:
  369.         Character expression.  The converted string.
  370.  
  371. Description:
  372.         The ASC2BIN() function converts a character
  373.         expression that contains one or more caret (^)
  374.         symbols followed by a character to it's 'control'
  375.         or binary value.  Use this function for creating
  376.         printer control strings.  For example :
  377.                 c=ASC2BIN("^A")  && caps important
  378.                 ? asc(c)         && would display chr(1) -- ASCII for
  379.                                  && control A
  380.  
  381. Sample:
  382.         ***********************************************
  383.         ** print a message on a laser printer in
  384.         ** landscape using HP escape sequence
  385.  
  386.         prtrt="^[&l0O"           && caret, left bracket (escape),
  387.                                  && ampersand, lower case L, zero,
  388.                                  && upper case O
  389.         lndscp="^[&l1O"          && caret, left bracket (escape),
  390.                                  && ampersand, lower case L, one,
  391.                                  && upper case O
  392.         set print on
  393.         ?? asc2bin(lndscp) && set printer to landscape
  394.         ? "This text printed using landscape."
  395.         ?? asc2bin(prtrt)  && set printer back to portrait
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.                                       <5>
  414.                   The Aeolus Procedure and Function Library
  415.                                 Reference Manual
  416.  
  417.  
  418.  
  419.         ADD_REC()
  420.  
  421. Syntax:
  422.         add_rec(<expN>)
  423.  
  424. Pass:
  425.         <expN> seconds until timeout, zero for no timeout.
  426.  
  427. Returns:
  428.         a logical expression.
  429.  
  430. Description:
  431.         Attempts to add a blank record to the currently selected data-
  432.         base for timeout period of <expN> seconds.  If a record cannot
  433.         be added after the timeout period an error box is presented to
  434.         try again, if No is selected, a logical false is returned.  If
  435.         <expN> is zero or not passed to the function, ADD_REC() will
  436.         wait indefinately.
  437.  
  438. Comment:
  439.         This function is called by the SAVE_IT() function therefore it
  440.         should never need to be used by you in a program, use the
  441.         SAVE_IT() function to do file I/O instead.  It is  included here
  442.         only for completness.
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.                                       <6>
  473.                   The Aeolus Procedure and Function Library
  474.                                 Reference Manual
  475.  
  476.  
  477.  
  478.         ASK()
  479.  
  480. Syntax:
  481.         ASK(<expC1>,<expC2>,<expN1>,<expN2>[,<expN3>][,expC3][,<expC4>])
  482.  
  483. Pass:
  484.         <expC1> prompt text.
  485.         <expC2> list of acceptable input characters.
  486.         <expN1> row for prompt.
  487.         <expN2> column for prompt.
  488.         <expN3> pad prompt to length.
  489.         <expC3> alternate color.
  490.         <expC4> "ESC" to allow ESC key.
  491.  
  492. Returns:
  493.         Character expression.  The keyboard character pressed.
  494.  
  495. Description:
  496.         <expC1> will be displayed at row <expN1> and column <expN2>.
  497.         ASK() will wait until any keyboard character contained in the
  498.         list <expC2> is pressed.
  499.  
  500.         <expC2> may be passed in upper or lower case, ASK() does not
  501.         distinguish.  If you pass "YN" either a lower or upper case 'Y'
  502.         key press will return an upper case "Y" from ASK().  Also if you
  503.         pass "yn" either a lower or upper case 'Y'key press will return
  504.         an upper case "Y".
  505.  
  506.         <expN3> spaces will be displayed before the message in <expC1>
  507.         to clear previous text, optional.  default is the length of
  508.         <expC1>.
  509.  
  510.         <expC3> is color to display <expC1>.  Default is current color.
  511.  
  512.         If <expC4> is equal to "ESC" then ASK() can be exited using the
  513.         ESC key.  If the ESC key is used to exit ASK() a null string
  514.         will be passed to the calling procedure.  The default is to not
  515.         allow ESCaping.
  516.  
  517.  
  518. Sample:
  519.         *****************************************************
  520.         **  display the question on line 24 column 0 and pad
  521.         **  the text to 80 characters.  Wait until a Y or N
  522.         **  is pressed on the keyboard.
  523.  
  524.         answer=ask("Do You Wish to Continue? (Y/N)","YN",24,0,80)
  525.  
  526.         ** the character variable "answer" will equal either "Y"
  527.         ** or "N" depending on what the key is pressed.
  528.  
  529.  
  530.  
  531.                                       <7>
  532.                   The Aeolus Procedure and Function Library
  533.                                 Reference Manual
  534.  
  535.  
  536.  
  537.         APOP()
  538.  
  539. Syntax:
  540.         apop(<expN1>,<expN2>,<expN3>,<expN4>,<expA>,<expN5>, ;
  541.         <expC1>[,<expC2][,<expC3>])
  542.  
  543. Pass:
  544.         <expN1> top left row.
  545.         <expN2> top left column.
  546.         <expN3> bottom right row.
  547.         <expN4> bottom right column.
  548.         <expA>  array name (prefixed with @).
  549.         <expN5> max element to show.
  550.         <expC1> procedure name to execute.
  551.         <expC2> alternate color choice.
  552.         <expC3> alternate reverse color choice.
  553.  
  554. Returns:
  555.         Nothing.
  556.  
  557. Description:
  558.         The APOP() function will put a box on the screen using <expN1>
  559.         through <expN4> as screen coordinates and allow you to scroll
  560.         through elements 1 to <expN5> of the array <expA>.  When a
  561.         selection is made by pressing the ENTER key that selection will
  562.         be bounded by bracket characters (« »). Pressing Ctrl+W will
  563.         execute the procedure <expC1>. <expC2> is an optional color
  564.         value, <expC3> is an alternate reverse color option.  Defaults
  565.         for <expC2> and <expC3> are the current colors.
  566.  
  567. Sample:
  568.         ********************************************************
  569.         ** APOP() example code to allow the selection of multiple
  570.         ** names from a list and then display the selected items.
  571.         **
  572.         declare names[10]        && declare array
  573.         names[01]="Rosalind  "   && initialize array
  574.         names[02]="Mark "
  575.         names[03]="John      "
  576.         names[04]="Lisa      "
  577.         names[05]="Denise    "
  578.         names[06]="Jeff      "
  579.         names[07]="Frank     "
  580.         names[08]="Joe       "
  581.         names[09]="Cathy     "
  582.         names[10]="Jerry     "
  583.  
  584.         ** call APOP()
  585.         apop(05,05,13,18,@names,10,"PRT_NMES")
  586.  
  587.  
  588.         ** the bracket character -chr(174)- is left on the array
  589.  
  590.                                       <8>
  591.                   The Aeolus Procedure and Function Library
  592.                                 Reference Manual
  593.  
  594.  
  595.  
  596.         ** elements that have been selected, so if it is in the
  597.         ** first character position, that element was selected by
  598.         ** the user
  599.  
  600.         procedure prt_nmes
  601.           set print on
  602.           set console off
  603.           for a=1 to 10
  604.             if left(names[a],1)=chr(174)
  605.               ? trim(subs(names[a],2))+" was selected."
  606.             endi
  607.           next
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.                                       <9>
  650.                   The Aeolus Procedure and Function Library
  651.                                 Reference Manual
  652.  
  653.  
  654.  
  655.         BETWEEN()
  656.  
  657. Syntax:
  658.         between(<exp1>,<exp2>,<exp3>)
  659.  
  660. Pass:
  661.         <exp1> value to test.
  662.         <exp2> minimum value.
  663.         <exp3> maximum value.
  664.  
  665. Returns:
  666.         a logical expression.
  667.  
  668. Description:
  669.         A logical true will be returned if <exp1> is greater than and
  670.         equal to <exp2> and less than and equal to <exp3>.  The argu-
  671.         ments passed to the BETWEEN()  function may be of type Character,
  672.         Numeric or Date; however all three arguments must be the same
  673.         data type.
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.                                       <10>
  709.                   The Aeolus Procedure and Function Library
  710.                                 Reference Manual
  711.  
  712.  
  713.  
  714.         BROWSER
  715.  
  716. Syntax:
  717.         do browser with <expN1>,<expN2>,<expN3>,<expN4>[,<expC>] ;
  718.         [,<expN5>][,<expN6>]
  719.  
  720. Pass:
  721.         <expN1> top left row.
  722.         <expN2> top left column.
  723.         <expN3> bottom right row.
  724.         <expN4> bottom right column.
  725.         <expC>  key exception function name.
  726.         <expN5> start field number.
  727.         <expN6> end field number.
  728.  
  729. Description:
  730.         The BROWSER procedure will "browse" the currently selected data-
  731.         base using the Clipper DBEDIT() function.  <expN1> through
  732.         <expN4> define the coordinates of the box that will be dis-
  733.         played, <expC> is the user defined function executed on each
  734.         key press.  <expN5> and <expN6> are the start and end field num-
  735.         bers (i.e. the FCOUNT() number) to browse.  If <expN5> is not
  736.         passed the first field will be browsed.  If <expN6> is not
  737.         passed the <expN5>th through FCOUNT() fields will be browsed.
  738.  
  739.         For more information on using the <expC> user defined function
  740.         consult your Clipper manual on the DBEDIT() function.  <expC> is
  741.         merely passed to DBEDIT() as the UDF for each key press.
  742.  
  743. Sample:
  744.         ******************************************************
  745.         ** BROWSER sample call
  746.         **
  747.         select 0
  748.         use customer
  749.         do browser with 5,3,17,73
  750.  
  751.         ** this will put a box on the screen from row 5 column 3 to row
  752.         ** 17 column 73 and browse all the fields in the database
  753.         ** CUSTOMER.
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.                                       <11>
  768.                   The Aeolus Procedure and Function Library
  769.                                 Reference Manual
  770.  
  771.  
  772.  
  773.         CENTER()
  774.  
  775. Syntax:
  776.         center(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2])
  777.  
  778. Pass:
  779.         <expC1> message to display.
  780.         <expN1> row to begin centering computation.
  781.         <expN2> column to begin centering computation.
  782.         <expN3> length for centering computation.
  783.         <expC2> alternate color.
  784.  
  785. Returns:
  786.         Start column of centered text.
  787.  
  788. Description:
  789.         The CENTER() function displays <expC1> on row <expN1> column
  790.         <expN2> centered within a width <expN3> wide. <expC2> is an
  791.         alternate color choice.  The default color is the current from
  792.         the last SET COLOR TO ... statement.
  793.  
  794. Sample:
  795.         ****************************************************
  796.         ** CENTER() function example
  797.         **
  798.         ** put a box on the screen
  799.         winpush(5,5,15,45)
  800.  
  801.         ** center text in the box
  802.         center("Yoo Hoo, I'm Centered",7,16,29)
  803.  
  804.         inkey(0)
  805.         ** remove box
  806.         winpop()
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.                                       <12>
  827.                   The Aeolus Procedure and Function Library
  828.                                 Reference Manual
  829.  
  830.  
  831.  
  832.         CKPRTR()
  833.  
  834. Syntax:
  835.         ckprtr([<expN>])
  836.  
  837. Pass:
  838.         nothing or 1, 1 if ESCaping is allowed.
  839.  
  840. Returns:
  841.         a logical expression.
  842.  
  843.         --DESCRIPTION:
  844.         The CKPRTR() function returns a logical true if the Clipper ISP-
  845.         RINTER() function returns a logical true.  CKPRTR() displays an
  846.         error box if ISPRINTER() returns false and checks the ISP-
  847.         RINTER() function again after a key is pressed.
  848.  
  849.         You can see that an infinite loop will be created if the printer
  850.         cannot be brought on-line, if <expN> is a value of one (1) then
  851.         the ESC key will allow an exit from CKPRTR() when the printer is
  852.         not operating and if ESCaped CKPRTR() will return false (.f.).
  853.  
  854.         --SAMPLE:     
  855.         *************************************************
  856.         ** CKPRTR() function example
  857.  
  858.         proc a_report
  859.  
  860.         set device to printer
  861.         do while !eof()
  862.           if !ckprtr(1)     && check printer on each print line
  863.             exit
  864.           endi
  865.  
  866.           .
  867.           print report commands .
  868.           .
  869.  
  870.         enddo
  871.  
  872.         >>COMMENT:      
  873.         The CKPRTR() function will only work with parallel printers.
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.                                       <13>
  886.                   The Aeolus Procedure and Function Library
  887.                                 Reference Manual
  888.  
  889.  
  890.  
  891.         DBPUBL
  892.  
  893. Syntax:
  894.         do dbpubl [with <expC>]
  895.  
  896. Pass:
  897.         Nothing or public variable prefix character(s).  If nothing is
  898.         passed, the default is "Q".
  899.  
  900. Description:
  901.         Dbpubl declares a public memory variable for each field variable
  902.         in a database.  The memory variables created will be prefixed by
  903.         <expC>.
  904.  
  905.         If <expC> is not passed "Q" is assumed as the default.
  906.         See DBREPL, DBSTOR and SAVE_IT().
  907.  
  908.         Variables are only made PUBLIC and not initialized to any value
  909.         therefore all variables will be set to .F. by Clipper at the
  910.         completion of this procedure.
  911.  
  912.  
  913. Sample:
  914.         ***************************************************
  915.         ** DBPUBL example
  916.         **
  917.         ** a database with the following structure is assumed
  918.         **
  919.         **  FNAME      Character   15
  920.         **  LNAME      Character   20
  921.         **  ADDRESS    Character   35
  922.         **  PHONE      Character   10
  923.         **
  924.  
  925.         select 0
  926.         use addrbook
  927.  
  928.         ** declares mfname,mlname,maddress,mphone as public
  929.         do dbpubl with "M"
  930.  
  931. Comment:
  932.         wise the
  933.         uniqueness to your field variables can be lost, I suggest
  934.         a length of one, two as an absolute maximum.
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.                                       <14>
  945.                   The Aeolus Procedure and Function Library
  946.                                 Reference Manual
  947.  
  948.  
  949.  
  950.         DBREPL
  951.  
  952. Syntax:
  953.         do dbrepl [with <expC>]
  954.  
  955. Pass:
  956.         Nothing or variable prefix character(s).  If nothing is passed,
  957.         the default is "Q".
  958.  
  959. Description:
  960.         DBREPL replaces all the field variables in a record using memory
  961.         variables that exactly the same names as the field variables
  962.         except they are prefixed with <expC>. 
  963.  
  964.         See DBPUBL, DBSTOR and SAVE_IT().
  965.  
  966. Sample:
  967.         ***************************************************
  968.         ** DBREPL example
  969.         **
  970.         ** a database with the following structure is assumed
  971.         **
  972.         **  FNAME      Character   15
  973.         **  LNAME      Character   20
  974.         **  ADDRESS    Character   35
  975.         **  PHONE      Character   10
  976.         **
  977.  
  978.         select 0
  979.         use addrbook
  980.  
  981.         ** declares mfname,mlname,maddress,mphone as memory vars
  982.         mfname="DENISE"
  983.         mlname="JOHNSON"
  984.         maddress="123 MAPLE ST"
  985.         mphone="6125551234"
  986.  
  987.         appe blan                && add a blank record
  988.         do dbrepl with "M"       && replace all field vars.
  989.  
  990. Comment:
  991.         wise the
  992.         uniqueness to your field variables can be lost, I suggest
  993.         a length of one, two as an absolute maximum.
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.                                       <15>
  1004.                   The Aeolus Procedure and Function Library
  1005.                                 Reference Manual
  1006.  
  1007.  
  1008.  
  1009.         DBSTOR
  1010.  
  1011. Syntax:
  1012.         do dbstor [with <expC1>][,<expC2>]
  1013.  
  1014. Pass:
  1015.         <expC1> prefix for memvars, default "Q".
  1016.         <expC2> nothing for data or "EMPTY" for empty values.
  1017.  
  1018. Description:
  1019.         DBSTOR stores all the field variables in a record to memory
  1020.         variables with exactly the same names as the field variables
  1021.         variable except they are prefixed with <expC1>.
  1022.  
  1023.         If <expC2> is passed as "EMPTY" then all memory variables will
  1024.         be assigned as if the record were blank.
  1025.  
  1026.         See DBPUBL, DBREPL and SAVE_IT().
  1027.  
  1028. Sample:
  1029.         ***************************************************
  1030.         ** DBSTOR example
  1031.         **
  1032.         ** a database with the following structure is assumed
  1033.         **
  1034.         **  FNAME      Character   15
  1035.         **  LNAME      Character   20
  1036.         **  ADDRESS    Character   35
  1037.         **  PHONE      Character   10
  1038.  
  1039.         select 0
  1040.         use addrbook
  1041.  
  1042.         ** declares mfname,mlname,maddress,mphone as public, you must
  1043.         ** do this in order to use DBSTOR
  1044.         do dbpubl with "M"
  1045.         do dbstor with "M","EMPTY"     && create 'blank' vars
  1046.  
  1047.         clea
  1048.         @ 0,0 say "First Name" get mfname pict "@!
  1049.         @ 1,0 say " Last Name" get mlname pict "@!"
  1050.         @ 2,0 say "   Address" get maddress pict "@!
  1051.         @ 3,0 say "     Phone" get mphone pict "@R (999) 999-9999"
  1052.         read
  1053.  
  1054.         appe blan                && add a blank record
  1055.         do dbrepl with "M"       && replace all field vars.
  1056.  
  1057. Comment:
  1058.         <expC> should be kept as short as possible otherwise the
  1059.         uniqueness to your field variables can be lost, I suggest
  1060.         a length of one, two as an absolute maximum.
  1061.  
  1062.                                       <16>
  1063.                   The Aeolus Procedure and Function Library
  1064.                                 Reference Manual
  1065.  
  1066.  
  1067.  
  1068.         ERRTONE()
  1069.  
  1070. Syntax:
  1071.         errtone([<expN>])
  1072.  
  1073. Pass:
  1074.         Nothing or one (1).
  1075.  
  1076. Returns:
  1077.         Nothing.
  1078.  
  1079. Description:
  1080.         The ERRTONE() function beeps the speaker in one of two ways,
  1081.         either a two tone error beep if no parameters are passed, or a
  1082.         short high pitched single tone if one (1) is passed.
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.                                       <17>
  1122.                   The Aeolus Procedure and Function Library
  1123.                                 Reference Manual
  1124.  
  1125.  
  1126.  
  1127.         FEOF()
  1128.  
  1129. Syntax:
  1130.         feof([<expL>])
  1131.  
  1132. Pass:
  1133.         A Logical Expression or Nothing
  1134.  
  1135. Returns:
  1136.         A logical expression
  1137.  
  1138. Description:
  1139.         The FEOF() function is designed only to be used in conjunction
  1140.         with the FGETS() function.  FEOF()  Returns .T. when end of file
  1141.         is encountered while reading a file using the FGETS() function.
  1142.  
  1143.         Before using FEOF() you must first initialize its internal vari-
  1144.         ables by issuing FEOF(.F.).  See the example code in the
  1145.         description for FGETS().
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.                                       <18>
  1181.                   The Aeolus Procedure and Function Library
  1182.                                 Reference Manual
  1183.  
  1184.  
  1185.  
  1186.         FGETS()
  1187.  
  1188. Syntax:
  1189.         fgets(<expN>)
  1190.  
  1191. Pass:
  1192.         A file handle of a previously FOPEN()'d or FCREATE()'d file.
  1193.  
  1194. Returns:
  1195.         Next logical record in a CR/LF delimited file.
  1196.  
  1197. Description:
  1198.         The FGETS() function will attempt to read the next logical
  1199.         record in a CR/LF delimited file.
  1200.  
  1201. Sample:
  1202.         ***************************************************************
  1203.         ** Sample code to read the AUTOEXEC.BAT file using the       **
  1204.         ** Aeolus FGETS() function.                                  **
  1205.         ***************************************************************
  1206.  
  1207.         ** Open the AUTOEXEC.BAT file
  1208.         hndl=fopen("C:\AUTOEXEC.BAT")
  1209.  
  1210.         feof(.f.)            && initialize FEOF()
  1211.         do whil !feof()
  1212.           ? fgets(hndl)        && read next AUTOEXEC record
  1213.         endd
  1214.         fclose(hndl)
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.                                       <19>
  1240.                   The Aeolus Procedure and Function Library
  1241.                                 Reference Manual
  1242.  
  1243.  
  1244.  
  1245.         FIL_LOCK()
  1246.  
  1247. Syntax:
  1248.         fil_lock(<expN>)
  1249.  
  1250. Pass:
  1251.         <expN> seconds to wait before returning false, zero will not
  1252.         return false.
  1253.  
  1254. Returns:
  1255.         A logical expression.
  1256.  
  1257. Description:
  1258.         The FIL_LOCK() function will attempt to lock a previously
  1259.         opened .DBF database, if it fails in <expN> seconds an error box
  1260.         is displayed allowing the user to try again or abort the
  1261.         operation.  If <expN> is passed as a value of zero then
  1262.         FIL_LOCK() will wait indefinately to attempt the lock.
  1263.  
  1264.         FIL_LOCK returns true if the lock is successful and false
  1265.         if the lock is unsuccessful.
  1266.  
  1267.         Issuing a successful FIL_LOCK() allows a database opened in
  1268.         non-exclusive mode to be treated as if it were opened
  1269.         exclusively.  Note that all other file or record locks will
  1270.         be rejected while you have a successful FIL_LOCK(), be sure
  1271.         to UNLOCK the file or close the database so others on the LAN
  1272.         can use it.
  1273.  
  1274. Sample:
  1275.         ******************************************************
  1276.         ** Attempt to lock a database previously opened in
  1277.         ** shared mode.
  1278.         **
  1279.         set exclusive off       && allow file sharing
  1280.         use addrbook
  1281.         if fil_lock(5)
  1282.           report form addr_rpt to print noeject
  1283.         endi
  1284.         unlock
  1285.  
  1286. Comment:
  1287.         An alternative to using FIL_LOCK() is simply to open your data-
  1288.         bases in exclusive mode.  Either method will accomplish the same
  1289.         thing.
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.                                       <20>
  1299.                   The Aeolus Procedure and Function Library
  1300.                                 Reference Manual
  1301.  
  1302.  
  1303.  
  1304.         FLD_REPL
  1305.  
  1306. Syntax:
  1307.         do fld_repl with <expC>,<exp>
  1308.  
  1309. Pass:
  1310.         <expC> The name of the field in the currently selected
  1311.         database to be replaced.
  1312.         <exp>  The value to place in the database field <expC>
  1313.  
  1314. Description:
  1315.         Use FLD_REPL whenever you need to REPLACE a single database
  1316.         field.  This procedure will work in a shared or single user
  1317.         application.  Using this procedure on single field REPLACEs
  1318.         will allow your application to be changed from a single to
  1319.         multi-user program simply by changing the NETWORK system
  1320.         variable from .F. to .T.!
  1321.  
  1322. Sample:
  1323.         ** replace a date field in the currently selected database
  1324.         ** with today's date - will work if single or multi user
  1325.  
  1326.         do fld_repl with "CURRNT_DT",date()
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.                                       <21>
  1358.                   The Aeolus Procedure and Function Library
  1359.                                 Reference Manual
  1360.  
  1361.  
  1362.  
  1363.         GEN_MAINT
  1364.  
  1365. Syntax:
  1366.         do gen_maint with <expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ;
  1367.         <expC2>[,<expN5>][,<expN6>][,<expL>]
  1368.  
  1369. Pass:
  1370.         <expN1> top left row
  1371.         <expN2> top left column
  1372.         <expN3> bottom right row
  1373.         <expN4> bottom right column
  1374.         <expC1> DBSTOR prefix character(s)
  1375.         <expC2> procedure name suffix
  1376.         <expN5> fast delete index order number
  1377.         <expN6> number of GET fields
  1378.         <expL>  .T. to allow duplicates in file
  1379.  
  1380. Description:
  1381.         The GEN_MAINT procedure is one of two generic file maintenance
  1382.         procedures included with the function library and is designed to
  1383.         be used as an all purpose file maintenance routine.
  1384.  
  1385.         Before you can call the GEN_MAINT procedure you must first code
  1386.         four procedures yourself, GSAYS_????, GGETS_????, GEDIT_???? and
  1387.         GKEY_????.  Where ???? is the value passed as <expC2>. The
  1388.         GSAYS_???? procedure must contain the screen displays,
  1389.         GGETS_???? the get's, and GEDIT_???? additional code performed
  1390.         after a READ statement.
  1391.  
  1392.         Call GEN_MAINT with <expN1> through <expN4> equal to the screen
  1393.         coordinates required.  <expC1> must equal the suffix portion of
  1394.         the three procedures you write.  <expC2> is the prefix character
  1395.         you want when GEN_MAINT creates memory variables.
  1396.  
  1397.         Optionally pass <expN5> as the 'fast delete' index order number.
  1398.         A fast delete index is created by issuing the following Clipper
  1399.         command:
  1400.  
  1401.         INDE ON IF(DELE(),"*"," ") TO ...
  1402.  
  1403.         If <expN5> is not passed or passed with a value of zero the
  1404.         database will be PACKed on every delete instead.  Using the fast
  1405.         delete, records marked for deletion are used as 'add space' so
  1406.         your database doesn't grow indefinately.  Note that you must use
  1407.         either SET DELETED ON or SET FILTER TO !DELE() for fast delete
  1408.         to work correctly.
  1409.  
  1410.         <expN6> is another optional parameter that should be used if you
  1411.         have any VALID clauses in your file maintenance.  The value
  1412.         passed in <expN6> should be equal to the number of fields that
  1413.         are in the file maintenance GET string.  If you use this, exec-
  1414.         cute a CLEAR TYPEAHEAD in the VALID function if an error occurs.
  1415.  
  1416.                                       <22>
  1417.                   The Aeolus Procedure and Function Library
  1418.                                 Reference Manual
  1419.  
  1420.  
  1421.  
  1422.         The cursor will be positioned at the error field if a VALID
  1423.         fails.
  1424.  
  1425.         And finally <expL> may be passed as true if duplicate records
  1426.         are to be allowed.  The default is false.
  1427.  
  1428.         You can create your own sample calls to GEN_MAINT by creating
  1429.         file maintenance windows in BUILDER.
  1430.  
  1431. Sample:
  1432.         proc fmnt_exmpl
  1433.           ** proc to call a generic maintenance routine
  1434.           **
  1435.  
  1436.           m_trow=04
  1437.           m_tcol=30
  1438.           m_brow=12
  1439.           m_bcol=67
  1440.           sele TCSREPS
  1441.           do gen_maint with m_trow,m_tcol,m_brow,m_bcol,"REPS","Q_"
  1442.  
  1443.         ** screen SAY's for generic maint of sales rep file
  1444.         **
  1445.         proc gsays_reps
  1446.           @ m_trow+2,m_tcol+2 say "Sales Rep #:"
  1447.           @ m_trow+4,m_tcol+2 say "  Last Name:"
  1448.           @ m_trow+5,m_tcol+2 say " First Name:"
  1449.           @ m_trow+7,m_tcol+2 say "      Phone:"
  1450.  
  1451.         ** screen GET's for generic maint of sales rep file
  1452.         **
  1453.         proc ggets_REPS
  1454.           @ m_trow+2,m_tcol+15 get &g_pfx.SLS_NBR pict "9999"
  1455.           clear gets
  1456.           @ m_trow+4,m_tcol+15 get &g_pfx.LAST pict "@!"
  1457.           @ m_trow+5,m_tcol+15 get &g_pfx.FIRST pict "@!"
  1458.           @ m_trow+7,m_tcol+15 get &g_pfx.PHONE pict "@R (999) 999-9999"
  1459.  
  1460.         ** Function to edit data called after a screen is keyed but
  1461.         ** before the disk write
  1462.         **
  1463.         func gedit_REPS
  1464.           retu(.t.)
  1465.  
  1466.         ** key GET's for generic maint of division file
  1467.         **
  1468.         func gkey_REPS
  1469.           para gk_func  && A-Add, D-Del, C-Change
  1470.  
  1471.           winpush(m_brow-2,m_bcol-15,m_brow+3,m_bcol+09)
  1472.           message("Enter Sales Rep Number or Press ESC to Abort",24,00 ;
  1473.              ,80,bmsg_clr)
  1474.  
  1475.                                       <23>
  1476.                   The Aeolus Procedure and Function Library
  1477.                                 Reference Manual
  1478.  
  1479.  
  1480.  
  1481.           pcd=space(4)
  1482.           @ m_brow-1,m_bcol-13 say "Sales Rep #:" get pcd pict "9999"
  1483.           @ m_brow+1,m_bcol-13 say "Enter Sales Rep # Code"
  1484.           if gk_func<>"A"
  1485.             @ m_brow+2,m_bcol-13 say "Blank for Current Rec"
  1486.           else
  1487.             @ m_brow+2,m_bcol-13 say "to Add or ESC to Exit"
  1488.           endi
  1489.           read
  1490.           message("",24,00,80,bmsg_clr)
  1491.           winpop()
  1492.  
  1493.           &g_pfx.SLS_NBR=if(empty(pcd) .or. ; last-
  1494.           key()=27,&g_pfx.SLS_NBR,pcd)
  1495.           retu(pcd)
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.  
  1527.  
  1528.  
  1529.  
  1530.  
  1531.  
  1532.  
  1533.  
  1534.                                       <24>
  1535.                   The Aeolus Procedure and Function Library
  1536.                                 Reference Manual
  1537.  
  1538.  
  1539.  
  1540.         GOT()
  1541.  
  1542. Syntax:
  1543.         got(<expC>,<expN1>,<expN2>)
  1544.  
  1545. Pass:
  1546.         <expC>  database alias name
  1547.         <expN1> field number in database
  1548.         <expN2> record number of database
  1549.  
  1550. Returns:
  1551.         an expression of type determined by TYPE(FIELD(<expN1>)).
  1552.  
  1553. Description:
  1554.         Normally used in a valid function to pop up a scroll box and put
  1555.         the selected item in the READ field.
  1556.  
  1557.         <expC> is the database alias used for the look up, <expN1> is
  1558.         <expN1>th field in the database whose alias is <expC>.  <expN2>
  1559.         is the record number in that database, usually the POP() func-
  1560.         tion.
  1561.  
  1562.         The return value is whatever is the databases <expN1>th field at
  1563.         record <expN2>.
  1564.  
  1565. Sample:
  1566.         @ 12,34 say "Building # " get qbldg_nbr pict "!!!!" ;
  1567.           valid ckbldg()
  1568.         set cursor on
  1569.         read
  1570.  
  1571.         set cursor off
  1572.  
  1573.         *************************************************************
  1574.         *** valid function to check the existance of a building ID #
  1575.         **  and pop a scroll box up and allow selection if the keyed
  1576.         **  value is not found in the building file.
  1577.         **
  1578.         func ckbldg
  1579.  
  1580.           v=readvar()               && get READ var name
  1581.           p=&v                      && get its value
  1582.  
  1583.           if empty(p)               && allow a blank in this function
  1584.             retu(.t.)               && to be a valid entry
  1585.           endi
  1586.  
  1587.           of=select()               && old file select area
  1588.           or=recn()                 && old record (in case same file)
  1589.           ret_val=.t.               && default return value
  1590.  
  1591.           set softseek on
  1592.  
  1593.                                       <25>
  1594.                   The Aeolus Procedure and Function Library
  1595.                                 Reference Manual
  1596.  
  1597.  
  1598.  
  1599.           sele bldg
  1600.           seek p                    && look for it
  1601.           if !found()
  1602.  
  1603.             k_bldg=space(4)
  1604.             bldg_fld='bldg_nbr+" "+city'
  1605.             r=row()
  1606.             c=col()
  1607.             set cursor off
  1608.  
  1609.             ** display pop box at row()-1, col()+3 of the field being
  1610.             ** tested.
  1611.             ckv=got("BLDG",1,pop(r-1,c+3,6,25,"BLDG",bldg_fld,"",.t., ;
  1612.             .f.,"k_bldg"))
  1613.             set cursor on
  1614.             ret_val=.f.
  1615.             if !empty(ckv)                 && if a record was chosen
  1616.               &v=ckv                       && put it in the READ var
  1617.               keyboard chr(13)     && enter key will display entry
  1618.             endi
  1619.           endi
  1620.           sele (of)
  1621.           go or
  1622.           retu(ret_val)
  1623.  
  1624.  
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.                                       <26>
  1653.                   The Aeolus Procedure and Function Library
  1654.                                 Reference Manual
  1655.  
  1656.  
  1657.  
  1658.         ISEEK()
  1659.  
  1660. Syntax:
  1661.         iseek(<exp>[,<expC>][,<expN>][,<expL>])
  1662.  
  1663. Pass:
  1664.         <exp>  expression to SEEK
  1665.         <expC> database alias name, default is current select alias.
  1666.         <expN> index order number to use for SEEK command, default used
  1667.           is the current index order.
  1668.         <expL> .T. to use SOFTSEEK ON, .F. for SOFTSEEK OFF, default is
  1669.           the current SOFTSEEK setting.
  1670.  
  1671. Returns:
  1672.         a logical expression.
  1673.  
  1674. Description:
  1675.         The ISEEK() function does an indexed search of a database and
  1676.         returns the FOUND() condition.
  1677.  
  1678.         <exp> is the key value to search for, <expC> is the database
  1679.         alias to SELECT for the indexed search.  <expN> is the index
  1680.         order number to use in the search, if zero or not supplied the
  1681.         current index order is used.  <expL> to true to use 'softseek
  1682.         on' or false for 'soft-seek off', if <expL> is not passed the
  1683.         current SOFTSEEK setting is used.
  1684.  
  1685. Sample:
  1686.         ******************************************************
  1687.         ** ISEEK() function example
  1688.         **
  1689.         select 0
  1690.         use customer
  1691.         index on cust_nbr to cstmr1
  1692.         index on trim(lname)+" "+fname to cstmr2
  1693.         set index to cstmr1,cstmr2
  1694.  
  1695.         clea
  1696.         mcust_nbr=space(9)
  1697.         @ 1,1 say "Enter Customer Number" get mcust_nbr
  1698.         read
  1699.  
  1700.         if iseek(mcust_nbr,"CUSTOMER",1,.f.)
  1701.           @ 2,1 say "Customer Number Found."
  1702.         endi
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.                                       <27>
  1712.                   The Aeolus Procedure and Function Library
  1713.                                 Reference Manual
  1714.  
  1715.  
  1716.  
  1717.         LSIDE         
  1718.         The LSIDE procedure is called by the TOTALKEYON and TOTALKEYOFF
  1719.         procedures only and should not be used otherwise.  Please see
  1720.         the TOTALKEYON and TOTALKEYOFF procedures for additional infor-
  1721.         mation.  This is included only for completness.
  1722.  
  1723.  
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.  
  1737.  
  1738.  
  1739.  
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.                                       <28>
  1771.                   The Aeolus Procedure and Function Library
  1772.                                 Reference Manual
  1773.  
  1774.  
  1775.  
  1776.         MAKE_EMPTY()
  1777.  
  1778. Syntax:
  1779.         make_empty(<expC>)
  1780.  
  1781. Pass:
  1782.         <expC> existing memory variable name
  1783.  
  1784. Returns:
  1785.         an expression of TYPE(<expC>).
  1786.  
  1787. Description:
  1788.         The memory variable name <expC> is returned in its empty form. A
  1789.         character variable is spaces the length of the passed variable,
  1790.         a numeric is returned as zero, etc.
  1791.  
  1792. Sample:
  1793.         ******************************************************
  1794.         *** Make empty function example
  1795.         ***
  1796.  
  1797.         tst_dat=date()
  1798.         ? make_empty("TST_DAT")     && same as ctod("  /  /  ")
  1799.         tst_nbr=998
  1800.         ? make_empty("TST_NBR")     && same as 0 (zero)
  1801.         tst_chr="Software Can be Groovy"
  1802.         ? make_empty("TST_CHR")     && same as space(22)
  1803.  
  1804.  
  1805.  
  1806.  
  1807.  
  1808.  
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.                                       <29>
  1830.                   The Aeolus Procedure and Function Library
  1831.                                 Reference Manual
  1832.  
  1833.  
  1834.  
  1835.         MAXHNDLS()
  1836.  
  1837. Syntax:
  1838.         maxhndls([<expN>)
  1839.  
  1840. Pass:
  1841.         Zero/nothing or a numeric expression
  1842.  
  1843. Returns:
  1844.         If zero or nothing is passed MAXHNDLS() returns the smaller of
  1845.         the CONFIG.SYS FILES= number or the CLIPPER Fnnn file handles.
  1846.         If a number is passed MAXHNDLS return true if the number of file
  1847.         handles in the system configuration is equal or greater, other-
  1848.         wise MAXHNDLS() returns false.  If false is to be returned
  1849.         MAXHNDLS() will display an error box before returning.
  1850.  
  1851. Description:
  1852.         Allows a Clipper program to determine the number of available
  1853.         file handles in the current system configuration.
  1854.  
  1855.         Also displays errors if fewer than <expN> file handles are pre-
  1856.         sent in the current configuration.
  1857.  
  1858.  
  1859.  
  1860.  
  1861.  
  1862.  
  1863.  
  1864.  
  1865.  
  1866.  
  1867.  
  1868.  
  1869.  
  1870.  
  1871.  
  1872.  
  1873.  
  1874.  
  1875.  
  1876.  
  1877.  
  1878.  
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.  
  1888.                                       <30>
  1889.                   The Aeolus Procedure and Function Library
  1890.                                 Reference Manual
  1891.  
  1892.  
  1893.  
  1894.         MESSAGE()
  1895.  
  1896. Syntax:
  1897.         message(<expC1>,<expN1>,<expN2>[,<expN3>][,<expC2>])
  1898.  
  1899. Pass:
  1900.         <expC1> text to display on the screen
  1901.         <expN1> row to display
  1902.         <expN2> column to display
  1903.         <expN3> length to pad/truncate message text
  1904.         <expC2> alternate color choice
  1905.  
  1906. Returns:
  1907.         Nothing.
  1908.  
  1909. Description:
  1910.         The MESSAGE() function places <expC1> on the screen at row
  1911.         <expN1> column <expN2> and pads <expC1> (or trims it) to a
  1912.         length of <expN3>.  <expC2> may be used as an alternate color
  1913.         choice. If <expN3> is not used, the LEN(<expC1>) is used
  1914.         instead.  If <expC2> is not passed, the current color is used.
  1915.  
  1916. Sample:
  1917.         ***********************************************************
  1918.         *** MESSAGE function example.
  1919.         ***
  1920.  
  1921.         message("Test Message 1",01,00,80,"+w/b")
  1922.         inkey(0)
  1923.  
  1924.  
  1925.  
  1926.  
  1927.  
  1928.  
  1929.  
  1930.  
  1931.  
  1932.  
  1933.  
  1934.  
  1935.  
  1936.  
  1937.  
  1938.  
  1939.  
  1940.  
  1941.  
  1942.  
  1943.  
  1944.  
  1945.  
  1946.  
  1947.                                       <31>
  1948.                   The Aeolus Procedure and Function Library
  1949.                                 Reference Manual
  1950.  
  1951.  
  1952.  
  1953.         MSGBOX()
  1954.  
  1955. Syntax:
  1956.         msgbox(<expC1>[,<expC2>][,<expC3>][,<expC4>][,<expN1>]
  1957.         [,<expN2>][,<expN3>][,<expN4>])
  1958.  
  1959. Pass:
  1960.         <expC1> message for line one
  1961.         <expC2> alternate color choice
  1962.         <expC3> message for line two - input prompt
  1963.         <expC4> character list for allowable input (null ("") for 
  1964.           any key)
  1965.         <expN1> top left row
  1966.         <expN2> top left column
  1967.         <expN3> bottom right row
  1968.         <expN4> bottom right column
  1969.  
  1970. Returns:
  1971.         nothing or a character expression depending on the value of
  1972.         <expC4>.
  1973.  
  1974. Description:
  1975.         This function puts a message box on the screen and waits for an
  1976.         acknowledgment.
  1977.  
  1978.         If only <expC1> is passed as an arguement a box is centered on
  1979.         the screen sized to fit <expC1> inside.  The message is dis-
  1980.         played in bright yellow with a red background by default, useful
  1981.         for error messages.
  1982.  
  1983.         Pass <expC2> as an alternate color choice.
  1984.  
  1985.         <expC3> and <expC4> usually work together, <expC3> is a prompt
  1986.         and <expC4> is a list of characters that, when entered from the
  1987.         keyboard, will remove the box from the screen.
  1988.  
  1989.         <expC4> need only contain one of each alphabetic character as it
  1990.         is converted to upper case before being used by MSGBOX().
  1991.  
  1992.         <expN1> and <expN2> are optional row and column screen positions
  1993.         for the box.
  1994.  
  1995.         <expN3> and <expN4> may be passed to optionally size the box.
  1996.  
  1997.  
  1998.  
  1999.  
  2000.  
  2001.  
  2002.  
  2003.  
  2004.  
  2005.  
  2006.                                       <32>
  2007.                   The Aeolus Procedure and Function Library
  2008.                                 Reference Manual
  2009.  
  2010.  
  2011.  
  2012. Sample:
  2013.         *********************************************************
  2014.         *** MSGBOX function example
  2015.         ***
  2016.  
  2017.         msgbox("Error Message")
  2018.         msgbox("Information Message","+w/b")
  2019.         if msgbox("Do You Play the Piano?","+w/b","Press Y or N", ;
  2020.         "YN",10,5)="Y"
  2021.         msgbox("You Pressed Yes","+w/b")
  2022.         else
  2023.         msgbox("You Pressed No","+w/b")
  2024.         endi
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.  
  2054.  
  2055.  
  2056.  
  2057.  
  2058.  
  2059.  
  2060.  
  2061.  
  2062.  
  2063.  
  2064.  
  2065.                                       <33>
  2066.                   The Aeolus Procedure and Function Library
  2067.                                 Reference Manual
  2068.  
  2069.  
  2070.  
  2071.         NET_USE()
  2072.  
  2073. Syntax:
  2074.         net_use(<expC1>,<expL>,<expN>,<expC2>)
  2075.  
  2076. Pass:
  2077.         <expC1> database alias name
  2078.         <expL>  .T. for exclusive open, .F. for shared
  2079.         <expN>  error timeout seconds if cannot be opened
  2080.         <expC2> alias to use when file is opened
  2081.  
  2082. Returns:
  2083.         a logical expression.
  2084.  
  2085. Description:
  2086.         Opens the database <expC1> in exclusive mode if <expL> is true
  2087.         or non-exclusive if <expL> is false.  If <expN> is the seconds
  2088.         before an error timeout.  <expC2> is the alias that will be
  2089.         used.
  2090.  
  2091. Comment:
  2092.         It is suggested that you use the OPEN_FIL procedure instead of
  2093.         the NET_USE() function, as it automatically handles error condi-
  2094.         tions and parameter passing is more convienient.
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.  
  2119.  
  2120.  
  2121.  
  2122.  
  2123.  
  2124.                                       <34>
  2125.                   The Aeolus Procedure and Function Library
  2126.                                 Reference Manual
  2127.  
  2128.  
  2129.  
  2130.         NUMERIC()
  2131.  
  2132. Syntax:
  2133.         numeric(<expC>)
  2134.  
  2135. Pass:
  2136.         <expC> a string that may or may not contain all numerics
  2137.  
  2138. Returns:
  2139.         a logical expression.
  2140.  
  2141. Description:
  2142.         This function scans every character in <expC> and if every
  2143.         charcter is between '0' and '9' then it returns true, otherwise
  2144.         false is returned.
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152.  
  2153.  
  2154.  
  2155.  
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.                                       <35>
  2184.                   The Aeolus Procedure and Function Library
  2185.                                 Reference Manual
  2186.  
  2187.  
  2188.  
  2189.         OPEN_FIL()
  2190.  
  2191. Syntax:
  2192.         do open_fil with <expC1>[,<expL1>][,<expC2>][,<expL2>]
  2193.  
  2194. Returns:
  2195.         a logical expression.
  2196.  
  2197. Pass:
  2198.         <expC1> database name to open
  2199.         <expL1>  .T. for shared open, nothing or .F. for exclusive open
  2200.         <expC2> alias name when open, if other than database name
  2201.         <expL2> .T. to exit to DOS on open errors, .F. to return false
  2202.                 on open errors.
  2203.  
  2204. Description:
  2205.         The OPEN_FIL function will attempt to open the file <expC1> in
  2206.         exclusive mode-even if SET EXCLUSIVE OFF is in effect-unless the
  2207.         second parameter is sent as true.  Use the third parameter to
  2208.         set the alias if you want the alias other than the default of
  2209.         <expC1>.  <expL2> determines how the OPEN_FIL function will react
  2210.         when it cannot open a .DBF file, passing .T. (or not passing this
  2211.         parameter) will cause OPEN_FIL to exit to DOS on error conditions.
  2212.         Passing <expL2> as .F. will cause OPEN_FIL to return a logical 
  2213.         false if it fails to open the file.
  2214.  
  2215.         The OPEN_FIL function tests for four (4) error conditions.  If an
  2216.         error is detected, an error box is displayed and OPEN_FIL either
  2217.         exits to DOS or returns false to the application depending on the
  2218.         value of <expL2>.  The errors tested for are as follows:
  2219.  
  2220.         1.  Invalid Alias Name.  If no specific alias name is sent to
  2221.             the OPEN_FIL function the file name (<expC1>) is used.  A
  2222.             valid alias name must contain the letter 'A' through 'Z' in the
  2223.             first character position.  The second through tenth character
  2224.             positions can contain 'A' through 'Z', '0' through '9' or '_'.
  2225.  
  2226.         2.  File not found.  Before a database is USEd OPEN_FIL tests the
  2227.             the Clipper FILE() function to determine if the file exists.
  2228.  
  2229.         3.  Already in Use.  The database is already USEd in EXCLUSIVE mode
  2230.             or the file has been locked.
  2231.  
  2232.         4.  .DBT file is missing.  OPEN_FIL tried to USE a database but the
  2233.             memo field data file (.DBT file) is missing.
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.                                       <36>
  2243.                   The Aeolus Procedure and Function Library
  2244.                                 Reference Manual
  2245.  
  2246.  
  2247.  
  2248.         PADC()
  2249.  
  2250. Syntax:
  2251.         padc(<expC1>,<expN>[,<expC2])
  2252.  
  2253. Pass:
  2254.         <expC1> text to pad/truncate
  2255.         <expN>  length of returned string
  2256.         <expC2> fill character, default is space
  2257.  
  2258. Returns:
  2259.         a character expression.
  2260.  
  2261. Description:
  2262.         This function pads or trims <expC1> to a length of <expN> using
  2263.         <expC2> as the fill character.  PADC() returns a centered
  2264.         character string.
  2265.  
  2266.  
  2267.  
  2268.  
  2269.  
  2270.  
  2271.  
  2272.  
  2273.  
  2274.  
  2275.  
  2276.  
  2277.  
  2278.  
  2279.  
  2280.  
  2281.  
  2282.  
  2283.  
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.                                       <37>
  2302.                   The Aeolus Procedure and Function Library
  2303.                                 Reference Manual
  2304.  
  2305.  
  2306.  
  2307.         PADL()
  2308.  
  2309. Syntax:
  2310.         padl(<expC1>,<expN>[,<expC2])
  2311.  
  2312. Pass:
  2313.         <expC1> text to pad/truncate
  2314.         <expN>  length of returned string
  2315.         <expC2> fill character, default is space
  2316.  
  2317. Returns:
  2318.         a character expression.
  2319.  
  2320. Description:
  2321.         This function pads or trims <expC1> to a length of <expN> using
  2322.         <expC2> as the fill character.  PADL() returns a right justified
  2323.         character string.
  2324.  
  2325.  
  2326.  
  2327.  
  2328.  
  2329.  
  2330.  
  2331.  
  2332.  
  2333.  
  2334.  
  2335.  
  2336.  
  2337.  
  2338.  
  2339.  
  2340.  
  2341.  
  2342.  
  2343.  
  2344.  
  2345.  
  2346.  
  2347.  
  2348.  
  2349.  
  2350.  
  2351.  
  2352.  
  2353.  
  2354.  
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.                                       <38>
  2361.                   The Aeolus Procedure and Function Library
  2362.                                 Reference Manual
  2363.  
  2364.  
  2365.  
  2366.         PADR()
  2367.  
  2368. Syntax:
  2369.         padr(<expC1>,<expN>[,<expC2])
  2370.  
  2371. Pass:
  2372.         <expC1> text to pad/truncate
  2373.         <expN>  length of returned string
  2374.         <expC2> fill characte, default is space
  2375.  
  2376. Returns:
  2377.         a character expression.
  2378.  
  2379. Description:
  2380.         This function pads or trims <expC1> to a length of <expN> using
  2381.         <expC2> as the fill character.  PADR() returns a left justified
  2382.         character string.
  2383.  
  2384.  
  2385.  
  2386.  
  2387.  
  2388.  
  2389.  
  2390.  
  2391.  
  2392.  
  2393.  
  2394.  
  2395.  
  2396.  
  2397.  
  2398.  
  2399.  
  2400.  
  2401.  
  2402.  
  2403.  
  2404.  
  2405.  
  2406.  
  2407.  
  2408.  
  2409.  
  2410.  
  2411.  
  2412.  
  2413.  
  2414.  
  2415.  
  2416.  
  2417.  
  2418.  
  2419.                                       <39>
  2420.                   The Aeolus Procedure and Function Library
  2421.                                 Reference Manual
  2422.  
  2423.  
  2424.  
  2425.         POP()
  2426.  
  2427. Syntax:
  2428.         pop(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2> ;
  2429.         [,<expL>][,<expC3>][,<expC4>][,<expC5>][,<expC6>]
  2430.  
  2431. Pass:
  2432.         <expN1> top left row for picklist box
  2433.         <expN2> top left column for picklist box
  2434.         <expN3> picklist height in rows
  2435.         <expN4> picklist width in columns
  2436.         <expC1> database alias name
  2437.         <expC2> expression to display on each picklist line
  2438.         <expL>  enable QWERTY scroll function, default false.
  2439.         <expC3> memvar for QWERTY scroll initialization (prefix with @)
  2440.         <expC4> color for pointer bar, if not using WREV_CLR
  2441.         <expC5> procedure to execute on ENTER key
  2442.         <expC6> database fieldname for bounded picklist
  2443.  
  2444. Returns:
  2445.         a numeric expression.  The record number selected.
  2446.  
  2447. Description:
  2448.         The POP() function creates a scrollable pick list box to be pre-
  2449.         sented on the screen.
  2450.  
  2451.         <expN1> and <expN2> are the row and column of the upper left
  2452.         corner of the pick list box.
  2453.  
  2454.         <expN3> and <expN4> are the height and width of the box respec-
  2455.         tively
  2456.  
  2457.         <expC1> is the database alias to 'browse'.
  2458.  
  2459.         When <expC2> is evaluated as a macro it is displayed on each
  2460.         line in the box.
  2461.  
  2462.         If <expL> is passed as true then a field delimited with square
  2463.         brackets will be placed on the top of the box.  Any QWERTY text
  2464.         entered will be displayed between the brackets and that text
  2465.         will change the data displayed in the box to use that as the key
  2466.  
  2467.         Warning:  Do not set <expL> to true if you are going to use
  2468.         <expC6>
  2469.  
  2470.         <expC3> is used in conjunction with <expL> and contains the name
  2471.         of the memory variable that contains the starting key value to
  2472.         be placed between the square brackets.  If you choose to set
  2473.         <expL> to true and not use this argument the QWERTY area will be
  2474.         sized according to the length of the INDEXKEY(0) function.
  2475.  
  2476.         <expC4> is an optional color for the pointer bar.
  2477.  
  2478.                                       <40>
  2479.                   The Aeolus Procedure and Function Library
  2480.                                 Reference Manual
  2481.  
  2482.  
  2483.  
  2484.  
  2485.         <expC5> is an optional (strongly reccomended) name of a proce-
  2486.         dure to be executed on selection of an element.
  2487.  
  2488.         Warning:  <expC5> can only contain the procedure name and cannot
  2489.         contain a 'WITH' clause or parameters.
  2490.  
  2491.         <expC6> is an optional fieldname that will restrict scrolling
  2492.         only while the fieldname passed is equal to the value on entry
  2493.         into the POP() function.  The database must be sorted or indexed
  2494.         so that the passed fieldname will have the same value for a con-
  2495.         tiguous series of records.
  2496.  
  2497.         Warning:  <expC6> can only be use if <expL> is set to false.
  2498.  
  2499. Sample:
  2500.         *****************************************************
  2501.         * This example displays a pick list box at row 2
  2502.         * column 40, it is 9 rows tall and 23 columns wide.
  2503.         * It displays the field COUNTRY from the database
  2504.         * INTRNTNL and provides the user a field to enter QWERTY
  2505.         * text to move to different parts of the database.
  2506.         * If a record is selected the procedure INTL_DTL is executed.
  2507.  
  2508.         sele intrntnl
  2509.         go top
  2510.  
  2511.         ** display international
  2512.         **
  2513.         sele intrntnl
  2514.         kf=space(20)
  2515.  
  2516.         intl_rec=pop(02,40,9,23,"INTRNTNL","country","",.t., ;
  2517.         @KF,"","intl_dtl")
  2518.  
  2519.         Sample2:
  2520.         *****************************************************
  2521.         * This example displays a pick list box at row 2
  2522.         * column 19, it is 9 rows tall and 20 columns wide.
  2523.         * It displays the fields PART_NBR and PART_END from the
  2524.         * database MSPART.
  2525.         * If a record is selected the procedure MS_DETAIL is executed.
  2526.  
  2527.         k_part_nbr=space(8)
  2528.  
  2529.         sele mspart
  2530.         go top
  2531.  
  2532.         ** display part list
  2533.         **
  2534.         sele mspart
  2535.         kf="K_PART_NBR"
  2536.  
  2537.                                       <41>
  2538.                   The Aeolus Procedure and Function Library
  2539.                                 Reference Manual
  2540.  
  2541.  
  2542.  
  2543.  
  2544.         ms_fld='if(empty(part_nbr),space(17),part_nbr+"-"+part_end)'
  2545.  
  2546.         prt_rec=pop(02,19,9,20,"MSPART",ms_fld,"",.t.,,"","", ;
  2547.         "ms_detail")
  2548.  
  2549.  
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.  
  2558.  
  2559.  
  2560.  
  2561.  
  2562.  
  2563.  
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.  
  2579.  
  2580.  
  2581.  
  2582.  
  2583.  
  2584.  
  2585.  
  2586.  
  2587.  
  2588.  
  2589.  
  2590.  
  2591.  
  2592.  
  2593.  
  2594.  
  2595.  
  2596.                                       <42>
  2597.                   The Aeolus Procedure and Function Library
  2598.                                 Reference Manual
  2599.  
  2600.  
  2601.  
  2602.         POP_KEY       
  2603.  
  2604.         The POP_KEY procedure is called by the POP() function only and
  2605.         should not be used otherwise.  Please see the POP() function for
  2606.         additional information.  This is included only for completness.
  2607.  
  2608.  
  2609.  
  2610.  
  2611.  
  2612.  
  2613.  
  2614.  
  2615.  
  2616.  
  2617.  
  2618.  
  2619.  
  2620.  
  2621.  
  2622.  
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.  
  2630.  
  2631.  
  2632.  
  2633.  
  2634.  
  2635.  
  2636.  
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644.  
  2645.  
  2646.  
  2647.  
  2648.  
  2649.  
  2650.  
  2651.  
  2652.  
  2653.  
  2654.  
  2655.                                       <43>
  2656.                   The Aeolus Procedure and Function Library
  2657.                                 Reference Manual
  2658.  
  2659.  
  2660.  
  2661.         PUBL_COLO
  2662.  
  2663. Syntax:
  2664.         do publ_colo
  2665.  
  2666. Pass:
  2667.         Nothing
  2668.  
  2669. Description:
  2670.         The BUILDER executes this procedure in the initialization of all
  2671.         the programs it creates.  This procedure creates several public
  2672.         variables and initializes them for use by the program.
  2673.  
  2674.         The initialized variables are:
  2675.  
  2676.         HDR_CLR   screen header box color
  2677.         HDR_MSG   header message color
  2678.         BKGD_CLR  screen background color
  2679.         BMSG_CLR  background message color
  2680.         BERR_CLR  background error color
  2681.         BREV_CLR  background reverse color
  2682.  
  2683.         WNDW_CLR  window color
  2684.         WMSG_CLR  window message color
  2685.         WERR_CLR  window error color
  2686.         WREV_CLR  window reverse color
  2687.  
  2688.         WNDW2_CLR secondary window color
  2689.         WMSG2_CLR secondary window message color
  2690.  
  2691.         SHDW_CLR  shadow color
  2692.         ERR_CLR   error box color
  2693.         MSG_CLR   message line color
  2694.  
  2695.         Most of these are modifiable using the Color option of the
  2696.         BUILDER main menu.
  2697.  
  2698.  
  2699.  
  2700.  
  2701.  
  2702.  
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.  
  2712.  
  2713.  
  2714.                                       <44>
  2715.                   The Aeolus Procedure and Function Library
  2716.                                 Reference Manual
  2717.  
  2718.  
  2719.  
  2720.         REC_LOCK()
  2721.  
  2722. Syntax:
  2723.         rec_lock(<expN>)
  2724.  
  2725. Pass:
  2726.         <expN> seconds before error timeout, pass zero to never timeout.
  2727.  
  2728. Returns:
  2729.         A logical expression.
  2730.  
  2731. Description:
  2732.         Attempts to lock lock the record of the currently selected data-
  2733.         base for timeout period of <expN> seconds.  If the record cannot
  2734.         be locked after the timeout period an error box is presented to
  2735.         try again, if No is selected, a logical false is returned.  If
  2736.         <expN> is zero or not passed to the function, REC_LOCK() will
  2737.         wait indefinately.
  2738.  
  2739. Comment:
  2740.         The SAVE_IT() function performs all record locking before any
  2741.         file I/O and you should not have to use this function.
  2742.  
  2743.         However...
  2744.         some shops require that a record is locked during editting and
  2745.         all the functions and procedures here only lock a record immedi-
  2746.         ately before any file I/O so you may need to use this function.
  2747.  
  2748.  
  2749.  
  2750.  
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.  
  2767.  
  2768.  
  2769.  
  2770.  
  2771.  
  2772.  
  2773.                                       <45>
  2774.                   The Aeolus Procedure and Function Library
  2775.                                 Reference Manual
  2776.  
  2777.  
  2778.  
  2779.         REL_MAINT
  2780.  
  2781. Syntax:
  2782.         DO REL_MAINT WITH <expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ;
  2783.             <expC2>,<expC3>,<expC4>,<expN5>,<expN6>
  2784.  
  2785. Pass:
  2786.         <expN1> The row number to put the Add/Change/Delete menu,
  2787.                 usually the top border of the window.
  2788.         <expN2> The column number for the Add/Change/Delete menu,
  2789.                 yes, you calculate to center it.
  2790.         <expN3> The row number for messages, usually the bottom line
  2791.                 of the box, not the border but inside the box.
  2792.         <expN4> The column number for messages, usually two spaces to
  2793.                 the right of the left window border.
  2794.         <expC1> You must declare a procedure that contains the GETs for
  2795.                 the maintenance the first three letters of which must 
  2796.                 be 'GET'.  Pass in <expC1> the characters you add to
  2797.                 make the procedure unique.
  2798.         <expC2> The condition that relates the file to be editted, this
  2799.                 must be a logical true when evaluated as a macro.  All
  2800.                 contigious records where the condition remains true
  2801.                 will be available for editting.
  2802.  
  2803.                 Note: The SET RELATION TO ... command does NOT need to
  2804.                 be in effect to use this procedure, the databases merely
  2805.                 need to have a one to many relationship.
  2806.         <expC3> Database alias name to be editted.
  2807.         <expC4> Memory variable prefix character(s).
  2808.         <expN5> The 'delete index' order number, zero (0) if a 'delete
  2809.                 index' is not used.
  2810.         <expN6> The number of fields to be editted.
  2811.  
  2812. Description:
  2813.         The REL_MAINT procedure is used to edit the 'many' records in
  2814.         the child database when a one-to-many database relationship
  2815.         exists.
  2816.  
  2817.         This procedure is designed to be easily created from a BUILDER
  2818.         dialog box.
  2819.  
  2820.         If you are unsure what a 'delete index' is refer to the
  2821.         GEN_MAINT procedure for clarification.
  2822.  
  2823.         Look carefully at the following sample to see how to set up a
  2824.         REL_MAINT call.
  2825.  
  2826. Sample:
  2827.         ** note: prior to calling rel_maint all fields in the database 
  2828.         ** have been copied to memory variables with identical names
  2829.         ** except the memory variables (in this example) are prefixed
  2830.         ** with the letter "Q".  See DBPUBL, DBSTOR for more info.
  2831.  
  2832.                                       <46>
  2833.                   The Aeolus Procedure and Function Library
  2834.                                 Reference Manual
  2835.  
  2836.  
  2837.  
  2838.  
  2839.         ************************************************
  2840.         ** CALLED BY: Pick List Window Proc:  PLST003 **
  2841.         **   Comment: Model Maint Dialog              **
  2842.         ************************************************
  2843.         proc dlog004
  2844.           private dr1,dc1,dr2,dc2
  2845.  
  2846.           ** save key to a memory variable
  2847.           ** important you code something like this!
  2848.           rpartno=model->partno
  2849.  
  2850.           dr1=15
  2851.           dc1=45
  2852.           dr2=dr1+04
  2853.           dc2=dc1+32
  2854.           set colo to (wndw_clr)
  2855.           winpush(dr1,dc1,dr2,dc2)
  2856.           @ dr1+02,dc1+04 say "Model Number"
  2857.  
  2858.           ** call rel_maint to edit all contigious records in the MODEL
  2859.           ** database with the field MODEL->PARTNO equal to the memory
  2860.           ** variable RPARTNO.
  2861.           do rel_maint with ;
  2862.             dr1,dc1+6,dr2-1,dc1+2,"004","MODEL->PARTNO=RPARTNO", ;
  2863.               "MODEL","Q",2,1
  2864.           winpop()
  2865.  
  2866.  
  2867.         ** this proc created by copying the GETs created by BUILDER to
  2868.         ** a proc with the first three characters equal to "GET", I
  2869.         ** arbitrarily chose "004" as the second part of the name (
  2870.         ** because it matches DLOG004) and pass "004" as the fifth
  2871.         ** parameter above.
  2872.         proc get004
  2873.  
  2874.           ** absolutely IMPERATIVE the key variables get set from
  2875.           ** previously saved memory variables here!!
  2876.           qpartno=rpartno
  2877.  
  2878.           @ dr1+02,dc1+18 get qmodel pict "@!"
  2879.  
  2880.  
  2881.         Not including the comments only four lines of code were added to
  2882.         a BUILDER dialog box to create this (many more were deleted).
  2883.         This is a small example, but should clearly show how to set up a
  2884.         REL_MAINT of your own.
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.                                       <47>
  2892.                   The Aeolus Procedure and Function Library
  2893.                                 Reference Manual
  2894.  
  2895.  
  2896.  
  2897.         RSIDE 
  2898.  
  2899.         The RSIDE procedure is called by the TOTALKEYON and TOTALKEYOFF
  2900.         procedures only and should not be used otherwise.  Please see
  2901.         the TOTALKEYON and TOTALKEYOFF procedures for additional infor-
  2902.         mation.  This is only included for completness.
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.  
  2910.  
  2911.  
  2912.  
  2913.  
  2914.  
  2915.  
  2916.  
  2917.  
  2918.  
  2919.  
  2920.  
  2921.  
  2922.  
  2923.  
  2924.  
  2925.  
  2926.  
  2927.  
  2928.  
  2929.  
  2930.  
  2931.  
  2932.  
  2933.  
  2934.  
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.  
  2941.  
  2942.  
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.                                       <48>
  2951.                   The Aeolus Procedure and Function Library
  2952.                                 Reference Manual
  2953.  
  2954.  
  2955.  
  2956.         SAVE_IT()
  2957.  
  2958. Syntax:
  2959.         save_it(<expC1>,<expC2>,<expN>,<expC3>)
  2960.  
  2961. Pass:
  2962.         <expC1> "ADD", "CHG" or "DEL" only
  2963.         <expC2> memory variable prefix character(s)
  2964.         <expN>  fast delete index order number
  2965.         <expC3> database alias name
  2966.  
  2967. Returns:
  2968.         a logical expression.
  2969.  
  2970. Description:
  2971.         The SAVE_IT() function will add, change or delete the current
  2972.         record from the database <expC3>.  The SAVE_IT() function uses
  2973.         file locking if the memory variable NETWORK is set to true.  The
  2974.         <expC1> argument must be equal to "ADD", "CHG" or "DEL" to tell
  2975.         SAVE_IT() to add, change or delete a record.  <expC2> is the
  2976.         character or characters the field variables are prefixed with to
  2977.         create the memory variables (See the DBPUBL and DBSTOR proce-
  2978.         dures).  Use <expN> to pass the order number of the "fast
  2979.         delete" index order number created like:
  2980.  
  2981.         INDEX ON IF(DELE(),"*"," ") TO ...
  2982.  
  2983.         Send <expN> as zero (0) if you are not using a "fast delete". If
  2984.         the NETWORK memory variable is set to true and the SAVE_IT()  
  2985.         function cannot lock the requested record and the user replies
  2986.         "No" to try the lock again, then the SAVE_IT() function will
  2987.         return false.
  2988.  
  2989. Sample:
  2990.         *************************************************************
  2991.         *** SAVE_IT() function example
  2992.         ***
  2993.  
  2994.         select 0
  2995.         use customer inde cust1,cust2
  2996.         do dbpubl with "Q"           && setup memvars
  2997.         do dbstor with "Q","EMPTY"   && set original values
  2998.         ** cust1 indexed on cust_nbr
  2999.         ** cust2 indexed on if(dele(),"*"," ")
  3000.  
  3001.         . change memvars to values for new record
  3002.         .
  3003.  
  3004.         if !save_it("ADD","Q",2,"CUSTOMER")
  3005.           msgbox("ERROR--RECORD NOT ADDED !")
  3006.           return
  3007.         endi
  3008.  
  3009.                                       <49>
  3010.                   The Aeolus Procedure and Function Library
  3011.                                 Reference Manual
  3012.  
  3013.  
  3014.  
  3015.  
  3016.         SHADOW()
  3017.  
  3018. Syntax:
  3019.         shadow(<expN1>,<expN2>,<expN3>,<expN4>)
  3020.  
  3021. Pass:
  3022.         <expN1> top left row
  3023.         <expN2> top left column
  3024.         <expN3> bottom right row
  3025.         <expN4> bottom right column
  3026.  
  3027. Description:
  3028.         Places a shadow on the area bounded by the four passed coordi-
  3029.         nates, where <expN1> and <expN2> are the upper left row and col-
  3030.         umn coordinates and <expN3> and <expN4> are the lower right.
  3031.  
  3032. Comment:
  3033.         the WINPUSH procedure uses this function to place a shadow on
  3034.         the window it creates.  You therefore should not have to use
  3035.         this function.
  3036.  
  3037.  
  3038.  
  3039.  
  3040.  
  3041.  
  3042.  
  3043.  
  3044.  
  3045.  
  3046.  
  3047.  
  3048.  
  3049.  
  3050.  
  3051.  
  3052.  
  3053.  
  3054.  
  3055.  
  3056.  
  3057.  
  3058.  
  3059.  
  3060.  
  3061.  
  3062.  
  3063.  
  3064.  
  3065.  
  3066.  
  3067.  
  3068.                                       <50>
  3069.                   The Aeolus Procedure and Function Library
  3070.                                 Reference Manual
  3071.  
  3072.  
  3073.  
  3074.         THERMOMETR()
  3075.  
  3076. Syntax:
  3077.         thermometr(<expN1>,<expN2>,<expN3>,<expN4>)
  3078.  
  3079. Pass:
  3080.         <expN1> thermometer length
  3081.         <expN2> start value of operation (i.e. 0%)
  3082.         <expN3> maximum value of operation (i.e. 100%)
  3083.         <expN4> current value, must be between <expN2> and <expN3>
  3084.  
  3085. Returns:
  3086.         a character expression.
  3087.  
  3088. Description:
  3089.         The THERMOMETR() function is used to display the progress of
  3090.         iterative program activity graphically.  The <expN1> argument is
  3091.         the length you want your thermometer, <expN2> is the number of
  3092.         the starting position of your process, <expN3> is the ending
  3093.         position and <expN4> is the current position.
  3094.  
  3095. Sample:
  3096.         ***************************************************************
  3097.         ** THERMOMETR() function example
  3098.         **
  3099.  
  3100.         select trnsctn
  3101.         go top
  3102.  
  3103.         strt=recno()
  3104.         end=reccount()
  3105.         width=40
  3106.         othm=" "            && old thermometer for comparison
  3107.  
  3108.         do whil !eof()
  3109.         thm=thermometr(width,strt,end,recno())
  3110.         if thm <> othm        && only display changes
  3111.           @ 1,0 say thm
  3112.           othm=thm
  3113.         endi
  3114.  
  3115.         .
  3116.         .
  3117.         .
  3118.  
  3119.         skip
  3120.         endd
  3121.  
  3122.  
  3123.  
  3124.  
  3125.  
  3126.  
  3127.                                       <51>
  3128.                   The Aeolus Procedure and Function Library
  3129.                                 Reference Manual
  3130.  
  3131.  
  3132.  
  3133.         TOTALKEYON/TOTALKEYOFF
  3134.  
  3135. Syntax:
  3136.         do totalkeyon
  3137.         do totalkeyoff
  3138.  
  3139. Description:
  3140.         Sets up the left and right arrow keys to jump from one drop down
  3141.         menu to the menu under the right or left.
  3142.  
  3143. Comment:
  3144.         The BUILDER program creates the source with TOTALKEYON and
  3145.         TOTALKEYOFF aleady called at the proper places and you should
  3146.         not need to use this procedure.
  3147.  
  3148.  
  3149.  
  3150.  
  3151.  
  3152.  
  3153.  
  3154.  
  3155.  
  3156.  
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.  
  3174.  
  3175.  
  3176.  
  3177.  
  3178.  
  3179.  
  3180.  
  3181.  
  3182.  
  3183.  
  3184.  
  3185.  
  3186.                                       <52>
  3187.                   The Aeolus Procedure and Function Library
  3188.                                 Reference Manual
  3189.  
  3190.  
  3191.  
  3192.         WAITKEY()
  3193.  
  3194. Syntax:
  3195.         waitkey([<expN>])
  3196.  
  3197. Pass:
  3198.         <expN> timeout seconds
  3199.  
  3200. Returns:
  3201.         a numeric expression.
  3202.  
  3203. Description:
  3204.         Use WAITKEY() as a substitute for the Clipper INKEY(<expN>)
  3205.         function.  The only difference between the two is that WAITKEY()
  3206.         will react to any SET KEY TO ... 's you have set.  Not passing
  3207.         the parameter or passing zero (the default) will cause WAITKEY()
  3208.         to wait until a key is pressed with no timeout.
  3209.  
  3210.  
  3211.  
  3212.  
  3213.  
  3214.  
  3215.  
  3216.  
  3217.  
  3218.  
  3219.  
  3220.  
  3221.  
  3222.  
  3223.  
  3224.  
  3225.  
  3226.  
  3227.  
  3228.  
  3229.  
  3230.  
  3231.  
  3232.  
  3233.  
  3234.  
  3235.  
  3236.  
  3237.  
  3238.  
  3239.  
  3240.  
  3241.  
  3242.  
  3243.  
  3244.  
  3245.                                       <53>
  3246.                   The Aeolus Procedure and Function Library
  3247.                                 Reference Manual
  3248.  
  3249.  
  3250.  
  3251.         WINPOP()
  3252.  
  3253. Syntax:
  3254.         winpop()
  3255.  
  3256. Pass:
  3257.         Nothing
  3258.  
  3259. Returns:
  3260.         A logical value, true if there was something removed from the
  3261.         screen.
  3262.  
  3263. Description:
  3264.         The WINPOP() function removes the last window on the screen that
  3265.         was created by the WINPUSH function.
  3266.  
  3267.         See WINPUSH() for examples.
  3268.  
  3269.  
  3270.  
  3271.  
  3272.  
  3273.  
  3274.  
  3275.  
  3276.  
  3277.  
  3278.  
  3279.  
  3280.  
  3281.  
  3282.  
  3283.  
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.  
  3296.  
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.                                       <54>
  3305.                   The Aeolus Procedure and Function Library
  3306.                                 Reference Manual
  3307.  
  3308.  
  3309.  
  3310.         WINPUSH()
  3311.  
  3312. Syntax:
  3313.         winpush(<expN1>,<expN2>,<expN3>,<expN4>[,<expL1>] ;
  3314.         [,<expL2>][,<expL3>][,<expL4>])
  3315.  
  3316. Pass:
  3317.         <expN1> top left row
  3318.         <expN2> top left column
  3319.         <expN3> bottom right row
  3320.         <expN4> bottom right column
  3321.         <expL1> save the screen area before displaying, default true
  3322.         <expL2> clear the interior of the box, default true
  3323.         <expL3> display the box with a border, default true
  3324.         <expL4> display the box with a shadow, default true
  3325.  
  3326. Returns:
  3327.         A logical value, if the window was successfully displayed, true
  3328.         is returned.
  3329.  
  3330. Description:
  3331.         The WINPUSH function saves the portion of the screen bounded the
  3332.         coordinates <expN1> through <expN4> with <expN1> and <expN2>
  3333.         being the upper left row and column positions and <expN3> and
  3334.         <expN4> the lower right corner positions and draws a box on the
  3335.         screen in the default color.
  3336.  
  3337.         All four of the logical expressions that can optionally be
  3338.         passed have a default value of true.
  3339.  
  3340.         If <expL1> is true the screen area bounded by the passed screen
  3341.         coordinates is saved to the screen array otherwise if set to
  3342.         false it cannot be WINPOPed.
  3343.  
  3344.         <expL2> if set to true will clear the box interior otherwise
  3345.         only the border, if any, is displayed.  The default it true.
  3346.  
  3347.         <expL3> if set to true will display a double border on the box.
  3348.  
  3349.         <expL4> controls the shadow on the box, if set to true a shadow
  3350.         is displayed.
  3351.  
  3352.         Note:  If the variable XPLODE is a logical variable set to true
  3353.         the WINPUSH function will explode the window onto the screen.
  3354.  
  3355. Sample:
  3356.         **************************************************************
  3357.         *** WINPUSH/WINPOP sample code
  3358.         ***
  3359.  
  3360.         ** put a window on the screen
  3361.         **     saving the area so it can be WINPOPed,
  3362.  
  3363.                                       <55>
  3364.                   The Aeolus Procedure and Function Library
  3365.                                 Reference Manual
  3366.  
  3367.  
  3368.  
  3369.         **     clearing the inside of the window when displayed,
  3370.         **     put double border charcters on the window,
  3371.         **     and put a shadow on the window.
  3372.  
  3373.         winpush(05,10,17,60)
  3374.         @ 07,12 say "My Window to the World."
  3375.         inkey(0)
  3376.  
  3377.         ** remove window, and shadow.
  3378.               winpop()
  3379.  
  3380.  
  3381.  
  3382.  
  3383.  
  3384.  
  3385.  
  3386.  
  3387.  
  3388.  
  3389.  
  3390.  
  3391.  
  3392.  
  3393.  
  3394.  
  3395.  
  3396.  
  3397.  
  3398.  
  3399.  
  3400.  
  3401.  
  3402.  
  3403.  
  3404.  
  3405.  
  3406.  
  3407.  
  3408.  
  3409.  
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416.  
  3417.  
  3418.  
  3419.  
  3420.  
  3421.  
  3422.                                       <56>
  3423.