/ 
VCS-CMSynergy-1.07
River stage zero No dependents
/ VCS::CMSynergy

NAME

VCS::CMSynergy - Perl interface to Telelogic CM Synergy

SYNOPSIS

use VCS::CMSynergy;

$ccm = VCS::CMSynergy->new(%attr);

($rc, $out, $err) = $ccm->ccm($ccm_command, @ccm_args);
($rc, $out, $err) = $ccm->any_ccm_command(@ccm_args);

$ary_ref = $ccm->query(@ccm_args);
$ary_ref = $ccm->query_object($query);
$ary_ref = $ccm->query_arrayref($query, @keywords);
$ary_ref = $ccm->query_hashref($query, @keywords);

$ary_ref = $ccm->finduse(@args);
$path = $ccm->findpath($file_spec, $proj_vers);

$ary_ref = $ccm->history(@ccm_args);
$ary_ref = $ccm->history_arrayref($file_spec, @keywords);
$ary_ref = $ccm->history_hashref($file_spec, @keywords);

$ary_ref = $ccm->ls(@ccm_args);
$ary_ref = $ccm->ls_object($file_spec);
$ary_ref = $ccm->ls_arrayref($file_spec, @keywords);
$ary_ref = $ccm->ls_hashref($file_spec, @keywords);

$value = $ccm->attribute($attr_name, $file_spec);
$ccm->attribute($attr_name, $file_spec, $value);
$hash_ref = $ccm->attributes($file_spec);

$delim = $ccm->delimiter;
@types = $ccm->types;

$last_error = $ccm->error;
$last_ccm_command = $ccm->ccm_command;

($ccm, $schema, $informix, @patches) = $h->version;
@ary = $h->databases;
$ary_ref = $h->ps;
$ary_ref = $h->ps(\%attr);
$ary_ref = $h->status;

This synopsis above only lists the major methods. Methods for administering users and their roles are described in the VCS::CMSynergy::Users documentation.

DESCRIPTION

  use VCS::CMSynergy;

  my $ccm = VCS::CMSynergy->new(database => "/ccmdb/test/tut62/db");

  $ccm->checkout(qw(foo/bar.c@foo~user -to test))
    or die "checkout failed: ".$ccm->error;

  my $csrcs = $ccm->query_hashref("type = 'csrc'",
				  qw(displayname modify_time));
  if ($csrcs)
  {
    print "$_->{displayname} $->{modify_time}\n" foreach (@$csrcs);
  }

METHODS

new
my $ccm = VCS::CMSynergy->new( database => "/ccmdb/foo/db" )
            or die VCS::CMSynergy->error;

Starts a new CM Synergy session. Returns a session handle if it succeeds.

If it fails to start a session, it returns undef. Use VCS::CMSynergy->error to get the error string printed by CM Synergy.

Multiple simultaneous sessions to multiple databases or with engines running on different hosts, even using different versions of CM Synergy, are supported.

new issues a ccm start command and remembers the CCM_ADDR in the session object (together with other session state). The session is stopped (ccm stop) when the session object is destroyed (see "DESTROY").

new is called with an attribute hash. The following attributes are currently supported:

database

CM Synergy database path.

This is the only attribute required on Unix systems.

host

CM Synergy engine host to use.

It defaults to the local host.

role

User's initial CM Synergy role.

It defaults to developer.

user

CM Synergy user.

This attribute is available and required on Windows systems only.

password

User's password.

This attribute is available and required on Windows systems only.

PrintError

This attribute can be used to force errors to generate warnings (using "carp" in Carp) in addition to returning error codes in the normal way. When set to true, any method which results in an error occuring will cause the corresponding $ccm->error to be printed to stderr.

It defaults to 1.

"PrintError" and "RaiseError" below are stolen from the excellent DBI module.

RaiseError

This attribute can be used to force errors to raise exceptions (using "croak" in Carp) rather than simply return error codes in the normal way. When set to true, any method which results in an error will cause effectively a die with the actual $ccm->error as the message.

It defaults to 0.

If you turn RaiseError on then you'd normally turn PrintError off. If PrintError is also on, then the PrintError is done first (naturally).

Typically RaiseError is used in conjunction with eval { ... } to catch the exception that's been thrown and followed by an if ($@) { ... } block to handle the caught exception.

If you want to temporarily turn RaiseError off (inside a library function that is likely to fail, for example), the recommended way is like this:

{
  local $ccm->{RaiseError};  # localize and turn off for this block
  ...
}

The original value will automatically and reliably be restored by Perl, regardless of how the block is exited. The same logic applies to other attributes, including PrintError.

ini_file

CM Synergy ini file to use.

In contrast to the CM Synergy ccm start command there is no default ini file consulted. (On Unix systems this is achieved by executing ccm start with the option -f /dev/null.) The reason is that we want scripts to behave in a reproducible way. Otherwise the script might accidentally work with the current contents of the current user's ini file, but might fail when invoked by another user. Or it might fail when invoked by the same user at a later time because of changes to her ini file (e.g. because of another session between invocations of the script). So if you really want to rely on an ini file, you have to supply it explicitly.

CCM_ADDR

Specifies the RFC address of an established CM Synergy session.

If you specify this attribut "new" does not create a new session, but will use the one specified. Also, destruction of the returned session handle will not cause a ccm stop.

Note that there is no default value. In particular, "new" ignores the environment variable of the same name.

CCM_HOME

Value of the CCM_HOME environment variable to use for this session.

It defaults from the environment variable of the same name, i.e. $ENV{CCM_HOME}.

This is only of interest if you have multiple version of CM Synergy installed. You can have simultaneous sessions using different CM Synergy versions (the module takes care of setting the CCM_HOME variable appropriately before issuing any ccm commands).

ui_database_dir

Specifies the path name to which your database information is copied when you are running a remote client session. This corresponds to the -u pathname option for ccm start.

FIXME

describe sessions attributes (RaiseError,PrintError,...)

DESTROY
$ccm->DESTROY;

Stops the CM Synergy session represented by the session handle by executing ccm stop (unless the session has the reuse attribut set).

There is usually no need to call this method explicitly, as it is invoked by the Perl runtime when the Perl process exits (either by calling exit or because of a die). Hence, a script using the VCS::CMSynergy module will not leave any CM Synergy sessions hanging around.

Actually, the Perl runtime will call DESTROY when the last reference to a session handle goes out of scope, so in the following example each session will be stopped as soon as one loop through the foreach body is completed, i.e. there is at most one session in progress at any one time:

my @databases = ...;		# a list of CM Synergy databases
foreach my $db (@databases)
{
  my $ccm = VCS::CMSynergy->new( database => $db, ... );
  ...
  # perform some operation on $db
  ...
  # session is stopped as "my" variable $ccm is about to go out of scope
}
ccm
($rc, $out, $err) = $ccm->ccm($command, @args);

This is the workhorse of the VCS::CMSynergy module. It executes ccm with command $command and (optional) parameters @args. In array context it returns a three-element array consisting of the (operating system) exit code of ccm, and what ccm printed on stdout and stderr. Note that the exit code is 0 if ccm operated successfully. On DOSish operating systems the (possibly multi-line) strings $out and $err have been read by Perl in "text" mode, i.e. contain LF characters instead of CRLF. In any case, $out and $err have been chomped.

In scalar context ccm returns the "logical" exit code, i.e. !$rc, so that you can write:

$ccm->ccm('checkout', $file_spec) 
    or die "checkout failed: ".$ccm->error;

Note that you must pass every ccm argument or option as a single Perl argument. For literal arguments the qw() notation may come in handy, e.g.

($rc, $out, $err) = $ccm->ccm(qw(finduse -state working));

Most specialized methods in the VCS::CMSynergy module are ultimately implemented via the "ccm" method. Using it directly is only recommended for commands that perform some action, e.g. ccm checkout, as opposed to query-like commands. For the latter, e.g. ccm query, use one of the methods that return the information in structured form, e.g. "query_arrayref" or "query_hashref", instead of having to parse $out yourself.

In fact, there is a shortcut for "action" commands: if you call a non-existent method on a VCS::CMSynergy object, it tries to invoke the "ccm" method with the original method name as the $command followed by the parameters of the original call, i.e.

$ccm->checkout($file_spec);

and

$ccm->ccm('checkout', $file_spec);

are equivalent (given that there is no real checkout method). Return values are those of "ccm" (depending on context). This is accomplished by a suitable AUTOLOAD method.

delimiter
$delim = $ccm->delimiter;

Returns the database delimiter.

query
$ary_ref = $ccm->query(@args);

Executes the ccm query command with the given @args as parameters. The output (as formatted by the -format option) is split into lines. These are chomped and a reference to the resulting array of strings is returned.

If there a no hits, a reference to an empty array is returned. (Note that ccm query considers this an error, but the VCS::CMSynergy module does not.)

If there was an error, undef is returned.

Note that you must pass every ccm query argument or option as a single Perl argument. For literal arguments the qw() notation may come in handy. Example:

$result = $ccm->query(qw(-t csrc -f), '%displayname %modify_time');
print "$_\n" foreach (@$result);

If you are interested in the value of several attributes for the result set of the query, you should look at the "query_arrayref" and "query_hashref" methods that return this information in structured form. If you are only interested in the identity of objects in the result set, you should look at the "query_object" method.

Note that "query" will probably produce unpredictable results when the -format option references attributes that can have multi-line values, e.g. status_log. "query_arrayref" and "query_hashref" handle this case correctly.

query_object
$ary_ref = $ccm->query_object($query);

Executes ccm query with the query expression $query and returns a reference to an array of VCS::CMSynergy::Objects that satisfy the query.

If there a no hits, a reference to an empty array is returned.

If there was an error, undef is returned.

NOTE: This query method does not support any of the shortcut query options of the ccm query command, e.g. -o owner or -n name, as these can all be expressed by suitable sub clauses of the $query expression.

query_arrayref
$ary_ref = $ccm->query_arrayref($query, @keywords);

Executes ccm query with the query expression $query asking for the values of the built-in keywords or attributes supplied in @keywords. Returns a reference to an array of references, one per result row. Each reference points to an array containing the values of the keywords for that particular object in the result set (in the order given by @keywords).

If there a no hits, a reference to an empty array is returned.

If there was an error, undef is returned.

If the value of a keyword or an attribute is undefined or the attribute is not present, the actual value of the corresponding array element is undef (whereas ccm query would print it as the string "void").

The following names may also be used as keywords though they are neither built-in nor attributes:

object

The value is a VCS::CMSynergy::Object representing the object in the result set.

finduse

The value is a reference to an array of names in project reference form identifying in what parts of what projects the object is used. This is the same list as reported by ccm finduse. In fact, if this keyword is given, "query_arrayref" invokes ccm finduse -query $query rather than ccm query $query.

Note that the keyword or attribute names given in @keywords should not contain a leading %. Example:

my $result = $ccm->query_arrayref("name match '*.c'", 
                                  qw(displayname type modify_time);
foreach my $row (@$result)
{
  my ($displayname, $type, $modify_time) = @$row;
  print "$displayname ($type) last modified at $modify_time\n";
  ...
}

NOTE: This query method does not support any of the shortcut query options of the ccm query command, e.g. -o owner or -n name, as these can all be expressed by suitable sub clauses of the $query expression.

query_hashref
$ary_ref = $ccm->query_hashref($query, @keywords);

Executes ccm query with the query expression $query asking for the values of the built-in keywords or attributes supplied in @keywords. Returns a reference to an array of references, one per result row. Each reference points to hash containing attribute and value pairs where the keys are @keywords.

If there a no hits, a reference to an empty array is returned.

If there was an error, undef is returned.

If the value of a keyword or an attribute is undefined or the attribute is not present, the actual value of the corresponding hash element is undef (whereas ccm query would print it as the string "void").

The following names may also be used as keywords though they are neither built-in nor attributes:

object

The value is a VCS::CMSynergy::Object representing the object in the result set.

finduse

The value is a reference to an array of names in project reference form identifying in what parts of what projects the object is used. This is the same list as reported by ccm finduse. In fact, if this keyword is given, "query_arrayref" invokes ccm finduse -query $query rather than ccm query $query.

Note that the keyword or attribute names given in @keywords should not contain a leading %. Example:

my $result = $ccm->query_hashref("name match '*.c'", 
                                 qw(displayname type modify_time);
foreach my $row (@$result)
{
  print "$row->{displayname} last modified at $row->{modify_time}\n";
  ...
}

NOTE: This query method does not support any of the shortcut query options of the ccm query command, e.g. -o owner or -n name, as these can all be expressed by suitable sub clauses of the $query expression.

history
$ary_ref = $ccm->history(@args);

Executes the ccm history command with the given @args as parameters. The output (probably formatted by the -format option) is split into chunks at the divider line (a line consisting of lots of asterisks). A reference to the resulting array of (multi-line) strings is returned.

If there was an error, undef is returned.

Note that you must pass every ccm history argument or option as a single Perl argument. For literal arguments the qw() notation may come in handy.

If you are interested in the successor or predecessor or certain attributes of an object in the history, you should look at the "history_arrayref" and "history_hashref" methods that return this information in structured form.

history_arrayref
$ary_ref = $ccm->history_arrayref($file_spec, @keywords);

Executes ccm history for $file_spec asking for the values of the built-in keywords or attributes supplied in @keywords. Returns a reference to an array of references, one per history entry. Each reference points to an array containing the values of the keywords for that particular object in the history (in the order given by @keywords).

If there a no hits, a reference to an empty array is returned.

If there was an error, undef is returned.

If the value of a keyword or an attribute is undefined or the attribute is not present, the actual value of the corresponding array element is undef (whereas ccm history would print it as the string "void").

The following names may also be used as keywords though they are neither built-in nor attributes:

object

The value is a VCS::CMSynergy::Object representing the object in the history.

predecessors

The value returned is a reference to an array of VCS::CMSynergy::Objects that represent the given object's predecessors.

successors

The value returned is a reference to an array of VCS::CMSynergy::Objects that represent the given object's successors.

Note that the keyword or attribute names given in @keywords should not contain a leading %. Example:

my $result = $ccm->history_arrayref('math.h-1:incl:1', 
                                    qw(displayname modify_time successors);
foreach my $row (@$result)
{
  my ($displayname, $modify_time, $successors) = @$row;
  print "$displayname: last modified at $modify_time\n";
  print "\t$_\n" foreach (@$successors);
  ...
}
history_hashref
$ary_ref = $ccm->history_hashref($file_spec, @keywords);

Executes ccm history for $file_spec asking for the values of the built-in keywords or attributes supplied in @keywords. Returns a reference to an array of references, one per history entry. Each reference points to a hash containing attribute and value pairs where the keys are @keywords.

If there was an error, undef is returned.

If the value of a keyword or an attribute is undefined or the attribute is not present, the actual value of the corresponding hash element is undef (whereas ccm history would print it as the string "void").

The following names may also be used as keywords though they are neither built-in nor attributes:

object

The value is a VCS::CMSynergy::Object representing the object in the history.

predecessors

The value returned is a reference to an array of VCS::CMSynergy::Objects that represent the given object's predecessors.

successors

The value returned is a reference to an array of VCS::CMSynergy::Objects that represent the given object's successors.

Note that the keyword or attribute names given in @keywords should not contain a leading %. Example:

my $result = $ccm->history_hashref('math.h-1:incl:1', 
                                   qw(displayname modify_time successors);
foreach my $row (@$result)
{
  print "$row->{displayname}: last modified at $row->{modify_time}\n";
  print "\t$_\n" foreach (@{ $row->{successors} });
  ...
}
finduse
$ary_ref = $ccm->finduse(@args);

Executes the ccm finduse command with the given @args as parameters. It returns a reference to an array of rows, usually one per file_spec given in @args, or one per query result if -query $query_expression is present in @args. Each row is a reference to an array, the first element is the description of the object followed by uses of the object given in project reference form. If there are no uses of the object in the given scope the array consists only of the first element.

If there was an error, undef is returned.

Note that you must pass every ccm finduse argument or option as a single Perl argument. For literal arguments the qw() notation may come in handy.

If you are interested in obtaining certain attributes of for all objects matching a query as well as their project usage, you should look at the "query_arrayref" and "query_hashref" methods, esp. the "finduse" keyword.

Example (recreate the output of the ccm finduse command):

  my $uses = $ccm->finduse(@args);
  foreach my $row (@$uses)
  {
    print shift @$row, "\n";
    if (@$row)
    {
	print "\t$_\n" foreach (@$row);
    }
    else
    {
	print "\tObject is not used in scope.\n";
    }
  }
findpath
$path = $ccm->findpath($file_spec, $proj_vers);

This is a convenience function. It returns the relative pathname for the object $file_spec within the project $proj_vers.

Returns undef if $file_spec is not used in $proj_vers or if $file_spec does not exist.

Example:

$ccm->findpath("main.c-1:csrc:3", "guilib-darcy"); 
# returns "guilib/sources/main.c"
attribute
$value = $ccm->attribute($attr_name, $file_spec);
$ccm->attribute($attr_name, $file_spec, $value);

Gets or sets an attribute associated with an object.

The first form gets the value of the attribute $attr_name for $file_spec (using (ccm attribute -show). If RaiseError is not set and an error occurs (e.g. attribute $attr_name does not exist on object $file_spec), undef will be returned.

The second form sets the value of the attribute $attr_name for $file_spec to $value (using (ccm attribute -modify). This works for all types of attributes, even those of type text or derived from text. Returns $value on success. If RaiseError is not set and an error occurs (e.g. attribute $attr_name does not exist on object $file_spec), undef will be returned.

attributes
$hash_ref = $ccm->attributes($file_spec);

Lists all attributes for $file_spec (using ccm attribute -la). Returns a reference to a hash containing pairs of attribute name and attribute type (e.g. string, time). Returns undef in case of error.

types
@types = $ccm->types;

Returns an array of types from ccm show -types.

error
$last_session_error = $ccm->error;
$last_cmsynergy_error = VCS::CMSynergy->error;

Returns the last error that occured in the session or in any VCS::CMSynergy session, resp.

ccm_command
$last_session_command = $ccm->ccm_command;
$last_cmsynergy_command = VCS::CMSynergy->ccm_command;

Returns the last CM Synergy command invoked in the session or in any VCS::CMSynergy session, resp.

ls
$ary_ref = $ccm->ls(@args);

Executes the ccm ls command with the given @args as parameters. The output (as formatted by the -format option) is split into lines. These are chomped and a reference to the resulting array of strings is returned.

If there was an error, undef is returned.

Note that you must pass every ccm ls argument or option as a single Perl argument.

If you are interested to obtain the value of several attributes, you should look at the "ls_arrayref" and "ls_hashref" methods that return this information in structured form. If you are only interested in the identity of the listed objects, you should look at the "ls_object" method.

ls_object
$ary_ref = $ccm->ls_object($file_spec);

Lists information about a file or the contents of a directory using the work area name $file_spec. Returns a reference to an array of corresponding VCS::CMSynergy::Objects. The default $file_spec is the working directory.

ls_arrayref
$ary_ref = $ccm->ls_arrayref($file_spec, @keywords);

Lists the values of the built-in keywords or attributes supplied in @keywords for a file or the contents of a directory using the work area name $file_spec. Returns a reference to an array of references, one per result row. Each reference points to an array containing the values of the keywords for that particular object (in the order given by @keywords).

If there was an error, undef is returned.

If the value of a keyword or an attribute is undefined or the attribute is not present, the actual value of the corresponding array element is undef (whereas ccm ls would print it as the string "void").

Note that the keyword or attribute names given in @keywords should not contain a leading %. Example:

my $result = $ccm->ls('foo', qw(displayname type modify_time);
foreach my $row (@$result)
{
  my ($displayname, $type, $modify_time) = @$row;
  print "$displayname ($type) last modified at $modify_time\n";
  ...
}
ls_hashref
$ary_ref = $ccm->ls_hashref($file_spec, @keywords);

Lists the values of the built-in keywords or attributes supplied in @keywords for a file or the contents of a directory using the work area name $file_spec. Returns a reference to an array of references, one per result row. Each reference points to hash containing attribute and value pairs where the keys are @keywords.

If there was an error, undef is returned.

If the value of a keyword or an attribute is undefined or the attribute is not present, the actual value of the corresponding hash element is undef (whereas ccm ls would print it as the string "void").

Note that the keyword or attribute names given in @keywords should not contain a leading %. Example:

my $result = $ccm->ls_hashref('foo', qw(displayname type modify_time);
foreach my $row (@$result)
{
  print "$row->{displayname} last modified at $row->{modify_time}\n";
  ...
}
set
$value = $ccm->set($option);
$old_value = $ccm->set($option, $new_value);
$hash_ref = $ccm->set;

Get or sets the value of an option.

In the first form it returns the value of $option. If the option is unset, undef is returned (whereas ccm set would print "(unset)" in this case).

In the second form, the $option is set to $new_value, the previous value is returned. If $new_value is undef, $option is unset.

In the third form, a reference to a hash is returned. The hash consists of all currently defined options as keys and their respective values.

ps
$ary_ref = $ccm->ps;
$ary_ref = $ccm->ps(user => "jdoe", process => "gui_interface", ...);

Executes ccm ps and returns a reference to an array of references, one per CM Synergy process. Each reference points to a hash containing pairs of field names (e.g. host, database, pid) and values for that particular process as listed by ccm ps.

The available keys vary with the type of the process (e.g. engine, gui_interface). The process type is listed under key process. The key rfc_address is always present. The object registrar (i.e. the unique process with key process equal to "objreg") has a special key db. Its value is a reference to an array of database names that the registrar as encountered during its lifetime.

In the second form of invocation, you can pass pairs of field name and field value and ps will only return processes whose fields match all the corresponding values. Note that in contrast to the ccm ps command, you can filter on multiple fields simultaneously.

This method can also be called as a class method, i.e. VCS::CMSynergy->ps, as it does not need an established session.

Here's an example of the value returned by ps as formatted by Data::Dumper:

  $ps = [
      {
	'process' => 'router',
	'host' => 'tiv01',
	'rfc_address' => 'tiv01:5415:160.50.76.15',
	'user' => 'ccm_root',
	'host_addr' => '',
	'pid' => '9428'
      },
      {
	'process' => 'gui_interface',
	'database' => '/ccmdb/tbd/slc/db',
	'engine_address' => 'tiv01:60682:160.50.76.15',
	'host' => 'lapis',
	'user' => 'q076273',
	'msg_handler_1' => 'uissys:message_handler',
	'display' => '',
	'callback' => 'vistartup:cb_init',
	'rfc_address' => 'lapis:1934:160.50.136.36',
	'pid' => '224',
	'host_addr' => ''
      },
      {
	'process' => 'cmd_interface',
	'database' => '/ccmdb/tbd/nasa_ix/db',
	'engine_address' => 'nasaora:1559:160.48.78.33',
	'host' => 'nasaora',
	'user' => 'qx06322',
	'msg_handler_1' => 'uissys:message_handler',
	'display' => 'nasaix11:0',
	'callback' => 'ciserver:cb_init',
	'rfc_address' => 'nasaora:1556:160.48.78.33',
	'pid' => '24367',
	'host_addr' => ''
      },
      {
	'process' => 'engine',
	'database' => '/ccmdb/tbd/nasa_ix/db',
	'host' => 'nasaora',
	'user' => 'qx06322',
	'callback' => 'engine_startup:cb_init',
	'rfc_address' => 'nasaora:1559:160.48.78.33',
	'pid' => '24490',
	'host_addr' => '',
	'ui_address' => 'nasaora:1556:160.48.78.33'
      },
      {
	'process' => 'objreg',
	'db' => [
		  '/ccmdb/tbd/nasa_ix/db',
		  '/ccmdb/tbd/slc/db',
		  '/ccmdb/tbd/eai/db',
		],
	'max_conns' => '256',
	'objreg_machine_addr' => '160.50.76.15',
	'host' => 'tiv01',
	'user' => 'ccm_root',
	'callback' => 'objreg:cb_init',
	'policy' => 'one_per_db',
	'noblock' => 'true',
	'rfc_address' => 'tiv01:60352:160.50.76.15',
	'objreg_machine' => 'tiv01',
	'host_addr' => '',
	'pid' => '9896',
	'objreg_machine_hostname' => 'tiv01'
      },
      ...
  ];
databases
@databases = $ccm->databases;
@databases = $ccm->databases($servername);

Returns an array containing the names of all known CM Synergy databases.

This method can also be called as a class method, i.e. VCS::CMSynergy->databases, as it does not need an established session.

version
($ccm, $schema, $informix, @patches) = $ccm->version;

Returns version info about the CM Synergy installation. In a scalar context version returns the (short) CM Synergy version number. In an array context the following information is returned:

  • the full CM Synergy version

  • the database schema version

  • the Informix version

  • a possible empty array of applied CM Synergy patches

This method can also be called as a class method, i.e. VCS::CMSynergy->version as it does not need an established session.

status
$ary_ref = $ccm->status;

Executes ccm status and returns a reference to an array of references, one per CM Synergy session. Each reference points to a hash containing pairs of field names (e.g. database) and values for that particular session.

The available keys are a subset of the keys returned by the "ps" method: rfc_address, database, user, and process. There is an additional key current with a boolean value marking CM Synergy's notion of the current session.

Note: Unlike the output of the ccm status command, the value for database has a trailing "/db". This makes it consistent with the session attribute database and the return value of "ps".

This method can also be called as a class method, i.e. VCS::CMSynergy->status, as it does not need an established session.

Here's an example of the value returned by status as formatted by Data::Dumper:

  $status = [
      {
	'process' => 'gui_interface',
	'database' => '/ccmdb/scm/support/db',
	'current' => '1',
	'rfc_address' => 'tiv01:53020:160.50.76.15',
	'user' => 'qx06959'
      },
      {
	'process' => 'gui_interface',
	'database' => '/ccmdb/scm/support/db',
	'current' => '',
	'rfc_address' => 'wmuc111931:4661:160.50.136.201',
	'user' => 'qx06959'
      },
      {
	'process' => 'cmd_interface',
	'database' => '/ccmdb/test/tut51/db',
	'current' => '',
	'rfc_address' => 'tiv01:53341:160.50.76.15',
	'user' => 'qx06959'
      }
  ];
trace
VCS::CMSynergy->trace($trace_level);
VCS::CMSynergy->trace($trace_level, $trace_filename);

This class method enables trace information to be written.

Trace levels $trace_level are as follows:

0 - Trace disabled.
1 - Trace VCS::CMSynergy method calls.
2 and above: FIXME

Initially trace output is written to STDERR. If $trace_filename is specified and can be opened in append mode then all trace output is redirected to that file. A warning is generated irfs the file can't be opened. Further calls to trace without a $trace_filename do not alter where the trace output is sent. If $trace_filename is undefined, then trace output is sent to STDERR and the previous trace file is closed.

The trace method returns the previous tracelevel.

See also "trace_msg".

You can also enable the same trace information by setting the CMSYNERGY_TRACE environment variable before starting Perl.

On Unix-like systems using a Bourne-like shell, you can do this easily on the command line:

CMSYNERGY_TRACE=2 perl your_test_script.pl

If CMSYNERGY_TRACE is set to a non-numeric value, then it is assumed to be a file name and the trace level will be set to 2 with all trace output appended to that file. If the name begins with a number followed by an equal sign (=), then the number and the equal sign are stripped off from the name, and the number is used to set the trace level. For example:

CMSYNERGY_TRACE=1=trace.log perl your_test_script.pl
trace_msg
$ccm->trace_msg($message_text);
$ccm->trace_msg($message_text, $min_level);

Writes $message_text to the trace file if trace is enabled. Can also be called as VCS::CMSynergy->trace_msg($msg). See "trace".

If $min_level is defined, then the message is output only if the trace level is equal to or greater than that level. $min_level defaults to 1.

use_ccm_coprocess
VCS::CMSynergy->use_ccm_coprocess;

This feature is highly experimental, use it at your own risk. You must have the Expect module installed to use this feature. (Since Expect is not available for Win32 systems, this feature cannot be used there.)

In its default operating mode, VCS::CMSynergy.pm invokes a separate ccm process for most simple methods, e.g.

$ccm->checkout('foo.c');
$ccm->checkout('bar.c');

results in the execution of

ccm checkout foo.c
ccm checkout bar.c

Hence we incur the startup overhead of ccm for most method invocations. This overhead is noticable, esp. if you are doing lots of CM Synergy operations.

If use_ccm_coprocess is in effect, only one ccm process per CM Synergy session is used. VCS::CMSynergy-new> starts an "interactive" ccm process, funnels commands to its input and reads back the output (up to the next "ccm>" prompt). This avoids the startup overhead, but may run into other problems, e.g. restrictions on the length of the ccm command line.

TODO

  • anything else?

SEE ALSO

VCS::CMSynergy::Users

AUTHORS

Roderich Schupp, argumentum GmbH <schupp@argumentum.de>

COPYRIGHT

Copyright (c) 2001-2002 argumentum GmbH, http://www.argumentum.de. All rights reserved.

You may distribute it under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.