DATASETS Procedure

AUDIT Statement

Initiates and controls event logging to an audit file as well as suspends, resumes, or terminates event logging in an audit file.

Tips:	The AUDIT statement takes one of two forms, depending on whether you are initiating the audit trail or suspending, resuming, or terminating event logging in an audit file. You can define attributes such as format and informat for the user variables in the data file by using the PROC DATASETS MODIFY statement.
See:	Understanding an Audit Trail in SAS Language Reference: Concepts

Creating an Audit File

Syntax

AUDIT SAS-file <(SAS-password)<GENNUM=integer>)>;

INITIATE <AUDIT_ALL=NO | YES>;

LOG<ADMIN_IMAGE=YES | NO>

<BEFORE_IMAGE=YES | NO>
<DATA_IMAGE=YES | NO>
<ERROR_IMAGE=YES | NO>;

<USER_VAR variable-1 <...variable-n>>;

Required Argument

SAS-file: specifies the SAS data file in the procedure input library that you want to audit.

Optional Arguments

SAS-password: specifies the password for the SAS data file, if one exists. The parentheses are required.

GENNUM=integer: specifies that the SUSPEND, RESUME, or TERMINATE action be performed on the audit trail of a generation file. You cannot initiate an audit trail on a generation file. Valid values for GENNUM= are integers, which is a number that references a specific version from a generation group. Specifying a positive number is an absolute reference to a specific generation number that is appended to a data set's name (that is, gennum=2 specifies MYDATA#002). Specifying a negative number is a relative reference to a historical version in relation to the base version, from the youngest to the oldest (that is, gennum=-1 refers to the youngest historical version). Specifying 0, which is the default, refers to the base version. The parentheses are required.

Restriction:The GENNUM= option cannot be specified before an INTIATE or USER_VAR statement.

Statements

INITIATE

creates an audit file that has the same name as the SAS data file and a data set type of AUDIT. The audit file logs additions, deletions, and updates to the SAS data file. You must initiate an audit trail before you can suspend, resume, or terminate it. An INITIATE statement is a required statement that can occur only once per audit file and must be placed directly after the AUDIT statement in the first AUDIT run group for that file. Although the AUDIT statement immediately preceding the INITIATE statement cannot specify a GENNUM= option, if the specified file identifies a generation data set group, the audit file created by the INITIATE statement will be attached to the most recently created generation in the generation group.

AUDIT_ALL=NO | YES: specifies whether logging can be suspended and audit settings can be changed. AUDIT_ALL=YES specifies that all images are logged and cannot be suspended. That is, you cannot use the LOG statement to turn off logging of particular images, and you cannot suspend event logging by using the SUSPEND statement. To turn off logging, you must use the TERMINATE statement, which terminates event logging and deletes the audit file.

Default:NO

Example:Initiating an Audit File

LABEL='variable-label': specifies a label for the variable.

length: specifies the length of the variable. If a length is not specified, the default is 8.

LOG

specifies the audit settings:

ADMIN_IMAGE=YES | NO: specifies whether the administrative events are logged to the audit file (that is, the SUSPEND and RESUME actions).

BEFORE_IMAGE=YES | NO: specifies whether the before-update record images are logged to the audit file.

DATA_IMAGE=YES | NO: specifies whether the added, deleted, and after-update record images are logged to the audit file.

ERROR_IMAGE=YES | NO: specifies whether the after-update record images are logged to the audit file.

Default:All images are logged by default (that is, all four are set to YES).

Tip:If you do not want to log a particular image, specify NO for the image type. For example, the following code turns off logging the error images, but the administrative, before, and data images continue to be logged: log error_image=no;

SUSPEND: suspends event logging to the audit file, but does not delete the audit file.

RESUME: resumes event logging to the audit file, if it was suspended.

TERMINATE: terminates event logging and deletes the audit file.

USER_VAR variable-1 < … variable-n>

defines optional variables to be logged in the audit file with each update to an observation. When you use USER_VAR, it must follow an INITIATE statement. The following syntax defines variables:

USER_VAR variable-name-1 <$> <length> <LABEL='variable-label' >
<… variable-name-n <$> <length> <LABEL='variable-label' > >

where

variable-name: is a name for the variable.

Restriction:The USER_VAR statement is optional. If specified, the USER_VAR statement must immediately follow the INITIATE statement for the applicable audit file.

$: indicates that the variable is a character variable.

Details

Creating an Audit File

The following example creates the audit file MYLIB.MYFILE.AUDIT to log updates to the data file MYLIB.MYFILE.DATA, storing all available record images:

proc datasets library=mylib;
   audit myfile (alter=password);
   initiate;
run;

The following example creates the same audit file but stores only error record images:

proc datasets library=mylib;
   audit myfile (alter=password);
   initiate;
      log data_image=no 
          before_image=no
          data_image=no;
run;

The following example initiates an audit file using AUDIT_ALL=YES:

proc datasets lib=mylib;  /* all audit image types will be logged 
                             and the file cannot be suspended */
     audit myfile (alter=password);
     initiate audit_all=yes;
quit;

The following example terminates an audit file:

proc datasets lib=mylib;           
     audit myfile (alter=password);
     terminate;
quit;

The AUDIT statement starts an audit run group for a file. Multiple audit run groups for that file can be submitted in the following ways:

in the same PROC DATASETS step
in separate PROC DATASETS steps
in separate SAS sessions

All audit file related statements (INITIATE, USER_VAR, LOG, SUSPEND, RESUME, TERMINATE) must be preceded by an AUDIT statement, which identifies the file that they apply to.

The INITIATE statement creates an audit file and must be submitted in the first AUDIT statement occurrence. No other audit-related statement, such as USER_VAR, LOG, SUSPEND, RESUME, or TERMINIATE will be valid for that audit file until the INITIATE statement has been submitted. You can initiate an audit file on a generation data set, but it must be the latest generation of the generation group. You cannot specify a GENNUM to identify the latest generation. You will get the latest generation by default.

The following is an example of the AUDIT statement in the first AUDIT run group for a given file:

AUDIT file <(SAS-password)>;

Once an audit file has been initiated, the AUDIT statements that follow the INITIATE statement for that file can specify a GENNUM:

 AUDIT file <(<SAS-password><GENNUM=integer>)>;

The USER_VAR statement must directly follow the INITIATE statement in the same AUDIT run group.