   Using TopSpeed C Standard Library Functions in Clarion Database Developer
==============================================================================

This document is a guide to using the TopSpeed C standard library functions
within Clarion Database Developer applications.  Most of these functions are
already being used internally by Clarion language statements.  Therefore,
there is no excess "overhead" involved in their use in your applications.

This document directly covers only those standard C library functions which
should prove most useful to a Clarion programmer.  However, the fundamental
principles of creating a Clarion prototype for any C function are also
discussed.  Therefore, any other standard C library function (documented in
the TopSpeed C Library Reference) is also available for use.

The C library functions covered in this document fall into four categories: 
File Management, Mathematical, Mouse Control, and Miscellaneous functions. 
The prototypes for all these functions are provided on this disk in the
C_LIB.INC file.

These standard library functions may also be referenced by any C, Pascal, or
Modula-2 code linked into a Clarion program.  The function prototypes for
these languages are contained in files which come with the appropriate
TopSpeed compiler.


Prototyping C Functions in Clarion
==================================

The only thing necessary to be able to use any of the C standard library
functions in Clarion code is the addition of the function's Clarion language
prototype to the Clarion application's MAP structure.  The Clarion prototype
tells the compiler and linker what type of parameters are passed and what
return data type (if any) to expect from the C function.  The "FUNCTION and
PROCEDURE Prototypes" section in Chapter 2 of Clarion's Language Reference
discusses the syntax and attributes required to create a prototype of a
Clarion procedure or function.  This same syntax is used to create Clarion
prototypes of C functions.

There are four major issues involved in creating a prototype for a C function:
calling convention, naming convention, parameter passing, and return data
types from functions.

The calling convention for all the TopSpeed C standard library functions is
the same register-based calling convention used by Clarion.  Therefore, there
is no need to use the C or PASCAL attributes in any standard C library
function's Clarion prototype.

The TopSpeed C compiler's naming convention is the normal C convention.  This
means an underscore is automatically prepended to the function name when
compiled.  The Clarion NAME attribute is usually used in the prototype to give
the linker the correct reference to a C function without requiring the Clarion
code to use the prepended underscore.  For example, the C function "access" is
actually named "_access" by the compiler.  Therefore, the NAME('_access')
attribute is required in the prototype (unless you want to refer to the
function in Clarion code as "_access").

Each parameter passed to a C function must appear in its Clarion prototype as
the data type of the passed parameter.  Parameters are passed in Clarion
either "by value" or "by address."

When a parameter is passed "by value," a copy of the data is received by the
function.  The passed parameter is represented in the prototype as the data
type of the parameter.  When passed "by address," the memory address of the
data is received by the function.  The parameter is represented in the
prototype as the data type of the parameter with a prepended asterisk (*). 
This corresponds to passing the C function the pointer to the data.

Parameter data type translation is the "key" to prototyping C functions in
Clarion.  The following is a table of C data types and the Clarion data type
which should be used in the prototype:

            C Data Type       Clarion Data Type
            -----------       -----------------
            char                    BYTE (gets linker warnings - ignore them)
            unsigned char           BYTE
            int                     SHORT
            unsigned int            USHORT
            short                   SHORT
            unsigned short          USHORT
            long                    LONG
            unsigned long           ULONG
            float                   SREAL
            double                  REAL
            unsigned char *         *BYTE
            int *                   *SHORT
            unsigned int *          *USHORT
            short *                 *SHORT
            unsigned short *        *USHORT
            long *                  *LONG
            unsigned long *         *ULONG
            float *                 *SREAL
            double *                *REAL
            char *                  *CSTRING w/ RAW attribute
            struct *                *STRING w/ RAW attribute

Since the Clarion language does not have a signed BYTE data type, linker
warnings ('type inconsistency') will result when you prototype a function
which receives a char parameter.  As long as you are aware that the C function
is expecting a signed value, and correctly adjust the BYTE field's bitmap to
pass a value in the range -128 to 127, this warning may be safely ignored.

The RAW attribute must be used when a C function expects to receive the
address of a CSTRING or GROUP parameter.  By default, Clarion STRING, CSTRING,
PSTRING, and GROUP parameters are passed (internally) to other Clarion
procedures and functions as both the address and length of the string.  C
functions do not usually want or need the length, and expect to receive only
the address of the data.  Therefore, the RAW attribute overrides this default.

If the C function returns void, there is no data returned and the function
fits the definition of a Clarion PROCEDURE.  If the C function does return
data, it is prototyped as the actual data type returned and the function fits
the definition of a Clarion FUNCTION.  Clarion PROCEDUREs must be called as a
separate statement, while FUNCTIONs must be called as part of a condition,
assignment, or parameter list.

Return data types from C functions are almost the same as passed parameters:

            C Return Type     Clarion Return Type
            -----------       -----------------
            char                    BYTE (gets linker warnings - ignore them)
            unsigned char           BYTE
            int                     SHORT
            unsigned int            USHORT
            short                   SHORT
            unsigned short          USHORT
            long                    LONG
            unsigned long           ULONG
            float                   SREAL
            double                  REAL
            unsigned char *         ULONG (gets linker warnings - ignore them)
            int *                   ULONG (gets linker warnings - ignore them)
            unsigned int *          ULONG (gets linker warnings - ignore them)
            short *                 ULONG (gets linker warnings - ignore them)
            unsigned short *        ULONG (gets linker warnings - ignore them)
            long *                  ULONG (gets linker warnings - ignore them)
            unsigned long *         ULONG (gets linker warnings - ignore them)
            float *                 ULONG (gets linker warnings - ignore them)
            double *                ULONG (gets linker warnings - ignore them)
            char *                  *CSTRING
            struct *                ULONG (gets linker warnings - ignore them)

Notice that the Clarion return data type listed for any function which returns
a pointer to anything other than a CSTRING is a ULONG.  This will generate a
"type inconsistency" linker warning when prototyped in Clarion.  This occurs
because Clarion does not have a data type for a pointer, since the Clarion
language does not use pointers.  The ULONG, being a four-byte integer, is the
normal replacement for a pointer return type.  These warnings are not a
problem and can be safely ignored.


File Management Functions
=========================

The following functions provide additional file management functionality. 
Some of these functions post errors in a global memory variable "errno."   If
the value in the "errno" variable must be checked, it should be declared in
the Clarion program as:

      ErrNo       SHORT,NAME('_errno'),EXTERNAL

This declaration indicates to the Clarion compiler the C global variable name
(the NAME attribute) and that it has been already allocated memory (the
EXTERNAL attribute).  It may then be accessed in the Clarion code as "ErrNo"
(the capitalization is for readability only, Clarion is a case-insensitive
language).

------------------------------------------------------------------------------

Access      FUNCTION

  C prototype:
      int access(const char *path, int mode);
  Clarion prototype:
      Access(*CSTRING,SHORT),SHORT,RAW,NAME('_access')

This function checks whether the file (or directory) specified by the path
parameter exists, and (if not a directory) whether it can be accessed in the
specified mode.

      path        Specifies the file to check.

      mode        Specifies the access mode to test.
                  Mode values:
                        0  -- Check for existence only
                        2  -- Check for Write permission
                        4  -- Check for Read permission
                        6  -- Check for Read and Write permission

      Return Value:
            Returns zero (0) if the file exists and the access has the
            specified mode.  Returns negative one (-1) if the file does not
            exist (ErrNo = 2: file not found) or the specified access is not
            available (ErrNo = 5: access denied).

------------------------------------------------------------------------------

RemoveFile  FUNCTION

  C prototype:
      int remove(const char *path);
  Clarion prototype:
      RemoveFile(*CSTRING),SHORT,RAW,NAME('_remove')

This function deletes the file specified by the path parameter.  The Clarion
prototype has changed the function's name to RemoveFile to avoid conflict with
the Clarion language REMOVE statement.

      path        Specifies the file to delete.

      Return Value:
            Returns zero (0) if the file was successfully deleted.  Returns
            negative one (-1) if an error occurred -- the file does not exist
            (ErrNo = 2: file not found) or the file is read-only (ErrNo = 5:
            access denied).

------------------------------------------------------------------------------

RenameFile  FUNCTION

  C prototype:
      int rename(const char *oldname, const char *newname);
  Clarion prototype:
      RenameFile(*CSTRING,*CSTRING),SHORT,RAW,NAME('_rename')

This function changes the name of the file or directory specified by the
oldname parameter.  The Clarion prototype has changed the function's name to
RenameFile to avoid conflict with the Clarion language RENAME statement.

      oldname     Specifies the file (or directory) to rename.

      newname     Specifies the new name.

      Return Value:
            Returns zero (0) if the file was successfully renamed.  Returns
            negative one (-1) if an error occurred -- the old file does not
            exist (ErrNo = 2: file not found), or the new filename already
            exists (ErrNo = 5: access denied), or an attempt is made to rename
            a file to a different device (ErrNo = 17: not same device).

------------------------------------------------------------------------------

FindFirst   FUNCTION

  C prototype:
      int findfirst(const char *path, struct ffblk *buffer, int attrib);
  Clarion prototype:
      FindFirst(*CSTRING,*STRING,SHORT),SHORT,RAW,NAME('_findfirst')

This function searches a directory for the first file meeting the criteria
specified by the path parameter (which may include wildcards).  Information
about the file is placed in the buffer parameter structure.

      path        Specifies the files to search for.  This may include the DOS
                  wildcard characters, asterisk (*) and question (?).

      buffer      Specifies a structure which contains information about the
                  file (name, size, attributes, etc.).  The ffblk structure is
                  defined as:

                  C structure:                  Clarion Structure:
                  ------------                  ------------------
                  struct ffblk {                FileInfo      GROUP
                    char ff_reserved[21];                       BYTE,DIM(21)
                    char ff_attrib;             Attributes      BYTE
                    int  ff_ftime;              TimeStamp       SHORT
                    int  ff_fdate;              DateStamp       SHORT
                    long ff_fsize;              Filesize        LONG
                    char ff_fname[13];          FileName        CSTRING(13)
                  };                                          END

      attrib      Specifies the attributes which the file being sought must
                  have to meet the search criteria.  This can have the
                  following values:

                        C values    Clarion     Description
                        -------     -------     -----------
                         0x00        00h         normal file 
                         0x01        01h         Read only attribute 
                         0x02        02h         Hidden file 
                         0x04        04h         System file 
                         0x08        08h         Volume label 
                         0x10        10h         Directory 
                         0x20        20h         Archive 

      Return Value:
            Returns zero (0) if a file was successfully found meeting the
            search criteria (path and attrib).  Returns negative one (-1) if
            an error occurred -- a file meeting the criteria does not exist
            (ErrNo = 2: file not found).

------------------------------------------------------------------------------

FindNext    FUNCTION

  C prototype:
      int findnext(struct ffblk *buffer);
  Clarion prototype:
      FindNext(*STRING),SHORT,RAW,NAME('_findnext')

This function searches a directory for subsequent files meeting the criteria
specified by a call to the FindFirst function.  FindNext must be passed the
same buffer parameter as was passed to the FindFirst function.  Information
about each file found is placed in the buffer parameter structure after each
call to FindNext.

      buffer      Specifies a structure which contains information about the
                  file (name, size, attributes, etc.).  The ffblk structure is
                  defined as:

                  C structure:                  Clarion Structure:
                  ------------                  ------------------
                  struct ffblk {                FileInfo      GROUP
                    char ff_reserved[21];                       BYTE,DIM(21)
                    char ff_attrib;             Attributes      BYTE
                    int  ff_ftime;              TimeStamp       SHORT
                    int  ff_fdate;              DateStamp       SHORT
                    long ff_fsize;              Filesize        LONG
                    char ff_fname[13];          FileName        CSTRING(13)
                  };                                          END

      Return Value:
            Returns zero (0) if a file was successfully found meeting the
            search criteria specified by a previous Find First.  Returns
            negative one (-1) if an error occurred -- no more files meeting
            the criteria (ErrNo = 18: no more files).

------------------------------------------------------------------------------

DosGetFileAttr    FUNCTION

  C prototype:
      unsigned _dos_getfileattr(const char *path, unsigned *attrib);
  Clarion prototype:
      DosGetFileAttr(*CSTRING,*USHORT),USHORT,RAW,NAME('__dos_getfileattr')

This function uses service 43H to get information about the file specified in
the path parameter.  The information is placed in the attrib parameter.

      path        Specifies the file or directory whose information is
                  requested.

      attrib      Receives the information about the file or directory in its
                  low-order byte.  This can contain the following values:

                        C values    Clarion     Description
                        -------     -------     -----------
                         0x00        00h         normal file 
                         0x01        01h         Read only attribute 
                         0x02        02h         Hidden file 
                         0x04        04h         System file 
                         0x08        08h         Volume ID file
                         0x10        10h         Sub-Directory 
                         0x20        20h         Archive file

      Return Value:
            Returns zero (0) if a file was successfully found meeting the
            search criteria specified by the path parameter.  Returns a DOS
            error code if an error occurred and sets ErrNo to 2: file not
            found.

------------------------------------------------------------------------------

DosSetFileAttr    FUNCTION

  C prototype:
      unsigned _dos_setfileattr(const char *path, unsigned attrib);
  Clarion prototype:
      DosSetFileAttr(*CSTRING,USHORT),USHORT,RAW,NAME('__dos_setfileattr')

This function uses service 43H to set the attributes of the file specified by
the path parameter.

      path        Specifies the file or directory whose information is
                  requested.

      attrib      Receives the information about the file or directory in its
                  low-order byte.  This can contain the following values:

                        C values    Clarion     Description
                        -------     -------     -----------
                         0x00        00h         normal file 
                         0x01        01h         Read only attribute 
                         0x02        02h         Hidden file 
                         0x04        04h         System file 
                         0x08        08h         Volume ID file
                         0x10        10h         Sub-Directory 
                         0x20        20h         Archive file

      Return Value:
            Returns zero (0) if successful.  Returns a DOS error code if an
            error occurred and sets ErrNo to 2 (file not found) or 5 (access
            denied - because a directory or volume ID was specified).

------------------------------------------------------------------------------

MkDir FUNCTION

  C prototype:
      int mkdir(const char *path);
  Clarion prototype:
      MkDir(*CSTRING),SHORT,RAW,NAME('_mkdir')

This function creates a new directory with the name passed in the path
parameter.  Only the last component of the path can be a new directory.

      path        Specifies the directory to create.

      Return Value:
            Returns zero (0) if the new directory was successfully created. 
            Returns negative one (-1) if an error occurred -- the path does
            not exist (ErrNo = 2: path not found) or the path already exists
            (ErrNo = 5: access denied).

------------------------------------------------------------------------------

RmDir FUNCTION

  C prototype:
      int rmdir(const char *path);
  Clarion prototype:
      RmDir(*CSTRING),SHORT,RAW,NAME('_rmdir')

This function removes the directory specified in the path parameter.  The
directory must be empty and must not be the current ot root directory.

      path        Specifies the directory to remove.

      Return Value:
            Returns zero (0) if the new directory was successfully removed. 
            Returns negative one (-1) if an error occurred -- the path does
            not exist (ErrNo = 2: path not found) or the path is the current
            or root directory (ErrNo = 5: access denied).

------------------------------------------------------------------------------

FnSplit     FUNCTION

  C prototype:
      int fnsplit(
            const char *path, 
            char *drive, 
            char *dir, 
            char *name, 
            char *ext);
  Clarion prototype:
      FnSplit(*CSTRING,*CSTRING,*CSTRING,*CSTRING,*CSTRING),SHORT, |
            RAW,NAME('_fnsplit')

This function breaks a complete path name into its component parts -- drive,
directory, filename, and extension.

      path        Specifies the complete filename to break into component
                  parts.

      drive       Receives the drive portion of the path, which ends with a
                  colon (:).

      dir         Receives the directory portion of the path, including
                  leading and trailing backslashes (\).

      name        Receives the filename portion of the path (without
                  extension).

      ext         Receives the extension portion of the path, including a
                  leading period (.).

      Return Value:

            Returns an integer containiong flags to indicate whether each
            component was present in the complete filename.  The flags are:

                        C values    Clarion     Description
                        -------     -------     -----------
                         0x01        01h        WILDCARDS  
                         0x02        02h        EXTENSION  
                         0x04        04h        FILENAME   
                         0x08        08h        DIRECTORY  
                         0x10        10h        DRIVE      

------------------------------------------------------------------------------

FnMerge     PROCEDURE

  C prototype:
      void fnmerge(
            const char *path, 
            char *drive, 
            char *dir, 
            char *name, 
            char *ext);
  Clarion prototype:
      FnMerge(*CSTRING,*CSTRING,*CSTRING,*CSTRING,*CSTRING), |
            RAW,NAME('_fnmerge')

This function builds a complete path name from its component parts -- drive,
directory, filename, and extension.

      path        Specifies the variable to receive the complete filename.

      drive       Specifies the drive portion of the path, which must end with
                  a colon (:).

      dir         Specifies the directory portion of the path, which must
                  include leading and trailing backslashes (\).

      name        Specifies the filename portion of the path (without
                  extension).

      ext         Specifies the extension portion of the path, which must
                  include a leading period (.).

      Return Value:

            None.  This C function must be used in Clarion code in the same
            manner as a Clarion PROCEDURE.  This means it must be called as a
            separate command statement -- it cannot be used in expressions or
            passed as a parameter.

------------------------------------------------------------------------------

GetVerify   FUNCTION

  C prototype:
      int getverify();
  Clarion prototype:
      GetVerify(),SHORT,NAME('_getverify')

This function returns the current state of the system verify flag.

      Return Value:

            Returns zero (0) if verify is off, and one (1) if it is on.

------------------------------------------------------------------------------

SetVerify   PROCEDURE

  C prototype:
      void getverify(int value);
  Clarion prototype:
      SetVerify(SHORT),NAME('_setverify')

This function sets the system verify flag.  This can be zero (0) for off or
one (1) for on.

      Return Value:

            None.  This C function must be used in Clarion code in the same
            manner as a Clarion PROCEDURE.  This means it must be called as a
            separate command statement -- it cannot be used in expressions or
            passed as a parameter.


Mathematical Functions
======================

The following functions provide additional mathematical functionality.

------------------------------------------------------------------------------

Hypot       FUNCTION

  C prototype:
      double hypot(double x, double y);
  Clarion prototype:
      Hypot(REAL,REAL),REAL,NAME('_hypot')

This function calculates the length of the hypotenuse of its x and y
parameters.

      Return Value:

            The function returns the value of the formula: the square root of
            the sum of the squares of the passed parameters (SQRT(x^2 + y^2)).

------------------------------------------------------------------------------

SinH  FUNCTION

  C prototype:
      double sinh(double x);
  Clarion prototype:
      SinH(REAL),REAL,NAME('_sinh')

This function calculates the hyperbolic sine of the x parameter, in radians.
If x is grater than 2^53, a total loss of significance occurs.

      Return Value:

            The function returns the angle in radians.  If x is too large, the
            value zero (0) is returned and errno is set to 34 (result too
            large).

------------------------------------------------------------------------------

CosH  FUNCTION

  C prototype:
      double cosh(double x);
  Clarion prototype:
      CosH(REAL),REAL,NAME('_cosh')

This function calculates the hyperbolic cosine of the x parameter, in radians.


      Return Value:

            The function returns the angle in radians.  If the result is too
            large, the return value is the largest possible value
            (+1.79769313496231e+308) and errno is set to 34 (result too
            large).

------------------------------------------------------------------------------

TanH  FUNCTION

  C prototype:
      double tanh(double x);
  Clarion prototype:
      TanH(REAL),REAL,NAME('_tanh')

This function calculates the hyperbolic tangent of the x parameter, in
radians. 

      Return Value:

            The function returns the angle in radians.  

------------------------------------------------------------------------------

ATan2       FUNCTION

  C prototype:
      double atan2(double x, double y);
  Clarion prototype:
      ATan2(REAL,REAL),REAL,NAME('_atan2')

This function calculates the arc tangent of y / x.  The quadrant of the return
value is determined by the signs of the two parameters.

      Return Value:

            The function returns the result of dividing the y parameter by the
            x parameter.  If both parameters are zero (0), zero is returned
            and errno is set to 33.

------------------------------------------------------------------------------

Exp   FUNCTION

  C prototype:
      double exp(double x);
  Clarion prototype:
      Exp(REAL),REAL,NAME('_exp')

This function calculates the base number of natural logarithms (e, approx.
2.71828...) raised to the power of the x parameter (e^x).

      Return Value:

            The function returns the result of raising e to the x power.  If
            the result of this is too large, the return value is set to the
            largest possible value (+1.79769313496231e+308) and errno is set
            to 34 (result too large).

------------------------------------------------------------------------------

Poly  FUNCTION

  C prototype:
      double poly(double indep, int degree, double coeff[]);
  Clarion prototype:
      Poly(REAL,SHORT,*REAL[]),REAL,NAME('_poly')

This function generates a polynomial of the specified degree.  

      indep       The value for which the polynomial will be computed.

      degree      The highest power to which indep will be raised.

      coeff       An array to store each of the coefficients of the
                  polynomial.

      Return Value:

            The function returns the value resulting from the evaluation of
            the polynomial.

------------------------------------------------------------------------------

Ceil  FUNCTION

  C prototype:
      double ceil(double x);
  Clarion prototype:
      Ceil(REAL),REAL,NAME('_ceil')

This function rounds the value of the x parameter to the next higher (toward
infinity) integer.

      x     The value to round up.

      Return Value:

            The function returns the result of the rounding.

------------------------------------------------------------------------------

Floor       FUNCTION

  C prototype:
      double floor(double x);
  Clarion prototype:
      Floor(REAL),REAL,NAME('_floor')

This function rounds the value of the x parameter to the next lower (toward
negative infinity) integer.

      x     The value to round down.

      Return Value:

            The function returns the result of the rounding.

------------------------------------------------------------------------------

RotL  FUNCTION

  C prototype:
      unsigned _rotl(unsigned val, int count);
  Clarion prototype:
      RotL(USHORT,SHORT),USHORT,NAME('__rotl')

This function rotates the bits in the unsigned integer passed as the val
parameter left by the number of positions specified by the count parameter. 
Bits which "fall off" the left end are "wrapped around" to the right.

      val         The value to rotate.

      count       The number of bits by which val is rotated.

      Return Value:

            The function returns the rotated value.

------------------------------------------------------------------------------

RotR  FUNCTION

  C prototype:
      unsigned _rotr(unsigned val, int count);
  Clarion prototype:
      RotR(USHORT,SHORT),USHORT,NAME('__rotr')

This function rotates the bits in the unsigned integer passed as the val
parameter right by the number of positions specified by the count parameter. 
Bits which "fall off" the right end are "wrapped around" to the left.

      val         The value to rotate.

      count       The number of bits by which val is rotated.

      Return Value:

            The function returns the rotated value.

------------------------------------------------------------------------------

LRotL       FUNCTION

  C prototype:
      unsigned long _lrotl(long val, int count);
  Clarion prototype:
      LRotL(LONG,SHORT),ULONG,NAME('__lrotl')

This function rotates the bits in the integer passed as the val parameter left
by the number of positions specified by the count parameter.  Bits which "fall
off" the left end are "wrapped around" to the right.

      val         The value to rotate.

      count       The number of bits by which val is rotated.

      Return Value:

            The function returns the rotated value.

------------------------------------------------------------------------------

LRotR       FUNCTION

  C prototype:
      unsigned long _lrotr(long val, int count);
  Clarion prototype:
      LRotR(LONG,SHORT),ULONG,NAME('__lrotr')

This function rotates the bits in the unsigned integer passed as the val
parameter right by the number of positions specified by the count parameter. 
Bits which "fall off" the right end are "wrapped around" to the left.

      val         The value to rotate.

      count       The number of bits by which val is rotated.

      Return Value:

            The function returns the rotated value.

------------------------------------------------------------------------------

FrExp       FUNCTION

  C prototype:
      double frexp(double val, int *exptr);
  Clarion prototype:
      FrExp(REAL,*SHORT),REAL,NAME('_frexp')

This function breaks the floating point value passed by the val parameter into
a mantissa (which is between 0.5 and 1.0) and an exponent.  The exponent is
stored in the variable passed as the exptr parameter.

      val         The floating point value to break up.

      exptr       The variable which receives the exponent.

      Return Value:

            The function returns the mantissa.  If val is zero (0), the
            function returns zero for the mantissa and exponent.

------------------------------------------------------------------------------

LdExp       FUNCTION

  C prototype:
      double ldexp(double x, int exp);
  Clarion prototype:
      LdExp(REAL,SHORT),REAL,NAME('_ldexp')

This function calculates the floating point value of the x parameter multipied
by 2 raised to the power passed as the exp parameter (x*(2^exp)).

      x           Specifies the number being raised to a power.

      exp         Specifies the power of two (2) to which the x parameter is
                  being raised.

      Return Value:

            The function returns (x*(2^exp)).  If the result is too large, the
            return value is the largest possible value
            (+1.79769313496231e+308) and errno is set to 34 (result too
            large).


Micellaneous Functions
======================

The following functions provide miscellaneous additional functionality.

------------------------------------------------------------------------------

Int86X      FUNCTION

  C prototype:
      int int86x(
            int intnum, 
            const union REGS *inregs, 
            union REGS *outregs, 
            struct SREGS *segregs);
  Clarion prototype:
      Int86X(SHORT,*STRING,*STRING,*STRING),SHORT,NAME('_int86x')

This function executes a specified interrupt.  Before calling int86x, the
values required by the interrupt must be stored in the inregs array. 
Similarly, the DS and ES registers in the segregs parameter must be
initialized (if the interrupt requires them).  The Clarion ADDRESS function
can be used to get the segment:offset of any variable in memory, and the
bitwise functions (BSHIFT(), BAND(), BOR(), and BXOR()) may be used to parse
the segment portion of that address.  When the interrupt returns, the int86x
function updates the ES and DS registers in the segregs parameter and restores
DS.  

      intnum      Specifies the interrupt to execute.

      inregs      Contains the register values passed to the interrupt.

      outregs     Contains the register values returned from the interrupt.

      segregs     Contains the segment register values required by the
                  interrupt.

      C structure:                  Clarion Structure:
      ------------                  ------------------
      union REGS {                  Regs          GROUP
        struct WORDREGS {           WordRegs        GROUP
          unsigned int ax,          AX                USHORT
          unsigned int bx,          BX                USHORT
          unsigned int cx,          CX                USHORT
          unsigned int dx,          DX                USHORT
          unsigned int si,          SI                USHORT
          unsigned int di,          DI                USHORT
          unsigned int cflag,       CFlag             USHORT
          unsigned int flags;       Flags             USHORT
        } ;                                         END
        struct BYTEREGS {           ByteRegs          GROUP,OVER(WordRegs)
          unsigned char al,         AL                BYTE
          unsigned char ah,         AH                BYTE
          unsigned char bl,         BL                BYTE
          unsigned char bh,         BH                BYTE
          unsigned char cl,         CL                BYTE
          unsigned char ch,         CH                BYTE
          unsigned char dl,         DL                BYTE
          unsigned char dh;         DH                BYTE
        } ;                                         END
      } ;                                         END

      struct SREGS {                SRegs         GROUP
        unsigned int es,            ES              USHORT
        unsigned int cs,            CS              USHORT
        unsigned int ss,            SS              USHORT
        unsigned int ds,            DS              USHORT
      } ;                                         END

      Return Value:

            The function returns its result as the contents of the AX register
            after the interrupt has returned.  If the cflag member of outregs
            is non-zero (an error has occurred), the error code is stored in
            _doserrno.

Th int86x function may not be used for interrupts 25H and 26H.  In Protected
Mode, the following interrupts are supported:

            INT 10h     BIOS video
            INT 11h     BIOS equipment
            INT 12h     BIOS memory size
            INT 13h     BIOS disk
            INT 14h     BIOS serial port
            INT 16h     BIOS keyboard
            INT 17h     BIOS printer
            INT 1Ah     BIOS clock
            INT 20h     DOS terminate
            INT 21h     DOS function call (some functions not supported)
            INT 33h     Mouse interface

In Protected Mode, the following INT 21h functions are NOT supported:

            0F-17, 21-24, 27-29     FCB-mode file operations
            31                      Terminate but stay resident
            5D                      DOS internal functions
            5E, 5F                  Microsoft Networks functions
            63                      Unused
            IOCTL 44, 0Ch           Generic character device request
            IOCTL 44, 0Dh           Generic block device request

------------------------------------------------------------------------------

Country     FUNCTION

  C prototype:
      struct country *country(int ccode, struct country *cptr);
  Clarion prototype:
      Country(SHORT,*STRING),ULONG,NAME('_country')

This function returns country dependent information (date, time, currency,
etc.).

      ccode       Specifies the country.  This must be a non-negative value.

      cptr        A structure which contains the country information.

                  C structure:                  Clarion Structure:
                  ------------                  ------------------
                  struct  country {             Country       GROUP
                    int       co_date;          Date            SHORT
                    char      co_curr[5];       Currency        CSTRING(5)
                    char      co_thsep[2];      ThousandSep     CSTRING(2)
                    char      co_desep[2];      DecimalSep      CSTRING(2)
                    char      co_dtsep[2];      DateSep         CSTRING(2)
                    char      co_tmsep[2];      TimeSep         CSTRING(2)
                    char      co_currstyle;     CurrencyStyle   BYTE
                    char      co_digits;        Digits          BYTE
                    char      co_time;          Time            BYTE
                    long      co_case;          Case            LONG
                    char      co_dasep[2];      DaySep          CSTRING(2)
                    char      co_fill[10];      Fill            CSTRING(10)
                  };                                          END

      Return Value:

            The function returns the value of cptr, if successful; otherwise
            it returns NULL.

The co_date member can take the following three values:

            0     U.S. style: month, day, year
            1     European style: day, month, year
            2     Japanese style: year, month, day

The co_currstyle member can take the following values, which determine how the
currency symbol is placed with respect to the number:

            0     Symbol precedes value, no space between symbol and number.
            1     Symbol follows value, no space between symbol and number.
            2     Symbol precedes value, space between symbol and number.
            3     Symbol follows value, space between symbol and number.

------------------------------------------------------------------------------

SRand       PROCEDURE

  C prototype:
      void srand(unsigned seed);
  Clarion prototype:
      SRand(USHORT),NAME('_srand')

This function sets the start point for the pseudo-random number generator (the
Clarion RANDOM() function).  Setting the start point to a specific value
before the first call to the RANDOM() function ensures that the sequence of
"random" numbers generated is always the same.

      seed        Specifies the starting point.

      Return Value:

            None.  This C function must be used in Clarion code in the same
            manner as a Clarion PROCEDURE.  This means it must be called as a
            separate command statement -- it cannot be used in expressions or
            passed as a parameter.

------------------------------------------------------------------------------

Mouse Control Functions
=======================

The following functions provide low-level mouse control functionality.

------------------------------------------------------------------------------

MsGetMotion       PROCEDURE

  C prototype:
      void _ms_getmotion(struct _ms_motion *mp);
  Clarion prototype:
      MsGetMotion(*STRING),RAW,NAME('__ms_getmotion')

This function copies the number of mickeys moved horizontally and vertically
since the last call to _ms_getmotion.

      mp          A GROUP to contain the information about the mouse movement.

                  C structure:                  Clarion Structure:
                  ------------                  ------------------
                  struct  _ms_motion {          MsMotion      GROUP
                    int       vert;             Vert            SHORT
                    int       horiz;            Horiz           SHORT
                  };                                          END

      Return Value:

            None.  This C function must be used in Clarion code in the same
            manner as a Clarion PROCEDURE.  This means it must be called as a
            separate command statement -- it cannot be used in expressions or
            passed as a parameter.

------------------------------------------------------------------------------

MsGetPress  PROCEDURE

  C prototype:
      void _ms_getpress(int button, struct _ms_data *mp);
  Clarion prototype:
      MsGetPress(SHORT,*STRING),RAW,NAME('__ms_getpress')

This function reads the mouse position and button press information for the
specified button and copies the data to the variable passed as the mp
parameter.

      button      Specifies which button has been pressed.  This may have the
                  following values:

                  0     Left button
                  1     Right button
                  2     Middle button

      mp          A GROUP to contain the information about the mouse status.

                  C structure:                  Clarion Structure:
                  ------------                  ------------------
                  struct  _ms_data {            MsData        GROUP
                    int       left_pressed;     LeftPressed     SHORT
                    int       middle_pressed;   MiddlePressed   SHORT
                    int       right_pressed;    RightPressed    SHORT
                    int       actions;          Actions         SHORT
                    int       row;              Row             SHORT
                    int       col;              Col             SHORT
                  };                                          END

                  The left_pressed, right_pressed, and middle_pressed
                  variables are non-zero if that button was pressed.  Actions
                  contains the number of presses on the specified button since
                  the last call.  Row and col contain the mouse cursor row and
                  column positions at the last press.

      Return Value:

            None.  This C function must be used in Clarion code in the same
            manner as a Clarion PROCEDURE.  This means it must be called as a
            separate command statement -- it cannot be used in expressions or
            passed as a parameter.

------------------------------------------------------------------------------

MsGetRelease      PROCEDURE

  C prototype:
      void _ms_getrelease(int button, struct _ms_data *mp);
  Clarion prototype:
      MsGetRelease(SHORT,*STRING),RAW,NAME('__ms_getrelease')

This function reads the mouse position and button release information for the
specified button and copies the data to the variable passed as the mp
parameter.

      button      Specifies which button has been released.  This may have the
                  following values:

                  0     Left button
                  1     Right button
                  2     Middle button

      mp          A GROUP to contain the information about the mouse status.

                  C structure:                  Clarion Structure:
                  ------------                  ------------------
                  struct  _ms_data {            MsData        GROUP
                    int       left_pressed;     LeftPressed     SHORT
                    int       middle_pressed;   MiddlePressed   SHORT
                    int       right_pressed;    RightPressed    SHORT
                    int       actions;          Actions         SHORT
                    int       row;              Row             SHORT
                    int       col;              Col             SHORT
                  };                                          END

                  The left_pressed, right_pressed, and middle_pressed
                  variables are non-zero if that button was pressed.  Actions
                  contains the number of presses on the specified button since
                  the last call.  Row and col contain the mouse cursor row and
                  column positions at the last press.

      Return Value:

            None.  This C function must be used in Clarion code in the same
            manner as a Clarion PROCEDURE.  This means it must be called as a
            separate command statement -- it cannot be used in expressions or
            passed as a parameter.

------------------------------------------------------------------------------

MsGetSensitivity  PROCEDURE

  C prototype:
      void _ms_getsensitivity(struct _ms_sense *mp);
  Clarion prototype:
      MsGetSensitivity(*STRING),RAW,NAME('__ms_getsensitivity')

This function copies the current speed, double speed, and double speed
threshold values to the variable passed as the mp parameter.

      mp          A GROUP to contain the information about the mouse speed.

                  C structure:                  Clarion Structure:
                  ------------                  ------------------
                  struct  _ms_sense {           MsSense       GROUP
                    int       h_speed;          HSpeed          SHORT
                    int       v_speed;          VSpeed          SHORT
                    int       threshold;        Threshold       SHORT
                  };                                          END

      Return Value:

            None.  This C function must be used in Clarion code in the same
            manner as a Clarion PROCEDURE.  This means it must be called as a
            separate command statement -- it cannot be used in expressions or
            passed as a parameter.

------------------------------------------------------------------------------

MsGetStatus       PROCEDURE

  C prototype:
      void _ms_getstatus(struct _ms_data *mp);
  Clarion prototype:
      MsGetStatus(*STRING),RAW,NAME('__ms_getstatus')

This function reads the mouse position and button status and copies the data
to the variable passed as the mp parameter.

      mp          A GROUP to contain the information about the mouse status.

                  C structure:                  Clarion Structure:
                  ------------                  ------------------
                  struct  _ms_data {            MsData        GROUP
                    int       left_pressed;     LeftPressed     SHORT
                    int       middle_pressed;   MiddlePressed   SHORT
                    int       right_pressed;    RightPressed    SHORT
                    int       actions;          Actions         SHORT
                    int       row;              Row             SHORT
                    int       col;              Col             SHORT
                  };                                          END

                  The left_pressed, right_pressed, and middle_pressed
                  variables are non-zero if that button was pressed.  Actions
                  contains the number of presses on the specified button since
                  the last call.  Row and col contain the mouse cursor row and
                  column positions at the last press.

      Return Value:

            None.  This C function must be used in Clarion code in the same
            manner as a Clarion PROCEDURE.  This means it must be called as a
            separate command statement -- it cannot be used in expressions or
            passed as a parameter.

------------------------------------------------------------------------------

MsReset     FUNCTION

  C prototype:
      int _ms_reset(void);
  Clarion prototype:
      MsReset(),SHORT,NAME('__ms_reset')

This function resets the mouse driver.

      Return Value:

            If the mouse driver or hardware are not installed, 32767 is
            returned.  If the driver is installed, it returns the number of
            mouse buttons:

                  -1    Two buttons
                  0     Other than 2 buttons
                  3     Mouse Systems Mouse

------------------------------------------------------------------------------

MsSetDouble       PROCEDURE

  C prototype:
      void _ms_getdouble(int threshold);
  Clarion prototype:
      MsSetDouble(SHORT),NAME('__ms_setdouble')

This function defines the double speed threshold in mickeys per second.  The
double speed threshold is the mouse speed at which the on-screen motion is
doubled.

      threshold   Specifies the speed to set the double speed threshold.  A
                  value of zero (0) in this parameter resets the default value
                  of 64 mickeys per second.

      Return Value:

            None.  This C function must be used in Clarion code in the same
            manner as a Clarion PROCEDURE.  This means it must be called as a
            separate command statement -- it cannot be used in expressions or
            passed as a parameter.

------------------------------------------------------------------------------

MsSetMickeys      PROCEDURE

  C prototype:
      void _ms_getmickeys(int vert, int horiz);
  Clarion prototype:
      MsSetMickeys(SHORT,SHORT),NAME('__ms_setmickeys')

This function defines the pixel per mickey ratio, both vertically and
horizontally.  The default values are 8 horizontally and 16 vertically.

      vert        Specifies the vertical pixel per mickey ratio.

      horiz       Specifies the horizontal pixel per mickey ratio.

      Return Value:

            None.  This C function must be used in Clarion code in the same
            manner as a Clarion PROCEDURE.  This means it must be called as a
            separate command statement -- it cannot be used in expressions or
            passed as a parameter.

------------------------------------------------------------------------------

MsSetSensitivity  PROCEDURE

  C prototype:
      void _ms_setsensitivity(struct _ms_sense *mp);
  Clarion prototype:
      MsSetSensitivity(*STRING),RAW,NAME('__ms_setsensitivity')

This function sets the speed, double speed, and double speed threshold values
to the values contained in the variable passed as the mp parameter.

      mp          A GROUP which contains the information about the mouse
speed.

                  C structure:                  Clarion Structure:
                  ------------                  ------------------
                  struct  _ms_sense {           MsSense       GROUP
                    int       h_speed;          HSpeed          SHORT
                    int       v_speed;          VSpeed          SHORT
                    int       threshold;        Threshold       SHORT
                  };                                          END

      Return Value:

            None.  This C function must be used in Clarion code in the same
            manner as a Clarion PROCEDURE.  This means it must be called as a
            separate command statement -- it cannot be used in expressions or
            passed as a parameter.

------------------------------------------------------------------------------
