Triggers (QVCS-Pro Only)

QVCS-Pro allows you to define what are called trigger programs. A trigger program is a separate executable that QVCS-Pro will invoke either before or after a QVCS operation.

Triggers provide a way to work your own logic or business process into QVCS version control operations. For example, QVCS uses the access list of an archive to determine whether a user is allowed to check out a revision. Using triggers, you could impose additional business/process rules on that check-out operation so that some check-outs that QVCS would allow would be dis-allowed.

If you have indicated that a trigger program should run before a QVCS operation, QVCS will invoke that trigger program before the QVCS operation. QVCS will wait for the trigger program to exit. If the trigger program exits with a status of 0, then QVCS will perform the QVCS operation. If the trigger program exits with any other status, QVCS will skip the QVCS operation.

If you have indicated that a trigger program should run after a QVCS operation, QVCS will invoke that trigger program after the QVCS operation, and wait for the trigger program to complete.

Enabling Triggers

To use triggers, you must write your own trigger program. A very simple trigger program is included with QVCS (SimpleTrigger.cpp and its associated SimpleTrigger.exe). In your trigger program, you must accept the name of a file on the command line, i.e. the command line that QVCS will use will look like:

Triggercommand someTempfilename

That file will contain information about the QVCS operation that is either going to be performed, or has already been performed. The contents of that file looks something like:

OPERATION_NAME: UnLock
USER_NAME: JimVoris
WORK FILE_NAME: C:\QumaTestArea\work files\Resume\RESUME.DOC
ARCHIVE_NAME: C:\QumaTestArea\work files\Resume\RESUME.EPD
COMMENT:
LABEL:
REVISION: 1.8

The OPERATION_NAME field identifies the QVCS operation. Operations that can be associated with triggers are:

Create	This operation indicates the creation of a QVCS archive, i.e., adding a file to the project.
CheckIn	This operation indicates the check-in of a revision into a QVCS archive.
CheckOut	This operation indicates the check-out of a revision from a QVCS archive.
Get	This operation indicates the get of a revision from a QVCS archive.
Label	This operation indicates the application of a label to a QVCS archive.
RemoveLabel	This operation indicates the removal of a label from a QVCS archive.
Lock	This operation indicates the locking of a revision in a QVCS archive.
UnLock	This operation indicates the unlocking of a revision in a QVCS archive.

The USER_NAME field identifies the QVCS user who is performing the indicated operation.

The WORK FILE_NAME is the full name of the work file to which the operation applies.

The ARCHIVE_NAME is the full name of the QVCS archive to which the operation applies.

The COMMENT field may be empty, or it may contain the comment associated with the operation.

The LABEL field may be empty, or it may contain the label associated with the requested operation.

The REVISION field may be empty, or it may contain the revision for the operation.

The temporary file whose name is passed on the command line will be deleted immediately after your trigger program executes.

You define whether to use triggers, and the names of the trigger command(s) via the Admin→Preferences... dialog. For QVCS-Pro users, there is a Define Triggers tab on the Preferences dialog.

On the dialog, there are four categories of triggers: Check-In triggers, Check-Out triggers, Label triggers, and Get triggers. The Check-In triggers are used for Create, CheckIn and UnLock operations. The Check-Out triggers are used for both CheckOut and Lock operations. The Label triggers are used for both Label and RemoveLabel operations. The Get triggers are used for non-locking get operations.

To enable a trigger operation, you must enable the associated check-box, and enter the name of your trigger program. Whenever QVCS performs that operation from within QWin, from within an IDE, or from a QVCS command line tool, the associated trigger program will be invoked (either before and/or after, depending on your preferences).

To get a simple introduction to the use of triggers, you can use the SimpleTrigger.exe program as a trigger program. The SimpleTrigger program just reads the temp file, echoes its contents to a command window, and then asks whether to perform the requested operation. An answer of 'y' will cause SimpleTrigger to exit with a status of 0 (meaning the operation should be performed); an answer of 'n' will cause SimpleTrigger to exit with a status of 1 (meaning the operation should not be performed).