Logging#

Handel provides a comprehensive logging and error reporting mechanism that allows an error to be traced back to a specific line of code in Handel.

By default Handel logs errors to stdout. Routines in this section allow the user to configure the output stream and increase verbosity to record additional internal information.

int xiaEnableLogOutput(void)#

Enables logging to the output stream as configured by a call to xiaSetLogOutput(). By default, logging is enabled and is directed to standard out, so you would only need to call this routine if you previously called xiaSuppressLogOutput() and wanted to re-enable logging.

Note

If Handel has not been initialized then it will be initialized silently by this routine.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_MD – Error reported by MD routine called by Handel.

Example Usage

int status;

status = xiaInitHandel();
if (status != XIA_SUCCESS) {
    /* ERROR initializing Handel */
}

/* This call is redundant since logging is enabled by default. */
status = xiaEnableLogOutput();
if (status != XIA_SUCCESS) {
    /* ERROR enabling log output */
}
int xiaSuppressLogOutput(void)#

Stops log output from being written to the current stream.

Note

If Handel has not been initialized then it will be initialized silently by this routine.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_MD – Error reported by MD routine called by Handel

Example Usage

int status;
status = xiaInitHandel();
if (status != XIA_SUCCESS) {
    /* ERROR initializing Handel */
}

status = xiaSuppressLogOutput();

if (status != XIA_SUCCESS) {
    /* ERROR suppressing log output */
}
int xiaSetLogLevel(int level)#

Sets the level of logging that will be reported to the log output stream. The levels are defined as constants in the file md_generic.h.

  • MD_DEBUG:

    All messages, including information only relevant to the developers at XIA. This level generates significantly more output and can should typically be used only if needed in debugging an issue with XIA.

  • MD_INFO:

    All messages except for debug level messages.

  • MD_WARNING:

    All warning and error messages. Warning message indicate conditions where a routine will keep executing but the user should probably fix the condition warned about. This is the most useful level of debugging since warning messages often indicate subtle user errors that aren’t catastrophic but may lead to an unexpected state.

  • MD_ERROR:

    Only messages that cause a routine to end its execution early. An error must be fixed before the routine that caused the original error is called again.

Note

If Handel has not been initialized then it will be initialized silently by this routine.

Param[in] level:

Level of logging desired. See above for discussion of allowed values.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_MD – Error reported by MD routine called by Handel

Example Usage

int status;
status = xiaInitHandel();
if (status != XIA_SUCCESS) {
    /* ERROR initializing Handel */
}

status = xiaSetLogLevel(MD_INFO);
if (status != XIA_SUCCESS) {
    /* ERROR setting log level to MD_INFO */
}
int xiaSetLogOutput(char *filename)#

Sets the output stream for the logging routines. Defaults to stdout.

The literal strings “stdout” and “stderr” redirect to the corresponding console device. All other names are opened as files.

Param[in] filename:

Name of file to redirect logging messages, or “stdout” or “stderr”.

Returns:

A status code indicating the result of the operation.

Return values:

XIA_SUCCESS – The operation completed successfully.

Example Usage

int status;
status = xiaInitHandel();
if (status != XIA_SUCCESS) {
    /* ERROR initializing Handel */
}

xiaSetLogOutput("my_log.txt");
int xiaCloseLog(void)#

Closes the logging stream. This effectively closes any open log file and redirects to stdout. Call this routine when cleaning up program resources if you set log output to a file with xiaSetLogOutput().

Returns:

A status code indicating the result of the operation.

Return values:

XIA_SUCCESS – The operation completed successfully.

char *xiaGetErrorText(int errorcode)#
Param[in] errorcode:

errorcode as returned by other Handel API functions.

Returns:

Returns the error text corresponding to specified error code.

Example Usage

printf("XIA_PRESET_VALUE_OOR    -- %s\n", xiaGetErrorText(XIA_LIVEOUTPUT_OOR));
printf("DXP_MEMORY_LENGTH       -- %s\n", xiaGetErrorText(DXP_MEMORY_LENGTH));