/ 
Pick-TCL-0.06
River stage zero No dependents
/ Pick::TCL

NAME

Pick::TCL - class to run commands in a Pick TCL shell

VERSION

Version 0.06

SYNOPSIS

use Pick::TCL;

# Establish connection
my $ap = Pick::TCL->new(%options);

# Execute commands
my $output = $ap->exec('TCL.COMMAND PARAMS (OPTIONS)');
my $unsanitised = $ap->execraw('TCL.COMMAND PARAMS (OPTIONS)');

# Spawn, check & retrieve output of long-running commands
$ap->spawn('TCL.COMMAND PARAMS (OPTIONS)')} = 1;
# ...
do_something_with($ap->output) if $ap->is_ready;

# Clean up
$ap->logout();

DESCRIPTION

Pick::TCL provides a class to run arbitrary TCL (that's Terminal Control Language, not the "other" TCL) commands in a local or remote Pick or Pick-like environment, either synchronously (blocking until execution has completed) or asynchronously.

Local connections

require either IPC::Run or Net::OpenSSH to be installed and usable.

Remote connections

require Net::OpenSSH to be installed and usable.

Note that Pick::TCL will croak() if used when neither IPC::Run nor Net::OpenSSH are usable.

CLASS METHODS

new(%options)

Returns a new Pick::TCL object on success (or undef on failure). %options is optional and if present may contain any combination of the following keys:

HOST

The hostname of the Pick host. If specified, all calls to Pick will be made via a Net::OpenSSH link to the host of the supplied name; if not specified, Pick is presumed to be running on the local host and Net::OpenSSH is not used (unless IPC::Run is missing and HOST is not specified, in which case HOST will be set implicitly to localhost).

PORT

Only valid if HOST is also set. Specifies the TCP port on which to connect to sshd(8) on HOST. Defaults to 22.

SSHUSER

Only valid if HOST is also given. Specifies the Unix username to supply to the remote sshd(8) on HOST. Defaults to the current local username.

SSHPASS

Only valid if HOST is also given. Specifies that password authentication should be used, with the given Unix password. If HOST is given but SSHPASS is not, public key authentication is used instead of password authentication.

SSHCMD

Only valid if HOST is also given. Specifies the full path to the ssh(1) binary (in case Net::OpenSSH cannot find it). If not specified, only /usr/local/bin/ssh, /usr/bin/ssh and /bin/ssh (in that order) are tried.

TIMEOUT

Only valid if HOST is also given. Specifies the maximum number of seconds for which to wait for a response from a remote Pick system.

VM

The name of the Pick virtual machine to which to connect. Defaults to pick0.

USER

The user name with which to log on to VM. Defaults to the value of SSHUSER (or to the current Unix username if HOST is not given).

PASS

The password with which to log on to VM, if required.

MD

The Pick master dictionary to log onto, if required.

MDPASS

Only valid if MD is also given. The password for MD, if required.

PICKBIN

The full path to the Pick binary on HOST. Defaults to /usr/bin/ap.

OPTVM

The switch to pass to PICKBIN indicating that the next parameter is a VM / config-file name. Defaults to -n.

OPTSILENT

The switch to pass to PICKBIN in order to suppress logon and logoff messages. Defaults to -s.

OPTDATA

The switch to pass to PICKBIN indicating that the next parameter contains "stacked" data for input to the Pick session. Defaults to -d.

All keys are optional, with the caveats that if PORT, SSHUSER, SSHPASS and/or TIMEOUT are specified, for those options to take effect HOST must also be specified; and likewise MDPASS has no effect without MD.

Note:

new() does not actually try to log on to VM -- where Pick is local, the %options are merely stored in the Pick::TCL object for later use; on the other hand if HOST is set (i.e. Pick is remote), new() will establish a Net::OpenSSH link to HOST or croak() trying.

INSTANCE METHODS

$ap->exec($tclcmd, @input)

Executes the Pick TCL command $tclcmd on the Pick VM associated with the Pick::TCL object $ap synchronously and returns the output.

In order to cope with the wide variety of terminal settings found on different Pick systems in the wild (or in some cases, even on different ports of the same VM, allocated dynamically...), line endings in the returned output are sanitised: any sequence of one or more control characters (other than tabs) is treated as a single line ending. As a consequence, any consecutive line endings are collapsed.

In list context, returns a list of output lines; in scalar context, returns all output lines joined with line feeds.

The second parameter, @input, is optional. If specified, its elements, joined with carriage returns, are supplied as input to the TCL session.

On caller or Pick error (including if Pick or ssh emit anything on stderr), returns false, sets $! and emits a suitable message. Likewise on ssh error, except that exit codes 11 and 255 are ignored, in order to support ancient versions of sshd(8)).

croak()s if the call to a local VM fails outright.

$ap->execraw($tclcmd, @input)

Does the same thing as the exec() method but without any output sanitisation.

This is useful when dealing with binary output, or when consecutive line breaks in output are significant. However, in those circumstances the caller will need to know in advance the pertinent terminal settings of the port to which it is connecting on the target Pick system and do its own filtering of extraneous nulls, form feeds, etc. to suit.

$ap->spawn($tclcmd, @input)

Spawns $tclcmd for asynchronous execution on the Pick VM associated with $ap.

On success, returns true. On failure, returns undef and sets $!.

Output can be retrieved later with the output() method (see below).

$ap->is_ready

Returns true if a previously spawned job has completed. Returns false but defined if the job is still running. Returns undef if the job has aborted or if no job was spawned in the first place.

$ap->output

$ap->outputraw

Returns the (raw or cooked) output of a previously spawned job if it has completed.

Sets $! and returns undef (or, for the cooked form, the empty list if called in list context) if no job has been spawned.

$ap->partialoutput

$ap->partialoutputraw

Returns the (raw or cooked) output of a previously spawned job that may not yet have completed.

Returns undef (or, for the cooked form, the empty list if called in list context) if a previously spawned job does not have any output yet or no job has been spawned.

$ap->logout

Destroys the connection. Not required to be called explicitly before exit; does nothing when Pick is local.

CAVEATS

Escaping metacharacters

The commands sent to exec() and execraw() are always interpreted by the Pick TCL interpreter -- so be sure to escape anything that needs escaping in TCL before feeding it to exec() or execraw() (no different from running native).

If HOST is set, there's also the remote login shell to consider. Pick::TCL uses Net::OpenSSH (which does auto-escaping of most metacharacters) for the remote link, so this should not cause problems either, so long as the remote user's login shell is set to the Bourne shell, or at least something that's sufficiently compatible with it.

Note especially that when HOST is set, parentheses around options to TCL commands must be balanced (even though the Pick TCL interpreter does not normally require that), as unbalanced parentheses will likely confuse the remote shell.

Parallel asynchronous commands

Each Pick::TCL object can only spawn() or exec() one TCL command at a time. If the caller needs to spawn() multiple TCL commands in parallel (or exec() a TCL command while waiting for an asynchronous one to complete), it should instantiate a separate Pick::TCL object for each TCL command.

Pick flavours

Pick::TCL has only been tested with D3/Linux as the target Pick platform (setting PICKBIN to /usr/bin/d3). It should also work unmodified with targets running D3/AIX, D3/SCO or legacy Advanced Pick systems (on any host OS on which an sshd can be found or built).

No attempt has been made thus far to cater specifically to other / licensee / "Pick-like" target platforms, although the configurability provided through %OPTIONS may be sufficient to work with some.

AUTHOR

Jack Burton, <jack@saosce.com.au>

BUGS

Please report any bugs or feature requests to bug-pick-tcl at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Pick-TCL. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

Thanks to Jemalong Wool who provided funding for initial development.

LICENSE AND COPYRIGHT

Copyright 2013, 2014 Jack Burton.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.