BLINKER Programming Functions
------------------------------------------------------------------------------
  Overview

  Blinker features a number of functions which provide the program
  developer with increased control over the runtime overlay environment
  and additional profiling and debugging information.

  These functions may be used to fine tune an existing program by
  monitoring and recording its performance in both memory usage and speed
  while it is executing. They may also be used while developing a new
  program to ensure that the design and implementation decisions being
  made are not adversely affecting program performance.

  All the functions which produce output take a file handle as an optional
  parameter, and all output from the function will be sent to that file
  handle. The handle is not validated, and should be either 1, to send
  output to the screen, 2 to send output to the standard error device, 4
  to send output to the printer, or the handle of a file opened by the
  program.

  The default handle may be set at link time using the BLINKER DEBUG
  HANDLE command or in the program using the Debug Handle function
  (BLIDBGHAN()) detailed below. If no handle is specified then the output
  is sent to DOS file handle 1 (the screen).

  Many of the Clipper specific functions relating to profiling and
  debugging are only enabled when the BLINKER CLIPPER PROFILE ON command
  is specified at link time. (See Chapter 6 for further information on
  this command.) The functions affected by this command are: BLICURCAL(),
  BLICURDSK(), BLICURNME(), BLIDBGHAN(), BLIDISSTS(), BLIDISTRC(),
  BLIPRFMOD(), BLITOTCAL() and BLITOTDSK().

  Each function is described here with the effect that it will have on the
  run time overlay environment, an example of how to use it, and a
  description of when it may be used (if there are any restrictions).

  Blinker functions called from BASIC which receive string parameters or
  return string values have a different function name - the letters 'BAS'
  are appended to the name. For example, the BASIC version of BLIDEMDTE()
  is called BLIDEMDTEBAS()



  Naming Conventions

  Assembler programmers note: when calling from assembler you should
  prepend an underbar character to the function names in order to comply
  with C naming conventions.

  BASIC programmers note: when calling any of the Blinker functions which
  pass or return string values, append the suffix 'BAS' to the normal nine
  character function name.

  Notational Conventions

  Many of the functions provided by Blinker can be accessed from several
  languages, using the standard C calling conventions.

  Blinker provides specific interfaces for the C language, Microsoft Basic
  PDS & QuickBasic, and for Clipper Summer '87 and 5.01. If you are using
  a language not mentioned here, it is likely that your compiler can be
  directed to use the C calling convention to access Blinker functions.
  Consult your compiler documentation for further information on mixed
  language programming.

  The tables on the following pages detail the notational convention used
  to describe the types of parameters and return values, and the
  appropriate data types for each calling convention.

  Each parameter, (or return value) is preceded by a two letter prefix
  denoting the type of the value, which also implies the way the parameter
  is passed to the function.

  Parameter type conventions
  The following tables show the data types used as parameters and return
  values from all Blinker functions. The prefixes have the following
  meanings:

  ni  numeric signed integer      (signed word)
  nu  numeric unsigned integer    (unsigned word)
  nl  numeric long integer        (signed dword)
  c   character string            (byte)
  l   logical (boolean)           (word)

  For each language listed in the table (Clipper, Basic, and C) the
  language declaration for each type is given (no type declaration is
  needed in the Clipper language, but the passed parameters must be of the
  correct type).

  Logical (or boolean) values are only directly supported for Clipper. All
  other languages should use the numeric integer type, passing a zero
  value to indicate false, and a non zero value to indicate true. Return
  values from the functions use the same convention.

  For languages not listed, use the data types which match the C types.

  Calling conventions
  The Blinker functions are provided with Clipper, BASIC and C interfaces.

  The Clipper interface uses the Nantucket extend system, and requires no
  special treatment as far as the Clipper programmer is concerned.

  The BASIC interface is identical to the C interface for simple data
  types, but strings require special treatment. For this reason, any of
  the Blinker functions which pass or return string values have the suffix
  'BAS' appended to the normal function name.

  The C interface uses the following calling conventions:

      o   Simple data types are passed on the stack
      o   Strings are passed by far reference
      o   Parameters are passed in reverse order, ie the last
          parameter is pushed onto the stack first.

  which are the same as standard C calling conventions. Languages for
  which no interface is provided should use the C interface.