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:

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:

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:

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
      ’

Topic: APLX Help : Interfacing to other languages : Interfacing to .Net
[Next | Previous | Contents | Index ]