Topic: APLX Help : Help on APL language : System Functions & Variables : ⎕SETUP Set up external environment
[ Previous | Next | Contents | Index | APL Home ]

www.microapl.co.uk

⎕SETUP Set up external environment.NetJavaRuby


The dyadic system function ⎕SETUP is used to set or query various parameters for the interface with external architectures such as .Net, Ruby and Java. Normally, you will want to set these parameters before using ⎕NEW or ⎕CALL to access the external system.

The left argument is a character vector which specifies the external environment, in the same format as for ⎕NEW. The right argument is either a character vector (containing a keyword specifying the parameter), or a nested vector where the first element is the keyword, and the remaining elements are parameters for that keyword. Keywords are case-insensitive. The options available depend on the environment, as follows:

Changing settings

Keyword: using

Sets the current search path for .Net namespaces and DLLs. These should be supplied as character vectors after the keyword:

      '.net' ⎕SETUP 'using' 'System' 'System.Text' 'QMath.Geom,c:\dev\qmath.dll'

Each element comprises either just a namespace (such 'System.Text'), or a namespace followed by the name of the DLL in which it is located. This can be a full path name, or just the name of the DLL (in which case the DLL should be in the Global Assembly Cache).

Keyword: byref

Sets or clears 'by reference' mode. The parameter should be a boolean scalar. The previous value is returned as the explicit result.

In 'by reference' mode, the list of arguments to each .Net method call is saved before the call. After the call has been made, it can be retrieved by querying the 'Args' parameter (see below). This is useful for the (relatively uncomon) cases where a .Net method takes an argument by reference, and modifies one or more of the arguments in-situ. (In C#, such parameters are identified by the keywords out or ref. In Visual Basic, they are identified by the keyword ByRef).

In this example, we call the HexUnescape method of the System.Uri class. This takes two parameters, a string (which might contain escaped character sequences such as '%20' corresponding to a space character), and an index position into the string. The index position is passed by reference. When the method completes, the index is incremented to point at the next character. By setting 'by reference' mode and reading back the arguments after the call, the new value of the by-reference argument is available to the APL application:

      uri←'.net' ⎕GETCLASS 'System.Uri'
      '.net' ⎕SETUP 'byref' 1
0
      ⎕AF  uri.HexUnescape 'The%20best%20way' 3
32
      '.net' ⎕SETUP 'args' 
 The%20best%20way 6
      '.net' ⎕SETUP 'byref' 0
1

Notice how the index position passed in, which was 3 to point at the first '%20', has been incremented to 6 after the call, pointing now at the 'b' character.

Because there is an overhead in saving the argument list in this way, you should switch off 'by reference' mode once you have made the call and retrieved the argument list.

Querying values

Keyword: version

Returns the version of the Common Language Runtime as a character vector:

      '.net' ⎕SETUP 'version'
2.0.50727.312

Keyword: using

Returns the current search path for class names and assemblies, as a nested vector of character vectors:

      '.net' ⎕SETUP 'using'
System System.Text System.Drawing,system.drawing.dll

Each element comprises either just a namespace (such 'System.Text'), or a namespace followed by the name of the DLL in which it is located. This can be a full path name, or just the name of the DLL (in which case the DLL should be in the Global Assembly Cache).

Keyword: args

Returns the argument list after a call-by-reference (see description of the ByRef parameter above). If the is no argument list available, or the ByRef parameter is 0, it returns a Null object.

Keyword: byref

Returns the current value of the 'by reference' setting as boolean scalar.

Java code runs inside a Java Virtual Machine (JVM). You can specify a number of settings to be used when the JVM is created. Creation will occur the first time you make a Java call other than setting one of the JVM creation parameters.

Changing settings

Keyword: vm

Specifies the full path and file name for the Java Virtual Machine (normally this will be set automatically from the registry or Java installation). The name should be supplied as a character vector after the keyword:

      'java' ⎕SETUP 'vm' 'c:\Program Files\Java\jre1.6.0\bin\client\jvm.dll'

The main purpose for this is to specify a particular version of Java when running Java code. You must set this parameter before making any Java call.

Keyword: classpath

Sets the path for the Java classes (normally this will be set automatically from the registry or Java installation). The path should be supplied as a character vector after the keyword. You must set this parameter before making any Java call.

      'java' ⎕SETUP 'classpath' 'c:\myjava\'

Keyword: vmoptions

Sets one or more command-line options for the Java Virtual machine. Each option is specified after the keyword as a character vector, in the form 'Option=Value'. You must set the options before making any Java call, since they are used as parameters when creating the Java Virtual Machine. Valid options vary depending on the JVM you are using.

Querying values

Keyword: vm

Queries the full path and file name for the Java Virtual Machine:

      'java' ⎕SETUP 'vm' 
c:\Program Files\Java\jre1.6.0\bin\client\jvm.dll

Keyword: classpath

Queries the Java class path:

      'java' ⎕SETUP 'classpath' 
.

Keyword: vmoptions

Queries the options passed to the Java Virtual Machine:

      'java' ⎕SETUP 'vmoptions' 

Keyword: version

Returns the Java Virtual Machine version as a character vector:

      'java' ⎕SETUP 'version'
1.6 

Note: This will cause the JVM to be created if this has not already happened.

Changing settings

Keyword: require

Adds a Ruby script to the list of scripts in which Ruby will search for class definitions. The parameter is a character vector containing the script name. This can be specified either as a full path name, or as just a file name in which case Ruby will search in its current search path for the script:

      'ruby' ⎕SETUP 'require' 'Date'
      'ruby' ⎕SETUP 'require' 'c:\ruby\myapp.rb'

Keyword: addpath

Adds one or more directories to Ruby's current search path for scripts:

      'ruby' ⎕SETUP 'addpath' 'c:\rubyapps' 'c:\rubylibs\version2' 

Keyword: safelevel

Sets the 'safe level' (security level) for Ruby execution. The parameter should be an integer in the range 0 to 4.

      'ruby' ⎕SETUP 'safelevel' 3
      'ruby' ⎕EVAL 's=String.new "Unsafe String"
Unsafe String
      'ruby' ⎕EVAL 's.taint'
      'ruby' ⎕EVAL 's.untaint'
#<SecurityError: (eval):0:in `untaint': Insecure operation `untaint' at level 3>
DOMAIN ERROR
      'ruby' ⎕EVAL 's.untaint'
      ^

Keyword: script

Sets the nominal script name for Ruby execution (the default is 'embedded')

      'ruby' ⎕SETUP 'script' 'APLXBridge'
      'ruby' ⎕EVAL '$0'
APLXBridge 

Querying values

Keyword: version

Returns the version of Ruby as a character vector:

      'ruby' ⎕SETUP 'version'
1.8.6

Keyword: path

Returns the current Ruby search path as a nested vector of character vectors:

      'ruby' ⎕SETUP 'path'
 c:/ruby/lib/ruby/site_ruby/1.8 c:/ruby/lib/ruby/site_ruby/1.8/i386-msvcrt c:/ru
      by/lib/ruby/site_ruby c:/ruby/lib/ruby/1.8 c:/ruby/lib/ruby/1.8/i386-mswin
      32 .

Keyword: script

Returns the current nominal script name as a character vector:

      'ruby' ⎕SETUP 'script'
embedded

Keyword: safelevel

Returns the current Ruby 'safe level' as an integer scalar

      'ruby' ⎕SETUP 'safelevel'
0

Topic: APLX Help : Help on APL language : System Functions & Variables : ⎕SETUP Set up external environment
[ Previous | Next | Contents | Index | APL Home ]