DB2 Version 9.7 for Linux, UNIX, and Windows

db2DbDirGetNextEntry API - Get the next system or local database directory entry

Returns the next entry in the system database directory or the local database directory copy returned by db2DbDirOpenScan. Subsequent calls to this API return additional entries.

Authorization

None

Required connection

None

API include file

db2ApiDf.h

API and data structure syntax

SQL_API_RC SQL_API_FN
  db2DbDirGetNextEntry (
       db2Uint32 versionNumber,
       void * pParmStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2DbDirNextEntryStructV9
{
   db2Uint16 iHandle;
   struct db2DbDirInfoV9 *poDbDirEntry;
} db2DbDirNextEntryStructV9;

SQL_STRUCTURE db2DbDirInfoV9
{
   _SQLOLDCHAR alias[SQL_ALIAS_SZ];
   _SQLOLDCHAR dbname[SQL_DBNAME_SZ];
   _SQLOLDCHAR drive[SQL_DB_PATH_SZ];
   _SQLOLDCHAR intname[SQL_INAME_SZ];
   _SQLOLDCHAR nodename[SQL_NNAME_SZ];
   _SQLOLDCHAR dbtype[SQL_DBTYP_SZ];
   _SQLOLDCHAR comment[SQL_CMT_SZ];
   short com_codepage;
   _SQLOLDCHAR type;
   unsigned short authentication;
   char glbdbname[SQL_DIR_NAME_SZ];
   _SQLOLDCHAR dceprincipal[SQL_DCEPRIN_SZ];
   short cat_nodenum;
   short nodenum;
   _SQLOLDCHAR althostname[SQL_HOSTNAME_SZ];
   _SQLOLDCHAR altportnumber[SQL_SERVICE_NAME_SZ];
};

SQL_API_RC SQL_API_FN
  db2gDbDirGetNextEntry (
       db2Uint32 versionNumber,
       void * pParmStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2gDbDirNextEntryStrV9
{
   db2Uint16 iHandle;
   struct db2DbDirInfoV9 *poDbDirEntry;
} db2gDbDirNextEntryStrV9;

db2DbDirGetNextEntry API parameters

versionNumber: Input. Specifies the version and release level of the structure passed in as the second parameter, pParmStruct.
pParmStruct: Input. A pointer to the db2DbDirGetNextEntryStructV9 structure.
pSqlca: Output. A pointer to the sqlca structure.

db2DbDirNextEntryStructV9 data structure parameters

iHandle: Input. Identifier returned from the associated db2DbDirOpenScan API.
poDbDirEntry: Output. A pointer to a db2DbDirInfoV9 structure. The space for the directory data is allocated by the API, and a pointer to that space is returned to the caller.

db2DbDirInfoV9 data structure parameters

alias

An alternate database name.

dbname

The name of the database.

drive

The local database directory path name where the database resides. This field is returned only if the system database directory is opened for scan.

Note: On Windows, this parameter is CHAR(12).

intname

A token identifying the database subdirectory. This field is returned only if the local database directory is opened for scan.

nodename

The name of the node where the database is located. This field is returned only if the cataloged database is a remote database.

dbtype

Database manager release information.

comment

The comment associated with the database.

com_codepage

The code page of the comment. Not used.

type

Entry type. Valid values are:

SQL_INDIRECT: Database created by the current instance (as defined by the value of the DB2INSTANCE environment variable).
SQL_REMOTE: Database resides at a different instance.
SQL_HOME: Database resides on this volume (always HOME in local database directory).
SQL_DCE: Database resides in DCE directories.

authentication

Authentication type. Valid values are:

SQL_AUTHENTICATION_SERVER: Authentication of the user name and password takes place at the server.
SQL_AUTHENTICATION_CLIENT: Authentication of the user name and password takes place at the client.
SQL_AUTHENTICATION_DCE: Authentication takes place using DCE Security Services.
SQL_AUTHENTICATION_KERBEROS: Authentication takes place using Kerberos Security Mechanism.
SQL_AUTHENTICATION_NOT_SPECIFIED: DB2 no longer requires authentication to be kept in the database directory. Specify this value when connecting to anything other than an earlier (DB2® V2 or less) server.
SQL_AUTHENTICATION_SVR_ENCRYPT: Specifies that authentication takes place on the node containing the target database, and that the authentication password is to be encrypted.
SQL_AUTHENTICATION_DATAENC: Specifies that authentication takes place on the node containing the target database, and that connections must use data encryption.
SQL_AUTHENTICATION_GSSPLUGIN: Specifies that authentication takes place using an external GSS API-based plug-in security mechanism.

glbdbname

The global name of the target database in the global (DCE) directory, if the entry is of type SQL_DCE.

dceprincipal

The principal name if the authentication is of type DCE or KERBEROS.

cat_nodenum

Catalog node number.

nodenum

Node number.

althostname

The hostname or IP address of the alternate server where the database is reconnected at failover time.

altportnumber

The port number of the alternate server where the database is reconnected at failover time.

Usage notes

All fields of the directory entry information buffer are padded to the right with blanks.

A subsequent db2DbDirGetNextEntry obtains the entry following the current entry.

If db2DbDirGetNextEntry is called when there are no more entries to scan, then SQL1014N is set in the SQLCA.

The count value returned by the db2DbDirOpenScan API can be used to scan through the entire directory by issuing db2DbDirGetNextEntry calls, one at a time, until the number of scans equals the count of entries.