Readme.java


   Jperl provides a set of methods to call PERL subroutines and pass 
   parameters and accept values from Java.

   In the following methods, 'fname' can be a PERL function name like "foo",
   or a fully qualified method name like "mypackage::foo". Do not use "()" in
   calls. See main.java for examples.

   Arguments :
          All PLCall methods, take an Object array as argument. Valid Objects
          are one of
                  Integer
                  Double
                  Float
                  String
                  Long
                  Short
                  Hashtable
                  Vector

          Other types cause an IllegalArgumentException to be thrown.

   Public methods
          public jp(String perlfile) throws RuntimeException;
          //Takes perlfilename as input. Throws exception on error.
          //Only one instance of jp can be alive at a given time
          
          public void DebugOn();
          //Turns debug on in native code.

          public void DebugOff();
          //Turns debug off in native code.

          public String PLCallScalar(String fname) throws RuntimeExceptio;
          //Calls PERL subroutine 'fname'. Returns scalar result from Perl
          //Throws exception in case of error
 
          public String PLCallScalar(String fname, Object[] args)
                 throws RuntimeException,IllegalArgumentException
          //Calls PERL subroutine 'fname'. 
          //Passes arguments Object args[] to PERL subroutine. 
          //Refer arguments for a list of valid arguments
          //Returns scalar result from Perl
          //Throws exception in case of error


          public String[] PLCallArray(String fname, Object[] args)
                 throws RuntimeException,IllegalArgumentException
          //Calls PERL subroutine 'fname'. 
          //Passes arguments Object args[] to PERL subroutine. 
          //Refer arguments for a list of valid arguments
          //Returns Array result from Perl as a an array of String
          //Throws exception in case of error


          public Hashtable PLCallHash(String fname, Object[] args)
                 throws RuntimeException,IllegalArgumentException
          //Calls PERL subroutine 'fname'. 
          //Passes arguments Object args[] to PERL subroutine. 
          //Refer arguments for a list of valid arguments
          //Returns Hasharray from Perl as Object Hashtable
          //Throws Runtime exception in case of error or odd number of arguments
          //returned to Hashtable


          public  native void IPLLoadLibrary(String libname) 
                  throws RuntimeException;
          // Internal routine available as public.
          // Can be used to load additioal PERL modules at run time

          public  native String[] IPLEval(String expression)
                  throws RuntimeException;
          // Internal routine available as public.
          // Can be used to evaluate PERL expressions and return values
          // example PLEval("$a = 'MyString'; $b = reverse($a); return ($a,$b);");

    Points to Note
       
       1. All values are returned as String/String[]. 
          It is left to the application to decide and convert the values
       2. When Hashtable is returned, all values are stored as strings.
       3. String can contain "" if nothing was returned from PERL. In case of
          error in conversion from PERL Datastructure to JAVA, the string will
          contain "(null)" as its value. All strings are guaranteed to be non
          null
       4. In case of PERL modules using dynamic libraries, 
          an error will be reported.
          Support for this will be added soon.
       5. Flush STDIN/OUT in PERL, so that output of print in PERL is 
          not buffered. This can be done by 
          select((select(STDOUT),$| = 1)[0]);
       6. Add the directory of libperl.so to your LD_LIBRARY_PATH
       7. Data transfer mechanism from PERL to JAVA is restricted to those 
          described above. In case of PERL taking complex data structures
          like Hash of Hash, Array of Hash etc., a wrapper PERL function needs to
          be written
       8. In Perl returning non existant values causes "(null)" to be returned.
          for example
              sub foo { return ("Iam there",$nonexistent); }
       9. If the PERL program exits or dies, control will not return to Java
      10. Using Scalar return, when PERL returns a list causes an exception to
          be thrown

      This has been tested only with JDK 1.1.4 and Perl 5.002 modules on Solaris