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.