IDMApplication Interface

Version: 1.1
Dispatch interface for DMApplication Object

GUID: {673A9FC1-9A0B-11D4-B2A4-FD6847C75367}

IDMApplication interface implemented only for backward compatibility with DM2000. Use IDMApplication3 interface instead.

Members:
Kind Name ID Description
DocumentCount 1 Return MainForm.MDIChildCount
Documents 2 Return IDMDocument for MainForm.MDIChildren[]
ActiveDocument 3 Return IDMDocument for MainForm.ActiveDataForm
DisplayMessage 4 Display message in main form statusline
RecordPoint 5 Invoke MainForm.RecordPoint()
ExecuteCommand 6 Invoke (Name as TAction).Execute
IsCommandVisible 7 Change (Name as TAction).Visible
IsCommandEnabled 8 Change (Name as TAction).Enabled
IsCommandChecked 9 Change (Name as TAction).Checked
SetExpSettings 10 Invoke MainForm.SetExpSettings()
CreateDocument 11 Create DataForm: empty, from file or template
ShowProgress 12 Show operation progress in MainForm.ProgressBar
DisplayHint 13 Display hint in statusline
Notes 14 Return IDMNotes
LMFit 15 Perform Levenberg-Marquardt fitting
LinearFit 16 Perform linear fitting

Syntax:
r/o property DocumentCount: Long

Applies to:
DMApplication, DMInternalApplication

Returns number of opened document windows. Use this property to determine whether active data window exists or not.

Example:

if Server.DocumentCount>0 then
  ' access Server.ActiveDocument
else
  ' no active documents
end if

or

MsgBox Server.DocumentCount

Syntax:
r/o property Documents[Index]: IDispatch

Applies to:
DMApplication, DMInternalApplication

Provide access to collection of DMDocument objects. Index range from 0 to DocumentCount-1 (Example 1). Note that you can also get access to the list of data windows using Application object as a collection (see Example 2).

Example 1:

for I=0 to Server.DocumentCount-1
  ' do something with data windows
  Server.Documents(I).WindowCaption="Window #" & I
next

Example 2:

for each Doc in Server
  ' do something with data window
  Doc.WindowCaption="My Window"
next

Syntax:
r/o property ActiveDocument: IDispatch

Applies to:
DMApplication, DMInternalApplication

Return DMDocument object for active document window. You may also check DocumentCount property to determine whether active document exists or not.

Example:

if not (Server.ActiveDocument is Nothing) then
  ' do something with active data window
  Server.ActiveDocument.WindowCaption="My New Window"
end if

Syntax:
function DisplayMessage(Msg): VOID

Applies to:
DMApplication, DMInternalApplication

Displays message in the statusline and plays system sound. The message will disappear automatically in seconds. Use this method to attract user's attention.

Notice that if toolbar picture is visible, and your OS version is greater than 5 (Windows2000 and later), DM2003 displays message text in the balloon tooltip instead of statusline.

Warning: if neither toolbar picture nor statusline is visible, nothing will be displayed by this method!

Example:

Server.DisplayMessage "My test message"

Syntax:
function RecordPoint(Labels, Values): VOID

Applies to:
DMApplication, DMInternalApplication

This method allows experimental program to record data point into first document window whose IsRecording property is set to true. It also automatically update worksheet column labels, scroll worksheet to end line and plot new point. Labels and Values may be strings or arrays. Instead of RecordPoint() you may decide to use DMDocument properties directly for full control of visualization process.

Example:

dim Labels(1), I
I=0
Labels(0)="X"
Labels(1)="Y=X^2"

sub Test
dim Values(1)
  Values(0)=I 
  Values(1)=I^2 
  I=I+1
  call Server.RecordPoint(Labels, Values)
end sub

Syntax:
function ExecuteCommand(Name): VOID

Applies to:
DMApplication, DMInternalApplication

Almost any action invoked from UI controls (menu or toolbar) may be performed programmatically by its name (note: name is not the same as caption!). You may test IsCommandAvailable() property to ensure that appropriate action is supported. See also the list of standard action names.

Another tip: in the HTML pages, you may invoke actions using "DM:" pseudoprotocol.

Examples:

VBScript:
Server.ExecuteCommand "NewAction"

HTML:
<a href="DM:NewAction">New Action</a>

Syntax:
property IsCommandVisible[Name]: Boolean

Applies to:
DMApplication, DMInternalApplication

Change visibility of UI controls associated with defined action. See also the list of standard action names.

Syntax:
property IsCommandEnabled[Name]: Boolean

Applies to:
DMApplication, DMInternalApplication

Enable or disable UI controls associated with defined action. See also the list of standard action names.

Syntax:
property IsCommandChecked[Name]: Boolean

Applies to:
DMApplication, DMInternalApplication

Check or uncheck UI controls associated with defined action. See also the list of standard action names.

Syntax:
function SetExpSettings(Settings): VOID

Applies to:
DMApplication, DMInternalApplication

This function is only for backward compatibility. Use ExpSettings property instead.

Syntax:
function CreateDocument(FileName): IDispatch

Applies to:
DMApplication, DMInternalApplication

Creates data window and returns reference to its DMDocument object. If FileName parameter is empty, this method creates empty window. If you specify non-empty file name, you can load appropriate data file or create new window from template (if filename extension is *.dmw).

Notice: as of build #300, FileName parameter may be an URL. So that, you can can download data files located on the Internet/Intranet, or use remote templates.

Syntax:
function ShowProgress(Progress): VOID

Applies to:
DMApplication, DMInternalApplication

Display progress of time-consuming operations in the progress bar. Available only from in-process scripting (like script window). Progress parameter must vary from 0 to 100. Values of 0 or 100 also hide progressbar.

Notice: on Windows Vista and newer OS versions, windows manager implements more aggressive monitoring of the message pump, so that any painting operations are blocked after ~5 seconds and ghost window with "not responding" title bar is created. DM2003 calls DisableProcessWindowsGhosting() so that progress bar is always operable. It is highly recommended to call ShowProgress method in all operations that may take significant time to complete and cannot be interrupted. Otherwise, use ProcessMessages method to enable normal message pumping cycle.

Syntax:
function DisplayHint(Hint): VOID

Applies to:
DMApplication, DMInternalApplication

Display hint in the hint area of status line. Use Script Editor (invoke Script|Dispatch command or compile the example code) to play with hints.

Example:

Server.DisplayHint "My test hint"

Syntax:
r/o property Notes: IDispatch

Applies to:
DMApplication, DMInternalApplication

Returns reference to DMNotes object.

Syntax:
function LMFit(X, Y, W, WType, Expression, Params, Sigma, NIter, ChiSqr, ResultCode): VOID

Applies to:
DMApplication, DMFitter, DMInternalApplication, LMFitter

In DM2003, this method performs up to NIter Levenberg-Marquardt iterations, actual number of iterations returned in this parameter. X, Y - variant arrays with curve to be fitted; W - point weights (also variant array). WType must be one of values in the WeightType enumeration.

Expression includes all standard functions (see the list of available functions), independent variable is named CX, parameters are named p1, p2, etc. Initial parameter values passed in the Params array, and any parameter may be fixed if you set corresponding Sigma[] value to -1, otherwise Sigma[] must be 0. The number of parameters in the Expression must be equal to the size of Params and Sigma arrays. After all iterations are completed, you should read parameters from Params array, their deviations from Sigma array, Chi2 and result code from appropriate parameters. Result codes defined in the FitResult Enumeration.

In addition, Expression may be also an object that implements two methods for calculating function and derivative. This feature may remarkably improve fitter performance. Method signatures must be exactly as shown in the Example 2 (see below).

There is an useful option: you may allocate exactly 3 extra numbers in the Sigma array for additional ParDel, ChiDel and Deriv parameters. First two determine Parameters and Chi2 convergence thresholds, and third (Deriv) used to calculate numeric derivative for Expression.

Example 1:

dim X(999), Y(999), Params(3), Sigma(3), NIter, ChiSqr, ResCode 
' initialize X, Y input vectors
for I=0 to UBound(X)
   X(I)=I
   Y(I)=12.345 + 3*I -0.2*I^2 + 0.045678*I^3
next
' initialize parameters and deviations
for I=0 to 3
  Params(I)=1
  Sigma(I)=0 
next
NIter=30
' perform fitting (point weights are not used)
call Server.LMFit(X, Y, 0, 0, "p1+p2*cx+p3*cx^2+p4*cx^3", _
  Params, Sigma, NIter, ChiSqr, ResCode)
' display result
S=""
for I=0 to 3
  S=S & Params(I) & vbCrLf
next
MsgBox S

Example 2:

' hardcoded polynomial fit
class MyFitterClass

  function CalculateFunction(X, Params)
    CalculateFunction=Params(0)+Params(1)*X+Params(2)*X^2+Params(3)*X^3
  end function

  function CalculateDerivative(X, Params, Sigma)
  dim Result(3)
    Result(0)=1
    Result(1)=X
    Result(2)=X^2
    Result(3)=X^3
    CalculateDerivative=Result
  end function

end class

dim F
set F=new MyFitterClass

sub RunFitting
dim X(999), Y(999), Params(3), Sigma(3), NIter, ChiSqr, ResCode 
' initialize X, Y input vectors
  for I=0 to UBound(X)
     X(I)=I
     Y(I)=12.345+3*I-0.2*I^2+0.045678*I^3
  next
' intialize parameters and deviations
  for I=0 to 3
    Params(I)=1
    Sigma(I)=0 
  next
  NIter=30
' perform fitting (point weights are not used)
  call Server.LMFit(X, Y, 0, 0, F, Params, Sigma, NIter, ChiSqr, ResCode)
' display result
  S=""
  for I=0 to 3
    S=S & Params(I) & vbCrLf
  next
  MsgBox S
end sub

For DMFitter ActiveX control, function LMFit invokes non-linear (Levenberg-Marquardt) fitter. It has no parameters. The returned value is True if fitting session was successful; otherwise it returns False. You can obtain more details from ResultCode property. Before you call LMFit, you must initialize following properties: X, Y, Expression, ParamCount, Parameters, Sigmas, Iterations and WeightType. In addition, you can initialize following properties: Weight and Options. After fitting you can obtain results from the following properties: Parameters, Sigmas, Iterations, Deviation and ResultCode.

Notice that unlike linear fitter, LM fitting is iterative procedure by its nature and may take a lot of time, especially for large number of parameters and complex expressions.

Syntax:
function LinearFit(X, Y, NumTerms, BasisType, Solution, Deviation, ResultCode): VOID

Applies to:
DMApplication, DMFitter, DMInternalApplication, LMFitter

In DM2003, Linear fitting is not so interesting as LM, but in some cases it may be more suitable. One of its main advantages is speed: linear fitting does not require iterative calculations. X,Y arrays are curve to be fitted, NumTerms and BasisType define fitting expression, parameter values returned in Solution array.

Example:

function LinFit(BasisType, NumTerms)
dim X,Y,NumPoints,Solution,Deviation,ResCode
dim I,FL,Ser,Cont,CX,CY,D,S

set Ser=Server.ActiveDocument.Plot.CurrentSerie
set Cont=Ser.Container
FL=Ser.FirstLine
NumPoints=Ser.LastLine-FL+1
CX=Ser.XColumn-1
CY=Ser.YColumn-1
ReDim X(NumPoints-1)         ' Redim(upper index=np-1!)
ReDim Y(NumPoints-1)

for I=1 to NumPoints         ' copy data being fitted
  D=Cont.Items(FL+I-1)
  X(I-1)=D(CX)
  Y(I-1)=D(CY)
next

call Server.LinearFit(X,Y,NumTerms,BasisType,Solution,Deviation,ResCode)

S=""
for I=1 to NumTerms
S=S & "Coef[" & I & "]=" & Solution(I-1) & vbCrLf
next

S=S & "Rescode=" & ResCode & vbCrLf & "Deviation=" & Deviation
LinFit=S

end function

sub FitTest
  Server.Notes.AddLine "======================================="
  Server.Notes.AddLine(LinFit(1,3))
end sub

In DMFitter ActiveX control, function LinearFit invokes linear fitter. It has no parameters. The returned value is True if fitting session was successful; otherwise it returns False. You can obtain more details from ResultCode property. Before you call LinearFit, you must initialize following properties: X, Y, Expression and ParamCount. After fitting you can obtain results from the following properties: Parameters, Deviation and ResultCode.