Drittentwicklermodule – Mercury

Mercury

Introduction

Mercury consists of a set of functions that provide an interface with GAUSS and the GAUSS Engine. These function permit sending strings, values and data from the external application to GAUSS, running GAUSS code or procedures, and returning the data back to the external application. Thread control is explicitly supported.
Mercury_Gauss requires Gauss for Windows 3.5 or higher.
Mercury_GE requires the Gauss Engine for Windows 4.0 or higher.
Mercury has four main components:

An Excel Addin that links an Excel Workbook to GAUSS. Data is sent to GAUSS, where it is processed, and the results are returned to the specified cells in the spreadsheet. Excel 95, 97, 2000 and XP are supported.

A library of interface functions for developers who need to link GAUSS to an external application using custom interfaces. Sample example code is provided for VB and C++ applications.

Windows clipboard support for GAUSS.

A demonstration project showing how Gauss compliant DLLs Anker auf folgende Überschrift are created.

Demonstration projects for Excel, VB, C and MFC applications are included which show how these calls are implemented.

 Excel Addin

The Excel Addin consists of a set of VBA functions that can be called from Microsoft Excel, either as a function directly from a worksheet, or as part of a macro. The Mercury Addin for Excel makes it simple to send complete data sets from Excel to GAUSS for analysis, and to retrieve the results back in to your Excel worksheet. From the user's point of view, it appears that Excel has suddenly gained an entire set of new functionality - that of GAUSS - but with an additional twist. You no longer wait while Excel computes. Rather, all the power, speed, depth and accuracy of GAUSS is a macro away.

The following code provides a simple example of how one would write a VBA macro in Excel to do something trivial - raise each element of a spreadsheet array to some power.

  1. Sub gausstest()
  2. Sheets("sheet1").Select
  3. mercury.load
  4. ge.WorkspaceCreate
  5. ge.RangePut "a3:c6", "x"
  6. ge.ExecCode "z = x^2; "
  7. ge.RangeGet "e3","z"
  8. End Sub

The macro consists of a sub called gausstest. The worksheet (sheet1) contains the input data, and this sheet is made the active sheet in line 2. An instance of the Mercury class (ge) is created in line 3. The array in a3:c6, which is the data that we are interested in using, is copied to GAUSS and stored with the name x using the RangePut command in line 5. The operation

           z=x^2;

is carried out using GAUSS in the command ExecCode shown in line 6. This creates the matrix z, which is retrieved into the worksheet using the RangeGet command in line 7, with the (1,1) element occurring at e3.
This example portrays one of the simplest ways of running GAUSS commands; that is, by embedding them as string arguments to the ExecCode command within an Excel macro. The string can contain a number of GAUSS commands, or the name of a GAUSS command file, or even a worksheet range containing GAUSS commands. GAUSS library functions are available as usual. The addin can be used as a macro - as shown above, or as an Excel function.
Hence all the power of GAUSS is available for mathematical computation and analysis, while the spreadsheet provides the advantages of data presentation and charting. The net effect is to have the functionality of GAUSS within Excel. The Mercury Addin also provides a link to the Mercury reference file on the Excel Tools menu.

Interface Tools

Mercury consists of a set of functions that enable programmers to interact with GAUSS or the Gauss Engine, as part of an external application. This enables programmers to make use of the power of GAUSS as part of an integrated system in which data and message transfer to and from GAUSS is required, and which is to be controlled by an external application. Support files for these libraries are provided for Excel, Visual Basic, C++ and MFC.

The GAUSS programming language lets you express in a couple of statements what would take many pages of custom written code. You simply embed complete GAUSS programs in your application, or permit access to GAUSS through your GUI.

The Mercury routines are provided as a class. Mercury is instanced (in C) with the statement:

           Mercury         ge;

Now, typing    ge.   results in a drop down menu of all the available methods - this makes programming very easy.



A typical Mercury session might send data from an application to GAUSS, using the MatPut command, running GAUSS commands using the ExecCode command, and retrieving results back to the application using the MatGet command. These libraries permit sending messages, strings, values and data between the external application and GAUSS, as well as routines for status checking status. This idea is shown in the Visual Basic screen shot. The core VB routines for this application for Mercury for Gauss are shown below:

 

  1. xname = inputname.Text
  2. zname = outputname.Text
  3. ge.MatPut xname, xmat
  4. ge.Exec Editbox.Text
  5. ge.MatGet zname, zmat()



Lines 1 and 2 pick up the name of the input and output matrices from two text boxes. The array xmat is stored in GAUSS using the MatPut command, and the GAUSS code in the Editbox is executed using the Exec command; this creates the variable zname, which is retrieved back into the application using the MatGet command.




A second example, using Mercury_GE is shown in the accompanying screen shot. This example was generated using VC. The MFC code is shown below:

  1. Mercury GE;
  2. GE.WorkspaceCreate();
  3. GE.ExecCode(m_code.GetBuffer(2048));
  4. GE.ArgListCreate(ahin);
  5. GE.ValPut(variance,1);
  6. GE.ThreadBegin("betahat",1);
  7. for (ahout = 1; ahout < rep+1; ahout++)
  8. GE.ExecProc("olssim", ahin, ahout);
  9. GE.ThreadEnd();

The code is executed when the Execute button is clicked. Line 1 creates an instance of the Mercury class called GE. A default workspace #1 is created in line 2 (Mercury allows for 64 separate workspaces). The GAUSS code for the "olssim" procedure, which is stored in the CString m_code is executed in line 3, so now workspace #1 has the proc olssim as a global. The GAUSS Engine allows for variables to be stored as globals in a given workspace, or as arguments in an argument list. Line 4 creates an argument list with the identifier (number) ahin, and makes it current. Line 5 places the variable variance as the first argument of the current argument list. Line 6 instructs Mercury that the following Gauss code is to be executed as separate threads, and to store the first output argument of each thread in betahat. These threads will occur concurrently, and can use multiple CPUs, if available. The "olssim" proc is executed rep times, with a new output argument ahout in each case. Line 10 informs Mercury to wait until all the threads are complete (joined). Subsequent code shows the output of each thread, and undertakes the analysis of betahat. Mercury permits the programmer to use the multithreading capability of the GAUSS Engine with a very shallow learning curve.

Libraries have been included for VB and C++; however, the code can be ported to any program that can access the Windows APIs -- for example, Toolbook, Delphi, Powerbuilder, etc. The code and DLL files are provided for use in your application under the same distribution rights as you have for the Gauss Engine. They can also be distributed, as part of an application. to any registered Gauss user. Mercury_GE also provides support for the Gauss Run Time Engine.

Clipboard Support

Mercury provides a means of communicating data or strings between GAUSS and the Window clipboard. For example, a section of a spreadsheet could be selected and copied to the clipboard in the usual fashion. This data could then be pasted directly into a GAUSS matrix (x) using the command:

               ge.ClipboardPaste("x");

Similarly, a GAUSS matrix, x, could be copied to the clipboard using the command:

               ge.ClipboardCopy("x");

x could then be pasted into a spreadsheet or word-processor. For the former, if x were an n by k matrix, then the spreadsheet array would also be n rows by k column. For the word-processor, the matrix has the form of tab delineated elements, again with n rows and k columns.

Mercury for GAUSS permits direct interaction between GAUSS and the clipboard:

               library mercury;
               x = rndu(3,2);
               copy(x);

copies the GAUSS matrix, x, to the clipboard, and

               z = paste;

creates the matrix or string z based on the contents of the clipboard.

Creating Gauss Compliant DLLs

Extensions to the GAUSS language is possible through custom DLLs. In effect, any code that one can write in C can become a GAUSS procedure. Not only does this provide for really fast DO loops, but it also gives the programmer low level control over the operating system through the Windows APIs. In effect, this makes GAUSS an open system. For example, the interface between GAUSS and Mercury rely on these extensions. A demonstration DLL project -- Testdll -- shows how such C code is written, and a step by step tutorial on how to create your own DLLs, running under Microsoft VC++, is also provided.

Zurück zum Seitenanfang

© ADDITIVE GmbH. Alle Rechte, Irrtümer und Änderungen vorbehalten.

Impressum  /  Datenschutz  /  AGB