IDMApplication2 Interface

Version: 2.0
Dispatch interface for DMApplication Object

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

IDMApplication2 interface implemented only for backward compatibility with earlier versions of DM2003. 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
IsCommandAvailable 101 Determine whether given command is supported
ShowDialog 102 Show dialog box or window
Browser 103 Returns Browser Application interface
GetActiveControl 104 Returns active (focused) control
ShowProgressHint 105 Display operation progress hint in statusline
Insert 106 Change Insert/Overwrite flag
Table 107 Calibration table
History 108 Expression history list
Parse 109 Parse expression and return the result
LoadDesktop 110 Load desktop file
SaveDesktop 111 Save desktop file
Version 112 Return dm2003.exe file version
ShowHelp 113 Display online help article
ExpSettings 114 Change experimental hardware settings
_NewEnum -4 Return Documents enumerator object

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.

Syntax:
r/o property IsCommandAvailable[Name]: Boolean

Applies to:
DMApplication, DMInternalApplication

Use this parameterized property to determine whether given command is available for IsCommandXXX properties and ExecuteCommand method or not. This feature helps you to ensure compatibility. See also the list of standard action names.

Syntax:
function ShowDialog(Name, Arguments): Variant

Applies to:
DMApplication, DMInternalApplication

This method is very important. It allows you to display your own dialog boxes (both modal and modeless) with arbitrary user interface as well as several predefined (hardcoded) dialogs. This feature allows you to take arbitrary input from user in the natural manner, and without reloading MiniBrowser.

See source code of scripts supplied with the DM2003 for numerous examples and several code snippets listed below:

Examples:

' html dialog box 
sub doHTML
dim Args(2), Result
  Args(0)="about:My test dialog" ' url of the page
  Args(1)=hdoModal ' options (see HTMLDialogOptions enumeration)
  Args(2)=0 ' input argument(s)
  ' Args(2) may be modified from within the html document 
  ' using r/w window.external.Arguments property
  ' Also available: window.external.Close method
  ' r/o window.external.Server property (DM application)
  ' r/w window.external.IsVisible property (modeless dialogs only)
  Result=Server.ShowDialog("HTMLDialog", Args) ' returns Args(2)
  ' Note: for modeless dialogs, reference to the Browser object returned!
end sub

' input box
sub doInput1
dim Args(1) 
  Args(0)="Default value" 
  Args(1)="Prompt:"
  if Server.ShowDialog("InputBox", Args) then ' cancelled?
    MsgBox Args(0) ' Yes clicked, return value
  end if
end sub

sub doInput2 ' if cancelled, returns empty string
  MsgBox Server.ShowDialog("InputBox", "Prompt:")
end sub

' File Open dialog
sub doFileOpen
dim FN
  FN="*.txt"
  FN=Server.ShowDialog("OpenFile", FN)
  MsgBox FN
end sub

' File Save dialog
sub doFileSave
dim FN
  FN="Save My file:"
  FN=Server.ShowDialog("SaveFile", FN)
  MsgBox FN
end sub

' Select Directory
dim Path
Path=""
sub doSelectDirectory
dim p
  P=Server.ShowDialog("SelectDirectory", Array("Select:", Path))
  if P<>"" then Path=P : MsgBox P
end sub

sub doSelectDirectory_js_style
  MsgBox Server.ShowDialog("SelectDirectory", "Select:")
end sub

' Select Color dialog
sub doColor
dim C
  C=255 ' red
  if Server.ShowDialog("Color", C) then
    MsgBox C
  end if  
end sub

' HTML text editor (plot labels etc.)
sub doHTMLText
dim s
  s="qwerty"
  if Server.ShowDialog("htmltext", s) then MsgBox s
end sub

' advanced version (with font and background color)
sub doHTMLText2
dim A(2), Document
' prepare window
  set Document=Server.CreateDocument("")
  Document.WindowState=1
  Document.Plot.Color=8454118
  Document.Plot.YAxis.Title="Qwerty"
  A(0)=Document.Plot.YAxis.Title
  A(1)=Document.Plot.Color
  set A(2)=Document.Plot.YAxis.Font ' notice: SET!
  if Server.ShowDialog("htmltext", A) then
    Document.Plot.YAxis.Title=A
  end if
end sub

' Show DM2003 floating point numbers precision
Server.ShowDialog "aboutbox", "precision"

' undock Notes window 
Server.ShowDialog "NotesForm", array(400,400,800,600)
' dock Notes window 
Server.ShowDialog "NotesForm", "RightDockPanel"
Server.ShowDialog "NotesForm", "LeftDockPanel"
Server.ShowDialog "NotesForm", "BottomDockPanel"
' show Notes window
Server.ShowDialog "NotesForm", -1
' hide Notes window
Server.ShowDialog "NotesForm", false

Syntax:
r/o property Browser: IDispatch

Applies to:
DMApplication, DMInternalApplication

Returns reference to the MiniBrowser Application interface. Use Microsoft documentation for more information.

Example:

Server.Browser.Navigate "about:mozilla"

Syntax:
function GetActiveControl: User_Defined

Applies to:
DMApplication, DMInternalApplication

Returns one of the values listed in the ActiveControlTypes enumeration depend on active visual control. This method is very important since a lot of operations in the DM2003 are polymorphic - the same operation acts in the similar way on different objects. A good example are editing commands.

Syntax:
function ShowProgressHint(Hint, ImageIndex): VOID

Applies to:
DMApplication, DMInternalApplication

This method is an enhancement of the DisplayHint method. It displays hint text and appropriate image in the statusbar, and in addition change cursor to the "Hour Glass". Pass empty hint to restore statusbar and cursor.

Example:

call Server.ShowProgressHint("Operation in progress...", 8)
' perform time-consuming calculations
' display calculations progress using ShowProgress method
call Server.ShowProgressHint("", 0)

Syntax:
property Insert: Boolean

Applies to:
DMApplication, DMInternalApplication

Syntax:
r/o property Table: IDispatch

Applies to:
DMApplication, DMInternalApplication

Returns reference to the DMContainer object that represents system calibration table. This is invisible container component that is not associated with any data window. It is used by embedded Table() function.

Syntax:
r/o property History: IDispatch

Applies to:
DMApplication, DMInternalApplication

Returns reference to the DMStrings object that represents expression history list. This list is remembered in the registry so that you don't need to type long strings again and again.

Syntax:
function Parse(Arguments, Expression): Double

Applies to:
DMApplication, DMInternalApplication

Parse() method performs expression evaluation using language-independent expression parser. Expression parameter is a string composed of function and parameter names and operators. Arguments parameter is a variant array of 28 double precision numbers, which represents parameter values. Array layout is as follows: cx, cy, a, b,...z. See also the list of available function and parameter names.

You can also pass in the Arguments parameter a string of up to 26 values delimited by spaces (first 2 values assigned to cx and cy, others to a..x), or any single numeric value (which is assigned to cx parameter).

Examples:

dim A(27)
A(0)=1.25 ' cx parameter
A(2)=4    ' "a" parameter
MsgBox Server.Parse(A, "(cx*a-2)^2")

S="1.23"
MsgBox Server.Parse(S, "cx*2") ' 2.46

S="1.2 3.4 5"
MsgBox Server.Parse(S, "cx+cy-a") ' -0.4

F=2.22
msgbox Server.Parse(F, "cx/2") ' 1.11

Syntax:
function LoadDesktop(FileName): VOID

Applies to:
DMApplication, DMInternalApplication

Syntax:
function SaveDesktop(FileName): VOID

Applies to:
DMApplication, DMInternalApplication

Syntax:
r/o property Version: BSTR

Applies to:
DMApplication, DMInternalApplication

Version property just returns DM2003.EXE file build. It may be used to ensure compatibility.

Example:

Function GetVersionInfo
Dim s
  s="Data Master Version " & Server.Version 
  s=S & vbCrLf & ScriptEngine & " Version "
  s=s & ScriptEngineMajorVersion & "."
  s=s & ScriptEngineMinorVersion & "."
  s=s & ScriptEngineBuildVersion 
  GetVersionInfo=s ' Return the results.
End Function

Syntax:
function ShowHelp(Context): VOID

Applies to:
DMApplication, DMInternalApplication

Use ShowHelp method to display help topics in the DM2003 standard Help Viewer window. You can either show files inside DM2003.CHM or navigate Viewer to the URLs of other local and remote files.

Examples:

Server.ShowHelp "pgmguide" ' a topic in DM2003.CHM

Server.ShowHelp "http://www.datamaster2003.com/welcome.html"

Server.ShowHelp "file:///c:\windows\setuplog.txt"

Server.ShowHelp "mk:@MSITStore:c:\WINDOWS\Help\" & _ 
  "calc.chm::/calc_simple.htm" ' topic from other CHM

Server.ShowHelp "c:\WINDOWS\Help\calc.chm" ' in new Viewer

Syntax:
property ExpSettings: BSTR

Applies to:
DMApplication, DMInternalApplication

Property ExpSettings should be used by experimental program to pass its settings to the MetaBase property pages. As a best practice, update this property every time when you change something in the experimental program configuration.

Syntax:
r/o property _NewEnum: Unknown

Applies to:
DMApplication, DMContainer, DMInternalApplication, DMLabels, DMListItems, DMNotes, DMPlot, DMStrings

This property returns so-called Enumerator Object. Do not use it explicitly. It is used internally in the "for each [item] in [object]" cycles. Every object that has this property may be enumerated in such a cycles. This is for your convenience.

Examples:

function EnumDocuments
dim S
  S=""
  for each Doc in Server
    S=S & Doc.WindowCaption & vbCrLf
  next
  EnumDocuments=S  
end function

function EnumNotes
dim S
  S=""
  for each Ss in Server.Notes
    S=S & Ss & vbCrLf
  next
  EnumNotes=S  
end function

function EnumSeries
dim S
  S=""
  for each Ser in Server.ActiveDocument.Plot
    S=S & Ser.Text & vbCrLf
  next
  EnumSeries=S  
end function

function EnumItems
dim S
  S=""
  for each D in Server.ActiveDocument.Container
    S=S & D(0) & vbCrLf
  next
  EnumItems=S  
end function