butler-mainframe 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2be056e6d5c2cd0b24cdd1ba7c27a92f2e11d295
-  data.tar.gz: 0265a490b0c3891b40e0c336c05e4d73563d9150
+  metadata.gz: 622cd36fbabc8ca579e69b36ef0d3ce535995854
+  data.tar.gz: bb98f4819d07e639c8cb88e092cc3a3a443fa648
 SHA512:
-  metadata.gz: 71d70a1deaf10b776b6e4b49a5eb57d608c5931b245f72010876f32d9946e05ac9aa1cee342c87df895719a63b79dd6ae2ebac3ab6b715269f173b454f6185f7
-  data.tar.gz: 721c158317b5282ca9e51df2988e1b081992420427176092a0a3001581ca2930792ae7392003ec6284a51a62f0e6b6247c07f97cdd872aa745a7d54092b5ee77
+  metadata.gz: 98f255d73ae417b65735be57cea9571d8d9f181ff794e4459a07e494ee8d1866af234d681a1f3af8301233d2b66ca166985677bbd94c14f23f33ae7c5a6565b7
+  data.tar.gz: 0f7ae6b50f6f8d5bdd0f0ede9fae786f3927f88ef707531f4c8fa871a8f3ddd0885331d98176b9a1fcdb6d4a82c9eeb0a30ac3ecfe6719b394505b6124e6c391

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+0.2.0 [☰](https://github.com/marcomd/butler-mainframe/compare/v0.1.0...v0.2.0) October 20th, 2015
+------------------------------
+* Added support for the free and open source x3270 terminal emulator, use :x3270 as host gateway in butler configuration
+* Added x3270 sections to documentation
+* Passport sub class now remove spaces from command input
+* Added :erase_field_first param to write method in the host base class in addition to :clean_first_chars to clear a given number of chars
+
 0.1.0 [☰](https://github.com/marcomd/butler-mainframe/compare/v0.0.6...v0.1.0) October 14th, 2015
 ------------------------------
 * Added IBM personal communication support (tested on 6.0.16), use :pcomm as host gateway in butler configuration

data/README.md

@@ -18,17 +18,15 @@ Instal the gem from rubygems
     gem install butler-mainframe
 
 Then you have to install your favorite emulator.
-At the moment is supported only [Passport web to host by rocket software](http://www.rocketsoftware.com/products/rocket-passport-web-to-host)
 
-## Emulator
-
-At the moment are managed two emulators both are commercial which must be purchased and installed on the machine.
-Both have x days free trial.
 
-    * [Passport web to host by Rocket Software](http://www.rocketsoftware.com/resource/rocket-passport-web-host-overview)
-    * [Personal communication by IBM](http://www-03.ibm.com/software/products/en/pcomm)
+## Emulator
 
+At the moment are managed the below emulators. First two are commercial which must be purchased and installed on the machine (both have x days free trial). The last is free and open source.
 
+* [Passport web to host by Rocket Software](http://www.rocketsoftware.com/resource/rocket-passport-web-host-overview)
+* [Personal communication by IBM](http://www-03.ibm.com/software/products/en/pcomm)
+* [x3270 maintained by Paul Mates](http://x3270.bgp.nu/)
 
 
 ## Configuration
@@ -43,29 +41,37 @@ In the config folder there are two files:
 config.rb can be used for the configuration of the gem and the emulator
 
 ```ruby
-# Example to configura Personal communication
+# Example to configure Passport web to host
 
 ButlerMainframe.configure do |config|
-  config.host_gateway   = :pcomm
-  config.browser_path   = "'C:/Program Files (x86)/IBM/Personal Communications/pcsws.exe'"
-  config.session_path   = "'C:/Users/Marco/AppData/Roaming/IBM/Personal Communications/host3270.ws'"
-  config.session_tag    = 'A'
+  config.host_gateway   = :passport
+  config.browser_path   = 'c:/Program Files (x86)/Internet Explorer/iexplore.exe'
+  config.session_path   = 'https://localhost/zephyr/Ecomes.zwh?sessionprofile=3270dsp/Sessions/host3270'
+  config.session_tag    = 1
   config.timeout        = 3000
 end
 ```
 
 ```ruby
-# Example to configura Passport web to host
+# Example to configure Personal communication
 
 ButlerMainframe.configure do |config|
-  config.host_gateway   = :passport
-  config.browser_path   = 'c:/Program Files (x86)/Internet Explorer/iexplore.exe'
-  config.session_path   = 'https://localhost/zephyr/Ecomes.zwh?sessionprofile=3270dsp/Sessions/host3270'
-  config.session_tag    = 1
+  config.host_gateway   = :pcomm
+  config.session_path   = '"C:/Program Files (x86)/IBM/Personal Communications/pcsws.exe" "C:/Users/Marco/AppData/Roaming/IBM/Personal Communications/host3270.ws"'
+  config.session_tag    = 'A'
   config.timeout        = 3000
 end
 ```
 
+```ruby
+# Example to configure X3270
+ButlerMainframe.configure do |config|
+  config.host_gateway   = :x3270
+  config.session_path   = '"C:/Program Files (x86)/wc3270/ws3270.exe" 127.0.0.1 -model 2 --'
+  config.timeout        = 5 # In seconds
+end
+```
+
 ### Use configuration
 
 settings.yml for the variables necessary to use the emulator like user, password, cics selection and everything else. It has one section for every environment in rails style.
@@ -89,7 +95,7 @@ In this example, I dont start the session and immediately create a new instance:
     Session not found, starting new...
     Starting session with process id 8560, wait please...
     ** Connection established with host3270 **
-    => #<ButlerMainframe::Host:0x29f3358 @debug=true, @wait=0.01, @wait_debug=2, @session=1, @close_session=:evaluate, @pid=8560, @action=#<WIN32OLE:0x29ebe10>, @session_started_by_me=true>
+    => #<ButlerMainframe::Host:0x29f3358 @debug=true, @wait=0.01, @wait_debug=2, @session=1, @close_session=:evaluate, @pid=8560, @action=#<WIN32OLE:0x29ebe10>>
 
 now session is ready to use:
 
@@ -128,8 +134,7 @@ host.write 'ruby on rails', :y => 6, :x => 15, hook: 'SYSTEM='
 
 The aim is to speed up browsing through static screens.
 The butler detects the current screen and It moves towards the target.
-For example, if the current screen is the login_session and you want to go to the next, to do that Butler log in
-In this case it identifies the first map the session login to the mainframe and it does the login to go to the next screen.
+For example, if the current screen is the login_session and you want to go to the next, Butler log in for you.
 
 ```ruby
 # Go to the login session screen
@@ -153,7 +158,6 @@ My advice is to use navigate method for generic navigation and use a specific mo
 
 ## With Rails
 
-__In development...__
 This module can be use on rails project.
 Add in your gemfile
 
@@ -195,10 +199,14 @@ end
 ```
 
 Create a polimorphic model:
-rails generate screen hook_id:integer 'hook_type:string{30}' 'screen_type:integer{1}' video:text 'message:string{160}' 'cursor_x:integer{1}' 'cursor_y:integer{1}'
+
+    rails generate screen hook_id:integer 'hook_type:string{30}' 'screen_type:integer{1}' video:text 'message:string{160}' 'cursor_x:integer{1}' 'cursor_y:integer{1}'
 
 In the model to be related to screen we insert:
+
+```ruby
 has_many :screens, :as => :hook, :dependent => :destroy
+```
 
 
 ## Test with rake
@@ -325,11 +333,24 @@ session.autECLOIA.ole_methods (screen):
     # CancelWaits          # RegisterCommEvent      # UnregisterCommEvent # RegisterOIAEvent 
     # UnregisterOIAEvent   # GetTypeInfoCount       # GetTypeInfo         # GetIDsOfNames 
 
+### x3270
+
+Documentation can be found [here](http://x3270.bgp.nu/documentation-manpages.html)
+__At the moment it doesn't support check on protect area__
+__x3270 module works only on ruby 1.9+__
+
+```ruby
+require 'open3'
+stdin, stdout, thread = Open3.popen2e('"C:/Program Files (x86)/wc3270/ws3270.exe" YOUR_HOST_IP -model 2 --')
+```
+
+Read the methods list documentation: [windows](http://x3270.bgp.nu/Windows/wc3270-script.html) or [unix](http://x3270.bgp.nu/Unix/x3270-script.html)
 
 ## ToDo
 
 * Improve unit test
 * Improve static navigation
+* Add meta class to choose your host method name and multi language support as well
 
 ## License
 

data/lib/butler-mainframe.rb

@@ -25,7 +25,9 @@ env = Rails.env if defined?(Rails)
 env ||= $ARGV[0] if $ARGV
 env ||= "development"
 debug = env == "development" ? true : false
-require "mainframe/#{ButlerMainframe.configuration.host_gateway.to_s.downcase}"
+
+# require the emulator sub class specified in the config.rb
+require "mainframe/emulators/#{ButlerMainframe.configuration.host_gateway.to_s.downcase}"
 
 
 ButlerMainframe::Settings.load!(File.join(ButlerMainframe.root,'lib','config','settings.yml'), :env => env)

data/lib/config/config.rb

@@ -1,8 +1,6 @@
 ButlerMainframe.configure do |config|
-  config.host_gateway   = 'passport'
-  config.browser_path   = 'c:/Program Files (x86)/Internet Explorer/iexplore.exe'
-  config.session_url    = 'https://ergmilict10/zephyr/Ecomes.zwh?sessionprofile=3270dsp/Sessions/host3270'
-  config.session_tag    = 1
-  config.timeout        = 3000
+  config.host_gateway   = :x3270
+  config.session_path   = '"C:/Program Files (x86)/wc3270/ws3270.exe" YOUR_HOST_IP -model 2 --'
+  config.timeout        = 5 # In seconds
 end
 

data/lib/config/config_EXAMPLE_x3270.rb

@@ -0,0 +1,6 @@
+ButlerMainframe.configure do |config|
+  config.host_gateway   = :x3270
+  config.session_path   = '"C:/Program Files (x86)/wc3270/ws3270.exe" YOUR_HOST_IP -model 2 --'
+  config.timeout        = 5 # In seconds
+end
+

data/lib/mainframe/{passport.rb → emulators/passport.rb}

@@ -48,7 +48,7 @@ module ButlerMainframe
     #Execute keyboard command like PF1 or PA2 or ENTER ...
     def sub_exec_command cmd, options={}
       # Cast cmd to_s cause it could be passed as label
-      @screen.SendKeys "<#{cmd}>"
+      @screen.SendKeys "<#{cmd.gsub /\s/, ''}>"
       @screen.WaitHostQuiet
     end
 

data/lib/mainframe/emulators/x3270.rb

@@ -0,0 +1,135 @@
+require 'open3'
+require 'mainframe/host_base'
+
+# This class use X3270, an interesting project open source
+# http://x3270.bgp.nu/Windows/wc3270-script.html
+# http://x3270.bgp.nu/Windows/ws3270-man.html
+module ButlerMainframe
+  class Host < HostBase
+
+    private
+
+    def sub_create_object options={}
+      str_obj = "#{options[:session_path]}"
+      puts "#{Time.now.strftime "%H:%M:%S"} Creating object #{str_obj}..." if @debug == :full
+      @action = {}
+      @action[:in], @action[:out], @action[:thr] = Open3.popen2e(str_obj)
+      @pid    = @action[:thr].pid
+    end
+
+    # Check is session is started
+    def sub_object_created?
+      res = @action[:in] && @action[:out] && @action[:thr]
+      puts "#{Time.now.strftime "%H:%M:%S"} Terminal successfully detected" if @debug == :full && res
+      res
+    end
+
+    # Check is session is operative
+    def sub_object_ready?
+      res = !x_cmd("Query(ConnectionState)").strip.empty?
+      puts "#{Time.now.strftime "%H:%M:%S"} Session ready" if @debug == :full && res
+      res
+    end
+
+    def sub_name
+      "X3270 #{x_cmd "Query(Host)"}".strip
+    end
+
+    def sub_fullname
+      "#{sub_name} #{x_cmd "Query(LuName)"}".strip
+    end
+
+    #Ends the connection and closes the session
+    def sub_close_session
+      @action[:in].close
+      @action[:out].close
+    end
+
+    #Execute keyboard command like PF1 or PA2 or ENTER ...
+    def sub_exec_command cmd, options={}
+      cmd = cmd.split.map(&:capitalize).join
+      if m=/^(Pf|Pa)(\d+)$/.match(cmd)
+        cmd = "#{m[1]}(#{m[2]})"
+      end
+      x_cmd cmd
+
+      command_skip_wait = %w(^erase ^delete)
+      x_cmd "Wait(#{@timeout}, Output)" unless /(#{command_skip_wait.join('|')})/i === cmd
+    end
+
+    #It reads one line part of the screen
+    def sub_scan_row y, x, len
+      x_cmd "Ascii(#{y-1},#{x-1},#{len})"
+    end
+
+    #It reads a rectangle on the screen
+    def sub_scan_area y1, x1, y2, x2
+      x_cmd "Ascii(#{y1-1},#{x1-1},#{y2-y1+1},#{x2-x1+1})"
+    end
+
+    # Get cursor coordinates
+    def sub_get_cursor_axes
+      res = x_cmd "Query(Cursor)"
+      res.split.map{|c| c.to_i + 1}
+    end
+
+    # Move cursor to given coordinates
+    def sub_set_cursor_axes y, x, options={}
+      options = {
+          :wait                     => true
+      }.merge(options)
+      x_cmd "MoveCursor(#{y-1},#{x-1})"
+      if options[:wait]
+        x_cmd "Wait(#{@timeout},InputField)"
+        raise "Positioning the cursor at the coordinates (#{y}, #{x}) failed!" unless sub_get_cursor_axes == [y, x]
+      end
+    end
+
+    # Write text on the screen at given coordinates
+    # :check_protect => true add sensitivity to protected areas
+    def sub_write_text text, y, x, options={}
+      options = {
+          :check_protect              => true
+      }.merge(options)
+      sub_set_cursor_axes y, x
+      x_cmd "String(#{text})"
+      # TODO
+      # if options[:check_protect]
+      # end
+    end
+
+    # Wait text at given coordinates and wait the session is available again
+    def sub_wait_for_string text, y, x
+      x_cmd "Wait(#{@timeout},InputField)"
+      total_time = 0.0
+      sleep_time = 0.5
+      while sub_scan_row(y, x, text.size) != text do
+        sleep sleep_time
+        total_time = total_time + sleep_time
+        # @timeout should be in milliseconds but everything is possible
+        break if total_time >= @timeout
+      end
+      raise "sub_wait_for_string: string #{text} not found at (#{y}, #{x})" unless sub_scan_row(y, x, text.size) == text
+      true
+    end
+
+    def x_cmd cmd
+      puts "x_cmd in: #{cmd}" if @debug
+      @action[:in].print "#{cmd}\n"
+      @action[:in].flush
+
+      str_res_ok = 'ok'
+      ar_res = [str_res_ok, 'error']
+
+      line, str_out = '', ''
+      while line = @action[:out].gets.chomp do
+        puts "x_cmd out: '#{line}'" if @debug
+        break if ar_res.include? line
+        str_out << "#{line[6..-1]}" if /^data:\s/ === line
+      end
+      line == str_res_ok ? str_out : raise(str_out)
+    end
+
+  end
+end
+

data/lib/mainframe/host_base.rb

@@ -31,7 +31,7 @@ module ButlerMainframe
       @session_tag      = options[:session_tag]
       @close_session    = options[:close_session]
       @timeout          = options[:timeout]
-      @pid = nil
+      @pid              = nil
 
       create_object options
     end
@@ -45,9 +45,9 @@ module ButlerMainframe
           puts "Session closed" if @debug
           wait_session 0.1
         when :evaluate
-          if @session_started_by_me
+          if @pid
             sub_close_session
-            puts "Session closed cause started by this process" if @debug
+            puts "Session closed because started by this process with id #{@pid}" if @debug
             wait_session 0.1
           else
             puts "Session not closed because it was already existing" if @debug
@@ -95,7 +95,7 @@ module ButlerMainframe
           :check                      => true,
           :raise_error_on_check       => true,
           :sensible_data              => nil,
-          :clean_first_chars          => nil
+          :clean_first_chars          => nil # clean x chars before writing a value
       }.merge(options)
 
       y           = options[:y]
@@ -104,18 +104,19 @@ module ButlerMainframe
       raise "Missing coordinates! y(row)=#{y} x(column)=#{x} " unless x && y
       raise "Sorry, cannot write null values" unless text
 
-      bol_written = nil
+      bol_written = false
       if options[:hook]
         (y-hooked_rows..y+hooked_rows).each do |row_number|
           if /#{options[:hook]}/ === scan_row(row_number, 1, MAX_TERMINAL_COLUMNS)
             puts "Change y from #{y} to #{row_number} cause hook to:#{options[:hook]}" if row_number != y && @debug
-            bol_written = write_clean_text_on_map text, row_number, x, options
+            bol_written = write_text_on_map text, row_number, x, options
             break
           end
         end
+      else
+        #If no control is required or was not found the label reference
+        bol_written = write_text_on_map(text, y, x, options) unless bol_written
       end
-      #If no control is required or was not found the label reference
-      bol_written = write_clean_text_on_map(text, y, x, options) unless bol_written
       bol_written
     end
 
@@ -144,8 +145,10 @@ module ButlerMainframe
 
       sub_create_object options
 
-      # if the terminal is not found then we start it
-      unless sub_object_created?
+      if sub_object_created?
+        puts "Using the terminal with process id #{@pid}" if @pid && @debug
+      else
+        # if the terminal is not found then we start it
         puts "Session #{@session_tag} not found, starting new..." if @debug
 
         executable, args =  if options[:browser_path] && !options[:browser_path].empty?
@@ -172,7 +175,6 @@ module ButlerMainframe
           sub_create_object
           sub_object_created? ? break : sleep(seconds_between_attempts)
         end
-        @session_started_by_me = true
       end
 
       raise "Session #{@session_tag} not started. Check the session #{options[:browser_path]} #{options[:session_path]}" unless sub_object_created?
@@ -210,47 +212,49 @@ module ButlerMainframe
       str
     end
 
-    # It has an additional option to clean the line before writing a value
-    def write_clean_text_on_map text, y, x, options={}
-      if options[:clean_first_chars] && options[:clean_first_chars].to_i > 0
-        puts "Clean #{options[:clean_first_chars]} char#{options[:clean_first_chars] == 1 ? '' : 's'} y:#{y} x:#{x}" if @debug
-        bol_cleaned = write_text_on_map(" " * options[:clean_first_chars], y, x, options)
-        unless bol_cleaned
-          puts "EHI! Impossible to clean the area specified" if @debug
-          return false
-        end
-      end
-      puts "Clean: #{options[:sensible_data] ? ('*' * text.size) : text} y:#{y} x:#{x}" if @debug
-      write_text_on_map(text, y, x, options)
-    end
-
     # Write a text on the screen
     # It also contains the logic to control the successful writing
     def write_text_on_map text, y, x, options={}
       options = {
           :check                      => true,
           :raise_error_on_check       => true,
-          :sensible_data              => nil
+          :sensible_data              => nil,
+          :clean_first_chars          => nil,
+          :erase_field_first          => nil
       }.merge(options)
-      raise "Impossible to write beyond row #{MAX_TERMINAL_ROWS}" if y > MAX_TERMINAL_ROWS
+      raise "Impossible to write beyond row #{MAX_TERMINAL_ROWS}"       if y > MAX_TERMINAL_ROWS
       raise "Impossible to write beyond column #{MAX_TERMINAL_COLUMNS}" if x > MAX_TERMINAL_COLUMNS
-      raise "Impossible to write a null value" unless text
+      raise "Impossible to write a null value"                          unless text
+
+      if options[:clean_first_chars] && options[:clean_first_chars].to_i > 0
+        puts "write_text_on_map: Clean #{options[:clean_first_chars]} char#{options[:clean_first_chars] == 1 ? '' : 's'} y:#{y} x:#{x}" if @debug
+        bol_cleaned = write_text_on_map(" " * options[:clean_first_chars], y, x, options)
+        unless bol_cleaned
+          puts "write_text_on_map: EHI! Impossible to clean the area specified" if @debug
+          return false
+        end
+      end
+
+      if options[:erase_field_first]
+        set_cursor_axes y, x
+        do_erase
+      end
+
       sub_write_text text, y, x, :check_protect => options[:check]
-      # It returns the function's result
-      if options[:check]
+      res = true
+      # If check is required it verify text is on the screen at given coordinates
+      # Sensible data option disable the check because it could be on hidden fields
+      if options[:check] && !options[:sensible_data]
         # It expects the string is present on the session at the specified coordinates
-        if sub_wait_for_string text, y, x
-          return true
-        else
+        unless sub_wait_for_string text, y, x
           if options[:raise_error_on_check]
-            raise "Impossible to write #{options[:sensible_data] ? ('*' * text.size) : text} at row #{y} column #{x}"
+            raise "write_text_on_map: Impossible to write #{options[:sensible_data] ? ('*' * text.size) : text} at row #{y} column #{x}"
           else
-            return false
+            res = false
           end
         end
-      else
-        return true
       end
+      res
     end
 
     # If is called a not existing method there is the chance that an optional module may not have been added

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: butler-mainframe
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Marco Mastrodonato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-14 00:00:00.000000000 Z
+date: 2015-10-20 00:00:00.000000000 Z
 dependencies: []
 description: This gem provides a virtual butler which can perform your custom tasks
   on a 3270 emulator. You just have to choose your emulator (atm only one choice)
@@ -27,6 +27,7 @@ files:
 - lib/config/config.rb
 - lib/config/config_EXAMPLE_passport.rb
 - lib/config/config_EXAMPLE_pcomm.rb
+- lib/config/config_EXAMPLE_x3270.rb
 - lib/config/settings.yml
 - lib/config/settings_EXAMPLE.yml
 - lib/core/configuration.rb
@@ -37,9 +38,10 @@ files:
 - lib/generators/butler_mainframe.rb
 - lib/mainframe/customization/active_record.rb
 - lib/mainframe/customization/generic_functions.rb
+- lib/mainframe/emulators/passport.rb
+- lib/mainframe/emulators/pcomm.rb
+- lib/mainframe/emulators/x3270.rb
 - lib/mainframe/host_base.rb
-- lib/mainframe/passport.rb
-- lib/mainframe/pcomm.rb
 - lib/vendor/deep_symbolize.rb
 - rakefile
 - test/test.rake
@@ -62,7 +64,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements:
-- Be awake and rested
+- A bit of awesomeness
 rubyforge_project: 
 rubygems_version: 2.2.5
 signing_key: