VA FileMan V. 22.2 Programmer Manual Banner

 

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

Auditing API

CHANGED^DIAUTL(): Retrieve Audit History

Reference Type Category ICR #
Supported Auditing 4397

The CHANGED^DIAUTL API returns a list of IENs of entries that have had audit events within a specified period. Optionally, the oldest value of each audited field within that period is returned with each entry.

Format
CHANGED^DIAUTL(file,fields[,flag],target_root[,start_date][,end_date])
Input Parameters
file (Required) File number of a file that 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.

  • Asterisk (*) meaning, "examine all audited fields."
flag (Optional) The O flag parameter if the "oldest" values within the specified 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, in VA FileMan internal format, of the auditing period.  If no start_date is specified, the file's audit history is scanned from its earliest date/time.
end_date (Optional) Ending date/time, in VA FileMan internal format, of the auditing period. If no end_date specified, the file's audit history is scanned through its most recent date/time.
Output Parameter
target_root The output array is found in TARGET_ROOT(IEN)="".
The oldest values, if requested by the O parameter, are in TARGET_ROOT(IEN,field#).

NOTE: CHANGED^DIAUTL can only retrieve what is recorded in the VA FileMan AUDIT (#1.1) file 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 [DIAUDIT PURGE DATA] option is run, information from the audit trail is removed.

Examples
Example 1

In this example, you want to find which entries in (fictitious) 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)=""

From this example, you find that three records have had audited events since yesterday at 12:01 AM.

Example 2

In this example, you want to find which NAMEs in (fictitious) File #999000 have ever been changed and retrieve the original NAMEs.

    >D CHANGED^DIAUTL(999000,.01,"O","ARRAY")  ZW ARRAY <Enter>

    ARRAY(344)=""
    ARRAY(344,.01)="DELETED,DAVID"
    ARRAY(477)=""
    ARRAY(477,.01)="UNMARRIED,UNA"

From this example, you find 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 was changed twice in the period, the oldest value would be returned.

 

Reviewed/Updated: March 10, 2007