home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / database / pc2lib.zip / PROCLIP2.DOC next >
Text File  |  1988-02-29  |  170KB  |  5,281 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                                          
  8.                                          
  9.                                          
  10.                                          
  11.                                          
  12.                                    PROCLIP2.LIB
  13.                                          
  14.                        - The Professional Clipper Library -
  15.                                          
  16.                                    Version 2.00
  17.                                          
  18.                                         By
  19.                                 Jason R. Matthews
  20.                                          
  21.                                          
  22.                                 February 15, 1988
  23.                                          
  24.                                          
  25.                         **********************************
  26.                         *   Programming extensions for   *
  27.                         *  NANTUCKET CLIPPER SUMMER '87  *
  28.                         **********************************
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.                               - Table of Contents -
  74.                                          
  75.                                          
  76.      ========================================================================
  77.      
  78.      
  79.      COPYRIGHTS     Acknowledgments.........................................v
  80.      
  81.      DISCLAIMER     "As is".................................................v
  82.      
  83.      OVERVIEW       General overview.......................................vi
  84.      
  85.      REGISTRATION   How to become a "registered user."....................vii
  86.      
  87.      USAGE          General syntax of functions..........................viii
  88.      
  89.      CAUTIONS       Indicates possible conflicts.........................viii
  90.      
  91.      LINKING        With Microsoft, Plink86 or Turbo Link...................x
  92.      
  93.      ERROR
  94.      HANDLING       Internal critical error handling functions.............xi
  95.      
  96.      SYNTAX
  97.      CONVENTIONS    PROCLIP2 Documentation syntax conventions............xiii
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                                         - i -
  129.                                           
  130.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  131.                                           
  132.  
  133.                                           
  134.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  135.      ======================================================================
  136.  
  137.  
  138.  
  139.                               - Table of Contents -
  140.                                          
  141.                                          
  142.      BORDER         Using the color as set in the SET COLOR TO...,
  143.                     activates the screen border on CGA and VGA
  144.                     monitors................................................1
  145.      
  146.      BOXCOLOR       Change the color attribute of the border of a
  147.                     "window" on the screen without having to
  148.                     rewrite the BOX.........................................3
  149.      
  150.      CLOCK          Display a dynamic clock anywhere on the screen
  151.                     using selectable colors and format......................6
  152.      
  153.      CURSOR         Set cursor to full, half, standard or any user
  154.                     selectable size or completely disable cursor
  155.                     from the current video screen...........................9
  156.      
  157.      ERASTEXT       Erase all text characters from within a
  158.                     specific area of the screen.  Great for erasing
  159.                     lines containing graphics characters you wish
  160.                     to retain..............................................12
  161.      
  162.      FILEATTR       Set or reset a file's directory attributes.............14
  163.      
  164.      GETCOLOR       Obtain the current foreground and background
  165.                     color attribute from the position requested............17
  166.      
  167.      ISCGA          Indicates if the attached monitor is driven by
  168.                     a standard Color Graphics Adapter (CGA)................19
  169.      
  170.      ISEGA          Indicates if the attached monitor is driven by
  171.                     a standard Enhanced Graphics Adapter (EGA).............20
  172.      
  173.      ISMONO         Indicates if the attached monitor is driven by
  174.                     a standard Monochrome Adapter (MDA)....................21
  175.      
  176.      ISVGA          Indicates if the attached monitor is driven by
  177.                     a standard Video Graphics Array Adapter (VGA)..........22
  178.      
  179.      NEWCOLOR       Change the color attribute of a "window" on the
  180.                     screen without having to rewrite the data..............23
  181.      
  182.      PRTSC          Provides print screen and print screen
  183.                     translation facilities.................................26
  184.      
  185.      RESET          Provides an instant hardware or software reset
  186.                     of the computer........................................29
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                        - ii -
  195.                                           
  196.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  197.                                           
  198.  
  199.                                           
  200.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  201.      ======================================================================
  202.  
  203.  
  204.  
  205.                               - Table of Contents -
  206.                                          
  207.                                          
  208.      RESTBOX        Restore a "window" area of the screen to the
  209.                     original, or different, screen location using
  210.                     original, or different screen colors...................31
  211.      
  212.      RESTCURS       Restore the cursor to the shape and position
  213.                     when it was saved into a numeric memory
  214.                     variable with SAVECURS.................................34
  215.      
  216.      SAVEBOX        Save a "window" area of the screen into a
  217.                     character memory variable..............................35
  218.      
  219.      SAVECURS       Save the current cursor shape and position.............37
  220.      
  221.      SCROLL         See VSCROLL
  222.      
  223.      SDIR           Read the directory entry by entry obtaining the
  224.                     filename, file update date & time and current
  225.                     file size using attributes specified...................39
  226.      
  227.      SOUND          Allows generation of a wide range on sounds for
  228.                     variable durations.  Similar to Clipper's
  229.                     TONE() command but with more flexibility on the
  230.                     duration...............................................44
  231.      
  232.      SPRINT         Prints a given string onto the screen using
  233.                     selectable color attributes without issuing a
  234.                     SET COLOR TO command.  Optionally resets the
  235.                     cursor position or not.................................47
  236.      
  237.      STAMP          Provides date and time stamping capabilities to
  238.                     any file...............................................50
  239.      
  240.      UNRESET        Intercepts CTRL ALT DEL to either prevent or
  241.                     warn the user of the attempt...........................52
  242.      
  243.      VIDEO          Turn on or off the video screen........................54
  244.      
  245.      VSCROLL        Provides vertical and horizontal scrolling with
  246.                     full control over the color attribute used
  247.                     during the scroll......................................56
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                                        - iii -
  261.                                           
  262.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  263.                                           
  264.  
  265.                                           
  266.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  267.      ======================================================================
  268.  
  269.  
  270.  
  271.                               - Table of Contents -
  272.                                          
  273.                                          
  274.      WILDAT         Search a target string for the first occurrence
  275.                     of another string or wildcard pattern
  276.                     optionally ignoring case, in a left to right
  277.                     search. ...............................................59
  278.      
  279.      WILDRAT        Search a target string for the first occurrence
  280.                     of another string or wildcard pattern
  281.                     optionally ignoring case, in a right to left
  282.                     search.................................................63
  283.      
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                                        - iv -
  327.                                           
  328.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  329.                                           
  330.  
  331.                                           
  332.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  333.      ======================================================================
  334.  
  335.  
  336.  
  337.      ------------------------------------------------------------------------
  338.                           - Copyright Acknowledgments -
  339.      ------------------------------------------------------------------------
  340.      
  341.      
  342.                     CLIPPER is a Trademark of Nantucket, Corp.
  343.               IBM is a Trademark of International Business Machines.
  344.               Tom Rettig Library is a Trademark of Tom Rettig Assoc.
  345.             Microsoft Overlay Linker is a Trademark of Microsoft Corp.
  346.         PLINK86 & PLINK86plus are Trademarks of Phoenix Technologies, Ltd.
  347.                Turbo Link is a Trademark of Borland International.
  348.                     Intel is a Trademark of Intel Corporation.
  349.      
  350.      All references in this documentation to trademarks, copyrights,
  351.      registered names or the like are intended only as a reference and do not
  352.      contain any inference.
  353.      
  354.               ******************************************************
  355.               * The author is not associated with Nantucket, Corp. *
  356.               ******************************************************
  357.      
  358.      ------------------------------------------------------------------------
  359.                              - Software Disclaimer -
  360.      ------------------------------------------------------------------------
  361.      
  362.      
  363.      Although a great deal of time and effort have been spent designing,
  364.      coding and debugging these functions, it cannot be certain that they are
  365.      totally error free.  It should be clearly understood that PROCLIP2 is
  366.      released "as is".  The author makes no warranties, express or implied,
  367.      with respect to this software, including without limitation, warranties
  368.      of merchantability and fitness for a particular purpose.  In no event
  369.      shall the author be liable for any direct, indirect or consequential
  370.      damages, real or imagined.
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.                                         - v -
  393.                                           
  394.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  395.                                           
  396.  
  397.                                           
  398.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  399.      ======================================================================
  400.  
  401.  
  402.  
  403.      ------------------------------------------------------------------------
  404.                                    - Overview -
  405.      ------------------------------------------------------------------------
  406.      
  407.      
  408.      The Professional Clipper Library (PROCLIP2), Version 2.00, is designed
  409.      for the CLIPPER programming language (Summer '87 release) from
  410.      Nantucket, Corp.  It is for the programmer who desires more than the
  411.      current language specifications can support.  PROCLIP2 is not designed
  412.      to replace the standard Nantucket Clipper Library, but to provide
  413.      enhanced capabilities in those areas Nantucket chose not to.  Some of
  414.      the functions provided by PROCLIP2 will undoubtedly be made available in
  415.      future releases of Clipper, but the need to utilize them in application
  416.      development is today and PROCLIP2 was designed to meet some of those
  417.      needs.  As with any language, Clipper contains features and functions
  418.      which are unique to it and therefore make it more attractive.  By the
  419.      same token, it lacks features which may appear to be "standard" in other
  420.      languages and thus makes it somewhat frustrating to use from time to
  421.      time.  While PROCLIP2 does not, and indeed cannot, solve all of these
  422.      frustrations it will help where it can.
  423.      
  424.      
  425.      Care has been taken to utilize only published and supported accesses
  426.      into Clipper in an effort to ensure upward compatibility with future
  427.      releases of Clipper.  Some of the routines contained within PROCLIP2 are
  428.      similar in name to those provided by Nantucket or another creator of
  429.      add-on libraries, Tom Rettig Assoc.  Each function has been created with
  430.      the concept of enhancing existing functions and procedures regardless of
  431.      their origin.  All functions contained within PROCLIP2 have been coded
  432.      in Intel 8088/8086 assembly language for compactness of code, execution
  433.      efficiency and compatibility through all Intel microprocessors.
  434.      
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.                                        - vi -
  459.                                           
  460.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  461.                                           
  462.  
  463.                                           
  464.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  465.      ======================================================================
  466.  
  467.  
  468.  
  469.      ------------------------------------------------------------------------
  470.                                  - Registration -
  471.      ------------------------------------------------------------------------
  472.      
  473.      
  474.      A good deal of effort, time and money have been spent designing,
  475.      creating and supporting PROCLIP2.  If these functions are of use, and
  476.      you would like to support the creation of more, a donation to help
  477.      defray these costs is greatly appreciated.  For a donation of US $25.00
  478.      you may become a "registered user" of PROCLIP2 and will receive
  479.      notification of upgrades prior to release to the general public as well
  480.      as notification of any programmer errors discovered.  Input to define
  481.      and develop useful functions to be added into PROCLIP2 are always
  482.      solicited.
  483.      
  484.      
  485.      Send all requests, registrations and suggestions to:
  486.      
  487.                                   Jason Matthews
  488.                                   P.O. Box 1296
  489.                               Rowlett, Texas  75088
  490.                                          
  491.                                   Source: NAN779
  492.                               CompuServe: 71410,2051
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.                                        - vii -
  525.                                           
  526.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  527.                                           
  528.  
  529.                                           
  530.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  531.      ======================================================================
  532.  
  533.  
  534.  
  535.      ------------------------------------------------------------------------
  536.                                  - Usage Format -
  537.      ------------------------------------------------------------------------
  538.      
  539.      
  540.      As Nantucket was kind enough to provide the facility to create User
  541.      Defined Functions (UDF), all of the PROCLIP2 functions utilize this
  542.      format.  Programmed into most of the functions is a sub-function which
  543.      validates parameter count, type and contents prior to attempting
  544.      function execution.  Hopefully this will resolve runtime errors.  If a
  545.      PROCLIP2 function is called and nothing seems to happen it quite
  546.      probably was ignored due to a parameter difficulty.  Almost all of
  547.      PROCLIP2s functions use the published Clipper vector names contained in
  548.      the EXTENDA.MAC released with Clipper.  Hopefully this will prevent
  549.      PROCLIP2 from becoming obsolete when Nantucket releases future versions
  550.      of their language.
  551.      
  552.      
  553.      ------------------------------------------------------------------------
  554.                       - Cautions, Warnings & Compatibility -
  555.      ------------------------------------------------------------------------
  556.      
  557.                           - Environment Compatibility -
  558.      
  559.      Some of the functions contained in PROCLIP2 assume they are operating in
  560.      an IBM (or 100% compatible) system utilizing DOS 2.xx or greater, OS/2
  561.      in "real" mode or Microsoft Windows.  What this means is that they will
  562.      access the ROM BIOS or perform DMA (direct memory access) from time to
  563.      time to perform specific functions or obtain information regarding the
  564.      current system environment.  As long as you are using an IBM (or 100%
  565.      compatible) with the proper version of DOS you should experience no
  566.      difficulties.
  567.      
  568.                             - Monitor Compatibility -
  569.      
  570.      PROCLIP2 is intelligent enough to determine the current monitor type and
  571.      treat it accordingly.  This includes Monochrome, Color Graphics (CGA),
  572.      Enhanced Graphics (EGA) and Video Graphics (VGA) monitors in either
  573.      native or emulated modes.  Those functions which offer DMA video buffer
  574.      updating should be tested on the system prior to releasing it for use.
  575.      These functions are again assuming they are operating in an IBM-type
  576.      environment and so they "know" where the video buffer currently resides.
  577.      DMA updating is useful when operating in personal computers which have a
  578.      clock speed slower than 8MHz.  If one of the screen functions appears to
  579.      be operating sluggishly try attempting the DMA update request specified
  580.      in the function.
  581.      
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.                                       - viii -
  591.                                           
  592.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  593.                                           
  594.  
  595.                                           
  596.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  597.      ======================================================================
  598.  
  599.  
  600.  
  601.      ------------------------------------------------------------------------
  602.                  - Cautions, Warnings & Compatibility (cont'd) -
  603.      ------------------------------------------------------------------------
  604.      
  605.                              - Memory Compatibility -
  606.      
  607.      Some functions within PROCLIP2 require a temporary allocation of memory
  608.      from the system.  If this allocation is not possible the function will
  609.      refuse to function.  The typical allocation request is less than 1Kb
  610.      (1024 bytes) so no real conflict should exist.  Once memory has been
  611.      allocated and used by PROCLIP2 it will be returned to the system memory
  612.      pool for use by other programs or DOS.  PROCLIP2 will not attempt to
  613.      allocate any memory outside of the standard 640Kb limit.
  614.      
  615.      
  616.                       - System / BIOS dependent functions -
  617.      
  618.      Some functions are dependent upon system level functions or internal
  619.      BIOS interrupt vectors.  These functions, when active, have the ability
  620.      to "hang" the computer if a serious error occurs in the system.
  621.      PROCLIP2 will intercept DOS level critical errors before DOS is made
  622.      aware of them and make every effort to restore any interrupt vectors or
  623.      system functions to their previous state before passing the error to DOS
  624.      for handling.  This feature of PROCLIP2 is unique to PROCLIP2 as it
  625.      requires no additional coding or intervention on your part.  When a
  626.      function is activated which depends on interrupt or system vectors (eg.
  627.      CLOCK) it will automatically create the "hook" into the DOS critical
  628.      error handler.  Should a critical error occur all PROCLIP2 functions
  629.      which are using interrupt or system vectors will be deactivated by
  630.      PROCLIP2.
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.                                        - ix -
  657.                                           
  658.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  659.                                           
  660.  
  661.                                           
  662.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  663.      ======================================================================
  664.  
  665.  
  666.  
  667.      ------------------------------------------------------------------------
  668.                                - Linking PROCLIP2 -
  669.      ------------------------------------------------------------------------
  670.      
  671.      
  672.      Use of this library is identical to that of any other library designed
  673.      for use with CLIPPER or other programming languages.  Refer to the
  674.      Clipper programming manual or any manual containing a description of how
  675.      to operate the linker you are currently using.
  676.      
  677.      Listed below are sample syntax for three of the most popular linkers.
  678.      
  679.      With MicroSoft Overlay Linker -
  680.      
  681.      C>LINK
  682.      Microsoft (R) Overlay Linker  Version 3.61
  683.      Copyright (C) Microsoft Corp 1983-1987.  All rights reserved.
  684.      
  685.      Object Modules [.OBJ]: YOURPROG
  686.      Run File [YOURPROG.EXE]:
  687.      List File [NUL.MAP]:
  688.      Libraries [.LIB]: CLIPPER + PROCLIP2
  689.      
  690.      
  691.      With Plink86 -
  692.      
  693.      C>PLINK86
  694.      PLINK86plus ( Nantucket ) Version 2.24
  695.      Copyright (C) 1987 by Phoenix Technologies Ltd.,
  696.      All Rights Reserved.
  697.      
  698.      =>FI YOURPROG
  699.      =>LIB CLIPPER
  700.      =>LIB PROCLIP2
  701.      =>;
  702.      
  703.      
  704.      With Turbo Link -
  705.      
  706.      C>TLINK YOURFILE,YOURFILE,NUL,CLIPPER + PROCLIP2
  707.      Turbo Link  Version 1.0  Copyright (c) 1987 Borland International
  708.      
  709.                                  * * * NOTE * * *
  710.      If you are using PROCLIP2 with any other library which contains the same
  711.      function names (eg. CLOCK) you will see some warning errors generated by
  712.      whichever linker you are using.  If you like the PROCLIP2 function
  713.      better than the others just make certain that PROCLIP2 is the first
  714.      library in the list after the CLIPPER library is specified.  Otherwise
  715.      make certain their library is first in the list.
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.                                         - x -
  723.                                           
  724.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  725.                                           
  726.  
  727.                                           
  728.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  729.      ======================================================================
  730.  
  731.  
  732.  
  733.      ------------------------------------------------------------------------
  734.                                 - Error Handling -
  735.      ------------------------------------------------------------------------
  736.      
  737.      
  738.      PROCLIP2 currently contains three functions which intercept low level
  739.      (BIOS) interrupt vectors to perform their functions.  They are:
  740.      
  741.                *    CLOCK
  742.      
  743.                Intercepts INT 08H, which is the timer interrupt.  This
  744.                interrupt was chosen over the more typical INT 1CH in order to
  745.                make it more usable under some TSR's which never relinquish
  746.                INT 1CH.  The CLOCK routine calculates the time at every timer
  747.                tick (18.2 times per second).
  748.      
  749.                *    PRTSC
  750.      
  751.                Intercepts INT 05H, which is the print screen interrupt.
  752.                PRTSC uses this interrupt vector to replace the standard BIOS
  753.                print screen with the translation facilities of PROCLIP2.
  754.      
  755.                *    UNRESET
  756.      
  757.                Intercepts INT 09H, which is the basic keyboard interrupt.
  758.                UNRESET requires access at this level in order to prevent the
  759.                CTRL ALT DEL sequence from resetting the computer.
  760.      
  761.      
  762.      With these three routines, and more to be included in subsequent
  763.      releases of PROCLIP2, it became evident that some type of error handling
  764.      was necessary.  Clipper Summer '87 now contains an extensive runtime
  765.      error handling function to intercept most errors and allow your
  766.      application to determine the best course of action.  While each of the
  767.      PROCLIP2 functions contains an "off" command, a given application could
  768.      not be expected to intercept every possible error condition.  In light
  769.      of this, PROCLIP2 now contains it's own built-in critical error handling
  770.      system.  The error handling system in PROCLIP2 is designed specifically
  771.      for these interrupt driven routines, nothing more.  When a critical
  772.      error is declared by the operating system (as in drive failure), the
  773.      PROCLIP2 critical error routine will automatically "unhook" all
  774.      interrupt driven routines.  The interrupt vectors in BIOS and DOS will
  775.      be restored to their original state and the PROCLIP2 interrupt driven
  776.      functions will cease their operation immediately.  This feature is
  777.      unique to PROCLIP2 in that no additional programming is necessary.
  778.      There is no need for you to remember which functions are currently
  779.      active, PROCLIP2 maintains it's own internal table and uses it to
  780.      process the error handling.  As an additional feature, you can invoke
  781.      the PROCLIP2 error recovery system by yourself.  Application error
  782.      trapping is great, but sometimes it can determine the best course of
  783.      action is a rapid termination of the program.
  784.  
  785.  
  786.  
  787.  
  788.                                        - xi -
  789.                                           
  790.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  791.                                           
  792.  
  793.                                           
  794.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  795.      ======================================================================
  796.  
  797.  
  798.  
  799.      ERROR HANDLING (cont'd)
  800.      
  801.                                      BAILOUT
  802.                                      -------
  803.      
  804.      
  805.      The BAILOUT function should only be used when a runtime error has
  806.      occurred which the application program determines is unrecoverable.
  807.      Invoking the BAILOUT function effectively terminates all PROCLIP2
  808.      interrupt driven functions.
  809.      
  810.      
  811.      Format:
  812.      
  813.                bailout()
  814.      
  815.      
  816.      Parameters:
  817.      
  818.                None.
  819.      
  820.      
  821.      Example:
  822.      
  823.                1.   The ERRORSYS.PRG has determined that a runtime error is
  824.                     unrecoverable.  Before quitting the program any interrupt
  825.                     driven PROCLIP2 functions need to be disabled.
  826.      
  827.                     .
  828.                     .
  829.                     .
  830.                     bailout()
  831.                     .
  832.                     .
  833.                     quit
  834.      
  835.      
  836.      Returns:
  837.      
  838.                Nothing.
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.                                        - xii -
  855.                                           
  856.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  857.                                           
  858.  
  859.                                           
  860.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  861.      ======================================================================
  862.  
  863.  
  864.  
  865.      ------------------------------------------------------------------------
  866.                               - Syntax Conventions -
  867.      ------------------------------------------------------------------------
  868.      
  869.      The follow are the syntax conventions used throughout the PROCLIP2
  870.      documentation.
  871.      
  872.      [...]     Indicates an optional parameter.  Any parameter surrounded by
  873.                square brackets should be considered optional.  All optional
  874.                parameters have a default.
  875.      
  876.      '...'     Indicates a parameter string.  A parameter string is a word or
  877.                phrase used to inform the function of a certain request, as in
  878.                'on' or 'off'.  All examples use lower case but case is not
  879.                sensitive in any of the PROCLIP2 functions which use a
  880.                parameter string.
  881.      
  882.      |         Indicates an exclusive or.  In other words, multiple
  883.                parameters separated by the | character are mutually exclusive
  884.                and cannot be used in the same function call, as in 'on' |
  885.                'off'.
  886.      
  887.      Example:
  888.      
  889.      As this function employs all syntax possibilities, it is the best to
  890.      discuss in an example.
  891.      
  892.                cursor(['std' | 'off' | 'half' | 'full'] | [start,end])
  893.      
  894.      [...]     The parameters surrounded by square brackets are optional in
  895.                that they are not necessary for the function to operate in
  896.                default mode.  When two or more parameters are enclosed within
  897.                the same bracket pair they are dependent upon each other in
  898.                one way or another.
  899.      
  900.      'std'     This, and the other parameters specified in this fashion, are
  901.                string parameters informing the function of the action to
  902.                take.  This mechanism makes reading the resulting source code
  903.                easier as no "cryptic" codes need to be interpreted.
  904.      
  905.      |         All parameters separated by the "|" character are mutually
  906.                exclusive in that they cannot be used in the same function
  907.                call.  Notice how all of the "pre-programmed" cursor sizes in
  908.                the example are grouped in the square brackets, but are also
  909.                mutually exclusive.  Further, the "pre-programmed" sizes are
  910.                exclusive from the programmable size specified in the
  911.                [start,end] group.
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.                                       - xiii -
  921.                                           
  922.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  923.                                           
  924.  
  925.                                           
  926.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  927.      ======================================================================
  928.  
  929.  
  930.  
  931.      
  932.                                       BORDER
  933.                                       ------
  934.      
  935.      
  936.           Although syntactically supported in the SET COLOR TO... command,
  937.           Clipper does not actually set the border color to the specified
  938.           color.  BORDER provides this functionality to standard color (CGA)
  939.           and the new VGA monitors.  EGA standards do not allow for border
  940.           color support but some EGA's will support them.
  941.      
  942.           This function can either accept a standard Clipper color string or
  943.           an individual color string to set the border color.
  944.      
  945.      
  946.      Format:
  947.      
  948.                border(aColor)
  949.      
  950.      
  951.      Parameters:
  952.      
  953.                aColor....Character string variable or constant, non case
  954.                          sensitive, which contains the color to use when
  955.                          setting the border.  Must be the alpha
  956.                          representation of the color, the numeric will be
  957.                          rejected.  If the string is a standard Clipper color
  958.                          command (eg. 'W/N,N/W,R,,N/W') the function will
  959.                          locate the border color within the string position
  960.                          as specified in the Clipper documentation.
  961.                          Otherwise the function assumed the color for the
  962.                          border is the string (eg. 'r').
  963.      
  964.                                   (valid colors)
  965.                          black                         N
  966.                          blue                          B
  967.                          green                         G
  968.                          cyan                          BG
  969.                          red                           R
  970.                          magenta                       RB
  971.                          brown                         GR
  972.                          white                         W
  973.      
  974.      
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.                                        Page #1
  987.                                           
  988.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  989.                                           
  990.  
  991.                                           
  992.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  993.      ======================================================================
  994.  
  995.  
  996.  
  997.      BORDER (cont'd)
  998.      
  999.      Examples:
  1000.      
  1001.                1.   Set the colors, including the border, to a nice shade of
  1002.                     blue.
  1003.      
  1004.                     .
  1005.                     .
  1006.                     .
  1007.                     aColor = '+gr/b,b/gr,b,,n/w'
  1008.                     set color to &aColor
  1009.                     border(aColor)
  1010.                     .
  1011.                     .
  1012.                     .
  1013.      
  1014.      2.          Set the border to red without affecting anything else.
  1015.      
  1016.                     .
  1017.                     .
  1018.                     .
  1019.                     border('r')
  1020.                     .
  1021.                     .
  1022.                     .
  1023.      
  1024.      
  1025.      Returns:
  1026.      
  1027.                Nothing.
  1028.      
  1029.      
  1030.      Cautions:
  1031.      
  1032.                None.
  1033.      
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.                                        Page #2
  1053.                                           
  1054.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1055.                                           
  1056.  
  1057.                                           
  1058.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1059.      ======================================================================
  1060.  
  1061.  
  1062.  
  1063.      
  1064.                                      BOXCOLOR
  1065.                                      --------
  1066.      
  1067.      
  1068.           Changing the color attributes within a given area can be
  1069.           accomplished with NEWCOLOR, but BOXCOLOR will only change the color
  1070.           attribute of the border of the area.  With an optional parameter
  1071.           you can instruct the function to change the color of the first
  1072.           column and last column inside the area thereby showing a more
  1073.           appealing BOX.  Changing the background color with BOXCOLOR you can
  1074.           create your own "boxes" or even exploding and imploding emulation.
  1075.      
  1076.      
  1077.      Format:
  1078.      
  1079.                boxcolor(top,left,bottom,right,attr[,double][,type])
  1080.      
  1081.      
  1082.      Parameters:
  1083.      
  1084.                top.......Numeric variable or constant indicating the top row
  1085.                          of the area to be changed.  Value checked to be
  1086.                          between 0 and 24 inclusive.
  1087.                
  1088.                left......Numeric variable or constant indicating the left
  1089.                          column of the area to be changed.  Value checked to
  1090.                          be between 0 and 79 inclusive.
  1091.                
  1092.                bottom....Numeric variable or constant indicating the ending
  1093.                          row of the area to be changed.  Value checked to be
  1094.                          greater than TOP but less than or equal to 24.
  1095.                
  1096.                right.....Numeric variable or constant indicating the right
  1097.                          column of the area to be changed.  Value checked to
  1098.                          be greater than LEFT but less than or equal to 79.
  1099.                
  1100.                attr......Character string variable or constant, non case
  1101.                          sensitive, which contains a valid color command or
  1102.                          combination for character and background.  Must be
  1103.                          the alpha representation of the color, the numeric
  1104.                          will be rejected.
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.                                        Page #3
  1119.                                           
  1120.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1121.                                           
  1122.  
  1123.                                           
  1124.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1125.      ======================================================================
  1126.  
  1127.  
  1128.  
  1129.      BOXCOLOR (cont'd)
  1130.      
  1131.                                   (valid colors)
  1132.                          black                         N
  1133.                          blue                          B
  1134.                          green                         G
  1135.                          cyan                          BG
  1136.                          red                           R
  1137.                          magenta                       RB
  1138.                          brown                         GR
  1139.                          white                         W
  1140.                          intense                       +
  1141.                          blink                         *
  1142.      
  1143.                double....OPTIONAL.  Character string variable or constant,
  1144.                          non case sensitive, which instructs the function to
  1145.                          change the attribute of the first and last columns
  1146.                          within the area specified.  As columns are "slimmer"
  1147.                          than rows, changing these columns as well causes a
  1148.                          more appealing border.
  1149.      
  1150.                          'd'            This is the only valid parameter.
  1151.                                         Any other letter will be rejected as
  1152.                                         a bad parameter.
  1153.      
  1154.                type......OPTIONAL.  Logical variable or constant instructing
  1155.                          the function to use DMA updating or not.
  1156.      
  1157.                          .T.            DEFAULT.  If not specified, the
  1158.                                         function will use DMA screen
  1159.                                         updating.
  1160.                
  1161.                          .F.            Setting this flag to a logical false
  1162.                                         will cause the function to use the
  1163.                                         standard BIOS INT 10H for screen
  1164.                                         updating.
  1165.      
  1166.      
  1167.      Examples:
  1168.      
  1169.                1.   Change the color of the border of an area.
  1170.      
  1171.                     .
  1172.                     .
  1173.                     .
  1174.                     boxcolor(05,05,10,10,'n/w')
  1175.                     .
  1176.                     .
  1177.                     .
  1178.      
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.                                        Page #4
  1185.                                           
  1186.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1187.                                           
  1188.  
  1189.                                           
  1190.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1191.      ======================================================================
  1192.  
  1193.  
  1194.  
  1195.      BOXCOLOR (cont'd)
  1196.      
  1197.                1.   Change the color of the border of the same area, but use
  1198.                     double wide columns.
  1199.      
  1200.                     .
  1201.                     .
  1202.                     .
  1203.                     boxcolor(05,05,10,10,'n/w','d')
  1204.                     .
  1205.                     .
  1206.                     .
  1207.      
  1208.      
  1209.      Returns:
  1210.      
  1211.                Nothing.
  1212.      
  1213.      
  1214.      Cautions:
  1215.      
  1216.                None.
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.                                        Page #5
  1251.                                           
  1252.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1253.                                           
  1254.  
  1255.                                           
  1256.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1257.      ======================================================================
  1258.  
  1259.  
  1260.  
  1261.      
  1262.                                       CLOCK
  1263.                                       ------
  1264.      
  1265.      
  1266.           Many programmers have wanted to display the current time on the
  1267.           screen from with Clipper, but due to the overhead involved in
  1268.           trying to keep it correct have dismissed the idea.  Now, with
  1269.           CLOCK, you simply specify the location, format and color attributes
  1270.           and PROCLIP2 will maintain the dynamic clock for you.  Formats
  1271.           include military (24 hour) or meridian (12 hour), with or without
  1272.           seconds displayed.  If no seconds are selected the colon between
  1273.           the hour and minutes will pulse every second re-enforcing the fact
  1274.           that it is keeping time.
  1275.      
  1276.      
  1277.      Format:
  1278.      
  1279.                clock('on' | 'off' [,format] [,seconds][,attr] )
  1280.      
  1281.      
  1282.      Parameters:
  1283.      
  1284.                'on'......Character string variable or constant, non case
  1285.                          sensitive, which instructs the CLOCK to become
  1286.                          active at the current cursor position.  Mutually
  1287.                          exclusive with the "off" parameter.
  1288.      
  1289.                'off'.....Character string variable or constant, non case
  1290.                          sensitive, which instructs the CLOCK to deactivate
  1291.                          itself.  The constant updating of the clock will
  1292.                          cease but the clock will remain on the display.
  1293.                          Mutually exclusive with the "on" parameter.
  1294.      
  1295.                attr......OPTIONAL.  Character string variable or constant,
  1296.                          non case sensitive, which informs the function what
  1297.                          color attributes to use when displaying.  If not
  1298.                          specified the function will use the attribute
  1299.                          currently displayed on the screen at the position
  1300.                          indicated.
  1301.      
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.                                        Page #6
  1317.                                           
  1318.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1319.                                           
  1320.  
  1321.                                           
  1322.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1323.      ======================================================================
  1324.  
  1325.  
  1326.  
  1327.      CLOCK (cont'd)
  1328.      
  1329.                                   (valid colors)
  1330.                          black                         N
  1331.                          blue                          B
  1332.                          green                         G
  1333.                          cyan                          BG
  1334.                          red                           R
  1335.                          magenta                       RB
  1336.                          brown                         GR
  1337.                          white                         W
  1338.                          intense                       +
  1339.                          blink                         *
  1340.      
  1341.                format....OPTIONAL.  Character string variable or constant,
  1342.                          non case sensitive, which informs the function of
  1343.                          the display format to use.
  1344.      
  1345.                          '12 hour'      DEFAULT.  Instructs the CLOCK
  1346.                                         function to display in standard 12
  1347.                                         hour format (eg. 10:00pm)
  1348.                          
  1349.                          '24 hour'      instructs the CLOCK function to
  1350.                                         display in military format (eg.
  1351.                                         22:00)
  1352.      
  1353.                seconds...OPTIONAL.  Character string variable or constant,
  1354.                          non case sensitive, which informs the function
  1355.                          whether to display the current seconds or not.
  1356.                
  1357.                          'seconds'      instructs the CLOCK function to
  1358.                                         display the seconds in the current
  1359.                                         format.
  1360.                          
  1361.                          'no seconds'   DEFAULT.  Instructs the CLOCK
  1362.                                         function to suppress display of the
  1363.                                         seconds and activate the pulse of the
  1364.                                         colon separator in hh:mm
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.                                        Page #7
  1383.                                           
  1384.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1385.                                           
  1386.  
  1387.                                           
  1388.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1389.      ======================================================================
  1390.  
  1391.  
  1392.  
  1393.      CLOCK (cont'd)
  1394.      
  1395.      Examples:
  1396.      
  1397.                1.   At row #00 and column #00 display the clock in military
  1398.                     format with the seconds displayed using a white
  1399.                     background with black characters.
  1400.      
  1401.                     .
  1402.                     .
  1403.                     .
  1404.                     @ 0,0 say clock('on','24 hour','seconds','n/w')
  1405.                     .
  1406.                     .
  1407.                     .
  1408.      
  1409.                2.   Disable the clock.
  1410.      
  1411.                     .
  1412.                     .
  1413.                     .
  1414.                     clock('off')
  1415.                     .
  1416.                     .
  1417.                     .
  1418.      
  1419.      
  1420.      Returns:
  1421.      
  1422.                Nothing.
  1423.      
  1424.      
  1425.      Cautions:
  1426.      
  1427.                This function should not be placed into an overlay as it is
  1428.                interrupt driven.  Any error routines which determine an
  1429.                unrecoverable runtime error has occurred should disable this
  1430.                function prior to exiting the program.  Failure to follow this
  1431.                caution may result in the computer locking up.
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.                                        Page #8
  1449.                                           
  1450.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1451.                                           
  1452.  
  1453.                                           
  1454.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1455.      ======================================================================
  1456.  
  1457.  
  1458.  
  1459.      
  1460.                                       CURSOR
  1461.                                       ------
  1462.      
  1463.      
  1464.           While Clipper contains a CURSOR command, it can't match the
  1465.           flexibility of this one.  CURSOR provides the programmer with full
  1466.           cursor shape control as well as information regarding the current
  1467.           cursor state.
  1468.      
  1469.           To use the "pre-programmed" mode, simply tell CURSOR what type of
  1470.           cursor you want.  Choices are 'off', 'std', 'half' and 'full' size.
  1471.           CURSOR will automatically adjust to different monitors so there is
  1472.           no need to remember starting and ending scan lines.
  1473.      
  1474.           For those programmers wishing even more control, CURSOR will accept
  1475.           starting and ending scan lines to adjust the cursor shape
  1476.           accordingly.  This is an excellent way to get that "special" cursor
  1477.           for your application.
  1478.      
  1479.           The last function contained in CURSOR is revealed when no
  1480.           parameters are used.  No parameters informs CURSOR that you want
  1481.           the current cursor state, on or off.  If the cursor is currently
  1482.           shown on the screen, regardless of shape, a logical true (.T.) will
  1483.           be returned, otherwise a logical false (.F.) will be.
  1484.      
  1485.      
  1486.      Format:
  1487.      
  1488.                cursor(['std' | 'off' | 'half' | 'full'] | [start,end])
  1489.      
  1490.      
  1491.      Parameters:
  1492.      
  1493.                'std'.....Character string variable or constant, non case
  1494.                          sensitive, instructing the function to set the
  1495.                          cursor to the default for the current monitor type.
  1496.      
  1497.                'off'.....Character string variable or constant, non case
  1498.                          sensitive, instructing the function to set the
  1499.                          cursor off.  The cursor will not show on the current
  1500.                          monitor.
  1501.      
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.                                        Page #9
  1515.                                           
  1516.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1517.                                           
  1518.  
  1519.                                           
  1520.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1521.      ======================================================================
  1522.  
  1523.  
  1524.  
  1525.      CURSOR (cont'd)
  1526.      
  1527.                'half'....Character string variable or constant, non case
  1528.                          sensitive, instructing the function to set the
  1529.                          cursor to one half of the total character size for
  1530.                          the current monitor type.
  1531.      
  1532.                'full'....Character string variable or constant, non case
  1533.                          sensitive, instructing the function to set the
  1534.                          cursor to cover the total character position for the
  1535.                          current monitor type.
  1536.      
  1537.                start.....Numeric variable or constant which will be used by
  1538.                          the function as the starting scan line.  Validity
  1539.                          determination is left up to the application program
  1540.                          in order to provide full flexibility.  Specifying
  1541.                          START assumes an END will be specified and is
  1542.                          mutually exclusive from the pre-programmed parameter
  1543.                          types.
  1544.      
  1545.                end.......Numeric variable or constant which will be used by
  1546.                          the function as the ending scan line.  Validity
  1547.                          determination is left up to the application program
  1548.                          in order to provide full flexibility.  Specifying
  1549.                          END assumes a START was specified and is mutually
  1550.                          exclusive from the pre-programmed parameter types.
  1551.      
  1552.                ()........If no parameters are given to the function, it will
  1553.                          return indicating whether the cursor is currently
  1554.                          displayed or not.
  1555.      
  1556.      
  1557.      Examples:
  1558.      
  1559.                1.   Set the cursor to one half of the current size and then
  1560.                     turn it off for some other activity.
  1561.      
  1562.                     .
  1563.                     .
  1564.                     .
  1565.                     cursor('half')
  1566.                     .
  1567.                     .
  1568.                     .
  1569.                     cursor('off')
  1570.                     .
  1571.                     .
  1572.                     .
  1573.      
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.                                       Page #10
  1581.                                           
  1582.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1583.                                           
  1584.  
  1585.                                           
  1586.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1587.      ======================================================================
  1588.  
  1589.  
  1590.  
  1591.      CURSOR (cont'd)
  1592.      
  1593.                2.   Change the cursor to a special shape.
  1594.      
  1595.                     .
  1596.                     .
  1597.                     .
  1598.                     cursor(2,7)
  1599.                     .
  1600.                     .
  1601.                     .
  1602.      
  1603.                3.   Determine if the cursor is currently displayed and turn
  1604.                     it off if it is.
  1605.      
  1606.                     .
  1607.                     .
  1608.                     .
  1609.                     if cursor()
  1610.                          cursor('off')
  1611.                     endif
  1612.                     .
  1613.                     .
  1614.                     .
  1615.      
  1616.      
  1617.      Returns:
  1618.      
  1619.                .T.  .....If no parameters were specified a return of a
  1620.                          logical true indicates that the cursor is currently
  1621.                          shown on the display.
  1622.                
  1623.                .F.  .....If no parameters were specified a return of a
  1624.                          logical false indicates that the cursor is not
  1625.                          currently shown on the display.
  1626.      
  1627.      
  1628.      Cautions:
  1629.      
  1630.                None.
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.                                       Page #11
  1647.                                           
  1648.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1649.                                           
  1650.  
  1651.                                           
  1652.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1653.      ======================================================================
  1654.  
  1655.  
  1656.  
  1657.      
  1658.                                      ERASTEXT
  1659.                                      --------
  1660.      
  1661.      
  1662.           If you've ever constructed a screen using the Clipper BOX command
  1663.           you know that it can be difficult to remember where the box border
  1664.           stops and your text begins, especially if you only want to erase a
  1665.           few lines of the text.  Generating FOR...NEXT loops to erase only
  1666.           that portion of an enclosed area is no fun.  Enter ERASTEXT, which
  1667.           will erase all standard ASCII characters (text & numbers) from
  1668.           within the requested area.  Simply specify the coordinates and
  1669.           "zap" all the text is gone.  Does not affect the attribute in use
  1670.           at the time.
  1671.      
  1672.      
  1673.      Format:
  1674.      
  1675.                erastext(top,left,bottom,right [,type])
  1676.      
  1677.      
  1678.      Parameters:
  1679.      
  1680.                top.......Numeric variable or constant indicating the top row
  1681.                          of the area to be changed.  Value checked to be
  1682.                          between 0 and 24 inclusive.
  1683.                
  1684.                left......Numeric variable or constant indicating the left
  1685.                          column of the area to be changed.  Value checked to
  1686.                          be between 0 and 79 inclusive.
  1687.                
  1688.                bottom....Numeric variable or constant indicating the ending
  1689.                          row of the area to be changed.  Value checked to be
  1690.                          greater than TOP but less than or equal to 24.
  1691.                
  1692.                right.....Numeric variable or constant indicating the right
  1693.                          column of the area to be changed.  Value checked to
  1694.                          be greater than LEFT but less than or equal to 79.
  1695.      
  1696.                type......OPTIONAL.  Logical variable or constant instructing
  1697.                          the function to use DMA updating or not.
  1698.      
  1699.                          .T.            DEFAULT.  If not specified, the
  1700.                                         function will use DMA screen
  1701.                                         updating.
  1702.                
  1703.                          .F.            Setting this flag to a logical false
  1704.                                         will cause the function to use the
  1705.                                         standard BIOS INT 10H for screen
  1706.                                         updating.
  1707.      
  1708.  
  1709.  
  1710.  
  1711.  
  1712.                                       Page #12
  1713.                                           
  1714.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1715.                                           
  1716.  
  1717.                                           
  1718.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1719.      ======================================================================
  1720.  
  1721.  
  1722.  
  1723.      ERASTEXT (cont'd)
  1724.      
  1725.      Examples:
  1726.      
  1727.                1.   Erase a video line without affecting the BOX borders
  1728.                     around the line.
  1729.      
  1730.                     .
  1731.                     .
  1732.                     .
  1733.                     @ 08,20,16,60 box '(special characters)'
  1734.                     @ 09,21 say (something useful)
  1735.                     @ 10,21 say (something useful)
  1736.                     @ 11,21 say (something useful)
  1737.                     @ 12,21 say (something useful)
  1738.                     @ 13,21 say (something useful)
  1739.                     .
  1740.                     .
  1741.                     .
  1742.                     erastext(11,20,13,60)
  1743.                     .
  1744.                     .
  1745.                     .
  1746.      
  1747.      
  1748.      Returns:
  1749.      
  1750.                Nothing.
  1751.      
  1752.      
  1753.      Cautions:
  1754.      
  1755.                None.
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.                                       Page #13
  1779.                                           
  1780.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1781.                                           
  1782.  
  1783.                                           
  1784.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1785.      ======================================================================
  1786.  
  1787.  
  1788.  
  1789.      
  1790.                                      FILEATTR
  1791.                                      --------
  1792.      
  1793.      
  1794.           If you have clients who like to tinker too much, this function can
  1795.           be invaluable.  Employing this function properly it is now
  1796.           extremely easy to "lock" a file where the average user cannot
  1797.           inadvertently damage it.
  1798.           
  1799.           The FILEATTR function allows setting or resetting the directory
  1800.           attributes of a given file.  Attributes available are read-only,
  1801.           archive, hidden and system.  Prudent use of the read-only and/or
  1802.           hidden attribute can protect your databases from prying eyes.  To
  1803.           reaccess the database simply have your application remove the
  1804.           necessary flags prior to use, it's that easy.
  1805.      
  1806.      
  1807.      Format:
  1808.      
  1809.                fileattr(filename,fileattr)
  1810.      
  1811.      
  1812.      Parameters:
  1813.      
  1814.                filename..Character string variable or constant, non case
  1815.                          sensitive, which contains the filename whose
  1816.                          attributes you wish to change.  The filename should
  1817.                          follow the standard [drive:][\path\]filename format
  1818.                          where drive and path are optional.  Wildcards (* &
  1819.                          ?) are not allowed in the filename.
  1820.      
  1821.                fileattr..Character string variable or constant, non case
  1822.                          sensitive, which provides the function with a list
  1823.                          of all attributes to set or reset.
  1824.                
  1825.                          + (plus sign)  An attribute proceeded by a plus sign
  1826.                                         (+) instructs the function to set
  1827.                                         this flag in the directory entry for
  1828.                                         this file.
  1829.                
  1830.                          - (minus sign) An attribute proceeded by a minus
  1831.                                         sign (-) instructs the function to
  1832.                                         clear this flag in the directory
  1833.                                         entry for this file.
  1834.                
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.                                       Page #14
  1845.                                           
  1846.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1847.                                           
  1848.  
  1849.                                           
  1850.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1851.      ======================================================================
  1852.  
  1853.  
  1854.  
  1855.      FILEATTR (cont'd)
  1856.      
  1857.                          NOTE:          Although not advisable, it is
  1858.                                         possible to place an activate (+) and
  1859.                                         deactivate (-) for the same flag in
  1860.                                         the attribute string (eg. '+r/o -arc
  1861.                                         -r/o').  The last flag encountered in
  1862.                                         a left to right scan will be the
  1863.                                         action taken.  In this example the
  1864.                                         file would have the read-only and
  1865.                                         archive cleared (not set), the '+r/o'
  1866.                                         would have no effect.
  1867.      
  1868.                                   (valid file attributes)
  1869.      
  1870.                               r/o                 Read only
  1871.                               hid                 Hidden
  1872.                               sys                 System
  1873.                               arc                 Archive
  1874.      
  1875.      
  1876.      Examples:
  1877.      
  1878.                1.   Suppose you have "dangerous" clients who are constantly
  1879.                     fiddling with your files and inadvertently deleting them
  1880.                     from time to time.  In order to prevent this your
  1881.                     application could set the "read-only" attribute prior to
  1882.                     terminating.  To access the files again the application
  1883.                     could reset the "read-only" attribute when starting up.
  1884.      
  1885.                     (program start)
  1886.                     .
  1887.                     .
  1888.                     fileattr('CLIENT.DBF','-r/o')
  1889.                     .
  1890.                     (program executes)
  1891.                     .
  1892.                     fileattr('CLIENT.DBF','+r/o')
  1893.                     .
  1894.                     .
  1895.                     (program ends)
  1896.      
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.                                       Page #15
  1911.                                           
  1912.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1913.                                           
  1914.  
  1915.                                           
  1916.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1917.      ======================================================================
  1918.  
  1919.  
  1920.  
  1921.      FILEATTR (cont'd)
  1922.      
  1923.                1.   Combined with the DIR function, do the above example
  1924.                     through all existing files in the subdirectory.
  1925.      
  1926.                     (program starts)
  1927.                     .
  1928.                     .
  1929.                     filename = DIR('*.*','first')
  1930.                     do while .not. empty(filename)
  1931.                          fileattr(filename,'-r/o')
  1932.                          filename = DIR('next')
  1933.                     enddo
  1934.                     .
  1935.                     (program executes)
  1936.                     .
  1937.                     filename = DIR('*.*','first')
  1938.                     do while .not. empty(filename)
  1939.                          fileattr(filename,'+r/o')
  1940.                          filename = DIR('next')
  1941.                     enddo
  1942.                     .
  1943.                     (program ends)
  1944.      
  1945.      
  1946.      Returns:
  1947.      
  1948.                .T.  .....Logical true (.T.) to indicate success of function.
  1949.                          Setting or resetting attributes which have already
  1950.                          been set or reset will still return a success flag.
  1951.      
  1952.                .F.  .....Logical false (.F.) to indicate failure of the
  1953.                          function.
  1954.      
  1955.      
  1956.      Cautions:
  1957.      
  1958.                In order to assume proper operation, all files should be
  1959.                closed which may be accessed by the function.
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.                                       Page #16
  1977.                                           
  1978.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  1979.                                           
  1980.  
  1981.                                           
  1982.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  1983.      ======================================================================
  1984.  
  1985.  
  1986.  
  1987.      
  1988.                                      GETCOLOR
  1989.                                      --------
  1990.      
  1991.      
  1992.           GETCOLOR goes to the screen location specified in the parameters
  1993.           and obtains the current color attribute.  This attribute is then
  1994.           returned to your program in the form of a standard Clipper
  1995.           character string compatible with the SET COLOR TO format (eg.
  1996.           '+gr/b').  The function may optionally "flip" the color attribute
  1997.           in that the returned string will be the exact inverse of what is
  1998.           actually there (eg. '+b/gr').
  1999.      
  2000.      
  2001.      Format:
  2002.      
  2003.                <memvar> = getcolor(row, col [,flip])
  2004.      
  2005.      
  2006.      Parameters:
  2007.      
  2008.                row.......Numeric variable or constant which, when combined
  2009.                          with COL, informs the function of the screen
  2010.                          location from which to obtain the current color.
  2011.      
  2012.                col.......Numeric variable or constant which, when combined
  2013.                          with ROW, informs the function of the screen
  2014.                          location from which to obtain the current color.
  2015.      
  2016.                flip......OPTIONAL.  Logical variable or constant which
  2017.                          instructs the function as to whether to invert the
  2018.                          color attribute before returning it
  2019.                
  2020.                          .T.            Force the attribute to invert (flip)
  2021.                                         itself.  For example, a color of
  2022.                                         '+w/b' would be flipped to be '+b/w'.
  2023.                
  2024.                          .F.            DEFAULT.  Do not flip the color
  2025.                                         attribute, return it as it actually
  2026.                                         is.
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.                                       Page #17
  2043.                                           
  2044.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2045.                                           
  2046.  
  2047.                                           
  2048.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2049.      ======================================================================
  2050.  
  2051.  
  2052.  
  2053.      GETCOLOR (cont'd)
  2054.      
  2055.      Examples:
  2056.      
  2057.                1.   After your application program loads you wish to obtain
  2058.                     the current screen color so it may be restored before
  2059.                     your application completes.  (The color of the screen
  2060.                     BEFORE your program invoked it's colors was bright yellow
  2061.                     text on a blue background)
  2062.      
  2063.                     doscolor = getcolor(0,0)
  2064.                     * now doscolor = '+gr/b'
  2065.                     .
  2066.                     .
  2067.                     set color to &mycolors
  2068.                     clear
  2069.                     .
  2070.                     .
  2071.                     (application program)
  2072.                     .
  2073.                     .
  2074.                     set color to &doscolor
  2075.                     quit
  2076.      
  2077.      
  2078.      Returns:
  2079.      
  2080.                memvar....A character string variable which will contain a
  2081.                          text description of the current color at the
  2082.                          position selected.  If nothing is returned an error
  2083.                          was detected in your screen coordinates.  The valid
  2084.                          range is (0,0) thru (24,79).
  2085.      
  2086.      
  2087.                           (Possible Return Color Values)
  2088.                          black                         n
  2089.                          blue                          b
  2090.                          green                         g
  2091.                          cyan                          bg
  2092.                          red                           r
  2093.                          magenta                       rb
  2094.                          brown                         gr
  2095.                          white                         w
  2096.                          intense                       +
  2097.                          blink                         *
  2098.      
  2099.      
  2100.      Cautions:
  2101.      
  2102.                None.
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.                                       Page #18
  2109.                                           
  2110.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2111.                                           
  2112.  
  2113.                                           
  2114.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2115.      ======================================================================
  2116.  
  2117.  
  2118.  
  2119.      
  2120.                                       ISCGA
  2121.                                       -----
  2122.      
  2123.      
  2124.           Determines if the current screen is driven by a Color Graphics
  2125.           Adapter (CGA).  Adapters which are supersets of the CGA standard
  2126.           should be tested for EGA or VGA compatibility first.  An EGA or VGA
  2127.           emulating a CGA will not return indicating a CGA is attached.
  2128.           Returns a logical true (.T.) or false (.F.) indicator.
  2129.      
  2130.      
  2131.      Format:
  2132.      
  2133.                iscga()
  2134.      
  2135.      
  2136.      Parameters:
  2137.      
  2138.                None.
  2139.      
  2140.      
  2141.      Examples:
  2142.      
  2143.                1.   Determine if the current monitor is standard CGA.
  2144.      
  2145.                     .
  2146.                     .
  2147.                     .
  2148.                     if iscga()
  2149.                          (do color stuff)
  2150.                     endif
  2151.                     .
  2152.                     .
  2153.                     .
  2154.      
  2155.      
  2156.      Returns:
  2157.      
  2158.                .T.  .....Indicates that the current screen is a CGA type.
  2159.                
  2160.                .F.  .....Indicates that the current screen is not a CGA type.
  2161.      
  2162.      
  2163.      Cautions:
  2164.      
  2165.                None.
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.                                       Page #19
  2175.                                           
  2176.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2177.                                           
  2178.  
  2179.                                           
  2180.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2181.      ======================================================================
  2182.  
  2183.  
  2184.  
  2185.      
  2186.                                       ISEGA
  2187.                                       -----
  2188.      
  2189.      
  2190.           Determines if the current screen is driven by an Enhanced Color
  2191.           Graphics Adapter (EGA).  Adapters which are supersets of the EGA
  2192.           standard should be tested for VGA compatibility first.  A VGA
  2193.           emulating an EGA will not return indicating an EGA is attached.
  2194.           Returns a logical true (.T.) or false (.F.) indicator.
  2195.      
  2196.      
  2197.      Format:
  2198.      
  2199.                isega()
  2200.      
  2201.      
  2202.      Parameters:
  2203.      
  2204.                None.
  2205.      
  2206.      
  2207.      Examples:
  2208.      
  2209.                1.   Determine if the current monitor is an EGA.
  2210.      
  2211.                     .
  2212.                     .
  2213.                     .
  2214.                     if isega()
  2215.                          (do fancy stuff)
  2216.                     endif
  2217.                     .
  2218.                     .
  2219.                     .
  2220.      
  2221.      
  2222.      Returns:
  2223.      
  2224.                .T.  .....Indicates that the current screen is an EGA type.
  2225.                
  2226.                .F.  .....Indicates that the current screen is not an EGA
  2227.                          type.
  2228.      
  2229.      
  2230.      Cautions:
  2231.      
  2232.                None.
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.                                       Page #20
  2241.                                           
  2242.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2243.                                           
  2244.  
  2245.                                           
  2246.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2247.      ======================================================================
  2248.  
  2249.  
  2250.  
  2251.      
  2252.                                       ISMONO
  2253.                                       ------
  2254.      
  2255.      
  2256.           Determines if the current screen is a monochrome or fully
  2257.           monochrome compatible monitor.  A VGA emulating a monochrome
  2258.           monitor will not return indicating a monochrome is attached.
  2259.           Returns a logical true (.T.) or false (.F.) indicator.
  2260.      
  2261.      
  2262.      Format:
  2263.      
  2264.                ismono()
  2265.      
  2266.      
  2267.      Parameters:
  2268.      
  2269.                None.
  2270.      
  2271.      
  2272.      Examples:
  2273.      
  2274.                1.   Determine if the current monitor is monochrome.
  2275.      
  2276.                     .
  2277.                     .
  2278.                     .
  2279.                     if ismono()
  2280.                          (do monochrome stuff)
  2281.                     endif
  2282.                     .
  2283.                     .
  2284.                     .
  2285.      
  2286.      
  2287.      Returns:
  2288.      
  2289.                .T.  .....Indicates that the current screen is a monochrome
  2290.                          type.
  2291.                
  2292.                .F.  .....Indicates that the current screen is not a
  2293.                          monochrome type.
  2294.      
  2295.      
  2296.      Cautions:
  2297.      
  2298.                None.
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.                                       Page #21
  2307.                                           
  2308.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2309.                                           
  2310.  
  2311.                                           
  2312.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2313.      ======================================================================
  2314.  
  2315.  
  2316.  
  2317.      
  2318.                                       ISVGA
  2319.                                       -----
  2320.      
  2321.      
  2322.           Determines if the current screen is driven by a Video Graphics
  2323.           Array Adapter (VGA) or 100% compatible.  Returns a logical true
  2324.           (.T.) or false (.F.) indicator.
  2325.      
  2326.      
  2327.      Format:
  2328.      
  2329.                isvga()
  2330.      
  2331.      
  2332.      Parameters:
  2333.      
  2334.                None.
  2335.      
  2336.      
  2337.      Examples:
  2338.      
  2339.                1.   Determine if the current monitor is a VGA.
  2340.      
  2341.                     .
  2342.                     .
  2343.                     .
  2344.                     if isvga()
  2345.                          (do real pretty and fancy stuff)
  2346.                     endif
  2347.                     .
  2348.                     .
  2349.                     .
  2350.      
  2351.      
  2352.      Returns:
  2353.      
  2354.                .T.  .....Indicates that the current screen is a VGA type.
  2355.                
  2356.                .F.  .....Indicates that the current screen is not a VGA type.
  2357.      
  2358.      
  2359.      Cautions:
  2360.      
  2361.                None.
  2362.  
  2363.  
  2364.  
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.  
  2371.  
  2372.                                       Page #22
  2373.                                           
  2374.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2375.                                           
  2376.  
  2377.                                           
  2378.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2379.      ======================================================================
  2380.  
  2381.  
  2382.  
  2383.      
  2384.                                      NEWCOLOR
  2385.                                      --------
  2386.      
  2387.      
  2388.           Changing colors on entire areas of the screen, regardless of the
  2389.           current screen contents, can now be managed very effectively and
  2390.           efficiently with NEWCOLOR.
  2391.           
  2392.           The NEWCOLOR function provides the programmer with the ability to
  2393.           change colors on the screen without having to reset the color and
  2394.           rewrite the screen information.  This is particularly useful in
  2395.           those occasions when a highlighting of information is necessary
  2396.           which would normally be prohibitive due to slow screen update
  2397.           characteristics.  Self programmed light bar menus and highlighting
  2398.           screen selections becomes much easier with this function employed.
  2399.      
  2400.      
  2401.      Format:
  2402.      
  2403.                newcolor(top, left, bottom, right, attr [,type])
  2404.      
  2405.      
  2406.      Parameters:
  2407.      
  2408.                top.......Numeric variable or constant indicating the top row
  2409.                          of the area to be changed.  Value checked to be
  2410.                          between 0 and 24 inclusive.
  2411.                
  2412.                left......Numeric variable or constant indicating the left
  2413.                          column of the area to be changed.  Value checked to
  2414.                          be between 0 and 79 inclusive.
  2415.                
  2416.                bottom....Numeric variable or constant indicating the ending
  2417.                          row of the area to be changed.  Value checked to be
  2418.                          greater than TOP but less than or equal to 24.
  2419.                
  2420.                right.....Numeric variable or constant indicating the right
  2421.                          column of the area to be changed.  Value checked to
  2422.                          be greater than LEFT but less than or equal to 79.
  2423.                
  2424.                attr......Character string variable or constant, non case
  2425.                          sensitive, valid color command or combination for
  2426.                          character and background.  Must be the alpha
  2427.                          representation of the color, the numeric will be
  2428.                          rejected.
  2429.      
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.                                       Page #23
  2439.                                           
  2440.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2441.                                           
  2442.  
  2443.                                           
  2444.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2445.      ======================================================================
  2446.  
  2447.  
  2448.  
  2449.      NEWCOLOR (cont'd)
  2450.      
  2451.                                   (valid colors)
  2452.                          black                         N
  2453.                          blue                          B
  2454.                          green                         G
  2455.                          cyan                          BG
  2456.                          red                           R
  2457.                          magenta                       RB
  2458.                          brown                         GR
  2459.                          white                         W
  2460.                          intense                       +
  2461.                          blink                         *
  2462.      
  2463.                type......OPTIONAL.  Logical variable or constant instructing
  2464.                          the function to use DMA updating or not.
  2465.      
  2466.                          .T.            DEFAULT.  If not specified, the
  2467.                                         function will use DMA screen
  2468.                                         updating.
  2469.                
  2470.                          .F.            Setting this flag to a logical false
  2471.                                         will cause the function to use the
  2472.                                         standard BIOS INT 10H for screen
  2473.                                         updating.
  2474.      
  2475.      
  2476.      Examples:
  2477.      
  2478.                1.   This will change the character attributes from row #10,
  2479.                     column #20 through row #12, column #60 to intense
  2480.                     blinking red (*+r) on a black background (n).
  2481.      
  2482.                     .
  2483.                     .
  2484.                     .
  2485.                     newcolor(10,20,12,60,'*+r/n)
  2486.                     .
  2487.                     .
  2488.                     .
  2489.      
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.  
  2503.  
  2504.                                       Page #24
  2505.                                           
  2506.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2507.                                           
  2508.  
  2509.                                           
  2510.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2511.      ======================================================================
  2512.  
  2513.  
  2514.  
  2515.      NEWCOLOR (cont'd)
  2516.      
  2517.                2.   This will change the character attributes from row #05,
  2518.                     column #10 through row #05, column #15 to inverse white
  2519.                     (w) with black characters (n).
  2520.      
  2521.                     .
  2522.                     .
  2523.                     .
  2524.                     newcolor(5,10,5,15,'n/w')
  2525.                     .
  2526.                     .
  2527.                     .
  2528.      
  2529.      
  2530.      Returns:
  2531.      
  2532.                Nothing.
  2533.      
  2534.      
  2535.      Cautions:
  2536.      
  2537.                None.
  2538.  
  2539.  
  2540.  
  2541.  
  2542.  
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.  
  2549.  
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.  
  2558.  
  2559.  
  2560.  
  2561.  
  2562.  
  2563.  
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.                                       Page #25
  2571.                                           
  2572.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2573.                                           
  2574.  
  2575.                                           
  2576.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2577.      ======================================================================
  2578.  
  2579.  
  2580.  
  2581.      
  2582.                                       PRTSC
  2583.                                       -----
  2584.      
  2585.      
  2586.           Many times users of your applications have simply wanted a print
  2587.           screen of what they see.  In order to accommodate them you usually
  2588.           need to write a routine will recreates the information on the
  2589.           printer.  With PRTSC this is no longer necessary.
  2590.           
  2591.           The PRTSC function actually contains two separate functions.  The
  2592.           first function is a command driven print screen.  Embedded in your
  2593.           source code, the PRTSC command will cause a print screen to happen
  2594.           just as if the SHIFT PRTSC keys were pressed.
  2595.           
  2596.           The second function of PRTSC is that of a translator.  With the use
  2597.           of the BOX command many screens have become "unprintable" by usual
  2598.           standards.  Doing a print screen causes strange characters or
  2599.           control codes to be sent to the printer.  The PRTSC function has
  2600.           the ability to intercept those "unprintable" characters and
  2601.           translate them into simple, unoffensive periods (.).  The basic
  2602.           design of your screen is intact but without lots of programming
  2603.           effort.
  2604.      
  2605.      
  2606.      Format:
  2607.      
  2608.                prtsc(['xlat' | 'off'])
  2609.      
  2610.      
  2611.      Parameters:
  2612.      
  2613.                ()........If no parameters are specified, instructs the
  2614.                          function to perform an immediate print screen.  If
  2615.                          the translate facility has been activated then the
  2616.                          function will perform the print screen translation,
  2617.                          otherwise the standard BIOS interrupt perform as
  2618.                          usual.
  2619.      
  2620.                'xlat'....Character string variable or constant, non case
  2621.                          sensitive, which instructs the function to begin
  2622.                          translation of all print screen activity.  If a
  2623.                          print screen is invoked, either from PRTSC() or from
  2624.                          the keyboard, all characters will be translated
  2625.                          which do not fall into the following range: ASCII 32
  2626.                          to 127 (" " to "~").  The characters are translated
  2627.                          into a period (.).
  2628.      
  2629.  
  2630.  
  2631.  
  2632.  
  2633.  
  2634.  
  2635.  
  2636.                                       Page #26
  2637.                                           
  2638.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2639.                                           
  2640.  
  2641.                                           
  2642.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2643.      ======================================================================
  2644.  
  2645.  
  2646.  
  2647.      PRTSC (cont'd)
  2648.      
  2649.                'off'.....Character string variable or constant, non case
  2650.                          sensitive, which instructs the function to terminate
  2651.                          translation of all print screen activity.  Control
  2652.                          is returned to the BIOS for print screen requests.
  2653.      
  2654.      
  2655.      Examples:
  2656.      
  2657.                1.   A user wishes a snapshot of the currently displayed
  2658.                     record.  Rather than writing a report routine, a print
  2659.                     screen is invoked but, as the screen contains graphical
  2660.                     box characters, a translation is first required.
  2661.      
  2662.                     .
  2663.                     .
  2664.                     .
  2665.                     prtsc('xlat')
  2666.                     prtsc()
  2667.                     prtsc('off')
  2668.                     .
  2669.                     .
  2670.                     .
  2671.      
  2672.                2.   Thinking ahead, the programmer has determined during
  2673.                     installation that the user's printer cannot print the
  2674.                     graphical box characters used on the display screen.  The
  2675.                     translate facility has been activated and when the user
  2676.                     performs a manual print screen the translation is still
  2677.                     effective.
  2678.      
  2679.                     .
  2680.                     .
  2681.                     prtsc('xlat')
  2682.                     .
  2683.                     .
  2684.                     (user presses Shift PrtSc)
  2685.                     .
  2686.                     .
  2687.                     prtsc('off')
  2688.                     (end of program)
  2689.      
  2690.      
  2691.  
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.  
  2701.  
  2702.                                       Page #27
  2703.                                           
  2704.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2705.                                           
  2706.  
  2707.                                           
  2708.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2709.      ======================================================================
  2710.  
  2711.  
  2712.  
  2713.      PRTSC (cont'd)
  2714.      
  2715.      Returns:
  2716.      
  2717.                Nothing.
  2718.      
  2719.      
  2720.      Cautions:
  2721.      
  2722.                This function should not be placed into an overlay as it is
  2723.                interrupt driven.  Any error routines which determine an
  2724.                unrecoverable runtime error has occurred should disable this
  2725.                function prior to exiting the program.  Failure to follow this
  2726.                caution may result in the computer locking up.
  2727.  
  2728.  
  2729.  
  2730.  
  2731.  
  2732.  
  2733.  
  2734.  
  2735.  
  2736.  
  2737.  
  2738.  
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.  
  2746.  
  2747.  
  2748.  
  2749.  
  2750.  
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.  
  2767.  
  2768.                                       Page #28
  2769.                                           
  2770.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2771.                                           
  2772.  
  2773.                                           
  2774.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2775.      ======================================================================
  2776.  
  2777.  
  2778.  
  2779.      
  2780.                                       RESET
  2781.                                       -----
  2782.      
  2783.      
  2784.           The ultimate in password protection, and possibly frustrating
  2785.           enough to prevent future attempts is a complete reset of the
  2786.           computer.  The RESET function provides an instantaneous reset of
  2787.           the computer.  The reset may either be a software reset or a full
  2788.           hardware reset.
  2789.      
  2790.      
  2791.      Format:
  2792.      
  2793.                reset([.T. | .F.])
  2794.      
  2795.      
  2796.      Parameters:
  2797.      
  2798.                .T.  .....Logical variable or constant which instructs the
  2799.                          function to perform a full hardware reset of the
  2800.                          computer.  A hardware reset is defined as a reset
  2801.                          which causes all hardware interrupts to be halted
  2802.                          and restarted by the regular BIOS routines.
  2803.                          Hardware reset may not prove functional on non-100%
  2804.                          compatible BIOS computers.  Hardware reset invokes
  2805.                          all BIOS manufacturer tests (i.e. RAM test).
  2806.      
  2807.                .F.  .....DEFAULT.  Logical variable or constant which
  2808.                          instructs the function to perform a standard
  2809.                          software reset.  This reset is similar in nature to
  2810.                          the CTRL ALT DEL key sequence.  If no parameter is
  2811.                          given to RESET then .F. is assumed.
  2812.      
  2813.      
  2814.      Examples:
  2815.      
  2816.                1.   Perform a hardware reset of the computer.
  2817.      
  2818.                     .
  2819.                     .
  2820.                     .
  2821.                     reset(.t.)
  2822.                     .
  2823.                     .
  2824.                     .
  2825.      
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.                                       Page #29
  2835.                                           
  2836.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2837.                                           
  2838.  
  2839.                                           
  2840.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2841.      ======================================================================
  2842.  
  2843.  
  2844.  
  2845.      RESET (cont'd)
  2846.      
  2847.                2.   Perform a software reset of the computer.
  2848.      
  2849.                     .
  2850.                     .
  2851.                     .
  2852.                     reset()
  2853.                     .
  2854.                     .
  2855.                     .
  2856.      
  2857.      
  2858.      Returns:
  2859.      
  2860.                Nothing.
  2861.      
  2862.      
  2863.      Cautions:
  2864.      
  2865.                This function will immediately halt all operation in the
  2866.                computer.  Due to this it is strongly suggested that no files
  2867.                or background operations (print queues) be active when RESET
  2868.                is invoked.
  2869.  
  2870.  
  2871.  
  2872.  
  2873.  
  2874.  
  2875.  
  2876.  
  2877.  
  2878.  
  2879.  
  2880.  
  2881.  
  2882.  
  2883.  
  2884.  
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.  
  2900.                                       Page #30
  2901.                                           
  2902.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2903.                                           
  2904.  
  2905.                                           
  2906.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2907.      ======================================================================
  2908.  
  2909.  
  2910.  
  2911.      
  2912.                                      RESTBOX
  2913.                                      -------
  2914.      
  2915.      
  2916.           Possibly one of the most flexible functions in PROCLIP2, the
  2917.           RESTBOX function is the companion to SAVEBOX.  Once a section of
  2918.           the screen has been placed into a memory variable by SAVEBOX, the
  2919.           RESTBOX function may be used to restore it.
  2920.           
  2921.           RESTBOX "knows" where the screen portion originally came from, so
  2922.           remembering the coordinates is no longer a necessity.  It is
  2923.           possible, however, to override those original coordinates and
  2924.           reposition the screen portion anywhere on the screen.  You may also
  2925.           use either the original colors, as it was saved, or override them
  2926.           with a new color attribute.
  2927.           
  2928.           Through creative use of SAVEBOX, RESTBOX and the standard Clipper
  2929.           BOX command an impressive control of the screen may be obtained.
  2930.           
  2931.           RESTBOX is not compatible with memory variables saved by the
  2932.           Clipper SAVESCREEN function.
  2933.      
  2934.      
  2935.      Format:
  2936.      
  2937.                restbox([top, left,] scrnarea [,attr][,type])
  2938.      
  2939.      
  2940.      Parameters:
  2941.      
  2942.                top.......OPTIONAL.  Numeric variable or constant indicating
  2943.                          the top row of where the SAVEBOX'd area is to be
  2944.                          restored.  Value checked to be between 0 and 24
  2945.                          inclusive.  If TOP is specified then LEFT must also
  2946.                          be specified.  If TOP,LEFT is not specified RESTBOX
  2947.                          will obtain the original position from within the
  2948.                          SAVEBOX'd variable.
  2949.                
  2950.                left......OPTIONAL.  Numeric variable or constant indicating
  2951.                          the left column of where the SAVEBOX'd area is to be
  2952.                          restored.  Value checked to be between 0 and 79
  2953.                          inclusive.  If LEFT is specified then TOP must also
  2954.                          be specified.
  2955.                
  2956.                scrnarea..Character string variable containing a saved portion
  2957.                          of the screen which was saved with SAVEBOX.  No
  2958.                          changes to this memory variable should have occurred
  2959.                          between the SAVEBOX command and RESTBOX.  Cannot be
  2960.                          a memory variable saved by the Clipper SAVESCREEN
  2961.                          function.
  2962.  
  2963.  
  2964.  
  2965.  
  2966.                                       Page #31
  2967.                                           
  2968.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  2969.                                           
  2970.  
  2971.                                           
  2972.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  2973.      ======================================================================
  2974.  
  2975.  
  2976.  
  2977.      RESTBOX (cont'd)
  2978.      
  2979.                attr......OPTIONAL.  Character string variable or constant,
  2980.                          non case sensitive, which contains a valid color
  2981.                          combination for character and background.  This
  2982.                          color attribute will be used during the restore to
  2983.                          the screen but the original image as saved by
  2984.                          SAVEBOX will not be modified.  Must be the alpha
  2985.                          representation of the color, the numeric will be
  2986.                          rejected.
  2987.      
  2988.                                   (valid colors)
  2989.                          black                         N
  2990.                          blue                          B
  2991.                          green                         G
  2992.                          cyan                          BG
  2993.                          red                           R
  2994.                          magenta                       RB
  2995.                          brown                         GR
  2996.                          white                         W
  2997.                          intense                       +
  2998.                          blink                         *
  2999.      
  3000.                type......OPTIONAL.  Logical variable or constant instructing
  3001.                          the function to use DMA updating or not.  As this is
  3002.                          an optional parameter the function will assume you
  3003.                          wish IBM standard BIOS INT 10H updating.
  3004.                
  3005.                          .T.            DEFAULT.  If not specified, the
  3006.                                         function will use DMA screen
  3007.                                         updating.
  3008.                
  3009.                          .F.            Setting this flag to a logical false
  3010.                                         will cause the function to use the
  3011.                                         standard BIOS INT 10H for screen
  3012.                                         updating.
  3013.      
  3014.      
  3015.      Examples:
  3016.      
  3017.                1.   This will restore a previously saved screen area to the
  3018.                     original location but use a different color attribute.
  3019.      
  3020.                     .
  3021.                     .
  3022.                     .
  3023.                     restbox(scrn1,'+r/n')
  3024.                     .
  3025.                     .
  3026.                     .
  3027.      
  3028.  
  3029.  
  3030.  
  3031.  
  3032.                                       Page #32
  3033.                                           
  3034.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3035.                                           
  3036.  
  3037.                                           
  3038.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3039.      ======================================================================
  3040.  
  3041.  
  3042.  
  3043.      RESTBOX (cont'd)
  3044.      
  3045.                2.   This will restore a previously saved screen area to row
  3046.                     #10, column #20 even if this is a different location than
  3047.                     it was originally obtained from.
  3048.      
  3049.                     .
  3050.                     .
  3051.                     .
  3052.                     restbox(10,20,scrn1)
  3053.                     .
  3054.                     .
  3055.                     .
  3056.      
  3057.                3.   A typical SAVEBOX and RESTBOX combination.
  3058.      
  3059.                     .
  3060.                     .
  3061.                     .
  3062.                     scrn1 = savebox(10,20,12,60)
  3063.                     .
  3064.                     .
  3065.                     .
  3066.                     restbox(scrn1)
  3067.                     .
  3068.                     .
  3069.                     .
  3070.      
  3071.      
  3072.      Returns:
  3073.      
  3074.                Nothing.
  3075.      
  3076.      
  3077.      Cautions:
  3078.      
  3079.                None.
  3080.  
  3081.  
  3082.  
  3083.  
  3084.  
  3085.  
  3086.  
  3087.  
  3088.  
  3089.  
  3090.  
  3091.  
  3092.  
  3093.  
  3094.  
  3095.  
  3096.  
  3097.  
  3098.                                       Page #33
  3099.                                           
  3100.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3101.                                           
  3102.  
  3103.                                           
  3104.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3105.      ======================================================================
  3106.  
  3107.  
  3108.  
  3109.      
  3110.                                      RESTCURS
  3111.                                      --------
  3112.      
  3113.      
  3114.           The companion function to SAVECURS, the RESTCURS function will
  3115.           restore the cursor to it's original shape and position as specified
  3116.           in the memory variable.  Great for restoring the look of a given
  3117.           screen without having to remember where everything was.
  3118.      
  3119.      
  3120.      Format:
  3121.      
  3122.                restcurs(<memvar>)
  3123.      
  3124.      
  3125.      Parameters:
  3126.      
  3127.                <memvar>..A numeric memory variable which was created through
  3128.                          SAVECURS and contains the cursor shape and position
  3129.                          to restore.
  3130.      
  3131.      
  3132.      Examples:
  3133.      
  3134.                See SAVECURS.
  3135.      
  3136.      
  3137.      Returns:
  3138.      
  3139.                Nothing.
  3140.      
  3141.      
  3142.      Cautions:
  3143.      
  3144.                See SAVECURS.
  3145.  
  3146.  
  3147.  
  3148.  
  3149.  
  3150.  
  3151.  
  3152.  
  3153.  
  3154.  
  3155.  
  3156.  
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164.                                       Page #34
  3165.                                           
  3166.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3167.                                           
  3168.  
  3169.                                           
  3170.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3171.      ======================================================================
  3172.  
  3173.  
  3174.  
  3175.      
  3176.                                      SAVEBOX
  3177.                                      -------
  3178.      
  3179.      
  3180.           The SAVEBOX function provides the programmer with a method of
  3181.           saving partial screen images into character memory variables and,
  3182.           using the RESTBOX function, restore them back when needed.
  3183.           
  3184.           SAVEBOX will allow the programmer to save any area of the screen
  3185.           which contains at least one (1) character and up to the entire
  3186.           screen (4000 bytes).  This allows multiple "snapshots" of various
  3187.           area of the screen using the minimum amount of memory necessary.
  3188.           
  3189.           As a temporary storage buffer is required for the screen area
  3190.           during the snapshot, this function temporarily allocates memory
  3191.           from DOS.  If insufficient memory is available the function will
  3192.           refuse to perform and none of the screen area will be saved.  It is
  3193.           very unlikely that this could happen as even the entire screen
  3194.           requires less than 4Kb for temporary storage.
  3195.      
  3196.      
  3197.      Format:
  3198.      
  3199.                <memvar> = savebox(top, left, bottom, right [,type])
  3200.      
  3201.      
  3202.      Parameters:
  3203.      
  3204.                top.......Numeric variable or constant indicating the top row
  3205.                          of the area to be saved.  Value checked to be
  3206.                          between 0 and 24 inclusive.
  3207.                
  3208.                left......Numeric variable or constant indicating the left
  3209.                          column of the area to be saved.  Value checked to be
  3210.                          between 0 and 79 inclusive.
  3211.                
  3212.                bottom....Numeric variable or constant indicating the ending
  3213.                          row of the area to be saved.  Value checked to be
  3214.                          greater than TOP but less than or equal to 24.
  3215.                
  3216.                right.....Numeric variable or constant indicating the right
  3217.                          column of the area to be changed.  Value checked to
  3218.                          be greater than LEFT but less than or equal to 79.
  3219.                
  3220.  
  3221.  
  3222.  
  3223.  
  3224.  
  3225.  
  3226.  
  3227.  
  3228.  
  3229.  
  3230.                                       Page #35
  3231.                                           
  3232.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3233.                                           
  3234.  
  3235.                                           
  3236.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3237.      ======================================================================
  3238.  
  3239.  
  3240.  
  3241.      SAVEBOX (cont'd)
  3242.      
  3243.                type......OPTIONAL.  Logical variable or constant instructing
  3244.                          the function to use DMA updating or not.
  3245.                
  3246.                          .T.            DEFAULT.  If not specified, the
  3247.                                         function will use DMA screen
  3248.                                         updating.
  3249.                
  3250.                          .F.            Setting this flag to a logical false
  3251.                                         will cause the function to use the
  3252.                                         standard BIOS INT 10H for screen
  3253.                                         updating.
  3254.      
  3255.      
  3256.      Examples:
  3257.      
  3258.                1.   To save the screen data, and attributes, into a memory
  3259.                     variable from row #10, column #20 through row #12, column
  3260.                     #60.
  3261.      
  3262.                     .
  3263.                     .
  3264.                     .
  3265.                     scrnarea = savebox(10,20,12,60)
  3266.                     .
  3267.                     .
  3268.                     .
  3269.      
  3270.      
  3271.      Returns:
  3272.      
  3273.                <memvar>..A character string variable which contains the data
  3274.                          as it was read from the screen preceded by four (4)
  3275.                          bytes of control information.
  3276.      
  3277.      
  3278.      Cautions:
  3279.      
  3280.                Do not modify the contents of the memory variable after it is
  3281.                returned from SAVEBOX.  The results may not be as you desire.
  3282.  
  3283.  
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.  
  3296.                                       Page #36
  3297.                                           
  3298.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3299.                                           
  3300.  
  3301.                                           
  3302.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3303.      ======================================================================
  3304.  
  3305.  
  3306.  
  3307.      
  3308.                                      SAVECURS
  3309.                                      --------
  3310.      
  3311.      
  3312.           SAVECURS provides the programmer with the ability to save the
  3313.           current cursor shape and position on the video screen.  This is
  3314.           extremely useful when using any type of on-line help system or
  3315.           other functions which temporarily occupy the screen and you'd like
  3316.           the cursor to return where it was when completed.  See RESTCURS.
  3317.      
  3318.      
  3319.      Format:
  3320.      
  3321.                <memvar> = savecurs()
  3322.      
  3323.      
  3324.      Parameters:
  3325.      
  3326.                None.
  3327.      
  3328.      
  3329.      Examples:
  3330.      
  3331.                1.   Save the current cursor shape and position while invoking
  3332.                     a subfunction.
  3333.      
  3334.                     .
  3335.                     .
  3336.                     .
  3337.                     aCursor = savecurs()
  3338.                     .
  3339.                     (do a sub function)
  3340.                     .
  3341.                     restcurs(aCursor)
  3342.                     .
  3343.                     .
  3344.                     .
  3345.      
  3346.      
  3347.  
  3348.  
  3349.  
  3350.  
  3351.  
  3352.  
  3353.  
  3354.  
  3355.  
  3356.  
  3357.  
  3358.  
  3359.  
  3360.  
  3361.  
  3362.                                       Page #37
  3363.                                           
  3364.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3365.                                           
  3366.  
  3367.                                           
  3368.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3369.      ======================================================================
  3370.  
  3371.  
  3372.  
  3373.      SAVECURS (cont'd)
  3374.      
  3375.      Returns:
  3376.      
  3377.                <memvar>..a numeric variable which will contain the cursor
  3378.                          shape and position on the screen.  These values are
  3379.                          embedded in this variable and the variable will
  3380.                          return a zero (0) value if accessed from Clipper.
  3381.      
  3382.      
  3383.      Cautions:
  3384.      
  3385.                In order to properly restore the cursor care should be taken
  3386.                not to use the numeric variable in any other fashion.
  3387.  
  3388.  
  3389.  
  3390.  
  3391.  
  3392.  
  3393.  
  3394.  
  3395.  
  3396.  
  3397.  
  3398.  
  3399.  
  3400.  
  3401.  
  3402.  
  3403.  
  3404.  
  3405.  
  3406.  
  3407.  
  3408.  
  3409.  
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416.  
  3417.  
  3418.  
  3419.  
  3420.  
  3421.  
  3422.  
  3423.  
  3424.  
  3425.  
  3426.  
  3427.  
  3428.                                       Page #38
  3429.                                           
  3430.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3431.                                           
  3432.  
  3433.                                           
  3434.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3435.      ======================================================================
  3436.  
  3437.  
  3438.  
  3439.      
  3440.                                        SDIR
  3441.                                        ----
  3442.      
  3443.      
  3444.           Similar to the standard Clipper ADIR command, the SDIR command
  3445.           provides the programmer with the ability to read any valid
  3446.           directory and obtain standard directory information on an entry by
  3447.           entry basis.  Entries include all valid directory entries including
  3448.           subdirectory and volume label names.  Using the attribute filter,
  3449.           the SDIR function will only return those files matching the
  3450.           attributes.  SDIR will return the entry name, date, time or file
  3451.           size depending upon the function call used.
  3452.      
  3453.      
  3454.      Format:
  3455.      
  3456.                <memvar> = SDIR(pattern, 'first' [,fileattr])
  3457.                <memvar> = SDIR('next')
  3458.                <memvar> = SDIR('date')
  3459.                <memvar> = SDIR('time')
  3460.                <memvar> = SDIR('size')
  3461.                <memvar> = SDIR(pattern, 'count' [,fileattr])
  3462.      
  3463.      
  3464.      Parameters:
  3465.      
  3466.                pattern...Character string variable or constant, non case
  3467.                          sensitive, which informs the function of the entry
  3468.                          pattern to search with.  The PATTERN may contain any
  3469.                          valid drive or DOS path as well as wildcards (eg.
  3470.                          "*" & "?").
  3471.      
  3472.                'first'...Character string variable or constant, non case
  3473.                          sensitive, which instructs the function to obtain
  3474.                          the first matching directory entry in the specified
  3475.                          directory.  If FIRST is specified then a PATTERN
  3476.                          must be supplied.  FIRST reinitializes the search
  3477.                          function and sets up the function for subsequent
  3478.                          activity based on the PATTERN provided.
  3479.      
  3480.  
  3481.  
  3482.  
  3483.  
  3484.  
  3485.  
  3486.  
  3487.  
  3488.  
  3489.  
  3490.  
  3491.  
  3492.  
  3493.  
  3494.                                       Page #39
  3495.                                           
  3496.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3497.                                           
  3498.  
  3499.                                           
  3500.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3501.      ======================================================================
  3502.  
  3503.  
  3504.  
  3505.      SDIR (cont'd)
  3506.      
  3507.                'next'....Character string variable or constant, non case
  3508.                          sensitive, which instructs the function to obtain
  3509.                          the next matching entry based on the last FIRST
  3510.                          function.  In other words, a FIRST must be called
  3511.                          first in order to obtain the first entry and
  3512.                          initialize the function.  Subsequent NEXT functions
  3513.                          will continue reading the directory one entry at a
  3514.                          time until all entries have been read.
  3515.      
  3516.                'date'....Character string variable or constant, non case
  3517.                          sensitive, which instructs the function to obtain
  3518.                          the date of the last entry returned with either
  3519.                          FIRST or NEXT, whichever was last.  If the file is
  3520.                          currently open (as in an active database file) this
  3521.                          date may not reflect the actual last update date.
  3522.                          In these cases the active file should be closed to
  3523.                          allow the operating system to update the directory
  3524.                          prior to requesting this function.
  3525.      
  3526.                'time'....Character string variable or constant, non case
  3527.                          sensitive, which instructs the function to obtain
  3528.                          the time of the last entry returned with either
  3529.                          FIRST or NEXT, whichever was last.  As in DATE the
  3530.                          file should be closed prior to requesting this
  3531.                          function.
  3532.      
  3533.                'size'....Character string variable or constant, non case
  3534.                          sensitive, which instructs the function to obtain
  3535.                          the size of the last entry returned with either
  3536.                          FIRST or NEXT, whichever was last.  As in TIME and
  3537.                          DATE above the file should be closed prior to
  3538.                          requesting this function.
  3539.      
  3540.                'count'...Character string variable or constant, non case
  3541.                          sensitive, which instructs the function to obtain
  3542.                          the number of files matching PATTERN.  If COUNT is
  3543.                          specified then PATTERN must also be specified.
  3544.      
  3545.  
  3546.  
  3547.  
  3548.  
  3549.  
  3550.  
  3551.  
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.  
  3559.  
  3560.                                       Page #40
  3561.                                           
  3562.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3563.                                           
  3564.  
  3565.                                           
  3566.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3567.      ======================================================================
  3568.  
  3569.  
  3570.  
  3571.      SDIR (cont'd)
  3572.      
  3573.                fileattr..Character string variable or constant, non case
  3574.                          sensitive, which instructs the function to only
  3575.                          select those directory entries which have at least
  3576.                          these attributes.
  3577.      
  3578.                                   (valid file attributes)
  3579.                
  3580.                               r/o                 Read only
  3581.                               hid                 Hidden
  3582.                               sys                 System
  3583.                               vol                 Volume label
  3584.                               sub                 Subdirectory
  3585.                               arc                 Archive
  3586.      
  3587.      
  3588.      Examples:
  3589.      
  3590.                1.   Read the current directory and when the chosen file is
  3591.                     found obtain the date, time and size of the file.  As no
  3592.                     attribute is specified all directory entries will be
  3593.                     returned which match the pattern and have at least the
  3594.                     archive attribute set (arc).
  3595.      
  3596.                     .
  3597.                     .
  3598.                     .
  3599.                     pattern = 'YOUR????.DBF'
  3600.                     filename = sdir(pattern,'first')
  3601.                     if .not. empty(filename)
  3602.                          filedate = sdir('date')
  3603.                          filetime = sdir('time')
  3604.                          filesize = sdir('size')
  3605.                     endif
  3606.                     .
  3607.                     .
  3608.                     .
  3609.      
  3610.  
  3611.  
  3612.  
  3613.  
  3614.  
  3615.  
  3616.  
  3617.  
  3618.  
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  
  3624.  
  3625.  
  3626.                                       Page #41
  3627.                                           
  3628.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3629.                                           
  3630.  
  3631.                                           
  3632.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3633.      ======================================================================
  3634.  
  3635.  
  3636.  
  3637.      SDIR (cont'd)
  3638.      
  3639.                1.   Read a different, valid, directory and return all of the
  3640.                     names of all subdirectory entries by specifying an
  3641.                     attribute of subdirectory only.
  3642.      
  3643.                     .
  3644.                     .
  3645.                     .
  3646.                     aSubDir = sdir('C:\LEVEL1\LEVEL2\*.*','first','sub')
  3647.                     do while .not. empty(aSubDir)
  3648.                          ? direntry
  3649.                          aSubDir = sdir('next')
  3650.                     enddo
  3651.                     .
  3652.                     .
  3653.                     .
  3654.      
  3655.      
  3656.      Returns:
  3657.      
  3658.                'first'...If successful, <memvar> is set to a character string
  3659.                          type and returned with the filename of the first
  3660.                          file matching PATTERN.  If unsuccessful, <memvar> is
  3661.                          set to a character string type and returned with a
  3662.                          zero length (null).
  3663.      
  3664.                'next'....Same as FIRST.
  3665.      
  3666.                'date'....If successful, <memvar> is set to a date type and
  3667.                          returned with the entry date per the active
  3668.                          directory entry.  If unsuccessful, <memvar> is set
  3669.                          to a date type and returned with a '00/00/00' date.
  3670.      
  3671.                'time'....If successful, <memvar> is set to a character type
  3672.                          and returned with the entry time per the active
  3673.                          directory entry in HH:MM:SS format.  If
  3674.                          unsuccessful, <memvar> is set to a character type
  3675.                          and returned with a zero length (null).
  3676.      
  3677.                'size'....If successful, <memvar> is set to a numeric type and
  3678.                          returned with the file size (subdirectory entries
  3679.                          are always zero (0) length) per the active directory
  3680.                          entry.  If unsuccessful, <memvar> is set to a
  3681.                          numeric type and returned with a zero value (0).
  3682.      
  3683.  
  3684.  
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.  
  3691.  
  3692.                                       Page #42
  3693.                                           
  3694.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3695.                                           
  3696.  
  3697.                                           
  3698.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3699.      ======================================================================
  3700.  
  3701.  
  3702.  
  3703.      SDIR (cont'd)
  3704.      
  3705.                'count'...If successful, <memvar> is set to a numeric type and
  3706.                          returned with the number of entries matching the
  3707.                          specified pattern.  If unsuccessful, <memvar> is set
  3708.                          to a numeric type and returned with a zero value
  3709.                          (0).
  3710.      
  3711.      
  3712.      Cautions:
  3713.      
  3714.                None.
  3715.  
  3716.  
  3717.  
  3718.  
  3719.  
  3720.  
  3721.  
  3722.  
  3723.  
  3724.  
  3725.  
  3726.  
  3727.  
  3728.  
  3729.  
  3730.  
  3731.  
  3732.  
  3733.  
  3734.  
  3735.  
  3736.  
  3737.  
  3738.  
  3739.  
  3740.  
  3741.  
  3742.  
  3743.  
  3744.  
  3745.  
  3746.  
  3747.  
  3748.  
  3749.  
  3750.  
  3751.  
  3752.  
  3753.  
  3754.  
  3755.  
  3756.  
  3757.  
  3758.                                       Page #43
  3759.                                           
  3760.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3761.                                           
  3762.  
  3763.                                           
  3764.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3765.      ======================================================================
  3766.  
  3767.  
  3768.  
  3769.      
  3770.                                       SOUND
  3771.                                       -----
  3772.      
  3773.           Similar in general concept to the Clipper TONE() command, SOUND()
  3774.           provides the programmer with the added flexibility of creating
  3775.           sounds for a shorter duration of time.  The Clipper TONE() command
  3776.           is driven off the internal timer of the computer which "pulses"
  3777.           18.2 times per second.  Due to this the TONE() command has a
  3778.           "resolution" of 1/18th of a second in that it cannot generate a
  3779.           tone for a shorter duration of time.  With SOUND() it is possible
  3780.           to create a sound for as little as 1/100th of a second.  Although
  3781.           1/100th of a second is the same from computer to computer, software
  3782.           can have difficultly calculating what 1/100th of a second is due to
  3783.           timing differences between computers.  SOUND() does not have this
  3784.           problem as it automatically calculates the exact timing necessary
  3785.           for 1/100th of a second to pass, regardless of CPU speed.
  3786.      
  3787.      
  3788.      Format:
  3789.      
  3790.                sound(tone, duration [,type])
  3791.      
  3792.      
  3793.      Parameters:
  3794.      
  3795.                tone......Numeric variable or constant which informs the
  3796.                          function of the frequency you wish to use.  The
  3797.                          frequency is the number of Hertz (cycles per
  3798.                          second).  The higher the frequency the higher the
  3799.                          tone, the lower the frequency the lower the tone.
  3800.                          Allowable range for this parameter is 37 through
  3801.                          32767.
  3802.      
  3803.                duration..Numeric variable or constant which informs the
  3804.                          function of the duration to use.  The duration is
  3805.                          the amount of time the speaker will generate the
  3806.                          tone before shutting off.  As two duration
  3807.                          resolutions are available (timer and internal), this
  3808.                          value will have different meanings.  See the "type"
  3809.                          description below.
  3810.  
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.  
  3823.  
  3824.                                       Page #44
  3825.                                           
  3826.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3827.                                           
  3828.  
  3829.                                           
  3830.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3831.      ======================================================================
  3832.  
  3833.  
  3834.  
  3835.      SOUND (cont'd)
  3836.      
  3837.                type......OPTIONAL.  Logical variable or constant which
  3838.                          informs the function as to the type of duration to
  3839.                          use.
  3840.                
  3841.                          .T.            DEFAULT.  Instructs the function to
  3842.                                         use timer ticks as the duration
  3843.                                         count.  A duration of 5 would last
  3844.                                         for 5 timer ticks or 5/18ths of a
  3845.                                         second.  Resolution range in this
  3846.                                         mode is 1/18th of a second to 3,640
  3847.                                         seconds (approx 1 hour).
  3848.                
  3849.                          .F.            Instructs the function to use
  3850.                                         1/100ths as the duration count.  A
  3851.                                         duration of 5 would last for 5/100ths
  3852.                                         (1/20th) of a second.  Resolution
  3853.                                         range in this mode is 1/100th of a
  3854.                                         second to 655 seconds (10.9 minutes).
  3855.      
  3856.      
  3857.      Examples:
  3858.      
  3859.                1.   Generate a good tone for an error message.  Use the
  3860.                     "internal timing" of 1/100ths of a second.  Each tone
  3861.                     will be generated for 3/100ths of a second.
  3862.      
  3863.                     .
  3864.                     .
  3865.                     .
  3866.                     sound(2000,3,.F.)
  3867.                     sound(500,3,.F.)
  3868.                     sound(2000,3,.F.)
  3869.                     .
  3870.                     .
  3871.                     .
  3872.      
  3873.                2.   Generate a tone indicating a different condition than
  3874.                     above.  Use the default timing of "timer ticks".  Each
  3875.                     sound will be generated for 1/18th of a second.
  3876.      
  3877.                     .
  3878.                     .
  3879.                     .
  3880.                     sound(2000,1)
  3881.                     sound(1000,1)
  3882.                     .
  3883.                     .
  3884.                     .
  3885.      
  3886.  
  3887.  
  3888.  
  3889.  
  3890.                                       Page #45
  3891.                                           
  3892.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3893.                                           
  3894.  
  3895.                                           
  3896.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3897.      ======================================================================
  3898.  
  3899.  
  3900.  
  3901.      SOUND (cont'd)
  3902.      
  3903.      Returns:
  3904.      
  3905.                Nothing.
  3906.      
  3907.      
  3908.      Cautions:
  3909.      
  3910.                None.
  3911.  
  3912.  
  3913.  
  3914.  
  3915.  
  3916.  
  3917.  
  3918.  
  3919.  
  3920.  
  3921.  
  3922.  
  3923.  
  3924.  
  3925.  
  3926.  
  3927.  
  3928.  
  3929.  
  3930.  
  3931.  
  3932.  
  3933.  
  3934.  
  3935.  
  3936.  
  3937.  
  3938.  
  3939.  
  3940.  
  3941.  
  3942.  
  3943.  
  3944.  
  3945.  
  3946.  
  3947.  
  3948.  
  3949.  
  3950.  
  3951.  
  3952.  
  3953.  
  3954.  
  3955.  
  3956.                                       Page #46
  3957.                                           
  3958.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  3959.                                           
  3960.  
  3961.                                           
  3962.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  3963.      ======================================================================
  3964.  
  3965.  
  3966.  
  3967.      
  3968.                                       SPRINT
  3969.                                       ------
  3970.      
  3971.      
  3972.           Add new flexibility to your programming with the SPRINT command.
  3973.           This function allows display of a character string on the screen
  3974.           using a different color attribute than that which is currently
  3975.           selected through SET COLOR TO.  The function will either retain the
  3976.           current cursor position or move the cursor to the end of the newly
  3977.           displayed string.  Not subject to SET DEVICE TO so updating of
  3978.           screen and printer can be performed easily.
  3979.      
  3980.      
  3981.      Format:
  3982.      
  3983.                sprint([row, col,] string [,attr][,type])
  3984.      
  3985.                     or
  3986.      
  3987.                @ x,y say sprint(string [,attr][,type])
  3988.      
  3989.      
  3990.      Parameters:
  3991.      
  3992.                row.......OPTIONAL.  Numeric variable or constant which
  3993.                          informs the function of the row (line) number on
  3994.                          which to begin display of the string.  Use of ROW
  3995.                          assumes a COL will be specified.  ROW must be a
  3996.                          valid video line number between 0 and 24 inclusive.
  3997.                          If the string will not fit on ROW it will be wrapped
  3998.                          to the following line (if any).
  3999.      
  4000.                col.......OPTIONAL.  Numeric variable or constant which
  4001.                          informs the function of the column number on which
  4002.                          to begin the display of the string.  Use of COL
  4003.                          assumes the use of ROW.  COL must be a valid video
  4004.                          column number between 0 and 79 inclusive.  Using the
  4005.                          format of sprint(row,col...) will not reposition the
  4006.                          cursor, the cursor position will not change.  Using
  4007.                          the @ x,y say... format will reposition the cursor
  4008.                          to the end of the displayed string.
  4009.      
  4010.                          sprint(row,col...)
  4011.                                         After printing the string, the cursor
  4012.                                         will be returned to the position last
  4013.                                         known by Clipper.  In other words the
  4014.                                         cursor will not move.
  4015.                
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.  
  4022.                                       Page #47
  4023.                                           
  4024.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4025.                                           
  4026.  
  4027.                                           
  4028.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4029.      ======================================================================
  4030.  
  4031.  
  4032.  
  4033.      SPRINT (cont'd)
  4034.      
  4035.                          @...SAY sprint(...)
  4036.                                         After printing the string, the cursor
  4037.                                         will be moved to the end of the
  4038.                                         string just printed.  Acts similar to
  4039.                                         the standard @...SAY... in this
  4040.                                         fashion but you still get the color
  4041.                                         override capability.
  4042.      
  4043.                string....Character string variable or constant which will be
  4044.                          displayed beginning at the requested position.
  4045.      
  4046.                attr......OPTIONAL.  Character string variable or constant,
  4047.                          non case sensitive, which informs the function what
  4048.                          color attributes to use when displaying.  If not
  4049.                          specified the function will use the attribute
  4050.                          currently displayed on the screen at the starting
  4051.                          position for the string.
  4052.      
  4053.                                   (valid colors)
  4054.                          black                         N
  4055.                          blue                          B
  4056.                          green                         G
  4057.                          cyan                          BG
  4058.                          red                           R
  4059.                          magenta                       RB
  4060.                          brown                         GR
  4061.                          white                         W
  4062.                          intense                       +
  4063.                          blink                         *
  4064.      
  4065.                type......OPTIONAL.  Logical variable or constant instructing
  4066.                          the function to use DMA updating or not.
  4067.                
  4068.                          .T.            DEFAULT.  If not specified, the
  4069.                                         function will use DMA screen
  4070.                                         updating.
  4071.                
  4072.                          .F.            Setting this flag to a logical false
  4073.                                         will cause the function to use the
  4074.                                         standard BIOS INT 10H for screen
  4075.                                         updating.
  4076.      
  4077.      
  4078.  
  4079.  
  4080.  
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.  
  4087.  
  4088.                                       Page #48
  4089.                                           
  4090.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4091.                                           
  4092.  
  4093.                                           
  4094.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4095.      ======================================================================
  4096.  
  4097.  
  4098.  
  4099.      SPRINT (cont'd)
  4100.      
  4101.      Examples:
  4102.      
  4103.                1.   Print a warning message on the screen but do not
  4104.                     reposition the cursor.  Further, print the message in
  4105.                     bright red on a black background even though those colors
  4106.                     are not currently selected.
  4107.      
  4108.                     .
  4109.                     .
  4110.                     .
  4111.                     sprint(24,00,"Don't press that key again!","+r/b")
  4112.                     .
  4113.                     .
  4114.                     .
  4115.      
  4116.                2.   Print a message on the screen and reposition the cursor
  4117.                     to the end of the message.  Use the intense white on a
  4118.                     black background.
  4119.      
  4120.                     .
  4121.                     .
  4122.                     .
  4123.                     @ 10,00 say sprint('Enter your password: ','+w/b')
  4124.                     .
  4125.                     .
  4126.                     .
  4127.      
  4128.      
  4129.      Returns:
  4130.      
  4131.                null......A null character string is returned thereby allowing
  4132.                          SPRINT to be used "in line" with a standard Clipper
  4133.                          @... SAY...  (eg.  @ X,Y SAY "Hi" + sprint(...) is
  4134.                          valid).
  4135.      
  4136.      
  4137.      Cautions:
  4138.      
  4139.                None.
  4140.  
  4141.  
  4142.  
  4143.  
  4144.  
  4145.  
  4146.  
  4147.  
  4148.  
  4149.  
  4150.  
  4151.  
  4152.  
  4153.  
  4154.                                       Page #49
  4155.                                           
  4156.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4157.                                           
  4158.  
  4159.                                           
  4160.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4161.      ======================================================================
  4162.  
  4163.  
  4164.  
  4165.      
  4166.                                       STAMP
  4167.                                       -----
  4168.      
  4169.      
  4170.           Many times date and time stamps are the only way to know when a
  4171.           database was last used.  The STAMP functions provides the
  4172.           programmer with the ability to change the date and/or time of any
  4173.           file.  If no date and time are given in the function call, the
  4174.           STAMP function will set the date and time of the file to the
  4175.           current date and time as maintained by DOS.
  4176.      
  4177.      
  4178.      Format:
  4179.      
  4180.                stamp(filename [,date] [,time])
  4181.      
  4182.      
  4183.      Parameters:
  4184.      
  4185.                filename..Character string variable or constant, non case
  4186.                          sensitive, which contains the filename to STAMP.
  4187.                          STAMP will not accept filenames containing wildcards
  4188.                          (* & ?) but paths and alternate drives are
  4189.                          acceptable.
  4190.      
  4191.                date......Date variable or constant which is the date to set
  4192.                          the file to.  If DATE is not specified, and TIME is
  4193.                          specified, the file's date stamp will not be
  4194.                          affected.
  4195.      
  4196.                time......Character string variable or constant containing the
  4197.                          time to set the file to.  The time format should be
  4198.                          HH:MM:SS but seconds are not necessary (eg. HH:MM is
  4199.                          also valid).  If TIME is not specified, and DATE is
  4200.                          specified, the file's time stamp will not be
  4201.                          affected.
  4202.      
  4203.                          If no parameters are specified other than the
  4204.                          FILENAME, the date and time will be obtained from
  4205.                          DOS and the file's date and time stamps will be
  4206.                          updated accordingly.
  4207.      
  4208.      
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219.  
  4220.                                       Page #50
  4221.                                           
  4222.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4223.                                           
  4224.  
  4225.                                           
  4226.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4227.      ======================================================================
  4228.  
  4229.  
  4230.  
  4231.      STAMP (cont'd)
  4232.      
  4233.      Examples:
  4234.      
  4235.                1.   Set all of the DBF files in the directory to a specific
  4236.                     date and time.
  4237.      
  4238.                     .
  4239.                     .
  4240.                     .
  4241.                     aDate = ctod("10/22/86")
  4242.                     aTime = "10:12:15"
  4243.                     filename = sdir("*.*","first")
  4244.                     do while .not. empty(filename)
  4245.                          stamp(filename,aDate,aTime)
  4246.                          filename = sdir('next')
  4247.                     enddo
  4248.                     .
  4249.                     .
  4250.                     .
  4251.      
  4252.      
  4253.      Returns:
  4254.      
  4255.                Nothing.
  4256.      
  4257.      
  4258.      Cautions:
  4259.      
  4260.                The file being STAMPed should not currently be opened by any
  4261.                other process.  Close all files first.
  4262.  
  4263.  
  4264.  
  4265.  
  4266.  
  4267.  
  4268.  
  4269.  
  4270.  
  4271.  
  4272.  
  4273.  
  4274.  
  4275.  
  4276.  
  4277.  
  4278.  
  4279.  
  4280.  
  4281.  
  4282.  
  4283.  
  4284.  
  4285.  
  4286.                                       Page #51
  4287.                                           
  4288.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4289.                                           
  4290.  
  4291.                                           
  4292.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4293.      ======================================================================
  4294.  
  4295.  
  4296.  
  4297.      
  4298.                                      UNRESET
  4299.                                      -------
  4300.      
  4301.      
  4302.           Having frustrated users reset the computer in the middle of your
  4303.           application is not fun...neither is recovering corrupted data
  4304.           bases.  UNRESET is designed to intercept the CTRL ALT DEL keyboard
  4305.           sequence and, optionally, prevent the computer from resetting.
  4306.           
  4307.           UNRESET will, at the programmers option, either intercept and
  4308.           ignore CTRL ALT DEL keyboard sequences or intercept and display a
  4309.           warning message to the operator which requires a second CTRL ALT
  4310.           DEL to activate the reset.
  4311.      
  4312.      
  4313.      Format:
  4314.      
  4315.                unreset('on' | 'off' | 'warn')
  4316.      
  4317.      
  4318.      Parameters:
  4319.      
  4320.                'on'......Character string variable or constant, non case
  4321.                          sensitive, which instructs the function to become
  4322.                          active and intercept and ignore all CTRL ALT DEL
  4323.                          keyboard sequences.
  4324.      
  4325.                'off'.....Character string variable or constant, non case
  4326.                          sensitive, which instructs the function to disable
  4327.                          itself and allow CTRL ALT DEL keyboard sequences
  4328.                          through to the regular computer keyboard routines.
  4329.      
  4330.                'warn'....Character string variable or constant, non case
  4331.                          sensitive, which instructs the function to become
  4332.                          active and intercept all CTRL ALT DEL keyboard
  4333.                          sequences.  Once intercepted the function will warn
  4334.                          the user of their action by opening a window
  4335.                          centered on the screen which reads:
  4336.      
  4337.                                  CTRL + ALT + DEL
  4338.      
  4339.                               Press again to confirm
  4340.      
  4341.                          The user must then reissue the CTRL ALT DEL sequence
  4342.                          to force a reset or, by pressing any regular key,
  4343.                          close the window and resume execution of the
  4344.                          program.
  4345.      
  4346.      
  4347.  
  4348.  
  4349.  
  4350.  
  4351.  
  4352.                                       Page #52
  4353.                                           
  4354.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4355.                                           
  4356.  
  4357.                                           
  4358.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4359.      ======================================================================
  4360.  
  4361.  
  4362.  
  4363.      UNRESET (cont'd)
  4364.      
  4365.      Examples:
  4366.      
  4367.                1.   Completely disable CTRL ALT DEL during critical
  4368.                     processing.
  4369.      
  4370.                     .
  4371.                     .
  4372.                     .
  4373.                     unreset('on')
  4374.                     use dbffile index ntxfile
  4375.                     append blank
  4376.                     replace ...
  4377.                     close databases
  4378.                     unreset('off')
  4379.                     .
  4380.                     .
  4381.                     .
  4382.      
  4383.                2.   Issue a warning prior to allowing a reset to occur.
  4384.                     Disable the UNRESET function before exiting program.
  4385.      
  4386.                     .
  4387.                     .
  4388.                     .
  4389.                     unreset('warn')
  4390.                     .
  4391.                     .
  4392.                     .
  4393.                     unreset('off')
  4394.                     quit
  4395.      
  4396.      
  4397.      Returns:
  4398.      
  4399.                Nothing.
  4400.      
  4401.      
  4402.      Cautions:
  4403.      
  4404.                This function should not be placed into an overlay as it is
  4405.                interrupt driven.  Any error routines which determine an
  4406.                unrecoverable runtime error has occurred should disable this
  4407.                function prior to exiting the program.  Failure to follow this
  4408.                caution may result in the computer locking up.
  4409.  
  4410.  
  4411.  
  4412.  
  4413.  
  4414.  
  4415.  
  4416.  
  4417.  
  4418.                                       Page #53
  4419.                                           
  4420.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4421.                                           
  4422.  
  4423.                                           
  4424.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4425.      ======================================================================
  4426.  
  4427.  
  4428.  
  4429.      
  4430.                                       VIDEO
  4431.                                       -----
  4432.      
  4433.      
  4434.           The VIDEO function has the ability to disable or enable the video
  4435.           signal to the current video controller.  This has the effect of
  4436.           "blanking" a monitor during idle times which will prevent monitor
  4437.           burn.  Current supported monitor types are monochrome (MONO), color
  4438.           (CGA), enhanced (EGA) and video graphics array (VGA).
  4439.      
  4440.      
  4441.      Format:
  4442.      
  4443.                video('on' | 'off')
  4444.      
  4445.      
  4446.      Parameters:
  4447.      
  4448.                'on'......Character string variable or constant, non case
  4449.                          sensitive, instructing  the function to enable the
  4450.                          video signal on the video controller.  Uses the last
  4451.                          BIOS saved screen mode to enable the video signal
  4452.                          through a direct command to the video controller.
  4453.                          The screen will restore to the current contents of
  4454.                          the video memory instantaneously.
  4455.      
  4456.                'off'.....Character string variable or constant, non case
  4457.                          sensitive, instructing the function to disable the
  4458.                          video signal on the video controller.  Uses the last
  4459.                          BIOS saved screen mode, modified with proper bit
  4460.                          settings, to disable the video signal through a
  4461.                          direct command to the video controller.  None of the
  4462.                          information is lost from the screen as the screen is
  4463.                          simply "turned off", not erased.
  4464.      
  4465.      
  4466.      Examples:
  4467.      
  4468.                1.   Turn off the video controller video drive signal after
  4469.                     waiting sixty (60) seconds for some keystroke.
  4470.      
  4471.                     .
  4472.                     .
  4473.                     .
  4474.                     inkey(60)
  4475.                     video('off')
  4476.                     .
  4477.                     .
  4478.                     .
  4479.      
  4480.  
  4481.  
  4482.  
  4483.  
  4484.                                       Page #54
  4485.                                           
  4486.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4487.                                           
  4488.  
  4489.                                           
  4490.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4491.      ======================================================================
  4492.  
  4493.  
  4494.  
  4495.      VIDEO (cont'd)
  4496.      
  4497.                2.   Turn on the video controller drive signal.
  4498.      
  4499.                     .
  4500.                     .
  4501.                     .
  4502.                     video('on')
  4503.                     .
  4504.                     .
  4505.                     .
  4506.      
  4507.      
  4508.      Returns:
  4509.      
  4510.                Nothing.
  4511.      
  4512.      
  4513.      Cautions:
  4514.      
  4515.                None.
  4516.  
  4517.  
  4518.  
  4519.  
  4520.  
  4521.  
  4522.  
  4523.  
  4524.  
  4525.  
  4526.  
  4527.  
  4528.  
  4529.  
  4530.  
  4531.  
  4532.  
  4533.  
  4534.  
  4535.  
  4536.  
  4537.  
  4538.  
  4539.  
  4540.  
  4541.  
  4542.  
  4543.  
  4544.  
  4545.  
  4546.  
  4547.  
  4548.  
  4549.  
  4550.                                       Page #55
  4551.                                           
  4552.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4553.                                           
  4554.  
  4555.                                           
  4556.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4557.      ======================================================================
  4558.  
  4559.  
  4560.  
  4561.      
  4562.                                      VSCROLL
  4563.                                      -------
  4564.      
  4565.      
  4566.           The premier scrolling function...bar none.  Many times we've all
  4567.           needed a scrolling function like VSCROLL.  The VSCROLL function
  4568.           performs video scrolling, either vertically (up and down) or
  4569.           horizontally (left and right), and allows the programmer to control
  4570.           the attribute of the blank line (or column) left behind by the
  4571.           scrolling action.
  4572.      
  4573.      
  4574.      Format:
  4575.      
  4576.                vscroll(top, left, bottom, right, lines, dir [,attr])
  4577.      
  4578.      
  4579.      Parameters:
  4580.      
  4581.                top.......Numeric variable or constant indicating the top row
  4582.                          of the area to be scrolled.  Value checked to be
  4583.                          between 0 and 24 inclusive.
  4584.                
  4585.                left......Numeric variable or constant indicating the left
  4586.                          column of the area to be scrolled.  Value checked to
  4587.                          be between 0 and 79 inclusive.
  4588.                
  4589.                bottom....Numeric variable or constant indicating the ending
  4590.                          row of the area to be scrolled.  Value checked to be
  4591.                          greater than TOP but less than or equal to 24.
  4592.                
  4593.                right.....Numeric variable or constant indicating the right
  4594.                          column of the area to be scrolled.  Value checked to
  4595.                          be greater than LEFT but less than or equal to 79.
  4596.      
  4597.                lines.....Numeric variable or constant indicating the number
  4598.                          of lines or columns to be scrolled, or zero (0) to
  4599.                          scroll entire window (effectively erasing it).
  4600.                          Value checked to be equal to or less than BOTTOM -
  4601.                          TOP if a vertical scroll or equal to or less than
  4602.                          RIGHT - LEFT if horizontal.  If greater than the
  4603.                          number of available lines or columns within the
  4604.                          specified area zero (0) will be assumed.
  4605.      
  4606.                dir.......Character string variable or constant, non case
  4607.                          sensitive, indicating the direction of the scroll
  4608.                          ('u' = Up, 'd' = Down, 'l' = Left, 'r' = Right).
  4609.      
  4610.  
  4611.  
  4612.  
  4613.  
  4614.  
  4615.  
  4616.                                       Page #56
  4617.                                           
  4618.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4619.                                           
  4620.  
  4621.                                           
  4622.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4623.      ======================================================================
  4624.  
  4625.  
  4626.  
  4627.      VSCROLL (cont'd)
  4628.      
  4629.                attr......OPTIONAL.  Character string variable or constant,
  4630.                          non case sensitive, containing a valid color command
  4631.                          or combination for character and background.  Must
  4632.                          be the alpha representation of the color, the
  4633.                          numeric will be rejected.  The default is the color
  4634.                          attribute currently on the screen for the character
  4635.                          in the TOP, LEFT position.
  4636.      
  4637.                                   (valid colors)
  4638.                          black                         N
  4639.                          blue                          B
  4640.                          green                         G
  4641.                          cyan                          BG
  4642.                          red                           R
  4643.                          magenta                       RB
  4644.                          brown                         GR
  4645.                          white                         W
  4646.                          intense                       +
  4647.                          blink                         *
  4648.      
  4649.      
  4650.      Examples:
  4651.      
  4652.                1.   This will scroll one line down in the area from row #10,
  4653.                     column #20 through row #12, column #60 using an attribute
  4654.                     of black character (n) and white background (w).
  4655.      
  4656.                     .
  4657.                     .
  4658.                     .
  4659.                     vscroll(10,20,12,60,1,'d','n/w')
  4660.                     .
  4661.                     .
  4662.                     .
  4663.      
  4664.                2.   This will scroll one column to the right in the area from
  4665.                     row #05,column #00 through row #20, column #79 using
  4666.                     whatever the attribute of the character at 10,20
  4667.                     currently is.
  4668.      
  4669.                     .
  4670.                     .
  4671.                     .
  4672.                     vscroll(05,00,20,79,1,'r')
  4673.                     .
  4674.                     .
  4675.                     .
  4676.      
  4677.      
  4678.  
  4679.  
  4680.  
  4681.  
  4682.                                       Page #57
  4683.                                           
  4684.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4685.                                           
  4686.  
  4687.                                           
  4688.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4689.      ======================================================================
  4690.  
  4691.  
  4692.  
  4693.      VSCROLL (cont'd)
  4694.      
  4695.      Returns:
  4696.      
  4697.                Nothing.
  4698.      
  4699.      
  4700.      Cautions:
  4701.      
  4702.                None.
  4703.  
  4704.  
  4705.  
  4706.  
  4707.  
  4708.  
  4709.  
  4710.  
  4711.  
  4712.  
  4713.  
  4714.  
  4715.  
  4716.  
  4717.  
  4718.  
  4719.  
  4720.  
  4721.  
  4722.  
  4723.  
  4724.  
  4725.  
  4726.  
  4727.  
  4728.  
  4729.  
  4730.  
  4731.  
  4732.  
  4733.  
  4734.  
  4735.  
  4736.  
  4737.  
  4738.  
  4739.  
  4740.  
  4741.  
  4742.  
  4743.  
  4744.  
  4745.  
  4746.  
  4747.  
  4748.                                       Page #58
  4749.                                           
  4750.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4751.                                           
  4752.  
  4753.                                           
  4754.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4755.      ======================================================================
  4756.  
  4757.  
  4758.  
  4759.      
  4760.      
  4761.                                       WILDAT
  4762.                                       ------
  4763.      
  4764.      
  4765.           The WILDAT function will perform a search of a target string for
  4766.           the first occurrence matching the specified string pattern.  The
  4767.           pattern string may contain the wildcard character (?) indicating a
  4768.           "don't care" for this position within the match.  The function also
  4769.           has the options of ignoring case during the match or altering the
  4770.           offset within the target string for the scan to begin.
  4771.      
  4772.      
  4773.      Format:
  4774.      
  4775.                wildat(pattern, target [,offset] [,case])
  4776.      
  4777.      
  4778.      Parameters:
  4779.      
  4780.                pattern...Character string variable or constant which is the
  4781.                          string to look for in the TARGET string.  The
  4782.                          PATTERN length must be greater than zero, less than
  4783.                          32,767 and shorter than the TARGET length.  The
  4784.                          following are special cases within the pattern.
  4785.      
  4786.                          ? (wildcard)   Indicates to the matching process
  4787.                                         that it should ignore the character
  4788.                                         in this position, but that a
  4789.                                         character will exist in that
  4790.                                         position.  The PATTERN of "t??" will
  4791.                                         match on all of the following
  4792.                                         examples: "that", "test", "text" and
  4793.                                         "with this".  The last one will match
  4794.                                         because of the .."th t.." matches the
  4795.                                         wildcard pattern.
  4796.      
  4797.                          \ (literal)    Indicates to the matching process
  4798.                                         that it should take the next
  4799.                                         character in the PATTERN literally.
  4800.                                         This may be used when attempting to
  4801.                                         match on the wildcard character
  4802.                                         itself.  For instance, a pattern of
  4803.                                         "\?" will match in the phrase "Do you
  4804.                                         understand?" when the question mark
  4805.                                         is encountered.  To match on the
  4806.                                         backslash character (\) itself, just
  4807.                                         precede it with a literal flag (eg.
  4808.                                         "\\").
  4809.  
  4810.  
  4811.  
  4812.  
  4813.  
  4814.                                       Page #59
  4815.                                           
  4816.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4817.                                           
  4818.  
  4819.                                           
  4820.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4821.      ======================================================================
  4822.  
  4823.  
  4824.  
  4825.      WILDAT (cont'd)
  4826.      
  4827.                target....Character string variable or constant which is the
  4828.                          string to search for the occurrence of PATTERN.  The
  4829.                          TARGET length must be greater than zero, equal to or
  4830.                          less than 32,767 and greater than the PATTERN
  4831.                          length.
  4832.      
  4833.                offset....OPTIONAL.  Numeric variable or constant which is the
  4834.                          offset within the TARGET for the search to begin.
  4835.                          The default is no offset so searching will start at
  4836.                          the first character in the TARGET.  The first
  4837.                          character in the TARGET is at offset zero (0) so all
  4838.                          offsets are the actual character position in the
  4839.                          string minus one.  Think of the offset as telling
  4840.                          the function to "ignore this many characters before
  4841.                          beginning the search."  The length of the PATTERN
  4842.                          string plus this OFFSET must not exceed the length
  4843.                          of the TARGET string.
  4844.      
  4845.                case......OPTIONAL.  Logical variable or constant which
  4846.                          instructs the function to ignore case during the
  4847.                          search.
  4848.                
  4849.                          .T.            DEFAULT.  Forces the matching process
  4850.                                         to adhere to case matching.
  4851.                
  4852.                          .F.            Setting this flag to false (.F.)
  4853.                                         instructs the function to ignore case
  4854.                                         matching.  Therefore, "The" and "the"
  4855.                                         will be considered identical for
  4856.                                         matching purposes.
  4857.      
  4858.      
  4859.  
  4860.  
  4861.  
  4862.  
  4863.  
  4864.  
  4865.  
  4866.  
  4867.  
  4868.  
  4869.  
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.  
  4879.  
  4880.                                       Page #60
  4881.                                           
  4882.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4883.                                           
  4884.  
  4885.                                           
  4886.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4887.      ======================================================================
  4888.  
  4889.  
  4890.  
  4891.      WILDAT (cont'd)
  4892.      
  4893.      Examples:
  4894.      
  4895.                1.   Search the TARGET text and return the position of every
  4896.                     occurrence of the word "the" and ignore case matching.
  4897.                     The function will find two occurrences, one at position
  4898.                     #01 and the other at position #33.
  4899.      
  4900.                     .
  4901.                     .
  4902.                     .
  4903.                     target = 'The quick brown fox jumped over the lazy dog.'
  4904.                     offset = 0
  4905.                     do while .T.
  4906.                          offset = WILDAT('the', target, offset, .f.)
  4907.                          if offset < 1
  4908.                               exit
  4909.                          endif
  4910.                          (do something)
  4911.                     enddo
  4912.                     .
  4913.                     .
  4914.                     .
  4915.                     
  4916.                     The quick brown fox jumped over the lazy dog
  4917.                     ^                               ^
  4918.      
  4919.                2.   Search the TARGET text and return the position of every
  4920.                     occurrence of the pattern "t??t" and enforce case
  4921.                     matching.  The function will find four occurrences, at
  4922.                     positions #16, #25, #32 and #35.
  4923.      
  4924.                     .
  4925.                     .
  4926.                     .
  4927.                     pattern = 't??t'
  4928.                     target = 'That guy gives tests on text with that book.'
  4929.                     offset = 0
  4930.                     do while .T.
  4931.                          offset = WILDAT(pattern, target, offset)
  4932.                          if offset < 1
  4933.                               exit
  4934.                          endif
  4935.                          (do something)
  4936.                     enddo
  4937.                     .
  4938.                     .
  4939.                     
  4940.                     That guy gives tests on text with that book.
  4941.                                    ^        ^      ^  ^
  4942.  
  4943.  
  4944.  
  4945.  
  4946.                                       Page #61
  4947.                                           
  4948.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  4949.                                           
  4950.  
  4951.                                           
  4952.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  4953.      ======================================================================
  4954.  
  4955.  
  4956.  
  4957.      WILDAT (cont'd)
  4958.      
  4959.                3.   Search the TARGET text and return the position of every
  4960.                     question mark (?).  As this is the wildcard character
  4961.                     remember we must use the literal (\) expression.  The
  4962.                     function will find two occurrences, one at position #13
  4963.                     and the other at position #24.
  4964.      
  4965.                     .
  4966.                     .
  4967.                     .
  4968.                     pattern = '\?'
  4969.                     target = 'Did you know?  Does she?'
  4970.                     offset = 0
  4971.                     do while .T.
  4972.                          offset = WILDAT(pattern, target, offset)
  4973.                          if offset < 1
  4974.                               exit
  4975.                          endif
  4976.                          (do something)
  4977.                     enddo
  4978.                     .
  4979.                     .
  4980.                     .
  4981.                     
  4982.                     Did you know?  Does she?
  4983.                                 ^          ^
  4984.      
  4985.      
  4986.      Returns:
  4987.      
  4988.                memvar....Number variable which, if greater than zero,
  4989.                          indicates the position within the TARGET where the
  4990.                          PATTERN was found.  This position is relative to the
  4991.                          start of the TARGET not the start of the
  4992.                          TARGET+OFFSET.  If zero then no match was found.  If
  4993.                          less than zero then an error in one of the
  4994.                          parameters prevented the search from beginning.
  4995.      
  4996.      
  4997.      Cautions:
  4998.      
  4999.                None.
  5000.  
  5001.  
  5002.  
  5003.  
  5004.  
  5005.  
  5006.  
  5007.  
  5008.  
  5009.  
  5010.  
  5011.  
  5012.                                       Page #62
  5013.                                           
  5014.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  5015.                                           
  5016.  
  5017.                                           
  5018.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  5019.      ======================================================================
  5020.  
  5021.  
  5022.  
  5023.      
  5024.                                      WILDRAT
  5025.                                      -------
  5026.      
  5027.      
  5028.           The WILDRAT function will perform a search of a target string for
  5029.           the first occurrence matching another string pattern but in a right
  5030.           to left type search.  The target string is searched in a right to
  5031.           left manner looking for the first occurrence of the pattern string.
  5032.           The pattern string may contain the wildcard character (?)
  5033.           indicating a "don't care" for this position within the match.  The
  5034.           function also has the options of ignoring case during the match or
  5035.           altering the offset within the target string for the scan to begin.
  5036.      
  5037.      
  5038.      Format:
  5039.      
  5040.                WILDRAT(pattern, target [,offset] [,case])
  5041.      
  5042.      
  5043.      Parameters:
  5044.      
  5045.                pattern...Character string variable or constant which is the
  5046.                          string to look for in the TARGET string.  The
  5047.                          PATTERN length must be greater than zero, less that
  5048.                          32,767 and shorter than the TARGET length.  The
  5049.                          following are special cases within the pattern.
  5050.      
  5051.                          ? (wildcard)   Indicates to the matching process
  5052.                                         that it should ignore the character
  5053.                                         in this position, but that a
  5054.                                         character will exist in that
  5055.                                         position.  The PATTERN of "t??" will
  5056.                                         match on all of the following
  5057.                                         examples: "that", "test", "text" and
  5058.                                         "with this".  The last one will match
  5059.                                         because of the .."th t.." matches the
  5060.                                         wildcard pattern.
  5061.      
  5062.                          \ (literal)    Indicates to the matching process
  5063.                                         that it should take the next
  5064.                                         character in the PATTERN literally.
  5065.                                         This may be used when attempting to
  5066.                                         match on the wildcard character
  5067.                                         itself.  For instance, a pattern of
  5068.                                         "\?" will match in the phrase "Do you
  5069.                                         understand?" when the question mark
  5070.                                         is encountered.  To match on the
  5071.                                         backslash character (\) itself, just
  5072.                                         precede it with a literal flag (eg.
  5073.                                         "\\").
  5074.  
  5075.  
  5076.  
  5077.  
  5078.                                       Page #63
  5079.                                           
  5080.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  5081.                                           
  5082.  
  5083.                                           
  5084.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  5085.      ======================================================================
  5086.  
  5087.  
  5088.  
  5089.      WILDRAT (cont'd)
  5090.      
  5091.                target....Character string variable or constant which is the
  5092.                          string to search for the occurrence of PATTERN.  The
  5093.                          TARGET length must be greater than zero, equal to or
  5094.                          less than 32,767 and greater than the PATTERN
  5095.                          length.
  5096.      
  5097.                offset....OPTIONAL.  Numeric variable or constant which is the
  5098.                          offset within the TARGET for the search to begin.
  5099.                          The default is no offset so searching will start at
  5100.                          the last character in the TARGET.  The last
  5101.                          character in the TARGET is at offset zero (0) so all
  5102.                          offsets are the actual character position in the
  5103.                          string minus one.  Think of the offset as telling
  5104.                          the function to "ignore this many characters before
  5105.                          beginning the search."  The length of the PATTERN
  5106.                          string plus this OFFSET must not exceed the length
  5107.                          of the TARGET string.
  5108.      
  5109.                case......OPTIONAL.  Logical variable or constant which
  5110.                          instructs the function to ignore case during the
  5111.                          search.
  5112.                
  5113.                          .T.            DEFAULT.  Forces the matching process
  5114.                                         to adhere to case matching.
  5115.                
  5116.                          .F.            Setting this flag to false (.F.)
  5117.                                         instructs the function to ignore case
  5118.                                         matching.  Therefore, "The" and "the"
  5119.                                         will be considered identical for
  5120.                                         matching purposes.
  5121.      
  5122.      
  5123.  
  5124.  
  5125.  
  5126.  
  5127.  
  5128.  
  5129.  
  5130.  
  5131.  
  5132.  
  5133.  
  5134.  
  5135.  
  5136.  
  5137.  
  5138.  
  5139.  
  5140.  
  5141.  
  5142.  
  5143.  
  5144.                                       Page #64
  5145.                                           
  5146.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  5147.                                           
  5148.  
  5149.                                           
  5150.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  5151.      ======================================================================
  5152.  
  5153.  
  5154.  
  5155.      WILDRAT (cont'd)
  5156.      
  5157.      Examples:
  5158.      
  5159.                1.   Search the TARGET text and return the position of every
  5160.                     occurrence of the word "the" and ignore case matching.
  5161.                     The function will find two occurrences, one at position
  5162.                     #13 and the other at position #45.
  5163.      
  5164.                     .
  5165.                     .
  5166.                     .
  5167.                     target = 'The quick brown fox jumped over the lazy dog.'
  5168.                     offset = 0
  5169.                     do while .T.
  5170.                          offset = WILDRAT('the', target, offset, .f.)
  5171.                          if offset < 1
  5172.                               exit
  5173.                          endif
  5174.                          (do something)
  5175.                     enddo
  5176.                     .
  5177.                     .
  5178.                     .
  5179.                     
  5180.                     The quick brown fox jumped over the lazy dog
  5181.                     ^                               ^
  5182.      
  5183.                2.   Search the TARGET text and return the position of every
  5184.                     occurrence of the pattern "t??t" and enforce case
  5185.                     matching.  The function will find four occurrences, at
  5186.                     positions #10, #13, #20 and #29.
  5187.      
  5188.                     .
  5189.                     .
  5190.                     .
  5191.                     pattern = 't??t'
  5192.                     target = 'That guy gives tests on text with that book.'
  5193.                     offset = 0
  5194.                     do while .T.
  5195.                          offset = WILDRAT(pattern, target, offset)
  5196.                          if offset < 1
  5197.                               exit
  5198.                          endif
  5199.                          (do something)
  5200.                     enddo
  5201.                     .
  5202.                     .
  5203.                     
  5204.                     That guy gives tests on text with that book.
  5205.                                    ^        ^      ^  ^
  5206.  
  5207.  
  5208.  
  5209.  
  5210.                                       Page #65
  5211.                                           
  5212.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  5213.                                           
  5214.  
  5215.                                           
  5216.      PROCLIP2.LIB 2.00 User Documentation                 February 15, 1988
  5217.      ======================================================================
  5218.  
  5219.  
  5220.  
  5221.      WILDRAT (cont'd)
  5222.      
  5223.                3.   Search the TARGET text and return the position of every
  5224.                     question mark (?).  As this is the wildcard character
  5225.                     remember we must use the literal (\) expression.  The
  5226.                     function will find two occurrences, one at position #01
  5227.                     and the other at position #12.
  5228.      
  5229.                     .
  5230.                     .
  5231.                     .
  5232.                     pattern = '\?'
  5233.                     target = 'Did you know?  Does she?'
  5234.                     offset = 0
  5235.                     do while .T.
  5236.                          offset = WILDRAT(pattern, target, offset)
  5237.                          if offset < 1
  5238.                               exit
  5239.                          endif
  5240.                          (do something)
  5241.                     enddo
  5242.                     .
  5243.                     .
  5244.                     .
  5245.                     
  5246.                     Did you know?  Does she?
  5247.                                 ^          ^
  5248.      
  5249.      
  5250.      Returns:
  5251.      
  5252.                memvar....Number variable which, if greater than zero,
  5253.                          indicates the position within the TARGET where the
  5254.                          PATTERN was found.  This position is relative to the
  5255.                          end of the TARGET not the end of the TARGET+OFFSET.
  5256.                          If zero then no match was found.  If less than zero
  5257.                          then an error in one of the parameters prevented the
  5258.                          search from beginning.
  5259.      
  5260.      
  5261.      Cautions:
  5262.      
  5263.                None.
  5264.  
  5265.  
  5266.  
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.  
  5275.  
  5276.                                       Page #66
  5277.                                           
  5278.           Copyright (c) 1985-88 by Jason R. Matthews - All Rights Reserved
  5279.                                           
  5280.  
  5281.