The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
VCS-CMSynergy-1.31
River stage zero No dependents
++
/ VCS::CMSynergy::Client

NAME

VCS::CMSynergy::Client - base class for CM Synergy methods that don't require a session

SYNOPSIS

  use VCS::CMSynergy::Client;

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

  $ary_ref = $client->ps;
  $short_version = $client->version;
  @ary = $client->status;

  $client->trace(1, "trace.out");
  $client->trace_msg("now tracing ccm calls...\n");

  @ary = $client->databases;
  @ary = $client->hostname;

This synopsis only lists the major methods.

DESCRIPTION

In most cases there is no need to know about VCS::CMSynergy::Client, the base class of VCS::CMSynergy. If you have an established session, you can invoke all methods on the session object. If you want to use a method without a session (e.g. "ps"), invoke it as a class method:

  $ps = VCS::CMSynergy->ps;

You need to use VCS::CMSynergy::Client explicitly if

  • you want to use a method without a session and

  • you have several installations of CM Synergy, i.e. several $CCM_HOMEs, and

  • you want to switch between different $CCM_HOMEs in the same invocation of your program.

A typical example is an administrative program that iterates over all your CM Synergy databases in all your installations:

  foreach my $ccm_home (qw(/usr/local/ccm51 /usr/local/ccm62 /usr/local/ccm63))
  {
      print "installation in $ccm_home ...\n";
      my $client = VCS::CMSynergy::Client->new(CCM_HOME => $ccm_home);

      foreach my $db ($client->databases)
      {
          ...
      }
  }

All methods below (except new) can be invoked on either:

  • a VCS::CMSynergy::Client object

  • a VCS::CMSynergy object

  • the VCS::CMSynergy::Client class

  • the VCS::CMSynergy class

The former two always use the setting of CCM_HOME given at their creation, while the latter two actually operate on a "default" instance of VCS::CMSynergy::Client. This instance is created the first time any VCS::CMSynergy::Client or VCS::CMSynergy class method is invoked in the course of your program. Its CCM_HOME uses the value of $ENV{CCM_HOME} that was in effect at the time the default instance was created.

METHODS

new

  my $client = VCS::CMSynergy::Client->new( CCM_HOME => "/usr/local/ccm62" );

Creates a new CM Synergy client.

If it fails (e.g. CCM_HOME doesn't seem to contain a valid CM Synergy installation), it returns undef.

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

CCM_HOME (string)

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

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

PrintError (boolean)

This attribute can be used to force errors to generate warnings (using 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 "on".

RaiseError (boolean)

This attribute can be used to force errors to raise exceptions (using croak) 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 "off".

HandleError (code ref)

This attribute can be used to provide your own alternative behaviour in case of errors. If set to a reference to a subroutine then that subroutine is called when an error is detected (at the same point that "RaiseError" and "PrintError" are handled).

See the "HandleError (code ref)" in VCS::CMSynergy for details.

ccm_home

  print "CCM_HOME=", $client->ccm_home;

Returns the setting of CCM_HOME as used by the client.

error

  $last_error = $client->error;

Returns the last error that occured in this client.

ccm_command

  $last_cmsynergy_command = $client->ccm_command;

Returns the last CM Synergy command invoked on behalf of the VCS::CMSynergy::Client.

out

Returns the raw standard output of the last CM Synergy command invoked on behalf of the VCS::CMSynergy::Client. In scalar context the output is returned as a possibly multi-line string. In list context it is returned as an array of pre-chomped lines.

err

Returns the raw standard error of the last CM Synergy command invoked on behalf of the VCS::CMSynergy::Client. The return value is a possibly multi-line string regardless of calling context.

ps

  $ary_ref = $client->ps;
  $ary_ref = $client->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.

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' => '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/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'
      },
      ...
  ];

status

  $ary_ref = $client->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.

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".

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

  $status = [
      {
        'process' => 'gui_interface',
        'database' => '/ccmdb/scm/support/db',
        'rfc_address' => 'tiv01:53020:160.50.76.15',
        'user' => 'rschupp'
      },
      {
        'process' => 'gui_interface',
        'database' => '/ccmdb/scm/support/db',
        'rfc_address' => 'wmuc111931:4661:160.50.136.201',
        'user' => 'rschupp'
      },
      {
        'process' => 'cmd_interface',
        'database' => '/ccmdb/test/tut51/db',
        'rfc_address' => 'tiv01:53341:160.50.76.15',
        'user' => 'rschupp'
      }
  ];

version

  $short_version = $client->version;
  ($full_version, $schema_version, 
    $informix_version, @patches) = $client->version;

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

  • the full CM Synergy version (e.g. "6.2.3041")

  • the database schema version (e.g. "6.2")

  • the Informix version (e.g. "9.21.UC3X6")

  • a possible empty array of applied CM Synergy patches

ccm_exe

Returns the absolute pathname of the ccm executable.

trace

  $client->trace($trace_level);
  $client->trace($trace_level, $trace_filename);

This method enables trace information to be written.

Trace levels $trace_level are as follows:

0

trace disabled

1

trace session start/stop; show arguments, exit code and elapsed time for all invocations of CMSynergy CLI

5

trace method autoloading; show query shortcut processing

8

show complete output for all invocations of CMSynergy CLI

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 if 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 undef, 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

  $client->trace_msg($message_text);
  $client->trace_msg($message_text, $min_level);

Writes $message_text to the trace file if trace is enabled. 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.

set_error

  $ccm->set_error($error);
  $ccm->set_error($error, $method);
  $ccm->set_error($error, $method, $rv, @rv);

Set the "error" value for the session to $error. This will trigger the normal DBI error handling mechanisms, such as "RaiseError" and "HandleError", if they are enabled. This method is typically only used internally.

The $method parameter provides an alternate method name for the "RaiseError"/"PrintError" error string. Normally the method name is deduced from caller(1).

The "set_error" method normally returns undef. The $rvand @rv parameters provides an alternate return value if "set_error" was called in scalar or in list context, resp.

run

  $client->run(\@cmd, $in, $out, $err);

Runs run3 from IPC::Run3 with the given arguments in an environment ($ENV{CCM_HOME}, $ENV{PATH etc) set up for $client. Returns the exit status (i.e. $?) from executing @cmd.

databases

  @databases = $client->databases;
  @databases = $client->databases($servername);

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

Note: This method does not work on Windows.

hostname

  $hostname = $client->hostname.

The hostname as returned by ccm_hostname (which might be different from what "uname" in POSIX returns).

SEE ALSO

VCS::CMSynergy, VCS::CMSynergy::Object

AUTHORS

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

COPYRIGHT AND LICENSE

The VCS::CMSynergy::Client module is Copyright (c) 2001-2005 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.

3 POD Errors

The following errors were encountered while parsing the POD:

Around line 974:

Expected text after =item, not a number

Around line 979:

Expected text after =item, not a number

Around line 983:

Expected text after =item, not a number