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