The
COMMENT statement adds or replaces comments in the catalog descriptions
of various objects.
Invocation
This statement can be embedded
in an application program or issued through the use of dynamic SQL
statements. It is an executable statement that can be dynamically
prepared only if DYNAMICRULES run behavior is in effect for the package
(SQLSTATE 42509).
Authorization
The privileges held by the
authorization ID of the statement must include at least one of the
following authorities:
- Owner of the object (underlying table for column or constraint),
as recorded in the OWNER column of the catalog view for the object
- ALTERIN privilege on the schema (applicable only to objects that
allow more than one-part names)
- CONTROL privilege on the object (applicable only to index, package,
table, or view objects)
- ALTER privilege on the object (applicable only to table objects)
- CREATE_SECURE_OBJECT authority (applicable
only to secure functions or secure triggers)
- The WITH ADMIN OPTION (applicable only to roles)
- WLMADM authority (applicable only to workload
manager objects)
- SECADM authority (applicable only to
audit policy, column mask, role, row permission, secure function,
secure trigger, security label, security label component, security
policy, or trusted context objects; also applicable to tables for
which row level access control or column level access control has
been activated)
- DBADM authority (applicable to all objects except
audit policy, role, security label, security label component, security
policy, or trusted context objects)
Note that for table space,
storage group, or database partition group, and bufferpools, the authorization
ID must have SYSCTRL or SYSADM authority.
Syntax
>>-COMMENT ON--------------------------------------------------->
>--+-| objects |--IS--string-constant---------------------------+-><
| .-,--------------------------------. |
| V | |
'-+-table-name-+--(----column-name--IS--string-constant-+--)-'
'-view-name--'
objects
|------+-| alias-designator |--------------------------------------+------|
+-AUDIT POLICY--policy-name---------------------------------+
+-COLUMN--+-table-name.column-name-+------------------------+
| '-view-name.column-name--' |
+-CONSTRAINT--table-name.constraint-name--------------------+
+-DATABASE PARTITION GROUP--db-partition-group-name---------+
+-| function-designator |-----------------------------------+
+-FUNCTION MAPPING--function-mapping-name-------------------+
+-HISTOGRAM TEMPLATE--template-name-------------------------+
| (1) |
+-INDEX--index-name-----------------------------------------+
+-MASK--mask-name-------------------------------------------+
+-MODULE--module-name---------------------------------------+
+-NICKNAME--nickname----------------------------------------+
+-PACKAGE--package-name--+-------------------------+--------+
| | .-VERSION-. | |
| '-+---------+--version-id-' |
+-PERMISSION--permission-name-------------------------------+
+-| procedure-designator |----------------------------------+
+-ROLE--role-name-------------------------------------------+
+-SCHEMA--schema-name---------------------------------------+
+-SECURITY LABEL--sec-label-name----------------------------+
+-SECURITY LABEL COMPONENT--label-comp-name-----------------+
+-SECURITY POLICY--label-pol-name---------------------------+
+-SEQUENCE--sequence-name-----------------------------------+
+-SERVER--server-name---------------------------------------+
+-SERVER OPTION--server-option-name--FOR--| remote-server |-+
+-| service-class-designator |------------------------------+
+-STOGROUP--storagegroup-name-------------------------------+
+-TABLE--+-table-name-+-------------------------------------+
| '-view-name--' |
+-TABLESPACE--tablespace-name-------------------------------+
+-THRESHOLD--threshold-name---------------------------------+
+-TRIGGER--trigger-name-------------------------------------+
+-TRUSTED CONTEXT--context-name-----------------------------+
+-TYPE--type-name-------------------------------------------+
+-TYPE MAPPING--type-mapping-name---------------------------+
+-USAGE LIST--usage-list-name-------------------------------+
+-VARIABLE--variable-name-----------------------------------+
+-WORK ACTION SET--work-action-set-name---------------------+
+-WORK CLASS SET--work-class-set-name-----------------------+
+-WORKLOAD--workload-name-----------------------------------+
+-WRAPPER--wrapper-name-------------------------------------+
'-XSROBJECT--xsrobject-name---------------------------------'
alias-designator
.-FOR TABLE----.
|----+--------+--ALIAS--alias-name--+--------------+------------|
'-PUBLIC-' +-FOR MODULE---+
'-FOR SEQUENCE-'
function-designator
|--+-FUNCTION--function-name--+-------------------------+-+-----|
| '-(--+---------------+--)-' |
| | .-,---------. | |
| | V | | |
| '---data-type-+-' |
'-SPECIFIC FUNCTION--specific-name---------------------'
procedure-designator
|--+-PROCEDURE--procedure-name--+-------------------------+-+---|
| '-(--+---------------+--)-' |
| | .-,---------. | |
| | V | | |
| '---data-type-+-' |
'-SPECIFIC PROCEDURE--specific-name----------------------'
remote-server
|--+-SERVER--server-name------------------------------------------------------------------+--|
'-SERVER TYPE--server-type--+--------------------------------------------------------+-'
'-VERSION--| server-version |--+-----------------------+-'
'-WRAPPER--wrapper-name-'
server-version
|--+-version--+------------------------+-+----------------------|
| '-.--release--+--------+-' |
| '-.--mod-' |
'-version-string-constant-------------'
service-class-designator
|----SERVICE CLASS--service-class-name--+--------------------------------+----|
'-UNDER--service-superclass-name-'
Notes:
- Index-name can be the name of either
an index or an index specification.
Description
- alias-designator
- ALIAS alias-name
- Indicates a comment will be added or replaced for an alias. The alias-name must
identify an alias that exists at the current server (SQLSTATE 42704).
- FOR TABLE, FOR MODULE, or FOR SEQUENCE
- Specifies the object type for the alias.
- FOR TABLE
- The alias is for a table, view, or nickname. The comment replaces
the value of the REMARKS column of the SYSCAT.TABLES catalog view
for the row that describes the alias.
- FOR MODULE
- The alias is for a module. The comment replaces the value of the
REMARKS column of the SYSCAT.MODULES catalog view for the row that
describes the alias.
- FOR SEQUENCE
- The alias is for a sequence. The comment replaces the value of
the REMARKS column of the SYSCAT.SEQUENCES catalog view for the row
that describes the alias.
If PUBLIC is specified, the alias-name must
identify a public alias that exists at the current server (SQLSTATE
42704).
- AUDIT POLICY policy-name
- Indicates a comment will be added or replaced for an audit policy.
The policy-name must identify an audit policy
that exists at the current server (SQLSTATE 42704). The comment
replaces the value of the REMARKS column of the SYSCAT.AUDITPOLICIES
catalog view for the row that describes the audit policy.
- COLUMN table-name.column-name or view-name.column-name
- Indicates that a comment for a column will be added or replaced.
The table-name.column-name or view-name.column-name combination
must identify a column and table combination that exists at the current
server (SQLSTATE 42704), but must not identify a global temporary
table (SQLSTATE 42995). The comment replaces the value of the REMARKS
column of the SYSCAT.COLUMNS catalog view for the row that describes
the column.
- CONSTRAINT table-name.constraint-name
- Indicates a comment will be added or replaced for a constraint.
The table-name.constraint-name combination
must identify a constraint and the table that it constrains; they
must exist at the current server (SQLSTATE 42704). The comment replaces
the value of the REMARKS column of the SYSCAT.TABCONST catalog view
for the row that describes the constraint.
- DATABASE PARTITION GROUP db-partition-group-name
- Indicates a comment will be added or replaced for a database partition
group. The db-partition-group-name must
identify a distinct database partition group that exists at the current
server (SQLSTATE 42704). The comment replaces the value for the REMARKS
column of the SYSCAT.DBPARTITIONGROUPS catalog view for the row that
describes the database partition group.
- function-designator
- Indicates
a comment will be added or replaced for a function. For more information,
see Function, method, and procedure designators.
It
is not possible to comment on a function that is in the SYSIBM, SYSIBMADM,
SYSFUN, or SYSPROC schema (SQLSTATE 42832).
The comment replaces
the value of the REMARKS column of the SYSCAT.ROUTINES catalog view
for the row that describes the function.
- FUNCTION MAPPING function-mapping-name
- Indicates a comment will be added or replaced for a function mapping.
The function-mapping-name must identify
a function mapping that exists at the current server (SQLSTATE 42704).
The comment replaces the value for the REMARKS column of the SYSCAT.FUNCMAPPINGS
catalog view for the row that describes the function mapping.
- HISTOGRAM TEMPLATE template-name
- Indicates a comment will be added or replaced for a histogram
template. The template-name must identify
a histogram template that exists at the current server (SQLSTATE 42704).
The comment replaces the value for the REMARKS column of the SYSCAT.HISTOGRAMTEMPLATES
catalog view for the row that describes the histogram template.
- INDEX index-name
- Indicates a comment will be added or replaced for an index or
index specification. The index-name must
identify either a distinct index or an index specification that exists
at the current server (SQLSTATE 42704). The comment replaces the value
for the REMARKS column of the SYSCAT.INDEXES catalog view for the
row that describes the index or index specification.
- MASK mask-name
- Identifies the column mask to which the comment applies. mask-name must
identify a column mask that exists at the current server (SQLSTATE
42704). The comment is placed in the REMARKS column of the SYSCAT.CONTROLS
catalog table for the row that describes the mask.
- MODULE module-name
- Indicates a comment will be added or
replaced for a module. The module-name must identify a module that exists
at the current server (SQLSTATE 42704). The specified name must not be an alias for a module
(SQLSTATE 560CT). The comment replaces the value for the REMARKS column of the SYSCAT.MODULES
catalog view for the row that describes the module.
- NICKNAME nickname
- Indicates a comment will be added or replaced for a nickname.
The nickname must be a nickname that exists
at the current server (SQLSTATE 42704). The comment replaces the value
for the REMARKS column of the SYSCAT.TABLES catalog view for the row
that describes the nickname.
- PACKAGE
package-name
- Indicates that a comment will be added or replaced for a package. The package
name must identify a package that exists at the current server (SQLSTATE 42704). The comment
replaces the value for the REMARKS column of the SYSCAT.PACKAGES catalog view for the row that
describes the package.
- VERSION version-id
- Identifies which package version is to be commented on. If a value
is not specified, the version defaults to the empty string. If multiple
packages with the same package name but different versions exist,
only one package version can be commented on in one invocation of
the COMMENT statement. Delimit the version identifier with double
quotation marks when it:
- Is generated by the VERSION(AUTO) precompiler option
- Begins with a digit
- Contains lowercase or mixed-case letters
If the statement is invoked from an operating system command
prompt, precede each double quotation mark delimiter with a back slash
character to ensure that the operating system does not strip the delimiters.
- PERMISSION permission-name
- Identifies the row permission to which the comment applies. permission-name must
identify a row permission that exists at the current server (SQLSTATE
42704, SQLCODE -204). The comment is placed in the REMARKS column
of the SYSCAT.CONTROLS catalog table for the row that describes the
permission.
- procedure-designator
- Indicates
a comment will be added or replaced for a procedure. For more information,
see Function, method, and procedure designators.
It
is not possible to comment on a procedure that is in the SYSIBM, SYSIBMADM,
SYSFUN, or SYSPROC schema (SQLSTATE 42832).
The comment replaces
the value of the REMARKS column of the SYSCAT.ROUTINES catalog view
for the row that describes the procedure.
- ROLE role-name
- Indicates a comment will be added or replaced for a role. The role-name must
identify a role that exists at the current server (SQLSTATE 42704).
The comment replaces the value of the REMARKS column of the SYSCAT.ROLES
catalog view for the row that describes the role.
- SCHEMA schema-name
- Indicates a comment will be added or replaced for a schema. The schema-name must
identify a schema that exists at the current server (SQLSTATE 42704).
The comment replaces the value of the REMARKS column of the SYSCAT.SCHEMATA
catalog view for the row that describes the schema.
- SECURITY LABEL sec-label-name
- Indicates that a comment will be added or replaced for the security
label named sec-label-name. The name
must be qualified with a security policy and must identify a security
label that exists at the current server (SQLSTATE 42704). The
comment replaces the value for the REMARKS column of the SYSCAT.SECURITYLABELS
catalog view for the row that describes the security label.
- SECURITY LABEL COMPONENT label-comp-name
- Indicates that a comment will be added or replaced for the security
label component named label-comp-name. The label-comp-name must
identify a security label component that exists at the current server
(SQLSTATE 42704). The comment replaces the value for the REMARKS
column of the SYSCAT.SECURITYLABELCOMPONENTS catalog view for the
row that describes the security label component.
- SECURITY POLICY label-pol-name
- Indicates that a comment will be added or replaced for the security
policy named label-pol-name. The label-pol-name must
identify a security policy that exists at the current server (SQLSTATE
42704). The comment replaces the value for the REMARKS column
of the SYSCAT.SECURITYPOLICIES catalog view for the row that describes
the security policy.
- SEQUENCE sequence-name
- Indicates a comment will be added or replaced for a sequence.
The sequence-name must identify a sequence
that exists at the current server (SQLSTATE 42704). The comment replaces
the value for the REMARKS column of the SYSCAT.SEQUENCES catalog view
for the row that describes the sequence.
- SERVER server-name
- Indicates a comment will be added or replaced for a data source.
The server-name must identify a data source
that exists at the current server (SQLSTATE 42704). The comment replaces
the value for the REMARKS column of the SYSCAT.SERVERS catalog view
for the row that describes the data source.
- SERVER OPTION server-option-name FOR remote-server
- Indicates a comment will be added or replaced for a server option.
- server-option-name
- Identifies a server option. This option must be one that exists
at the current server (SQLSTATE 42704). The comment replaces the value
for the REMARKS column of the SYSCAT.SERVEROPTIONS catalog view for
the row that describes the server option.
- remote-server
- Describes the data source to which the server-option applies.
- SERVER server-name
- Names the data source to which the server-option applies.
The server-name must identify a data source
that exists at the current server.
- TYPE server-type
- Specifies the type of data source
(such as DB2® for z/OS® or Oracle) to
which the server-option applies. The server-type
can be specified in either lower- or uppercase; it will be stored in uppercase in the catalog.
- VERSION
- Specifies the version of the data source identified by server-name.
- version
- Specifies the version number. version must
be an integer.
- release
- Specifies the number of the release of the version denoted by version. release must
be an integer.
- mod
- Specifies the number of the modification of the release denoted
by release. mod must
be an integer.
- version-string-constant
- Specifies the complete designation of the version. The version-string-constant can
be a single value (for example, '8i'); or it can be the concatenated
values of version, release,
and, if applicable, mod (for example, '8.0.3').
- WRAPPER wrapper-name
- Identifies the wrapper that is used to access the data source
referenced by server-name.
- service-class-designator
- SERVICE CLASS service-class-name
- Indicates a comment will be added or replaced for a service class.
The service-class-name must identify a service
class that exists at the current server (SQLSTATE 42704). To add or
replace a comment for a service subclass, the service-superclass-name must
be specified using the UNDER clause. The comment replaces the value
for the REMARKS column of the SYSCAT.SERVICECLASSES catalog view for
the row that describes the service class.
- UNDER service-superclass-name
- Specifies the service superclass of the service subclass when
adding or replacing a comment for a service subclass. The service-superclass-name must
identify a service superclass that exists at the current server (SQLSTATE
42704).
- STOGROUP storagegroup-name
- Indicates a comment will be added or replaced for a storage group.
The storagegroup-name must identify a distinct
storage group that exists at the current server (SQLSTATE 42704).
The comment replaces the value for the REMARKS column of the SYSCAT.STOGROUPS
catalog view for the row that describes the storage group.
- TABLE table-name or view-name
- Indicates a comment will be added or replaced for a table or view.
The table-name or view-name must
identify a table or view (not an alias or nickname) that exists at
the current server (SQLSTATE 42704) and must not identify a declared
temporary table (SQLSTATE 42995). The comment replaces the value for
the REMARKS column of the SYSCAT.TABLES catalog view for the row that
describes the table or view.
- TABLESPACE tablespace-name
- Indicates a comment will be added or replaced for a table space.
The tablespace-name must identify a distinct
table space that exists at the current server (SQLSTATE 42704). The
comment replaces the value for the REMARKS column of the SYSCAT.TABLESPACES
catalog view for the row that describes the table space.
- THRESHOLD threshold-name
- Indicates a comment will be added or replaced for a threshold.
The threshold-name must identify a threshold
that exists at the current server (SQLSTATE 42704). The comment replaces
the value for the REMARKS column of the SYSCAT.THRESHOLDS catalog
view for the row that describes the threshold.
- TRIGGER trigger-name
- Indicates a comment will be added or replaced for a trigger. The trigger-name must
identify a distinct trigger that exists at the current server (SQLSTATE
42704). The comment replaces the value for the REMARKS column of the
SYSCAT.TRIGGERS catalog view for the row that describes the trigger.
- TRUSTED CONTEXT context-name
- Indicates a comment will be added or replaced for a trusted context.
The context-name must identify a trusted
context that exists at the current server (SQLSTATE 42704). The
comment replaces the value for the REMARKS column of the SYSCAT.CONTEXTS
catalog view for the row that describes the trusted context.
- TYPE type-name
- Indicates a comment will be added or replaced for a user-defined
type. The type-name must identify a user-defined
type that exists at the current server (SQLSTATE 42704). The comment
replaces the value of the REMARKS column of the SYSCAT.DATATYPES catalog
view for the row that describes the user-defined type.
In dynamic
SQL statements, the CURRENT SCHEMA special register is used as a qualifier
for an unqualified object name. In static SQL statements the QUALIFIER
precompile/bind option implicitly specifies the qualifier for unqualified
object names.
- TYPE MAPPING type-mapping-name
- Indicates a comment will be added or replaced for a user-defined
data type mapping. The type-mapping-name must
identify a data type mapping that exists at the current server (SQLSTATE
42704). The comment replaces the value for the REMARKS column of the
SYSCAT.TYPEMAPPINGS catalog view for the row that describes the mapping.
- USAGE LIST usage-list-name
- Indicates
a comment will be added or replaced for a usage list. The usage-list-name must
identify a usage list that exists at the current server (SQLSTATE
42704). The comment replaces the value for the REMARKS column of the
SYSCAT.USAGELISTS catalog view for the row that describes the usage
list.
- VARIABLE variable-name
- Indicates a comment will be added or replaced for a global variable.
The variable-name must identify a global
variable that exists at the current server (SQLSTATE 42704). The comment
replaces the value for the REMARKS column of the SYSCAT.VARIABLES
catalog view for the row that describes the variable.
- WORK ACTION SET work-action-set-name
- Indicates a comment will be added or replaced for a work action
set. The work-action-set-name must identify
a work action set that exists at the current server (SQLSTATE 42704).
The comment replaces the value for the REMARKS column of the SYSCAT.WORKACTIONSETS
catalog view for the row that describes the work action set.
- WORK CLASS SET work-class-set-name
- Indicates a comment will be added or replaced for a work class
set. The work-class-set-name must identify
a work class set that exists at the current server (SQLSTATE 42704).
The comment replaces the value for the REMARKS column of the SYSCAT.WORKCLASSSETS
catalog view for the row that describes the work class set.
- WORKLOAD workload-name
- Indicates that a comment will be added or replaced for a workload.
The workload-name must identify a workload
that exists at the current server (SQLSTATE 42704). The comment
replaces the value for the REMARKS column of the SYSCAT.WORKLOADS
catalog view for the row that describes the workload.
- WRAPPER wrapper-name
- Indicates a comment will be added or replaced for a wrapper. The wrapper-name must
identify a wrapper that exists at the current server (SQLSTATE 42704).
The comment replaces the value for the REMARKS column of the SYSCAT.WRAPPERS
catalog view for the row that describes the wrapper.
- XSROBJECT xsrobject-name
- Indicates a comment will be added or replaced for an XSR object.
The xsrobject-name must identify an XSR
object that exists at the current server (SQLSTATE 42704). The comment
replaces the value for the REMARKS column of the SYSCAT.XSROBJECTS catalog
view for the row that describes the XSR object.
- IS string-constant
- Specifies the comment to be added or replaced. The string-constant can
be any character string constant of up to 254 bytes. (Carriage return
and line feed each count as 1 byte.)
- table-name|view-name (
{ column-name IS string-constant }
... )
- This form of the COMMENT statement provides the ability to specify
comments for multiple columns of a table or view. The column names
must not be qualified, each name must identify a column of the specified
table or view, and the table or view must exist at the current server.
The table-name cannot be a declared temporary
table (SQLSTATE 42995).
A comment cannot be made on a column of
an inoperative view (SQLSTATE 51024).
Notes
- Syntax alternatives: The following syntax alternatives are supported for
compatibility with previous versions of DB2 and with other
database products. These alternatives are non-standard and should not be used.
- NODEGROUP can be specified in place of DATABASE PARTITION GROUP
- DISTINCT TYPE type-name can be specified in place of TYPE
type-name
- DATA TYPE type-name can be specified in place of TYPE
type-name
- SYNONYM can be specified in place of ALIAS
Examples
- Example 1: Add a comment for the EMPLOYEE table.
COMMENT ON TABLE EMPLOYEE
IS 'Reflects first quarter reorganization'
- Example 2: Add a comment for the EMP_VIEW1 view.
COMMENT ON TABLE EMP_VIEW1
IS 'View of the EMPLOYEE table without salary information'
- Example 3: Add a comment for the EDLEVEL column of the
EMPLOYEE table.
COMMENT ON COLUMN EMPLOYEE.EDLEVEL
IS 'highest grade level passed in school'
- Example 4: Add comments for two different columns of the
EMPLOYEE table.
COMMENT ON EMPLOYEE
(WORKDEPT IS 'see DEPARTMENT table for names',
EDLEVEL IS 'highest grade level passed in school' )
- Example 5: Pellow wants to comment on the CENTRE function,
which he created in his PELLOW schema, using the signature to identify
the specific function to be commented on.
COMMENT ON FUNCTION CENTRE (INT,FLOAT)
IS 'Frank''s CENTRE fctn, uses Chebychev method'
- Example 6: McBride wants to comment on another CENTRE
function, which she created in the PELLOW schema, using the specific
name to identify the function instance to be commented on:
COMMENT ON SPECIFIC FUNCTION PELLOW.FOCUS92 IS
'Louise''s most triumphant CENTRE function, uses the
Brownian fuzzy-focus technique'
- Example 7: Comment on the function ATOMIC_WEIGHT in the
CHEM schema, where it is known that there is only one function with
that name:
COMMENT ON FUNCTION CHEM.ATOMIC_WEIGHT
IS 'takes atomic nbr, gives atomic weight'
- Example 8: Eigler wants to comment on the SEARCH procedure,
which he created in his EIGLER schema, using the signature to identify
the specific procedure to be commented on.
COMMENT ON PROCEDURE SEARCH (CHAR,INT)
IS 'Frank''s mass search and replace algorithm'
- Example 9: Macdonald wants to comment on another SEARCH
function, which he created in the EIGLER schema, using the specific
name to identify the procedure instance to be commented on:
COMMENT ON SPECIFIC PROCEDURE EIGLER.DESTROY IS
'Patrick''s mass search and destroy algorithm'
- Example 10: Comment on the procedure OSMOSIS in the BIOLOGY
schema, where it is known that there is only one procedure with that
name:
COMMENT ON PROCEDURE BIOLOGY.OSMOSIS
IS 'Calculations modelling osmosis'
- Example 11: Comment on an index specification named INDEXSPEC.
COMMENT ON INDEX INDEXSPEC
IS 'An index specification that indicates to the optimizer
that the table referenced by nickname NICK1 has an index.'
- Example 12: Comment on the wrapper whose default name is
NET8.
COMMENT ON WRAPPER NET8
IS 'The wrapper for data sources associated with
Oracle's Net8 client software.'
- Example 13: Create a comment on the XML schema HR.EMPLOYEE.
COMMENT ON XSROBJECT HR.EMPLOYEE
IS 'This is the base XML Schema for employee data.'
- Example 14: Create a comment for trusted context APPSERVER.
COMMENT ON TRUSTED CONTEXT APPSERVER
IS 'WebSphere Server'
- Example 15: Create a comment
for column mask M1.
COMMENT ON MASK M1 IS 'Column mask for column EMP.SALARY'