DB2 10.5 for Linux, UNIX, and Windows

sqlecadb API - Catalog a database in the system database directory

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

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 database partition server where the database resides.

Authorization

One of the following authorities:

SYSADM
SYSCTRL

Required connection

None

API include file

sqlenv.h

API and data structure syntax

SQL_API_RC SQL_API_FN
  sqlecadb (
        _SQLOLDCHAR * pDbName,
        _SQLOLDCHAR * pDbAlias,
        unsigned char Type,
        _SQLOLDCHAR * pNodeName,
        _SQLOLDCHAR * pPath,
        _SQLOLDCHAR * pComment,
        unsigned short Authentication,
        _SQLOLDCHAR * pPrincipal,
        struct sqlca * pSqlca);

SQL_API_RC SQL_API_FN
  sqlgcadb (
        unsigned short PrinLen,
        unsigned short CommentLen,
        unsigned short PathLen,
        unsigned short NodeNameLen,
        unsigned short DbAliasLen,
        unsigned short DbNameLen,
        struct sqlca * pSqlca,
        _SQLOLDCHAR * pPrinName,
        unsigned short Authentication,
        _SQLOLDCHAR * pComment,
        _SQLOLDCHAR * pPath,
        _SQLOLDCHAR * pNodeName,
        unsigned char Type,
        _SQLOLDCHAR * pDbAlias,
        _SQLOLDCHAR * pDbName);

sqlecadb API parameters

pDbName

Input. A string containing the database name.

pDbAlias

Input. A string containing an alias for the database.

Type

Input. A single character that designates whether the database is indirect, remote, or is cataloged via DCE. Valid values (defined in sqlenv.h) are:

SQL_INDIRECT: Specifies that the database resides at this instance.
SQL_REMOTE: Specifies that the database resides at another instance.
SQL_DCE: Specifies that the database is cataloged via DCE.

pNodeName

Input. A string containing the name of the database partition where the database is located. May be NULL.

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.

pPath

Input. A string which, on Linux and UNIX systems, specifies the name of the path on which the database being cataloged resides. Maximum length is 215 characters.

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

pComment

Input. A string containing an optional description of the database. A null string indicates no comment. The maximum length of a comment string is 30 characters.

Authentication

Input. Contains the authentication type specified for the database. Authentication is a process that verifies that the user is who he/she claims to be. Access to database objects depends on the user's authentication. Valid values (from sqlenv.h) are:

SQL_AUTHENTICATION_SERVER: Specifies that authentication takes place on the database partition server containing the target database.
SQL_AUTHENTICATION_CLIENT: Specifies that authentication takes place on the database partition server where the application is invoked.
SQL_AUTHENTICATION_KERBEROS: Specifies that authentication takes place using Kerberos Security Mechanism.
SQL_AUTHENTICATION_NOT_SPECIFIED: Authentication not specified.
SQL_AUTHENTICATION_SVR_ENCRYPT: Specifies that authentication takes place on the database partition server containing the target database, and that the authentication password is to be encrypted.
SQL_AUTHENTICATION_DATAENC: Specifies that authentication takes place on the database partition server 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.
SQL_AUTHENTICATION_SVRENC_AESO: Specifies that authentication takes place on the database partition server containing the target database, and that the authentication userid and password are to be encrypted using an Advanced Encryption Standard (AES) encryption algorithm.

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.

pPrincipal

Input. A string containing the principal name of the DB2 server on which the database resides. This value should only be specified when authentication is SQL_AUTHENTICATION_KERBEROS.

pSqlca

Output. A pointer to the sqlca structure.

sqlgcadb API-specific parameters

PrinLen: Input. A 2-byte unsigned integer representing the length in bytes of the principal name. Set to zero if no principal is provided. This value should be nonzero only when authentication is specified as SQL_AUTHENTICATION_KERBEROS.
CommentLen: Input. A 2-byte unsigned integer representing the length in bytes of the comment. Set to 0 if no comment is provided.
PathLen: Input. A 2-byte unsigned integer representing the length in bytes of the path of the local database directory. Set to 0 if no path is provided.
NodeNameLen: Input. A 2-byte unsigned integer representing the length in bytes of the node name. Set to 0 if no node name is provided.
DbAliasLen: Input. A 2-byte unsigned integer representing the length in bytes of the database alias.
DbNameLen: Input. A 2-byte unsigned integer representing the length in bytes of the database name.
pPrinName: Input. A string containing the principal name of the DB2 server on which the database resides. This value should only be specified when authentication is SQL_AUTHENTICATION_KERBEROS.

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:

Alias
Authentication type
Comment
Database
Entry type
Local database directory (when cataloging a local database)
Node name (when cataloging a remote database)
Release information

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.

If directory caching is enabled, 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 the shared cache (server only) in DB2, stop (db2stop) and then restart (db2start) the database manager. To refresh the directory cache for another application, stop and then restart that application.

REXX API syntax

CATALOG DATABASE dbname [AS alias] [ON path|AT NODE nodename]
[AUTHENTICATION authentication] [WITH "comment"]
CATALOG GLOBAL DATABASE db_global_name AS alias
USING DIRECTORY {DCE} [WITH "comment"]

REXX API parameters

dbname

Name of the database to be cataloged.

alias

Alternate name for the database. If an alias is not specified, the database name is used as the alias.

path

Path on which the database being cataloged resides.

nodename

Name of the remote workstation where the database being cataloged resides.

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.

authentication

Place where authentication is to be done. Valid values are:

SERVER: Authentication occurs at the database partition server containing the target database. This is the default.
CLIENT: Authentication occurs at the database partition server where the application is invoked.
KERBEROS: Specifies that authentication takes place using Kerberos Security Mechanism.
NOT_SPECIFIED: Authentication not specified.
SVR_ENCRYPT: Specifies that authentication takes place on the database partition server containing the target database, and that the authentication userid and password are to be encrypted.
DATAENC: Specifies that authentication takes place on the database partition server containing the target database, and that connections must use data encryption.
GSSPLUGIN: Specifies that authentication takes place using an external GSS API-based plug-in security mechanism.
SQL_AUTHENTICATION_SVRENC_AESO: Specifies that authentication takes place on the database partition server containing the target database, and that the authentication userid and password are to be encrypted using an AES encryption algorithm.

comment

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.

db_global_name

The fully qualified name that uniquely identifies the database in the DCE name space.

DCE

The global directory service being used.

REXX examples

call SQLDBS 'CATALOG GLOBAL DATABASE /.../cell1/subsys/database/DB3
AS dbtest USING DIRECTORY DCE WITH "Sample Database"'