ADDPFTRG

La commande ADDPFTRG (Ajouter déclencheur fichier physique) ajoute un déclencheur système au fichier physique indiqué. Un déclencheur définit un programme appelé par une opération de suppression, d'insertion, de mise à jour ou de lecture sur un fichier.

Vous pouvez demander que l'appel du programme de déclenchement se produise avant ou après une opération de modification. Les opérations de modification reconnues sont l'insertion, la mise à jour, la suppression ou la lecture par le biais de n'importe quelle interface. En revanche, le déclenchement ne peut pas être effectué par la mise à blanc, l'initialisation, le déplacement, l'application de modifications journalisées, le retrait de modifications journalisées ou la modification de la fin de données.

Vous pouvez ajouter 300 déclencheurs au maximum à un fichier physique. Ces déclencheurs peuvent appeler le même programme ou des programmes différents.

Lors de l'ajout d'un déclencheur à un fichier physique, ce dernier et les fichiers logiques qui en dépendent font l'objet d'un verrouillage exclusif sans lecture permise.

Le déclencheur ajouté au fichier physique concerne tous les membres de ce fichier. Lorsqu'une opération de modification est effectuée sur un membre du fichier indiqué, le programme de déclenchement est appelé. Lorsqu'un membre est modifié, le programme de déclenchement est appelé. Un appel a également lieu lorsqu'une modification est effectuée par le biais d'un fichier logique ou d'une vue SQL dépendant de ce fichier physique.

Pour plus d'informations sur les programmes de déclenchement, reportez-vous au manuel Rubrique Base de données de l'IBM i Information Center, à l'adresse http://www.ibm.com/systems/i/infocenter/.

Restrictions

• Pour recourir à cette commande, vous devez disposer des droits de lecture (*READ), d'opération sur l'objet (*OBJOPR), de modification d'objet (*OBJALTER) ou de gestion d'objet (*OBJMGT) sur le fichier physique, ainsi que du droit d'exécution (*EXECUTE) sur la bibliothèque de ce fichier, sur le programme de déclenchement et sur sa bibliothèque.
• Si ALWREPCHG(*YES) a été précisé, vous devez disposer des droits de mise à jour (*UPD) et d'opération (*OBJOPR) sur le fichier indiqué.
• Si le fichier physique ou bien un fichier logique ou une vue SQL qui en dépendent sont ouverts dans le travail en cours ou un autre travail, l'ajout d'un déclencheur ne peut pas avoir lieu.
• Lors de l'exécution de cette commande, ni le fichier physique, ni les fichiers logiques dépendants ne peuvent être ouverts.
• Le programme de déclenchement doit être un programme de type *PGM. Il ne peut pas s'agir d'un programme de service ILE (Integrated Language Environment) de type *SRVPGM.
• Cette commande est à unités d'exécution protégées sous certaines conditions. Dans le cas de travaux à unités d'exécution multiples, cette commande n'admet pas l'utilisation d'unités d'exécution multiples pour les fichiers répartis. Elle échoue dans le cas de fichiers répartis utilisant une base de données relationnelle de type *SNA.
• Vous ne pouvez pas ajouter de déclencheur de lecture aux tables de requêtes matérialisées SQL.

Paramètres

Fichier physique (FILE)

Indique le fichier physique auquel le programme de déclenchement est ajouté. Ce fichier doit exister sur le système.

Ce paramètre est obligatoire.

Qualificatif 1 : Fichier physique

nom

Indiquez le nom du fichier auquel le programme de déclenchement est ajouté.

Qualificatif 2 : Biblio

*LIBL

La recherche porte sur toutes les bibliothèques de la liste des bibliothèques de l'unité d'exécution en cours jusqu'à ce que la première occurrence soit trouvée.

*CURLIB

La recherche porte sur la bibliothèque en cours du travail. Si celle-ci n'est pas précisée, QGPL est utilisée par défaut.

nom

Indiquez le nom de la bibliothèque dans laquelle la recherche doit être effectuée.

Moment de déclenchement (TRGTIME)

Indique le moment auquel le programme de déclenchement doit être appelé.

Ce paramètre est obligatoire.

*BEFORE

Le programme de déclenchement est appelé avant l'exécution de la modification sur le fichier physique indiqué.

*AFTER

Le programme de déclenchement est appelé après l'exécution de la modification sur le fichier physique indiqué.

Evénement de déclenchement (TRGEVENT)

Indique l'événement (modification apportée au fichier physique) entraînant l'appel du programme de déclenchement. Un seul événement peut être précisé par commande émise.

Ce paramètre est obligatoire.

*INSERT

Le programme de déclenchement est appelé par une opération d'insertion.

Remarque :Si le fichier physique n'est pas accessible en lecture et en écriture, la valeur *INSERT ne peut pas être indiquée.

*DELETE

Le programme de déclenchement est appelé par une opération de suppression.

Remarques :

• Si le fichier physique n'est pas accessible en lecture et en suppression, la valeur *DELETE ne peut pas être indiquée.
• Si le fichier physique est associé à une contrainte référentielle avec la règle de suppression en cascade, la valeur *DELETE ne peut pas être indiquée.

*UPDATE

Le programme de déclenchement est appelé par une opération de mise à jour.

Remarques :

• Si le fichier physique n'est pas accessible en lecture et en mise à jour, la valeur *UPDATE ne peut pas être indiquée.
• Si le fichier physique est un fichier dépendant comportant une clé associée dont la règle de suppression est *SETNULL ou *SETDFT, la valeur *UPDATE ne peut pas être indiquée.

*READ

Le programme de déclenchement est appelé par une opération de lecture.

Remarque :Si le fichier physique n'est pas accessible en lecture, la valeur *READ ne peut pas être indiquée.

Programme (PGM)

Indique le programme appelé lorsque l'événement indiqué a lieu dans le fichier physique. Le programme doit exister sur le système et être de type *PGM.

Ce paramètre est obligatoire.

Qualificatif 1 : Programme

nom

Indiquez le nom du programme à appeler lorsque l'événement spécifié se produit dans le fichier physique.

Qualificatif 2 : Biblio

*LIBL

La recherche porte sur toutes les bibliothèques de la liste des bibliothèques de l'unité d'exécution en cours jusqu'à ce que la première occurrence soit trouvée.

*CURLIB

La recherche porte sur la bibliothèque en cours du travail. Si celle-ci n'est pas précisée, QGPL est utilisée par défaut.

nom

Indiquez le nom de la bibliothèque dans laquelle la recherche doit être effectuée.

Remarque :Les valeurs spéciales *LIBL et *CURLIB sont les valeurs du travail en cours d'exécution lors de l'ajout du programme de déclenchement.

Remplacer déclencheur (RPLTRG)

Indique si le déclencheur existant est remplacé par le déclencheur ajouté lorsque tous deux sont associés au même événement et au même moment de déclenchement.

*NO

Le déclencheur existant n'est pas remplacé.

*YES

Le déclencheur existant est remplacé. Il est remplacé si *GEN a été indiqué pour le nom de déclencheur et que le moment et l'événement correspondent à un même poste. Il est également remplacé si un nom de déclencheur a été indiqué et que celui-ci correspond à un poste existant. Si aucun déclencheur ne correspond au nom indiqué, le nouveau déclencheur est ajouté au fichier physique.

Déclencheur (TRG)

Indique le nom du déclencheur à ajouter.

*GEN

Le nom du déclencheur est généré par le système.

valeur-caractères

Indiquez le nom du déclencheur. Ce nom doit être unique dans la bibliothèque. Il permet de distinguer les déclencheurs dont les valeurs de moment et d'événement sont identiques. Vous pouvez indiquer 128 caractères au maximum sans délimiteur, ou 258 caractères délimités par des guillemets (").

Remarque :La casse est conservée lorsque des minuscules sont indiquées.

Bibliothèque du déclencheur (TRGLIB)

Indique la bibliothèque du déclencheur à ajouter.

*FILE

La bibliothèque du fichier indiqué par le paramètre FILE est utilisée.

*CURLIB

La bibliothèque en cours du travail est utilisée. Si celle-ci n'est pas précisée, QGPL est utilisée par défaut.

Remarque :La valeur spéciale *CURLIB correspond à la valeur du travail en cours d'exécution lors de l'ajout du programme de déclenchement.

nom

Indiquez le nom de la bibliothèque à utiliser.

Modifications répétées admises (ALWREPCHG)

Indique si les modifications répétées d'un enregistrement au sein d'un déclencheur ou des déclencheurs suivants appelés pendant l'exécution du programme de déclencheur sont autorisées.

*NO

Les modifications répétées d'un enregistrement au sein d'un déclencheur ou des déclencheurs suivants ne sont pas autorisées.

*YES

Les modifications répétées d'un enregistrement au sein d'un déclencheur ou des déclencheurs suivants sont autorisées.

Unités d'exécution protégées (THDSAFE)

Indique si le programme de déclenchement admet les unités d'exécution multiples (à des fins de documentation uniquement). Ce paramètre peut servir à déterminer la valeur du paramètre MLTTHDACN, mais il n'existe aucune relation directe entre les mots clés THDSAFE et MLTTHDACN.

*UNKNOWN

L'état d'admission ou non d'unités d'exécution multiples est inconnu pour ce programme de déclenchement.

*NO

Le programme de déclenchement n'admet pas les unités d'exécution multiples.

*YES

Le programme de déclenchement admet les unités d'exécution multiples.

Action travail exéc multiples (MLTTHDACN)

Indique l'action à effectuer lorsque le programme de déclenchement est appelé dans un travail à unités d'exécution multiples. L'attribut THDSAFE de ce programme peut servir à déterminer l'action requise. Cependant, il n'existe aucune relation directe entre les mots clés THDSAFE et MLTTHDACN.

*SYSVAL

La valeur système QMLTTHDACN permet de déterminer l'action à effectuer.

*MSG

Permet d'exécuter le programme dans un travail à unités d'exécution multiples, mais un message de diagnostic est alors émis.

*NORUN

Permet de ne pas exécuter le programme de déclenchement dans un travail à unités d'exécution multiples. Un message d'échappement est alors émis.

*RUN

Permet d'exécuter le programme dans un travail à unités d'exécution multiples.

Si la valeur du paramètre THDSAFE vous sert à déterminer celle du paramètre MLTTHDACN, prenez connaissance des recommandations suivantes :

• Si la valeur *NO est associée à THDSAFE, la valeur *NORUN doit être défini pour MLTTHDACN.
• Si THDSAFE est associé à la valeur *UNKNOWN, MLTTHDACN doit être associé à *SYSVAL.
• Si THDSAFE est associé à *YES, MLTTHDACN doit être associé à *RUN.

Condition déclenchement en màj (TRGUPDCND)

Indique la condition déterminant l'appel du programme de déclenchement par un événement de mise à jour.

Remarque :Ce paramètre est valable uniquement lorsque la valeur *UPDATE est affectée au paramètre Evénement de déclenchement (TRGEVENT).

*ALWAYS

Le programme de déclenchement est appelé chaque fois qu'un enregistrement est mis à jour, qu'une valeur ait été modifiée ou non.

*CHANGE

Le programme de déclenchement est appelé uniquement lorsqu'un enregistrement est mis à jour et qu'une valeur a été modifiée.

Protection par disque miroir (MIRROR)

Indique si un déclencheur exécuté dans un environnement protégé par disque miroir sera appelé uniquement sur le système qui initie l'opération ou sur les deux systèmes de la paire protégée par disque miroir.

*YES

Indique qu'un déclencheur exécuté dans un environnement protégé par disque miroir sera appelé sur les deux systèmes de la paire protégée par disque miroir.

*NO

Indique qu'un déclencheur exécuté dans un environnement protégé par disque miroir sera appelé uniquement sur le système qui initie l'opération.

Exemples

Exemple 1 : Ajout d'un déclencheur pour un événement d'insertion

ADDPFTRG   FILE(EMP)  TRGTIME(*AFTER)  TRGEVENT(*INSERT)
           PGM(LIB2/INSTRG)

Cette commande ajoute, dans le fichier physique EMP, un déclencheur dont le programme de déclenchement INSTRG se trouve dans la bibliothèque LIB2. A la suite d'une opération d'insertion sur le fichier EMP, le programme INSTRG est appelé. Le fichier est recherché dans la liste de bibliothèques (*LIBL) car la valeur FILE n'est pas qualifiée par un nom de bibliothèque.

Exemple 2 : Configuration de plusieurs événements de déclenchement de sorte qu'ils appellent un seul programme de déclenchement

ADDPFTRG   FILE(EMP)  TRGTIME(*AFTER)  TRGEVENT(*INSERT)
           PGM(LIB2/INSTRG)
ADDPFTRG   FILE(EMP)  TRGTIME(*AFTER)  TRGEVENT(*UPDATE)
           PGM(LIB2/INSTRG)

Ces deux commandes ajoutent des déclencheurs pour appeler le programme de déclenchement INSTRG de la bibliothèque LIB2, lorsqu'une opération d'insertion ou de mise à jour a lieu sur le fichier EMP.

Exemple 3 : Ajout d'un déclencheur uniquement lorsqu'un événement de mise à jour modifie des valeurs

ADDPFTRG   FILE(EMP)  TRGTIME(*BEFORE)  TRGEVENT(*UPDATE)
           PGM(LIB2/UPDTRG)  TRGUPDCND(*CHANGE)

Le programme de déclenchement UPDTRG de la bibliothèque LIB2 est appelé avant qu'une valeur d'une zone d'un enregistrement dans le fichier EMP soit modifiée lors d'une mise à jour.

Exemple 4 : Remplacement d'un déclencheur existant

ADDPFTRG   FILE(EMP)  TRGTIME(*BEFORE)  TRGEVENT(*UPDATE)
           PGM(LIB2/NEWPGM)  RPLTRG(*YES)  TRGUPDCND(*CHANGE)

Le programme de déclenchement NEWPGM ajouté au fichier EMP comporte le même délai de déclenchement (*BEFORE) et le même événement de déclenchement (*UPDATE) que le programme de déclenchement UPDTRG qui a été ajouté dans l'exemple 3. Par conséquent, le programme de déclenchement ajouté NEWPGM remplace le programme de déclenchement existant UPDTRG.

Exemple 5 : Remplacement d'un déclencheur par un déclencheur relatif à une autre condition de mise à jour

ADDPFTRG   FILE(EMP)  TRGTIME(*BEFORE)  TRGEVENT(*UPDATE)
           PGM(LIB2/NEWPGM)  RPLTRG(*YES)  TRGUPDCND(*ALWAYS)

Le déclencheur ajouté dans l'exemple 4, qui appelle le programme de déclenchement NEWPGM uniquement lorsque les valeurs sont modifiées, est remplacé par un déclencheur qui appelle toujours le programme de déclenchement NEWPGM, quelles que soient les valeurs.

Messages d'erreur

Messages *ESCAPE

CPF32C6

La procédure de reprise du déclencheur a échoué.