ADDPFTRG (Add Physical File Trigger)

ADDPFTRG Command syntax diagram

 

Purpose

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

The trigger program can be specified to be called before or after an operation occurs. The operation can be an insert, update, delete or read operation through any interface. 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 held with an 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 Programming topic in the Information Center.

Restrictions

  1. You must have read authority, object operational, and object management or object alter authority to the physical file, execute authority to the file library, update and object operational authority to the physical file if ALWREPCHG(*YES) has been specified, and execute authority to the trigger program and its library.

  2. If the physical file or a dependent logical file or SQL view is opened in this or another job, a trigger cannot be added.

  3. While this command is running, neither the physical file nor any dependent logical files can be opened.

  4. 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.

  5. In multithreaded jobs, this command is not threadsafe for distributed files and fails for distributed files that use relational databases of type *SNA.

  6. A trigger program cannot be added if the program is in the QTEMP library.

 

Required Parameters

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

The name of the physical file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list 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.

library-name: Specify the name of the library to be searched.

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

TRGTIME
Specifies the time when the trigger program is called.

*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.

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

*INSERT: An insert operation calls the trigger program.

Note: 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

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

  2. 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

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

  2. 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.

 

Notes

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

  2. *READ can be specified as the trigger event only when *AFTER has been specified for the trigger time.

PGM
Specifies the name of 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.

The name of the trigger program can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list 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.

library-name: Specify the name of the library to be searched.

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

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

 

Optional Parameters

TRG
Specifies the name of the trigger. This is to distinguish between triggers with the same trigger time and trigger event. The trigger name must be unique to the library of the trigger. You can specify a maximum of 128 characters without delimiters or 258 characters with quotation mark delimiters.

*GEN: A trigger name will automatically be generated.

trigger-name: Specify the name of the trigger to be added.

TRGLIB
Specifies the name of the library where the trigger is to be added.

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

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

library-name: Specify the name of the library to be used.

RPLTRG
Specifies whether an existing trigger is replaced by the trigger to be added when the triggers have the same trigger name or 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.

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.

This value is ignored if *READ is specified for the TRGEVENT parameter.

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

Note: This parameter applies only when *UPDATE is specified on the 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.

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.

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:

  1. If the THDSAFE value is *NO, MLTTHDACN should be set to *NORUN.

  2. If the THDSAFE value is *UNKNOWN, MLTTHDACN should be set to *SYSVAL.

  3. If the THDSAFE value is *YES, MLTTHDACN should be set to *RUN.

Examples for ADDPFTRG

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.

Error messages for ADDPFTRG

*ESCAPE Messages

CPF32C6
Trigger operation not successful.