CL Command Reference - ADDPFTRG
CL Command List > ADDPFTRG Reference
Description:
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.
Restrictions
. You must have read (*READ), object operational (*OBJOPR), and object alter (*OBJALTER) or object management (*OBJMGT) authorities to the physical file, execute (*EXECUTE) authority to the file library, and *EXECUTE authority to the trigger program and its library to use this command.
. You must have update (*UPD) and *OBJOPR authorities to the file if ALWREPCHG(*YES) has been specified.
. If the physical file or a dependent logical file or SQL view is opened in this or another job, a trigger cannot be added.
. While this command is running, neither the physical file nor any dependent logical files can be opened.
. The trigger program must be a program of object type *PGM. It cannot be an Integrated Language Environment (ILE) service program of object type *SRVPGM.
. This command is conditionally threadsafe. In multithreaded jobs, this command is not threadsafe for distributed files and fails for distributed files that use relational databases of type *SNA.
. Triggers may not be added to files in library QTEMP.
. Read triggers may not be added to SQL materialized query tables.
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.