Print Page as PDF
DIAUTL ICR (4397)

DIAUTL    ICR (4397)

Name Value
NUMBER 4397
IA # 4397
DATE CREATED 2004/04/08
CUSTODIAL PACKAGE VA FILEMAN
CUSTODIAL ISC San Francisco
USAGE Supported
TYPE Routine
DBIC APPROVAL STATUS APPROVED
ROUTINE DIAUTL
NAME DIAUTL
GENERAL DESCRIPTION
Auditing Utilities.  Auditing allows VA FileMan users
and developers to look back through the dimension of time at prior values in
any file. Auditing is not just a tool that enhances quality control and system
security. It also allows the easy retrieval of "old" values (e.g., "address",
"maiden name," and so on).

STATUS Active
KEYWORDS auditing
ID DIAUTL
COMPONENT/ENTRY POINT
COMPONENT/ENTRY POINT COMPONENT DESCRIPTION VARIABLES
TURNON()
This is a utility to enable/disable auditing.

This procedure turns on (or off) auditing for specified fields in a file
(except for Computed and Word-Processing fields).  These changes are recorded
in the Data Dictionary audit, if the file has Data-Dictionary auditing turned
on.  Also, input templates containing the changed fields are recompiled.

Usage:

D TURNON^DIAUTL(file,field,mode)

Examples:

To turn on auditing for the STOP CODE NUMBER (#8) field in the HOSPITAL
LOCATION (#44) file:

D TURNON^DIAUTL(44,8) or D TURNON^DIAUTL(44,8,"y")

To turn off auditing for that field:

D TURNON^DIAUTL(44,8,"n")

VARIABLES TYPE VARIABLES DESCRIPTION
FILE Input
(Required) File number of a file which is being
audited.
FIELD Input
(Required) Specifies which fields from the file will
be forced on ("ALWAYS") for auditing.  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 will be audited.

- * meaning, "audit all fields."

MODE Input
This is an optional parameter. It defaults to "y",
which means to turn on auditing.

y - Yes, always audit (default). Turn auditing on.  e - Audit only when edited
or deleted.  n - No, don't audit. Turn auditing off.

LAST()
This extrinsic function uses the audit trail to
retrieve the last user who touched a particular field value, and the date/time
when this editing occurred.

Usage:

W $$LAST^DIAUTL(file,entry,field)

Example:

Find who last changed demographics of entry number 666 in File #2.

>W $$LAST^DIAUTL(2,666,"0:1")
3000708.103432^78

In this example, user number 78 was the user who most recently changed any of
the audited fields numbered between 0 and 1 in this Entry.  This user did so
on 8 July, 2000 at 10:34 AM.


VARIABLES TYPE VARIABLES DESCRIPTION
FILE Input
(Required) File number of a file which is being
audited.

ENTRY Input
(Required) Entry number in the audited file.

FIELD Input
(Required) Specifies which fields in 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.

- * for all fields.


CHANGED()
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.

Usage:

DO CHANGED^DIAUTL(FILE,FIELD,FLAG,TARGET_ROOT,START_DATE,END_DATE)

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

Examples:

Example 1

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)=""

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

Example 2

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

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 was changed twice in the time period, the oldest value would be
returned.


VARIABLES TYPE VARIABLES DESCRIPTION
FILE Input
(Required) File number of a file which is being
audited.

FIELD Input
(Required) Specifies which fields in 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 number within this range are retrieved.

- * for all fields.


FLAG Input
(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 Both
Input: (Required) The name of a closed root
reference.

Output: The output array is found in TARGET_ROOT(IEN)=""oldest values, if
requested by the "O" parameter, are in TARGET_ROOT(IEN,field#)

START_DATE Input
(Optional) Beginning date/time (VA FileMan 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 Input
(Optional) Ending date/time (VA FileMan format) of
the auditing period. If no END_DATE specified, the file's audit history is
scanned through its most recent date/time.

DATE ACTIVATED 2016/02/05