ClearCase Reference Manual, Release 4.0, Windows

clearaudit

Non-clearmake build and shell command auditing facility for dynamic views

APPLICABILITY

ClearCase (command)

SYNOPSIS

clearaudit [ shell_cmd ]

DESCRIPTION

NOTE: clearaudit is applicable to dynamic views only.

The clearaudit command runs an audited shell with the same view and working directory as the current process. MVFS files created within an audited shell (or any of its children) are derived objects (DOs). When it exits, an audited shell creates a configuration record (CR) and associates it with each of the newly created DOs.

The CR and DOs produced by clearaudit are similar to those created by clearmake. They can be listed, compared, and deleted with the same cleartool commands used for other DOs (see below). They can be shared with other views through explicit winkin commands, but they cannot be winked in by clearmake. They can be checked in as DO versions. For more information about configuration records, see Derived Objects and Configuration Records in Building Software with ClearCase.

clearaudit itself is not a shell. It starts an audit and then executes an underlying shell. clearaudit determines which shell to run as follows:

First choice: the value of environment variable CLEARAUDIT_SHELL, which must be the full pathname of a program
Second choice: the value of environment variable COMSPEC, which must be the full pathname of a program
If neither EV is set: cmd.exe

The process from which you invoke clearaudit must have a view context; the audited process uses that view. An error occurs if the invoking process has no view context.

Location of Temporary Build Files

clearaudit creates temporary build files in the directory specified by the CCASE_AUDIT_TMPDIR environment variable. If this EV is not set or is set to an empty value, clearaudit creates temporary files in the directory specified by the TMP environment variable. All temporary files are deleted when clearaudit exits. If the value of CCASE_AUDIT_TMPDIR is a directory under a VOB-tag, clearaudit prints an error message and exits.

Auditing Any Process

clearaudit can be used to document the work performed by any process. For example, you can use clearaudit to audit a backup operation, producing a configuration record that describes exactly which files and/or versions were saved.

Auditing a Non-ClearCase make

You can also use clearaudit to produce derived objects and configuration records for software builds performed with another make program, such as nmake. Follow these guidelines:

Set the value of COMSPEC to ccase-home-dir\bin\clearaudit in the makefile.
Set your process's CLEARAUDIT_SHELL environment variable to your normal shell, for example, %SYSTEMROOT%\system32\cmd.exe. This prevents recursive invocation of clearaudit: if CLEARAUDIT_SHELL is not set, clearaudit attempts to start the shell specified in COMSPEC, which was set to clearaudit.
If you want to produce a single CR for each target's build script, structure your makefiles so that each build script is a single shell command. Use continuation lines (^) as necessary.

OPTIONS AND ARGUMENTS

shell_cmd: One or more words, which are passed as arguments to %CLEARAUDIT_SHELL% (or %COMSPEC%, or cmd.exe).

NOTE: Some shells, including cmd.exe, require the use of the /c shell option, which tells the shell what command to execute. This option must precede any shell_cmd arguments.

EXAMPLES

Run program myscr in an audited command shell.

C:\> clearaudit /c myscr

Run program validation_suite in an audited third-party shell tool.

C:\> set CLEARAUDIT_SHELL= R:\MKSNT\mksnt\bin\sh.exe

C:\> clearaudit /c validation_suite

This example shows a typical CR produced by clearaudit. It describes all files produced by a software build with Microsoft's nmake. View-private files are marked with time stamps.

Target ClearAudit_Shell built by block.user Host "starfield" running Windows NT 3.5 Reference Time 16-Nov-98.10:24:08, this audit started 16-Nov-98.10:24:08 View was \\saturn\vw_store\proj3\941931.vws Initial working directory was m:\vobs\src\test ---------------------------- MVFS objects: ---------------------------- \myvob\src\test\hello@@16-Nov.10:25.16742 \myvob\test\hello.c <16-Nov-98.10:11:34> \myvob\test\hello.o@@16-Nov.10:25.16740 \myvob\test\makefile <16-Nov-98.10:23:57>

Run a batch file that performs a backup in an audited shell; create an empty derived object (bkup_do) whose CR lists all of the backed-up objects.

C:\> clearaudit /c audit_bkup C:\users e:

Batch file audit_bkup:

rem echo Audited backup of %1 echo Backup destination is %2 backup %1 %2 /s rem echo Creating derived object bkup_do echo "" > .\bkup_dofc