CATALOG DATABASE command

CATALOG DATABASE command

( DB2 Version 9.7 for Linux, UNIX, and Windows)

Stores database location information in the system database directory. The database can be located either on the local workstation or on a remote database partition server.

Scope

In a partitioned database environment, when cataloging a local database into the system database directory, this command must be issued from a database partition on the server where the database resides.

Authorization

One of the following:
SYSADM
SYSCTRL

Required connection

None. Directory operations affect the local directory only.

Command syntax

>>-CATALOG--+-DATABASE-+--database-name--+-----------+---------->
            '-DB-------'                 '-AS--alias-'   

>--+-------------------+---------------------------------------->
   +-ON--+-path--+-----+   
   |     '-drive-'     |   
   '-AT NODE--nodename-'   

>--+--------------------------------------------------------------+-->
   '-AUTHENTICATION--+-SERVER-----------------------------------+-'   
                     +-CLIENT-----------------------------------+     
                     +-SERVER_ENCRYPT---------------------------+     
                     +-SERVER_ENCRYPT_AES-----------------------+     
                     +-KERBEROS TARGET PRINCIPAL--principalname-+     
                     +-DATA_ENCRYPT-----------------------------+     
                     '-GSSPLUGIN--------------------------------'     

>--+------------------------+----------------------------------><
   '-WITH--"comment-string"-'   

Command parameters

DATABASE database-nameSpecifies the name of the database to catalog.
AS aliasSpecifies an alias as an alternate name for the database being cataloged. If an alias is not specified, the database manager uses database-name as
the alias.
ON path | driveSpecifies the path on which the database being cataloged resides. On Windows operating systems, may instead specify the letter of the drive on which the database being cataloged resides (if it was created on a drive, not
on a specific path).
AT NODE nodenameSpecifies the name of the database partition server where the database being cataloged resides. This name should match the name of an entry in the node directory. If the node name specified does not exist in the node directory,
a warning is returned, but the database is cataloged in the system database directory. The node name should be cataloged in the node directory if a connection to the cataloged database is desired.
AUTHENTICATIONThe authentication value is stored for remote databases (it appears in the output from the LIST DATABASE DIRECTORY command) but it is not stored for local databases.
Specifying an authentication type can result in a performance benefit.

SERVERSpecifies that authentication takes place on the database partition server containing the target database.
CLIENTSpecifies that authentication takes place on the database partition server where the application is invoked.
SERVER_ENCRYPTSpecifies that authentication takes place on the database partition server containing the target database, and that user IDs and passwords are encrypted at the source. User IDs and passwords are decrypted at the target,
as specified by the authentication type cataloged at the source.
KERBEROSSpecifies that authentication takes place using Kerberos Security Mechanism.

TARGET PRINCIPAL principalnameFully qualified Kerberos principal name for the target server; that is, the fully qualified Kerberos principal of the DB2® instance owner in the form ofname/instance@REALM.
For Windows 2000, Windows XP, and Wi
4000
ndows Server 2003, this is the logon account of the DB2 server service in the form of userid@DOMAIN, userid@xxx.xxx.xxx.com or domain\userid.
DATA_ENCRYPTSpecifies that authentication takes place on the database partition server containing the target database, and that connections must use data encryption.
GSSPLUGINSpecifies that authentication takes place using an external GSS API-based plug-in security mechanism.
SERVER_ENCRYPT_AESSpecifies that authentication takes place on the database partition server containing the target database, and that user IDs and passwords are encrypted with an Advanced Encryption Standard (AES) encryption algorithm at
the source and decrypted at the target.
WITH "comment-string"Describes the database or the database entry in the system database directory. The maximum length of a comment string is 30 characters. A carriage return or a line feed character is not permitted. The comment text must
be enclosed by double quotation marks.

Examples

db2 catalog database sample on /databases/sample
with "Sample Database"

Usage notes

Use CATALOG DATABASE to catalog databases located on local or remote database partition servers, 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 thesystem
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.
If neither path nor database partition server name 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.
Databases on the same database partition server as the database manager instance are cataloged as indirect entries. Databases on other database
partition servers are cataloged as remote entries.
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, and is maintained outside of the database.
List the contents of the system database directory using the LIST DATABASE DIRECTORY command. To list the contents of the local database
directory use the LIST DATABASE DIRECTORY ON path,
where path is where the database was created.
If directory caching is enabled, database, node and DCS directory files are cached in memory. To see if directory caching is enabled, check the value for thedir_cache directory
cache support configuration parameter in the output from the GET DATABASE MANAGER CONFIGURATION command. 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 might not be effective until the application has restarted.
To refresh the CLP's directory cache, use the TERMINATE command. To refresh the database manager's shared cache, stop (db2stop)
and then restart (db2start) the database manager. To refresh the directory cache for another application, stop and then restart that application.

Related tasks:
Cataloging databases

Related reference:
GET DATABASE MANAGER CONFIGURATION command
LIST DATABASE DIRECTORY command
sqlecadb API - Catalog a database in the system database
directory
TERMINATE command
UNCATALOG DATABASE command


 Reference topic