Administrative API Reference

sqlecadb - Catalog Database

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 * pPrincipal,
    struct sqlca * pSqlca);
/* ... */

Generic API Syntax 



/* File: sqlenv.h */
/* API: Catalog Database */
/* ... */
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);
/* ... */

API 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_DCE or SQL_AUTHENTICATION_KERBEROS.

CommentLen
Input. A 2-byte unsigned integer representing the length in bytes of the comment. Set to zero 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 zero if no path is provided.

NodeNameLen
Input. A 2-byte unsigned integer representing the length in bytes of the node name. Set to zero 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.

pSqlca
Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

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_DCE or SQL_AUTHENTICATION_KERBEROS. For DCE, the principal must be the same as the value stored in the server's keytab file.

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) are:

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

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

SQL_AUTHENTICATION_DCS
Specifies that authentication takes place on the node containing the target database, except when using DB2 Connect, when it specifies that authentication takes place at the DRDA AS.

SQL_AUTHENTICATION_DCE
Specifies that authentication takes place using DCE Security Services.

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 node containing the target database, and that the authentication password is to be encrypted.

SQL_AUTHENTICATION_DCS_ENCRYPT
Specifies that authentication takes place on the node containing the target database except when using DB2 Connect, in which case authentication takes place at the DRDA AS. Also, the authentication password is to be encrypted.

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.

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.

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

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.

pNodeName
Input. A string containing the name of the node 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.

Type
Input. A single character that designates whether the database is indirect, remote, or is cataloged via DCE. Valid values (defined in sqlenv) 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.

pDbAlias
Input. A string containing an alias for the database.

pDbName
Input. A string containing the database name.

REXX API Syntax 



CATALOG DATABASE dbname [AS alias] [ON path|AT NODE nodename]
[AUTHENTICATION authentication] [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 node containing the target database. This is the default.

CLIENT
Authentication occurs at the node where the application is invoked.

DCS
Specifies how authentication will take place for databases accessed using DB2 Connect. The behavior is the same as for the type SERVER, except that when the authentication type is SERVER, DB2 Connect forces authentication at the gateway, and when the authentication type is DCS, authentication is assumed to take place at the host.

DCE SERVER PRINCIPAL dce_principal_name
Fully qualified DCE principal name for the target server. This value is also recorded in the keytab file at the target server.

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.

REXX API Syntax 



CATALOG GLOBAL DATABASE db_global_name AS alias
USING DIRECTORY {DCE} [WITH comment]

REXX API Parameters

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

alias
Alternate name for the database.

DCE
The global directory service being used.

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.

Examples 

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

Sample Programs

C
\sqllib\samples\c\dbcat.c

COBOL
\sqllib\samples\cobol\dbcat.cbl

REXX
\sqllib\samples\rexx\dbcat.cmd

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.

[ Top of Page | Previous Page | Next Page ]