PACKAGE

Un package est un groupe de procédures et de fonctions qui représentent un seul objet de base de données.

Les packages Firebird se composent de deux parties : l’en-tête (mot-clé PACKAGE) et le corps (mot-clé PACKAGE BODY). Cette séparation est très similaire aux modules Delphi, l’en-tête correspond à la partie interface, et le corps à la partie implémentation.

Il faut d’abord créer un en-tête CREATE PACKAGE, puis un corps. (CREATE PACKAGE BODY).

`CREATE PACKAGE`

affectation

Création d’un en-tête de package.

Disponible en

DSQL

Syntaxe

CREATE PACKAGE package_name
[<rights clause>]
AS
BEGIN
  [<package_item> ...]
END

<rights clause> ::=
  SQL SECURITY {DEFINER | INVOKER}

<package_item> ::=
    <function_decl>;
  | <procedure_decl>;

<function_decl> ::=
  FUNCTION func_name [(<in_params>)]
  RETURNS <type> [NOT NULL] [COLLATE collation]
  [DETERMINISTIC]

<procedure_decl> ::=
  PROCEDURE proc_name [(<in_params>)]
  [RETURNS (<out_params>)]

<in_params> ::= <inparam> [, <inparam> ...]

<inparam> ::= <param_decl> [{= | DEFAULT} <value>]

<value> ::=  {literal | NULL | context_var}

<out_params> ::= <outparam> [, <outparam> ...]

<outparam>  ::=  <param_decl>

<param_decl> ::= paramname <type> [NOT NULL] [COLLATE collation]

<type> ::= <datatype> | [TYPE OF] domain_name | TYPE OF COLUMN rel.col

<datatype> ::=
    <scalar_datatype> | <blob_datatype>

<scalar_datatype> ::= Voir Syntaxe des types de données scalaires.

<blob_datatype> ::= Voir Syntaxe du type de données BLOB.

Table 1. Paramètres de la fonction`CREATE PACKAGE`
Paramètre	Description
package_name	Le nom du package, qui peut comporter jusqu’à 63 caractères.
function_decl	Déclaration de fonction.
procedure_decl	Déclaration de la procédure.
proc_name	Nom de la procédure, pouvant contenir jusqu’à 63 caractères.
func_name	Nom de la fonction. Peut contenir jusqu’à 63 caractères.
inparam	Description du paramètre d’entrée.
outparam	Description du paramètre de sortie.
literal	Un littéral dont le type est compatible avec le paramètre.
context_var	Toute variable contextuelle dont le type est compatible avec celui du paramètre.
paramname	Nom du paramètre d’entrée ou de sortie de la procédure/fonction. Peut contenir jusqu’à 63 caractères. Le nom du paramètre doit être unique parmi les paramètres d’entrée et de sortie de la procédure/fonction, ainsi que ses variables locales.
datatype	Type de données SQL.
collation	Ordre de tri.Ordre de tri.
domain_name	Nom de domaine.
rel	Le nom d’une table ou d’une vue.
col	Le nom de la colonne de la table ou de la vue.

L’instruction CREATE PACKAGE crée un nouvel en-tête de paquetage. Le nom du paquetage doit être unique parmi tous les noms de paquetage.

Les procédures et les fonctions déclarées dans l’en-tête du paquet sont disponibles en dehors du corps du paquet via l’identifiant complet du nom de la procédure et de la fonction (package_name.procedure_name et package_name.function_name). Les procédures et les fonctions définies dans le corps du paquet, mais non déclarées dans l’en-tête du paquet, ne sont pas visibles en dehors du corps du paquet.

Les noms de procédures et de fonctions déclarés dans l’en-tête du paquet doivent être uniques parmi les noms de procédures et de fonctions déclarés dans l’en-tête et le corps du paquet.

Note

Il est préférable que les noms des procédures stockées et des fonctions du paquetage ne se chevauchent pas avec les noms des procédures stockées et des fonctions de l’espace de noms global, bien que cela soit acceptable. Le fait est que vous ne pouvez actuellement pas appeler une fonction/procédure de l’espace de noms global à l’intérieur d’un paquetage si une fonction/procédure du même nom est déclarée dans le paquetage.

Privilèges d’exécution

La clause optionnelle SQL SECURITY vous permet de spécifier avec quels privilèges les procédures et fonctions du package sont exécutées. Si INVOKER est sélectionné, alors les procédures et fonctions du package sont exécutées avec les privilèges de l’utilisateur appelant. Si DEFINER est sélectionné, alors les procédures et fonctions du package sont exécutées avec les privilèges de l’utilisateur définissant (propriétaire du package). Ces privilèges s’ajoutent aux privilèges accordés au paquet lui-même à l’aide de l’opérateur GRANT. Par défaut, les procédures et les fonctions du paquet sont exécutées avec les privilèges de l’utilisateur appelant. Il n’est pas possible de remplacer les privilèges d’exécution des procédures et des fonctions du paquet.

Tip	Les privilèges d’exécution par défaut pour les objets de métadonnées nouvellement créés peuvent être modifiés à l’aide de la commande ALTER DATABASE SET DEFAULT SQL SECURITY {DEFINER \| INVOKER}

Opérateur de terminaison

Certains éditeurs d’instructions SQL — notamment l’utilitaire isql de la suite Firebird, et peut-être certains éditeurs tiers — utilisent une convention interne qui exige que toutes les instructions soient terminées par un point-virgule.

Cela crée un conflit avec la syntaxe PSQL lors du codage dans ces environnements. Si vous n’êtes pas familier avec ce problème et sa solution, veuillez étudier les détails dans le chapitre PSQL dans la section intitulée Changing the terminator in isql.

Paramètres des procédures et des fonctions

Le type de données est spécifié pour chaque paramètre. Il est également possible de spécifier une restriction NOT NULL pour un paramètre, interdisant ainsi de lui passer une valeur NULL.

Pour un paramètre de type chaîne, il est possible de spécifier l’ordre de tri en utilisant la phrase COLLATE.

Paramètres d’entrée

Les paramètres d’entrée sont placés entre parenthèses après le nom de la procédure enregistrée. Ils sont transmis à la procédure par valeur, c’est-à-dire que toute modification des paramètres d’entrée dans la procédure n’aura aucun effet sur les valeurs de ces paramètres dans le programme appelant.

Les paramètres d’entrée peuvent avoir une valeur par défaut. Les paramètres pour lesquels des valeurs sont définies doivent être placés à la fin de la liste des paramètres.

Paramètres de sortie

Pour les procédures stockées, la liste des paramètres de sortie est spécifiée dans la clause optionnelle RETURNS.

Pour les fonctions stockées, la clause obligatoire RETURNS spécifie le type de la valeur de retour.

Utilisation de domaines lors de la déclaration de paramètres

Vous pouvez spécifier un nom de domaine comme type de paramètre, auquel cas le paramètre héritera de toutes les caractéristiques du domaine.

Si la clause TYPE OF est utilisée en plus avant le nom du domaine, seul le type de données du domaine est utilisé — ses contraintes NOT NULL et CHECK (si elles existent) ne sont pas vérifiées, et aucune valeur par défaut n’est utilisée. Si le domaine est un type de texte, son jeu de caractères et son ordre de tri sont toujours utilisés.

Utilisation du type de colonne lors de la déclaration des paramètres

Les paramètres d’entrée et de sortie peuvent être déclarés en utilisant le type de données colonne des tables et vues existantes. Pour ce faire, on utilise la phrase TYPE OF COLUMN, suivie du nom de la table ou de la vue et d’un nom de colonne séparé par un point.

Lorsque vous utilisez TYPE OF COLUMN, seul le type de données est hérité, et dans le cas des types de chaînes de caractères, également le jeu de caractères et l’ordre de tri. Les limitations et les valeurs par défaut de la colonne ne sont jamais utilisées.

Fonctions déterministes

La clause optionnelle DETERMINISTIC dans la déclaration de la fonction indique que la fonction est déterministe. Les fonctions déterministes retournent le même résultat à chaque fois si on leur donne le même ensemble de valeurs d’entrée. Les fonctions non déterministes peuvent retourner des résultats différents à chaque fois, même si on leur donne le même ensemble de valeurs d’entrée.

Note

En fait, dans la version actuelle de Firebird, il n’y a pas de cache de fonctions stockées avec des arguments d’entrée mis en correspondance avec des valeurs de sortie.

Spécifier une instruction DETERMINISTIC est en fait une sorte de promesse que le code de la fonction retournera la même chose. A ce stade, une fonction déterministe est considérée comme un invariant et fonctionne sur les mêmes principes que les autres invariants. C’est-à-dire qu’elle est calculée et mise en cache au niveau d’exécution actuel de cette requête.

Qui peut créer un paquet ?

L’instruction CREATE PACKAGE peut être exécutée :

Administrateurs.
Utilisateurs avec le privilège CREATE PACKAGE.

L’utilisateur qui a créé l’en-tête du paquet devient le propriétaire du paquet.

Exemples

Example 1. Création d’un en-tête de paquet

CREATE PACKAGE APP_VAR
AS
BEGIN
  FUNCTION GET_DATEBEGIN() RETURNS DATE DETERMINISTIC;
  FUNCTION GET_DATEEND() RETURNS DATE DETERMINISTIC;
  PROCEDURE SET_DATERANGE(ADATEBEGIN DATE, ADATEEND DATE DEFAULT CURRENT_DATE);
END

Idem, mais les procédures et fonctions du paquet seront exécutées avec les droits de l’utilisateur qui les définit (propriétaire du paquet).

CREATE PACKAGE APP_VAR
SQL SECURITY DEFINER
AS
BEGIN
  FUNCTION GET_DATEBEGIN() RETURNS DATE DETERMINISTIC;
  FUNCTION GET_DATEEND() RETURNS DATE DETERMINISTIC;
  PROCEDURE SET_DATERANGE(ADATEBEGIN DATE, ADATEEND DATE DEFAULT CURRENT_DATE);
END

Voir aussi :

CREATE PACKAGE BODY, ALTER PACKAGE, DROP PACKAGE.

`ALTER PACKAGE`

affectation

Modification de l’en-tête du paquet.

Disponible en

DSQL

Syntaxe

ALTER PACKAGE package_name
[<rights clause>]
AS
BEGIN
  [<package_item> ...]
END

<package_item> ::=
    <function_decl>;
  | <procedure_decl>;

<function_decl> ::=
  FUNCTION func_name [(<in_params>)]
  RETURNS <type> [COLLATE collation]
  [DETERMINISTIC]

<procedure_decl> ::=
  PROCEDURE proc_name [(<in_params>)]
  [RETURNS (<out_params>)]

Pour plus d'informations, voir. CREATE PACKAGE

L’opérateur ALTER PACKAGE modifie l’en-tête du paquet. Il vous permet de changer le nombre et la composition des procédures et des fonctions, leurs paramètres d’entrée et de sortie. Le code source du corps du paquet est conservé. L’état du corps du paquet correspondant à son en-tête est indiqué dans la colonne RDB$PACKAGES.RDB$VALID_BODY_FLAG.

Qui peut modifier l’en-tête du paquet ?

L’instruction ALTER PACKAGE peut être exécutée :

Administrateurs.
Propriétaire du paquet ;
Utilisateurs avec le privilège ALTER ANY PACKAGE.

Exemples

Example 1. Modification de l’en-tête du paquet

ALTER PACKAGE APP_VAR
AS
BEGIN
  FUNCTION GET_DATEBEGIN() RETURNS DATE DETERMINISTIC;
  FUNCTION GET_DATEEND() RETURNS DATE DETERMINISTIC;
  PROCEDURE SET_DATERANGE(ADATEBEGIN DATE, ADATEEND DATE DEFAULT CURRENT_DATE);
END

Voir aussi :

CREATE PACKAGE, DROP PACKAGE, RECREATE PACKAGE BODY.

`CREATE OR ALTER PACKAGE`

affectation

Créer un nouvel en-tête de paquet ou modifier un en-tête de paquet existant.

Disponible en

DSQL

Syntaxe

CREATE OR ALTER PACKAGE package_name
[<rights clause>]
AS
BEGIN
  [<package_item> ...]
END

<package_item> ::=
    <function_decl>;
  | <procedure_decl>;

<function_decl> ::=
  FUNCTION func_name [(<in_params>)]
  RETURNS <type> [COLLATE collation]
  [DETERMINISTIC]

<procedure_decl> ::=
  PROCEDURE proc_name [(<in_params>)]
  [RETURNS (<out_params>)]

Pour plus d'informations, voir. CREATE PACKAGE

L’instruction CREATE OR ALTER PACKAGE crée un nouvel en-tête de paquetage ou modifie un en-tête de paquetage existant. Si l’en-tête de paquetage n’existe pas, il sera créé en utilisant l’instruction CREATE PACKAGE. S’il existe déjà, il sera modifié et recompilé, tandis que les privilèges et dépendances existants seront préservés.

Exemples

Example 1. Création d’un nouvel en-tête de paquet ou modification d’un en-tête existant

CREATE OR ALTER PACKAGE APP_VAR
AS
BEGIN
  FUNCTION GET_DATEBEGIN() RETURNS DATE DETERMINISTIC;
  FUNCTION GET_DATEEND() RETURNS DATE DETERMINISTIC;
  PROCEDURE SET_DATERANGE(ADATEBEGIN DATE, ADATEEND DATE DEFAULT CURRENT_DATE);
END

Voir aussi :

CREATE PACKAGE, ALTER PACKAGE, RECREATE PACKAGE BODY.

`DROP PACKAGE`

affectation

Suppression de l’en-tête du paquet.

Disponible en

DSQL

Syntaxe

DROP PACKAGE package_name

Table 1. Paramètres de la fonction`DROP PACKAGE`
Paramètre	Description
package_name	Nom du paquet.

L’instruction DROP PACKAGE supprime un en-tête de paquetage existant. Avant de supprimer un en-tête de paquetage (DROP PACKAGE), le corps du paquetage (DROP PACKAGE BODY) doit être supprimé, sinon une erreur sera générée. Si des dépendances existent sur l’en-tête du paquetage, une erreur sera générée lors de la tentative de suppression de cet en-tête.

Qui peut supprimer l’en-tête d’un paquet ?

L’instruction DROP PACKAGE peut être exécutée :

Administrateurs.
Propriétaire du paquet ;
Utilisateurs avec le privilège DROP ANY PACKAGE.

Exemples

Example 1. Suppression de l’en-tête du paquet

DROP PACKAGE APP_VAR;

Voir aussi :

CREATE PACKAGE, ALTER PACKAGE, DROP PACKAGE BODY.

`RECREATE PACKAGE`

affectation

Créer un nouvel en-tête de paquet ou recréer un en-tête de paquet existant.

Disponible en

DSQL

Syntaxe

RECREATE PACKAGE package_name
[<rights clause>]
AS
BEGIN
  [<package_item> ...]
END

<package_item> ::=
    <function_decl>;
  | <procedure_decl>;

<function_decl> ::=
  FUNCTION func_name [(<in_params>)]
  RETURNS <type> [COLLATE collation]
  [DETERMINISTIC]

<procedure_decl> ::=
  PROCEDURE proc_name [(<in_params>)]
  [RETURNS (<out_params>)]

Pour plus d'informations, voir. CREATE PACKAGE

L’instruction RECREATE PACKAGE crée un nouvel en-tête de paquetage ou recrée un en-tête de paquetage existant. Si un en-tête de paquetage portant ce nom existe déjà, l’instruction essaiera de le supprimer et de créer un nouvel en-tête de paquetage. Il n’est pas possible de recréer un en-tête de paquetage si l’en-tête de paquetage existant a des dépendances ou si le corps du paquetage existe. Après avoir recréé un en-tête de paquetage, les sous-routines et les privilèges du paquetage ne sont pas conservés.

Exemples

Example 1. Création d’un nouvel en-tête de paquet ou recréation d’un en-tête de paquet existant

RECREATE PACKAGE APP_VAR
AS
BEGIN
  FUNCTION GET_DATEBEGIN() RETURNS DATE DETERMINISTIC;
  FUNCTION GET_DATEEND() RETURNS DATE DETERMINISTIC;
  PROCEDURE SET_DATERANGE(ADATEBEGIN DATE, ADATEEND DATE DEFAULT CURRENT_DATE);
END

Voir aussi :

CREATE PACKAGE, DROP PACKAGE, RECREATE PACKAGE BODY.