Introduction
The building blocks of the Industrial Application Server are Application Objects. These objects themselves are made out of components called Primitives. Primitives have Attributes and Attributes have Properties. Each Application Object has at least the Common Primitive that is shared amongst all objects. In addition to this Primitive Application Objects can contain several other Primitives that are provided by the Industrial Application Server. On top of the basic set of Primitives one or more Custom Primitives can be added to an Application Objects. The Application Object Toolkit provides the tools to create Custom Primitives and glue them together with other standard Primitives to create a new type of Application Object.
Figure 1: Components of the International Spacestation
The AOT allows a developer to statically define Attributes of a new Custom Primitive in the Object Designer, or to dynamically create Attributes in the PackageServer component of the new Application Object. This post explains how to create Dynamic Attributes to expose other Attributes that are for example only available during configuration to the runtime sub system.
Prerequisites
The sample Application Object discussed in this post has been developed using the following tools:
- Visual Studio.NET 2003
- IAS 3.0 SP1
- Application Object Toolkit 1.0
Problem description
Some Attributes values are only available during the configuration of the object and are not accessible at runtime. The Attributes "MinorVersion" and "CodeBase", which are part of the Common Primitive, are configuration only Attributes. The following sample describes a simple approach to exposing these values to the runtime sub system by creating new Dynamic Attributes that are visble in runtime and copying the values of the configuration Attributes into the new Dynamic attributes
Figure 2: MinorVersion and CodeBase Attributes are ConfigOnly
Solution
Create new AOT project
Open the AOT Object Designer and create a new object called "ExportPackageOnlyAttributes". Then add one static Attribute in the Designer of type integer with the name "PV". Assign it the category "Writeable_USC_Lockable"
Figure 3: Creating a new object with the Object Designer
Now generate the source code, open the Visual Studio solution and build the new Application Object. Import it into the IDE and deploy it to an Application Engine.
Modify the Package Server
From this point on all modifications are made to the "ExportPackageOnlyAttributesPackage.cpp" file of the Package Server Visual Studio project. The code that we are going to add will be executed by the "CExportPackageOnlyAttributesPackage::OnPostCreate" event handler.
Add Attribute
To add a new attribute we need access to two functions that are provided by the Site COM object, which we get by calling the GetSite() function. First we want to make sure that the Attribute hasn't already been added by checking "GetAttributeHandle" passing in the name of our Dynamic Attribute. If it returns a valid handle, then we know that the Attribute has already been added, if not we are going to add the Attribute.
1: // Create two dynamic attributes if they don't exist already
2: // First check whether they exist
3:
4: ATL::CComBSTR MinorVersionExName = L"MinorVersionEx";
5: ATL::CComBSTR MajorVersionExName = L"MajorVersionEx";
6: AttributeHandle MinorVersionExAttributeID;
7: AttributeHandle MajorVersionExAttributeID;
8:
9:
10: IPrimitivePackageSite * P = GetSite();
11:
12: // 1) MINOR VERSION
13: HRESULT r = P->GetAttributeHandle( MinorVersionExName, &MinorVersionExAttributeID);
14:
15: if(!(SUCCEEDED(r)))
16: { 17: LogWarning(L"GetAttributeHandle - HRESULT = %x", r);
18: return;
19: }
20:
21: LogInfo(L"%s has AttributeID = %d" , MinorVersionExName, MinorVersionExAttributeID.shAttributeId);
22:
23: // If Attribute doesn't exist, create one
24: if( MinorVersionExAttributeID.shAttributeId == 0)
25: { 26:
27: AttributeInfo ai;
28: AttributeID ID;
29:
30: ai.Name = MinorVersionExName;
31: ai.Category = MxCategoryWriteable_C_Lockable;
32: ai.Security = MxSecurityFreeAccess;
33: ai.Datatype = MxInteger;
34: ai.LockType = MxLockedInMe;
35:
36: //Add dynamic attribute
37: r = P->AddAttribute(eTopLevelCustomPrimitiveId, &ai, &ID);
38:
39: if(!(SUCCEEDED(r)))
40: { 41: LogWarning(L"AddAttribute - HRESULT = %x", r);
42: return;
43: }
44:
45: LogInfo(L"Added Attribute %s! Its AttributeID = %d" , MinorVersionExName, MinorVersionExAttributeID.shAttributeId);
The category of the two Dynamic Attributes is set "Writeable_C_Locable". This way the Attribute values are constants and cannot be changed in runtime.
Set Value
Once we created the new Dynamic Attributes we can get the values from the "MinorVersion" and "CodeBase" and copy them to the new Dynamic Attributes "MinorVersionEx" and "MajorVersionEx". For the latter one we have to parse the "CodeBase" Attribute value string and get the version number at the end of the string. Here is the source code that does it.
1: // Set value of dynamic attribute equal to PackageOnly MajorVersion attribute
2: CMxValue MxCodeBase = Get(idxCommonCodeBase, eCommonPrimitiveId);
3: long int MajorVersion = 0;
4: ATL::CComBSTR CodeBase = L"";
5:
6: // Getting CodeBase attribute from Common Primitive
7: r = MxCodeBase->GetString(&CodeBase);
8: if(!(SUCCEEDED(r)))
9: { 10: LogWarning(L"GetString - HRESULT = %x", r);
11: return;
12: }
13: LogInfo(L"CodeBase is: %s", CodeBase);
14:
15: // Converting BSTR to STL wstring
16: std::wstring strCodeBase(CodeBase);
17:
18: // Parsing version number from ProgID string contained in CodeBase attribute
19: size_t b = strCodeBase.find_last_of(L".");
20: LogInfo(L"b %d", (int) b);
21: std::wstring strMajorVersion = L"";
22: strMajorVersion = strCodeBase.substr(b + 1);
23:
24: // Converting string to long integer
25: swscanf(strMajorVersion.c_str(), L"%d", &MajorVersion);
26:
27: LogInfo(L"MajorVersion String: %s", strMajorVersion.c_str());
28: LogInfo(L"MajorVersion Integer: %d", MajorVersion);
29:
30: // Converting long integer to MxValue object
31: CMxValue MxMajorVersion(MajorVersion);
32:
33: // Setting MajorVersionEx attribute value
34: Set(ID, MxMajorVersion);
Build and test
Compile the modified project, import the new object and deploy it. The new dynamic attributes should now display the values of the configuration counter parts. Check the object property page in the IDE and the runtime values of object attributes in the ObjectViewer.
Figure 4: Object properties displayed by the IDE
Figure 5: ObjectViewer displays the new Dynamic Attributes
Download
The complete Visual Studio .NET 2003 solution can be downloaded here: CExportPackageOnlyAttributes.zip
Summary
Creating Dynamic Attributes is without any doubt an advanced feature of the Application Object toolkit. On the other hand Dynamic Attributes can increase productivity of an application developer by providing a mechanism to automate the "shaping" of an Application Object.
Subscribe
