Related Manuals for Sun Microsystems Sun StorageTek 5800
Summary of Contents for Sun Microsystems Sun StorageTek 5800
- Page 1 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...
- Page 2 Etats-Unis et dans d'autres pays; elle est licenciée exclusivement par X/Open Company, Ltd. Sun, Sun Microsystems, le logo Sun, le logo Solaris, le logo Java Coffee Cup, docs.sun.com, Java et Solaris sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc.
-
Page 3: Table Of Contents
The 5800 System Query Model ... 20 The 5800 System Query Integrity Model ... 21 Deleting Objects from the 5800 System ... 22 Sun StorageTek 5800 System Java Client API ... 25 Overview of the 5800 System Java Client API ... 25 Client Library ... 25 Interfaces ... - Page 4 ... 51 Synchronous C API Functions ... 53 Managing 5800 System Sessions ... 53 hc_session_create_ez ... 53 hc_session_free ... 55 hc_session_get_status ... 55 hc_session_get_schema ... 56 hc_session_get_host ... 57 Sun StorageTek 5800 System Client API Reference Manual • June 2008...
- Page 5 Contents hc_session_get_platform_result ... 58 hc_session_get_archive ... 59 Managing a Schema ... 59 hc_schema_get_type ... 60 hc_schema_get_length ... 61 hc_schema_get_count ... 61 hc_schema_get_type_at_index ... 62 Manipulating Name-Value Records ... 63 Using the API for Storing Name-Value Records ... 63 Using Returned Name-Value Records ... 64 Creating and Freeing Name-Value Records ...
- Page 6 ... 111 Translating Error and Type Codes ... 112 hc_decode_hcerr ... 112 hc_decode_hc_type ... 113 Sun StorageTek 5800 System Query Language ... 115 Interfaces ... 115 Operation ... 116 Sun StorageTek 5800 System Client API Reference Manual • June 2008...
- Page 7 Supported Data Types ... 116 Queries ... 117 Translating a Query to the Underlying Database ... 117 Attribute Format in Queries ... 117 SQL Syntax in 5800 System Queries ... 118 Literals In Queries ... 118 Dynamic Parameters ... 118 String Literals ...
- Page 9 Tables Canonical String Representation of Data Types ... 119 TABLE 4–1...
-
Page 11: Preface
How This Book Is Organized Chapter 1, “Sun StorageTek 5800 System Client API, ” ■ for the Sun StorageTek 5800 System 1.1 release, and overviews of the client APIs and query language. Chapter 2, “Sun StorageTek 5800 System Java Client API, ”... -
Page 12: Typographic Conventions
Typographic Conventions TABLE P–1 Typeface AaBbCc123 AaBbCc123 aabbcc123 Sun StorageTek 5800 System Client API Reference Manual • June 2008 Meaning The names of commands, files, and directories, and onscreen computer output What you type, contrasted with onscreen computer output Placeholder: replace with a real name or value Example Edit your .login file. -
Page 13: Shell Prompts In Command Examples
You can submit your comments by clicking the Feedback link on the http://docs.sun.com web site. Please include the title and part number of your document with your feedback: Sun StorageTek 5800 System Client API Reference Manual, part number 820-4796 (Continued) Meaning... -
Page 15: Sun Storagetek 5800 System Client Api
Synchronous versions are provided in C and Java use with POSIX operations. This chapter provides a summary of the changes for the Sun StorageTek 5800 System 1.1 release, and overviews of the client APIs and query language. The following topics are discussed: “Changes in Version 1.1”... -
Page 16: 5800 System Overview
The Java API is described in ■ The C API is described in ■ Sun StorageTek 5800 System Client API Reference Manual • June 2008 Chapter 2, “Sun StorageTek 5800 System Java Client API” Chapter 3, “Sun StorageTek 5800 System C Client API”... -
Page 17: The 5800 System And Honeycomb
In the following sections, the terms from the Java API are used as an aid to exposition. In all cases, a simple equivalent using the C API is available. Chapter 4, “Sun StorageTek 5800 System Query Language, ” ■ of query capabilties and query syntax. - Page 18 There is no way to tie together two different store operations so that both either succeed together or fail together. A stored object may or may not immediately be queryable. For more information, see Note – “The 5800 System Query Integrity Model” on page Sun StorageTek 5800 System Client API Reference Manual • June 2008...
-
Page 19: The 5800 System Metadata Model
If the names or values supplied for the user metadata do not match the active schema, then an exception is generated and the object is not stored. Chapter 1 • Sun StorageTek 5800 System Client API... -
Page 20: The 5800 System Query Model
Each object is considered individually without reference to any other objects. There are no queries that compare fields in one object with fields in a different object. Sun StorageTek 5800 System Client API Reference Manual • June 2008... -
Page 21: The 5800 System Query Integrity Model
In other words, there is an implicit INNER JOIN between all the fields in the query and in the select list. There are significant limitations on which queries may be executed efficiently, or at all. See Chapter 4, “Sun StorageTek 5800 System Query Language, ” Chapter 5, “Programming Considerations and Best Practices”s for details of these limitations. -
Page 22: Deleting Objects From The 5800 System
OID. Once a delete operation completes normally, subsequent attempts to retrieve that object will fail with an exception. In addition, the object will stop showing up in query result sets that Sun StorageTek 5800 System Client API Reference Manual • June 2008... - Page 23 Alternatively, the customer application may choose to re-execute the delete operation until it succeeds, or until it fails with an error that indicates the object is already deleted. Chapter 1 • Sun StorageTek 5800 System Client API...
-
Page 25: Sun Storagetek 5800 System Java Client Api
C H A P T E R Sun StorageTek 5800 System Java Client API This chapter provides information on the 5800 system Java client API. The following topics are discussed: “Overview of the 5800 System Java Client API” on page 25 ■... -
Page 26: Interfaces
(blocking). HTTP connections are pooled for performance. You should instantiate one instance of the NameValueObjectArchive per 5800 system server and use it for all access to that server until exit. Sun StorageTek 5800 System Client API Reference Manual • June 2008 platform 4.0 or later with HTTP connectivity... -
Page 27: Updating Client View Of The Schema
Contains classes for server-side exceptions. Java API Documentation The Java API documentation (Javadoc) is located in the SDK java/doc/htdocs directory, and can be accessed using a browser. Chapter 2 • Sun StorageTek 5800 System Java Client API Java API... -
Page 28: Basic Concepts
API. For more information on using the following classes, see Also see the Javadoc provided with the 5800 system SDK. “NameValueObjectArchive” on page 29 ■ “NameValueSchema” on page 29 ■ Sun StorageTek 5800 System Client API Reference Manual • June 2008 “Basic Concepts” on page... - Page 29 5800 system system uses to index data. This instance can be used to enumerate the fields available in the schema as attributes. Each attribute has a name and a type. See the Sun StorageTek 5800 System Administrator’s Guide for information on how to define attributes.
-
Page 30: Namevalueobjectarchive Application Access
“checkIndexed” on page 32 ■ “retrieveObject” on page 33 ■ “retrieveMetadata” on page 33 ■ “getSchema” on page 33 ■ “query” on page 34 ■ “query (with selectKeys)” on page 34 ■ Sun StorageTek 5800 System Client API Reference Manual • June 2008... - Page 31 Deletes the metadata record. If it is the last metadata record referencing the underlying object data, the underlying object data will also be deleted. storeObject Uploads a new data object with an associated name-value metadata record. Chapter 2 • Sun StorageTek 5800 System Java Client API Java API...
- Page 32 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. Sun StorageTek 5800 System Client API Reference Manual • June 2008 throws ArchiveException, IOException...
- Page 33 Returns a NameValueRecord instance containing the system and name-value metadata for the metadata record identified by the OID. getSchema Returns the runtime configuration of the name-value object archive as a NameValueSchema instance. Chapter 2 • Sun StorageTek 5800 System Java Client API Java API...
- Page 34 StorageTek 5800 System Query Language. ” query (with selectKeys) Returns a ResultSet of NameValueRecord instances containing the selected values. Synopsis public QueryResultSet query(java.lang.String query, java.lang.String[] selectKeys,int maxResults) throws ArchiveException, java.io.IOException Sun StorageTek 5800 System Client API Reference Manual • June 2008 Chapter 4, “Sun...
- Page 35 StorageTek 5800 System Query Language. ” query (with PreparedStatement and selectKeys) Returns specified fields from metadata records matching the query as a QueryResultSet instance. Chapter 2 • Sun StorageTek 5800 System Java Client API Java API Chapter 4, “Sun Chapter 4, “Sun...
- Page 36 PreparedStatement may be passed to the NameValueObjectArchive.query method to be executed, for example: NameValueObjectArchive archive = new NameValueObjectArchive(hostname); Date date_value= new java.sql.Date(); PreparedStatement stmt = new PreparedStatement("date_field<?”); Sun StorageTek 5800 System Client API Reference Manual • June 2008 Chapter 4, “Sun...
- Page 37 Returns whether the set of results constitutes a complete set Synopsis boolean isQueryComplete() Description Returns whether the set of results constitutes a complete set. See Integrity Model” on page Chapter 2 • Sun StorageTek 5800 System Java Client API Java API “The 5800 System Query...
- Page 38 QueryIntegrityTime Get detailed status on which store index exceptions might still be unresolved Synopsis QueryResultSet.isQueryComplete(), QueryResultSet.getQueryIntegrityTime(); Sun StorageTek 5800 System Client API Reference Manual • June 2008...
-
Page 39: Sun Storagetek 5800 System C Client Api
C H A P T E R 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” on page 39 ■... -
Page 40: Architecture
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. Sun StorageTek 5800 System Client API Reference Manual • June 2008 to create its own session. Sessions must not be shared... -
Page 41: Memory Usage
(*reallocator_t) (void *p,size_t size); Initializing a Global Session The following function initializes a global session: Chapter 3 • Sun StorageTek 5800 System C Client API Overview of the 5800 System C Client API 41). to access the schema changes. -
Page 42: System Record
} hc_system_record_t; About the fields: Sun StorageTek 5800 System Client API Reference Manual • June 2008 53. If “hc_session_create_ez” on page 53 “hc_session_create_ez” on page 53 is called before , see... -
Page 43: Failure And Recovery
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. Chapter 3 • Sun StorageTek 5800 System C Client API Nonblocking C API... -
Page 44: Synchronous C Api
“hc_nvr_add_date” on page 72 – “hc_nvr_add_time” on page 73 – “hc_nvr_add_timestamp” on page 74 – “hc_nvr_get_binary” on page 81 – “hc_nvr_get_date” on page 82 Sun StorageTek 5800 System Client API Reference Manual • June 2008 “hc_session_create_ez” on page 53 (once per... -
Page 45: Limitations
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. Chapter 3 • Sun StorageTek 5800 System C Client API “hc_retrieve_ez” on page 91 “hc_store_metadata_ez” on page 88... -
Page 46: Synchronous C Data Types
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. Sun StorageTek 5800 System Client API Reference Manual • June 2008... -
Page 47: Hc_Type_T
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; Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C Data Types... -
Page 48: Hc_Schema_T
Structure describing the connection from one thread to one 5800 system server. Synopsis typedef void hc_session_t; Sun StorageTek 5800 System Client API Reference Manual • June 2008 hc_bytearray_t hcv_bytearray; struct tm hcv_tm; struct timespec hcv_timespec;... -
Page 49: Hc_Pstmt_T
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); Chapter 3 • Sun StorageTek 5800 System C Client API “Querying Metadata” on page Synchronous C Data Types... -
Page 50: Write_To_Data_Destination
See Also “hc_store_both_ez” on page 87 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); Sun StorageTek 5800 System Client API Reference Manual • June 2008 “hc_store_both_ez” on... -
Page 51: Hcerr_T
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, Chapter 3 • Sun StorageTek 5800 System C Client API “hc_retrieve_ez” on page “hc_decode_hcerr” on page 112 Synchronous C Data Types... - Page 52 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; Sun StorageTek 5800 System Client API Reference Manual • June 2008...
-
Page 53: Synchronous C Api Functions
“hc_session_get_host” on page 57 ■ “hc_session_get_platform_result” on page 58 ■ “hc_session_get_archive” on page 59 ■ hc_session_create_ez Creates a session. Synopsis hcerr_t hc_session_create_ez(char *host, int port, hc_session_t **sessionp); Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions... -
Page 54: Return Codes
OUT: Updated to point to a session object. Return Codes HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_ILLEGAL_ARGUMENT Sun StorageTek 5800 System Client API Reference Manual • June 2008 to create its own session. Sessions must not be shared “Initializing a Global Session” on page 41... -
Page 55: Hc_Session_Free
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. Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions... -
Page 56: Hc_Session_Get_Schema
55, at which time it will be implicitly released. Sun StorageTek 5800 System Client API Reference Manual • June 2008 “hc_session_free” on page 55 is called, “hc_session_free” on... -
Page 57: Hc_Session_Get_Host
OUT: Updated to be the port number. Return Codes HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions “hc_session_free” on page... -
Page 58: Hc_Session_Get_Platform_Result
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 Sun StorageTek 5800 System Client API Reference Manual • June 2008... -
Page 59: Hc_Session_Get_Archive
5800 system server. The following functions are used to manage a schema: “hc_schema_get_type” on page 60 ■ “hc_schema_get_length” on page 61 ■ “hc_schema_get_count” on page 61 ■ Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions... -
Page 60: Hc_Schema_Get_Type
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 Sun StorageTek 5800 System Client API Reference Manual • June 2008... -
Page 61: Hc_Schema_Get_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); Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions... -
Page 62: 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 IN: The schema to query. index Sun StorageTek 5800 System Client API Reference Manual • June 2008... -
Page 63: Manipulating Name-Value Records
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. Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions “hc_schema_get_count” on page... -
Page 64: Using Returned Name-Value Records
“hc_nvr_t”on page 48 Structures created by hc_nvr_create can also be freed by calling hc_nvr_free. Note – Sun StorageTek 5800 System Client API Reference Manual • June 2008 to initialize the session and download the schema. “hc_nvr_create”on page 66) for each 5800 system type. -
Page 65: Creating And Freeing Name-Value Records
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 Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions... -
Page 66: Hc_Nvr_Free
■ “hc_nvr_add_double” on page 69 ■ “hc_nvr_add_string” on page 70 ■ “hc_nvr_add_binary” on page 71 ■ “hc_nvr_add_date” on page 72 ■ “hc_nvr_add_time” on page 73 ■ Sun StorageTek 5800 System Client API Reference Manual • June 2008 “hc_nvr_create” on page... -
Page 67: Hc_Nvr_Add_Value
IN: Name for the tuple. value IN: Value for the tuple, in the type-tagged Return Codes HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_ILLEGAL_VALUE_FOR_METADATA HCERR_NO_SUCH_ATTRIBUTE Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions “hc_value_t” on page 47 format. -
Page 68: Hc_Nvr_Add_Long
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 Sun StorageTek 5800 System Client API Reference Manual • June 2008 “hc_type_t” on page 47). The name-value record... -
Page 69: Hc_Nvr_Add_Double
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 Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions “hc_type_t” on page 47). The name-value record... -
Page 70: Hc_Nvr_Add_String
The string is copied into the structure. Parameters 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 Sun StorageTek 5800 System Client API Reference Manual • June 2008... -
Page 71: Hc_Nvr_Add_Binary
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 Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions... -
Page 72: Hc_Nvr_Add_Date
Parameters 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 Sun StorageTek 5800 System Client API Reference Manual • June 2008... -
Page 73: Hc_Nvr_Add_Time
Parameters 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 Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions... -
Page 74: Hc_Nvr_Add_Timestamp
The name and value are copied into the structure. Parameters 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 Sun StorageTek 5800 System Client API Reference Manual • June 2008... -
Page 75: Hc_Nvr_Add_From_String
Parameters 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 Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions... -
Page 76: Retrieving Name-Value Records
This function retrieves the number of metadata name and value tuples in the specified name-value record. Parameters 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 Sun StorageTek 5800 System Client API Reference Manual • June 2008... -
Page 77: Hc_Nvr_Get_Value_At_Index
OUT: Updated to point to the attribute name at the specified index. valuep OUT: Updated with the “hc_value_t” on page 47 Return Codes HCERR_OK HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT HCERR_NO_MORE_ARGUMENTS HCERR_OOM Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions “hc_nvr_create_from_string_arrays” type-tagged value at the specified index. -
Page 78: Hc_Nvr_Get_Long
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 Sun StorageTek 5800 System Client API Reference Manual • June 2008 “hc_type_t” on page 47) associated... -
Page 79: Hc_Nvr_Get_Double
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 Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions “hc_type_t” on page 47) associated... -
Page 80: Hc_Nvr_Get_String
Parameters 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 Sun StorageTek 5800 System Client API Reference Manual • June 2008... -
Page 81: Hc_Nvr_Get_Binary
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 Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions... -
Page 82: Hc_Nvr_Get_Date
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. Sun StorageTek 5800 System Client API Reference Manual • June 2008... -
Page 83: Hc_Nvr_Get_Timestamp
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); Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions... -
Page 84: Creating And Converting Name-Value Records From And To String Arrays
“hc_nvr_create_from_string_arrays” on page 84 ■ “hc_nvr_convert_to_string_arrays” on page 86 ■ 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, Sun StorageTek 5800 System Client API Reference Manual • June 2008... - Page 85 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 Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions structure, so the original names table and...
-
Page 86: Hc_Nvr_Convert_To_String_Arrays
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 Sun StorageTek 5800 System Client API Reference Manual • June 2008 after calling this function. -
Page 87: Storing Data And Metadata
This function stores both object data and metadata and returns a system_record descriptor. The status from this operation can be reclaimed using Chapter 3 • Sun StorageTek 5800 System C Client API method may be used to attempt to resolve a store index “hc_session_get_status”... -
Page 88: Hc_Store_Metadata_Ez
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); Sun StorageTek 5800 System Client API Reference Manual • June 2008 “read_from_data_source” on page... -
Page 89: 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); Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions... - Page 90 Return Codes HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION HCERR_INVALID_OID Sun StorageTek 5800 System Client API Reference Manual • June 2008 21). Once a store index exception occurs (as...
-
Page 91: Retrieving Data And Metadata
IN: The opaque data delivered to the data_writer callback to identify this data stream. IN: Identifier for the metadata record to retrieve. Return Codes HCERR_OK HCERR_BAD_REQUEST Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions “write_to_data_destination”... -
Page 92: Hc_Retrieve_Metadata_Ez
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 Sun StorageTek 5800 System Client API Reference Manual • June 2008 to free the name-value-record. -
Page 93: Hc_Range_Retrieve_Ez
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 Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions... -
Page 94: Querying Metadata
Prepared statement example: “Querying With a Prepared Statement” on page 110 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, Sun StorageTek 5800 System Client API Reference Manual • June 2008... - Page 95 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 Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions “hc_nvr_free” on page 66. In both cases the result 46, each member of which is the name of a field “hc_query_result_set_t”...
-
Page 96: Hc_Qrs_Next_Ez
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 Sun StorageTek 5800 System Client API Reference Manual • June 2008 “hc_query_result_set_t” on page “hc_nvr_free” on page... -
Page 97: Hc_Qrs_Is_Query_Complete
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 Chapter 3 • Sun StorageTek 5800 System C Client API “hc_query_result_set_t” on page... -
Page 98: Hc_Qrs_Get_Query_Integrity_Time
Parameter rset Updated to point to the new query result set. See Return Codes HCERR_OK HCERR_BAD_REQUEST Sun StorageTek 5800 System Client API Reference Manual • June 2008 “hc_query_result_set_t” on page... -
Page 99: Hc_Qrs_Free
Parameter rset Return Codes HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_RESULT_SET See Also “hc_query_ez” on page 94 “hc_pstmt_query_ez” on page 109 Chapter 3 • Sun StorageTek 5800 System C Client API “hc_query_ez” on page 94. Your application should be Synchronous C API Functions... -
Page 100: Hc_Pstmt_Create
OUT: Updated to point to opaque Return Codes HCERR_OK HCERR_OOM See Also “hc_pstmt_query_ez” on page 109 Sun StorageTek 5800 System Client API Reference Manual • June 2008 for use with the “hc_pstmt_query_ez” on page 109 “hc_pstmt_query_ez” on page 109 “hc_pstmt_t” on page... -
Page 101: Hc_Pstmt_Free
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 server. Chapter 3 • Sun StorageTek 5800 System C Client API with all its bindings. to one of the variables in a prepared “hc_pstmt_t”... -
Page 102: Hc_Pstmt_Set_Char
Errors in binding and type are returned when the “hc_pstmt_t” on page 49 Parameters pstmt Prepared statement to add the binding to. which Sun StorageTek 5800 System Client API Reference Manual • June 2008 “hc_pstmt_t” on page is used to query the server. -
Page 103: Hc_Pstmt_Set_Double
IN: Variable (”?’) in the prepared statement, numbered from 1. value IN: Double precision value to bind. Chapter 3 • Sun StorageTek 5800 System C Client API “hc_pstmt_t” on page to one of the variables in a prepared is used to query the server. -
Page 104: Hc_Pstmt_Set_Long
“hc_long_t” on page 46 Return Codes HCERR_OK HCERR_OOM Sun StorageTek 5800 System Client API Reference Manual • June 2008 binding to a “hc_pstmt_t” on page “hc_long_t” on page 46 to one of the variables in a prepared statement. “hc_pstmt_t” on page 49 is used to query the server. -
Page 105: Hc_Pstmt_Set_Date
IN: Variable (”?’) in the prepared statement, numbered from 1. value IN: struct tm (time.h) value to bind. Return Codes HCERR_OK HCERR_OOM Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions is used to query the server. -
Page 106: Hc_Pstmt_Set_Time
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_create” on page 100 Sun StorageTek 5800 System Client API Reference Manual • June 2008 “hc_pstmt_t” on page is used to query the server. -
Page 107: Hc_Pstmt_Set_Timestamp
IN: struct timespec (time.h) value to bind. Return Codes HCERR_OK HCERR_OOM See Also “hc_pstmt_create” on page 100 Chapter 3 • Sun StorageTek 5800 System C Client API Synchronous C API Functions “hc_pstmt_t” on page 49 is used to query the... -
Page 108: Hc_Pstmt_Set_Binary
IN: Number of bytes in array of binary data. Return Codes HCERR_OK HCERR_OOM See Also “hc_pstmt_create” on page 100 Sun StorageTek 5800 System Client API Reference Manual • June 2008 “hc_pstmt_t” on page is used to query the server. -
Page 109: Hc_Pstmt_Query_Ez
IN: The number of results per internal fetch. rsetp OUT: Updated to point to the new result set. See Chapter 3 • Sun StorageTek 5800 System C Client API is used to access the results in the result set. If the “hc_nvr_free” on page 66. -
Page 110: Querying With A Prepared Statement
= 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) printf("today’s oid: %s\n", oid); res = hc_qrs_free(rset); Sun StorageTek 5800 System Client API Reference Manual • June 2008 break;... -
Page 111: Deleting Records
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. Chapter 3 • Sun StorageTek 5800 System C Client API int finished;... -
Page 112: Translating Error And Type Codes
Translates an error code into a string. Synopsis char *hc_decode_hcerr(hcerr_t res); Description Translates an error code into a string. Parameter IN: The error code returned by a function. Sun StorageTek 5800 System Client API Reference Manual • June 2008... -
Page 113: Hc_Decode_Hc_Type
Querying With a Prepared Statement 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. Chapter 3 • Sun StorageTek 5800 System C Client API... -
Page 115: Sun Storagetek 5800 System Query Language
This chapter provides information on the 5800 system query language. For details of the metadata system and how it is configured, see Chapter 8, “Configuring Note – Metadata and Virtual File System Views” in Sun StorageTek 5800 Storage System Administration Guide. The following topics are discussed: “Interfaces”... -
Page 116: Sun Storagetek 5800 System Client Api Reference Manual • June
Other fields that must store an OID should use the string or binary type for that field. Sun StorageTek 5800 System Client API Reference Manual • June 2008 123. These are the query expression types that should work identically on the 5800... -
Page 117: Queries
SQL reserved word in any of the Sun StorageTek 5800 underlying metadata databases. Attribute names must appear in the current 5800 system schema to be used in a query. This is because the proper type information about each attribute must be derived to build the query. -
Page 118: Sql Syntax In 5800 System Queries
Only ASCII digits are recognized as numeric literals. For example, 45, -1, 3.14, 5.2E10. Digits from other parts of the Unicode code space will cause a parse error. Sun StorageTek 5800 System Client API Reference Manual • June 2008 “query (with PreparedStatement)” on page “PreparedStatement”... -
Page 119: Literals For 5800 System Data Types
This canonical string encoding is used in the following places: When exposing the field as a directory component or a filename component in a virtual view ■ Chapter 4 • Sun StorageTek 5800 System Query Language “Canonical String Format” on page Table Canonical String Representation The string itself. -
Page 120: The Canonical String Decode Operation
5800 system cluster and client machine. Sun StorageTek 5800 System Client API Reference Manual • June 2008 to create a typed query value from a string representation of that value. -
Page 121: Reserved Words
– _ matches one character in the corresponding position in expr1. – Any other character matches only that character in the corresponding position in the character expression. ■ expr1 BETWEEN expr2 AND expr3 Chapter 4 • Sun StorageTek 5800 System Query Language Supported Expression Types... - Page 122 The form "field_name IS NULL" to identify all the objects that lack a value for a Note – specific field is not supported and will not work properly in all cases. Sun StorageTek 5800 System Client API Reference Manual • June 2008...
-
Page 123: Examples Of Supported Query Expressions
DEGREES(number) ■ EXP(float) ■ FLOOR(number) ■ LOG(float) ■ LOG10(float) ■ ASCII(string) ■ MOD(float1, float2) ■ PI() ■ POWER(number, power) ■ RADIANS(number) ■ RAND(integer) ■ SIGN(number) Chapter 4 • Sun StorageTek 5800 System Query Language Queries Not Supported in Version 1.1... -
Page 124: Sql Words That Are Allowed In Queries
ATOMIC, AUTHORIZATION, AVG, BEGIN, BY, CALL, CASCADE, CASCADED, CATALOG, CHECK, CLOSE, COLUMN, COMMIT, COMPRESS, CONNECT, CONNECTION, CONSTRAINT, CONSTRAINTS, CONTINUE, CONVERT, CORRESPONDING, CREATE, CROSS, CURRENT, CURRENT_PATH, CURRENT_SCHEMA, CURRENT_SCHEMAID, CURRENT_USER, CURRENT_USERID, CURSOR, DATA, Sun StorageTek 5800 System Client API Reference Manual • June 2008... - Page 125 UNIQUE, UNTIL, UPDATE, USAGE, USER, USING, VALUE, VALUES, VIEW, WHERE, WHILE, WITH, WORK, WRITE, ALLSCHEMAS, ALLTABLES, ALLVIEWS, ALLVIEWTEXTS, ALLCOLUMNS, ALLINDEXES, ALLINDEXCOLS, ALLUSERS, ALLTBTS, TABLEPRIVILEGES, TBTPRIVILEGES, MYSCHEMAS, MYTABLES, MYTBTS, MYVIEWS, SCHEMAVIEWS, DUAL, SCHEMAPRIVILEGES, SCHEMATABLES, STATISTICS, USRTBL, STRINGTABLE, LONGTABLE, DOUBLETABLE. Chapter 4 • Sun StorageTek 5800 System Query Language...
-
Page 127: Programming Considerations And Best Practices
C H A P T E R Programming Considerations and Best Practices This chapter provides considerations and practices that can help you create efficient 5800 system applications. The following topics are discussed: “Retries and Timeouts” on page 127 ■ “Query Size Limit” on page 127 ■... -
Page 128: Limit The Size Of Schema Query Parameters And Literals
These sizes are similar to what is described in the Sun StorageTek 5800 System Administration Guide, Table 7-6, Number of Bytes Used by Each Element Type in a Schema Table. -
Page 129: Index
Index Numbers and Symbols 5800 system Honeycomb project, 17 summary, 16-17 best practices max results per fetch, 128 retries and timeouts, 127 schema query size, 128 C client API application deployment, 43 architecture, 40 failure and recovery, 43 hc_cleanup, 42 hc_init, 41-42 hc_system_record_t, 42-43 heap memory... - Page 130 41 deallocator, 41 reallocator, 41 Honeycomb project, overview, 17 isQueryComplete method, 37 Sun StorageTek 5800 System Client API Reference Manual • June 2008 Java client API application deployment, 27 basic concepts, 28 classes, 28 NameValueObjectArchive, 29, 30-38...
- Page 131 metadata (Continued) retrieving, 91 storing, 87 hc_store_both_ez, 87-88 metadata model, overview, 19-20 models data, 17-19 deleting objects, 22-23 metadata, 19-20 query, 20-21 query integrity, 21-22 multithreaded access, 40 name-value records, 63 building, 66-67 hc_nvr_add_binary, 71 hc_nvr_add_date, 72 hc_nvr_add_double, 69 hc_nvr_add_from_string, 75 hc_nvr_add_long, 68 hc_nvr_add_string, 70 hc_nvr_add_time, 73...
- Page 132 100 freeing hc_pstmt_free, 101 querying example, 110-113 retrieve OIDs, optionally retrieve name-value record hc_pstmt_query_ez, 109-110 Sun StorageTek 5800 System Client API Reference Manual • June 2008 queries, 117-118 best practices, 128 determine if complete hc_qrs_is_query_complete, 97-98 determine query integrity time...
- Page 133 StorageTek 5800, Query Language, 115-125 storeMetadata method, 32 storeObject method, 31-32 string decode operation, canonical, 120 string format, canonical, 119-120 Sun StorageTek 5800, Query Language, 115-125 Sun StorageTek 5800 system semantics data and metadata, 17-19 Sun StorageTek 5800 system, semantics (Continued)
- Page 134 63 building, 66-67 creating and converting, 84 creating and freeing, 65 hc_nvr_add_binary, 71 Sun StorageTek 5800 System Client API Reference Manual • June 2008 synchronous C API, name-value records (Continued) hc_nvr_add_date, 72 hc_nvr_add_double, 69 hc_nvr_add_from_string, 75 hc_nvr_add_long, 68...
- Page 135 Index timeouts, 127...
Need help?
Do you have a question about the Sun StorageTek 5800 and is the answer not in the manual?
Questions and answers