The Trigger Sample tool provides some sample objects for learning how
to write a trigger program. Starting with a sample that uses
standard field names for basic trigger fields and your own data base
field names makes it simple to write a trigger program. You must
copy the code from the TAA Archive to be able to work with it.
Several objects make up the tool.
** File TAADBODQ. The sample data base file will have a trigger
program specified for it in the later instructions. It has 2
fields FLD1 and FLD2. The file has no data when it is
shipped. You can display the format with:
DSPFMT TAADBODQ
** The file TAADBODP. This provides an external definition of
the standard fields passed to a trigger program. The file
format is used as an externally described data structure in
the sample trigger program and can be used in any trigger
program. The format has several binary fields. You can
display the format with:
DSPFMT TAADBODP
** Programs TAADBODR and TAADBODR2. TAADBODR is an RPG III
program that will act as the trigger program. A second
version (TAADBODR2) is an RPG IV program. Either program may
be used. These programs just print the data that is passed to
them, but the source provides a base that you can use to begin
your own trigger program. You may want to copy the code from
the TAA Archive to source file members so you may then copy it
for your own program.
CPYTAA TAAARCMBR(TAADBODR)
CPYTAA TAAARCMBR(TAADBODR2)
By default, the source is copied to the QATTRPG source file in
TAATOOL.
** Program TAADBODR3. This is a simple RPG program to add
records to the TAADBODQ file as part of a demonstration.
Getting started with the sample
-------------------------------
** Begin by using ADDPFTRG for the sample file and sample program
which will add a trigger program to the TAADBODQ file:
ADDPFTRG FILE(TAATOOL/TAADBODQ) TRGTIME(*AFTER)
TRGEVENT(*INSERT) PGM(TAATOOL/TAADBODR)
The TRGTIME(*AFTER) entry specifies that you want the trigger
program called after the record has been written to the file.
The other option is *BEFORE meaning your program would be able
to check before writing to the data base.
The TRGEVENT(*INSERT) option specifies that you want to
process the information when a new record is added to the
file. The other options are *READ, *UPDATE, or *DELETE. You
must use an ADDPFTRG command for each event you want to
handle. The same program may handle multiple events or you
can have unique programs.
Using RPG III, it is possible for the same program to handle
multiple files that use the same format.
Using RPG IV, it is possible for the same program to handle
multiple files with different formats based on multiple data
structures each based on a pointer.
The data is passed to the trigger program in one parameter
which includes standard fields and the record image. The
standard fields may be used to determine what is being passed
and has offsets to the record image(s). Since the sample
command specified *AFTER and *INSERT, the data passed to the
trigger program will contain only the 'new record'
information. The 'original record' information will be blank.
** An 'Add' program exists to let you add records to the TAADBODQ
file. Enter:
CALL TAADBODR3 PARM('AAAAA' 'BBB')
Because there is a trigger program specified for the file, the
trigger program would be passed information about the new
record. The sample trigger program only prints the data.
** Use WRKSPLF and look at the QPRINT spooled file.
WRKSPLF
The Type column on the left indicates either the 'Original'
record or the 'New' record. Since TRGTIME(*AFTER) and
TRGEVENT(*INSERT) was specified, only the 'New' record
information is printed by the program.
The sample program only prints one record and then ends. If
you add another record, another spooled file would be created.
If you have completed the test, you can remove the trigger
program with:
RMVPFTRG FILE(TAATOOL/TAADBODQ)
The Sample Program TAADBODR
----------------------------
Assuming you copied the source from the TAA Archive with CPYTAA in a
previous step, look at the source with:
STRSEU SRCFILE(TAATOOL/QATTRPG) SRCMBR(TAADBODR)
OPTION(5)
** The program defines QPRINT as a printer file. If you don't
need to print, delete the file.
** The INP array holds the data passed to the program. It is
defined as 9999 bytes.
** The INPDS data structure is the first parameter passed to the
trigger program. The data is placed in the INP array.
** Change the source for the externally described data structure
from TAADBODQ to the name of your file. This will allow you
to process using your field names.
** The parameter list describes 2 fields. INPDS is the field
that describes the INP array. The second parameter INPLEN is
ignored in the program. It contains the length that is
passed, but the value is ignored in the program.
** The EXCPT HDG line prints a heading which is only needed if
you are printing in the program.
** The MOVEA from INP,1 moves the basic information to the
TRFFLDS array. This allows you to work with field names such
as TGMBR (the member name) and TGRR (the relative record
number).
** The EXSR statement uses a subroutine to convert the single
character codes for TGEVNT and TGTIME to descriptive text.
This is probably not needed in a production program.
** The TGTIME field contains a single character for the 'time'
passed to the trigger program. A '1' means the data is for
the 'New record'.
** The TGNRGO field contains the offset in the INP array where
the data for the 'New record' exists. The offset must have 1
added to it to determine the starting position. The data is
then moved to the FILEDS data structure which contains the
fields defined for the file (FLD1 and FLD2 in the sample
file).
** The same process occurs for the 'Original record'. Since
*INSERT was specified, the TGTIME field is checked and since
no '2' Time codes exist, the process is bypassed. If you had
specified *UPDATE, the same program would handle both the 'New
record' and the 'Original record'.
** The sample program then ends with LR on.
** The CVTFLD subroutine converts the single character codes to
descriptive text.
** Printer output specs define the output.
Other comments
--------------
The system description of the trigger function implies that you can
use a trigger to write a single validity checking function before
writing data to the data base. However, there is no good method of
describing an error back to the originating program. A data queue
convention could be used, but is not fail safe as the main program
could just ignore the data queue or any value entered. You could
send an escape message, but that would probably abort the originating
program.
Restrictions
------------
None.
Prerequisites
-------------
None.
Implementation
--------------
Follow the instructions for 'Getting started with the sample'.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
TAADBODR *PGM RPG TAADBODR QATTRPG
TAADBODR2 *PGM RPGLE TAADBODR2 QATTRPG
TAADBODR3 *PGM RPG TAADBODR3 QATTRPG
TAADBODP *FILE PF TAADBODP QATTDDS
TAADBODQ *FILE PF TAADBODQ QATTDDS
|
