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:
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 1Notice 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.
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.dllEach 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.
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.
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.6Note: This will cause the JVM to be created if this has not already happened.
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
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
Under Linux and MacOS, R uses environment variables to specify where the R executables, libraries and packages are held. In particular, an environment variable R_HOME must be set up before you can use the R interface. This can either be done outside APLX (in a startup script), or you can use ŒSETUP to initialize it from within APL, before opening the interface using ŒNEW.
Keyword: R_HOME
Specifies the full path to the R installation. The name should be supplied as a character vector after the keyword:
'r' ŒSETUP 'R_HOME' '/usr/local/lib/R/' © Linux 'r' ŒSETUP 'R_HOME' '/Library/Frameworks/R.framework/Resources/' © MacOS
Note: In the R interface, ŒSETUP can be used to set any environment variable, not only R_HOME. The interface does not check the name of the variable.
Keyword: R_HOME
Returns the value of the environment variable as a character vector:
'r' ŒSETUP 'R_HOME' /usr/local/lib/R/