1 /* @source ensdatabaseconnection **********************************************
2 **
3 ** Ensembl Database Connection functions
4 **
5 ** @author Copyright (C) 1999 Ensembl Developers
6 ** @author Copyright (C) 2006 Michael K. Schuster
7 ** @version $Revision: 1.37 $
8 ** @modified $Date: 2013/02/17 13:02:40 $ by $Author: mks $
9 ** @modified $Date: 2013/02/17 13:02:40 $ by $Author: mks $
10 **
11 ** This library is free software; you can redistribute it and/or
12 ** modify it under the terms of the GNU Lesser General Public
13 ** License as published by the Free Software Foundation; either
14 ** version 2.1 of the License, or (at your option) any later version.
15 **
16 ** This library is distributed in the hope that it will be useful,
17 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 ** Lesser General Public License for more details.
20 **
21 ** You should have received a copy of the GNU Lesser General Public
22 ** License along with this library; if not, write to the Free Software
23 ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
24 ** MA 02110-1301, USA.
25 **
26 ******************************************************************************/
27
28 /* ========================================================================= */
29 /* ============================= include files ============================= */
30 /* ========================================================================= */
31
32 #include "ensdatabaseconnection.h"
33
34
35
36
37 /* ========================================================================= */
38 /* =============================== constants =============================== */
39 /* ========================================================================= */
40
41
42
43
44 /* ========================================================================= */
45 /* =========================== global variables ============================ */
46 /* ========================================================================= */
47
48
49
50
51 /* ========================================================================= */
52 /* ============================= private data ============================== */
53 /* ========================================================================= */
54
55
56
57
58 /* ========================================================================= */
59 /* =========================== private constants =========================== */
60 /* ========================================================================= */
61
62
63
64
65 /* ========================================================================= */
66 /* =========================== private variables =========================== */
67 /* ========================================================================= */
68
69
70
71
72 /* ========================================================================= */
73 /* =========================== private functions =========================== */
74 /* ========================================================================= */
75
76
77
78
79 /* ========================================================================= */
80 /* ======================= All functions by section ======================== */
81 /* ========================================================================= */
82
83
84
85
86 /* @filesection ensdatabaseconnection *****************************************
87 **
88 ** @nam1rule ens Function belongs to the Ensembl library
89 **
90 ******************************************************************************/
91
92
93
94
95 /* @datasection [EnsPDatabaseconnection] Ensembl Database Connection **********
96 **
97 ** @nam2rule Databaseconnection Functions for manipulating
98 ** Ensembl Database Connection objects
99 **
100 ** @cc Bio::EnsEMBL::DBSQL::DBConnection
101 ** @cc CVS Revision: 1.79
102 ** @cc CVS Tag: branch-ensembl-68
103 **
104 ** NOTE: The Perl API also supports the ORACLE, ODBC and Sybase SQL client
105 ** libraries.
106 ******************************************************************************/
107
108
109
110
111 /* @section constructors ******************************************************
112 **
113 ** All constructors return a new Ensembl Database Connection by pointer.
114 ** It is the responsibility of the user to first destroy any previous
115 ** Database Connection. The target pointer does not need to be initialised to
116 ** NULL, but it is good programming practice to do so anyway.
117 **
118 ** @fdata [EnsPDatabaseconnection]
119 **
120 ** @nam3rule New Constructor
121 ** @nam4rule Cpy Constructor with existing object
122 ** @nam4rule Ini Constructor with initial values
123 ** @nam4rule Ref Constructor by incrementing the reference counter
124 ** @nam4rule Url Constructor with a Uniform Resource Locator
125 **
126 ** @argrule Cpy dbc [EnsPDatabaseconnection] Ensembl Database Connection
127 ** @argrule Cpy database [AjPStr] SQL database name (optional)
128 ** @argrule Ini client [AjESqlconnectionClient] AJAX SQL Connection client
129 ** @argrule Ini user [AjPStr] User name
130 ** @argrule Ini password [AjPStr] Password
131 ** @argrule Ini host [AjPStr] Host name or IP address
132 ** @argrule Ini port [AjPStr] Host TCP/IP port
133 ** @argrule Ini socketfile [AjPStr] UNIX socket file
134 ** @argrule Ini database [AjPStr] SQL database name
135 ** @argrule Ini dbctimeout [ajuint]
136 ** Timeout in seconds for idle, non-interactive connections
137 ** @argrule Ref dbc [EnsPDatabaseconnection] Ensembl Database Connection
138 ** @argrule Url url [const AjPStr] Uniform Resource Locator
139 **
140 ** @valrule * [EnsPDatabaseconnection] Ensembl Database Connection or NULL
141 **
142 ** @fcategory new
143 ******************************************************************************/
144
145
146
147
148 /* @func ensDatabaseconnectionNewCpy ******************************************
149 **
150 ** Construct an Ensembl Database Connection on an already existing connection.
151 ** Optionally, a database name may be provided to connect to a different
152 ** database on the same SQL server using the same SQL account information.
153 **
154 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::new
155 ** @param [u] dbc [EnsPDatabaseconnection] Ensembl Database Connection
156 ** @param [uN] database [AjPStr] SQL database name (optional)
157 **
158 ** @return [EnsPDatabaseconnection] Ensembl Database Connection or NULL
159 **
160 ** @release 6.4.0
161 ** @@
162 ******************************************************************************/
163
ensDatabaseconnectionNewCpy(EnsPDatabaseconnection dbc,AjPStr database)164 EnsPDatabaseconnection ensDatabaseconnectionNewCpy(
165 EnsPDatabaseconnection dbc,
166 AjPStr database)
167 {
168 EnsPDatabaseconnection pthis = NULL;
169
170 if (!dbc)
171 return NULL;
172
173 if (ajDebugTest("ensDatabaseconnectionNewCpy"))
174 {
175 ajDebug("ensDatabaseconnectionNewCpy\n"
176 " dbc %p\n"
177 " database '%S'\n",
178 dbc,
179 database);
180
181 ensDatabaseconnectionTrace(dbc, 1);
182 }
183
184 AJNEW0(pthis);
185
186 pthis->Sqlconnectionclient = dbc->Sqlconnectionclient;
187
188 if (dbc->Username)
189 pthis->Username = ajStrNewRef(dbc->Username);
190
191 if (dbc->Password)
192 pthis->Password = ajStrNewRef(dbc->Password);
193
194 if (dbc->Hostname)
195 pthis->Hostname = ajStrNewRef(dbc->Hostname);
196
197 if (dbc->Hostport)
198 pthis->Hostport = ajStrNewRef(dbc->Hostport);
199
200 if (dbc->Socketfile)
201 pthis->Socketfile = ajStrNewRef(dbc->Socketfile);
202
203 if (database && ajStrGetLen(database))
204 pthis->Databasename = ajStrNewRef(database);
205 else
206 {
207 if (dbc->Databasename)
208 pthis->Databasename = ajStrNewRef(dbc->Databasename);
209 }
210
211 pthis->Timeout = dbc->Timeout;
212
213 pthis->Use = 1U;
214
215 return pthis;
216 }
217
218
219
220
221 /* @func ensDatabaseconnectionNewIni ******************************************
222 **
223 ** Constructor for an Ensembl Database Connection with initial values.
224 **
225 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::new
226 ** @param [u] client [AjESqlconnectionClient] AJAX SQL Connection client
227 ** @param [uN] user [AjPStr] User name
228 ** @param [uN] password [AjPStr] Password
229 ** @param [uN] host [AjPStr] Host name or IP address
230 ** @param [uN] port [AjPStr] Host TCP/IP port
231 ** @param [uN] socketfile [AjPStr] UNIX socket file
232 ** @param [uN] database [AjPStr] SQL database name
233 ** @param [rN] dbctimeout [ajuint]
234 ** Timeout in seconds for idle, non-interactive connections
235 **
236 ** @return [EnsPDatabaseconnection] Ensembl Database Connection or NULL
237 **
238 ** @release 6.4.0
239 ** @@
240 ******************************************************************************/
241
ensDatabaseconnectionNewIni(AjESqlconnectionClient client,AjPStr user,AjPStr password,AjPStr host,AjPStr port,AjPStr socketfile,AjPStr database,ajuint dbctimeout)242 EnsPDatabaseconnection ensDatabaseconnectionNewIni(
243 AjESqlconnectionClient client,
244 AjPStr user,
245 AjPStr password,
246 AjPStr host,
247 AjPStr port,
248 AjPStr socketfile,
249 AjPStr database,
250 ajuint dbctimeout)
251 {
252 EnsPDatabaseconnection dbc = NULL;
253
254 if (!client)
255 return NULL;
256
257 if (ajDebugTest("ensDatabaseconnectionNewIni"))
258 ajDebug("ensDatabaseconnectionNewIni\n"
259 " client %d\n"
260 " user '%S'\n"
261 " password '***'\n"
262 " host '%S'\n"
263 " port '%S'\n"
264 " socketfile '%S'\n"
265 " database '%S'\n"
266 " dbctimeout %u\n",
267 client,
268 user,
269 host,
270 port,
271 socketfile,
272 database,
273 dbctimeout);
274
275 AJNEW0(dbc);
276
277 dbc->Sqlconnectionclient = client;
278
279 if (user)
280 dbc->Username = ajStrNewRef(user);
281
282 if (password)
283 dbc->Password = ajStrNewRef(password);
284
285 if (host)
286 dbc->Hostname = ajStrNewRef(host);
287
288 if (port)
289 dbc->Hostport = ajStrNewRef(port);
290
291 if (socketfile)
292 dbc->Socketfile = ajStrNewRef(socketfile);
293
294 if (database)
295 dbc->Databasename = ajStrNewRef(database);
296
297 dbc->Timeout = dbctimeout;
298
299 dbc->Use = 1U;
300
301 return dbc;
302 }
303
304
305
306
307 /* @func ensDatabaseconnectionNewRef ******************************************
308 **
309 ** Ensembl Object referencing function, which returns a pointer to the
310 ** Ensembl Object passed in and increases its reference count.
311 **
312 ** @param [u] dbc [EnsPDatabaseconnection] Ensembl Database Connection
313 **
314 ** @return [EnsPDatabaseconnection] Ensembl Database Connection
315 **
316 ** @release 6.3.0
317 ** @@
318 ******************************************************************************/
319
ensDatabaseconnectionNewRef(EnsPDatabaseconnection dbc)320 EnsPDatabaseconnection ensDatabaseconnectionNewRef(EnsPDatabaseconnection dbc)
321 {
322 if (!dbc)
323 return NULL;
324
325 dbc->Use++;
326
327 return dbc;
328 }
329
330
331
332
333 /* @func ensDatabaseconnectionNewUrl ******************************************
334 **
335 ** Construct an Ensembl Database Connection from a Uniform Resource Locator
336 ** with the following schema where brackets indicate optional components.
337 **
338 ** client://username[:password]@host[:port][/databasename]
339 **
340 ** The following URL would be an example for the public Ensembl MySQL instance.
341 **
342 ** mysql://anonymous@ensembldb.ensembl.org:5306/
343 **
344 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::*
345 ** @param [r] url [const AjPStr] Uniform Resource Locator
346 **
347 ** @return [EnsPDatabaseconnection] Ensembl Database Connection or NULL
348 **
349 ** @release 6.3.0
350 ** @@
351 ******************************************************************************/
352
ensDatabaseconnectionNewUrl(const AjPStr url)353 EnsPDatabaseconnection ensDatabaseconnectionNewUrl(const AjPStr url)
354 {
355 AjPRegexp urlre = NULL;
356
357 AjESqlconnectionClient eclient = ajESqlconnectionClientNULL;
358
359 EnsPDatabaseconnection dbc = NULL;
360
361 AjPStr client = NULL;
362 AjPStr user = NULL;
363 AjPStr password = NULL;
364 AjPStr host = NULL;
365 AjPStr port = NULL;
366 AjPStr database = NULL;
367
368 if (ajDebugTest("ensDatabaseconnectionNewUrl"))
369 ajDebug("ensDatabaseconnectionNewUrl\n"
370 " url '%S'\n",
371 url);
372
373 if ((url == NULL) || (ajStrGetLen(url) == 0))
374 return NULL;
375
376 urlre = ajRegCompC("([^:]+)://(?:([^@:]+)(?:\\:([^@]*))?@)?"
377 "([^:/]+)(?:\\:)?(\\d+)?(?:\\/(\\w+))?");
378
379 if (ajRegExec(urlre, url))
380 {
381 client = ajStrNew();
382 user = ajStrNew();
383 password = ajStrNew();
384 host = ajStrNew();
385 port = ajStrNew();
386 database = ajStrNew();
387
388 ajRegSubI(urlre, 1, &client);
389 ajRegSubI(urlre, 2, &user);
390 ajRegSubI(urlre, 3, &password);
391 ajRegSubI(urlre, 4, &host);
392 ajRegSubI(urlre, 5, &port);
393 ajRegSubI(urlre, 6, &database);
394
395 eclient = ajSqlconnectionClientFromStr(client);
396
397 if (!eclient)
398 ajDebug("ensDatabaseconnectionNewUrl encountered "
399 "unexpected string '%S' in the "
400 "client part of the URL '%S'.\n",
401 client, url);
402
403 dbc = ensDatabaseconnectionNewIni(eclient,
404 user,
405 password,
406 host,
407 port,
408 (AjPStr) NULL,
409 database,
410 0);
411
412 ajStrDel(&client);
413 ajStrDel(&user);
414 ajStrDel(&password);
415 ajStrDel(&host);
416 ajStrDel(&port);
417 ajStrDel(&database);
418 }
419
420 ajRegFree(&urlre);
421
422 return dbc;
423 }
424
425
426
427
428 /* @section destructors *******************************************************
429 **
430 ** Destruction destroys all internal data structures and frees the memory
431 ** allocated for an Ensembl Database Connection object.
432 **
433 ** @fdata [EnsPDatabaseconnection]
434 **
435 ** @nam3rule Del Destroy (free) an Ensembl Database Connection
436 **
437 ** @argrule * Pdbc [EnsPDatabaseconnection*]
438 ** Ensembl Database Connection address
439 **
440 ** @valrule * [void]
441 **
442 ** @fcategory delete
443 ******************************************************************************/
444
445
446
447
448 /* @func ensDatabaseconnectionDel *********************************************
449 **
450 ** Default destructor for an Ensembl Database Connection.
451 **
452 ** Before freeing memory, the AJAX SQL Connection to the SQL RDBMS instance
453 ** is dropped.
454 **
455 ** @param [d] Pdbc [EnsPDatabaseconnection*]
456 ** Ensembl Database Connection address
457 **
458 ** @return [void]
459 **
460 ** @release 6.2.0
461 ** @@
462 ******************************************************************************/
463
ensDatabaseconnectionDel(EnsPDatabaseconnection * Pdbc)464 void ensDatabaseconnectionDel(EnsPDatabaseconnection *Pdbc)
465 {
466 EnsPDatabaseconnection pthis = NULL;
467
468 if (!Pdbc)
469 return;
470
471 #if defined(AJ_DEBUG) && AJ_DEBUG >= 1
472 if (ajDebugTest("ensDatabaseconnectionDel"))
473 {
474 ajDebug("ensDatabaseconnectionDel\n"
475 " *Pdbc %p\n",
476 *Pdbc);
477
478 ensDatabaseconnectionTrace(*Pdbc, 1);
479 }
480 #endif /* defined(AJ_DEBUG) && AJ_DEBUG >= 1 */
481
482 if (!(pthis = *Pdbc) || --pthis->Use)
483 {
484 *Pdbc = NULL;
485
486 return;
487 }
488
489 ajSqlconnectionDel(&pthis->Sqlconnection);
490
491 ajStrDel(&pthis->Username);
492 ajStrDel(&pthis->Password);
493 ajStrDel(&pthis->Hostname);
494 ajStrDel(&pthis->Hostport);
495 ajStrDel(&pthis->Socketfile);
496 ajStrDel(&pthis->Databasename);
497
498 ajMemFree((void **) Pdbc);
499
500 return;
501 }
502
503
504
505
506 /* @section member retrieval **************************************************
507 **
508 ** Functions for returning members of an Ensembl Database Connection object.
509 **
510 ** @fdata [EnsPDatabaseconnection]
511 **
512 ** @nam3rule Get Return Database Connection attribute(s)
513 ** @nam4rule Autodisconnect Return the auto disconnect flag
514 ** @nam4rule Databasename Return the database name
515 ** @nam4rule Hostname Return the host name
516 ** @nam4rule Hostport Return host port
517 ** @nam4rule Password Return the password
518 ** @nam4rule Socketfile Return the UNIX socket file
519 ** @nam4rule Sqlconnection Return the AJAX SQL Connection
520 ** @nam4rule Sqlconnectionclient Return the AJAX SQL Connection client
521 ** @nam4rule Timeout Return the timeout
522 ** @nam4rule Username Return the user name
523 **
524 ** @argrule * dbc [const EnsPDatabaseconnection] Ensembl Database Connection
525 **
526 ** @valrule Autodisconnect [AjBool] Auto disconnect flag or ajFalse
527 ** @valrule Databasename [AjPStr] Database name or NULL
528 ** @valrule Hostname [AjPStr] Host name or NULL
529 ** @valrule Hostport [AjPStr] Host port or NULL
530 ** @valrule Password [AjPStr] Password or NULL
531 ** @valrule Socketfile [AjPStr] UNIX socket file or NULL
532 ** @valrule Sqlconnection [AjPSqlconnection] AJAX SQL Connection or NULL
533 ** @valrule Sqlconnectionclient [AjESqlconnectionClient]
534 ** AJAX SQL Connection Client enumeration or ajESqlconnectionClientNULL
535 ** @valrule Timeout [ajuint] Timeout or 0U
536 ** @valrule Username [AjPStr] User name or NULL
537 **
538 ** @fcategory use
539 ******************************************************************************/
540
541
542
543
544 /* @func ensDatabaseconnectionGetAutodisconnect *******************************
545 **
546 ** Get the auto disconnect member of an Ensembl Database Connection.
547 **
548 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::disconnect_when_inactive
549 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
550 **
551 ** @return [AjBool] Auto disconnect or ajFalse
552 ** ajTrue: The Ensembl Database Connection will automatically
553 ** disconnect, i.e. delete the AJAX SQL Connection,
554 ** if no AJAX SQL Statement is active.
555 ** ajFalse: No automatic disconnects will occur.
556 **
557 ** @release 6.4.0
558 ** @@
559 ******************************************************************************/
560
ensDatabaseconnectionGetAutodisconnect(const EnsPDatabaseconnection dbc)561 AjBool ensDatabaseconnectionGetAutodisconnect(
562 const EnsPDatabaseconnection dbc)
563 {
564 return (dbc) ? dbc->Autodisconnect : ajFalse;
565 }
566
567
568
569
570 /* @func ensDatabaseconnectionGetDatabasename *********************************
571 **
572 ** Get the database name member of an Ensembl Database Connection.
573 **
574 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::dbname
575 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
576 **
577 ** @return [AjPStr] Database name or NULL
578 **
579 ** @release 6.4.0
580 ** @@
581 ******************************************************************************/
582
ensDatabaseconnectionGetDatabasename(const EnsPDatabaseconnection dbc)583 AjPStr ensDatabaseconnectionGetDatabasename(
584 const EnsPDatabaseconnection dbc)
585 {
586 return (dbc) ? dbc->Databasename : NULL;
587 }
588
589
590
591
592 /* @func ensDatabaseconnectionGetHostname *************************************
593 **
594 ** Get the host name member of an Ensembl Database Connection.
595 **
596 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::host
597 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
598 **
599 ** @return [AjPStr] Host name or NULL
600 **
601 ** @release 6.4.0
602 ** @@
603 ******************************************************************************/
604
ensDatabaseconnectionGetHostname(const EnsPDatabaseconnection dbc)605 AjPStr ensDatabaseconnectionGetHostname(
606 const EnsPDatabaseconnection dbc)
607 {
608 return (dbc) ? dbc->Hostname : NULL;
609 }
610
611
612
613
614 /* @func ensDatabaseconnectionGetHostport *************************************
615 **
616 ** Get the host port member of an Ensembl Database Connection.
617 **
618 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::port
619 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
620 **
621 ** @return [AjPStr] Host port or NULL
622 **
623 ** @release 6.4.0
624 ** @@
625 ******************************************************************************/
626
ensDatabaseconnectionGetHostport(const EnsPDatabaseconnection dbc)627 AjPStr ensDatabaseconnectionGetHostport(
628 const EnsPDatabaseconnection dbc)
629 {
630 return (dbc) ? dbc->Hostport : NULL;
631 }
632
633
634
635
636 /* @func ensDatabaseconnectionGetPassword *************************************
637 **
638 ** Get the password member of an Ensembl Database Connection.
639 **
640 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::password
641 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
642 **
643 ** @return [AjPStr] Password or NULL
644 **
645 ** @release 6.2.0
646 ** @@
647 ******************************************************************************/
648
ensDatabaseconnectionGetPassword(const EnsPDatabaseconnection dbc)649 AjPStr ensDatabaseconnectionGetPassword(
650 const EnsPDatabaseconnection dbc)
651 {
652 return (dbc) ? dbc->Password : NULL;
653 }
654
655
656
657
658 /* @func ensDatabaseconnectionGetSocketfile ***********************************
659 **
660 ** Get the UNIX socket file member of an Ensembl Database Connection.
661 **
662 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
663 **
664 ** @return [AjPStr] UNIX socket file or NULL
665 **
666 ** @release 6.4.0
667 ** @@
668 ******************************************************************************/
669
ensDatabaseconnectionGetSocketfile(const EnsPDatabaseconnection dbc)670 AjPStr ensDatabaseconnectionGetSocketfile(
671 const EnsPDatabaseconnection dbc)
672 {
673 return (dbc) ? dbc->Socketfile : NULL;
674 }
675
676
677
678
679 /* @func ensDatabaseconnectionGetSqlconnection ********************************
680 **
681 ** Get the AJAX SQL Connection member of an Ensembl Database Connection.
682 **
683 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
684 **
685 ** @return [AjPSqlconnection] AJAX SQL Connection or NULL
686 **
687 ** @release 6.2.0
688 ** @@
689 ******************************************************************************/
690
ensDatabaseconnectionGetSqlconnection(const EnsPDatabaseconnection dbc)691 AjPSqlconnection ensDatabaseconnectionGetSqlconnection(
692 const EnsPDatabaseconnection dbc)
693 {
694 return (dbc) ? dbc->Sqlconnection : NULL;
695 }
696
697
698
699
700 /* @func ensDatabaseconnectionGetSqlconnectionclient **************************
701 **
702 ** Get the AJAX SQL Connection Client enumeration member of an
703 ** Ensembl Database Connection.
704 **
705 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::driver
706 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
707 **
708 ** @return [AjESqlconnectionClient]
709 ** AJAX SQL Connection Client enumeration or ajESqlconnectionClientNULL
710 **
711 ** @release 6.4.0
712 ** @@
713 ******************************************************************************/
714
ensDatabaseconnectionGetSqlconnectionclient(const EnsPDatabaseconnection dbc)715 AjESqlconnectionClient ensDatabaseconnectionGetSqlconnectionclient(
716 const EnsPDatabaseconnection dbc)
717 {
718 return (dbc) ? dbc->Sqlconnectionclient : ajESqlconnectionClientNULL;
719 }
720
721
722
723
724 /* @func ensDatabaseconnectionGetTimeout **************************************
725 **
726 ** Get the timeout member of an Ensembl Database Connection.
727 **
728 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::timeout
729 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
730 **
731 ** @return [ajuint] Timeout or 0U
732 **
733 ** @release 6.4.0
734 ** @@
735 ******************************************************************************/
736
ensDatabaseconnectionGetTimeout(const EnsPDatabaseconnection dbc)737 ajuint ensDatabaseconnectionGetTimeout(
738 const EnsPDatabaseconnection dbc)
739 {
740 return (dbc) ? dbc->Timeout : 0U;
741 }
742
743
744
745
746 /* @func ensDatabaseconnectionGetUsername *************************************
747 **
748 ** Get the user name member of an Ensembl Database Connection.
749 **
750 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::username
751 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
752 **
753 ** @return [AjPStr] User name or NULL
754 **
755 ** @release 6.4.0
756 ** @@
757 ******************************************************************************/
758
ensDatabaseconnectionGetUsername(const EnsPDatabaseconnection dbc)759 AjPStr ensDatabaseconnectionGetUsername(
760 const EnsPDatabaseconnection dbc)
761 {
762 return (dbc) ? dbc->Username : NULL;
763 }
764
765
766
767
768 /* @section member assignment *************************************************
769 **
770 ** Functions for assigning members of an Ensembl Database Connection object.
771 **
772 ** @fdata [EnsPDatabaseconnection]
773 **
774 ** @nam3rule Set Set one member of an Ensembl Database Connection
775 ** @nam4rule Autodisconnect Set the automatic disconnect flag
776 **
777 ** @argrule * dbc [EnsPDatabaseconnection] Ensembl Database Connection object
778 ** @argrule Autodisconnect autodisconnect [AjBool] Auto disconnect flag
779 **
780 ** @valrule * [AjBool] ajTrue upon success, ajFalse otherwise
781 **
782 ** @fcategory modify
783 ******************************************************************************/
784
785
786
787
788 /* @func ensDatabaseconnectionSetAutodisconnect *******************************
789 **
790 ** Set the auto disconnect member of an Ensembl Database Connection.
791 **
792 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::disconnect_when_inactive
793 ** @param [u] dbc [EnsPDatabaseconnection] Ensembl Database Connection
794 ** @param [r] autodisconnect [AjBool] Auto disconnect flag
795 **
796 ** ajTrue: The Ensembl Database Connection will automatically
797 ** disconnect, i.e. delete the AJAX SQL Connection,
798 ** if no AJAX SQL Statement is active.
799 **
800 ** ajFalse: No automatic disconnects will occur.
801 **
802 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
803 **
804 ** @release 6.4.0
805 ** @@
806 ******************************************************************************/
807
ensDatabaseconnectionSetAutodisconnect(EnsPDatabaseconnection dbc,AjBool autodisconnect)808 AjBool ensDatabaseconnectionSetAutodisconnect(
809 EnsPDatabaseconnection dbc,
810 AjBool autodisconnect)
811 {
812 if (!dbc)
813 return ajFalse;
814
815 dbc->Autodisconnect = autodisconnect;
816
817 return ajTrue;
818 }
819
820
821
822
823 /* @section debugging *********************************************************
824 **
825 ** Functions for reporting of an Ensembl Database Connection object.
826 **
827 ** @fdata [EnsPDatabaseconnection]
828 **
829 ** @nam3rule Trace Report Ensembl Database Connection members to debug file
830 **
831 ** @argrule Trace dbc [const EnsPDatabaseconnection] Ensembl Database
832 ** Connection
833 ** @argrule Trace level [ajuint] Indentation level
834 **
835 ** @valrule * [AjBool] ajTrue upon success, ajFalse otherwise
836 **
837 ** @fcategory misc
838 ******************************************************************************/
839
840
841
842
843 /* @func ensDatabaseconnectionTrace *******************************************
844 **
845 ** Trace an Ensembl Database Connection.
846 **
847 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
848 ** @param [r] level [ajuint] Indentation level
849 **
850 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
851 **
852 ** @release 6.2.0
853 ** @@
854 ******************************************************************************/
855
ensDatabaseconnectionTrace(const EnsPDatabaseconnection dbc,ajuint level)856 AjBool ensDatabaseconnectionTrace(const EnsPDatabaseconnection dbc,
857 ajuint level)
858 {
859 AjPStr indent = NULL;
860
861 if (!dbc)
862 return ajFalse;
863
864 indent = ajStrNew();
865
866 ajStrAppendCountK(&indent, ' ', level * 2);
867
868 ajDebug("%SensDatabaseconnectionTrace %p\n"
869 "%S Sqlconnection %p\n"
870 "%S Sqlconnectionclient '%s'\n"
871 "%S Username '%S'\n"
872 "%S Password '***'\n"
873 "%S Hostname '%S'\n"
874 "%S Hostport '%S'\n"
875 "%S Socketfile '%S'\n"
876 "%S Databasename '%S'\n"
877 "%S Use %u\n",
878 indent, dbc,
879 indent, dbc->Sqlconnection,
880 indent, ajSqlconnectionClientToChar(dbc->Sqlconnectionclient),
881 indent, dbc->Username,
882 indent,
883 indent, dbc->Hostname,
884 indent, dbc->Hostport,
885 indent, dbc->Socketfile,
886 indent, dbc->Databasename,
887 indent, dbc->Use);
888
889 ajSqlconnectionTrace(dbc->Sqlconnection, level + 1);
890
891 ajStrDel(&indent);
892
893 return ajTrue;
894 }
895
896
897
898
899 /* @section test **************************************************************
900 **
901 ** Functions for testing Ensembl Database Connection objects
902 **
903 ** @fdata [EnsPDatabaseconnection]
904 **
905 ** @nam3rule Is Ensembl Database Connection has a property
906 ** @nam4rule Connected Test whether an active AJAX SQL Connection exists
907 **
908 ** @argrule * dbc [const EnsPDatabaseconnection] Ensembl Database Connection
909 **
910 ** @valrule Connected [AjBool] ajTrue if connected
911 **
912 ** @fcategory use
913 ******************************************************************************/
914
915
916
917
918 /* @func ensDatabaseconnectionIsConnected *************************************
919 **
920 ** Test whether an Ensembl Database Connection has an active
921 ** AJAX SQL Connection assigned.
922 **
923 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::connected
924 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
925 **
926 ** @return [AjBool] ajTrue if the Ensembl Database Connection has an active
927 ** AJAX SQL Connection assigned
928 **
929 ** @release 6.2.0
930 ** @@
931 ******************************************************************************/
932
ensDatabaseconnectionIsConnected(const EnsPDatabaseconnection dbc)933 AjBool ensDatabaseconnectionIsConnected(const EnsPDatabaseconnection dbc)
934 {
935 return (dbc && dbc->Sqlconnection) ? ajTrue : ajFalse;
936 }
937
938
939
940
941 /* @section comparison ********************************************************
942 **
943 ** Functions for comparing Ensembl Database Connections
944 **
945 ** @fdata [EnsPDatabaseconnection]
946 **
947 ** @nam3rule Match Compare two Ensembl Database Connections
948 **
949 ** @argrule * dbc1 [const EnsPDatabaseconnection] Ensembl Database Connection
950 ** @argrule * dbc2 [const EnsPDatabaseconnection] Ensembl Database Connection
951 **
952 ** @valrule * [AjBool] ajTrue on success
953 **
954 ** @fcategory use
955 ******************************************************************************/
956
957
958
959
960 /* @func ensDatabaseconnectionMatch *******************************************
961 **
962 ** Tests for matching two Ensembl Database Connections.
963 **
964 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::equals
965 ** @param [r] dbc1 [const EnsPDatabaseconnection] Ensembl Database Connection
966 ** @param [r] dbc2 [const EnsPDatabaseconnection] Ensembl Database Connection
967 **
968 ** @return [AjBool] ajTrue if the Ensembl Database Connection objects match
969 **
970 ** @release 6.2.0
971 ** @@
972 ** The comparison is based on initial pointer equality and if that fails a
973 ** direct comparison of Ensembl Database Connection members.
974 ******************************************************************************/
975
ensDatabaseconnectionMatch(const EnsPDatabaseconnection dbc1,const EnsPDatabaseconnection dbc2)976 AjBool ensDatabaseconnectionMatch(const EnsPDatabaseconnection dbc1,
977 const EnsPDatabaseconnection dbc2)
978 {
979 if (!dbc1)
980 return ajFalse;
981
982 if (!dbc2)
983 return ajFalse;
984
985 if (dbc1 == dbc2)
986 return ajTrue;
987
988 /*
989 ** The AJAX SQL Connection is not tested as it can be disconnected at any
990 ** time and the database name is most likely to be different and
991 ** therefore tested first. String matches are rather expensive...
992 */
993
994 if (!ajStrMatchS(dbc1->Databasename, dbc2->Databasename))
995 return ajFalse;
996
997 if (!ajStrMatchS(dbc1->Username, dbc2->Username))
998 return ajFalse;
999
1000 if (!ajStrMatchS(dbc1->Password, dbc2->Password))
1001 return ajFalse;
1002
1003 if (!ajStrMatchS(dbc1->Hostname, dbc2->Hostname))
1004 return ajFalse;
1005
1006 if (!ajStrMatchS(dbc1->Hostport, dbc2->Hostport))
1007 return ajFalse;
1008
1009 if (!ajStrMatchS(dbc1->Socketfile, dbc2->Socketfile))
1010 return ajFalse;
1011
1012 if (dbc1->Sqlconnectionclient != dbc2->Sqlconnectionclient)
1013 return ajFalse;
1014
1015 return ajTrue;
1016 }
1017
1018
1019
1020
1021 /* @section connection ********************************************************
1022 **
1023 ** Functions for connecting and disconnecting Ensembl Database Connections
1024 **
1025 ** @fdata [EnsPDatabaseconnection]
1026 **
1027 ** @nam3rule Connect Connect an Ensembl Database Connection
1028 ** @nam3rule Disconnect Disconnect an Ensembl Database Connection
1029 **
1030 ** @argrule * dbc [EnsPDatabaseconnection] Ensembl Database Connection
1031 **
1032 ** @valrule * [AjBool] True on success, ajFalse otherwise
1033 **
1034 ** @fcategory use
1035 ******************************************************************************/
1036
1037
1038
1039
1040 /* @func ensDatabaseconnectionConnect *****************************************
1041 **
1042 ** Connect an Ensembl Database Connection to the specified SQL database.
1043 **
1044 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::connect
1045 ** @param [u] dbc [EnsPDatabaseconnection] Ensembl Database Connection
1046 **
1047 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1048 **
1049 ** @release 6.2.0
1050 ** @@
1051 ******************************************************************************/
1052
ensDatabaseconnectionConnect(EnsPDatabaseconnection dbc)1053 AjBool ensDatabaseconnectionConnect(EnsPDatabaseconnection dbc)
1054 {
1055 AjPSqlstatement sqls = NULL;
1056
1057 AjPStr statement = NULL;
1058
1059 if (!dbc)
1060 return ajFalse;
1061
1062 if (dbc->Sqlconnection)
1063 return ajTrue;
1064
1065 if (ajDebugTest("ensDatabaseconnectionConnect"))
1066 ajDebug("ensDatabaseconnectionConnect\n"
1067 " dbc %p\n",
1068 dbc);
1069
1070 dbc->Sqlconnection = ajSqlconnectionNewData(dbc->Sqlconnectionclient,
1071 dbc->Username,
1072 dbc->Password,
1073 dbc->Hostname,
1074 dbc->Hostport,
1075 dbc->Socketfile,
1076 dbc->Databasename);
1077
1078 if (!dbc->Sqlconnection)
1079 {
1080 ajWarn("Could not establish an SQL connection for user '%S' "
1081 "to host '%S' at port '%S' for database '%S'.\n",
1082 dbc->Username,
1083 dbc->Hostname,
1084 dbc->Hostport,
1085 dbc->Databasename);
1086
1087 return ajFalse;
1088 }
1089
1090 /* NOTE: Setting a connection timeout is MySQL-specific for the moment. */
1091
1092 if ((dbc->Timeout > 0)
1093 &&
1094 (dbc->Sqlconnectionclient == ajESqlconnectionClientMySQL))
1095 {
1096 statement = ajFmtStr("SET SESSION wait_timeout=%u", dbc->Timeout);
1097
1098 sqls = ajSqlstatementNewRun(dbc->Sqlconnection, statement);
1099
1100 ajSqlstatementDel(&sqls);
1101
1102 ajStrDel(&statement);
1103 }
1104
1105 return ajTrue;
1106 }
1107
1108
1109
1110
1111 /* @func ensDatabaseconnectionDisconnect **************************************
1112 **
1113 ** Disconnect an Ensembl Database Connection from its SQL database.
1114 **
1115 ** This function will only disconnect, if no other AJAX SQL Statement holds a
1116 ** reference to the AJAX SQL Connection, i.e. no AJAX SQL Statement is active.
1117 **
1118 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::disconnect_if_idle
1119 ** @param [u] dbc [EnsPDatabaseconnection] Ensembl Database Connection
1120 **
1121 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1122 **
1123 ** @release 6.2.0
1124 ** @@
1125 ******************************************************************************/
1126
ensDatabaseconnectionDisconnect(EnsPDatabaseconnection dbc)1127 AjBool ensDatabaseconnectionDisconnect(EnsPDatabaseconnection dbc)
1128 {
1129 if (ajDebugTest("ensDatabaseconnectionDisconnect"))
1130 {
1131 ajDebug("ensDatabaseconnectionDisconnect\n"
1132 " dbc %p\n",
1133 dbc);
1134
1135 ensDatabaseconnectionTrace(dbc, 1);
1136 }
1137
1138 if (!dbc)
1139 return ajFalse;
1140
1141 if (!dbc->Sqlconnection)
1142 return ajTrue;
1143
1144 /*
1145 ** Disconnect if no other AJAX SQL Statement has a reference to the
1146 ** AJAX SQL Connection, except this Ensembl Database Connection object.
1147 */
1148
1149 if (ajSqlconnectionGetUse(dbc->Sqlconnection) == 1)
1150 ajSqlconnectionDel(&dbc->Sqlconnection);
1151
1152 return ajTrue;
1153 }
1154
1155
1156
1157
1158 /* @section convenience functions *********************************************
1159 **
1160 ** Ensembl Database Connection convenience functions
1161 **
1162 ** @fdata [EnsPDatabaseconnection]
1163 **
1164 ** @nam3rule Escape Escape a string
1165 ** @nam4rule C Escape to an AJAX String
1166 ** @nam4rule S Escape to a C-type character string
1167 ** @nam3rule Sqlstatement AJAX SQL Statement
1168 ** @nam4rule Del Delete an AJAX SQL Statement
1169 ** @nam4rule New Run a new AJAX SQL statement
1170 **
1171 ** @argrule * dbc [EnsPDatabaseconnection] Ensembl Database Connection
1172 ** @argrule EscapeC Ptxt [char**] Address of the (new) SQL-escaped C string
1173 ** @argrule EscapeC str [const AjPStr] AJAX String to be escaped
1174 ** @argrule EscapeS Pstr [AjPStr*] Address of the (new) SQL-escaped AJAX String
1175 ** @argrule EscapeS str [const AjPStr] AJAX String to be escaped
1176 ** @argrule SqlstatementDel Psqls [AjPSqlstatement*] AJAX SQL Statement address
1177 ** @argrule SqlstatementNew statement [const AjPStr] SQL statement
1178 **
1179 ** @valrule EscapeC [AjBool] ajTrue upon success, ajFalse otherwise
1180 ** @valrule EscapeS [AjBool] ajTrue upon success, ajFalse otherwise
1181 ** @valrule SqlstatementDel [AjBool] ajTrue upon success, ajFalse otherwise
1182 ** @valrule SqlstatementNew [AjPSqlstatement] AJAX SQL Statement
1183 **
1184 ** @fcategory use
1185 ******************************************************************************/
1186
1187
1188
1189
1190 /* @func ensDatabaseconnectionEscapeC *****************************************
1191 **
1192 ** Escape special characters in an AJAX String for use in an SQL statement,
1193 ** taking into account the current character set of the AJAX SQL Connection
1194 ** and return a C-type character string.
1195 **
1196 ** The caller is responsible for deleting the escaped C-type character string.
1197 **
1198 ** @param [u] dbc [EnsPDatabaseconnection] Ensembl Database Connection
1199 ** @param [wP] Ptxt [char**] Address of the (new) SQL-escaped C string
1200 ** @param [r] str [const AjPStr] AJAX String to be escaped
1201 **
1202 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1203 **
1204 ** @release 6.2.0
1205 ** @@
1206 ******************************************************************************/
1207
ensDatabaseconnectionEscapeC(EnsPDatabaseconnection dbc,char ** Ptxt,const AjPStr str)1208 AjBool ensDatabaseconnectionEscapeC(EnsPDatabaseconnection dbc,
1209 char **Ptxt,
1210 const AjPStr str)
1211 {
1212 if (!dbc)
1213 return ajFalse;
1214
1215 if (!Ptxt)
1216 return ajFalse;
1217
1218 if (!str)
1219 return ajFalse;
1220
1221 if (ajDebugTest("ensDatabaseconnectionEscapeC"))
1222 {
1223 ajDebug("ensDatabaseconnectionEscapeC\n"
1224 " dbc %p\n"
1225 " Ptxt %p\n"
1226 " str '%S'\n",
1227 dbc,
1228 Ptxt,
1229 str);
1230
1231 ensDatabaseconnectionTrace(dbc, 1);
1232 }
1233
1234 if (!ensDatabaseconnectionIsConnected(dbc))
1235 if (!ensDatabaseconnectionConnect(dbc))
1236 return ajFalse;
1237
1238 return ajSqlconnectionEscapeC(dbc->Sqlconnection, Ptxt, str);
1239 }
1240
1241
1242
1243
1244 /* @func ensDatabaseconnectionEscapeS *****************************************
1245 **
1246 ** Escape special characters in an AJAX String for use in an SQL statement,
1247 ** taking into account the current character set of the AJAX SQL Connection
1248 ** and return an AJAX String.
1249 **
1250 ** The caller is responsible for deleting the escaped AJAX String.
1251 **
1252 ** @param [u] dbc [EnsPDatabaseconnection] Ensembl Database Connection
1253 ** @param [wP] Pstr [AjPStr*] Address of the (new) SQL-escaped AJAX String
1254 ** @param [r] str [const AjPStr] AJAX String to be escaped
1255 **
1256 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1257 **
1258 ** @release 6.2.0
1259 ** @@
1260 ******************************************************************************/
1261
ensDatabaseconnectionEscapeS(EnsPDatabaseconnection dbc,AjPStr * Pstr,const AjPStr str)1262 AjBool ensDatabaseconnectionEscapeS(EnsPDatabaseconnection dbc,
1263 AjPStr *Pstr,
1264 const AjPStr str)
1265 {
1266 if (!dbc)
1267 return ajFalse;
1268
1269 if (!Pstr)
1270 return ajFalse;
1271
1272 if (!str)
1273 return ajFalse;
1274
1275 if (ajDebugTest("ensDatabaseconnectionEscapeS"))
1276 {
1277 ajDebug("ensDatabaseconnectionEscapeS\n"
1278 " dbc %p\n"
1279 " Pstr %p\n"
1280 " str '%S'\n",
1281 dbc,
1282 Pstr,
1283 str);
1284
1285 ensDatabaseconnectionTrace(dbc, 1);
1286 }
1287
1288 if (!ensDatabaseconnectionIsConnected(dbc))
1289 if (!ensDatabaseconnectionConnect(dbc))
1290 return ajFalse;
1291
1292 return ajSqlconnectionEscapeS(dbc->Sqlconnection, Pstr, str);
1293 }
1294
1295
1296
1297
1298 /* @func ensDatabaseconnectionSqlstatementDel *********************************
1299 **
1300 ** Delete an AJAX SQL Statement associated with an
1301 ** Ensembl Database Connection.
1302 **
1303 ** @param [u] dbc [EnsPDatabaseconnection] Ensembl Database Connection
1304 ** @param [d] Psqls [AjPSqlstatement*] AJAX SQL Statement address
1305 **
1306 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1307 **
1308 ** @release 6.3.0
1309 ** @@
1310 ******************************************************************************/
1311
ensDatabaseconnectionSqlstatementDel(EnsPDatabaseconnection dbc,AjPSqlstatement * Psqls)1312 AjBool ensDatabaseconnectionSqlstatementDel(
1313 EnsPDatabaseconnection dbc,
1314 AjPSqlstatement *Psqls)
1315 {
1316 if (!dbc)
1317 return ajFalse;
1318
1319 if (!Psqls)
1320 return ajFalse;
1321
1322 if (ajDebugTest("ensDatabaseconnectionSqlstatementDel"))
1323 ajDebug("ensDatabaseconnectionSqlstatementDel\n"
1324 " dbc %p\n"
1325 " Psqls %p\n",
1326 dbc,
1327 Psqls);
1328
1329 ajSqlstatementDel(Psqls);
1330
1331 *Psqls = NULL;
1332
1333 if (dbc->Autodisconnect)
1334 ensDatabaseconnectionDisconnect(dbc);
1335
1336 return ajTrue;
1337 }
1338
1339
1340
1341
1342 /* @func ensDatabaseconnectionSqlstatementNew *********************************
1343 **
1344 ** Run an SQL statement against an Ensembl Database Connection.
1345 **
1346 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::prepare
1347 ** @cc Bio::EnsEMBL::DBSQL::DBConnection::do
1348 ** @param [u] dbc [EnsPDatabaseconnection] Ensembl Database Connection
1349 ** @param [r] statement [const AjPStr] SQL statement
1350 **
1351 ** @return [AjPSqlstatement] AJAX SQL Statement
1352 **
1353 ** @release 6.2.0
1354 ** @@
1355 ******************************************************************************/
1356
ensDatabaseconnectionSqlstatementNew(EnsPDatabaseconnection dbc,const AjPStr statement)1357 AjPSqlstatement ensDatabaseconnectionSqlstatementNew(
1358 EnsPDatabaseconnection dbc,
1359 const AjPStr statement)
1360 {
1361 if (ajDebugTest("ensDatabaseconnectionSqlstatementNew"))
1362 {
1363 ajDebug("ensDatabaseconnectionSqlstatementNew\n"
1364 " dbc %p\n"
1365 " statement '%S'\n",
1366 dbc,
1367 statement);
1368
1369 ensDatabaseconnectionTrace(dbc, 1);
1370 }
1371
1372 if (!dbc)
1373 return NULL;
1374
1375 if (!ensDatabaseconnectionIsConnected(dbc))
1376 if (!ensDatabaseconnectionConnect(dbc))
1377 return NULL;
1378
1379 return ajSqlstatementNewRun(dbc->Sqlconnection, statement);
1380 }
1381
1382
1383
1384
1385 /* @section retrieval *********************************************************
1386 **
1387 ** Ensembl Database Connection retrieval functions
1388 **
1389 ** @fdata [EnsPDatabaseconnection]
1390 **
1391 ** @nam3rule Fetch Fetch an object from an Ensembl Database Connection
1392 ** @nam4rule Url Fetch a Uniform Resource Locator representation
1393 **
1394 ** @argrule * dbc [const EnsPDatabaseconnection] Ensembl Database Connection
1395 ** @argrule FetchUrl Purl [AjPStr*] Uniform Resource Locator
1396 **
1397 ** @valrule * [AjBool] ajTrue upon success, ajFalse otherwise
1398 **
1399 ** @fcategory use
1400 ******************************************************************************/
1401
1402
1403
1404
1405 /* @func ensDatabaseconnectionFetchUrl ****************************************
1406 **
1407 ** Fetch a Uniform Resource Locator representation of an
1408 ** Ensembl Database Connection.
1409 **
1410 ** NOTE: The URL contains the password in text form so fetching the URL is a
1411 ** security risk.
1412 **
1413 ** The caller is responsible for deleting the AJAX String.
1414 **
1415 ** @param [r] dbc [const EnsPDatabaseconnection] Ensembl Database Connection
1416 ** @param [wP] Purl [AjPStr*] Uniform Resource Locator
1417 **
1418 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1419 **
1420 ** @release 6.4.0
1421 ** @@
1422 ******************************************************************************/
1423
ensDatabaseconnectionFetchUrl(const EnsPDatabaseconnection dbc,AjPStr * Purl)1424 AjBool ensDatabaseconnectionFetchUrl(const EnsPDatabaseconnection dbc,
1425 AjPStr *Purl)
1426 {
1427 if (!dbc)
1428 return ajFalse;
1429
1430 if (!Purl)
1431 return ajFalse;
1432
1433 if (*Purl)
1434 ajStrAssignClear(Purl);
1435 else
1436 *Purl = ajStrNew();
1437
1438 if (dbc->Socketfile && ajStrGetLen(dbc->Socketfile))
1439 {
1440 ajStrAppendC(Purl, "file:///");
1441 ajStrAppendS(Purl, dbc->Socketfile);
1442 }
1443 else
1444 {
1445 ajStrAppendC(Purl,
1446 ajSqlconnectionClientToChar(dbc->Sqlconnectionclient));
1447 ajStrAppendC(Purl, "://");
1448
1449 if ((dbc->Username != NULL) && (ajStrGetLen(dbc->Username) > 0))
1450 {
1451 ajStrAppendS(Purl, dbc->Username);
1452
1453 if ((dbc->Password != NULL) && (ajStrGetLen(dbc->Password) > 0))
1454 {
1455 ajStrAppendC(Purl, ":");
1456 ajStrAppendS(Purl, dbc->Password);
1457 }
1458
1459 ajStrAppendC(Purl, "@");
1460 }
1461
1462 ajStrAppendS(Purl, dbc->Hostname);
1463
1464 if ((dbc->Hostport != NULL) && (ajStrGetLen(dbc->Hostport) > 0))
1465 {
1466 ajStrAppendC(Purl, ":");
1467 ajStrAppendS(Purl, dbc->Hostport);
1468 }
1469
1470 ajStrAppendC(Purl, "/");
1471
1472 if ((dbc->Databasename != NULL) && (ajStrGetLen(dbc->Databasename) > 0))
1473 ajStrAppendS(Purl, dbc->Databasename);
1474 }
1475
1476 return ajTrue;
1477 }
1478