butler-mainframe 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 622cd36fbabc8ca579e69b36ef0d3ce535995854
-  data.tar.gz: bb98f4819d07e639c8cb88e092cc3a3a443fa648
+  metadata.gz: 54a4d86d300e73b9a93e3877cb23884911c51bd3
+  data.tar.gz: 4eb90e449628bca9f88f45f7b06038296ea86ff0
 SHA512:
-  metadata.gz: 98f255d73ae417b65735be57cea9571d8d9f181ff794e4459a07e494ee8d1866af234d681a1f3af8301233d2b66ca166985677bbd94c14f23f33ae7c5a6565b7
-  data.tar.gz: 0f7ae6b50f6f8d5bdd0f0ede9fae786f3927f88ef707531f4c8fa871a8f3ddd0885331d98176b9a1fcdb6d4a82c9eeb0a30ac3ecfe6719b394505b6124e6c391
+  metadata.gz: da00ccbc5269ee7cf04bf3cf3cd396b919e31da9456d1bfd13103b2942cdd7bf50158a574e4880e217b8030df5f96e491de4d5389de23cb509290b7c1f139fa2
+  data.tar.gz: 8ab5b447a48c02abb919ea0d82294b44be93685845f51a967a95aaa7d18821feb93e10fff80ff7362a8a5d0e73d6eeb88cb6eae50d0dcfe72197c42dd529caf2

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+0.3.0 [☰](https://github.com/marcomd/butler-mainframe/compare/v0.2.0...v0.3.0) October 22th, 2015
+------------------------------
+* Improved the host base class code to make it simpler
+* Improved automated tests with a more complex sequence and three iterations with decreasing latencies
+* Pcomm sub class now use safer method to close session
+* x3270 sub class is now more stable, It now passes all the tests although not always, rarely this does not happen with short delay time. There is still something to fix.
+* Improved navigation and added new setting parameters
+* Improved documentation
+* Several little improvements
+
 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

data/README.md

@@ -26,7 +26,7 @@ At the moment are managed the below emulators. First two are commercial which mu
 
 * [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/)
+* [x3270 maintained by Paul Mates](http://x3270.bgp.nu/) (only on ruby 1.9+)
 
 
 ## Configuration
@@ -40,9 +40,9 @@ 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 configure Passport web to host
+Example to configure Passport web to host:
 
+```ruby
 ButlerMainframe.configure do |config|
   config.host_gateway   = :passport
   config.browser_path   = 'c:/Program Files (x86)/Internet Explorer/iexplore.exe'
@@ -52,9 +52,9 @@ ButlerMainframe.configure do |config|
 end
 ```
 
-```ruby
-# Example to configure Personal communication
+Example to configure Personal communication:
 
+```ruby
 ButlerMainframe.configure do |config|
   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"'
@@ -63,8 +63,9 @@ ButlerMainframe.configure do |config|
 end
 ```
 
+Example to configure X3270:
+
 ```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 --'
@@ -171,42 +172,58 @@ run generator to copy configuration files suitable for the emulator you need
 
     rails g butler:install --emulator=passport
 
+You should have a model for every function to perform.
+In this simple example i have to insert an invoice number on a cics map so i create the invoice model:
+
+    rails generate scaffold invoice number:integer
+
+You may create a polimorphic model to save mainframe screen:
+
+    rails generate migration CreateScreens hook_id:integer 'hook_type:string{30}' 'screen_type:integer{1}' video:text 'message:string{160}' 'cursor_x:integer{1}' 'cursor_y:integer{1}'
+
+Create something like this:
+
 ```ruby
 Class Invoice
-    # ... your code
+    has_many :screens, :as => :hook, :dependent => :destroy
+
+    # ... your rails code: validations, scopes etc.
 
+    # Your main function method that perform the action on the mainframe
     def host3270
         @host = ButlerMainframe::Host.new
+
+        # Move to your starting position
+        # They often are static screens so it's easier to use navigate method
         @host.navigate :my_starting_position
 
         # Always check whether we are positioned on the screen that we expect
-        raise 'Screen not expected' unless self.my_function_start_screen?
+        raise 'Screen not expected' unless @host.my_function_start_screen?
 
         # We develop the function.
-        # In this simple case we put a number in a map cics and press Enter
-        @host.write self.invoice_number
+        # In this simple case we put a number in a map CICS at row 10 and column 5
+        # as option we also choose to erase any previous value in the field
+        @host.write self.number, y: 10, x: 5, erase_field_first: true
+
+        # Press enter because the example mainframe program expects it as confirmation
         @host.do_enter
 
-        # to read the confirmation message
-        raise 'Message not expected' unless /SUCCESSFUL/ === self.catch_message
+        # Read the confirmation message otherwise raise an exception
+        raise 'Message not expected' unless /SUCCESSFUL/ === @host.catch_message
 
+        # At the end close the session
         @host.close_session
     rescue
-        host.screenshot :error
+        # Save the screen as error to show to your mainframe users
+        @host.screenshot :error
         # Manage the invoice status etc.
     end
 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}'
-
-In the model to be related to screen we insert:
-
-```ruby
-has_many :screens, :as => :hook, :dependent => :destroy
-```
+Massive uses or one shot depends on your needs.
+The uses are many and only limited by your imagination!
+Experiment and you'll find the solution right for you :rocket:
 
 
 ## Test with rake
@@ -220,6 +237,10 @@ For more informations:
 
     bundle exec rake -T
 
+These tests consist in iterations of a simple navigation sequence.
+Each iteration uses different latency times, we start from high and therefore simple for the emulator to the default very low.
+It is not so easy make more complex sequence to share because mainframe screens are strongly diversified but everyone can add their own and iterate as many times as deemed appropriate.
+
 
 ## More informations about supported emulators
 
@@ -336,7 +357,9 @@ session.autECLOIA.ole_methods (screen):
 ### 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
@@ -348,7 +371,7 @@ Read the methods list documentation: [windows](http://x3270.bgp.nu/Windows/wc327
 
 ## ToDo
 
-* Improve unit test
+* <s>Improve unit test</s> **Done** although it is still a simple rake
 * Improve static navigation
 * Add meta class to choose your host method name and multi language support as well
 

data/lib/config/config.rb

@@ -1,6 +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
+  config.timeout        = 6 # In seconds
 end
 

data/lib/config/config_EXAMPLE_passport.rb

@@ -3,6 +3,6 @@ ButlerMainframe.configure do |config|
   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
+  config.timeout        = 6000
 end
 

data/lib/config/config_EXAMPLE_pcomm.rb

@@ -1,6 +1,6 @@
 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_path   = '"C:/Program Files (x86)/IBM/Personal Communications/pcsws.exe" "C:/Users/XXXXXXXXXX/AppData/Roaming/IBM/Personal Communications/host3270.ws" /Q /H /S=A'
   config.session_tag    = 'A'
   config.timeout        = 6000
 end

data/lib/config/config_EXAMPLE_x3270.rb

@@ -1,6 +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
+  config.timeout        = 6 # In seconds
 end
 

data/lib/config/settings.yml

@@ -1,10 +1,19 @@
 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]
-
+  # The number of iteration through static screen
+  navigation_iterations: 10
+  cics: '7'
+  user: 'YOURUSER'
+  password: 'YOURPASSWORD'
+  #foo: add every variable you need and use it with => ButlerMainframe::Settings.foo
+  #  bar: sub variable are accessible with hash => ButlerMainframe::Settings.foo[:bar]
+  logoff_cics:        'cesf logoff'
+  session_login_tag:  'EMSP00' #use a regular expression
+  cics_selection_tag: 'EMSP01' #use a regular expression
+  company_menu_tag:   '\*\*       \*\*        \*\*        \*\*' #use a regular expression
+  # Starts these transactions from blank cics in order to move forward
+  transactions_cics:
+    company_menu:     'vita'
+    main_application: 'life'
 
 development:
   <<: *defaults

data/lib/config/settings_EXAMPLE.yml

@@ -1,10 +1,19 @@
 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]
-
+  # The number of iteration through static screen
+  navigation_iterations: 10
+  cics: '7'
+  user: 'YOURUSER'
+  password: 'YOURPASSWORD'
+  #foo: add every variable you need and use it with => ButlerMainframe::Settings.foo
+  #  bar: sub variable are accessible with hash => ButlerMainframe::Settings.foo[:bar]
+  logoff_cics:        'cesf logoff'
+  session_login_tag:  'EMSP00' #use a regular expression
+  cics_selection_tag: 'EMSP01' #use a regular expression
+  company_menu_tag:   '\*\*       \*\*        \*\*        \*\*' #use a regular expression
+  # Starts these transactions from blank cics in order to move forward
+  transactions_cics:
+    company_menu:     'vita'
+    main_application: 'life'
 
 development:
   <<: *defaults

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

@@ -12,6 +12,9 @@ module Host3270
     #
     # def do_quit; exec_command "CLEAR" end
     #
+    # def do_erase; exec_command "ERASE EOF" end
+    #
+    # # If you add your static screen you must add it in the navigation method to define how to manage it
     # def destination_list
     #   [
     #       :company_menu,
@@ -21,6 +24,12 @@ module Host3270
     #       :back]
     # end
     #
+    # # Use navigation method to move through the static screens
+    # # Options:
+    # # :cics             => ButlerMainframe::Settings.cics,
+    # # :user             => ButlerMainframe::Settings.user,
+    # # :password         => ButlerMainframe::Settings.password,
+    # # :raise_on_abend   => false raise an exception if an abend is occured
     # def navigate destination, options={}
     #   options = {
     #       :cics             => ButlerMainframe::Settings.cics,
@@ -28,32 +37,50 @@ module Host3270
     #       :password         => ButlerMainframe::Settings.password,
     #       :raise_on_abend   => false
     #   }.merge(options)
-    #   attempts_number         = 10
-    #   transactions_after_cics = ['tra1','tra2']
+    #   attempts_number       = ButlerMainframe::Settings.navigation_iterations
+    #   transactions_cics     = ButlerMainframe::Settings.transactions_cics
     #
     #   raise "Destination #{destination} not valid, please use: #{destination_list.join(', ')}" unless destination_list.include? destination
     #   bol_found = nil
     #   attempts_number.times do
     #     if abend?
     #       options[:raise_on_abend] ? raise(catch_abend) : do_quit
+    #     elsif company_menu?
+    #       case destination
+    #         when  :cics_selection,
+    #             :session_login      then
+    #           do_quit
+    #         when  :back               then
+    #           do_quit
+    #           bol_found = true; break
+    #         when :next                then
+    #           company_menu
+    #           bol_found = true; break
+    #         when :company_menu        then bol_found = true; break
+    #         else
+    #           # Every other destination is forward
+    #           company_menu
+    #       end
     #     elsif cics?
     #       case destination
     #         when :cics_selection,
     #             :session_login       then
-    #           write "cesf logoff", :y => 1, :x => 1
+    #           write ButlerMainframe::Settings.logoff_cics, :y => 1, :x => 1
     #           do_enter
     #         when :back                then
-    #           write "cesf logoff", :y => 1, :x => 1
+    #           write ButlerMainframe::Settings.logoff_cics, :y => 1, :x => 1
     #           do_enter
     #           bol_found = true; break
     #         when :next                then
-    #           write transactions_after_cics[0], :y => 1, :x => 1
+    #           write transactions_cics[:main_application], :y => 1, :x => 1
     #           do_enter
     #           bol_found = true; break
-    #         when :company_menu        then write transactions_after_cics[1], :y => 1, :x => 1
+    #         when :company_menu        then
+    #           write transactions_cics[:company_menu], :y => 1, :x => 1
+    #           do_enter
     #         else
-    #           #Se siamo nel cics avviamo direttamente il life
-    #           write transactions_after_cics[0], :y => 1, :x => 1
+    #           #If we are in CICS with blank screen start the first transaction
+    #           write transactions_cics[:main_application], :y => 1, :x => 1
     #           do_enter
     #       end
     #     elsif cics_selection?
@@ -82,15 +109,19 @@ module Host3270
     #     else
     #       # If we do not know where we are...
     #       case destination
-    #         when :back            then
-    #           # ...we can try to go back
+    #         when  :session_login    then
+    #           # ...to come back to the first screen we surely have to go back
+    #           go_back
+    #         when  :back               then
+    #           # ...we can try to go back (not all the screen may go back in the same way)
     #           go_back
     #           bol_found = true; break
     #         when :next              then
     #           # ...but we dont know how to move forward
+    #           raise "Define how to go forward in the navigation method on generic function module"
     #         else
     #           # We unlock the position with both commands to be sure that they are managed by all maps cics
-    #           go_back; do_quit
+    #           raise "Destination #{destination} not defined in the current screen"
     #       end
     #     end
     #     wait_session
@@ -99,15 +130,19 @@ module Host3270
     #   raise "It was waiting #{destination} map instead of: #{screen_title(:rows => 2).strip}" unless bol_found
     # end
     #
+    # # Check if we are the first blank cics screen
     # def cics?
     #   scan(:y1 => 1, :x1 => 1, :y2 => 22, :x2 => 80).strip.empty?
     # end
     #
-    # #Login to mainframe
+    # # Check if we are on the login mainframe screen
     # def session_login?
-    #   /EMSP00/i === screen_title
+    #   /#{ButlerMainframe::Settings.session_login_tag}/i === screen_title
     # end
     #
+    # # Login to mainframe
+    # # param1 user
+    # # param2 password [sensible data]
     # def session_login user, password
     #   puts "Starting session login..." if @debug
     #   wait_session
@@ -118,22 +153,41 @@ module Host3270
     #   do_enter
     # end
     #
-    # # We need a label to know when we are on the cics selection map, usually ibm use EMSP01
+    # # Check the label to know when we are on the cics selection map
     # def cics_selection?
-    #   /EMSP01/i === screen_title
+    #   /#{ButlerMainframe::Settings.cics_selection_tag}/i === screen_title
     # end
     #
     # # On this map, we have to select the cics environment
+    # # param1 cics usually is a number
     # def cics_selection cics
     #   puts "Starting selezione_cics..." if @debug
     #   wait_session
-    #   raise "It was waiting cics selezion map instead of: #{screen_title}, messaggio: #{catch_message}" unless cics_selection?
+    #   raise "It was waiting cics selezion map instead of: #{screen_title}, message: #{catch_message}" unless cics_selection?
     #   write cics, :y => 23, :x => 14
     #   do_enter
     #   wait_session 1
     # end
     #
+    # # Check the label to know when we are on the cics selection map
+    # def company_menu?
+    #   /#{ButlerMainframe::Settings.company_menu_tag}/i === screen_title
+    # end
     #
+    # # On this map, we have to select the cics environment
+    # # param1 cics usually is a number
+    # def company_menu
+    #   puts "Starting company menu..." if @debug
+    #   wait_session
+    #   raise "It was waiting company menu map instead of: #{screen_title}, message: #{catch_message}" unless company_menu?
+    #   write "01", :y => 24, :x => 43
+    #   do_enter
+    # end
+    #
+    # # Get the message line usually in the bottom of the screen
+    # # You can define which rows provide the message:
+    # #     :first_row                    => 22,
+    # #     :last_row                     => 23
     # def catch_message options={}
     #   options = {
     #       :first_row                    => 22,
@@ -141,12 +195,19 @@ module Host3270
     #   }.merge(options)
     #   scan(:y1 => options[:first_row], :x1 => 1, :y2 => options[:last_row], :x2 => 80).gsub(/\s+/, " ").strip
     # end
+    #
+    # # Get the abend message
     # def catch_abend
     #   scan(:y1 => 23, :x1 => 1, :y2 => 23, :x2 => 80)
     # end
+    #
+    # # Check if there was a malfunction on the mainframe
     # def abend?
     #   /DFHA/i === catch_abend
     # end
+    #
+    # # Get the title usually the first row
+    # # You can change default option :rows to get more lines starting from the first
     # def screen_title options={}
     #   options = {
     #       :rows                      => 1

data/lib/mainframe/customization/generic_functions.rb

@@ -12,6 +12,7 @@ module Host3270
 
     def do_erase; exec_command "ERASE EOF" end
 
+    # If you add your static screen you must add it in the navigation method to define how to manage it
     def destination_list
       [
       :company_menu,
@@ -21,6 +22,12 @@ module Host3270
       :back]
     end
 
+    # Use navigation method to move through the static screens
+    # Options:
+    # :cics             => ButlerMainframe::Settings.cics,
+    # :user             => ButlerMainframe::Settings.user,
+    # :password         => ButlerMainframe::Settings.password,
+    # :raise_on_abend   => false raise an exception if an abend is occured
     def navigate destination, options={}
       options = {
           :cics             => ButlerMainframe::Settings.cics,
@@ -28,35 +35,54 @@ module Host3270
           :password         => ButlerMainframe::Settings.password,
           :raise_on_abend   => false
       }.merge(options)
-      attempts_number         = 10
-      transactions_after_cics = ['tra1','tra2']
+      attempts_number       = ButlerMainframe::Settings.navigation_iterations
+      transactions_cics     = ButlerMainframe::Settings.transactions_cics
 
       raise "Destination #{destination} not valid, please use: #{destination_list.join(', ')}" unless destination_list.include? destination
+
+      puts "Navigating to #{destination}" if @debug
       bol_found = nil
       attempts_number.times do
         if abend?
+          puts "Navigate: abend" if @debug
           options[:raise_on_abend] ? raise(catch_abend) : do_quit
+        elsif company_menu?
+          puts "Navigating to #{destination} from company menu" if @debug
+          case destination
+            when  :cics_selection,
+                  :session_login      then
+              do_quit
+            when  :back               then
+              do_quit
+              bol_found = true; break
+            when :next                then
+              company_menu
+              bol_found = true; break
+            when :company_menu        then bol_found = true; break
+            else
+              # Every other destination is forward
+              company_menu
+          end
         elsif cics?
+          puts "Navigating to #{destination} from cics" if @debug
           case destination
             when :cics_selection,
                  :session_login       then
-              write "cesf logoff", :y => 1, :x => 1
-              do_enter
+              execute_cics ButlerMainframe::Settings.logoff_cics
             when :back                then
-              write "cesf logoff", :y => 1, :x => 1
-              do_enter
+              execute_cics ButlerMainframe::Settings.logoff_cics
               bol_found = true; break
             when :next                then
-              write transactions_after_cics[0], :y => 1, :x => 1
-              do_enter
+              execute_cics transactions_cics[:main_application]
               bol_found = true; break
-            when :company_menu        then write transactions_after_cics[1], :y => 1, :x => 1
+            when :company_menu        then
+              execute_cics transactions_cics[:company_menu]
             else
-              #Se siamo nel cics avviamo direttamente il life
-              write transactions_after_cics[0], :y => 1, :x => 1
-              do_enter
+              #If we are in CICS with blank screen start the first transaction
+              execute_cics transactions_cics[:main_application]
           end
         elsif cics_selection?
+          puts "Navigating to #{destination} from cics selection" if @debug
           case destination
             when :cics_selection      then bol_found = true; break
             when :session_login       then exec_command("PF3")
@@ -70,6 +96,7 @@ module Host3270
               cics_selection options[:cics] if options[:cics]
           end
         elsif session_login?
+          puts "Navigating to #{destination} from session login" if @debug
           case destination
             when :session_login,
                  :back                then bol_found = true; break
@@ -80,17 +107,22 @@ module Host3270
               session_login options[:user], options[:password] if options[:user] && options[:password]
           end
         else
+          puts "Navigating to #{destination} from unknown screen" if @debug
           # If we do not know where we are...
           case destination
-            when :back            then
-              # ...we can try to go back
+            when  :session_login    then
+              # ...to come back to the first screen we surely have to go back
+              go_back
+            when  :back               then
+              # ...we can try to go back (not all the screen may go back in the same way)
               go_back
               bol_found = true; break
             when :next              then
               # ...but we dont know how to move forward
+              raise "Define how to go forward in the navigation method on generic function module"
             else
               # We unlock the position with both commands to be sure that they are managed by all maps cics
-              go_back; do_quit
+              raise "Destination #{destination} not defined in the current screen"
           end
         end
         wait_session
@@ -99,15 +131,19 @@ module Host3270
       raise "It was waiting #{destination} map instead of: #{screen_title(:rows => 2).strip}" unless bol_found
     end
 
+    # Check if we are the first blank cics screen
     def cics?
       scan(:y1 => 1, :x1 => 1, :y2 => 22, :x2 => 80).strip.empty?
     end
 
-    #Login to mainframe
+    # Check if we are on the login mainframe screen
     def session_login?
-      /EMSP00/i === screen_title
+      /#{ButlerMainframe::Settings.session_login_tag}/i === screen_title
     end
 
+    # Login to mainframe
+    # param1 user
+    # param2 password [sensible data]
     def session_login user, password
       puts "Starting session login..." if @debug
       wait_session
@@ -118,22 +154,41 @@ module Host3270
       do_enter
     end
 
-    # We need a label to know when we are on the cics selection map, usually ibm use EMSP01
+    # Check the label to know when we are on the cics selection map
     def cics_selection?
-      /EMSP01/i === screen_title
+      /#{ButlerMainframe::Settings.cics_selection_tag}/i === screen_title
     end
 
     # On this map, we have to select the cics environment
+    # param1 cics usually is a number
     def cics_selection cics
       puts "Starting selezione_cics..." if @debug
       wait_session
-      raise "It was waiting cics selezion map instead of: #{screen_title}, messaggio: #{catch_message}" unless cics_selection?
+      raise "It was waiting cics selezion map instead of: #{screen_title}, message: #{catch_message}" unless cics_selection?
       write cics, :y => 23, :x => 14
       do_enter
       wait_session 1
     end
 
+    # Check the label to know when we are on the cics selection map
+    def company_menu?
+      /#{ButlerMainframe::Settings.company_menu_tag}/i === screen_title
+    end
+
+    # On this map, we have to select the cics environment
+    # param1 cics usually is a number
+    def company_menu
+      puts "Starting company menu..." if @debug
+      wait_session
+      raise "It was waiting company menu map instead of: #{screen_title}, message: #{catch_message}" unless company_menu?
+      write "01", :y => 24, :x => 43
+      do_enter
+    end
 
+    # Get the message line usually in the bottom of the screen
+    # You can define which rows provide the message:
+    #     :first_row                    => 22,
+    #     :last_row                     => 23
     def catch_message options={}
       options = {
         :first_row                    => 22,
@@ -141,18 +196,30 @@ module Host3270
       }.merge(options)
       scan(:y1 => options[:first_row], :x1 => 1, :y2 => options[:last_row], :x2 => 80).gsub(/\s+/, " ").strip
     end
+
+    # Get the abend message
     def catch_abend
       scan(:y1 => 23, :x1 => 1, :y2 => 23, :x2 => 80)
     end
+
+    # Check if there was a malfunction on the mainframe
     def abend?
       /DFHA/i === catch_abend
     end
+
+    # Get the title usually the first row
+    # You can change default option :rows to get more lines starting from the first
     def screen_title options={}
       options = {
           :rows                      => 1
       }.merge(options)
       scan(:y1 => 1, :x1 => 1, :y2 => options[:rows], :x2 => 80)
     end
+
+    def execute_cics name
+      write name, :y => 1, :x => 2
+      do_enter
+    end
   end
 
 end

data/lib/mainframe/emulators/passport.rb

@@ -12,37 +12,37 @@ module ButlerMainframe
     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?
+      @action[:ole] = WIN32OLE.new(str_obj)
+      @screen = @action[:ole].Sessions(@session_tag).Screen if sub_object_created?
     end
 
     # Check is session is started
     def sub_object_created?
-      res = @action && @action.Sessions(@session_tag)
+      res = @action[:ole] && @action[:ole].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
+      res = @action[:ole].Sessions(@session_tag).Connected == -1
       puts "#{Time.now.strftime "%H:%M:%S"} Session ready" if @debug == :full && res
       res
     end
 
     def sub_name
-      "#{@action.Name} #{@action.Sessions(@session_tag).Name}"
+      "#{@action[:ole].Name} #{@action[:ole].Sessions(@session_tag).Name}"
     end
 
     def sub_fullname
-      "#{sub_name} #{@action.Sessions(@session_tag).FullName}"
+      "#{sub_name} #{@action[:ole].Sessions(@session_tag).FullName}"
     end
 
     #Ends the connection and closes the session
     def sub_close_session
-      @action.Sessions(@session_tag).Close
-      @action.Quit
-      @action = nil
+      @action[:ole].Sessions(@session_tag).Close
+      @action[:ole].Quit
+      @action[:ole] = nil
     end
 
     #Execute keyboard command like PF1 or PA2 or ENTER ...

data/lib/mainframe/emulators/pcomm.rb

@@ -4,6 +4,7 @@ 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
+# http://www-01.ibm.com/support/knowledgecenter/SSEQ5Y_6.0.0/com.ibm.pcomm.doc/books/html/admin_guide10.htm?lang=en
 module ButlerMainframe
   class Host < HostBase
 
@@ -13,39 +14,41 @@ module ButlerMainframe
     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
+      @action[:ole] = WIN32OLE.new(str_obj)
+      @action[:ole].SetConnectionByName @session_tag
+      @space  = @action[:ole].autECLPS
+      @screen = @action[:ole].autECLOIA
     end
 
     # Check is session is started
     def sub_object_created?
-      res = @action && @action.CommStarted
+      res = @action[:ole] && @action[:ole].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
+      res = @action[:ole].Ready
       puts "#{Time.now.strftime "%H:%M:%S"} Session ready" if @debug == :full && res
       res
     end
 
     def sub_name
-      "PComm #{@action.Name}"
+      "PComm #{@action[:ole].Name}"
     end
 
     def sub_fullname
-      "#{sub_name} #{@action.ConnType}"
+      "#{sub_name} #{@action[:ole].ConnType}"
     end
 
     #Ends the connection and closes the session
     def sub_close_session
-      @action.StopCommunication
-      @action = nil
-      Process.kill 9, @pid if @pid
+      @action[:ole].StopCommunication
+      @action[:ole] = nil
+      # See http://www-01.ibm.com/support/knowledgecenter/SSEQ5Y_6.0.0/com.ibm.pcomm.doc/books/html/admin_guide10.htm?lang=en
+      Process.spawn "PCOMSTOP /S=#{@session_tag} /q" if @pid
+      # Process.kill 9, @pid #Another way is to kill the process but the session start 2nd process pcscm.exe
     end
 
     #Execute keyboard command like PF1 or PA2 or ENTER ...

data/lib/mainframe/emulators/x3270.rb

@@ -92,13 +92,13 @@ module ButlerMainframe
           :check_protect              => true
       }.merge(options)
       sub_set_cursor_axes y, x
-      x_cmd "String(#{text})"
+      x_cmd "String(\"#{text}\")", options
       # TODO
       # if options[:check_protect]
       # end
     end
 
-    # Wait text at given coordinates and wait the session is available again
+    # Wait text at given coordinates
     def sub_wait_for_string text, y, x
       x_cmd "Wait(#{@timeout},InputField)"
       total_time = 0.0
@@ -109,12 +109,12 @@ module ButlerMainframe
         # @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
+      sub_scan_row(y, x, text.size) == text
     end
 
-    def x_cmd cmd
-      puts "x_cmd in: #{cmd}" if @debug
+    # To communicate with executable
+    def x_cmd cmd, options={}
+      puts "x_cmd in: #{options[:sensible_data] ? ('*' * cmd.size) : cmd}" if @debug == :full
       @action[:in].print "#{cmd}\n"
       @action[:in].flush
 
@@ -123,7 +123,7 @@ module ButlerMainframe
 
       line, str_out = '', ''
       while line = @action[:out].gets.chomp do
-        puts "x_cmd out: '#{line}'" if @debug
+        puts "x_cmd out: '#{line}'" if @debug == :full
         break if ar_res.include? line
         str_out << "#{line[6..-1]}" if /^data:\s/ === line
       end

data/lib/mainframe/host_base.rb

@@ -14,7 +14,7 @@ module ButlerMainframe
           :session_tag      => ButlerMainframe.configuration.session_tag,
           :wait             => 0.01,  #wait screen in seconds
           :wait_debug       => 2,     #wait time for debug purpose
-          :debug            => true,
+          :debug            => false,
           :browser_path     => ButlerMainframe.configuration.browser_path,
           :session_url      => ButlerMainframe.configuration.session_url,
           :session_path     => ButlerMainframe.configuration.session_path,
@@ -31,6 +31,7 @@ module ButlerMainframe
       @session_tag      = options[:session_tag]
       @close_session    = options[:close_session]
       @timeout          = options[:timeout]
+      @action           = {}
       @pid              = nil
 
       create_object options
@@ -87,19 +88,32 @@ module ButlerMainframe
 
     # Write text on screen at the coordinates
     # Based on the parameters provided it writes a line or an area
+    # Options:
+    #     :hook                       => nil,
+    #     :y                          => nil, #row
+    #     :x                          => nil, #column
+    #     :check                      => true,
+    #     :raise_error_on_check       => true,
+    #     :sensible_data              => nil,
+    #     :clean_first_chars          => nil, # clean x chars before writing a value
+    #     :erase_field_first          => nil  # erase first until end of field
     def write text, options={}
       options = {
           :hook                       => nil,
-          :y                          => nil, #riga
-          :x                          => nil, #colonna
+          :y                          => nil, #row
+          :x                          => nil, #column
           :check                      => true,
           :raise_error_on_check       => true,
           :sensible_data              => nil,
-          :clean_first_chars          => nil # clean x chars before writing a value
+          :clean_first_chars          => nil, # clean x chars before writing a value
+          :erase_field_first          => nil  # erase first until end of field
       }.merge(options)
 
       y           = options[:y]
       x           = options[:x]
+      y         ||= get_cursor_axes[0]
+      x         ||= get_cursor_axes[1]
+
       hooked_rows = 2
       raise "Missing coordinates! y(row)=#{y} x(column)=#{x} " unless x && y
       raise "Sorry, cannot write null values" unless text
@@ -135,14 +149,14 @@ module ButlerMainframe
     # 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,
+    #     :session_tag      => Fixnum, String or null depending on emulator
+    #     :debug            => boolean
     def create_object options={}
-      connection_attempts       = 8
-      seconds_between_attempts  = 2
+      connection_attempts       = 10
+      seconds_between_attempts  = 1
 
+      # Creating session object for emulators managed by API
+      # Some emulator may start session terminal and return a process id in @pid
       sub_create_object options
 
       if sub_object_created?
@@ -151,23 +165,10 @@ module ButlerMainframe
         # 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?
-                              [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 "#{executable} #{args}"}
-          @pid = $?.pid if $?
-        else
-          #It works only on ruby 1.9+
-          @pid = Process.spawn *[executable, args].compact
-        end
+        # Starting executable, check configuration file
+        start_terminal_session options
 
+        # New connection attempts after starting session...
         puts "Starting session with process id #{@pid}, wait please..." if @debug
         sleep 2
         connection_attempts.times do
@@ -179,6 +180,7 @@ module ButlerMainframe
 
       raise "Session #{@session_tag} not started. Check the session #{options[:browser_path]} #{options[:session_path]}" unless sub_object_created?
 
+      # Session detected and waiting it become operative
       unless sub_object_ready?
         connection_attempts.times do
           puts "Waiting for the session to be ready..." if @debug
@@ -186,11 +188,12 @@ module ButlerMainframe
         end
       end
 
+      # At this stage the session must be operative otherwise raise an exception
       if sub_object_ready?
         puts "** Connection established with #{sub_name} **"
         puts "Session full name: #{sub_fullname}" if @debug == :full
       else
-        raise "Connection refused. Check session #{@session_tag} with process id #{@pid}"
+        raise "Connection refused. Check session #{@session_tag}#{" with process id #{@pid}" if @pid}!"
       end
 
     rescue
@@ -198,6 +201,31 @@ module ButlerMainframe
       raise $!
     end
 
+    # Starting terminal session
+    # Options:
+    #     :browser_path     => browser executable path, default value ButlerMainframe::Settings.browser_path (used by web emulator)
+    #     :session_url      => the session url used by browser
+    #     :session_path     => terminal session executable path, default value ButlerMainframe::Settings.session_path
+    def start_terminal_session options
+      # Check configuration to know emulator starting type
+      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 "#{executable} #{args}"}
+        @pid = $?.pid if $?
+      else
+        #It works only on ruby 1.9+
+        @pid = Process.spawn *[executable, args].compact
+      end
+    end
+
     #It reads one line on the screen
     def scan_row y, x, len
       str = sub_scan_row y, x, len

data/test/test.rake

@@ -6,21 +6,107 @@ namespace :butler do
     desc "Test butler mainframe gem"
     task(:test) do  |task_name, args|
 
+      host = nil
       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
+        wait_between_iterations = 3
 
+        # SLOW
+        simple_iteration  :wait => 0.6
+        sleep(wait_between_iterations)
+
+        # MEDIUM
+        simple_iteration  :wait => 0.08
+        sleep(wait_between_iterations)
+
+        # FAST (default 0.01 atm)
+        simple_iteration
+        sleep(wait_between_iterations)
+
+        puts "*** RAKE TESTS COMPLETE SUCCESSFULLY ***"
       rescue
         puts $!.message
+        puts "--- RAKE TESTS FAILED ---"
         exit(9)
       end
     end
 
   end
+end
+
+def simple_iteration options={}
+  options = {
+      :host                       => nil,
+      :wait                       => nil
+
+  }.merge(options)
+
+  puts
+  puts "*** START ITERATION TEST WAIT #{options[:wait] || 'DEFAULT'} ***"
+  params        = {:debug => false, :wait_debug => 0.5}
+  params[:wait] = options[:wait] if options[:wait]
+  host          = options[:host] || ButlerMainframe::Host.new(params)
+
+  navigate host, :session_login
+
+  str_screen1 = host.scan_page
+  raise 'host.scan_page' if str_screen1.empty?
+
+  navigate host, :next
+  str_screen2 = host.scan_page
+  raise 'navigate :next does not pass login screen' if str_screen1 == str_screen2
+
+  navigate host, :next
+  str_screen2 = host.scan_page
+  raise 'navigate :next does not pass cics selection' if str_screen1 == str_screen2
+
+  # Go back until the first screen
+  navigate host, :session_login
+
+  raise "host.scan row failed"  unless host.scan(:y => 1, :x => 1, :len => 80).size             == 80
+  raise "host.scan area failed" unless host.scan(:y1 => 1, :x1 => 1, :y2 => 3, :x2 => 80).size  == 240
+
+  navigate host, :back
+
+  navigate host, :company_menu
+
+  navigate host, :next
+
+  navigate host, :back
+
+  navigate host, :back
+
+  navigate host, :company_menu
+
+  navigate host, :back
+
+  navigate host, :back
+
+  navigate host, :session_login
+
+  navigate host, :cics_selection
+
+  navigate host, :next
+
+  navigate host, :back
+
+  navigate host, :back
+
+  navigate host, :session_login
+
+  navigate host, :company_menu
+
+  navigate host, :cics_selection
+
+  navigate host, :session_login
+
+  host.close_session
+end
+
+# Easy navigation for rake test
+def navigate host, action
+  msg = "Rake Navigate to #{action}: "
+  print msg
+  host.navigate action
+  puts "#{' ' * (40 - msg.size).abs}OK"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: butler-mainframe
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Marco Mastrodonato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-20 00:00:00.000000000 Z
+date: 2015-10-22 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)