VA FileMan V. 22.0 Programmer Manual Banner

 

Contents: Main Chapter See Also: Getting Started Manual Advanced User Manual

Auditing API

CHANGED^DIAUTL( ): Historical Data Retriever

This procedure returns a list of IENs of entries that have had audit events within a specified time period. Optionally, the oldest value of each audited field within that time period is returned with each entry.

Format
DO CHANGED^DIAUTL(FILE,FIELDS,FLAG,TARGET_ROOT,START_DATE,END_DATE)
Input Parameters
FILE (Required) File number of a file which is being audited. 
FIELDS (Required) Specifies which fields from the audited file are to be examined for audit history.  Can be one of the following: 
  • A single field number.

  • A list of field numbers, separated by semicolons.

  • A range of field numbers, in the form M:N, where M and N are the end points of the inclusive range. All field numbers within this range are retrieved.

  • * meaning, "examine all audited fields."
FLAG (Optional) "O" if the "oldest" values within the specified time period are to be returned.  Without the "O" parameter, the API returns only the entry numbers.
TARGET_ROOT (Required) The name of a closed root reference. 
START_DATE (Optional) Beginning date/time (FileMan format) of the auditing period.  If no START_DATE is specified, the file's audit history will be scanned from its earliest date/time.
END_DATE (Optional) Ending date/time (FileMan format) of the auditing period. If no END_DATE specified, the file's audit history will be scanned through its most recent date/time.
Output
TARGET_ROOT The output array is found in TARGET_ROOT(IEN)=""
oldest values, if requested by the "O" parameter, are in TARGET_ROOT(IEN,field#)

Note that CHANGED^DIAUTL can only retrieve what is recorded in the FileMan Audit file (#1.1),  and does not look at subfiles (multiple fields).  Data entry events that happen before auditing is turned on for a particular field, are not recorded.

Also, if the PURGE DATA AUDITS option is run, information from the audit trail is removed.
 

Examples
Example 1

Find which entries in File #999000 have been changed since yesterday.

    >S %DT="",X="T-1" D ^%DT,CHANGED^DIAUTL(999000,"*","","^TMP($J)",Y)

    ^TMP($J,7)=""
    ^TMP($J,4878)=""
    ^TMP($J,9899)=""

Three records have had audited events since yesterday at 12:01 AM.

Example 2
Find which NAMEs in File #999000 have ever been changed, and retrieve the original NAMEs. 
    >D CHANGED^DIAUTL(999000,.01,"O","ARRAY")  ZW ARRAY

    ARRAY(344)=""
    ARRAY(344,.01)="DELETED,DAVID"
    ARRAY(477)=""
    ARRAY(477,.01)="UNMARRIED,UNA"
Two records are found, because the audit status of the .01 field of this  file is "EDITED OR DELETED".  Entry 344 no longer exists.  Entry 477 has a  new married name.  It is the EXTERNAL version of the old value that is returned.  If the name were changed twice in the time period, the oldest value would be  returned.

 

Reviewed/Updated: March 10, 2007