ToC path:

Samples Helper Functions in C

The samples/native/common directory contains several common*.c and common*.h files that define and implement helper functions used in the C API SDK samples. These functions allow the sample applications to focus on only the specific eXtremeDB functionality that the sample is intended to demonstrate by implementing outside of the main function some of the unrelated code.

The following table describes briefly the content of each file. (Note that the actual files in your package may not include all of these listed.) It is recommended that these files be examined in your development environment during testing and modification of the SDK samples. (Some functions provide a link for more detailed descriptions).

common.h / common.c (used in most samples)

MCO_RET sample_open_database( ... ) Open an in-memory or persistent database

MCO_RET sample_load_database( ... ) Load a database

MCO_RET sample_close_database( const char * db_name, sample_memory_t * pdev ) Close the specified database and free its memory

void sample_header( const char * descr ) Display the specified message descr (normally called at the beginning of a sample application to indicate the features being demonstrated)

void sample_errhandler( MCO_RET n ) Implement a simple eXtremeDB fatal error handler

void sample_pause( const char * prompt ) Display a prompt and pause the sample for user input

void sample_pause_end( const char * prompt ) For Windows applications, if in release mode, print a line, and call sample_pause()

void sample_show_runtime_info( const char * lead_line ) Display runtime information indicating which libraries are linked and which eXtremeDB features are enabled

void sample_show_device_info( const char * lead_line, mco_device_t dev[], int nDev ) Display the memory type, assignment type and file information (for persistent databases) of all memory devices

void sample_rc_check( const char * msg, MCO_RET rc ) Display "Successful" and the specified message msg or an error message if the return code rc is not MCO_S_OK

int sample_is_release() Return a non-zero value if the release libraries are linked

int sample_disk_supported() Return a non-zero value if the persistent database disk manager libraries are linked

const char * mco_ret_string( MCO_RET rc, int * is_error ) Return the error message string associated with an eXtremeDB return code and set is_error true if the code represents a non-fatal error

#define CHECK( func ) Macro to call a function and terminate the applications with an error message if an error occurs

#define CHECK_CODE( func, code ) Macro to call a function and terminate the applications with an error code and message if an error occurs

unsigned int sample_start_task( ... ) Call sample_start_connected_task() to spawn a thread

unsigned int sample_start_connected_task( ... ) Initialize the task descriptor and spawn a task (thread)

unsigned int sample_stop_task( sample_task_t * descr ) Sett the task descriptor flag stopped to cause the thread to stop

unsigned int sample_join_task( sample_task_t * descr ) Join the task (thread) pointed to by the specified descriptor

int sample_msec() Return the current system time in milliseconds

void sample_sleep( unsigned int duration_msec ) Cause the application to sleep for the specified number of milliseconds

commonSQL.h / commonSQL.c (used in SQL samples)

const char * sql_ret_string( MCO_RET rc ) Return the SQL message string corresponding to the specified return code rc

void sample_sql_rc_check(const char * msg, MCO_RET rc) Display "Successful" and the specified message msg or an SQL error message if the return code rc is not MCO_S_OK

commonha.h / commonha.c (used in High Availability samples)

#define CLEAR_PROCESS_MASKS( set ) Define macro CLEAR_PROCESS_MASKS for the current platform

#define SET_PROCESS_MASK( set, mask ) Define macro SET_PROCESS_MASKS for the current platform

void sample_HA_replica_notifying( ... ) Replica notifying procedure that simply prints replica notifications in human-readable form

commoncl.h / commoncl.c (used in Cluster samples)

int sample_cluster_parse_opts( ... ) Parse the application's argv[] argument list and set cluster parameters accordingly

void sample_cluster_print_params( mco_cluster_params_t *cl_params ) Display the Cluster runtime parameter settings

void sample_cluster_usage() Display the possible application runtime options and their meanings

initos.h / initos.c (used in most samples)

void sample_os_initialize( int req_features ) A startup function to initialize specific platform dependent features for embedded systems like VxWorks and ecos

void sample_os_shutdown() A termination function to shutdown specific platform dependent features for embedded systems like VxWorks and ecos

int main( int argc, char* argv[] ) and int main() A standardized main entry point for applications on embedded systems like VxWorks and ecos

common.h / common.c (used in most samples)
MCO_RET sample_open_database( ... )	Open an in-memory or persistent database
MCO_RET sample_load_database( ... )	Load a database
MCO_RET sample_close_database( const char * db_name, sample_memory_t * pdev )	Close the specified database and free its memory
void sample_header( const char * descr )	Display the specified message `descr` (normally called at the beginning of a sample application to indicate the features being demonstrated)
void sample_errhandler( MCO_RET n )	Implement a simple eXtremeDB fatal error handler
void sample_pause( const char * prompt )	Display a prompt and pause the sample for user input
void sample_pause_end( const char * prompt )	For Windows applications, if in release mode, print a line, and call `sample_pause()`
void sample_show_runtime_info( const char * lead_line )	Display runtime information indicating which libraries are linked and which eXtremeDB features are enabled
void sample_show_device_info( const char * lead_line, mco_device_t dev[], int nDev )	Display the memory type, assignment type and file information (for persistent databases) of all memory devices
void sample_rc_check( const char * msg, MCO_RET rc )	Display "Successful" and the specified message `msg` or an error message if the return code `rc` is not `MCO_S_OK`
int sample_is_release()	Return a non-zero value if the release libraries are linked
int sample_disk_supported()	Return a non-zero value if the persistent database disk manager libraries are linked
const char * mco_ret_string( MCO_RET rc, int * is_error )	Return the error message string associated with an eXtremeDB return code and set `is_error` true if the code represents a non-fatal error
#define CHECK( func )	Macro to call a function and terminate the applications with an error message if an error occurs
#define CHECK_CODE( func, code )	Macro to call a function and terminate the applications with an error code and message if an error occurs
unsigned int sample_start_task( ... )	Call `sample_start_connected_task()` to spawn a thread
unsigned int sample_start_connected_task( ... )	Initialize the task descriptor and spawn a task (thread)
unsigned int sample_stop_task( sample_task_t * descr )	Sett the task descriptor flag `stopped` to cause the thread to stop
unsigned int sample_join_task( sample_task_t * descr )	Join the task (thread) pointed to by the specified descriptor
int sample_msec()	Return the current system time in milliseconds
void sample_sleep( unsigned int duration_msec )	Cause the application to sleep for the specified number of milliseconds
commonSQL.h / commonSQL.c (used in SQL samples)
const char * sql_ret_string( MCO_RET rc )	Return the SQL message string corresponding to the specified return code `rc`
void sample_sql_rc_check(const char * msg, MCO_RET rc)	Display "Successful" and the specified message `msg` or an SQL error message if the return code `rc` is not `MCO_S_OK`
commonha.h / commonha.c (used in High Availability samples)
#define CLEAR_PROCESS_MASKS( set )	Define macro `CLEAR_PROCESS_MASKS` for the current platform
#define SET_PROCESS_MASK( set, mask )	Define macro `SET_PROCESS_MASKS` for the current platform
void sample_HA_replica_notifying( ... )	Replica notifying procedure that simply prints replica notifications in human-readable form
commoncl.h / commoncl.c (used in Cluster samples)
int sample_cluster_parse_opts( ... )	Parse the application's `argv[]` argument list and set cluster parameters accordingly
void sample_cluster_print_params( mco_cluster_params_t *cl_params )	Display the Cluster runtime parameter settings
void sample_cluster_usage()	Display the possible application runtime options and their meanings
initos.h / initos.c (used in most samples)
void sample_os_initialize( int req_features )	A startup function to initialize specific platform dependent features for embedded systems like VxWorks and ecos
void sample_os_shutdown()	A termination function to shutdown specific platform dependent features for embedded systems like VxWorks and ecos
int main( int argc, char* argv[] ) and int main()	A standardized main entry point for applications on embedded systems like VxWorks and ecos