Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

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

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


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 the VCS::CMSynergy manpage. 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 the VCS::CMSynergy manpage 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 the Data::Dumper manpage:


  $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 the Data::Dumper manpage:


  $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:

  1. trace disabled

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

  3. trace method autoloading; show query shortcut processing

  4. 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 the IPC::Run3 manpage 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 POSIX/uname returns).


SEE ALSO

the VCS::CMSynergy manpage, the VCS::CMSynergy::Object manpage


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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy