COMMENTS

CHARACTER SETResponsables du traitement des données(DML)

Les objets de la base de données et la base de données elle-même peuvent contenir des annotations, ce qui constitue un outil de documentation pratique pendant le développement et la maintenance de la base de données.

`COMMENT ON`

Destination

Documentation des métadonnées.

Disponible en

DSQL, ESQL

Syntaxe

COMMENT ON <object> IS {'sometext' | NULL}
<object> ::=
    { DATABASE | SCHEMA }
  | <basic-type> objectname
  | USER username [USING PLUGIN plugin_name]
  | COLUMN relationname.fieldname
  | [PROCEDURE | FUNCTION] PARAMETER
    [package_name.] routinename.paramname
  | {PROCEDURE | [EXTERNAL] FUNCTION}
    routinename
  | [GLOBAL] MAPPING mappingname

<basic-type> ::=
    CHARACTER SET
  | COLLATION
  | DOMAIN
  | EXCEPTION
  | FILTER
  | GENERATOR
  | INDEX
  | PACKAGE
  | ROLE
  | SEQUENCE
  | TABLE
  | TRIGGER
  | VIEW

Table 1. Paramètres de l’opérateur `COMMENT ON`
Paramètre	Description
sometext	Texte du commentaire.
basic-type	Le type d’objet de métadonnées.
objectname	Le nom de l’objet de métadonnées.
relationname	Le nom d’une table ou d’une vue.
filedname	Le nom du champ d’une table ou d’une vue.
routinename	Le nom de la procédure ou de la fonction stockée.
paramname	Le nom du paramètre de la procédure ou de la fonction stockée.
package_name	Nom du paquet.
username	Nom d’utilisateur.
plugin_name	Le nom du plug-in de gestion des utilisateurs.
mappingname	Mapping Name.

L’instruction COMMENT ON ajoute des commentaires aux objets de la base de données (métadonnées). Les commentaires sont enregistrés dans les champs de texte RDB$DESCRIPTION du type BLOB de la table système correspondante (à partir de ces champs, l’application client peut visualiser les commentaires).

Lorsque vous ajoutez un commentaire pour un utilisateur, vous pouvez spécifier dans quel plugin de gestion d’utilisateur il se trouve en utilisant la phrase optionnelle USING PLUGIN. Si cette phrase est manquante, on suppose que l’utilisateur est créé dans le plugin de gestion par défaut, c’est-à-dire le premier plugin spécifié dans le paramètre UserManager du fichier firebird.conf ou databases.conf.

Note	Si vous entrez un commentaire vide (''), il sera stocké dans la base de données comme `NULL`.

Qui peut ajouter un commentaire ?

L’instruction COMMENT ON peut être exécutée :

Administrateurs.
Le propriétaire de l’objet pour lequel le commentaire est ajouté ;
Utilisateurs avec le privilège ALTER ANY <object_type>.

Exemples

Example 1. Ajout d’un commentaire pour la base de données actuelle.

COMMENT ON DATABASE IS 'Ceci est une base de données de test ('my.fdb')';

Example 2. Ajout d’un commentaire à un table.

COMMENT ON TABLE METALS IS 'Répertoire des métaux';

Example 3. Ajout d’un commentaire à un champ de table.

COMMENT ON COLUMN METALS.ISALLOY
IS '0 = métal pur, 1 = alliage';

Example 4. Ajout d’un commentaire pour un paramètre de procédure.

COMMENT ON PARAMETER ADD_EMP_PROJ.EMP_NO
IS 'Code de l'employé';

Example 5. Ajout d’un commentaire pour un paquet, ses procédures et fonctions, et leurs paramètres.

COMMENT ON PACKAGE APP_VAR IS 'Variables d'application';

COMMENT ON FUNCTION APP_VAR.GET_DATEBEGIN
IS 'Renvoie la date de début de la période';

COMMENT ON PROCEDURE APP_VAR.SET_DATERANGE
IS 'Réglage de la plage de dates';

COMMENT ON
PROCEDURE PARAMETER APP_VAR.SET_DATERANGE.ADATEBEGIN
IS 'Date de début';

Example 6. Ajout d’un commentaire pour un utilisateur.

COMMENT ON USER BOB35 IS 'C'est Bob du plug-in par défaut';

COMMENT ON USER JHON USING PLUGIN Legacy_UserManager
IS 'C''est John du plug-in Legacy_UserManager';