home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / dos / prg / builder / libs87.doc < prev    next >
Text File  |  1994-10-26  |  155KB  |  6,373 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,1993 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. Aeolus Software
  53. P.O. Box 11915
  54. St. Paul, MN  55111-0915
  55.  
  56. Mark H. Kania, CIS# 76270,2436
  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..................................................8
  72.         ADD_REC..................................................9
  73.         ASK......................................................10
  74.         APOP.....................................................11 ^^
  75.         BETWEEN..................................................13
  76.         BROWSER..................................................14
  77.         CENTER...................................................15
  78.         CHGDIR...................................................16 * ++
  79.         CHGDSK...................................................17 * ++
  80.         CHKCHR...................................................18 ++
  81.         CKPRTR...................................................20
  82.         CRSR_STATE...............................................21 * ++
  83.         DBCHANGED................................................22 ++
  84.         DBPUBL...................................................23
  85.         DBREPL...................................................24
  86.         DBSTATE..................................................25 ++
  87.         DBSTOR...................................................26
  88.         DEC2HEX..................................................27 ++
  89.         DRVTST...................................................28 * ++
  90.         DUPCHK...................................................29 ++
  91.         EDT_MEMO.................................................31 ++
  92.         ERRTONE..................................................32 ^^
  93.         ETC......................................................33 ++
  94.         FEOF.....................................................34
  95.         FGETS....................................................35
  96.         FGETSR...................................................36 ++
  97.         FIL_LOCK.................................................37
  98.         FLD_REPL.................................................38
  99.         GEN_MAINT................................................39 ^^
  100.         GENVLD...................................................43 ++
  101.         GOT......................................................44 ||
  102.         HEX2DEC..................................................46 ++
  103.         IN_CANADA................................................47 ++
  104.         IN_USA...................................................48 ++
  105.         INFILE...................................................49 ++
  106.         INPATH...................................................50 ++
  107.         ISEEK....................................................51
  108.         LSIDE....................................................52 ||
  109.         MAKE_EMPTY...............................................53 ||
  110.         MAKDIR...................................................54 * ++
  111.         MAXHNDLS.................................................55
  112.         MEM_HELP.................................................56 ++
  113.         MEMFUNC..................................................57 ++
  114.         MESSAGE..................................................58
  115.         MSGBOX...................................................59 ^^
  116.         NET_USE..................................................61 ||
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.                                TABLE OF CONTENTS
  125.  
  126.  
  127.  
  128.         NOT_REQ..................................................62 ++
  129.         NUMERIC..................................................63
  130.         OPEN_FIL.................................................64
  131.         PADC.....................................................65
  132.         PADL.....................................................66
  133.         PADR.....................................................67
  134.         PCKVLD...................................................68 ++
  135.         PLIST....................................................70
  136.         POP......................................................74 ^^
  137.         POP_KEY..................................................77
  138.         PUBL_COLO................................................78
  139.         REC_LOCK.................................................79
  140.         REL_MAINT................................................80 ^^
  141.         REQ......................................................83 ++
  142.         RGHT_JST.................................................84 ++
  143.         RSIDE....................................................85 ||
  144.         SAVE_IT..................................................86
  145.         SETMSGLIN................................................88 ++
  146.         SHADOW...................................................89
  147.         SHOW_MEMO................................................90 ++
  148.         SHOW_TXT.................................................91 ++
  149.         TEXTVIEW.................................................93 ++
  150.         THERMOMETR...............................................96
  151.         TIMEOUT..................................................97 * ++
  152.         TOTALKEYON/TOTALKEYOFF...................................101 ||
  153.         WAITKEY..................................................102
  154.         WINPOP...................................................103
  155.         WINPUSH..................................................104
  156.  
  157.         * These functions are located in BLDRASM.LIB.
  158.  
  159.         WARNING:
  160.         Do NOT link BLDRASM into an overlay as some of the routines take
  161.         over system interrupts and if these routines are in an overlay
  162.         your computer will lock up.  That is why it is in a separate
  163.         LIB.
  164.  
  165.         ++ These functions are new to BUILDER.LIB v2.0.
  166.         ^^ These functions are updated from the last release.
  167.         || These functions are copied from the book "Programming in
  168.            Clipper" 2nd Edition by Stephen J. Straley (use by permis-
  169.            sion)
  170.  
  171.         I would also like to highly recommend Steves's new book "Clip-
  172.         per Power Tools" from Sirius Software I comes with a diskette of
  173.         indispensable Clipper routines.
  174.  
  175.  
  176.  
  177.  
  178.                   The Aeolus Procedure and Function Library
  179.                             Reference Manual
  180.  
  181.  
  182.  
  183.         Conventions used in this guide:
  184.         <expC>:  A character expression
  185.         <expL>:  A logical expression (i.e. .t. or .f.)
  186.         <expD>:  A date expression
  187.         <expN>:  A numeric expression, a number or calculation
  188.         <expA>:  An array name
  189.         <exp>:   An expression that may be of any type
  190.         <expB>:  A binary expression.
  191.  
  192.  
  193.         Parameters notated inside square brackets ([]) are optional par-
  194.         ameters, defaults will be given where applicable.
  195.  
  196.  
  197.  
  198.         Many BUILDER library procedures and functions use one or more
  199.         system wide memory variables.  These variables must be declared
  200.         in the initialization of ALL programs which use this library.
  201.         Fortunately the BUILDER code generator does this for you, but if
  202.         you would like to code from scratch and use the library be sure
  203.         these variables exist before using any library proce-
  204.         dures/functions:
  205.  
  206.         SYSDEL   - Logical if set to true tells the library that SET
  207.                    DELETED is ON.  If false OFF.
  208.         XPLODE   - Logical if set to true tells the WINPUSH() function
  209.                    to explode your windows onto the screen.  If false
  210.                    windows 'pop' onto screen.
  211.         MSG_LN   - Numeric, the line number where messages are displayed,
  212.                    should always be set to 24.
  213.         NETWORK  - Logical if set to true opens files in shared mode and
  214.                    locks records before writing to files.  If false
  215.                    files are opened EXCLUSIVE.
  216.  
  217.         The 15 color variables - See the PUBL_COLO procedure for their
  218.         names.
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.                                   <1>
  237.                   The Aeolus Procedure and Function Library
  238.                             Reference Manual
  239.  
  240.  
  241.  
  242.         Alphabetical Proc/Func summary
  243.  
  244.         ASC2BIN(<expC>)
  245.           Converts ASCII control indicators to control characters.
  246.  
  247.        *ADD_REC(<expN>)
  248.           Adds a blank .DBF record.
  249.  
  250.         ASK(<expC1>,<expC2>,<expN1>,<expN2>[,<expN3>][,<expC3>] ;
  251.         [,<expC4>])
  252.           Prompt function.
  253.  
  254.         APOP(<expN1>,<expN2>,<expN3>,<expN4>,<expA>,<expN5>,<expC1>[<exp-
  255.         C2>][,<expC3>])
  256.           Choose multiple menu items from array.
  257.  
  258.         BETWEEN(<exp1>,<exp2>,<exp3>)
  259.           Evaluates if expression 1 is greater than and equal to expres-
  260.           sion 2 and less than and equal to expression 3
  261.  
  262.         BROWSER WITH
  263.         <expN1>,<expN2>,<expN3>,<expN4>[,<expC>][,<expN5>][,<expN6>]
  264.           Sets up window to browse a database
  265.  
  266.         CENTER(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>])
  267.           Centers text on the screen or within a window.
  268.  
  269.         CALL CHGDIR WITH <expC>
  270.           Changes the DOS default directory.
  271.  
  272.         CALL CHGDSK WITH <expC>
  273.           Changes the DOS default drive.
  274.  
  275.         VALID CHKCHR(<expC1>,<expC2>,<expN1>,<expN2>,<expN3>[,<expC3>])
  276.           VALID, tests if keyed input is in <expC1>.
  277.  
  278.         CKPRTR(<expN>)
  279.           Checks if parallel printer is available.
  280.  
  281.         CRSR_STATE()
  282.           Returns true if a SET CURSOR ON is in effect, false if SET
  283.           CURSOR OFF is in effect.
  284.  
  285.         DBCHANGED(<expC>)
  286.           Returns true if database fields do not exactly match memory
  287.           variables.
  288.  
  289.         DBPUBL WITH <expC>
  290.           Creates public memory variables from database field variables.
  291.  
  292.         DBREPL WITH <expC>
  293.           Replaces database field variables with memory variables.
  294.  
  295.                                   <2>
  296.                   The Aeolus Procedure and Function Library
  297.                             Reference Manual
  298.  
  299.  
  300.  
  301.  
  302.         DBSTATE([<expC1>])
  303.           Returns all relevant database info in a string, sets back to
  304.           a previous DBSTATE() also.
  305.  
  306.         DBSTOR WITH <expC>
  307.           Stores database field variables to memory variables.
  308.  
  309.         DEC2HEX(<expN>)
  310.           Returns a Hexadecimal string of the passed integer.
  311.  
  312.         CALL DRVTST WITH <expC1>,<expC2>
  313.           Tests a disk drive and returns a DOS error code.
  314.  
  315.         VALID DUPCHK(<expC1>,<expC2>,<expN1>,<expC3>,<expN2>,<expN3>, ;
  316.             <expN4>,<expL>,<expC4>)
  317.           VALID function to test for a duplicate condition for the keyed
  318.           input.
  319.  
  320.         EDT_MEMO(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2>,<expC3>, ;
  321.             <expC5>,<expC6>[,<expN5>][,<expL>]
  322.           Either stand alone or VALID function to display/edit a Memo field
  323.           inside a border.
  324.  
  325.         ERRTONE([<expN>])
  326.           Beep speaker with optional sounds.
  327.  
  328.         ETC(<expC>,<expN1>,<expN2>,<expN3>)
  329.           Calculate estimated time to complete an iterative process.
  330.  
  331.         FEOF([<expL>])
  332.           Use when reading a .SDF file with FGETS().
  333.  
  334.         FGETS(<expN>)
  335.           Returns next record in a .SDF type file.
  336.  
  337.         FGETSR(<expN>)
  338.           Returns the previous record in a .SDF type file.
  339.  
  340.         FIL_LOCK(<expN>)
  341.           Locks a file for exclusive type activity.
  342.  
  343.         FLD_REPL WITH <expC1>,<expC2>
  344.           Replace one database field in a shared or single user
  345.           environment.
  346.  
  347.        *GEN_MAINT WITH ;
  348.         <expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2>[,<expN5>] ;
  349.         [,<expN6>][,<expL>]
  350.           Generic file maintenance.
  351.  
  352.         GENVLD(<expL1>,<expC1>,<expN1>,<expN2>,<expN3>,<expL2>[,<expC2>])
  353.  
  354.                                   <3>
  355.                   The Aeolus Procedure and Function Library
  356.                             Reference Manual
  357.  
  358.  
  359.  
  360.           VALID generic function to test a user defined condition on
  361.           a GET.
  362.  
  363.         GOT(<expC>,<expN1>,<expN2>)
  364.           Get field data from a database record number and field number.
  365.  
  366.         HEX2DEC(<expC>)
  367.           Converts a string of Hexadecimal characters to a numeric integer.
  368.  
  369.         IN_CANADA(<expC>)
  370.           Returns true if the passed two byte string is a valid Canadian
  371.           province code.
  372.  
  373.         IN_USA(<expC>)
  374.           Returns true if the passed two byte string is a valid U.S. state
  375.           code.
  376.  
  377.         INFILE(<expC1>,<expN1>,<expC2>,<expN2>,<expN3>,<expN4>,<expL>
  378.             [,<expC3>])
  379.           VALID function to only force data entered into a GET field
  380.           to be found in another file.
  381.  
  382.         INPATH(<expC1>[,<expC2>])
  383.           Returns the pathname where <expC1> is located.  Checks directories
  384.           listed in DOS environment variable PATH or <expC2> if passed.
  385.  
  386.         ISEEK(<exp>,<expC>,<expN>,<expL>)
  387.           Locate a record in a database via an index.
  388.  
  389.        *LSIDE
  390.           left arrow logic for drop down menu scrolling.
  391.  
  392.         CALL MAKDIR WITH <expC>
  393.           Makes a DOS subdirectory.
  394.  
  395.         MAKE_EMPTY(<expC>)
  396.           Create an empty memory variable based on the passed variable.
  397.  
  398.        *MAXHNDLS(<expN>)
  399.           Tests system configuration for number of file handles.
  400.  
  401.        *MEM_HELP
  402.           Procedure called when F1 key is pressed during when user is
  403.           editing a Memo field through the EDT_MEMO() function.
  404.  
  405.        *MEMFUNC(<expN1>,<expN2>,<expN3>)
  406.           Function executed on every key press while editing a Memo
  407.           field through SHOW_MEMO or EDT_MEMO().
  408.  
  409.         MESSAGE(<expC1>,<expN1>,<expN2>[,<expN3>][,<expC2>])
  410.           Display a screen message.
  411.  
  412.  
  413.                                   <4>
  414.                   The Aeolus Procedure and Function Library
  415.                             Reference Manual
  416.  
  417.  
  418.  
  419.         MSGBOX(<expC1>[,<expC2>][,<expC3>][,<expC4>][,<expN1>] ;
  420.         [,<expN2>][,<expN3>][,<expN4>])
  421.           Display a message box on the screen, optionally ask a ques-
  422.           tion.
  423.  
  424.        *NET_USE(<expC1>,<expL>,<expN>,<expC2>)
  425.           Network file open function.
  426.  
  427.         NOT_REQ(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>])
  428.           VALID function to force a GET field to be empty.
  429.  
  430.         NUMERIC(<expC>)
  431.           Check a character string for any non-numeric characters.
  432.  
  433.         OPEN_FIL(<expC1>[,<expL1>][,<expC2>][,<expL2>])
  434.           All purpose file open routine.
  435.  
  436.         PADC(<expC1>,<expN>[,<expC2>])
  437.           Pad a character string to the middle, centering it.
  438.  
  439.         PADL(<expC1>,<expN>[,<expC2>])
  440.           Pad a character string to the left, right justify it.
  441.  
  442.         PADR(<expC1>,<expN>[,<expC2>])
  443.           Pad a character string to the right, left justify it.
  444.  
  445.         PCKVLD(<expC1>,<expN1>,<expN2>,<expL1>,<expC2>,<expL2> ;
  446.             [,<expC3>][,<expC4>])
  447.           VALID function to force entry into a GET field to be
  448.           in another database.  Gives user a pick list of the
  449.           nearest data to what was keyed.
  450.  
  451.         PLIST(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expN5>,<expC1>, ;
  452.         <expC2>[,<expL1>][,<expC3>][,<expC4>][,<expC5>][,<expC6>])
  453.           New picklist window function.
  454.  
  455.         POP(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2>[,<expL1>] ;
  456.         [,<expC3>][,<expC4>][,<expC5>][,<expC6>])
  457.           Pick list window function.
  458.  
  459.        *PUBL_COLO
  460.           Sets default color variables.
  461.  
  462.        *REC_LOCK(<expN>)
  463.           Record lock function.
  464.  
  465.         REL_MAINT WITH <expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ;
  466.                <expC2>,<expC3>,<expC4>,<expN5>,<expN6>
  467.           Child relation file maintenance.
  468.  
  469.         REQ(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>])
  470.           VALID function to force a GET field to not be empty.
  471.  
  472.                                   <5>
  473.                   The Aeolus Procedure and Function Library
  474.                             Reference Manual
  475.  
  476.  
  477.  
  478.  
  479.         RGHT_JST([<expC>])
  480.           VALID function to right justify input to a GET field.
  481.  
  482.        *RSIDE
  483.           right arrow logic for drop down menu scrolling.
  484.  
  485.         SAVE_IT(<expC1>,<expC2>,<expN>,<expC3>)
  486.           All purpose file I/O routine.
  487.  
  488.         SETMSGLIN([<expC>])
  489.           Function to Get/Set the application message line.
  490.  
  491.        *SHADOW(<expN1>,<expN2>,<expN3>,<expN4>)
  492.           Puts a shadow on a box.
  493.  
  494.         SHOW_MEMO WITH <expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ;
  495.             <expL>[,<expC2>][,<expN5>]
  496.           Display/Edit a Memo field without a border or message line
  497.           or title.
  498.  
  499.         SHOW_TXT(<exp>,<expN1>,<expN2>,<expN3>[,<expC>])
  500.           VALID function to display data after input from a GET.
  501.  
  502.         TEXTVIEW WITH <expN1>,<expN2>,<expN3>,<expN4>,<expC1>[,<expC2>]
  503.           Display a text file.
  504.  
  505.         THERMOMETR(<expN1>,<expN2>,<expN3>,<expN4>)
  506.           Creates a thermometer to show the progress of a routine.
  507.  
  508.         CALL TIMEOUT WITH <expB1>,<expB2>,<expC>
  509.           Set up an application timeout if idle for a passed length
  510.           of time.  Also changes the cursor to a block if in insert
  511.           mode and underline when not.
  512.  
  513.        *TOTALKEYON/TOTALKEYOFF
  514.           Enables/Disables drop down menu right and left scrolling.
  515.  
  516.         WAITKEY([<expN>])
  517.           Works like INKEY(0) but allows SET KEY TO ...'s to be pro-
  518.           cessed.
  519.  
  520.         WINPOP()
  521.           Remove a window from the screen create with WINPUSH.
  522.  
  523.         WINPUSH(<expN1>,<expN2>,<expN3>,<expN4>[,<expL1>] ;
  524.         [,<expL2>][,<expL3>][<expL4>])
  525.           Put a window on the screen, may be saved for later removal.
  526.  
  527.         * Procedures and functions preceded by an asterisk (*) are
  528.         either dealt with entirely by BUILDER generated code or are
  529.         called by another library function.  You will probably never
  530.  
  531.                                   <6>
  532.                   The Aeolus Procedure and Function Library
  533.                             Reference Manual
  534.  
  535.  
  536.  
  537.         need to use these and are included only for the sake of
  538.         completeness.
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.                                   <7>
  591.                   The Aeolus Procedure and Function Library
  592.                             Reference Manual
  593.  
  594.  
  595.  
  596.         ASC2BIN()
  597.  
  598. Syntax:
  599.         ASC2BIN(<expC>)
  600.  
  601. Pass:
  602.         <expC> string with control character expressions embedded.
  603.  
  604. Returns:
  605.         Character expression.  The converted string.
  606.  
  607. Description:
  608.         The ASC2BIN() function converts a character expression that con-
  609.         tains one or more caret (^) symbols followed by a character to
  610.         it's 'control' or binary value.  Use this function for creating
  611.         printer control strings.  For example :
  612.                 c=ASC2BIN("^A")  && caps important
  613.                 ? asc(c)         && would display 1 -- ASCII for
  614.                                  && control A
  615.  
  616. Sample:
  617.         ***********************************************
  618.         ** print a message on a laser printer in
  619.         ** landscape using HP escape sequence
  620.  
  621.         prtrt="^[&l0O"           && caret, left bracket (escape),
  622.                                  && ampersand, lower case L, zero,
  623.                                  && upper case O
  624.         lndscp="^[&l1O"          && caret, left bracket (escape),
  625.                                  && ampersand, lower case L, one,
  626.                                  && upper case O
  627.         set print on
  628.         ?? asc2bin(lndscp) && set printer to landscape
  629.         ? "This text printed using landscape."
  630.         ?? asc2bin(prtrt)  && set printer back to portrait
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.                                   <8>
  650.                   The Aeolus Procedure and Function Library
  651.                             Reference Manual
  652.  
  653.  
  654.  
  655.         ADD_REC()
  656.  
  657. Syntax:
  658.         add_rec(<expN>)
  659.  
  660. Pass:
  661.         <expN> seconds until timeout, zero for no timeout.
  662.  
  663. Returns:
  664.         a logical expression.
  665.  
  666. Description:
  667.         Attempts to add a blank record to the currently selected data-
  668.         base for timeout period of <expN> seconds.  If a record cannot
  669.         be added after the timeout period an error box is presented to
  670.         try again, if No is selected, a logical false is returned.  If
  671.         <expN> is zero or not passed to the function, ADD_REC() will
  672.         wait indefinitely.
  673.  
  674. Comment:
  675.         This function is called by the SAVE_IT() function therefore it
  676.         should never need to be used by you in a program, use the
  677.         SAVE_IT() function to do file I/O instead.  It is  included here
  678.         only for completeness.
  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.                                   <9>
  709.                   The Aeolus Procedure and Function Library
  710.                             Reference Manual
  711.  
  712.  
  713.  
  714.         ASK()
  715.  
  716. Syntax:
  717.         ASK(<expC1>,<expC2>,<expN1>,<expN2>[,<expN3>][,expC3][,<expC4>])
  718.  
  719. Pass:
  720.         <expC1> prompt text.
  721.         <expC2> list of acceptable input characters.
  722.         <expN1> row for prompt.
  723.         <expN2> column for prompt.
  724.         <expN3> pad prompt to length.
  725.         <expC3> alternate color.
  726.         <expC4> "ESC" to allow ESC key.
  727.  
  728. Returns:
  729.         Character expression.  The keyboard character pressed.
  730.  
  731. Description:
  732.         <expC1> will be displayed at row <expN1> and column <expN2>.
  733.         ASK() will wait until any keyboard character contained in the
  734.         list <expC2> is pressed.
  735.  
  736.         <expC2> may be passed in upper or lower case, ASK() does not
  737.         distinguish.  If you pass "YN" either a lower or upper case 'Y'
  738.         key press will return an upper case "Y" from ASK().  Also if you
  739.         pass "yn" either a lower or upper case 'Y'key press will return
  740.         an upper case "Y".
  741.  
  742.         <expN3> spaces will be displayed before the message in <expC1>
  743.         to clear previous text, optional.  default is the length of
  744.         <expC1>.
  745.  
  746.         <expC3> is color to display <expC1>.  Default is current color.
  747.  
  748.         If <expC4> is equal to "ESC" then ASK() can be exited using the
  749.         ESC key.  If the ESC key is used to exit ASK() a null string
  750.         will be passed to the calling procedure.  The default is to not
  751.         allow ESCaping.
  752.  
  753.  
  754. Sample:
  755.         *****************************************************
  756.         **  display the question on line 24 column 0 and pad
  757.         **  the text to 80 characters.  Wait until a Y or N
  758.         **  is pressed on the keyboard.
  759.  
  760.         answer=ask("Do You Wish to Continue? (Y/N)","YN",24,0,80)
  761.  
  762.         ** the character variable "answer" will equal either "Y"
  763.         ** or "N" depending on what the key is pressed.
  764.  
  765.  
  766.  
  767.                                   <10>
  768.                   The Aeolus Procedure and Function Library
  769.                             Reference Manual
  770.  
  771.  
  772.  
  773.         APOP()
  774.  
  775. Syntax:
  776.         apop(<expN1>,<expN2>,<expN3>,<expN4>,<expA>,<expN5> ;
  777.         [,<expC1>][,<expC2][,<expC3>])
  778.  
  779. Pass:
  780.         <expN1> top left row.
  781.         <expN2> top left column.
  782.         <expN3> bottom right row.
  783.         <expN4> bottom right column.
  784.         <expA>  array name (prefixed with @).
  785.         <expN5> max element to show.
  786.         <expC1> procedure name to execute.
  787.         <expC2> alternate color choice.
  788.         <expC3> alternate reverse color choice.
  789.  
  790. Returns:
  791.         Nothing.
  792.  
  793. Description:
  794.         The APOP() function will put a box on the screen using <expN1>
  795.         through <expN4> as screen coordinates and allow you to scroll
  796.         through elements 1 to <expN5> of the array <expA>.  When a
  797.         selection is made by pressing the 'T' key will Tag that element
  798.         and display it bounded by bracket characters (« »). Pressing
  799.         ENTER will either execute the procedure <expC1> or exit APOP().
  800.         <expC2> is an optional color value, <expC3> is an alternate
  801.         reverse color option.  Defaults for <expC2> and <expC3> are the
  802.         current colors.
  803.  
  804.         Upon return from APOP() check the first character of each array
  805.         element for chr(174) for tagged elements.
  806.  
  807. Sample:
  808.         ********************************************************
  809.         ** APOP() example code to allow the selection of multiple
  810.         ** names from a list and then display the selected items.
  811.         **
  812.         declare names[10]        && declare array
  813.         names[01]="Rosalind  "   && initialize array
  814.         names[02]="Mark "
  815.         names[03]="John      "
  816.         names[04]="Lisa      "
  817.         names[05]="Denise    "
  818.         names[06]="Jeff      "
  819.         names[07]="Frank     "
  820.         names[08]="Joe       "
  821.         names[09]="Cathy     "
  822.         names[10]="Jerry     "
  823.  
  824.         ** call APOP()
  825.  
  826.                                   <11>
  827.                   The Aeolus Procedure and Function Library
  828.                             Reference Manual
  829.  
  830.  
  831.  
  832.         apop(05,05,13,18,@names,10,"PRT_NMES")
  833.  
  834.  
  835.         ** the bracket character -chr(174)- is left on the array
  836.         ** elements that have been selected, so if it is in the
  837.         ** first character position, that element was selected by
  838.         ** the user
  839.  
  840.         procedure prt_nmes
  841.           set print on
  842.           set console off
  843.           for a=1 to 10
  844.             if left(names[a],1)=chr(174)
  845.               ? trim(subs(names[a],2))+" was selected."
  846.             endi
  847.           next
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.                                   <12>
  886.                   The Aeolus Procedure and Function Library
  887.                             Reference Manual
  888.  
  889.  
  890.  
  891.         BETWEEN()
  892.  
  893. Syntax:
  894.         between(<exp1>,<exp2>,<exp3>)
  895.  
  896. Pass:
  897.         <exp1> value to test.
  898.         <exp2> minimum value.
  899.         <exp3> maximum value.
  900.  
  901. Returns:
  902.         a logical expression.
  903.  
  904. Description:
  905.         A logical true will be returned if <exp1> is greater than and
  906.         equal to <exp2> and less than and equal to <exp3>.  The argu-
  907.         ments passed to the BETWEEN()  function may be of type Character,
  908.         Numeric or Date; however all three arguments must be the same
  909.         data type.
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.                                   <13>
  945.                   The Aeolus Procedure and Function Library
  946.                             Reference Manual
  947.  
  948.  
  949.  
  950.         BROWSER
  951.  
  952. Syntax:
  953.         do browser with <expN1>,<expN2>,<expN3>,<expN4>[,<expC>] ;
  954.         [,<expN5>][,<expN6>]
  955.  
  956. Pass:
  957.         <expN1> top left row.
  958.         <expN2> top left column.
  959.         <expN3> bottom right row.
  960.         <expN4> bottom right column.
  961.         <expC>  key exception function name.
  962.         <expN5> start field number.
  963.         <expN6> end field number.
  964.  
  965. Description:
  966.         The BROWSER procedure will "browse" the currently selected data-
  967.         base using the Clipper DBEDIT() function.  <expN1> through
  968.         <expN4> define the coordinates of the box that will be dis-
  969.         played, <expC> is the user defined function executed on each key
  970.         press.  <expN5> and <expN6> are the start and end field numbers
  971.         (i.e. the FCOUNT() number) to browse.  If <expN5> is not passed
  972.         the first field will be browsed.  If <expN6> is not passed the
  973.         <expN5>th through FCOUNT() fields will be browsed.
  974.  
  975.         For more information on using the <expC> user defined function
  976.         consult your Clipper manual on the DBEDIT() function.  <expC> is
  977.         merely passed to DBEDIT() as the UDF for each key press.
  978.  
  979. Sample:
  980.         ******************************************************
  981.         ** BROWSER sample call
  982.         **
  983.         select 0
  984.         use customer
  985.         do browser with 5,3,17,73
  986.  
  987.         ** this will put a box on the screen from row 5 column 3 to row
  988.         ** 17 column 73 and browse all the fields in the database
  989.         ** CUSTOMER.
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.                                   <14>
  1004.                   The Aeolus Procedure and Function Library
  1005.                             Reference Manual
  1006.  
  1007.  
  1008.  
  1009.         CENTER()
  1010.  
  1011. Syntax:
  1012.         center(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2])
  1013.  
  1014. Pass:
  1015.         <expC1> message to display.
  1016.         <expN1> row to begin centering computation.
  1017.         <expN2> column to begin centering computation.
  1018.         <expN3> length for centering computation.
  1019.         <expC2> alternate color.
  1020.  
  1021. Returns:
  1022.         Start column of centered text.
  1023.  
  1024. Description:
  1025.         The CENTER() function displays <expC1> on row <expN1> column
  1026.         <expN2> centered within a width <expN3> wide. <expC2> is an
  1027.         alternate color choice.  The default color is the current from
  1028.         the last SET COLOR TO ... statement.
  1029.  
  1030. Sample:
  1031.         ****************************************************
  1032.         ** CENTER() function example
  1033.         **
  1034.         ** put a box on the screen
  1035.         winpush(5,5,15,45)
  1036.  
  1037.         ** center text in the box
  1038.         center("Yoo Hoo, I'm Centered",7,16,29)
  1039.  
  1040.         inkey(0)
  1041.         ** remove box
  1042.         winpop()
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.                                   <15>
  1063.                   The Aeolus Procedure and Function Library
  1064.                             Reference Manual
  1065.  
  1066.  
  1067.  
  1068.         CHGDIR
  1069.  
  1070. Syntax:
  1071.         call chgdir with <expC>
  1072.  
  1073. Pass:
  1074.         <expC> - a DOS subdirectory name on the current drive.
  1075.  
  1076. Returns:
  1077.         Nothing.
  1078.  
  1079. Description:
  1080.         The CHGDIR assembly subroutine simply attempts to change to the
  1081.         subdirectory named in the passed parameter <expC>. No error
  1082.         checking is done and nothing is passed back as a return value.
  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.                                   <16>
  1122.                   The Aeolus Procedure and Function Library
  1123.                             Reference Manual
  1124.  
  1125.  
  1126.  
  1127.         CHGDSK
  1128.  
  1129. Syntax:
  1130.         call chgdsk with <expC>
  1131.  
  1132. Pass:
  1133.         <expC> - A single byte of the disk drive letter to set
  1134.                  as the new default drive.
  1135.  
  1136. Returns:
  1137.         Nothing.
  1138.  
  1139. Description:
  1140.         The CHGDSK assembly subroutine simply attempts to change the
  1141.         default DOS disk drive to the passed drive letter parameter
  1142.         <expC>.  No error checking is done and nothing is passed back as
  1143.         a return value.
  1144.  
  1145.  
  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.                                   <17>
  1181.                   The Aeolus Procedure and Function Library
  1182.                             Reference Manual
  1183.  
  1184.  
  1185.  
  1186.         CHKCHR()
  1187.  
  1188. Syntax:
  1189.         chkchr(<expC1>,<expC2>,<expN1>,<expN2>,<expN3>,[<expC3>])
  1190.  
  1191. Pass:
  1192.         <expC1> - A list of allowable entry data into the GET.
  1193.         <expC2> - Error message on entry of non-allowable data.
  1194.         <expN1> - Row for error message to display.
  1195.         <expN2> - Column for error message display.
  1196.         <expN3> - Rightmost column for error message display.
  1197.         <expC3> - Optional color for error message.  default
  1198.                   WERR_CLR.
  1199.  
  1200. Returns:
  1201.         A logical expression.
  1202.  
  1203. Description:
  1204.         This function is designed to be use as a VALID function to a GET
  1205.         only.  It will test if the data keyed into the GET is embedded
  1206.         in the <expC1> string.  If it is the GET is allowed otherwise an
  1207.         error beep is sounded and the error message <expC2> is displayed
  1208.         at screen row <expN1> column <expN2> and will be padded or trun-
  1209.         cated to screen column <expN3>.  If <expC3> is passed as a par-
  1210.         ameter the error message will be display using it as the color
  1211.         value otherwise the color contained in the public memory vari-
  1212.         able WERR_CLR will be used.
  1213.  
  1214. Samples:
  1215.  
  1216.         ** QTYPE is a one byte variable with allowable values of 1, 2, or 3
  1217.         ** only.  Use CHKCHR() to force a 1, 2, or 3 into this field like
  1218.         ** this ...
  1219.         qtype=" "
  1220.         @ dr1+02,dc1+21 get qtype pict "9" valid ;
  1221.             chkchr("123","1, 2, 3 Only Allowed",dr2-1,dc1+2,dc2-2)
  1222.         set cursor on
  1223.         read
  1224.         set cursor off
  1225.  
  1226.  
  1227.  
  1228.         ** Same example, but allow QTYPE to be blank.  Just add a
  1229.         ** space as an allowable character in the list!
  1230.         qtype=" "
  1231.         @ dr1+02,dc1+21 get qtype pict "9" valid ;
  1232.             chkchr(" 123","1, 2, 3 or Blank Only",dr2-1,dc1+2,dc2-2)
  1233.         set cursor on
  1234.         read
  1235.         set cursor off
  1236.  
  1237.  
  1238.  
  1239.                                   <18>
  1240.                   The Aeolus Procedure and Function Library
  1241.                             Reference Manual
  1242.  
  1243.  
  1244.  
  1245.         If QTYPE (or whatever field) is more than one character long, be
  1246.         sure to use a separator between allowable field values.
  1247.  
  1248.         ** QTYPE2 allowable values are "EA" for Each,  "PK" for
  1249.         ** Package, or "WT" for Weight.
  1250.         ** You can use CHKCHR() in the following manner to
  1251.         ** force the field QTYPE2 to be one of these values...
  1252.         qtype2="  "
  1253.         @ dr1+02,dc1+21 get qtype2 pict "!!" valid ;
  1254.             chkchr("EA~PK~WT","Enter EA-Each, PK-Package, or WT-Weight", ;
  1255.             dr2-1,dc1+2,dc2-2)
  1256.  
  1257.         Note though that if the user entered "A~" or "~P" CHKCHR() would
  1258.         allow it. You may choose to use a separator that cannot be
  1259.         entered from the keyboard, however, I cannot foresee a user
  1260.         accidentally stumbling the tilde condition.
  1261.  
  1262.  
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.  
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.                                   <19>
  1299.                   The Aeolus Procedure and Function Library
  1300.                             Reference Manual
  1301.  
  1302.  
  1303.  
  1304.         CKPRTR()
  1305.  
  1306. Syntax:
  1307.         ckprtr([<expN>])
  1308.  
  1309. Pass:
  1310.         nothing or 1, 1 if ESCaping is allowed.
  1311.  
  1312. Returns:
  1313.         a logical expression.
  1314.  
  1315.         --DESCRIPTION:
  1316.         The CKPRTR() function returns a logical true if the Clipper ISP-
  1317.         RINTER() function returns a logical true.  CKPRTR() displays an
  1318.         error box if ISPRINTER() returns false and checks the ISP-
  1319.         RINTER() function again after a key is pressed.
  1320.  
  1321.         You can see that an infinite loop will be created if the printer
  1322.         cannot be brought on-line, if <expN> is a value of one (1) then
  1323.         the ESC key will allow an exit from CKPRTR() when the printer is
  1324.         not operating and if ESCaped CKPRTR() will return false (.f.).
  1325.  
  1326.         --SAMPLE:
  1327.         *************************************************
  1328.         ** CKPRTR() function example
  1329.  
  1330.         proc a_report
  1331.  
  1332.         set device to printer
  1333.         do while !eof()
  1334.           if !ckprtr(1)     && check printer on each print line
  1335.             exit
  1336.           endi
  1337.  
  1338.           .
  1339.           print report commands .
  1340.           .
  1341.  
  1342.         enddo
  1343.  
  1344.         >>COMMENT:
  1345.         The CKPRTR() function will only work with parallel printers.
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.                                   <20>
  1358.                   The Aeolus Procedure and Function Library
  1359.                             Reference Manual
  1360.  
  1361.  
  1362.  
  1363.         CRSR_STATE
  1364.  
  1365. Syntax:
  1366.         crsr_state()
  1367.  
  1368. Pass:
  1369.         Nothing
  1370.  
  1371. Returns:
  1372.         A logical value.
  1373.  
  1374. Description:
  1375.         If the Clipper program currently has a SET CURSOR ON in effect
  1376.         the CRSR_STATE() function will return true (.T.).  If a SET CUR-
  1377.         SOR OFF is in effect, false (.F.) is returned.
  1378.  
  1379.         This function is very useful when programming for Clipper SET
  1380.         KEY TO ... procedures.
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.  
  1404.  
  1405.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.                                   <21>
  1417.                   The Aeolus Procedure and Function Library
  1418.                             Reference Manual
  1419.  
  1420.  
  1421.  
  1422.         DBCHANGED()
  1423.  
  1424. Syntax:
  1425.         dbchanged(<expC>)
  1426.  
  1427. Pass:
  1428.        <expC> - Prefix character(s) to database field names for
  1429.                 memory variables.
  1430.  
  1431. Returns:
  1432.         A logical value.
  1433.  
  1434. Description:
  1435.         The DBCHANGED() function returns true (.T.) if any of the data-
  1436.         base field values are different from the memory variables
  1437.         created with the exact same prefix character(s), otherwise false
  1438.         (.F.) is returned.
  1439.  
  1440.         See DBPUBL, DBSTOR
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.  
  1465.  
  1466.  
  1467.  
  1468.  
  1469.  
  1470.  
  1471.  
  1472.  
  1473.  
  1474.  
  1475.                                   <22>
  1476.                   The Aeolus Procedure and Function Library
  1477.                             Reference Manual
  1478.  
  1479.  
  1480.  
  1481.         DBPUBL
  1482.  
  1483. Syntax:
  1484.         do dbpubl [with <expC>]
  1485.  
  1486. Pass:
  1487.         Nothing or public variable prefix character(s).  If nothing is
  1488.         passed, the default is "Q".
  1489.  
  1490. Description:
  1491.         Dbpubl declares a public memory variable for each field variable
  1492.         in a database.  The memory variables created will be prefixed by
  1493.         <expC>.
  1494.  
  1495.         If <expC> is not passed "Q" is assumed as the default. See
  1496.         DBREPL, DBSTOR and SAVE_IT().
  1497.  
  1498.         Variables are only made PUBLIC and not initialized to any value
  1499.         therefore all variables will be set to .F. by Clipper at the
  1500.         completion of this procedure.
  1501.  
  1502.  
  1503. Sample:
  1504.         ***************************************************
  1505.         ** DBPUBL example
  1506.         **
  1507.         ** a database with the following structure is assumed
  1508.         **
  1509.         **  FNAME      Character   15
  1510.         **  LNAME      Character   20
  1511.         **  ADDRESS    Character   35
  1512.         **  PHONE      Character   10
  1513.         **
  1514.  
  1515.         select 0
  1516.         use addrbook
  1517.  
  1518.         ** declares mfname,mlname,maddress,mphone as public
  1519.         do dbpubl with "M"
  1520.  
  1521. Comment:
  1522.         <expC> should be kept as short as possible otherwise the unique-
  1523.         ness to your field variables can be lost, I suggest a length of
  1524.         one, two as an absolute maximum.
  1525.  
  1526.  
  1527.  
  1528.  
  1529.  
  1530.  
  1531.  
  1532.  
  1533.  
  1534.                                   <23>
  1535.                   The Aeolus Procedure and Function Library
  1536.                             Reference Manual
  1537.  
  1538.  
  1539.  
  1540.         DBREPL
  1541.  
  1542. Syntax:
  1543.         do dbrepl [with <expC>]
  1544.  
  1545. Pass:
  1546.         Nothing or variable prefix character(s).  If nothing is passed,
  1547.         the default is "Q".
  1548.  
  1549. Description:
  1550.         DBREPL replaces all the field variables in a record using memory
  1551.         variables that exactly the same names as the field variables
  1552.         except they are prefixed with <expC>.
  1553.  
  1554.         See DBPUBL, DBSTOR and SAVE_IT().
  1555.  
  1556. Sample:
  1557.         ***************************************************
  1558.         ** DBREPL example
  1559.         **
  1560.         ** a database with the following structure is assumed
  1561.         **
  1562.         **  FNAME      Character   15
  1563.         **  LNAME      Character   20
  1564.         **  ADDRESS    Character   35
  1565.         **  PHONE      Character   10
  1566.         **
  1567.  
  1568.         select 0
  1569.         use addrbook
  1570.  
  1571.         ** declares mfname,mlname,maddress,mphone as memory vars
  1572.         mfname="DENISE"
  1573.         mlname="JOHNSON"
  1574.         maddress="123 MAPLE ST"
  1575.         mphone="6125551234"
  1576.  
  1577.         appe blan                && add a blank record
  1578.         do dbrepl with "M"       && replace all field vars.
  1579.  
  1580. Comment:
  1581.         <expC> should be kept as short as possible otherwise the unique-
  1582.         ness to your field variables can be lost, I suggest a length of
  1583.         one, two as an absolute maximum.
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.  
  1593.                                   <24>
  1594.                   The Aeolus Procedure and Function Library
  1595.                             Reference Manual
  1596.  
  1597.  
  1598.  
  1599.         DBSTATE()
  1600.  
  1601. Syntax:
  1602.         dbstate([<expC>])
  1603.  
  1604. Pass:
  1605.         Nothing or a string returned from a previous DBSTATE() function
  1606.         call.
  1607.  
  1608. Returns:
  1609.         A string of the complete state of the currently selected database.
  1610.         Select area, record number, index order number, filter expres-
  1611.         sion, all relation information.
  1612.  
  1613. Description:
  1614.         DBSTATE() saves all the information possible for the currently
  1615.         selected work and returns it to the program in a single charac-
  1616.         ter string.  Passing a string saved from a previous DBSTATE()
  1617.         call as <expC> will set the work area of that DBSTATE() string
  1618.         to the state it was in.
  1619.  
  1620.         This function is very useful when you want to preserve the cur-
  1621.         rent database conditions exactly but you also need to use the
  1622.         same database for another purpose.
  1623.  
  1624. Sample:
  1625.  
  1626.        select a_database
  1627.        dbsav=dbstate()           && save state of A_DATABASE
  1628.  
  1629.        ** change state of A_DATABASE
  1630.  
  1631.        set order to 3
  1632.        set filter to the_field="A"
  1633.        set relation to
  1634.        go top
  1635.  
  1636.        select another
  1637.  
  1638.        dbstate(dbsav)           && selects A_DATABASE and puts it in the
  1639.                                 && state it was in on the first DBSTATE()
  1640.                                 && call.
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.                                   <25>
  1653.                   The Aeolus Procedure and Function Library
  1654.                             Reference Manual
  1655.  
  1656.  
  1657.  
  1658.         DBSTOR
  1659.  
  1660. Syntax:
  1661.         do dbstor [with <expC1>][,<expC2>]
  1662.  
  1663. Pass:
  1664.         <expC1> prefix for memvars, default "Q".
  1665.         <expC2> nothing for data or "EMPTY" for empty values.
  1666.  
  1667. Description:
  1668.         DBSTOR stores all the field variables in a record to memory
  1669.         variables with exactly the same names as the field variables
  1670.         variable except they are prefixed with <expC1>.
  1671.  
  1672.         If <expC2> is passed as "EMPTY" then all memory variables will
  1673.         be assigned as if the record were blank.
  1674.  
  1675.         See DBPUBL, DBREPL and SAVE_IT().
  1676.  
  1677. Sample:
  1678.         ***************************************************
  1679.         ** DBSTOR example
  1680.         **
  1681.         ** a database with the following structure is assumed
  1682.         **
  1683.         **  FNAME      Character   15
  1684.         **  LNAME      Character   20
  1685.         **  ADDRESS    Character   35
  1686.         **  PHONE      Character   10
  1687.  
  1688.         select 0
  1689.         use addrbook
  1690.  
  1691.         ** declares mfname,mlname,maddress,mphone as public, you must
  1692.         ** do this in order to use DBSTOR
  1693.         do dbpubl with "M"
  1694.         do dbstor with "M","EMPTY"     && create 'blank' vars
  1695.  
  1696.         clea
  1697.         @ 0,0 say "First Name" get mfname pict "@!
  1698.         @ 1,0 say " Last Name" get mlname pict "@!"
  1699.         @ 2,0 say "   Address" get maddress pict "@!
  1700.         @ 3,0 say "     Phone" get mphone pict "@R (999) 999-9999"
  1701.         read
  1702.  
  1703.         appe blan                && add a blank record
  1704.         do dbrepl with "M"       && replace all field vars.
  1705.  
  1706. Comment:
  1707.         <expC> should be kept as short as possible otherwise the unique-
  1708.         ness to your field variables can be lost, I suggest a length of
  1709.         one, two as an absolute maximum.
  1710.  
  1711.                                   <26>
  1712.                   The Aeolus Procedure and Function Library
  1713.                             Reference Manual
  1714.  
  1715.  
  1716.  
  1717.         DEC2HEX()
  1718.  
  1719. Syntax:
  1720.         dec2hex(<expN>)
  1721.  
  1722. Pass:
  1723.         A numeric integer value.
  1724.  
  1725. Returns:
  1726.         A character string of the hexadecimal value of the passed
  1727.         integer.
  1728.  
  1729. Description:
  1730.         This function is the compliment to the HEX2DEC() function. If
  1731.         you have a need to convert numbers to hexadecimal, you will find
  1732.         this function useful.
  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.                                   <27>
  1771.                   The Aeolus Procedure and Function Library
  1772.                             Reference Manual
  1773.  
  1774.  
  1775.  
  1776.         DRVTST
  1777.  
  1778. Syntax:
  1779.         call drvtst with <expC1>,<expC2>
  1780.  
  1781. Pass:
  1782.         <expC1> - The DOS drive letter to test.
  1783.         <expC2> - A place for DRVTST to put the return code.
  1784.  
  1785. Returns:
  1786.         N - No error or 0-C to indicate the DOS error number that
  1787.         occurred while attempting to read from or write to the disk drive
  1788.         indicated as <expC1>
  1789.  
  1790. Description:
  1791.         Use the DRVTST assembly subroutine tests the disk drive with the
  1792.         letter passed as <expC1>.  This routine reads a disk sector then
  1793.         writes it back out to make sure the drive is usable.  The return
  1794.         value is placed in <expC2> which must be at least one (1) byte
  1795.         in length BEFORE the call to DRVTST.
  1796.  
  1797.         The possible return values are:
  1798.  
  1799.           N - No error occurred
  1800.  
  1801.           0 - Disk is Write Protected
  1802.           1 - Cannot Access Disk Drive
  1803.           2 - Drive Not Ready
  1804.           3 - Unknown Error on Disk Drive
  1805.           4 - Data Error Reading Drive
  1806.           5 - General Error 5
  1807.           6 - Seek Error on Disk Drive
  1808.           7 - Unknown Disk Format
  1809.           8 - Sector Not Found
  1810.           9 - Printer Out of Paper??
  1811.           A - Write Fault Reading Disk Drive
  1812.           B - Read Fault Error on Disk Drive
  1813.           C - General Failure Reading Disk Drive
  1814.  
  1815.         If some of the return values seem strange or out of place con-
  1816.         sult your DOS manual as that is where I found them.
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.                                   <28>
  1830.                   The Aeolus Procedure and Function Library
  1831.                             Reference Manual
  1832.  
  1833.  
  1834.  
  1835.         DUPCHK()
  1836.  
  1837. Syntax:
  1838.         dupchk(<expC1>,<exp>,<expN1>,<expC2>,<expN2>,<expN3>,<expN4>, ;
  1839.            <expL>[,<expC3>])
  1840.  
  1841. Pass:
  1842.         <expC1> - either "A" to check of the Addition of a record will
  1843.                   cause a duplicate, or "C" to check if Changing the
  1844.                   record will cause a duplicate.
  1845.         <exp>   - Key value to duplicate check.
  1846.         <expN1> - Index order number for duplicate check.
  1847.         <expC2> - Error message to display.
  1848.         <expN2> - Screen row to display error message.
  1849.         <expN3> - Screen column to display error message.
  1850.         <expN4> - Rightmost screen column to display error message.
  1851.         <expL>  - GET is required (.T.) or may be blank (.F.).
  1852.         <expC3> - Color to display error message, default is WERR_CLR.
  1853.  
  1854. Returns:
  1855.         A logical value, this function is to be used as a VALID for a
  1856.         GET only.
  1857.  
  1858. Description:
  1859.         The DUPCHK() valid function tests the value entered into a GET
  1860.         field to see if it will cause a duplicate record when saved.
  1861.  
  1862.         This function is useful when two indexes are maintained on a
  1863.         single database and both keys must not contain duplicates.
  1864.  
  1865.         If you are using GEN_MAINT or REL_MAINT pass G_FUNC as <expC1>
  1866.         as it will contain "A" on Adds and "C" on changes.
  1867.  
  1868.         The 2nd parameter (<exp>) should (almost has to) include the GET
  1869.         memvar somewhere within it.
  1870.  
  1871. Sample:
  1872.         Let's say you have a file maintenance routine of customer infor-
  1873.         mation.  This file has a primary key of customer number which is
  1874.         a unique number your company assigns to each customer. One of
  1875.         the fields in your customer information file is a serial number
  1876.         which is the serial number of the product your company sold
  1877.         them.  Since no two customers can possess the same product at
  1878.         the same time you would like to make sure all the product serial
  1879.         numbers entered into the database are unique.
  1880.  
  1881.         This is a situation where DUPCHK() could be used effectively.
  1882.  
  1883.         Let's now assume the system you designed contains a file called
  1884.         CUSTOMER containing the customer information and index order
  1885.         number three (3) is on the a field called SERIAL_NBR.
  1886.  
  1887.  
  1888.                                   <29>
  1889.                   The Aeolus Procedure and Function Library
  1890.                             Reference Manual
  1891.  
  1892.  
  1893.  
  1894.         You could program DUPCHK() to make sure inventory items are
  1895.         never keyed duplicated in the customer file as follows:
  1896.  
  1897.  
  1898.        Other file maintenance GETs.
  1899.         .
  1900.         .
  1901.         .
  1902.  
  1903.        @ fmr1+05,fmc1+22 get &g_pfx.serial_nbr valid ;
  1904.               dupchk(g_func,"CUSTOMER",&g_pfx.serial_nbr,3, ;
  1905.               "ERROR: Serial Number Already in Use",fmr2-1,fmc1+2,fmc2-2,.t.)
  1906.  
  1907.  
  1908.         The DUPCHK() Valid above would force entry into the SERIAL_NBR
  1909.         field to be unique.  The error message would be displayed if the
  1910.         field were or would create a duplicate.  Because the ninth par-
  1911.         ameter is set to true (.T.) the error message would display if
  1912.         the user attempted to leave the field blank.  An error beep
  1913.         accompanies the error message display and the user is not
  1914.         allowed to proceed to the next field in the GET stream.
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.  
  1922.  
  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.                                   <30>
  1948.                   The Aeolus Procedure and Function Library
  1949.                             Reference Manual
  1950.  
  1951.  
  1952.  
  1953.         EDT_MEMO()
  1954.  
  1955. Syntax:
  1956.         edt_memo(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2>, ;
  1957.             <expC3>,<expC4>,<expC5>[,<expN5>][,<expL1>][,<expL2>]
  1958.  
  1959. Pass:
  1960.         <expN1> - Top row screen coordinate.
  1961.         <expN2> - Left column screen coordinate.
  1962.         <expN3> - Bottom row screen coordinate.
  1963.         <expN4> - Right column screen coordinate.
  1964.         <expC1> - Prefix character(s) for memo memvar.
  1965.         <expC2> - Memo field database field name.
  1966.         <expC3> - Memo title.
  1967.         <expC4> - Color for memo data.
  1968.         <expC5> - Color for title display.
  1969.         <expN5> - Maximum lines memo may contain.  Default unlimited.
  1970.         <expL1> - .F. view only, .T. allow editing.  Default .T.
  1971.         <expL2> - .F. does nothing, .T. starts editing at the end of
  1972.                   the memo text.  Default .F.
  1973.  
  1974. Returns:
  1975.         Nothing.
  1976.  
  1977. Description:
  1978.         EDT_MEMO() Puts a border on the screen, a title on the top line
  1979.         of the border, Displays an appropriate message line, and Saves
  1980.         the memo data if Ctrl+W is pressed.  This function may be used
  1981.         as a Valid function (BUILDER can create the call) or as a stand
  1982.         alone command.
  1983.  
  1984.         If used as a Valid function, DO NOT try to GET the memo field.
  1985.         Issue a GET on a one byte character memvar and EDT_MEMO() will
  1986.         force the user to press "Y" to edit the memo data or "N" to
  1987.         bypass the field.
  1988.  
  1989.  
  1990.  
  1991.  
  1992.  
  1993.  
  1994.  
  1995.  
  1996.  
  1997.  
  1998.  
  1999.  
  2000.  
  2001.  
  2002.  
  2003.  
  2004.  
  2005.  
  2006.                                   <31>
  2007.                   The Aeolus Procedure and Function Library
  2008.                             Reference Manual
  2009.  
  2010.  
  2011.  
  2012.         ERRTONE()
  2013.  
  2014. Syntax:
  2015.         errtone([<expN>])
  2016.  
  2017. Pass:
  2018.         Nothing or one (1) through five (5).
  2019.  
  2020. Returns:
  2021.         Nothing.
  2022.  
  2023. Description:
  2024.         The ERRTONE() function beeps the speaker in one of five ways, a
  2025.         two tone error beep if no parameters (or zero) are passed, a
  2026.         short high pitched single tone if one (1) is passed.  Passing a
  2027.         two (2) will make a two-tone ON indication sound, three (3) will
  2028.         make the opposite or a two-tone OFF sound.  Passing a four (4)
  2029.         makes a long low error tone.
  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.                                   <32>
  2066.                   The Aeolus Procedure and Function Library
  2067.                             Reference Manual
  2068.  
  2069.  
  2070.  
  2071.         ETC()
  2072.  
  2073. Syntax:
  2074.         etc(<expC>,<expN1>,<expN2>,<expN3>)
  2075.  
  2076. Pass:
  2077.         <expC>  start time of process
  2078.         <expN1> start value of operation
  2079.         <expN2> maximum value of operation
  2080.         <expN3> current value, must be between <expN1> and <expN2>
  2081.  
  2082. Returns:
  2083.         a character expression.
  2084.  
  2085. Description:
  2086.         The ETC() function will calculate the estimated time to comple-
  2087.         tion of an iterative process.  In order to be accurate, be sure
  2088.         to use this only in loops that occurs at regular intervals.
  2089.         Looping where some iterations are longer than others will cause
  2090.         some very unusual time estimates.
  2091.  
  2092.         See THERMOMETR()
  2093.  
  2094. Sample:
  2095.         ***************************************************************
  2096.         ** ETC() function example to display current estimated time
  2097.         **       to compete a process.
  2098.  
  2099.         stim=time()
  2100.         for j=1 to 500
  2101.           if time()<>stim       && Should only recalculate on time change
  2102.             @ 1,0 say etc(stim,1,500,j)
  2103.             stim=time()
  2104.           endi
  2105.           inkey(.25)
  2106.         next
  2107.  
  2108.  
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.  
  2119.  
  2120.  
  2121.  
  2122.  
  2123.  
  2124.                                   <33>
  2125.                   The Aeolus Procedure and Function Library
  2126.                             Reference Manual
  2127.  
  2128.  
  2129.  
  2130.         FEOF()
  2131.  
  2132. Syntax:
  2133.         feof([<expL>])
  2134.  
  2135. Pass:
  2136.         A Logical Expression or Nothing
  2137.  
  2138. Returns:
  2139.         A logical expression
  2140.  
  2141. Description:
  2142.         The FEOF() function is designed only to be used in conjunction
  2143.         with the FGETS() function.  FEOF()  Returns .T. when end of file
  2144.         is encountered while reading a file using the FGETS() function.
  2145.  
  2146.         Before using FEOF() you must first initialize its internal vari-
  2147.         ables by issuing FEOF(.F.).  See the example code in the
  2148.         description for FGETS().
  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.                                   <34>
  2184.                   The Aeolus Procedure and Function Library
  2185.                             Reference Manual
  2186.  
  2187.  
  2188.  
  2189.         FGETS()
  2190.  
  2191. Syntax:
  2192.         fgets(<expN>)
  2193.  
  2194. Pass:
  2195.         A file handle of a previously FOPEN()'d or FCREATE()'d file.
  2196.  
  2197. Returns:
  2198.         Next logical record in a CR/LF delimited file.
  2199.  
  2200. Description:
  2201.         The FGETS() function will attempt to read the next logical
  2202.         record in a CR/LF delimited file.
  2203.  
  2204. Sample:
  2205.         ***************************************************************
  2206.         ** Sample code to read the AUTOEXEC.BAT file using the       **
  2207.         ** Aeolus FGETS() function.                                  **
  2208.         ***************************************************************
  2209.  
  2210.         ** Open the AUTOEXEC.BAT file
  2211.         hndl=fopen("C:\AUTOEXEC.BAT")
  2212.  
  2213.         feof(.f.)            && initialize FEOF()
  2214.         do whil !feof()
  2215.           ? fgets(hndl)        && read next AUTOEXEC record
  2216.         endd
  2217.         fclose(hndl)
  2218.  
  2219.  
  2220.  
  2221.  
  2222.  
  2223.  
  2224.  
  2225.  
  2226.  
  2227.  
  2228.  
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.                                   <35>
  2243.                   The Aeolus Procedure and Function Library
  2244.                             Reference Manual
  2245.  
  2246.  
  2247.  
  2248.         FGETSR()
  2249.  
  2250. Syntax:
  2251.        fgetsr(<expN>)
  2252.  
  2253. Pass:
  2254.         A file handle of a previously FOPEN()'d or FCREATE()'d file.
  2255.  
  2256. Returns:
  2257.         The previous logical record in a CR/LF delimited file.
  2258.  
  2259. Description:
  2260.         The FGETSR() function will attempt to read the previous logical
  2261.         record in a CR/LF delimited file.
  2262.  
  2263. Sample:
  2264.         ***************************************************************
  2265.         ** Sample code to read the AUTOEXEC.BAT file using the       **
  2266.         ** Aeolus FGETS and FGETSR() functions.                      **
  2267.         ***************************************************************
  2268.  
  2269.         ** Open the AUTOEXEC.BAT file
  2270.         hndl=fopen("C:\AUTOEXEC.BAT")
  2271.  
  2272.         feof(.f.)            && initialize FEOF()
  2273.         do whil !feof()
  2274.           ? fgets(hndl)        && read next AUTOEXEC record
  2275.         endd
  2276.  
  2277.         ** file pointer is at the end of file, let's use FGETSR()
  2278.         ** to read and display AUTOEXEC.BAT backwards.
  2279.  
  2280.         feof(.f.)            && reinitialize FEOF()
  2281.         do whil !feof()
  2282.           ? fgetsr(hndl)
  2283.         endd
  2284.         fclose(hndl)
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.                                   <36>
  2302.                   The Aeolus Procedure and Function Library
  2303.                             Reference Manual
  2304.  
  2305.  
  2306.  
  2307.         FIL_LOCK()
  2308.  
  2309. Syntax:
  2310.         fil_lock(<expN>)
  2311.  
  2312. Pass:
  2313.         <expN> seconds to wait before returning false, zero will not
  2314.         return false.
  2315.  
  2316. Returns:
  2317.         A logical expression.
  2318.  
  2319. Description:
  2320.         The FIL_LOCK() function will attempt to lock a previously opened
  2321.         .DBF database, if it fails in <expN> seconds an error box is
  2322.         displayed allowing the user to try again or abort the operation.
  2323.         If <expN> is passed as a value of zero then FIL_LOCK() will wait
  2324.         indefinitely to attempt the lock.
  2325.  
  2326.         FIL_LOCK returns true if the lock is successful and false if the
  2327.         lock is unsuccessful.
  2328.  
  2329.         Issuing a successful FIL_LOCK() allows a database opened in non-
  2330.         exclusive mode to be treated as if it were opened exclusively.
  2331.         Note that all other file or record locks will be rejected while
  2332.         you have a successful FIL_LOCK(), be sure to UNLOCK the file or
  2333.         close the database so others on the LAN can use it.
  2334.  
  2335. Sample:
  2336.         ******************************************************
  2337.         ** Attempt to lock a database previously opened in
  2338.         ** shared mode.
  2339.         **
  2340.         set exclusive off       && allow file sharing
  2341.         use addrbook
  2342.         if fil_lock(5)
  2343.           report form addr_rpt to print noeject
  2344.         endi
  2345.         unlock
  2346.  
  2347. Comment:
  2348.         An alternative to using FIL_LOCK() is simply to open your data-
  2349.         bases in exclusive mode.  Either method will accomplish the same
  2350.         thing.
  2351.  
  2352.  
  2353.  
  2354.  
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.                                   <37>
  2361.                   The Aeolus Procedure and Function Library
  2362.                             Reference Manual
  2363.  
  2364.  
  2365.  
  2366.         FLD_REPL()
  2367.  
  2368. Syntax:
  2369.         fld_repl(<expC>,<exp>[,<expN>])
  2370.  
  2371. Pass:
  2372.         <expC> The name of the field in the currently selected
  2373.         database to be replaced.
  2374.         <exp>  The value to place in the database field <expC>
  2375.         <expN> The number of seconds to wait for a record lock before
  2376.         returning false.
  2377.  
  2378. Returns:
  2379.         A logical value.
  2380.  
  2381. Description:
  2382.         Use FLD_REPL whenever you need to REPLACE a single database
  2383.         field.  This function will work in a shared or single user
  2384.         application.  Using this function on single field REPLACEs will
  2385.         allow your application to be changed from a single to multi-user
  2386.         program simply by changing the NETWORK system variable from .F.
  2387.         to .T.!
  2388.  
  2389. Sample:
  2390.         ** replace a date field in the currently selected database
  2391.         ** with today's date - will work if single or multi user
  2392.  
  2393.         do fld_repl with "CURRNT_DT",date()
  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.                                   <38>
  2420.                   The Aeolus Procedure and Function Library
  2421.                             Reference Manual
  2422.  
  2423.  
  2424.  
  2425.         GEN_MAINT
  2426.  
  2427. Syntax:
  2428.         do gen_maint with <expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ;
  2429.         <expC2>[,<expN5>][,<expN6>][,<expL>][,<expC3>][,<expC4>]
  2430.  
  2431. Pass:
  2432.         <expN1> top left row
  2433.         <expN2> top left column
  2434.         <expN3> bottom right row
  2435.         <expN4> bottom right column
  2436.         <expC1> DBSTOR prefix character(s)
  2437.         <expC2> procedure name suffix
  2438.         <expN5> fast delete index order number
  2439.         <expN6> number of GET fields
  2440.         <expL>  .T. to allow duplicates in file
  2441.         <expC3> menu options to use
  2442.         <expC4> function name to execute after file I/O and just before exit.
  2443.  
  2444. Description:
  2445.         The GEN_MAINT procedure is one of two generic file maintenance
  2446.         procedures included with the function library and is designed to
  2447.         be used as an all purpose file maintenance routine.
  2448.  
  2449.         Before you can call the GEN_MAINT procedure you must first code
  2450.         four procedures yourself, GSAYS_????, GGETS_????, GEDIT_???? and
  2451.         GKEY_????.  Where ???? is the value passed as <expC2>. The
  2452.         GSAYS_???? procedure must contain the screen displays,
  2453.         GGETS_???? the get's, and GEDIT_???? additional code performed
  2454.         after a READ statement.
  2455.  
  2456.         Call GEN_MAINT with <expN1> through <expN4> equal to the screen
  2457.         coordinates required.  <expC1> must equal the suffix portion of
  2458.         the three procedures you write.  <expC2> is the prefix character
  2459.         you want when GEN_MAINT creates memory variables.
  2460.  
  2461.         Optionally pass <expN5> as the 'fast delete' index order number.
  2462.         A fast delete index is created by issuing the following Clipper
  2463.         command:
  2464.  
  2465.         INDE ON IF(DELE(),"*"," ") TO ...
  2466.  
  2467.         If <expN5> is not passed or passed with a value of zero the
  2468.         database will be PACKed on every delete instead.  Using the fast
  2469.         delete, records marked for deletion are used as 'add space' so
  2470.         your database doesn't grow indefinitely.  Note that you must use
  2471.         either SET DELETED ON or SET FILTER TO !DELE() for fast delete
  2472.         to work correctly.
  2473.  
  2474.         <expN6> is another optional parameter that should be used if you
  2475.         have any VALID clauses in your file maintenance.  The value
  2476.         passed in <expN6> should be equal to the number of fields that
  2477.  
  2478.                                   <39>
  2479.                   The Aeolus Procedure and Function Library
  2480.                             Reference Manual
  2481.  
  2482.  
  2483.  
  2484.         are in the file maintenance GET string.  If you use this, exec-
  2485.         cute a CLEAR TYPEAHEAD in the VALID function if an error occurs.
  2486.         The cursor will be positioned at the error field if a VALID
  2487.         fails.
  2488.  
  2489.         <expL> may be passed as true if duplicate records are to be
  2490.         allowed.  The default is false.
  2491.  
  2492.         <expC3> is used to tell GEN_MAINT which of the three basic menu
  2493.         options to use, Add-Change- and/or Delete.  Pass a character
  2494.         string with the first letter of each of the menu options to
  2495.         allow during the GEN_MAINT.  Passing "AC" for example will only
  2496.         put "Add", "Change" and "Find" on the file maintenance menu,
  2497.         skipping "Delete".  Passing a null string ("") will only allow
  2498.         "Find". The default is "ACD" if this is parameter is not passed.
  2499.  
  2500.         <expC4> is a character string of the name of a function to be
  2501.         executed on every file Add, Change, or Delete and before the
  2502.         File Maintenance is exited.  A character parameter is passed to
  2503.         this function indicating the action taking place "A" for Add,
  2504.         "C" for Change, "D" for Delete and "E" for Exit.  You must
  2505.         return a logical value from this function.  The return value is
  2506.         NOT checked for Adds, Changes, or Deletes.  However, on Exit if
  2507.         the return value is false (.F.) then the user will not be
  2508.         allowed to exit the file maintenance.
  2509.  
  2510.         You can create your own sample calls to GEN_MAINT by creating
  2511.         file maintenance windows in BUILDER.
  2512.  
  2513. Sample:
  2514.         proc fmnt_exmpl
  2515.           ** proc to call a generic maintenance routine
  2516.           **
  2517.  
  2518.           m_trow=04
  2519.           m_tcol=30
  2520.           m_brow=12
  2521.           m_bcol=67
  2522.           sele TCSREPS
  2523.           do gen_maint with m_trow,m_tcol,m_brow,m_bcol,"REPS","Q_",.f., ;
  2524.               "AC","TESTFUNC"
  2525.  
  2526.           ** since the 8th parm is "AC" only Adds and Changes will be allowed
  2527.  
  2528.         ** screen SAY's for generic maint of sales rep file
  2529.         **
  2530.         proc gsays_reps
  2531.           @ m_trow+2,m_tcol+2 say "Sales Rep #:"
  2532.           @ m_trow+4,m_tcol+2 say "  Last Name:"
  2533.           @ m_trow+5,m_tcol+2 say " First Name:"
  2534.           @ m_trow+7,m_tcol+2 say "      Phone:"
  2535.  
  2536.  
  2537.                                   <40>
  2538.                   The Aeolus Procedure and Function Library
  2539.                             Reference Manual
  2540.  
  2541.  
  2542.  
  2543.         ** screen GET's for generic maint of sales rep file
  2544.         **
  2545.         proc ggets_REPS
  2546.           para g_func       && A-Add, C-Change, D-Delete or null if
  2547.                             && display only.
  2548.  
  2549.           @ m_trow+2,m_tcol+15 get &g_pfx.SLS_NBR pict "9999"
  2550.           clear gets
  2551.           @ m_trow+4,m_tcol+15 get &g_pfx.LAST pict "@!"
  2552.           @ m_trow+5,m_tcol+15 get &g_pfx.FIRST pict "@!"
  2553.           @ m_trow+7,m_tcol+15 get &g_pfx.PHONE pict "@R (999) 999-9999"
  2554.  
  2555.         ** Function to edit data called after a screen is keyed but
  2556.         ** before the disk write
  2557.         **
  2558.         func gedit_REPS
  2559.           retu(.t.)
  2560.  
  2561.         ** key GET's for generic maint of division file
  2562.         **
  2563.         func gkey_REPS
  2564.           para gk_func  && A-Add, D-Del, C-Change
  2565.  
  2566.           winpush(m_brow-2,m_bcol-15,m_brow+3,m_bcol+09)
  2567.           message("Enter Sales Rep Number or Press ESC to Abort",24,00 ;
  2568.              ,80,bmsg_clr)
  2569.           pcd=space(4)
  2570.           @ m_brow-1,m_bcol-13 say "Sales Rep #:" get pcd pict "9999"
  2571.           @ m_brow+1,m_bcol-13 say "Enter Sales Rep # Code"
  2572.           if gk_func<>"A"
  2573.             @ m_brow+2,m_bcol-13 say "Blank for Current Rec"
  2574.           else
  2575.             @ m_brow+2,m_bcol-13 say "to Add or ESC to Exit"
  2576.           endi
  2577.           read
  2578.           message("",24,00,80,bmsg_clr)
  2579.           winpop()
  2580.  
  2581.           &g_pfx.SLS_NBR=if(empty(pcd) .or. ; lastkey()=27, ;
  2582.                    &g_pfx.SLS_NBR,pcd)
  2583.           retu(pcd)
  2584.  
  2585.         func testfunc
  2586.           para t_func        && "A"-Add, "C"-Change, "D"-Delete, "E"-Exit.
  2587.  
  2588.           do case
  2589.           case t_func="A"
  2590.             ** Record was added to database, do whatever we need to
  2591.             ** after that activity.
  2592.           case t_func="C"
  2593.             ** Current database record was Changed, do whatever is needed
  2594.             ** in that case.
  2595.  
  2596.                                   <41>
  2597.                   The Aeolus Procedure and Function Library
  2598.                             Reference Manual
  2599.  
  2600.  
  2601.  
  2602.           case t_func="D"
  2603.             ** Current database record is now a Deleted record, do
  2604.             ** whatever is needed (usually delete child relation records).
  2605.           case t_func="E"
  2606.             ** User is trying to exit the file maintenance, make sure it
  2607.             ** is ok for them to do so at this time.  If it is then return
  2608.             ** true (.T.) otherwise return false (.F.) to keep them in the
  2609.             ** file maintenance.
  2610.           endc
  2611.           retu(.t.)
  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.                                   <42>
  2656.                   The Aeolus Procedure and Function Library
  2657.                             Reference Manual
  2658.  
  2659.  
  2660.  
  2661.         GENVLD()
  2662.  
  2663. Syntax:
  2664.         genvld(<expL1>,<expC1>,<expN1>,<expN2>,<expN3>,<expL2>
  2665.                [,<expC2>])
  2666.  
  2667. Pass:
  2668.         <expL1> - The validation test expression.
  2669.         <expC1> - The error message on incorrect GET input.
  2670.         <expN1> - The screen row number to display the error message.
  2671.         <expN2> - The screen column number to display the error message.
  2672.         <expN3> - The screen rightmost column number to pad/allow the
  2673.                   error message to display.
  2674.         <expL2> - Required indicator.  True (.T.) if field cannot be
  2675.         empty or false (.F.) if field is allowed to be empty.
  2676.         <expC2> - Color string for error message to display, default
  2677.                   is WERR_CLR.
  2678.  
  2679. Returns:
  2680.         A logical value.
  2681.  
  2682. Description:
  2683.         The GENVLD() function is a generic valid function used to vali-
  2684.         date a GET for any logical expression and display an error mes-
  2685.         sage on invalid input.
  2686.  
  2687. Sample:
  2688.         You have a two byte character GET for the U.S. state code and
  2689.         you would like to make sure what is keyed is legitimate code.
  2690.         The following GENVLD() would do this:
  2691.  
  2692.        @ dr1+05,dc1+22 get state pict "!!" valid ;
  2693.               genvld(in_usa(state), ;
  2694.               "ERROR: Not a Valid U.S. State Code",dr2-1,dc1+2,dc2-2,.t.)
  2695.  
  2696.         See the IN_USA() function in this text also.
  2697.  
  2698.         In the above sample code the user would be forced to enter a
  2699.         valid U.S. state code into the STATE field.  Attempting to leave
  2700.         the field blank would produce an error beep and the error mes-
  2701.         sage due to the sixth parameter being set to true.
  2702.  
  2703.         Any expression that returns a logical value (including your own
  2704.         UDFs) may be used in place of the IN_USA() function in the
  2705.         example.
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.  
  2712.  
  2713.  
  2714.                                   <43>
  2715.                   The Aeolus Procedure and Function Library
  2716.                             Reference Manual
  2717.  
  2718.  
  2719.  
  2720.         GOT()
  2721.  
  2722. Syntax:
  2723.         got(<expC>,<expN1>,<expN2>)
  2724.  
  2725. Pass:
  2726.         <expC>  database alias name
  2727.         <expN1> field number in database
  2728.         <expN2> record number of database
  2729.  
  2730. Returns:
  2731.         an expression of type determined by TYPE(FIELD(<expN1>)).
  2732.  
  2733. Description:
  2734.         Normally used in a valid function to pop up a scroll box and put
  2735.         the selected item in the READ field.
  2736.  
  2737.         <expC> is the database alias used for the look up, <expN1> is
  2738.         <expN1>th field in the database whose alias is <expC>.  <expN2>
  2739.         is the record number in that database, usually the POP() func-
  2740.         tion.
  2741.  
  2742.         The return value is whatever is the databases <expN1>th field at
  2743.         record <expN2>.
  2744.  
  2745. Sample:
  2746.         @ 12,34 say "Building # " get qbldg_nbr pict "!!!!" ;
  2747.           valid ckbldg()
  2748.         set cursor on
  2749.         read
  2750.  
  2751.         set cursor off
  2752.  
  2753.         *************************************************************
  2754.         *** valid function to check the existence of a building ID #
  2755.         **  and pop a scroll box up and allow selection if the keyed
  2756.         **  value is not found in the building file.
  2757.         **
  2758.         func ckbldg
  2759.  
  2760.           v=readvar()               && get READ var name
  2761.           p=&v                      && get its value
  2762.  
  2763.           if empty(p)               && allow a blank in this function
  2764.             retu(.t.)               && to be a valid entry
  2765.           endi
  2766.  
  2767.           of=select()               && old file select area
  2768.           or=recn()                 && old record (in case same file)
  2769.           ret_val=.t.               && default return value
  2770.  
  2771.           set softseek on
  2772.  
  2773.                                   <44>
  2774.                   The Aeolus Procedure and Function Library
  2775.                             Reference Manual
  2776.  
  2777.  
  2778.  
  2779.           sele bldg
  2780.           seek p                    && look for it
  2781.           if !found()
  2782.  
  2783.             k_bldg=space(4)
  2784.             bldg_fld='bldg_nbr+" "+city'
  2785.             r=row()
  2786.             c=col()
  2787.             set cursor off
  2788.  
  2789.             ** display pop box at row()-1, col()+3 of the field being
  2790.             ** tested.
  2791.             ckv=got("BLDG",1,pop(r-1,c+3,6,25,"BLDG",bldg_fld,"",.t., ;
  2792.             .f.,"k_bldg"))
  2793.             set cursor on
  2794.             ret_val=.f.
  2795.             if !empty(ckv)                 && if a record was chosen
  2796.               &v=ckv                       && put it in the READ var
  2797.               keyboard chr(13)     && enter key will display entry
  2798.             endi
  2799.           endi
  2800.           sele (of)
  2801.           go or
  2802.           retu(ret_val)
  2803.  
  2804.  
  2805.  
  2806.  
  2807.  
  2808.  
  2809.  
  2810.  
  2811.  
  2812.  
  2813.  
  2814.  
  2815.  
  2816.  
  2817.  
  2818.  
  2819.  
  2820.  
  2821.  
  2822.  
  2823.  
  2824.  
  2825.  
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.                                   <45>
  2833.                   The Aeolus Procedure and Function Library
  2834.                             Reference Manual
  2835.  
  2836.  
  2837.  
  2838.         HEX2DEC()
  2839.  
  2840. Syntax:
  2841.         HEX2DEC(<expC>)
  2842.  
  2843. Pass:
  2844.         <expC> - A string of hexadecimal digits.
  2845.  
  2846. Returns:
  2847.         A numeric decimal integer of the passed hexadecimal number.
  2848.  
  2849. Description:
  2850.         HEX2DEC() converts a hexadecimal character string to a numeric
  2851.         integer value.  This function is useful when calling some of the
  2852.         assembly routines in the BLDRASM library.
  2853.  
  2854.         See the TIMEOUT assembly routine also.
  2855.  
  2856.  
  2857.  
  2858.  
  2859.  
  2860.  
  2861.  
  2862.  
  2863.  
  2864.  
  2865.  
  2866.  
  2867.  
  2868.  
  2869.  
  2870.  
  2871.  
  2872.  
  2873.  
  2874.  
  2875.  
  2876.  
  2877.  
  2878.  
  2879.  
  2880.  
  2881.  
  2882.  
  2883.  
  2884.  
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.                                   <46>
  2892.                   The Aeolus Procedure and Function Library
  2893.                             Reference Manual
  2894.  
  2895.  
  2896.  
  2897.         IN_CANADA()
  2898.  
  2899. Syntax:
  2900.         in_canada(<expC>)
  2901.  
  2902. Pass:
  2903.         <expC> - A two byte character string
  2904.  
  2905. Returns:
  2906.         A logical expression.
  2907.  
  2908. Description:
  2909.         The IN_CANADA() function tests the passed parameter and returns
  2910.         true (.T.) if the value is a valid Canadian province code (see
  2911.         list below), otherwise false (.F.) is returned.  This function
  2912.         is useful when building VALID functions.  See the GENVLD()
  2913.         sample code also.
  2914.  
  2915. Notes:
  2916.         Canadian provinces tested in IN_CANADA():
  2917.  
  2918.         AB - Alberta               NF - Newfoundland
  2919.         BC - British Columbia      NS - Nova Scotia
  2920.         MB - Manitoba              ON - Ontario
  2921.         NB - New Brunswick         PQ - Quebec
  2922.         NF - Newfoundland          SK - Saskatchewan
  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.                                   <47>
  2951.                   The Aeolus Procedure and Function Library
  2952.                             Reference Manual
  2953.  
  2954.  
  2955.  
  2956.         IN_USA()
  2957.  
  2958. Syntax:
  2959.         in_usa(<expC>)
  2960.  
  2961. Pass:
  2962.         <expC> - A two byte character string
  2963.  
  2964. Returns:
  2965.         A logical expression.
  2966.  
  2967. Description:
  2968.         The IN_USA() function tests the passed parameter and returns
  2969.         true (.T.) if the value is a valid U.S. State code (see list
  2970.         below), otherwise false (.F.) is returned.  This function is
  2971.         useful when building VALID functions.  See the GENVLD() sample
  2972.         code also.
  2973.  
  2974. Notes:
  2975.         U.S. State codes tested in IN_USA():
  2976.  
  2977.         AL - Alabama            KY - Kentucky           ND - North
  2978.         Dakota
  2979.         AK - Alaska             LA - Louisiana          OH - Ohio
  2980.         AZ - Arizona            ME - Maine              OK - Oklahoma
  2981.         AR - Arkansas           MD - Maryland           OR - Oregon
  2982.         CA - California         MA - Massachusetts      PA - Pennsylva-
  2983.                                                              nia
  2984.         CO - Colorado           MI - Michigan           RI - Rhode
  2985.                                                              Island
  2986.         CT - Connecticut        MN - Minnesota          SC - South Caro-
  2987.                                                              lina
  2988.         DE - Delaware           MS - Mississippi        SD - South
  2989.                                                              Dakota
  2990.         DC - Washington D.C.    MO - Missouri           TN - Tennessee
  2991.         FL - Florida            MT - Montana            TX - Texas
  2992.         GA - Georgia            NE - Nebraska           UT - Utah
  2993.         HI - Hawaii             NV - Nevada             VT - Vermont
  2994.         ID - Idaho              NH - New Hampshire      VA - Virginia
  2995.         IL - Illinois           NJ - New Jersey         WA - Washington
  2996.         IN - Indiana            NM - New Mexico         WV - West Virgi-
  2997.                                                              nia
  2998.         IA - Iowa               NY - New York           WI - Wisconsin
  2999.         KS - Kansas             NC - North Carolina     WY - Wyoming
  3000.  
  3001. Note:
  3002.         The codes for Puerto Rico (PR) and the U.S. Virgin Islands (VI)
  3003.         are not tested.
  3004.  
  3005.  
  3006.  
  3007.  
  3008.  
  3009.                                   <48>
  3010.                   The Aeolus Procedure and Function Library
  3011.                             Reference Manual
  3012.  
  3013.  
  3014.  
  3015.         INFILE()
  3016.  
  3017. Syntax:
  3018.         infile(<expC1>,<expN1>,<expC2>,<expN2>,<expN3>,<expN4>, ;
  3019.                <expL>[,<expC3>])
  3020.  
  3021. Pass:
  3022.         <expC1> - File alias name of look up table.
  3023.         <expN1> - Index order number for SEEK.
  3024.         <expC2> - The error message on incorrect GET input.
  3025.         <expN2> - The screen row number to display the error message.
  3026.         <expN3> - The screen column number to display the error message.
  3027.         <expN4> - The screen rightmost column number to pad/allow the
  3028.                   error message to display.
  3029.         <expL>  - Required indicator.  True (.T.) if field cannot be
  3030.                   empty or false (.F.) if field is allowed to be empty.
  3031.         <expC3> - Color string for error message to display, default
  3032.                   is WERR_CLR.
  3033.  
  3034. Returns:
  3035.         A logical value.
  3036.  
  3037. Description:
  3038.         The INFILE() function tests the input of the @...GET and dis-
  3039.         plays an error message if the value entered is not FOUND() in a
  3040.         database.  The programmer may allow or disallow the entry of a
  3041.         blank into the field with <expL>
  3042.  
  3043. Sample:
  3044.         You have a four byte character GET for an employee number and
  3045.         you would like to make sure what is keyed is a legitimate code.
  3046.         Further there is an employee file with index order one (1) on
  3047.         the four digit employee code.  The following get will force the
  3048.         entry of a valid employee code based on the look up table
  3049.         (called EMPLYEE).
  3050.  
  3051.        @ dr1+05,dc1+22 get emp_nbr pict "!!" valid ;
  3052.               infile("EMPLYEE",1, ;
  3053.               "ERROR: Not a Valid Employee Code",dr2-1,dc1+2,dc2-2,.t.)
  3054.  
  3055.         In the above sample code the user would be forced to enter a
  3056.         valid employee code into the EMP_NBR field.  Attempting to leave
  3057.         the field blank would produce an error beep and the error mes-
  3058.         sage due to the seventh parameter being set to true.
  3059.  
  3060.         The INFILE() function is only useful if you specifically do not
  3061.         want to help your users find the required field entry from the
  3062.         look up table.  Sometimes this is necessary, however, I believe
  3063.         the PCKVLD() function will be useful in more situations.
  3064.  
  3065.  
  3066.  
  3067.  
  3068.                                   <49>
  3069.                   The Aeolus Procedure and Function Library
  3070.                             Reference Manual
  3071.  
  3072.  
  3073.  
  3074.         INPATH()
  3075.  
  3076. Syntax:
  3077.         inpath(<expC1>[,<expC2>])
  3078.  
  3079. Pass:
  3080.         <expC1> - DOS filename to locate.
  3081.         <expC2> - environment variable with pathnames separated by
  3082.                   semicolons of paths to search for <expC1>.  Default
  3083.                   value is "PATH".
  3084.  
  3085. Returns:
  3086.         A character value of the path where <expC1> is located.  A null
  3087.         string is returned if it was not found.  A "." (period charac-
  3088.         ter) is returned if it was found in the current directory.
  3089.  
  3090. Description:
  3091.         The INPATH() function first searches the current DOS directory
  3092.         for the file <expC1> and returns "." if it is found.  It then
  3093.         searches each directory in the DOS PATH environment variable or
  3094.         if <expC2> is passed that environment variable.  If <expC2> is
  3095.         passed it must contain directory names separated by semicolons
  3096.         just like the DOS PATH.
  3097.  
  3098.  
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.  
  3110.  
  3111.  
  3112.  
  3113.  
  3114.  
  3115.  
  3116.  
  3117.  
  3118.  
  3119.  
  3120.  
  3121.  
  3122.  
  3123.  
  3124.  
  3125.  
  3126.  
  3127.                                   <50>
  3128.                   The Aeolus Procedure and Function Library
  3129.                             Reference Manual
  3130.  
  3131.  
  3132.  
  3133.         ISEEK()
  3134.  
  3135. Syntax:
  3136.         iseek(<exp>[,<expC>][,<expN>][,<expL>])
  3137.  
  3138. Pass:
  3139.         <exp>  expression to SEEK
  3140.         <expC> database alias name, default is current select alias.
  3141.         <expN> index order number to use for SEEK command, default used
  3142.         is the current index order.
  3143.         <expL> .T. to use SOFTSEEK ON, .F. for SOFTSEEK OFF, default is
  3144.         the current SOFTSEEK setting.
  3145.  
  3146. Returns:
  3147.         a logical expression.
  3148.  
  3149. Description:
  3150.         The ISEEK() function does an indexed search of a database and
  3151.         returns the FOUND() condition.
  3152.  
  3153.         <exp> is the key value to search for, <expC> is the database
  3154.         alias to SELECT for the indexed search.  <expN> is the index
  3155.         order number to use in the search, if zero or not supplied the
  3156.         current index order is used.  <expL> to true to use 'softseek
  3157.         on' or false for 'soft-seek off', if <expL> is not passed the
  3158.         current SOFTSEEK setting is used.
  3159.  
  3160. Sample:
  3161.         ******************************************************
  3162.         ** ISEEK() function example
  3163.         **
  3164.         select 0
  3165.         use customer
  3166.         index on cust_nbr to cstmr1
  3167.         index on trim(lname)+" "+fname to cstmr2
  3168.         set index to cstmr1,cstmr2
  3169.  
  3170.         clea
  3171.         mcust_nbr=space(9)
  3172.         @ 1,1 say "Enter Customer Number" get mcust_nbr
  3173.         read
  3174.  
  3175.         if iseek(mcust_nbr,"CUSTOMER",1,.f.)
  3176.           @ 2,1 say "Customer Number Found."
  3177.         endi
  3178.  
  3179.  
  3180.  
  3181.  
  3182.  
  3183.  
  3184.  
  3185.  
  3186.                                   <51>
  3187.                   The Aeolus Procedure and Function Library
  3188.                             Reference Manual
  3189.  
  3190.  
  3191.  
  3192.         LSIDE
  3193.  
  3194.         The LSIDE procedure is called by the TOTALKEYON and TOTALKEYOFF
  3195.         procedures only and should not be used otherwise.  Please see
  3196.         the TOTALKEYON and TOTALKEYOFF procedures for additional infor-
  3197.         mation.  This is included only for completeness.
  3198.  
  3199.  
  3200.  
  3201.  
  3202.  
  3203.  
  3204.  
  3205.  
  3206.  
  3207.  
  3208.  
  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.                                   <52>
  3246.                   The Aeolus Procedure and Function Library
  3247.                             Reference Manual
  3248.  
  3249.  
  3250.  
  3251.         MAKE_EMPTY()
  3252.  
  3253. Syntax:
  3254.         make_empty(<expC>)
  3255.  
  3256. Pass:
  3257.         <expC> existing memory variable name
  3258.  
  3259. Returns:
  3260.         an expression of TYPE(<expC>).
  3261.  
  3262. Description:
  3263.         The memory variable name <expC> is returned in its empty form. A
  3264.         character variable is spaces the length of the passed variable,
  3265.         a numeric is returned as zero, etc.
  3266.  
  3267. Sample:
  3268.         ******************************************************
  3269.         *** Make empty function example
  3270.         ***
  3271.  
  3272.         tst_dat=date()
  3273.         ? make_empty("TST_DAT")     && same as ctod("  /  /  ")
  3274.         tst_nbr=998
  3275.         ? make_empty("TST_NBR")     && same as 0 (zero)
  3276.         tst_chr="Software Can be Groovy"
  3277.         ? make_empty("TST_CHR")     && same as space(22)
  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.                                   <53>
  3305.                   The Aeolus Procedure and Function Library
  3306.                             Reference Manual
  3307.  
  3308.  
  3309.  
  3310.         MAKDIR
  3311.  
  3312. Syntax:
  3313.         call makdir with <expC>
  3314.  
  3315. Pass:
  3316.         <expC> - Name of new DOS subdirectory to create.
  3317.  
  3318. Returns:
  3319.         Nothing.
  3320.  
  3321. Description:
  3322.         The MAKDIR assembly subroutine attempts to create the DOS subdi-
  3323.         rectory passed as <expC>.  No error checking is done and there
  3324.         is no return value.
  3325.  
  3326.         This routine is useful when writing installation programs or end
  3327.         of year archiving and any other reason you may have to create a
  3328.         DOS subdirectory from your Clipper program.  You can test the
  3329.         results of MAKDIR using CHGDIR, CHGDSK and CURDIR()
  3330.  
  3331.         See CHGDIR, CHGDSK
  3332.  
  3333.  
  3334.  
  3335.  
  3336.  
  3337.  
  3338.  
  3339.  
  3340.  
  3341.  
  3342.  
  3343.  
  3344.  
  3345.  
  3346.  
  3347.  
  3348.  
  3349.  
  3350.  
  3351.  
  3352.  
  3353.  
  3354.  
  3355.  
  3356.  
  3357.  
  3358.  
  3359.  
  3360.  
  3361.  
  3362.  
  3363.                                   <54>
  3364.                   The Aeolus Procedure and Function Library
  3365.                             Reference Manual
  3366.  
  3367.  
  3368.  
  3369.         MAXHNDLS()
  3370.  
  3371. Syntax:
  3372.         maxhndls([<expN>)
  3373.  
  3374. Pass:
  3375.         Zero/nothing or a numeric expression
  3376.  
  3377. Returns:
  3378.         If zero or nothing is passed MAXHNDLS() returns the number of
  3379.         file handles available to the program
  3380.  
  3381.         If a number is passed, MAXHNDLS returns true if the number of
  3382.         file handles available is equal or greater, otherwise MAXHNDLS()
  3383.         returns false.  If false is to be returned MAXHNDLS() will dis-
  3384.         play an error box before returning.
  3385.  
  3386. Description:
  3387.         Allows a Clipper program to determine the number of available
  3388.         file handles in the current system configuration.
  3389.  
  3390.         Also displays errors if fewer than <expN> file handles are pre-
  3391.         sent in the current configuration.
  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.                                   <55>
  3423.                   The Aeolus Procedure and Function Library
  3424.                             Reference Manual
  3425.  
  3426.  
  3427.  
  3428.         MEM_HELP
  3429.  
  3430. Syntax:
  3431.         do mem_help
  3432.  
  3433. Pass:
  3434.         Nothing.
  3435.  
  3436. Returns:
  3437.         Nothing
  3438.  
  3439. Description:
  3440.         The MEM_HELP procedure is the three pages of help available when
  3441.         entering a memo field through the EDT_MEMO() function.  There
  3442.         should never be a need for BUILDER users to call it and is
  3443.         included here only for completeness.
  3444.  
  3445.         See EDT_MEMO(), SHOW_MEMO
  3446.  
  3447.  
  3448.  
  3449.  
  3450.  
  3451.  
  3452.  
  3453.  
  3454.  
  3455.  
  3456.  
  3457.  
  3458.  
  3459.  
  3460.  
  3461.  
  3462.  
  3463.  
  3464.  
  3465.  
  3466.  
  3467.  
  3468.  
  3469.  
  3470.  
  3471.  
  3472.  
  3473.  
  3474.  
  3475.  
  3476.  
  3477.  
  3478.  
  3479.  
  3480.  
  3481.                                   <56>
  3482.                   The Aeolus Procedure and Function Library
  3483.                             Reference Manual
  3484.  
  3485.  
  3486.  
  3487.         MEMFUNC()
  3488.  
  3489. Syntax:
  3490.         memfunc(<expN1>,<expN2>,<expN3>)
  3491.  
  3492. Pass:
  3493.         <expN1> - MEMOEDIT() mode
  3494.         <expN2> - MEMOEDIT() row
  3495.         <expN3> - MEMOEDIT() column
  3496.  
  3497. Returns:
  3498.         A numeric expression for MEMOEDIT() to interpret.
  3499.  
  3500. Description:
  3501.         The MEMFUNC() function is called on every keypress while
  3502.         editing a memo field called from the SHOW_MEMO procedure.  It's
  3503.         only function is to limit the number of lines a user can enter
  3504.         into a memo field (if that parameter was passed).  It should not
  3505.         be called and is included only for completeness.
  3506.  
  3507.         See EDT_MEMO(), SHOW_MEMO
  3508.  
  3509.  
  3510.  
  3511.  
  3512.  
  3513.  
  3514.  
  3515.  
  3516.  
  3517.  
  3518.  
  3519.  
  3520.  
  3521.  
  3522.  
  3523.  
  3524.  
  3525.  
  3526.  
  3527.  
  3528.  
  3529.  
  3530.  
  3531.  
  3532.  
  3533.  
  3534.  
  3535.  
  3536.  
  3537.  
  3538.  
  3539.  
  3540.                                   <57>
  3541.                   The Aeolus Procedure and Function Library
  3542.                             Reference Manual
  3543.  
  3544.  
  3545.  
  3546.         MESSAGE()
  3547.  
  3548. Syntax:
  3549.         message(<expC1>,<expN1>,<expN2>[,<expN3>][,<expC2>])
  3550.  
  3551. Pass:
  3552.         <expC1> text to display on the screen
  3553.         <expN1> row to display
  3554.         <expN2> column to display
  3555.         <expN3> length to pad/truncate message text
  3556.         <expC2> alternate color choice
  3557.  
  3558. Returns:
  3559.         Nothing.
  3560.  
  3561. Description:
  3562.         The MESSAGE() function places <expC1> on the screen at row
  3563.         <expN1> column <expN2> and pads <expC1> (or trims it) to a
  3564.         length of <expN3>.  <expC2> may be used as an alternate color
  3565.         choice. If <expN3> is not used, the LEN(<expC1>) is used
  3566.         instead.  If <expC2> is not passed, the current color is used.
  3567.  
  3568. Sample:
  3569.         ***********************************************************
  3570.         *** MESSAGE function example.
  3571.         ***
  3572.  
  3573.         message("Test Message 1",01,00,80,"+w/b")
  3574.         inkey(0)
  3575.  
  3576.  
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.  
  3592.  
  3593.  
  3594.  
  3595.  
  3596.  
  3597.  
  3598.  
  3599.                                   <58>
  3600.                   The Aeolus Procedure and Function Library
  3601.                             Reference Manual
  3602.  
  3603.  
  3604.  
  3605.         MSGBOX()
  3606.  
  3607. Syntax:
  3608.         msgbox(<expC1>[,<expC2>][,<expC3>][,<expC4>][,<expN1>]
  3609.         [,<expN2>][,<expN3>][,<expN4>])
  3610.  
  3611. Pass:
  3612.         <expC1> message for line one or array name.
  3613.         <expC2> alternate color choice
  3614.         <expC3> message for line two - input prompt
  3615.         <expC4> character list for allowable input (null ("") for
  3616.                 any key)
  3617.         <expN1> top left row
  3618.         <expN2> top left column
  3619.         <expN3> bottom right row
  3620.         <expN4> bottom right column
  3621.  
  3622. Returns:
  3623.         nothing or a character expression depending on the value of
  3624.         <expC4>.
  3625.  
  3626. Description:
  3627.         This function puts a message box on the screen and waits for an
  3628.         acknowledgment.
  3629.  
  3630.         If only <expC1> is passed as an argument a box is centered on
  3631.         the screen sized to fit <expC1> inside.  The message is dis-
  3632.         played in bright yellow with a red background by default, useful
  3633.         for error messages.
  3634.  
  3635.         Pass <expC2> as an alternate color choice.
  3636.  
  3637.         <expC3> and <expC4> usually work together, <expC3> is a prompt
  3638.         and <expC4> is a list of characters that, when entered from the
  3639.         keyboard, will remove the box from the screen.
  3640.  
  3641.         <expC4> need only contain one of each alphabetic character as it
  3642.         is converted to upper case before being used by MSGBOX().
  3643.  
  3644.         <expN1> and <expN2> are optional row and column screen positions
  3645.         for the box.
  3646.  
  3647.         <expN3> and <expN4> may be passed to optionally size the box.
  3648.  
  3649.  
  3650.  
  3651.  
  3652.  
  3653.  
  3654.  
  3655.  
  3656.  
  3657.  
  3658.                                   <59>
  3659.                   The Aeolus Procedure and Function Library
  3660.                             Reference Manual
  3661.  
  3662.  
  3663.  
  3664. Sample:
  3665.         *********************************************************
  3666.         *** MSGBOX function example
  3667.         ***
  3668.  
  3669.         msgbox("Error Message")
  3670.         msgbox("Information Message","+w/b")
  3671.         if msgbox("Do You Play the Piano?","+w/b","Press Y or N", ;
  3672.         "YN",10,5)="Y"
  3673.         msgbox("You Pressed Yes","+w/b")
  3674.         else
  3675.         msgbox("You Pressed No","+w/b")
  3676.         endi
  3677.  
  3678.         ** ONLY FOR ARRAYs:  Each element may (optionally) be prefixed
  3679.         **   with "@L" to left justify, "@R" to right justify or "@C" to
  3680.         **   center that element inside the box.  If not used the default
  3681.         **   is "@L".
  3682.  
  3683.         decl msg[0x]
  3684.         msg[01]="An ARRAY message"
  3685.         msg[03]="for the MSGBOX() function to"
  3686.         msg[05]="to Display!"
  3687.         msg[07]="@CI'm Centered !"
  3688.         msg[08]="@RRight Justified."
  3689.         msgbox(@msg)
  3690.  
  3691.  
  3692.  
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.  
  3704.  
  3705.  
  3706.  
  3707.  
  3708.  
  3709.  
  3710.  
  3711.  
  3712.  
  3713.  
  3714.  
  3715.  
  3716.  
  3717.                                   <60>
  3718.                   The Aeolus Procedure and Function Library
  3719.                             Reference Manual
  3720.  
  3721.  
  3722.  
  3723.         NET_USE()
  3724.  
  3725. Syntax:
  3726.         net_use(<expC1>,<expL>,<expN>,<expC2>)
  3727.  
  3728. Pass:
  3729.         <expC1> database alias name
  3730.         <expL>  .T. for exclusive open, .F. for shared
  3731.         <expN>  error timeout seconds if cannot be opened
  3732.         <expC2> alias to use when file is opened
  3733.  
  3734. Returns:
  3735.         a logical expression.
  3736.  
  3737. Description:
  3738.         Opens the database <expC1> in exclusive mode if <expL> is true
  3739.         or non-exclusive if <expL> is false.  If <expN> is the seconds
  3740.         before an error timeout.  <expC2> is the alias that will be
  3741.         used.
  3742.  
  3743. Comment:
  3744.         It is suggested that you use the OPEN_FIL procedure instead of
  3745.         the NET_USE() function, as it automatically handles error condi-
  3746.         tions and parameter passing is more convenient.
  3747.  
  3748.  
  3749.  
  3750.  
  3751.  
  3752.  
  3753.  
  3754.  
  3755.  
  3756.  
  3757.  
  3758.  
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.  
  3768.  
  3769.  
  3770.  
  3771.  
  3772.  
  3773.  
  3774.  
  3775.  
  3776.                                   <61>
  3777.                   The Aeolus Procedure and Function Library
  3778.                             Reference Manual
  3779.  
  3780.  
  3781.  
  3782.         NOT_REQ()
  3783.  
  3784. Syntax:
  3785.         not_req(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>])
  3786.  
  3787. Pass:
  3788.         <expC1> - Error message if field is not blank.
  3789.         <expN1> - Screen row coordinate to display error message.
  3790.         <expN2> - Screen column coordinate to display error message.
  3791.         <expN3> - Rightmost screen column to display error message.
  3792.         <expC2> - Color to display error message.  Default is WERR_CLR.
  3793.  
  3794. Returns:
  3795.         A logical value.
  3796.  
  3797. Description:
  3798.         There are times when you may want to force a user to enter an
  3799.         @...GET as a blank.  The NOT_REQ() valid function is used in
  3800.         these (rare) cases.  Usually conditionally executed.
  3801.  
  3802. Sample:
  3803.        In the following sample @...GETs the user is required to enter
  3804.         a state code and a country name.  If the state code is a valid
  3805.         U.S. state then the country name must be blank otherwise the
  3806.         country name field is required.
  3807.  
  3808.         Program this using BUILDER valids as follows:
  3809.  
  3810.  
  3811.        ** Force a valid U.S. State or Canadian Province or blank
  3812.        **
  3813.        @ dr1+07,dc1+17 get state pict "!!" valid ;
  3814.            genvld(in_usa(state) .or. in_canada(state), ;
  3815.            "ERROR: Not a Valid State or Province",dr2-1,dc1+2,dc2-2,.f.)
  3816.  
  3817.        ** if the state code is valid U.S. state then the country name
  3818.        ** must be blank, otherwise the country name is required.
  3819.        @ dr1+08,dc1+17 get country valid ;
  3820.            if(in_usa(state), ;
  3821.               not_req("Leave Country Blank",dr2-1,dc1+2,dc2-2), ;
  3822.               req("Country Name is Required",dr2-1,dc1+2,dc2-2))
  3823.  
  3824.  
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.  
  3833.  
  3834.  
  3835.                                   <62>
  3836.                   The Aeolus Procedure and Function Library
  3837.                             Reference Manual
  3838.  
  3839.  
  3840.  
  3841.         NUMERIC()
  3842.  
  3843. Syntax:
  3844.         numeric(<expC>)
  3845.  
  3846. Pass:
  3847.         <expC> a string that may or may not contain all numerics
  3848.  
  3849. Returns:
  3850.         a logical expression.
  3851.  
  3852. Description:
  3853.         This function scans every character in <expC> and if every
  3854.         character is between '0' and '9' then it returns true, otherwise
  3855.         false is returned.
  3856.  
  3857.  
  3858.  
  3859.  
  3860.  
  3861.  
  3862.  
  3863.  
  3864.  
  3865.  
  3866.  
  3867.  
  3868.  
  3869.  
  3870.  
  3871.  
  3872.  
  3873.  
  3874.  
  3875.  
  3876.  
  3877.  
  3878.  
  3879.  
  3880.  
  3881.  
  3882.  
  3883.  
  3884.  
  3885.  
  3886.  
  3887.  
  3888.  
  3889.  
  3890.  
  3891.  
  3892.  
  3893.  
  3894.                                   <63>
  3895.                   The Aeolus Procedure and Function Library
  3896.                             Reference Manual
  3897.  
  3898.  
  3899.  
  3900.         OPEN_FIL()
  3901.  
  3902. Syntax:
  3903.         open_fil(<expC1>[,<expL1>][,<expC2>][,<expL2>])
  3904.  
  3905. Returns:
  3906.         a logical expression.
  3907.  
  3908. Pass:
  3909.         <expC1> database name to open
  3910.         <expL1>  .T. for shared open, nothing or .F. for exclusive open
  3911.         <expC2> alias name when open, if other than database name
  3912.         <expL2> .T. to exit to DOS on open errors, .F. to return false
  3913.                 on open errors.
  3914.  
  3915. Description:
  3916.         The OPEN_FIL function will attempt to open the file <expC1> in
  3917.         exclusive mode-even if SET EXCLUSIVE OFF is in effect-unless the
  3918.         second parameter is sent as true.  Use the third parameter to
  3919.         set the alias if you want the alias other than the default of
  3920.         <expC1>.  <expL2> determines how the OPEN_FIL function will
  3921.         react when it cannot open a .DBF file, passing .T. (or not pass-
  3922.         ing this parameter) will cause OPEN_FIL to exit to DOS on error
  3923.         conditions. Passing <expL2> as .F. will cause OPEN_FIL to return
  3924.         a logical false if it fails to open the file.
  3925.  
  3926.         The OPEN_FIL function tests for four (4) error conditions.  If
  3927.         an error is detected, an error box is displayed and OPEN_FIL
  3928.         either exits to DOS or returns false to the application depend-
  3929.         ing on the value of <expL2>.  The errors tested for are as fol-
  3930.         lows:
  3931.  
  3932.         1.  Invalid Alias Name.  If no specific alias name is sent to
  3933.         the OPEN_FIL function the file name (<expC1>) is used.  A valid
  3934.         alias name must contain the letter 'A' through 'Z' in the first
  3935.         character position.  The second through tenth character posi-
  3936.         tions can contain 'A' through 'Z', '0' through '9' or '_'.
  3937.  
  3938.         2.  File not found.  Before a database is USEd OPEN_FIL tests
  3939.         the Clipper FILE() function to determine if the file exists.
  3940.  
  3941.         3.  Already in Use.  The database is already USEd in EXCLUSIVE
  3942.         mode or the file has been locked.
  3943.  
  3944.         4.  .DBT file is missing.  OPEN_FIL tried to USE a database but
  3945.         the memo field data file (.DBT file) is missing.
  3946.  
  3947.  
  3948.  
  3949.  
  3950.  
  3951.  
  3952.  
  3953.                                   <64>
  3954.                   The Aeolus Procedure and Function Library
  3955.                             Reference Manual
  3956.  
  3957.  
  3958.  
  3959.         PADC()
  3960.  
  3961. Syntax:
  3962.         padc(<expC1>,<expN>[,<expC2])
  3963.  
  3964. Pass:
  3965.         <expC1> text to pad/truncate
  3966.         <expN>  length of returned string
  3967.         <expC2> fill character, default is space
  3968.  
  3969. Returns:
  3970.         a character expression.
  3971.  
  3972. Description:
  3973.         This function pads or trims <expC1> to a length of <expN> using
  3974.         <expC2> as the fill character.  PADC() returns a centered char-
  3975.         acter string.
  3976.  
  3977.  
  3978.  
  3979.  
  3980.  
  3981.  
  3982.  
  3983.  
  3984.  
  3985.  
  3986.  
  3987.  
  3988.  
  3989.  
  3990.  
  3991.  
  3992.  
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.                                   <65>
  4013.                   The Aeolus Procedure and Function Library
  4014.                             Reference Manual
  4015.  
  4016.  
  4017.  
  4018.         PADL()
  4019.  
  4020. Syntax:
  4021.         padl(<expC1>,<expN>[,<expC2])
  4022.  
  4023. Pass:
  4024.         <expC1> text to pad/truncate
  4025.         <expN>  length of returned string
  4026.         <expC2> fill character, default is space
  4027.  
  4028. Returns:
  4029.         a character expression.
  4030.  
  4031. Description:
  4032.         This function pads or trims <expC1> to a length of <expN> using
  4033.         <expC2> as the fill character.  PADL() returns a right justified
  4034.         character string.
  4035.  
  4036.  
  4037.  
  4038.  
  4039.  
  4040.  
  4041.  
  4042.  
  4043.  
  4044.  
  4045.  
  4046.  
  4047.  
  4048.  
  4049.  
  4050.  
  4051.  
  4052.  
  4053.  
  4054.  
  4055.  
  4056.  
  4057.  
  4058.  
  4059.  
  4060.  
  4061.  
  4062.  
  4063.  
  4064.  
  4065.  
  4066.  
  4067.  
  4068.  
  4069.  
  4070.  
  4071.                                   <66>
  4072.                   The Aeolus Procedure and Function Library
  4073.                             Reference Manual
  4074.  
  4075.  
  4076.  
  4077.         PADR()
  4078.  
  4079. Syntax:
  4080.         padr(<expC1>,<expN>[,<expC2])
  4081.  
  4082. Pass:
  4083.         <expC1> text to pad/truncate
  4084.         <expN>  length of returned string
  4085.         <expC2> fill character, default is space
  4086.  
  4087. Returns:
  4088.         a character expression.
  4089.  
  4090. Description:
  4091.         This function pads or trims <expC1> to a length of <expN> using
  4092.         <expC2> as the fill character.  PADR() returns a left justified
  4093.         character string.
  4094.  
  4095.  
  4096.  
  4097.  
  4098.  
  4099.  
  4100.  
  4101.  
  4102.  
  4103.  
  4104.  
  4105.  
  4106.  
  4107.  
  4108.  
  4109.  
  4110.  
  4111.  
  4112.  
  4113.  
  4114.  
  4115.  
  4116.  
  4117.  
  4118.  
  4119.  
  4120.  
  4121.  
  4122.  
  4123.  
  4124.  
  4125.  
  4126.  
  4127.  
  4128.  
  4129.  
  4130.                                   <67>
  4131.                   The Aeolus Procedure and Function Library
  4132.                             Reference Manual
  4133.  
  4134.  
  4135.  
  4136.         PCKVLD()
  4137.  
  4138. Syntax:
  4139.         pckvld(<expC1>,<expN1>,<expN2>,<expL1>,<expC2>,<expL2> ;
  4140.                [,<expC3>][,<expC4>])
  4141.  
  4142. Pass:
  4143.         <expC1> - File alias name for picklist.
  4144.         <expN1> - Field ordinal number in database to place in
  4145.                   GET field on pick list selection.
  4146.         <expN2> - Index order number to use on <expC1> to find
  4147.                   the GET input data.
  4148.         <expL1> - .T. = Use QWERTY scroll.  .F. Do not use QWERTY
  4149.                   scroll.
  4150.         <expC2> - Display expression for picklist.
  4151.         <expL2> - .T. = accept blank for GET input, .F. = force
  4152.                   entry into GET.
  4153.         <expC3> - Key value SEEK prefix.  Default nothing.
  4154.         <expC4> - STAY AT field name for a bounded by picklist.
  4155.                   Default is no bounded by field.
  4156.  
  4157. Returns:
  4158.         A logical expression.
  4159.  
  4160. Description:
  4161.         The PCKVLD() function can only be used in the VALID of a GET.
  4162.         PCKVLD() will SEEK on the <expC1> database using index order
  4163.         <expN2> and if value of FIELD(<expN1>) is equal to the value
  4164.         entered into the GET the cursor will move to the next field in
  4165.         the GET stream.  If there is not an exact match a pick list is
  4166.         given to the user with the highlight bar positioned to the near-
  4167.         est record to the GET input.  The user may then move to the
  4168.         desired record, and press ENTER to put that data into the GET
  4169.         field an move to the next field in the GET stream.
  4170.  
  4171.         See POP().
  4172.  
  4173. Sample:
  4174.         You are building an order entry system and one of the fields on
  4175.         the order is 'Sales Person'.  This field is a three character
  4176.         field of the persons initials.  You want to verify that what is
  4177.         entered into this field is a valid employee, but also that the
  4178.         employee is a sales person.  PCKVLD() can be used to do this in
  4179.         the following manner.
  4180.  
  4181.         Technical assumptions:
  4182.           Employee file is called "EMPLYEE".
  4183.  
  4184.           The field EMPLYEE->TYPE is a one byte character field indicating
  4185.           the department the employee works in.
  4186.  
  4187.           That EMPLYEE->TYPE="S" is the sales department.
  4188.  
  4189.                                   <68>
  4190.                   The Aeolus Procedure and Function Library
  4191.                             Reference Manual
  4192.  
  4193.  
  4194.  
  4195.  
  4196.           The field EMPLYEE->INITIALS is a three byte character field
  4197.           of the employees initials.
  4198.  
  4199.           Index order number one has the index key TYPE+INITIALS on
  4200.           the EMPLYEE file.
  4201.  
  4202.           The field EMPLYEE->INITIALS is the second field in the database.
  4203.  
  4204.  
  4205.           ** The following PCKVLD() will not allow QINV_SLSMAN
  4206.           ** to be blank.  Will only allow entry if these Clipper
  4207.           ** program statements ...
  4208.           **
  4209.           ** SELECT EMPLYEE
  4210.           ** SET ORDER TO 1
  4211.           ** SEEK "S"+QINV_SLSMAN
  4212.           **
  4213.           ** ... set FOUND() to .T.
  4214.           **
  4215.           ** If the entry is not FOUND() then a pick list is presented
  4216.           ** displaying the initials, first, and last name.  The picklist
  4217.           ** will only display EMPLYEE->TYPE="S" records because of the
  4218.           ** index key expression, the key prefix passed, and the bounded
  4219.           ** by being set.
  4220.           **
  4221.           @ dr1+11,dc1+23 get qinv_slsman pict "!!!" valid ;
  4222.               pckvld("EMPLYEE",2,1,.f., ;
  4223.               'initials+" "+fname+" "+lname',.t.,"S","TYPE")
  4224.  
  4225.           The PCKVLD() function is easier to digest if you understand the
  4226.           POP() function.  The source code to call this function can be
  4227.           automatically generated by BUILDER.
  4228.  
  4229.  
  4230.  
  4231.  
  4232.  
  4233.  
  4234.  
  4235.  
  4236.  
  4237.  
  4238.  
  4239.  
  4240.  
  4241.  
  4242.  
  4243.  
  4244.  
  4245.  
  4246.  
  4247.  
  4248.                                   <69>
  4249.                   The Aeolus Procedure and Function Library
  4250.                             Reference Manual
  4251.  
  4252.  
  4253.  
  4254.         PLIST()
  4255.  
  4256. Syntax:
  4257.         plist(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expN5>,<expC2> ;
  4258.         [,<expL1>][,<expC3>][,<expC4>][,<expC5>][,<expC6>] ;
  4259.         [,<expL2>][,<expL3>][,<expC7>]
  4260.  
  4261. Pass:
  4262.         <expN1> top row for picklist box
  4263.         <expN2> left column for picklist box
  4264.         <expN3> bottom row for picklist box
  4265.         <expN4> right column for picklist box
  4266.         <expC1> database alias name
  4267.         <expN5> index order number used for picklist
  4268.         <expC2> expression to display on each picklist line
  4269.         <expL1> enable QWERTY scroll function, default false.
  4270.         <expC3> memvar for QWERTY scroll initialization (prefix with @)
  4271.         <expC4> color for pointer bar, if not using WREV_CLR
  4272.         <expC5> procedure to execute on ENTER key
  4273.         <expC6> condition expression for bounded picklist
  4274.         <expL2> PLIST() to display message line?
  4275.         <expL3> PLIST() to display border?
  4276.         <expC7> Seek prefix when QWERTY scroll is used.
  4277.  
  4278. Returns:
  4279.         a numeric expression.  The record number selected.
  4280.  
  4281. Description:
  4282.         The PLIST() function creates a scrollable pick list box to be pre-
  4283.         sented on the screen.  This function is a replacement for the
  4284.         POP() function of BUILDER ver 1.0.  POP() is kept in the librar-
  4285.         y for compatibility.
  4286.  
  4287.         <expN1> and <expN2> are the row and column of the upper left
  4288.         corner of the pick list box.
  4289.  
  4290.         <expN3> and <expN4> are the height and width of the box respec-
  4291.         tively
  4292.  
  4293.         <expC1> is the database alias to 'browse'.
  4294.  
  4295.         <expN5> is the index order number to use when this picklist if
  4296.         being viewed.
  4297.  
  4298.         When <expC2> is evaluated as a macro it is displayed on each
  4299.         line in the box.
  4300.  
  4301.         If <expL1> is passed as true then a field delimited with square
  4302.         brackets will be placed on the top of the box.  Any QWERTY text
  4303.         entered will be displayed between the brackets and that text
  4304.         will be used as a SEEK key and the POP() box will be refilled
  4305.         using that value.  If <expC7> was passed the SEEK value will be
  4306.  
  4307.                                   <70>
  4308.                   The Aeolus Procedure and Function Library
  4309.                             Reference Manual
  4310.  
  4311.  
  4312.  
  4313.         <expC7> + QWERTY value before refilling the PLIST() box.
  4314.  
  4315.         <expC3> is used in conjunction with <expL1> and contains the
  4316.         name of the memory variable that contains the starting key value
  4317.         to be placed between the square brackets.  If you choose to set
  4318.         <expL1> to true and not use this argument the QWERTY area will
  4319.         be sized according to the length of the INDEXKEY(0) function.
  4320.  
  4321.         <expC4> is an optional color for the pointer bar.
  4322.  
  4323.         <expC5> is an optional (strongly recommended) name of a proce-
  4324.         dure to be executed on selection of an element.
  4325.  
  4326.         Warning:  <expC5> can only contain the procedure name and cannot
  4327.         contain a 'WITH' clause or parameters.
  4328.  
  4329.         <expC6> is an optional logical expression that will restrict
  4330.         scrolling only while the expression returns true (.T.).  This
  4331.         expression must return true (.T.) when PLIST() is initially
  4332.         called.  Pass this parameter as a character expression that when
  4333.         evaluated as a macro will return a logical value.
  4334.  
  4335.         Warning:  if you use <expC6> to set database bounds AND <expL1>
  4336.         is set to true, you will need to also use <expC7> (SEEK pre-
  4337.         fix).
  4338.  
  4339.         Use <expL2> and <expL3> to optionally turn off some PLIST()
  4340.         default display items.  Both <expL2> and <expL3> default to true
  4341.         (.T.).  Pass false (.F.) in <expL2> and PLIST() will not display
  4342.         it's default message line.  Pass false (.F.) in <expL3> and
  4343.         PLIST() will not display a window border around the PLIST()
  4344.         data.
  4345.  
  4346. Sample:
  4347.         *****************************************************
  4348.         * This example displays a pick list box at row 2
  4349.         * column 40, it is 9 rows tall and 23 columns wide.
  4350.         * It displays the field COUNTRY from the database
  4351.         * INTRNTNL and provides the user a field to enter QWERTY
  4352.         * text to move to different parts of the database.
  4353.         * If a record is selected the procedure INTL_DTL is executed.
  4354.  
  4355.         sele intrntnl
  4356.         go top
  4357.  
  4358.         ** display international
  4359.         **
  4360.         sele intrntnl
  4361.         kf=space(20)
  4362.  
  4363.         intl_rec=pop(02,40,9,23,"INTRNTNL",1,"country",.t., ;
  4364.                      @KF,"","intl_dtl")
  4365.  
  4366.                                   <71>
  4367.                   The Aeolus Procedure and Function Library
  4368.                             Reference Manual
  4369.  
  4370.  
  4371.  
  4372.  
  4373.         Sample2:
  4374.         *****************************************************
  4375.         * This example displays a pick list box at row 2
  4376.         * column 19, it is 9 rows tall and 20 columns wide.
  4377.         * It displays the fields PART_NBR and PART_END from the
  4378.         * database MSPART.
  4379.         * If a record is selected the procedure MS_DETAIL is executed.
  4380.  
  4381.         sele mspart
  4382.         go top
  4383.  
  4384.         ** display part list
  4385.         **
  4386.         ms_fld='part_nbr+"-"+part_end'
  4387.  
  4388.         prt_rec=plist(02,19,11,39,"MSPART",1,ms_fld,.t.,"","", ;
  4389.         "ms_detail")
  4390.  
  4391.  
  4392.         Sample 3:
  4393.         *************************************************************
  4394.         ** This example will display a picklist box on the screen and
  4395.         ** combine both the Bounded by AND the QWERTY scroll features
  4396.         ** The last parameter passed allows this, however, careful
  4397.         ** consideration must also be given to the index and database
  4398.         ** being used.
  4399.         **
  4400.         ** We will browse the database PARTS which is a very large
  4401.         ** database with part numbers and names we want to display.
  4402.         ** This database also has a code to indicate what type of
  4403.         ** part the record contains.  There are three part type codes
  4404.         ** "P"-Plumbing, "H"-Heating, and "E"-Electrical.
  4405.         **
  4406.         ** Before reaching this point in the program the user has
  4407.         ** already selected the part type to be viewed.  So the
  4408.         ** picklist should be bounded by the PART_TYP field.
  4409.         ** The only part type to be displayed in this pick list is
  4410.         ** indicated in the memvar DTYP which is equal to "P", "H",
  4411.         ** or "E" before this area of the program is executed
  4412.         **
  4413.         ** Since there are so many parts of each type, we will also
  4414.         ** provide a QWERTY scroll field to allow faster locating.
  4415.         **
  4416.         ** Index order one has the index key expression of:
  4417.         **     PART_TYP+PART_NBR
  4418.         **
  4419.         **     PART_TYP is Character 1 byte long
  4420.         **     PART_NBR is Character 12 bytes long
  4421.         **
  4422.         ** If a part number is selected, proceed to the order entry
  4423.         ** screen, procedure ORD_ENTRY
  4424.  
  4425.                                   <72>
  4426.                   The Aeolus Procedure and Function Library
  4427.                             Reference Manual
  4428.  
  4429.  
  4430.  
  4431.  
  4432.  
  4433.         bpart_typ=PARTS->part_typ
  4434.         bcond="PART_TYP==BPART_TYP"
  4435.  
  4436.         kf=space(12)          && length of part number for qwerty
  4437.                               && scroll default would be length of
  4438.                               && index expression, in this case 13.
  4439.  
  4440.         ** set up the display expression
  4441.         de='transform(part_nbr,"@R 99-999999-999-!")+" "+desc'
  4442.  
  4443.         ** display the picklist
  4444.         plist(02,01,14,66,"PARTS",1,DE,.t.,@kf,"","ORD_ENTRY", ;
  4445.               BCOND,.t.,.t.,DTYP)
  4446.  
  4447.         ** Parms 1-4 set the screen coordinates.
  4448.         ** Parms 5 and 6 are the database alias name and index order
  4449.         ** used during picklist operation.
  4450.         ** Parm 7 (DE) is the display expression defined above.
  4451.         ** Parm 8 (.T.) turns on the QWERTY scroll feature.
  4452.         ** Parm 9 (@kf) passes the QWERTY scroll initialization
  4453.         ** value.  This could also have been initialized like:
  4454.         **    kf=PARTS->part_nbr
  4455.         ** to put something IN the picklist entry field.
  4456.         ** Parm 10 ("") nothing, use the default color for the
  4457.         ** highlight bar.
  4458.         ** Parm 11 ("ORD_ENTRY") the procedure named ORD_ENTRY
  4459.         ** will get executed after the ENTER key is pressed.  i.e.
  4460.         ** a part is selected.
  4461.         ** Parm 12 (BCOND) passes the Bounds condition variable.
  4462.         ** This memvar is set above and if macro'd returns true,
  4463.         ** all records where this returns false will not be visible
  4464.         ** in this picklist.
  4465.         ** Parms 13 and 14 tell PLIST() to display a window border and
  4466.         ** a default message line
  4467.         ** Parm 15 (DTYP) Required for Bounded QWERTY picklists.  When
  4468.         ** a QWERTY key is pressed, the SEEK will be on DTYP+{Current-
  4469.         ** QWERTY-Text}.
  4470.  
  4471.  
  4472.  
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480.  
  4481.  
  4482.  
  4483.  
  4484.                                   <73>
  4485.                   The Aeolus Procedure and Function Library
  4486.                             Reference Manual
  4487.  
  4488.  
  4489.  
  4490.         POP()
  4491.  
  4492. Syntax:
  4493.         pop(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2> ;
  4494.         [,<expL1>][,<expC3>][,<expC4>][,<expC5>][,<expC6>] ;
  4495.         [,<expL2>][,<expL3>][,<expC7>]
  4496.  
  4497. Pass:
  4498.         <expN1> top left row for picklist box
  4499.         <expN2> top left column for picklist box
  4500.         <expN3> picklist height in rows
  4501.         <expN4> picklist width in columns
  4502.         <expC1> database alias name
  4503.         <expC2> expression to display on each picklist line
  4504.         <expL1> enable QWERTY scroll function, default false.
  4505.         <expC3> memvar for QWERTY scroll initialization (prefix with @)
  4506.         <expC4> color for pointer bar, if not using WREV_CLR
  4507.         <expC5> procedure to execute on ENTER key
  4508.         <expC6> database fieldname for bounded picklist
  4509.         <expL2> POP() to display message line.
  4510.         <expL3> POP() to display border.
  4511.         <expC7> Seek prefix when QWERTY scroll is used.
  4512.  
  4513. Returns:
  4514.         a numeric expression.  The record number selected.
  4515.  
  4516. Description:
  4517.         The POP() function creates a scrollable pick list box to be pre-
  4518.         sented on the screen.
  4519.  
  4520.         <expN1> and <expN2> are the row and column of the upper left
  4521.         corner of the pick list box.
  4522.  
  4523.         <expN3> and <expN4> are the height and width of the box respec-
  4524.         tively
  4525.  
  4526.         <expC1> is the database alias to 'browse'.
  4527.  
  4528.         When <expC2> is evaluated as a macro it is displayed on each
  4529.         line in the box.
  4530.  
  4531.         If <expL1> is passed as true then a field delimited with square
  4532.         brackets will be placed on the top of the box.  Any QWERTY text
  4533.         entered will be displayed between the brackets and that text
  4534.         will be used as a SEEK key and the POP() box will be refilled
  4535.         using that value.  If <expC7> was passed the SEEK value will be
  4536.         <expC7> + QWERTY value before refilling the POP() box.
  4537.  
  4538.         <expC3> is used in conjunction with <expL1> and contains the
  4539.         name of the memory variable that contains the starting key value
  4540.         to be placed between the square brackets.  If you choose to set
  4541.         <expL1> to true and not use this argument the QWERTY area will
  4542.  
  4543.                                   <74>
  4544.                   The Aeolus Procedure and Function Library
  4545.                             Reference Manual
  4546.  
  4547.  
  4548.  
  4549.         be sized according to the length of the INDEXKEY(0) function.
  4550.  
  4551.         <expC4> is an optional color for the pointer bar.
  4552.  
  4553.         <expC5> is an optional (strongly recommended) name of a proce-
  4554.         dure to be executed on selection of an element.
  4555.  
  4556.         Warning:  <expC5> can only contain the procedure name and cannot
  4557.         contain a 'WITH' clause or parameters.
  4558.  
  4559.         <expC6> is an optional fieldname that will restrict scrolling
  4560.         only while the fieldname passed is equal to the value on entry
  4561.         into the POP() function.  The database must be sorted or indexed
  4562.         so that the passed fieldname will have the same value for a con-
  4563.         tiguous series of records.
  4564.  
  4565.         Warning:  <expC6> can only be use if <expL1> is set to false.
  4566.  
  4567.         Use <expL2> and <expL3> to optionally turn off some POP()
  4568.         default display items.  Both <expL2> and <expL3> default to true
  4569.         (.T.).  Pass false (.F.) in <expL2> and POP() will not display
  4570.         it's default message line.  Pass false (.F.) in <expL3> and
  4571.         POP() will not display a window border around the POP() data.
  4572.  
  4573. Sample:
  4574.         *****************************************************
  4575.         * This example displays a pick list box at row 2
  4576.         * column 40, it is 9 rows tall and 23 columns wide.
  4577.         * It displays the field COUNTRY from the database
  4578.         * INTRNTNL and provides the user a field to enter QWERTY
  4579.         * text to move to different parts of the database.
  4580.         * If a record is selected the procedure INTL_DTL is executed.
  4581.  
  4582.         sele intrntnl
  4583.         go top
  4584.  
  4585.         ** display international
  4586.         **
  4587.         sele intrntnl
  4588.         kf=space(20)
  4589.  
  4590.         intl_rec=pop(02,40,9,23,"INTRNTNL","country",.t., ;
  4591.         @KF,"","intl_dtl")
  4592.  
  4593.         Sample2:
  4594.         *****************************************************
  4595.         * This example displays a pick list box at row 2
  4596.         * column 19, it is 9 rows tall and 20 columns wide.
  4597.         * It displays the fields PART_NBR and PART_END from the
  4598.         * database MSPART.
  4599.         * If a record is selected the procedure MS_DETAIL is executed.
  4600.  
  4601.  
  4602.                                   <75>
  4603.                   The Aeolus Procedure and Function Library
  4604.                             Reference Manual
  4605.  
  4606.  
  4607.  
  4608.         k_part_nbr=space(8)
  4609.  
  4610.         sele mspart
  4611.         go top
  4612.  
  4613.         ** display part list
  4614.         **
  4615.         sele mspart
  4616.         kf="K_PART_NBR"
  4617.  
  4618.         ms_fld='if(empty(part_nbr),space(17),part_nbr+"-"+part_end)'
  4619.  
  4620.         prt_rec=pop(02,19,9,20,"MSPART",ms_fld,.t.,"","", ;
  4621.         "ms_detail")
  4622.  
  4623.  
  4624.  
  4625.  
  4626.  
  4627.  
  4628.  
  4629.  
  4630.  
  4631.  
  4632.  
  4633.  
  4634.  
  4635.  
  4636.  
  4637.  
  4638.  
  4639.  
  4640.  
  4641.  
  4642.  
  4643.  
  4644.  
  4645.  
  4646.  
  4647.  
  4648.  
  4649.  
  4650.  
  4651.  
  4652.  
  4653.  
  4654.  
  4655.  
  4656.  
  4657.  
  4658.  
  4659.  
  4660.  
  4661.                                   <76>
  4662.                   The Aeolus Procedure and Function Library
  4663.                             Reference Manual
  4664.  
  4665.  
  4666.  
  4667.         POP_KEY
  4668.  
  4669.         The POP_KEY procedure is called by the POP() function only and
  4670.         should not be used otherwise.  Please see the POP() function for
  4671.         additional information.  This is included only for completeness.
  4672.  
  4673.  
  4674.  
  4675.  
  4676.  
  4677.  
  4678.  
  4679.  
  4680.  
  4681.  
  4682.  
  4683.  
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.  
  4691.  
  4692.  
  4693.  
  4694.  
  4695.  
  4696.  
  4697.  
  4698.  
  4699.  
  4700.  
  4701.  
  4702.  
  4703.  
  4704.  
  4705.  
  4706.  
  4707.  
  4708.  
  4709.  
  4710.  
  4711.  
  4712.  
  4713.  
  4714.  
  4715.  
  4716.  
  4717.  
  4718.  
  4719.  
  4720.                                   <77>
  4721.                   The Aeolus Procedure and Function Library
  4722.                             Reference Manual
  4723.  
  4724.  
  4725.  
  4726.         PUBL_COLO
  4727.  
  4728. Syntax:
  4729.         do publ_colo
  4730.  
  4731. Pass:
  4732.         Nothing
  4733.  
  4734. Description:
  4735.         The BUILDER executes this procedure in the initialization of all
  4736.         the programs it creates.  This procedure creates several public
  4737.         variables and initializes them for use by the program.
  4738.  
  4739.         The initialized variables are:
  4740.  
  4741.         HDR_CLR   screen header box color
  4742.         HDR_MSG   header message color
  4743.         BKGD_CLR  screen background color
  4744.         BMSG_CLR  background message color
  4745.         BERR_CLR  background error color
  4746.         BREV_CLR  background reverse color
  4747.  
  4748.         WNDW_CLR  window color
  4749.         WMSG_CLR  window message color
  4750.         WERR_CLR  window error color
  4751.         WREV_CLR  window reverse color
  4752.  
  4753.         WNDW2_CLR secondary window color
  4754.         WMSG2_CLR secondary window message color
  4755.  
  4756.         SHDW_CLR  shadow color
  4757.         ERR_CLR   error box color
  4758.         MSG_CLR   message line color
  4759.  
  4760.         Most of these are modifiable using the "Colors" option of the
  4761.         BUILDER main menu.
  4762.  
  4763.  
  4764.  
  4765.  
  4766.  
  4767.  
  4768.  
  4769.  
  4770.  
  4771.  
  4772.  
  4773.  
  4774.  
  4775.  
  4776.  
  4777.  
  4778.  
  4779.                                   <78>
  4780.                   The Aeolus Procedure and Function Library
  4781.                             Reference Manual
  4782.  
  4783.  
  4784.  
  4785.         REC_LOCK()
  4786.  
  4787. Syntax:
  4788.         rec_lock(<expN>)
  4789.  
  4790. Pass:
  4791.         <expN> seconds before error timeout, pass zero to never timeout.
  4792.  
  4793. Returns:
  4794.         A logical expression.
  4795.  
  4796. Description:
  4797.         Attempts to lock the record of the currently selected data-
  4798.         base for timeout period of <expN> seconds.  If the record cannot
  4799.         be locked after the timeout period an error box is presented to
  4800.         try again, if No is selected, a logical false is returned.  If
  4801.         <expN> is zero or not passed to the function, REC_LOCK() will
  4802.         wait indefinitely.
  4803.  
  4804. Comment:
  4805.         The SAVE_IT() function performs all record locking before any
  4806.         file I/O and you should not have to use this function.
  4807.  
  4808.         However...
  4809.         some shops require that a record is locked during editing and
  4810.         all the functions and procedures here only lock a record immedi-
  4811.         ately before any file I/O so you may need to use this function.
  4812.  
  4813.  
  4814.  
  4815.  
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.  
  4823.  
  4824.  
  4825.  
  4826.  
  4827.  
  4828.  
  4829.  
  4830.  
  4831.  
  4832.  
  4833.  
  4834.  
  4835.  
  4836.  
  4837.  
  4838.                                   <79>
  4839.                   The Aeolus Procedure and Function Library
  4840.                             Reference Manual
  4841.  
  4842.  
  4843.  
  4844.         REL_MAINT
  4845.  
  4846. Syntax:
  4847.         REL_MAINT(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ;
  4848.             <expC2>,<expC3>,<expC4>,<expN5>,<expN6>[,<expC5>][,<expC6>]
  4849.  
  4850. Pass:
  4851.         <expN1> The row number to put the Add/Change/Delete menu, usu-
  4852.                 ally the top border of the window.
  4853.         <expN2> The column number for the Add/Change/Delete menu,
  4854.                 yes, you calculate to center it.
  4855.         <expN3> The row number for messages, usually the bottom line
  4856.                 of the box, not the border but inside the box.
  4857.         <expN4> The column number for messages, usually two spaces to
  4858.                 the right of the left window border.
  4859.         <expC1> You must declare a procedure that contains the GETs for
  4860.                 the maintenance the first three letters of which must
  4861.                 be 'GET'.  Pass in <expC1> the characters you add to
  4862.                 make the procedure unique.
  4863.         <expC2> The condition that relates the file to be edited, this
  4864.                 must be a logical true when evaluated as a macro.  All
  4865.                 contiguous records where the condition remains true
  4866.                 will be available for editing.
  4867.  
  4868.                 Note: The SET RELATION TO ... command does NOT need to
  4869.                 be in effect to use this procedure, the databases merely
  4870.                 need to have a one to many relationship.
  4871.         <expC3> Database alias name to be edited.
  4872.         <expC4> Memory variable prefix character(s).
  4873.         <expN5> The 'delete index' order number, zero (0) if a 'delete
  4874.                 index' is not used.
  4875.         <expN6> The number of fields to be edited.
  4876.         <expC5> The first character of each menu pad to use.
  4877.         <expC6> User function executed on file I/O and before exit.
  4878.  
  4879.         <expC5> and <expC6> work identically to the last two parameters
  4880.         passed to GEN_MAINT.  See the documentation on that procedure
  4881.         for more information on these parameters.
  4882.  
  4883. Description:
  4884.         The REL_MAINT procedure is used to edit the 'many' records in
  4885.         the child database when a one-to-many database relationship
  4886.         exists.
  4887.  
  4888.         This function is designed to be easily created from a BUILDER
  4889.         dialog box.
  4890.  
  4891.         If you are unsure what a 'delete index' is refer to the
  4892.         GEN_MAINT procedure for clarification.
  4893.  
  4894.         Look carefully at the following sample to see how to set up a
  4895.         REL_MAINT call.
  4896.  
  4897.                                   <80>
  4898.                   The Aeolus Procedure and Function Library
  4899.                             Reference Manual
  4900.  
  4901.  
  4902.  
  4903.  
  4904. Sample:
  4905.         ** note: prior to calling rel_maint all fields in the database
  4906.         ** have been copied to memory variables with identical names
  4907.         ** except the memory variables (in this example) are prefixed
  4908.         ** with the letter "Q".  See DBPUBL, DBSTOR for more info.
  4909.  
  4910.         ************************************************
  4911.         ** CALLED BY: Pick List Window Proc:  PLST003 **
  4912.         **   Comment: Model Maint Dialog              **
  4913.         ************************************************
  4914.         proc dlog004
  4915.           private dr1,dc1,dr2,dc2
  4916.  
  4917.           ** save key to a memory variable
  4918.           ** important you code something like this!
  4919.           rpartno=model->partno
  4920.  
  4921.           dr1=15
  4922.           dc1=45
  4923.           dr2=dr1+04
  4924.           dc2=dc1+32
  4925.           set colo to (wndw_clr)
  4926.           winpush(dr1,dc1,dr2,dc2)
  4927.           @ dr1+02,dc1+04 say "Model Number"
  4928.  
  4929.           ** call rel_maint to edit all contiguous records in the MODEL
  4930.           ** database with the field MODEL->PARTNO equal to the memory
  4931.           ** variable RPARTNO.
  4932.           rel_maint(;
  4933.             dr1,dc1+6,dr2-1,dc1+2,"004","MODEL->PARTNO=RPARTNO", ;
  4934.               "MODEL","Q",2,1)
  4935.           winpop()
  4936.  
  4937.  
  4938.         ** this proc created by copying the GETs created by BUILDER to
  4939.         ** a proc with the first three characters equal to "GET", I
  4940.         ** arbitrarily chose "004" as the second part of the name (
  4941.         ** because it matches DLOG004) and pass "004" as the fifth
  4942.         ** parameter above.
  4943.         proc get004
  4944.           para g_func           && A-Add, C-Change, D-Delete.
  4945.  
  4946.           ** absolutely IMPERATIVE the key variables get set from
  4947.           ** previously saved memory variables here!!
  4948.           qpartno=rpartno
  4949.  
  4950.           @ dr1+02,dc1+18 get qmodel pict "@!"
  4951.  
  4952.  
  4953.         Not including the comments only four lines of code were added to
  4954.         a BUILDER dialog box to create this (many more were deleted).
  4955.  
  4956.                                   <81>
  4957.                   The Aeolus Procedure and Function Library
  4958.                             Reference Manual
  4959.  
  4960.  
  4961.  
  4962.         This is a small example, but should clearly show how to set up a
  4963.         REL_MAINT of your own.
  4964.  
  4965.  
  4966.  
  4967.  
  4968.  
  4969.  
  4970.  
  4971.  
  4972.  
  4973.  
  4974.  
  4975.  
  4976.  
  4977.  
  4978.  
  4979.  
  4980.  
  4981.  
  4982.  
  4983.  
  4984.  
  4985.  
  4986.  
  4987.  
  4988.  
  4989.  
  4990.  
  4991.  
  4992.  
  4993.  
  4994.  
  4995.  
  4996.  
  4997.  
  4998.  
  4999.  
  5000.  
  5001.  
  5002.  
  5003.  
  5004.  
  5005.  
  5006.  
  5007.  
  5008.  
  5009.  
  5010.  
  5011.  
  5012.  
  5013.  
  5014.  
  5015.                                   <82>
  5016.                   The Aeolus Procedure and Function Library
  5017.                             Reference Manual
  5018.  
  5019.  
  5020.  
  5021.         REQ()
  5022.  
  5023. Syntax:
  5024.         req(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>])
  5025.  
  5026. Pass:
  5027.         <expC1> - Error message if field is blank.
  5028.         <expN1> - Screen row coordinate to display error message.
  5029.         <expN2> - Screen column coordinate to display error message.
  5030.         <expN3> - Rightmost screen column to display error message.
  5031.         <expC2> - Color to display error message.  Default is WERR_CLR.
  5032.  
  5033. Returns:
  5034.         A logical value.
  5035.  
  5036. Description:
  5037.         This VALID function forces entry of an @...GET field to be non-
  5038.         blank.  It simply checks if the GET value is EMPTY() and only
  5039.         allows the cursor past the GET is it is not EMPTY().
  5040.  
  5041. Sample:
  5042.         In this example the system you are building has a date field on
  5043.         a screen and the field must be entered, it cannot be blank.
  5044.         That is all the validation that can be performed. The following
  5045.         REQ() function will accomplish this.
  5046.  
  5047.        @ dr1+05,dc1+11 get mdate valid ;
  5048.            req("A Date is Required",dr2-1,dc1+2,dc2-2)
  5049.  
  5050.  
  5051.  
  5052.  
  5053.  
  5054.  
  5055.  
  5056.  
  5057.  
  5058.  
  5059.  
  5060.  
  5061.  
  5062.  
  5063.  
  5064.  
  5065.  
  5066.  
  5067.  
  5068.  
  5069.  
  5070.  
  5071.  
  5072.  
  5073.  
  5074.                                   <83>
  5075.                   The Aeolus Procedure and Function Library
  5076.                             Reference Manual
  5077.  
  5078.  
  5079.  
  5080.         RGHT_JST()
  5081.  
  5082. Syntax:
  5083.         rght_jst([<expC>])
  5084.  
  5085. Returns:
  5086.         A logical true (.T.)
  5087.  
  5088. Pass:
  5089.         <expC> - Fill character after field is right justified.  Default
  5090.                  space.
  5091.  
  5092. Description:
  5093.         The RGHT_JST() VALID function will right justify and fill a
  5094.         character field with <expC> or spaces if <expC> is not passed.
  5095.  
  5096. Sample:
  5097.         Suppose you have a field to be keyed by a user and for whatever
  5098.         reason it makes sense to make it a character field.  You also
  5099.         want to right justify and zero fill the field because the field
  5100.         will be used as the key value to look up something in another
  5101.         database.  Use the RGHT_JST() function to accomplish this in the
  5102.         following manner:
  5103.  
  5104.  
  5105.         mkeyval=space(07)
  5106.         @ dr1+01,dc1+14 get mkeyval pict "9999999" valid ;
  5107.              rght_jst("0")
  5108.  
  5109.         If the user keys one (1) and then presses ENTER then MKEYVAL
  5110.         will equal "0000001".  If twenty-one (21) is entered then
  5111.         MKEYVAL will equal "0000021"
  5112.  
  5113.         The field will be right justified.
  5114.  
  5115.  
  5116.  
  5117.  
  5118.  
  5119.  
  5120.  
  5121.  
  5122.  
  5123.  
  5124.  
  5125.  
  5126.  
  5127.  
  5128.  
  5129.  
  5130.  
  5131.  
  5132.  
  5133.                                   <84>
  5134.                   The Aeolus Procedure and Function Library
  5135.                             Reference Manual
  5136.  
  5137.  
  5138.  
  5139.         RSIDE
  5140.  
  5141.         The RSIDE procedure is called by the TOTALKEYON and TOTALKEYOFF
  5142.         procedures only and should not be used otherwise.  Please see
  5143.         the TOTALKEYON and TOTALKEYOFF procedures for additional infor-
  5144.         mation.  This is only included for completeness.
  5145.  
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.  
  5153.  
  5154.  
  5155.  
  5156.  
  5157.  
  5158.  
  5159.  
  5160.  
  5161.  
  5162.  
  5163.  
  5164.  
  5165.  
  5166.  
  5167.  
  5168.  
  5169.  
  5170.  
  5171.  
  5172.  
  5173.  
  5174.  
  5175.  
  5176.  
  5177.  
  5178.  
  5179.  
  5180.  
  5181.  
  5182.  
  5183.  
  5184.  
  5185.  
  5186.  
  5187.  
  5188.  
  5189.  
  5190.  
  5191.  
  5192.                                   <85>
  5193.                   The Aeolus Procedure and Function Library
  5194.                             Reference Manual
  5195.  
  5196.  
  5197.  
  5198.         SAVE_IT()
  5199.  
  5200. Syntax:
  5201.         save_it(<expC1>,<expC2>,<expN>,<expC3>)
  5202.  
  5203. Pass:
  5204.         <expC1> "ADD", "CHG" or "DEL" only
  5205.         <expC2> memory variable prefix character(s)
  5206.         <expN>  fast delete index order number
  5207.         <expC3> database alias name
  5208.  
  5209. Returns:
  5210.         a logical expression.
  5211.  
  5212. Description:
  5213.         The SAVE_IT() function will add, change or delete the current
  5214.         record from the database <expC3>.  The SAVE_IT() function uses
  5215.         file locking if the memory variable NETWORK is set to true.  The
  5216.         <expC1> argument must be equal to "ADD", "CHG" or "DEL" to tell
  5217.         SAVE_IT() to add, change or delete a record.  <expC2> is the
  5218.         character or characters the field variables are prefixed with to
  5219.         create the memory variables (See the DBPUBL and DBSTOR proce-
  5220.         dures).  Use <expN> to pass the order number of the "fast
  5221.         delete" index order number created like:
  5222.  
  5223.         INDEX ON IF(DELE(),"*"," ") TO ...
  5224.  
  5225.         Send <expN> as zero (0) if you are not using a "fast delete". If
  5226.         the NETWORK memory variable is set to true and the SAVE_IT()
  5227.         function cannot lock the requested record and the user replies
  5228.         "No" to try the lock again, then the SAVE_IT() function will
  5229.         return false.
  5230.  
  5231. Sample:
  5232.         *************************************************************
  5233.         *** SAVE_IT() function example
  5234.         ***
  5235.  
  5236.         select 0
  5237.         use customer inde cust1,cust2
  5238.         do dbpubl with "Q"           && setup memvars
  5239.         do dbstor with "Q","EMPTY"   && set original values
  5240.  
  5241.         ** cust1 indexed on cust_nbr
  5242.         ** cust2 indexed on if(dele(),"*"," ")
  5243.  
  5244.         .
  5245.         . change memvars to values for new record
  5246.         .
  5247.  
  5248.  
  5249.         if !save_it("ADD","Q",2,"CUSTOMER")
  5250.  
  5251.                                   <86>
  5252.                   The Aeolus Procedure and Function Library
  5253.                             Reference Manual
  5254.  
  5255.  
  5256.  
  5257.           msgbox("ERROR--RECORD NOT ADDED !")
  5258.           return
  5259.         endi
  5260.  
  5261.  
  5262.  
  5263.  
  5264.  
  5265.  
  5266.  
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.  
  5275.  
  5276.  
  5277.  
  5278.  
  5279.  
  5280.  
  5281.  
  5282.  
  5283.  
  5284.  
  5285.  
  5286.  
  5287.  
  5288.  
  5289.  
  5290.  
  5291.  
  5292.  
  5293.  
  5294.  
  5295.  
  5296.  
  5297.  
  5298.  
  5299.  
  5300.  
  5301.  
  5302.  
  5303.  
  5304.  
  5305.  
  5306.  
  5307.  
  5308.  
  5309.  
  5310.                                   <87>
  5311.                   The Aeolus Procedure and Function Library
  5312.                             Reference Manual
  5313.  
  5314.  
  5315.  
  5316.         SETMSGLIN()
  5317.  
  5318. Syntax:
  5319.         setmsglin([<expC>])
  5320.  
  5321. Description:
  5322.         The SETMSGLIN() function returns the screen text on line 24. If
  5323.         <expC> is passed then <expC> is displayed on line 24 using the
  5324.         value of MSG_CLR as the color value.
  5325.  
  5326.  
  5327.  
  5328.  
  5329.  
  5330.  
  5331.  
  5332.  
  5333.  
  5334.  
  5335.  
  5336.  
  5337.  
  5338.  
  5339.  
  5340.  
  5341.  
  5342.  
  5343.  
  5344.  
  5345.  
  5346.  
  5347.  
  5348.  
  5349.  
  5350.  
  5351.  
  5352.  
  5353.  
  5354.  
  5355.  
  5356.  
  5357.  
  5358.  
  5359.  
  5360.  
  5361.  
  5362.  
  5363.  
  5364.  
  5365.  
  5366.  
  5367.  
  5368.  
  5369.                                   <88>
  5370.                   The Aeolus Procedure and Function Library
  5371.                             Reference Manual
  5372.  
  5373.  
  5374.  
  5375.         SHADOW()
  5376.  
  5377. Syntax:
  5378.         shadow(<expN1>,<expN2>,<expN3>,<expN4>)
  5379.  
  5380. Pass:
  5381.         <expN1> top left row
  5382.         <expN2> top left column
  5383.         <expN3> bottom right row
  5384.         <expN4> bottom right column
  5385.  
  5386. Description:
  5387.         Places a shadow on the area bounded by the four passed coordi-
  5388.         nates, where <expN1> and <expN2> are the upper left row and col-
  5389.         umn coordinates and <expN3> and <expN4> are the lower right.
  5390.  
  5391. Comment:
  5392.         the WINPUSH procedure uses this function to place a shadow on
  5393.         the window it creates.  You therefore should not have to use
  5394.         this function.
  5395.  
  5396.  
  5397.  
  5398.  
  5399.  
  5400.  
  5401.  
  5402.  
  5403.  
  5404.  
  5405.  
  5406.  
  5407.  
  5408.  
  5409.  
  5410.  
  5411.  
  5412.  
  5413.  
  5414.  
  5415.  
  5416.  
  5417.  
  5418.  
  5419.  
  5420.  
  5421.  
  5422.  
  5423.  
  5424.  
  5425.  
  5426.  
  5427.  
  5428.                                   <89>
  5429.                   The Aeolus Procedure and Function Library
  5430.                             Reference Manual
  5431.  
  5432.  
  5433.  
  5434.         SHOW_MEMO
  5435.  
  5436. Syntax:
  5437.         do show_memo with <expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ;
  5438.                           <expL1>[,<expC2>][,<expN5>][,<expL2>]
  5439.  
  5440. Pass:
  5441.         <expN1> - Top row screen coordinate.
  5442.         <expN2> - Left column screen coordinate.
  5443.         <expN3> - Bottom row screen coordinate.
  5444.         <expN4> - Right column screen coordinate.
  5445.         <expC1> - Memo field database field name.
  5446.         <expL1> - .F. view only, .T. allow editing.
  5447.         <expC2> - Color for memo data.
  5448.         <expN5> - Maximum lines memo may contain.  Default unlimited.
  5449.         <expL2> - .F. does nothing, .T. starts editing at the end of
  5450.                   the memo text.  Default .F.
  5451.  
  5452. Description:
  5453.         The SHOW_MEMO procedure calls the Clipper EDITMEMO() function
  5454.         and provides a few small additional functions.  It does not put
  5455.         a border or title on the screen.  This procedure is called by
  5456.         the EDT_MEMO() function.  If you want to use your own screen
  5457.         border and message line use this instead of EDT_MEMO().
  5458.  
  5459.         See EDT_MEMO(), MEMFUNC()
  5460.  
  5461.  
  5462.  
  5463.  
  5464.  
  5465.  
  5466.  
  5467.  
  5468.  
  5469.  
  5470.  
  5471.  
  5472.  
  5473.  
  5474.  
  5475.  
  5476.  
  5477.  
  5478.  
  5479.  
  5480.  
  5481.  
  5482.  
  5483.  
  5484.  
  5485.  
  5486.  
  5487.                                   <90>
  5488.                   The Aeolus Procedure and Function Library
  5489.                             Reference Manual
  5490.  
  5491.  
  5492.  
  5493.         SHOW_TXT()
  5494.  
  5495. Syntax:
  5496.         show_txt(<expC1>,<expN1>,<exp>,<expC2>,<expN2>,<expN3>, ;
  5497.                  <expN4>[,<expC3>])
  5498.  
  5499. Pass:
  5500.         <expC1> - Alias name of database for SEEK.
  5501.         <expN1> - Index order number of <expC1> for SEEK.
  5502.         <exp>   - Key expression for SEEK.
  5503.         <expC2> - Screen display expression.
  5504.         <expN2> - Screen row coordinate for display.
  5505.         <expN3> - Screen column coordinate for display.
  5506.         <expN4> - Rightmost screen column to display.
  5507.         <expC3> - Alternate color choice for display, default
  5508.                   is WMSG_CLR
  5509.  
  5510. Returns:
  5511.         A logical value.
  5512.  
  5513. Description:
  5514.         The SHOW_TXT() function is very useful VALID function that sim-
  5515.         ply puts text on the screen after a user moves past the field
  5516.         where the SHOW_TXT() VALID is located.
  5517.  
  5518. Sample:
  5519.         Suppose you have a database for customer purchases and one of
  5520.         the fields in this database is a Part Number. This represents
  5521.         the item your customer has purchased. When the Part Number is
  5522.         keyed you would like to display the Part Description that corre-
  5523.         sponds to the Part Number. The SHOW_TXT() VALID function can do
  5524.         this in the following manner:
  5525.  
  5526.         Technical assumptions:
  5527.  
  5528.         The customer database is called CUSTOMER and contains a five
  5529.         byte character field called PART_NBR which contains the Part
  5530.         Number the customer purchased.
  5531.  
  5532.         The look up table database with the part descriptions is called
  5533.         PARTS and index order one (1) is on the PART_NBR field.
  5534.  
  5535.         The PARTS database part description field is called PART_DESC.
  5536.  
  5537.         .
  5538.         .
  5539.         .
  5540.         ** add the ISEEK/MESSAGE to have the display of the
  5541.         ** Part Description on PgUp's and PgDn's
  5542.         **
  5543.         iseek(qpart_nbr,"PARTS",1,.f.)
  5544.         message(parts->part_desc,dr1+10,dc1+2,dc1+32,wmsg_clr)
  5545.  
  5546.                                   <91>
  5547.                   The Aeolus Procedure and Function Library
  5548.                             Reference Manual
  5549.  
  5550.  
  5551.  
  5552.         **
  5553.  
  5554.         @ dr1+09,dc1+16 get qpart_nbr pict "!!!!!" valid ;
  5555.               show_txt("PARTS",1,qpart_nbr,parts->part_desc, ;
  5556.                        dr1+10,dc1+2,dc1+32)
  5557.         .
  5558.         .
  5559.  
  5560.  
  5561.  
  5562.  
  5563.  
  5564.  
  5565.  
  5566.  
  5567.  
  5568.  
  5569.  
  5570.  
  5571.  
  5572.  
  5573.  
  5574.  
  5575.  
  5576.  
  5577.  
  5578.  
  5579.  
  5580.  
  5581.  
  5582.  
  5583.  
  5584.  
  5585.  
  5586.  
  5587.  
  5588.  
  5589.  
  5590.  
  5591.  
  5592.  
  5593.  
  5594.  
  5595.  
  5596.  
  5597.  
  5598.  
  5599.  
  5600.  
  5601.  
  5602.  
  5603.  
  5604.  
  5605.                                   <92>
  5606.                   The Aeolus Procedure and Function Library
  5607.                             Reference Manual
  5608.  
  5609.  
  5610.  
  5611.         TEXTVIEW
  5612.  
  5613. Syntax:
  5614.         do textview with <expN1>,<expN2>,<expN3>,<expN4>,<expC1> ;
  5615.                          [,<expL>][,<expC2>]
  5616.  
  5617. Pass:
  5618.         <expN1> - Top row screen coordinate.
  5619.         <expN2> - Left column screen coordinate.
  5620.         <expN3> - Bottom row screen coordinate.
  5621.         <expN4> - Right column screen coordinate.
  5622.         <expC1> - Name of a CR/LF delimited text file,
  5623.                   include the extension.
  5624.         <expL>  - Print key enable/disable.  Pass .T. to
  5625.                   enable or .F. to disable.  Default is
  5626.                   disabled.
  5627.         <expC2> - Name of a user defined function to program
  5628.                   alternate keystrokes and use TEXTVIEW
  5629.                   passed parameters.
  5630.  
  5631. Description:
  5632.         The TEXTVIEW function simply displays a CR/LF (carriage return
  5633.         /line feed) delimited text file within the passed screen coordi-
  5634.         nates, <expN1> through <expN4>.  The advantage of this function
  5635.         over the EDITMEMO() function provided by Clipper is that TEXT-
  5636.         VIEW can view any size file whereas EDITMEMO() is restricted to
  5637.         a maximum of 64K.  TEXTVIEW does not read the whole file into
  5638.         memory, only the portion of the file currently displayed is in
  5639.         memory, so TEXTVIEW uses very little of the programs available
  5640.         memory.
  5641.  
  5642.         Passing <expC2> the programmer can customize TEXTVIEW by examin-
  5643.         ing the parameters passed and writing custom routines for view-
  5644.         ing text files.
  5645.  
  5646.         The parameters passed to the UDF are:
  5647.  
  5648.          <expN1> - The leftmost column of the file currently
  5649.                    being displayed.
  5650.          <expC>  - The status of TEXTVIEW when the UDF was called:
  5651.                    "BF" - Beginning of File.
  5652.                    "EF" - End of File.
  5653.                    "BP" - Beginning to Print.
  5654.                    "EP" - End of Print.
  5655.          <expN2> - Length of the longest record in the current display
  5656.                    window.
  5657.          <expN3> - INKEY() value of the last key pressed.
  5658.          <expN4> - The file handle of the text file being viewed.
  5659.  
  5660.         The return value from the UDF MUST be a logical value, if your
  5661.         function returns true (.T.) then the screen will be refreshed.
  5662.         If your function returns false (.F.) then the screen will not be
  5663.  
  5664.                                   <93>
  5665.                   The Aeolus Procedure and Function Library
  5666.                             Reference Manual
  5667.  
  5668.  
  5669.  
  5670.         changed.
  5671.  
  5672. Sample:
  5673.         A TEXTVIEW call with a UDF to display a report file.
  5674.  
  5675.           .
  5676.           .
  5677.           .
  5678.           set colo to (wndw_clr)
  5679.           winpush(dr1,dc1,dr2,dc2)
  5680.           message("▓ "+chr(27)+chr(26)+"/TAB/Shft+TAB/"+chr(24)+chr(25)+ ;
  5681.                   "/PgUp/PgDn/Home/End-Scroll ▓ Alt+P-Print ▓ ESC-Exit ▓", ;
  5682.                   msg_ln,00,80,msg_clr)
  5683.  
  5684.           @ dr1,dc2-12 say chr(181)+"REPORT.TXT"+chr(198)
  5685.           set colo to (wmsg_clr)
  5686.           do textview with dr1+1,dc1+1,dr2-1,dc2-1,"REPORT.TXT",.t.,"TEXTFUNC"
  5687.           set colo to (wndw_clr)
  5688.           winpop()
  5689.  
  5690.         *********************************************************************
  5691.         ** Example function called by TEXTVIEW text file viewer with examples
  5692.         ** of how to use the passed parameters.
  5693.         *********************************************************************
  5694.         func textfunc
  5695.           para tcol,tstat,twdth,tkey,thndl
  5696.  
  5697.           *********************************************************************
  5698.           ** TCOL    - Leftmost column position in the current display window.
  5699.           ** TSTAT   - BF-Beginning of File; EF-End of File; BP-Begin of Print;
  5700.           **           EP-End of Print; or nul if no status to report.
  5701.           ** TWDTH   - Character width of the widest record in the current
  5702.           **           display window.
  5703.           ** TKEY    - INKEY() value of the last key pressed.  Use TKEY to
  5704.           **           program your own keystrokes during a TEXTVIEW.
  5705.           ** THNDL   - File handle of file being viewed.
  5706.           *********************************************************************
  5707.  
  5708.           ** check all status conditions and display result
  5709.           set colo to (wndw_clr)
  5710.           do case
  5711.           case tstat="BF"
  5712.             @ dr1,dc1+1 say chr(181)+"TOP"+chr(198)
  5713.           case tstat="EF"
  5714.             @ dr1,dc1+1 say chr(181)+"BOT"+chr(198)
  5715.           case tstat="BP"
  5716.             tfoc=setcolor()
  5717.             set colo to ("*"+tfoc)
  5718.             @ dr1,dc1+2 say "PRT"
  5719.             set colo to (tfoc)
  5720.           case tstat="EP"
  5721.             @ dr1,dc1+1 say chr(181)+"   "+chr(198)
  5722.  
  5723.                                   <94>
  5724.                   The Aeolus Procedure and Function Library
  5725.                             Reference Manual
  5726.  
  5727.  
  5728.  
  5729.           otherwise
  5730.             @ dr1,dc1+1 say chr(181)+"   "+chr(198)
  5731.           endc
  5732.  
  5733.           ** display left/right helper arrows if needed
  5734.           if tcol>1
  5735.             @ dr2,dc1 say chr(27)
  5736.           else
  5737.             @ dr2,dc1 say chr(200)
  5738.           endi
  5739.  
  5740.           if tcol+(dc2-dc1)-2<twdth
  5741.             @ dr2,dc2 say chr(26)
  5742.           else
  5743.             @ dr2,dc2 say chr(188)
  5744.           endi
  5745.  
  5746.           set colo to (wmsg_clr)
  5747.  
  5748.           ** Trap CTRL+HOME key and make it do the same thing as
  5749.           ** the HOME key.
  5750.           if tkey=29                 && INKEY() value of Ctrl+Home
  5751.             fseek(thndl,0,0)         && go to the beginning of the file
  5752.             tcol=0                   && set left column also
  5753.             retu(.f.)                && make TEXTVIEW redisplay window
  5754.           endi
  5755.  
  5756.           retu(.f.)    && no need to redisplay the window
  5757.  
  5758.  
  5759.  
  5760.  
  5761.  
  5762.  
  5763.  
  5764.  
  5765.  
  5766.  
  5767.  
  5768.  
  5769.  
  5770.  
  5771.  
  5772.  
  5773.  
  5774.  
  5775.  
  5776.  
  5777.  
  5778.  
  5779.  
  5780.  
  5781.  
  5782.                                   <95>
  5783.                   The Aeolus Procedure and Function Library
  5784.                             Reference Manual
  5785.  
  5786.  
  5787.  
  5788.         THERMOMETR()
  5789.  
  5790. Syntax:
  5791.         thermometr(<expN1>,<expN2>,<expN3>,<expN4>)
  5792.  
  5793. Pass:
  5794.         <expN1> thermometer length
  5795.         <expN2> start value of operation (i.e. 0%)
  5796.         <expN3> maximum value of operation (i.e. 100%)
  5797.         <expN4> current value, must be between <expN2> and <expN3>
  5798.  
  5799. Returns:
  5800.         a character expression.
  5801.  
  5802. Description:
  5803.         The THERMOMETR() function is used to display the progress of
  5804.         iterative program activity graphically.  The <expN1> argument is
  5805.         the length you want your thermometer, <expN2> is the number of
  5806.         the starting position of your process, <expN3> is the ending
  5807.         position and <expN4> is the current position.
  5808.  
  5809. Sample:
  5810.         ***************************************************************
  5811.         ** THERMOMETR() function example
  5812.         **
  5813.  
  5814.         select trnsctn
  5815.         go top
  5816.  
  5817.         strt=1
  5818.         end=reccount()
  5819.         width=40
  5820.         othm=" "            && old thermometer for comparison
  5821.  
  5822.         do whil !eof()
  5823.         thm=thermometr(width,strt,end,recno())
  5824.         if thm <> othm        && only display changes
  5825.           @ 1,0 say thm
  5826.           othm=thm
  5827.         endi
  5828.  
  5829.         .
  5830.         .
  5831.         .
  5832.  
  5833.         skip
  5834.         endd
  5835.  
  5836.  
  5837.  
  5838.  
  5839.  
  5840.  
  5841.                                   <96>
  5842.                   The Aeolus Procedure and Function Library
  5843.                             Reference Manual
  5844.  
  5845.  
  5846.  
  5847.         TIMEOUT
  5848.  
  5849. Syntax:
  5850.         call timeout with <expB1>,<expB2>,<expC>
  5851.  
  5852. Pass:
  5853.         <expB1> - Computer idle time in seconds.
  5854.         <expB2> - Keyboard scan code to put in keyboard buffer on
  5855.                   a timeout condition.
  5856.         <expC>  - one byte or longer character memory variable set
  5857.                   to any value other than "Y".
  5858.  
  5859. Returns:
  5860.         Nothing
  5861.  
  5862. Description:
  5863.         The TIMEOUT assembly subroutine tests the computer's keyboard,
  5864.         disk(s), serial port, video interface, and printer port(s) for
  5865.         activity.  If no activity has occurred and one (1) second has
  5866.         passed, an internal variable is incremented.  If any activity
  5867.         whatsoever occurs on the computer the internal variable is set
  5868.         to zero.  If the subroutine's internal variable counter reaches
  5869.         the value passed as <expB1> then <expB2> is put in the keyboard
  5870.         buffer as if the key was pressed on the keyboard and the Clipper
  5871.         memory variable passed as <expC> is set to "Y".
  5872.  
  5873.         So if the computer is completely idle (i.e. NO ACTIVITY AT ALL)
  5874.         for <expB1> seconds then <expC> is set to "Y" and <expB2> is put
  5875.         in the keyboard buffer.
  5876.  
  5877.         Note also that TIMEOUT will change the cursor between an under-
  5878.         line and a block when the insert key is pressed.
  5879.  
  5880.  
  5881.         WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*WARNING
  5882.  
  5883.         TIMEOUT CANNOT (!) BE USED IN AN OVERLAY.  IT TAKES OVER SYSTEM
  5884.         INTERRUPTS.  IF PUT IN AN OVERLAY, YOUR COMPUTER WILL (WILL !!)
  5885.         CRASH.
  5886.  
  5887.         WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*WARNING
  5888.  
  5889.         It is up the Clipper program to be set up to deal with these
  5890.         conditions.  See the following example and also see the program
  5891.         source for TTEST.PRG included in the BUILDER package.
  5892.  
  5893.         .
  5894.         .
  5895.         .
  5896.         set key 259 to tmout_xit             && Ctrl+2 INKEY() value
  5897.         idle_var="N"
  5898.         readinsert(.f.)
  5899.  
  5900.                                   <97>
  5901.                   The Aeolus Procedure and Function Library
  5902.                             Reference Manual
  5903.  
  5904.  
  5905.  
  5906.  
  5907.         ** Clipper program to time out after one hour (3600 seconds)
  5908.         **
  5909.         ** Hex 0300 is the keyboard scan code for Ctrl+2
  5910.         **
  5911.         call timeout with l2bin(3600),l2bin(hex2dec("0300")),idle_var
  5912.  
  5913.         .
  5914.         .
  5915.         .
  5916.         .
  5917.         ** Proc executed on every press of Ctrl+2
  5918.         ** if IDLE_VAR="Y" then the program timed out, so set errorlevel
  5919.         ** and exit.
  5920.         **
  5921.         proc tmout_xit
  5922.            para prc,lin,var
  5923.  
  5924.            if idle_var<>"Y"
  5925.              return
  5926.            endif
  5927.  
  5928.            set cursor on
  5929.            set colo to w/n
  5930.            errorlevel(1)
  5931.            clea
  5932.            quit
  5933.  
  5934.  
  5935.         Use the following table to find keyboard scan codes:
  5936.  
  5937.                 TIMEOUT Keyboard Scan Codes
  5938.  
  5939.         Key      Normal    Shifted   w/Ctrl    w/Alt
  5940.  
  5941.          A        1E61      1E41      1E01      1E00
  5942.          B        3062      3042      3002      3000
  5943.          C        2E63      2E42      2E03      2E00
  5944.          D        2064      2044      2004      2000
  5945.          E        1265      1245      1205      1200
  5946.          F        2166      2146      2106      2100
  5947.          G        2267      2247      2207      2200
  5948.          H        2368      2348      2308      2300
  5949.          I        1769      1749      1709      1700
  5950.          J        246A      244A      240A      2400
  5951.          K        256B      254B      250B      2500
  5952.          L        266C      264C      260C      2600
  5953.          M        326D      324D      320D      3200
  5954.          N        316E      314E      310E      3100
  5955.          O        186F      184F      180F      1800
  5956.          P        1970      1950      1910      1900
  5957.          Q        1071      1051      1011      1000
  5958.  
  5959.                                   <98>
  5960.                   The Aeolus Procedure and Function Library
  5961.                             Reference Manual
  5962.  
  5963.  
  5964.  
  5965.                TIMEOUT Keyboard Scan Codes
  5966.  
  5967.         Key      Normal    Shifted   w/Ctrl    w/Alt
  5968.  
  5969.          R        1372      1352      1312      1300
  5970.          S        1F73      1F53      1F13      1F00
  5971.          T        1474      1454      1414      1400
  5972.          U        1675      1655      1615      1600
  5973.          V        2F76      2F56      2F16      2F00
  5974.          W        1177      1157      1117      1100
  5975.          X        2D78      2D58      2D18      2D00
  5976.          Y        1579      1559      1519      1500
  5977.          Z        2C7A      2C5A      2C1A      2C00
  5978.  
  5979.          1        0231      0221                7800
  5980.          2        0332      0340      0300      7900
  5981.          3        0433      0423                7A00
  5982.          4        0534      0524                7B00
  5983.          5        0635      0625                7C00
  5984.          6        0736      075E      071E      7D00
  5985.          7        0837      0826                7E00
  5986.          8        0938      092A                7F00
  5987.          9        0A39      0A28                8000
  5988.          0        0B30      0B29                8100
  5989.  
  5990.          -        0C2D      0C5F      0C1F      8200
  5991.          =        0D3D      0D2B                8300
  5992.          [        1A5B      1A7B      1A1B      1A00
  5993.          ]        1B5D      1B7D      1B1D      1B00
  5994.                   273B      273A                2700
  5995.          '        2827      2822
  5996.          `        2960      297E
  5997.          \        2B5C      2B7C      2B1C      2600 (same as Alt L)
  5998.          ,        332C      333C
  5999.          .        342E      343E
  6000.          /        352F      353F
  6001.  
  6002.         F1        3B00      5400      5E00      6800
  6003.         F2        3C00      5500      5F00      6900
  6004.         F3        3D00      5600      6000      6A00
  6005.         F4        3E00      5700      6100      6B00
  6006.         F5        3F00      5800      6200      6C00
  6007.         F6        4000      5900      6300      6D00
  6008.         F7        4100      5A00      6400      6E00
  6009.         F8        4200      5B00      6500      6F00
  6010.         F9        4300      5C00      6600      7000
  6011.         F10       4400      5D00      6700      7100
  6012.         F11       8500      8700      8900      8B00
  6013.         F12       8600      8800      8A00      8C00
  6014.  
  6015.  
  6016.  
  6017.  
  6018.                                   <99>
  6019.                   The Aeolus Procedure and Function Library
  6020.                             Reference Manual
  6021.  
  6022.  
  6023.  
  6024.                 TIMEOUT Keyboard Scan Codes
  6025.  
  6026.         Key      Normal    Shifted   w/Ctrl    w/Alt
  6027.  
  6028.         BackSpace    0E08      0E08      0E7F     0E00
  6029.         Del          5300      532E      9300     A300
  6030.         Down Arrow   5000      5032      9100     A000
  6031.         End          4F00      4F31      7500     9F00
  6032.         Enter        1C0D      1C0D      1C0A     A600
  6033.         Esc          011B      011B      011B     0100
  6034.         Home         4700      4737      7700     9700
  6035.         Ins          5200      5230      9200     A200
  6036.         Keypad 5               4C35      8F00
  6037.         Keypad *     372A                9600     3700
  6038.         Keypad -     4A2D      4A2D      8E00     4A00
  6039.         Keypad +     4E2B      4E2B               4E00
  6040.  
  6041.  
  6042.         Keypad /     352F      352F      9500     A400
  6043.         Left Arrow   4B00      4B34      7300     9B00
  6044.         PgDn         5100      5133      7600     A100
  6045.         PgUp         4900      4939      8400     9900
  6046.         PrtSc                            7200
  6047.         Right Arrow  4D00      4D36      7400     9D00
  6048.         SpaceBar     3920      3920      3920     3920
  6049.         Tab          0F09      0F00      9400     A500
  6050.         Up Arrow     4800      4838      8D00     9800
  6051.  
  6052.  
  6053.         - Some key combinations are not available on all systems.  The PS/2
  6054.           includes many that aren't available on the PC, XT and AT.
  6055.  
  6056.  
  6057.  
  6058.  
  6059.  
  6060.  
  6061.  
  6062.  
  6063.  
  6064.  
  6065.  
  6066.  
  6067.  
  6068.  
  6069.  
  6070.  
  6071.  
  6072.  
  6073.  
  6074.  
  6075.  
  6076.  
  6077.                                  <100>
  6078.                   The Aeolus Procedure and Function Library
  6079.                             Reference Manual
  6080.  
  6081.  
  6082.  
  6083.         TOTALKEYON/TOTALKEYOFF
  6084.  
  6085. Syntax:
  6086.         do totalkeyon
  6087.         do totalkeyoff
  6088.  
  6089. Description:
  6090.         Sets up the left and right arrow keys to jump from one drop down
  6091.         menu to the menu under the right or left.
  6092.  
  6093. Comment:
  6094.         The BUILDER program creates the source with TOTALKEYON and
  6095.         TOTALKEYOFF already called at the proper places and you should
  6096.         not need to use this procedure.
  6097.  
  6098.  
  6099.  
  6100.  
  6101.  
  6102.  
  6103.  
  6104.  
  6105.  
  6106.  
  6107.  
  6108.  
  6109.  
  6110.  
  6111.  
  6112.  
  6113.  
  6114.  
  6115.  
  6116.  
  6117.  
  6118.  
  6119.  
  6120.  
  6121.  
  6122.  
  6123.  
  6124.  
  6125.  
  6126.  
  6127.  
  6128.  
  6129.  
  6130.  
  6131.  
  6132.  
  6133.  
  6134.  
  6135.  
  6136.                                  <101>
  6137.                   The Aeolus Procedure and Function Library
  6138.                             Reference Manual
  6139.  
  6140.  
  6141.  
  6142.         WAITKEY()
  6143.  
  6144. Syntax:
  6145.         waitkey([<expN>])
  6146.  
  6147. Pass:
  6148.         <expN> timeout seconds
  6149.  
  6150. Returns:
  6151.         a numeric expression.
  6152.  
  6153. Description:
  6154.         Use WAITKEY() as a substitute for the Clipper INKEY(<expN>)
  6155.         function.  The only difference between the two is that WAITKEY()
  6156.         will react to any SET KEY TO ... 's you have set.  Not passing
  6157.         the parameter or passing zero (the default) will cause WAITKEY()
  6158.         to wait until a key is pressed with no timeout.
  6159.  
  6160.  
  6161.  
  6162.  
  6163.  
  6164.  
  6165.  
  6166.  
  6167.  
  6168.  
  6169.  
  6170.  
  6171.  
  6172.  
  6173.  
  6174.  
  6175.  
  6176.  
  6177.  
  6178.  
  6179.  
  6180.  
  6181.  
  6182.  
  6183.  
  6184.  
  6185.  
  6186.  
  6187.  
  6188.  
  6189.  
  6190.  
  6191.  
  6192.  
  6193.  
  6194.  
  6195.                                  <102>
  6196.                   The Aeolus Procedure and Function Library
  6197.                             Reference Manual
  6198.  
  6199.  
  6200.  
  6201.         WINPOP()
  6202.  
  6203. Syntax:
  6204.         winpop()
  6205.  
  6206. Pass:
  6207.         Nothing
  6208.  
  6209. Returns:
  6210.         A logical value, true if there was something removed from the
  6211.         screen.
  6212.  
  6213. Description:
  6214.         The WINPOP() function removes the last window on the screen that
  6215.         was created by the WINPUSH function.
  6216.  
  6217.         See WINPUSH() for examples.
  6218.  
  6219.  
  6220.  
  6221.  
  6222.  
  6223.  
  6224.  
  6225.  
  6226.  
  6227.  
  6228.  
  6229.  
  6230.  
  6231.  
  6232.  
  6233.  
  6234.  
  6235.  
  6236.  
  6237.  
  6238.  
  6239.  
  6240.  
  6241.  
  6242.  
  6243.  
  6244.  
  6245.  
  6246.  
  6247.  
  6248.  
  6249.  
  6250.  
  6251.  
  6252.  
  6253.  
  6254.                                  <103>
  6255.                   The Aeolus Procedure and Function Library
  6256.                             Reference Manual
  6257.  
  6258.  
  6259.  
  6260.         WINPUSH()
  6261.  
  6262. Syntax:
  6263.         winpush(<expN1>,<expN2>,<expN3>,<expN4>[,<expL1>] ;
  6264.         [,<expL2>][,<expL3>][,<expL4>])
  6265.  
  6266. Pass:
  6267.         <expN1> top left row
  6268.         <expN2> top left column
  6269.         <expN3> bottom right row
  6270.         <expN4> bottom right column
  6271.         <expL1> save the screen area before displaying, default true
  6272.         <expL2> clear the interior of the box, default true
  6273.         <expL3> display the box with a border, default true
  6274.         <expL4> display the box with a shadow, default true
  6275.  
  6276. Returns:
  6277.         A logical value, if the window was successfully displayed, true
  6278.         is returned.
  6279.  
  6280. Description:
  6281.         The WINPUSH function saves the portion of the screen bounded the
  6282.         coordinates <expN1> through <expN4> with <expN1> and <expN2>
  6283.         being the upper left row and column positions and <expN3> and
  6284.         <expN4> the lower right corner positions and draws a box on the
  6285.         screen in the default color.
  6286.  
  6287.         All four of the logical expressions that can optionally be
  6288.         passed have a default value of true.
  6289.  
  6290.         If <expL1> is true the screen area bounded by the passed screen
  6291.         coordinates is saved to the screen array otherwise if set to
  6292.         false it cannot be WINPOPed.
  6293.  
  6294.         <expL2> if set to true will clear the box interior otherwise
  6295.         only the border, if any, is displayed.  The default it true.
  6296.  
  6297.         <expL3> if set to true will display a double border on the box.
  6298.  
  6299.         <expL4> controls the shadow on the box, if set to true a shadow
  6300.         is displayed.
  6301.  
  6302.         Note:  If the variable XPLODE is a logical variable set to true
  6303.         the WINPUSH function will explode the window onto the screen.
  6304.  
  6305. Sample:
  6306.         **************************************************************
  6307.         *** WINPUSH/WINPOP sample code
  6308.         ***
  6309.  
  6310.         ** put a window on the screen
  6311.         **     saving the area so it can be WINPOPed,
  6312.  
  6313.                                  <104>
  6314.                   The Aeolus Procedure and Function Library
  6315.                             Reference Manual
  6316.  
  6317.  
  6318.  
  6319.         **     clearing the inside of the window when displayed,
  6320.         **     put double border characters on the window,
  6321.         **     and put a shadow on the window.
  6322.  
  6323.         winpush(05,10,17,60)
  6324.         @ 07,12 say "My Window to the World."
  6325.         inkey(0)
  6326.  
  6327.         ** remove window, and shadow.
  6328.               winpop()
  6329.  
  6330.  
  6331.  
  6332.  
  6333.  
  6334.  
  6335.  
  6336.  
  6337.  
  6338.  
  6339.  
  6340.  
  6341.  
  6342.  
  6343.  
  6344.  
  6345.  
  6346.  
  6347.  
  6348.  
  6349.  
  6350.  
  6351.  
  6352.  
  6353.  
  6354.  
  6355.  
  6356.  
  6357.  
  6358.  
  6359.  
  6360.  
  6361.  
  6362.  
  6363.  
  6364.  
  6365.  
  6366.  
  6367.  
  6368.  
  6369.  
  6370.  
  6371.  
  6372.                                  <105>
  6373.