# 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

Related Topics