Interfacing to .Net
Specifying a call to the .Net environment
You can interface to .Net by supplying 'net' or .net as the environment string (left argument) for ⎕NEW, ⎕GETCLASS, or ⎕CALL. These system functions will allow you to create an instance of a .Net class, or to call a .Net static (shared) method.
Specifying .Net class names
.Net classes are defined in Assemblies (each assembly usually corresponds to a single .Net library DLL, for example mscorlib.dll which contains the basic .Net utility classes), and are organized into Namespaces (such as System, System.Text, System.IO and so on). For example, Microsoft provide a class called Font for representing fonts. This is defined in the System.Drawing namespace, so its fully-qualified name is System.Drawing.Font. The code for this class is held in the System.Drawing assembly, in the shared library system.drawing.dll.
When you use ⎕NEW (or ⎕GETCLASS or ⎕CALL) to refer to a .Net class, you can specify the class name in one of the following ways:
As an undecorated class name, without the namespace qualifier, for example: 'Font'. In this case, the assembly must be one of those loaded by default or already loaded by a previous call, and the namespace must be included in the namespace search list (see below).
As a fully (or partially) qualified namespace and class name, for example 'System.Drawing.Font'. In this case, the assembly must be one of those loaded by default, or already loaded by a previous call, but the namespace does not have to be included in the namespace search list.
As an undecorated or fully-qualified class name, and a simple file name specifying the DLL in which the assembly can be found, for example: 'System.Data.SqlClient,system.data.dll'. A comma is used as the delimiter between the class and file name. In this case, the DLL must exist in the standard location known as the Global Assembly Cache (GAC).
As an undecorated or fully-qualified class name and a full path name specifying the DLL, for example: 'MyBase.MyFirstClass,c:\devt\myclasses.dll' Again a comma is used as a delimiter between the class and file name.
Setting the search paths for namespaces and .Net assemblies
When you use ⎕NEW (or ⎕GETCLASS or ⎕CALL) to refer to a .Net class, the system searches through the namespaces and assemblies which are in its search path to resolve the class name. If the class is not found, you will get an error:
SW←'.net' ⎕NEW 'StringWriter'
Class StringWriter not found in current search list
DOMAIN ERROR
SW←'.net' ⎕NEW 'StringWriter'
^
The above example has failed because StringWriter is a class defined in the System.IO namespace, which is not included in the default search list. You can set the current search path for .Net namespaces and DLLs by using the system function ⎕SETUP and the 'using' keyword. For example, we can tell the .Net subsystem to include System.IO in the search list:
'.net' ⎕SETUP 'using' 'System' 'System.IO'
SW←'.net' ⎕NEW 'StringWriter'
SW
[.net:StringWriter]
The namespaces (and optionally DLLs in which they are located) 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).
For convenience, the path is set by default to include the most important .Net libraries, as follows:
System System,system.dll System.Text System.Collections System.Windows.Forms,system.windows.forms.dll System.Drawing,system.drawing.dll
You can read the current search list by supplying the 'using' keyword to ⎕SETUP with no arguments.
Conversion of .Net data types to APL data
When your read a .Net property, or call a method which returns a result, APLX by default applies the following data conversion rules:
Any .Net numeric types (Int32, Int64, single- or double-precision floats, decimal, etc) are converted to APL integers or floats. 64-bit integers are converted to APL floats on 32-bit platforms, to APL integers on 64-bit platforms.
.Net Booleans are converted to APL binary values 0 or 1
.Net Strings and Chars are converted to APL character arrays, translated from Unicode to APLX internal representation. (Any characters which do not appear in the APLX character set are converted to question marks.)
.Net Enumeration types are converted to APL integers (see below)
Simple .Net arrays are converted to APL arrays, with individual elements converted as above.
Anything else is left as an Object in the .Net environment, and a reference to the object is returned to APL.
There are some special cases to consider. The data might not be convertible at all, or it might lose precision in the conversion. For example, a .Net Decimal might have a higher precision than an APL double-precision floating point can represent. To handle cases like this, APLX provides the ⎕REF system method. This forces the data to remain as a .Net object. You can then call ToString, or other .Net methods appropriate to the Decimal data type, to manipulate the data without losing precision.
An example which cannot be represented at all is where a .Net Double contains a NaN (Not A Number). APL does not handle NaNs, so it cannot be converted to an APL floating-point value. Instead, NaNs are left as Objects. If you try to use the data in an APL expression, you will get a DOMAIN ERROR, but you can see that it is a NaN and use ToString and other operations on it.
Enumeration Types
Enumeration types are special classes in .Net, which contain sets of alternative values which a particular type of variable can hold (somewhat similar to enum types in the C language). When a .Net nethod or property returns an Enumeration type, APLX converts it to the equivalent integer. Equally, calls which expect an Enumeration type can be passed the equivalent integer from APL (the type is converted automatically). This means that Enumerations which are sets of bits can be combined in APL using the + primitive. However, for readability of code, and to avoid having to check the specific value of an Enumeration, you can use ⎕GETCLASS to fetch the Enumeration type, and use that directly.
For example, most .Net dialogs (such as OpenFileDialog, which puts up a dialog inviting the user to select an existing file) return a Enumeration type called DialogResult, indicating which button (OK, Cancel, etc) was clicked to end the dialog. We can access this class to see what the various enumeration values are:
DR←'.net' ⎕GETCLASS 'DialogResult'
DR.OK
1
DR.OK.ToString
OK
DR.Cancel
2
DR.Cancel.ToString
Cancel
⎕BOX DR.⎕NL 2
Abort Cancel Ignore No None OK Retry value__ Yes
This means that, if you call the ShowDialog method of the OpenFileDialog, you can test which button ended the dialog either by checking the numeric value returned, or by seeing if it is equal to the named enumeration value:
∇R←FileDialog;DR;DLG
[1] ⍝ Put up file dialog, return file selected or empty vector if none
[2] DR←'.net' ⎕GETCLASS 'DialogResult'
[3] DLG←'.net' ⎕NEW 'OpenFileDialog'
[4] :If DLG.ShowDialog=DR.OK
[5] R←DLG.FileName
[6] :Else
[7] R←''
[8] :End
∇
Parameters passed by reference
To handle the (relatively uncomon) cases where a .Net method takes an argument 'by reference', and modifies one or more of the arguments in-situ, you can use ⎕SETUP and the 'byref' keyword. See the documentation for ⎕SETUP.
Using the .Net interface from multiple APL tasks
There are no special restrictions on using the .Net interface from multiple APL tasks. Each task will have an independent copy of the interface, which will be deleted on )CLEAR, )LOAD, or )OFF.
Inheriting from .Net classes
Your own classes (written in APL) cannot inherit directly from a .Net class. However, you can achieve much the same result by using mixins.
In this example, the constructor of a user-defined class called APLDate 'mixes-in' the .Net class DateTime
⎕cr 'APLDate'
APLDate {
∇APLDate b
⍝ Constructor for APLDate class
⍝ Argument is vector of Year Month Day Hour Sec
⍝ (or just Year Month day)
⍝ If no argument supplied, use current ⎕ts value
:If 0=⍴b
'.net' ⎕mixin(⊂'DateTime'),6↑⎕ts
:Else
'.net' ⎕mixin(⊂'DateTime'),b
:End
∇
∇r←ts
⍝ Return .Net DateTime in ⎕TS format
r←Year,Month,Day,Hour,Minute,Second,Millisecond
∇
∇r←ts_gmt;gmt
⍝ Return the date/time adjusted to GMT, in ⎕ts form
gmt←ToUniversalTime
r←gmt.Year,gmt.Month,gmt.Day,gmt.Hour,gmt.Minute,gmt.Second,gmt.Millisecond
∇
}
dt←⎕new APLDate
As well as the methods written in APL, all the public properties and methods of the .Net DateTime class become available in the APL class APLDate:
dt←⎕new APLDate
dt.⎕nl 2
Date
Day
DayOfWeek
DayOfYear
Hour
Kind
MaxValue
Millisecond
MinValue
Minute
Month
Now
Second
Ticks
TimeOfDay
Today
UtcNow
Year
dt.ToLongDateString ⍝ Method 'mixed-in' from .Net DateTime
19 March 2009
dt.ts ⍝ Method written in APL
2009 3 19 16 0 5 0
dt.ts_gmt
2009 3 19 21 0 5 0
Exceptions
If the .Net environment raises an error (or exception), APLX will normally try to print the error message or exception text on the session window, and then raise an APL error (typically DOMAIN ERROR). You can get further information by using ⎕LE Last Exception to read back the .Net exception object: For example:
'.net' ⎕NEW 'DateTime' 'Bastille Day'
Constructor on type 'System.DateTime' not found.
DOMAIN ERROR
'.net' ⎕NEW 'DateTime' 'Bastille Day'
^
exception←'.net' ⎕LE 1
exception
[.net:MissingMethodException]
exception.⎕NL 2
Data
HelpLink
InnerException
Message
Source
StackTrace
TargetSite
exception.Message
Constructor on type 'System.DateTime' not found.
exception.Source
mscorlib
exception.ToString
System.MissingMethodException: Constructor on type 'System.DateTime' not found.
at System.RuntimeType.CreateInstanceImpl(BindingFlags bindingAttr, Binder bin
der, Object[] args, CultureInfo culture, Object[] activationAttributes)
at System.Activator.CreateInstance(Type type, BindingFlags bindingAttr, Binde
r binder, Object[] args, CultureInfo culture, Object[] activationAttribute
s)
at NetBridge.NetBridge.CreateNamedInstance(String class_name, Object[] arg_li
st)
at APLXObj_New(Void* arch_if, Void** objref, wsobj* args, _ExportedProcs* pro
cs, SByte* errmsg)
User-interface programming in .Net
User-interface programming in APLX can be done by using the built-in System classes (formerly accessed through ⎕WI). This has the advantages that it is relatively easy to do, and that APLX applications using the System classes will work on other platforms (e.g. the Macintosh). But for more flexibility, you can alternatively use Microsoft's .Net classes directly.
User-interface programming using the .Net framework (System.Windows.Forms) is a special case of using .Net objects from within APLX. See the Microsoft documentation for full information on this topic.
From the APL programmer's point of view, there are a few specific points to note:
The typical scenario is that you create a .Net Form object, set various properties of the Form (such as the Text property, which is the window title), and then create further items using control classes such as Button and TextBox. You need to use the Add method of the form's Controls property to link up the controls and the form. (Note: If you have a copy of Microsoft Visual Studio or Visual Studio Express, you can use the form designer to design a form interactively, and then copy the dimensions and other properties created in C# or Visual Basic into your APLX code, adjusting the syntax as necessary).
To handle .Net events, you need to assign the name of an APL callback function (or some other expression) to one of the control's event properties. For example, a Button has a Click event, which fires when the button is clicked. As with System classes, the event is held in a queue and de-queued using the system function
⎕WE, which causes your event handler to be run.When one of your callback functions is running, there are three system functions which you can use to find out more about the event. These are:
⎕EVAReturns a reference to the event argument object (class EventArgs)
⎕EVNReturns the name of the event (such as 'Click')
⎕EVTReturns a reference to the target object, for example the Button object
Example 1
The following complete example (available in the workspace 10 HELPDOTNET) shows a simple application which displays a window with an edit box, a text box to output results, and a button. When the button is clicked, it simply evaluates the APL expression typed into the edit box and displays the result in the text box. Note in particular the callbacks set up on lines 32 and 33. The first of these (the Closed event) is triggered when the window is closed; this terminates the function by clearing the )SI, and this in turn causes all the object references to be deleted because they are held in localized variables. The second call back (the Click event of the button) causes the EVALUATE function to be run.
∇DOT_Forms;X;F;EditResult;EditIn;ButtonDo
[1] ⍝ Simple example of using Windows Forms from APLX v4
[2] ⍝ Create main form
[3] F←'.net' ⎕NEW 'Form'
[4] F.Text←'Expression Evaluator'
[5] ⍝
[6] ⍝ Create edit box for input line
[7] EditIn←'.net' ⎕NEW 'TextBox'
[8] EditIn.Left←12 ⋄ EditIn.Top←21
[9] EditIn.Width←265 ⋄ EditIn.Height←20
[10] EditIn.Font←'.net' ⎕NEW 'Font' 'APLX Upright' 10
[11] F.Controls.Add EditIn
[12] ⍝
[13] ⍝ Create multi-line box for result
[14] EditResult←'.net' ⎕NEW 'TextBox'
[15] EditResult.Multiline←1
[16] EditResult.Left←12 ⋄ EditResult.Top←50
[17] EditResult.Width←265 ⋄ EditResult.Height←180
[18] EditResult.Font←'.net' ⎕NEW 'Font' 'APLX Upright' 10
[19] F.Controls.Add EditResult
[20] ⍝
[21] ⍝ Create button
[22] ButtonDo←'.net' ⎕NEW 'Button'
[23] ButtonDo.Left←94 ⋄ ButtonDo.Top←240
[24] ButtonDo.Width←100 ⋄ ButtonDo.Height←22
[25] ButtonDo.Text←'Evaluate'
[26] F.Controls.Add ButtonDo
[27] ⍝
[28] ⍝ Make the button accept Enter as equivalent to clicking
[29] F.AcceptButton←ButtonDo
[30] ⍝
[31] ⍝ Add callbacks
[32] F.Closed←'"Cleaning up.." ⋄ →'
[33] ButtonDo.Click←'EditResult EVALUATE EditIn.Text'
[34] ⍝
[35] ⍝ Show the window
[36] F.Show
[37] ⍝
[38] ⍝ Process events
[39] X←⎕WE ¯1
∇
∇A EVALUATE B;RESULT;⎕IO
[1] ⍝ Evaluate expression B and put it into the Text property of object A
[2] ⍝ If an error occurs, change the colour of the text
[3] ⎕IO←1
[4] RESULT←⎕EC B
[5] :Select ↑RESULT
[6] :Case 0 ⍝ Error
[7] A.ForeColor←A.ForeColor.Red
[8] A.Text←MAKEVEC 3⊃RESULT
[9] :Case 1 ⍝ Expression with a result which would display
[10] A.ForeColor←A.ForeColor.DarkOliveGreen
[11] A.Text←MAKEVEC⍕3⊃RESULT
[12] :Else
[13] ⍝ 2 Expression with a result which would not display
[14] ⍝ 3 Expression with no explicit result
[15] ⍝ 4 Branch to a line
[16] ⍝ 5 Naked branch
[17] A.Text←''
[18] :End
∇
∇R←MAKEVEC B
[1] ⍝ Given a character array, ensure it's a text vector
[2] ⍝ If matrix or higher rank, make into CRLF-delimited vector
[3] :If 2>⍴⍴B
[4] R←B
[5] :Else
[6] R←⎕R ⎕BOX B
[7] :EndIf
[8] R←⎕SS R ⎕R(⎕R,⎕L)
∇
Example 2
This function shows a simple example of using the System.IO namespace to create a text file and write some text to it. On line [1], it sets up the search path for .Net classes. Lines [2] and [3] fetch the FileMode and FileAccess enumeration types, which are then used in line [5].
∇FileWrite;sw;MyFile;FileMode;FileAccess;DateTime
[1] '.net' ⎕SETUP 'using' 'System' 'System.IO'
[2] FileMode←'.net' ⎕GETCLASS 'FileMode'
[3] FileAccess←'.net' ⎕GETCLASS 'FileAccess'
[4] DateTime←'.net' ⎕GETCLASS 'DateTime'
[5] MyFile←'.net' ⎕NEW 'FileStream' 'c:\temp\testdotnet.txt'
(FileMode.OpenOrCreate) (FileAccess.ReadWrite)
[6] sw←'.net' ⎕NEW 'StreamWriter' MyFile
[7] sw.Write 'Written from APLX',⎕R,⎕L
[8] sw.Write 'Created by APLX Version 4 at ',DateTime.Now.ToString
[9] sw.Close
[10] MyFile.Close
∇