Sun StorageTek 5800 SystemClient API Reference ManualSun Microsystems, Inc.4150 Network CircleSanta Clara, CA 95054U.S.A.Part No: 820–4796June 2008
hc_pstmt_createCreates an “hc_pstmt_t” on page 49 for use with the “hc_pstmt_query_ez” on page 109function.Synopsishcerr_t hc_pstmt_create(hc_session_
hc_pstmt_freeFrees a “hc_pstmt_t ” on page 49 with all its bindings.Synopsishcerr_t hc_pstmt_free(hc_pstmt_t *pstmt);DescriptionThis function frees a
ParameterspstmtPrepared statement to add the binding to.whichIN: Variable (”?’) in the prepared statement, numbered from 1.valueIN: String to bind.Ret
IN: Variable (”?’) in the prepared statement, numbered from 1.valueIN: char * string to bind.Return CodesHCERR_OKHCERR_OOMSee Also“hc_pstmt_create” on
Return CodesHCERR_OKHCERR_OOMSee Also“hc_pstmt_create” on page 100hc_pstmt_set_longAdds a “hc_long_t” on page 46 binding to a “hc_pstmt_t” on page 49.
See Also“hc_pstmt_create” on page 100hc_pstmt_set_dateAdds a date binding to a “hc_pstmt_t” on page 49.Synopsis#include <time.h>hcerr_t hc_pstmt
See Also“hc_pstmt_create” on page 100hc_pstmt_set_timeAdds a time-of-day binding to a “hc_pstmt_t” on page 49.Synopsis#include <time.h>hcerr_t h
hc_pstmt_set_timestampAdds a timestamp binding to a “hc_pstmt_t” on page 49.Synopsis#include <time.h>hcerr_t hc_pstmt_set_timestamp(hc_pstmt_t *
hc_pstmt_set_binaryAdds a binary binding to a “hc_pstmt_t” on page 49.Synopsishcerr_t hc_pstmt_set_binary(hc_pstmt_t *pstmt,int which,unsigned char *d
hc_pstmt_query_ezRetrieves OIDs and optionally name-value records matching a prepared statement.Synopsishcerr_t hc_pstmt_query_ez(*pstmt,hc_string_t s
PrefaceThe Sun StorageTek 5800 System Client API Reference Manual is written for programmers andapplication developers who develop custom applications
Return CodesHCERR_OKHCERR_OOMHCERR_BAD_REQUESTHCERR_NULL_SESSIONHCERR_INVALID_SESSIONHCERR_ILLEGAL_ARGUMENTSee Also“hc_pstmt_create” on page 100Queryi
// list all OIDs from yesterday with test_statust = 86400; // 86400 sec/daydate = gmtime(&t);res = hc_pstmt_set_date(pstmt, 1, date);res = hc_pstm
ParameterssessionIN: Pointer to the session.oidIN: The specied OID.Return CodesHCERR_OKHCERR_BAD_REQUESTHCERR_OOMHCERR_NULL_SESSIONHCERR_INVALID_SESS
hc_decode_hc_typeTranslates a type code into a string.Synopsischar *hc_decode_hc_type(hc_type_t type);DescriptionTranslates a type code into a string.
114
Sun StorageTek 5800 System Query LanguageThis chapter provides information on the 5800 system query language.Note – For details of the metadata system
OperationThe query format is similar to the where clause of an SQL query. The two main dierences arethat 5800 system queries do not contain embedded
QueriesA query in the 5800 system query language is translated into an equivalent query for theunderlying database that implements the query engine. T
SQL Syntax in 5800 System QueriesGeneral Unicode characters outside of the ASCII range in queries are allowed in only two placesto the 5800 system. Sp
Literals for 5800 System DataTypesFor each 5800 system data type, there is a syntax to include literals of that type in a query string.The syntax is {
Related Third-Party Web Site ReferencesThird-party URLs are referenced in this document and provide additional, related information.Note – Sun is not
When converting a typed value to a string as the result of the getAsString operation on aNameValueRecord or a QueryResultSet operation When parsing a
The following JDBC function escapes supported:TIMESTAMPDIFF, TIMESTAMPADD, CURRENT_TIMESTAMP, CURRENT_TIME, CURRENT_DATE,HOUR, MINUTE, SECOND.Reserve
expr [NOT] IN (valueslist).Note – The 5800 system emulator supports (but the cluster database does not) a JDBC“escape” clause that allows you to trea
Examples of Supported Query Expressions {fn LCASE(mp3.artist)} LIKE ’%floyd%’ AND system.object_size > 2000000 (object_size < 200) OR "Coll
SIN(float) SQRT(float) TAN(float)SQL WordsThat Are Allowed in QueriesSome SQL reserved words (such as BETWEEN or LIKE) are allowed in queries and are
DEALLOCATE, DECLARE, DEFAULT, DEFERRABLE, DEFERRED, DELETE, DESC, DESCRIBE,DESCRIPTOR, DETERMINISTIC, DIAGNOSTICS, DIRECTORY, DISCONNECT, DISTINCT, DO
126
Programming Considerations and BestPrac ticesThis chapter provides considerations and practices that can help you create ecient 5800system applicatio
eld consumes the same number of bytes as the length of the value. A string value consumestwice as many bytes as the length of the value. These sizes
IndexNumbers and Symbols5800 systemHoneycomb project, 17summary, 16-17Bbest practicesmax results per fetch, 128retries and timeouts, 127schema query s
TABLE P–1 Typographic Conventions (Continued)Typeface Meaning ExampleAaBbCc123 Book titles, new terms, and terms to beemphasizedRead Chapter 6 in the
data type, synchronous C API (Continued)hc_string_t,46hc_value_t, 47-48hcerr_t, 51-53read_from_data_source, 49-50write_to_data_destination, 50-51delet
metadata (Continued)retrieving, 91storing, 87hc_store_both_ez, 87-88metadata model, overview, 19-20modelsdata, 17-19deleting objects, 22-23metadata, 1
OID (Continued)retrieve metadata forhc_retrieve_metadata_ez,92retrieve range of data forhc_range_retrieve_ez, 93-94operationsretrying, 26, 40overview,
Rretries, 127retrieveMetadata method, 33retrieveObject method, 33retrying operations, 26, 40Sschemamanaging, 59-60hc_schema_get_count, 61-62hc_schema_
synchronous C API (Continued)error codestranslating into a string, 112fetch next OIDhc_qrs_next_ez, 96-97free prepared statementhc_pstmt_free, 101func
Ttimeouts, 127Index135
Sun StorageTek 5800 System Client APIThe SunTMStorageTekTM5800 system client API provides programmatic access to a 5800 systemserver to store, retriev
In 5800 system version 1.1, an attempt to store a value that is longer than the associated eldgenerates an immediate error.5800 System OverviewThis s
This chapter provides a summary of key points of the 5800 system usage model that are usefulfor understanding either API.In the following sections, th
Read-Multiple (WORM) archive. Each object corresponds to a single stream of data and asingle set of metadata; there are no “grouped objects” or “compo
The 5800 System Metadata ModelMetadata means “data about the data”; it describes the data and helps to determine how the datashould be interpreted. In
Copyright 2008 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. All rights reserved.Sun Microsystems, Inc. has intellectual pr
The metadata associated with an object is immutable. There is no operation to modify themetadata associated with an object after the object has been s
Query expressions can use much of the power of Structured Query Language (SQL). Each queryexpression combines SQL functions and operators, eld names
Note – The format of records as stored in the reliable and scalable object archive is not suitablefor fast query. To enable searching, the queryable
match the original object metadata. There are no transactional guarantees regarding orderingof queries and delete operations that are occurring at the
24
Sun StorageTek 5800 System Java Client APIThis chapter provides information on the 5800 system Java client API.The following topics are discussed: “Ov
The 5800 system Java client library provides a platform-independent mechanism to upload dataand metadata to a 5800 system, and to retrieve and query t
Updating Client View of the SchemaIn the Java client API, the schema is fetched when the NameValueObjectArchive class isinstantiated. If the schema ha
Basic ConceptsThe root of the 5800 system Java client API is the NameValueObjectArchive class, whichrepresents a connection to a single 5800 system se
“ObjectIdentifier” on page 29 “QueryResultSet” on page 30 “SystemRecord” on page 30 “NameValueRecord” on page 30For more information on using these c
ContentsPreface ...
later for retrieving objects. External storage can be accomplished using an identier's stringrepresentation by invoking the toString method. An
“query (with PreparedStatement)” on page 35 “query (with PreparedStatement and selectKeys)” on page 35 “PreparedStatement” on page 36 “QueryResultSet
Synopsispublic SystemRecord storeObject(java.nio.channels.ReadableByteChannel dataChannel)public SystemRecordstoreObject(ReadableByteChannel dataChann
checkIndexed returns an int value that indicates if the metadata for this object has beeninserted into the query engine. The value is -1 if the metada
Synopsispublic NameValueSchema getSchema()throws ArchiveException, java.io.IOExceptionDescriptionReturns the runtime conguration of the name-value ob
DescriptionTakes a where clause and a select clause and returns a QueryResultSet of NameValueRecordinstances containing the selected values.selectKeys
Synopsispublic QueryResultSetquery(PreparedStatement query,java.lang.String[] selectKeys,int resultsPerFetch)DescriptionTakes a where clause and a sel
stmt.bindParameter(date_value,1);QueryResultSet qrs = archive.query(stmt);QueryResultSetThe QueryResultSet class is used to page through OIDs and asso
getQueryIntegrityTimeReturns the most recent time at which all store index exceptions are known to have beenresolved.Synopsislong getQueryIntegrityTim
Sun StorageTek 5800 System C Client APIThis chapter provides detailed information on the 5800 system C client API.The following topics are discussed:
3 Sun StorageTek 5800 System C Client API ... 39Overview of the 58
ArchitectureThe 5800 system C API client supports two dierent access patterns: a synchronous “EZ” accessvery similar to the current Java implementati
Memory UsageThe 5800 system C client library generally follows the model of populating externally allocateddata structures such as handles, buers, an
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 the5
oid — The objectid for this object, equivalent to the system.object_id eld. digest_algo — Always set to "sha1" for this release. Equivalen
Synchronous C APIA multiplatform synchronous C API in which operations are accomplished in a few simplefunction calls is provided for the 5800 system.
– “hc_nvr_get_time” on page 82– “hc_nvr_get_timestamp” on page 83– “hc_pstmt_create” on page 100– “hc_pstmt_free” on page 101– “hc_pstmt_set_string” o
Synchronous C Data TypesThe following data types are dened for the C API: “hc_string_t” on page 46 “hc_long_t” on page 46 “hc_double_t” on page 46 “h
Synopsistypedef double hc_double_t;DescriptionType for holding oating-point values.hc_type_t5800 system name-value metadata type specier.Synopsistyp
hc_bytearray_t hcv_bytearray;struct tm hcv_tm;struct timespec hcv_timespec;} hcv;} hc_value_t;DescriptionThis tagged union type can be used to hold a
DescriptionAn opaque structure to represent the session from one thread to one 5800 system server. Itcontains the schema used to interpret metadata st
hc_session_get_platform_result ... 58hc_session_get_archive ...
DescriptionFunction pointers of read_from_data_source type are used to upload object data. The functionpointer and opaque cookie reference are supplie
DescriptionFunction pointers of write_to_data_destination type are used to download object data to anetwork or other destination from the 5800 system
HCERR_BAD_REQUEST,HCERR_NO_SUCH_OBJECT,HCERR_INTERNAL_SERVER_ERROR,HCERR_FAILED_GETTING_FDSET,HCERR_FAILED_CHECKING_FDSET,HCERR_MISSING_SELECT_CLAUSE,
DescriptionThis structure denes the 5800 system C client API error codes.Synchronous C API FunctionsThe 5800 system synchronous C API functions are d
DescriptionThis function initializes the 5800 system API and must be called before calling any of the otherfunctions in this API. It downloads a copy
hc_session_freeReleases the session object.Synopsishcerr_t hc_session_free (hc_session_t *session);DescriptionThis function releases the session objec
response_codepOUT: Updated to be the HTTP response code.errstrIN: Updated to be the error returned in the response body if the response code is not 20
Return CodesHCERR_OKHCERR_BAD_REQUESTHCERR_OOMHCERR_NULL_SESSIONHCERR_INVALID_SESSIONhc_session_get_hostReturns the host name and port number associat
hc_session_get_platform_resultReturns low-level error codes associated with the current session.Synopsishcerr_t hc_session_get_platform_result(hc_sess
hc_session_get_archiveReturns the current archive object associated with this session.Synopsishcerr_t hc_session_get_archive(hc_session_t *session,hc_
Storing Data and Metadata ... 87hc_store_both_ez
“hc_schema_get_type_at_index” on page 62hc_schema_get_typeLooks up type in schema.Synopsishcerr_t hc_schema_get_type(hc_schema_t *schema,char *name,
hc_schema_get_lengthLooks up length of char and string attribute elds.Synopsishcerr_t hc_schema_get_length(hc_schema_t *schema,char *name, int *lengt
DescriptionThis function returns the number of name-value pairs in the metadata schema.ParametershspIN: The schema to interrogate.countpOUT: Updated w
IN: Should range from 0 up to the count-1 returned in “hc_schema_get_count” on page 61.namepOUT: Updated to point to a string that is an attribute nam
▼To Use the API for Storing Name-Value RecordsCall hc_init once per process.Call“hc_session_create_ez”on page 53 to initialize the session and downloa
Creating and Freeing Name-Value RecordsThe following functions are dened to create and free name-value records: “hc_nvr_create” on page 65 “hc_nvr_fr
See Also“hc_nvr_free” on page 66hc_nvr_freeFrees a name-value record.Synopsishcerr_t hc_nvr_free(hc_nvr_t *nvr);DescriptionThis function frees a name-
“hc_nvr_add_timestamp” on page 74 “hc_nvr_add_from_string” on page 75hc_nvr_add_valueAdds a new metadata value.Synopsishcerr_t hc_nvr_add_value(hc_nv
hc_nvr_add_longAdds a new metadata value of type hc_long_t.Synopsishcerr_t hc_nvr_add_long(hc_nvr_t *nvr,char *name, hc_long_t value)DescriptionThis f
hc_nvr_add_doubleAdds a new metadata value of type hc_double_t.Synopsishcerr_t hc_nvr_add_double(hc_nvr_t *nvr,char *name,hc_double_t value);Descripti
Supported Data Types ... 116Querie
hc_nvr_add_stringAdds a new metadata value of type Unicode UTF-8 string.Synopsishcerr_t hc_nvr_add_string(hc_nvr_t *nvr,char *name,hc_string_t value);
hc_nvr_add_binaryAdds new metadata value of type binary.Synopsishcerr_t hc_nvr_add_binary(hc_nvr_t *nvr,hc_string_t name,int size,unsigned char *bytes
hc_nvr_add_dateAdds 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 *v
hc_nvr_add_timeAdds 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 *valu
hc_nvr_add_timestampAdds new metadata value of type timestamp.Synopsis#include <time.h>hcerr_t hc_nvr_add_timestamp(hc_nvr_t *nvr,hc_string_t na
hc_nvr_add_from_stringAdds a new metadata value where the value always starts out as a string.Synopsishcerr_t hc_nvr_add_from_string(hc_nvr_t *nvr,cha
Retrieving Name-Value RecordsThe following functions are dened to retrieve name-value records: “hc_nvr_get_count” on page 76 “hc_nvr_get_value_at_ind
hc_nvr_get_value_at_indexIterates through the names and values in a name-value record.Synopsishc_nvr_get_value_at_index(hc_nvr_t *nvr,hc_long_t index,
hc_nvr_get_longRetrieves a value of type hc_long_t.Synopsishcerr_t hc_nvr_get_long(hc_nvr_t *nvr,char *name,hc_long_t *retlong);DescriptionThis functi
hc_nvr_get_doubleRetrieves a value of type hc_double_t.Synopsishcerr_t hc_nvr_get_double(hc_nvr_t *nvr,char *name,hc_double_t *retdouble);DescriptionT
hc_nvr_get_stringRetrieves a value of a Unicode UTF-8 string.Synopsishcerr_t hc_nvr_get_string(hc_nvr_t *nvr,char *name,hc_string_t *retstring);Descri
hc_nvr_get_binaryRetrieves a metadata value of type binary.Synopsishcerr_t hc_nvr_get_binary(hc_nvr_t *nvr,hc_string_t name,int *size,unsigned char **
hc_nvr_get_dateRetrieves 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 *
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
This function retrieves the value of type struct timespec associated with an indicatedattribute name in a name-value record.ParametersnvrPoints to a n
char **names,char **values,hc_long_t nitems);DescriptionThis function creates a name-value-record from parallel tables of string names and stringvalue
hc_nvr_convert_to_string_arraysConverts name-value-record to string names and string values.Synopsishcerr_t hc_nvr_convert_to_string_arrays(hc_nvr_t *
HCERR_OOMHCERR_INVALID_NVRHCERR_ILLEGAL_ARGUMENTStoring Data and MetadataThe following functions are dened to store data and metadata and to enforce
ParameterssessionIN: The session for the host and port to talk to.data_source_readerIN: The source of data to be stored. See“read_from_data_source” on
DescriptionThis function adds a metadata record for the specied OID and returns a system_recorddescriptor.ParameterssessionIN: The session for the ho
TablesTABLE 4–1 Canonical String Representation of Data Types ...1199
DescriptioncheckIndexed is intended as way to resolve a store index exception under program control (see“The 5800 System Query Integrity Model” on pag
Retrieving Data and MetadataThe following functions are dened to retrieve data and metadata: “hc_retrieve_ez” on page 91 “hc_retrieve_metadata_ez” on
HCERR_OOMHCERR_NULL_SESSIONHCERR_INVALID_SESSIONHCERR_INVALID_OIDhc_retrieve_metadata_ezRetrieves a metadata record for the specied OID.Synopsishcerr
hc_range_retrieve_ezRetrieves a specied range of data for a specied OID.Synopsishc_range_retrieve_ez(hc_session_t *session,write_to_data_destination
HCERR_NULL_SESSIONHCERR_INVALID_SESSIONHCERR_INVALID_OIDHCERR_ILLEGAL_ARGUMENTQuerying MetadataThe following functions are dened for simple queries:
int results_per_fetch,hc_query_result_set_t **rsetp);DescriptionThis function retrieves OIDs and optionally name-value records matching a query. If th
Return CodesHCERR_OKHCERR_OOMHCERR_BAD_REQUESTHCERR_NULL_SESSIONHCERR_INVALID_SESSIONHCERR_ILLEGAL_ARGUMENTSee Also“hc_qrs_free” on page 99hc_qrs_next
finishedpOUT: Points to an int that is updated to 0 if query data has been returned and to 1 if the resultset is empty.Return CodesHCERR_OKHCERR_OOMHC
Return CodesHCERR_OKHCERR_BAD_REQUESTHCERR_OOMHCERR_INVALID_RESULT_SEThc_qrs_get_query_integrity_timeReturns a time that helps get more detail on whic
HCERR_OOMHCERR_INVALID_RESULT_SEThc_qrs_freeReleases the resources associated with this QueryResultSet.Synopsishcerr_t hc_qrs_free (**rsetp);Descripti
Komentáře k této Příručce