Using OLE (COM) Server Applications

The third use of OLE automation is to link to an external server application. This is somewhat similar to embedding a document in an OLEContainer, but the application runs independently of APLX and is not associated with one of your windows. It may not even be visible. For example, you could invoke Word, cause it to load a document, and extract the text from the document, without the user being involved.

Using an OLE (also known as COM) Server Application is very similar to the previous examples, except that you create the object as a top-level object, using the external class name (as returned by the oleclasses property) as the APLX class name.

For example, this function invokes Excel and retrieves a spreadsheet as a nested array (see the workspace 10 SAMPLESEXCEL for more examples):

      ∇R←GetSpreadsheet SHEETNAME;ROWS;COLS;COLNAMES;⎕IO
[1]  ⍝
[2]  ⍝ APLX for Windows OLE Example:
[3]  ⍝     Get an Excel spreadsheet as a nested array
[4]  ⍝
[5]  ⍝
[6]   ⎕IO←1
[7]  ⍝
[8]  ⍝ Launch Excel 
[9]  ⍝ Because 'Excel.Application' is not an APLX class, it looks for a server
[10]  XL←'⎕' ⎕NEW 'Excel.Application'
[11] ⍝
[12] ⍝ In this example we don't want to see Excel. It runs in the background
[13]  XL.visible←0
[14] ⍝
[15] ⍝ Open specified spreadsheet
[16]  R←XL.Workbooks.Open SHEETNAME
[17] ⍝
[18] ⍝ Get number of rows and columns
[19]  ROWS←XL.Activesheet.UsedRange.Rows.Count
[20]  COLS←XL.Activesheet.UsedRange.Columns.Count
[21] ⍝
[22] ⍝ Get column names. They are called, A B C..Z AA AB AC..AZ BA BB, etc
[23]  COLNAMES←GetColumnNames COLS
[24] ⍝
[25] ⍝ Read all data into APL nested array
[26]  R←XL.name ⎕WI 'Range().Value' ('A1:',(⊃COLNAMES[COLS]),⍕ROWS)
[27] ⍝
[28] ⍝ Ask Excel to quit (reference localized, so reclaim memory at end) 
[29]  XL.Quit
      ∇

Line 26 of the above function is an example of reading an Array Property, where the parentheses are used to tell APLX that the parameter (in this case a string containing the cell range) should be used to select the particular property required.

Using references to returned objects

The APLX OCX interface allows you to use numeric 'LPDISPATCH' handles which may be returned by some OCX/ActiveX controls or OLE Servers. This usually applies in the case where you create a new object in the external control, and need some way to refer to it. Windows returns a 'handle', which in APL is represented as an integer. You can use the text representation of the integer as part of a hierarchical property or method name to access the newly-created object.

For example, you can create a new Word document using the Add method of the Word application. This returns a handle. In APLX, you can use this as follows:

      W←'⎕' ⎕NEW 'Word.Application'
      MYDOC←⍕'W' ⎕WI 'Documents.Add'
      MYDOC
1797860
      'W' ⎕WI MYDOC,'.Words.Count'
1