TAA Tools
TRGSAMPLE       Trigger Sample                         TAADBOD

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
					

Added to TAA Productivity tools January 15, 2013


Home Page Up to Top