NAME

Win32::HostExplorer - Automate telnet using Hummingbird HostExplorer and interact with the presentation space.

VERSION

Version 0.01

SYNOPSIS

    use Win32::HostExplorer;

    # Create new instance of HostExplorer
    my $obj = Win32::HostExplorer->new( debug => 3, logfile => $log_file );

    # Print the first line, last line
    print $obj->title_row(),  "\n";
    print $obj->status_row(), "\n";

    # Retrieve lines 2 and 7 through 12
    my @array = $obj->show_lines( 2, 7..12 );

    # Search lines 7 through 9 for the pattern
    $obj->match_pattern( '.*money\s+(\S+)', 7..9 );

    # Position cursor on row 7, column 11
    my ( $row, $col ) = $obj->cursor_pos( 7, 11 );

    # Send text to row/column 7,1
    $obj->field_input( 7, 1, 'Thelonius Monk' );

    # Execute function key 'F1' within terminal
    $obj->f1();

DESCRIPTION

The Win32::HostExplorer module provides an object-oriented interface and methods to interact with the HostExplorer presentation space.

METHODS

CONSTRUCTION AND METHODS

• Win32::HostExplorer->new();

  The constructor returning the object for a new HostExplorer instance using Win32::OLE. Two options are supported with this method in hash format. All are optional.

  debug

  Setting the debug level to 1 will cause each to method to announce itself and its caller. Setting debug to 2 will add the arguments passed to the method. Setting debug to 3 will add the return value of the method.

  logfile

  This designates a log file to be used in conjunction with the write_log() method.

• show_lines( 3, 8..14 )

  Reads lines from the presentation space using line numbers as arguments. They are returned in list or scalar context. The default action, with no arguments, returns lines 1-24. Ranges are expressed as (start)..(end).

• title_row()

  Reads the first row of the presentation space, which can often contain the page title.

• status_row()

  Reads the last row of the presentation space, which can often contain the results of a command sequence.

• cursor_pos( 7, 11 )

  With row/col arguments, positions the cursor in the presentation space, else returns the cursor position only.

  Row and column indexes begin with 1;

• field_input( 7, 1, 'bang a gong' )

  Combines three methods to position the cursor on a given row/column, clear the field, and insert keys.

• match_pattern( '.*free money\s+(\S+)', 7..9 )

  Applies a regex pattern against the specified lines in the presentation space.

  This returns, either the entire pattern matched or the parenthesized group. Only one group is allowed.

GENERIC METHODS

System Commands

• activate()

  Brings the window to the foreground.

• close()

  This will close the session immediately.

• connect()

  Connect the client to a host system.

• connect_status()

  Tests the connection to your host. 0 = not connected, 1 = connected

• clear()

  Clears all data from the terminal.

• disconnect()

  Disconnects the client from a host system.

• hide() show()

  Hide or display the screen whether it is minimized, normal, or maximized. A hidden screen no longer shows in the taskbar.

• maximize() minimize() restore()

  Methods to size the window.

• hide_toolbar() show_toolbar()

  Use these methods to hide or show the session toolbar.

• start_capture() stop_capture()

  Starts/stops capture mode.

• set_font()

  A method to change the font.

  $obj->set_font( 'Courier New', 0, 12 ); # ( $fontname, $width, $height )

• font_larger() font_smaller()

  Resize the font.

• print_screen()

  Print the current host session to the Windows printer specified in the profile for the session

• save_screen()

  Save the current screen to a file.

  $obj->save_screen( 'C:\saved.txt' );

• search()

  Search the presentation space for a string. Returns (row,col) — found or 0 — not found. Parameters - 'string', case( def. 0 = no case or 1 = case sensitive ), start_row( def. 1 ), start_col( def. 1 ).

  $obj->search( "elvis", 0 ,1 ,1 );

• set_font()

  Set the session font.

  $obj->set_font( 'Courier New',$w, $h );

• text()

  Use to retrieve the entire screen as a string.

  my $text = $obj->text();

• text_rc()

  Used to retrieve part of the screen as a string. Values for length include: 0 = Copy to EOF, -1 = Copy to EOL, -2 = Copy to EOW, -3 = Copy to EOScr, >0 = Exact length.

  my $text = $obj->text_rc($row,$column,$length);

• update() This method forces a repaint of the session window.

  $obj->update();

Action Keys

• enter()

  Sends the 'enter' key sequence.

• f1() .. f12() pa1() .. pa3()

  Function keys within the session.

Editing

• back_space()

  Sends the 'backspace' key.

• send_keys( 'Thelonius Monk' )

  Used to insert a key sequence into the presentation space at the current cursor position.

• erase_eof()

  Clears text from the cursor position to the end of the field.

• erase_eol()

  Clears text from the cursor position to the end of the line.

• erase_input()

  Clears all editable text from the presentation space.

• selectall() copy() selectall_copy() paste() paste_wordwrap()

  Copy/paste commands.

• set_insert() unset_insert()

  These toggle the insert mode and return the state of the mode. 0 = reset, 1 = set

• newline()

  Sends the 'newline' key sequence moving the cursor to the first editable position on the next line.

• tab() back_tab()

  These methods are used to send the 'tab' or 'back-tab' key sequences, moving the cursor tab-wise through the input fields.

• left() right() up() down() home() end()

  Cursor movement.

• put_text()

  Like the send_keys() method but it allows you to specify the location to write the text. $obj->put_text( "Donna Lee", 2, 10 )

AUTHOR

George Kevin Hathorn, <gekeha at gmail dot com>

BUGS

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

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Win32::HostExplorer

You can also look for information at:

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/Win32-HostExplorer

• CPAN Ratings

  http://cpanratings.perl.org/d/Win32-HostExplorer

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=Win32-HostExplorer

• Search CPAN

  http://search.cpan.org/dist/Win32-HostExplorer

COPYRIGHT & LICENSE

Copyright 2007 George Kevin Hathorn, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Win32::HostExplorer

perl -MCPAN -e shell
install Win32::HostExplorer