Getting Started with the StressCheck COM API

Microsoft Excel VBA Programming with COM

I. Introduction
The following getting started guide is intended to demonstrate the
basics of using Microsoft Excel VBA (Visual Basic for Applications)
object-oriented programming concepts in conjunction with the
StressCheck COM API (Application Programming Interface). This is not
intended to be a getting started guide for VBA, but on the StressCheck
COM API. The goal is for users to gain proficiency in using Excel to
solve and post-process StressCheck problems in the automation mode.
A framework for developing automation scripts will be outlined, and a
comprehensive example provided to practice and refine key concepts.
II. What is COM?1
Microsoft COM (Component Object Model) technology in the Microsoft
Windows-family of Operating Systems enables software components to
communicate. COM is used by developers to create re-usable software
components, link components together to build applications, and take
advantage of Windows services. COM is used in applications such as
the Microsoft Office Family of products. For example COM OLE
technology allows Word documents to dynamically link to data in Excel
spreadsheets and COM Automation allows users to build scripts in their
applications to perform repetitive tasks or control one application from
another.
In this guide, it will be shown how Excel can be used to communicate
with StressCheck objects, through VBA and COM API technology, in
order to accomplish a wide variety of automation tasks. First, we must
learn how to enable Microsoft Excel to communicate with StressCheck.
III. Linking Microsoft Excel with the StressCheck Object Library
It is very simple enable Microsoft Excel to communicate with
StressCheck. All that is necessary are proper installations of each
application, and specification of the StressCheck object library to be
referenced by Excel. This library contains all StressCheck objects,
along with the associated methods and properties, needed to develop,
solve, and post-process StressCheck models on the fly. The concepts
contained in the previous sentence will be clarified shortly; that is, if
1

http://www.microsoft.com/com/default.mspx

2013 ESRD, Inc. All Rights Reserved. StressCheck is a

registered trademark of ESRD, Inc.

the user is not familiar with object-oriented programming concepts.

To specify the StressCheck object library to be referenced by Excel
VBA, simply go to the Visual Basic Editor (navigate to the Visual Basic
editor by clicking the Developer tab then Visual Basic, or by simply
using Alt+F11). Once the Visual Basic Editor interface is shown, go to
Tools->References to enable the library. Check the library named
StressCheck Application 2.0 Object Library. Once this library is
enabled, you are able to link Excel and StressCheck using the
StressCheck COM API. (Note: you must save your Excel file in order
to keep the reference to the StressCheck object library.)

Figure 1. Activating the StressCheck Object Library in Excel VBA

Let us now examine a few introductory object-oriented programming

concepts, namely how objects are created and managed in VBA.
IV. Introduction to Objects in Visual Basic2
An object is a structure containing data and methods that manipulate
the data. Almost everything you do in Visual Basic is associated with
objects. For example, a StressCheck or Excel application is an object,
as are the components which make up the application hierarchy. Each
2

http://msdn2.microsoft.com/en-us/library/zztsbwsx(VS.80).aspx

2013 ESRD, Inc. All Rights Reserved. StressCheck is a

registered trademark of ESRD, Inc.

object has properties, methods and events which give the object
distinction. The properties, methods, and events of an object are
enabled by the class from which the object is defined. Generally
speaking, a class is an abstract representation of something, whereas
an object is a usable example of the thing the class represents.
Objects are therefore instances of a given class. A class may be
imagined as a blueprint, capable of providing instructions as to how an
object is to be represented. For example, imagine a floor plan for a
house. The floor plan may be represented by the number of rooms,
dimensions for each room, etc. These are properties of the house.
Additionally, instructions may be provided as to how modifications may
be made to a floor plan. These modifications are implemented by
various methods. The floor plan, though, is only a set of instructions,
or an abstraction, for how to produce a house (class). A house is
therefore a habitable, or usable, instance of a given floor plan (object).
From the above example, the idea of StressCheck object hierarchy can
be extrapolated and explored.
V. StressCheck Application Object Hierarchy
In the way that a house can be represented by the number of rooms
and the dimensions of each room, the doors, windows and other
attributes (properties) for each individual room can also be specified.
Additionally, each of the doors in a given room may be assigned a
different color. We may continue extending this hierarchic approach
until all the attributes of the house, meaning all objects and their
properties, have been assigned. These attributes may be assigned by
using the default configurations provided in the floor plan or by
explicitly stating them as the house is built. Since StressCheck is
hierarchic in the manner described above, a user has access to any
StressCheck model attribute through the object hierarchy provided by
the StressCheck COM API.
At the top of the StressCheck object hierarchy is the Application.
Below the Application is the Document (dataset). The StressCheck
Document (dataset) is therefore a property of the StressCheck
Application, but it is also a hierarchic object with its own methods,
properties, etc. The StressCheck Document methods include the
ability to solve a pre-defined solution saved within a StressCheck input
file, or to extract engineering information from a solution using a predefined extraction. Below the Document (dataset) are Model,
Extractions, Solutions, etc. Again, these are properties of the
StressCheck Document but are also hierarchic objects. For instance,
the Model object has as its properties geometric objects, mesh objects,
2013 ESRD, Inc. All Rights Reserved. StressCheck is a
registered trademark of ESRD, Inc.

boundary condition assignments, and so on. If we want to create a

new, or modify the properties of an existing, instance of a mesh
object, such as a node or an element, methods exist which will
perform such actions. In this manner, we may continue to work our
way through the StressCheck COM API hierarchy until all relevant
information has been communicated. The StressCheck COM API
hierarchy may be examined in detail through the COM API Help
included in the StressCheck installation. Let us now establish the basic
concepts of the StressCheck automation framework as it pertains to
the hierarchic nature of StressCheck.
VI. Basic Concepts of the StressCheck Automation Framework
The StressCheck automation framework outlined in this getting started
guide includes the following basic, but fundamental, concepts:
1)
2)
3)
4)
5)
6)
7)
8)

Starting a new StressCheck application

Opening a new StressCheck dataset
Loading a StressCheck input file to play back a model
Modifying existing parameters to change model definition
Solving a linear analysis using p-extensions
Extracting engineering quantities (stress, strain) to a table
Transferring data from StressCheck tables to Excel spreadsheet
Ending the StressCheck session

These concepts are intended to show how the loading, solving, and
post-processing of pre-defined StressCheck models is accomplished via
Excel VBA scripting combined with COM automation. To practice these
concepts, an example will be given at the end of this guide which will
use the framework provided to load, solve, and post-process a
StressCheck Handbook model.
In the following sections, each of the concepts outlined in the
StressCheck automation framework will be examined in detail. Sample
VBA code, with explanations of syntax and structure, will be provided.
VII. Example 1: Plate with Central Hole under Uniform Tension
The goal of the following example is to read an existing StressCheck
Handbook model (peter02.sci in 2-D Basic Handbook folder), modify a
geometric parameter, solve a linear solution and extract the maximum
first principal stress with the error in this value.

2013 ESRD, Inc. All Rights Reserved. StressCheck is a

registered trademark of ESRD, Inc.

Figure 2. Example 1: Plate with Central Hole Under Uniform Traction

Step 1: Create a New Excel Worksheet and Activate the

StressCheck Object Library from the References Menu
Create a new Excel worksheet by simply double-clicking on the Excel
icon or selecting it from the Programs list. Once the Excel worksheet
is initialized, navigate to the Visual Basic editor by clicking the
Developer tab then Visual Basic, or by simply using Alt+F11.
Once the editor is displayed, use Tools->References to display a list
of libraries. Scroll the list until the StressCheck Application 2.0 Object
Library is found. Activate the reference to the object library by
checking the box and clicking OK. We will also take advantage of the
file I/O (FileSystemObject) capabilities of the Microsoft Scripting
Runtime library, so activate this reference as well.

2013 ESRD, Inc. All Rights Reserved. StressCheck is a

registered trademark of ESRD, Inc.

Figure 3. Activating the StressCheck Object Library in Excel VBA

Step 2: Create a Command Button on an Excel Spreadsheet

A command button, placed on the spreadsheet, will be used to execute
the VBA script. To create a command button, switch back to the
spreadsheet view, click Insert on the Developer tab (

) and click

on the Command Button icon in ActiveX controls ( ). Draw

rectangle and release the mouse button to create the command
button. Note: to access these features, the Developer tab must be
activated. Right click on the command button and select Properties.
Change the name of the command to cmd_Solve and the caption to
Solve! Let us save our Excel document at this time to your My
Documents folder as MyFirstSCCom.

2013 ESRD, Inc. All Rights Reserved. StressCheck is a

registered trademark of ESRD, Inc.

Figure 4. Creating and Editing a Command Button in Excel

After the command button has been created, double-click on it to

enter the VBA code. A subroutine is automatically created with the
name of cmd_Solve. This is where we will place our code for
StressCheck automation tasks.

2013 ESRD, Inc. All Rights Reserved. StressCheck is a

registered trademark of ESRD, Inc.

Figure 5. Visual Basic for Applications (VBA) Code Interface

VBA Code for StressCheck Automation Tasks

The following code for Example 1 will be written such that a Handbook
model of a plate with a center hole under uniform tension (peter02.sci)
will be read into a StressCheck session, solved, and post-processed.
Commonly used keywords when using objects, and properties of
objects, include Dim and Set. Dim declares and allocates storage
space for one or more variables or objects. Set is a procedure used to
assign a value to an object or an object property.
Step 3: Starting a new StressCheck application
To enable initialization a new StressCheck application within the
Microsoft Excel VBA framework, simply click in the empty space
between the subroutine and input the following lines:
Dim SCApp As StressCheck.Application
Set SCApp = New StressCheck.Application
These lines will enable an object called SCApp to exist as a new
StressCheck application. We shall see momentarily that a new session
(StressCheck.exe) will exist in your Task Manager once these lines
are executed.
2013 ESRD, Inc. All Rights Reserved. StressCheck is a
registered trademark of ESRD, Inc.

Step 4: Opening a new StressCheck Document (Dataset)

Next, we will provide the code necessary to open a new StressCheck
Document (i.e. dataset). But first, we must specify the path to the
StressCheck dataset that will reside in a temp directory in My
Documents.
In VBA, there exists a function called ThisWorkbook.Path which
determines the current location of the Excel workbook and returns the
path to this file as a String. This string can be combined with the
name of our temp folder (Test) to specify the path to the
StressCheck dataset:
Dim fndummy As String
fndummy = ThisWorkbook.Path & "\Test"
Now, we can provide code that will allow us to delete any existing
temp directory with the name Test in My Documents, and create a
new one. This is accomplished through the FileSystemObject class:
Dim FSO As FileSystemObject
Set FSO = New FileSystemObject
If FSO.FolderExists(fndummy) Then
FSO.DeleteFolder fndummy
End If
FSO.CreateFolder fndummy
A folder called Test in My Documents should now exist. Then, the
Open method of StressCheck.Document is called to open a new
dataset with the name dummy in our temp directory:
SCApp.Document.Open fndummy & "\dummy"
This statement may be used because the StressCheck Document is a
property of the StressCheck Application (SCApp). We can now issue a
Set statement to assign the new StressCheck dataset under SCApp to
a separate StressCheck Document object called SCDoc:
Dim SCDoc As StressCheck.Document
Set SCDoc = SCApp.Document
It must be mentioned that the SCDoc object is now equivalent to the
object returned by SCApp.Document. The Set statement is thus used
in this manner to compact object hierarchies.
2013 ESRD, Inc. All Rights Reserved. StressCheck is a
registered trademark of ESRD, Inc.

Step 5: Reading an existing StressCheck Handbook Model

In order to read an existing StressCheck Handbook Model, we must
specify the location and name of the input file to be read. The input
file for Example1 is called peter02.sci and is located in the
ESRD/StressCheck9/Handbook/Basic/2D-Basic directory. We will copy
this input file into the same location as our Excel workbook (i.e. My
Documents). Since the input file contains all of the Model
information, Reading the input file is a method of the StressCheck
Model object:
Dim SCModel As StressCheck.Model
Set SCModel = SCDoc.Model
SCModel.Read ThisWorkbook.Path & "\peter02.sci"
Note that the StressCheck Model object is a property of the
StressCheck Document object. Once the input file is read,
StressCheck Model properties of SCModel will be set depending on the
information given by the input file. If we choose to show the live
StressCheck session as we work with the model, then we may input
the following line:
SCApp.Show True
Otherwise, StressCheck will be hidden from our view.
Step 6: Modifying an Existing Model Parameter
In the StressCheck model described by the peter02.sci input file, there
are several pre-existing parameters which we may modify. These
include geometric parameters (L = Plate Length = 15 inches, W =
Plate Width = 5 inches, a = Hole Diameter = 1 inch, and h = Plate
Thickness = 1 inch) and a load parameter (S = Remote Axial Stress =
1 ksi). We will modify the hole diameter from the default value of 1
inch to 0.5 inches and update the model:
SCDoc.ParameterAssign a, 0.5, True
Note that ParameterAssign is a method of the StressCheck
Document. The syntax requires the name of the parameter as it
appears in the input file, the new value of the parameter, and the
update condition (True or False). An arbitrary number of parameters
may be changed and updated.
2013 ESRD, Inc. All Rights Reserved. StressCheck is a
registered trademark of ESRD, Inc.

10

For example, if we wanted to update each parameter with a value read

from the Excel spreadsheet:
Dim a As Double, h As Double, L
As Double
a = CDbl(Sheet1.Cells(17, 4))
h = CDbl(Sheet1.Cells(18, 4))
L = CDbl(Sheet1.Cells(19, 4))
S = CDbl(Sheet1.Cells(20, 4))
W = CDbl(Sheet1.Cells(21, 4))
With SCDoc
.ParameterAssign "a", a,
.ParameterAssign "h", h,
.ParameterAssign "L", L,
.ParameterAssign "S", S,
.ParameterAssign "W", W,
End With

As Double, S As Double, W

True
True
True
True
True

However, for simplicity, we will focus at this time on changing the

value of the parameter a only to a fixed value of 0.5 inches.
Step 7: Solving a Linear Solution Using P-Extensions
Once we have updated the model parameter for the hole diameter, we
are ready to solve a linear solution for the model using p-extensions.
Because this is a Handbook model with saved solution and extraction
settings, let us use the parameters (linear solution, p-extension from 1
to 8) stored in the 1-Linear solution setting. To solve the model
using this solution setting, we simply call the method xSolve and give
the name of the desired solution setting (1-Linear):
SCDoc.xSolve ("1-Linear")
Note that xSolve is a method of the StressCheck Document object.
Once the solution is complete, we may perform extractions on the
solutions.
Step 8: Extracting Maximum S1 to Excel Worksheet
When an extraction is performed in StressCheck, the data of interest
(S1 in our example here), as well as other associated information (Run
#, DOF, Maximum Limit, etc.), are placed in a StressCheck Datatable
for access. This datatable is in row and column format. The
StressCheck Datatable for Example1 will appear as the following:
2013 ESRD, Inc. All Rights Reserved. StressCheck is a
registered trademark of ESRD, Inc.

11

Figure 6. Example 1 StressCheck Datatable for Extraction of Maximum S1

There are eight (8) rows, one for each polynomial level, and seven (7)
columns, each describing the attributes of the extraction, in the above
StressCheck Datatable. To perform the extraction shown above, we
will simply call the xExtractData method. This is used in the same
manner as the xSolve method, in that we supply the name of the
saved extraction setting (2-Min/Max/Avg). However, because the
xExtractData method returns a StressCheck Datatable object, we must
define a StressCheck Datatable object for assignment (SCDT):
Dim SCDT As StressCheck.DataTable
Set SCDT = SCDoc.xExtractData("2-Min/Max/Avg")
Once the StressCheck Datatable object SCDT is set to the datatable
output by the xExtractData method from the 2-Min/Max/Avg extraction
setting, we may interrogate this datatable for relevant engineering
information. The relevant information for Example1 is the maximum
first principal stress (S1max) and the estimated maximum for this
quantity. From these two values, we can determine the estimated

2013 ESRD, Inc. All Rights Reserved. StressCheck is a

registered trademark of ESRD, Inc.

12

relative error in S1max. Since we are interested in the p=8 value for
S1max, we can directly interrogate the Data property for this value:
Dim S1max As Double, S1maxEstimated As Double, S1maxError
As Double
S1max = SCDT.Data (7, 2)
S1maxEstimated = SCDT.Data (7, 3)
S1maxError = (S1maxEstimated-S1max)/S1maxEstimated*100
The Data property of the SCDT object contains an array of all
extraction information relevant to the given datatable type. As
mentioned, this array is in row and column format with a beginning
index of zero (0). This means that at p=8, we will interrogate row
number seven (7), and for the Max. S1 and Maximum Limit we use
column numbers two and three (2 and 3), respectively. The
S1maxError variable will give us the estimated error percentage for
S1max. We are now ready to place the information from these
variables into our Excel spreadsheet. Navigate back to the Excel
spreadsheet by click on the
icon in the upper left-hand corner of the
Visual Basic interface. Next, click on cell A10 and type Maximum S1,
then click on cell B10 and type Estimated Error. Now, click on the
icon on the Developers tab to bring back the Visual Basic
interface. Finally, input the following code:
Sheet1.Cells (11, 1) = S1max
Sheet1.Cells (11, 2) = S1maxError
This will place the values of S1max and S1maxError in the cells A11
and B11, respectively.
Step 9: Closing the StressCheck Document and Application
After we have completed our tasks, we must close and release the
StressCheck Document and Application objects before exiting the
Visual Basic session. To release the objects, we will simply set them
to Nothing such that the object variables no longer refer to any object
instance:
SCDoc.Close
Set SCDoc = Nothing
SCApp.Close
Set SCApp = Nothing
2013 ESRD, Inc. All Rights Reserved. StressCheck is a
registered trademark of ESRD, Inc.

13

1. Important Note Regarding StressCheck Object Declarations in VBA

If a StressCheck object is declared within a VBA subroutine, such as
the cmd_Solve_Click() subroutine, it is not always necessary to set
this object to Nothing. It is necessary, however, to set the object to
Nothing if the object is declared globally (outside any subroutine).
Otherwise, the StressCheck process will remain in the background
after the application has closed due to unreleased references.
Step 10: Execution of the Visual Basic Code
We have now completed the code for Example 1, and may now
execute the code to perform the above tasks. To do so, simply click
on the
icon to view the Excel spreadsheet. We may now activate
the command button by clicking on the Design Mode
icon in the
Developers tab. Finally, click on the command button Solve! to
execute. The output to the Excel spreadsheet should appear as
follows:

Figure 7. Excel Spreadsheet after Execution of Visual Basic Code

We can verify from the StressCheck Datatable given in Figure 6 that

the values have been properly extracted.
In Example 1, we learned how to work with the StressCheck COM API
in conjunction with Excel VBA programming to perform simple
automation tasks.

2013 ESRD, Inc. All Rights Reserved. StressCheck is a

registered trademark of ESRD, Inc.

14