te3270 0.6.0

data/lib/te3270/emulator_factory.rb

@@ -0,0 +1,23 @@
+require 'te3270/emulators/extra'
+require 'te3270/emulators/quick3270'
+require 'te3270/emulators/x3270'
+
+module TE3270
+  #
+  # Provides a mapping between a key used in the +emulator_for+ method
+  # and the class that implements the access to the emulator.
+  #
+  module EmulatorFactory
+
+    EMULATORS = {
+        extra: TE3270::Emulators::Extra,
+        quick3270: TE3270::Emulators::Quick3270,
+        x3270: TE3270::Emulators::X3270
+    }
+
+    def self.emulator_for(platform)
+      EMULATORS[platform]
+    end
+
+  end
+end

data/lib/te3270/emulators/extra.rb

@@ -0,0 +1,227 @@
+module TE3270
+  module Emulators
+    #
+    # This class has the code necessary to communicate with the terminal emulator called EXTRA! X-treme.
+    # You can use this emulator by providing the +:extra+ parameter to the constructor of your screen
+    # object or by passing the same value to the +emulator_for+ method on the +TE3270+ module.
+    #
+    class Extra
+
+      attr_writer :session_file, :visible, :window_state, :max_wait_time
+
+
+      def initialize
+        if jruby?
+          require 'jruby-win32ole'
+          require 'java'
+          include_class 'java.awt.Dimension'
+          include_class 'java.awt.Rectangle'
+          include_class 'java.awt.Robot'
+          include_class 'java.awt.Toolkit'
+          include_class 'java.awt.event.InputEvent'
+          include_class 'java.awt.image.BufferedImage'
+          include_class 'javax.imageio.ImageIO'
+        else
+          require 'win32ole'
+          require 'win32/screenshot'
+        end
+      end
+
+      #
+      # Creates a method to connect to Extra System. This method expects a block in which certain
+      # platform specific values can be set.  Extra can take the following parameters.
+      #
+      # * session_file - this value is required and should be the filename of the session.
+      # * visible - determines if the emulator is visible or not. If not set it will default to +true+.
+      # * window_state - determines the state of the session window.  Valid values are +:minimized+,
+      #   +:normal+, and +:maximized+.  If not set it will default to +:normal+.
+      #
+      # @example Example calling screen object constructor with a block
+      #   screen_object = MyScreenObject.new(:extra)
+      #   screen_object.connect do |emulator|
+      #     emulator.session_file = 'path_to_session_file'
+      #     emulator.visible = true
+      #     emulator.window_state = :maximized
+      #   end
+      #
+      def connect
+        start_extra_system
+
+        yield self if block_given?
+        raise 'The session file must be set in a block when calling connect with the Extra emulator.' if @session_file.nil?
+        open_session
+        @screen = session.Screen
+        @area = screen.SelectAll
+      end
+
+      #
+      # Disconnects the Extra System connection
+      #
+      def disconnect
+        session.Close
+      end
+
+      #
+      # Extracts text of specified length from a start point.
+      #
+      # @param [Fixnum] row the x coordinate of location on the screen.
+      # @param [Fixnum] column the y coordinate of location on the screen.
+      # @param [Fixnum] length the length of string to extract
+      # @return [String]
+      #
+      def get_string(row, column, length)
+        screen.GetString(row, column, length)
+      end
+
+      #
+      # Puts string at the coordinates specified.
+      #
+      # @param [String] str the string to set
+      # @param [Fixnum] row the x coordinate of the location on the screen.
+      # @param [Fixnum] column the y coordinate of the location on the screen.
+      #
+      def put_string(str, row, column)
+        screen.PutString(str, row, column)
+        quiet_period
+      end
+
+      #
+      # Sends keystrokes to the host, including function keys.
+      #
+      # @param [String] keys keystokes up to 255 in length
+      #
+      def send_keys(keys)
+        screen.SendKeys(keys)
+        quiet_period
+      end
+
+      #
+      # Wait for the string to appear at the specified location
+      #
+      # @param [String] str the string to wait for
+      # @param [Fixnum] row the x coordinate of location
+      # @param [Fixnum] column the y coordinate of location
+      #
+      def wait_for_string(str, row, column)
+        wait_for do
+          screen.WaitForString(str, row, column)
+        end
+      end
+
+      #
+      # Waits for the host to not send data for a specified number of seconds
+      #
+      # @param [Fixnum] seconds the maximum number of seconds to wait
+      #
+      def wait_for_host(seconds)
+        wait_for(seconds) do
+          screen.WaitHostQuiet
+        end
+      end
+
+      #
+      # Waits until the cursor is at the specified location.
+      #
+      # @param [Fixnum] row the x coordinate of the location
+      # @param [Fixnum] column the y coordinate of the location
+      #
+      def wait_until_cursor_at(row, column)
+        wait_for do
+          screen.WaitForCursor(row, column)
+        end
+      end
+
+      #
+      # Creates a method to take screenshot of the active screen.  If you have set the +:visible+
+      # property to false it will be made visible prior to taking the screenshot and then changed
+      # to invisible after.
+      #
+      # @param [String] filename the path and name of the screenshot file to be saved
+      #
+      def screenshot(filename)
+        File.delete(filename) if File.exists?(filename)
+        session.Visible = true unless visible
+
+        if jruby?
+          toolkit = Toolkit::getDefaultToolkit()
+          screen_size = toolkit.getScreenSize()
+          rect = Rectangle.new(screen_size)
+          robot = Robot.new
+          image = robot.createScreenCapture(rect)
+          f = java::io::File.new(filename)
+          ImageIO::write(image, "png", f)
+        else
+          hwnd = session.WindowHandle
+          Win32::Screenshot::Take.of(:window, hwnd: hwnd).write(filename)
+        end
+
+        session.Visible = false unless visible
+      end
+
+      #
+      # Returns the text of the active screen
+      #
+      # @return [String]
+      #
+      def text
+        area.Value
+      end
+
+      private
+
+      attr_reader :system, :sessions, :session, :screen, :area
+
+      WINDOW_STATES = {
+          minimized: 0,
+          normal: 1,
+          maximized: 2
+      }
+
+      def wait_for(seconds = system.TimeoutValue / 1000)
+        wait_collection = yield
+        wait_collection.Wait(seconds * 1000)
+      end
+
+      def quiet_period
+        wait_for_host(max_wait_time)
+      end
+
+      def max_wait_time
+        @max_wait_time ||= 1
+      end
+
+      def window_state
+        @window_state.nil? ? 1 : WINDOW_STATES[@window_state]
+      end
+
+      def visible
+        @visible.nil? ? true : @visible
+      end
+
+      def hide_splash_screen
+        version = system.Version
+        sessions.VisibleOnStartup = true if version.to_i >= 9
+      end
+
+      def open_session
+        @sessions = system.Sessions
+        hide_splash_screen
+        @session = sessions.Open @session_file
+        @session.WindowState = window_state
+        @session.Visible = visible
+      end
+
+      def start_extra_system
+        begin
+          @system = WIN32OLE.new('EXTRA.System')
+        rescue Exception => e
+          $stderr.puts e
+        end
+      end
+
+      def jruby?
+        RUBY_PLATFORM == 'java'
+      end
+    end
+  end
+end

data/lib/te3270/emulators/quick3270.rb

@@ -0,0 +1,180 @@
+if Gem.win_platform?
+  require 'win32ole'
+  require 'win32/screenshot'
+end
+
+module TE3270
+  module Emulators
+
+    #
+    # This class has the code necessary to communicate with the terminal emulator called Quick3270.
+    # You can use this emulator by providing the +:quick+ parameter to the constructor of your screen
+    # object or by passing the same value to the +emulator_for+ method on the +TE3270+ module.
+    #
+
+    class Quick3270
+
+      attr_writer :session_file, :visible, :max_wait_time
+
+      #
+      # Creates a method to connect to Quick System. This method expects a block in which certain
+      # platform specific values can be set.  Quick can take the following parameters.
+      #
+      # * session_file - this value is required and should be the filename of the session.
+      # * visible - determines if the emulator is visible or not. If not set it will default to +true+.
+      #
+      # @example Example calling screen object constructor with a block
+      #   screen_object = MyScreenObject.new(:quick3270)
+      #   screen_object.connect do |emulator|
+      #     emulator.session_file = 'path_to_session_file'
+      #     emulator.visible = true
+      #   end
+      #
+      def connect
+        start_quick_system
+        yield self if block_given?
+        raise "The session file must be set in a block when calling connect with the Quick3270 emulator." if @session_file.nil?
+        establish_session
+      end
+
+      #
+      # Disconnects the Quick System connection
+      #
+      def disconnect
+        session.Disconnect
+        system.Application.Quit
+      end
+
+      #
+      # Extracts text of specified length from a start point.
+      #
+      # @param [Fixnum] row the x coordinate of location on the screen.
+      # @param [Fixnum] column the y coordinate of location on the screen.
+      # @param [Fixnum] length the length of string to extract
+      # @return [String]
+      #
+      def get_string(row, column, length)
+        screen.GetString(row, column, length)
+      end
+
+      #
+      # Puts string at the coordinates specified.
+      #
+      # @param [String] str the string to set
+      # @param [Fixnum] row the x coordinate of the location on the screen.
+      # @param [Fixnum] column the y coordinate of the location on the screen.
+      #
+      def put_string(str, row, column)
+        screen.MoveTo(row, column)
+        screen.PutString(str)
+        quiet_period
+      end
+
+      #
+      # Sends keystrokes to the host, including function keys.
+      #
+      # @param [String] keys keystokes up to 255 in length
+      #
+      def send_keys(keys)
+        screen.SendKeys(keys)
+        quiet_period
+      end
+
+      #
+      # Wait for the string to appear at the specified location
+      #
+      # @param [String] str the string to wait for
+      # @param [Fixnum] row the x coordinate of location
+      # @param [Fixnum] column the y coordinate of location
+      #
+      def wait_for_string(str, row, column)
+        screen.WaitForString(str, row, column)
+      end
+
+      #
+      # Waits for the host to not send data for a specified number of seconds
+      #
+      # @param [Fixnum] seconds the maximum number of seconds to wait
+      #
+      def wait_for_host(seconds)
+        screen.WaitHostQuiet(seconds * 1000)
+      end
+
+      #
+      # Waits until the cursor is at the specified location.
+      #
+      # @param [Fixnum] row the x coordinate of the location
+      # @param [Fixnum] column the y coordinate of the location
+      #
+      def wait_until_cursor_at(row, column)
+        screen.WaitForCursor(row, column)
+      end
+
+      #
+      # Creates a method to take screenshot of the active screen.  If you have set the +:visible+
+      # property to false it will be made visible prior to taking the screenshot and then changed
+      # to invisible after.
+      #
+      # @param [String] filename the path and name of the screenshot file to be saved
+      #
+      def screenshot(filename)
+        File.delete(filename) if File.exists?(filename)
+        system.Visible = true unless visible
+        title = system.WindowTitle
+        Win32::Screenshot::Take.of(:window, title: title).write(filename)
+        system.Visible = false unless visible
+      end
+
+      #
+      # Returns the text of the active screen
+      #
+      # @return [String]
+      #
+      def text
+        rows = screen.Rows
+        columns = screen.Cols
+        result = ''
+        rows.times { |row| result += "#{screen.GetString(row+1, 1, columns)}\\n" }
+        result
+      end
+
+      private
+
+      attr_reader :system, :session, :screen
+
+      def quiet_period
+        screen.WaitHostQuiet(max_wait_time)
+      end
+
+      def max_wait_time
+        @max_wait_time ||= 3000
+      end
+
+      def visible
+        @visible.nil? ? true : @visible
+      end
+
+      def start_quick_system
+        begin
+          @system = WIN32OLE.new('Quick3270.Application')
+        rescue Exception => e
+          $stderr.puts e
+        end
+      end
+
+      def establish_session
+        system.Visible = visible
+        @session = system.ActiveSession
+        session.Open @session_file
+        @screen = session.Screen
+        session.Connect
+        connected = session.Connected
+        while not connected
+          screen.WaitHostQuiet(1000)
+          connected = session.Connected
+        end
+      end
+
+    end
+  end
+end

data/lib/te3270/emulators/x3270.rb

@@ -0,0 +1,185 @@
+require 'open3'
+
+module TE3270
+  module Emulators
+    #
+    # This class has the code necessary to communicate with the terminal emulator called EXTRA! X-treme.
+    # You can use this emulator by providing the +:extra+ parameter to the constructor of your screen
+    # object or by passing the same value to the +emulator_for+ method on the +TE3270+ module.
+    #
+    class X3270
+
+      attr_writer :executable_command, :host, :max_wait_time, :trace
+
+      #
+      # Creates a method to connect to x3270. This method expects a block in which certain
+      # platform specific values can be set.  Extra can take the following parameters.
+      #
+      # * executable_command - this value is required and should be the name of the ws3270 executable
+      # * host - this is required and is the (DNS) name of the host to connect to
+      # * max_wait_time - max time to wait in wait_for_string (defaults to 10 if not specified)
+      #
+      # @example Example x3270 object constructor with a block
+      #   screen_object = MyScreenObject.new(:x3270)
+      #   screen_object.connect do |emulator|
+      #     emulator.executable_command = 'path_to_executable'
+      #     emulator.host = 'host.example.com'
+      #     emulator.max_wait_time = 5
+      #   end
+      #
+      def connect
+        @max_wait_time = 10
+        @trace = false
+        yield self if block_given?
+        raise 'The executable command must be set in a block when calling connect with the X3270 emulator.' if @executable_command.nil?
+        raise 'The host must be set in a block when calling connect with the X3270 emulator.' if @host.nil?
+        start_x3270_system
+      end
+
+      #
+      # Disconnects the x3270 System connection
+      #
+      def disconnect
+          @x3270_input.close
+          @x3270_output.close
+      end
+
+      #
+      # Extracts text of specified length from a start point.
+      #
+      # @param [Fixnum] row the x coordinate of location on the screen.
+      # @param [Fixnum] column the y coordinate of location on the screen.
+      # @param [Fixnum] length the length of string to extract
+      # @return [String]
+      # 
+      def get_string row, column, length
+        x_send "ascii(#{row-1},#{column-1},#{length})"
+        result_string = ""
+        while line = x_read do
+          break if line == 'ok'
+          result_string = result_string + line[6..-1] if line[0..5] == 'data: '
+        end
+        result_string
+      end
+
+      #
+      # Puts string at the coordinates specified.
+      #
+      # @param [String] str the string to set
+      # @param [Fixnum] row the x coordinate of the location on the screen.
+      # @param [Fixnum] column the y coordinate of the location on the screen.
+      #
+      def put_string(str, row, column)
+        x_send_no_rsp "MoveCursor(#{row-1},#{column-1})"
+        x_send_no_rsp 'string "' + str.gsub('"', '\\"') + '"'
+      end
+
+      #
+      # Sends keystrokes to the host, including function keys.
+      #
+      # @param [String] keys keystokes up to 255 in length
+      #
+      def send_keys(keys)
+        key = keys[1..-2]
+        if m=/^(Pf|Pa)(\d+)$/.match(key)
+          key = "#{m[1]}(#{m[2]})"
+        end
+        x_send_no_rsp key
+        x_send_no_rsp "wait(output)"
+      end
+
+      #
+      # Wait for the string to appear at the specified location
+      #
+      # @param [String] str the string to wait for
+      # @param [Fixnum] row the x coordinate of location
+      # @param [Fixnum] column the y coordinate of location
+      #
+      def wait_for_string(str, row, column)
+        total_time = 0.0
+        sleep_time = 0.5
+        while get_string(row, column, str.length) != str do
+          sleep sleep_time
+          total_time = total_time + sleep_time
+          break if total_time >= @max_wait_time
+        end
+      end
+
+      #
+      # Waits for the host to not send data for a specified number of seconds
+      #
+      # @param [Fixnum] seconds the maximum number of seconds to wait
+      #
+      def wait_for_host(seconds)
+        x_send_no_rsp "Wait(#{seconds},Output)"
+      end
+
+      #
+      # Waits until the cursor is at the specified location.
+      #
+      # @param [Fixnum] row the x coordinate of the location
+      # @param [Fixnum] column the y coordinate of the location
+      #
+      def wait_until_cursor_at(row, column)
+        x_send_no_rsp "MoveCursor(#{row-1},#{column-1})"
+      end
+
+      #
+      # Creates a method to take screenshot of the active screen.  If you have set the +:visible+
+      # property to false it will be made visible prior to taking the screenshot and then changed
+      # to invisible after.
+      #
+      # @param [String] filename the path and name of the screenshot file to be saved
+      #
+      def screenshot(filename)
+        File.delete(filename) if File.exists?(filename)
+        x_send_no_rsp "printtext(file,#{filename})"
+      end
+
+      #
+      # Returns the text of the active screen
+      #
+      # @return [String]
+      #
+      def text
+        get_string(1,1,24*80)
+      end
+
+      private
+
+      attr_reader :x3270_input, :x3270_output
+
+      def x_read
+        line = @x3270_output.gets.chomp
+        puts "x_read: '#{line}'" if @trace
+        line
+      end
+
+      def x_send cmd
+        puts "x_send: #{cmd}" if @trace
+        @x3270_input.print "#{cmd}\n"
+        @x3270_input.flush
+      end
+
+      def x_send_no_rsp cmd
+        x_send cmd
+        while line = x_read do
+          break if line == 'ok'
+        end
+      end
+
+      def start_x3270_system
+        begin
+          args = [
+              "-model", "2",
+              ""
+          ]
+          cmd = "#{@executable_command} #{args.join " "} #{@host}"
+          @x3270_input, @x3270_output, @x3270_thr = Open3.popen2e(cmd)
+        rescue Exception => e
+          raise "Could not start x3270 '#{@executable_command}': #{e}"
+        end
+      end
+    end
+  end
+end