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

You must provide the following user-defined data structures to the sqgetdbs() function:

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

The sqgetdbs.ec file in the demo directory contains this sample program.

/*
   * 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

The output you see from the sqgetdbs sample program depends on how you set your ONEDB_SERVER and DBPATH environment variables. The following sample output assumes that the ONEDB_SERVER environment variable is set to mainserver and that this database server contains three databases that are called stores7, sysmaster, and tpc. This output also assumes that the DBPATH environment is not set.

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.