DB2 10.5 for Linux, UNIX, and Windows

COMMENT statement

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'