CMATH Version 6 for C/C++ and for Delphi
OptiCode Dr. Martin Sander Software Development Steinachstr. 9A D-69198 Schriesheim Germany http://www.optivec.com e-mail: optivec@gmx.de

CMATH is available both separately and as a part of OptiVec. If you ordered or downloaded CMATH alone, please disregard all references to OptiVec in this documentation.
If you got CMATH as a part of OptiVec, you may wish to refer to HANDBOOK.HTM for a description of the basic principles of the OptiVec libraries and an overview over VectorLib, the first part of OptiVec. The second part, MatrixLib is described in MATRIX.HTM.
Chapter 1.2 of this file contains the licence terms for the Shareware version, Chapter 1.3 for the Registered version.
 
OptiCode™ and OptiVec™ are trademarks of 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.
 

German-speaking users: Um die Kosten für das Herunterladen der Shareware-Version über das Internet für alle so gering wie möglich zu halten, enthält diese nur die englische Dokumentation. Sie finden die deutsche Beschreibung separat unter http://www.optivec.com/download/CMDOCD.ZIP.

Contents

---

1. Introduction

1.1 What is CMATH ?

Superior speed, accuracy and safety are achieved through the implementation in Assembly language (as opposed to the compiled or inline code of available complex C++ class libraries). Only for the most simple tasks, alternative inline C++ functions are used in the C++ version.

As far as the scope of CMATH overlaps with the complex class implementations of Visual C++, Borland C++, and Delphi, CMATH is a high-quality replacement for the latter, which are all awfully inefficient and inaccurate.

In contrast to the written-down-and-compiled textbook formulas of most other available complex libraries (including those coming with Visual C++ and the Borland compilers), the implementation of CMATH was guided by the following rules:

1. Without any compromise, top priority is always given to the mathematically 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. (Textbook formulas do not need to treat these situations separately, as they theoretically assume infinite accuracy of intermediate results; an actual implementation, however, has to work with the limited accuracy given by real-life processors.)
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.

This documentation describes the CMATH implementations for

• the Embarcadero / Borland / CodeGear series of C/C++ compilers (all versions of RAD Studio, Borland C++ Builder and Borland C++, version 4.0 or higher, including Turbo C++ 2006) for Win32 (native Win32 only; no .NET applications!) or the Win32 mode of 64-bit Windows.
• Microsoft Visual C++ (all version of Microsoft Visual Studio and MSVC down to MSVC 5.0+) for 32-bit Windows (or 32-bit mode of Win64) and 64-bit Windows (requires at least Visual Studio 2005) on PC platforms.
• Embarcadero / Borland Delphi, all versions from Delphi 4 on (RAD Studio, BDS, Stand-alone Delphi) on 32-bit Windows (or 32-bit mode of Win64)

1. Embarcadero / Borland / CodeGear C++:
   You have to choose between static and dynamic BC++ run-time library and link CMATHFS.LIB + CMATHF4W.LIB with the static BC++ RTL, but CMATHFD.LIB + CMATHF4W.LIB with the dynamic RTL.
   The Shareware version runs on all processors down to 486DX or Athlon computer. Additional P6 libraries (for Pentium III, Pentium IV or higher) are included with the registered version. Since CMATH functions cannot profit from the SSE2 commands introduced with the Pentium 4 processor and only marginally so from SSE3, there are no separate Pentium 4 or Core2, AMDx64 libraries for 32-bit CMATH.

2. Microsoft Visual C++:
   The 32-bit Shareware version has 486DX/Pentium libraries for "single-thread debug", "multi-thread debug", and "multi-thread DLL debug". The 64-bit Shareware version requires at least a Core2xxx or AMD x64 processor. The full (registered) version for Microsoft Visual C++ contains additional libraries for the three corresponding release libraries. In addition, 32-bit libraries optimized for Pentium III or higher are included in the full version. There is no actual debug information enclosed in the OptiVec "debug" libraries, but they have to be used with the debug libraries of Visual C++.

3. Delphi:
   Each Delphi release requires its own OptiVec library version. Only Delphi 2006 and 2007 share the same OptiVec units.
   The Shareware version requires, at least, a 486DX or Athlon computer. The Registered version offers an additional library optimized for P6 (Pentium III or higher).

Back to Table of Contents

1.1.1 C/C++ Specifics

Here is a detailed description of how to switch from the complex classes of Borland C++ to the new implementation given by CMATH:

1. In C++ modules, replace the statement
   #include <complex.h>
   by the statement
   #include <newcplx.h>
   Then, the following six complex classes are defined:
   class complex<float>, class complex<double>, class complex<long double>, class polar<float>, class polar<double>, and class polar<long double>.

   The data types fComplex, dComplex, eComplex, fPolar, dPolar, and ePolar are defined as synonyms for these classes.
   In order to avoid the letter "L" (which is already over-used by long and unsigned long, extended is used as a synonym for long double in the Borland C++ version of CMATH. In the MSVC version, it is a synonym for double, as MSVC does not support 80-bit IEEE reals. Consequently, the complex data types of extended precision are named eComplex and ePolar. Thereby, the way is held open for a future inclusion of whole-number complex types into CMATH. Then, liComplex and ulComplex shall denote the complex types consisting of long int and unsigned long parts, respectively.
    

2. If you prefer to have the "classic" class complex of older releases of Borland C++, you have to declare
   #define CMATH_CLASSIC_COMPLEX
   before (!) including <newcplx.h>.
   In this case, only the class complex will be defined and gets the synonym dComplex. Here you will have no access to the complex-number functions of float and of extended precision, and all functions in polar coordinates are unavailable as well.
    
3. For plain-C modules, you cannot include <newcplx.h>. Rather, please declare
   #include <cmath.h>
   If you are using only one level of floating-point precision, you may wish to include only one of the type-specific include-files: <cfmath.h>, <cdmath.h>, or <cemath.h>, respectively.
   The plain-C implementation of CMATH is based upon the following definitions of the complex data types:
   typedef struct { float Re, Im; } fComplex;
   typedef struct { double Re, Im; } dComplex;
   typedef struct { extended Re, Im; } eComplex;
   typedef struct { float Mag, Arg; } fPolar;
   typedef struct { double Mag, Arg; } dPolar;
   typedef struct { extended Mag, Arg; } ePolar;
   As described above, the data type extended is used as a synonym for long double (Borland C++ version) or double (MSVC version).
    
4. Replace calls to the complex member function polar by calls to magargtoc.
    
5. The constituent parts of the C++ classes are declared as public (in contrast to Borland C++ !). They are named "Re" and "Im" in the cartesian classes, and "Mag" and "Arg" in the polar classes. This allows to access them as z.Re, z.Im, p.Mag, or p.Arg in C++ modules as well as in plain-C modules.
    
6. For time-critical applications, we recommend to use the C rather than the C++ version of CMATH, as C/C++ compilers handle structs much more efficiently than classes. To use the C version with your C++ modules, please note the following points:
   • include <cmath.h> instead of <newcplx.h>
   • for initialization, assign the real/imaginary or Mag/Arg parts directly (e.g., z.Re = 3; z.Im = 5; ) or use the functions fcplx, dcplx, ecplx, fpolr, dpolr, epolr. The constructors complex(), fComplex(), polar(), fPolar(), etc. are not available.
   • if you do a C++ compile on modules with <cmath.h> included, you have the choice between calling CMATH functions by their type-specific names (like cf_sin,   cd_exp), or by their overloaded C++ names (e.g., sin,   exp). On some occasions, you might be forced to use the type-specific names in order to resolve ambiguities.

Back to Table of Contents

1.1.2 Pascal/Delphi Specifics

CMATH for Pascal/Delphi defines six complex data types:
type fComplex = record Re, Im: Single; end;
type dComplex = record Re, Im: Double; end;
type eComplex = record Re, Im: Extended; end;
type fPolar = record Mag, Arg: Float; end;
type dPolar = record Mag, Arg: Double; end;
type ePolar = record Mag, Arg: 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.

The CMATH-Pascal data types are binary compatible with those of the C/C++ versions.

The type-specific function names are the same as in the plain-C version. The syntax, however, is somewhat different, as complex numbers as return values could be implemented most efficiently by passed them as var arguments to the complex functions, e.g.
procedure cf_sin( var zy:fComplex; zx:fComplex );

The overloaded function names are the same as in the C++ version. Here, the results are treated as true return values, e.g.
function sin( zx:fComplex ): fComplex;

Back to Table of Contents

1.2 Licence Terms for the Shareware Version

Back to Table of Contents

1.3 Registered Versions

1.3.1 Registered Versions: Ordering

Purchasing the full (registered) version gives you the right to use it on as many computers at a time as the number of units you bought.

The right to distribute applications employing functions of CMATH is included in the commercial-version licence. No run-time licence are needed for your customers! Corporate site and world-wide licences are available upon request.

The full versions (both the commercial and the educational editions) of CMATH

• support Windows 98/2000/ME, NT, XP, Vista, 7
  
• single-thread, multi-thread, multi-thread DLL debug and release for Win32 and Win64 (Microsoft Visual C++)
  
• Delphi 4 through 7, 2005 through 2010 and XE (RAD Studio, BDS, Borland Delphi)
  
• have individually optimized libraries for each degree of processor backward-compatibility:
  P8 (requiring Core2xxx, Core i3, i5, i7 etc., AMD x64+; 64-bit libraries only)
  P6 (requiring Pentium III+)
  486DX/Pentium+ (optimized for Pentium II)
• (C/C++ versions only:) come with printed documentation (which, however, is updated much less frequently than the electronic documentation).
  
• entitle you to two years of free updates (by downloading from our web site)
  
• can be ordered the following ways:
  a) International orders (credit-card or US cheque) by Internet, mail, FAX, or phone
  b) Orders within the European Union (pre-paid or upon invoice)

a) International Orders: Pricing

CMATH for Embarcadero / Borland C/C++,  Microsoft Visual C++,  or Embarcadero / Borland Delphi
(CD-ROM, manual in English)

International: Ordering Options

You may also order by e-mail to register@shareit.com.
US customers can also contact ShareIt! by telephone 1-724-850-8186 or FAX 1-724-850-8189 (only for orders, please).
Note the program No.: 

	commercial	educational
CMATH for Embarcadero / Borland C/C++	101353	102655
CMATH for Microsoft Visual C++	103422	103441
CMATH for Delphi	103844	103860

b) Orders in the European Union

CMATH for Embarcadero / Borland C/C++,  Microsoft Visual C++,  or Embarcadero / Borland Delphi
(CD-ROM, manual in English)

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

Please send a print-out of this order form to

OptiCode - Dr. Martin Sander Software Dev.
Steinachstr. 9A
D-69198 Schriesheim
Germany

FAX +49 - 6203 - 92 53 96

For any other questions related to ordering CMATH, please contact us at: optivec@gmx.de

Back to Table of Contents

1.3.2 License Terms for the Registered version

Back to Table of Contents

1.4 Getting Started

If you got CMATH as a part of OptiVec, you should read chapter 1.4 of HANDBOOK.HTM instead of the remainder of the present paragraph. If you have already read that, continue with chapter 2, or go back to the Table of Contents.

To install CMATH, please follow these steps:

1. In order to use CMATH, you need an already installed copy of your C/C++, Delphi, or Pascal compiler. Install CMATH by executing INSTALL.EXE from the root directory of the installation disk or CD-ROM. Normally, CMATH will be installed into a directory named "CMATH". This directory holds the documentation.
2. Include the CMATH lib and include (C/C++) or units (Delphi) subdirectories into the search path.
3. a) C/C++:
   Assuming your CMATH directory is C:\CMATH, add
   C:\CMATH\LIB to the library search path and
   C:\CMATH\INCLUDE to the include-file search path of the IDE (and of the configuration file TURBOC.CFG and BCC32.CFG in case you are using Borland's command-line compilers).
    
   b) Delphi, Shareware version:
   The units (.DCU files) will be installed into the directory CMATH\LIB.
    
   c) Delphi, Registered version:
   Delphi: The installation routine you have to execute is named after the target Delphi version: INSTALL4.EXE, INSTALL5.EXE, INSTALL6.EXE, etc.. The installation routine for Delphi 2005 is INSTALL9.EXE, the one for Delphi 2006 and 2007 (Borland Developer Suite or Turbo Delphi) is INSTALL10.EXE. The 2009 version needs INSTALL12.EXE, the 2010 version INSTALL13.EXE and the XE version INSTALL14.EXE. The units (.DCU files) for 486/Pentium will be installed into CMATH\LIB4, and those for Pentium III+ into CMATH\LIB6.
4. Choose the desired platform, target, and configuration:
   1. Embarcadero / Borland C++:
      You have to include not only one, but two CMATH libraries: First the CMATH base library, CMATHFS.LIB (interface to the static runtime library of BC++) or CMATHFD.LIB (interface to the dynamically-linked runtime library of BC++). Second, select the required processor-specific library from the following table and add it to your project.

      Processor	CMATH library
      486DX/Pentium	CMATHF4W.LIB
      newer processors (at least Pentium III)	CMATHF6W.LIB

       
      
   2. Visual C++: You have to include not only one, but two CMATH libraries. The first one contains the interface between CMATH and the VC++ runtime library; it has to be matched with the specific version of the VC++ runtime library you chose for your project. The second one is independent from the configuration and runtime library; you have to choose it according to the desired CPU support.
      First choose the project configuration and runtime library. The latter is set at Project / (Configuration) Settings / C/C++ / Code Generation / Runtime Library. Under Project / (Configuration) Settings / Linker / Input, add the matching OptiVec library to your project, according to the following table. The Single-Thread libraries can be used only with Visual C++ versions up to and including Visual Studio 2003. From Visual Studio 2005 on, you always have to use the multithread libraries, even if your application generates only one thread. The "normal" OptiVec base libraries are compatible with all versions of Visual C++. If you are working with Visual Studio 2005 or 2008, however, we recommend to profit from some safety improvements by linking the CMATH base libraries marked by an additional "8" or "9", respectively (present only in the registered version).
       

      Runtime Library	CMATH base library (all VC++-versions)	Visual Studio 2005 only	Visual Studio 2008 or 2010
      Win32, single-thread debug	CMVCSD.LIB	----	----
      Win32, single-thread release	CMVCSR.LIB	----	----
      Win32, multi-thread debug	CMVCMTD.LIB	CMVC8MTD.LIB	CMVC9MTD.LIB
      Win32, multi-thread release	CMVCMTR.LIB	CMVC8MTR.LIB	CMVC9MTR.LIB
      Win32, multi-thread DLL debug	CMVCMDD.LIB	CMVC8MDD.LIB	CMVC9MDD.LIB
      Win32, multi-thread DLL release	CMVCMDR.LIB	CMVC8MDR.LIB	CMVC9MDR.LIB
      Win64, multi-thread debug	CMVCx64MTD.LIB
      Win64, multi-thread release	CMVCx64MTR.LIB
      Win64, multi-thread DLL debug	CMVCx64MDD.LIB
      Win64, multi-thread DLL release	CMVCx64MDR.LIB

       
      After that, please add the second, processor-specific CMATH library according to the following table:

      Processor	32-bit CMATH library	64-bit CMATH library
      486DX/Pentium	CMVC4.LIB	----
      newer processors (at least Pentium III)	CMVC6.LIB	----
      latest processors (Core2xxx, i3, i5, i7, AMDx64)	----	CMVC64_8.LIB

       
      In order to allow CMATH to be used in applications both with and without MFC, it calls the Windows API only directly, not via MFC. However, if you use MFC (either as a static library or as a DLL), Visual C++ does not automatically link the import library, user32.lib. You have to explicitly do this yourself: The line, Project / Settings / Linker / Object and Library Modules must contain user32.lib. Otherwise you would get the linker error "error LNK2001: Unresolved external symbol __imp__MessageBoxA@??".
       
   3. Borland Delphi:
      No choices are to be made at this level.
5. Declare the use of CMATH functions in your program,:
   • C/C++:
     #include <newcplx.h> (C++) or <cmath.h> (C or C++), as described above.
     If you are writing MFC or Borland C++ ObjectWindows applications, the CMATH header files should be included after the MFC or OWL header files.
   • Pascal/Delphi:
     Declare the use of CMATH units as usual with the "uses CMATH" statement.
6. Have a look into the sample programs by opening the project appropriate for your compiler:
   • Microsoft Visual C++:
     Visual Studio 2005, 2008, 2010: CDEMO.sln
     MSVC 6.0, VS 2003:         CDEMO.DSW.
     Depending on the exact version, Visual Studio may have to convert this project map and its parts into a newer format. When prompted, answer "Yes to all" to accept this automatic conversion.
   • Embarcadero / Borland C++:
     CDEMO.cbproj and MANDEL.cbproj are projects for RAD Studio 2009, 2010, XE
     CDEMO.bdsproj and MANDEL.bdsproj are for BDS 2006 and 2007
     CDEMOB6.BPR and MANDELB6.BPR are for BC++ Builder 6+.
   • Delphi:
     Delphi 2009, 2010, XE: open CDEMO.dproj or MANDEL.dproj
     Delphi 2005, 2006, 2007: open CDEMO.bdsproj or MANDEL.bdsproj
     all older Delphi versions: open CDEMO.DPR or MANDEL.DPR

Back to Table of Contents

2. Overview over the Functions of CMATH

In C++ and Delphi, synonyms are defined for all these functions. The synonyms do not have a prefix, since the data type information is implicitly handled by the compiler. The overloaded function names are mostly identical to those found in the complex class libraries (if the respective function exists there). Note, however, that the member function polar had to be replaced by magargtoc, as the name "polar" is now reserved for the polar classes.

C++ only: If you wish to use the C function names in your C++ modules, be sure to include <cmath.h> instead of <newcplx.h>.

---

2.1. Initialization of Complex Numbers

In the following, we denote the complex classes by by their short names, fComplex, fPolar, etc. In C++, you can always use the template nomenclature instead, writing "complex<float>" wherever "fComplex" is written here, and so on for all other complex types and classes.

Complex numbers are initialized by separately assigning a value to the imaginary and real parts or to the Mag and Arg parts, e.g.:
z.Re  = 3.0; z.Im  = 5.7;
p.Mag = 8.8; p.Arg = 3.14;
(Of course, for Pascal/Delphi, the assignment operator is written ":=").
Alternatively, the same initialization can be accomplished by the functions fcplx or fpolr:
C/C++:
z = fcplx( 3.0, 5.7 );
p = fpolr( 4.0, 0.7 );

Pascal/Delphi:
fcplx( z, 3.0, 5.7 );
fpolr( p, 3.0, 5.7 );

For double-precision complex numbers, use dcplx and dpolr, for extended-precision complex numbers, use ecplx and epolr.

---

2.2. Data-Type Interconversions

Interconversions between the various complex types are performed via the functions:

cftocd,   cdtocf,   cftoce,   cetocf,   cdtoce,   cetocd	up- or down-conversion of accuracy within the cartesian-complex types
pftopd,   pdtopf,   pftope,   petopf,   pdtope,   petopd	up- or down-conversion of accuracy within the polar-complex types
cftopf,   cftopd,   cftope, cdtopf,   cdtopd,   cdtope, cetopf,   cetopd,   cetope	conversion from cartesian into polar complex
pftocf,   pftocd,   pftoce, pdtocf,   pdtocd,   pdtoce, petocf,   petocd,   petoce	conversion from polar into cartesian complex

 
OVERFLOW errors in the course of down-conversions are silently cured: program execution is continued with the largest value possible.

C++ only:

For C++ modules, there are several overloaded constructors as an alternative to the above functions: basic forms:    fComplex fComplex( float RePart, float ImPart=0 );    fComplex fComplex( dComplex );    fComplex fComplex( eComplex );    fPolar fPolar( float MagPart, float ArgPart=0 );    fPolar fPolar( dPolar );    fPolar fPolar( ePolar ); interconversion cartesian <--> polar:    fComplex fComplex( fPolar );    fComplex fComplex( dPolar );    fComplex fComplex( ePolar );    fPolar fPolar( fComplex );    fPolar fPolar( dComplex );    fPolar fPolar( eComplex ); Similarly to the constructors fComplex() and fPolar(), also dComplex(), dPolar(), eComplex, and ePolar() exist in overloaded versions performing the same tasks for the classes dComplex, dPolar, eComplex, and ePolar, respectively. As described above for the C/Pascal/Delphi versions, OVERFLOW errors in the course of down-conversions are silently cured, without calling _matherr.

 
A special constructor for polar numbers is
fPolar pf_principal( fPolar __p );
and, for C++ only, its overloaded form for two separate real input numbers
fPolar principal( float Mag, float Arg );
These functions reduce the input Arg to the range -p < Arg <= +p. You might recall that each complex number has an infinite number of representations in polar coordinates, with the angles differing by an integer multiple of 2 p. The representation with -p < Arg <= +p is called the principal value.
Please note that these are the only polar functions reducing the output to the principal value. All others accept and return arguments whose angles may fall outside this range.

The conversion between cartesian and polar format involves transcedental functions and is, therefore, quite time-consuming. It is true that multiplications are faster in polar coordinates, whereas additions are much faster in Cartesian. The difference, however, is so much smaller than the cost of switching back and forth between the different representations, that we recommend you stay in general with the cartesian format. Only in the following cases, the conversion really makes sense:

1. You have only multiplications and related math functions (like square,  sqrt,  ipow). Then, you should start out with polar coordinates.
2. You have to call the complex exponential function. In this case, cf_exptop brings you into polar coordinates in a very natural manner.
3. You are in polar coordinates and have to calculate the logarithm. In this case, pf_logtoc (or similarly pf_log2toc,   pf_log10toc) brings you "down" to the cartesian representation.

Zurück zum Inhaltsverzeichnis

2.3 Basic Complex Operations

Back to Table of Contents

2.4 Arithmetic Operations

Since it is only C++ and Delphi, but neither plain-C nor Pascal, which allows overloaded arithmetic operators, all arithmetic operations of complex numbers are implemented additionally as functions which may be called from C/Pascal/Delphi as well as C++ modules:
 

Cartesian	Polar
cf_add	N.A.	addition of two complex numbers
cf_addRe	N.A.	addition of a complex number and a real number
cf_sub	N.A.	subtraction of two complex numbers (first operand minus the second operand)
cf_subRe	N.A.	subtraction of a real number from a complex number
cf_subrRe	N.A.	subtraction of a complex number from a real number
cf_mul	pf_mul	multiplication of two complex numbers
cf_mulRe	pf_mulRe	multiplication of a complex number and a real number
cf_div	pf_div	division of two complex numbers (first operand divided by the second operand)
cf_divRe	pf_divRe	division of a complex number by a real number
cf_divrRe	pf_divrRe	division of a real number by a complex number

(similarly the double- and extended-precision versions) 

The assignment operator "=" or ":=" is the only operator defined also in plain-C and Pascal/Delphi for complex numbers.

Back to Table of Contents

2.5 Mathematical Functions

As noted above, the exponential and logarithm functions provide a natural transition between cartesian and polar coordinates. While there are exp and log functions for fComplex as argument and as return value, cf_exptop takes an fComplex argument and returns fPolar. In the opposite direction, pf_logtoc takes an fPolar argument and returns fComplex.

Back to Table of Contents

3. Error Handling

3.1 General Error Handling of Complex Functions

In contrast to the arithmetic operations, all mathematical functions and all data-type interconversions perform a tight error checking. All error messages eventually generated use the C/Pascal name (rather than the overloaded C++/Delphi name) of the failing function.

If you got CMATH as a part of OptiVec, you should read chapter 5 of HANDBOOK.HTM rather than the present chapter.

3.1.1 C/C++ Specifics

Borland C++ 16-bit programs only:

Back to Table of Contents

3.1.2 Pascal/Delphi Specifics

Back to Table of Contents

3.2 Advanced Error Handling: Writing Messages into a File

You might wish to circumvent this. To this end, OptiVec and CMATH provide the function V_setErrorEventFile. This function needs as arguments the desired name of your event file and a switch named ScreenAndFile which decides if you wish to have error messages printed simultaneously into the file and onto the screen (ScreenAndFile = TRUE (non-zero)) or exclusively into the file (ScreenAndFile = FALSE (0)).

Example:
V_setErrorEventFile( "MyLogFil.TXT", 0 ); /* C/C++ */
V_setErrorEventFile( 'MyLogFil.TXT', FALSE ); (* Pascal/Delphi *)
Here, you will get all subsequent error messages only into your log file, MyLogFil.TXT and no messages on the screen. The default, i.e., printing error messages to the screen, is restored by V_closeErrorEventFile. (That function does not take any arguments and does not return anything.)

Note that this redirection of error messages is valid only for errors occurring in OptiVec (CMATH) routines. If you wish to do so, however, there is a way in C/C++ to extend the redirection also to the "non-OptiVec" functions: you may modify _matherr and _matherrl such that the statement
return 0;
(which signals an unresolved error) is replaced by the sequence
V_noteError( e->name, e->type ); return 1;
Thereby the task of printing the error message for unresolved errors is passed to the OptiVec function V_noteError which shall check if an error event file was defined or not and direct its output to the desired place. Keep in mind that it is the return value of _matherr which decides if an error message is printed by the default error handler of your compiler. Thus, after the call to V_noteError, the printing of the default error messages is by-passed by returning "1". (Also, do not forget that OptiVec / CMATH uses your _matherr routine to determine which errors you accept and which not!)

For example, your _matherr function (matherr - without the leading underbar - for Borland C++ 3.0 and 3.1) might look like the following one:
#include <math.h>
int _matherr( struct exception *e) /* "_exception" for MSVC */
{
  if( (e->type == UNDERFLOW) || (e->type == TLOSS) ) ; /* ignore */
  else /* all other errors deserve at least notice */
  {
    V_noteError( e->name, e->type );
    if (e->type == DOMAIN) exit(1); /* really fatal */
  }
  return 1;
}
(Of course, if you decide to change _matherr, do not forget to change _matherrl in the same way, if you are using Borland C++!).

Zurück zum Inhaltsverzeichnis

4. Syntax Reference

Zurück zum Inhaltsverzeichnis

4.1 Plain-C, Pascal/Delphi Functions

fComplex cf_tanh( fComplex __z );
procedure cf_tanh( var zy:fComplex; zx:fComplex );

Back to Table of Contents

4.2 Overloaded C++/Delphi Functions

fComplex tanh( fComplex _z );
function tanh( zx:fComplex ): fComplex;

Back to Table of Contents

---

E N D