WORKING WITH CLIPPER TOOLS ONE

  Installation
  Clipper Tools One is supplied in the form of a library, CT1.LIB, and a
  separate object module,CTOOLD87.DAT.  Copy these two files into your work
  directory using the DOS COPY command.  It is assumed that you are using a
  computer with a hard disk.  Store the original disks in a safe place once
  you have made a back-up copy.  Never work with the original disk.

  Programming with the Tools
  Clipper Tools One is a collection of functions that can be used like any
  other Clipper function once you have included CT1.LIB and CTOOLD87.DAT
  in the link process.

  All the rules of Clipper apply to these functions.  This means, for example,
  that it is not necessary to assign the return value of the function.

        FUNCTION(par1,par2,..)
     or
        A = FUNCTION(par1,par2,..)

  As in Clipper, it is not possible to leave out an argument with the syntax
  FUNCTION(par1,par2).

  Linking
  When linking, it is possible to use the PLINK86-Plus linker or the Micro-
  soft Linker (frequently referred to as the DOS Linker).

  Example of how to use the PLINK86-Plus:

     PLINK86 FILE Prog1,Prog2,CTOOLSD87 LIB CLIPPER,CT1

  Example of how to use the Microsoft Linker:

     LINK Prog1+Prog2+CTOOLSD87,,,CLIPPER,CT1

  The object files and libraries must also be included in the interactive
  mode of PLINK86-Plus and in .LNK files.



POSSIBLE PROBLEMS WHEN LINKING

  If one of your own procedures or functions has the same name as one of the
  functions in Clipper Tools One, you will get a duplicate symbol error mess-
  age from the linker, or you will not be able to use the function in CT1.LIB.
  This is because object files always override a module with the same name as
  one contained in a library file.  For example, CTOOLD87.DAT overrides the
  standard screen and keyboard module in CLIPPER.LIB.

  Also if two libraries contain functions with the same name, the linker will
  use the function from the first library on the linker command line contain-
  ing the called function.



OVERLAY APPLICATIONS

  In general, it is not possible to place functions from Clipper Tool One in
  overlays because many of the functions include interrupt service routines.
  These may not be included in an overlay under any circumstances.
  The expanded driver, CTOOLDS87.OBJ, should not be placed in an overlay
  either.  Placing the expanded driver in an overlay will cause the system
  to crash.


EXPANDED DRIVER

  Clipper Tools One includes an object module (.OBJ file) named CTOOLD87.DAT.
  This replaces the standard IBM PC screen and keyboard driver found in
  CLIPPER.LIB.  It is needed when using the window functions and provides some
  other important enhancements.  We recommend that you use this alternate
  driver so that all interrupt vectors are automatically saved when your
  application loads and restored upon returning to DOS.  This will prevent
  a system crash if one of the functions changes the vector expected by an
  application executed after yours.  All the serial port functions, KEYTIME(),
  KEYSEC() and SHOWTIME() change interrupt vectors.  Place CTOOLD87.DAT in the
  list of files to be linked to override the standard driver module.
  See the "Expanded Driver" chapter for further information.


SUPPLEMENTARY PROGRAMS - INTSAVE and INTOFF:

  Two additional programs have been supplied for cases where Clipper Tools
  One functions operating with interrupts have not been correctly uninstalled
  or where the expanded driver could not be used.

  INTSAVE.EXE stores all 256 interrupt vectors in a file named INTSAVE.TAB.
  Vectors can be saved to there previous state by passing "/R" to INTSAVE.EXE
  on the DOS command line.

  INTSAVE.EXE  may be used in three different ways:

     C:INTSAVE

  Saves all interrupt vectors to a file named INTSAVE.TAB if it does not
  already exist, vectors are restored from this file.

     C:INTSAVE /S

  Always saves the current interrupt vectors.  Any existing INSAVE.TAB file
  will be overwritten.

     C:INTSAVE /R

  Restores the interrupt vectors with the contents of INTSAVE.TAB (the file
  will not be erased in this instance).


  The second program, INTOFF.EXE, will set the following vectors to harmless
  IRET addresses.

  Vectors used by the communications functions:
        0Bh for COM1
        0Ch for COM2

  Vector used by KEYSEC() and SHOWTIME() for the timer tick:
        1Ch

  Vector used by the alarm in KEYTIME():
        4Ah

  These two programs that are useful in restoring the DOS environment may
  also be used in conjunction with other programs.


PASSING PARAMETERS BY REFERENCE

  Clipper normally passes character arguments by value to user defined
  functions.  Character arguments may be passed by reference, however,
  by preceding them with the at sign (@).  Pointers to the actual value
  in memory are passed to the function rather than creating a copy of the
  value in another memory location.  Changing the value within the function
  will change the original parameter.

  Passing parameters by reference uses less memory and takes less processing
  time.  Runtime errors that occur because of insufficient memory to make a
  copy of the string parameter can sometimes be avoided by passing arguments
  by reference.  However, it is often important that the original string
  remain unchanged.  The following example passes the address of the string
  to MYFUNC.

  memvar = "Hello"
  MYFUNC(@memvar)

  The traditional method of passing the value and assigning the new value to
  the original memory variable:

  memvar = "Hello"
  memvar = MYFUNC(memvar)

  You cannot change the length of a string passed by reference.