Developer Info#

Introduction#

This section provides developers with additional context and information for developing their own applications using the Handel API.

Language Interface#

Handel is supported for calls from other C programs or libraries. XIA does not officially support other language interfaces such as Visual Basic or Fortran, but we provide sample C# interop definitions in the examples folder of the source distribution.

Header Files#

Note

This section assumes you are using the Handel libraries in a C or C++ programming environment.

handel.h is the main header file for the Handel libraries and should be included in every source file that calls a Handel library function. This header contains prototypes for all of the exported Handel functions and some useful constants.

handel_errors.h contains all of the error codes and a short comment describing the meaning of each error code. The constants in this file can be used to create descriptive error handling in source code. For instance:

#include "handel.h"
#include "handel_errors.h"

int status;
status = xiaInitHandel();

else if (status == XIA_NOMEM) {
    printf("Out-of-memory!\n");
}
else if (status == XIA_SUCCESS) {
    printf("Success!\n");
}

If you choose not to interpret all possible returned error values, XIA highly recommends at least checking the returned status against the constant XIA_SUCCESS. All of the routines in Handel follow the standard of returning an integer value indicating the success or failure of the routine.

int status;
status = xiaInitHandel();
if (status != XIA_SUCCESS) {
    printf("ERROR = %d\n", status);
    abort();
}

status = xiaStartSystem();
if (status != XIA_SUCCESS) {
    printf("ERROR = %d\n", status);
    abort();
}

Warning

Handel may not be in a consistent state if a routine fails. If execution continues with the next Handel call, the behavior will be indeterminate and may result in unexpected application errors

handeldef.h defines HANDEL_IMPORT, which is used in handel.h to define the API routines. This file does not need to be included directly since handel.h includes it, but it does need to be in the same directory as your other Handel header files.

handel_generic.h defines constants like MAXALIAS_LEN, used for allocating memory to pass to Handel routines.

Include md_generic.h if you are going to use the constants associated with xiaSetLogLevel(): MD_ERROR, MD_WARNING, MD_INFO, and MD_DEBUG.

Linking#

Handel is built as a shared library. Both the ProSpect SDK and the Handel binary distribution provide the necessary import libraries and headers for linking the libraries directly into your application. Similarly, building Handel using the source release ensures that the necessary import libraries will be created.

Integer Functions#

If successful, all Handel routines return XIA_SUCCESS, otherwise they return a status code indicating a problem (see handel_errors.h for error codes). In addition, all routines that sense an error print a message to either stdout (the default setting) or to the stream indicated by a call to xiaSetLogOutput(). This has the effect of producing a trace-back for identifying where a problem occurred.

Word Size#

Handel APIs use standard integer types, not fixed width integer types. When interfacing to the driver library from languages other than C, the user must be careful to match the length of variable types across compilers.

For the x86 architecture, the word size is as follows:

  • short/unsigned short = 2 bytes

  • int/unsigned int = 4 bytes long/unsigned

  • long = 4 bytes

DSP parameters are of length 2 bytes.

Searching For Files#

Handel follows a standard search procedure when trying to find a file specified by the user:

  1. Attempt to open the file in the current directory.

  2. Attempt to open the file in the directory pointed to by the environment variable XIAHOME.

  3. Attempt to open the file in the directory pointed to by the environment variable DXPHOME. (This is only for backwards compatibility with previous XIA libraries and should not be used.)

  4. Interpret the filename as an environment variable that points to a different file.

  5. Interpret the filename as an environment variable that points to a different file located in the directory pointed to by the environment variable XIAHOME.

  6. Interpret the filename as an environment variable that points to a different file located in the directory pointed to by DXPHOME.

If all of the search steps fail then an error is returned.