Class: TE3270::Emulators::BlueZone

Inherits:
Object
  • Object
show all
Defined in:
lib/te3270/emulators/bluezone.rb

Overview

This class has the code necessary to communicate with the terminal emulator called Rocket BlueZone. You can use this emulator by providing the :bluezone parameter to the constructor of your screen object or by passing the same value to the emulator_for method on the TE3270 module.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ BlueZone

Initialize the emulator with defaults. This also loads libraries used to take screenshots on supported platforms.



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/te3270/emulators/bluezone.rb', line 29

def initialize
  @connect_retry_timeout = 30
  @max_column_length = 80
  @max_wait_time = 100
  @session_file = nil
  @session_id = 1
  @timeout = 10
  @visible = true
  @window_state = :normal
  @write_errors_to_ignore = [5, 6]
  @write_method = :full_string

  if jruby?
    require 'jruby-win32ole'
    require 'java'
    include_class 'java.awt.Dimension'
    include_class 'java.awt.Rectangle'
    include_class 'java.awt.Robot'
    include_class 'java.awt.Toolkit'
    include_class 'java.awt.event.InputEvent'
    include_class 'java.awt.image.BufferedImage'
    include_class 'javax.imageio.ImageIO'
  else
    require 'win32ole'
    require 'win32/screenshot'
  end
end

Instance Attribute Details

#connect_retry_timeout=(value) ⇒ Object (writeonly)

Sets the attribute connect_retry_timeout

Parameters:

  • value —

    the value to set the attribute connect_retry_timeout to.



16
17
18
 
# File 'lib/te3270/emulators/bluezone.rb', line 16

def connect_retry_timeout=(value)
  @connect_retry_timeout = value
end

#max_column_length=(value) ⇒ Object (writeonly)

Sets the attribute max_column_length

Parameters:

  • value —

    the value to set the attribute max_column_length to.



16
17
18
 
# File 'lib/te3270/emulators/bluezone.rb', line 16

def max_column_length=(value)
  @max_column_length = value
end

#max_wait_time=(value) ⇒ Object (writeonly)

Sets the attribute max_wait_time

Parameters:

  • value —

    the value to set the attribute max_wait_time to.



16
17
18
 
# File 'lib/te3270/emulators/bluezone.rb', line 16

def max_wait_time=(value)
  @max_wait_time = value
end

#session_file=(value) ⇒ Object (writeonly)

Sets the attribute session_file

Parameters:

  • value —

    the value to set the attribute session_file to.



16
17
18
 
# File 'lib/te3270/emulators/bluezone.rb', line 16

def session_file=(value)
  @session_file = value
end

#session_id=(value) ⇒ Object (writeonly)

Sets the attribute session_id

Parameters:

  • value —

    the value to set the attribute session_id to.



16
17
18
 
# File 'lib/te3270/emulators/bluezone.rb', line 16

def session_id=(value)
  @session_id = value
end

#timeout=(value) ⇒ Object (writeonly)

Sets the attribute timeout

Parameters:

  • value —

    the value to set the attribute timeout to.



16
17
18
 
# File 'lib/te3270/emulators/bluezone.rb', line 16

def timeout=(value)
  @timeout = value
end

#write_errors_to_ignore=(value) ⇒ Object (writeonly)

Sets the attribute write_errors_to_ignore

Parameters:

  • value —

    the value to set the attribute write_errors_to_ignore to.



16
17
18
 
# File 'lib/te3270/emulators/bluezone.rb', line 16

def write_errors_to_ignore=(value)
  @write_errors_to_ignore = value
end

#write_method=(value) ⇒ Object (writeonly)

Sets the attribute write_method

Parameters:

  • value —

    the value to set the attribute write_method to.



16
17
18
 
# File 'lib/te3270/emulators/bluezone.rb', line 16

def write_method=(value)
  @write_method = value
end

Instance Method Details

#connect {|_self| ... } ⇒ Object

Creates a method to connect to BlueZone. This method expects a block in which certain platform specific values can be set. BlueZone can take the following parameters.

  • connect_retry_timeout - number of seconds to retry connecting to a session. Defaults to 30.

  • max_column_length - number of columns in a terminal row. Defaults to 80.

  • max_wait_time - number of milliseconds to wait before resuming script execution after sending keys from host. Defaults to 100.

  • session_file - this value is required and should be the filename of the session.

  • session_id - numeric identifier for type of session to connect to. From BlueZone’s docs: 1 for S1: 2 for S2; 3 for S3; etc. Defaults to 1.

  • timeout - numeric number of seconds till system calls timeout. Defaults to 10.

  • visible - determines if the emulator is visible or not. If not set it will default to true.

  • window_state - determines the state of the session window. Valid values are :minimized, :normal, and :maximized. If not set it will default to :normal.

  • write_errors_to_ignore - array of error codes to ignore during “char” write method. Defaults to [5, 6].

  • write_method - write strings to the terminal all at once or one character at a time Valid values are :full_string, and :char. Default is :full_string.

Examples:

Example calling screen object constructor with a block

screen_object = MyScreenObject.new(:bluezone)
screen_object.connect do |emulator|
  emulator.session_file = 'path_to_session_file'
  emulator.visible = true
  emulator.window_state = :maximized
end

Yields:

  • (_self)

Yield Parameters:

Raises:



82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/te3270/emulators/bluezone.rb', line 82

def connect
  start_bluezone_system
  yield self if block_given?
  raise InvalidWriteMethodError unless [:char, :full_string].include?(@write_method)
  raise SessionFileMissingError if @session_file.nil?

  result = system.OpenSession(SESSION_TYPE[:Mainframe], @session_id, @session_file, @timeout, 1)
  raise BlueZoneError, "Error opening session: #{result}; #{@session_file}" if result != 0

  result = system.Connect('!', @connect_retry_timeout)
  raise BlueZoneError, "Error connecting to session: #{result}" if result != 0
end

#disconnect ⇒ Object

Disconnects the BlueZone connection



98
99
100
 
# File 'lib/te3270/emulators/bluezone.rb', line 98

def disconnect
  system.CloseSession(SESSION_TYPE[:Mainframe], @session_id)
end

#get_string(row, column, length) ⇒ String

Extracts text of specified length from a start point.

Parameters:

  • row (Fixnum) —

    the x coordinate of location on the screen.

  • column (Fixnum) —

    the y coordinate of location on the screen.

  • length (Fixnum) —

    the length of string to extract

Returns:

  • (String) 


110
111
112
 
# File 'lib/te3270/emulators/bluezone.rb', line 110

def get_string(row, column, length)
  system.PSGetText(length, ((row - 1) * @max_column_length) + column)
end

#put_string(input, row, column) ⇒ Object

Puts string at the coordinates specified.

Parameters:

  • input (String|Fixnum) —

    the value to set; value is cast to string

  • row (Fixnum) —

    the x coordinate of the location on the screen.

  • column (Fixnum) —

    the y coordinate of the location on the screen.



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/te3270/emulators/bluezone.rb', line 121

def put_string(input, row, column)
  input_as_string = input.to_s

  if @write_method == :full_string
    system.WriteScreen(input_as_string, row, column)
    system.WaitReady(@timeout, @max_wait_time)
  elsif @write_method == :char
    input_as_string.chars.each_with_index do |char, index|
      position = ((row - 1) * @max_column_length) + column + index
      position_row = (position / @max_column_length.to_f).ceil
      position_col = position % @max_column_length
      position_col = position_col == 0 ? @max_column_length : position_col
      result = system.WriteScreen(char, position_row, position_col)
      break unless ([0] + @write_errors_to_ignore).include?(result)
      system.WaitReady(@timeout, @max_wait_time)
    end
  else
    raise InvalidWriteMethodError, @write_method
  end
end

#screenshot(filename) ⇒ Object

Creates a method to take screenshot of the active screen. If you have set the :visible property to false it will be made visible prior to taking the screenshot and then changed to invisible after.

Parameters:

  • filename (String) —

    the path and name of the screenshot file to be saved



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/te3270/emulators/bluezone.rb', line 149

def screenshot(filename)
  File.delete(filename) if File.exists?(filename)
  original_visibility = @visible
  self.visible = true

  if jruby?
    toolkit = Toolkit::getDefaultToolkit()
    screen_size = toolkit.getScreenSize()
    rect = Rectangle.new(screen_size)
    robot = Robot.new
    image = robot.createScreenCapture(rect)
    f = java::io::File.new(filename)
    ImageIO::write(image, "png", f)
  else
    hwnd = system.WindowHandle
    Win32::Screenshot::Take.of(:window, hwnd: hwnd).write(filename)
  end

  self.visible = false unless original_visibility
end

#send_keys(keys) ⇒ Object

Sends keystrokes to the host, including function keys.

Parameters:

  • keys (String) —

    keystokes up to 255 in length



175
176
177
178
 
# File 'lib/te3270/emulators/bluezone.rb', line 175

def send_keys(keys)
  system.SendKey(keys)
  system.WaitReady(@timeout, @max_wait_time)
end

#text ⇒ String

Returns the text of the active screen

Returns:

  • (String) 


185
186
187
 
# File 'lib/te3270/emulators/bluezone.rb', line 185

def text
  system.PSText
end

#visible=(value) ⇒ Object

Sets the currently connected windows visibility.

Parameters:

  • value (Bool)

Raises:



194
195
196
197
198
199
200
 
# File 'lib/te3270/emulators/bluezone.rb', line 194

def visible=(value)
  raise InvalidVisibleStateError, value unless [false, true].include?(value)

  @visible = value
  window = system.Window
  window.Visible = value
end

#wait_for_host(seconds) ⇒ Object

Waits for the host to not send data for a specified number of seconds

Parameters:

  • seconds (Fixnum) —

    the maximum number of seconds to wait



207
208
209
 
# File 'lib/te3270/emulators/bluezone.rb', line 207

def wait_for_host(seconds)
  system.Wait(seconds)
end

#wait_for_string(str, row, column) ⇒ Object

Wait for the string to appear at the specified location

Parameters:

  • str (String) —

    the string to wait for

  • row (Fixnum) —

    the x coordinate of location

  • column (Fixnum) —

    the y coordinate of location



218
219
220
 
# File 'lib/te3270/emulators/bluezone.rb', line 218

def wait_for_string(str, row, column)
  system.WaitForText(str, row, column, @timeout)
end

#wait_until_cursor_at(row, column) ⇒ Object

Waits until the cursor is at the specified location.

Parameters:

  • row (Fixnum) —

    the x coordinate of the location

  • column (Fixnum) —

    the y coordinate of the location



228
229
230
 
# File 'lib/te3270/emulators/bluezone.rb', line 228

def wait_until_cursor_at(row, column)
  system.WaitCursor(@timeout, row, column, 3)
end

#window_state=(state) ⇒ Object

Sets the currently connected windows state.

Parameters:

  • state (Symbol)

Raises:



237
238
239
240
241
242
 
# File 'lib/te3270/emulators/bluezone.rb', line 237

def window_state=(state)
  raise InvalidWindowStateError, state unless WINDOW_STATE.keys.include?(state)

  @window_state = state
  system.WindowState = WINDOW_STATE[state]
end