Add Physical File Trigger (ADDPFTRG)

Where allowed to run: All environments (*ALL)
Threadsafe: Conditional
Parameters
Examples
Error messages

The Add Physical File Trigger (ADDPFTRG) command adds a system trigger to a specified physical file. A trigger defines a program that is called with a delete, insert, update or read operation occurs for a file.

The trigger program can be specified to be called before or after a change operation occurs. The change operation can be an insert, update, delete or read operation through any interface. Change operations do not include clearing, initializing, moving, applying journal changes, removing journal changes, or changing end of data operations.

A maximum of 300 triggers can be added to one physical file. The trigger program to be called can be the same for each trigger or it can be a different program for each trigger.

An exclusive-no-read lock is held on the physical file when adding a trigger to that file. All logical files which are built over the physical file are also held with the exclusive-no-read lock.

Once a trigger is added to the physical file, all members of that specified file are affected by the trigger. When a change operation occurs on a member of the specified file, the trigger program is called. The trigger program is also called when a change operation occurs by way of either a dependent logical file or a Structured Query Language (SQL) view that is built over the physical file.

More information on the trigger program is in the Database information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

Restrictions

Top


 

Parameters

Keyword Description Choices Notes
FILE Physical file Qualified object name Required, Positional 1
Qualifier 1: Physical file Name
Qualifier 2: Library Name, *LIBL, *CURLIB
TRGTIME Trigger time *BEFORE, *AFTER Required, Positional 2
TRGEVENT Trigger event *INSERT, *DELETE, *UPDATE, *READ Required, Positional 3
PGM Program Qualified object name Required, Positional 4
Qualifier 1: Program Name
Qualifier 2: Library Name, *LIBL, *CURLIB
RPLTRG Replace trigger *NO, *YES Optional
TRG Trigger Character value, *GEN Optional
TRGLIB Trigger library Name, *FILE, *CURLIB Optional
ALWREPCHG Allow Repeated Change *NO, *YES Optional
THDSAFE Threadsafe *UNKNOWN, *NO, *YES Optional
MLTTHDACN Multithreaded job action *SYSVAL, *MSG, *NORUN, *RUN Optional
TRGUPDCND Trigger update condition *ALWAYS, *CHANGE Optional

Top

 

Physical file (FILE)

Specifies the physical file to which this trigger program is added. The file must exist on the system.

This is a required parameter.

Qualifier 1: Physical file

name

Specify the name of the file to which the trigger program is added.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB

The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

name

Specify the name of the library to be searched.

Top

 

Trigger time (TRGTIME)

Specifies the time when the trigger program is called.

This is a required parameter.

*BEFORE

The trigger program is called before the change operation on the specified physical file.

*AFTER

The trigger program is called after the change operation on the specified physical file.

Top

 

Trigger event (TRGEVENT)

Specifies the event (the change operation to the physical file) that calls the trigger program. Only one event can be specified for each command issued.

This is a required parameter.

*INSERT

An insert operation calls the trigger program.

If the physical file is not read and write capable, the *INSERT value cannot be specified.

*DELETE

A delete operation calls the trigger program.

Notes:

  • If the physical file is not read and delete capable, the *DELETE value cannot be specified.

  • If the physical file has a referential constraint with a delete rule of CASCADE, the *DELETE value cannot be specified.

*UPDATE

An update operation calls the trigger program.

Notes:

  • If the physical file is not read and update capable, the *UPDATE value cannot be specified.

  • If the physical file is a dependent file which has a foreign key with a delete rule of SET NULL or SET DEFAULT, the *UPDATE value cannot be specified.

*READ

A read operation calls the trigger program.

If the physical file is not read capable, the *READ value cannot be specified.

Top

 

Program (PGM)

Specifies the program that is called when the specified event occurs on the physical file. The program must exist on the system and be of object type *PGM.

This is a required parameter.

Qualifier 1: Program

name

Specify the name of the program to be called when the specified event occurs on the specified physical file.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB

The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

name

Specify the name of the library to be searched.

The special values *LIBL and *CURLIB are the values of the job running when the trigger program is added.

Top

 

Replace trigger (RPLTRG)

Specifies whether an existing trigger is replaced by the trigger to be added when the triggers have the same trigger event and trigger time.

*NO

The existing trigger is not replaced.

*YES

The existing trigger is replaced. If *GEN was specified for the trigger name and the time and event match a single entry, the trigger will be replaced. If a trigger name was specified and it matches an existing entry, the trigger will be replaced. If a trigger with the specified trigger name does not exist, the new trigger is added to the physical file.

Top

 

Trigger (TRG)

Specifies the name of the trigger being added.

*GEN

The system generates a trigger name.

character-value

Specify the name of the trigger. The trigger name must be unique to the library. The trigger name is used to distinguish triggers with the same time and event values. You can specify a maximum of 128 characters without delimiters or 258 characters with quotation mark (") delimiters.

The case is preserved when lowercase characters are specified.

Top

 

Trigger library (TRGLIB)

Specifies the library for the trigger being added.

*FILE

The library for the file specified on the FILE parameter is used.

*CURLIB

The current library for the job is used. If no library is specified as the current library for the job, the QGPL library is used.

The special value *CURLIB is the value of the job running when the trigger program is added.

name

Specify the name of the library to be used.

Top

 

Allow Repeated Change (ALWREPCHG)

Specifies whether repeated changes to a record within a trigger are allowed.

*NO

Repeated changes to a record within a trigger are not allowed.

*YES

Repeated changes to a record within a trigger are allowed.

Top

 

Threadsafe (THDSAFE)

Specifies whether the trigger program is threadsafe. This is intended for documentation purposes only. It may be used in determining the MLTTHDACN value, but there is no direct relationship between the THDSAFE and MLTTHDACN keywords.

*UNKNOWN

The threadsafe status of the trigger program is not known.

*NO

The trigger program is not threadsafe.

*YES

The trigger program is threadsafe.

Top

 

Multithreaded job action (MLTTHDACN)

Specifies the action to take when the trigger program is called in a multithreaded job. The THDSAFE attribute of the trigger program can be used in determining the action, however, there is no direct relationship between the THDSAFE and MLTTHDACN keywords.

*SYSVAL

Use the QMLTTHDACN system value to determine the action to take.

*MSG

Run the trigger program in a multithreaded job, but send a diagnostic message.

*NORUN

Do not run the trigger program in a multithreaded job. Send an escape message.

*RUN

Run the trigger program in a multithreaded job.

If you do use the THDSAFE value to determine the value for MLTTHDACN, please read the following recommendations:

Top

 

Trigger update condition (TRGUPDCND)

Specifies the condition under which an update event calls the trigger program.

This parameter applies only when *UPDATE is specified for the Trigger event (TRGEVENT) parameter.

*ALWAYS

The trigger program is called whenever a record is updated, whether or not a value changes.

*CHANGE

The trigger program is called only when a record is updated and a value is changed.

Top


 

Examples

Example 1: Adding a Trigger for an Insert Event

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

This command adds a trigger with trigger program INSTRG in library LIB2 to the physical file named EMP. When an insert operation occurs on the EMP file, the program INSTRG is called after the insert operation. The library list (*LIBL) is used to find the file because the FILE value is not qualified by a library name.

Example 2: Setting Multiple Trigger Events to Call One Trigger Program

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

These two commands add triggers to call the trigger program INSTRG in library LIB2 when an insert or update operation occurs on the EMP file.

Example 3: Adding a Trigger Only When an Update Event Changes Values

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

The trigger program UPDTRG in library LIB2 is called before a value for a field of a record in the EMP file changes during an update.

Example 4: Replacing an Existing Trigger

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

The trigger program NEWPGM being added to the file EMP has the same trigger time (*BEFORE) and trigger event (*UPDATE) as the trigger program UPDTRG that was added in Example 3. Therefore, the added trigger program NEWPGM replaces the existing trigger program UPDTRG.

Example 5: Replacing a Trigger with a Trigger for a Different Update Condition

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

The trigger added in Example 4 that calls the trigger program NEWPGM only is the values are changed, is replace by a trigger that always calls the trigger program NEWPGM regardless of the values.

Top


 

Error messages

*ESCAPE Messages

CPF32C6

Trigger operation not successful.

Top