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
- 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).
- 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"'