The Down Low on Mathcad DLLs

DLL Mathcad

**Guest Post by John Sheehan**

More and more engineers are coming to the table with programming skills. Bravo!! But many draw the line at DLLs. They are a mystery, dark magic. DLLs are just another mechanism to distribute your code.

DLL stands for Dynamically Linked Library. This is different from statically linked libraries. The concept of DLLs has been around for many years. VMS, UNIX, Linux have all had their variation on this common, dynamically shared library theme; VMS had *.OLB files, UNIX and Linux have *.so files.

The idea is to be able to provide an application developer with routines he/she can leverage in the application without having to distribute the source code to said developer. A DLL is a binary file, much like an *.exe, however it cannot run standalone like an *.exe. It needs to be linked into the main application and then called by the application. Updates to the application can be made by simply installing newer versions of the DLLs.

Mathcad provides a mechanism for end users to call DLLs within the Mathcad interface. A DLL can be one function or as in the case of the Prode.DLL (Prode Physical Properties) there are 225 functions which the user can call. In Mathcad Prime 3.0 we call user DLLs “Custom Functions.”

Mathcad provides a number of examples showing developers the MCADUSER.LIB functions necessary to turn C code into a Mathcad “Custom Function.” These examples are terrific because they are simple and complete. They demonstrate programmatically 1.) How to get data into your Custom Functions function. 2.) How to return data from your Custom Functions function to the Mathcad worksheet and also, 3.) How to register your Custom Functions, so Mathcad sees it.

Those three areas of interest represent what is known in programming circles as the “wrapper.” What does Mathcad require to “wrap” my code into a usable Mathcad Custom Functions?

Installed with Mathcad Prime 3.0 under installdir\Custom functions are a number of examples.

ComplexSum .c contains all 3 areas of interest in one file. It not only defines what is passed in to and what is passed out of the Customer Function, it also defines its DLL entry point.

Mutliply.c is of the same ilk. It contains all 3 areas of interest in 3 code segment.

The USERPACK example steps up the interest level. This example separates the computational code from the DLL code. REALSUM.c and TRNSPOSE.c house the computational code along with memory allocation calls for data returning to Mathcad’s worksheet. USERPACK.c creates the DLL entry point and registers both REALSUM and TRNSPOSE functions. This is closer to real world. No need to repeat the DLL entry point code for every module. Think about the Prode example referenced earlier. Copy all that code 225 times? Imagine if you made a mistake, 225 files to edit!

I’d like to make this even simpler and much more real world. The Mathcad online help instructions have you compile and link by command line, a subset of the documentation is shown below. Now while this is accurate it is not how developers really work today.

Command

Description

cl —c —I..\ —DWIN32 CMPLXSUM.C Generates the cmplxsum.obj file in the current folder.
link -out:..\cmplxsum.dll -dll -entry:”DllEntryPoint” cmplxsum.obj ..\MCADUSER.LIB Generates the cmplxsum.dll file in the Custom Functions folder.

For most developers on the Windows platform we are using Microsoft Visual Studio and leverage their awesome website for any help, examples, tutorial etc. A combination of Microsoft tools and Mathcad examples are the best recipe for getting you building Mathcad Custom Functions in minutes.

Specifically, I am recommending you use Microsoft Visual Studio to create MVS Solution which builds a DLL. With this in place you can easily edit, compile, and run your DLL in a professional development environment. When you complete building your Custom Function, simply copy it to the Custom Functions directory, start Mathcad Prime 3.0 and call your function.

In addition to this blog, I have included the USERPACK example as a Visual Studio Solution. Along with REALSUM and TRNSPOSE I have added a new function: “gmtime,” which when called with you time zone, from GMT (east coast = -4) it will return the date and time for your TZ. Below is the code, it is a simple modification to REALSUM or TRNSPOSE. Then I simply add “gmtime” twice to USERPACK.C.  This code is the “wrapper” for my date function and USERPACK registers it in the USERPACK.dll, which I then copy to installdir\Custom Functions.

#include “StdAfx.h”

#include “mcadincl.h”

#include <time.h>

LRESULT gmdateFunction(LPCOMPLEXARRAY    datevec, LPCCOMPLEXSCALAR    TZ   );

FUNCTIONINFO    gmdate =

{

“gmdate”,                        // Name by which Mathcad will recognize the function

   “TZ”,                              // Date will be called as Date(TZ)

“returns vector of time date info”,      // description of Date(TZ)

(LPCFUNCTION)gmdateFunction,       // pointer to the executable code

COMPLEX_ARRAY,                     // the return type is vector

1,                                  // the function takes on 1 arguments

{COMPLEX_SCALAR}   // one argument is a complex scalar

};

LRESULT gmdateFunction(LPCOMPLEXARRAY datevec, LPCCOMPLEXSCALAR TZ   )

{

time_t rawtime;

struct tm * ptm;

MathcadArrayAllocate ( datevec,  // allocate space for Y

                    5,    //  with cols

                    1,    //  and X rows

                    1,   //  allocate the real part if X has a real part

                    0    //  allocate the imaginary part if X has

                                //  an imaginary part

);

time (&rawtime);

ptm = gmtime(&rawtime);

datevec->hReal[0][0] = (int)(ptm->tm_hour+TZ->real)%24;

datevec->hReal[0][1] = ptm->tm_min;

datevec->hReal[0][2] = ptm->tm_mday;

datevec->hReal[0][3] = ptm->tm_mon;

datevec->hReal[0][4] = (1900+ptm->tm_year);

return 0;               // return 0 to indicate there was no error  

}

To create your own Microsoft Visual Studio DLL solution for Mathcad

Of course you can modify the included example, but if you want to start from scratch follow these instructions.

========================================================================

Using Visual Studio 2010 to build Custom Functions in Mathcad Prime 3.0

User EFI Dev Studio Project

========================================================================

  1. In Dev Studio 2010 build a Windows Console app and on the property page select DLL as project type

2.  Set up path for external libraries and headers

The path settings will need to be in project property sheets per project.

Go to “Project” and select “Properties”, find “Configuration Properties”,

and then “VC++ Directories”.

2.1 If you are building on 64-bit Windows, find the “Platform” dropdown

and select “x64″.

2.2 Add the header path to the “Include Directories” setting.

C:\Program Files\PTC\Mathcad Prime 3.0\Custom Functions

2.3 Add the library path to the “Library Directories” setting.

C:\Program Files\PTC\Mathcad Prime 3.0\Custom Functions

2.4 Select Linker->Input and beginning with the

“Additional Dependencies” line, enter the library names.

Enter: mcaduser.lib

3. Copy target DLL to C:\Program Files\PTC\Mathcad Prime 3.0\Custom Functions

This entry was posted in Mathcad A to Z, The Inside Scoop, Tips & Tricks and tagged , , , , , , , , , . Bookmark the permalink.

6 Responses to The Down Low on Mathcad DLLs

  1. Josh says:

    Thanks for the details about this feature. I watched the product intro video on the Mathcad webpage, and it piqued my curiosity, but when I went to the Features and Functions page (http://www.ptc.com/product/mathcad/features-and-functions/) the link that’s supposed to be for the Custom Functions details instead points to the Advanced Numerics page. Someone at PTC might want to fix that.

  2. Thibault says:

    Hello,

    Are these programming capabilities available in Prime 2.0 ?

    I m looking for a way to make a query in an external database.

    Should I make a DLL for that or is there any std feature for that purpose ?

    Thibault

    • Aaron Shaw says:

      Hi Thibault,

      Thank you for your inquiry. These programming capabilities are only available in PTC Mathcad Prime 3.0. John Sheehan is currently working on ReadODBC, WriteODBC, look for a follow-up blog post addressing this issue in the next few weeks.

      • Thibault says:

        Thanks a lot.
        Good news.
        I ‘m looking forward to get it !

  3. Thibault says:

    Hello Aaron,
    Could you give an update on the availibility of the “ReadODBC, WriteODBC” features ?
    I really need this for an ongoing project.
    Thibault

    • Aaron Shaw says:

      Hi Thibault,

      John indicated he will have a post up on Monday, please check back then.

      Thank you,
      Aaron

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s