/ 
VCS-CMSynergy-1.52
River stage zero No dependents
/ VCS::CMSynergy::Client

NAME

VCS::CMSynergy::Client - base class for 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;

@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 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 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 Synergy client.

If it fails (e.g. CCM_HOME doesn't seem to contain a valid 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 occurring 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 behavior 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 occurred in this client.

ccm_command

$last_cmsynergy_command = $client->ccm_command;

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

out

Returns the raw standard output of the last 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 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 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 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 Synergy installation. In a scalar context version returns the (short) Synergy version number, e.g. "6.2". In an array context the following information is returned:

  • the full 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 Synergy patches

ccm_exe

Returns the absolute pathname of the ccm executable.

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, $out, $err);

Runs run3 from IPC::Run3 with the given arguments in an environment ($ENV{CCM_HOME}, $ENV{PATH etc) set up for $client and STDIN redirected to /dev/null. 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 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>