Stores database location information in the system database directory. The database can be located either on the local workstation or on a remote node.
Scope
This API affects the system database directory. In a partitioned database environment, when cataloging a local database into the system database directory, this API must be called from a node on the server where the database resides.
Authorization
One of the following:
Required Connection
None
Version
sqlenv.h
C API Syntax
/* File: sqlenv.h */
/* API: Catalog Database */
/* ... */
SQL_API_RC SQL_API_FN
sqlecadb (
_SQLOLDCHAR * pDbName,
_SQLOLDCHAR * pDbAlias,
unsigned char Type,
_SQLOLDCHAR * pNodeName,
_SQLOLDCHAR * pPath,
_SQLOLDCHAR * pComment,
unsigned short Authentication,
_SQLOLDCHAR * pDcePrincipal,
struct sqlca * pSqlca);
/* ... */
|
Generic API Syntax
/* File: sqlenv.h */
/* API: Catalog Database */
/* ... */
SQL_API_RC SQL_API_FN
sqlgcadb (
unsigned short DCEPrinLen,
unsigned short CommentLen,
unsigned short PathLen,
unsigned short NodeNameLen,
unsigned short DbAliasLen,
unsigned short DbNameLen,
struct sqlca * pSqlca,
_SQLOLDCHAR * pDcePrin,
unsigned short Authentication,
_SQLOLDCHAR * pComment,
_SQLOLDCHAR * pPath,
_SQLOLDCHAR * pNodeName,
unsigned char Type,
_SQLOLDCHAR * pDbAlias,
_SQLOLDCHAR * pDbName);
/* ... */
|
API Parameters
This parameter can be set to SQL_AUTHENTICATION_NOT_SPECIFIED, except when cataloging a database that resides on a DB2 Version 1 server.
Specifying the authentication type in the database catalog results in a performance improvement during a connect.
For more information about authentication types, see the Administration Guide.
On OS/2 or the Windows operating system, this string specifies the letter of the drive on which the database being cataloged resides.
If a NULL pointer is provided, the default database path is assumed to be that specified by the database manager configuration parameter dftdbpath.
| Note: | If neither pPath nor pNodeName is specified, the database is assumed to be local, and the location of the database is assumed to be that specified in the database manager configuration parameter dftdbpath. |
REXX API Syntax
CATALOG DATABASE dbname [AS alias] [ON path|AT NODE nodename] [AUTHENTICATION authentication] [WITH "comment"] |
REXX API Parameters
| Note: | If neither path nor nodename is specified, the database is assumed to be local, and the location of the database is assumed to be that specified in the database manager configuration parameter dftdbpath. |
REXX API Syntax
CATALOG GLOBAL DATABASE db_global_name AS alias
USING DIRECTORY {DCE} [WITH comment]
|
REXX API Parameters
Examples
call SQLDBS 'CATALOG GLOBAL DATABASE /.../cell1/subsys/database/DB3 AS dbtest USING DIRECTORY DCE WITH "Sample Database"'
Sample Programs
Usage Notes
Use CATALOG DATABASE to catalog databases located on local or remote nodes, recatalog databases that were uncataloged previously, or maintain multiple aliases for one database (regardless of database location).
DB2 automatically catalogs databases when they are created. It catalogs an entry for the database in the local database directory, and another entry in the system database directory. If the database is created from a remote client (or a client which is executing from a different instance on the same machine), an entry is also made in the system database directory at the client instance.
Databases created at the current instance (as defined by the value of the DB2INSTANCE environment variable) are cataloged as indirect. Databases created at other instances are cataloged as remote (even if they physically reside on the same machine).
CATALOG DATABASE automatically creates a system database directory if one does not exist. The system database directory is stored on the path that contains the database manager instance that is being used. The system database directory is maintained outside of the database. Each entry in the directory contains:
If a database is cataloged with the type parameter set to SQL_INDIRECT, the value of the authentication parameter provided will be ignored, and the authentication in the directory will be set to SQL_AUTHENTICATION_NOT_SPECIFIED.
List the contents of the system database directory using sqledosd - Open Database Directory Scan, sqledgne - Get Next Database Directory Entry, and sqledcls - Close Database Directory Scan.
If directory caching is enabled (see the configuration parameter dir_cache in sqlfxsys - Get Database Manager Configuration), database, node, and DCS directory files are cached in memory. An application's directory cache is created during its first directory lookup. Since the cache is only refreshed when the application modifies any of the directory files, directory changes made by other applications may not be effective until the application has restarted. To refresh DB2's shared cache (server only), stop (db2stop) and then restart (db2start) the database manager. To refresh the directory cache for another application, stop and then restart that application.
See Also
sqledcls - Close Database Directory Scan
sqledgne - Get Next Database Directory Entry
sqledosd - Open Database Directory Scan
sqleuncd - Uncatalog Database.