DB2 - CATALOG DATABASE Command

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

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---------------------------+
                     +-KERBEROS TARGET PRINCIPAL--principalname-+
                     +-7 DATA_ENCRYPT-----------------------------+
                     +-7 DATA_ENCRYPT_CMP-------------------------+
                     '-7 GSSPLUGIN--------------------------------'

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

Command parameters

DATABASE database-name

Specifies the name of the database to catalog.

AS alias

Specifies 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/drive

On UNIX based systems, specifies the path on which the database being cataloged resides. On Windows operating systems, specifies the letter of the drive on which the database being cataloged resides.

AT NODE nodename

Specifies the name of the node 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.

AUTHENTICATION

The 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.

SERVER

Specifies that authentication takes place on the node containing the target database.

CLIENT

Specifies that authentication takes place on the node where the application is invoked.

SERVER_ENCRYPT

Specifies that authentication takes place on the node containing the target database, and that passwords are encrypted at the source. Passwords are decrypted at the target, as specified by the authentication type cataloged at the source.

KERBEROS

Specifies that authentication takes place using Kerberos Security Mechanism. When authentication is Kerberos, and an APPC connection is used for access, only SECURITY=NONE is supported.

TARGET PRINCIPAL principalname

7 Fully qualified Kerberos principal name for the target server; that is, 7 the fully qualified Kerberos principal of the DB2 instance owner in the form 7 of name/instance@REALM. For Windows 2000, Windows XP, and Windows 7 Server 2003, this is 7 the logon account of the DB2 server service in the form of userid@DOMAIN, 7 [e-mail] or domain\userid.

7 7

DATA_ENCRYPT

7

Specifies that authentication takes place on the node containing 7 the target database, and that connections must use data encryption. 7

7 7

DATA_ENCRYPT_CMP

7

Specifies that authentication takes place on the node containing 7 the target database, and that connections must use data encryption. 7 This option is provided for compatibility with downlevel products that 7 do not support data encryption, 7 in which case they will be allowed to connect with SERVER_ENCRYPT and not 7 encrypt user data. Any product that does support data encryption will 7 be forced to use it. 7

7 7

GSSPLUGIN

7

Specifies that authentication takes place using an external GSS API-based 7 plug-in security mechanism. When authentication is GSSPLUGIN, and an APPC connection is 7 used for access, only SECURITY=NONE is supported. 7

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 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.

If neither path nor node 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 node as the database manager instance are cataloged as indirect entries. Databases on other nodes 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.

Note:

If directory caching is enabled, database and node 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 might not be effective until the application has restarted.

To refresh the CLP's directory cache, use the TERMINATE command. To refresh DB2'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 reference

This topic can be found in: Command Reference.