The 5800 system synchronous C API functions are defined to perform the following tasks:
The following functions are used to manage 5800 system sessions:
Creates a session.
hcerr_t hc_session_create_ez(char *host, int port, hc_session_t **sessionp);
This function initializes the 5800 system API and must be called before calling any of the other functions in this API. It downloads a copy of the schema for a particular host or port. The schema is used to validate the name-value-type tuples that are added to metadata records.
Both the synchronous and the nonsynchronous C APIs are fully thread-safe and can be used simultaneously in multiple threads from the same process. Each thread must call hc_session_create_ez to create its own session. Sessions must not be shared between threads.
hc_init should be called once per process before any thread calls hc_session_create_ez. If hc_session_create_ez is called before hc_init, an implicit call is made to hc_init from that thread. But that call to hc_init is not interlocked with other threads, and it uses the C API shared library’s version of malloc and free, which might be different than the application’s version of malloc and free. It is strongly recommended that all applications call hc_init once per process with their own allocator and deallocator.
For more information on hc_init, see Initializing a Global Session
host
IN: The name or IP address of a 5800 system server.
port
IN: The port number of the 5800 system server (normally 8080).
sessionp
OUT: Updated to point to a session object.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_ILLEGAL_ARGUMENT
Releases the session object.
hcerr_t hc_session_free (hc_session_t *session);
This function releases the session object and recovers handles and memory for one connection.
session
IN: The session object to free.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION
Gets the session status.
hcerr_t hc_session_get_status(hc_session_t *session, int32_t *response_codep,char **errstrp);
This function returns the HTTP response code and the error message string associated with the last request on this session.
session
IN: The session object.
response_codep
OUT: Updated to be the HTTP response code.
errstr
IN: Updated to be the error returned in the response body if the response code is not 200 (OK). errstr should not be written to by the application (that is, it is read only), and will persist until the next request to the 5800 system server or until hc_session_free is called, whichever comes first.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION
Gets schema object associated with this session.
hcerr_t hc_session_get_schema (hc_session_t *session, hc_schema_t **schemap);
This function returns the current schema object associated with this session.
session
IN: The session object.
schemap
OUT: Updated to be the schema associated with the current session. schemap should not be modified by the application and will persist until the next call to hc_session_free, at which time it will be implicitly released.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION
Returns the host name and port number associated with the session.
hc_session_get_host(hc_session_t *session, char **hostp,int *portp);
This function returns the host name and port number associated with the session.
session
IN: The session object.
hostp
OUT: Updated to point to host name (read-only string). hostp should not be modified by the application and will persist until the next call to hc_session_free.
portp
OUT: Updated to be the port number.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION
Returns low-level error codes associated with the current session.
hcerr_t hc_session_get_platform_result(hc_session_t *session, int32_t *connect_errnop, int32_t *platform_resultp);
This function returns low-level error codes associated with the current session.
The values returned by hc_session_get_platform_result will not be updated properly after calls to the functions hc_retrieve_ez and hc_delete_ez.
session
IN: The session object.
connect_errnop
OUT: Updated to be the operating system’s errno value associated with the last connect operation on the current session.
platform_resultp
OUT: Updated to be the error code reported by the underlying HTTP library (for example, the Curl library).
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION
Returns the current archive object associated with this session.
hcerr_t hc_session_get_archive(hc_session_t *session, hc_archive_t **archivep);
This function returns the current archive object associated with this session.
The archive object is not needed for the synchronous C API, but is made available for interfacing with the lower-level (nondocumented) API.
session
IN: The session object.
archivep
OUT: Updated to be the archive object associated with the current session.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION
When a session commences, the C client API downloads information about the metadata schema that is in use on the 5800 system server.
The following functions are used to manage a schema:
Looks up type in schema.
hcerr_t hc_schema_get_type(hc_schema_t *schema, char *name, hc_type_t *typep);
This function looks up the type associated with a given name in the current metadata schema, or returns an error if the name is not known.
schema
IN: The schema to interrogate.
name
IN: The attribute name to look up in the schema.
typep
OUT: Updated to be the type associated with that name in the schema.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_SCHEMA HCERR_ILLEGAL_ARGUMENT
Looks up length of char and string attribute fields.
hcerr_t hc_schema_get_length(hc_schema_t *schema, char *name, int *length);
This function looks up the length of a char or string field associated with a given attribute name in the current metadata schema, or returns an error if the name is not known.
schema
IN: The schema to interrogate.
name
IN: The attribute name to look up in the schema.
length
OUT: Updated to be the length of the field associated with that name in the schema.
HCERR_OK HCERR_BAD_REQUEST HCERR_INVALID_SCHEMA HCERR_ILLEGAL_ARGUMENT
Returns the number of name-value pairs in the metadata schema.
hcerr_t hc_schema_get_count(hc_schema_t *hsp, hc_long_t *countp);
This function returns the number of name-value pairs in the metadata schema.
hsp
IN: The schema to interrogate.
countp
OUT: Updated with the number of name-value pairs in the schema.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_SCHEMA
Iterates through the name-value pairs in a schema.
hcerr_t hc_schema_get_type_at_index (hc_schema_t *hsp, hc_long_t index,char **namep, hc_type_t *typep);
This function provides a simple way to iterate through the name-value pairs in a schema.
hsp
IN: The schema to query.
index
IN: Should range from 0 up to the count-1 returned in hc_schema_get_count.
namep
OUT: Updated to point to a string that is an attribute name of one attribute in the schema.
typep
OUT: Updated to be the type associated with that name in the schema. If the server schema references a type that the client library does not support, then the type is returned as HC_UNKNOWN_TYPE.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_SCHEMA HCERR_ILLEGAL_ARGUMENT
5800 system synchronous C API functions are defined to perform the following name-value record manipulation tasks:
A common way of storing metadata in the synchronous C API for the 5800 system is to use the name-value record API.
Call hc_init once per process.
Call hc_session_create_ez to initialize the session and download the schema.
Create the metadata record with hc_nvr_create.
Fill the new metadata piece by piece with hc_nvr_add_metadata_* functions (see Building Name-Value Records) for each 5800 system type.
Call either hc_store_metadata_ez or hc_store_both_ez to store the new metadata record.
When you are done, free the metadata record by calling hc_nvr_free.
When the session is finished, call hc_session_free to free the session data structures.
When all threads are completed, call hc_cleanup to release the global session.
Name-value records are also returned as the result of queries that return metadata information, such as hc_retrieve_metadata_ez.
Run the query to create an hc_nvr_t record or a table of hc_nvr_t structures.
Use either name-based access (for example, hc_nvr_get_*) or index-based access (for example, hc_nvr_get_count and hc_nvr_get_value_at_index).
To free the hc_nvr_t structure, call hc_nvr_free.
Structures created by hc_nvr_create can also be freed by calling hc_nvr_free.
The following functions are defined to create and free name-value records:
Creates a name-value record.
hcerr_t hc_nvr_create(hc_session_t *session, hc_long_t nslots, hc_nvr_t **nvrp);
This function creates a name-value record with a designated initial size that is associated with a particular session. Metadata that is added to this name-value record must match the schema associated with the session.
session
IN: The session with which this name-value record is associated.
nslots
IN: The number of slots for name-value-type tuples.
nvrp
OUT: Updated with a pointer to a new name-value record of the designated size.
HCERR_OK HCERR_ILLEGAL_ARGUMENT HCERR_OOM
Frees a name-value record.
hcerr_t hc_nvr_free(hc_nvr_t *nvr);
This function frees a name-value record that was created by hc_nvr_create.
nvr
IN: Points to the name-value-record to be freed.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR
The following functions are defined to build name-value records:
Adds a new metadata value.
hcerr_t hc_nvr_add_value(hc_nvr_t *nvr, char *name, hc_value_t value);
This function adds a new metadata name-value-type tuple to a designated name-value record. The name-value record will automatically expand as needed.
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: Value for the tuple, in the type-tagged hc_value_t format.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_NO_SUCH_ATTRIBUTE
Adds a new metadata value of type hc_long_t.
hcerr_t hc_nvr_add_long(hc_nvr_t *nvr, char *name, hc_long_t value)
This function adds a new metadata name-value-type tuple to a designated name-value record, where type is known to be hc_long_t (see hc_type_t). The name-value record will automatically expand as needed.
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The hc_long_t value.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_NO_SUCH_ATTRIBUTE
Adds a new metadata value of type hc_double_t.
hcerr_t hc_nvr_add_double(hc_nvr_t *nvr, char *name, hc_double_t value);
This function adds a new metadata name-value-type tuple to a designated name-value record, where type is known to be hc_double_t (see hc_type_t). The name-value record will automatically expand as needed.
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The hc_double_t value.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_NO_SUCH_ATTRIBUTE
Adds a new metadata value of type Unicode UTF-8 string.
hcerr_t hc_nvr_add_string(hc_nvr_t *nvr, char *name, hc_string_t value);
This function adds a new metadata name-value-type tuple to a designated name-value record, where type is a Unicode UTF-8 string. The name-value record automatically expands as needed. The string is copied into the structure.
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The hc_string_t value.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_NO_SUCH_ATTRIBUTE
Adds new metadata value of type binary.
hcerr_t hc_nvr_add_binary(hc_nvr_t *nvr, hc_string_t name, int size, unsigned char *bytes);
This function adds a new metadata name-value-type tuple to a designated name-value record, where type is binary data. The name-value record automatically expands as needed. The name and data are copied into the structure.
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
size
IN: The size of the data.
bytes
IN: The binary data.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_NO_SUCH_ATTRIBUTE
Adds new metadata value of type date.
#include <time.h> hcerr_t hc_nvr_add_date(hc_nvr_t *nvr, hc_string_t name,struct tm *value);
This function adds a new metadata name-value-type tuple to a designated name-value record.
The struct tm fields are as defined in the POSIX standard and interpreted by mktime(3C). All fields are ignored except:
int tm_mday; /* day of the month - [1, 31] */ int tm_mon; /* months since January - [0, 11] */ int tm_year; /* years since 1900 */
The name-value record automatically expands as needed. The name and value are copied into the structure.
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The struct tm (time.h) value.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_NO_SUCH_ATTRIBUTE
Adds new metadata value of type time.
#include <time.h> hcerr_t hc_nvr_add_time(hc_nvr_t *nvr, hc_string_t name, time_t *value);
This function adds a new metadata name-value-type tuple to a designated name-value record. The value represents seconds since midnight.
The name-value record automatically expands as needed. The name and value are copied into the structure.
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The time_t (time.h) value.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_NO_SUCH_ATTRIBUTE
Adds new metadata value of type timestamp.
#include <time.h> hcerr_t hc_nvr_add_timestamp(hc_nvr_t *nvr, hc_string_t name, struct timespec *value);
This function adds a new metadata name-value-type tuple to a designated name-value record, where type is hc_timestamp_t. The struct timespec is defined in the POSIX standard:
time_t tv_sec; /* seconds */ long tv_nsec; /* and nanoseconds */
where tv_sec is measured since the UNIX epoch (00:00:00 UTC on January 1, 1970). The maximum value of tv_sec is truncated by three decimal digits owing to database limitations and tv_nsec is truncated to milliseconds. The name-value record automatically expands as needed. The name and value are copied into the structure.
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The ’struct timespec’ (time.h) value.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_NO_SUCH_ATTRIBUTE
Adds a new metadata value where the value always starts out as a string.
hcerr_t hc_nvr_add_from_string(hc_nvr_t *nvr, char *name, char *value);
This is a convenient function for adding a new metadata name-value-type tuple to a designated name-value, where the value always starts out as a string. The correct metadata type for name must be looked up from the schema. The name-value record will automatically expand as needed. The string is copied into the structure.
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The string value to be added.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT
The following functions are defined to retrieve name-value records:
Retrieves the number of metadata name and value tuples in this name-value record.
hcerr_t hc_nvr_get_count(hc_nvr_t *nvr, hc_long_t *retcount);
This function retrieves the number of metadata name and value tuples in the specified name-value record.
nvr
IN: Points to a name-value-record.
retcount
OUT: Updated to contain the count of name-value pairs.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR
Iterates through the names and values in a name-value record.
hc_nvr_get_value_at_index(hc_nvr_t *nvr, hc_long_t index, char **namep, hc_value_t *valuep);
This function iterates through the names and values in a name-value record. The returned names are read-only. Unpredictable results will occur if either the name or the value is referenced after either hc_nvr_free or hc_nvr_create_from_string_arrays is called on this name-value record.
nvr
Points to a name-value-record.
index
IN: The index to examine.
namep
OUT: Updated to point to the attribute name at the specified index.
valuep
OUT: Updated with the hc_value_t type-tagged value at the specified index.
HCERR_OK HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_NO_MORE_ARGUMENTS HCERR_OOM
Retrieves a value of type hc_long_t.
hcerr_t hc_nvr_get_long(hc_nvr_t *nvr, char *name, hc_long_t *retlong);
This function retrieves the value of type hc_long_t (see hc_type_t) associated with an indicated attribute name in a name-value record.
nvr
Points to a name-value-record.
name
IN: Attribute name to look for.
retlong
OUT: Updated to contain the hc_long_t value.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_ILLEGAL_ARGUMENT
Retrieves a value of type hc_double_t.
hcerr_t hc_nvr_get_double(hc_nvr_t *nvr, char *name, hc_double_t *retdouble);
This function retrieves the value of type hc_double_t (see hc_type_t) associated with an indicated attribute name in a name-value record.
nvr
Points to a name-value-record.
name
IN: Attribute name to look for.
retdouble
OUT: Updated to contain the hc_double_t value.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_ILLEGAL_ARGUMENT
Retrieves a value of a Unicode UTF-8 string.
hcerr_t hc_nvr_get_string(hc_nvr_t *nvr, char *name, hc_string_t *retstring);
This function retrieves the value of a Unicode UTF-8 string associated with an indicated attribute name in a name-value record. Note that the memory pointed to will be freed when the record is freed.
nvr
Points to a name-value-record.
name
IN: Attribute name to look for.
retstring
OUT: Updated to contain the hc_string_t value.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_ILLEGAL_ARGUMENT
Retrieves a metadata value of type binary.
hcerr_t hc_nvr_get_binary(hc_nvr_t *nvr, hc_string_t name, int *size, unsigned char **bytes);
This function retrieves the value of type binary associated with an indicated attribute name in a name-value record. The binary data is not copied and is freed when the name-value record is freed.
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
size
OUT: Updated with the size of the data.
bytes
OUT: Updated to point to the binary data.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_NO_SUCH_ATTRIBUTE
Retrieves metadata value of type date.
#include <time.h> hcerr_t hc_nvr_get_date(hc_nvr_t *nvr, hc_string_t name, struct tm *value);
This function retrieves the value of type struct tm associated with an indicated attribute name in a name-value record.
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
OUT: Updated with the struct tm (time.h) value.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_NO_SUCH_ATTRIBUTE
Retrieves metadata value of type time.
#include <time.h> hcerr_t hc_nvr_get_time(hc_nvr_t *nvr, hc_string_t name, time_t *value);
This function retrieves the value of type time_t (seconds since midnight) associated with an indicated attribute name in a name-value record.
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
OUT: Updated with the time_t (time.h) value.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_NO_SUCH_ATTRIBUTE
Retrieves metadata value of type timestamp.
#include <time.h> hcerr_t hc_nvr_get_timestamp(hc_nvr_t *nvr, hc_string_t name, struct timespec *value);
This function retrieves the value of type struct timespec associated with an indicated attribute name in a name-value record.
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
OUT: Updated with the struct timespec (time.h) value.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_NO_SUCH_ATTRIBUTE
The following functions are defined to create name-value records from string arrays and convert name-value records to string arrays:
Creates name-value-record from string names and string values.
hcerr_t hc_nvr_create_from_string_arrays(hc_session_t *session, hc_nvr_t **nvrp, char **names, char **values, hc_long_t nitems);
This function creates a name-value-record from parallel tables of string names and string values. The correct metadata type for each name must be looked up from the schema associated with this session. The name-value record will automatically expand as needed. The names and data values are copied into the hc_nvr_t structure, so the original names table and values table are left unchanged.
Any time there is a conversion from a double type to or from a string type, there might be a loss of precision.
session
IN: The session with which this name-value record is associated.
nvrp
OUT: Updated to point to a name-value-record.
names
IN: Points to an array of string names.
values
IN: Points to an array of string values.
nitems
IN: Number of active elements in the paired arrays.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION HCERR_ILLEGAL_ARGUMENT
Converts name-value-record to string names and string values.
hcerr_t hc_nvr_convert_to_string_arrays(hc_nvr_t *nvr, char ***namesp, char ***valuesp, int *nitemsp);
This function converts a name-value-record into parallel tables of string names and string values. This destructively modifies the name-value record and frees it, so do not call hc_nvr_free after calling this function.
When the conversion is finished, each string in the names and values tables should be freed with the designated deallocator (for example, free), as well as the names and values tables themselves.
Any time there is a conversion from a double type to or from a string type, there might be a loss of precision.
nvr
IN: The name-value-record.
namesp
OUT: Updated to point to an array of string names.
valuesp
OUT: Updated to point to an array of string values.
nitemsp
OUT: Updated to the number of active elements in the paired arrays.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT
The following functions are defined to store data and metadata and to enforce indexing of metadata where necessary:
The is_indexed value in the returned system record (hc_system_record_t) indicates whether this record was successfully inserted in the query engine at the time of store, and is hence available for query. Objects that were not inserted into the query engine at time of store are called store index exceptions. Until they are resolved, store index exceptions may or may not show up in the result sets of queries that match the store. A store index exception is resolved once the metadata for that object has been successfully inserted into the query engine, after which the object will definitely show up in the result sets of queries that match the store. The hc_check_indexed_ez method may be used to attempt to resolve a store index exception under program control. Store index exceptions will also be resolved automatically (eventually) by ongoing system healing.
Stores a metadata record and associated data.
hcerr_t hc_store_both_ez (hc_session_t *session, *data_source_reader, void *cookie, hc_nvr_t *nvr, hc_system_record_t *system_record);
This function stores both object data and metadata and returns a system_record descriptor. The status from this operation can be reclaimed using hc_session_get_status.
session
IN: The session for the host and port to talk to.
data_source_reader
IN: The source of data to be stored. See read_from_data_source.
cookie
IN: An opaque data structure (cookie) to be provided to data_source_reader. For example, this could be a file descriptor.
nvr
IN: Pointer to a name-value record with the metadata.
system_record
OUT: Returned descriptor of a stored metadata record.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_NO_SUCH_TYPE HCERR_XML_BUFFER_OVERFLOW
Adds a metadata record for the specified OID.
hcerr_t hc_store_metadata_ez(hc_session_t *session, hc_oid *oid, hc_nvr_t *nvr, hc_system_record_t *system_record);
This function adds a metadata record for the specified OID and returns a system_record descriptor.
session
IN: The session for the host and port to talk to.
oid
IN: An identifier of object data to which the metadata record is attached.
nvr
IN: Pointer to a name-value record with the metadata.
system_record
OUT: Returned descriptor of a stored metadata record.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION HCERR_INVALID_NVR HCERR_INVALID_OID HCERR_ILLEGAL_ARGUMENT HCERR_XML_BUFFER_OVERFLOW
Checks if the metadata for an object is present in the query engine, and inserts it if not.
hcerr_t hc_check_indexed_ez(hc_session_t *session, hc_oid *oid, int *resultp);
checkIndexed is intended as way to resolve a store index exception under program control (see The 5800 System Query Integrity Model). Once a store index exception occurs (as indicated by a non-zero value of the is_indexed field in the hc_system_record_t returned from a store operation) then hc_check_indexed_ez can be called repeatedly until it returns with *resultp set to any non-zero value. This will ensure that the metadata for the object has been inserted into the query engine; the object should then start to show up in matching queries.
session
IN: The session for the host and port to talk to.
oid
IN: An identifier of object data to which the metadata record is attached.
resultp
OUT: Points to an int that is updated to a value that indicates if the metadata for this object has been inserted into the query engine. The returned value of *resultp is set to -1 if the object was already present in the query engine, and is set to 0 if the object was not already in the query engine and could not be added, and to 1 if the object was just now added to the query engine. In other words, a non-zero value of resultp indicates that the store index exception has been resolved.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION HCERR_INVALID_OID
The following functions are defined to retrieve data and metadata:
Retrieves data for the specified OID.
hcerr_t hc_retrieve_ez(hc_session_t *session, *data_writer, void *cookie, hc_oid *oid);
This function retrieves data for the specified OID.
session
IN: The session for the host and port to talk to.
data_writer
IN: A function callback to store the retrieved data locally. See write_to_data_destination.
cookie
IN: The opaque data delivered to the data_writer callback to identify this data stream.
oid
IN: Identifier for the metadata record to retrieve.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION HCERR_INVALID_OID
Retrieves a metadata record for the specified OID.
hcerr_t hc_retrieve_metadata_ez (hc_session_t *session, hc_oid *oid, hv_nvr_t **nvrp);
This function retrieves a metadata record for the specified OID. When it has finished, you should call hc_nvr_free to free the name-value-record.
session
IN: The session for the host and port to talk to.
oid
IN: An identifier of the metadata record to retrieve.
nvrp
OUT: Updated with a pointer to a dynamically allocated name-value record with the metadata.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION HCERR_INVALID_OID
Retrieves a specified range of data for a specified OID.
hc_range_retrieve_ez(hc_session_t *session, write_to_data_destination data_writer, void *cookie, hc_oid *oid, hc_long_t; firstbyte, hc_long_t lastbyte);
This function retrieves a specified range of data for a specified OID.
session
IN: The session for the host and port to talk to.
data_writer
IN: Function callback to store the retrieved data locally.
cookie
IN: Opaque data delivered to the data_writer callback to identify this data cookie.
oid
IN: An identifier of the data record to retrieve.
firstbyte
IN: First byte of data range to retrieve.
lastbyte
IN: Last byte of data range to retrieve, or -1 for the end of the record.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION HCERR_INVALID_OID HCERR_ILLEGAL_ARGUMENT
The following functions are defined for simple queries:
The following functions are defined for prepared statement queries:
Prepared statement example:
Querying With a Prepared Statement
Retrieves OIDs and optionally name-value records matching a query.
hcerr_t hc_query_ez(hc_session_t *session, hc_string_t query, hc_string_t selects[], int n_selects, int results_per_fetch, hc_query_result_set_t **rsetp);
This function retrieves OIDs and optionally name-value records matching a query. If the selects list is NULL, only OIDs are retrieved. If selects is not NULL, name-value records are also retrieved and should each be freed using hc_nvr_free. In both cases the result set should be freed using hc_qrs_free.
When a query is incorrect and elicits an error from the server, the error is often reported after hc_qrs_freeand not from hc_query_ez. Your application should be prepared to receive and report an error from either place.
session
IN: The session for the host and port to talk to.
query
IN: Query (where clause with names in single quotes).
selects
IN: Points to an array of hc_string_t, each member of which is the name of a field to retrieve from the metadata (select clause). Set to NULL to only retrieve OIDs matching the query.
n_selects
IN: The number of items in the select clause.
results_per_fetch
IN: The number of results to return on each fetch from the server. results_per_fetch must be greater than 0.
rsetp
OUT: Updated to point to the new result set. See hc_query_result_set_t.
HCERR_OK HCERR_OOM HCERR_BAD_REQUEST HCERR_NULL_SESSION HCERR_INVALID_SESSION HCERR_ILLEGAL_ARGUMENT
Fetches the next OID and optionally name-value record from the QueryResultSet.
hcerr_t hc_qrs_next_ez(**rset, hc_oid *oid, hc_nvr_t **nvrp, int *finishedp);
This function fetches an OID and optionally name-value record from the query result set. Once the last result is fetched, in subsequent calls the int pointed to by finishedp is set to 1.
rset
IN: Current query result set. See hc_query_result_set_t.
oid
OUT: Points to an OID that is updated to the OID of a record matching the query, assuming finishedp is 0.
nvrp
OUT: Updated to point to a name-value record with the metadata from the OID matching the query, assuming the query specified selects and assuming finishedp is 0. Note that you must free the name-value record using hc_nvr_free.
finishedp
OUT: Points to an int that is updated to 0 if query data has been returned and to 1 if the result set is empty.
HCERR_OK HCERR_OOM HCERR_BAD_REQUEST HCERR_INVALID_RESULT_SET HCERR_ILLEGAL_ARGUMENT
Indicates whether results of this query are complete in the sense that all objects that match the query, aside from possible store index exceptions, are included in the result set,
hcerr_t hc_qrs_is_query_complete(hc_query_result_set_t *rset, int *completep);
Indicates whether results of this query are complete in the sense that all objects that match the query, aside from possible store index exceptions, are included in the result set. Applications that depend on completeness of query results can interrogate hc_qrs_is_query_complete after retrieving all the query results that match a particular query. When completep is set to 1, the only items that should be missing from the result set are store index exceptions that were indicated to the application by a value of 0 in the is_indexed field of the hc_system_record_t structure returned from the store.
rset
IN: Current query result set. See hc_query_result_set_t.
completep
OUT: Points to an int that is updated to 1 if all objects that match the query (other than potential store index exceptions) should be present in the result set
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_RESULT_SET
Returns a time that helps get more detail on which store index exceptions might still be unresolved.
hcerr_t hc_qrs_get_query_integrity_time(hc_query_result_set_t *rset, hc_long_t *query_timep);
If the query integrity time is non-zero, then all store index exceptions whose object creation time falls before the query integrity time have been resolved. Stored objects from before that time should show up in all matching query result sets. Store index exceptions that occurred after that time may not yet have been resolved, and hence might still be missing from a matching query result set. If the Query Integrity Time is zero, then the set of results in this ResultSet is not known to be complete. Note that hc_is_query_complete will return a non-zero completep value if and only if hc_get_query_integrity_time would set query_timep to non-zero query integrity time.
Time values from getQueryIntegrityTime can be compared to object creation time values returned in the creation_time field of the hc_system_record_t structure to determine if a particular store operation has been resolved. Note: the query integrity time as reported may well be earlier than the actual oldest time of a still-unresolved store index exception. The query integrity time can even go backwards, in other words, a later query can report an earlier query integrity time.
rset
Updated to point to the new query result set. See hc_query_result_set_t.
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_RESULT_SET
Releases the resources associated with this QueryResultSet.
hcerr_t hc_qrs_free (**rsetp);
This function releases the resources associated with this QueryResultSet.
When a query is incorrect and elicits an error from the server, the error is often reported after hc_qrs_free and not from hc_query_ez. Your application should be prepared to receive and report an error from either place.
rset
HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_RESULT_SET
Creates an hc_pstmt_t for use with the hc_pstmt_query_ez function.
hcerr_t hc_pstmt_create(hc_session_t *session, hc_string_t query, hc_pstmt_t **ptr);
This function creates a prepared statement for use with the hc_pstmt_query_ez function.
session
IN: session that this query will be used with.
query
IN: Query (where clause with ”?’ for values).
ptr
OUT: Updated to point to opaque hc_pstmt_t.
HCERR_OK HCERR_OOM
Frees a hc_pstmt_t with all its bindings.
hcerr_t hc_pstmt_free(hc_pstmt_t *pstmt);
This function frees a prepared statement.
pstmt
Prepared statement to be freed.
HCERR_OK
Adds a string binding to a hc_pstmt_t.
hcerr_t hc_pstmt_set_string(hc_pstmt_t *pstmt, int which, hc_string_t value);
This function binds an hc_string_t to one of the variables in a prepared statement. The variable must be of the appropriate type in the database, that is, string (UTF-8). Errors in binding and type are returned when the hc_pstmt_t is used to query the server.
pstmt
Prepared statement to add the binding to.
which
IN: Variable (”?’) in the prepared statement, numbered from 1.
value
IN: String to bind.
HCERR_OK HCERR_OOM
Adds a char binding to a hc_pstmt_t.
hcerr_t hc_pstmt_set_char(hc_pstmt_t *pstmt, int which,char *value);
This function binds a char * Latin-1 string to one of the variables in a prepared statement. The variable must be of the appropriate type in the database. Errors in binding and type are returned when the hc_pstmt_t is used to query the server.
pstmt
Prepared statement to add the binding to.
which
IN: Variable (”?’) in the prepared statement, numbered from 1.
value
IN: char * string to bind.
HCERR_OK HCERR_OOM
Adds a double precision binding to a hc_pstmt_t.
hcerr_t hc_pstmt_set_double(hc_pstmt_t *pstmt, int which, hc_double_t value)
This function binds an hc_double_t to one of the variables in a prepared statement. The variable must be of the appropriate type in the database. Errors in binding and type are returned when the hc_pstmt_t is used to query the server.
pstmt
Prepared statement to add the binding to.
which
IN: Variable (”?’) in the prepared statement, numbered from 1.
value
IN: Double precision value to bind.
HCERR_OK HCERR_OOM
Adds a hc_long_t binding to a hc_pstmt_t.
hcerr_t hc_pstmt_set_long(hc_pstmt_t *pstmt, int which, hc_long_t value);
This function binds an hc_long_t to one of the variables in a prepared statement. The variable must be of the appropriate type in the database. Errors in binding and type are returned when the hc_pstmt_t is used to query the server.
pstmt
Prepared statement to add the binding to.
which
IN: Variable (”?’) in the prepared statement, numbered from 1.
value
IN: hc_long_t value to bind to.
HCERR_OK HCERR_OOM
Adds a date binding to a hc_pstmt_t.
#include <time.h> hcerr_t hc_pstmt_set_date(hc_pstmt_t *pstmt, int which, struct tm *value);
This function binds a date in the form of the POSIX struct to one of the variables in a prepared statement. The variable must be of the appropriate type in the database. Errors in binding and type are returned when the hc_pstmt_t is used to query the server.
The struct tm fields are as defined in the POSIX standard and interpreted by mktime(3C). All fields are ignored except:
int tm_mday; /* day of the month - [1, 31] */ int tm_mon; /* months since January - [0, 11] */ int tm_year; /* years since 1900 */
pstmt
Prepared statement to add the binding to.
which
IN: Variable (”?’) in the prepared statement, numbered from 1.
value
IN: struct tm (time.h) value to bind.
HCERR_OK HCERR_OOM
Adds a time-of-day binding to a hc_pstmt_t.
#include <time.h> hcerr_t hc_pstmt_set_time(hc_pstmt_t *pstmt, int which, time_t *value);
This function binds a time of day in seconds to one of the variables in a prepared statement. The variable must be of the appropriate type in the database. Errors in binding and type are returned when the hc_pstmt_t is used to query the server.
pstmt
Prepared statement to add the binding to.
which
IN: Variable (”?’) in the prepared statement, numbered from 1.
value
IN: time_t (time.h) value to bind.
HCERR_OK HCERR_OOM
Adds a timestamp binding to a hc_pstmt_t.
#include <time.h> hcerr_t hc_pstmt_set_timestamp(hc_pstmt_t *pstmt, int which, struct timespec *value);
This function binds a timestamp in the form of the POSIX struct timespec to one of the variables in a prepared statement. The variable must be of the appropriate type in the database. Errors in binding and type are returned when the hc_pstmt_t is used to query the server.
pstmt
Prepared statement to add the binding to.
which
IN: Variable (”?’) in the prepared statement, numbered from 1.
value
IN: struct timespec (time.h) value to bind.
HCERR_OK HCERR_OOM
Adds a binary binding to a hc_pstmt_t.
hcerr_t hc_pstmt_set_binary(hc_pstmt_t *pstmt, int which, unsigned char *data,int size);
This function binds a binary array to one of the variables in a prepared statement. The variable must be of the appropriate type in the database. Errors in binding and type are returned when the hc_pstmt_t is used to query the server.
pstmt
Prepared statement to add the binding to.
which
IN: Variable (”?’) in the prepared statement, numbered from 1.
data
IN: Pointer to binary data to bind.
size
IN: Number of bytes in array of binary data.
HCERR_OK HCERR_OOM
Retrieves OIDs and optionally name-value records matching a prepared statement.
hcerr_t hc_pstmt_query_ez(*pstmt,hc_string_t selects[], int n_selects, int results_per_fetch, hc_query_result_set_t **rsetp);
This function retrieves OIDs and optionally name-value records matching a prepared statement. hc_qrs_next_ez is used to access the results in the result set. If the selects list is NULL, only OIDs are retrieved. If selects is not NULL, name-value records are also retrieved and should each be freed using hc_nvr_free. In both cases the result set should be freed using hc_qrs_free.
When a query is incorrect and elicits an error from the server, the error is often reported after hc_qrs_free and not from hc_pstmt_query_ez. Your application should be prepared to receive and report an error from either place.
pstmt
IN: Prepared statement generated by hc_pstmt_create.
selects
IN: Points to an array of hc_string_t, each of which is the name of a field to retrieve from the metadata (select clause). Set to NULL to only retrieve OIDs matching the query.
n_selects
IN: The number of items in the select clause.
results_per_fetch
IN: The number of results per internal fetch.
rsetp
OUT: Updated to point to the new result set. See hc_query_result_set_t.
HCERR_OK HCERR_OOM HCERR_BAD_REQUEST HCERR_NULL_SESSION HCERR_INVALID_SESSION HCERR_ILLEGAL_ARGUMENT