Summary of the content on the page No. 1
SunStorageTek5800System
ClientAPIReferenceManual
SunMicrosystems,Inc.
4150NetworkCircle
SantaClara,CA95054
U.S.A.
PartNo:820–4796
June2008
Summary of the content on the page No. 2
Copyright2008SunMicrosystems,Inc. 4150NetworkCircle,SantaClara,CA95054U.S.A. Allrightsreserved. SunMicrosystems,Inc.hasintellectualpropertyrightsrelatingtotechnologyembodiedintheproductthatisdescribedinthisdocument.Inparticular,andwithout limitation,theseintellectualpropertyrightsmayincludeoneormoreU.S.patentsorpendingpatentapplicationsintheU.S.andinothercountries. U.S.GovernmentRights–Commercialsoftware.GovernmentusersaresubjecttotheSunMicrosystems,Inc.standardlicenseagreementandapplicableprovi
Summary of the content on the page No. 3
Contents Preface...................................................................................................................................................11 1 SunStorageTek5800SystemClientAPI ..........................................................................................15 ChangesinVersion1.1 .......................................................................................................................15 5800SystemOverview .............................................
Summary of the content on the page No. 4
Contents 3 SunStorageTek5800SystemCClientAPI.......................................................................................39 Overviewofthe5800SystemCClientAPI ......................................................................................39 Architecture..................................................................................................................................40 Interfaces........................................................................................
Summary of the content on the page No. 5
Contents hc_session_get_platform_result.........................................................................................58 hc_session_get_archive..........................................................................................................59 ManagingaSchema .....................................................................................................................59 hc_schema_get_type ...................................................................................
Summary of the content on the page No. 6
Contents StoringDataandMetadata .........................................................................................................87 hc_store_both_ez ......................................................................................................................87 hc_store_metadata_ez ..............................................................................................................88 hc_check_indexed_ez ....................................................................
Summary of the content on the page No. 7
Contents SupportedDataTypes.......................................................................................................................116 Queries................................................................................................................................................117 TranslatingaQuerytotheUnderlyingDatabase...................................................................117 AttributeFormatinQueries ...........................................................
Summary of the content on the page No. 8
8
Summary of the content on the page No. 9
Tables TABLE4–1 CanonicalStringRepresentationofDataTypes..................................................119 9
Summary of the content on the page No. 10
10
Summary of the content on the page No. 11
Preface TheSunStorageTek5800SystemClientAPIReferenceManualiswrittenforprogrammersand TM applicationdeveloperswhodevelopcustomapplicationsfortheSunStorageTek 5800System. Thisdocument,alongwiththeSunStorageTek5800SystemSDKReferenceManual,providesthe informationthatyouneedtodevelopcustomapplicationsforthe5800system. HowThisBookIsOrganized ■ Chapter1,“SunStorageTek5800SystemClientAPI,”providesasummaryofthechanges fortheSunStorageTek5800System1.1release,andoverviewsoftheclientAPIsandquery language. ■
Summary of the content on the page No. 12
Preface RelatedThird-PartyWebSiteReferences Third-partyURLsarereferencedinthisdocumentandprovideadditional,relatedinformation. Note–Sunisnotresponsiblefortheavailabilityofthird-partywebsitesmentionedinthis document.Sundoesnotendorseandisnotresponsibleorliableforanycontent,advertising, products,orothermaterialsthatareavailableonorthroughsuchsitesorresources.Sunwillnot beresponsibleorliableforanyactualorallegeddamageorlosscausedorallegedtobecausedby orinconnectionwithuseoforrelianceonanysuchconten
Summary of the content on the page No. 13
Preface TABLEP–1 TypographicConventions (Continued) Typeface Meaning Example AaBbCc123 Booktitles,newterms,andtermstobe ReadChapter6intheUser'sGuide. emphasized Acacheisacopythatisstored locally. Donotsavethefile. Note:Someemphasizeditems appearboldonline. ShellPromptsinCommandExamples ThefollowingtableshowsthedefaultUNIX®systempromptandsuperuserpromptfortheC shell,Bourneshell,andKornshell. TABLEP–2 ShellPrompts Shell Prompt Cshell machine_name% Cshellforsuperuser machine_name# BourneshellandKor
Summary of the content on the page No. 14
14
Summary of the content on the page No. 15
CHAPTER 1 1 SunStorageTek5800SystemClientAPI TM TM TheSun StorageTek 5800systemclientAPIprovidesprogrammaticaccesstoa5800system servertostore,retrieve,query,anddeleteobjectdataandmetadata.Synchronousversionsare TM providedinCandJava languages.Afuturereleasewillimplementanon-blockingCAPIfor usewithPOSIXoperations. ThischapterprovidesasummaryofthechangesfortheSunStorageTek5800System1.1 release,andoverviewsoftheclientAPIsandquerylanguage. Thefollowingtopicsarediscussed: ■ “ChangesinVersion1.1”onpag
Summary of the content on the page No. 16
5800SystemOverview In5800systemversion1.1,anattempttostoreavaluethatislongerthantheassociatedfield generatesanimmediateerror. 5800SystemOverview Thissectionprovidesanoverviewsofthe5800system,the5800systemhistory,anda summariesofthekeypointsofthe5800systemusagemodel. Thefollowingtopicsarediscussed: ■ “5800SystemSummary”onpage16 ■ “The5800SystemandHoneycomb”onpage17 ■ “The5800SystemDataModel”onpage17 ■ “The5800SystemMetadataModel”onpage19 ■ “The5800SystemQueryModel”onpage20 ■ “The5800SystemQueryIn
Summary of the content on the page No. 17
5800SystemOverview Thischapterprovidesasummaryofkeypointsofthe5800systemusagemodelthatareuseful forunderstandingeitherAPI. Inthefollowingsections,thetermsfromtheJavaAPIareusedasanaidtoexposition.Inall cases,asimpleequivalentusingtheCAPIisavailable. ■ Chapter4,“SunStorageTek5800SystemQueryLanguage,”providesadetaileddescription ofquerycapabiltiesandquerysyntax. ■ Chapter5,“ProgrammingConsiderationsandBestPractices,”providesprogramming considerationsandbestpracticesthatcanhelpyoucreateefficient5800
Summary of the content on the page No. 18
5800SystemOverview Read-Multiple(WORM)archive.Eachobjectcorrespondstoasinglestreamofdataanda singlesetofmetadata;thereareno“groupedobjects”or“compoundobjects”otherthanby applicationconvention. Eachobjectcorrespondstoasinglestreamofdataandasinglesetofmetadata.Thereareno “groupedobjects”or“compoundobjects”otherthanbyapplicationconvention.Similarly, thereareno“links”or“associations“fromoneobjecttoanother.Thecustomerapplicationis shieldedfromalldetailsofhoworwheretheobjectisstored.Internally,theactu
Summary of the content on the page No. 19
5800SystemOverview The5800SystemMetadataModel Metadatameans“dataaboutthedata”;itdescribesthedataandhelpstodeterminehowthedata shouldbeinterpreted.Inaddition,metadatacanbeusedtofacilitatequeryingthe5800system forobjectsthatmatchaparticularsetofsearchcriteria. Forthe5800system,thesupportedmetadataoptionisintheformofname-valuefieldsstored witheachobject.Thesetofpossiblefieldsisdefinedinthemetadataschema.Settingupa metadataschemaisanimportantsystemadministrationtaskthatisdescribedinthe5800 SystemAdm
Summary of the content on the page No. 20
5800SystemOverview Themetadataassociatedwithanobjectisimmutable.Thereisnooperationtomodifythe metadataassociatedwithanobjectaftertheobjecthasbeenstored.Instead,thestoreMetadata operationcanbeusedtocreateacompletelynewobjectbyassociatingnewusermetadatawith theunderlyingdataandsystem-metadataofanexistingobject.ThestoreMetadataoperation doesnotmergethenewmetadatainwiththemetadatafromtheoriginalOID;instead,the storeMetadataoperationcreatesanewmetadatarecordpointingtothesamedataobject.To accomplisham
