Sun-microsystems Sun StorageTek 5800 Uživatelský manuál

Procházejte online nebo si stáhněte Uživatelský manuál pro Hardware Sun-microsystems Sun StorageTek 5800. Sun Microsystems Sun StorageTek 5800 User Manual Uživatelská příručka

  • Stažení
  • Přidat do mých příruček
  • Tisk
  • Strana
    / 136
  • Tabulka s obsahem
  • KNIHY
  • Hodnocené. / 5. Na základě hodnocení zákazníků
Zobrazit stránku 0
Sun StorageTek 5800 System
Client API Reference Manual
Sun Microsystems, Inc.
4150 Network Circle
Santa Clara, CA 95054
U.S.A.
Part No: 820–4796
June 2008
Zobrazit stránku 0
1 2 3 4 5 6 ... 135 136

Shrnutí obsahu

Strany 1 - Client API Reference Manual

Sun StorageTek 5800 SystemClient API Reference ManualSun Microsystems, Inc.4150 Network CircleSanta Clara, CA 95054U.S.A.Part No: 820–4796June 2008

Strany 3 - Contents

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_

Strany 4

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

Strany 5

ParameterspstmtPrepared statement to add the binding to.whichIN: Variable (”?’) in the prepared statement, numbered from 1.valueIN: String to bind.Ret

Strany 6

IN: Variable (”?’) in the prepared statement, numbered from 1.valueIN: char * string to bind.Return CodesHCERR_OKHCERR_OOMSee Also“hc_pstmt_create” on

Strany 7

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.

Strany 8

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

Strany 9

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

Strany 10

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 *

Strany 11 - Related Books

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

Strany 12 - Typographic Conventions

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

Strany 13 - Sun WelcomesYour Comments

PrefaceThe Sun StorageTek 5800 System Client API Reference Manual is written for programmers andapplication developers who develop custom applications

Strany 14

Return CodesHCERR_OKHCERR_OOMHCERR_BAD_REQUESTHCERR_NULL_SESSIONHCERR_INVALID_SESSIONHCERR_ILLEGAL_ARGUMENTSee Also“hc_pstmt_create” on page 100Queryi

Strany 15 - Changes in Version 1.1

// 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

Strany 16 - 5800 System Overview

ParameterssessionIN: Pointer to the session.oidIN: The specied OID.Return CodesHCERR_OKHCERR_BAD_REQUESTHCERR_OOMHCERR_NULL_SESSIONHCERR_INVALID_SESS

Strany 17 - The 5800 System Data Model

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.

Strany 19

Sun StorageTek 5800 System Query LanguageThis chapter provides information on the 5800 system query language.Note – For details of the metadata system

Strany 20

OperationThe query format is similar to the where clause of an SQL query. The two main dierences arethat 5800 system queries do not contain embedded

Strany 21

QueriesA query in the 5800 system query language is translated into an equivalent query for theunderlying database that implements the query engine. T

Strany 22

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

Strany 23

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 {

Strany 24

Related Third-Party Web Site ReferencesThird-party URLs are referenced in this document and provide additional, related information.Note – Sun is not

Strany 25 - Client Library

When converting a typed value to a string as the result of the getAsString operation on aNameValueRecord or a QueryResultSet operation When parsing a

Strany 26 - Performance and Scalability

The following JDBC function escapes supported:TIMESTAMPDIFF, TIMESTAMPADD, CURRENT_TIMESTAMP, CURRENT_TIME, CURRENT_DATE,HOUR, MINUTE, SECOND.Reserve

Strany 27 - Java API

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

Strany 28 - Key Classes

Examples of Supported Query Expressions {fn LCASE(mp3.artist)} LIKE ’%floyd%’ AND system.object_size > 2000000 (object_size < 200) OR "Coll

Strany 29 - NameValueSchema

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

Strany 30 - NameValueRecord

DEALLOCATE, DECLARE, DEFAULT, DEFERRABLE, DEFERRED, DELETE, DESC, DESCRIBE,DESCRIPTOR, DETERMINISTIC, DIAGNOSTICS, DIRECTORY, DISCONNECT, DISTINCT, DO

Strany 32

Programming Considerations and BestPrac ticesThis chapter provides considerations and practices that can help you create ecient 5800system applicatio

Strany 33

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

Strany 34

IndexNumbers and Symbols5800 systemHoneycomb project, 17summary, 16-17Bbest practicesmax results per fetch, 128retries and timeouts, 127schema query s

Strany 35

TABLE P–1 Typographic Conventions (Continued)Typeface Meaning ExampleAaBbCc123 Book titles, new terms, and terms to beemphasizedRead Chapter 6 in the

Strany 36 - PreparedStatement

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

Strany 37

metadata (Continued)retrieving, 91storing, 87hc_store_both_ez, 87-88metadata model, overview, 19-20modelsdata, 17-19deleting objects, 22-23metadata, 1

Strany 38 - QueryIntegrityTime

OID (Continued)retrieve metadata forhc_retrieve_metadata_ez,92retrieve range of data forhc_range_retrieve_ez, 93-94operationsretrying, 26, 40overview,

Strany 39 - CHAPTER 3

Rretries, 127retrieveMetadata method, 33retrieveObject method, 33retrying operations, 26, 40Sschemamanaging, 59-60hc_schema_get_count, 61-62hc_schema_

Strany 40 - Multithreaded Access

synchronous C API (Continued)error codestranslating into a string, 112fetch next OIDhc_qrs_next_ez, 96-97free prepared statementhc_pstmt_free, 101func

Strany 41 - Session Management

Ttimeouts, 127Index135

Strany 44 - Synchronous C API

Sun StorageTek 5800 System Client APIThe SunTMStorageTekTM5800 system client API provides programmatic access to a 5800 systemserver to store, retriev

Strany 45 - Limitations

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

Strany 46 - Synchronous C Data Types

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

Strany 47

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

Strany 48

The 5800 System Metadata ModelMetadata means “data about the data”; it describes the data and helps to determine how the datashould be interpreted. In

Strany 49

Copyright 2008 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. All rights reserved.Sun Microsystems, Inc. has intellectual pr

Strany 50

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

Strany 51

Query expressions can use much of the power of Structured Query Language (SQL). Each queryexpression combines SQL functions and operators, eld names

Strany 52

Note – The format of records as stored in the reliable and scalable object archive is not suitablefor fast query. To enable searching, the queryable 

Strany 53

match the original object metadata. There are no transactional guarantees regarding orderingof queries and delete operations that are occurring at the

Strany 55

Sun StorageTek 5800 System Java Client APIThis chapter provides information on the 5800 system Java client API.The following topics are discussed: “Ov

Strany 56

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

Strany 57

Updating Client View of the SchemaIn the Java client API, the schema is fetched when the NameValueObjectArchive class isinstantiated. If the schema ha

Strany 58

Basic ConceptsThe root of the 5800 system Java client API is the NameValueObjectArchive class, whichrepresents a connection to a single 5800 system se

Strany 59 - Managing a Schema

“ObjectIdentifier” on page 29 “QueryResultSet” on page 30 “SystemRecord” on page 30 “NameValueRecord” on page 30For more information on using these c

Strany 60

ContentsPreface ...

Strany 61

later for retrieving objects. External storage can be accomplished using an identier's stringrepresentation by invoking the toString method. An

Strany 62

“query (with PreparedStatement)” on page 35 “query (with PreparedStatement and selectKeys)” on page 35 “PreparedStatement” on page 36 “QueryResultSet

Strany 63

Synopsispublic SystemRecord storeObject(java.nio.channels.ReadableByteChannel dataChannel)public SystemRecordstoreObject(ReadableByteChannel dataChann

Strany 64

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

Strany 65

Synopsispublic NameValueSchema getSchema()throws ArchiveException, java.io.IOExceptionDescriptionReturns the runtime conguration of the name-value ob

Strany 66 - Building Name-Value Records

DescriptionTakes a where clause and a select clause and returns a QueryResultSet of NameValueRecordinstances containing the selected values.selectKeys

Strany 67

Synopsispublic QueryResultSetquery(PreparedStatement query,java.lang.String[] selectKeys,int resultsPerFetch)DescriptionTakes a where clause and a sel

Strany 68

stmt.bindParameter(date_value,1);QueryResultSet qrs = archive.query(stmt);QueryResultSetThe QueryResultSet class is used to page through OIDs and asso

Strany 69

getQueryIntegrityTimeReturns the most recent time at which all store index exceptions are known to have beenresolved.Synopsislong getQueryIntegrityTim

Strany 70

Sun StorageTek 5800 System C Client APIThis chapter provides detailed information on the 5800 system C client API.The following topics are discussed:

Strany 71

3 Sun StorageTek 5800 System C Client API ... 39Overview of the 58

Strany 72

ArchitectureThe 5800 system C API client supports two dierent access patterns: a synchronous “EZ” accessvery similar to the current Java implementati

Strany 73

Memory UsageThe 5800 system C client library generally follows the model of populating externally allocateddata structures such as handles, buers, an

Strany 74

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

Strany 75

oid — The objectid for this object, equivalent to the system.object_id eld. digest_algo — Always set to "sha1" for this release. Equivalen

Strany 76 - Retrieving Name-Value Records

Synchronous C APIA multiplatform synchronous C API in which operations are accomplished in a few simplefunction calls is provided for the 5800 system.

Strany 77

– “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

Strany 78

Synchronous C Data TypesThe following data types are dened for the C API: “hc_string_t” on page 46 “hc_long_t” on page 46 “hc_double_t” on page 46 “h

Strany 79

Synopsistypedef double hc_double_t;DescriptionType for holding oating-point values.hc_type_t5800 system name-value metadata type specier.Synopsistyp

Strany 80

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

Strany 81

DescriptionAn opaque structure to represent the session from one thread to one 5800 system server. Itcontains the schema used to interpret metadata st

Strany 82

hc_session_get_platform_result ... 58hc_session_get_archive ...

Strany 83

DescriptionFunction pointers of read_from_data_source type are used to upload object data. The functionpointer and opaque cookie reference are supplie

Strany 84

DescriptionFunction pointers of write_to_data_destination type are used to download object data to anetwork or other destination from the 5800 system

Strany 85

HCERR_BAD_REQUEST,HCERR_NO_SUCH_OBJECT,HCERR_INTERNAL_SERVER_ERROR,HCERR_FAILED_GETTING_FDSET,HCERR_FAILED_CHECKING_FDSET,HCERR_MISSING_SELECT_CLAUSE,

Strany 86

DescriptionThis structure denes the 5800 system C client API error codes.Synchronous C API FunctionsThe 5800 system synchronous C API functions are d

Strany 87 - Storing Data and Metadata

DescriptionThis function initializes the 5800 system API and must be called before calling any of the otherfunctions in this API. It downloads a copy

Strany 88

hc_session_freeReleases the session object.Synopsishcerr_t hc_session_free (hc_session_t *session);DescriptionThis function releases the session objec

Strany 89

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

Strany 90

Return CodesHCERR_OKHCERR_BAD_REQUESTHCERR_OOMHCERR_NULL_SESSIONHCERR_INVALID_SESSIONhc_session_get_hostReturns the host name and port number associat

Strany 91 - Retrieving Data and Metadata

hc_session_get_platform_resultReturns low-level error codes associated with the current session.Synopsishcerr_t hc_session_get_platform_result(hc_sess

Strany 92

hc_session_get_archiveReturns the current archive object associated with this session.Synopsishcerr_t hc_session_get_archive(hc_session_t *session,hc_

Strany 93

Storing Data and Metadata ... 87hc_store_both_ez

Strany 94 - Querying Metadata

“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,

Strany 95

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

Strany 96

DescriptionThis function returns the number of name-value pairs in the metadata schema.ParametershspIN: The schema to interrogate.countpOUT: Updated w

Strany 97

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

Strany 98

▼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

Strany 99

Creating and Freeing Name-Value RecordsThe following functions are dened to create and free name-value records: “hc_nvr_create” on page 65 “hc_nvr_fr

Strany 100 - See Also

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-

Strany 101 - HCERR_OK

“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

Strany 102 - HCERR_OOM

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

Strany 103

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

Strany 104 - Synchronous C API Functions

Supported Data Types ... 116Querie

Strany 105

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);

Strany 106

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

Strany 107

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

Strany 108

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

Strany 109

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

Strany 110

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

Strany 111 - Deleting Records

Retrieving Name-Value RecordsThe following functions are dened to retrieve name-value records: “hc_nvr_get_count” on page 76 “hc_nvr_get_value_at_ind

Strany 112 - Parameter

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,

Strany 113

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

Strany 114

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

Strany 116 - Supported Data Types

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

Strany 117 - Attribute Format in Queries

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 **

Strany 118 - Literals In Queries

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 *

Strany 119 - Canonical String Format

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

Strany 120 - Virtual View Lookup Operation

This function retrieves the value of type struct timespec associated with an indicatedattribute name in a name-value record.ParametersnvrPoints to a n

Strany 121 - Supported Expression Types

char **names,char **values,hc_long_t nitems);DescriptionThis function creates a name-value-record from parallel tables of string names and stringvalue

Strany 122 - Supported ExpressionTypes

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 *

Strany 123

HCERR_OOMHCERR_INVALID_NVRHCERR_ILLEGAL_ARGUMENTStoring Data and MetadataThe following functions are dened to store data and metadata and to enforce

Strany 124

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

Strany 125

DescriptionThis function adds a metadata record for the specied OID and returns a system_recorddescriptor.ParameterssessionIN: The session for the ho

Strany 126

TablesTABLE 4–1 Canonical String Representation of Data Types ...1199

Strany 127 - Prac tices

DescriptioncheckIndexed is intended as way to resolve a store index exception under program control (see“The 5800 System Query Integrity Model” on pag

Strany 128 - Limit Results Per Fetch

Retrieving Data and MetadataThe following functions are dened to retrieve data and metadata: “hc_retrieve_ez” on page 91 “hc_retrieve_metadata_ez” on

Strany 129 - Numbers and Symbols

HCERR_OOMHCERR_NULL_SESSIONHCERR_INVALID_SESSIONHCERR_INVALID_OIDhc_retrieve_metadata_ezRetrieves a metadata record for the specied OID.Synopsishcerr

Strany 130

hc_range_retrieve_ezRetrieves a specied range of data for a specied OID.Synopsishc_range_retrieve_ez(hc_session_t *session,write_to_data_destination

Strany 131

HCERR_NULL_SESSIONHCERR_INVALID_SESSIONHCERR_INVALID_OIDHCERR_ILLEGAL_ARGUMENTQuerying MetadataThe following functions are dened for simple queries:

Strany 132

int results_per_fetch,hc_query_result_set_t **rsetp);DescriptionThis function retrieves OIDs and optionally name-value records matching a query. If th

Strany 133

Return CodesHCERR_OKHCERR_OOMHCERR_BAD_REQUESTHCERR_NULL_SESSIONHCERR_INVALID_SESSIONHCERR_ILLEGAL_ARGUMENTSee Also“hc_qrs_free” on page 99hc_qrs_next

Strany 134

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

Strany 135

Return CodesHCERR_OKHCERR_BAD_REQUESTHCERR_OOMHCERR_INVALID_RESULT_SEThc_qrs_get_query_integrity_timeReturns a time that helps get more detail on whic

Strany 136

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

Žádné komentáře