Writing triggers for the ClearCase Remote Client

BM® Rational® ClearCase® Remote Client (CCRC) supports interactive triggers that use clearprompt to interact with users. In a remote client-server environment like CCRC, there are considerations that trigger developers need to be aware of.

Solution

User Interaction

CCRC client now supports clearprompt interaction which:

· provides list, text, proceed, and yes_no dialogs.

· does not support File dialog because of ambiguities in client-side file selection versus server side utilization.

· times out after five minutes without user response.

Note: Under certain conditions, pre-op triggers will not work (for example, triggers that look into a file before the operation).

Since CCWeb (when being accessed by a browser) does not support clearprompt, trigger writers may need to adjust the behavior when writing triggers for all of the clients in the enterprise. The ATRIA_WEB_GUI environment variable can be used to distinguish between a CCWeb or CCRC user and a traditional “thick” client user. However, a ClearCase trigger cannot distinguish between a CCRC user and a CCWeb browser user. When a trigger fires that requires clearprompt for a CCWeb browser user, CCWeb should display an error message indicating that it doesn't support the clearprompt protocol and clearprompt will return an error code instead of a valid yes/no/abort/proceed response code.

Trigger Output

· If the CCRC operation fails, trigger output should appear in the client error message; for example, a pre-op checkin trigger that fails will cause the CCRC checkin operation to fail.

· If the CCRC operation does not fail, output is not shown (for example, because a post-checkout trigger failure won't stop checkout, output won’t be displayed). Trigger output may be present in internal status information returned from the host but it is not displayed to the user.

· On Windows, Perl scripts do not capture output from sub processes such as system calls (calls to clearprompt, for example) or secondary Perl scripts (nested triggers that call other triggers). So error messages can be lost before they get back to the client user.

Debugging suggestion: Since the client does not always see trigger output sent to stdout, the trigger developer can add a local function that prints debug output to a text file on the server for analysis.

Example:

sub debugPrint {

my ($m) = @_;
open (OUTFILE, ">>c:/temp/debugPrint.out");
print OUTFILE "$m\n";
close OUTFILE;
}

debugPrint(“Reached step one”);

Environment

CCRC runs as a client process that sends RPC commands to the CCRC server, where they are executed by separate CCRC server processes. These server processes run under Apache, so the environment variables (EVs) will likely be different from those seen in command shell windows during interactive development.

To display what the current system environment is for a CCRC server (this only displays RWP variables and basic web server or system environments):

· Pass http://hostname/ccrc/?cmd=dump in a browser and supply a username and password when prompted.

· To display a more detailed listing of a users credentials, use http://hostname/ccrc/?cmd=creds

The server config file (rwp.conf, ccrc.conf) can be modified to add environment variables using the SetEnv command. This is one way to set an EV that defines the machine OS, etc. There may also be other ways to get essential environment information using standard Perl packages like Config.pm instead of relying on locally defined EVs.

CCRC server processes are started as the "system" user and then impersonate the original CCRC client user. This means that the trigger can't assume EVs exist that define where the "user home" directory is (for example, "~" on UNIX or "Documents and Settings/" on Windows).

The primary group for a ClearCase Remote Client can be set under the workspace preferences (This is only applicable to Windows based CCRC Servers)

· Temporary files. The lack of reliance on a "home" or a persistent user temp directory can complicate relying on the EV's to determine where user-specific temporary files go and where data can be cached between trigger invocations. Using a more generic temp file directory and process-specific suffices (i.e. c:\temp\tempfile.2034) is one solution

· Paths to supporting executables can also be problematic if the path where the executables lives tends to rely on local user environment definitions (.cshrc and %USERHOME% etc)

ClearCase Operations

· The CLEARCASE_* EVs are defined because the trigger is a sub process under the server-side ClearCase operation , i.e. checkout.

· CLEARCASE_* pathname EVs (CLEARCASE_PN, CLEARCASE_XPN, etc) reference a temporary snapshot view on the server side (backing store) which is an unpopulated area where files appear temporarily during operations.

· The file may not exist in the server snapshot view when the trigger fires. A pre-checkin trigger will NOT see the file or the correct contents on the server side until AFTER the checkin has occurred. A post-checkin trigger will see the correct contents. The file will not necessarily stay around long after the operation so a later trigger for another file may find the earlier file no longer available.

The CLEARCASE_SERIES_* EV's are NOT currently supported. These EV's identify when a ClearCase operation is part of a "batch" of related operations, i.e. when checking out 10 files together. Currently interactive triggers can NOT determine when a series is in progress.