Chapter 3 Sun StorageTek 5800 System C Client API
This chapter provides detailed information on the 5800 system C client API.
The following topics are discussed:
Overview of the 5800 System C Client API
This section provides an overview of the 5800 system C client API. The following topics are discussed:
Architecture
The 5800 system C API client supports two different access patterns: a synchronous “EZ” access very similar to the current Java implementation, and a more flexible, nonblocking access based on the POSIX model.
Note –
For this release, the nonblocking C API client is not implemented.
Interfaces
The C client library interacts with the 5800 system server entirely through an HTTP protocol.
Retrying Operations
Calls to the C API should be wrapped with retry logic so that their applications are resilient to transient failures that may be experienced when a node or switch fails while servicing an operation.
Multithreaded Access
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.
Caution – Name resolution must be done in a single thread with the subsequent IP address passed to hc_session_create_ez, otherwise core dumps will occur if multiple name resolution threads call getaddrinfo at the same time.
Performance and Scalability
The 5800 system C client library provides high performance and is highly scalable.
The synchronous C API performs its own calls to select() internally.
For the nonblocking C API (not yet implemented), access is provided to the underlying fd_set so that all pending I/O operations can be serviced by a single thread on the basis of status returned by the POSIX select() function, possibly after merging the 5800 system fd_set with some external, application-specific fd_set.
Memory Usage
The 5800 system C client library generally follows the model of populating externally allocated data structures such as handles, buffers, and result arrays.
Some internal data structures are generated during XML document construction. These data structures are allocated and freed using the function pointers supplied to hc_init when initializing the library (see Initializing a Global Session).
Other data structures are allocated and returned to the user; these have corresponding functions to free them. For example, hc_session_create_ez and hc_session_free.
Updating Schema Definitions
The C client library does not automatically refresh its in-memory schema definitions. If the schema is changed through the command-line interface (CLI), a new session must be created with a new call to hc_session_create_ez to access the schema changes.
Session Management
A global session must be explicitly initialized with a call to hc_init and released with a call to hc_cleanup. Memory allocators and deallocators are supplied in the initialization function to control how memory allocation occurs. You will normally supply the standard malloc, free, and realloc functions for this functionality.
Heap Memory Allocator
The heap memory allocator is defined as follows:
typedef void* (*allocator_t) (size_t size);
Heap Memory Deallocator
The heap memory deallocator is defined as follows:
typedef void (*deallocator_t) (void *p);
Heap Memory Reallocator
The heap memory reallocator is defined as follows:
typedef void (*reallocator_t) (void *p,size_t size);
Initializing a Global Session
The following function initializes a global session:
hcerr_t hc_init(allocator_t,
deallocator_t,
reallocator_t);
This function must be called once per process to initialize the memory functions used in the 5800 system C API. It also initializes global session properties.
A global session is initialized once per process, regardless of how many threads in that process are using the C API.
Note –
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.
Note –
For more information on hc_session_create_ez , see hc_session_create_ez.
Terminating a Global Session
The following function terminates a global session:
void hc_cleanup();
System Record
All 5800 system store operations return a system record, which encapsulates information about the stored object. In particular, the system record contains the OID, which can be used to retrieve the stored object data or metadata.
typedef struct hc_system_record_ {
char is_indexed;
hc_oid oid;
hc_digest_algo digest_algo;
hc_digest data_digest;
hc_long_t size;
hc_long_t creation_time;
hc_long_t deleted_time;
char shredMode;
} hc_system_record_t;
About the fields:
-
oid — The objectid for this object, equivalent to the system.object_id field.
-
digest_algo — Always set to "sha1" for this release. Equivalent to the system.object_hash_alg field.
-
data_digest — An array of bytes that represent the content digest of this object's data. Equivalent to the system.object_hash field.
-
size — The size of the data in this object, in bytes. Equivalent to the system.object_size field.
-
creation_time — The object creation time, expressed as number of milliseconds since the epoch. Equivalent to the system.object_ctime field.
-
deleted_time — The deletion time of this record, if any, as the number of milliseconds since the epoch.
-
shredMode — Not used in this release.
-
is_indexed — indicates, after a store_data or store_metadata operation, whether the metadata for the object was successfully inserted into the query engine, and the object is hence available for query. 0 if false, 1 if true.
Failure and Recovery
Every function in the 5800 system C client library returns a result code of type hcerr_t. Any value other than HCERR_OK indicates a nonrecoverable error. See the hc.h file for specific error codes.
C Client Application Deployment
C applications using the 5800 system C API use both the 5800 systemlibraries and the curl libraries. These libraries are different for each supported platform (Windows, Linux, Solaris (x86), Solaris (SPARC)) and are located in the c/<OS>/lib directory in the SDK.
Note –
The environment variable http_proxy should not be set for processes using the C API, since the HTTP client library ( curl) makes use of it.
Nonblocking C API
The nonblocking C API is not implemented for this release of the 5800 system. If you are interested in working with the nonblocking C API, contact your 5800 system Sales Representative.
Synchronous C API
A multiplatform synchronous C API in which operations are accomplished in a few simple function calls is provided for the 5800 system. The API calls include operations for storing, retrieving, deleting, and querying of data and metadata records. Multiple threads are supported, and operations block until they complete.
You must call hc_init (once per process) and hc_session_create_ez (once per thread) prior to making any other API calls.
All functions in the 5800 system C API return an hc_err. Any value other than HCERR_OK indicates failure.
This section discusses the following topics for the 5800 system synchronous C API.
Changes for This Release
This release of the synchronous C API contains the following changes:
-
Handling is added for storing, retrieving and querying the following new metadata types:
-
unicode
-
binary
-
date
-
time
-
timestamp
Query and queryplus are merged
-
-
Prepared statements (pstmts) are introduced to handle values of queries that cannot be placed inline, and a new query is introduced to handle them.
-
The following new functions have been added to the API:
The following functions have changed in the API:
The following functions and types have been removed from the API:
-
hc_query_plus_result_set_t
-
hc_query_plus_ez
-
hc_qprs_next_ez
-
hc_qprs_free
Limitations
This release of the synchronous C API is subject to the following limitations:
-
Changes to the metadata schema at the server are only detected at the client at the next call to hc_session_create_ez.
-
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.
-
When using the C API, the maximum metadata size of a data item stored using either hc_store_both_ez or hc_store_metadata_ez is limited to approximately 76300 bytes. The exact maximum metadata size depends on many factors and should not be relied on. This limitation does not apply to metadata stored using the Java API.
Synchronous C Data Types
The following data types are defined for the C API:
hc_string_t
Type for holding Unicode (UTF-8) and Latin-1 null-terminated strings.
Synopsis
typedef char *hc_string_t;
Description
This type is used interchangeably for holding Unicode (UTF-8) and Latin-1 null-terminated metadata strings. The context determines whether the contents are UTF-8 or Latin-1.
hc_long_t
Type for holding integer values.
Synopsis
typedef int64_t hc_long_t;
Description
Type for holding integer values.
hc_double_t
Type for holding floating-point values.
Synopsis
typedef double hc_double_t;
Description
Type for holding floating-point values.
hc_type_t
5800 system name-value metadata type specifier.
Synopsis
typedef enum hc_types_{
HC_UNKNOWN_TYPE = -1,
HC_BOGUS_TYPE = 0,
HC_STRING_TYPE = 1,
HC_LONG_TYPE = 2,
HC_DOUBLE_TYPE = 3,
HC_BYTE_TYPE = 4,
HC_CHAR_TYPE = 5,
HC_BINARY_TYPE = 6,
HC_DATE_TYPE = 7,
HC_TIME_TYPE = 8,
HC_TIMESTAMP_TYPE = 9,
HC_OBJECTID_TYPE = 10,
} hc_type_t;
Description
Specifies one of the 5800 system metadata types that can go in the archive.
hc_value_t
5800 system name-value metadata data value.
Synopsis
typedef struct hc_value_ {
hc_type_t hcv_type;
union {
hc_string_t hcv_string;
hc_long_t hcv_long;
hc_double_t hcv_double;
hc_bytearray_t hcv_bytearray;
struct tm hcv_tm;
struct timespec hcv_timespec;
} hcv;
} hc_value_t;
Description
This tagged union type can be used to hold a reference to any of the 5800 system data types.
hc_schema_t
5800 system name-value metadata schema.
Synopsis
typedef void hc_schema_t;
Description
An opaque structure that holds the names and data types of each element in the archive’s metadata schema.
hc_nvr_t
5800 system name-value record.
Synopsis
typedef void hc_nvr_t;
Description
An opaque structure to represent one metadata record. There is a count of metadata tuples, and parallel sets of names and of typed values for the tuples in this metadata record.
hc_session_t
Structure describing the connection from one thread to one 5800 system server.
Synopsis
typedef void hc_session_t;
Description
An opaque structure to represent the session from one thread to one 5800 system server. It contains the schema used to interpret metadata store and retrieve operations to this 5800 system server.
hc_pstmt_t
Structure for holding a prepared statement.
Synopsis
typedef void hc_pstmt_t;
Description
An opaque structure representing a query, including the query text and bound fields.
hc_query_result_set_t
Structure used to hold the results of a query.
Synopsis
typedef void hc_query_result_set_t;
Description
This opaque structure is used to hold the results of a query. For more information on the functions that use this structure, see Querying Metadata.
read_from_data_source
Data source template used to upload object data to the cluster.
Synopsis
typedef long (*read_from_data_source)
(void *cookie, char *buf, long buf_size);
Description
Function pointers of read_from_data_source type are used to upload object data. The function pointer and opaque cookie reference are supplied as arguments to hc_store_both_ez and other functions that store object data. The data source reader function will be called repeatedly, with the supplied cookie as an argument, to gather the object data to upload into storage.
A read_from_data_source function should read up to buf_size bytes from the data source indicated by cookie into the buffer at location buff and return the actual number of bytes read as the return value from the function.
There are two special return codes:
-
A return value of 0 indicates the end-of-file condition. The data should be committed to the data store.
-
A return value of -1 indicates a request to cancel the store. The store operation should be aborted with an error code of HCERR_ABORTED_BY_CALLBACK.
Parameters
cookie
An opaque data structure to identify this data cookie. The cookie is likely to be an open file descriptor.
buf
Where to store the data.
buf_size
The number of available bytes of space in buf.
See Also
write_to_data_destination
Data destination template used to download object data to the cluster.
Synopsis
typedef long (*write_to_data_destination)
(void *cookie, char *buff, long buff_len);
Description
Function pointers of write_to_data_destination type are used to download object data to a network or other destination from the 5800 system server using hc_retrieve_ez. The function pointer and opaque cookie reference are supplied as arguments to hc_retrieve_ez, and the function will be called with the supplied cookie argument to deliver the downloaded data to a local data storage function.
A write_to_data_destination function should write exactly buff_len bytes to the data destination indicated by cookie, reading the bytes from the buffer at location buff. It should return a long value indicating the number of bytes actually processed. A return code that differs from buff_len indicates that the transfer should be terminated.
Parameters
- cookie
-
An opaque data structure to identify this data cookie. The cookie is likely to be an open file descriptor.
- buff
-
Where to copy the data from.
- buff_len
-
The number of bytes of space in buff.
See Also
hcerr_t
5800 system C client API error codes.
To decode hcerr_t values into strings, see hc_decode_hcerr
Synopsis
typedef enum hcerr {
HCERR_OK = 0,
HCERR_NOT_INITED,
HCERR_ALREADY_INITED,
HCERR_INIT_FAILED,
HCERR_OOM,
HCERR_NOT_YET_IMPLEMENTED,
HCERR_SESSION_CREATE_FAILED,
HCERR_ADD_HEADER_FAILED,HCERR_IO_ERR,
HCERR_FAILOVER_OCCURRED,
HCERR_CAN_CALL_AGAIN,
HCERR_GET_RESPONSE_CODE_FAILED,
HCERR_CONNECTION_FAILED,
HCERR_BAD_REQUEST,
HCERR_NO_SUCH_OBJECT,
HCERR_INTERNAL_SERVER_ERROR,
HCERR_FAILED_GETTING_FDSET,
HCERR_FAILED_CHECKING_FDSET,
HCERR_MISSING_SELECT_CLAUSE,
HCERR_URL_TOO_LONG,
HCERR_COULD_NOT_OPEN_FILE,
HCERR_FAILED_TO_WRITE_TO_FILE,
HCERR_NULL_SESSION,
HCERR_INVALID_SESSION,
HCERR_INVALID_OID,
HCERR_NULL_HANDLE,
HCERR_INVALID_HANDLE,
HCERR_INVALID_SCHEMA,
HCERR_INVALID_RESULT_SET,
HCERR_INVALID_NVR,
HCERR_WRONG_HANDLE_FOR_OPERATION,
HCERR_HANDLE_IN_WRONG_STATE_FOR_OPERATION,
HCERR_READ_PAST_LAST_RESULT,
HCERR_XML_PARSE_ERROR,
HCERR_XML_MALFORMED_XML,
HCERR_XML_EXPECTED_LT,
HCERR_XML_INVALID_ELEMENT_TAG,
HCERR_XML_MALFORMED_START_ELEMENT,
HCERR_XML_MALFORMED_END_ELEMENT,
HCERR_XML_BAD_ATTRIBUTE_NAME,
HCERR_XML_BUFFER_OVERFLOW,
HCERR_BUFFER_OVERFLOW,
HCERR_NO_SUCH_TYPE,
HCERR_ILLEGAL_VALUE_FOR_METADATA,
HCERR_NO_SUCH_ATTRIBUTE,
HCERR_NO_MORE_ATTRIBUTES,
HCERR_EOF,HCERR_FAILED_GETTING_SILO_DATA,
HCERR_PLATFORM_NOT_INITED,
HCERR_PLATFORM_ALREADY_INITED,
HCERR_PLATFORM_INIT_FAILED,
HCERR_PLATFORM_HEADER_TOO_LONG,
HCERR_PLATFORM_TOO_LATE_FOR_HEADERS,
HCERR_PLATFORM_NOT_ALLOWED_FOR_GET,
HCERR_FAILED_TO_GET_SYSTEM_RECORD,
HCERR_PARTIAL_FILE,
HCERR_ABORTED_BY_CALLBACK,
HCERR_PLATFORM_GENERAL_ERROR,
HCERR_ILLEGAL_ARGUMENT
} hcerr_t;
Description
This structure defines the 5800 system C client API error codes.
Synchronous C API Functions
The 5800 system synchronous C API functions are defined to perform the following tasks:
Managing 5800 System Sessions
The following functions are used to manage 5800 system sessions:
hc_session_create_ez
Creates a session.
Synopsis
hcerr_t hc_session_create_ez(char *host,
int port,
hc_session_t **sessionp);
Description
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.
Note –
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
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_ILLEGAL_ARGUMENT
hc_session_free
Releases the session object.
Synopsis
hcerr_t hc_session_free (hc_session_t *session);
Description
This function releases the session object and recovers handles and memory for one connection.
Parameters
session
IN: The session object to free.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
hc_session_get_status
Gets the session status.
Synopsis
hcerr_t hc_session_get_status(hc_session_t *session,
int32_t *response_codep,char **errstrp);
Description
This function returns the HTTP response code and the error message string associated with the last request on this session.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
hc_session_get_schema
Gets schema object associated with this session.
Synopsis
hcerr_t hc_session_get_schema (hc_session_t *session,
hc_schema_t **schemap);
Description
This function returns the current schema object associated with this session.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
hc_session_get_host
Returns the host name and port number associated with the session.
Synopsis
hc_session_get_host(hc_session_t *session,
char **hostp,int *portp);
Description
This function returns the host name and port number associated with the session.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
hc_session_get_platform_result
Returns low-level error codes associated with the current session.
Synopsis
hcerr_t hc_session_get_platform_result(hc_session_t *session,
int32_t *connect_errnop,
int32_t *platform_resultp);
Description
This function returns low-level error codes associated with the current session.
Note –
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.
Parameters
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).
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
hc_session_get_archive
Returns the current archive object associated with this session.
Synopsis
hcerr_t hc_session_get_archive(hc_session_t *session,
hc_archive_t **archivep);
Description
This function returns the current archive object associated with this session.
Note –
The archive object is not needed for the synchronous C API, but is made available for interfacing with the lower-level (nondocumented) API.
Parameters
session
IN: The session object.
archivep
OUT: Updated to be the archive object associated with the current session.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
Managing a Schema
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:
hc_schema_get_type
Looks up type in schema.
Synopsis
hcerr_t hc_schema_get_type(hc_schema_t *schema,
char *name, hc_type_t *typep);
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_SCHEMA
HCERR_ILLEGAL_ARGUMENT
hc_schema_get_length
Looks up length of char and string attribute fields.
Synopsis
hcerr_t hc_schema_get_length(hc_schema_t *schema,
char *name, int *length);
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_INVALID_SCHEMA
HCERR_ILLEGAL_ARGUMENT
hc_schema_get_count
Returns the number of name-value pairs in the metadata schema.
Synopsis
hcerr_t hc_schema_get_count(hc_schema_t *hsp,
hc_long_t *countp);
Description
This function returns the number of name-value pairs in the metadata schema.
Parameters
hsp
IN: The schema to interrogate.
countp
OUT: Updated with the number of name-value pairs in the schema.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_SCHEMA
See Also
hc_schema_get_type_at_index
Iterates through the name-value pairs in a schema.
Synopsis
hcerr_t hc_schema_get_type_at_index (hc_schema_t *hsp,
hc_long_t index,char **namep,
hc_type_t *typep);
Description
This function provides a simple way to iterate through the name-value pairs in a schema.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_SCHEMA
HCERR_ILLEGAL_ARGUMENT
See Also
Manipulating Name-Value Records
5800 system synchronous C API functions are defined to perform the following name-value record manipulation tasks:
Using the API for Storing Name-Value Records
A common way of storing metadata in the synchronous C API for the 5800 system is to use the name-value record API.
To Use the API for Storing Name-Value Records
-
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.
Using Returned Name-Value Records
Name-value records are also returned as the result of queries that return metadata information, such as hc_retrieve_metadata_ez.
To Use Returned Name-Value Records
-
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.
Note –Structures created by hc_nvr_create can also be freed by calling hc_nvr_free.
Creating and Freeing Name-Value Records
The following functions are defined to create and free name-value records:
hc_nvr_create
Creates a name-value record.
Synopsis
hcerr_t hc_nvr_create(hc_session_t *session,
hc_long_t nslots,
hc_nvr_t **nvrp);
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_ILLEGAL_ARGUMENT
HCERR_OOM
See Also
hc_nvr_free
Frees a name-value record.
Synopsis
hcerr_t hc_nvr_free(hc_nvr_t *nvr);
Description
This function frees a name-value record that was created by hc_nvr_create.
Parameter
nvr
IN: Points to the name-value-record to be freed.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
See Also
Building Name-Value Records
The following functions are defined to build name-value records:
hc_nvr_add_value
Adds a new metadata value.
Synopsis
hcerr_t hc_nvr_add_value(hc_nvr_t *nvr,
char *name, hc_value_t value);
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_NO_SUCH_ATTRIBUTE
hc_nvr_add_long
Adds a new metadata value of type hc_long_t.
Synopsis
hcerr_t hc_nvr_add_long(hc_nvr_t *nvr,
char *name, hc_long_t value)
Description
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.
Parameters
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The hc_long_t value.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_NO_SUCH_ATTRIBUTE
hc_nvr_add_double
Adds a new metadata value of type hc_double_t.
Synopsis
hcerr_t hc_nvr_add_double(hc_nvr_t *nvr,
char *name,
hc_double_t value);
Description
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.
Parameters
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The hc_double_t value.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_NO_SUCH_ATTRIBUTE
hc_nvr_add_string
Adds a new metadata value of type Unicode UTF-8 string.
Synopsis
hcerr_t hc_nvr_add_string(hc_nvr_t *nvr,
char *name,
hc_string_t value);
Description
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.
Parameters
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The hc_string_t value.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_NO_SUCH_ATTRIBUTE
hc_nvr_add_binary
Adds new metadata value of type binary.
Synopsis
hcerr_t hc_nvr_add_binary(hc_nvr_t *nvr,
hc_string_t name,
int size,
unsigned char *bytes);
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_NO_SUCH_ATTRIBUTE
hc_nvr_add_date
Adds new metadata value of type date.
Synopsis
#include <time.h>
hcerr_t hc_nvr_add_date(hc_nvr_t *nvr,
hc_string_t name,struct tm *value);
Description
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.
Parameters
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The struct tm (time.h) value.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_NO_SUCH_ATTRIBUTE
hc_nvr_add_time
Adds new metadata value of type time.
Synopsis
#include <time.h>
hcerr_t hc_nvr_add_time(hc_nvr_t *nvr,
hc_string_t name,
time_t *value);
Description
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.
Parameters
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The time_t (time.h) value.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_NO_SUCH_ATTRIBUTE
hc_nvr_add_timestamp
Adds new metadata value of type timestamp.
Synopsis
#include <time.h>
hcerr_t hc_nvr_add_timestamp(hc_nvr_t *nvr,
hc_string_t name,
struct timespec *value);
Description
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.
Parameters
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The ’struct timespec’ (time.h) value.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_NO_SUCH_ATTRIBUTE
hc_nvr_add_from_string
Adds a new metadata value where the value always starts out as a string.
Synopsis
hcerr_t hc_nvr_add_from_string(hc_nvr_t *nvr,
char *name,
char *value);
Description
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.
Parameters
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
IN: The string value to be added.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
Retrieving Name-Value Records
The following functions are defined to retrieve name-value records:
hc_nvr_get_count
Retrieves the number of metadata name and value tuples in this name-value record.
Synopsis
hcerr_t hc_nvr_get_count(hc_nvr_t *nvr,
hc_long_t *retcount);
Description
This function retrieves the number of metadata name and value tuples in the specified name-value record.
Parameters
nvr
IN: Points to a name-value-record.
retcount
OUT: Updated to contain the count of name-value pairs.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
hc_nvr_get_value_at_index
Iterates through the names and values in a name-value record.
Synopsis
hc_nvr_get_value_at_index(hc_nvr_t *nvr,
hc_long_t index,
char **namep,
hc_value_t *valuep);
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
HCERR_NO_MORE_ARGUMENTS
HCERR_OOM
hc_nvr_get_long
Retrieves a value of type hc_long_t.
Synopsis
hcerr_t hc_nvr_get_long(hc_nvr_t *nvr,
char *name,
hc_long_t *retlong);
Description
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.
Parameters
nvr
Points to a name-value-record.
name
IN: Attribute name to look for.
retlong
OUT: Updated to contain the hc_long_t value.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_ILLEGAL_ARGUMENT
hc_nvr_get_double
Retrieves a value of type hc_double_t.
Synopsis
hcerr_t hc_nvr_get_double(hc_nvr_t *nvr,
char *name,
hc_double_t *retdouble);
Description
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.
Parameters
nvr
Points to a name-value-record.
name
IN: Attribute name to look for.
retdouble
OUT: Updated to contain the hc_double_t value.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_ILLEGAL_ARGUMENT
hc_nvr_get_string
Retrieves a value of a Unicode UTF-8 string.
Synopsis
hcerr_t hc_nvr_get_string(hc_nvr_t *nvr,
char *name,
hc_string_t *retstring);
Description
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.
Parameters
nvr
Points to a name-value-record.
name
IN: Attribute name to look for.
retstring
OUT: Updated to contain the hc_string_t value.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_ILLEGAL_ARGUMENT
hc_nvr_get_binary
Retrieves a metadata value of type binary.
Synopsis
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_NO_SUCH_ATTRIBUTE
hc_nvr_get_date
Retrieves metadata value of type date.
Synopsis
#include <time.h>
hcerr_t hc_nvr_get_date(hc_nvr_t *nvr,
hc_string_t name,
struct tm *value);
Description
This function retrieves the value of type struct tm associated with an indicated attribute name in a name-value record.
Parameters
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
OUT: Updated with the struct tm (time.h) value.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_NO_SUCH_ATTRIBUTE
hc_nvr_get_time
Retrieves metadata value of type time.
Synopsis
#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.
Parameters
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
OUT: Updated with the time_t (time.h) value.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_NO_SUCH_ATTRIBUTE
hc_nvr_get_timestamp
Retrieves metadata value of type timestamp.
Synopsis
#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.
Parameters
nvr
Points to a name-value-record.
name
IN: Name for the tuple.
value
OUT: Updated with the struct timespec (time.h) value.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
HCERR_ILLEGAL_VALUE_FOR_METADATA
HCERR_NO_SUCH_ATTRIBUTE
Creating and Converting Name-Value Records From and To String Arrays
The following functions are defined to create name-value records from string arrays and convert name-value records to string arrays:
hc_nvr_create_from_string_arrays
Creates name-value-record from string names and string values.
Synopsis
hcerr_t hc_nvr_create_from_string_arrays(hc_session_t *session,
hc_nvr_t **nvrp,
char **names,
char **values,
hc_long_t nitems);
Description
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.
Note –
Any time there is a conversion from a double type to or from a string type, there might be a loss of precision.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
HCERR_ILLEGAL_ARGUMENT
hc_nvr_convert_to_string_arrays
Converts name-value-record to string names and string values.
Synopsis
hcerr_t hc_nvr_convert_to_string_arrays(hc_nvr_t *nvr,
char ***namesp,
char ***valuesp,
int *nitemsp);
Description
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.
Note –
Any time there is a conversion from a double type to or from a string type, there might be a loss of precision.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_NVR
HCERR_ILLEGAL_ARGUMENT
Storing Data and Metadata
The following functions are defined to store data and metadata and to enforce indexing of metadata where necessary:
Note –
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.
hc_store_both_ez
Stores a metadata record and associated data.
Synopsis
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);
Description
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.
Parameters
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.
Return Codes
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
hc_store_metadata_ez
Adds a metadata record for the specified OID.
Synopsis
hcerr_t hc_store_metadata_ez(hc_session_t *session,
hc_oid *oid,
hc_nvr_t *nvr,
hc_system_record_t *system_record);
Description
This function adds a metadata record for the specified OID and returns a system_record descriptor.
Parameters
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.
Return Codes
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
hc_check_indexed_ez
Checks if the metadata for an object is present in the query engine, and inserts it if not.
Synopsis
hcerr_t hc_check_indexed_ez(hc_session_t *session,
hc_oid *oid,
int *resultp);
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
HCERR_INVALID_OID
Retrieving Data and Metadata
The following functions are defined to retrieve data and metadata:
hc_retrieve_ez
Retrieves data for the specified OID.
Synopsis
hcerr_t hc_retrieve_ez(hc_session_t *session,
*data_writer,
void *cookie,
hc_oid *oid);
Description
This function retrieves data for the specified OID.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
HCERR_INVALID_OID
hc_retrieve_metadata_ez
Retrieves a metadata record for the specified OID.
Synopsis
hcerr_t hc_retrieve_metadata_ez (hc_session_t *session,
hc_oid *oid,
hv_nvr_t **nvrp);
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
HCERR_INVALID_OID
hc_range_retrieve_ez
Retrieves a specified range of data for a specified OID.
Synopsis
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);
Description
This function retrieves a specified range of data for a specified OID.
Parameters
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.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
HCERR_INVALID_OID
HCERR_ILLEGAL_ARGUMENT
Querying Metadata
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
hc_query_ez
Retrieves OIDs and optionally name-value records matching a query.
Synopsis
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);
Description
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.
Note –
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_OOM
HCERR_BAD_REQUEST
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
HCERR_ILLEGAL_ARGUMENT
See Also
hc_qrs_next_ez
Fetches the next OID and optionally name-value record from the QueryResultSet.
Synopsis
hcerr_t hc_qrs_next_ez(**rset,
hc_oid *oid,
hc_nvr_t **nvrp,
int *finishedp);
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_OOM
HCERR_BAD_REQUEST
HCERR_INVALID_RESULT_SET
HCERR_ILLEGAL_ARGUMENT
hc_qrs_is_query_complete
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,
Synopsis
hcerr_t hc_qrs_is_query_complete(hc_query_result_set_t *rset,
int *completep);
Description
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.
Parameters
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
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_RESULT_SET
hc_qrs_get_query_integrity_time
Returns a time that helps get more detail on which store index exceptions might still be unresolved.
Synopsis
hcerr_t hc_qrs_get_query_integrity_time(hc_query_result_set_t *rset,
hc_long_t *query_timep);
Description
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.
Parameter
rset
Updated to point to the new query result set. See hc_query_result_set_t.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_RESULT_SET
hc_qrs_free
Releases the resources associated with this QueryResultSet.
Synopsis
hcerr_t hc_qrs_free (**rsetp);
Description
This function releases the resources associated with this QueryResultSet.
Note –
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.
Parameter
rset
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_INVALID_RESULT_SET
See Also
hc_pstmt_create
Creates an hc_pstmt_t for use with the hc_pstmt_query_ez function.
Synopsis
hcerr_t hc_pstmt_create(hc_session_t *session,
hc_string_t query,
hc_pstmt_t **ptr);
Description
This function creates a prepared statement for use with the hc_pstmt_query_ez function.
Parameters
rset
Updated to point to the new query result set. See hc_query_result_set_t.
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.
Return Codes
HCERR_OK
HCERR_OOM
See Also
hc_pstmt_free
Frees a hc_pstmt_t with all its bindings.
Synopsis
hcerr_t hc_pstmt_free(hc_pstmt_t *pstmt);
Description
This function frees a prepared statement.
Parameters
pstmt
Prepared statement to be freed.
Return Codes
HCERR_OK
See Also
hc_pstmt_set_string
Adds a string binding to a hc_pstmt_t.
Synopsis
hcerr_t hc_pstmt_set_string(hc_pstmt_t *pstmt,
int which,
hc_string_t value);
Description
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.
Parameters
pstmt
Prepared statement to add the binding to.
which
IN: Variable (”?’) in the prepared statement, numbered from 1.
value
IN: String to bind.
Return Codes
HCERR_OK
HCERR_OOM
See Also
hc_pstmt_set_char
Adds a char binding to a hc_pstmt_t.
Synopsis
hcerr_t hc_pstmt_set_char(hc_pstmt_t *pstmt,
int which,char *value);
Description
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.
Parameters
pstmt
Prepared statement to add the binding to.
which
IN: Variable (”?’) in the prepared statement, numbered from 1.
value
IN: char * string to bind.
Return Codes
HCERR_OK
HCERR_OOM
See Also
hc_pstmt_set_double
Adds a double precision binding to a hc_pstmt_t.
Synopsis
hcerr_t hc_pstmt_set_double(hc_pstmt_t *pstmt,
int which,
hc_double_t value)
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_OOM
See Also
hc_pstmt_set_long
Adds a hc_long_t binding to a hc_pstmt_t.
Synopsis
hcerr_t hc_pstmt_set_long(hc_pstmt_t *pstmt,
int which,
hc_long_t value);
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_OOM
See Also
hc_pstmt_set_date
Adds a date binding to a hc_pstmt_t.
Synopsis
#include <time.h>
hcerr_t hc_pstmt_set_date(hc_pstmt_t *pstmt,
int which,
struct tm *value);
Description
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 */
Parameters
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.
Return Codes
HCERR_OK
HCERR_OOM
See Also
hc_pstmt_set_time
Adds a time-of-day binding to a hc_pstmt_t.
Synopsis
#include <time.h>
hcerr_t hc_pstmt_set_time(hc_pstmt_t *pstmt,
int which,
time_t *value);
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_OOM
See Also
hc_pstmt_set_timestamp
Adds a timestamp binding to a hc_pstmt_t.
Synopsis
#include <time.h>
hcerr_t hc_pstmt_set_timestamp(hc_pstmt_t *pstmt,
int which,
struct timespec *value);
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_OOM
See Also
hc_pstmt_set_binary
Adds a binary binding to a hc_pstmt_t.
Synopsis
hcerr_t hc_pstmt_set_binary(hc_pstmt_t *pstmt,
int which,
unsigned char *data,int size);
Description
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_OOM
See Also
hc_pstmt_query_ez
Retrieves OIDs and optionally name-value records matching a prepared statement.
Synopsis
hcerr_t hc_pstmt_query_ez(*pstmt,hc_string_t selects[],
int n_selects,
int results_per_fetch,
hc_query_result_set_t **rsetp);
Description
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.
Note –
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.
Parameters
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.
Return Codes
HCERR_OK
HCERR_OOM
HCERR_BAD_REQUEST
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
HCERR_ILLEGAL_ARGUMENT
See Also
Querying With a Prepared Statement
The following code is an example of querying with a prepared statement. Error handling is omitted. Two metadata fields are used with the definitions from the schema:
<field name="test_date" type="date">
<field name="test_status" type="string">
hcerr_t res;
time_t t;
struct tm *date;
hc_pstmt_t *pstmt;
hc_query_result_set_t *rset;
hc_string_t selects[] = { "test_status" };
// get today’s date
time(&t);
date = gmtime(&t);
// list all OIDs with today’s date
res = hc_pstmt_create(session, "test_date = ?", &pstmt);
res = hc_pstmt_set_date(pstmt, 1, date);
res = hc_pstmt_query_ez(pstmt, NULL, 0, 2000, &rset);
while (1) {
hc_oid oid;
int finished;
res = hc_qrs_next_ez(rset, &oid, NULL, &finished);
if (finished)
break;
printf("today’s oid: %s\n", oid);
}
res = hc_qrs_free(rset);
// list all OIDs from yesterday with test_status
t = 86400; // 86400 sec/day
date = gmtime(&t);
res = hc_pstmt_set_date(pstmt, 1, date);
res = hc_pstmt_query_ez(pstmt, selects, 1, 2000, &rset);
while (1) {
hc_oid oid;
hc_nvr_t *nvr int finished;
hc_string_t test_status;
res = hc_qrs_next_ez(rset, &oid, &nvr, &finished);
if (finished)
break;
res = hc_nvr_get_string(nvr, "test_status", &test_status);
printf("yesterday’s oid & test_status: %s %s\n", oid, test_status);
hc_nvr_free(nvr);
}
res = hc_qrs_free(rset);
Deleting Records
The following function is defined to delete records: hc_delete_ez.
hc_delete_ez
Deletes the metadata record for specified OID.
Synopsis
hcerr_t hc_delete_ez(hc_session_t *session,
hc_oid *oid);
Description
This function deletes the metadata record for the specified OID. When the last metadata record associated with a data object is deleted, the underlying data object is also deleted.
Parameters
session
IN: Pointer to the session.
oid
IN: The specified OID.
Return Codes
HCERR_OK
HCERR_BAD_REQUEST
HCERR_OOM
HCERR_NULL_SESSION
HCERR_INVALID_SESSION
HCERR_INVALID_OID
Translating Error and Type Codes
The following functions are defined for translating error codes and type codes into strings:
hc_decode_hcerr
Translates an error code into a string.
Synopsis
char *hc_decode_hcerr(hcerr_t res);
Description
Translates an error code into a string.
Parameter
res
IN: The error code returned by a function.
hc_decode_hc_type
Translates a type code into a string.
Synopsis
char *hc_decode_hc_type(hc_type_t type);
Description
Translates a type code into a string.
Parameters
type
IN: The type code to translate.
- © 2010, Oracle Corporation and/or its affiliates