Administrative API Reference

sqledcgd - Change Database Comment

Changes a database comment in the system database directory or the local database directory. New comment text can be substituted for text currently associated with a comment.

Scope

This API only affects the node on which it is issued.

Authorization

One of the following:

Required Connection

None

Version

sqlenv.h

C API Syntax 



/* File: sqlenv.h */
/* API: Change Database Comment */
/* ... */
SQL_API_RC SQL_API_FN
  sqledcgd (
    _SQLOLDCHAR * pDbAlias,
    _SQLOLDCHAR * pPath,
    _SQLOLDCHAR * pComment,
    struct sqlca * pSqlca);
/* ... */

Generic API Syntax 



/* File: sqlenv.h */
/* API: Change Database Comment */
/* ... */
SQL_API_RC SQL_API_FN
  sqlgdcgd (
    unsigned short CommentLen,
    unsigned short PathLen,
    unsigned short DbAliasLen,
    struct sqlca * pSqlca,
    _SQLOLDCHAR * pComment,
    _SQLOLDCHAR * pPath,
    _SQLOLDCHAR * pDbAlias);
/* ... */

API Parameters

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 parameter. Set to zero if no path is provided.

DbAliasLen
Input. A 2-byte unsigned integer representing the length in bytes of the database alias.

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

pComment
Input. A string containing an optional description of the database. A null string indicates no comment. It can also indicate no change to an existing database comment.

pPath
Input. A string containing the path on which the local database directory resides. If the specified path is a null pointer, the system database directory is used.

The comment is only changed in the local database directory or the system database directory on the node on which the API is executed. To change the database comment on all nodes, run the API on every node.

pDbAlias
Input. A string containing the database alias. This is the name that is cataloged in the system database directory, or the name cataloged in the local database directory if the path is specified.

REXX API Syntax 



CHANGE DATABASE database_alias COMMENT [ON path] WITH comment

REXX API Parameters

database_alias
Alias of the database whose comment is to be changed.

To change the comment in the system database directory, it is necessary to specify the database alias.

If the path where the database resides is specified (with the path parameter), enter the name (not the alias) of the database. Use this method to change the comment in the local database directory.

path
Path on which the database resides.

comment
Describes the entry in the system database directory or the local database directory. Any comment that helps to describe the cataloged database can be entered. 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.

Sample Programs

C
\sqllib\samples\c\dbcmt.c

COBOL
\sqllib\samples\cobol\dbcmt.cbl

REXX
\sqllib\samples\rexx\dbcmt.cmd

Usage Notes

New comment text replaces existing text. To append information, enter the old comment text, followed by the new text.

To modify an existing comment:

  1. Call sqledosd - Open Database Directory Scan
  2. Call sqledgne - Get Next Database Directory Entry to retrieve the old comment
  3. Modify the retrieved comment
  4. Call sqledcls - Close Database Directory Scan
  5. Call "sqledcgd - Change Database Comment" to replace the old text with the modified text.

Only the comment for an entry associated with the database alias is modified. Other entries with the same database name, but with different aliases, are not affected.

If the path is specified, the database alias must be cataloged in the local database directory. If the path is not specified, the database alias must be cataloged in the system database directory.

See Also

sqlecrea - Create Database

sqlecadb - Catalog Database.

[ Top of Page | Previous Page | Next Page ]