The sqgetdbs() function
The sqgetdbs() function returns the names of databases that a database server can access.
Syntax
mint sqgetdbs(ret_fcnt, dbnarray, dbnsize, dbnbuffer, dbnbufsz)
mint *ret_fcnt;
char **dbnarray;
mint dbnsize;
char *dbnbuffer;
mint dbnbufsz;
- ret_fcnt
- A pointer to the number of database names that the function returns.
- dbnarray
- A user-defined array of character pointers.
- dbnsize
- The size of the dbnarray user-defined array.
- dbnbuffer
- A pointer to a user-defined buffer that contains the names of the databases that the function returns.
- dbnbufsz
- The size of the dbnbuffer user-defined buffer.
Usage
- The dbnbuffer buffer holds the names of the null-terminated database names that sqgetdbs() returns.
- The dbnarray array holds pointers to the database names that the function stores in the dbnbuffer buffer. For example, dbnarray[0] points to the first character of the first database name (in dbnbuffer), dbnarray[1] points to the first character of the second database name, and so on.
If the application is connected to a database server, a call to the sqgetdbs() function returns the names of the databases that are available in the database server of the current connection. This includes the user-defined databases and the sysmaster database. Otherwise, it returns the database names that are available in the default database server (that the ONEDB_SERVER environment variable indicates). If you use the DBPATH environment variable to identify additional database servers that contain databases, sqgetdbs() also lists the databases that are available on these database servers. It first lists the databases that are available through DBPATH and then the databases that are available through the ONEDB_SERVER environment variable.
Return codes
- 0
- Successfully obtained database names
- <0
- Unable to obtain database names
Example
/*
* sqgetdbs.ec *
This program lists the available databases in the database server
of the current connection.
*/
#include <stdio.h>
/* Defines used with exception-handling function: exp_chk() */
#define WARNNOTIFY 1
#define NOWARNNOTIFY 0
/* Defines used for user-defined data structures for sqgetdbs() */
#define BUFFSZ 256
#define NUM_DBNAMES 10
main()
{
char db_buffer[ BUFFSZ ]; /* buffer for database names */
char *dbnames[ NUM_DBNAMES ]; /* array of pointers to database
names in ‘db_buffer’ */
mint num_returned; /* number of database names returned */
mint ret, i;
printf("SQGETDBS Sample ESQL Program running.\n\n");
EXEC SQL connect to default;
exp_chk("CONNECT TO default server", NOWARNNOTIFY);
printf("Connected to default server.\n");
ret = sqgetdbs(&num_returned, dbnames, NUM_DBNAMES,
db_buffer, BUFFSZ);
if(ret < 0)
{
printf("Unable to obtain names of databases.\n");
exit(1);
}
printf("\nNumber of database names returned = %d\n", num_returned);
printf("Databases currently available:\n");
for (i = 0; i < num_returned; i++)
printf("\t%s\n", dbnames[i]);
printf("\nSQGETDBS Sample Program over.\n\n");
}
/*
* The exp_chk() file contains the exception handling functions to
* check the SQLSTATE status variable to see if an error has occurred
* following an SQL statement. If a warning or an error has
* occurred, exp_chk() executes the GET DIAGNOSTICS statement and
* displays the detail for each exception that is returned.
*/
EXEC SQL include exp_chk.ec;
Output
SQGETDBS Sample ESQL Program running.
Connected to default server.
Number of database names returned = 3
Databases currently available:
stores7@mainserver
sysmaster@mainserver
tpc@mainserver
SQGETDBS Sample Program over.