Component Editions
Applicability: Cranium, Synapse (core version 0325+)

Microsoft's COM (Component Object Model) is a technology that enables a software program (the COM client) to access and utilize the functions contained within another software program (the COM server). Both Cranium and Synapse can function as COM servers, providing physical property data, estimates, structure editing, unit conversions, and other capabilites to process simulators, Microsoft® Excel®, and internally developed applications.

The video to the right provides a brief overview of the Component Edition.

Component Edition Processing
The Component Edition provides physical property data and estimates to other software applications. We call these "other" applications "interface applications". The diagram below details the five-step interaction process between the user, the interface application, and the component edition of Cranium or Synapse:
  1. A user may need physical property data or estimates while working with Excel or another, possibly user created, interface application.
  1. The interface application prepares a request for these property values and sends it to the Component Edition of Cranium or Synapse.
  2. The Component Edition retrieves knowledge base data and performs calculations.
  3. The Component Edition then sends a response back to the interface application.
  4. The interface application formats this response and displays the retrieved data, estimates, and graphs to the user.
Working with Excel

Interacting with the Component Edition from within Excel begins by adding a reference to the installed software program. The image to the right shows the selected reference to the library of the Component Edition of Cranium.

Once the the reference has been added, you can use library's objects and their functions within any VBA code you write. The objects contained within the Cranium, Component Edition library are prefixed with "MKSCCE". The objects contained with the Synapse, Component Edition are prefixed with "MKSSCE".

For example, the code below is a VBA subroutine that retrieves the boiling points of Acetone - both a data value and an estimated value. The code is based upon a heirarchy of five MKS Library Objects:
application - request - entity - property - datum
Rem - Retrieve boling point values Sub BoilingPointDemo() Rem - Initialize error handling On Error GoTo ExitCode Rem - Variable declarations, objects Dim mksDProp As MKSCCE.Property, mksEProp As MKSCCE.Property Dim mksApp As MKSCCE.Application Dim mksReq As MKSCCE.request Dim mksEnt As MKSCCE.Entity Rem - Create mks application Set mksApp = CreateObject("MKSCCE.Application") mksApp.SetDocPathname (GetDocumentPath) Rem - Create mks request Set mksReq = mksApp.CreateRequest mksReq.SetType ("Get Values") Rem - Add entity to request Set mksEnt = mksReq.AddEntity() mksEnt.SetIdentifier ("Acetone") mksEnt.SetEntityType ("Chemical") Rem - Request boiling point data Set mksDProp = mksEnt.AddProperty() mksDProp.SetName ("Boiling Point") mksDProp.SetStatus ("Active") mksDProp.SetComponent (0) Rem - Request boiling point estimate Set mksEProp = mksEnt.AddProperty() mksEProp.SetName ("Boiling Point") mksEProp.SetStatus ("New Estimate") mksEProp.SetComponent (0) Rem - Process request If (mksApp.ProcessCOM(mksReq)) Then Rem - Display retrieve values MsgBox mksDProp.Datum(0).GetDValue() MsgBox mksEProp.Datum(0).GetDValue() End If ExitCode: Rem - Clear objects Set mksApp = Nothing End Sub
  • Lines 7 through 11 declare the MKS Library Objects that will be used in the subroutine.
  • Lines 13 through 15 create the Component Edition application and assign the pathname for the knowledge base that will be used as the source of data and estimates.
  • Lines 17 through 19 create a request object and assign its type as "Get Values".
  • Lines 21 through 24 create an entity object. This entity's name is assigned to be "Acetone" and its type set to "Chemical".
  • Lines 26 through 30 create our first property object. This property's attributes are assigned to retrieve the active data value of Acetone's boiling point.
  • Lines 32 through 36 create our second property object. This property's attributes are assigned to retrieve an estimated value of Acetone's boiling point.
  • Now with our request prepared, Line 39 calls the Component Edition's ProcessCOM function. If successful, we extract some of the retrieved values in the following code.
Working with Visual C++

Interacting with the Component Edition from within Visual C++ begins by using the "#import" directive to process the application's type library. For example, the line:

#import "MKSCCE.tlb"

instructs Visual C++ to create the associated classes and smart pointers from those listed within the type library.

Once the the type library has been imported, you can use library's objects and their functions within any C++ code you write. The objects contained within the Cranium, Component Edition library are prefixed with "MKSCCE". The objects contained with the Synapse, Component Edition are prefixed with "MKSSCE".
For example, the code below is part of a Visual C++ console application that retrieves the boiling points of Acetone - both a data value and an estimated value. The code is based upon a heirarchy of five MKS Library Objects:
application - request - entity - property - datum
// Initialize com library if( !InitComLibrary() ) return 0; // Variables IMKSApplicationPtr pApp = nullptr; CLSID id; // Create mks application HRESULT hr1 = CLSIDFromProgID(OLESTR("MKSCCE.Application"), &id); HRESULT hr2 = CoCreateInstance(id, NULL, CLSCTX_LOCAL_SERVER, IID_PPV_ARGS(&pApp)); if (hr1 != S_OK || hr2 != S_OK) return 1; pApp->SetDocPathname(path.c_str()); // Create mks request MKSCCE::IMKSRequestPtr pRequest = pApp->CreateRequest(); pRequest->SetType("Get Values"); // Add entity to request MKSCCE::IMKSEntityPtr pChem = pRequest->AddEntity(); pChem->SetEntityType("Chemical"); pChem->SetIdentifier("Acetone"); // Request boiling point data MKSCCE::IMKSPropertyPtr pDProp = pChem->AddProperty(); pDProp->SetName("Boiling Point"); pDProp->SetStatus("Active"); pDProp->SetComponent(0); // Request boiling point estimate MKSCCE::IMKSPropertyPtr pEProp = pChem->AddProperty(); pEProp->SetName("Boiling Point"); pEProp->SetStatus("New Estimate"); pEProp->SetComponent(0); // Process request if( !pApp->ProcessCOM(pRequest) ) { // Show error message _bstr_t error = pApp->GetError(); std::cout << std::string(error, error.length()); // Error return return 2; } // Output some results std::cout << pDProp->Datum(0)->GetDValue() << std::endl; std::cout << pEProp->Datum(0)->GetDValue() << std::endl; // Successful return 0;
  • Lines 1 and 2 initialize the COM library functionality.
  • Lines 4 through 6 declare variables used in this function.
  • Lines 8 and 13 create the Component Edition application and assign the pathname for the knowledge base that will be used as the source of data and estimates.
  • Lines 15 through 17 create a request object and assign its type as "Get Values".
  • Lines 19 through 22 create an entity object. This entity's name is assigned to be "Acetone" and its type set to "Chemical".
  • Lines 24 through 28 create a property object to retrieve the active data value of Acetone's boiling point.
  • Lines 30 through 34 create our second property object to retrieve an estimated value of Acetone's boiling point.
  • Line 37 calls the Component Edition's "ProcessCOM" function to process the request. If successful, we extract some of the retrieved values in the following code.
Detailed Documentation

Detailed documentation on each of the MKS Library Objects and their associated functions is available here.

Related Documentation
Topic Description
Getting Started using Cranium provides a quick tour of Cranium's capabilities including physical property estimation and a discussion of structure editing.
Getting Started using Synapse provides a quick tour of Synapse's capabilities including examples of chemical product design.