nwrfc 0.0.2 → 0.0.3

data/README.rdoc

@@ -51,6 +51,13 @@ Setting and getting parameters and fields:
 
 == Installation
 
+In order to install and run nwrfc, you need to install {http://github.com/ffi/ffi Ruby-FFI} which requires 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 gem:
+
 On Linux:
 
     sudo gem install nwrfc
@@ -77,6 +84,10 @@ so that ["system2"] at the end points to whatever label you gave it in the YAML
 
 == Release Notes
 
+=== What's new in 0.0.3
+
+* Basic RFC server functionality
+
 === What's new in 0.0.2
 
 * More comprehensive type support

data/lib/nwrfc.rb

@@ -16,20 +16,19 @@ require 'time'
 # This library provides a way to call the functions of the SAP Netweaver RFC
 # SDK, i.e. opening a connection to an ABAP system, calling functions etc., as
 # well as running an RFC service
-#---
-# *TODO*: Create an error class that wraps the SAP error struct, so it can
-# be raised and the caller can get all the information from there
-#+++
 
 module NWRFC
 
+  # ABAP Time Format ("HHMMSS")
   NW_TIME_FORMAT = "%H%M%S"
+  # ABAP Date Format ("YYYYMMDD")
   NW_DATE_FORMAT = "%Y%m%d"
 
   def inspect
     self.to_s
   end
 
+  # Return the version of the NW RFC SDK library
   def NWRFC.get_version
     # See custom method FFI::Pointer#read_string_dn in nwrfclib.rb
     # http://stackoverflow.com/questions/9293307/ruby-ffi-ruby-1-8-reading-utf-16le-encoded-strings
@@ -41,7 +40,7 @@ module NWRFC
   end
 
   # Take Hash of connection parameters and returns FFI pointer to an array
-  # for passing to connection
+  # for setting up a connection
   def NWRFC.make_conn_params(params) #https://github.com/ffi/ffi/wiki/Structs
     par = FFI::MemoryPointer.new(NWRFCLib::RFCConnParam, params.length)
     pars = params.length.times.collect do |i|
@@ -55,6 +54,7 @@ module NWRFC
     par
   end
 
+  # Check for an error using error handle (used internally)
   def NWRFC.check_error(error_handle)
     raise NWError, error_handle \
       if error_handle[:code] > 0
@@ -62,7 +62,7 @@ module NWRFC
       
   end
 
-  # Represents a connection to a SAP system that can be used to invoke
+  # Represents a client connection to a SAP system that can be used to invoke
   # remote-enabled functions
   class Connection
     attr_reader :handle
@@ -82,18 +82,22 @@ module NWRFC
     end
 
     # Call the NW RFC SDK's RfcCloseConnection() function with the current
-    # connection; this (should - *TODO* - check) invalidate the connection handle
+    # connection; this *should* invalidate the connection handle
     # and cause an error on any subsequent use of this connection
+    #@todo Write test to check that handle is invalidated and causes subsequent calls to fail
     def disconnect
       NWRFCLib.close_connection(@handle, @error.to_ptr)
       NWRFC.check_error(@error)
     end
-    
+
+    # Get the description of a given function module from the system to which we are connected
+    # @return [Function] function module description
     def get_function(function_name)
       Function.new(self, function_name)
     end
 
     # Return details about the current connection and the system
+    # @return [Hash] information about the current connection
     def connection_info
       return @get_connection_attributes if @get_connection_attributes
       conn_info = NWRFCLib::RFCConnection.new
@@ -103,35 +107,43 @@ module NWRFC
         hash[member] = conn_info[member].get_str #get_str, own definition in nwrfclib.rb, FFI::StructLayout::CharArray#get_str
         hash
       }
-    end  
+    end
+
+    alias :close :disconnect
 
   end
 
+  # Converts ABAP true/false into Ruby true/false
+  # @return True for 'X', False for ' ' or nil otherwise
   def NWRFC.abap_bool(value)
     return true if value == 'X'
     return false if value == ' '
     nil
   end
 
+  # Converts Ruby true/false into ABAP true/false
+  # @return 'X' for true,, ' ' for false or nil otherwise
   def NWRFC.bool_abap(value)
     return 'X' if value == true
     return ' ' if value == false
     nil
   end
 
-  # Represents a function parameter
+  # Represents the metadata of a function parameter
   class Parameter
 
     attr_accessor :handle
 
     # Create a parameter by setting parameter attributes
+    #@todo For certain types, e.g. :RFCTYPE_BCD, a length specification is
+    #  required, otherwise a segfault is the result later down the line.
+    #  Find and implement all the types where this is required
     def initialize(*args)  
 
       attr = args[0]
       
-      #TODO: For certain types, e.g. :RFCTYPE_BCD, a length specification is 
-      # required, otherwise a segfault is the result later down the line.
-      # Find and implement all the types where this is required
+
+
       raise "RFCTYPE_BCD requires a length" if attr[:type] == :RFCTYPE_BCD && !(attr[:length])
 
       @handle                 = NWRFCLib::RFCFuncParam.new
@@ -160,11 +172,19 @@ module NWRFC
     attr_reader :desc, :function_name
     attr_accessor :connection
 
-    # TODO: Update doc to reflect different calling options
     # Get a function module instance; can also be obtained by calling Connection#get_function
     # Takes either: (connection, function_name) or (function_name)
     # When passed only `function_name`, creates a new function description locally, instead of
     # fetching it form the server pointed to by connection
+    #@overload new(connection, function_name)
+    #   Fetches a function definition from the server pointed to by the connection
+    #   @param [Connection] connection Connection to SAP ABAP system
+    #   @param [String] function_name Name of the function module on the connected system
+    #
+    #@overload new(function_name)
+    #   Returns a new function descriptor. This is ideally used in the case of establishing a
+    #   server function. In this case, the function cannot be used to make a remote function call.
+    #   @param [String] function_name Name of the new function module
     def initialize(*args)#(connection, function_name)
       raise("Must initialize function with 1 or 2 arguments") if args.size != 1 && args.size != 2
       @error =  NWRFCLib::RFCError.new
@@ -181,6 +201,9 @@ module NWRFC
       end
     end
 
+    # Add a parameter to a function module. Ideally to be used in the case where a function definition is built
+    # up in the client code, rather than fetching it from the server for a remote call
+    # @param [Parameter] Definition of a function module parameter
     def add_parameter(parameter)
       rc = NWRFCLib.add_parameter(@desc, parameter.handle, @error)
       NWRFC.check_error(@error) if rc > 0
@@ -225,16 +248,28 @@ module NWRFC
   class FunctionCall < DataContainer
     attr_reader :handle, :desc, :connection, :function
 
-    # TODO: Update doc to reflect different calling options
     # Call with either Function or Connection and Function Call instance (handle)
+    #@overload new(function)
+    #   Get a function call instance from the function description
+    #   @param [Function] function Function Description
+    #@overload new(function_handle)
+    #   Used in the case of server functions; instantiate a function call instance from the connection
+    #   and function description handles received when function is invoked on our side from a remote
+    #   system; in this case, there is no handle to the connection, and we take advantage only of the
+    #   data container capabilities
+    #   @param [FFI::Pointer] function_handle Pointer to the function handle (RFC_FUNCTION_HANDLE)
     def initialize(*args)
-      raise("Must initialize function with 1 or 2 arguments") if args.size != 1 && args.size != 2
       @error = NWRFCLib::RFCError.new
-      if args.size == 2
-        @handle = args[1]
-        @connection = args[0].connection
-        # TODO: Get function description from instance
-      else
+      if args[0].class == FFI::Pointer
+        @handle = args[0]
+        @connection = nil
+        @function = nil
+        # @connection = args[0].connection
+        @desc = NWRFCLib.describe_function(@handle, @error)
+        #@todo Investigate having a referenced Function object as well in the server case; does it have practical applications?
+        #  Doing this would require an extra way of handling the constructor of Function
+        # @function = Function.new
+      elsif args[0].class == Function
         @function = args[0] #function
         @connection = args[0].connection
         @handle = NWRFCLib.create_function(@function.desc, @error.to_ptr)
@@ -243,8 +278,12 @@ module NWRFC
       NWRFC.check_error(@error)
     end
 
+    # Execute the function on the connected ABAP system
+    #@raise NWRFC::NWError
     def invoke
+      raise "Not a callable function" unless @connection
       rc = NWRFCLib.invoke(@connection.handle, @handle, @error.to_ptr)
+      #@todo Handle function exceptions by checking for :RFC_ABAP_EXCEPTION (5)
       NWRFC.check_error(@error) if rc > 0
     end
   end
@@ -297,10 +336,17 @@ module NWRFC
     end
 
     # Add new (empty) row and return the structure handle
+    # or yield it to a passed block
+    # @return Structure
     def new_row
       s_handle = NWRFCLib.append_new_row(@handle, @error)
       NWRFC.check_error(@error)
-      Structure.new(s_handle)
+      s = Structure.new(s_handle)
+      if block_given?
+        yield s
+      else
+        s
+      end
     end
 
   end #class Table

data/lib/nwrfc/datacontainer.rb

@@ -1,6 +1,8 @@
 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
   class DataContainer
     attr_reader :handle, :desc
 

data/lib/nwrfc/nwrfclib.rb

@@ -51,10 +51,13 @@ end
 # architectures, though the plan is not to support them)
 #String.class_eval{define_method(:cU){ Iconv.conv("UTF-16LE", "UTF8", self+"\0") }}
 class String
+
+  # Convert string from UTF-8 to doudble-null terminated UTF-16LE string
   def cU
     NWRFCLib::Cutf8_to_utf16le.iconv(self+"\0")
   end
 
+  # Convert string from UTF-16LE to UTF-8 and trim trailing whitespace
   def uC
     NWRFCLib::Cutf16le_to_utf8.iconv(self).strip
   end
@@ -80,7 +83,7 @@ module NWRFCLib
   ffi_lib 'sapnwrfc'
 
   # Multiplier for providing correct byte size for String passed to RFC library
-  #TODO: Make platform-dependent size based on RUBY_PLATFORM
+  #@todo Make platform-dependent size based on RUBY_PLATFORM
   B_SIZE = 2
 
   RFC_RC = enum(
@@ -281,7 +284,13 @@ module NWRFCLib
     [:add_parameter, :RfcAddParameter, [:pointer, :pointer, :pointer], :int],
     [:add_type_desc, :RfcAddTypeDesc, [:pointer, :pointer, :pointer], :int],
     [:add_type_field, :RfcAddTypeField, [:pointer, :pointer, :pointer], :int],
+  # @method append_new_row(table_handle, error_handle)
+  # @returns FFI::Pointer pointer to structure of new row
+  # calls RfcAppendNewRow()
     [:append_new_row, :RfcAppendNewRow, [:pointer, :pointer], :pointer],
+  # @method append_row(table_handle, structure, error_handle)
+  # @returns Integer RC
+  # calls RfcAppendRow()
     [:append_row, :RfcAppendRow, [:pointer, :pointer, :pointer], :int],
     [:clone_structure, :RfcCloneStructure, [:pointer, :pointer], :pointer],
     [:clone_table, :RfcCloneTable, [:pointer, :pointer], :pointer],

data/lib/nwrfc/server.rb

@@ -1,10 +1,9 @@
 module NWRFC
 
   # Implementation of a server to host RFC functions to be called from an ABAP system
-  # or from another RFC implementation
   class Server
 
-    TIMEOUT = 200
+    TIMEOUT = 0
 
     # Register a server with the given gateway and program ID
     def initialize(params)
@@ -16,21 +15,32 @@ module NWRFC
       NWRFC.check_error(@error)
     end
 
+
+    # Start serving an RFC function, given the definition and the block,
+    # to which the connection and functions are yielded
     def serve(function, &block)
       # Establish callback handler
-      callback = Proc.new do |connection, function_call, error|
-        fc = 
-        debugger
+      callback = Proc.new do |connection, function_handle, error|
+        function_call = FunctionCall.new(function_handle)
         yield(function_call)
       end
       rc = NWRFCLib.install_server_function(nil, function.desc, callback, @error)
       NWRFC.check_error(@error) if rc > 0
+
       # Server loop
       while (rc==NWRFCLib::RFC_RC[:RFC_OK] || rc==NWRFCLib::RFC_RC[:RFC_RETRY] || rc==NWRFCLib::RFC_RC[:RFC_ABAP_EXCEPTION])
         rc = NWRFCLib.listen_and_dispatch(@handle, TIMEOUT, @error)
       end
     end
 
+    # Disconnect from the server
+    def disconnect
+      NWRFCLib.close_connection(@handle, @error)
+      NWRFC.check_error(@error)
+    end
+
+    alias :close :disconnect
+
   end
   
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: nwrfc
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: 
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Martin Ceronio
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-02-22 00:00:00 Z
+date: 2012-02-23 00:00:00 Z
 dependencies: []
 
 description: SAP Netweaver RFC Library Wrapper using Ruby-FFI