CALL_RUBY_EX

This activity "calls" a named method in a Ruby script.  See also the description of the CALL_RUBY activity.

For more information about Ruby, you might start by referring to Ruby Programming Language.

The implementation of the CALL_RUBY and CALL_RUBY_EX activities utilizes JRuby, which is an implementation of the Ruby Programming Language that runs in a Java Virtual Machine (JVM).  For more information about JRuby, we suggest you refer to Home – JRuby.org.  In order to use the CALL_RUBY or CALL_RUBY_EX activities, you must separately download and install JRuby-bin-1.7.10.zip from the http://jruby.org/ website.

The CALL_RUBY_EX activity loads and evaluates the specified script.  Any Ruby code that is specified "globally" in the script (that is, outside of method and class definitions) will be executed, just like the CALL_RUBY activity.  Then the named method will be called.

Optionally, the CALL_RUBY_EX activity can pass and receive a list of parameter name-value pairs, if the method is written to receive and send them in the way required by this activity.

In practice, if you wish to use this capability, you will need to create a method in your Ruby script specifically suited to the CALL_RUBY_EX activity.  However, this technique allows more flexibility because you can pass an unlimited number of name-value pairs, and the method can similarly return multiple name-value pairs to the Processing Sequence.

The CALL_RUBY_EX activity passes and receives the name-value pairs using an instance of a Ruby Hash class.  Your method must be written to accept a single parameter, which is the Hash, and optionally, to return an instance of Hash containing any name-value pairs that you wish to return to the Processing Sequence.

Note: This activity requires that the LANSA Integrator JSM is executing on a JVM at Java 6 or above.

 

CALL_RUBY_EX Example

The following is an example of a Ruby script containing a method that is suitable for use with the CALL_RUBY_EX activity.  It receives name-value pairs in a Hash instance in the method parameter properties.  It extracts the values for the names STRINGIN1 and STRINGIN2 and concatenates them.  It then creates and returns a new Hash instance containing values for the names STATUS and STRINGOUT.

 

def my_concatenate ( properties )

 

     s1 = properties['STRINGIN1']

     s2 = properties['STRINGIN2']

     

     result = s1 + s2

 

     response = Hash.new

     response['STATUS'] = 'OK'

     response['STRINGOUT'] = result

 

     return response;

 

end

 

 

A LANSA Composer Processing Sequence might invoke the script and receive the result in the following way:

 

INPUT Parameters:

SCRIPT: Required

This parameter must specify the path and filename of the Ruby script file to be loaded.  For example:

    C:\My_Ruby_Scripts\my_script.rb (for a Windows server), OR

    /My_Ruby_Scripts/my_script.rb (for an IBM i server)

METHOD: Required

This parameter must specify the name of the method to be called.  The method must be defined in the script file specified by the SCRIPT parameter.

PARMNAMES
PARMVALUES: Optional

These parameters can specify variable lists containing, respectively, the names and values of parameters to be passed to the specified method in the Ruby script.  On return, the variable lists will containg the names and values retruned by the method.

RUBYHOME: Optional

This parameter can specify the path to the JRuby home directory (where the JRuby executable files are located.  For example:

    C:\JRuby-1.7.10 (for a Windows server), OR

    /JRuby-1.7.10 (for an IBM i server)

(If not specified, or if the special value *DEFAULT is specified, then the CALL_RUBY activity will use the value specified in the LANSA Integrator rubyservice.properties file for the property name "rubyhome".)

LOADPATH: Optional

This parameter can specify the load path for additional Ruby script files.  If your Ruby script file specified in the SCRIPT parameter references other Ruby script files (for example using Ruby "require" or "load" directives), then you may need to specify the load path in this parameter to enable JRuby to locate the script files.

The default value is *AUTOMATIC, which means that the CALL_RUBY activity will use the same directory containing the script file specified in the SCRIPT parameter.  If all your script files are contained in one directory, then this value will usually work for you.

INPUT and OUTPUT Parameters:

RESULTSTATUS: Optional

The value returned in this parameter depends on the behavior of the script.  If the script uses the "return" directive, then this parameter will contain a string representation of the return value, if possible.  If the script uses an "exit" directive (which specifies an integer exit value), then this parameter will contain the exit value.