ib-extensions 1.0

data/lib/ib/gateway/account-infos.rb

@@ -0,0 +1,115 @@
+require 'ib/alerts/base-alert'
+require 'ib/models/account'
+
+module IB
+	class Alert
+		class << self
+			def alert_2101 msg
+				logger.error {msg.message}
+				@status_2101 = msg.dup	
+			end
+
+			def status_2101 account # resets status and raises IB::TransmissionError
+				error account.account + ": " +@status_2101.message, :reader unless @status_2101.nil?
+				@status_2101 = nil  # always returns nil 
+			end
+		end
+	end 
+end #  module
+
+module AccountInfos
+
+=begin
+Queries the tws for Account- and PortfolioValues
+The parameter can either be the account_id, the IB::Account-Object or 
+an Array of account_id and IB::Account-Objects.
+
+raises an IB::TransmissionError if the account-data are not transmitted in time (1 sec)
+
+raises an IB::Error if less then 100 items are recieved-
+=end
+	def get_account_data  *accounts,  watchlists: []
+
+		logger.progname = 'Gateway#get_account_data'
+
+		@account_data_subscription ||=   subscribe_account_updates
+
+		accounts =  clients if accounts.empty?
+		logger.warn{ "No active account present. AccountData are NOT requested" } if accounts.empty?
+		# Account-infos have to be requested sequencially. 
+		# subsequent (parallel) calls kill the former once on the tws-server-side
+		# In addition, there is no need to cancel the subscription of an request, as a new
+		# one overwrites the active one.
+		accounts.each do | ac |
+			account =  ac.is_a?( IB::Account ) ?  ac  : clients.find{|x| x.account == ac } 
+			error( "No Account detected " )  unless account.is_a? IB::Account
+			# don't repeat the query until 170 sec. have passed since the previous update
+			if account.last_updated.nil?  || ( Time.now - account.last_updated ) > 170 # sec   
+				logger.debug{ "#{account.account} :: Requesting AccountData " }
+				account.update_attribute :connected, false  # indicates: AccountUpdate in Progress
+				# reset account and portfolio-values
+				account.portfolio_values =  []
+				account.account_values =  []
+				send_message :RequestAccountData, subscribe: true, account_code: account.account
+				Timeout::timeout(3, IB::TransmissionError, "RequestAccountData failed (#{account.account})") do
+#					 initialize requests sequencially					
+					loop{ sleep 0.1; break if account.connected  }
+				end
+				if watchlists.present?
+					watchlists.each{|w| error "Watchlists must be IB::Symbols--Classes :.#{w.inspect}" unless w.is_a? IB::Symbols }
+					account.organize_portfolio_positions watchlists  
+				end
+				send_message :RequestAccountData, subscribe: false  ## do this only once
+			else
+				logger.info{ "#{account.account} :: Using stored AccountData " }
+			end
+		end
+	end
+
+
+  def all_contracts
+		clients.map(&:contracts).flat_map(&:itself).uniq(&:con_id)
+  end
+
+
+	private
+
+	# The subscription method should called only once per session.
+	# It places subscribers to AccountValue and PortfolioValue Messages, which should remain
+	# active through its session.
+	# 
+	
+	def subscribe_account_updates continously: true
+		tws.subscribe( :AccountValue, :PortfolioValue,:AccountDownloadEnd )  do | msg |
+			account_data( msg.account_name ) do | account |   # enter mutex controlled zone
+				case msg
+				when IB::Messages::Incoming::AccountValue
+					account.account_values << msg.account_value
+					account.update_attribute :last_updated, Time.now
+					logger.debug { "#{account.account} :: #{msg.account_value.to_human }"}
+				when IB::Messages::Incoming::AccountDownloadEnd 
+					if account.account_values.size > 10
+							# simply don't cancel the subscripton if continously is specified
+							# the connected flag is set in any case, indicating that valid data are present
+						send_message :RequestAccountData, subscribe: false, account_code: account.account unless continously
+						account.update_attribute :connected, true   ## flag: Account is completely initialized
+						logger.info { "#{account.account} => Count of AccountValues: #{account.account_values.size}"  }
+					else # unreasonable account_data recieved -  request is still active
+						error  "#{account.account} => Count of AccountValues too small: #{account.account_values.size}" , :reader 
+					end
+				when IB::Messages::Incoming::PortfolioValue
+						account.contracts.update_or_create  msg.contract
+						account.portfolio_values << msg.portfolio_value 
+#						msg.portfolio_value.account = account
+						# link contract -> portfolio value
+#						account.contracts.find{ |x| x.con_id == msg.contract.con_id }
+#								.portfolio_values
+#								.update_or_create( msg.portfolio_value ) { :account } 
+						logger.debug { "#{ account.account } :: #{ msg.contract.to_human }" }
+					end # case
+			end # account_data 
+		end # subscribe
+	end  # def 
+
+
+end # module

data/lib/ib/gateway/order-handling.rb

@@ -0,0 +1,150 @@
+
+module OrderHandling
+=begin
+UpdateOrderDependingObject
+
+Generic method which enables operations on the order-Object,
+which is associated to OrderState-, Execution-, CommissionReport- 
+events fired by the tws.
+The order is identified by local_id and perm_id
+
+Everything is carried out in a mutex-synchonized environment
+=end
+	def update_order_dependent_object order_dependent_object  # :nodoc:
+		  account_data  do  | a | 
+			order = if order_dependent_object.local_id.present?
+								a.locate_order( :local_id => order_dependent_object.local_id)
+							else
+								a.locate_order( :perm_id => order_dependent_object.perm_id)
+							end
+			yield order if order.present?
+		end 
+	end
+	def initialize_order_handling
+		tws.subscribe( :CommissionReport, :ExecutionData, :OrderStatus, :OpenOrder, :OpenOrderEnd, :NextValidId ) do |msg| 
+			logger.progname = 'Gateway#order_handling'
+			case msg
+
+			when IB::Messages::Incoming::CommissionReport
+				# Commission-Reports are not assigned to a order -  
+				logger.info "CommissionReport -------#{msg.exec_id} :...:C: #{msg.commission} :...:P/L: #{msg.realized_pnl}-"
+			when IB::Messages::Incoming::OrderStatus
+
+				# The order-state only links via local_id and perm_id to orders.
+				# There is no reference to a contract or an account
+
+				success= update_order_dependent_object( msg.order_state) do |o|
+					o.order_states.update_or_create msg.order_state, :status 
+				end
+
+				logger.info {  "Order State not assigned-- #{msg.order_state.to_human} ----------" } if success.nil?
+
+			when IB::Messages::Incoming::OpenOrder
+				## todo --> handling of bags --> no con_id
+				account_data(msg.order.account) do | this_account |
+					# first update the contracts
+					# make open order equal to IB::Spreads (include negativ con_id)
+					msg.contract[:con_id] = -msg.contract.combo_legs.map{|y| y.con_id}.sum  if msg.contract.is_a? IB::Bag
+					msg.contract.orders.update_or_create msg.order, :local_id
+					this_account.contracts.first_or_create msg.contract, :con_id
+					# now save the order-record
+					msg.order.contract = msg.contract
+					this_account.orders.update_or_create msg.order, :local_id
+				end
+
+				#     update_ib_order msg  ## aus support 
+			when  IB::Messages::Incoming::OpenOrderEnd
+				#             exitcondition=true
+				logger.debug { "OpenOrderEnd" }
+
+			when IB::Messages::Incoming::ExecutionData
+				# Excution-Data are fired independly from order-states.
+				# The Objects are stored at the associated order
+				success= update_order_dependent_object( msg.execution) do |o|
+					logger.progname = 'Gateway#order_handling::ExecutionData '
+					o.executions << msg.execution 
+					if  msg.execution.cumulative_quantity.to_i == o.total_quantity.abs
+						logger.info{ "#{o.account} --> #{o.contract.symbol}: Execution completed" }
+						o.order_states.first_or_create(  IB::OrderState.new( perm_id: o.perm_id, local_id: o.local_id,
+
+																																status: 'Filled' ),  :status )
+						# update portfoliovalue
+						a = @accounts.detect{|x| x.account == o.account } #  we are in a mutex controlled environment
+						pv =  a.portfolio_values.detect{|y| y.contract.con_id == o.contract.con_id}
+						change =  o.action == :sell ? -o.total_quantity : o.total_quantity
+						if pv.present?
+							pv.update_attribute :position,  pv.position + change
+						else
+							a.portfolio_values << IB::PortfolioValue.new( position: change, contract: o.contract)
+						end
+					else
+						logger.debug{ "#{o.account} --> #{o.contract.symbol}: Execution not completed (#{msg.execution.cumulative_quantity.to_i}/#{o.total_quantity.abs})" }
+					end  # branch
+				end # block
+
+				logger.error {  "Execution-Record not assigned-- #{msg.execution.to_human} ----------" } if success.nil?
+
+			end  # case msg.code
+		end # do
+	end # def subscribe
+
+# Resets the order-array for each account first.
+# Requests all open (eg. pending)  orders from the tws 
+#
+# Waits until the OpenOrderEnd-Message is recieved
+
+
+	def request_open_orders
+
+		exit_condition = false
+		subscription = tws.subscribe(  :OpenOrderEnd ){ exit_condition = true }
+		account_data{| account | account.orders=[] }
+		send_message :RequestAllOpenOrders
+		Timeout::timeout(1, IB::TransmissionError,"OpenOrders not received" ) do
+			loop{  sleep 0.1; break if exit_condition  }
+		end
+		tws.unsubscribe subscription
+	end
+
+	alias update_orders request_open_orders 
+
+
+
+
+end # module
+
+
+
+
+
+module IB
+
+	class Order
+		def auto_adjust
+			# lambda to perform the calculation
+		adjust_price = ->(a,b) do
+			a=BigDecimal(a,5) 
+			b=BigDecimal(b,5) 
+			_,o =a.divmod(b)
+			a-o 
+		end
+		# adjust_price[2.6896, 0.1].to_f     => 2.6 
+		# adjust_price[2.0896, 0.05].to_f    => 2.05 
+		# adjust_price[2.0896, 0.002].to_f   => 2.088 
+
+
+		error "No Contract provided to Auto adjust " unless contract.is_a? IB::Contract
+		unless contract.is_a? IB::Bag
+			# ensure that contract_details are present
+			
+			contract.verify do |the_contract | 
+				the_details =  the_contract.contract_detail.presence || the_contract.verify.first.contract_detail
+				# there are two attributes to consider: limit_price and aux_price
+				# limit_price +  aux_price may be nil or an empty string. Then ".to_f.zero?" becomes true 
+				self.limit_price= adjust_price.call(limit_price.to_f, the_details.min_tick) unless limit_price.to_f.zero?
+				self.aux_price= adjust_price.call(aux_price.to_f, the_details.min_tick) unless aux_price.to_f.zero?
+			end
+		end
+	end
+end  # class Order
+end  # module

data/lib/ib/market-price.rb

@@ -0,0 +1,134 @@
+
+module CoreExtensions
+  module Array
+    module DuplicatesCounter
+      def count_duplicates
+        self.each_with_object(Hash.new(0)) { |element, counter| counter[element] += 1 }.sort_by{|k,v| -v}.to_h
+      end
+    end
+  end
+end
+
+Array.include CoreExtensions::Array::DuplicatesCounter
+module IB
+
+
+	
+ class Contract
+# Ask for the Market-Price 
+# 
+# For valid contracts, either bid/ask or last_price and close_price are transmitted.
+# 
+# If last_price is received, its returned. 
+# If not, midpoint (bid+ask/2) is used. Else the closing price will be returned.
+# 
+# Any  value (even 0.0) which is stored in IB::Contract.misc indicates that the contract is 
+# accepted by `place_order`.
+# 
+# The result can be customized by a provided block.
+# 
+# 	IB::Symbols::Stocks.sie.market_price{ |x| x }
+# 	-> {"bid"=>0.10142e3, "ask"=>0.10144e3, "last"=>0.10142e3, "close"=>0.10172e3}
+#  
+# 
+#  Raw-data are stored in the _bars_-attribute of IB::Contract 
+#  (volatile, ie. data are not preserved when the Object is copied)
+#  
+#Example:  IB::Stock.new(symbol: :ge).market_price
+# returns the current market-price
+#
+#Example:  IB::Stock.new(symbol: :ge).market_price(thread: true).join 
+# assigns IB::Symbols.sie.misc with the value of the :last (or delayed_last) TickPrice-Message
+# and returns this value, too
+#
+#Raises IB::Error 
+#  if no Marketdata Subscription is present and delayed: false is specified
+#  
+#
+#  Solutions: Catch the Error and retry with delayed: true
+#
+#             if that fails use alternative exchanges  (look to Contract.valid_exchanges)
+#
+			def market_price delayed:  true, thread: false
+
+				tws=  Connection.current 		 # get the initialized ib-ruby instance
+				the_id , the_price =  nil, nil
+				tickdata =  Hash.new
+				# define requested tick-attributes
+				last, close, bid, ask	 = 	[ [ :delayed_last , :last_price ] , [:delayed_close , :close_price ],
+																[  :delayed_bid , :bid_price ], [  :delayed_ask , :ask_price ]] 
+				request_data_type =  delayed ? :frozen_delayed :  :frozen
+
+				tws.send_message :RequestMarketDataType, :market_data_type =>  IB::MARKET_DATA_TYPES.rassoc( request_data_type).first
+
+				#keep the method-call running until the request finished
+				#and cancel subscriptions to the message handler
+				# method returns the (running) thread
+				th = Thread.new do
+					finalize, raise_delay_alert = false, false
+					s_id = tws.subscribe(:TickSnapshotEnd){|x| finalize = true if x.ticker_id == the_id }
+
+				e_id = tws.subscribe(:Alert){|x| raise_delay_alert = true if x.code == 354 && x.error_id == the_id } 
+					# TWS Error 354: Requested market data is not subscribed.
+#					r_id = tws.subscribe(:TickRequestParameters) {|x| } # raise_snapshot_alert =  true  if x.snapshot_permissions.to_i.zero?  && x.ticker_id == the_id  }
+								 
+					# subscribe to TickPrices
+					sub_id = tws.subscribe(:TickPrice ) do |msg| #, :TickSize,  :TickGeneric, :TickOption) do |msg|
+						[last,close,bid,ask].each do |x| 
+							tickdata[x] = msg.the_data[:price] if x.include?( IB::TICK_TYPES[ msg.the_data[:tick_type]]) 
+							#  fast exit condition
+							finalize = true if tickdata.size ==4  || ( tickdata[bid].present? && tickdata[ask].present? )  
+						end if  msg.ticker_id == the_id 
+					end
+					# initialize »the_id« that is used to identify the received tick messages
+					# by firing the market data request
+					the_id = tws.send_message :RequestMarketData,  contract: self , snapshot: true 
+
+					# todo implement config-feature to set timeout in configuration   (DRY-Feature)
+					# Alternative zu Timeout
+					# Thread.new do 
+					#     i=0; loop{ i+=1; sleep 0.1; break if finalize || i > 1000 }
+
+					i=0; 
+					loop{ i+=1; break if i > 1000 || finalize || raise_delay_alert; sleep 0.05 } 
+					tws.unsubscribe sub_id, s_id, e_id 
+					# reduce :close_price delayed_close  to close a.s.o 
+					if raise_delay_alert && !delayed
+						error "No Marketdata Subscription, use delayed data <-- #{to_human}" 
+			#		elsif raise_snapshot_alert
+			#			error "No Snapshot Permissions, try alternative exchange  <-- #{to_human}"
+					elsif i <= 1000
+						tz = -> (z){ z.map{|y| y.to_s.split('_')}.flatten.count_duplicates.max_by{|k,v| v}.first.to_sym}
+						data =  tickdata.map{|x,y| [tz[x],y]}.to_h
+						valid_data = ->(d){ !(d.to_i.zero? || d.to_i == -1) }
+						self.bars << data											#  store raw data in bars
+						the_price = if block_given? 
+													yield data 
+													# yields {:bid=>0.10142e3, :ask=>0.10144e3, :last=>0.10142e3, :close=>0.10172e3}
+												else # behavior if no block is provided
+													if valid_data[data[:last]]
+														data[:last] 
+													elsif valid_data[data[:bid]]
+														(data[:bid]+data[:ask])/2
+													elsif data[:close].present? 
+														data[:close]
+													else
+														nil
+													end
+												end
+						self.misc =  the_price if thread  # store internally if in thread modus
+					else   #  i > 1000
+						tws.logger.info{ "#{to_human} --> No Marketdata received " }
+					end
+
+				end
+				if thread
+					th		# return thread
+				else
+					th.join
+					the_price	# return 
+				end
+			end #
+
+ end
+end

data/lib/ib/models/account.rb

@@ -0,0 +1,329 @@
+module IB
+
+	class Account 
+
+
+		def account_data_scan search_key, search_currency=nil
+			if account_values.is_a? Array
+				if search_currency.present? 
+					account_values.find_all{|x| x.key.match( search_key )  && x.currency == search_currency.upcase }
+				else
+					account_values.find_all{|x| x.key.match( search_key ) }
+				end
+
+			else  # not tested!!
+				if search_currency.present?
+					account_values.where( ['key like %', search_key] ).where( currency: search_currency )
+				else  # any currency
+					account_values.where( ['key like %', search_key] )
+				end
+			end
+		end
+
+
+
+=begin rdoc
+given any key of local_id, perm_id or order_ref
+and an optional status, which can be a string or a 
+regexp ( status: /mitted/ matches Submitted and Presubmitted) 
+the last associated Orderrecord is returned.
+
+Thus if several Orders are placed with the same order_ref, the active one is returned
+
+(If multible keys are specified, local_id preceeds perm_id)
+
+=end
+		def locate_order local_id: nil, perm_id: nil, order_ref: nil, status: /ubmitted/, con_id: nil
+			search_option= [ local_id.present? ? [:local_id , local_id] : nil ,
+										perm_id.present? ? [:perm_id, perm_id] : nil,
+										order_ref.present? ? [:order_ref , order_ref ] : nil ].compact.first
+			matched_items = if search_option.nil? 
+												orders 
+											else 
+												orders.find_all{|x| x[search_option.first].to_i == search_option.last.to_i }
+											end
+			matched_items = matched_items.find_all{|x| x.contract.con_id == con_id } if con_id.present?
+
+			if status.present?
+				status = Regexp.new(status) unless status.is_a? Regexp
+				matched_items.detect{|x| x.order_state.status =~ status }
+			else
+				matched_items.last  # return the last item
+			end
+		end
+
+
+=begin rdoc 
+requires an IB::Order as parameter. 
+
+If attached, the associated IB::Contract is used to specify the tws-command
+
+The associated Contract overtakes  the specified (as parameter)
+
+auto_adjust: Limit- and Aux-Prices are adjusted to Min-Tick
+
+convert_size: The action-attribute (:buy  :sell) is associated according the content of :total_quantity.
+
+
+The parameter «order» is modified! 
+
+It can be used to modify and eventually cancel 
+
+The method raises an  IB::TransmissionError if the transmitted order ist not acknowledged by the tws after
+one second.
+
+Example
+
+   j36 =  IB::Stock.new symbol: 'J36', exchange: 'SGX'
+   order =  IB::Limit.order size: 100, price: 65.5
+   g =  IB::Gateway.current.clients.last
+
+	 g.preview contract: j36, order: order
+      => {:init_margin=>0.10864874e6, 
+			    :maint_margin=>0.9704137e5, 
+					:equity_with_loan=>0.97877973e6, 
+					:commission=>0.524e1, 
+					:commission_currency=>"USD", 
+					:warning=>""}
+
+   the_local_id = g.place order: order
+		  => 67						# returns local_id
+	 order.contract			# updated contract-record 
+      => #<IB::Contract:0x00000000013c94b0 @attributes={:con_id=>95346693, 
+			                                                   :exchange=>"SGX", 
+																												 :right=>"", 
+																												 :include_expired=>false}> 
+
+		order.limit_price = 65   # set new price
+	  g.modify order: order    # and transmit 
+		  => 67 # returns local_id
+
+		g.locate_order( local_id: the_local_id  )
+		  => returns the assigned order-record for inspection
+
+		g.cancel order: order
+				# logger output: 05:17:11 Cancelling 65 New #250/ from 3000/DU167349>
+	 
+=end
+
+		def place_order  order:, contract: nil, auto_adjust: true, convert_size:  false
+			# adjust the orderprice to  min-tick
+			logger.progname =  'Account#PlaceOrder' 
+			result = ->(l){ orders.detect{|x| x.local_id == l  && x.submitted? } }
+			#·IB::Symbols are always qualified. They carry a description-field
+			qualified_contract = ->(c) { c.description.present? || (c.con_id.present?  &&  !c.con_id.to_i.zero?) || 
+																c.con_id <0  && c.sec_type == :bag  }
+			order.contract = contract.verify.first if contract.present? && order.contract.nil? 
+
+			## sending of plain vanilla IB::Bags will fail using account.place, unless a (negative) con-id is provided!
+#			error "place order: ContractVerification failed. No con_id assigned"  unless qualified_contract[order.contract]
+			ib = IB::Connection.current
+			wrong_order = nil
+			the_local_id =  nil
+
+			### Handle Error messages
+			### Default action:  display error in log and return nil
+			sa = ib.subscribe( :Alert ) do | msg |
+				if msg.error_id == the_local_id
+				 if [ 110, #  The price does not conform to the minimum price variation for this contract
+					   388,  # Order size x is smaller than the minimum required size of yy.
+					  ].include? msg.code
+					 wrong_order =  msg.error_id.to_i  
+					 ib.logger.error msg.message
+				 end
+				end
+			end
+			order.account =  account  # assign the account_id to the account-field of IB::Order
+			if qualified_contract[order.contract]
+				self.orders.update_or_create order, :order_ref
+				order.auto_adjust # if auto_adjust  /defined in lib/order_handling
+			end
+			if convert_size 
+			 	order.action = order.total_quantity.to_i > 0  ? 	:buy : :sell 
+				order.total_quantity  = order.total_quantity.to_i.abs
+			end
+				# apply non_guarenteed and other stuff bound to the contract to order.
+			order.attributes.merge! order.contract.order_requirements unless order.contract.order_requirements.blank?
+				#  con_id and exchange fully qualify a contract, no need to transmit other data
+			the_contract = order.contract.con_id >0 ? Contract.new( con_id: order.contract.con_id, exchange: order.contract.exchange) : nil 
+			the_local_id = order.place the_contract # return the local_id
+			Timeout::timeout(1, IB::TransmissionError,"TimeOut ::Transmitted Order was not acknowledged") do 
+				loop{ sleep(0.001); break if locate_order( local_id: the_local_id, status: nil ).present? }
+			end
+
+			ib.unsubscribe sa
+
+			if wrong_order.nil?
+				the_local_id  # return_value
+			else
+				nil
+			end
+		end # place 
+
+		# shortcut to enable
+		#  account.place order: {} , contract: {} 
+		#  account.preview order: {} , contract: {}
+		#  account.modify order: {}
+		alias place place_order
+
+=begin #rdoc
+Account#ModifyOrder operates in two modi:
+
+First: The order is specified  via local_id, perm_id or order_ref.
+	It is checked, whether the order is still modificable.
+	Then the Order ist provided through  the block. Any modification is done there. 
+	Important: The Block has to return the modified IB::Order
+
+Second: The order can be provided as parameter as well. This will be used
+without further checking. The block is now optional. 
+	Important: The OrderRecord must provide a valid Contract.
+
+The simple version does not adjust the given prices to tick-limits.
+This has to be done manualy in the provided block
+=end
+
+		def modify_order  local_id: nil, order_ref: nil, order:nil
+
+			result = ->(l){ orders.detect{|x| x.local_id == l  && x.submitted? } }
+			logger.tap{ |l| l.progname = "Account #{account}#modify_order"}
+			order ||= locate_order( local_id: local_id, 
+														 status: /ubmitted/ ,
+														 order_ref: order_ref ) 
+			if order.is_a? IB::Order
+				order.modify
+			else
+				error "No suitable IB::Order provided/detected. Instead: #{order.inspect}" 
+			end  
+		end
+
+		alias modify modify_order
+
+# Preview
+		#
+		# Submits a "WhatIf" Order
+		#
+		# Returns the order_state.forcast 
+		#
+		# The order received from the TWS is kept in account.orders
+		#
+		# Raises IB::TransmissionError if the Order could not be placed properly
+		#
+	def preview order:, contract: nil, **args_which_are_ignored
+		# to_do:  use a copy of order instead of temporary setting order.what_if
+		result = ->(l){ orders.detect{|x| x.local_id == l  && x.submitted? } }
+		order.what_if = true
+		the_local_id = place_order order: order, contract: contract
+		i=0; loop{ i= i+1;  break if result[the_local_id] || i > 1000; sleep 0.01 }
+		raise IB::TransmissionError,"(Preview-)Order is not transmitted properly" if i >=1000
+		order.what_if = false # reset what_if flag
+		order.local_id = nil  # reset local_id to enable reusage of the order-object for placing
+		result[the_local_id].order_state.forcast  #  return_value
+	end 
+
+# closes the contract by submitting an appropiate order
+	# the action- and total_amount attributes of the assigned order are overwritten.
+	#
+	# if a ratio-value (0 ..1) is specified in _order.total_quantity_ only a fraction of the position is closed. 
+	# Other values are silently ignored
+	#
+	# if _reverse_ is specified, the opposide position is established. 
+	# Any value in total_quantity is overwritten 
+	#
+	# returns the order transmitted
+	#
+	# raises an IB::Error if no PortfolioValues have been loaded to the IB::Acoount
+	def close order:, contract: nil, reverse: false,  **args_which_are_ignored
+		error "must only be called after initializing portfolio_values "  if portfolio_values.blank?
+		contract_size = ->(c) do			# note: portfolio_value.position is either positiv or negativ
+			if c.con_id <0 # Spread
+				p = portfolio_values.detect{|p| p.contract.con_id ==c.legs.first.con_id} &.position.to_i
+				p/ c.combo_legs.first.weight  unless p.to_i.zero?
+			else
+				portfolio_values.detect{|x| x.contract.con_id == c.con_id} &.position.to_i   # nil.to_i -->0
+			end
+		end
+
+		contract &.verify{|c| order.contract = c}   # if contract is specified: don't touch the parameter, get a new object . 
+		error "Cannot transmit the order – No Contract given " unless order.contract.is_a?(IB::Contract)
+	
+		the_quantity = if reverse
+														 -contract_size[order.contract] * 2 
+													 elsif order.total_quantity.abs < 1 && !order.total_quantity.zero? 
+														-contract_size[order.contract] *  order.total_quantity.abs 
+													 else
+														 -contract_size[order.contract] 
+													 end
+		if the_quantity.zero?
+			logger.info{ "Cannot close #{order.contract.to_human} - no position detected"}
+		else
+			order.total_quantity = the_quantity
+			order.action =  nil
+			order.local_id =  nil  # in any case, close is a new order
+			logger.info { "Order modified to close, reduce or revese position: #{order.to_human}" }
+			place order: order, convert_size: true
+		end
+	end
+
+# just a wrapper to the Gateway-cancel-order method
+	def cancel order: 
+		Gateway.current.cancel_order order 
+	end
+
+	#returns an hash where portfolio_positions are grouped into Watchlists.
+	#
+	# Watchlist => [  contract => [ portfoliopositon] , ... ] ]
+	#
+		def organize_portfolio_positions   the_watchlists
+		  the_watchlists = [ the_watchlists ] unless the_watchlists.is_a?(Array)
+			self.focuses = portfolio_values.map do | pw |
+											z=	the_watchlists.map do | w |		
+												ref_con_id = pw.contract.con_id
+												watchlist_contract = w.find do |c| 
+													c.is_a?(IB::Bag) ? c.combo_legs.map(&:con_id).include?(ref_con_id) : c.con_id == ref_con_id 
+												end rescue nil	
+												watchlist_contract.present? ? [w,watchlist_contract] : nil
+											end.compact
+
+											z.empty? ? [ IB::Symbols::Unspecified, pw.contract, pw ] : z.first << pw
+			end.group_by{|a,_,_| a }.map{|x,y|[x, y.map{|_,d,e|[d,e]}.group_by{|e,_| e}.map{|f,z| [f, z.map(&:last)]} ] }.to_h
+			# group:by --> [a,b,c] .group_by {|_g,_| g} --->{ a => [a,b,c] }
+			# group_by+map --> removes "a" from the resulting array
+		end
+
+
+		def locate_contract con_id
+			contracts.detect{|x| x.con_id.to_i == con_id.to_i }
+		end
+
+		## returns the contract definition of an complex portfolio-position detected in the account
+		def complex_position con_id
+			con_id = con_id.con_id	if con_id.is_a?(IB::Contract)
+			focuses.map{|x,y| y.detect{|x,y| x.con_id.to_i==  con_id.to_i} }.compact.flatten.first
+		end
+	end # class
+		##
+		# in the console   (call gateway with watchlist: [:Spreads, :BuyAndHold])
+#head :001 > .active_accounts.first.focuses.to_a.to_human
+#Unspecified
+#<Stock: BLUE EUR SBF>
+#<PortfolioValue: DU167348 Pos=720 @ 15.88;Value=11433.24;PNL=-4870.05 unrealized;<Stock: BLUE EUR SBF>
+#<Stock: CSCO USD NASDAQ>
+#<PortfolioValue: DU167348 Pos=44 @ 44.4;Value=1953.6;PNL=1009.8 unrealized;<Stock: CSCO USD NASDAQ>
+#<Stock: DBB USD ARCA>
+#<PortfolioValue: DU167348 Pos=-1 @ 16.575;Value=-16.58;PNL=1.05 unrealized;<Stock: DBB USD ARCA>
+#<Stock: NEU USD NYSE>
+#<PortfolioValue: DU167348 Pos=1 @ 375.617;Value=375.62;PNL=98.63 unrealized;<Stock: NEU USD NYSE>
+#<Stock: WFC USD NYSE>
+#<PortfolioValue: DU167348 Pos=100 @ 51.25;Value=5125.0;PNL=-171.0 unrealized;<Stock: WFC USD NYSE>
+#BuyAndHold
+#<Stock: CIEN USD NYSE>
+#<PortfolioValue: DU167348 Pos=812 @ 29.637;Value=24065.57;PNL=4841.47 unrealized;<Stock: CIEN USD NYSE>
+#<Stock: J36 USD SGX>
+#<PortfolioValue: DU167348 Pos=100 @ 56.245;Value=5624.5;PNL=-830.66 unrealized;<Stock: J36 USD SGX>
+#Spreads
+#<Strangle Estx50(3200.0,3000.0)[Dec 2018]>
+#<PortfolioValue: DU167348 Pos=-3 @ 168.933;Value=-5067.99;PNL=603.51 unrealized;<Option: ESTX50 20181221 call 3000.0  EUR>
+#<PortfolioValue: DU167348 Pos=-3 @ 142.574;Value=-4277.22;PNL=-867.72 unrealized;<Option: ESTX50 20181221 put 3200.0  EUR>
+# => nil 
+#		# 
+end ## module