# eXtremeDB/rt API Reference

## Transaction Control API (RT)

Name
Description
Aware of Real-Time Constraints
mco_trans_rt_start
This function initiates a real-time transaction for the database referenced by db
Yes
mco_trans_rt_rollback_deadline_check
This function is a pre-defined callback implementation that indicates to the database kernel that the application is using the adaptable deadline policy
No
mco_trans_end
Ends the current transaction
Yes
mco_trans_get_start_time
This function returns the clock start time
No
mco_trans_rt_estimate_rollback_time
This function returns the time in milliseconds required to roll back the current transaction
No
mco_trans_set_error
Sets error state for the transaction
No
mco_get_last_error
Returns the current transaction error code
No
mco_trans_rt_get_remaining_time
This function returns the time in milliseconds left until the deadline expires
No
mco_trans_rt_set_params
This function allows to change parameters of a running real-time transaction
No
mco_trans_rt_register_callback
The mco_trans_rt_register_callback() registers a callback function that is called by the database kernel at the cancelation points
No
mco_rollback_buf_info
The function fills in the mco_rollback_buf_info_t structure passed via rb_info
No
mco_trans_get_current
This function returns the handle to the active transaction or MCO_E_TRANS_NOT_ACTIVE if there is no active transaction for the given connection
No
mco_trans_rt_deadline_check
This function is a pre-defined callback implementation that indicates to the database kernel that the application is using the strict deadline policy
No

## EWSLite API

Name
Description
Aware of Real-Time Constraints
mco_lews_initialize
mco_lews_initialize() initializes the HTTP server parameters, including the networking interface, port, socket parameters, incoming connections handler, and spawns connection handling threads (in the multi-threaded configuration)
No
mco_lews_start
mco_lews_start() initiates the HTTP web server by activating the listening socket and starting the incoming connection handling loop
No
mco_lews_stop
mco_lews_stop() stops the incoming connection handling loop (running in mco_lews_start())
No
mco_lews_has_been_stopped
This function checks whether a shutdown request has been issued for the EWSLite server by calling mco_lews_stop().
No
mco_lews_destroy
mco_lews_destroy() concludes the operations of the HTTP web server by shutting down the listening socket, finishing the connections handling threads (tasks), and releasing the utilized resources
No
mco_lews_start_listen
The function starts listening for incoming connection on the LEWS server socket.
No
mco_lews_check_connections
The function checks for new incoming client connections on the LEWS server socket and processes them if available.
No
mco_lews_send_response_err
The mco_lews_send_response_err() function sends a standard HTTP response with an HTTP error code
No
mco_lews_flush
The mco_lews_flush() function transfers the contents of the outgoing buffer and subsequently clears the buffer
No
mco_lews_append_http_header
The mco_lews_append_http_header() function prepares and adds an HTTP response header to the outgoing buffer
No
mco_lews_append_header_end
The mco_lews_append_header_end() function completes the HTTP response header in the outgoing buffer
No
mco_lews_get_header_value
The mco_lews_get_header_value() function retrieves the value of an HTTP response header from the incoming buffer
No
mco_lews_get_query_param_int
The mco_lews_get_query_param_int() function retrieves the value of an integer query parameter from the incoming buffer
No
mco_lews_get_query_param_str
The mco_lews_get_query_param_str() function retrieves the value of a string query parameter from the incoming buffer
No
mco_lews_append_uint64
mco_lews_append_uint64() appends the string representation of an unsigned integer number to the outgoing buffer
No
mco_lews_append_int
mco_lews_append_int() appends the string representation of an integer number to the outgoing buffer
No
mco_lews_append_str
mco_lews_append_str() appends string data to the outgoing buffer
No
mco_lews_startswith
The mco_lews_startswith() function checks whether the given string is a prefix in the data buffer starting from the specified position.
No
mco_lews_strcmp
This function compares string data with a segment of the buffer
No
mco_lews_startswith
The function checks whether the given string is a prefix in the data buffer starting from the specified position (case-insensitive).
No
mco_lews_strcmp
This function compares string data with a segment of the buffer (case-insensitive).
No
mco_lews_base64_encode
This function encodes a string using Base64 encoding.
No
mco_lews_url_param_decode
This function decodes a URL-encoded (percent-encoded) string according to RFC 3986.
No
mco_lews_is_websocket_request
This function checks whether the incoming request is a WebSocket request.
No
mco_lews_send_websocket_closing_frame
This function sends a WebSocket closing frame to the client.
No
mco_lews_send_websocket_data_frame
This function sends a WebSocket data frame over an established connection.
No
mco_lews_websocket_negotiation_response
This function completes the WebSocket handshake by generating and sending the HTTP 101 Switching Protocols response to the client.
No
mco_lews_is_websocket_close_frame
This function checks whether the incoming request is a WebSocket close control frame.
No
IS_METHOD
This macro checks whether the HTTP request method matches the specified `method` string.
No
IS_URL
This macro checks whether the URL path in the current HTTP request exactly matches the specified `url` string.
No
mco_lJSON_ctx_open
This function initializes the provided JSON context and opens a root JSON object (`{`) in the output buffer of the specified connection.
No
mco_lJSON_ctx_close
This function closes the root JSON object (`{`) in the output buffer of the specified connection.
No
mco_lJSON_obj_open_arr
This function adds a new JSON array as a member of the current JSON object.
No
mco_lJSON_obj_open
This function opens a new JSON object as an element of the current JSON array.
No
mco_lJSON_arr_open
This function opens a new JSON array as an element of the current JSON array.
No
mco_lJSON_obj_close
This function closes the current JSON object or array.
No
mco_lJSON_obj_open_obj
This function opens a new JSON object as an element of the current JSON object.
No
mco_lJSON_obj_add_str
This function adds a string value to the current JSON object.
No
mco_lJSON_obj_add_int
This function adds an integer value to the current JSON object.
No
mco_lJSON_obj_add_uint
This function adds an unsigned integer value to the current JSON object.
No
mco_lJSON_arr_add_str
This function adds a string value to the current JSON array.
No
mco_lJSON_arr_add_int
This function adds an integer value to the current JSON array.
No
mco_lJSON_arr_add_uint
This function adds an unsigned integer value to the current JSON array.
No

## REST/RT API

Name
Description
Aware of Real-Time Constraints
mcorest_stop
mcorest_stop() sends the "stop" message to the RESTrt web service (informing it to finish its web service handling loop)
No
mcorest_initialize
mcorest_initialize() performs initialization of the networking interface and the RESTrt web service internal parameters
No
mcorest_start
mcorest_start() launches the RESTrt web service handling loop
No
mcorest_shutdown
mcorest_shutdown() completes the work of the RESTrt web service by closing the listening network socket and releasing internal resources
No
Name
Description
Aware of Real-Time Constraints
mco_async_event_wait
This function blocks the thread until the event referenced by event_id occurs or the application explicitly releases the event handler
No
mco_async_event_release
This function unblocks all the threads that are waiting on the event referenced by event_id
No
mco_async_event_release_all
This function unblocks all the threads that are waiting on all events for the specified database
No

## Transaction Control API

Name
Description
Aware of Real-Time Constraints
mco_trans_rollback
This function aborts a transaction
Yes
mco_trans_commit
This function completes a transaction, committing any changes to the database
Yes
mco_trans_upgrade
This function upgrades a MCO_READ_ONLY or MCO_UPDATE transaction to MCO_READ_WRITE
Yes
mco_trans_no
This function is used by mco_translog_iterate() callback functions (part of the Transaction Logging API) when iterating through the Transaction Log file to retrieve the “counter” number which uniquely identifies a transaction
No
mco_trans_type
This function returns the type of a transaction referenced by the handle
No
mco_trans_start
This function initiates a transaction for the database referenced by db
No
mco_trans_checkpoint
This function inserts updated objects into indexes
Yes
mco_trans_iterate
This function provides the ability to iterate over all modifications made by a transaction, read the modified objects, and determine what kind of modifications were applied (new, update, delete)
No
mco_set_trans_callback
This function assigns a callback function to be called when a transaction is committed or rolled back
No
mco_trans_is_active
This function checks whether a database transaction is currently active
No
mco_trans_iterable
This function enables or disables transaction iteration support for a database connection
No
mco_trans_set_options
This function configures runtime options that affect the behavior of the current transaction
No

## Database Control API

Name
Description
Aware of Real-Time Constraints
mco_db_disconnect
This function destroys the connection handle to the database and invalidates any existing transaction handles for the connection
No
mco_db_open_dev
This function creates the database dbname on the devices defined by devs according to the parameters specified in params
No
mco_close_all_instances
This function destroys all database instances
No
mco_db_load
This function loads a previously saved image of a database and opens it by internally calling mco_db_open_dev() with the passed parameters
No
mco_db_open_disk
This function create or open a persistent database
No
mco_db_extend_dev_t
This function extends the available database memory by adding the specified memory device
No
mco_copy_handle
Because object handles cannot be copied as a raw sequence of bytes (using memcpy() for example), this function is provided for rare occasions when it might be useful to copy an object handle
No
mco_db_recover
Normally a database that was not properly closed (perhaps after a system crash) will be recovered automatically during the mco_db_open_dev()
No
mco_db_close
This function destroys the database dbname
No
mco_is_object_deleted
This function allows an application to determine if an object has been deleted within the current transaction
Yes
mco_db_kill
This function removes the shared memory segment allocated by the runtime for the database identified by the dbname
No
mco_get_class_code
This function returns the class code of the object referenced by the object handle
No
mco_get_last_autoid
This function returns the last generated value for an object of any database class that has an autoid field defined
No
mco_db_open
This function creates the database dbname in the space referenced by mem with an initial size of total_size (the database size can be extended) and with a page size of page_size
No
mco_db_connection_context
This function returns the database context data associated with this connection
No
mco_db_extend_t
This function extends the amount of memory used by the database
No
mco_db_connect
This function connects an application (thread) to a database
No
mco_db_clean
This function removes all objects from an opened database
No
mco_db_connect_ctx
This function connects to a database specifying connection context values that can later be accessed for application specific purposes
No
mco_current_registry_size
This function returns the number of bytes required to load the database registry at runtime
No
mco_class_load
This function loads a previously saved image of a database class
No
mco_db_save
This function is used to stream an database to permanent storage
No
mco_db_extend
This function extends the amount of memory used by the database dbname
No
mco_db_extend_dev
This function extends the available database memory by adding the specified memory device
No
mco_db_recover_all
This function allows an application to explicitly recover anydatabases connections that were not properly closed
No
mco_db_databases
This function returns a list of all database names registered in the system
No
mco_db_extend_ctx
This function extends the amount of memory used by the database
No
mco_db_connection_info
This function returns the current and maximal number of connections to a database
No
mco_db_params_init
This function sets default parameters (page sizes, number of connections, log policies, etc
No
mco_db_sniffer
This function inspects the state of all connections to the database using the provided user's callback function
No
mco_db_sniffer
This function is extended version of `mco_db_sniffer()` function
No
mco_db_register_udf
This function registers the array of user-defined functions with the runtime
No
mco_db_extend_dev_ctx
This function extends the available database memory by adding the specified memory device
No
mco_class_save
This function is used to stream the entire contents of a database class to permanent storage
No
mco_db_register_collations
Register custom collation functions for a database instance.
No

## Cursor Control API

Name
Description
Aware of Real-Time Constraints
mco_cursor_type
This function determines the validity of a cursor handle and returns the cursor type if the handle is valid
No
mco_cursor_next
This function positions the cursor to the next object in the index
Yes
mco_cursor_close
This function allows applications to explicitly close a cursor
Yes
mco_cursor_store
This function stores the cursor so that applications using the MVCC Transaction Manager can pass its handle between transacitons
Yes
mco_cursor_check
This function checks the internal structure of the cursor
Yes
mco_cursor_get_class_code
This function returns the class code of the object at the current cursor position
No
mco_cursor_first
This function positions the cursor to the first object in the index
Yes
mco_cursor_last
This function positions the cursor to the last object in the index
Yes
mco_cursor_prev
This function positions the cursor to the previous object in the index
Yes

## Disk Manager API

Name
Description
Aware of Real-Time Constraints
mco_disk_save_cache
This function saves the Disk Manager cache to persistent media
No
mco_disk_get_cache_info
This function allows applications to obtain runtime disk manager cache statistics in structure mco_disk_cache_info_t, including cache hits and cache misses
No
mco_disk_info
This function returns the information about the current state of the Disk Manager in the mco_disk_info_t structure
No
mco_disk_load_cache
This function loads the previously saved state of the Disk Manager cache from persistent media
No
mco_disk_fs_cache_warmup
This function allows an application to load database files into the file system cache which can give up to 8x performance improvement for traversal of database records
No
mco_disk_get_alloc_info
This function collects information about the distribution of free disk space.
No
mco_disk_get_allocated_space
This function collects information about the size of allocated and used pages in the database file.
No
mco_disk_cache_usage
Estimate the amount of disk cache memory used by persistent objects of each class.
No

## Error Handling

Name
Description
Aware of Real-Time Constraints
mco_get_last_error
This function returns the value of the last return code from an function that caused a transaction to enter an error state
No
mco_error_set_handler
This function registers an application function to handle fatal error conditions
No
mco_error_set_handler_ex
Set the extended fatal error handler that accepts __FILE and __LINE parameters
No
mco_strerror
Return a string describing the error code
No

## UDA API

Name
Description
Aware of Real-Time Constraints
mco_dict_field_name
This function returns a field descriptor referred to by name
No
mco_metadict_register
The API registers a database dictionary in the meta-dictionary
No
mco_metadict_register_conn
The API registers the database dictionaries for the current connection in the meta-dictionary
No
mco_uda_db_close
This function closes the database referenced by the specified index dict_no
No
mco_uda_from_mco
This function makes a UDA object handle from a “native” database object handle.
No
mco_uda_cursor
Initializes a cursor based on the index specified through its number `index_no`
Yes
mco_uda_length
Return the length (number of elements) of the vector or array field
Yes
mco_uda_delete
Removes an object from the database.
Yes
mco_metadict_entry_conn
This function returns a pointer to the dictionary based on a database connection
No
mco_uda_put
Assigns the field value for the object or structure.
Yes
mco_dict_index_name
This function returns an index descriptor by name
No
mco_dict_event
This function returns an event descriptor based on the dictionary number, class number and the DDL field name
No
mco_metadict_unregister
The API unregisters a database dictionary from the meta-dictionary
No
mco_uda_async_event_wait
This function blocks the thread until the specified event is fired by the application, or the application explicitly releases the event handler by calling function mco_uda_async_event_release() or mco_uda_async_event_release_all()
No
mco_uda_lookup
Perform a database lookup
Yes
mco_uda_field_alloc
Allocate a vector field.
Yes
mco_uda_compare
Compare the value(s) referenced by the current position of the index cursor with value(s) in parameter keys
Yes
mco_uda_get_udfmap_size
This function returns the amount of memory necessary to keep information about all user-defined functions at runtime
No
mco_uda_collate_get_range
This function returns a string value from the specified collation by copying from the specified starting position from to the end of the string withing the collation
Yes
mco_uda_locate
Positions the cursor in the index referenced by index_no at the given object
Yes
mco_uda_delete_all
This function deletes all objects of the specified class.
Yes
mco_dict_nested_ifield
This function returns a compound index field (segment) descriptor by the nested index field with number ifield_no
No
mco_uda_cursor_info
Returns information about the index associated with the cursor
No
mco_metadict_entry
This function returns a pointer to the dictionary based on its index in the array metadict->entries
No
mco_uda_checkpoint
This function inserts a new object into indexes.
Yes
mco_metadict_init
This function initializes the meta-dictionary
No
mco_dict_ifield_name
This function returns a compound index field (segment) descriptor by the index field name
No
mco_metadict_size
The function returns the size of the meta-dictionary in bytes (including the header)
No
mco_uda_get
Returns the field value
Yes
mco_metadict_entry_name
This function returns a pointer to the dictionary based on its name metadict->entries[]->name
No
mco_uda_field_erase
Remove an optional structure field or vector element
Yes
mco_dict_ifield
This function returns a compound index field (segment) descriptor by index field number ifield_no
No
mco_dict_field_init_data
This function returns a pointer to the field’s default data value by field_no
No
mco_uda_get_class_code
This function gets the “native” class code of a UDA object
No
mco_uda_register_collation
Register a collation with the database runtime
No
mco_uda_async_event_release_all
This function releases all event handlers for the specified database
No
mco_dict_collation_count
This function returns the number of collation descriptors in the dictionary
No
mco_dict_field
This function returns a field descriptor referred to by field_no
No
mco_dict_struct
This function returns the structure/class descriptor referred to by the index dict_no in the array metadict->entries[] and class/structure number struct_no
No
mco_dict_struct_name
This function returns the descriptor for the structure/class referred to by the index dict_no in the array metadict->entries[] and class/structure name (as defined in the schema )
No
mco_dict_struct_classcode
This function returns the descriptor for the structure/class referred to by its class code
No
mco_dict_collation_name
This function returns a collation descriptor based on the dictionary and collation name
No
mco_uda_from_cursor
Return a handle to the object in the cursor
Yes
mco_uda_db_open
This function can be used to replace mco_db_open_dev()
No
mco_uda_oid_find
Searches the database for the object with the specified oid
Yes
mco_dict_struct_count
This function returns the number of structures/classes for the dictionary referred to by the index dict_no in the array metadict->entries[]
No
mco_uda_collate_get
This function returns a value from the mco_collate_h struct
Yes
mco_dict_index
This function returns an index descriptor by index_no
No
mco_uda_async_event_release
This function releases the specified event handler
No
mco_uda_get_collmap_size
This function returns the size of the collation map structure
No
mco_dict_collation
This function Returns Returns a collation descriptor based on the dictionary and collation number
No
mco_uda_to_mco
This function makes a “native” object handle from a UDA object handle
No
mco_uda_new
Allocates a new object
No
mco_metadict_count
This function returns the number of registered databases (metadict->n_allocated)
No
mco_uda_register_udf
Registers user-defined functions with the database runtime
No

## Runtime Control API

Name
Description
Aware of Real-Time Constraints
mco_runtime_setoption
This function sets the runtime option to the specified value
No
mco_runtime_stop
This function terminates the runtime and releases all resources initialized by mco_runtime_start()
No
mco_get_runtime_info
This function reports the version and enabled features of the eXtremeDB database runtime
No
mco_runtime_getoption
Returns the value of the specified runtime option
No
mco_runtime_start
This function initializes a semaphore to coordinate access to the database dictionary
No
mco_get_max_connections
This function returns the maximum number of concurrent connections
No
mco_get_last_unique_violation_index
This function returns the index number of the unique constraint that was most recently violated
No

## Auxiliary Functions

Name
Description
Aware of Real-Time Constraints
mco_sys_valloc
This function allocates a of size bytes aligned to a multiple of the value returned by sysconf(_SC_PAGESIZE)
No
mco_sys_realloc
This function reallocates a block of memory previously allocated by mco_sys_malloc()
No
mco_sys_calloc
This function allocates an array of memory blocks each of size bytes and the space is initialized to 0
No
mco_sys_free
This function frees a memory block
No
mco_sys_vfree
This function frees a memory block allocated by mco_sys_valloc()
No
mco_sys_malloc
This function allocates a properly aligned block of memory
No

## Backup API

Name
Description
Aware of Real-Time Constraints
mco_backup_create
This function creates a backup record of the database
No
mco_backup_list
This function creates a list of backup records in the specified backup file
No
mco_backup_list_db_name
This function creates a list of backup records in the specified backup file
No
mco_backup_restore
This function restores the backup (specified by file_name and label) by reading the backup from the latest snapshot record up to the specified label
No
mco_backup_verify
This function tests the backup (specified with a file_name and a label) for validity by reading the backup one record at a time and then checks the CRC of all of the records
No
mco_backup
Low-level backup routine.
No
mco_restore
Low-level restore routine.
No
mco_backup_incremental_processing_get
Retrieve the current status of incremental backup processing for a database.
No
mco_backup_incremental_processing_set
Enable or disable incremental backup processing for a database.
No
mco_backup_progress_info
Retrieve the current progress information of an ongoing backup operation.
No
mco_backup_chunk
Write data chunks to a backup file.
No
mco_backup_info
Write metadata headers to a backup file.
No
mco_restore_chunk
Read data chunks from a backup file.
No

## Miscellaneous Functions

Name
Description
Aware of Real-Time Constraints
mco_time2ticks
This function converts the argument time to the corresponding value specified by the resolution argument scale
No
mco_system_get_current_time
This function retrieves from the operating system the number of timer ticks (microseconds) since 1 Jan 1970 (Epoch)
No
mco_ticks2time
This function converts the argument ticks to the corresponding value specified by the resolution argument scale
No
mco_system_get_hi_res_freq
This function returns the frequency of the high-resolution timer
No
mco_system_get_hi_res_time
This function returns the number of ticks elapsed since the high-resolution timer was started.
No
mco_set_system_get_current_time
This function sets a new user-defined routine for obtaining the current time in ticks
No
mco_open_file_rt
This function opens a file
Yes
mco_begin_wait_event
This function sets the current wait event type for profiling and diagnostics.
No
mco_end_wait_event
This function clears the current wait event type for profiling and diagnostics.
No
mco_dict_version
This function returns the current version number of the database schema (dictionary).
No
Name
Description
Aware of Real-Time Constraints
mco_db_total_pages
This function returns into total_pages the count of in-memory pages in the database referenced by handle db
No
mco_db_free_pages
This function returns into free_pages the count of available in-memory pages in the database referenced by handle db
No
mco_index_stat_num
This function returns the number of indexes in the database
No
mco_db_page_size
This function returns into page_size the page size for the database referenced by handle db
No
mco_index_stat_get
This function returns statistics that are maintained for the index
No
mco_index_get_size
The function returns the size of the index -- the number of key values in the index structure (tree)
No
mco_class_stat_get
This function returns statistics that are maintained for the class
No
Name
Description
Aware of Real-Time Constraints
mco_trace_set_modules_mask
This function determines the modules to be logged
No
mco_trace_set_level
This function sets the severity level for tracing messages
No
mco_trace_set_handler
This function registers a user-defined custom handler to be called when database operations trigger messages
No
Name
Description
Aware of Real-Time Constraints
mco_crypt_algorithm
This function returns the algorithm type supported by the encryption library currently linked
No
mco_crypt_block
This function encrypts or decrypts a block of data using the specified pre-initialized encryption context crypt_cts
No
mco_crypt_stream
This function encrypts or decrypts a data buffer buf of size size to be placed into or retrieved from a stream
No
mco_crypt_init_state
This function creates an encryption state structure using the pre-initialized encryption context
No
mco_crypt_init_ctx
This function prepares the encryption context by a cipher key string
No

## Flash Simulator API

Name
Description
Aware of Real-Time Constraints
mco_open_flash_media
Opens a flash media device
No
mco_flashsim_open
Initializes the flash simulator and opens a handle to the flash media device
No
mco_flashsim_close
Closes the flash simulator handle and releases all associated resources
No
mco_flashsim_get_stat
Retrieves the statistics of the flash simulator
No
mco_flashsim_print_stat
Prints the statistics of the flash simulator to stdout
No
mco_flashsim_save_image
Saves the simulator state image to a file
No
mco_flashsim_media_context
Retrieves the flash media context associated with the flash simulator handle
No
mco_flashsim_memory_size
Returns the size of the memory segment calculated based on the flash simulator parameters
No
mco_get_media_context
Retrieve the custom media context associated with a file-based device
No

## STATrt API

Name
Description
Aware of Real-Time Constraints
mco_stat_counter_count
Retrieve the total number of registered runtime statistics counters and histograms.
No
mco_stat_counter_get
Retrieve the current value of a runtime statistics counter.
No
mco_stat_get_all
Retrieve the current values of all runtime statistics counters and histograms.
No
mco_stat_get_conn_stats
Retrieve the current values of runtime statistics counters and histograms for a specific database connection.
No
mco_stat_get_counter_info
Retrieve the metadata information of a runtime statistics counter.
No
mco_stat_get_histogram_source
Retrieve the internal histogram index associated with a given statistics counter.
No
mco_stat_histogram_append
Append a value to the histogram associated with a given statistics counter.
No
mco_stat_histogram_get
Retrieve the current values of all buckets in the histogram associated with a given statistics counter.
No
mco_stat_histogram_init
Initialize the histogram associated with a given statistics counter.
No
mco_statrt_get
Retrieve the current value of a runtime statistics counter.
No
mco_statrt_register_counter
Register a new runtime statistics counter.
No
mco_statrt_update
Update the value of a runtime statistics counter.
No
mco_stat_memsize
Calculate the amount of memory required to store runtime statistics for a database instance.
No
mco_stat_get_disk_stats
Retrieve the current values of disk I/O statistics counters.
No
mco_disk_stat
Retrieve the current values of disk I/O statistics counters.
No