Library initialization, error handling, loggging and a few minor libc extensions. More...

Detailed Description

Library initialization, error handling, loggging and a few minor libc extensions.

Data Structures
struct	DasBuf
	Little buffer class to handle accumulating string data. More...

struct	das_error_msg
	Structure returned from das_get_error(). More...

Macros
#define	daslog_trace(M) daslog(DASLOG_TRACE, __FILE__, __LINE__, M)
	Macro wrapper around das_log() for TRACE messages with out variable args.

#define	daslog_debug(M) daslog(DASLOG_DEBUG, __FILE__, __LINE__, M)
	Macro wrapper around das_log() for DEBUG messages with out variable args.

#define	daslog_info(M) daslog(DASLOG_INFO, __FILE__, __LINE__, M)
	Macro wrapper around das_log() for INFO messages with out variable args.

#define	daslog_warn(M) daslog(DASLOG_WARN, __FILE__, __LINE__, M)
	Macro wrapper around das_log() for WARNING messages with out variable args.

#define	daslog_error(M) daslog(DASLOG_ERROR, __FILE__, __LINE__, M)
	Macro wrapper around das_log() for ERROR messages with out variable args.

#define	daslog_critical(M) daslog(DAS_LL_CRITICAL, __FILE__, __LINE__, M)
	Macro wrapper around das_log() for CRITICAL messages with out variable args.

#define	daslog_trace_v(F,...) daslog(DASLOG_TRACE, __FILE__, __LINE__, F, __VA_ARGS__)
	Macro wrapper around das_log() for TRACE messages with variable arguments.

#define	daslog_debug_v(F,...) daslog(DASLOG_DEBUG, __FILE__, __LINE__, F, __VA_ARGS__)
	Macro wrapper around das_log() for DEBUG messages with variable arguments.

#define	daslog_info_v(F,...) daslog(DASLOG_INFO, __FILE__, __LINE__, F, __VA_ARGS__)
	Macro wrapper around das_log() for INFO messages with variable arguments.

#define	daslog_warn_v(F,...) daslog(DASLOG_WARN, __FILE__, __LINE__, F, __VA_ARGS__)
	Macro wrapper around das_log() for WARNING messages with variable arguments.

#define	daslog_error_v(F,...) daslog(DASLOG_ERROR, __FILE__, __LINE__, F, __VA_ARGS__)
	Macro wrapper around das_log() for ERROR messages with variable arguments.

#define	daslog_critical_v(F,...) daslog(DASLOG_CRIT, __FILE__, __LINE__, F, __VA_ARGS__)
	Macro wrapper around das_log() for CRITICAL messages with variable arguments.

#define	DAS_OKAY 0
	success return code

#define	DASERR_DIS_EXIT 0
	Used to indicate that errors should trigger program exit.

#define	DASERR_DIS_RET 1
	Used to indicate that errors should trigger library functions to return error values.

#define	DASERR_DIS_ABORT 43
	Used to indicate that errors should trigger program abort with a core dump.

#define	das_error(nErrCode,...) das_error_func(__FILE__, __func__, __LINE__, nErrCode, __VA_ARGS__ )
	Signal an error condition. More...

#define	das_within(A, B, E) (fabs(A - B) < E ? true : false)
	Check to see if two floating point values are within an epsilon of each other.

#define	DAS_XML_MAXPROPS 400
	limit of number of properties per descriptor. More...

#define	DAS_XML_BUF_LEN 1000000
	The limit on xml packet length, in bytes. More...

#define	DAS_XML_NODE_NAME_LEN 256
	The limit of xml element name length, in bytes. More...

Typedefs
typedef int	DasErrCode
	return code type 0 indicates success, negative integer indicates failure

typedef void(*	das_log_handler_t )(int nLevel, const char *sMsg, bool bPrnTime)
	Definition of a message handler function pointer. More...

Functions
int	daslog_level (void)
	Get the log level. More...

int	daslog_setlevel (int nLevel)
	Set the logging level for this thread. More...

bool	daslog_set_showline (int nLevel)
	Output source file and line numbers for messages at or above this level.

das_log_handler_t	daslog_sethandler (das_log_handler_t new_handler)
	Install a new message handler function for this thread. More...

void	das_init (const char *sProgName, int nErrDis, int nErrBufSz, int nLevel, das_log_handler_t logfunc)
	Initialize any global structures in the Das2 library. More...

void	das_abort_on_error (void)
	Error handling: Trigger Core Dumps. More...

void	das_exit_on_error (void)
	Error handling: Normal Exit Set the library to call exit(ErrorCode) when a problem is detected. More...

void	das_return_on_error (void)
	Error handling: Normal Return Set the library to return normally to the calling function with a return value that indicates a problem has occurred. More...

int	das_error_disposition (void)
	Error handling: get the library's error disposition. More...

void	das_print_error (void)
	Error handling: Print formatted error to standard error stream Set the library to ouput formatted error messages to the processes standard error stream. More...

bool	das_save_error (int maxmsg)
	Error handling: Save formatted error in a message buffer. More...

const char *	das_lib_version (void)
	Get the library version. More...

bool	das_assert_valid_id (const char *sId)
	Check that a string is suitable for use as an object ID. More...

void	das_store_str (char *psDest, size_t puLen, const char *sSrc)
	Store string in a buffer that is reallocated if need be. More...

char *	das_string (const char *fmt,...)
	Allocate a new string on the heap and format it. More...

char *	das_strdup (const char *sIn)
	Copy a string into a new buffer allocated on the heap. More...

char *	das_vstring (const char *fmt, va_list ap)
	Store a formatted string in a newly allocated buffer. More...

bool	das_isdir (const char *path)
	Is the path a directory. More...

bool	das_isfile (const char *path)
	Is the path a file. More...

int	das_dirlist (const char *sPath, char ppDirList[][256], size_t uMaxDirs, char cType)
	Get a sorted directory listing. More...

das_error_msg *	das_get_error (void)
	Return the saved das2 error message buffer. More...

void	das_error_free (das_error_msg *pMsg)
	Free an error message structure allocated on the heap. More...

Macro Definition Documentation

#define das_error	(	nErrCode,
		...
	)	das_error_func(__FILE__, __func__, __LINE__, nErrCode, __VA_ARGS__ )

Signal an error condition.

This routine is called throughout the code when an error condition arrises.

The default handler for error conditions prints the message provided to the standard error channel and then calls exit(nErrCode). To have the library call your handler instead use the das_set_error_handler() function. To have the library abort with a core dump on an error use das_abort_on_error().

Each source file in the code has it's own error code. Though it's probably not that useful to end users, the codes are provided here:

8 : Not yet implemented - DASERR_NOTIMP
9 : Assertion Failures - DASERR_ASSERT
10 : das1.c - D1ERR
11 : Lib initialization errors - DASERR_INIT
12 : buffer.c - DASERR_BUF
13 : util.c - DASERR_UTIL
14 : encoding.c - DASERR_ENC
15 : units.c - DASERR_UNITS
16 : descriptor.c - DASERR_DESC
17 : plane.c - DASERR_PLANE
18 : packet.c - DASERR_PKT
19 : stream.c - DASERR_STREAM
20 : oob.c - DASERR_OOB
21 : io.c - DASERR_IO
22 : dsdf.c - DASERR_DSDF
23 : dft.c - DASERR_DFT
24 : log.c - DASERR_LOG
25 : array.c - DASERR_ARRAY
26 : variable.c - DASERR_VAR
27 : dimension.c - DASERR_DIM
28 : dataset.c - DASERR_DS
29 : builder.c - DASERR_BLDR
30 : http.c - DASERR_HTTP
31 : datum.c - DASERR_DATUM
32 : value.c - DASERR_VALUE
34 : operater.c - DASERR_OP
35 : credentials.c - DASERR_CRED
36 : catalog.c - DASERR_CAT

Application programs are recommended to use values 64 and above to avoid colliding with future das2 error codes.

Parameters

nErrCode The value to return to the shell, should be one of the above.

Returns: By default this function never returns but if the libdas2 error disposition has been set to DAS2_ERRDIS_RET then the value of nErrCode is returned.

#define DAS_XML_MAXPROPS 400

limit of number of properties per descriptor.

#define DAS_XML_BUF_LEN 1000000

The limit on xml packet length, in bytes.

(ascii encoding.)

#define DAS_XML_NODE_NAME_LEN 256

The limit of xml element name length, in bytes.

Typedef Documentation

typedef void(* das_log_handler_t)(int nLevel, const char *sMsg, bool bPrnTime)

Definition of a message handler function pointer.

Message handlers need to be prepared for any of the string pointers sMsg, sDataStatus, or sStackTrace to be null.

Parameters

nLevel	The message level. If nLevel is equal to or greater than das_log_getlevel() then the message should be logged.
sMsg	The message, usually not null.
bPrnTime	The current system time should be included in the log output.

Function Documentation

int daslog_level ( void )

Get the log level.

Returns: one of: DAS_LL_CRIT, DAS_LL_ERROR, DAS_LL_WARN, DAS_LL_INFO, DAS_LL_DEBUG, DAS_LL_TRACE

int daslog_setlevel ( int nLevel )

Set the logging level for this thread.

Parameters

nLevel

Set to one of

DASLOG_TRACE
DASLOG_DEBUG
DASLOG_NOTICE
DASLOG_WARN
DASLOG_ERROR
DASLOG_CRITICAL
DASLOG_NOTHING

Returns: The previous log level.

das_log_handler_t daslog_sethandler ( das_log_handler_t new_handler )

Install a new message handler function for this thread.

The default message handler just prints to stderr, which is not very effecient, nor is it appropriate for GUI applications.

Parameters

new_handler The new message handler, or NULL to set to the default handler.

Returns: The previous message handler function pointer

void das_init	(	const char *	sProgName,
		int	nErrDis,
		int	nErrBufSz,
		int	nLevel,
		das_log_handler_t	logfunc
	)

Initialize any global structures in the Das2 library.

This should be the first function your program calls before using any libdas2 functions. In general libdas2 tries to avoid global structures but does use them in three areas:

Error and log handling - Since the error and logging disposition should be the same for all library calls handlers are set here
Unit conversions - Since das_unit varibles should be comparible using a simple equality test, a global registry of const char pointers is needed
FFTW plan mutexes - Since the FFTW library unfortunatly uses global plan memory
OpenSSL Contex mutexes - The openssl library contex cannot be changed by multiple threads at the same time, a mutex is setup to prevent this from happening

This function initializes defaults for the items above.

Parameters

sProgName	The name of the program using the library. Used in some error messages.
nErrDis	Set the behavior the library takes when an error is encountered. May be one of DASERR_DIS_EXIT, call exit() when an error occurs; DASERR_DIS_RET, return with an error code; or DASERR_DIS_ABORT, call abort(). The value of DASERR_DIS_EXIT is 0 so you can use that for the default behavior. If DASERR_DIS_RET is used, the function das_get_error() can be used to retrieve the most recent error message.
nErrBufSz	If not zero, a global error message buffer will be allocated that is this many bytes long and error message will be saved into the buffer instead of being sent to the standard error channel. Messages can be retrieved via das_get_error(). If zero, these will be send to the standard error channel as soon as they occur. Saving errors is only useful if the error disposition is DAS2_ERRDIS_RET as otherwise the program exits before the message can be output.
nLevel	Set the logging level to one of, DASLOG_TRACE, DASLOG_DEBUG, DASLOG_NOTICE, DASLOG_WARN, DASLOG_ERROR, DASLOG_CRITICAL.
logfunc	A callback for handling log messages. The callback need not be thread safe as it will only be triggered inside mutual exclusion (mutex) locks. If NULL messages are printed to the stardard error channel.

The error disposition does not affect any errors that are encountered within das_init. Errors should not occur during initialization, any that do trigger a call to exit()

void das_abort_on_error ( void )

Error handling: Trigger Core Dumps.

Call this function to have the library exit via an abort() call instead of using exit(ErrorCode). On most systems this will trigger the generation of a core file that can be used for debugging.

Warning: : Calling this function prevents open file handles from being flushed to disk which will typically result in corrupted output.

void das_exit_on_error ( void )

Error handling: Normal Exit Set the library to call exit(ErrorCode) when a problem is detected.

This is usually what you want and the library's default setting.

void das_return_on_error ( void )

Error handling: Normal Return Set the library to return normally to the calling function with a return value that indicates a problem has occurred.

This will be the new default, but is not yet tested.

int das_error_disposition ( void )

Error handling: get the library's error disposition.

Returns

one of the following integers:

DAS2_ERRDIS_EXIT - Library exits when there is a problem
DAS2_ERRDIS_ABORT - Library aborts, possibly with core dump on a problem
DAS2_ERRDIS_RET - Library returns normally with an error code

void das_print_error ( void )

Error handling: Print formatted error to standard error stream Set the library to ouput formatted error messages to the processes standard error stream.

This is the default.

bool das_save_error ( int maxmsg )

Error handling: Save formatted error in a message buffer.

Set the library to save formatted error message to a message buffer.

Parameters

maxmsg maximum message size. The buffer created will be maxmsg in length, meaning any formatted messages longer than the available buffer size will be truncated to maxmsg-1

Returns: true if error buffer setup was successful, false otherwise.

const char* das_lib_version ( void )

Get the library version.

Returns: the version tag string for the das2 core library, or the string "untagged" if the version is unknown

bool das_assert_valid_id ( const char * sId )

Check that a string is suitable for use as an object ID.

Object ID strings are ascii strings using only characters from the set a-z, A-Z, 0-9, and _. They do not start with a number. They are no more than 63 bytes long. Basically they can be used as variable names in most programming languages.

If the das_error_disposition is set to exit this function never returns.

Parameters

sId

Returns: True if the string can be used as an ID, false otherwise.

void das_store_str	(	char **	psDest,
		size_t *	puLen,
		const char *	sSrc
	)

Store string in a buffer that is reallocated if need be.

Parameters

psDest	a pointer to the storage location
puLen	a pointer to the size of the storage location
sSrc	the source string to store.

char* das_string	(	const char *	fmt,
			...
	)

Allocate a new string on the heap and format it.

Except for using das_error on a failure, this is a copy of the code out of man 3 printf on Linux.

Returns: A pointer to the newly allocated and formatted string on the heap, or NULL if the function failed and the das2 error disposition allows for continuation after a failure

char* das_strdup ( const char * sIn )

Copy a string into a new buffer allocated on the heap.

Parameters

sIn	the string to copy

Returns: a pointer to the newly allocated buffer containing the same characters as the input string or NULL if the input length was zero

char* das_vstring	(	const char *	fmt,
		va_list	ap
	)

Store a formatted string in a newly allocated buffer.

This version is suitable for calling from variable argument functions.

Except for using das_error on a failure, this is a copy of the code out of man 3 printf on Linux.

Parameters

fmt	- a printf format string
ap	A va_list list, see vfprintf or stdarg.h for details

Returns: A pointer to the newly allocated and formatted string on the heap, or NULL if the function failed and the das2 error disposition allows for continuation after a failure

bool das_isdir ( const char * path )

Is the path a directory.

Parameters

path	The directory in question, passed to stat(2)

Returns: true if path can be determined to be a directory, false otherwise

bool das_isfile ( const char * path )

Is the path a file.

Parameters

path	The file in question, passed to stat(2)

Returns: true if path can be determined to be a file, false otherwise

int das_dirlist	(	const char *	sPath,
		char	ppDirList[][256],
		size_t	uMaxDirs,
		char	cType
	)

Get a sorted directory listing.

Parameters

sPath	The path to the directory to read.
ppDirList	A pointer to a 2-D character array where the first index is the directory item and the second index is the character position. The max value of the second index must be = NAME_MAX - 1. The value NAME_MAX is defined in the POSIX header limits.h
uMaxDirs	The maximum number of directory entries that may be stored
cType	May be used to filter the items returned. If cType = 'f' only files will be return, if cType = 'd' then only directories will be returned. Any other value, including 0 will return both.

Returns: On success the number of items in the directory not counting '.' and '..' are returned, on failure a negative error code is returned. Item names are sorted before return.

das_error_msg * das_get_error ( void )

Return the saved das2 error message buffer.

Returns: an instance of Das2ErrorMessage. The struct returned contains the error code, formatted message, max message size, and the source file, function name, and line number of where the message originated.

void das_error_free ( das_error_msg * pMsg )

Free an error message structure allocated on the heap.

Parameters

pMsg	the message buffer to free

Detailed Description

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

Typedef Documentation

Function Documentation