1 /*=========================================================================== 2 * 3 * PUBLIC DOMAIN NOTICE 4 * National Center for Biotechnology Information 5 * 6 * This software/database is a "United States Government Work" under the 7 * terms of the United States Copyright Act. It was written as part of 8 * the author's official duties as a United States Government employee and 9 * thus cannot be copyrighted. This software/database is freely available 10 * to the public for use. The National Library of Medicine and the U.S. 11 * Government have not placed any restriction on its use or reproduction. 12 * 13 * Although all reasonable efforts have been taken to ensure the accuracy 14 * and reliability of the software and data, the NLM and the U.S. 15 * Government do not and cannot warrant the performance or results that 16 * may be obtained by using this software or data. The NLM and the U.S. 17 * Government disclaim all warranties, express or implied, including 18 * warranties of performance, merchantability or fitness for any particular 19 * purpose. 20 * 21 * Please cite the author in any work or product based on this material. 22 * 23 * =========================================================================== 24 * 25 */ 26 27 #ifndef _h_vdb_vdb_priv_ 28 #define _h_vdb_vdb_priv_ 29 30 #ifndef _h_vdb_extern_ 31 #include <vdb/extern.h> 32 #endif 33 34 #ifndef _h_klib_defs_ 35 #include <klib/defs.h> 36 #endif 37 38 #ifndef _h_vdb_quality_ 39 #include <vdb/quality.h> /* VQuality */ 40 #endif 41 42 #include <stdarg.h> 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 49 /*-------------------------------------------------------------------------- 50 * forwards 51 */ 52 struct KDatabase; 53 struct KTable; 54 struct KMetadata; 55 struct KMDataNode; 56 struct KDBManager; 57 struct KDirectory; 58 struct VDBManager; 59 struct VFSManager; 60 struct VPath; 61 struct VResolver; 62 struct VSchema; 63 struct VTypedef; 64 struct VDatabase; 65 struct VTable; 66 struct VCursor; 67 struct VCursorParams; 68 struct VXformInfo; 69 struct KDataBuffer; 70 struct KNamelist; 71 struct String; 72 73 74 /*-------------------------------------------------------------------------- 75 * VDBManager 76 */ 77 78 79 /* MakeRsrc 80 * common make, regardless of library 81 */ 82 VDB_EXTERN rc_t CC VDBManagerMakeRsrc ( struct VDBManager **mgr, struct VFSManager * vfs ); 83 84 85 /* OpenKDBManager 86 * returns a new reference to KDBManager used by VDBManager 87 */ 88 VDB_EXTERN rc_t CC VDBManagerOpenKDBManagerRead ( struct VDBManager const *self, 89 struct KDBManager const **kmgr ); 90 VDB_EXTERN rc_t CC VDBManagerOpenKDBManagerUpdate ( struct VDBManager *self, 91 struct KDBManager **kmgr ); 92 93 #define VDBManagerGetKDBManagerRead VDBManagerOpenKDBManagerRead 94 #define VDBManagerGetKDBManagerUpdate VDBManagerOpenKDBManagerUpdate 95 96 97 /* ListExternalSchemaModules 98 */ 99 VDB_EXTERN rc_t CC VDBManagerListExternalSchemaModules ( struct VDBManager const *self, 100 struct KNamelist **list ); 101 102 /* DisablePagemapThread 103 * this can cause difficulties for some clients 104 */ 105 VDB_EXTERN rc_t CC VDBManagerDisablePagemapThread ( struct VDBManager const *self ); 106 107 /* DisableFlushThread 108 * Disable the background cursor flush thread, may be useful when debugging 109 */ 110 VDB_EXTERN rc_t CC VDBManagerDisableFlushThread ( struct VDBManager *self ); 111 112 113 /* Make with custom VFSManager */ 114 VDB_EXTERN rc_t CC VDBManagerMakeReadWithVFSManager ( 115 struct VDBManager const **mgr, 116 struct KDirectory const *wd, struct VFSManager *vmgr ); 117 VDB_EXTERN rc_t CC VDBManagerMakeUpdateWithVFSManager ( 118 struct VDBManager **mgr, struct KDirectory *wd, struct VFSManager *vmgr ); 119 VDB_EXTERN rc_t CC VDBManagerMakeWithVFSManager ( struct VDBManager const **mgr, 120 struct KDirectory const *wd, struct VFSManager *vmgr ); 121 122 /** Reset VResolver to set protected repository context */ 123 VDB_EXTERN rc_t CC VDBManagerSetResolver 124 ( struct VDBManager const * self, struct VResolver * resolver ); 125 126 127 /** Unreliable object: do not report occured erros */ 128 VDB_EXTERN int CC VDBManagerPathTypeUnreliable ( const struct VDBManager * self, 129 const char *object, ... ); 130 131 132 /*-------------------------------------------------------------------------- 133 * VSchema 134 */ 135 136 /* DescribeTypedef - PRIVATE 137 * a type is defined as either: 138 */ 139 VDB_EXTERN rc_t CC VSchemaDescribeTypedef ( struct VSchema const *self, 140 struct VTypedef *def, uint32_t type_id ); 141 142 /* LastIntrinsicTypeId - PRIVATE 143 * used to allow cast to intrinsics 144 */ 145 VDB_EXTERN uint32_t CC VSchemaLastIntrinsicTypeId ( struct VSchema const *self ); 146 147 /* ListLegacyTables - PRIVATE 148 * scan all tables defined in schema 149 * return the fully-qualified and versioned name of each legacy SRA table 150 */ 151 VDB_EXTERN rc_t CC VSchemaListLegacyTables ( struct VSchema const *self, struct KNamelist **list ); 152 153 /* DumpToKMDataNode 154 * given a VSchema, an updatable KMDataNode, an object spec string and object type, 155 * find the typed object within VSchema by name, dump its schema text into the node, 156 * and set the attribute name to the full object name and version. 157 */ 158 VDB_EXTERN rc_t CC VSchemaDumpToKMDataNode ( struct VSchema const * self, 159 struct KMDataNode * node, const char * spec ); 160 161 162 /*-------------------------------------------------------------------------- 163 * VDatabase 164 */ 165 166 /* OpenDBReadVPathLight 167 * used just to analyze VDatabase: 168 * - don't try to locate and open vdbcache 169 * - don't fail if database's quality does not match requested one 170 */ 171 VDB_EXTERN rc_t CC VDBManagerOpenDBReadVPathLight( 172 struct VDBManager const *self, const struct VDatabase **db, 173 struct VSchema const *schema, const struct VPath *path); 174 175 /* OpenKDatabase 176 * returns a new reference to underlying KDatabase 177 */ 178 VDB_EXTERN rc_t CC VDatabaseOpenKDatabaseRead ( struct VDatabase const *self, struct KDatabase const **kdb ); 179 VDB_EXTERN rc_t CC VDatabaseOpenKDatabaseUpdate ( struct VDatabase *self, struct KDatabase **kdb ); 180 181 182 /* IsCSRA 183 * ask an open database if it conforms to cSRA schema 184 */ 185 VDB_EXTERN bool CC VDatabaseIsCSRA ( struct VDatabase const *self ); 186 187 /* Get accession of database (is avalibable) 188 * acc needs to be released 189 */ 190 VDB_EXTERN rc_t CC 191 VDatabaseGetAccession(const struct VDatabase * self, const struct String ** acc); 192 193 /*-------------------------------------------------------------------------- 194 * VTable 195 */ 196 197 /* OpenKTable 198 * returns a new reference to underlying KTable 199 */ 200 VDB_EXTERN rc_t CC VTableOpenKTableRead ( struct VTable const *self, struct KTable const **ktbl ); 201 VDB_EXTERN rc_t CC VTableOpenKTableUpdate ( struct VTable *self, struct KTable **ktbl ); 202 203 #define VTableGetKTableRead VTableOpenKTableRead 204 #define VTableGetKTableUpdate VTableOpenKTableUpdate 205 206 207 /* DropColumn 208 */ 209 VDB_EXTERN rc_t CC VTableDropColumn ( struct VTable *self, const char *name, ... ); 210 VDB_EXTERN rc_t CC VTableVDropColumn ( struct VTable *self, const char *name, va_list args ); 211 212 /* RenameColumn 213 */ 214 VDB_EXTERN rc_t CC VTableRenameColumn ( struct VTable *self, bool force, 215 const char *from, const char *to ); 216 217 /* ListPhysColumns 218 * ListSeededWritableColumns 219 * avail: 2.4 220 */ 221 VDB_EXTERN rc_t CC VTableListPhysColumns ( struct VTable const *self, struct KNamelist **names ); 222 VDB_EXTERN rc_t CC VTableListSeededWritableColumns ( struct VTable *self, 223 struct KNamelist **names, struct KNamelist const *seed ); 224 225 226 /* HasStaticColumn 227 * given a physical column name, report whether it exists 228 * and is ( currently ) static 229 * avail: 2.5 230 */ 231 VDB_EXTERN bool CC VTableHasStaticColumn ( struct VTable const *self, const char *name ); 232 VDB_EXTERN bool CC VTableVHasStaticColumn ( struct VTable const *self, const char *name, va_list args ); 233 234 235 /* VUntypedTableTest 236 * support for tables created before embedded schema 237 * 238 * "ktbl" [ IN ] - physical table to recognize 239 * 240 * "meta" [ IN ] - open metadata for table 241 * 242 * returns true if table is recognized 243 */ 244 typedef bool ( CC * VUntypedTableTest ) 245 ( struct KTable const *ktbl, struct KMetadata const *meta ); 246 247 248 /* StoreSchema 249 * stores current schema definition in metadata 250 * 251 * useful if table was opened using a later version of schema than 252 * was used for its creation. 253 */ 254 VDB_EXTERN rc_t VTableStoreSchema ( struct VTable *self ); 255 256 257 /*-------------------------------------------------------------------------- 258 * VCursor 259 */ 260 261 262 /* CreateCursorView 263 * creates a read-only cursor onto table 264 * uses table schema as base 265 * uses view described in viewspec as view 266 * 267 * AVAILABILITY: version 2.3 268 * 269 * for pre-vdb-2.3 tables, defaults to CreateCursorRead, ignoring 270 * schema specification 271 * 272 * "curs" [ OUT ] - return parameter for newly created cursor 273 * 274 * "viewspec" [ IN ] - NUL terminated string describing the view schema 275 */ 276 VDB_EXTERN rc_t CC VTableCreateCursorView ( struct VTable const *self, 277 struct VCursor const **curs, const char *viewspec ); 278 279 /* PermitPostOpenAdd 280 * allows columns to be added to open cursor 281 * for write cursor, the effect lasts until the first row commit 282 */ 283 VDB_EXTERN rc_t CC VCursorPermitPostOpenAdd ( struct VCursor const *self ); 284 /* SuspendTriggers 285 * blocks resolution of schema-based triggers 286 * 287 */ 288 VDB_EXTERN rc_t CC VCursorSuspendTriggers ( struct VCursor const *self ); 289 290 /* VCursorGetSchema 291 * returns current schema of the open cursor 292 */ 293 VDB_EXTERN struct VSchema const* CC VCursorGetSchema ( struct VCursor const *self); 294 295 /* PageIdRange 296 * returns id range for page 297 * 298 * "id" [ IN ] - page containing this row id is target 299 * 300 * "first" [ OUT, NULL OKAY ] and "last" [ OUT, NULL OKAY ] - 301 * id range is returned in these output parameters, where 302 * at least ONE must be NOT-NULL 303 */ 304 VDB_EXTERN rc_t CC VCursorPageIdRange ( struct VCursor const *self, 305 uint32_t idx, int64_t id, int64_t *first, int64_t *last ); 306 307 308 /* IsStaticColumn 309 * answers question: "does this column have the same value for every cell?" 310 */ 311 VDB_EXTERN rc_t CC VCursorIsStaticColumn ( struct VCursor const *self, 312 uint32_t col_idx, bool *is_static ); 313 314 315 VDB_EXTERN rc_t CC VCursorLinkedCursorGet(const struct VCursor *cself,const char *tbl, struct VCursor const **curs); 316 VDB_EXTERN rc_t CC VCursorLinkedCursorSet(const struct VCursor *cself,const char *tbl, struct VCursor const *curs); 317 318 VDB_EXTERN uint64_t CC VCursorSetCacheCapacity(struct VCursor *self,uint64_t capacity); 319 VDB_EXTERN uint64_t CC VCursorGetCacheCapacity(const struct VCursor *self); 320 321 322 /*-------------------------------------------------------------------------- 323 * VCursorParams 324 */ 325 326 /* Get 327 * return KDataBuffer value by reference 328 */ 329 VDB_EXTERN rc_t CC VCursorParamsGet ( struct VCursorParams const *self, 330 const char *name, struct KDataBuffer **value ); 331 332 /* Set 333 * set a textual parameter value 334 */ 335 VDB_EXTERN rc_t CC VCursorParamsSet( struct VCursorParams const *self, 336 const char *name, const char *fmt, ... ); 337 VDB_EXTERN rc_t CC VCursorParamsVSet ( struct VCursorParams const *self, 338 const char *name, const char *fmt, va_list args ); 339 340 /* Unset 341 * set the value of a named parameter to "undefined" 342 */ 343 VDB_EXTERN rc_t CC VCursorParamsUnset ( struct VCursorParams const *self, const char *name ); 344 345 346 /*-------------------------------------------------------------------------- 347 * xform 348 */ 349 350 /* 351 uses vftReserved code 352 returns little-endian data, no row-wise rle 353 fixed row-length is calculated as dst->elem_count / num_rows 354 */ 355 #define vftLegacyBlob vftReserved 356 357 typedef struct VLegacyBlobResult VLegacyBlobResult; 358 struct VLegacyBlobResult 359 { 360 struct KDataBuffer *dst; 361 uint8_t byte_order; 362 }; 363 364 typedef rc_t ( CC * VNoHdrBlobFunc ) ( void *self, 365 struct VXformInfo const *info, VLegacyBlobResult *rslt, 366 struct KDataBuffer const *src ); 367 368 /* function to call to test table against schema */ 369 typedef bool ( CC * VUntypedFunc ) 370 ( struct KTable const *tbl, struct KMetadata const *meta ); 371 372 373 VDB_EXTERN VQuality CC VDBManagerGetQuality(const struct VDBManager * self); 374 375 376 #ifdef __cplusplus 377 } 378 #endif 379 380 #endif /* _h_vdb_vdb_priv_ */ 381