## ŒSETUP Set up external environment

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:

## .Net

### 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

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.

## Ruby

### 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

## R

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.

### Changing settings

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.

### Querying values

Keyword: R_HOME

> Returns the value of the environment variable as a character vector:

>           'r' ŒSETUP 'R_HOME'
>     /usr/local/lib/R/

Topic: APLX Help : Help on APL language : System Functions & Variables : ŒSETUP Set up external environment

[ Previous | Next | Contents | Index ]