Audit trail

The audit trail facility is an optional feature that a site may use to keep track of file updates. Option 2 from the PKINSTAL program will generate the code shown below. If required this module (named PKADTN01) will be called by PEEK under conditions specified by the site in module PKUSRN01.

The following excerpt from PKUSRN01 shows the code required to specify the calling behaviour of the audit trail.

1550 * If you wish to record any audit trail information, set the audit
1560 * level here. The options are:
1570 *
1580 *    0 = No audit logging
1590 *    1 = Module PKADTN01 called once per transaction (after the
1600 *        update)
1610 *    2 = Module PKADTN01 called twice per transaction (once before
1620 *        and again after the update)
1630 *
1640   #AUDIT-LEVEL := 0

The sequence in which Peek makes the calls to the audit trail is as follows:

If the #AUDIT-LEVEL = 2 then the audit trail module will be called before the update takes place, with #STATUS = 'ENTRY'.

The record is then updated, and if #AUDIT-LEVEL = 1 OR = 2 the audit trail is called with #STATUS = 'EXIT'. At this stage the audit trail may write its own records to the database, or indicate rejection of the transaction by altering the #STATUS field to 'CANCEL'.

Depending on the value in the status field, Peek will then either do an ET or BT to complete the transaction. For this reason it is essential that the audit trail not issue any END TRANSACTION or BACKOUT TRANSACTION calls as this may cause a loss of data integrity.

0010 * ----------------------------------------------------------------------
0020 * Description
0030 * -----------
0040 * This module may be used to provide an audit trail of any file
0050 * modifications. The setting of the field #AUDIT-LEVEL in the module
0060 * PKUSRN01 determines how often this module is executed. The options
0070 * are:
0080 *       0 = never called
0090 *       1 = called after the update has taken place
0100 *       2 = both before and after the update
0110 *
0120 * The possible values for action are:
0130 *       ADD = record being added
0140 *       MOD = record being modified
0150 *       DEL = record being deleted
0160 *
0170 * The possible values for #STATUS are:
0180 *       ENTRY  = record has not yet been updated
0190 *       EXIT   = transaction has been completed (and ET done)
0200 *       CANCEL = the transaction was cancelled by the user
0210 *       ERROR  = an error occurred which prevented any update
0220 *
0230 * Note that all the parameter fields are protected (passed with AD=O),
0240 * and therefore may not be altered.
0250 * ----------------------------------------------------------------------
0260 DEFINE DATA
0270 PARAMETER
0280   1 #ACTION                        (A3)
0290   1 #STATUS                        (A6)
0300   1 #DB                            (B2)
0310   1 #FN                            (B2)
0320   1 #DDM-NAME                      (A32)
0330   1 #ISN                           (B4)
0340   1 #FB                            (A252)
0350   1 REDEFINE #FB
0360     2 #FB-DISPLAY                  (A50/5)
0370   1 #RB-LENGTH                     (P5)
0380   1 #RB                            (B1/1:V)
0390 LOCAL
0400   1 #DB-N5                         (N5)
0410   1 #FN-N5                         (N5)
0420   1 #ISN-N10                       (N10)
0430   1 #P1                            (P5)     INIT <1>
0440   1 #P2                            (P5)
0450   1 #LEN                           (P3)
0460   1 #TEXT                          (A16)    INIT <'Record buffer...'>
0470 END-DEFINE
0480 *
0490 * ESCAPE ROUTINE     /* do nothing
0500 *
0510 PERFORM SCREEN-DISPLAY
0520 #STATUS := 'CANCEL'
0530 *
0540 * ------------------------------
0550 DEFINE SUBROUTINE SCREEN-DISPLAY
0560 * ------------------------------
0570 *
0580   #ISN-N10 := #ISN
0590   #DB-N5   := #DB
0600   #FN-N5   := #FN
0610 *
0620 WRITE NOTITLE NOHDR (CD=YE)
0630     'This is the PEEK audit trail user exit' (GR)
0640   / '--------------------------------------' (GR)
0650   / 'Action..........' (GR) #ACTION
0660 40T 'Database........' (GR) #DB  '/' (TU) #DB-N5 (AD=L SG=OFF)
0670   / 'Status..........' (GR) #STATUS
0680 40T 'File number.....' (GR) #FN  '/' (TU) #FN-N5 (AD=L SG=OFF)
0690   / 'User............' (GR) *USER
0700 40T 'ISN.............' (GR) #ISN '/' (TU) #ISN-N10 (AD=L SG=OFF)
0710   / 'DDM name........' (GR) #DDM-NAME
0720   / 'Format buffer...' (GR) #FB-DISPLAY (1)
0730   / '................' (GR) #FB-DISPLAY (2)
0740   / 'RB length.......' (GR) #RB-LENGTH (AD=L)
0750 *
0760   REPEAT
0770     IF #P1 + 19 LE #RB-LENGTH
0780       #P2 := #P1 + 19
0790     ELSE
0800       #P2 := #RB-LENGTH
0810     END-IF
0820     #LEN := #P2 - #P1 + 1
0830 *
0840     DECIDE ON FIRST VALUE OF #LEN
0850     VALUE  0 WRITE (CD=TU) #TEXT (IS=ON CD=GR)
0860     VALUE  1 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1)
0870     VALUE  2 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+1)
0880     VALUE  3 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+2)
0890     VALUE  4 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+3)
0900     VALUE  5 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+4)
0910     VALUE  6 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+5)
0920     VALUE  7 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+6)
0930     VALUE  8 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+7)
0940     VALUE  9 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+8)
0950     VALUE 10 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+9)
0960     VALUE 11 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+10)
0970     VALUE 12 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+11)
0980     VALUE 13 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+12)
0990     VALUE 14 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+13)
1000     VALUE 15 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+14)
1010     VALUE 16 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+15)
1020     VALUE 17 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+16)
1030     VALUE 18 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+17)
1040     VALUE 19 WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+18)
1050     NONE     WRITE (CD=TU) #TEXT (IS=ON CD=GR) #RB (#P1:#P1+19)
1060     END-DECIDE
1070     ADD 20 TO #P1
1080     UNTIL #P1 GT #RB-LENGTH
1090   END-REPEAT
1100 *
1110   NEWPAGE
1120 *
1130 END-SUBROUTINE
1140 *
1150 END