butler-mainframe 0.0.6 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c4002cfeff0a68711d48ded02dabdcfb246dfd8f
-  data.tar.gz: d48bb6bd6986aa9b12cb2fe1695de8a73639ccbc
+  metadata.gz: 2be056e6d5c2cd0b24cdd1ba7c27a92f2e11d295
+  data.tar.gz: 0265a490b0c3891b40e0c336c05e4d73563d9150
 SHA512:
-  metadata.gz: efbafb8fc1ae9f9416294f4f2b8dfd9e863d49f2651d6b16771ed9bf593466a4688f673d888a679c298f4b3c0e62b8e28ab520be9d99f54b28a8f0db44cf3d0d
-  data.tar.gz: 5e4043550886c4bfc8540c8044da940f326e98fe3c3f7160f415d180bdca608c0fb80e12146f584f5f27cadd7e380b6598af7ea723ef9eb5cc43ccd98aa83ce3
+  metadata.gz: 71d70a1deaf10b776b6e4b49a5eb57d608c5931b245f72010876f32d9946e05ac9aa1cee342c87df895719a63b79dd6ae2ebac3ab6b715269f173b454f6185f7
+  data.tar.gz: 721c158317b5282ca9e51df2988e1b081992420427176092a0a3001581ca2930792ae7392003ec6284a51a62f0e6b6247c07f97cdd872aa745a7d54092b5ee77

data/CHANGELOG.md

@@ -1,8 +1,18 @@
+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
+* Many documentation improvements with technical details and examples
+* Little improvements in host base to manage ready? sub methods, a new check as well as created?
+* Two new config parameters: timeout and session_tag to connect to the right session
+* Write text now have an option parameter :check_protect which raise an error when on protect area
+* Improved passport driver class: now it use a session screen @variable to optimize memory use
+* Change include module methods to monkey patch to add ruby 1.8.7 support
+
 0.0.6 [☰](https://github.com/marcomd/butler-mainframe/compare/v0.0.5...v0.0.6) October 12th, 2015
 ------------------------------
 * Added a simple rake test
 * Improved documentation
-* Several little improvements
+* Some little improvements
 
 0.0.5 October 7th, 2015
 ------------------------------

data/README.md

@@ -20,17 +20,67 @@ Instal the gem from rubygems
 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)
+
+
+
+
+## Configuration
+
+In the config folder there are two files:
+
+   * config.rb
+   * settings.yml
+
+### Emulator configuration
+
+config.rb can be used for the configuration of the gem and the emulator
+
+```ruby
+# Example to configura Personal communication
+
+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.timeout        = 3000
+end
+```
+
+```ruby
+# Example to configura Passport web to host
+
+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.timeout        = 3000
+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.
+
+    foo: add every variable you need and use it with => ButlerMainframe::Settings.foo
+        bar: sub variable are accessible with hash => ButlerMainframe::Settings.foo[:bar]
+
+
 ## How to use
 
 In irb:
 
     C:\Ruby>irb
     irb(main):001:0> require 'butler-mainframe'
-
-    Use ButlerMainframe::Host.new
-    Please read the documentation on github for more information
     => true
-    irb(main):002:0>
 
 You can start the emulator 3270 manually, the butler will lean on that and will let it open at the end.
 In this example, I dont start the session and immediately create a new instance:
@@ -113,9 +163,9 @@ then
 
     bundle install
 
-run generator to copy configuration files
+run generator to copy configuration files suitable for the emulator you need
 
-    rails g butler:install
+    rails g butler:install --emulator=passport
 
 ```ruby
 Class Invoice
@@ -163,6 +213,124 @@ For more informations:
     bundle exec rake -T
 
 
+## More informations about supported emulators
+
+I hope this can help to support my work or yours if you need something different
+
+### Passport web to host
+
+Documentation can be found [here](http://www.zephyrcorp.com/legacy-integration/Documentation/passport_host_integration_objects.htm) Rocket use old Zephyr documentation, unfortunately it's obsolete :disappointed:
+
+```ruby
+require 'win32ole'
+passport = WIN32OLE.new("PASSPORT.System")
+```
+
+passport.ole_methods:
+
+    # QueryInterface      # AddRef          # Release         # GetTypeInfoCount
+    # GetTypeInfo         # GetIDsOfNames   # Invoke          # ActiveSession
+    # Application         # DefaultFilePath # DefaultFilePath # FullName
+    # Name                # Parent          # Path            # Sessions
+    # TimeoutValue        # Version         # Quit            # ViewStatus
+    # GetTypeInfoCount    # GetTypeInfo     # GetIDsOfNames   # Invoke
+    # TimeoutValue
+
+passport.Sessions(1).ole_methods
+
+    # QueryInterface      # AddRef              # Release             # GetTypeInfoCount    # Toolbars
+    # GetTypeInfo         # GetIDsOfNames       # Invoke              # Application         # Visible
+    # ColorScheme         # ColorScheme         # Connected           # Connected           # Activate
+    # EditScheme          # EditScheme          # FileTransferHostOS  # FileTransferHostOS  # SaveAs
+    # FileTransferScheme  # FileTransferScheme  # FullName            # Height
+    # Height              # HotSpotScheme       # HotSpotScheme       # KeyboardLocked
+    # KeyboardLocked      # KeyMap              # KeyMap              # Left
+    # Name                # PageRecognitionTime # PageRecognitionTime # Parent
+    # Path                # QuickPads           # Saved               # Screen
+    # Top                 # Top                 # Type                # Visible
+    # Width               # Width               # WindowState         # WindowState
+    # Close               # NavigateTo          # ReceiveFile         # Save
+    # SendFile            # FileTransferOptions # GetTypeInfoCount    # GetTypeInfo
+    # GetIDsOfNames       # Invoke
+
+passport.Sessions(1).Screen.ole_methods:
+
+    # QueryInterface     # AddRef           # Release          # GetTypeInfoCount # GetTypeInfo
+    # GetIDsOfNames      # Invoke           # Application      # Col              # Col
+    # Cols               # Name             # OIA              # Parent           # Row
+    # Row                # Rows             # Selection        # Updated          # Area
+    # Copy               # Cut              # Delete           # GetString        # MoveRelative
+    # MoveTo             # Paste            # PutString        # Search           # Select
+    # SelectAll          # SendInput        # SendKeys         # WaitForCursor    # WaitForCursorMove
+    # WaitForKeys        # WaitForStream    # WaitForString    # WaitHostQuiet    # CheckTimeInterval
+    # CheckTimeInterval  # WaitAfterAIDKey  # WaitAfterAIDKey  # GetTypeInfoCount # GetTypeInfo
+    # GetIDsOfNames      # Invoke
+
+### Personal communication
+
+Documentation can be found [here](http://www-01.ibm.com/support/knowledgecenter/SSEQ5Y_6.0.0/com.ibm.pcomm.doc/books/html/host_access08.htm) Ibm did a good work!
+
+```ruby
+require 'win32ole'
+session  = WIN32OLE.new("PComm.autECLSession")
+session.SetConnectionByName 'A'
+space   = session.autECLPS
+screen  = session.autECLOIA
+```
+
+session.ole_methods:
+
+    # QueryInterface        # AddRef                  # Release
+    # GetTypeInfoCount      # GetTypeInfo             # autECLWinMetrics
+    # GetIDsOfNames         # Invoke                  # Handle
+    # autECLXfer            # autECLPS                # Started
+    # autECLOIA             # Name                    # Ready
+    # ConnType              # CodePage
+    # CommStarted           # APIEnabled
+    # StartCommunication    # StopCommunication
+    # SetConnectionByName   # SetConnectionByHandle
+    # RegisterSessionEvent  # UnregisterSessionEvent
+    # RegisterCommEvent     # UnregisterCommEvent
+    # autECLPageSettings    # autECLPrinterSettings
+    # GetTypeInfoCount      # GetTypeInfo
+    # GetIDsOfNames         # Invoke
+
+session.autECLPS.ole_methods (presentation space):
+
+    # QueryInterface      # AddRef                # Release             # GetTypeInfoCount 
+    # GetTypeInfo         # GetIDsOfNames         # Invoke              # autECLFieldList 
+    # NumRows             # NumCols               # CursorPosRow        # CursorPosCol 
+    # SetConnectionByName # SetConnectionByHandle # SetCursorPos        # GetTextRect 
+    # SendKeys            # SearchText            # GetText             # WaitWhileCursor 
+    # SetText             # Wait                  # StartMacro          # WaitWhileStringInRect
+    # WaitForCursor       # WaitWhileString       # WaitForString       # WaitForScreen  
+    # WaitForStringInRect # WaitWhileAttrib       # WaitForAttrib       # UnregisterPSEvent 
+    # WaitWhileScreen     # CancelWaits           # RegisterPSEvent     # Handle 
+    # RegisterKeyEvent    # UnregisterKeyEvent    # RegisterCommEvent   # CommStarted 
+    # UnregisterCommEvent # SetTextRect           # Name                # StopCommunication
+    # ConnType            # CodePage              # Started             # Invoke
+    # APIEnabled          # Ready                 # StartCommunication   
+    # GetTypeInfoCount    # GetTypeInfo           # GetIDsOfNames   
+
+session.autECLOIA.ole_methods (screen):
+
+    # QueryInterface       # AddRef                 # Release             # GetTypeInfoCount  # UpperShift 
+    # GetTypeInfo          # GetIDsOfNames          # Invoke              # Alphanumeric      # CommErrorReminder
+    # APL                  # Katakana               # Hiragana            # DBCS              # ConnType   
+    # NumLock              # Numeric                # CapsLock            # InsertMode        # Ready    
+    # MessageWaiting       # InputInhibited         # Name                # Handle            # Invoke  
+    # CodePage             # Started                # CommStarted         # APIEnabled          
+    # SetConnectionByName  # SetConnectionByHandle  # StartCommunication  # StopCommunication   
+    # WaitForInputReady    # WaitForSystemAvailable # WaitForAppAvailable # WaitForTransition 
+    # CancelWaits          # RegisterCommEvent      # UnregisterCommEvent # RegisterOIAEvent 
+    # UnregisterOIAEvent   # GetTypeInfoCount       # GetTypeInfo         # GetIDsOfNames 
+
+
+## ToDo
+
+* Improve unit test
+* Improve static navigation
+
 ## License
 
 The GNU Lesser General Public License, version 3.0 (LGPL-3.0)

data/lib/butler-mainframe.rb

@@ -30,26 +30,30 @@ require "mainframe/#{ButlerMainframe.configuration.host_gateway.to_s.downcase}"
 
 ButlerMainframe::Settings.load!(File.join(ButlerMainframe.root,'lib','config','settings.yml'), :env => env)
 
-if ButlerMainframe::Settings.modules_included[:activerecord]
-  require 'mainframe/customization/active_record'
-  # puts "Extending Host class with #{Host3270::ActiveRecord}" if debug
-  ButlerMainframe::Host.include Host3270::ActiveRecord
+require 'mainframe/customization/active_record'
+# puts "Extending Host class with #{Host3270::ActiveRecord}" if debug
+# Use monkey patch for 1.8 compatibility
+class ButlerMainframe::Host
+  include Host3270::ActiveRecord
 end
 
-if ButlerMainframe::Settings.modules_included[:generic_functions]
-  require 'mainframe/customization/generic_functions'
-  # puts "Extending Host class with #{Host3270::GenericFunctions}" if debug
-  ButlerMainframe::Host.include Host3270::GenericFunctions
+require 'mainframe/customization/generic_functions'
+# puts "Extending Host class with #{Host3270::GenericFunctions}" if debug
+class ButlerMainframe::Host
+  include Host3270::GenericFunctions
 end
 
-if ButlerMainframe::Settings.modules_included[:custom_functions] && defined?(Host3270::CustomFunctions)
+if defined?(Host3270::CustomFunctions)
   # puts "Extending Host class with #{Host3270::CustomFunctions}" if debug
-  ButlerMainframe::Host.include Host3270::CustomFunctions
+  class ButlerMainframe::Host
+    include Host3270::CustomFunctions
+  end
 end
 
 =begin
 # To test in irb
 require 'butler-mainframe'
-host=ButlerMainframe::Host.new
+host=ButlerMainframe::Host.new(debug: :full)
 host.scan_page
+host.navigate :next
 =end

data/lib/config/config.rb

@@ -1,7 +1,8 @@
 ButlerMainframe.configure do |config|
-  # config.language       = :it #NOT READY YET
   config.host_gateway   = 'passport'
   config.browser_path   = 'c:/Program Files (x86)/Internet Explorer/iexplore.exe'
-  config.session_path   = 'https://ergmilict10/zephyr/Ecomes.zwh?sessionprofile=3270dsp/Sessions/host3270'
+  config.session_url    = 'https://ergmilict10/zephyr/Ecomes.zwh?sessionprofile=3270dsp/Sessions/host3270'
+  config.session_tag    = 1
+  config.timeout        = 3000
 end
 

data/lib/config/config_EXAMPLE_passport.rb

@@ -0,0 +1,8 @@
+ButlerMainframe.configure do |config|
+  config.host_gateway   = :passport
+  config.browser_path   = 'c:/Program Files (x86)/Internet Explorer/iexplore.exe'
+  config.session_url    = 'https://localhost/zephyr/Ecomes.zwh?sessionprofile=3270dsp/Sessions/host3270'
+  config.session_tag    = 1
+  config.timeout        = 3000
+end
+

data/lib/config/config_EXAMPLE_pcomm.rb

@@ -0,0 +1,7 @@
+ButlerMainframe.configure do |config|
+  config.host_gateway   = :pcomm
+  config.session_path   = '"C:/Program Files (x86)/IBM/Personal Communications/pcsws.exe" "C:/Users/XXXXXXXXXX/AppData/Roaming/IBM/Personal Communications/host3270.ws"'
+  config.session_tag    = 'A'
+  config.timeout        = 6000
+end
+

data/lib/config/settings.yml

@@ -2,12 +2,9 @@ defaults: &defaults
   cics: 7
   user: "IBM0001"
   password: "password"
-  life_user: "LIFE1"
-  life_password: "password"
-  modules_included:
-    activerecord: yes
-    generic_functions: yes
-    custom_functions: yes
+ #foo: add every variable you need and use it with => ButlerMainframe::Settings.foo
+ #  bar: sub variable are accessible with hash => ButlerMainframe::Settings.foo[:bar]
+
 
 development:
   <<: *defaults

data/lib/config/settings_EXAMPLE.yml

@@ -0,0 +1,17 @@
+defaults: &defaults
+  cics: 7
+  user: "IBM0001"
+  password: "password"
+ #foo: add every variable you need and use it with => ButlerMainframe::Settings.foo
+ #  bar: sub variable are accessible with hash => ButlerMainframe::Settings.foo[:bar]
+
+
+development:
+  <<: *defaults
+
+test:
+  <<: *defaults
+
+production:
+  <<: *defaults
+  cics: 4

data/lib/core/configuration.rb

@@ -2,13 +2,16 @@ module ButlerMainframe
   class Configuration
     attr_writer :allow_sign_up
 
-    attr_accessor :language, :host_gateway, :browser_path, :session_path
+    attr_accessor :language, :host_gateway, :browser_path, :session_url, :session_path, :session_tag, :timeout
 
     def initialize
       @language       = :en
       @host_gateway   = nil
       @browser_path   = ""
+      @session_url    = ""
       @session_path   = ""
+      @session_tag    = nil
+      @timeout        = 1000
     end
 
   end

data/lib/generators/butler/install_generator.rb

@@ -1,16 +1,20 @@
 require 'rails/generators/base'
+require File.join(File.dirname(__FILE__), '../butler_mainframe')
 
 module Butler
   module Generators
     class InstallGenerator < Rails::Generators::Base
+      include ::ButlerMainframe::Base
+
       desc "Installs ButlerMainframe configuration files"
       source_root File.expand_path('../../', __FILE__)
+      class_option :emulator, :type => :string, :default => 'passport', :desc => "Choose your favorite emulator [passport]"
 
       def copy_to_local
         copy_file "butler/templates/custom_functions.rb", "config/initializers/butler_custom_functions.rb"
         copy_file "../config/settings.yml", "config/butler.yml"
         file = "config/initializers/butler.rb"
-        copy_file "../config/config.rb", file
+        copy_file "../config/config_EXAMPLE_#{options[:emulator]}.rb", file
         append_file file do
           <<-FILE.gsub(/^            /, '')
             ButlerMainframe::Settings.load!(File.join(Rails.root,'config','butler.yml'), :env => Rails.env)

data/lib/generators/butler/templates/custom_functions.rb

@@ -156,4 +156,6 @@ module Host3270
   end
 end
 
-ButlerMainframe::Host.include Host3270::CustomFunctions
+class ButlerMainframe::Host
+  include Host3270::CustomFunctions
+end

data/lib/mainframe/customization/generic_functions.rb

@@ -10,6 +10,8 @@ module Host3270
 
     def do_quit; exec_command "CLEAR" end
 
+    def do_erase; exec_command "ERASE EOF" end
+
     def destination_list
       [
       :company_menu,

data/lib/mainframe/host_base.rb

@@ -11,12 +11,14 @@ module ButlerMainframe
 
     def initialize options={}
       options = {
-          :session          => 1,
+          :session_tag      => ButlerMainframe.configuration.session_tag,
           :wait             => 0.01,  #wait screen in seconds
           :wait_debug       => 2,     #wait time for debug purpose
           :debug            => true,
           :browser_path     => ButlerMainframe.configuration.browser_path,
+          :session_url      => ButlerMainframe.configuration.session_url,
           :session_path     => ButlerMainframe.configuration.session_path,
+          :timeout          => ButlerMainframe.configuration.timeout,
           :close_session    => :evaluate
                               #:evaluate    if the session is found will not be closed
                               #:never       never close the session
@@ -26,8 +28,9 @@ module ButlerMainframe
       @debug            = options[:debug]
       @wait             = options[:wait]
       @wait_debug       = options[:wait_debug]
-      @session          = options[:session]
+      @session_tag      = options[:session_tag]
       @close_session    = options[:close_session]
+      @timeout          = options[:timeout]
       @pid = nil
 
       create_object options
@@ -59,7 +62,6 @@ module ButlerMainframe
 
     # Execute keyboard command like PF1 or PA2 or ENTER ...
     def exec_command cmd
-      cmd = "<#{cmd}>"
       puts "Command: #{cmd}" if @debug
       sub_exec_command cmd
       wait_session
@@ -96,17 +98,18 @@ module ButlerMainframe
           :clean_first_chars          => nil
       }.merge(options)
 
-      y=options[:y]
-      x=options[:x]
+      y           = options[:y]
+      x           = options[:x]
+      hooked_rows = 2
       raise "Missing coordinates! y(row)=#{y} x(column)=#{x} " unless x && y
       raise "Sorry, cannot write null values" unless text
 
       bol_written = nil
       if options[:hook]
-        (y-2..y+2).each do |y_riga|
-          if /#{options[:hook]}/ === scan_row(y_riga, 1, MAX_TERMINAL_COLUMNS)
-            puts "Change y from #{y} to #{y_riga} cause hook to:#{options[:hook]}" if y_riga != y && @debug
-            bol_written = write_clean_text_on_map text, y_riga, x, options
+        (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
             break
           end
         end
@@ -116,47 +119,76 @@ module ButlerMainframe
       bol_written
     end
 
-    # It returns the coordinates of the cursor
+    # Return the coordinates of the cursor
     def get_cursor_axes
       sub_get_cursor_axes
     end
 
+    # Move the cursor at given coordinates
+    def set_cursor_axes y, x, options={}
+      sub_set_cursor_axes y, x, options
+    end
+
     private
 
     # It creates the object calling subclass method
+    # It depends on the emulator chosen but typically the object is present after starting the terminal session
     # These are the options with default values:
     #     :session          => 1,
     #     :debug            => true,
     #     :browser_path     => ButlerMainframe::Settings.browser_path,
     #     :session_path     => ButlerMainframe::Settings.session_path,
     def create_object options={}
-      sub_create_object
+      connection_attempts       = 8
+      seconds_between_attempts  = 2
+
+      sub_create_object options
+
+      # if the terminal is not found then we start it
       unless sub_object_created?
-        puts "Session not found, starting new..." if @debug
+        puts "Session #{@session_tag} not found, starting new..." if @debug
+
+        executable, args =  if options[:browser_path] && !options[:browser_path].empty?
+                              [options[:browser_path], options[:session_url]]
+                            elsif options[:session_path] && !options[:session_path].empty?
+                              [options[:session_path], nil]
+                            else
+                              [nil, nil]
+                            end
+        raise "Specify an executable in the configuration file!" unless executable
 
         if /^1.8/ === RUBY_VERSION
-          Thread.new {system "#{options[:browser_path]} #{options[:session_path]}"}
+          Thread.new {system "#{executable} #{args}"}
           @pid = $?.pid if $?
         else
           #It works only on ruby 1.9+
-          @pid = Process.spawn "#{options[:browser_path]}", "#{options[:session_path]}"
+          @pid = Process.spawn *[executable, args].compact
         end
 
         puts "Starting session with process id #{@pid}, wait please..." if @debug
         sleep 2
-        5.times do
-          puts "Wait please..." if @debug
+        connection_attempts.times do
+          puts "Detecting session #{@session_tag}, wait please..." if @debug
           sub_create_object
-          sub_object_created? ? break : sleep(10)
+          sub_object_created? ? break : sleep(seconds_between_attempts)
         end
         @session_started_by_me = true
       end
 
-      if sub_object_created?
+      raise "Session #{@session_tag} not started. Check the session #{options[:browser_path]} #{options[:session_path]}" unless sub_object_created?
+
+      unless sub_object_ready?
+        connection_attempts.times do
+          puts "Waiting for the session to be ready..." if @debug
+          sub_object_ready? ? break : sleep(seconds_between_attempts)
+        end
+      end
+
+      if sub_object_ready?
         puts "** Connection established with #{sub_name} **"
         puts "Session full name: #{sub_fullname}" if @debug == :full
       else
-        raise "Connection refused. Check the session #{options[:session]} and it was on the initial screen."
+        raise "Connection refused. Check session #{@session_tag} with process id #{@pid}"
       end
 
     rescue
@@ -194,7 +226,7 @@ module ButlerMainframe
 
     # 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={})
+    def write_text_on_map text, y, x, options={}
       options = {
           :check                      => true,
           :raise_error_on_check       => true,
@@ -203,7 +235,7 @@ module ButlerMainframe
       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
-      sub_write_text text, y, x
+      sub_write_text text, y, x, :check_protect => options[:check]
       # It returns the function's result
       if options[:check]
         # It expects the string is present on the session at the specified coordinates

data/lib/mainframe/passport.rb

@@ -2,64 +2,98 @@ require 'win32ole'
 require 'mainframe/host_base'
 
 # This class use Rocket 3270 emulator API
-# http://www.rocketsoftware.com/products/rocket-passport-web-to-host
+# http://www.zephyrcorp.com/legacy-integration/Documentation/passport_host_integration_objects.htm
 module ButlerMainframe
   class Host < HostBase
 
     private
 
-    def sub_create_object
+    # Create objects from emulator library
+    def sub_create_object options={}
       str_obj = 'PASSPORT.System'
       puts "#{Time.now.strftime "%H:%M:%S"} Creating object #{str_obj}..." if @debug == :full
       @action = WIN32OLE.new(str_obj)
+      @screen = @action.Sessions(@session_tag).Screen if sub_object_created?
     end
 
+    # Check is session is started
     def sub_object_created?
-      puts "#{Time.now.strftime "%H:%M:%S"} Terminal successfully detected" if @debug == :full
-      @action.Sessions(@session)
+      res = @action && @action.Sessions(@session_tag)
+      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 = @action.Sessions(@session_tag).Connected == -1
+      puts "#{Time.now.strftime "%H:%M:%S"} Session ready" if @debug == :full && res
+      res
     end
 
     def sub_name
-      @action.Sessions(@session).Name
+      "#{@action.Name} #{@action.Sessions(@session_tag).Name}"
     end
 
     def sub_fullname
-      @action.Sessions(@session).FullName
+      "#{sub_name} #{@action.Sessions(@session_tag).FullName}"
     end
 
     #Ends the connection and closes the session
     def sub_close_session
-      @action.Sessions(@session).Close
+      @action.Sessions(@session_tag).Close
       @action.Quit
       @action = nil
     end
 
     #Execute keyboard command like PF1 or PA2 or ENTER ...
-    def sub_exec_command cmd
-      @action.Sessions(@session).Screen.SendKeys cmd
-      @action.Sessions(@session).Screen.WaitHostQuiet
+    def sub_exec_command cmd, options={}
+      # Cast cmd to_s cause it could be passed as label
+      @screen.SendKeys "<#{cmd}>"
+      @screen.WaitHostQuiet
     end
 
     #It reads one line part of the screen
     def sub_scan_row y, x, len
-      @action.Sessions(@session).Screen.GetString(y, x, len)
+      @screen.GetString(y, x, len)
     end
 
     #It reads a rectangle on the screen
     def sub_scan_area y1, x1, y2, x2
-      @action.Sessions(@session).Screen.Area(y1, x1, y2, x2).Value
+      @screen.Area(y1, x1, y2, x2).Value
     end
 
+    # Get cursor coordinates
     def sub_get_cursor_axes
-      [@action.Sessions(@session).Screen.Col, @action.Sessions(@session).Screen.Row]
+      [@screen.Col, @screen.Row]
+    end
+
+    # Move cursor to given coordinates
+    def sub_set_cursor_axes y, x, options={}
+      options = {
+          :wait                     => true
+      }.merge(options)
+      @screen.MoveTo y, x
+      @screen.WaitForCursor(y, x) if options[:wait]
     end
 
-    def sub_write_text text, y, x
-      @action.Sessions(@session).Screen.PutString(text, y, x)
+    # 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)
+      if options[:check_protect]
+        # This method is sensitive to protected areas
+        sub_set_cursor_axes y, x
+        @screen.SendKeys text
+      else
+        @screen.PutString(text, y, x)
+      end
     end
 
+    # Wait text at given coordinates and wait the session is available again
     def sub_wait_for_string text, y, x
-      @action.Sessions(@session).Screen.WaitForString(text, y, x).Value == -1
+      @screen.WaitForString(text, y, x).Value == -1
     end
 
   end

data/lib/mainframe/pcomm.rb

@@ -0,0 +1,105 @@
+require 'win32ole'
+require 'mainframe/host_base'
+
+# This class use IBM personal communication
+# http://www-01.ibm.com/support/knowledgecenter/SSEQ5Y_6.0.0/welcome.html
+# http://www-01.ibm.com/support/knowledgecenter/SSEQ5Y_6.0.0/com.ibm.pcomm.doc/books/html/host_access08.htm
+module ButlerMainframe
+  class Host < HostBase
+
+    private
+
+    # Create objects from emulator library
+    def sub_create_object options={}
+      str_obj = 'PComm.autECLSession'
+      puts "#{Time.now.strftime "%H:%M:%S"} Creating object #{str_obj}..." if @debug == :full
+      @action = WIN32OLE.new(str_obj)
+      @action.SetConnectionByName @session_tag
+      @space  = @action.autECLPS
+      @screen = @action.autECLOIA
+    end
+
+    # Check is session is started
+    def sub_object_created?
+      res = @action && @action.CommStarted
+      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 = @action.Ready
+      puts "#{Time.now.strftime "%H:%M:%S"} Session ready" if @debug == :full && res
+      res
+    end
+
+    def sub_name
+      "PComm #{@action.Name}"
+    end
+
+    def sub_fullname
+      "#{sub_name} #{@action.ConnType}"
+    end
+
+    #Ends the connection and closes the session
+    def sub_close_session
+      @action.StopCommunication
+      @action = nil
+      Process.kill 9, @pid if @pid
+    end
+
+    #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
+      @space.SendKeys "[#{cmd}]"
+      @screen.WaitForAppAvailable @timeout
+      @screen.WaitForInputReady @timeout
+    end
+
+    #It reads one line part of the screen
+    def sub_scan_row y, x, len
+      @space.GetText(y, x, len)
+    end
+
+    #It reads a rectangle on the screen
+    def sub_scan_area y1, x1, y2, x2
+      @space.GetTextRect(y1, x1, y2, x2)
+    end
+
+    # Get cursor coordinates
+    def sub_get_cursor_axes
+      [@space.CursorPosCol, @space.CursorPosRow]
+    end
+
+    # Move cursor to given coordinates
+    def sub_set_cursor_axes y, x, options={}
+      options = {
+          :wait                     => true
+      }.merge(options)
+      @space.SetCursorPos y, x
+      @space.WaitForCursor(y, x, @timeout) if options[:wait]
+    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)
+      if options[:check_protect]
+        # This method is sensitive to protected areas
+        @space.SendKeys(text, y, x)
+      else
+        @space.SetText(text, y, x)
+      end
+    end
+
+    # Wait text at given coordinates and wait the session is available again
+    def sub_wait_for_string text, y, x
+      @space.WaitForString text, y, x, @timeout
+      @screen.WaitForInputReady @timeout
+    end
+
+  end
+end
+

data/rakefile

@@ -0,0 +1,4 @@
+require "bundler/gem_tasks"
+require 'rake'
+
+Dir["#{File.dirname(__FILE__)}/test/*.rake"].sort.each { |ext| load ext }

data/test/test.rake

@@ -0,0 +1,26 @@
+require 'fileutils'
+
+namespace :butler do
+  namespace :mainframe do
+
+    desc "Test butler mainframe gem"
+    task(:test) do  |task_name, args|
+
+      begin
+        require 'butler-mainframe'
+        host = ButlerMainframe::Host.new
+        str_screen1 = host.scan_page
+        raise 'host.scan_page' if str_screen1.empty?
+        host.navigate :next
+        str_screen2 = host.scan_page
+        raise 'host.navigate :next' if str_screen1 == str_screen2
+        host.close_session
+
+      rescue
+        puts $!.message
+        exit(9)
+      end
+    end
+
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: butler-mainframe
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.1.0
 platform: ruby
 authors:
 - Marco Mastrodonato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-12 00:00:00.000000000 Z
+date: 2015-10-14 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)
@@ -25,7 +25,10 @@ files:
 - README.md
 - lib/butler-mainframe.rb
 - lib/config/config.rb
+- lib/config/config_EXAMPLE_passport.rb
+- lib/config/config_EXAMPLE_pcomm.rb
 - lib/config/settings.yml
+- lib/config/settings_EXAMPLE.yml
 - lib/core/configuration.rb
 - lib/core/configuration_dynamic.rb
 - lib/generators/butler/USAGE
@@ -36,7 +39,10 @@ files:
 - lib/mainframe/customization/generic_functions.rb
 - lib/mainframe/host_base.rb
 - lib/mainframe/passport.rb
+- lib/mainframe/pcomm.rb
 - lib/vendor/deep_symbolize.rb
+- rakefile
+- test/test.rake
 homepage: https://github.com/marcomd/butler-mainframe
 licenses:
 - LGPL-3.0
@@ -56,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements:
-- So many patience
+- Be awake and rested
 rubyforge_project: 
 rubygems_version: 2.2.5
 signing_key: