1 /* @source ensdatabaseadaptor *************************************************
2 **
3 ** Ensembl Database Adaptor functions
4 **
5 ** @author Copyright (C) 1999 Ensembl Developers
6 ** @author Copyright (C) 2006 Michael K. Schuster
7 ** @version $Revision: 1.45 $
8 ** @modified 2009 by Alan Bleasby for incorporation into EMBOSS core
9 ** @modified $Date: 2013/02/17 13:02:40 $ by $Author: mks $
10 ** @@
11 **
12 ** This library is free software; you can redistribute it and/or
13 ** modify it under the terms of the GNU Lesser General Public
14 ** License as published by the Free Software Foundation; either
15 ** version 2.1 of the License, or (at your option) any later version.
16 **
17 ** This library is distributed in the hope that it will be useful,
18 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 ** Lesser General Public License for more details.
21 **
22 ** You should have received a copy of the GNU Lesser General Public
23 ** License along with this library; if not, write to the Free Software
24 ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
25 ** MA 02110-1301, USA.
26 **
27 ******************************************************************************/
28
29 /* ========================================================================= */
30 /* ============================= include files ============================= */
31 /* ========================================================================= */
32
33 #include "ensdatabaseadaptor.h"
34 #include "ensmetainformation.h"
35 #include "enssoftware.h"
36
37
38
39
40 /* ========================================================================= */
41 /* =============================== constants =============================== */
42 /* ========================================================================= */
43
44 /* @const ensKDatabaseadaptorRegCollection ************************************
45 **
46 ** Regular expression to match Ensembl collection databases.
47 **
48 ******************************************************************************/
49
50 const char *ensKDatabaseadaptorRegCollection =
51 "^" /* Start of string assertion */
52 "(\\w+)" /* Genus name (1) */
53 "_" /* Separator */
54 "collection" /* Prefix */
55 "_" /* Separator */
56 "([a-z]+)" /* Ensembl Database group (2) */
57 "(?:_\\d+)?" /* Ensembl Genomes version */
58 "_" /* Separator */
59 "(\\d+)" /* Ensembl Software version (3) */
60 "_" /* Separator */
61 "[0-9a-z]+" /* Assembly suffix */
62 "$"; /* End of string assertion */
63
64
65
66
67 /* @const ensKDatabaseadaptorRegMulti *****************************************
68 **
69 ** Regular expression to match Ensembl multi-species databases.
70 **
71 ******************************************************************************/
72
73 const char *ensKDatabaseadaptorRegMulti =
74 "^" /* Start of string assertion */
75 "ensembl(?:genomes)?" /* Prefix */
76 "_" /* Separator */
77 "([a-z]+)" /* Ensembl Database group (1) */
78 "(_\\w+?)*?" /* Ensembl Genomes section (2) */
79 "(?:_\\d+)?" /* Ensembl Genomes version */
80 "_" /* Separator */
81 "(\\d+)" /* Ensembl Software version (3) */
82 "$"; /* End of string assertion */
83
84
85
86
87 /* @const ensKDatabaseadaptorRegSpecies ***************************************
88 **
89 ** Regular expression to match Ensembl species-specific databases.
90 **
91 ******************************************************************************/
92
93 const char *ensKDatabaseadaptorRegSpecies =
94 "^" /* Start of string assertion */
95 "([a-z]+_[0-9a-z]+(?:_[a-z0-9]+)?)" /* Species name (1) */
96 /* homo_sapiens or canis_lupus_familiaris */
97 "_" /* Separator */
98 "([a-z]+)" /* Database group (2) */
99 "(?:_\\d+)?" /* Ensembl Genomes version */
100 "_" /* Separator */
101 "(\\d+)" /* Ensembl Software version (3) */
102 "_" /* Separator */
103 "[0-9a-z]+" /* Assembly suffix */
104 "$"; /* End of string assertion */
105
106
107
108
109 /* ========================================================================= */
110 /* =========================== global variables ============================ */
111 /* ========================================================================= */
112
113
114
115
116 /* ========================================================================= */
117 /* ============================= private data ============================== */
118 /* ========================================================================= */
119
120
121
122
123 /* ========================================================================= */
124 /* =========================== private constants =========================== */
125 /* ========================================================================= */
126
127 /* @conststatic databaseadaptorKGroup *****************************************
128 **
129 ** The Ensembl Database Adaptor group member is enumerated in the data
130 ** structure. The following strings are used for conversion in database
131 ** operations and correspond to EnsEDatabaseadaptorGroup.
132 **
133 ******************************************************************************/
134
135 static const char *databaseadaptorKGroup[] =
136 {
137 "",
138 "core",
139 "vega",
140 "otherfeatures",
141 "cdna",
142 "variation",
143 "funcgen",
144 "compara",
145 "ontology",
146 "qc",
147 "pipeline",
148 "hive",
149 "coreexpressionest",
150 "coreexpressiongnf",
151 "ancestral",
152 "website",
153 "production",
154 (const char *) NULL
155 };
156
157
158
159
160 /* ========================================================================= */
161 /* =========================== private variables =========================== */
162 /* ========================================================================= */
163
164
165
166
167 /* ========================================================================= */
168 /* =========================== private functions =========================== */
169 /* ========================================================================= */
170
171
172
173
174 /* ========================================================================= */
175 /* ======================= All functions by section ======================== */
176 /* ========================================================================= */
177
178
179
180
181 /* @filesection ensdatabaseadaptor ********************************************
182 **
183 ** @nam1rule ens Function belongs to the Ensembl library
184 **
185 ******************************************************************************/
186
187
188
189
190 /* @datasection [EnsPDatabaseadaptor] Ensembl Database Adaptor ****************
191 **
192 ** @nam2rule Databaseadaptor Functions for manipulating
193 ** Ensembl Database Adaptor objects
194 **
195 ** @cc Bio::EnsEMBL::DBSQL::DBAdaptor
196 ** @cc CVS Revision: 1.231.2.1
197 ** @cc CVS Tag: branch-ensembl-68
198 **
199 ******************************************************************************/
200
201
202
203
204 /* @section constructors ******************************************************
205 **
206 ** All constructors return a new Ensembl Database Adaptor by pointer.
207 ** It is the responsibility of the user to first destroy any previous
208 ** Database Adaptor. The target pointer does not need to be initialised to
209 ** NULL, but it is good programming practice to do so anyway.
210 **
211 ** @fdata [EnsPDatabaseadaptor]
212 **
213 ** @nam3rule New Constructor
214 ** @nam4rule Databasename Constructor with a database name
215 ** @nam4rule Ini Constructor with initial values
216 ** @nam4rule Url Constructor with a Uniform Resource Locator (URL)
217 **
218 ** @argrule Databasename dbc [EnsPDatabaseconnection]
219 ** Ensembl Database Connection
220 ** @argrule Databasename database [AjPStr] Database name
221 ** @argrule Ini dbc [EnsPDatabaseconnection] Ensembl Database Connection
222 ** @argrule Ini database [AjPStr] Database name
223 ** @argrule Ini species [AjPStr] Species
224 ** @argrule Ini dbag [EnsEDatabaseadaptorGroup]
225 ** Ensembl Database Adaptor Group enumeration
226 ** @argrule Ini multi [AjBool] Multiple species
227 ** @argrule Ini identifier [ajuint] Species identifier
228 ** @argrule Url url [const AjPStr] Uniform Resource Locator
229 **
230 ** @valrule * [EnsPDatabaseadaptor] Ensembl Database Adaptor or NULL
231 **
232 ** @fcategory new
233 ******************************************************************************/
234
235
236
237
238 /* @func ensDatabaseadaptorNewDatabasename ************************************
239 **
240 ** Constructor for an Ensembl Database Adaptor with a database name.
241 **
242 ** An Ensembl database name encodes all information to create an
243 ** Ensembl Database Adaptor. This function parses the database name and sets
244 ** the species and Ensembl Database Adaptor Group accordingly. For collection
245 ** databases only a single Ensembl Database Adaptor representing the entire
246 ** collection is returned, which has the multi-species member set to ajTrue and
247 ** the species indentifier set to 0. An Ensembl Database Adaptor representing a
248 ** collection has to be expanded into species-specific ones.
249 **
250 ** Ensembl Database Adaptors are singleton objects in the sense that a single
251 ** instance of an Ensembl Database Adaptor connected to a particular database
252 ** is sufficient to instantiate any number of Ensembl Object Adaptors from the
253 ** database. Each Ensembl Object Adaptor will have a weak reference to the
254 ** Ensembl Database Adaptor that instantiated it. Therefore, Ensembl Database
255 ** Adaptors should not be instantiated directly, but rather obtained from the
256 ** Ensembl Registry, which will in turn call this function if neccessary.
257 **
258 ** @see ensRegistryNewDatabaseadaptor
259 ** @see ensRegistryGetDatabaseadaptor
260 **
261 ** @param [u] dbc [EnsPDatabaseconnection] Ensembl Database Connection
262 ** @param [u] database [AjPStr] Database name
263 **
264 ** @return [EnsPDatabaseadaptor] Ensembl Database Adaptor or NULL
265 **
266 ** @release 6.4.0
267 ** @@
268 ******************************************************************************/
269
ensDatabaseadaptorNewDatabasename(EnsPDatabaseconnection dbc,AjPStr database)270 EnsPDatabaseadaptor ensDatabaseadaptorNewDatabasename(
271 EnsPDatabaseconnection dbc,
272 AjPStr database)
273 {
274 AjBool debug = AJFALSE;
275
276 AjPRegexp rec = NULL;
277 AjPRegexp rem = NULL;
278 AjPRegexp res = NULL;
279
280 AjPStr group = NULL;
281 AjPStr prefix = NULL;
282 AjPStr swversion = NULL;
283 AjPStr multi = NULL;
284
285 EnsEDatabaseadaptorGroup dbag = ensEDatabaseadaptorGroupNULL;
286
287 EnsPDatabaseadaptor dba = NULL;
288
289 debug = ajDebugTest("ensDatabaseadaptorNewDatabasename");
290
291 if (debug)
292 {
293 ajDebug("ensDatabaseadaptorNewDatabasename\n"
294 " dbc %p\n"
295 " database '%S'\n",
296 dbc,
297 database);
298
299 ensDatabaseconnectionTrace(dbc, 1);
300 }
301
302 if (!dbc)
303 return NULL;
304
305 if ((database == NULL) || (ajStrGetLen(database) == 0))
306 return NULL;
307
308 rec = ajRegCompC(ensKDatabaseadaptorRegCollection);
309 rem = ajRegCompC(ensKDatabaseadaptorRegMulti);
310 res = ajRegCompC(ensKDatabaseadaptorRegSpecies);
311
312 multi = ajStrNewC("default");
313
314 if (ajRegExec(rec, database))
315 {
316 /* Ensembl Collection databases have to be matched first. */
317
318 group = ajStrNew();
319 prefix = ajStrNew();
320 swversion = ajStrNew();
321
322 ajRegSubI(rec, 1, &prefix);
323 ajRegSubI(rec, 2, &group);
324 ajRegSubI(rec, 3, &swversion);
325
326 if (ajStrMatchCaseC(swversion, ensKSoftwareVersion))
327 {
328 if (debug)
329 ajDebug("ensDatabaseadaptorNewDatabasename matched "
330 "collection database '%S'.\n",
331 database);
332
333 dbag = ensDatabaseadaptorGroupFromStr(group);
334
335 if (dbag)
336 dba = ensDatabaseadaptorNewIni(dbc,
337 database,
338 prefix,
339 dbag,
340 ajTrue,
341 0);
342 else
343 ajDebug("ensDatabaseadaptorNewDatabasename got unexpected "
344 "group string '%S' for database name '%S'.\n",
345 group, database);
346 }
347 else
348 {
349 if (debug)
350 ajDebug("ensDatabaseadaptorNewDatabasename matched "
351 "collection database '%S', "
352 "but not the software version '%s'.\n",
353 database, ensKSoftwareVersion);
354 }
355
356 ajStrDel(&group);
357 ajStrDel(&prefix);
358 ajStrDel(&swversion);
359 }
360 else if (ajRegExec(rem, database))
361 {
362 /* Multi-species databases */
363
364 group = ajStrNew();
365 prefix = ajStrNew();
366 swversion = ajStrNew();
367
368 ajRegSubI(rem, 1, &group);
369
370 if (ajRegLenI(rem, 3))
371 {
372 ajRegSubI(rem, 2, &prefix);
373 ajRegSubI(rem, 3, &swversion);
374
375 /* Remove leading underscores from the species prefix. */
376
377 if (ajStrPrefixC(prefix, "_"))
378 ajStrCutStart(&prefix, 1);
379 }
380 else
381 ajRegSubI(rem, 2, &swversion);
382
383 if (ajStrMatchCaseC(swversion, ensKSoftwareVersion))
384 {
385 if (debug)
386 ajDebug("ensDatabaseadaptorNewDatabasename matched "
387 "multi-species database '%S'.\n",
388 database);
389
390 dbag = ensDatabaseadaptorGroupFromStr(group);
391
392 if (dbag)
393 dba = ensDatabaseadaptorNewIni(dbc,
394 database,
395 (ajStrGetLen(prefix))
396 ? prefix : multi,
397 dbag,
398 ajFalse,
399 0);
400 else
401 ajDebug("ensDatabaseadaptorNewDatabasename got unexpected "
402 "group string '%S' for database name '%S'.\n",
403 group, database);
404 }
405 else
406 {
407 if (debug)
408 ajDebug("ensDatabaseadaptorNewDatabasename matched "
409 "multi-species database '%S', "
410 "but not the software version '%s'.\n",
411 database, ensKSoftwareVersion);
412 }
413
414 ajStrDel(&group);
415 ajStrDel(&prefix);
416 ajStrDel(&swversion);
417 }
418 else if (ajRegExec(res, database))
419 {
420 /* Species-specific databases */
421
422 prefix = ajStrNew();
423 group = ajStrNew();
424 swversion = ajStrNew();
425
426 ajRegSubI(res, 1, &prefix);
427 ajRegSubI(res, 2, &group);
428 ajRegSubI(res, 3, &swversion);
429
430 if (ajStrMatchCaseC(swversion, ensKSoftwareVersion))
431 {
432 if (debug)
433 ajDebug("ensDatabaseadaptorNewDatabasename matched "
434 "species-specific database '%S'.\n",
435 database);
436
437 dbag = ensDatabaseadaptorGroupFromStr(group);
438
439 if (dbag)
440 dba = ensDatabaseadaptorNewIni(dbc,
441 database,
442 prefix,
443 dbag,
444 ajFalse,
445 0);
446 else
447 ajDebug("ensDatabaseadaptorNewDatabasename got unexpected "
448 "group string '%S' for database name '%S'.\n",
449 group, database);
450 }
451 else
452 {
453 if (debug)
454 ajDebug("ensDatabaseadaptorNewDatabasename matched "
455 "species-specific database '%S', "
456 "but not the software version '%s'.\n",
457 database, ensKSoftwareVersion);
458 }
459
460 ajStrDel(&prefix);
461 ajStrDel(&group);
462 ajStrDel(&swversion);
463 }
464 else
465 ajDebug("ensDatabaseadaptorNewDatabasename no match for "
466 "database name '%S'.\n",
467 database);
468
469 ajRegFree(&rec);
470 ajRegFree(&rem);
471 ajRegFree(&res);
472
473 ajStrDel(&multi);
474
475 return dba;
476 }
477
478
479
480
481 /* @func ensDatabaseadaptorNewIni *********************************************
482 **
483 ** Constructor for an Ensembl Database Adaptor with initial values.
484 **
485 ** If a database name has not been provided, the database name of the
486 ** Ensembl Database Connection will be used.
487 **
488 ** Ensembl Database Adaptors are singleton objects in the sense that a single
489 ** instance of an Ensembl Database Adaptor connected to a particular database
490 ** is sufficient to instantiate any number of Ensembl Object Adaptors from the
491 ** database. Each Ensembl Object Adaptor will have a weak reference to the
492 ** Ensembl Database Adaptor that instantiated it. Therefore, Ensembl Database
493 ** Adaptors should not be instantiated directly, but rather obtained from the
494 ** Ensembl Registry, which will in turn call this function if neccessary.
495 **
496 ** @see ensRegistryNewDatabaseadaptor
497 ** @see ensRegistryGetDatabaseadaptor
498 **
499 ** @cc Bio::EnsEMBL::DBSQL::DBAdaptor::new
500 ** @param [u] dbc [EnsPDatabaseconnection] Ensembl Database Connection
501 ** @param [uN] database [AjPStr] Database name
502 ** @param [u] species [AjPStr] Species
503 ** @param [u] dbag [EnsEDatabaseadaptorGroup]
504 ** Ensembl Database Adaptor Group enumeration
505 ** @param [r] multi [AjBool] Multiple species
506 ** @param [r] identifier [ajuint] Species identifier
507 **
508 ** @return [EnsPDatabaseadaptor] Ensembl Database Adaptor or NULL
509 **
510 ** @release 6.4.0
511 ** @@
512 ** NOTE: The Perl API automatically registers the Ensembl Database Adaptor in
513 ** the Ensembl Registry via Bio::EnsEMBL::Utils::ConfigRegistry::gen_load.
514 ** In this implementation both objects are kept separate. The Ensembl Registry
515 ** object provides a function, which generates an Ensembl Database Adaptor
516 ** based on the same parameter set and automatically registers it.
517 ******************************************************************************/
518
ensDatabaseadaptorNewIni(EnsPDatabaseconnection dbc,AjPStr database,AjPStr species,EnsEDatabaseadaptorGroup dbag,AjBool multi,ajuint identifier)519 EnsPDatabaseadaptor ensDatabaseadaptorNewIni(
520 EnsPDatabaseconnection dbc,
521 AjPStr database,
522 AjPStr species,
523 EnsEDatabaseadaptorGroup dbag,
524 AjBool multi,
525 ajuint identifier)
526 {
527 EnsPDatabaseadaptor dba = NULL;
528
529 if (ajDebugTest("ensDatabaseadaptorNewIni"))
530 {
531 ajDebug("ensDatabaseadaptorNewIni\n"
532 " dbc %p\n"
533 " database '%S'\n"
534 " species '%S'\n"
535 " dbag %d\n"
536 " multi '%B'\n"
537 " identifier %u\n",
538 dbc,
539 database,
540 species,
541 dbag,
542 multi,
543 identifier);
544
545 ensDatabaseconnectionTrace(dbc, 1);
546 }
547
548 if (!dbc)
549 return NULL;
550
551 if (!species)
552 return NULL;
553
554 if (!dbag)
555 return NULL;
556
557 AJNEW0(dba);
558
559 dba->Databaseconnection = ensDatabaseconnectionNewCpy(dbc, database);
560
561 if (species)
562 dba->Species = ajStrNewRef(species);
563
564 dba->Group = dbag;
565
566 dba->Multispecies = multi;
567
568 dba->Identifier = identifier;
569
570 return dba;
571 }
572
573
574
575
576 /* @func ensDatabaseadaptorNewUrl *********************************************
577 **
578 ** Constructor for an Ensembl Database Adaptor with a
579 ** Uniform Resource Locator (URL).
580 **
581 ** Ensembl Database Adaptors are singleton objects in the sense that a single
582 ** instance of an Ensembl Database Adaptor connected to a particular database
583 ** is sufficient to instantiate any number of Ensembl Object Adaptors from the
584 ** database. Each Ensembl Object Adaptor will have a weak reference to the
585 ** Ensembl Database Adaptor that instantiated it. Therefore, Ensembl Database
586 ** Adaptors should not be instantiated directly, but rather obtained from the
587 ** Ensembl Registry, which will in turn call this function if neccessary.
588 **
589 ** @see ensRegistryNewDatabaseadaptor
590 ** @see ensRegistryGetDatabaseadaptor
591 **
592 ** @param [r] url [const AjPStr] Uniform Resource Locator
593 **
594 ** @return [EnsPDatabaseadaptor] Ensembl Database Adaptor or NULL
595 **
596 ** @release 6.4.0
597 ** @@
598 ******************************************************************************/
599
ensDatabaseadaptorNewUrl(const AjPStr url)600 EnsPDatabaseadaptor ensDatabaseadaptorNewUrl(const AjPStr url)
601 {
602 EnsPDatabaseadaptor dba = NULL;
603
604 EnsPDatabaseconnection dbc = NULL;
605
606 if ((url == NULL) || (ajStrGetLen(url) == 0))
607 return NULL;
608
609 dbc = ensDatabaseconnectionNewUrl(url);
610
611 if (!dbc)
612 return NULL;
613
614 dba = ensDatabaseadaptorNewDatabasename(
615 dbc,
616 ensDatabaseconnectionGetDatabasename(dbc));
617
618 ensDatabaseconnectionDel(&dbc);
619
620 return dba;
621 }
622
623
624
625
626 /* @section destructors *******************************************************
627 **
628 ** Destruction destroys all internal data structures and frees the memory
629 ** allocated for an Ensembl Database Adaptor object.
630 **
631 ** @fdata [EnsPDatabaseadaptor]
632 **
633 ** @nam3rule Del Destroy (free) an Ensembl Database Adaptor
634 **
635 ** @argrule * Pdba [EnsPDatabaseadaptor*]
636 ** Ensembl Database Adaptor address
637 **
638 ** @valrule * [void]
639 **
640 ** @fcategory delete
641 ******************************************************************************/
642
643
644
645
646 /* @func ensDatabaseadaptorDel ************************************************
647 **
648 ** Default destructor for an Ensembl Database Adaptor.
649 **
650 ** Ensembl Database Adaptors are singleton objects that are registered in the
651 ** Ensembl Registry and weakly referenced by Ensembl Object Adaptors that have
652 ** been instantiated by it. Therefore, Ensembl Database Adaptors should never
653 ** be destroyed directly. Upon exit, the Ensembl Registry will call this
654 ** function if required.
655 **
656 ** @see ensExit
657 ** @see ensRegistryExit
658 **
659 ** @param [d] Pdba [EnsPDatabaseadaptor*] Ensembl Database Adaptor address
660 **
661 ** @return [void]
662 **
663 ** @release 6.2.0
664 ** @@
665 ** NOTE: The Perl API removes the Ensembl Database Adaptor from the
666 ** Ensembl Registry via Bio::EnsEMBL::Registry::remove_db.
667 ** This implementation keeps both objects independent and Ensembl Database
668 ** Adaptors are deleted from the Ensembl Registry.
669 ******************************************************************************/
670
ensDatabaseadaptorDel(EnsPDatabaseadaptor * Pdba)671 void ensDatabaseadaptorDel(EnsPDatabaseadaptor *Pdba)
672 {
673 EnsPDatabaseadaptor pthis = NULL;
674
675 if (!Pdba)
676 return;
677
678 #if defined(AJ_DEBUG) && AJ_DEBUG >= 1
679 if (ajDebugTest("ensDatabaseadaptorDel"))
680 {
681 ajDebug("ensDatabaseadaptorDel\n"
682 " *Pdba %p\n",
683 *Pdba);
684
685 ensDatabaseadaptorTrace(*Pdba, 1);
686 }
687 #endif /* defined(AJ_DEBUG) && AJ_DEBUG >= 1 */
688
689 if (!(pthis = *Pdba))
690 return;
691
692 ensDatabaseconnectionDel(&pthis->Databaseconnection);
693
694 ajStrDel(&pthis->Species);
695
696 ajListstrFreeData(&pthis->SpeciesNames);
697
698 ajMemFree((void **) Pdba);
699
700 return;
701 }
702
703
704
705
706 /* @section member retrieval **************************************************
707 **
708 ** Functions for returning members of an Ensembl Database Adaptor object.
709 **
710 ** @fdata [EnsPDatabaseadaptor]
711 **
712 ** @nam3rule Get Return Ensembl Database Adaptor attribute(s)
713 ** @nam4rule Databaseconnection Return the Ensembl Database Connection
714 ** @nam4rule Group Return the Ensembl Database Adaptor Group enumeration
715 ** @nam4rule Identifier Return the species identifier
716 ** @nam4rule Multispecies Return the multi-species flag
717 ** @nam4rule Species Return the species
718 **
719 ** @argrule * dba [const EnsPDatabaseadaptor] Ensembl Database Adaptor
720 **
721 ** @valrule Databaseconnection [EnsPDatabaseconnection]
722 ** Ensembl Database Connection or NULL
723 ** @valrule Species [AjPStr] Species or NULL
724 ** @valrule Group [EnsEDatabaseadaptorGroup]
725 ** Ensembl Database Adaptor Group enumeration or ensEDatabaseadaptorGroupNULL
726 ** @valrule Multispecies [AjBool] Multiple species or ajFalse
727 ** @valrule Identifier [ajuint] Species identifier or 0U
728 **
729 ** @fcategory use
730 ******************************************************************************/
731
732
733
734
735 /* @func ensDatabaseadaptorGetDatabaseconnection ******************************
736 **
737 ** Get the Ensembl Database Connection member of an Ensembl Database Adaptor.
738 **
739 ** @cc Bio::EnsEMBL::DBSQL::DBAdaptor::dbc
740 ** @param [r] dba [const EnsPDatabaseadaptor] Ensembl Database Adaptor
741 **
742 ** @return [EnsPDatabaseconnection] Ensembl Database Connection or NULL
743 **
744 ** @release 6.2.0
745 ** @@
746 ******************************************************************************/
747
ensDatabaseadaptorGetDatabaseconnection(const EnsPDatabaseadaptor dba)748 EnsPDatabaseconnection ensDatabaseadaptorGetDatabaseconnection(
749 const EnsPDatabaseadaptor dba)
750 {
751 return (dba) ? dba->Databaseconnection : NULL;
752 }
753
754
755
756
757 /* @func ensDatabaseadaptorGetGroup *******************************************
758 **
759 ** Get the group member of an Ensembl Database Adaptor.
760 **
761 ** @cc Bio::EnsEMBL::DBSQL::DBAdaptor::group
762 ** @param [r] dba [const EnsPDatabaseadaptor] Ensembl Database Adaptor
763 **
764 ** @return [EnsEDatabaseadaptorGroup]
765 ** Ensembl Database Adaptor Group enumeration or ensEDatabaseadaptorGroupNULL
766 **
767 ** @release 6.2.0
768 ** @@
769 ******************************************************************************/
770
ensDatabaseadaptorGetGroup(const EnsPDatabaseadaptor dba)771 EnsEDatabaseadaptorGroup ensDatabaseadaptorGetGroup(
772 const EnsPDatabaseadaptor dba)
773 {
774 return (dba) ? dba->Group : ensEDatabaseadaptorGroupNULL;
775 }
776
777
778
779
780 /* @func ensDatabaseadaptorGetIdentifier **************************************
781 **
782 ** Get the species identifier member of an Ensembl Database Adaptor.
783 **
784 ** @cc Bio::EnsEMBL::DBSQL::DBAdaptor::species_id
785 ** @param [r] dba [const EnsPDatabaseadaptor] Ensembl Database Adaptor
786 **
787 ** @return [ajuint] Species identifier or 0U, defaults to 1U
788 **
789 ** @release 6.2.0
790 ** @@
791 ******************************************************************************/
792
ensDatabaseadaptorGetIdentifier(const EnsPDatabaseadaptor dba)793 ajuint ensDatabaseadaptorGetIdentifier(
794 const EnsPDatabaseadaptor dba)
795 {
796 return (dba) ? ((dba->Identifier) ? dba->Identifier : 1U) : 0U;
797 }
798
799
800
801
802 /* @func ensDatabaseadaptorGetMultispecies ************************************
803 **
804 ** Get the multi-species member of an Ensembl Database Adaptor.
805 **
806 ** @cc Bio::EnsEMBL::DBSQL::DBAdaptor::is_multispecies
807 ** @param [r] dba [const EnsPDatabaseadaptor] Ensembl Database Adaptor
808 **
809 ** @return [AjBool] ajTrue if the database contains multiple species
810 **
811 ** @release 6.4.0
812 ** @@
813 ******************************************************************************/
814
ensDatabaseadaptorGetMultispecies(const EnsPDatabaseadaptor dba)815 AjBool ensDatabaseadaptorGetMultispecies(
816 const EnsPDatabaseadaptor dba)
817 {
818 return (dba) ? dba->Multispecies : ajFalse;
819 }
820
821
822
823
824 /* @func ensDatabaseadaptorGetSpecies *****************************************
825 **
826 ** Get the species member of an Ensembl Database Adaptor.
827 **
828 ** @cc Bio::EnsEMBL::DBSQL::DBAdaptor::species
829 ** @param [r] dba [const EnsPDatabaseadaptor] Ensembl Database Adaptor
830 **
831 ** @return [AjPStr] Species or NULL
832 **
833 ** @release 6.2.0
834 ** @@
835 ******************************************************************************/
836
ensDatabaseadaptorGetSpecies(const EnsPDatabaseadaptor dba)837 AjPStr ensDatabaseadaptorGetSpecies(
838 const EnsPDatabaseadaptor dba)
839 {
840 return (dba) ? dba->Species : NULL;
841 }
842
843
844
845
846 /* @section load on demand ****************************************************
847 **
848 ** Functions for returning members of an Ensembl Database Adaptor object,
849 ** which may need loading from an Ensembl SQL database on demand.
850 **
851 ** @fdata [EnsPDatabaseadaptor]
852 **
853 ** @nam3rule Load Return Ensembl Database Adaptor attribute(s)
854 ** loaded on demand
855 ** @nam4rule Speciesnames Return all species names
856 **
857 ** @argrule * dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
858 **
859 ** @valrule Speciesnames [const AjPList]
860 ** AJAX List of AJAX String (species name) objects or NULL
861 **
862 ** @fcategory use
863 ******************************************************************************/
864
865
866
867
868 /* @func ensDatabaseadaptorLoadSpeciesnames ***********************************
869 **
870 ** Load all species name objects of an Ensembl Database Adaptor.
871 **
872 ** This is not a simple accessor function, it will fetch species name
873 ** objects from the Ensembl SQL database in case the AJAX List is not defined.
874 **
875 ** @param [u] dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
876 **
877 ** @return [const AjPList]
878 ** AJAX List of AJAX String (species name) objects or NULL
879 **
880 ** @release 6.5.0
881 ** @@
882 ******************************************************************************/
883
ensDatabaseadaptorLoadSpeciesnames(EnsPDatabaseadaptor dba)884 const AjPList ensDatabaseadaptorLoadSpeciesnames(EnsPDatabaseadaptor dba)
885 {
886 if (!dba)
887 return NULL;
888
889 if (dba->SpeciesNames)
890 return dba->SpeciesNames;
891 else
892 dba->SpeciesNames = ajListstrNew();
893
894 if (dba->Multispecies)
895 ensMetainformationadaptorRetrieveAllSpeciesnames(
896 ensRegistryGetMetainformationadaptor(dba),
897 dba->SpeciesNames);
898 else
899 ajListPushAppend(dba->SpeciesNames, (void *) ajStrNewS(dba->Species));
900
901 return dba->SpeciesNames;
902 }
903
904
905
906
907 /* @section member assignment *************************************************
908 **
909 ** Functions for assigning members of an Ensembl Database Adaptor object.
910 **
911 ** @fdata [EnsPDatabaseadaptor]
912 **
913 ** @nam3rule Set Set one member of an Ensembl Database Adaptor
914 ** @nam4rule Databaseconnection Set the Ensembl Database Connection
915 ** @nam4rule Group Set the group
916 ** @nam4rule Identifier Set the species identifier
917 ** @nam4rule Multispecies Set the multiple-species flag
918 ** @nam4rule Species Set the species
919 **
920 ** @argrule * dba [EnsPDatabaseadaptor] Ensembl Database Adaptor object
921 ** @argrule Databaseconnection dbc [EnsPDatabaseconnection]
922 ** Ensembl Database Connection
923 ** @argrule Group dbag [EnsEDatabaseadaptorGroup]
924 ** Ensembl Database Adaptor Group enumeration
925 ** @argrule Identifier identifier [ajuint] Species identifier
926 ** @argrule Multispecies multi [AjBool] Multi-species attribute
927 ** @argrule Species species [AjPStr] Species
928 **
929 ** @valrule * [AjBool] ajTrue upon success, ajFalse otherwise
930 **
931 ** @fcategory modify
932 ******************************************************************************/
933
934
935
936
937 /* @func ensDatabaseadaptorSetDatabaseconnection ******************************
938 **
939 ** Set the Ensembl Database Connection member of an Ensembl Database Adaptor.
940 **
941 ** @cc Bio::EnsEMBL::DBSQL::DBAdaptor::dbc
942 ** @param [u] dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
943 ** @param [u] dbc [EnsPDatabaseconnection] Ensembl Database Connection
944 **
945 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
946 **
947 ** @release 6.2.0
948 ** @@
949 ******************************************************************************/
950
ensDatabaseadaptorSetDatabaseconnection(EnsPDatabaseadaptor dba,EnsPDatabaseconnection dbc)951 AjBool ensDatabaseadaptorSetDatabaseconnection(EnsPDatabaseadaptor dba,
952 EnsPDatabaseconnection dbc)
953 {
954 if (!dba)
955 return ajFalse;
956
957 ensDatabaseconnectionDel(&dba->Databaseconnection);
958
959 dba->Databaseconnection = ensDatabaseconnectionNewRef(dbc);
960
961 return ajTrue;
962 }
963
964
965
966
967 /* @func ensDatabaseadaptorSetGroup *******************************************
968 **
969 ** Set the group member of an Ensembl Database Adaptor.
970 **
971 ** @cc Bio::EnsEMBL::DBSQL::DBAdaptor::group
972 ** @param [u] dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
973 ** @param [u] dbag [EnsEDatabaseadaptorGroup]
974 ** Ensembl Database Adaptor Group enumeration
975 **
976 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
977 **
978 ** @release 6.2.0
979 ** @@
980 ******************************************************************************/
981
ensDatabaseadaptorSetGroup(EnsPDatabaseadaptor dba,EnsEDatabaseadaptorGroup dbag)982 AjBool ensDatabaseadaptorSetGroup(EnsPDatabaseadaptor dba,
983 EnsEDatabaseadaptorGroup dbag)
984 {
985 if (!dba)
986 return ajFalse;
987
988 dba->Group = dbag;
989
990 return ajTrue;
991 }
992
993
994
995
996 /* @func ensDatabaseadaptorSetIdentifier **************************************
997 **
998 ** Set the species identifier member of an Ensembl Database Adaptor.
999 **
1000 ** @cc Bio::EnsEMBL::DBSQL::DBAdaptor::species_id
1001 ** @param [u] dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
1002 ** @param [r] identifier [ajuint] Species identifier
1003 **
1004 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1005 **
1006 ** @release 6.2.0
1007 ** @@
1008 ******************************************************************************/
1009
ensDatabaseadaptorSetIdentifier(EnsPDatabaseadaptor dba,ajuint identifier)1010 AjBool ensDatabaseadaptorSetIdentifier(EnsPDatabaseadaptor dba,
1011 ajuint identifier)
1012 {
1013 if (!dba)
1014 return ajFalse;
1015
1016 dba->Identifier = identifier;
1017
1018 return ajTrue;
1019 }
1020
1021
1022
1023
1024 /* @func ensDatabaseadaptorSetMultispecies ************************************
1025 **
1026 ** Set the multi-species member of an Ensembl Database Adaptor.
1027 **
1028 ** @cc Bio::EnsEMBL::DBSQL::DBAdaptor::is_multispecies
1029 ** @param [u] dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
1030 ** @param [r] multi [AjBool] Multi-species attribute
1031 **
1032 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1033 **
1034 ** @release 6.4.0
1035 ** @@
1036 ******************************************************************************/
1037
ensDatabaseadaptorSetMultispecies(EnsPDatabaseadaptor dba,AjBool multi)1038 AjBool ensDatabaseadaptorSetMultispecies(EnsPDatabaseadaptor dba,
1039 AjBool multi)
1040 {
1041 if (!dba)
1042 return ajFalse;
1043
1044 dba->Multispecies = multi;
1045
1046 return ajTrue;
1047 }
1048
1049
1050
1051
1052 /* @func ensDatabaseadaptorSetSpecies *****************************************
1053 **
1054 ** Set the species member of an Ensembl Database Adaptor.
1055 **
1056 ** @cc Bio::EnsEMBL::DBSQL::DBAdaptor::species
1057 ** @param [u] dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
1058 ** @param [u] species [AjPStr] Species
1059 **
1060 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1061 **
1062 ** @release 6.2.0
1063 ** @@
1064 ******************************************************************************/
1065
ensDatabaseadaptorSetSpecies(EnsPDatabaseadaptor dba,AjPStr species)1066 AjBool ensDatabaseadaptorSetSpecies(EnsPDatabaseadaptor dba, AjPStr species)
1067 {
1068 if (!dba)
1069 return ajFalse;
1070
1071 ajStrDel(&dba->Species);
1072
1073 if (species)
1074 dba->Species = ajStrNewRef(species);
1075
1076 return ajTrue;
1077 }
1078
1079
1080
1081
1082 /* @section debugging *********************************************************
1083 **
1084 ** Functions for reporting of an Ensembl Database Adaptor object.
1085 **
1086 ** @fdata [EnsPDatabaseadaptor]
1087 **
1088 ** @nam3rule Trace Report Ensembl Database Adaptor members to debug file
1089 **
1090 ** @argrule Trace dba [const EnsPDatabaseadaptor] Ensembl Database Adaptor
1091 ** @argrule Trace level [ajuint] Indentation level
1092 **
1093 ** @valrule * [AjBool] ajTrue upon success, ajFalse otherwise
1094 **
1095 ** @fcategory misc
1096 ******************************************************************************/
1097
1098
1099
1100
1101 /* @func ensDatabaseadaptorTrace **********************************************
1102 **
1103 ** Trace an Ensembl Database Adaptor.
1104 **
1105 ** @param [r] dba [const EnsPDatabaseadaptor] Ensembl Database Adaptor
1106 ** @param [r] level [ajuint] Indentation level
1107 **
1108 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1109 **
1110 ** @release 6.2.0
1111 ** @@
1112 ******************************************************************************/
1113
ensDatabaseadaptorTrace(const EnsPDatabaseadaptor dba,ajuint level)1114 AjBool ensDatabaseadaptorTrace(const EnsPDatabaseadaptor dba, ajuint level)
1115 {
1116 AjIList iter = NULL;
1117
1118 AjPStr indent = NULL;
1119 AjPStr name = NULL;
1120
1121 if (!dba)
1122 return ajFalse;
1123
1124 indent = ajStrNew();
1125
1126 ajStrAppendCountK(&indent, ' ', level * 2);
1127
1128 ajDebug("%SensDatabaseadaptorTrace %p\n"
1129 "%S Databaseconnection %p\n"
1130 "%S Species '%S'\n"
1131 "%S SpeciesNames %p\n"
1132 "%S Group '%s'\n"
1133 "%S Multispecies '%B'\n"
1134 "%S Identifier %u\n",
1135 indent, dba,
1136 indent, dba->Databaseconnection,
1137 indent, dba->Species,
1138 indent, dba->SpeciesNames,
1139 indent, ensDatabaseadaptorGroupToChar(dba->Group),
1140 indent, dba->Multispecies,
1141 indent, dba->Identifier);
1142
1143 ensDatabaseconnectionTrace(dba->Databaseconnection, level + 1);
1144
1145 /* Trace the AJAX List of AJAX String (species name) objects. */
1146
1147 if (dba->SpeciesNames)
1148 {
1149 ajDebug("%S AJAX List %p of AJAX String (species name) objects:\n",
1150 indent, dba->SpeciesNames);
1151
1152 iter = ajListIterNewread(dba->SpeciesNames);
1153
1154 while (!ajListIterDone(iter))
1155 {
1156 name = (AjPStr) ajListIterGet(iter);
1157
1158 ajDebug("%S %S\n", indent, name);
1159 }
1160
1161 ajListIterDel(&iter);
1162 }
1163
1164 ajStrDel(&indent);
1165
1166 return ajTrue;
1167 }
1168
1169
1170
1171
1172 /* @section comparison ********************************************************
1173 **
1174 ** Functions for comparing Ensembl Database Adaptor objects.
1175 **
1176 ** @fdata [EnsPDatabaseadaptor]
1177 **
1178 ** @nam3rule Match Compare two Ensembl Database Adaptor objects
1179 ** @nam3rule Matchcomponents Match components of an Ensembl Database Adaptor
1180 **
1181 ** @argrule Match dba1 [const EnsPDatabaseadaptor] Ensembl Database Adaptor
1182 ** @argrule Match dba2 [const EnsPDatabaseadaptor] Ensembl Database Adaptor
1183 ** @argrule Matchcomponents dba [const EnsPDatabaseadaptor]
1184 ** Ensembl Database Adaptor
1185 ** @argrule Matchcomponents dbc [const EnsPDatabaseconnection]
1186 ** Ensembl Database Connection
1187 ** @argrule Matchcomponents species [const AjPStr] Species
1188 ** @argrule Matchcomponents dbag [EnsEDatabaseadaptorGroup]
1189 ** Ensembl Database Adaptor Group enumeration
1190 ** @argrule Matchcomponents multi [AjBool] Multiple species
1191 ** @argrule Matchcomponents identifier [ajuint] Species identifier
1192 **
1193 ** @valrule * [AjBool] True on success
1194 **
1195 ** @fcategory use
1196 ******************************************************************************/
1197
1198
1199
1200
1201 /* @func ensDatabaseadaptorMatch **********************************************
1202 **
1203 ** Tests for matching two Ensembl Database Adaptors.
1204 **
1205 ** @param [r] dba1 [const EnsPDatabaseadaptor] First Ensembl Database Adaptor
1206 ** @param [r] dba2 [const EnsPDatabaseadaptor] Second Ensembl Database Adaptor
1207 **
1208 ** @return [AjBool] ajTrue if the Ensembl Database Adaptors are equal
1209 **
1210 ** @release 6.2.0
1211 ** @@
1212 ** The comparison is based on initial pointer equality and if that fails a
1213 ** comparison of the group member, the species identifier and a
1214 ** case-insensitive string comparison of the species member.
1215 ******************************************************************************/
1216
ensDatabaseadaptorMatch(const EnsPDatabaseadaptor dba1,const EnsPDatabaseadaptor dba2)1217 AjBool ensDatabaseadaptorMatch(const EnsPDatabaseadaptor dba1,
1218 const EnsPDatabaseadaptor dba2)
1219 {
1220 if (!dba1)
1221 return ajFalse;
1222
1223 if (!dba2)
1224 return ajFalse;
1225
1226 if (dba1 == dba2)
1227 return ajTrue;
1228
1229 if (!ensDatabaseconnectionMatch(dba1->Databaseconnection,
1230 dba2->Databaseconnection))
1231 return ajFalse;
1232
1233 if (dba1->Group != dba2->Group)
1234 return ajFalse;
1235
1236 if (dba1->Multispecies != dba2->Multispecies)
1237 return ajFalse;
1238
1239 if (dba1->Identifier != dba2->Identifier)
1240 return ajFalse;
1241
1242 if (!ajStrMatchCaseS(dba1->Species, dba2->Species))
1243 return ajFalse;
1244
1245 return ajTrue;
1246 }
1247
1248
1249
1250
1251 /* @func ensDatabaseadaptorMatchcomponents ************************************
1252 **
1253 ** Tests whether an Ensembl Database Adaptor matches component members.
1254 **
1255 ** @param [r] dba [const EnsPDatabaseadaptor] Ensembl Database Adaptor
1256 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
1257 ** @param [r] species [const AjPStr] Species
1258 ** @param [u] dbag [EnsEDatabaseadaptorGroup]
1259 ** Ensembl Database Adaptor Group enumeration
1260 ** @param [r] multi [AjBool] Multiple species
1261 ** @param [r] identifier [ajuint] Species identifier
1262 **
1263 ** @return [AjBool] ajTrue if all members match
1264 **
1265 ** @release 6.4.0
1266 ** @@
1267 ******************************************************************************/
1268
ensDatabaseadaptorMatchcomponents(const EnsPDatabaseadaptor dba,const EnsPDatabaseconnection dbc,const AjPStr species,EnsEDatabaseadaptorGroup dbag,AjBool multi,ajuint identifier)1269 AjBool ensDatabaseadaptorMatchcomponents(const EnsPDatabaseadaptor dba,
1270 const EnsPDatabaseconnection dbc,
1271 const AjPStr species,
1272 EnsEDatabaseadaptorGroup dbag,
1273 AjBool multi,
1274 ajuint identifier)
1275 {
1276 if (!dba)
1277 return ajFalse;
1278
1279 if (!dbc)
1280 return ajFalse;
1281
1282 if (!species)
1283 return ajFalse;
1284
1285 if (!dbag)
1286 return ajFalse;
1287
1288 if (dba->Group != dbag)
1289 return ajFalse;
1290
1291 if (dba->Multispecies != multi)
1292 return ajFalse;
1293
1294 if (dba->Identifier != identifier)
1295 return ajFalse;
1296
1297 if (!ensDatabaseconnectionMatch(dba->Databaseconnection, dbc))
1298 return ajFalse;
1299
1300 if (!ajStrMatchCaseS(dba->Species, species))
1301 return ajFalse;
1302
1303 return ajTrue;
1304 }
1305
1306
1307
1308
1309 /* @section convenience functions *********************************************
1310 **
1311 ** Ensembl Database Adaptor convenience functions
1312 **
1313 ** @fdata [EnsPDatabaseadaptor]
1314 **
1315 ** @nam3rule Disconnect Disconnect the underlying Ensembl Database Connection
1316 ** @nam3rule Escape Escape a string
1317 ** @nam4rule C Escape to an AJAX String
1318 ** @nam4rule S Escape to a C-type character string
1319 ** @nam3rule Sqlstatement AJAX SQL Statement
1320 ** @nam4rule Del Delete an AJAX SQL Statement
1321 ** @nam4rule New Run a new AJAX SQL statement
1322 **
1323 ** @argrule * dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
1324 ** @argrule EscapeC Ptxt [char**] Address of the (new) SQL-escaped C string
1325 ** @argrule EscapeC str [const AjPStr] AJAX String to be escaped
1326 ** @argrule EscapeS Pstr [AjPStr*] Address of the (new) SQL-escaped AJAX String
1327 ** @argrule EscapeS str [const AjPStr] AJAX String to be escaped
1328 ** @argrule SqlstatementDel Psqls [AjPSqlstatement*] AJAX SQL Statement address
1329 ** @argrule SqlstatementNew statement [const AjPStr] SQL statement
1330 **
1331 ** @valrule Disconnect [AjBool] ajTrue upon success, ajFalse otherwise
1332 ** @valrule EscapeC [AjBool] ajTrue upon success, ajFalse otherwise
1333 ** @valrule EscapeS [AjBool] ajTrue upon success, ajFalse otherwise
1334 ** @valrule Speciesnames [const AjPList] AJAX List of
1335 ** AJAX String (species name) objects
1336 ** @valrule SqlstatementDel [AjBool] ajTrue upon success, ajFalse otherwise
1337 ** @valrule SqlstatementNew [AjPSqlstatement] AJAX SQL Statement
1338 **
1339 ** @fcategory use
1340 ******************************************************************************/
1341
1342
1343
1344
1345 /* @func ensDatabaseadaptorDisconnect *****************************************
1346 **
1347 ** Disconnect the Ensembl Database Connection this Ensembl Database Adaptor
1348 ** is based on.
1349 **
1350 ** @param [u] dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
1351 **
1352 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1353 **
1354 ** @release 6.3.0
1355 ** @@
1356 ******************************************************************************/
1357
ensDatabaseadaptorDisconnect(EnsPDatabaseadaptor dba)1358 AjBool ensDatabaseadaptorDisconnect(EnsPDatabaseadaptor dba)
1359 {
1360 if (!dba)
1361 return ajFalse;
1362
1363 return ensDatabaseconnectionDisconnect(dba->Databaseconnection);
1364 }
1365
1366
1367
1368
1369 /* @func ensDatabaseadaptorEscapeC ********************************************
1370 **
1371 ** Escape special characters in an AJAX String for use in an SQL statement,
1372 ** taking into account the current character set of the AJAX SQL Connection
1373 ** and return a C-type character string.
1374 **
1375 ** The caller is responsible for deleting the escaped C-type character string.
1376 **
1377 ** @param [u] dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
1378 ** @param [wP] Ptxt [char**] Address of the (new) SQL-escaped C string
1379 ** @param [r] str [const AjPStr] AJAX String to be escaped
1380 **
1381 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1382 **
1383 ** @release 6.2.0
1384 ** @@
1385 ******************************************************************************/
1386
ensDatabaseadaptorEscapeC(EnsPDatabaseadaptor dba,char ** Ptxt,const AjPStr str)1387 AjBool ensDatabaseadaptorEscapeC(EnsPDatabaseadaptor dba,
1388 char **Ptxt,
1389 const AjPStr str)
1390 {
1391 if (!dba)
1392 return ajFalse;
1393
1394 if (!Ptxt)
1395 return ajFalse;
1396
1397 if (!str)
1398 return ajFalse;
1399
1400 if (ajDebugTest("ensDatabaseadaptorEscapeC"))
1401 {
1402 ajDebug("ensDatabaseadaptorEscapeC\n"
1403 " dba %p\n"
1404 " Ptxt %p\n"
1405 " str '%S'\n",
1406 dba,
1407 Ptxt,
1408 str);
1409
1410 ensDatabaseadaptorTrace(dba, 1);
1411 }
1412
1413 return ensDatabaseconnectionEscapeC(dba->Databaseconnection, Ptxt, str);
1414 }
1415
1416
1417
1418
1419 /* @func ensDatabaseadaptorEscapeS ********************************************
1420 **
1421 ** Escape special characters in an AJAX String for use in an SQL statement,
1422 ** taking into account the current character set of the AJAX SQL Connection
1423 ** and return an AJAX String.
1424 **
1425 ** The caller is responsible for deleting the escaped AJAX String.
1426 **
1427 ** @param [u] dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
1428 ** @param [wP] Pstr [AjPStr*] Address of the (new) SQL-escaped AJAX String
1429 ** @param [r] str [const AjPStr] AJAX String to be escaped
1430 **
1431 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1432 **
1433 ** @release 6.2.0
1434 ** @@
1435 ******************************************************************************/
1436
ensDatabaseadaptorEscapeS(EnsPDatabaseadaptor dba,AjPStr * Pstr,const AjPStr str)1437 AjBool ensDatabaseadaptorEscapeS(EnsPDatabaseadaptor dba,
1438 AjPStr *Pstr,
1439 const AjPStr str)
1440 {
1441 if (!dba)
1442 return ajFalse;
1443
1444 if (!Pstr)
1445 return ajFalse;
1446
1447 if (!str)
1448 return ajFalse;
1449
1450 if (ajDebugTest("ensDatabaseadaptorEscapeS"))
1451 {
1452 ajDebug("ensDatabaseadaptorEscapeS\n"
1453 " dba %p\n"
1454 " Pstr %p\n"
1455 " str '%S'\n",
1456 dba,
1457 Pstr,
1458 str);
1459
1460 ensDatabaseadaptorTrace(dba, 1);
1461 }
1462
1463 return ensDatabaseconnectionEscapeS(dba->Databaseconnection, Pstr, str);
1464 }
1465
1466
1467
1468
1469 /* @func ensDatabaseadaptorSqlstatementDel ************************************
1470 **
1471 ** Delete an AJAX SQL Statement associated with an
1472 ** Ensembl Database Adaptor.
1473 **
1474 ** @param [u] dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
1475 ** @param [d] Psqls [AjPSqlstatement*] AJAX SQL Statement address
1476 **
1477 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1478 **
1479 ** @release 6.3.0
1480 ** @@
1481 ******************************************************************************/
1482
ensDatabaseadaptorSqlstatementDel(EnsPDatabaseadaptor dba,AjPSqlstatement * Psqls)1483 AjBool ensDatabaseadaptorSqlstatementDel(EnsPDatabaseadaptor dba,
1484 AjPSqlstatement *Psqls)
1485 {
1486 if (!dba)
1487 return ajFalse;
1488
1489 if (!Psqls)
1490 return ajFalse;
1491
1492 if (ajDebugTest("ensDatabaseadaptorSqlstatementDel"))
1493 ajDebug("ensDatabaseadaptorSqlstatementDel\n"
1494 " dba %p\n"
1495 " PSqls %p\n",
1496 dba,
1497 Psqls);
1498
1499 return ensDatabaseconnectionSqlstatementDel(dba->Databaseconnection,
1500 Psqls);
1501 }
1502
1503
1504
1505
1506 /* @func ensDatabaseadaptorSqlstatementNew ************************************
1507 **
1508 ** Constructor for an AJAX SQL statement via an Ensembl Database Adaptor.
1509 **
1510 ** @param [u] dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
1511 ** @param [r] statement [const AjPStr] SQL statement
1512 **
1513 ** @return [AjPSqlstatement] AJAX SQL Statement or NULL
1514 **
1515 ** @release 6.2.0
1516 ** @@
1517 ******************************************************************************/
1518
ensDatabaseadaptorSqlstatementNew(EnsPDatabaseadaptor dba,const AjPStr statement)1519 AjPSqlstatement ensDatabaseadaptorSqlstatementNew(EnsPDatabaseadaptor dba,
1520 const AjPStr statement)
1521 {
1522 if (!dba)
1523 return NULL;
1524
1525 if (!statement)
1526 return NULL;
1527
1528 return ensDatabaseconnectionSqlstatementNew(dba->Databaseconnection,
1529 statement);
1530 }
1531
1532
1533
1534
1535 /* @section fetch *************************************************************
1536 **
1537 ** Functions for fetching objects of an Ensembl Database Adaptor object.
1538 **
1539 ** @fdata [EnsPDatabaseadaptor]
1540 **
1541 ** @nam3rule Fetch Fetch Ensembl Database Adaptor-related objects
1542 ** @nam4rule All Fetch all objects
1543 ** @nam4rule Schemabuild Fetch the schema build
1544 **
1545 ** @argrule Schemabuild dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
1546 ** @argrule Schemabuild Pbuild [AjPStr*] Schema build
1547 **
1548 ** @valrule * [AjBool] ajTrue upon success, ajFalse otherwise
1549 **
1550 ** @fcategory misc
1551 ******************************************************************************/
1552
1553
1554
1555
1556 /* @func ensDatabaseadaptorFetchSchemabuild ***********************************
1557 **
1558 ** Fetch the schema build of an Ensembl database, which is the software version
1559 ** and the data version separated by an underscore.
1560 ** So for database homo_sapiens_core_50_36l the schema build would be 50_36l.
1561 ** The caller is responsible for deleting the AJAX String.
1562 **
1563 ** @param [u] dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
1564 ** @param [u] Pbuild [AjPStr*] Schema build
1565 **
1566 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1567 **
1568 ** @release 6.4.0
1569 ** @@
1570 ******************************************************************************/
1571
ensDatabaseadaptorFetchSchemabuild(EnsPDatabaseadaptor dba,AjPStr * Pbuild)1572 AjBool ensDatabaseadaptorFetchSchemabuild(EnsPDatabaseadaptor dba,
1573 AjPStr *Pbuild)
1574 {
1575 register ajuint i = 0U;
1576 ajuint tokens = 0U;
1577
1578 AjPStr database = NULL;
1579 AjPStr temp = NULL;
1580 AjPStrTok token = NULL;
1581
1582 if (!dba)
1583 return ajFalse;
1584
1585 if (!Pbuild)
1586 return ajFalse;
1587
1588 if (*Pbuild)
1589 ajStrAssignClear(Pbuild);
1590 else
1591 *Pbuild = ajStrNew();
1592
1593 database = ensDatabaseconnectionGetDatabasename(dba->Databaseconnection);
1594
1595 tokens = ajStrParseCountC(database, "_");
1596
1597 if (tokens < 2U)
1598 return ajFalse;
1599
1600 token = ajStrTokenNewC(database, "_");
1601
1602 /* Parse all string tokens but the last two. */
1603
1604 temp = ajStrNew();
1605
1606 for (i = 0U; i < (tokens - 2U); i++)
1607 ajStrTokenNextParse(token, &temp);
1608
1609 ajStrDel(&temp);
1610
1611 ajStrTokenRestParse(token, Pbuild);
1612
1613 ajStrTokenDel(&token);
1614
1615 return ajTrue;
1616 }
1617
1618
1619
1620
1621 /* @datasection [EnsEDatabaseadaptorGroup] Ensembl Database Adaptor Group *****
1622 **
1623 ** @nam2rule Databaseadaptor Functions for manipulating
1624 ** Ensembl Database Adaptor objects
1625 ** @nam3rule DatabaseadaptorGroup Functions for manipulating
1626 ** Ensembl Database Adaptor Group enumerations
1627 **
1628 ******************************************************************************/
1629
1630
1631
1632
1633 /* @section Misc **************************************************************
1634 **
1635 ** Functions for returning an Ensembl Database Adaptor Group enumeration.
1636 **
1637 ** @fdata [EnsEDatabaseadaptorGroup]
1638 **
1639 ** @nam4rule From Ensembl Database Adaptor Group query
1640 ** @nam5rule Str AJAX String object query
1641 **
1642 ** @argrule Str group [const AjPStr] Group string
1643 **
1644 ** @valrule * [EnsEDatabaseadaptorGroup]
1645 ** Ensembl Database Adaptor Group enumeration or ensEDatabaseadaptorGroupNULL
1646 **
1647 ** @fcategory misc
1648 ******************************************************************************/
1649
1650
1651
1652
1653 /* @func ensDatabaseadaptorGroupFromStr ***************************************
1654 **
1655 ** Convert an AJAX String into an Ensembl Database Adaptor Group enumeration.
1656 **
1657 ** @param [r] group [const AjPStr] Group string
1658 **
1659 ** @return [EnsEDatabaseadaptorGroup]
1660 ** Ensembl Database Adaptor Group enumeration or ensEDatabaseadaptorGroupNULL
1661 **
1662 ** @release 6.2.0
1663 ** @@
1664 ******************************************************************************/
1665
ensDatabaseadaptorGroupFromStr(const AjPStr group)1666 EnsEDatabaseadaptorGroup ensDatabaseadaptorGroupFromStr(const AjPStr group)
1667 {
1668 register EnsEDatabaseadaptorGroup i = ensEDatabaseadaptorGroupNULL;
1669
1670 EnsEDatabaseadaptorGroup dbag = ensEDatabaseadaptorGroupNULL;
1671
1672 for (i = ensEDatabaseadaptorGroupNULL;
1673 databaseadaptorKGroup[i];
1674 i++)
1675 if (ajStrMatchCaseC(group, databaseadaptorKGroup[i]))
1676 dbag = i;
1677
1678 if (!dbag)
1679 ajDebug("ensDatabaseadaptorGroupFromStr encountered "
1680 "unexpected string '%S'.\n", group);
1681
1682 return dbag;
1683 }
1684
1685
1686
1687
1688 /* @section Cast **************************************************************
1689 **
1690 ** Functions for returning attributes of an
1691 ** Ensembl Database Adaptor Group enumeration.
1692 **
1693 ** @fdata [EnsEDatabaseadaptorGroup]
1694 **
1695 ** @nam4rule To Return Ensembl Database Adaptor Group enumeration
1696 ** @nam5rule Char Return C character string value
1697 **
1698 ** @argrule To dbag [EnsEDatabaseadaptorGroup]
1699 ** Ensembl Database Adaptor Group enumeration
1700 **
1701 ** @valrule Char [const char*]
1702 ** Ensembl Database Adaptor Group C-type (char *) string
1703 **
1704 ** @fcategory cast
1705 ******************************************************************************/
1706
1707
1708
1709
1710 /* @func ensDatabaseadaptorGroupToChar ****************************************
1711 **
1712 ** Convert an Ensembl Database Adaptor Group enumeration into a
1713 ** C-type (char *) string.
1714 **
1715 ** @param [u] dbag [EnsEDatabaseadaptorGroup]
1716 ** Ensembl Database Adaptor Group enumeration
1717 **
1718 ** @return [const char*] Ensembl Database Adaptor Group C-type (char *) string
1719 **
1720 ** @release 6.2.0
1721 ** @@
1722 ******************************************************************************/
1723
ensDatabaseadaptorGroupToChar(EnsEDatabaseadaptorGroup dbag)1724 const char* ensDatabaseadaptorGroupToChar(EnsEDatabaseadaptorGroup dbag)
1725 {
1726 register EnsEDatabaseadaptorGroup i = ensEDatabaseadaptorGroupNULL;
1727
1728 for (i = ensEDatabaseadaptorGroupNULL;
1729 databaseadaptorKGroup[i] && (i < dbag);
1730 i++);
1731
1732 if (!databaseadaptorKGroup[i])
1733 ajDebug("ensDatabaseadaptorGroupToChar "
1734 "encountered an out of boundary error on "
1735 "Ensembl Databaseadaptor Group "
1736 "enumeration %d.\n",
1737 dbag);
1738
1739 return databaseadaptorKGroup[i];
1740 }
1741