butler-mainframe 0.0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 707011c7063ddf39ff8cfa148f2b91ddaa8a555b
+  data.tar.gz: 3b42e4a7fe6b12d18c746801b3f79bf714c9bd4b
+SHA512:
+  metadata.gz: 31fef2374924d2681e5b68c2e87cde56cc5aeb5038609b7c6bb107ad8bcc7224121d3e1bdbe0515ff71ab2f31af7df022d80b2ec2c97d352b4f376115e75e805
+  data.tar.gz: 4fd2d8220c14bc1edcbca590757d3b9956dcb8de0ef317b54ad6ee18f5368c0d41e5ba150c76b2c320807e49c8cfd9fbcae0f8736c941dc48bf8b6def90efcfc

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+0.0.1 October 5th, 2015
+------------------------------
+* First release

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+#gem "docile"
+gem "i18n"
+gem "butler-mainframe", path: "."

data/LICENSE

@@ -0,0 +1,16 @@
+butler-mainframe
+This software can perform your custom tasks on a 3270 emulator.
+
+Copyright (C) 2015  Marco Mastrodonato, m.mastrodonato@gmail.com
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/README.md

@@ -0,0 +1,154 @@
+# Butler-mainframe
+
+[![Version     ](http://img.shields.io/gem/v/butler-mainframe.svg)                     ](https://rubygems.org/gems/butler-mainframe)
+[![Travis CI   ](http://img.shields.io/travis/marcomd/butler-mainframe/master.svg)     ](https://travis-ci.org/marcomd/butler-mainframe)
+[![Quality     ](http://img.shields.io/codeclimate/github/marcomd/butler-mainframe.svg)](https://codeclimate.com/github/marcomd/butler-mainframe)
+
+This gem provides a virtual butler which can perform your custom tasks on a 3270 emulator.
+You just have to choose your emulator and configure your task.
+
+## Compatibility
+
+At the moment it works only on windows plaftorms.
+Check on travis badge
+
+
+## Install
+
+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)
+
+## 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:
+
+    irb(main):002:0> host = ButlerMainframe::Host.new
+    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>
+
+now session is ready to use:
+
+    host.scan_page
+
+should return you what you see on your terminal
+
+## Commands
+
+You can do anything (disclaimer: as long as it was planned :innocent:)
+
+### Scan
+```ruby
+# Scan and return all text in the terminal:
+host.scan_page
+
+# only a rectangle, in this example the first two rows:
+host.scan x1: 1, y1: 1, x2: 80, y2: 2
+
+# only a text
+host.scan x: 10, y: 10, len: 10
+```
+
+### Write
+```ruby
+# write a text at the coordinates
+host.write 'ruby on rails', :y => 6, :x => 15
+
+# write a text using a hook
+# With the hook you can use a regular expression to search a label on the y axis (3 rows up and down)
+# It is usefull when the y position could change (atm it does not use x axis)
+host.write 'ruby on rails', :y => 6, :x => 15, hook: 'SYSTEM='
+```
+
+### Navigate
+
+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.
+
+```ruby
+# Go to the login session screen
+host.navigate :login_session
+
+# Now go to the next
+host.navigate :next
+
+# To go to the next screen Butler login for you
+
+# Go back is simple as well
+host.navigate :back
+
+# You can configure your own destination in the generic functions module
+host.navigate :your_favourite_screen
+```
+
+This is possible because it is configured in the navigate method which have to be configured to fit your needs. You can find it inside lib\mainframe\customization.
+
+My advice is to use navigate method for generic navigation and use a specific module (or rails model) for each task.
+
+## With Rails
+
+This module can be use on rails project.
+Add in your gemfile
+
+    gem 'butler-mainframe'
+
+then
+
+    bundle install
+
+run generator to copy configuration files
+
+    rails g butler:install
+
+```ruby
+Class Invoice
+    ... your code
+
+    def host3270
+        host = ButlerMainframe::Host.new
+        host.navigate :my_starting_position
+        host.write 'Hello world'
+        host.close_session
+    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:
+has_many :screens, :as => :hook, :dependent => :destroy
+
+## License
+
+The GNU Lesser General Public License, version 3.0 (LGPL-3.0)
+See LICENSE file
+Custom files are yours and not under license.
+
+
+## Found a bug?
+
+If you are having a problem please submit an issue at
+* m.mastrodonato@gmail.com
+
+
+
+

data/lib/butler-mainframe.rb

@@ -0,0 +1,55 @@
+# This software can perform your custom tasks on a 3270 emulator.
+#
+# Copyright (C) 2015  Marco Mastrodonato, m.mastrodonato@gmail.com
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License
+
+require 'core/configuration'
+require 'core/configuration_dynamic'
+require 'config/config'
+
+module ButlerMainframe
+  def self.root
+    File.expand_path('../..', __FILE__)
+  end
+end
+
+# TODO
+# require 'i18n'
+# I18n.load_path=Dir['config/locales/*.yml']
+# I18n.locale = ButlerMainframe.configuration.language
+
+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}"
+
+
+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
+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
+end
+
+if ButlerMainframe::Settings.modules_included[:custom_functions] && defined?(Host3270::CustomFunctions)
+  # puts "Extending Host class with #{Host3270::CustomFunctions}" if debug
+  ButlerMainframe::Host.include Host3270::CustomFunctions
+end
+
+=begin
+# To test in irb
+require 'butler-mainframe'
+host=ButlerMainframe::Host.new
+host.scan_page
+=end

data/lib/config/config.rb

@@ -0,0 +1,7 @@
+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'
+end
+

data/lib/config/settings.yml

@@ -0,0 +1,20 @@
+defaults: &defaults
+  cics: 7
+  user: "IBM0001"
+  password: "password"
+  life_user: "LIFE1"
+  life_password: "password"
+  modules_included:
+    activerecord: yes
+    generic_functions: yes
+    custom_functions: yes
+
+development:
+  <<: *defaults
+
+test:
+  <<: *defaults
+
+production:
+  <<: *defaults
+  cics: 4

data/lib/core/configuration.rb

@@ -0,0 +1,27 @@
+module ButlerMainframe
+  class Configuration
+    attr_writer :allow_sign_up
+
+    attr_accessor :language, :host_gateway, :browser_path, :session_path
+
+    def initialize
+      @language       = :en
+      @host_gateway   = nil
+      @browser_path   = ""
+      @session_path   = ""
+    end
+
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configuration=(config)
+    @configuration = config
+  end
+
+  def self.configure
+    yield configuration
+  end
+end

data/lib/core/configuration_dynamic.rb

@@ -0,0 +1,67 @@
+require 'yaml'
+require 'vendor/deep_symbolize'
+
+module ButlerMainframe
+  # we don't want to instantiate this class - it's a singleton,
+  # so just keep it as a self-extended module
+  extend self
+
+  # Appdata provides a basic single-method DSL with .parameter method
+  # being used to define a set of available settings.
+  # This method takes one or more symbols, with each one being
+  # a name of the configuration option.
+  def parameter(*names)
+    names.each do |name|
+      attr_accessor name
+
+      # For each given symbol we generate accessor method that sets option's
+      # value being called with an argument, or returns option's current value
+      # when called without arguments
+      define_method name do |*values|
+        value = values.first
+        value ? self.send("#{name}=", value) : instance_variable_get("@#{name}")
+      end
+    end
+  end
+
+  # And we define a wrapper for the configuration block, that we'll use to set up
+  # our set of options
+  def configure_on_the_fly(&block)
+    instance_eval &block
+  end
+  
+  module Settings
+    # again - it's a singleton, thus implemented as a self-extended module
+    extend self
+
+    @_settings = {}
+    attr_reader :_settings
+
+    # This is the main point of entry - we call Settings.load! and provide
+    # a name of the file to read as it's argument. We can also pass in some
+    # options, but at the moment it's being used to allow per-environment
+    # overrides in Rails
+    def load!(filename, options = {})
+      newsets = YAML::load_file(filename)
+      newsets.extend DeepSymbolizable
+      newsets = newsets.deep_symbolize
+      newsets = newsets[options[:env].to_sym] if options[:env] && \
+                                                 newsets[options[:env].to_sym]
+      deep_merge!(@_settings, newsets)
+    end
+
+    # Deep merging of hashes
+    # deep_merge by Stefan Rusterholz, see http://www.ruby-forum.com/topic/142809
+    def deep_merge!(target, data)
+      merger = proc{|key, v1, v2|
+        Hash === v1 && Hash === v2 ? v1.merge(v2, &merger) : v2 }
+      target.merge! data, &merger
+    end
+
+    def method_missing(name, *args, &block)
+      @_settings[name.to_sym] ||
+      fail(NoMethodError, "unknown configuration root #{name}", caller)
+    end
+
+  end
+end

data/lib/generators/butler/USAGE

@@ -0,0 +1,10 @@
+Description:
+    Copy configurations file into local rails app
+
+Example:
+    rails generate butler:install
+
+Check all your generators:
+    rails g --help
+
+

data/lib/generators/butler/install_generator.rb

@@ -0,0 +1,23 @@
+require 'rails/generators/base'
+
+module Butler
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Installs ButlerMainframe configuration files"
+      source_root File.expand_path('../../', __FILE__)
+
+      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
+        append_file file do
+          <<-FILE.gsub(/^            /, '')
+            ButlerMainframe::Settings.load!(File.join(Rails.root,'config','butler.yml'), :env => Rails.env)
+          FILE
+        end
+      end
+    end
+  end
+end
+

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

@@ -0,0 +1,159 @@
+# These modules contain extensions for the Host class
+module Host3270
+  module CustomFunctions
+    ### Insert here your custom methods ###
+
+    ### Update default generic function ###
+    # def do_enter; exec_command "ENTER" end
+    #
+    # def go_back; exec_command "PA2" end
+    #
+    # def do_confirm; exec_command "PF3" end
+    #
+    # def do_quit; exec_command "CLEAR" end
+    #
+    # def destination_list
+    #   [
+    #       :company_menu,
+    #       :cics_selection,
+    #       :session_login,
+    #       :next,
+    #       :back]
+    # end
+    #
+    # def navigate destination, options={}
+    #   options = {
+    #       :cics             => ButlerMainframe::Settings.cics,
+    #       :user             => ButlerMainframe::Settings.user,
+    #       :password         => ButlerMainframe::Settings.password,
+    #       :raise_on_abend   => false
+    #   }.merge(options)
+    #   attempts_number         = 10
+    #   transactions_after_cics = ['tra1','tra2']
+    #
+    #   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 cics?
+    #       case destination
+    #         when :cics_selection,
+    #             :session_login       then
+    #           write "cesf logoff", :y => 1, :x => 1
+    #           do_enter
+    #         when :back                then
+    #           write "cesf logoff", :y => 1, :x => 1
+    #           do_enter
+    #           bol_found = true; break
+    #         when :next                then
+    #           write transactions_after_cics[0], :y => 1, :x => 1
+    #           do_enter
+    #           bol_found = true; break
+    #         when :company_menu        then write transactions_after_cics[1], :y => 1, :x => 1
+    #         else
+    #           #Se siamo nel cics avviamo direttamente il life
+    #           write transactions_after_cics[0], :y => 1, :x => 1
+    #           do_enter
+    #       end
+    #     elsif cics_selection?
+    #       case destination
+    #         when :cics_selection      then bol_found = true; break
+    #         when :session_login       then exec_command("PF3")
+    #         when :next                then
+    #           cics_selection options[:cics] if options[:cics]
+    #           bol_found = true; break
+    #         when :back                then
+    #           exec_command("PF3")
+    #           bol_found = true; break
+    #         else
+    #           cics_selection options[:cics] if options[:cics]
+    #       end
+    #     elsif session_login?
+    #       case destination
+    #         when :session_login,
+    #             :back                then bol_found = true; break
+    #         when :next                then
+    #           session_login options[:user], options[:password] if options[:user] && options[:password]
+    #           bol_found = true; break
+    #         else
+    #           session_login options[:user], options[:password] if options[:user] && options[:password]
+    #       end
+    #     else
+    #       # If we do not know where we are...
+    #       case destination
+    #         when :back            then
+    #           # ...we can try to go back
+    #           go_back
+    #           bol_found = true; break
+    #         when :next              then
+    #           # ...but we dont know how to move forward
+    #         else
+    #           # We unlock the position with both commands to be sure that they are managed by all maps cics
+    #           go_back; do_quit
+    #       end
+    #     end
+    #     wait_session
+    #   end
+    #
+    #   raise "It was waiting #{destination} map instead of: #{screen_title(:rows => 2).strip}" unless bol_found
+    # end
+    #
+    # def cics?
+    #   scan(:y1 => 1, :x1 => 1, :y2 => 22, :x2 => 80).strip.empty?
+    # end
+    #
+    # #Login to mainframe
+    # def session_login?
+    #   /EMSP00/i === screen_title
+    # end
+    #
+    # def session_login user, password
+    #   puts "Starting session login..." if @debug
+    #   wait_session
+    #   #inizializza_sessione
+    #   raise "It was waiting session login map instead of: #{screen_title}" unless session_login?
+    #   write user,      :y => 16, :x => 36
+    #   write password,  :y => 17, :x => 36, :sensible_data => true
+    #   do_enter
+    # end
+    #
+    # # We need a label to know when we are on the cics selection map, usually ibm use EMSP01
+    # def cics_selection?
+    #   /EMSP01/i === screen_title
+    # end
+    #
+    # # On this map, we have to select the cics environment
+    # 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?
+    #   write cics, :y => 23, :x => 14
+    #   do_enter
+    #   wait_session 1
+    # end
+    #
+    #
+    # def catch_message options={}
+    #   options = {
+    #       :first_row                    => 22,
+    #       :last_row                     => 23
+    #   }.merge(options)
+    #   scan(:y1 => options[:first_row], :x1 => 1, :y2 => options[:last_row], :x2 => 80).gsub(/\s+/, " ").strip
+    # end
+    # def catch_abend
+    #   scan(:y1 => 23, :x1 => 1, :y2 => 23, :x2 => 80)
+    # end
+    # def abend?
+    #   /DFHA/i === catch_abend
+    # end
+    # def screen_title options={}
+    #   options = {
+    #       :rows                      => 1
+    #   }.merge(options)
+    #   scan(:y1 => 1, :x1 => 1, :y2 => options[:rows], :x2 => 80)
+    # end
+  end
+end
+
+ButlerMainframe::Host.include Host3270::CustomFunctions

data/lib/generators/butler_mainframe.rb

@@ -0,0 +1,38 @@
+module ButlerMainframe
+  module Base
+    protected
+    # def authorization_file
+    #   "app/models/ability.rb"
+    # end
+    # def authorization?
+    #   File.exists? authorization_file
+    # end
+    # def authentication_file auth_class="User"
+    #   "app/models/#{auth_class.downcase}.rb"
+    # end
+    # def authentication? auth_class="User"
+    #   return true if File.exists? authentication_file(auth_class)
+    #   File.exists? "config/initializers/devise.rb"
+    # end
+    # def activeadmin_file
+    #   "config/initializers/active_admin.rb"
+    # end
+    # def activeadmin?
+    #   File.exists? activeadmin_file
+    # end
+    # def auth_class
+    #   return unless options[:auth_class]
+    #   options[:auth_class].classify
+    # end
+    #def formtastic?
+    #  return false unless options.formtastic?
+    #  File.exists? "config/initializers/formtastic.rb"
+    #end
+    #def jquery_ui?
+    #  File.exists? "vendor/assets/javascripts/jquery-ui"
+    #end
+    #def pagination?
+    #  File.exists? "config/initializers/kaminari_config.rb"
+    #end
+  end
+end

data/lib/mainframe/customization/active_record.rb

@@ -0,0 +1,26 @@
+# These modules contain extensions for the Host class
+module Host3270
+  # This module can be use on rails project.
+  #
+  # 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:
+  # has_many :screens, :as => :hook, :dependent => :destroy
+  module ActiveRecord
+    # screen_type: error, alert, notice...
+    def screenshot screen_type, options={}
+      options = {
+          :message          => nil,
+          :video            => nil,
+          :rails_model      => Screen
+      }.merge(options)
+      screen              = options[:rails_model].new
+      screen.screen_type  = screen_type
+      screen.message      = options[:message] || catch_message
+      screen.video        = options[:video]   || scan(:y1 => 1, :x1 => 1, :y2 => 22, :x2 => 80)
+      screen.cursor_y, screen.cursor_x = get_cursor_axes
+      screen
+    end
+  end
+end

data/lib/mainframe/customization/generic_functions.rb

@@ -0,0 +1,156 @@
+# These modules contain extensions for the Host class
+module Host3270
+  module GenericFunctions
+
+    def do_enter; exec_command "ENTER" end
+
+    def go_back; exec_command "PA2" end
+
+    def do_confirm; exec_command "PF3" end
+
+    def do_quit; exec_command "CLEAR" end
+
+    def destination_list
+      [
+      :company_menu,
+      :cics_selection,
+      :session_login,
+      :next,
+      :back]
+    end
+
+    def navigate destination, options={}
+      options = {
+          :cics             => ButlerMainframe::Settings.cics,
+          :user             => ButlerMainframe::Settings.user,
+          :password         => ButlerMainframe::Settings.password,
+          :raise_on_abend   => false
+      }.merge(options)
+      attempts_number         = 10
+      transactions_after_cics = ['tra1','tra2']
+
+      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 cics?
+          case destination
+            when :cics_selection,
+                 :session_login       then
+              write "cesf logoff", :y => 1, :x => 1
+              do_enter
+            when :back                then
+              write "cesf logoff", :y => 1, :x => 1
+              do_enter
+              bol_found = true; break
+            when :next                then
+              write transactions_after_cics[0], :y => 1, :x => 1
+              do_enter
+              bol_found = true; break
+            when :company_menu        then write transactions_after_cics[1], :y => 1, :x => 1
+            else
+              #Se siamo nel cics avviamo direttamente il life
+              write transactions_after_cics[0], :y => 1, :x => 1
+              do_enter
+          end
+        elsif cics_selection?
+          case destination
+            when :cics_selection      then bol_found = true; break
+            when :session_login       then exec_command("PF3")
+            when :next                then
+              cics_selection options[:cics] if options[:cics]
+              bol_found = true; break
+            when :back                then
+              exec_command("PF3")
+              bol_found = true; break
+            else
+              cics_selection options[:cics] if options[:cics]
+          end
+        elsif session_login?
+          case destination
+            when :session_login,
+                 :back                then bol_found = true; break
+            when :next                then
+              session_login options[:user], options[:password] if options[:user] && options[:password]
+              bol_found = true; break
+            else
+              session_login options[:user], options[:password] if options[:user] && options[:password]
+          end
+        else
+          # If we do not know where we are...
+          case destination
+            when :back            then
+              # ...we can try to go back
+              go_back
+              bol_found = true; break
+            when :next              then
+              # ...but we dont know how to move forward
+            else
+              # We unlock the position with both commands to be sure that they are managed by all maps cics
+              go_back; do_quit
+          end
+        end
+        wait_session
+      end
+
+      raise "It was waiting #{destination} map instead of: #{screen_title(:rows => 2).strip}" unless bol_found
+    end
+
+    def cics?
+      scan(:y1 => 1, :x1 => 1, :y2 => 22, :x2 => 80).strip.empty?
+    end
+
+    #Login to mainframe
+    def session_login?
+      /EMSP00/i === screen_title
+    end
+
+    def session_login user, password
+      puts "Starting session login..." if @debug
+      wait_session
+      #inizializza_sessione
+      raise "It was waiting session login map instead of: #{screen_title}" unless session_login?
+      write user,      :y => 16, :x => 36
+      write password,  :y => 17, :x => 36, :sensible_data => true
+      do_enter
+    end
+
+    # We need a label to know when we are on the cics selection map, usually ibm use EMSP01
+    def cics_selection?
+      /EMSP01/i === screen_title
+    end
+
+    # On this map, we have to select the cics environment
+    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?
+      write cics, :y => 23, :x => 14
+      do_enter
+      wait_session 1
+    end
+
+
+    def catch_message options={}
+      options = {
+        :first_row                    => 22,
+        :last_row                     => 23
+      }.merge(options)
+      scan(:y1 => options[:first_row], :x1 => 1, :y2 => options[:last_row], :x2 => 80).gsub(/\s+/, " ").strip
+    end
+    def catch_abend
+      scan(:y1 => 23, :x1 => 1, :y2 => 23, :x2 => 80)
+    end
+    def abend?
+      /DFHA/i === catch_abend
+    end
+    def screen_title options={}
+      options = {
+          :rows                      => 1
+      }.merge(options)
+      scan(:y1 => 1, :x1 => 1, :y2 => options[:rows], :x2 => 80)
+    end
+  end
+
+end

data/lib/mainframe/host_base.rb

@@ -0,0 +1,232 @@
+module ButlerMainframe
+  # This is the host class base that contains high level logic
+  # It uses sub method that have to be defined in the specific sub class
+  class HostBase
+
+    attr_reader :action, :wait
+    attr_accessor :debug
+
+    MAX_TERMINAL_COLUMNS = 80
+    MAX_TERMINAL_ROWS    = 24
+
+    def initialize options={}
+      options = {
+          :session          => 1,
+          :wait             => 0.01,  #wait screen in seconds
+          :wait_debug       => 2,     #wait time for debug purpose
+          :debug            => true,
+          :browser_path     => ButlerMainframe.configuration.browser_path,
+          :session_path     => ButlerMainframe.configuration.session_path,
+          :close_session    => :evaluate
+                              #:evaluate    if the session is found will not be closed
+                              #:never       never close the session
+                              #:always      the session is always closed
+      }.merge(options)
+
+      @debug            = options[:debug]
+      @wait             = options[:wait]
+      @wait_debug       = options[:wait_debug]
+      @session          = options[:session]
+      @close_session    = options[:close_session]
+      @pid = nil
+
+      create_object options
+    end
+
+    # Ends the connection and closes the session
+    def close_session
+      puts "Closing session with criterion \"#{@close_session}\"" if @debug
+      case @close_session
+        when :always
+          sub_close_session
+          puts "Session closed" if @debug
+          wait_session 0.1
+        when :evaluate
+          if @session_started_by_me
+            sub_close_session
+            puts "Session closed cause started by this process" if @debug
+            wait_session 0.1
+          else
+            puts "Session not closed because it was already existing" if @debug
+          end
+      end
+      @action = nil
+    end
+
+    # Sleep time between operations
+    def wait_session wait=nil
+      sleep(wait || (@debug ? @wait_debug : @wait))
+    end
+
+    # 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
+    end
+
+    # It reads one line or an area on the screen according to parameters supplied
+    def scan options={}
+      options = {
+          :y => nil, :x => nil, :len => nil,
+          :y1 => nil, :x1 => nil, :y2 => nil, :x2 => nil,
+      }.merge(options)
+      if options[:len]
+        scan_row options[:y], options[:x], options[:len]
+      else
+        scan_area options[:y1], options[:x1], options[:y2], options[:x2]
+      end
+    end
+
+    # Scans and returns the text of the entire page
+    def scan_page
+      scan_area 1, 1, MAX_TERMINAL_ROWS, MAX_TERMINAL_COLUMNS
+    end
+
+    # Write text on screen at the coordinates
+    # Based on the parameters provided it writes a line or an area
+    def write text, options={}
+      options = {
+          :hook                       => nil,
+          :y                          => nil, #riga
+          :x                          => nil, #colonna
+          :check                      => true,
+          :raise_error_on_check       => true,
+          :sensible_data              => nil,
+          :clean_first_chars          => nil
+      }.merge(options)
+
+      y=options[:y]
+      x=options[:x]
+      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
+            break
+          end
+        end
+      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
+
+    # It returns the coordinates of the cursor
+    def get_cursor_axes
+      sub_get_cursor_axes
+    end
+
+    private
+
+    # It creates the object calling subclass method
+    # 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
+      unless sub_object_created?
+        puts "Session not found, starting new..." if @debug
+
+        if /^1.8/ === RUBY_VERSION
+          Thread.new {system "#{options[:browser_path]} #{options[:session_path]}"}
+          @pid = $?.pid if $?
+        else
+          #It works only on ruby 1.9+
+          @pid = Process.spawn "#{options[:browser_path]}", "#{options[:session_path]}"
+        end
+
+        puts "Starting session with process id #{@pid}, wait please..." if @debug
+        sleep 2
+        5.times do
+          puts "Wait please..." if @debug
+          sub_create_object
+          sub_object_created? ? break : sleep(10)
+        end
+        @session_started_by_me = true
+      end
+
+      if sub_object_created?
+        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."
+      end
+
+    rescue
+      puts $!.message
+      raise $!
+    end
+
+    #It reads one line on the screen
+    def scan_row y, x, len
+      str = sub_scan_row y, x, len
+      puts "Scan row y:#{y} x:#{x} lungo:#{len} = #{str}" if @debug
+      str
+    end
+
+    #It reads a rectangle on the screen
+    def scan_area y1, x1, y2, x2
+      str = sub_scan_area y1, x1, y2, x2
+      puts "Scan area y1:#{y1} x1:#{x1} y2:#{y2} x2:#{x2} = #{str}" if @debug
+      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
+      }.merge(options)
+      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
+      # It returns the function's result
+      if options[:check]
+        # It expects the string is present on the session at the specified coordinates
+        if sub_wait_for_string text, y, x
+          return true
+        else
+          if options[:raise_error_on_check]
+            raise "Impossible to write #{options[:sensible_data] ? ('*' * text.size) : text} at row #{y} column #{x}"
+          else
+            return false
+          end
+        end
+      else
+        return true
+      end
+    end
+
+    # If is called a not existing method there is the chance that an optional module may not have been added
+    def method_missing method_name, *args
+      raise NoMethodError, "Method #{method_name} not found! Please check you have included any optional modules"
+    end
+
+  end
+end
+

data/lib/mainframe/passport.rb

@@ -0,0 +1,66 @@
+require 'win32ole'
+require 'mainframe/host_base'
+
+# This class use Rocket 3270 emulator API
+# http://www.rocketsoftware.com/products/rocket-passport-web-to-host
+module ButlerMainframe
+  class Host < HostBase
+
+    private
+
+    def sub_create_object
+      str_obj = 'PASSPORT.System'
+      puts "#{Time.now.strftime "%H:%M:%S"} Creating object #{str_obj}..." if @debug == :full
+      @action = WIN32OLE.new(str_obj)
+    end
+
+    def sub_object_created?
+      puts "#{Time.now.strftime "%H:%M:%S"} Terminal successfully detected" if @debug == :full
+      @action.Sessions(@session)
+    end
+
+    def sub_name
+      @action.Sessions(@session).Name
+    end
+
+    def sub_fullname
+      @action.Sessions(@session).FullName
+    end
+
+    #Ends the connection and closes the session
+    def sub_close_session
+      @action.Sessions(@session).Close
+      @action.Quit
+    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
+    end
+
+    #It reads one line part of the screen
+    def sub_scan_row y, x, len
+      @action.Sessions(@session).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
+    end
+
+    def sub_get_cursor_axes
+      [@action.Sessions(@session).Screen.Col, @action.Sessions(@session).Screen.Row]
+    end
+
+    def sub_write_text text, y, x
+      @action.Sessions(@session).Screen.PutString(text, y, x)
+    end
+
+    def sub_wait_for_string text, y, x
+      @action.Sessions(@session).Screen.WaitForString(text, y, x).Value == -1
+    end
+
+  end
+end
+

data/lib/vendor/deep_symbolize.rb

@@ -0,0 +1,60 @@
+# Symbolizes all of hash's keys and subkeys.
+# Also allows for custom pre-processing of keys (e.g. downcasing, etc)
+# if the block is given:
+#
+# somehash.deep_symbolize { |key| key.downcase }
+#
+# Usage: either include it into global Hash class to make it available to
+#        to all hashes, or extend only your own hash objects with this
+#        module.
+#        E.g.:
+#        1) class Hash; include DeepSymbolizable; end
+#        2) myhash.extend DeepSymbolizable
+ 
+module DeepSymbolizable
+  def deep_symbolize(&block)
+    method = self.class.to_s.downcase.to_sym
+    syms = DeepSymbolizable::Symbolizers
+    syms.respond_to?(method) ? syms.send(method, self, &block) : self
+  end
+ 
+  module Symbolizers
+    extend self
+ 
+    # the primary method - symbolizes keys of the given hash,
+    # preprocessing them with a block if one was given, and recursively
+    # going into all nested enumerables
+    def hash(hash, &block)
+      hash.inject({}) do |result, (key, value)|
+        # Recursively deep-symbolize subhashes
+        value = _recurse_(value, &block)
+ 
+        # Pre-process the key with a block if it was given
+        key = yield key if block_given?
+        # Symbolize the key string if it responds to to_sym
+        sym_key = key.to_sym rescue key
+ 
+        # write it back into the result and return the updated hash
+        result[sym_key] = value
+        result
+      end
+    end
+ 
+    # walking over arrays and symbolizing all nested elements
+    def array(ary, &block)
+      ary.map { |v| _recurse_(v, &block) }
+    end
+ 
+    # handling recursion - any Enumerable elements (except String)
+    # is being extended with the module, and then symbolized
+    def _recurse_(value, &block)
+      if value.is_a?(Enumerable) && !value.is_a?(String)
+        # support for a use case without extended core Hash
+        value.extend DeepSymbolizable unless value.class.include?(DeepSymbolizable) 
+        value = value.deep_symbolize(&block)
+      end
+      value
+    end
+  end
+ 
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: butler-mainframe
+version: !ruby/object:Gem::Version
+  version: 0.0.5
+platform: ruby
+authors:
+- Marco Mastrodonato
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-10-07 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)
+  and configure your task.
+email:
+- m.mastrodonato@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- lib/butler-mainframe.rb
+- lib/config/config.rb
+- lib/config/settings.yml
+- lib/core/configuration.rb
+- lib/core/configuration_dynamic.rb
+- lib/generators/butler/USAGE
+- lib/generators/butler/install_generator.rb
+- lib/generators/butler/templates/custom_functions.rb
+- lib/generators/butler_mainframe.rb
+- lib/mainframe/customization/active_record.rb
+- lib/mainframe/customization/generic_functions.rb
+- lib/mainframe/host_base.rb
+- lib/mainframe/passport.rb
+- lib/vendor/deep_symbolize.rb
+homepage: https://github.com/marcomd/butler-mainframe
+licenses:
+- LGPL-3.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- So many patience
+rubyforge_project: 
+rubygems_version: 2.2.5
+signing_key: 
+specification_version: 4
+summary: A virtual butler to perform tasks on a 3270 emulator
+test_files: []