Intro to Dev Ref

Welcome!

Welcome to the Developer's Reference. These pages are designed to help you, the advanced Mathcad user, customize Mathcad for use as an integral component of your engineering, business, and applied math solutions. This reference assumes that you are familiar with a supported scripting language, such as VBScript or JScript. You will find information regarding Scriptable Object components, including customized scripted objects that come preloaded in Mathcad, Mathcad's Object Model, and OLE Automation. Topics include:

  • Information for creating a user DLL.

  • Classes, methods, properties, and events associated with the Data Acquisition control (DAC).

  • Methods, properties, and events associated with MathSoft Custom controls.

  • Methods, properties, and events exposed for scripts written with the Scriptable Object component, including script examples.

  • Methods and sample scripts for accessing Mathcad from within other applications that support OLE Automation.

  • Information for using the Mathcad Component Wizard.

For convenience, script examples in each section use VBScript style syntax unless otherwise noted. For sample worksheets that demonstrate use of customized scripted objects, see the SAMPLES directory of your Mathcad installation.


Introduction to Creating a User DLL

Extend Mathcad's power by writing your own customized functions. Your functions will have the same advanced features as Mathcad built-in functions, such as customized error messages, interruption, and exception handling in case of overflow and divide by zero. Your functions will appear in the Insert Function dialog box like all built-in functions. The functions may operate on complex scalars and complex arrays and they may return complex scalars, complex arrays, and error messages.

This section describes how to create 32-bit DLLs for Mathcad. The following topics make up this section:

Creating dynamically linked libraries

An overview of how to write your function and fill out the FUNCTIONINFO structure.

A sample DLL

A simple example of a user-created DLL with extensive comments. This sample can be used as a template for your own DLL.

Examining a sample DLL

A detailed examination of a simple example DLL, explaining the COMPLEXARRAY and COMPLEXSCALAR structures, error handling and function registration.

Handling arrays

Using the COMPLEXARRAY structure to handle arrays.

Allocating memory

Allocating and freeing memory.

Exception handling

How Mathcad traps the floating point exceptions.

Structure and function definitions

A reference guide to the structures and functions used.


Creating Dynamically Linked Libraries

To create customized functions, you will first need to create source code in C or C++, then compile the source code with a 32-bit compiler. Next, you will link the object files together with the MathSoft-provided MCADUSER.LIB library to create a DLL. Finally, you will place your DLL into the USEREFI subdirectory and add an entry to USER.XML so that your function appears in the Insert Function dialog box.


Writing your DLL Source Code

Provided below is an overview of the steps involved in creating a DLL. Refer to the rest of this appendix for specific details on how to perform each step.

Writing a DLL entry point routine

When you start Mathcad, it looks in the USEREFI directory for library files with a DLL extension. Mathcad then attempts to load all such files. During the loading process, your DLL must supply Mathcad with information about your library, including the names of the functions in the library, the types of arguments the functions take, the types of values they return, and the text of possible error messages. To supply this information, your DLL must have an entry point routine. A DLL entry point routine is called by the operating system when the DLL is loaded. Because the way to specify the DLL entry point routine is linker specific, refer to the README.TXT file in the compiler specific subdirectory of the USEREFI directory for linking instructions.

Registering your function

For each function in your library, there must be a FUNCTIONINFO structure. The FUNCTIONINFO structure contains the information that Mathcad uses to register a user function. FUNCTIONINFO structure is an argument of CreateUserFunction. A call to CreateUserFunction inside the DLL entry point routine registers your function with Mathcad.

Writing your function

You must, of course, write a C or C++ code that implements your Mathcad user function. The parameters of your C/C++ function are pointers to the return value and to the arguments. The C/C++ function returns 0 if successful, otherwise it returns an error code. The address of the C/C++ function is passed to Mathcad inside a FUNCTIONINFO structure. In this way, Mathcad knows to execute your code when the function is called from a Mathcad document. Refer to MyCFunction.

Error Handling

C/C++ functions which return error messages require an error message table in the DLL code. A call to CreateUserErrorMessageTable inside the DLL entry point routine informs Mathcad of the meaning of error codes returned by the C/C++ functions in the DLL.


Compiling and Linking your DLL

To create your DLL you will need a 32-bit compiler such as Microsoft Visual C++ 5.0, Borland C++ version 5.0, or Watcom C++ version 11.0 (of course, more recent versions of any of these compilers will work as well). Instructions on compiling and linking your DLL are given in the README.TXT file in the compiler specific subdirectory of the USEREFI directory for linking instructions. For more specific instructions on how to link and compile your source code, refer to the user guide provided with your compiler.


Making the Function Available through the Insert Function Box

Making the Function Available

In order to make a function appear in the Insert Function dialog box, you must provide information in the file USER.XML located in the subdirectory \DOC\FUNCDOC. Each function is an entry between <function> tag. Use the <name>, <category>, and <description> tags to specify the function name, its category, and its description as they should appear in the Insert Function dialog box. Between the <params> tag, indicate the parameters the function accepts. If you create a CHM Help file for your functions, use the <help_file> tag at the top of the XML file to provide the CHM filename. Use the <help_topic> tag between the <function> tag to specify the name of a help topic for a function.

See Providing Information for the Insert Function Dialog Box for a sample function entry.

Note:

  • Since Mathcad function names are case-sensitive, be careful to use the proper case when specifying the function name in the USER.XML file.


A Sample DLL

To get you started writing DLLs for Mathcad a number of code samples are included. The example given in the Sample Code topic is the file MULTIPLY.C located in the USEREFI\MICROSOFT\SOURCES\SIMPLE subdirectory.

The file contains a function that returns the result of multiplying an array by a scalar. This code implements the Mathcad user function multiply(a, M), which returns the result of an array M multiplied by a scalar a. For a complete examination of the source code, see Examining a Sample DLL.


Sample Code

#include "mcadincl.h"

#define INTERRUPTED 1
#define INSUFFICIENT_MEMORY 2
#define MUST_BE_REAL 3
#define NUMBER_OF_ERRORS 3

// tool tip error messages
// if your function never returns an error, you do not need to create this table
char * myErrorMessageTable[NUMBER_OF_ERRORS] =
{

"interrupted",.
"insufficient memory",
"must be real"

};

// this code executes the multiplication
// see the information on MyCFunction to find out more
LRESULT MultiplyRealArrayByRealScalar(

COMPLEXARRAY * const Product,
const COMPLEXSCALAR * const Scalar,
const COMPLEXARRAY * const Array )

{

unsigned int row, col;
// check that the scalar argument is real
if ( Scalar->imag != 0.0)

// if not, display “must be real” under scalar argument
return MAKELRESULT( MUST_BE_REAL, 1 );

// check that the array argument is real
if ( Array->hImag != NULL )

// if not, display “must be real” under array argument
return MAKELRESULT( MUST_BE_REAL, 2 );

// allocate memory for the product
if( !MathcadArrayAllocate( Product, Array-rows,Array-cols,

// allocate memory for the real part
TRUE,

// do not allocate memory for the imaginary part
FALSE ))&#9;

// if allocation is not successful, return with the appropriate error code
return INSUFFICIENT_MEMORY;

// if all is well so far, perform the multiplication
for ( col = 0; col < Product-> cols; col++ )
{

// check that a user has not tried to interrupt the calculation
if ( isUserInterrupted() )
{

// if user has interrupted, free the allocated memory
MathcadArrayFree( Product );

// and return with an appropriate error code
return INTERRUPTED;
}
for ( row = 0; row < Product-> rows; row++ )

Product->hReal[col][row] =

Scalar-> real*Array-> hReal[col][row];

}

// normal return
return 0;

}
// fill out a FunctionInfo structure with
// the information needed for registering the function with Mathcad
FUNCTIONINFO multiply =
{
// name by which Mathcad will recognize the function
"multiply",

// description of “multiply” parameters
"a,M",

// description of the function
"returns the product of real scalar a and real array M",

// pointer to the executable code
// i.e. code that should be executed when a user types in “multiply(a,M)=”
(LPCFUNCTION)MultiplyRealArrayByRealScalar;

// multiply(a, M) returns a complex array
COMPLEX_ARRAY,

// multiply(a, M) takes on two arguments
2,

// the first is a complex scalar, the second a complex array
{ COMPLEX_SCALAR, COMPLEX_ARRAY}
};

// all Mathcad DLLs must have a DLL entry point code
// the _CRT_INIT function is needed if you are using Microsoft's 32-bit compiler
BOOL WINAPI _CRT_INIT(HINSTANCE hinstDLL, DWORD dwReason, LPVOID lpReserved);
BOOL WINAPI DllEntryPoint (HINSTANCE hDLL, DWORD dwReason, LPVOID lpReserved)
{

switch (dwReason)
{

case DLL_PROCESS_ATTACH:

// DLL is attaching to the address space of the current process.
// the next two lines are Microsoft-specific
if (!_CRT_INIT(hDLL, dwReason, lpReserved))

return FALSE;

// register the error message table
// if your function never returns an error,
// you don't need to register an error message table
if ( CreateUserErrorMessageTable( hDLL,

NUMBER_OF_ERRORS, myErrorMessageTable ) )
// and if the errors register OK, register the user function
CreateUserFunction( hDLL, &multiply );

break;

case DLL_THREAD_ATTACH:
case DLL_THREAD_DETACH:
case DLL_PROCESS_DETACH:

// the next two lines are Microsoft-specific
if (!_CRT_INIT(hDLL, dwReason, lpReserved))

return FALSE;

break;

}
return TRUE;

}

#undef INTERRUPTED
#undef INSUFFICIENT_MEMORY
#undef MUST_BE_REAL
#undef NUMBER_OF_ERRORS


Compiling and Linking the Sample DLL

If you are using a Microsoft 32-bit compiler you can compile this file with the following command

cl -c -I..\..\include -DWIN32 multiply.c

This creates an object file MULTIPLY.OBJ. You can use the following command to link MULTIPLY.OBJ with the appropriate library and place MULTIPLY.DLL in the USEREFI directory.

link -out:..\..\..\multiply.dll -dll
-entry:"DllEntryPoint" multiply.obj
..\..\lib\mcaduser.lib

Check to make sure the MULTIPLY.DLL file is in the USEREFI subdirectory.


Providing Information for the Insert Function Dialog Box

In order to make the function and its description appear in the Insert Function dialog box, you must provide information in the file USER.XML located in the subdirectory \DOC\FUNCDOC. You can edit the XML file using a simple text editor such as Notepad or Wordpad. For this function, you can enter the following:

<function>
<name>
multiply
</name>
<params>
a, M
</params>
<category>
User defined
</category>
<description>
Returns the product of real scalar a and real array M
</description>

Save the file. Start Mathcad and verify that multiply appears in the Insert Function dialog box. You are now ready to use multiply in Mathcad.


Examining a Sample DLL

This section will examine the source code of the simple example in the previous section. Refer to the source code in the Sample DLL topic. Topics are as follows:

MyCFunction

COMPLEXSCALAR Structure

COMPLEXARRAY Structure

Error Messages

DLL Entry Point Function

FUNCTIONINFO Structure

Precision

mcadincl.h


MyCFunction

The heart of the program is MyCFunction, called MultiplyRealArrayByRealScalar function. It performs the actual multiplication. When the user types multiply(a,M)=, Mathcad executes the MultiplyRealArrayByRealScalar routine. The value of a is passed to the MultiplyRealArrayByRealScalar function in the Scalar argument. The value of M is passed in the Array argument. A pointer to the return value Product is the first argument of the MultiplyRealArrayByRealScalar function.


COMPLEXSCALAR Structure

The scalar value a is passed to the MultiplyRealArrayByRealScalar function in a COMPLEXSCALAR structure. The structure has two members, real and imag. The real part of a is stored in ScalarÞreal, the imaginary part in ScalarÞimag.


COMPLEXARRAY Structure

The array value M is passed to the MultiplyRealArrayByRealScalar function in a COMPLEXARRAY structure. The COMPLEXARRAY structure has four members, rows, cols, hReal, and hImag. The number of rows in M is found in ArrayÞrows, the number of columns is found in ArrayÞcols. The real part of the element Mrow,col is found in ArrayÞhReal[col][row] and the imaginary part in ArrayÞhImag[col][row]. If no element of M has an imaginary part, ArrayÞhImag is equal to NULL. If all elements of M are purely imaginary, ArrayÞhReal is equal to NULL.

The result of the multiplication of M by a is stored by the program in the COMPLEXARRAY structure pointed to by the argument Product. Note the memory for the multiplication result is allocated inside the MultiplyRealArrayByRealScalar function with a call to the MathcadArrayAllocate function.


Error Messages

If the multiplication was successful, MultiplyRealArrayByRealScalar stores the result in the COMPLEXARRAY structure pointed to by the argument Product and returns 0. In the case of an error, its return value has two components. One is the error code and the other is the location in which to display the error message.

Look at the error message table from the top of the file:

char * myErrorMessageTable[NUMBER_OF_ERRORS] =
{

"interrupted",
"insufficient memory",
"must be real"

};

The function MultiplyRealArrayByRealScalar returns MAKELRESULT(3,1) to display string number 3, “must be real,” under the first argument of multiply(a,M). If MathcadArrayAllocate is unable to allocate memory, MultiplyRealArrayByRealScalar returns 2 to display string number 2, “insufficient memory,” under the function name.

As shown in the sample DLL code, the following steps are involved in producing an error message:

  • creation of an array of error message strings.

  • registering the error message strings with Mathcad via a call to CreateUserErrorMessageTable. This call is made within the DLL entry point routine.

  • returning an appropriate error code from the user function.


DLL Entry Point Function

The DLL entry point is called by the operating system when the DLL is loaded. Mathcad requires that you register your user functions and your error message table while the DLL is being loaded. Note how this is done in the following code lines.

BOOL WINAPI DllEntryPoint (HINSTANCE hDLL, DWORD dwReason, LPVOID lpReserved)
{

switch (dwReason)
{

case DLL_PROCESS_ATTACH:

if ( CreateUserErrorMessageTable( hDLL,

NUMBER_OF_ERRORS, myErrorMessageTable ) )
// if the errors register OK, register user function
CreateUserFunction( hDLL, &multiply );

break;

case DLL_THREAD_ATTACH:
case DLL_THREAD_DETACH:
case DLL_PROCESS_DETACH:

break;

}
return TRUE;

}

CreateUserErrorMessageTable registers the error messages. CreateUserFunction registers the function. You can register only one error message table per DLL, but you can register more than one function per DLL.


FUNCTIONINFO Structure

The FUNCTIONINFO structure, multiply, is used for registering the DLL function with Mathcad. It contains information about the name by which Mathcad recognizes the function, the description of the function parameters, its arguments, its return value, and the pointer to the code which executes the function.

FUNCTIONINFO multiply =
{

"multiply",
"a,M",
"returns the product of real scalar a and real array M",
(LPCFUNCTION)MultiplyRealArrayByRealScalar;
COMPLEX_ARRAY,
2,
{COMPLEX_SCALAR, COMPLEX_ARRAY}

};


Precision

Data is passed between Mathcad and MyCFunction in double precision. Use the appropriate conversion inside MyCFunction for different data types.


mcadincl.h

MathSoft provides the mcadincl.h include file. This file contains the prototypes for the following functions:

CreateUserFunction
CreateUserErrorMessageTable
MathcadAllocate
MathcadFree
MathcadArrayAllocate
MyCFunction
MathcadArrayFree
isUserInterrupted

mcadincl.h also includes the type definitions for the structures COMPLEXSCALAR, COMPLEXARRAY, and FUNCTIONINFO.


Handling Arrays

If your function takes an array as its argument or returns an array, refer to The COMPLEXARRAY Structure. Note that the arrays are two-dimensional and the structure contains information about the size of the arrays and the pointers to the real and imaginary parts of the array. Refer to Allocating Memory for information on how to allocate memory inside COMPLEXARRAY structures.


Allocating Memory

The first argument of MyCFunction is a pointer to a return value. If it points to a COMPLEXARRAY structure, you will need to allocate memory for the members of this structure using MathcadArrayAllocate. If MyCFunction is returning an error, free the memory allocated for the return value using MathcadArrayFree. In the case of an error-free return, do not free the memory allocated for the return value.

Use the MathcadAllocate and MathcadFree functions to allocate and free memory inside MyCFunction.


Exception Handling

Mathcad traps the following floating point exceptions; overflow, divide by zero, and invalid operation. In the case of these exceptions, Mathcad will display a floating point error message under the function. Mathcad will also free all the memory allocated inside MyCFunction with MathcadArrayAllocate and MathcadAllocate.


Structure and Function Definitions

This section describes in more detail the structures and functions used in creating your own dynamically linked library. Topics are as follows:

The COMPLEXSCALAR Structure

The COMPLEXARRAY Structure

The FUNCTIONINFO Structure

CreateUserFunction

CreateUserErrorMessageTable

MathcadAllocate

MathcadFree

MathcadArrayAllocate

My C Function

MathcadArrayFree

isUserInterrupted


The COMPLEXSCALAR Structure

typedef struct tagCOMPLEXSCALAR {

double real;
double imag;

} COMPLEXSCALAR;

The COMPLEXSCALAR structure is used to pass scalar data between Mathcad and a user DLL. The real part of a scalar is stored in the real member of a COMPLEXSCALAR, and the imaginary in the imag member.

Member | Description
real | Contains the real part of a scalar.
imag | Contains the imaginary part of a scalar.


The COMPLEXARRAY Structure

typedef struct tagCOMPLEXARRAY {

unsigned int rows;
unsigned int cols;
double **hReal;
double **hImag;

} COMPLEXARRAY;

The COMPLEXARRAY structure is used to pass array data between Mathcad and a user DLL. It contains the information about the size of the array and whether any of the elements in the array has an imaginary or a real component.

Member | Description
rows | Number of rows in the array.
cols | Number of columns in the array.
hReal | Points to the real part of a complex array hReal[i][j] contains the element in the ith column and the jth row of the array. hReal is equal to NULL if the array has no real component.
hImag | Points to the imaginary part of a complex array hImag[i][j], contains the element in the ith column and the jth row of the array. hImag equals NULL if the array has no imaginary component.

Comments

hReal and hImag members of the argument array are indexed as two-dimensional array of the range [0 .. cols – 1][0 .. rows – 1].


The FUNCTIONINFO Structure

typedef struct tagFUNCTIONINFO{

char * lpstrName;
char * lpstrParameters;
char * lpstrDescription;
LPCFUNCTION lpfnMyCFunction;
long unsigned int returnType;
unsigned int nArgs;
long unsigned int argType[MAX_ARGS];

} FUNCTIONINFO;

The FUNCTIONINFO structure contains the information that Mathcad uses to register a user function. Refer below for each member and its description.

Member | Description
lpstrName | Points to a NULL-terminated string that specifies the name of the user function.
lpstrParameters | Points to a NULL-terminated string that specifies the parameters of the user function. The string is used by the Insert Function dialog box.
lpstrDescription | Points to a NULL-terminated string that specifies the function description for the Insert Function dialog box.
lpfnMyCFunction | Pointer to the code that executes the user function.
returnType | Specifies the type of value returned by the function. The values are COMPLEX_ARRAY or COMPLEX_SCALAR.
nArgs | Specifies the number of arguments expected by the function. Must be between 1 and MAX_ARGS.
argType | Specifies an array of long unsigned integers containing input parameter types.


CreateUserFunction

const void * CreateUserFunction(hDLL, functionInfo)
HINSTANCE hDLL;
FUNCTIONINFO * functionInfo;

CreateUserFunction is called when the DLL is attaching to the address space of the current process in order to register the user function with Mathcad.

Parameter

Description

hDLL

Handle of the DLL supplied by the DLL entry point routine.

functionInfo

Points to the FUNCTIONINFO structure that contains information about the function.
The FUNCTIONINFO structure has the following form:

typedef struct tagFUNCTIONINFO{

char * lpstrName;
char * lpstrParameters;
char * lpstrDescription;
LPCFUNCTION lpfnMyCFunction;
long unsigned int returnType;
unsigned int nArgs;
long unsigned int argType[MAX_ARGS];

} FUNCTIONINFO;

Return value

The return value is a non-NULL handle if the registration is successful. Otherwise, it is NULL.


CreateUserErrorMessageTable

BOOL CreateUserErrorMessageTable(hDLL,n,ErrorMessageTable)
HINSTANCE hDLL;
unsigned int n;
char * ErrorMessageTable[ ];

CreateUserErrorMessageTable is called when the DLL is attaching to the address space of the current process in order to register the user error message table with Mathcad.

Parameter | Description
hDLL | Handle of the DLL supplied by the DLL entry point routine.
n | Number of error messages in the table.
ErrorMessageTable | An array of n strings with the text of the error messages.

Return value

The return value is TRUE if the registration is successful. Otherwise, it is FALSE.


MathcadAllocate

char * MathcadAllocate(size)
unsigned int size;

Should be used to allocate memory inside the MyCFunction. Allocates a memory block of a given size (in bytes) of memory.

Parameter | Description
size | Size (in bytes) of memory block to allocate. Should be non-zero.

Return value

Returns a pointer to the storage space. To get a pointer to a type other than char, use a type cast on the return value. Returns NULL if the allocation failed or if size is equal to 0.


MathcadFree

void MathcadFree(address)
char * address;

Should be used to free memory allocated with MathcadAllocate. The argument address points to the memory previously allocated with MathcadAllocate. A NULL pointer argument is ignored.

Parameter | Description
address | Address of the memory block that is to be freed.

Return value

The function does not return a value.


MathcadArrayAllocate

BOOL MathcadArrayAllocate(array, rows, cols, allocateReal,
allocateImaginary)
COMPLEXARRAY* const array;
unsigned int rows;
unsigned int cols;
BOOL allocateReal;
BOOL allocateImaginary;

Allocates memory for a COMPLEXARRAY of cols columns and rows rows. Sets the hReal, hImag, rows and cols members of the argument array.

Parameter

Description

array

Points to the COMPLEXARRAY structure that is to be filled with the information about an array.

The COMPLEXARRAY structure has the following form:

&#9;typedef struct tagCOMPLEXARRAY {
unsigned int rows;
unsigned int cols;
double **hReal;
double **hImag;
} COMPLEXARRAY;

rows

Row dimension of the array that is being allocated. After a successful allocation, the rows member of the argument array is set to the value of rows.

cols

Column dimension of the array that is being allocated. After a successful allocation, the cols member of the argument array is set to the value of cols.

allocateReal

Boolean flag indicating whether a memory block should be allocated to store the real part of the array. If allocateReal is FALSE the function does not allocate storage for the real part of array and sets the hReal member to NULL.

allocateImag

Boolean flag indicating whether a memory block should be allocated to store the imaginary part of the array. If allocateImag is FALSE the function does not allocate storage for the imaginary part of array and sets the hImag member to NULL.

Return value

Returns TRUE if the allocation is successful, FALSE otherwise.

Comments

hReal and hImag members of the argument array are allocated as 2-dimensional array of the range [0 .. cols – 1][0 .. rows – 1].


My C Function

LRESULT MyCFunction(returnValue, argument1,...)
void * const returnValue;
const void * const argument1;
...

MyCFunction is the actual code which executes the user function. Mathcad arguments and a pointer to a return value are passed to this function. It puts the result of the calculation in the return value.

Parameter | Description
returnValue | Points to a COMPLEXARRAY or a COMPLEXSCALAR structure where the function result is to be stored. If you are implementing a Mathcad user function which returns a scalar, returnValue is a pointer to a COMPLEXSCALAR structure. If you are implementing a Mathcad user function that returns an array, returnValue points to a COMPLEXARRAY structure.
argument1 | Points to a read-only COMPLEXARRAY or a COMPLEXSCALAR structure where the first function argument is stored. If you are implementing a Mathcad user function that has a scalar as its first argument, argument1 is a pointer to a COMPLEXSCALAR structure. If you are implementing a Mathcad user function that has an array as its first argument, argument1 points to a COMPLEXARRAY structure.
... | If you are implementing a Mathcad user function that has more than one argument, your MyCFunction will have additional arguments. The additional arguments will be pointers to the read-only COMPLEXARRAY or a COMPLEXSCALAR structures where the data for the corresponding Mathcad user function argument is stored.

Return value

MyCFunction should return 0 to indicate an error-free return. To indicate an error MyCFunction should return an error code in the low word of the returned LRESULT, and in the high word the number of the argument under which the error box should be placed. If the high word is zero the error message box is placed under the function itself. See the section on error handling to find out more about error codes.

Comments

MyCFunction is a placeholder for the library-supplied function name. You can name the function that executes your Mathcad user function anything you would like, but you must register the address of your executable code with Mathcad by setting the lpfnMyCFunction member of the FUNCTIONINFO structure.


MathcadArrayFree

void MathcadArrayFree(array)
COMPLEXARRAY * const array;

Frees memory that was allocated by the MathcadArrayAllocate function to the hReal and hImag members of the argument array.

Parameter

Description

array

Points to the COMPLEXARRAY structure that is to be filled with the information about an array.
The COMPLEXARRAY structure has the following form:

typedef struct tagCOMPLEXARRAY {

unsigned int rows;
unsigned int cols;
double **hReal;
double **hImag;

} COMPLEXARRAY;

Return value

The function does not return a value.


isUserInterrupted

BOOL isUserInterrupted(void)

The isUserInterrupted function is used to check whether a user has pressed the [Esc] key. Include this function if you want to be able to interrupt your function like other Mathcad functions.

Parameter

The function does not take any parameters.

Return value

Returns TRUE if the[Esc] key has been pressed, FALSE otherwise.


end

Terms of Use

DLL interface specifications contained in this Developer's Reference may be used for creating user-written external functions which work with Mathcad for your personal or internal business use only. These specifications may not be used for creating external functions for commercial resale without the prior written consent of MathSoft, Inc.


Intro to DAC

Data Acquisition Control (DAC) Overview

The Mathcad Data Acquisition Control (DAC) is an ActiveX control that allows you to acquire data from and send data to National Instruments (NI) data acquisition devices installed on your computer. Its purpose is to allow a direct connection between Mathcad and any installed NI data acquisition devices by inserting the control into a scriptable object component (SOC). However, it may also be used in other programming environments, for example, in a Visual Basic project or on an Excel spreadsheet.

For the Mathcad Data Acquisition Control to work properly, your data acquisition devices must be properly installed in accordance with the instructions provided by National Instruments.

At this time, the control only supports National Instruments E-Series data acquisition boards and PC cards. The control may also work with non-E-Series devices (e.g. the DAQCard-500).

This help file contains descriptions and code examples for all methods, properties and events associated with the control. The methods, properties and events are organized into individual book chapters.

The properties and methods of the control may be accessed and changed in various ways. You can use the form-like user interface, the properties dialog, or access properties and methods programmatically. The form-like user interface is the easiest way to access the properties and methods if you are using a visible instance of the control.

Minimum Requirements

For the data acquisition control to work you must have NI-DAQ Version 6.7 or higher and Mathcad 2000 or higher installed. You must, of course, also satisfy the minimum requirements of all required software for them to work properly.

General Overview of Data Acquisition

The Mathcad Data Acquisition Control is an ActiveX control that interacts with National Instruments data acquisition devices installed on your computer.

The Data Acquisition Component (DAC) is comprised of the data acquisition control embedded in a scriptable object component (SOC). The SOC is then saved to a user component MCM file. The user component can be inserted like any other component.

Thus, the DAC is not a native Mathcad component. As such, some scripting must be done to communicate with the embedded control. At a minimum, you must bind inputs and outputs of the SOC to data members of the embedded control.

When the DAC is inserted into a Mathcad worksheet it is set up for the default operation of single point analog input. The control properties can be changed by using the form-like user interface (UI), the Properties dialog, or programmatically. Any subsequent changes you make to the control's properties are saved when you close the Mathcad worksheet. So, the next time you open a worksheet containing a DAC the embedded control will be set up as it last was.

Example worksheets contained in the \Samples\DAC subfolder of the Mathcad installation folder illustrate how to use the DAC for single point and waveform analog input and output. These example files are an excellent starting point for creating your own worksheets.

Basic Operation

The basic operation of the DAC is as follows. You specify the particular operation to be performed and the channels that it will be performed on. The channels are specified using the ChannelString property. When the ChannelString property is set, a Channel object is created for each channel specified. Interaction with the outside world is accomplished through the Data member of each Channel object.

When acquiring data the SOC should automatically recalculate whenever any of its output values change. The embedded control also raises the DataAcquired or DataSent events upon completion of data transfer. These events can be used for event handler routines within the SOC.

When sending data the SOC should pass an input value to the Data member of a Channel object and the Send method should be called in the Exec routine of the SOC. If you don't want to automatically send data when the SOC is recalculated leave the Send method out of the Exec routine and manually click the Send button on the UI.

Use of Triggers

The wait for trigger feature is only applicable for waveform analog input operations.

In order to use the wait for trigger feature your device must support digital or analog triggers. Digital triggers are applied at the PFI0 pin and are TTL transitions from either high-to-low or low-to-high (depending on your device). Analog triggers can be specified at PFI0 or an analog input channel and can be set for either a high-to-low or low-to-high transition and a specific voltage level can set to trigger at. Only the first channel in the channel string may be the analog trigger input.

To eliminate spurious triggers on analog input channels, make sure you read the trigger-related information in your device documentation.


Limitations

Limitations of the Mathcad Data Acquisition Control

  1. The control uses the default settings for the active device, i.e. input polarity and range and the input mode (e.g. referenced single ended, non-referenced single ended, or differential) . To configure the default setting for the devices installed on your computer, use the National Instruments Measurement & Automation Explorer.

  2. The use of AMUX-64T multiplexer devices is not supported at this time.

  3. Before you can access data members of the Channels collection, you must set the ChannelString property.

  4. The analog channel used for analog triggering is always the first channel in the channel string. If you edit the channel string, the order that the channels appear in the Channels collection may not agree with what is typed (e.g. if the channel string was 1:3 and then you edited it to be 0,1,2,3 channel zero would be added to the end of the channels collection and would actually be the fourth item in the collection). To clear the channel string set it equal to a blank string and then specify a new channel string. This will place members into the Channels collection in the order that they appear in the ChannelString.

  5. The values you receive from and send to the active device are in volts.

  6. The control does not implement all possible functions as it is intended to be used with Mathcad. For example, there is no wait for trigger feature for analog output because it is assumed that the results of a Mathcad calculation will trigger the analog output operation.


MDAQ_CHANNEL

MDAQChannel Class

The MDAQChannel class stores information related to all channels in the channel string.

The Channels collection is populated with an MDAQChannel object for each channel in the channel string as a result of any change to the ChannelString property.

The MDAQChannel class members are Variants so that they may be accessed via VBScript and are described as follows:

Member Description

Number As Variant (Integer)

The actual channel number that the object refers to.

Data As Variant (Double)

Stores data related to the data transfer operation. For output, the data values are specified prior to sending data to the device. For input, this member stores the results of the data acquisition. The value is a scalar for single point operations and an array for waveform operations.

AIGain As Variant (Integer)

The analog input gain for the channel.

DeltaT As Variant (Double)

For waveform input or output operations, this value represents the actual time difference in seconds between analog to digital or digital to analog conversions. Usually, this number is the same as the inverse of the sample or update rate. However, if the device could not exactly match the particular rate this number will differ. Always check this value when performing waveform operations to ensure that actual time between samples or updates is known.


MDAQ_DEVICE

MDAQDevice Class

The MDAQDevice class stores information related to all data acquisition devices installed on your computer.

The InstalledDevices collection is populated with an MDAQDevice object for each installed device as a result of a call to the QueryDevices Method. The QueryDevices Method is automatically called when the control is initialized so there should be no need to call it under normal circumstances. However, if you reconfigure devices while an instance of the control is running (e.g. change the device number) the QueryDevices method should be called to update information on the devices.

The MDAQDevice class has these members:

Member Description

Number As Integer

The number assigned to the device by the configuration utility.

DevType As String

The name of the device, e.g. DAQCard-500.

DevTypeCode As Long

The National Instruments device type code.

NumAIChannels As Long

The number of analog input channels that the device supports.

SupportsDIFFAI As Boolean

True if the device supports differential analog input.

SupportsNRSEAI As Boolean

True if the device supports non-referenced single ended analog input.

SupportsRSEAI As Boolean

True if the device supports referenced single ended analog input.

AllowedAIGains As Integer

Specifies the allowed gain values for the device. The values correspond to:

0: 1

1: 1, 10, and 100

2: 1, 2, 10, and 100

3: 1, 2, 5, 10, 20, 50, and 100

ChannelString As String

The channel string for the device.

InputResolution As Integer

The number of bits of resolution for the analog to digital converter.

SupportsAO As Boolean

True if the device supports analog output.

NumAOChannels As Long

The number of analog output channels.

OutputResolution As Integer

The number of bits of resolution for the digital to analog converter.

HasDigTrig As Boolean

True if the device supports digital triggers.

HasAnalogTrig As Boolean

True if the device supports analog triggers.

Supported As Boolean

True if the device is supported by the control.


Acquire

Acquire Method

Reads data from the active data acquisition device.

Syntax

Variant = object.Acquire( )

The Acquire method syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

Remarks

The Acquire method retrieves a reading, in volts, from every channel in the channel string. The data is stored in the Data member of the Channel object. The type of data returned depends on the IOType setting and is a scalar for single point operations and a vector for waveform operations.

The Acquire method returns 0 if successful or -1 if there was an error in at least one of the channels being acquired.

Example

Sub AcquireData()

Dim McadDAQ As AnalogIO

Dim vResult as Variant

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the channel string

McadDAQ.ChannelString = "0,1,3"

'set the IOFunction and IOType to input a single point from every channel in the channel string

McadDAQ.IOFunction = 0

McadDAQ.IOType = 0

'use the Acquire method to get the data

vResult = McadDAQ.Acquire

End Sub


Send

Send Method

Sends data to the active data acquisition device.

Syntax

Variant = object.Send( )

The Send method syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

Remarks

The Send method sends the voltage value associated with a channel to all channels in the channel string. Each channel can have its own voltage value independent of the others. If the IOFunction property is set to send, the voltage values are remembered after the document containing the control is closed.

The data to be sent is stored in the Data member of the Channel object. The type of data sent depends on the IOType setting and is a scalar for single point operations and a vector for waveform operations.

The Send method returns 0 if successful or -1 if there was an error in at least one of the channels having data sent to it.

Example

Sub SendData()

Dim McadDAQ As AnalogIO

Dim vResult as Variant

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the channel string

McadDAQ.ChannelString = "0,1"

'set the IOFunction and IOType to output a single point from every channel

' in the channel string

McadDAQ.IOFunction = 1

McadDAQ.IOType = 0

'set the channel data to send

McadDAQ.Channels("0").Data = 1.5#

McadDAQ.Channels("1").Data = 4.25#

'use the Send method to send the data to the output channels

vResult = McadDAQ.Send

End Sub


QueryDevices

QueryDevices Method

Retrieves information on installed and configured data acquisition devices.

Syntax

Variant = object.QueryDevices( )

The QueryDevices method syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

Remarks

The QueryDevices method is called when the control initializes and looks for installed and confugured data acquisition devices on your computer. The results are stored in the InstalledDevices collection. The QueryDevices method returns 0 if there was at least one supported device installed on your computer and -1 otherwise.

Example

Sub GetDeviceInfo()

Dim McadDAQ As AnalogIO

Dim vResult as Variant

'the next statement assumes there was a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

vResult = McadDAQ.QueryDevices

End Sub


ShowAbout

ShowAbout Method

Shows the about box for the control.

Syntax

object.ShowAbout( )

The ShowAbout method syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

Remarks

The ShowAbout method is useful for determining the version number of the control. The version number of the control can also be determined by navigating to the file "MathcadDAQ.ocx" in Windows Explorer, right-clicking on the file and selecting "Properties", and then clicking on the "Version" tab of the properties dialog.

If you encounter any errors when using this control please notify MathSoft technical support and provide a complete description of the problem and the version number of the control so that the problem can be logged in our database and fixed in a future release.

Example

Sub ShowAbout()

Dim McadDAQ As AnalogIO

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

McadDAQ.ShowAboutBox

End Sub


ActiveDevice

ActiveDevice Property

Returns or sets the active data acquisition device.

Syntax

Variant = object.ActiveDevice( )

object.ActiveDevice = vNewValue

The ActiveDevice property syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

vNewValue Variant (Integer). The number of the device to make the active device.

Remarks

The ActiveDevice property is used to determine or specify the device that will be used for all subsequent operations. The numbers for devices installed on your computer are assigned using the National Instruments Measurement & Automation Explorer. Valid ranges are from 1 to 16 inclusive.

If an invalid number is specified, e.g. a non-existent device or a non-numeric value, the value reverts to a known good value.

Example

Sub SetGetActiveDevice()

Dim McadDAQ As AnalogIO

Dim vResult as Variant

'the next statement assumes there was a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the new active device

McadDAQ.ActiveDevice = 2%

vResult = McadDAQ.ActiveDevice

MsgBox "The ActiveDevice is now: " & CStr(vResult)

End Sub


ChannelString

ChannelString Property

Returns or sets the channels that subsequent operations are performed on.

Syntax

Variant = object.ChannelString( )

object.ChannelString = vNewValue

The ChannelString property syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

vNewValue Variant (String). The new channel string.

Remarks

The ChannelString property is used to determine or specify the channels that all subsequent operations will be performed on.

Individual channels are specified using a comma separating the channels, e.g. "1,3,5" for channels 1, 3, and 5.

A continuous range of channels may be specified using a colon to separate the lower and upper bounds, e.g. "0:4" for channels 0, 1, 2, 3, and 4 or "5:2" for channels 5, 4, 3, and 2.

The ChannelString property must be set before any operation can be performed. Upon specifying the ChannelString property members of the Channels collection are created.

Operations are performed on the channels according to their order in the Channels collection.

Example

Sub SetGetChanString()

Dim McadDAQ As AnalogIO

Dim vResult as Variant

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the new channel string

McadDAQ.ChannelString = "0:4"

vResult = McadDAQ.ChannelString

MsgBox "The new ChannelString is: " & Cstr(vResult)

End Sub


InstalledDevices

InstalledDevices Collection

A collection of information on all installed data acquisition devices. Members of the collection are MDAQDevice class objects.

Syntax

Device = object.InstalledDevices( index)

The InstalledDevices collection syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

index Required. A string or integer value representing the device object to return. Specifying a string for index returns information for the device having the same number. Specifying an integer for index returns that item of the collection. A particular device may not necessarily have the same name as its index in the collection.

Device Required. MDAQDevice. A variable used to hold the device member.

Remarks

The InstalledDevices collection is populated when the control is initialized or after a call to the QueryDevices method.

Example

Sub GetDeviceObject()

Dim McadDAQ As AnalogIO

Dim MyDevice as MDAQDevice

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'get the information for device 1

Set MyDevice = McadDAQ.InstalledDevices("1")

If MyDevice.HasDigTrig Then

MsgBox "Device 1 supports digital triggers"

Else

MsgBox "Device 1 does not support digital triggers"

End If

End Sub


IOType

IOType Property

Returns or sets type of operation the data acquisition device will perform.

Syntax

Variant = object.IOType( )

object.IOType = vNewValue

The IOType property syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

vNewValue Variant (Integer). The type of operation to perform. Set to 0 for single point and 1 for waveform.

Remarks

The IOType property is used to determine or specify the type of operation the active device will perform. Valid values for the new value are 0 for single point and 1 for waveform.

Single point operations send or receive a single point of data to or from all channels in the ChannelString.

Waveform input operations acquire the same number of data points from all channels in the ChannelString. Waveform output is only sent to the first analog output channel in the channel string.

For input operations you must specify the Rate and NumSamples properties (or use their default values). For output operation you must specify the Rate and the NumIterations properties (or use their default values) and the number of samples is determined from the size of the data in the channels Data member.

Example

Sub SetGetIOType()

Dim McadDAQ As AnalogIO

Dim vResult as Variant

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the new active device

McadDAQ.IOType = 1%

vResult = McadDAQ.IOType

MsgBox "The IOType is now: " & CStr(vResult)

End Sub


IOFunction

IOFunction Property

Returns or sets function of the data acquisition device.

Syntax

Variant = object.IOFunction( )

object.IOFunction = vNewValue

The IOFunction property syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

vNewValue Variant (Integer). The function to perform. Set to 0 for analog input and 1 for analog output.

Remarks

The IOFunction property is used to determine or specify the function of the active device. Valid values for the new value are 0 for analog input and 1 for analog output.

Example

Sub SetGetIOFunction()

Dim McadDAQ As AnalogIO

Dim vResult as Variant

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the new active device

McadDAQ.IOFunction = 0%

vResult = McadDAQ.IOFunction

MsgBox "The IOFunction is now: " & CStr(vResult)

End Sub


Channels Collection

Returns a collection containing MDAQChannel members.

Syntax

Channel = object.Channels(index)

The Channels collection syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

index Required. A string or integer value representing the channel object to return. Specifying a string for index returns information for the channel having the same name. Specifying an integer for index returns that item of the collection.

Channel Required. MDAQChannel. A variable used to store the collection member.

Remarks

The Channels collection is composed of MDAQChannel class objects. The collection is accessed to set or retrieve data for the particular operation. If a non-existent channel index is specified a VB run time error occurs.

Example

Sub GetChannelObject()

Dim McadDAQ As AnalogIO

Dim MyChannel as MDAQChannel

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'get the information for channel 0

Set MyChannel = McadDAQ.Channels("0")

If IsArray(MyChannel.Data) Then

MsgBox "Channel 0 contains array data"

Else

MsgBox "Channel 0 contains scalar data"

End If

End Sub


NumSamples

NumSamples Property

Returns or sets the number of samples to retrieve during waveform acquisition.

Syntax

Variant = object.NumSamples()

object.NumSamples = vNewValue

The NumSamples property syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

vNewValue Required. Variant (Integer). The number of samples to acquire.

Remarks

During waveform data acquisition NumSamples of data points are acquired form each channel in the channel string.

Example

Sub GetWaveform()

Dim McadDAQ As AnalogIO

Dim lTemp as Long

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the channel string to acquire from channels 0 and 3

McadDAQ.ChannelString = "0,3"

'set the IOFunction to input

McadDAQ.IOFunction = 0&

'set the IOType to waveform

McadDAQ.IOType = 1&

'set the number of samples to acquire for all channels

McadDAQ.NumSamples = 1000%

'set the sample rate

McadDAQ.Rate = 10000%

'acuire the data

McadDAQ.Acquire

'See if the right number of samples was acquired

lTemp = UBound(McadDAQ.Channels("0").Data) + 1

MsgBox CStr(lTemp) & " samples were acquired"

End Sub


WaitForTrigger

WaitForTrigger Property

Returns or sets a variable that tells the control whether or not to wait for a trigger before starting waveform acquisition.

Syntax

Variant = object.WaitForTrigger()

object.WaitForTrigger = vNewValue

The WaitForTrigger property syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

vNewValue Required. Variant (Integer). Set to 1 to wait for a trigger or 0 for not to wait.

Remarks

The WaitForTrigger property, as its name implies, tells the control whether or not to wait for a trigger before starting waveform acquisition. You must specify the trigger properties using the TriggerType, TriggerEdge, TriggerSource, and TriggerLevel properties as appropriate. The default trigger is a digital trigger at the PFI0 pin.

If an invalid value, e.g. other than 0 or 1 or non-numeric, is specified for the property it will default back to 0.

Example

Sub GetWaveformOnTrigger()

Dim McadDAQ As AnalogIO

Dim lTemp as Long

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the channel string to acquire from channel 1

McadDAQ.ChannelString = "1"

'set the IOFunction to input

McadDAQ.IOFunction = 0&

'set the IOType to waveform

McadDAQ.IOType = 1&

'set the number of samples to acquire for all channels

McadDAQ.NumSamples = 1000%

'set the sample rate in samples per second

McadDAQ.Rate = 10000%

'set trigger related information

McadDAQ.WaitForTrigger = 1%

'Set up for low-to-high analog trigger of 2.5 Volts at the PFI0 pin

McadDAQ.TriggerType = 1%

McadDAQ.TriggerSource = 0&

McadDAQ.TriggerEdge = 0&

McadDAQ.TriggerLevel = 2.5#

'acquire the data

McadDAQ.Acquire

'See if the right number of samples was acquired, zero base assumed

On Error Resume Next

lTemp = UBound(McadDAQ.Channels("1").Data) + 1

If Err.Number = 0 Then

MsgBox CStr(lTemp) & " samples were acquired"

Else

MsgBox "Acquisition Error"

End If

End Sub


ShowErrors

ShowErrors Property

Returns or sets a variable that tells the control whether or not to generate NI-DAQ error messages.

Syntax

Variant = object.ShowErrors()

object.ShowErrors = vNewValue

The ShowErrors property syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

vNewValue Required. Variant (Integer). Set to 1 to show or 0 for not to show NI-DAQ error messages.

Remarks

If the ShowErrors property is set to 0, no error messages will be generated if inappropriate properties are specified for the active device, for example specifying an out of range channel number in the channel string. This is done so as not to interrupt calculation flow in Mathcad.

If you think all properties are specified correctly for the particular operation being performed but nothing is happening, set the ShowErrors property to 1 and try the operation again.

Example

Sub SetShowErrors()

Dim McadDAQ As AnalogIO

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the ShowErrors property

McadDAQ.ShowErrors = 1%

End Sub


SampleRate

Rate Property

Returns or sets the rate, in samples per second, at which analog to digital or digital to analog conversions take place.

Syntax

Variant = object.Rate()

object.Rate = vNewValue

The Rate property syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

vNewValue Required. Variant (Double). The new sample or transfer rate.

Remarks

The Rate property has dual usage. For input operations it specifies the rate at which analog to digital conversions take place. For output operations it specifies the rate at which digital to analog conversions take place.

The time between samples or updates, in seconds, is usually the inverse of the Rate property. However, this may not always be the case. To determine the actual time between samples that was used for the data transfer operation, get the DeltaT property of the channel item.

Example

Sub GetWaveform()

Dim McadDAQ As AnalogIO

Dim lTemp as Long

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the channel string to acquire from channels 0 and 3

McadDAQ.ChannelString = "0,3"

'set the IOFunction to input

McadDAQ.IOFunction = 0&

'set the IOType to waveform

McadDAQ.IOType = 1&

'set the number of samples to acquire for all channels

McadDAQ.NumSamples = 1000%

'set the sample rate in samples per second

McadDAQ.Rate = 10000%

'acuire the data

McadDAQ.Acquire

'See if the right number of samples was acquired, zero base assumed

lTemp = UBound(McadDAQ.Channels("0").Data) + 1

MsgBox CStr(lTemp) & " samples were acquired"

End Sub


NumIterations

NumIterations Property

Returns or sets the number of times to repeat a waveform output.

Syntax

Variant = object.NumIterations()

object.NumIterations = vNewValue

The NumIterations property syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

vNewValue Required. Variant (Integer). The number of times to repeat a waveform output.

Remarks

During waveform data output NumIterations of the waveform are sent to the output channel. The minimum value is one. This property is useful for generating a waveform for a long time. For example, instead of generating one thousand cycles of a sine wave, you could generate one cycle and repeat it one thousand times. The latter method can be done specifying less data points.

Example

Sub SendWaveform()

Dim McadDAQ As AnalogIO

Dim i as Integer

Dim vData(99) as Variant

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the channel string to send to channel 0

'Note: you can only send waveform data to one channel

McadDAQ.ChannelString = "0"

'set the IOFunction to output

McadDAQ.IOFunction = 1&

'set the IOType to waveform

McadDAQ.IOType = 1&

'Generate the data to send to the output channel

For i = 0 To 99

vData(i) = sin(i * 2 * 3.14159/100)

Next

'set the channel data

McadDAQ.Channels("0").Data = vData

'set the number of iterations

McadDAQ.NumIterations = 10%

'set the update rate

McadDAQ.Rate = 100%

'generate the waveform

McadDAQ.Send

End Sub


TrigEdge

TriggerEdge Property

Returns or sets the trigger edge transition for analog trigger operations.

Syntax

Variant = object.TriggerEdge()

object.TriggerEdge = vNewValue

The TriggerEdge property syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

vNewValue Required. Variant (Long). Set to 0 for low-to-high transition or 1 for high-to-low transition.

Remarks

The TriggerEdge property is used in conjunction with the TriggerLevel property for analog trigger operations and is ignored for digital triggers.

If an invalid value, e.g. other than 0 or 1 or non-numeric, is specified for the property it will default back to 0.

Example

Sub GetWaveformOnTrigger()

Dim McadDAQ As AnalogIO

Dim lTemp as Long

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the channel string to acquire from channel 1

McadDAQ.ChannelString = "1"

'set the IOFunction to input

McadDAQ.IOFunction = 0&

'set the IOType to waveform

McadDAQ.IOType = 1&

'set the number of samples to acquire for all channels

McadDAQ.NumSamples = 1000%

'set the sample rate in samples per second

McadDAQ.Rate = 10000%

'set trigger related information

McadDAQ.WaitForTrigger = 1%

'Set up for low-to-high analog trigger of 2.5 Volts at the PFI0 pin

McadDAQ.TriggerType = 1%

McadDAQ.TriggerSource = 0&

McadDAQ.TriggerEdge = 0&

McadDAQ.TriggerLevel = 2.5#

'acquire the data

McadDAQ.Acquire

'See if the right number of samples was acquired, zero base assumed

On Error Resume Next

lTemp = UBound(McadDAQ.Channels("1").Data) + 1

If Err.Number = 0 Then

MsgBox CStr(lTemp) & " samples were acquired"

Else

MsgBox "Acquisition Error"

End If

End Sub


TrigLevel

TriggerLevel Property

Returns or sets the analog trigger level.

Syntax

Variant = object.TriggerLevel()

object.TriggerLevel = vNewValue

The TriggerLevel property syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

vNewValue Required. Variant (Double). The analog trigger level in volts.

Remarks

The TriggerLevel property is used to specify the level of the analog trigger.

If an invalid value, e.g. non-numeric, is specified for the property it will default to 0 volts.

Example

Sub GetWaveformOnTrigger()

Dim McadDAQ As AnalogIO

Dim lTemp as Long

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the channel string to acquire from channel 1

McadDAQ.ChannelString = "1"

'set the IOFunction to input

McadDAQ.IOFunction = 0&

'set the IOType to waveform

McadDAQ.IOType = 1&

'set the number of samples to acquire for all channels

McadDAQ.NumSamples = 1000%

'set the sample rate in samples per second

McadDAQ.Rate = 10000%

'set trigger related information

McadDAQ.WaitForTrigger = 1%

'Set up for low-to-high analog trigger of 2.5 Volts at the PFI0 pin

McadDAQ.TriggerType = 1%

McadDAQ.TriggerSource = 0&

McadDAQ.TriggerEdge = 0&

McadDAQ.TriggerLevel = 2.5#

'acquire the data

McadDAQ.Acquire

'See if the right number of samples was acquired, zero base assumed

On Error Resume Next

lTemp = UBound(McadDAQ.Channels("1").Data) + 1

If Err.Number = 0 Then

MsgBox CStr(lTemp) & " samples were acquired"

Else

MsgBox "Acquisition Error"

End If

End Sub


TrigSource

TriggerSource Property

Returns or sets the trigger source.

Syntax

Variant = object.TriggerSource()

object.TriggerSource = vNewValue

The TriggerSource property syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

vNewValue Required. Variant (Long). Set to 0 for PFI0 or 1 for the analog input channel.

Remarks

The TriggerSource property is used to specify the source of the analog trigger. Digital triggers always use the PFI0 pin for the trigger input. If the TriggerType is analog then you can specify that either PFI0 pin or the analog input channel be the source of the trigger. Analog triggers also require that the TriggerLevel and TriggerEdge properties be specified.

If the analog input channel is the source of the trigger and there are multiple channels in the channel string, the first channel in the channels collection is the source of the trigger.

If an invalid value, e.g. other than 0 or 1 or non-numeric, is specified for the property it will default back to 0.

Example

Sub GetWaveformOnTrigger()

Dim McadDAQ As AnalogIO

Dim lTemp as Long

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the channel string to acquire from channel 1

McadDAQ.ChannelString = "1"

'set the IOFunction to input

McadDAQ.IOFunction = 0&

'set the IOType to waveform

McadDAQ.IOType = 1&

'set the number of samples to acquire for all channels

McadDAQ.NumSamples = 1000%

'set the sample rate in samples per second

McadDAQ.Rate = 10000%

'set trigger related information

McadDAQ.WaitForTrigger = 1%

'Set up for low-to-high analog trigger of 2.5 Volts at the PFI0 pin

McadDAQ.TriggerType = 1%

McadDAQ.TriggerSource = 0&

McadDAQ.TriggerEdge = 0&

McadDAQ.TriggerLevel = 2.5#

'acquire the data

McadDAQ.Acquire

'See if the right number of samples was acquired, zero base assumed

On Error Resume Next

lTemp = UBound(McadDAQ.Channels("1").Data) + 1

If Err.Number = 0 Then

MsgBox CStr(lTemp) & " samples were acquired"

Else

MsgBox "Acquisition Error"

End If

End Sub


TrigType

TriggerType Property

Returns or sets the type of trigger to be used.

Syntax

Variant = object.TriggerType()

object.TriggerType = vNewValue

The TriggerType property syntax has these parts:

Part Description

object Required. A valid Mathcad Data Acquisition Control object.

vNewValue Required. Variant (Integer). Set to 0 for digital or 1 for analog.

Remarks

The TriggerType property specifies if digital or analog triggers are to be used. If analog trigger is specified the the TriggerType, TriggerEdge, TriggerSource, and TriggerLevel properties should also be specified as appropriate.

If an invalid value, e.g. other than 0 or 1 or non-numeric, is specified for the property it will default back to 0.

Example

Sub GetWaveformOnDigitalTrigger()

Dim McadDAQ As AnalogIO

Dim lTemp as Long

'the next statement assumes there is a Mathcad Data Acquisition control called

' AnalogIO1 on Form1 of a VisualBasic project

Set McadDAQ = Form1.AnalogIO1

'set the channel string to acquire from channel 1

McadDAQ.ChannelString = "1"

'set the IOFunction to input

McadDAQ.IOFunction = 0&

'set the IOType to waveform

McadDAQ.IOType = 1&

'set the number of samples to acquire for all channels

McadDAQ.NumSamples = 1000%

'set the sample rate in samples per second

McadDAQ.Rate = 10000%

'set trigger related information

McadDAQ.WaitForTrigger = 1%

'Set up for digital trigger at the PFI0 pin

McadDAQ.TriggerType = 0%

'acquire the data

McadDAQ.Acquire

'See if the right number of samples was acquired, zero base assumed

On Error Resume Next

lTemp = UBound(McadDAQ.Channels("1").Data) + 1

If Err.Number = 0 Then

MsgBox CStr(lTemp) & " samples were acquired"

Else

MsgBox "Acquisition Error"

End If

End Sub


DataAcquired

DataAcquired Event

This event is raised after all data for the specified operation has been acquired from the active device.

The purpose of the event is to allow for an event handler routine.


DataSent

DataSent Event

This event is raised after all data for the specified operation has been sent to the active device.

The purpose of the event is to allow for an event handler routine.


AcceptFiles Property

The AcceptFiles property sets or gets whether the TextBox accepts files via drag and drop. This property is disabled and can not be used programmatically.


Appearance Property

Not currently used.


AutoSize Property

The AutoSize property sets or gets whether autosize is active.

Syntax

bMode = TextBox.AutoSize

TextBox.AutoSize = bMode

Element | Description
bMode | True indicates that autosize is active; false indicates that autosize is inactive.

Remarks

The user may need to adjust the control's size if AutoSize is off, as the caption text may be cut off if it extends beyond the current boundaries of the TextBox.


AutoHScroll Property

The AutoHScroll property gets or sets whether automatic horizontal scrolling is active.

Syntax

bMode = TextBox.AutoHScroll

TextBox.AutoHScroll = bMode

Element | Description
bMode | True indicates that automatic horizontal scrolling is active; false indicates that it is not active.

Remarks

Automatically scrolls the text in the edit control to the right when the user types a character at the end of the line. If AutoHScroll is false, only text that fits within the rectangular boundary is allowed.


AutoVScroll Property

The AutoVScroll property gets or sets whether automatic vertical scrolling is active.

Syntax

bMode = TextBox.AutoVScroll

TextBox.AutoVScroll = bMode

Element | Description
bMode | True indicates that automatic vertical scrolling is active; false indicates that it is not active.

Remarks

Automatically scrolls the text in the edit control down when the user types a character at the end of the line. If AutoVScroll is false, only text that fits within the rectangular boundary is allowed.


BackColor Property

The BackColor property sets or gets the background color for the control.

Syntax

OLE_COLOR = TextBox.BackColor

TextBox.BackColor = OLE_COLOR

Element | Description
OLE_COLOR | A value that determines the background color of the control.

Remarks

Accepts any value in the valid range for an RGB color.


Border Property

The Border property sets or gets whether the TextBox has a border.

Syntax

bMode = TextBox.Border

TextBox.Border = bMode

Element | Description
bMode | True indicates that a border is visible; False indicates that it is not.

Remarks

Changes the appearance of the TextBox.


BorderStyle Property

The BorderStyle property changes the appearance of the TextBox.

Syntax

intStyle = TextBox.BorderStyle

TextBox.BorderStyle = intStyle

Element | Description
intStyle | Integer value that indicates the border style of the TextBox. 0 = no border; 1 = border.

Remarks

Changes the appearance of the TextBox.


CausesValidation Property

The CausesValidation property sets or gets whether validation occurs on the control which lost focus.

Syntax

bMode = TextBox.CausesValidation

TextBox.CausesValidation = bMode

Element | Description
bMode | True indicates that the control causes validation; False indicates that it does not.

Remarks

Not commonly used in the Mathcad environment.


ClientEdge Property

The ClientEdge property sets or gets whether the TextBox has a client edge.

Syntax

bMode = TextBox.ClientEdge

TextBox.ClientEdge = bMode

Element | Description
bMode | True indicates that the TextBox has a client edge; False indicates that it does not.

Remarks

Changes the appearance of the TextBox.


DisableNoScroll Property

The DisableNoScroll property sets or gets the scrollbar style of the TextBox.

Syntax

bMode = TextBox.DisableNoScroll

TextBox.DisableNoScroll = bMode

Element | Description
bMode | When True, text box shows a disabled vertical scroll bar when the text box does not contain enough items to scroll. When False, the scroll bar is hidden when the text box does not contain enough items.

Remarks

Applies only to multiline TextBox.


Enabled Property

The Enabled property sets or gets a value that determines whether an object can respond to user-generated events.

Syntax

bMode = TextBox.Enabled

TextBox.Enabled = bMode

Element | Description
bMode | True indicates that the TextBox is enabled; False indicates that it is disabled.

Remarks

A disable TextBox can not receive any user events, so is similar to a static label.


Font Property

Font property is used by the Properties page to set the font for the TextBox. Not used programmatically.


ForeColor Property

The ForeColor property sets or gets the foreground color for the control.

Syntax

OLE_COLOR = TextBox.ForeColor

TextBox.ForeColor = OLE_COLOR

Element | Description
OLE_COLOR | A value that determines the foreground color of the control.

Remarks

Accepts any value in the valid range for an RGB color. See also the BackColor property.


HelpContextID Property

The HelpContextID property specifies the default Help file context ID for an object.

Syntax

longVal = TextBox.HelpContextID

TextBox.HelpContextID = longVal

Element | Description
longVal | A long value that indicates the default Help file context ID for an object.


HorizontalScroll Property

The HorizontalScroll property gets or sets whether a horizontal scrollbar is visible in the TextBox.

Syntax

bMode = TextBox.HorizontalScroll

TextBox.HorizontalScroll = bMode

Element | Description
bMode | True indicates that the control will create a horizontal scrollbar on the bottom; False indicates that no scrollbar will be visible.

Remarks

This property is useful if the text extends beyond the width of the TextBox.


hWnd Property

The hWnd property gets the window handle of the window containing the control.

Syntax

OLE_HANDLE = TextBox.hWnd

Element | Description
OLE_HANDLE | The handle of the window containing the control.


LeftScrollBar Property

The LeftScrollBar property gets or sets whether a vertical scrollbar is shown on the left.

Syntax

bMode = TextBox.LeftScrollBar

TextBox.LeftScrollBar = bMode

Element | Description
bMode | True indicates that the control will show the vertical scrollbar on the left; False indicates that it will appear on the right.

Remarks

Changes the appearance of the TextBox.


Lowercase Property

The Lowercase property sets or gets a value that determines the default case of the text typed in the TextBox.

Syntax

bMode = TextBox.Lowercase

TextBox.Lowercase = bMode

Element | Description
bMode | True indicates that the added text will be converted to lowercase; False indicates that this is not enforced.

Remarks

See also the Uppercase property.


ModalFrame Property

The ModalFrame property sets or gets a value that determines whether a modal frame is used.

Syntax

bMode = TextBox.ModalFrame

TextBox.ModalFrame = bMode

Element | Description
bMode | True indicates that the TextBox has a modal frame; False indicates that it does not.

Remarks

This setting affects the appearance of the TextBox only.


Multiline Property

The Multiline property sets or gets a value that determines whether a TextBox can have multiple lines of text.

Syntax

bMode = TextBox.Multiline

TextBox.Multiline = bMode

Element | Description
bMode | True indicates that the TextBox can have multiple lines; False indicates that it can not.

Remarks

Useful if the TextBox is likely to contain more than one line of text.


NoHideSelection Property

The NoHideSelection property sets or gets a value that determines the appearance of selected text within the TextBox.

Syntax

bMode = TextBox.NoHideSelection

TextBox.NoHideSelection = bMode

Element | Description
bMode | True indicates that the TextBox doesn't hide the selection; False indicates that it does.

Remarks

Normally, an edit control hides the selection when the control loses the input focus and inverts the selection when the control receives the input focus.


Number Property

The Number property sets or gets a value that determines whether only numbers are allowed in the TextBox.

Syntax

bMode = TextBox.Number

TextBox.Number = bMode

Element | Description
bMode | True indicates that the TextBox accepts only numbers; False indicates that it will accept other characters.

Remarks

Use this setting to filter user input to block out unwanted keystrokes.


OEMConvert Property

The OEMConvert property sets or gets a value that determines whether or not text entered in the edit control is converted from the ANSI character set to the OEM character set and then back to ANSI.

Syntax

bMode = TextBox.OEMConvert

TextBox.OEMConvert = bMode

Element | Description
bMode | True indicates that the TextBox performs the conversion; False indicates that it does not.


Password Property

The Password property sets or gets a value that determines whether input text is hidden with asterisks.

Syntax

bMode = TextBox.Password

TextBox.Password = bMode

Element | Description
bMode | True indicates that the TextBox text is visible to users as typed; False indicates that it is masked by asterisks.

Remarks

Use this setting to hide sensitive information but note that this property does not secure the text. It merely hides the keystroke input from users.


ReadOnly Property

The ReadOnly property sets or gets a value that determines whether the text is read-only or is editable.

Syntax

bMode = TextBox.ReadOnly

TextBox.ReadOnly = bMode

Element | Description
bMode | True indicates that the text is read-only; False indicates that the text is editable.

Remarks

Use this property to prevent users from editing the text.


RightAlignedText Property

The RightAlignedText property sets or gets a value that determines whether the text is right justified.

Syntax

bMode = TextBox.RightAlignedText

TextBox.RightAlignedText = bMode

Element | Description
bMode | True indicates that the text is right-justified; False that it is not.

Remarks

Right justification is often useful for numerical inputs.


RightToLeftReadingOrder Property

The RightToLeftReadingOrder property sets or gets a value that determines whether the text is read right-to-left. Often used for Kanji.

Syntax

bMode = TextBox.RightToLeftReadingOrder

TextBox.RightToLeftReadingOrder = bMode

Element | Description
bMode | True indicates that the text ordering is right-to-left; False indicates left-to-right.

Remarks

Language localization may require this for languages that use a different ordering than English.


RtfText Property

Not currently used.


StaticEdge Property

The StaticEdge property sets or gets a value that affects the appearance of the TextBox.

Syntax

bMode = TextBox.StaticEdge

TextBox.StaticEdge = bMode

Element | Description
bMode | True indicates that a static edge is used; False indicates that it is not.

Remarks

Changes the appearance of the TextBox.


Text Property

The Text property sets or gets the text of the TextBox.

Syntax

stringText = TextBox.Text

TextBox.Text = stringText

Element | Description
stringText | A string that indicates the text of the TextBox.

Remarks

This is probably the most commonly used property of this control. Used to retrieve the contents of the TextBox.


TextAlignment Property

Set at design time to Left, Center, or Right from the Properties dialog. Only enabled when Multiline property is checked.


Transparent Property

The Transparent property sets or gets a value that determines whether the control "underneath" is visible.

Syntax

bMode = TextBox.Transparent

TextBox.Transparent = bMode

Element | Description
bMode | True indicates that the TextBox is transparent; False indicates that it is solid.


Uppercase Property

The Uppercase property sets or gets a value that determines the case of the text permitted in the TextBox.

Syntax

bMode = TextBox.Uppercase

TextBox.Uppercase = bMode

Element | Description
bMode | True indicates that the added text will be converted to uppercase; False indicates that this is not enforced.

Remarks

See also the Lowercase property.


VerticalScroll Property

The VerticalScroll property gets or sets whether a verticall scrollbar is visible in the TextBox.

Syntax

bMode = TextBox.VerticalScroll

TextBox.VerticalScroll = bMode

Element | Description
bMode | True indicates that the control will create a vertical scrollbar on the right side; False indicates that no scrollbar will be visible.

Remarks

Useful for multiline TextBox.


WantsReturn Property

The WantsReturn property gets or sets ???????.

Syntax

bMode = TextBox.WantsReturn

TextBox.WantsReturn = bMode

Element | Description
bMode | True indicates ??????


AcceptFiles Property

The AcceptFiles property sets or gets whether the ComboBox accepts files via drag and drop. This property is disabled and can not be used programmatically.


AutoHScroll Property

The AutoHScroll property gets or sets whether automatic horizontal scrolling is active.

Syntax

bMode = ComboBox.AutoHScroll

ComboBox.AutoHScroll = bMode

Element | Description
bMode | True indicates that automatic horizontal scrolling is active; false indicates that it is not active.

Remarks

Automatically scrolls the text in the edit control to the right when the user types a character at the end of the line. If AutoHScroll is set to false, only text that fits within the rectangular boundary is allowed.


AutoVScroll Property

The AutoVScroll property gets or sets whether automatic vertical scrolling is active.

Syntax

bMode = ComboBox.AutoVScroll

ComboBox.AutoVScroll = bMode

Element | Description
bMode | True indicates that automatic vertical scrolling is active; false indicates that it is not active.

Remarks

Automatically scrolls the text in the edit control down when the user types a character at the end of the line. If AutoVScroll is set to false, only text that fits within the rectangular boundary is allowed.


Border Property

The Border property sets or gets whether the ComboBox has a border.

Syntax

bMode = ComboBox.Border

ComboBox.Border = bMode

Element | Description
bMode | True indicates that a border is visible; False indicates that it is not.

Remarks

Affects the appearance of the ComboBox.


CBERR Property

The CBERR property sets or gets the CBERR constant.

Syntax

longCBERR = ComboBox.CBERR

ComboBox.CBERR = longCBERR

Element | Description
longCBERR | A value that indicates the setting of the CBERR constant.

Remarks

CBERR constant is returned as an error by the CurSel property when no item is selected.


CBERRSPACE Property

The CBERRSPACE property sets or gets the CBERRSPACE constant.

Syntax

longCBERRSPACE = ComboBox.CBERRSPACE

ComboBox.CBERRSPACE = longCBERRSPACE

Element | Description
longCBERRSPACE | A value that indicates the setting of the CBERRSPACE constant.

Remarks

CBERRSPACE constant is returned as error????


ClientEdge Property

The ClientEdge property sets or gets whether the ComboBox has a client edge.

Syntax

bMode = ComboBox.ClientEdge

ComboBox.ClientEdge = bMode

Element | Description
bMode | True indicates that the ComboBox has a client edge; False indicates that it does not.

Remarks

Changes the appearance of the ComboBox.


Count Property

The Count property is read-only and returns the number of items in the ComboBox.

Syntax

longCount = ComboBox.Count

Element | Description
longCount | The number of items in the ComboBox.

Remarks

This important property can be used to set up a loop to examine the items in the ComboBox using methods such as GetText.


CurSel Property

The CurSel property sets or gets the index of the currently selected item in the ComboBox.

Syntax

longSelIndex = ComboBox.CurSel

ComboBox.CurSel = longSelIndex

Element | Description
longSelIndex | The index of the selected item or item to select. Zero based.

Remarks

Note that index is zero based, so first item in list has index of 0. Returns constant LBERR if no item selected. The CurSel property can used with GetText method to retrieve the text of selected item.


DisableNoScroll Property

The DisableNoScroll property sets or gets whether the ComboBox shows a disabled scroll bar when it does not contain enough items to fill visible space.

Syntax

bMode = ComboBox.DisableNoScroll

ComboBox.DisableNoScroll = bMode

Element | Description
bMode | True indicates that a disabled scrollbar is shown when not enough items are present; False indicates that no scrollbar is shown.


EditLen Property

The EditLen property is a read-only property that returns the length of the string in the editbox portion of the control.

Syntax

longLen = ComboBox.EditLen

Element | Description
longLen | The length of the string in the editbox.

Remarks

Can be used to determine whether the selected item is a null string.


HorizontalScroll Property

The HorizontalScroll property gets or sets whether a horizontal scrollbar is visible in the ComboBox.

Syntax

bMode = ComboBox.HorizontalScroll

ComboBox.HorizontalScroll = bMode

Element | Description
bMode | True indicates that the control will horizontal scrollbar on the bottom; False indicates that no scrollbar will be visible.


Lowercase Property

The Lowercase property sets or gets a value that determines the default case of the text typed in the ComboBox.

Syntax

bMode = ComboBox.Lowercase

ComboBox.Lowercase = bMode

Element | Description
bMode | True indicates that the added text will be converted to lowercase; False indicates that this is not enforced.

Remarks

The Lowercase property be used to filter input. See also the Uppercase property.


ModalFrame Property

The ModalFrame property sets or gets a value that determines whether a modal frame is used.

Syntax

bMode = ComboBox.ModalFrame

ComboBox.ModalFrame = bMode

Element | Description
bMode | True indicates that the ComboBox has a modal frame; False indicates that it does not.

Remarks

This setting affects the appearance of the ComboBox only.


NoIntegralHeight Property

The NoIntegralHeight property sets or gets a value that determines how the control is resized to display items.

Syntax

bMode = ComboBox.NoIntegralHeight

ComboBox.NoIntegralHeight = bMode

Element | Description
bMode | True specifies that the size of the combo box is exactly the size specified by the application when it created the combobox. Normally, Windows sizes a combobox so that the combobox does not display partial items. False indicates that Windows may resize the ComboBox.

Remarks

This property changes the appearance of the ComboBox.


OEMConvert Property

The OEMConvert property sets or gets a value that determines whether or not text entered in the edit control is converted from the ANSI character set to the OEM character set and then back to ANSI.

Syntax

bMode = ComboBox.OEMConvert

ComboBox.OEMConvert = bMode

Element | Description
bMode | True indicates that the ComboBox performs the conversion; False that it does not.

Remarks

Not commonly used.


RightAlignedText Property

The RightAlignedText property sets or gets a value that determines whether the text is right justified.

Syntax

bMode = ComboBox.RightAlignedText

ComboBox.RightAlignedText = bMode

Element | Description
bMode | True indicates that the text is right-justified; False that it is not.

Remarks

Right justification is often useful for numerical inputs.


RightToLeftReadingOrder Property

The RightToLeftReadingOrder property sets or gets a value that determines whether the text is read right-to-left.

Syntax

bMode = ComboBox.RightToLeftReadingOrder

ComboBox.RightToLeftReadingOrder = bMode

Element | Description
bMode | True indicates that the text ordering is right-to-left; False indicates left-to-right.

Remarks

Language localization may require this for languages that use a different ordering than English.


Sort Property

The Sort property sets or gets whether the ComboBox items are displayed in alphabetical order.

Syntax

bMode = ComboBox.Sort

ComboBox.Sort = bMode

Element | Description
bMode | True indicates that contents of ComboBox will be sorted; False indicates that contents appear in original order.

Remarks

Affects display only. Internally, items remain in original order.


StaticEdge Property

The StaticEdge property sets or gets a value that determines the appearance of the ComboBox.

Syntax

bMode = ComboBox.StaticEdge

ComboBox.StaticEdge = bMode

Element | Description
bMode | True indicates that a static edge is used; False indicates that it is not.

Remarks

Changes the appearance of the ComboBox.


Style Property

The Style property sets or gets the style of the ComboBox.

Syntax

intStyle = ComboBox.Style

ComboBox.Style = intStyle

Element | Description
intStyle | Setting for style is usually done at design time via a dropdown list on the Properties dialog. See remarks below.

Remarks

Either Simple (Style = 0), Dropdown (Style = 1) or DropdownList (Style = 2).

SIMPLE. The list box is displayed at all times. The current selection in the list box is displayed in the edit control.

DROPDOWN. Similar to SIMPLE, except that the list box is not displayed unless the user selects an icon next to the edit control.

DROPDOWNLIST. Similar to DROPDOWN, except that the edit control is replaced by a static-text item that displays the current selection in the list box.


Transparent Property

The Transparent property sets or gets a value that determines whether the control "underneath" is visible.

Syntax

bMode = ComboBox.Transparent

ComboBox.Transparent = bMode

Element | Description
bMode | True indicates that the ComboBox is transparent; False indicates that it is solid.

Remarks

Usually Transparent is left at default False value.


Uppercase Property

The Uppercase property sets or gets a value that determines the case of the text permitted in the ComboBox.

Syntax

bMode = ComboBox.Uppercase

ComboBox.Uppercase = bMode

Element | Description
bMode | True indicates that the added text will be converted to uppercase; False indicates that this is not enforced.

Remarks

The Uppercase property can be used to filter input. See also the Lowercase property.


VerticalScroll Property

The VerticalScroll property gets or sets whether a verticall scrollbar is visible in the ComboBox.

Syntax

bMode = ComboBox.VerticalScroll

ComboBox.VerticalScroll = bMode

Element | Description
bMode | True indicates that the control will create a vertical scrollbar on the right side; False indicates that no scrollbar will be visible.


AddString Method

The AddString method adds a string item to the ComboBox

Syntax

longRet = ComboBox.AddString(strItem as String)

Element | Description
longRet | Returns the index at which string was added.
strItem | A string to be added to the ComboBox.

Remarks

Adds a string to the end of the list. If Sort is TRUE, a string is inserted into the list in its sorted position.


DeleteString Method

The DeleteString method deletes a string item from the ComboBox

Syntax

longRet = ComboBox.DeleteString(intItem as Integer)

Element | Description
longRet | Returns the index from which the string was deleted.
intItem | A integer indicating the index of the item to remove.


FindString Method

The FindString method finds the index of a particular item in a ComboBox.

Syntax

longRet = ComboBox.FindString(longStartAfter as Long, strItem as String)

Element | Description
longRet | Returns the index at which the string was found or LBERR if not found.
strItem | The string to search for.
longStartAfter | An integer indicating the index at which to begin search. If set to -1, entire ComboBox is searched.

Remarks

Search is case independent.


FindStringExact Method

The FindStringExact method finds the index of a particular item in a ComboBox.

Syntax

longRet = ComboBox.FindStringExact(longStartAfter as Long, strItem as String)

Element | Description
longRet | Returns the index at which the string was found or LBERR if not found.
strItem | The string to search for.
longStartAfter | An integer indicating the index at which to begin search. If set to -1, entire ComboBox is searched.

Remarks

Search is case independent.


GetEditText Method

The GetText method gets the text in the editbox portion of the control.

Syntax

strRet = ComboBox.GetEditText()

Element | Description
strRet | The string in the edit portion of the control

Remarks

Can be used to return user-entered text from the editbox portion of the control.


GetText Method

The GetText method get the text of an item at a specified index.

Syntax

strRet = ComboBox.GetText(longIndex as Long)

Element | Description
strRet | The string at the specified index.
longIndex | The index at which to find the text.

Remarks

Commonly used method to retrieve text of desired item.


InsertString Method

The InsertString method inserts a string into the ComboBox at a specified index.

Syntax

longRet = ComboBox.InsertString(longIndex as Long, strItem as String)

Element | Description
longRet | Returns the index at which the string was inserted.
longIndex | The location at which to insert the string.
strItem | A string to be inserted into the ComboBox.


Recalculate Method

The Recalculate method recalculates the control.

Syntax

ComboBox.Recalculate()

Remarks

Use within the framework of the Mathcad worksheet to force the scripted object to recalculate. This fires the Start, Exec, and Stop events. This method can be called from within events the control might listen for, including the SelChanged event. After the ComboBoxc recalculates, any dependent expressions in the Mathcad worksheet will also update if AutoCalculate is on.


ResetContent method

The ResetContent method removes all strings from the ComboBox.

Syntax

ComboBox.ResetContent()

Remarks

Use to clear the contents of the ComboBox.


SelectString Method

The SelectString method selects the string at a specified index of the ComboBox.

Syntax

longRet = ComboBox.SelectString(longStartAfter as Long, strItem as String)

Element | Description
longRet | Returns the index of the selected string, else returns CBERR if the string is not found.
longStartAfter | The location at which to start searching. -1 indicates to search the entire ComboBox.
strItem | A string to select.


DblClick Event

The DblClick event is fired when the ComboBox is double clicked.

Syntax

Private Sub ComboBox_DblClick()

Remarks

Can be used to confirm user selection. Within the Mathcad framework, the Recalculate method can be called be called to update the control. In the Exec event you would provide code that uses the GetEditText or GetText methods to get the desired string.


Error Event

The Error event is fired when an error occurs.

Syntax

Private Sub ComboBox_Error(short Number, BSTR* Description, SCODE Scode, BSTR Source, BSTR HelpFile, long HelpContext, boolean* CancelDisplay);


SelChanged Event

The SelChanged event is fired when the selection in the ComboBox changes.

Syntax

Private Sub ComboBox_SelChanged()

Remarks

The most commonly used event to handle a user selection. Within the Mathcad framework, the Recalculate method can be called be called to update the control. In the Exec event you would provide code that uses the GetEditText or GetText methods to get the desired string.


AcceptFiles Property

The AcceptFiles property sets or gets whether the ListBox accepts files via drag and drop. This property is disabled and can not be used programmatically.


Border Property

The Border property sets or gets whether the ListBox has a border.

Syntax

bMode = ListBox.Border

ListBox.Border = bMode

Element | Description
bMode | True indicates that a border is visible; False indicates that it is not.

Remarks

Changes the appearance of the ListBox.


ClientEdge Property

The ClientEdge property sets or gets whether the ListBox has a client edge.

Syntax

bMode = ListBox.ClientEdge

ListBox.ClientEdge = bMode

Element | Description
bMode | True indicates that the ListBox has a client edge; False indicates that it does not.

Remarks

Changes the appearance of the ListBox.


Count Property

The Count property is read-only and returns the number of items in the ListBox.

Syntax

longCount = ListBox.Count

Element | Description
longCount | The number of items in the ListBox.

Remarks

This important property can be used to set up a loop to iterate through the control using methods such as GetText.


CurSel Property

The CurSel property sets or gets the index of the currently selected item in the ListBox.

Syntax

longSelIndex = ListBox.CurSel

ListBox.CurSel = longSelIndex

Element | Description
longSelIndex | The index of the selected item or item to select. Zero based.

Remarks

Note that index is zero based, so first item in list has index of 0. Returns constant LBERR if no item selected.


DisableNoScroll Property

The DisableNoScroll property sets or gets whether the ListBox shows a disabled scroll bar when it does not contain enough items to fill visible space.

Syntax

bMode = ListBox.DisableNoScroll

ListBox.DisableNoScroll = bMode

Element | Description
bMode | True indicates that a disabled scrollbar is shown when not enough items are present; False indicates that no scrollbar is shown.


HorizontalScroll Property

The HorizontalScroll property gets or sets whether a horizontal scrollbar is visible in the ListBox.

Syntax

bMode = ListBox.HorizontalScroll

ListBox.HorizontalScroll = bMode

Element | Description
bMode | True indicates that the control will create a vertical scrollbar on the right side; False indicates that no scrollbar will be visible.


LBERR Property

The LBERR property sets or gets the LBERR constant.

Syntax

longLBERR = ListBox.LBERR

ListBox.LBERR = longLBERR

Element | Description
longLBERR | A value that indicates the setting of the LBERR constant.

Remarks

LBERR constant is returned as error by CurSel property when no item is selected.


LBERRSPACE Property

The LBERRSPACE property sets or gets the LBERRSPACE constant.

Syntax

longLBERR SPACE = ListBox.LBERRSPACE

ListBox.LBERRSPACE = longLBERR SPACE

Element | Description
longLBERR SPACE | A value that indicates the setting of the LBERRSPACE constant.


ModalFrame Property

The ModalFrame property sets or gets a value that determines whether a modal frame is used.

Syntax

bMode = ListBox.ModalFrame

ListBox.ModalFrame = bMode

Element | Description
bMode | True indicates that the ListBox has a modal frame; False indicates that it does not.

Remarks

This setting affects the appearance of the ListBox only.


RightAlignedText Property

The RightAlignedText property sets or gets a value that determines whether the text is right justified.

Syntax

bMode = ListBox.RightAlignedText

ListBox.RightAlignedText = bMode

Element | Description
bMode | True indicates that the text is right-justified; False that it is not.

Remarks

Right justification is often useful for numerical inputs.


RightToLeftReadingOrder Property

The RightToLeftReadingOrder property sets or gets a value that determines whether the text is read right-to-left.

Syntax

bMode = ListBox.RightToLeftReadingOrder

ListBox.RightToLeftReadingOrder = bMode

Element | Description
bMode | True indicates that the text ordering is right-to-left; False indicates left-to-right.

Remarks

Language localization may require this for languages that use a different ordering than English.


Sort Property

The Sort property sets or gets whether the ListBox items are displayed in alphabetical order.

Syntax

bMode = ListBox.Sort

ListBox.Sort = bMode

Element | Description
bMode | True indicates that contents of ListBox will be sorted; False indicates that contents appear in original order.

Remarks

Affects display only. Internally, items remain in original order.


StaticEdge Property

The StaticEdge property sets or gets a value that determines the appearance of the ListBox.

Syntax

bMode = ListBox.StaticEdge

ListBox.StaticEdge = bMode

Element | Description
bMode | True indicates that a static edge is used; False indicates that it is not.

Remarks

Changes the appearance of the ListBox only.


Transparent Property

The Transparent property sets or gets a value that determines whether the control "underneath" is visible.

Syntax

bMode = ListBox.Transparent

ListBox.Transparent = bMode

Element | Description
bMode | True indicates that the ListBox is transparent; False indicates that it is solid.

Remarks

A ListBox is often rendered as solid.


VerticalScroll Property

The VerticalScroll property gets or sets whether a verticall scrollbar is visible in the ListBox.

Syntax

bMode = ListBox.VerticalScroll

ListBox.VerticalScroll = bMode

Element | Description
bMode | True indicates that the control will create a vertical scrollbar on the right side; False indicates that no scrollbar will be visible.


AddString Method

The AddString method adds a string item to the ListBox.

Syntax

longRet = ListBox.AddString(strItem as String)

Element | Description
longRet | Returns the index at which string was added.
strItem | A string to be added to the ListBox.

Remarks

Adds a string to the end of the list. If Sort if TRUE, string is inserted into the list in its sorted position.


DeleteString Method

The DeleteString method deletes a string item from the ListBox

Syntax

longRet = ListBox.DeleteString(intItem as Integer)

Element | Description
longRet | Returns the index from which the string was deleted.
intItem | A integer indicating the index of the item to remove.


FindString Method

The FindString method finds the index of a particular item in a ListBox.

Syntax

longRet = ListBox.FindString(longStartAfter as Long, strItem as String)

Element | Description
longRet | Returns the index at which the string was found or LBERR if not found.
strItem | The string to search for.
longStartAfter | An integer indicating the index at which to begin search. If set to -1, entire ListBox is searched.

Remarks

Search is case independent.


FindStringExact Method

The FindStringExact method finds the index of a particular item in a ListBox.

Syntax

longRet = ListBox.FindStringExact(longStartAfter as Long, strItem as String)

Element | Description
longRet | Returns the index at which the string was found or LBERR if not found.
strItem | The string to search for.
longStartAfter | An integer indicating the index at which to begin search. If set to -1, entire ListBox is searched.

Remarks

Search is case independent.


GetText Method

The GetText method get the text of an item at a specified index.

Syntax

strRet = ListBox.GetText(longIndex as Long)

Element | Description
strRet | The string at the specified index.
longIndex | The index at which to find the text.

Remarks

Note that index is zero based.


InsertString Method

The InsertString method inserts a string into the ListBox at a specified index.

Syntax

longRet = ListBox.InsertString(longIndex as Long, strItem as String)

Element | Description
longRet | Returns the index at which the string was inserted.
longIndex | The location at which to insert the string.
strItem | A string to be inserted into the ListBox.


Recalculate Method

The Recalculate method recalculates the control.

Syntax

ListBox.Recalculate()

Remarks

Use within the framework of the Mathcad worksheet to force the scripted object to recalculate. This fires the Start, Exec, and Stop events. This method can be called from within events the control might listen for, including the SelChanged event. After the ListBox recalculates, any dependent expressions in the Mathcad worksheet will also update if AutoCalculate is on.


ResetContent Method

The ResetContent method removes all strings from the ListBox.

Syntax

ListBox.ResetContent()

Remarks

Use to clear the contents of the ListBox.


SelectString Method

The SelectString method selects the string at a specified index of the ListBox.

Syntax

longRet = ListBox.SelectString(longStartAfter as Long, strItem as String)

Element | Description
longRet | Returns the index of the selected string, else returns LBERR if the string is not found.
longStartAfter | The location at which to start searching. -1 indicates to search the entire ListBox.
strItem | A string to select.


DblClick Event

The DblClick event is fired when the ListBox is double clicked.

Syntax

Private Sub ListBox_DblClick()

Remarks

Can be used to confirm user selection. Within Mathcad framework, the Recalculate method can be called to update control and retrieve the current selection, for example.


Error Event

The Error event is fired when an error occurs.

Syntax

Private Sub ListBox_Error(short Number, BSTR* Description, SCODE Scode, BSTR Source, BSTR HelpFile, long HelpContext, boolean* CancelDisplay);


SelChanged Event

The SelChanged event is fired when the selection in the ListBox changes.

Syntax

Private Sub ListBox_SelChanged()

Remarks

Can be used to confirm user selection. Within the Mathcad framework, the Recalculate method can be called to update control and retrieve the current selection in the Exec event handler, using the CurSel property and the GetText method.


Auto Property

The Auto property sets or gets a value that determines whether the Button handles its state.

Syntax

bMode = Button.Auto

Button.Auto = bMode

Element | Description
bMode | True indicates that the Button handles its state; False indicates that the state must be handled manually.


AutoSize Property

The AutoSize property sets or gets whether autosize is active.

Syntax

bMode = Button.AutoSize

Button.AutoSize = bMode

Element | Description
bMode | True indicates that autosize is active; false indicates that autosize is not active.

Remarks

Use to resize control automatically based on caption length.


Bitmap Property

The Bitmap property is used by the Properties pages to set the bitmap image for the Button. Not used programmatically.


ButtonID Property

The ButtonID property sets or gets a number that is used as reference when control is part of a radio Button group.

Syntax

intID = Button.ButtonID

Button.ButtonID = intID

Element | Description
intID | Number that is used to reference control in radio-Button group.


ButtonStyle Property

The ButtonStyle property sets or gets a number that determines the style of the Button.

Syntax

intStyle = Button.ButtonStyle

Button.ButtonStyle = intStyle

Element | Description
intStyle | Number that defines the style of the Button; either default checkbox (1), push button (0), or radio button (2).

Remarks

Note that this property can be set from Properties pages via a drop down list. For further control over the Button's appearance, see the Type grouping on the General tab of the Properties page.


Check Property

The Check property sets or gets a value that determines the checked state of the Button.

Syntax

bMode = Button.Check

Button.Check = bMode

Element | Description
bMode | True indicates that the radio button is selected or checkbox is checked; False indicates that it is unchecked.

Remarks

The Check property of the Button is commonly queried after the Click event. Not applicable to Button when push button style is selected.


Enabled Property

The Enabled property sets or gets a value that determines whether an object can respond to user-generated events.

Syntax

bMode = Button.Enabled

Button.Enabled = bMode

Element | Description
bMode | True indicates that Button can be checked and unchecked; False indicates that it can not.

Remarks

If Button is disabled, it can not receive user events.


Flat Property

The Flat property sets or gets a value that determines the appearance of the Button, whether flat or 3D.

Syntax

bMode = Button.Flat

Button.Flat = bMode

Element | Description
bMode | True indicates that Button has a flat appearance; False indicates that Button has the more common 3D appearance.


Font Property

The Font property is used by the Properties page to set the font for the caption. Not used programmatically.


GroupID Property

The GroupID property sets or gets a number that is used to a group of radio buttons.

Syntax

intID = Button.GroupID

Button.GroupID = intID

Element | Description
intID | Number that is used to refer to a group of radio buttons.


HorizontalAlignment Property

Not currently used.


Icon Property

The Icon property is used by the Properties page to set the icon image for the button. Not used programmatically.


LeftText Property

The LeftText property sets or gets a value that determines whether the Button's caption is left aligned.

Syntax

bMode = Button.LeftText

Button.LeftText = bMode

Element | Description
bMode | True indicates that Button's caption is left-aligned; False indicates that it is not.


Multiline Property

The Multiline property sets or gets a value that determines whether the Button's caption can wrap to multiple lines.

Syntax

bMode = Button.Multiline

Button.Multiline = bMode

Element | Description
bMode | True indicates that Button's caption can occupy multiple lines; False indicates that it can only occupy a single line.

Remarks

This properly is commonly used when the text might occupy more than one line.


PushLike Property

The PushLike property sets or gets a value that determines the appearance of the checkbox.

Syntax

bMode = Button.PushLike

Button.PushLike = bMode

Element | Description
bMode | True indicates that the checkbox should appear to user as a push button; False indicates that it does not.

Remarks

If PushLike is set to true, Button can be toggled much like a checkbox.


Text Property

The Text property sets or gets the caption of the Button.

Syntax

stringText = Button.Text

Button.Text = stringText

Element | Description
stringText | A string that indicates the Button's caption.

Remarks

Can be set via Properties page or dynamically at run-time.


UseBitmap Property

The UseBitmap property sets or gets a value that determines whether the Button uses a bitmap for its face.

Syntax

bMode = Button.UseBitmap

Button.UseBitmap = bMode

Element | Description
bMode | True indicates that the Button uses a bitmap image; False that it uses only the text caption.


UseIcon Property

The UseIcon property sets or gets a value that determines whether the Button uses a icon for its face.

Syntax

bMode = Button.UseIcon

Button.UseIcon = bMode

Element | Description
bMode | True indicates that the Button uses an icon for its face; False indicates that it uses only the caption.


VerticalAlignment Property

Not currently used.


AboutBox Method

The AboutBox method displays the about box dialog.

Syntax

Button.AboutBox()


Recalculate Method

The Recalculate method recalculates the control.

Syntax

Button.Recalculate()

Remarks

Use within the framework of the Mathcad worksheet to force the scripted object to recalculate. This fires the Start, Exec, and Stop events. This method can be called from within events the control might listen for, such as the Click event. After the Button recalculates, any dependent expressions in the Mathcad worksheet will also update if AutoCalculate is on.


SelectedButton Method

The SelectedButton method returns the Button ID of the selected button in a button group.

Syntax

int Ret = Button.SelectedButton()

Element | Description
intRet | Returns the button ID of the button in the button group


Click Event

The Click event is fired when the button is single clicked.

Syntax

Private Sub Button_Click()

Remarks

This event is commonly used for the button, checkbox, or pushbutton styles to process code. In the Click event handler, you would likely call the Recalculate method. Then in the Exec event handler, you would query the Check property to determine the state of the Button.


DblClick Event

The DblClick event is fired when the button is double clicked.

Syntax

Private Sub Button_DblClick()

Remarks

Not commonly used for buttons.


Error Event

The Error event is fired when an error occurs.

Syntax

Private Sub Button_Error(short Number, BSTR* Description, SCODE Scode, BSTR Source, BSTR HelpFile, long HelpContext, boolean* CancelDisplay);


KeyDown Event

The KeyDown event is fired when a key is pressed.

Syntax

Private Sub Button_KeyDown(KeyCode As Integer, Shift As Integer)

Element | Description
KeyCode | An integer that represents the key code of the key that was pressed or released.
Shift | The state of SHIFT, CTRL, and ALT.

Remarks

KeyDown, KeyPress, and KeyUp are fired in sequence.


KeyPress Event

The KeyPress event is fired when a key is pressed.

Syntax

Private Sub Button_KeyPress(KeyAscii As Integer)

Element | Description
KeyAscii | An integer value that represents a standard numeric ANSI key code.

Remarks

Commonly used to intercept keystrokes received by a form or control.


KeyUp Event

The KeyUp event is fired when a key is released.

Syntax

Private Sub Button_KeyUp(KeyCode As Integer, Shift As Integer)

Element | Description
KeyCode | An integer that represents the key code of the key that was pressed or released.
Shift | The state of SHIFT, CTRL, and ALT.

Remarks

KeyPress event is more commonly handled.


MouseDown Event

The MouseDown event is fired when the user presses a mouse button.

Syntax

Private Sub Button_MouseDown(Button As Integer, Shift As Integer, x As OLE_XPOS_PIXELS, y As OLE_YPOS_PIXELS)

Element | Description
Button | An integer value that identifies which mouse button caused the event.
Shift | The state of SHIFT, CTRL, and ALT.
x,y | The horizontal or vertical position, in points, from the left or top edge of the form, Frame, or Page.


MouseMove Event

The MouseMove event is fired when the user moves the mouse over the control.

Syntax

Private Sub Button_MouseMove(Button As Integer, Shift As Integer, x As OLE_XPOS_PIXELS, y As OLE_YPOS_PIXELS)

Element | Description
Button | An integer value that identifies which mouse button caused the event.
Shift | The state of SHIFT, CTRL, and ALT.
x,y | The horizontal or vertical position, in points, from the left or top edge of the form, Frame, or Page.


MouseUp Event

The MouseUp event is fired when the user releases the mouse button.

Syntax

Private Sub Button_MouseUp(Button As Integer, Shift As Integer, x As OLE_XPOS_PIXELS, y As OLE_YPOS_PIXELS)

Element | Description
Button | An integer value that identifies which mouse button caused the event.
Shift | The state of SHIFT, CTRL, and ALT.
x,y | The horizontal or vertical position, in points, from the left or top edge of the form, Frame, or Page.


ReadyStateChange Event

The ReadyStateChange event is fired when a control transitions to the next ready state due to the amount of data received.

Syntax

Private Sub Button_ReadyStateChange()


SelectionChange Event

The SelectionChange event is fired when the selection of the Radio-Button group changes.

Syntax

Private Sub Button_SelectionChange()


ClientEdge Property

The ClientEdge property sets or gets whether the Slider has a client edge.

Syntax

bMode = Slider.ClientEdge

Slider.ClientEdge = bMode

Element | Description
bMode | True indicates that the Slider has a client edge; False indicates that it does not.

Remarks

Affects the appearance of the Slider.


StaticEdge Property

The StaticEdge property sets or gets whether the Slider has a static edge.

Syntax

bMode = Slider.StaticEdge

Slider.StaticEdge = bMode

Element | Description
bMode | True indicates that a static edge is used; False indicates that it is not.

Remarks

Affects the appearance of the Slider.


Transparent Property

The Transparent property sets or gets a value that determines whether the control "underneath" is visible.

Syntax

bMode = Slider.Transparent

Slider.Transparent = bMode

Element | Description
bMode | True indicates that the Slider is transparent; False indicates that it is solid.


Border Property

The Border property sets or gets whether the Slider has a border.

Syntax

bMode = Slider.Border

Slider.Border = bMode

Element | Description
bMode | True indicates that a border is visible; False indicates that it is not.

Remarks

Affects the appearance of the Slider.


AutoTicks Property

The AutoTicks property sets or gets whether the slider displays a tick mark for each increment in its range of values.

Syntax

bMode = Slider.AutoTicks

Slider.AutoTicks = bMode

Element | Description
bMode | True indicates that a tick appears for each increment in the range; False indicates that the TickFrequency property determines the tick mark frequency.

Remarks

Used to adjust the number of ticks on the Slider.


Ticks Property

The Ticks property sets or gets whether the slider displays tick marks.

Syntax

bMode = Slider.Ticks

Slider.Ticks = bMode

Element | Description
bMode | True indicates that ticks are shown; False indicates that no ticks are shown.

Remarks

Affects the appearance of the Slider.


EnableSelection Property

The EnableSelection property sets or gets whether a selection range is displayed that highlights a portion of the Slider's range.

Syntax

bMode = Slider.EnableSelection

Slider.EnableSelection = bMode

Element | Description
bMode | True indicates that a portion of the range can be selected and highlighted; False indicates single value selection only.

Remarks

Affects the appearance of the Slider.


MinRange Property

The MinRange property gets or sets the minimum value of the control.

Syntax

longMin = Slider.MinRange

Slider.MinRange = longMin

Element | Description
longMin | A value that indicates the minimum value of the Slider control.

Remarks

This property can also be accessed via the Properties page.


MaxRange Property

The MaxRange property gets or sets the maximum value of the control.

Syntax

longMax = Slider.MaxRange

Slider.MaxRange = longMax

Element | Description
longMax | A value that indicates the maximum value of the Slider control.

Remarks

This property can also be accessed via the Properties page.


Orientation Property

The Orientation property gets or sets a value that indicates the orientation of the Slider control.

Syntax

longOrientation = Slider.Orientation

Slider.Orientation = longOrientation

Element | Description
longOrientation | Defines the orientation of the slider. 0 = horizontal Slider, 1 = vertical Slider.

Remarks

Affects the appearance of the Slider. This property can also be accessed via the Properties page.


Point Property

The Point property gets or sets a value that indicates the style of the pointer.

Syntax

longStyle = Slider.Point

Slider.Point = longStyle

Element | Description
longStyle | Defines the pointer style. 0 = no point, 1 = top / left, 2 = right/bottom.

Remarks

Setting the property to 0 gives a rectangular pointer. Setting the property to 1 gives a pointer toward the top or left. Setting the property to 2 gives a pointer toward the right or bottom.


Position Property

The Position property gets or sets a value that indicates the logical position of the pointer.

Syntax

longPos = Slider.Position

Slider.Position = longPos

Element | Description
longPos | A value that determines the logical position of the pointer.

Remarks

This is probably the most important property of the Slider control. Use this property to get the current position by invoking the Recalculate method in the Valuechanged event, and querying this property in the Exec event.


TickFrequency Property

The TickFrequency property gets or sets a value that indicates the spacing of the ticks on the Slider.

Syntax

longFreq = Slider.TickFrequency

Slider.TickFrequency = longFreq

Element | Description
longFreq | A value that determines the spacing of the ticks.

Remarks

This value determines the spacing of the ticks. For example, with a MinRange = 0 and a MaxRange = 100, setting TickFrequency = 20 would give 5 divisions with 6 tick marks total. For even tick spacing, the (MaxRange-MinRange)/TickFrequency should be a whole number.


LineSize Property

The LineSize property gets or sets a value that indicates a small interval for moving the slider with the keyboard or mouse wheel.

Syntax

longLineSize = Slider.LineSize

Slider.LineSize = longLineSize

Element | Description
longLineSize | A value that indicates the small incremental adjustment to the Slider position while using the keyboard or mouse wheel.

Remarks

Affects the feel and operation of the Slider. Use a small value to allow fine adjustment of the slider via the arrow keys.


PageSize Property

The PageSize property gets or sets a value that indicates a large interval for moving the slider with the keyboard or mouse wheel.

Syntax

longPageSize = Slider.PageSize

Slider.PageSize = longPageSize

Element | Description
longPageSize | A value that indicates the large incremental adjustment to the Slider position while using the keyboard or mouse wheel.

Remarks

Affects the operation of the Slider. Use a large value to quickly change the Slider position using the Page Up and Page Down keys, or by clicking to either side of the Slider pointer. Use Home and End to move quickly to the MinRange and MaxRange values via the keyboard, independent of the PageSize setting.


NumTicks Property

The NumTicks property is a read-only property that indicates how many ticks are displayed, including the first and last ticks that are always created.

Syntax

longNumTicks = Slider.NumTicks

Element | Description
longNumTicks | A value that indicates the number of ticks displayed on the Slider.

Remarks

A read-only property. See TickFrequency property to set the number of ticks on the Slider.


SelectionLow Property

The SelectionLow property gets or sets a value that indicates the low value of the selection range

Syntax

longSelLow = Slider.SelectionLow

Slider.SelectionLow = longSelLow

Element | Description
longSelLow | A value that indicates the low value of the selection range.

Remarks

The value for the SelectionLow property must be within the MinRange and MaxRange properties and less than the SelectionHigh property.


SelectionHigh Property

The SelectionHigh property gets or sets a value that indicates the high value of the selection range

Syntax

longSelHigh = Slider.SelectionHigh

Slider.SelectionHigh = longSelHigh

Element | Description
longSelHigh | A value that indicates the high value of the selection range.

Remarks

The value for the SelectionHigh property must be within the MinRange and MaxRange properties and greater than the SelectionLow property.


Recalculate Method

The Recalculate method recalculates the control.

Syntax

Slider.Recalculate()

Remarks

Use within the framework of the Mathcad worksheet to force the scripted object to recalculate. This fires the Start, Exec, and Stop events. This method can be called from within events the control might listen for, including the Valuechanged event. After the Slider control recalculates, any dependent expressions in the Mathcad worksheet will also update if AutoCalculate is on.


Valuechanged Event

The Valuechanged event is fired when the Sliders pointer has changed position.

Syntax

Private Sub Slider_Valuechanged()

Remarks

This is the only event the Slider control handles. In this event handler, you commonly would call the Recalculate method. In your Exec event, you would retrieve the current value of the Position property as an output.


Scripting

Scripting OLE Automation Objects in Mathcad and MathConnex

Mathcad and MathConnex expose a component that allows you to script an OLE Automation object for use within the Mathcad or MathConnex computational environment. This component uses the Microsoft ActiveX Scripting specification, allowing you to use standard scripting languages to “drive” the Automation object. While these languages provide features that allow you, the developer, to communicate with the OLE object, they do not have any intrinsic facilities for communicating with the outside environment (in this case, either Mathcad or MathConnex). For a scripted object to be useful in a computation, it must have a mechanism for processing inputs and sending outputs to and from the host environment. The Scriptable Object component, using the Scripting Object model, solves this problem by providing a framework for scripting languages to interact with Mathcad or MathConnex.


Event-Driven vs. Procedural

Most programming languages are structured to be executed as a series of statements: either in a top-down fashion starting with the first statement encountered, or with a predefined entry point (such as main() in the C language). This procedural approach assumes a program which will be executed linearly, continuously executing statements until the last statement is reached. While this works well in a variety of contexts, it's not as useful in an environment which is event-driven. In an event driven environment, the program doesn't execute in such a continuous fashion, but rather is called upon to do work based on the triggering of an outside event. This is typically accomplished by defining one or more event functions which are called by the event controller whenever an appropriate event is triggered.


Overview of Events

The scripting component has adopted an event-driven model to serve as the framework for scripting components. This model defines three basic events which are triggered by the outside (host) environment. These are discussed in the following sections.


Start Event

The "Start" event is fired by the host environment whenever a computation is started. This is a good place for scripts to set initialization variables, open files for reading or writing, etc. This is called once before the computation actually begins.

Example VBScript code:

Sub MyControlEvent_Start()

'place code here to handle initialization, etc.

End Sub


Exec Event

This event is fired when the host environment supplies inputs and requests any outputs from the script. There are two parameters defined for the Exec function: Inputs and Outputs. These parameters are objects of type DataValue. See the description of the DataValues Collection for details.

Example VBScript code:

Sub MyControlEvent_Exec(Inputs,Outputs)

'put your code here handling Inputs from Mathcad 'worksheet and Outputs to return to Mathcad worksheet 'if desired

End Sub

Note:

  • It is possible for this event function to be called many times after a single Start event is triggered. This can happen in environments where repeated computation is required during a single recalculation of the host environment. (MathConnex is an example of this kind of environment, since the user presses "Run" and repeated computations may occur before the worksheet is stopped.) Script writers should put any "one-time" initialization code in the Start event so that the script is able to handle repeated calls to Exec for processing of input and output data.


Stop Event

This event is fired to tell the script that the current computation has stopped. It will only be called after the Start event has been called. This is a good place for cleanup of data, closing any open files, etc.

Example VBScript code:

Sub MyControlEvent_Stop()

'place code here to handle cleanup, closing files, 'etc.

End Sub

Note:

  • It is possible for the Start and Stop event to be triggered one after the other without the Exec event ever being triggered. This can happen in cases where the computation begins but the input data is never available to the script component, preventing it from executing.


Event Function Implementation

The actual event function syntax is language-specific. Most scripting languages provide a standard mechanism for event functions, usually a combination of the object which defines the event (sometimes referred to as the object which sources the event) and the name of the event. When a script contains a function which matches the naming convention used for the event, the language "attaches" the function to the event so that it is called whenever the event is fired. VBScript, for example, uses the name of the event source, followed by an underscore, followed by the event name. So if an object called "MyEventSrc" defined an event handler called "Event1", then the VBScript function would look something like this:

Sub MyEventSrc_Event1( )

' do something when the event is triggered

End Sub

The event functions are defined in an OLE object's type library. The script writer must be aware that the events exist and the names used for them in order to provide appropriate event handler functions in the script.


Introduction

The JScript language is a relatively recent addition to the scripting support provided by Microsoft, and is a language originally developed by Netscape for scripting of web pages. Due to this history, JScript doesn't always follow the common conventions for automation languages. The following summarizes the main differences between an "automation" language such as VBScript and JScript.


Events

JScript has two main differences with a language such as VBScript when it comes to providing event handlers in the scripting language. First, JScript is case sensitive, whereas VBScript is not. As a result, care must be taken when writing event handling functions in JScript since the names "foo()" and "Foo()" are considered two different functions.

Secondly, JScript's event mechanism is similar to VBScript except that you must specify the event by the object name followed by a double colon (::) followed by the event name (respecting upper-lower case conventions). Thus the following event handlers would be valid event handlers in VBScript and JScript, respectively:

VBScript

Sub MyEventSrc_Event1()

'add your code here

End Sub

JScript

function MyEventSrc::Event1()
{
// add your code here
}


Collections

Collections are natively supported in VBScript using the For Each&ldots;Next syntax. Although JScript provides a similar for (x in y) type of mechanism, the current implementation does not appear to work with automation collections. This is only a convenience, since collections can still be accessed with the standard for loop syntax in both languages.


Comparison With Variant Arrays

Arrays in VBScript follow the standard automation variant object. That is, if you create a variant array used in automation, the array elements can be directly accessed via VBScript. JScript uses an internal representation for arrays and therefore will not be able to access variant arrays. This is a serious limitation, since most automation objects which deal in arrays will represent them as variant arrays. To avoid this limitation for the arrays represented in a DataValue object, the Value and IValue properties of the DataValue object are overloaded to allow a column and row index to be supplied. This means that scripting languages that do not support variant arrays natively can still access data values through the use of indexing.


Multi-Dimensional Arrays

JScript's internal array creation mechanism only supports single-dimension arrays. Therefore you can declare an array of 5 elements (x=new Array(5)), but you cannot directly declare a 2D array. To circumvent this restriction, JScript allows "nested" arrays to achieve multiple dimensions. An example of this would be the following code which creates a 2x2 2D array:

var js2DArray = new Array(2);
for (var j = 0; j < js2DArray.length; j++)
{
// Prepare to fill it with rows.
var aRow = new Array(2); // Create a row.
for (var i = 0; i < aRow.length; i++)
{
// fill the row with zeroes.
 aRow[i] = 0;
}
// Put the row into the outer array.
js2DArray[j] = aRow;
}

Once a nested array is declared, elements in the array can be accessed using multiple sets of brackets ([]).. For example, js2DArray[col][row] is valid for the example above, while js2DArray[col,row] would generate an error.


Array Assignment

JScript does allow the assignment of variant array values from one object to another. This means that a variant array can be passed from an input DataValue to a scripted object, then back to an output DataValue as long as JScript is not used to access the elements in the variant array. Examples are provided at the end of this document to show the syntax for accessing the DataValue object with each language.

Internally created JScript arrays (i.e. x = new Array()) cannot be assigned to the methods or properties of Automation objects which expect variant arrays, since JScript represents arrays in a different format. Therefore the following sequence of statements is not valid in JScript:

var jsArray = new Array(5);
Outputs(0).Value = jsArray;


Intro to Scripting Object Model

Introduction to the Scripting Object Model

The following topics detail all methods, properties, and events exposed for scripts written with the Scriptable Object component. For convenience, the examples use VBScript style syntax unless otherwise noted.


alert Function

This function is provided mainly for compatibility with the JScript language. This function takes a single parameter as a string which will be presented to the user as a standard modal Windows message box with an OK button.

Syntax

alert(string)

Element

Description

string

A string to show.

Remarks

VBScript users will probably want to use the more extensive MsgBox function -- which is provided natively by the VBScript engine -- rather than the alert method.

Example Code

function MyEventSrc::Event1( )
{

// will pop up a message box with the following text

alert("In MyEventSrc_Event1!");
}

Note:

  • The example above uses the JScript language syntax.


errmsg Function

This function is provided mainly for compatibility with the JScript language. This function will display an error message from within the script and cause the script to stop execution. In some environments, this error message may include line number information for the source of the error.

The first parameter is the error message text. There is a second, optional parameter which can be used to display the source of the error.

Syntax

errmsg(msg,[src])

Element

Description

msg

A string to show.

src

Optional string that specifies a caption for the dialog.

Remarks

This function is similar to the alert function.

Example Code

// will pop up a message box with the following text

// and cause the script to stop execution

errmsg("An error has occured!");

// same effect, but with second parameter specified

errmsg("An error has occured", "My Script");

Note:

  • the example above uses the JScript language syntax.


Introduction

Collections are an Automation concept which allows a set of associated elements to be bundled together. Standard methods and properties are provided to allow access to each of the elements in the collection. Collections are directly supported in some languages, allowing easy iteration over the elements in the collection. VBScript supports collections through the For Each&ldots;Next construct. Languages that do not directly support collections can still iterate through the elements using the standard properties and methods described below.

The DataValues collection is used in the Exec event which has two DataValues collections as parameters. The first parameter (named "Inputs") is a collection of inputs. Each input element in the collection is an object of type DataValue. Script authors can iterate through elements and query the total number of elements in the collection. The "Outputs" parameter is also a collection of DataValue objects representing each output provided by the component. Script authors may set the data for each output object in the collection. These output values are then used by the host environment when the event function returns.


Count Property

The read-only Count property can be used to query the total number of elements in the collection.

Syntax

num = collDataValues.Count

Element

Description

num

Number of items in the DataValues collection

Remarks

Note that the collection is zero based.

Example Code

'cycle through the collection, assigning each item to a variable

for i= 0 to Inputs.Count-1
val = Inputs(i)

'additional code...

next


Item Method

The Item method is used to specify an individual element in the collection. The DataValues collection is zero-based, so the item numbers range from 0 to Count-1.

The Item method is the default method for this object; for languages that support it, this means that the method name can be omitted, in which case the default method is implied.

Syntax

collDataValues.Item( index )
collDataValues( index )

Element

Description

index

The index of the item to retrieve.

Remarks

Note that the DataValues collection is zero based.

Example Code

'retrieve each item from the collection

for i= 0 to Inputs.Count-1
val = Inputs.Item(i)

'additional code

next

or, since Item is the default property, the following is also valid:

for i= 0 to Inputs.Count-1
val = Inputs(i)
next

Note:

  • Although the example above shows VBScript, both VBScript and JScript support this shorthand approach for default methods and properties.


Value Property

The Value property is used to access the real portion of the data in the DataValue object.

Syntax

x = objDataValue.Value ( [row, col] )
objDataValue.Value ( [row, col] ) = x

Element

Description

x

The real portion of the data at this position.

row

The index of the desired row.

col

The index of the desired column.

Remarks

Note that the row and col parameters are optional. If the row and col parameters are omitted, then the value is returned as a 2D variant array of double values or as a 1D variant array of double values or as a scalar, depending on the type of data contained in the DataValue object. If the row and col parameters are specified, a scalar value at the specified row/column is returned.

When the Value property is used on the left hand side of an assignment, the array automatically grows (if necessary) to fit the data. For example, if Outputs(0) initially contains no data and the script writer does the following :

Outputs(0).Value(1,2) = 1

A 2 row, 3 column data value is created which contains the value "1" at row 1, col 2. If a value already exists and an assignment is made which exceeds the current maximum row or column, the value is automatically re-dimensioned to fit the new data. This feature of the Value property allows languages that do not directly support variant arrays (such as JScript) to create and access DataValue arrays.

Example Code

for i= 0 to Inputs.Count-1
valmatrix = Inputs(i).Value ' returns a whole matrix
valscalar = Inputs(i).Value(0,0) ' returns element at 0,0
next


IValue Property

The IValue property is used to access the imaginary portion of the data in the DataValue object.

Syntax

x = objDataValue.IValue ( [row, col] )
objDataValue.IValue ( [row, col] ) = x

Element

Description

x

The imaginary portion of the data at this position.

row

The index of the desired row.

col

The index of the desired column.

Remarks

Note that the row and col parameters are optional. If the row and col parameters are omitted, then the value is returned as a 2D variant array of double values or as a 1D variant array of double values or as a scalar, depending on the type of data contained in the DataValue object. If the row and col parameters are specified, a scalar value at the specified column/row representing the imaginary portion of the data is returned. Note that the DataValue object may not contain an imaginary value (e.g. it is a real number), in which case the IValue portion will return NIL.

Example Code

for i= 0 to Inputs.Count-1
valmatrix = Inputs(i).IValue ' returns a whole matrix
if (valmatrix != nil) then
valscalar = Inputs(i).IValue(1,0) ' returns element
end if
next


Rows Property

The Rows property is a read-only value which returns the number of rows in the DataValue object.

Syntax

x = objDataValue.Rows

Element | Description
x | The number of rows in the DataValue object.

Remarks

Can be used to determine the dimensions of a vector of array stored at a particular element at run-time. This provides flexibility and allows the programmer to avoid hard-coding a fixed number of rows.

Example Code

NumRows = Inputs(0).Rows


Cols Property

The Cols property is a read-only value which returns the number of columns in the DataValue object.

Syntax

x = objDataValue.Cols

Element | Description
x | The number of columns in the DataValue object.

Remarks

Can be used to determine the dimensions of a vector of array stored at a particular element at run-time. This provides flexibility and allows the programmer to avoid hard-coding a fixed number of columns.

Example Code

NumRows = Inputs(0).Cols


IsComplex Property

The IsComplex property is a read-only value which returns TRUE if the value has a valid imaginary portion (which can be accessed through the IValue property). If IsComplex returns FALSE, it can be assumed that the value has only a real portion.

Syntax

if (objDataValue.IsComplex) then&ldots;

Remarks

Could be used to filter input.

Example Code

'check a particular input and inform the user whether complex or real

if (Inputs(0).IsComplex ) then
MsgBox( "Complex Value!" )
else
MsgBox( "Real Value!" )
end if


Script Examples Introduction

Introduction to Script Examples

The following sections show sample scripts using two popular scripting engines within a MathConnex or Mathcad environment. Note that these examples are intended to give an impression of the syntactical conventions and how they apply to various object methods and properties, rather than a truly useful script.

The scripts below all accomplish the same task. They iterate through the available inputs, display the value of the first element in a popup message box, assign the input to the output, and finally add one to the first element of each output.


VBScript Examples

This version of the script will iterate through each available input using the For Each&ldots;Next construct.

Sub ScriptObjEvent_Start()

'Add your code here

End Sub
Sub ScriptObjEvent_Exec(Inputs,Outputs)
  Dim i
  Dim dataval
  i=0
  'loop through Inputs collection
  For each dataval in Inputs
    'extract value of this particular Input
    val = dataval.Value
    'pop up a message box to show progress through collection, using
    'only upper left element of array
    If IsArray(val) Then
      MsgBox "Input: " & CStr(i) & " is an array"
    Else
      MsgBox "Input: " & CStr(i) & ", Value: " & CStr(val)
    End If
    'just pass inputs to the outputs, incrementing
    'the first element at 0,0 position by 1
    If i < Outputs.Count Then
      If IsArray(val) Then
        On Error Resume Next
        vTemp = UBound(val,2)
        If Err.Number = 0 Then
          val(0,0) = val(0,0) + 1
        Else
          val(0) = val(0) + 1
        End If
      Else
      val = val + 1
      End If
      Outputs(i).Value = val
    End If
    i = i + 1
  Next
End Sub
Sub ScriptObjEvent_Stop()
  'Add your code here
End Sub

The second version accomplishes the same task without using the For Each&ldots;Next construct:

Sub ScriptObjEvent_Start()

'Add your code here

End Sub
Sub ScriptObjEvent_Exec(Inputs,Outputs)
Dim dataval

'use for/next construct to loop over inputs

for i=0 to Inputs.Count-1

'get the current input and its value

set dataval = Inputs(i)
val = dataval.Value

'pop up a message box to show progress through collection

MsgBox(val(0,0))

'just pass inputs on to the outputs, incrementing

'the first element by 1

if i < Outputs.Count then
val(0,0) = val(0,0)+1
Outputs(i).Value = val
end if
next
End Sub
Sub ScriptObjEvent_Stop()

'Add your code here

End Sub


JScript Examples

The JScript version of the VBScript Examples is shown below.

function ScriptObjEvent::Start()
{

// TODO: Add code here

}

function ScriptObjEvent::Exec(inputs,outputs)
{
  var dataval;
  for ( i=0; i<Inputs.Count; i++ )
  {
    // look at each dataval in the collection
    dataval = Inputs(i)
    // show what we found
    alert("Input: " + i.toString() + ", Value: " + dataval.Value(0,0).toString());
    // pass inputs on to outputs, incrementing
    // first element by one
    if ( i<Outputs.Count )
    {
      Outputs(i).Value = dataval.Value;
      Outputs(i).Value(0,0) += 1 ;
    }
  }
}
function ScriptObjEvent::Stop()
{

// TODO: Add code here

}


OLE Automation Object Model

Using Mathcad's OLE Automation Interface

Mathcad's OLE Automation interface provides a mechanism for communicating with Mathcad from within another Windows application. (If you are interested instead in scripting an OLE object within the Mathcad or MathConnex environment, see the section on Scripting Custom OLE Objects) Using OLE Automation, you can send data to Mathcad from another application, use Mathcad to perform calculations or other data manipulations, and send results back to the original application. In Mathcad 5 and 6, this kind of communication was carried out using DDE (dynamic data exchange). With Mathcad 7 and higher, DDE has been superseded by OLE Automation. Mathcad's OLE Automation interface described here can be used with Mathcad 7.02 and higher.

To use OLE Automation technology, you must write a program in Visual Basic 5.0 (or higher) or in an application that can serve as an OLE Automation client, such as Microsoft Excel version 5.0 (or higher). Check with the application's documentation to find out if it can serve as an OLE Automation client. The program defines and retrieves variables in Mathcad Document objects. The variables defined in Mathcad must be named in0, in1, in2, myVariable, etc. and the number of inputs to the Mathcad Document object is virtually unlimited. The variables being retrieved from Mathcad must be called out0, out1, out2, etc. and the number of outputs is limited to ten (i.e. out0-out9 are the only allowable values).


GetComplex Method

The GetComplex method retrieves complex data (real and imaginary parts) from Mathcad variables.

Syntax

longRet = objMC.GetComplex(Name As String, RealPart, ImagPart)

Element | Description
longRet | Return value indicating success or failure.
objMC | A Mathcad document object.
Name | A string that is one of out0, out1, out2, etc.
RealPart | A variant that receives the real part of the Mathcad document variable described by Name.
ImagPart | A variant that receives the imaginary part of the Mathcad document variable described by Name.

Remarks

When using Visual Basic, the RealPart and ImagPart variables should be declared as variants.


SetComplex method

The SetComplex method assigns complex data (real and imaginary parts) to Mathcad variable Name, where Name is one of in0, in1, in2, myVariable, etc.

Syntax

longRet = objMC.SetComplex(Name As String, RealPart, ImagPart)

Element | Description
longRet | Return value indicating success or failure.
objMC | A Mathcad document object.
Name | A string that is one of in0, in1, in2, myVariable, etc.
RealPart | A variant whose contents will be assigned to the real part of the Mathcad document variable described by Name.
ImagPart | A variant whose contents will be assigned to the imaginary part of the Mathcad document variable described by Name.

Remarks

When using Visual Basic, the RealPart and ImagPart variables should be declared as variants.


Recalculate method

The Recalculate method recalculates the Mathcad document.

Syntax

longRet = objMC.Recalculate

Element | Description
longRet | Return value indicating success or failure.
objMC | A Mathcad document object.

Remarks

The Recalculate method should be invoked after passing new values to the Mathcad document via the SetComplex method. This is necessary to ensure that the contents of the worksheet, including outputs, remain consistent with the new inputs.


SaveAs method

The SaveAs method saves the Mathcad document to a file.

Syntax

longRet = objMC.SaveAs(Name)

Element | Description
longRet | Return value indicating success or failure.
objMC | A Mathcad document object.
Name | The complete path name for the file. Supplying a filename only will result in a save to the current working directory.

Remarks

This method is useful for saving the contents of a Mathcad Document object that was not created from a file.


Overview of Examples

The examples that follow illustrate how you can use Mathcad's OLE Automation interface with Excel and Visual Basic 6.0. The specific steps involved differ slightly depending on the application in which you are working, but the main steps are as follows:

  • Provide a Mathcad Document OLE object with which to communicate.

  • Set up the application with the data to send to Mathcad and/or places to put the data retrieved from Mathcad.

  • Write code to specify the data to send to Mathcad and/or the data to retrieve.

Although the examples are simple, they should help you understand the basics of using Mathcad's OLE Automation interface.


Visual Basic Example

This example uses a simple Visual Basic 6.0 program to set the variable in0 in a Mathcad OLE object to a complex number, allow Mathcad to perform a calculation, and put the answer into a TextBox control.

Step 1. Add a Reference to the Mathcad object to the object browser.

  1. Choose References from the Project menu.

  2. In the list of Available References, select Mathcad.

  3. Make sure the check box to the left of Mathcad is checked and click "OK."

  4. To view Mathcad's object model, choose Object Browser from the View menu and select Mathcad in the list of available libraries.

Step 2. Design the form. For example, your form might look like this:

On the left is the Mathcad Document object within an OLE Container control. It contains statements to show the input, perform a single calculation, and display the output. On the right are textboxes to provide input and view output from the Mathcad object. There is also a CommandButton control used to submit the input to Mathcad, recalculate, and extract the output to the output TextBox controls.

Step 3. Write the code.

Private Sub cmdSubmit_Click()
Dim objMC As Object
Dim varInReal As Variant, varInImag As Variant
Dim varOutReal As Variant, varOutImag As Variant

'set a reference to the Mathcad object in the OLE container

Set objMC = OLE1.Object

'pass data to Mathcad worksheet via the SetComplex method

'getting inputs from the contents of the textboxes

'NOTE: normally you would validate inputs here prior to conversion from string values

varInReal = CDbl(txtInReal.Text)
varInImag = CDbl(txtInImag.Text)
Call objMC.SetComplex("in0", varInReal, varInImag)

'recalculate worksheet

Call objMC.Recalculate

'retrieve data from Mathcad using the GetComplex method

Call objMC.GetComplex("out0", varOutReal, varOutImag)

'assign outputs to textboxes

txtOutReal.Text = CStr(varOutReal)
txtOutImag.Text = CStr(varOutImag)
End Sub

Note:

  • See the VB projects in the SAMPLES\VBASIC folder in your Mathcad installation directory for working projects that demonstrate Mathcad's Automation interface.


Excel Example

You can use an application such as Microsoft Excel to access Mathcad's OLE Automation interface using Excel's VBA environment. The following example sets the variable in0 in a Mathcad OLE object to a complex number, allows Mathcad to perform a calculation, and puts the answer back into Excel.

Step 1. Insert an OLE object into an Excel worksheet:

  1. Choose Object from the Insert menu.

  2. Choose Mathcad Document in the New tab or choose an existing Mathcad worksheet from the Create from File tab.

  3. Click "OK."

Step 2. Set up the application so that there is data to pass to Mathcad and/or available cells to store data retrieved from Mathcad.

Step 3. Write a Visual Basic macro module:

  1. Choose Macro/Module from the Insert menu.

  2. Enter appropriate VBA code that refers to data in your worksheet and the variables in Mathcad.

Step 4. Run the macro:

  1. First, double-click on the Mathcad object in the Excel worksheet to activate the object.

  2. Run the macro from the Excel worksheet by choosing Macro/Run from the Tools menu.

For example, the following is an Excel worksheet communicating with Mathcad through a VBA macro. The data stored in cells I7 through J8 are passed into the Mathcad variable in0. Mathcad performs a calculation (in this case, it trivially adds 1 to the values, but you can use Mathcad to perform any calculation you can do in Mathcad). The results stored in the Mathcad variable out0 are passed into the cells I12 through J13.

TheVBA macro looks like this:

Sub UpdateWorksheet()
Dim MathcadObject As Object
Dim outRe, outIm As Variant
Dim inRe, inIm As Variant

' Set a reference to the Mathcad object on the shee

Set MathcadObject = ActiveSheet.OLEObjects(1).Object

' Read in values to be passed from Excel to Mathcad

inRe = ActiveSheet.Range("I7:I8").Value
inIm = ActiveSheet.Range("J7:J8").Value

' Send the values over to Mathcad, assign them to variable in0,

' recalculate, and read the results from out0 back into Excel

Call MathcadObject.SetComplex("in0", inRe, inIm)
Call MathcadObject.Recalculate
Call MathcadObject.GetComplex("out0", outRe, outIm)

' Place the result values into the chosen Excel cells

ActiveSheet.Range("I12:I13").Value = outRe
ActiveSheet.Range("J12:J13").Value = outIm
End Sub

Note that in order to pass real data, you should have cell(s) containing zeros for the imaginary part.

Note:

  • See SAMPLES\EXCEL\TRAJECT.XLS in your Mathcad installation directory for a working example with documented code.


Introduction to the Mathcad Component Wizard

The Mathcad Component Wizard is a Visual C++ Add-in that allows you to create custom components for use with Mathcad. The Wizard guides you through the steps of creating the "skeleton" source code for a Mathcad component, which you must then complete to implement the component. The skeleton shows how inputs and outputs are processed by the component, but you will probably have to customize them to your own particular component.

The pages of the Wizard help you specify:

  1. The component type.

  2. The OLE component for the Buddy interface, if applicable.

  3. The component name and Wizard.

  4. The Wizard class name, if applicable.


Selecting the Component Type

Selecting Component Type

Wizard Component Wizard: Dialog 1

In this dialog, you use the radio buttons to select the Control type. The three types are Native, Combo and Buddy. The Native component type should be used if the control is being designed specifically for Mathcad. The Combo component type is used for controls that are designed specifically for Mathcad and also are used with other applications that use the OLE Automation Interface. The Buddy component type is used to provide integration of an existing ActiveX control or DLL that does not have an OLE Automation Interface.


Selecting the OLE Component for the Buddy Interface

Wizard Component Wizard: Dialog 2 (If Buddy component)

Dialog 2 is only displayed if the component type selected is a Buddy component. A list of OLE components that have the ‘insertable’ registry key are listed. The CLSID and the ProgID are displayed. The CLSID is required to access the IDispach Interface of the component. The ProgID is displayed for reference.


Selecting Component Name and Wizard

Mathcad Component Wizard: Dialog 3

The Component Name edit box is for setting the name of the component. This is the name that is used for the ProgID in the Registry. The Component Label is used in the Insert Component menu item list for Mathcad.

If the component requires additional information before it can be inserted into a Mathcad document, a Wizard can be programmed. Check the "Uses a wizard" check box to enable the Wizard templates. The Number of Wizard Steps indicates how many Wizard step code templates should be generated.


Selecting Wizard Class Name

Mathcad Component Wizard: Dialog 4

If the component uses a Wizard, Dialog 4 is displayed. The top list box displays the names of the classes and files used for the Wizard code. The Wizard Class Name is the base name for the class. The Wizard Implementation File is the base name of the CPP file. The Wizard Header File is the name of the .H include file. This is generated from the Implementation file.