3. Error Handling, License, Memory System, Standard Output, Quadruple Precision - Error, License, Memory, Print, VQuad

CEETRON SAM provides facilities for detecting and handling errors in module functions using the Error module. The Memory module provides the user with access to the functions used within CEETRON SAM for memory management. The Print module allows the user to redirect console output to a file. The VQuad module allows the user to operate on quadruple precision floating point variables of type VQuad.

The error facilities have been designed to minimize the overhead of error checking and to allow the use of user defined error handler functions. Conditional compilation options exist to include more extensive error checking during the software development phase which can be removed from production software for performance optimization.

Each module in CEETRON SAM contains a function to return the current error flag (type Vint) of an object. For example, to return the error flag for a Contour object, use vis_ContourError() as follows.

Vint errorflag;
errorflag  = vis_ContourError (contour);

When an error is detected by an object, the object error flag is set to the appropriate error flag value. When the error query function (eg. vis_ContourError()) is called, the current error flag is returned and the flag is reset to SYS_ERROR_NONE. Possible error flags are the following,

SYS_ERROR_NONE

No error recorded. This value is zero

SYS_ERROR_VALUE

Argument with an improper value

SYS_ERROR_ENUM

Argument is not a valid option

SYS_ERROR_OBJECTTYPE

Argument is not a valid object type

SYS_ERROR_MEMORY

Memory allocation failure

SYS_ERROR_NULLOBJECT

A NULL object pointer has been encountered

SYS_ERROR_FILE

Argument is not a valid file name

SYS_ERROR_COMPUTE

A compute error has occurred

SYS_ERROR_OPERATION

An operation is illegal in current state

SYS_ERROR_OVERFLOW

A data structure overflow has occurred

SYS_ERROR_UNDERFLOW

A data structure underflow has occurred

SYS_ERROR_UNKNOWN

An error of unknown type has occurred

SYS_ERROR_FORMAT

Improper or incomplete file format or contents

SYS_ERROR_SEVERE

Severe internal error has occurred

SYS_ERROR_LICENSE

Failure when checking License

Also, each CEETRON SAM component library defines error flags, such as the VisTools error flag VIS_ERROR_ENUM, which have the same meaning and value as the related system error flags.

The Error module performs the error handling tasks. The default error handler prints error information to standard output. The user may install a custom error handler. Also the Error module can be used to return a descriptive string corresponding to a given error flag.

Error checking within an object can be a performance consideration when a function may be called literally hundreds of millions of times. This is most likely the case in query functions which may be retrieving data from the private data of an object. In this case the user may define VKI_CHECK_ERRS at compile time to include error checking code during the software development phase which can be removed from production software when it can be shown that functions of interest are used error free. In summary, the compile time definitions related to error checking are the following.

VKI_CHECK_ERRS - Include additional error checking

3.1. Error Handling - Error

The Error module is not an object module in the sense that it supports the instancing of multiple objects. Instead, the Error module represents a single system wide data structure which is used by all CEETRON SAM objects and perhaps user code when calling an error handler. Functions exist to install a user defined error handler or a default CEETRON SAM error handler. For convenience, a user defined error pointer may also be installed and queried. The information passed to the error handler is the name of the calling function, the error flag and a message string.

The Error module supports the following functions.

Use vut_ErrorSetHandler() to install a user defined error handler. The function vut_ErrorHandler() is the default installed error handler. It simply prints the error information to standard output. The function vut_ErrorCall() calls the installed error handler. Any CEETRON SAM module calls vut_ErrorCall() internally when an error is detected. Of course the user may call vut_ErrorCall() if it is desired to use the Error module in the host application error system.

3.2. Function Descriptions

The currently available Error functions are described in detail in this section.

void vut_ErrorSetHandler(void (*func)(const Vchar*, Vint, const Vchar*))

install a pointer to the error handler

Install a pointer to a user defined error handler function. If a NULL pointer is passed, the default function vut_ErrorHandler() is installed. Please see vut_ErrorHandler() for a description of the arguments to the error handler.

Parameters:

func – Pointer to error handler

void vut_ErrorGetHandler(void (**func)(const Vchar*, Vint, const Vchar*))

query pointer to the current error handler

Query for the pointer to the current error handler function. Set a user defined error handler using vut_ErrorSetHandler().

Parameters:

func – [out] Pointer to error handler

void vut_ErrorSetObject(Vobject *object)

set a pointer to the error object

Install a pointer to a user defined error object. Query for the current user defined object pointer using vut_ErrorGetObject().

Parameters:

object – Pointer to user defined object

void vut_ErrorGetObject(Vobject **object)

get pointer to the current error object

Query for the current user defined object pointer. Install a pointer to a user defined error object using vut_ErrorSetObject().

Parameters:

object – [out] Pointer to user defined object

void vut_ErrorCall(const Vchar *funcname, Vint errorflag, const Vchar *message)

call installed error handler

The function passes the input arguments to the installed error handler.

To invoke the default error handler directly call 

void vut_ErrorHandler (const Vchar *funcname,
                       Vint errorflag,
                       const Vchar *message)
The default error handler prints the name of the calling function, the integer error flag and the message string to standard output. Note that standard output may be redirected to a file descriptor using the Print module function vut_PrintSetFile(). If the message string is a NULL or an empty string, then the descriptive error string is printed.

Parameters:

  • funcname – Name of calling function

  • errorflag – Error flag

  • message – Message string

Vchar *vut_ErrorString(Vint errorflag)

return a descriptive error string

Return a pointer to a descriptive error string associated with the error flag, errorflag. If errorflag is not a valid error flag, then NULL is returned. Do not attempt to free the string returned by this function.

Parameters:

errorflag – Error flag

Returns:

The function returns a pointer to the descriptive string associated with the error flag, errorflag.

3.3. License Check - License

The License module is not an object module in the sense that it supports the instancing of multiple objects. Instead, the License module represents a single system used by the user to validate the CEETRON SAM license or to query information about its duration and enabled features.

The License module supports the following functions.

Use vsy_LicenseValidate() to install a valid CEETRON SAM License. The function vsy_LicenseValidate() must be called before any call to the SAM products.

3.4. Function Descriptions

The currently available License functions are described in detail in this section.

void vsy_LicenseValidate(const Vchar *licenseKey)

Initialize and verify License for CEETRON Products.

This method must to be called before calling any other method from the CEETRON suite.

Parameters:

licenseKey – Valid Hoops License for CEETRON Products

void vsy_LicenseRelease()

Release the license.

After invoking this method, any further interaction with CEETRON SAM will proceed as if no license has been previously validated and the program will terminate with a License Error.

void vsy_LicenseIsValid(Vint *isValidFlag)

Check for validity of license key for CEETRON Products.

The flag will return 1 for a valid license. 0 for invalid license. In order to know, which products the current license support please referer to method vsy_LicenseHasMesh, vsy_LicenseHasSolve, vsy_LicenseHasAccess.

Parameters:

isValidFlag – [out] Flag indicating if the license is valid or not.

void vsy_LicenseHasExpired(Vint *hasExpiredFlag)

Tells if license has expired.

The flag will return 1 for a expired license. 0 otherwise.

Parameters:

hasExpiredFlag – [out] Flag indicating if the license is expired or not.

void vsy_LicenseIsPerpetual(Vint *isPerpetualFlag)

Tells if license is perpetual.

The flag will return 1 for a perpetual license. 0 otherwise.

Parameters:

isPerpetualFlag – [out] Flag indicating if the license is perpetual or not.

void vsy_LicenseHasMesh(Vint *hasMesh)

Tells the current valid license holds support for CEETRON Mesh.

The flag will return 1 for a true and 0 otherwise.

Parameters:

hasMesh – [out] Flag indicating if the license support CEETRON Mesh.

void vsy_LicenseHasAccess(Vint *hasAccess)

Tells the current valid license holds support for CEETRON Access.

The flag will return 1 for a true and 0 otherwise.

Parameters:

hasAccess – [out] Flag indicating if the license support CEETRON Access.

void vsy_LicenseHasSolve(Vint *hasSolve)

Tells the current valid license holds support for CEETRON Solve.

The flag will return 1 for a true and 0 otherwise.

Parameters:

hasSolve – [out] Flag indicating if the license support CEETRON Solve.

void vsy_LicenseCustomerName(Vchar **customerName, Vint *customerNameSize)

Retrieve the customer name associated to the License.

This method takes a the double pointer to a Vchar in order to make it point to the current internal allocated customerName.

Parameters:

  • customerName – [out] Retrieve the customer name associated to the License

  • customerNameSize – [out] Retrieve the size of the string

void vsy_LicenseExpiryDate(Vchar **expiryDate, Vint *expiryDataSize)

Retrieve the expiry date of the current license.

This method takes the double pointer to a VChar in order to make it point to the current internal expiry date.

Parameters:

  • expiryDate – [out] Expiry date of the current license

  • expiryDataSize – [out] The size of the string

3.5. Memory System - Memory

Like the Error module, the Memory module is not an object module in the sense that it supports the instancing of multiple objects. Instead, the Memory module represents a single system wide data structure which is used by all CEETRON SAM objects and perhaps user code when managing memory resources.

By default, CEETRON SAM performs all memory management through the C language system functions malloc, realloc and free. Each of these three basic memory functions is wrapped by a Memory module function with an identical prototype. CEETRON SAM modules then access the underlying malloc, realloc and free system functions through these wrapper functions. The user may install replacements for the basic malloc, realloc and free functions called within the Memory module if desired.

If the Memory module is compiled using VKI_CHECK_MEM, then the memory system perform memory protection and checking functions. In addtion, if the Memory module is compiled using VKI_CHECK_MEMSTATS, the memory system will compute memory statistics which the user may query. These features are only available if user has not installed functions for malloc, realloc and free.

The Memory module supports the following functions.

Use vut_MemorySetFunctions() to install user defined basic memory functions. The functions vut_MemoryMalloc(), vut_MemoryRealloc() and vut_MemoryFree() invoke the current basic memory functions. Use vut_MemoryStatistics() to return the current memory management statistics.

3.6. Function Descriptions

The currently available Memory functions are described in detail in this section.

void vut_MemorySetFunctions(void *(*mfun)(size_t), void *(*rfun)(void*, size_t), void (*ffun)(void*))

install malloc, realloc and free functions

Install a pointer to user defined malloc, realloc and free memory functions. If a NULL pointer is passed for a particular function, the default function is installed. By default the C language library functions malloc, realloc and free are installed.

Parameters:

  • mfun – Pointer to malloc function

  • rfun – Pointer to realloc function

  • ffun – Pointer to free function

void vut_MemoryStatistics(size_t *cursize, size_t *msize, Vint *nmalloc, Vint *nrealloc, Vint *nfree)

query for memory system statistics

Return memory management statistics. These statistics will be returned as zeros if not compiled with VKI_CHECK_MEM and VKI_CHECK_MEMSTATS

Parameters:

  • cursize – [out] Current memory allocated in bytes.

  • msize – [out] Maximum memory allocated in bytes.

  • nmalloc – [out] Number of vut_MemoryMalloc calls

  • nrealloc – [out] Number of vut_MemoryRealloc calls

  • nfree – [out] Number of vut_MemoryFree calls

void *vut_MemoryMalloc(size_t bytes)

call memory functions

These functions call the basic C language free, malloc and realloc C language library functions or user defined free, realloc and malloc functions installed using vut_MemorySetFunctions().

Parameters:

bytes – Number of bytes of memory to allocate

void *vut_MemoryRealloc(void *ptr, size_t bytes)

call memory functions

These functions call the basic C language free, malloc and realloc C language library functions or user defined free, realloc and malloc functions installed using vut_MemorySetFunctions().

Parameters:

  • ptr – Pointer to memory to be freed or realloced

  • bytes – Number of bytes of memory to allocate

void vut_MemoryFree(void *ptr)

call memory functions

These functions call the basic C language free, malloc and realloc C language library functions or user defined free, realloc and malloc functions installed using vut_MemorySetFunctions().

3.7. Standard Output - Print

Like the Error module, the Print module is not an object module in the sense that it supports the instancing of multiple objects. Instead, the Print module manages a single system wide data file descriptor which is used by all CEETRON SAM objects for directing printing to the console.

By default, the file descriptor (type FILE*), used by CEETRON SAM is stdout. The user may install an alternative file descriptor if desired. This is useful when building Microsoft Windows applications in which a console does not exist by default.

The Print module supports the following functions.

3.8. Function Descriptions

The currently available Print functions are described in detail in this section.

void vut_PrintSetFile(FILE *fd)

install printing file descriptor

Install a file descriptor which will be used for all printing in DevTools. If a fd NULL pointer is passed, the default file descriptor is installed. By default the C language library file descriptor stdout is installed.

Parameters:

fd – Print to file descriptor

void vut_PrintSetPath(Vchar *path)

install printing file path

Install a file descriptor associated with path which will be used for all printing in DevTools. If path is not NULL, a file descriptor to the path name will be opened and installed. If a path NULL pointer is passed, the current file descriptor is closed and the default file descriptor is installed. By default the C language library file descriptor stdout is installed.

Parameters:

path – Print to file path

3.9. Quadruple Precision - VQuad

Like the Error module, the VQuad module is not an object module in the sense that it supports the instancing of multiple objects. Instead, the VQuad module comprises a set of functions that operate on 128-bit quadruple-precision floating-point variables.

Quadruple precision variables are declared with the VQuad data type. Operators such as +, -, *, etc. are not defined for this data type. Instead, all operations are performed via VQuad functions.

The VQuad module supports the following functions.

3.10. Function Descriptions

The currently available VQuad functions are described in detail in this section.

void vut_VQuadPrintf(Vquad f, Vint width, Vint signflag, Vint *ierr)

prints variable to console

Same as vut_VQuadSPrintf() except that rather than a string the output goes to the console. Console output can be redirected using the Print module.

Parameters:

  • f – Quadruple precision variable to be printed

  • width – Width of output field

  • signflag – Flag for printed positive sign

  • ierr – [out] Error, if any

void vut_VQuadSPrintf(Vquad f, Vint width, Vint signflag, Vchar buf[], Vint *ierr)

prints variable to a string

Prints the value of the quadruple precision variable f onto the string buf. width and sign are borrowed from the C language. They describe the total field’s width and whether to print a + sign for positive numbers, respectively.

If width is less than 9 or if an arithmetic error occurs during the print operation then ierr is set to 1. Otherwise it is set to 0.

Parameters:

  • f – Quadruple precision variable to be printed

  • width – Width of output field

  • signflag – Flag for printed positive sign

  • buf – The output string

  • ierr – [out] Error, if any

Vquad vut_VQuadLoad(Vdouble a)

loads a Vdouble into a Vquad

Casts a double precision floating point number into a quadruple precision variable. Since a double precision variable can always be written in quadruple precision this operation is always successful.

Parameters:

a – Double precision variable to be loaded

Returns:

The function value is the loaded quadruple precision variable

Vdouble vut_VQuadStore(Vquad a, Vint *ierr)

stores a Vquad into a Vdouble

Casts a quadruple precision floating point number into a double precision variable. If the quadruple precision variable is too large such that the double precision variable would overflow ierr is set to 1. Otherwise it is set to 0.

Parameters:

  • a – Quadruple precision variable to be stored

  • ierr – [out] Error, if any

Returns:

The function value is the stored double precision variable

Vint vut_VQuadEQ(Vquad a, Vquad b)

checks for Vquad a == Vquad b

Checks for equality two quadruple precision numbers a and b.

Parameters:

  • a – First number to compare

  • b – Second number to compare

Returns:

The function value is set to 1 if a and b are equal and to 0 otherwise.

Vint vut_VQuadGT(Vquad a, Vquad b)

checks for Vquad a > Vquad b

Checks whether a is greater than b.

Parameters:

  • a – First number to compare

  • b – Second number to compare

Returns:

The function value is set to 1 if a is greater than b and to 0 otherwise.

Vint vut_VQuadGE(Vquad a, Vquad b)

checks for Vquad a >= Vquad b

Checks whether a is greater to or equal to b.

Parameters:

  • a – First number to compare

  • b – Second number to compare

Returns:

The function value is set to 1 if a is greater than or equal to b and to 0 otherwise.

Vint vut_VQuadLT(Vquad a, Vquad b)

checks for Vquad a < Vquad b

Checks whether a is less than b

Parameters:

  • a – First number to compare

  • b – Second number to compare

Returns:

The function value is set to 1 if a is less than b and to 0 otherwise.

Vint vut_VQuadLE(Vquad a, Vquad b)

checks for Vquad a <= Vquad b

Checks whether a is less than or equal to b.

Parameters:

  • a – First number to compare

  • b – Second number to compare

Returns:

The function value is set to 1 if a is less than or equal to b and to 0 otherwise.

Vquad vut_VQuadAdd(Vquad a, Vquad b, Vint *ierr)

performs Vquad a + Vquad b

Adds two quadruple precision numbers. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.

Parameters:

  • a – First number to be added

  • b – Second number to be added

  • ierr – Error, if any

Returns:

The function value is set to the quadruple precision number that is the sum of a and b.

Vquad vut_VQuadSub(Vquad a, Vquad b, Vint *ierr)

performs Vquad a - Vquad b

Subtracts two quadruple precision numbers. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.

Parameters:

  • a – Number to be added

  • b – Number to be subtracted

  • ierr – [out] Error, if any

Returns:

The function value is set to the quadruple precision number that is the sum of a and b.

Vquad vut_VQuadMult(Vquad a, Vquad b, Vint *ierr)

performs Vquad a * Vquad b

Multiplies two quadruple precision numbers. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.

Parameters:

  • a – First multiplier

  • b – Second multiplier

  • ierr – [out] Error, if any

Returns:

The function value is set to the quadruple precision number that is the product of a and b.

Vquad vut_VQuadDiv(Vquad a, Vquad b, Vint *ierr)

performs Vquad a / Vquad b

Divides two quadruple precision numbers. If the result overflows or if the denominator is zero then ierr is set to 1. Otherwise, it is set to 0.

Parameters:

  • a – Numerator

  • b – Denominator

  • ierr – [out] Error, if any

Returns:

The function value is set to the quadruple precision number that is the division of a by b.

Vquad vut_VQuadSqrt(Vquad a, Vint *ierr)

performs sqrt(Vquad a)

Takes the square root of a quadruple precision number. If a is negative ierr is set to 1. Otherwise it is set to 0.

Parameters:

  • a – Number whose square root is needed

  • ierr – [out] Error, if any

Returns:

The function value is set to the square root of the quadruple precision number a provided.

Vquad vut_VQuadHalf(Vquad a)

performs (Vquad a)/2

Divides a quadruple precision number by 2.

Parameters:

a – Number whose half is requested

Returns:

The function value is set to the quadruple precision number that is half of a.

Vquad vut_VQuadNeg(Vquad a)

checks for Vquad a <= Vquad b

Takes the negative of a quadruple precision number.

Parameters:

a – Number whose negative is needed

Returns:

The function value is set to the negative of quadruple precision number a provided.

Vquad vut_VQuadDot3(Vquad a[3], Vquad b[3], Vint *ierr)

dot product of two 3-vectors

Takes the dot product of vectors a and b. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.

Parameters:

  • a – First vector

  • b – Second vector

  • ierr – [out] Error, if any

Returns:

The function value is set to the quadruple precision number that is the dot product between vectors a and b.

void vut_VQuadCross3(Vquad a[3], Vquad b[3], Vquad c[3], Vint *ierr)

cross product of two 3-vectors

Takes the cross product of vectors a and b. If any component of the result overflows then ierr is set to 1. Otherwise, it is set to 0.

Parameters:

  • a – First vector

  • b – Second vector

  • c – [out] Cross product of a and b.

  • ierr – [out] Error, if any

void vut_VQuadScale3(Vquad a[3], Vquad s, Vquad b[3], Vint *ierr)

scales a 3-vector

Scales vector a by the scalar s. If any component of b overflows then ierr is set to 1. Otherwise, it is set to 0.

Parameters:

  • a – Vector to be scaled

  • s – Scalar value

  • b – [out] The scaled vector

  • ierr – [out] Error, if any

Vquad vut_VQuadMag3(Vquad a[3], Vint *ierr)

computes the magnitude of a 3-vector

Computes the magnitude of vector a. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.

Parameters:

  • a – Vector whose magnitude is required

  • ierr – [out] Error, if any

Returns:

The function value is set to the quadruple precision number that is the magnitude of vector a.

void vut_VQuadUnit3(Vquad a[3], Vint *ierr)

scales a 3-vector to a unit 3-vector

Scales vector a into a unit vector.

Parameters:

  • a – [inout] Vector whose unit is requested

  • ierr – [out] Error, if any

Vquad vut_VQuadAbs(Vquad a)

performs ABS(Vquad a)

Takes the absolute value of a quadruple precision number.

Parameters:

a – Number whose absolute value is required

Returns:

The function value is set to the quadruple precision number that is the absolute value of a.