    CCCCCCC     MM         MM          A         TTTTTTTTTT    HH      HH
  CC            MMM       MMM         AAA            TT        HH      HH
 CCC            MMMM     MMMM        AA AA           TT        HH      HH
 CCC            MM MM   MM MM       AA   AA          TT        HHHHHHHHHH
 CCC            MM  MM MM  MM      AAAAAAAAA         TT        HH      HH
  CC            MM   MMM   MM     AA       AA        TT        HH      HH
    CCCCCCC     MM    M    MM    AA         AA       TT        HH      HH


                              CMATH 2

                  for Borland Pascal and Delphi

            (Borland (Turbo) Pascal 7.0, Delphi 2, 4)

                    OptiCode - Dr. Martin Sander Software Development
                    Serturnerstr. 11
                    D-37085 Goettingen
                    Germany
                    e-mail: support@optivec.com  or  sales@optivec.com
                    http://www.optivec.com

For the commercial version, see chapter 1.3.

*****************************************************************************

!!     This is an ASCII text file!  It is best viewed with a simple        !!
!!     DOS editor.                                                         !!
!!     If you load this file into a word processor under Windows, you      !!
!!     must use the filter "DOS text".                                     !!


OptiCode (TM) and OptiVec (TM) are trademarks of
    OptiCode - Dr. Martin Sander Software Dev.
Other brand and product names mentioned in this handbook for identification
purposes are trademarks or registered trademarks of their respective holders.


****************************************************************************
*                                                                          *
*******                           Contents                           *******
*                                                                          *
****************************************************************************

1. Introduction
   1.1 What is CMATH ?
   1.2 Licence Terms Shareware Version
   1.3 Registered Version
       1.3.1 CMATH for Borland Pascal
       1.3.2 CMATH for Borland Delphi
       1.3.3 Licence Terms for the Registered Version

2. Getting Started
   2.1 Installation
   2.2 De-Installation

3. Overview over the Functions of CMATH
   3.1 Initialization of Complex Numbers
   3.2 Data-Type Interconversions
   3.3 Basic Complex Operations
   3.4 Arithmetic Operations
   3.5 Mathematical Functions

4. Error Handling
   4.1 General Error Handling of Complex Functions
   4.2 Advanced Error Handling: Writing Messages into a File

5. Syntax Reference

****************************************************************************
*                                                                          *
*******                       1. Introduction                        *******
*                                                                          *
*****************************************************************************


1.1 What is CMATH ?
-------------------

CMATH is a comprehensive library for complex-number arithmetis and
mathematics. Superior speed, accuracy and safety are achieved through the
implementation in Assembly language (as opposed to the compiled or
inline code you might know from C++ compilers' complex class libraries).

The implementation was guided by the following rules:

   1. Without any compromise, top priority is always given to the mathema-
      tically correct result, with the accuracy demanded for the respective
      data type. Especially for complex functions, this necessitates a
      very thorough treatment of many different situations. To this end,
      the various cases have to be distinguished with pedantic care.
   2. Mathematical functions must be "safe" under all circumstances.
      They may for no reason simply crash, but have to perform a decent
      error treatment. This is true even - and perhaps especially - for
      seemingly nonsense arguments, with the single exception of the
      non-numbers INF and NAN, which occur themselves only as a result
      of serious errors in other functions.
   3. By all possible means, greatest execution speed must be attained.
      (After all, you did not buy your fast computer for nothing!)
   4. The program code has to be as compact as possible. However, in case
      of conflicts, faster execution speed is always given priority
      over smaller code size.

Unlike the C++ version of CMATH, the Pascal/Delphi versions define
complex numbers as records instead of classes. The reason is that,
in Object-Pascal, overloading of arithmetic operators and of functions
is not possible to the same degree as in C++.
The CMATH-Pascal data types are binary compatible with those of the
C/C++ versions. The function names are also the same as in the plain-C
version. The syntax, however, is somewhat different, as C supports
complex numbers as return values, whereas Pascal does not.

CMATH defines three complex data types:
    type  fComplex = record   Re, Im: Single;    end;
    type  dComplex = record   Re, Im: Double;    end;
    type  eComplex = record   Re, Im: Extended;  end;

The reason why the single-precision type gets the name fComplex instead
of sComplex is that the letter "s" is already over-used by "ShortInt"
and "SmallInt" in Pascal. Therefore, this name is derived from the C/C++
analogue of Single, which is "float."
This also holds the way open for a future inclusion of whole-number
complex types into CMATH. Then,"siComplex" and "usComplex" will denote
the complex types consisting of "SmallInt" or "Word" ("UnsignedSmall")
parts, respectively.

All data types and functions are contained in one single unit: CMATH.

The implementation described in this documentation refers to
* Borland (Turbo) Pascal, version 7.0 for DOS, or
* Borland Delphi 2 or 4.

Depending on your choice when ordering or downloading the Shareware version
of CMATH, you have got either or these versions. Any of them requires,
at least, a 386 computer equipped with a 387 coprocessor. This means:
no emulation, no 486SX, but preferrably 486DX, Pentium or higher.


1.2 Licence Terms Shareware Version
-----------------------------------

The following licence terms apply to the Shareware version of CMATH.
If you got this file with the Registered version, please see paragraph 1.3
for your valid licence.

This is the English Shareware version of CMATH for Borland Pascal/Delphi
("Software"). It may be used under the following licence terms:

1. You may test the SOFTWARE free of charge for a period of up to 90 days
   on one computer. This testing phase ends when you permanently integrate
   functions of this SOFTWARE into any of your applications (programs,
   program parts...).
2. Applications, created with the Shareware version of this SOFTWARE, will
   run only on the same computer on which this SOFTWARE has been installed.
   They cannot and may not be distributed to others.
3. If you want to continue using this SOFTWARE after testing, and/or
   if you wish to distribute programs containing functions of this SOFTWARE,
   you have to purchase the registered version (see chapter 1.3).
4. This SOFTWARE is provided on an "as is" basis. Any explicit or implicit
   warranties for the SOFTWARE are excluded.
   Despite thorough testing of the SOFTWARE, errors and bugs cannot
   be excluded with certainty. No claims as to merchantability or fitness
   for a particular purpose are made.
   You may not use the SOFTWARE in any environment or situation where
   personal injury or excessive damage to anyone's property (including
   your own) could arise from malfunctioning of the SOFTWARE.


Copyright for the SOFTWARE and its documentation (C) 1996-1999 Martin Sander

All rights reserved, including those of translation into foreign languages.

Address of the author:
              Dr. Martin Sander Software Development
              Sertrnerstr. 11
              D-37085 Gttingen
              Germany
              e-mail: MartinSander@optivec.com



1.3 Registered Version
----------------------

1.3.1 Registered Version of CMATH for Borland Pascal
-----------------------------------------------------

The registered version of CMATH for Borland Pascal

-  supports all targets of Borland Pascal:
   real-mode DOS, DPMI, and Windows 3.x

-  has individually optimized units for three degrees of
   processor backward-compatibility:
      486DX/Pentium+
      386+ (coprocessor required)
      286+ (with emulation; i.e., no coprocessor required)

-  costs  $25 or EUR 19 per unit
          plus a mailing fee of  $5 or EUR 5.

   and can be ordered directly from the author (e-mail or a printout
   of ORDER.TXT), or through the secure-server ordering service
   "ShareIt" at

   http://www.shareit.com/programs/103424.htm

-  If you upgrade to CMATH for Delphi at any time, the above registration
   fee will be deduced from the price of CMATH for Delphi.

-  Multi-user licences are available upon request.


1.3.2 Registered Version of CMATH for Borland Delphi
----------------------------------------------------

In order to make this product affordable also for those who will not
themselves make money using it, we offer an "educational edition" at a
strongly reduced rate, in addition to the full "commercial edition".
The contents of these two editions is identical. The only difference lies
in the restrictions of use: The "educational edition" may not be used for
commercial / business / government purposes, but is restricted to private
and educational use.

The registered version of CMATH for Borland Delphi

-  supports Borland Delphi 2 and 4

-  has individually optimized units for two degrees of
   processor backward-compatibility:
      486DX/Pentium+
      386+387

-  entitles you to two years of free updates
   (by downloading from our web site)

-  can be ordered at the following conditions:

   a) if you can pay in German Marks (from 1999 on: in Euro)
      and order directly from the author, the price is
      DM  59,- for  1 unit of the educational edition
      DM  99,- for  1 unit of the commercial edition,
      DM 350,- for  5 units,
      DM 600,- for 10 units    (incl. 16% VAT, plus DM 10,- handling charge).
      Please order by sending an e-mail to  sales@optivec.com
      or use a print-out of the file ORDER.TXT.
      Payment options:
          - pre-paid by DM Eurocheque
          - C.O.D. (Cash-On-Delivery)
          - upon invoice (only within Germany, net 14 days)

      If you have a European VAT ID, or if you order from outside the
      European Union, you are exempt from the German VAT, but you may
      have to pay your local VAT and/or import duties according to
      local laws.

   b) International credit card or US-$ cheque orders are possible 
      through the following web-sites:

      Atlantic Coast's SoftShop:
      http://www.soft-shop.com/cgi-bin/order.html?136

      (this is the SoftShop sales page for all our products; please
       be sure to choose the right one from the menu)

          $ 39 for  1 unit of the educational edition
          $ 60 for  1 unit of the commercial edition,
          $200 for  5 units,
          $350 for 10 units
          Add $5 for shipping&handling and applicable VAT.

      ShareIt:
      http://www.shareit.com/programs/103844.htm

          $ 65 per unit of the commercial edition (including S&H),
          $ 44 per unit of the educational edition (including S&H).
               Add applicable VAT.

      You may also order by e-mail to register@shareit.com.
      US customers can also call 1-800-903-4152 (only for orders, please).
      US check and cash orders can be sent to ShareIt!'s US office at
           ShareIt! Inc.
           P.O. Box 97841 
           Pittsburgh, PA 15227-0241
           USA
      * When ordering by e-mail, phone, or postal mail through ShareIt,  *
      * please have the program number ready:                            *
      * CMATH for Delphi:         No. 103844                             *
      *     dto., educational:    No. 103860                             *



1.3.3 Licence Terms for the Registered Version
----------------------------------------------

The following licence terms apply for the Registered version of either
CMATH for Borland Pascal or CMATH for Delphi:

This is a single copy license for CMATH for Pascal/Delphi ("SOFTWARE")
granted by Dr. Martin Sander Software Development.
The SOFTWARE in this package is licensed to you as the user. It is not sold.
Once you have paid the required license fee, you may use the SOFTWARE for as
long as you like, provided you do not violate the copyright and if you
observe the following rules:
1. You may use the SOFTWARE on any computer for which it is designed as long
   as not more than one person uses it at any time.
2. You may make backup copies of the SOFTWARE for your personal use. You may
   only transfer the SOFTWARE to somebody else if you transfer the original
   and all copies, retaining no copies for yourself. You may not lease or
   rent the SOFTWARE to others.
3. You may not decompile, disassemble, or otherwise reverse engineer the
   SOFTWARE into a machine-readable form. You may, however, inspect the
   functions contained in this SOFTWARE by means of debuggers like those
   included in Borland Pascal/Delphi.
4. If you payed the reduced licence fee for the "educational version" rather
   than the full rate for the "commercial version", the use of this SOFTWARE
   is restricted to private and educational purposes. In this case, you may
   not use the SOFTWARE for commercial purposes or for government purposes
   other than education.
5. You may not use the SOFTWARE in any environment or situation where
   personal injury or excessive damage to anyone's property (including your
   own) could arise from malfunctioning of the SOFTWARE.
6. Martin Sander's liability is limited by the enclosed Limited Warranty.
   In no case shall Martin Sander's liability exceed the license paid for
   the right to use the SOFTWARE.


Limited Warranty for the Registered version
-------------------------------------------
1. Martin Sander warrants that the magnetic or optic media on which the
   SOFTWARE is recorded are free from defects in materials and workmanship
   under normal use. The SOFTWARE itself will perform substantially in
   accordance with the specifications set forth in the documentation.
2. The above express warranties are made for a period of six months from
   the date the SOFTWARE is delivered to you as the first user.
3. Any magnetic/optic or printed media from this package proving defective
   in materials or workmanship will be replaced on an exchange basis.
4. Great care has been taken to ensure that the SOFTWARE operates in
   accordance with the specifications as described in the documentation.
   However, it is not guaranteed that this SOFTWARE will operate completely
   free of errors or that the documentation is free of errors.
5. Any implied warranties including any warranties of merchantability or of
   fitness for a particular purpose are limited to the terms of the above
   express warranties.
7. Martin Sander shall not in any case be liable for special, incidental,
   consequential, indirect or other damages arising from any breach of these
   warranties or of the license conditions, even if he has been notified of
   the possibility of such damages.

Copyright for the SOFTWARE and its documentation (C) 1996-1999 Martin Sander



****************************************************************************
*                                                                          *
*******                 2. Getting Started                           *******
*                                                                          *
****************************************************************************

2.1 Installation
----------------
If you got CMATH as a part of OptiVec (a comprehensive library of
vectorized functions by the same author), CMATH is automatically installed
when you install OptiVec itself. In this case, installation of CMATH is
already included and you should skip this chapter to continue with chapter 3.

Otherwise, please note the following points:

1.  In order to use CMATH, you need an already installed copy of your
    target compiler. Install CMATH by executing INSTALL.EXE on the
    installation disk.

2.  For Pascal, use the protected-mode version of the compiler, i.e.,
    BP.EXE or TPX.EXE, if you can.  The real-mode version, TP.EXE, might
    run out of linker memory. If you encounter that problem, set the linker
    option "link buffer" to "disk". If even that does not help, you
    can only use the command-line compiler.

3.  Add the installation directory (which you chose during installation) to
    the Units search path of the IDE
    (Pascal: menu "Options/Directories";
     Delphi: menu "Project/Options/Directories").

4.  BP.EXE only: Choose the target "real-mode DOS";
    you should also choose 286 code generation and real coprocessor
    commands (i.e., switch emulation off !).

5.  Add CMATH to the "uses" clause in the header of your programs/units
    which call functions of CMATH.

After these preparations, all CMATH functions are available for your programs.


2.2 De-Installation
-------------------

Should you wish to remove CMATH from your computer after testing, please
run UNINSTAL.EXE, or simply delete the directory CMATH with its
subdirectories.
