nwrfc-aphid 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ed5e67139740dc21e73cad3b3d3a5366851fa436394daac1b17b660bcdc20e01
+  data.tar.gz: e4d8d6aef9fac386235529d6d2503dd0c0a4f7bdf3b9272fa3edb8058c2a1dc8
+SHA512:
+  metadata.gz: 689b4474fd486532d19efb12e6087a23befb2d0ca3f2b95bd9cb62f605a6e79d15875dd857e3590d910fbdb805f3f33b32ce639db6ae559b4c6fc75b80e85d7a
+  data.tar.gz: c11fdfd60fec5ce470102196e9ea445147e85a57ca6cfd072305838d45edd74eabde57a29482de8766c21c7438bdaf1b8f0755dd681340bba1de7ffad078c078

data/README.rdoc

@@ -0,0 +1,189 @@
+= NWRFC - Wrapper for SAP Netweaver RFC SDK using Ruby-FFI
+
+This library provides a wrapper around the sapnwrfc shared library provided in the SAP Netweaver RFC SDK using Ruby-FFI.
+
+The NW RFC SDK allows you to call remote-enabled function modules on an ABAP server (referred to as RFC,
+which stands for "Remote Function Call").
+
+To use this library, you must have the nwrfcsdk (libsapnwrfc.so / sapnwrfc.dll) library
+and related libraries somewhere in your path.
+
+I am developing the library using the 7.20 patch level 2 version of the NW RFC SDK. I have used 7.11, but found for instance
+that it suffers from the bug described in note 1058327, where RfcGetStringLength() returns the incorrect length
+of the string if it is longer than 255 characters (supposed to have been fixed in 7.10 patch 2).
+
+== Issues
+
+Ruby-FFI does not seem to be able to take string encoding into consideration, so for example, calling RfcGetVersion()
+is problematic, because the returned string pointer has (like all NW RFC SDK functions) UTF-16LE encoding,
+and FFI does not seem to be able to work with this. So far this is not too problematic, but let's see.
+
+== Obtaining the Netweaver RFC shared library
+The Netweaver RFC SDK libraries are available from SAP. You cannot, unfortunately, obtain these as a public user; you need to have access via a customer account to download them
+from SAP Service Marketplace (http://service.sap.com)
+
+Alternatively, you can download and install one of the Netweaver Trial Editions from SDN (requires signup): http://www.sdn.sap.com/irj/scn/downloads
+
+After installation, the files are available in /usr/sap/<sysid>/exe
+
+== Usage
+
+Connecting to the SAP system:
+
+  require 'rubygems'
+
+  gem 'nwrfc-aphid'
+  require 'nwrfc'
+  include NWRFC
+
+  c = Connection.new {"user" => "martin", "passwd" => "secret",
+    "client" => "100", "ashost" => "ajax.domain.com", "sysnr" => "00"}
+
+Calling a function:
+
+  f = c.get_function("STFC_STRUCTURE") #Obtain description of a function module
+  f.with_function_call do |fc|
+    fc.invoke
+  end
+
+Or close the function call explicitly. Closing it also releases all nested table and structure data:
+
+  fc = f.get_function_call
+  begin
+    fc.invoke
+  ensure
+    fc.close
+  end
+
+Function descriptions fetched through a connection are cached and borrowed from the SDK, so +f.close+
+never destroys them. A locally defined function owns its description and should be closed after all calls
+created from it have been closed:
+
+  local_function = Function.new("MY_FUNCTION")
+  begin
+    # add parameters and use local_function
+  ensure
+    local_function.close
+  end
+
+Transactions retain their handle when submit or confirm fails so +commit+ can retry the appropriate step.
+Close an abandoned transaction explicitly; +close+ and +destroy+ are idempotent:
+
+  transaction = c.start_transaction
+  begin
+    fc.invoke(transaction)
+    transaction.commit
+  ensure
+    transaction.close
+  end
+
+Connections and servers also have idempotent +close+ methods. Function calls received by server callbacks,
+and table or structure handles obtained from a function call, are borrowed and are never destroyed directly.
+
+Setting and getting parameters and fields:
+
+  import_struc = fc[:IMPORTSTRUC]
+  import_struc[:RFCCHAR1] = 'a'
+
+Close function calls before their connection:
+
+  fc.close
+  c.close
+
+== Installation
+
+In order to install and run nwrfc-aphid, you need to install {http://github.com/ffi/ffi Ruby-FFI} which may require compilation.
+On Windows, you should be running the one-click {http://rubyinstaller.org/downloads/ Ruby Installer} and install the
+{http://github.com/oneclick/rubyinstaller/wiki/Development-Kit DevKit} which is really the easiest way to compile
+it on Windows.
+
+Then install the nwrfc-aphid gem:
+
+In a Bundler Gemfile:
+
+    gem 'nwrfc-aphid', require: 'nwrfc'
+
+On Linux:
+
+    sudo gem install nwrfc-aphid
+
+On Windows
+
+    gem install nwrfc-aphid
+
+== Documentation
+
+Documentation is installed locally when you install the gem, but you can install it with `rdoc` or `yard` or whatever
+if you have cloned the repository from GitHub.
+
+== Running the tests
+The test are located in the tests/ directory. The file `login_params.yaml` contains parameters that you will need
+to customize to log on to your local system that you are testing with. The YAML file contains parameters for multiple
+systems, so if you want to switch to a different system, change the following line in `test_nwrfc.rb`:
+
+  $login_params = YAML.load_file(File.dirname(__FILE__) + "/login_params.yaml")["system2"]
+
+so that ["system2"] at the end points to whatever label you gave it in the YAML file, then
+
+  rake test
+
+== Release Notes
+
+=== Available in 0.1.0 (nwrfc-aphid)
+
+* Maintained fork packaged as nwrfc-aphid
+* Ruby 4 and Bundler 4 dependency compatibility
+
+=== Available in 0.0.9
+
+* Support for qRFC/tRFC
+
+=== Available in 0.0.8
+
+* BigDecimal support added for BCD values (BCD is also returned as BigDecimal to cater for very big numbers like timestamps)
+* Support for String::encode in Ruby 1.9 and above instead of iconv (thanks Meatballs1)
+
+=== What's new in 0.0.7
+
+* Add support for JRuby by extending FFI::StructLayout::CharArrayProxy
+* Fix #7 (error when reading timestamp value / BCD field)
+
+=== What's new in 0.0.6
+
+* Add :blocking => true in attach_function to allow other threads to continue running (thanks Meatballs1[https://github.com/Meatballs1])
+
+=== What's new in 0.0.5
+
+* Bug fix for Table#each
+
+=== What's new in 0.0.4
+
+* Add parameter activation/deactivation functionality
+* Fix/add metadata retrieval for DataContainer
+
+=== What's new in 0.0.3
+
+* Basic RFC server functionality
+
+=== What's new in 0.0.2
+
+* More comprehensive type support
+* More table operations
+
+=== What's new in 0.0.1
+
+* Fix loading sapnw library
+* Fix UTF-8 conversion for Windows
+* Enhanced type support
+
+=== What's new in 0.0.0
+
+* Able to call functions
+* Most types work,
+* Getting list of fields from a structure causes a SEGFAULT
+
+== Contributing
+
+* Improvements to the source code are welcome
+* Indicate on which platforms you have tested the gem
+* Suggestions for improving the API / Hints for idiomatic Ruby

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/test*.rb']
+end

data/lib/nwrfc/datacontainer.rb

@@ -0,0 +1,346 @@
+require 'bigdecimal'
+
+module NWRFC
+
+  # Representation of a data container (function, structure or table)
+  # Implements common functions for data containers, such as setting and getting values, tables, structures and
+  # takes care of type conversion and calling correct SDK functions to set or get values
+  #
+  # == Type Conversions
+  # To ensure that data is passed correctly to the NW RFC SDK functions, certain conversions are applied to values
+  # passed, depending on the type of the field. ABAP supports a number of elementary types, which are listed in the
+  #
+  # DECFLOAT16 and DECFLOAT34 types are not yet supported.
+  #
+  # === Inbound
+  # For character and string
+  class DataContainer
+    attr_reader :handle, :desc
+
+    def initialize(handle)
+      @error = NWRFCLib::RFCError.new
+      @handle = handle
+      @desc = NWRFCLib.describe_type(@handle, @error)
+      @member_metadata = {} #Cache of metadata for members
+      NWRFC.check_error(@error)
+    end
+
+    #--
+    # VALUE RETRIEVAL
+    #++
+
+    # Get value from a data container (structure, function instance or table)
+    def [](element)
+      member = element.to_s.upcase
+      metadata = member_metadata(element)
+      case metadata[:type]
+
+        when :RFCTYPE_CHAR
+          # TODO: Try use :string parameter in get_chars
+          return read_chars(metadata)
+
+        when :RFCTYPE_DATE
+          res = read_chars(metadata)
+          if res == "00000000" # empty date in SAP, Date.parse will throw an error on this
+            return nil
+          else
+            return Date.parse(res)
+          end
+          #return Date.new(date[0..3].to_i, date[4..5].to_i, date[6..7].to_i)
+
+        when :RFCTYPE_BCD
+          size = metadata[:nucLength] + (metadata[:decimals] || 0)
+          size += 10 # Temporary fix for issue https://github.com/mydoghasworms/nwrfc/issues/7
+          buf = FFI::MemoryPointer.new(:uchar, size*2)
+          rc = NWRFCLib.get_chars(@handle, metadata[:name].cU, buf, size, @error.to_ptr)
+          NWRFC.check_error(@error) if rc > 0
+          str = buf.get_bytes(0, size*2).uC.strip
+          return str.empty? ? BigDecimal(0) : BigDecimal(str)
+
+        when :RFCTYPE_TIME
+          # TODO: See whether we can optimize this
+          timec = read_chars(metadata)
+          return Time.parse("#{timec[0..1]}:#{timec[2..3]}:#{timec[4..5]}")
+
+        when :RFCTYPE_BYTE
+          size = metadata[:ucLength]
+          buf = FFI::MemoryPointer.new(:uchar, size)
+          rc = NWRFCLib.get_bytes(@handle, metadata[:name].cU, buf, size, @error.to_ptr)
+          NWRFC.check_error(@error) if rc > 0
+          return buf.get_bytes(0, size)
+
+        when :RFCTYPE_TABLE
+          # TODO Cache instances of table members and return those where available
+          new_handle = NWRFCLib::RFCDataContainer.new
+          rc = NWRFCLib.get_table(@handle, member.cU, new_handle.to_ptr, @error.to_ptr)
+          NWRFC.check_error(@error) if rc > 0
+          # CAVEAT: Other calls using the handle require "handle" field
+          # of the RFC_DATA_CONTAINER struct for some reason.
+          new_handle = new_handle[:handle]
+          return Table.new(new_handle)
+
+        when :RFCTYPE_NUM
+          return read_chars(metadata)
+
+        when :RFCTYPE_FLOAT
+          double = FFI::MemoryPointer.new :double
+          rc = NWRFCLib.get_float(@handle, member.cU, double, @error)
+          NWRFC.check_error(@error) if rc > 0
+          return double.get_double(0)
+
+        when :RFCTYPE_INT
+          int = FFI::MemoryPointer.new :int
+          rc = NWRFCLib.get_int(@handle, member.cU, int, @error)
+          NWRFC.check_error(@error) if rc > 0
+          return int.get_int(0)
+
+        when :RFCTYPE_INT2
+          short = FFI::MemoryPointer.new :short
+          rc = NWRFCLib.get_int2(@handle, member.cU, short, @error)
+          NWRFC.check_error(@error) if rc > 0
+          return short.get_short(0)
+
+        when :RFCTYPE_INT1
+          int1 = FFI::MemoryPointer.new :uint8
+          rc = NWRFCLib.get_int1(@handle, member.cU, int1, @error)
+          NWRFC.check_error(@error) if rc > 0
+          return int1.get_uint8(0)
+
+        when :RFCTYPE_NULL
+          raise "Unsupported type RFCTYPE_NULL" #You should never run into this
+
+        when :RFCTYPE_STRUCTURE
+          # TODO Cache instances of structure members and return those where available
+          new_handle = NWRFCLib::RFCDataContainer.new
+          rc = NWRFCLib.get_structure(@handle, member.cU, new_handle.to_ptr, @error.to_ptr)
+          NWRFC.check_error(@error) if rc > 0
+          new_handle = new_handle[:handle]
+          return Structure.new(new_handle)
+
+        when :RFCTYPE_DECF16
+          double = FFI::MemoryPointer.new :double
+          rc = NWRFCLib.get_dec_f16(@handle, member.cU, double, @error)
+          NWRFC.check_error(@error) if rc > 0
+          return double.get_double(0)
+
+        when :RFCTYPE_DECF34
+          double = FFI::MemoryPointer.new :double, 2
+          rc = NWRFCLib.get_dec_f34(@handle, member.cU, double, @error)
+          NWRFC.check_error(@error) if rc > 0
+          return double.get_double(0)
+
+        when :RFCTYPE_XMLDATA
+          raise "Unsupported type RFCTYPE_XMLDATA (no longer used)" #You should never run into this
+
+        when :RFCTYPE_STRING
+          return read_string(metadata)
+
+        when :RFCTYPE_XSTRING
+          size = FFI::MemoryPointer.new(:uint)
+          rc = NWRFCLib.get_string_length(@handle, metadata[:name].cU, size, @error)
+          NWRFC.check_error(@error) if rc > 0
+          buf_len = size.read_uint
+          sbuf = FFI::MemoryPointer.new :uchar, buf_len
+          rc = NWRFCLib.get_x_string(@handle, metadata[:name].cU, sbuf, buf_len, size, @error)
+          NWRFC.check_error(@error) if rc > 0
+          return sbuf.read_string(sbuf.size)
+
+        else
+          raise "Illegal member type #{metadata[:type]}"
+      end
+
+    end
+
+    #--
+    # VALUE STORAGE
+    #++
+
+    # Set value on a data container (structure, function instance or table)
+    def []=(element, value)
+      member = element.to_s.upcase
+      metadata = member_metadata(element)
+      case metadata[:type]
+
+        when :RFCTYPE_CHAR
+          value = value.to_s
+          NWRFCLib.set_chars(@handle, member.cU, value.cU, value.length, @error.to_ptr)
+
+        when :RFCTYPE_DATE
+          value = value_to_date(value)
+          NWRFCLib.set_date(@handle, member.cU, value.cU, @error.to_ptr)
+
+        when :RFCTYPE_BCD
+          if value.class == BigDecimal
+            stval = value.to_s('F')
+          else
+            stval = value.to_s
+          end
+          m = FFI::MemoryPointer.from_string stval.cU
+          NWRFCLib.set_string(@handle, member.cU, m, stval.size, @error)
+
+        when :RFCTYPE_TIME
+          value = value_to_time(value)
+          NWRFCLib.set_time(@handle, member.cU, value.cU, @error.to_ptr)
+
+        when :RFCTYPE_BYTE
+          m = FFI::MemoryPointer.from_string value.to_s
+          NWRFCLib.set_bytes(@handle, member.cU, m, value.to_s.size, @error.to_ptr)
+
+        when :RFCTYPE_TABLE
+          raise "Value must be of type table" unless value.class == NWRFC::Table
+          NWRFCLib.set_table(@handle, member.cU, value.handle, @error)
+
+        when :RFCTYPE_NUM
+          value = value.to_s
+          NWRFCLib.set_num(@handle, member.cU, value.cU, value.length, @error.to_ptr)
+
+        when :RFCTYPE_FLOAT
+          NWRFCLib.set_float(@handle, member.cU, value.to_f, @error.to_ptr)
+
+        when :RFCTYPE_INT
+          NWRFCLib.set_int(@handle, member.cU, value.to_i, @error.to_ptr)
+
+        when :RFCTYPE_INT2
+          NWRFCLib.set_int2(@handle, member.cU, value.to_i, @error.to_ptr)
+
+        when :RFCTYPE_INT1
+          NWRFCLib.set_int1(@handle, member.cU, value.to_i, @error.to_ptr)
+
+        when :RFCTYPE_NULL
+          raise "Unsupported type RFCTYPE_NULL" #You should never run into this
+
+        when :RFCTYPE_STRUCTURE
+          raise "Value must be of type table" unless value.class == NWRFC::Structure
+          NWRFCLib.set_structure(@handle, member.cU, value.handle, @error)
+
+        when :RFCTYPE_DECF16
+          raise "#{@members[:type]}: decfloat16 not supported yet"
+          double = NWRFCLib::RFC_DECF16.new #FFI::MemoryPointer.new :double
+          double[:align] = value.to_f
+                                            #double.put_double(0, value.to_f)
+                                            #double = FFI::Pointer.new 4
+          NWRFCLib.set_dec_f16(@handle, member.cU, double.pointer, @error)
+
+        when :RFCTYPE_DECF34
+          raise "#{@members[:type]}: decfloat34 not supported yet"
+          #        double = FFI::MemoryPointer.new :double, 2
+          #        double.put_double(0, value.to_f)
+          double = NWRFCLib::RFC_DECF34.new #FFI::MemoryPointer.new :double
+          double[:align] = value.to_f
+          NWRFCLib.set_dec_f34(@handle, member.cU, double, @error)
+
+        when :RFCTYPE_XMLDATA
+          raise "Unsupported type RFCTYPE_XMLDATA (no longer used)" #You should never run into this
+
+        when :RFCTYPE_STRING
+          stval = value.cU
+          m = FFI::MemoryPointer.from_string stval
+          NWRFCLib.set_string(@handle, member.cU, m, value.size, @error)
+
+        when :RFCTYPE_XSTRING
+          m = FFI::MemoryPointer.new value.size
+          m.put_bytes 0, value
+          NWRFCLib.set_x_string(@handle, member.cU, m, value.size, @error)
+
+        else
+          raise "Illegal member type #{@members[:type]}"
+      end
+      NWRFC.check_error(@error)
+    end
+
+    # Return value as a SAP-formatted date ("YYYYMMDD"). Force value to fit into 8 chars by
+    # truncating or padding with spaces
+    def value_to_date(value)
+      return value.strftime(NW_DATE_FORMAT) if value.respond_to? :strftime
+      # Force the resulting string into 8 characters otherwise
+      value = value.to_s
+      value << ' ' until value.size == 8 if value.size < 8
+      value = value[0..7] if value.size > 8
+      value
+    end
+
+    # Return value as a SAP-formatted time ("HHMMSS"). Force value to fit into 6 chars by
+    # truncating or padding with spaces
+    def value_to_time(value)
+      return value.strftime(NW_TIME_FORMAT) if value.respond_to? :strftime
+      # Force the resulting string into 6 characters otherwise
+      value = value.to_s
+      value << ' ' until value.size == 6 if value.size < 6
+      value = value[0..6] if value.size > 6
+      value
+    end
+
+    # Return a list (array) of symbols representing the names of the fields (or parameters, in the case of a function)
+    # of this data container
+    def fields
+      fc = FFI::MemoryPointer.new(:uint)
+      rc = NWRFCLib.get_field_count(@desc, fc, @error)
+      NWRFC.check_error(@error) if rc > 0
+      fc = fc.read_uint
+      fd = NWRFCLib::RFCFieldDesc.new
+      # Make a list of field names
+      fc.times.inject([]) {|array, index|
+        rc = NWRFCLib.get_field_desc_by_index(@desc, index, fd.to_ptr, @error.to_ptr)
+        NWRFC.check_error(@error) if rc > 0
+        #@todo WARNING! our get_str method did not handle getting the name of the RESPTEXT parameter in STFC_DEEP_TABLE correctly
+        # As a workaround, we use our read_string_dn method; do we need to use this elsewhere?
+        #array << fd[:name].get_str.to_sym #<-The code with good intentions
+        array << fd[:name].to_ptr.read_string_dn.uC.to_sym #<- Workaround; the way of the future?
+      }
+    end
+
+    # Get the metadata of a member (function, structure or table)
+    def member_metadata(member_name)
+      # TODO: Cache metadata definitions; will it be quicker than making a hash of metadata for a given member each time?
+      member = member_name.to_s.upcase
+      if self.class == NWRFC::FunctionCall
+        fpar = NWRFCLib::RFCFuncParam.new
+        rc = NWRFCLib.get_parameter_desc_by_name(@desc, member.cU, fpar.to_ptr, @error.to_ptr)
+        NWRFC.check_error(@error) if rc > 0
+        member_to_hash(fpar)
+      elsif self.class == NWRFC::Table || self.class == NWRFC::Structure
+        fd = NWRFCLib::RFCFieldDesc.new
+        rc = NWRFCLib.get_field_desc_by_name(@desc, member.cU, fd.to_ptr, @error.to_ptr)
+        NWRFC.check_error(@error) if rc > 0
+        member_to_hash(fd)
+      end
+    end
+
+
+
+    private
+    # Returns the subset of metadata values common to both a function parameter
+    # and a type field
+    def member_to_hash(member)
+      {
+          :name => member[:name].get_str,
+          :type => NWRFCLib::RFC_TYPE[member[:type]],
+          :nucLength => member[:nucLength],
+          :ucLength => member[:ucLength],
+          :decimals => member[:decimals],
+          :typeDescHandle => member[:typeDescHandle]
+      }
+    end
+
+    def read_chars(metadata)
+      size = metadata[:ucLength]
+      cb = FFI::MemoryPointer.new :char, size
+      rc = NWRFCLib.get_chars(@handle, metadata[:name].cU, cb, metadata[:nucLength], @error.to_ptr)
+      NWRFC.check_error(@error) if rc > 0
+      cb.read_string(size).uC
+    end
+
+    def read_string(metadata)
+      size = FFI::MemoryPointer.new(:uint)
+      rc = NWRFCLib.get_string_length(@handle, metadata[:name].cU, size, @error)
+      NWRFC.check_error(@error) if rc > 0
+      buf_len = size.read_uint + 1
+      sbuf = FFI::MemoryPointer.new :char, buf_len * NWRFCLib::B_SIZE
+      rc = NWRFCLib.get_string(@handle, metadata[:name].cU, sbuf, buf_len, size, @error)
+      NWRFC.check_error(@error) if rc > 0
+      sbuf.read_string(sbuf.size).uC
+    end
+
+  end
+
+end

data/lib/nwrfc/nwerror.rb

@@ -0,0 +1,40 @@
+module NWRFC
+  
+  class NWError < Exception
+
+    attr_reader :code, :group, :message, :class, :type, :number
+
+    # Instantiate Error object with a handle to an FFI::MemoryPointer
+    # to an NWRFCLib::RFCError object. The error object is analyzed so that
+    # when the caller intercepts it with Rescue, all the error details are
+    # available
+    def initialize(error)
+      @code =    NWRFCLib::RFC_RC[error[:code]]
+      # In the event that the called function raised an exception, we must create a more specific
+      # error
+      raise(NWABAPException, error[:key].get_str)  if @code == :RFC_ABAP_EXCEPTION
+      @group =   NWRFCLib::RFC_ERROR_GROUP[error[:group]]
+      @message = error[:message].get_str
+      @type =    error[:abapMsgType].get_str
+      @number =  error[:abapMsgNumber].get_str
+    end
+
+    def inspect
+      "#{@message} (code #{@code}, group #{@group}, type #{@type}, number #{@number})"
+    end
+
+  end
+
+  class NWABAPException < NWError
+    attr_reader :exception
+    def initialize(exception)
+      @exception = exception
+    end
+
+    def to_s
+      "Function exception #{@exception}"
+    end
+
+  end
+
+end