API Reference
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.
Authorization
One of the following:
- sysadm
- sysctrl
Required Connection
None
API Include File
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 * pDcePrincipal,
struct sqlca * pSqlca);
/* ... */
|
Generic API Syntax
/* File: sqlenv.h */
/* API: Catalog Database */
/* ... */
SQL_API_RC SQL_API_FN
sqlgcadb (
unsigned short DCEPrinLen,
unsigned short CommentLen,
unsigned short PathLen,
unsigned short NodeNameLen,
unsigned short DbAliasLen,
unsigned short DbNameLen,
struct sqlca * pSqlca,
_SQLOLDCHAR * pDcePrin,
unsigned short Authentication,
_SQLOLDCHAR * pComment,
_SQLOLDCHAR * pPath,
_SQLOLDCHAR * pNodeName,
unsigned char Type,
_SQLOLDCHAR * pDbAlias,
_SQLOLDCHAR * pDbName);
/* ... */
|
API Parameters
- DCEPrinLen
- Input. A 2-byte unsigned integer representing the length in bytes of the
DCE principal. Set to zero if no principal is provided. This value should be
nonzero only when authentication is specified as
SQL_AUTHENTICATION_DCE.
- 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.
- pDcePrin
- Input. A string containing the DCE principal name of the DB2 server on
which the database resides. This value should only be specified when
authentication is SQL_AUTHENTICATION_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 DDCS, 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_NOT_SPECIFIED
- Authentication not specified.
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.
CATALOG DATABASE - 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
DDCS. The behavior is the same as for the type SERVER, except that
when the authentication type is SERVER, DDCS 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.
CATALOG GLOBAL DATABASE - 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.
Example
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
- FORTRAN
- \sqllib\samples\fortran\dbcat.f
- 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:
- 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.
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
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
[ DB2 List of Books |
Search the DB2 Books ]