GR Access 1.0
Last
revision: 10/24/03
This
document contains important information about WonderwareÒ GRAccess Toolkit 1.0. Please carefully review this
document for known issues in this unsupported version.
Known Issues – GRAccess Toolkit
The
GRAccess Toolkit is designed to allow programmatic access to the Industrial
Application Server configuration environment.
The functionality is crafted to mirror the functionality in the Wonderware
Integrated Development Environment (IDE). In addition to IDE functionality this Application
Programming Interface (API) affords the client code the ability to execute
Galaxy Repository Backup and Restore functionality found in the Galaxy Database
Manager of the System Management Console (SMC). This unsupported release is not complete, subsequently special
care must be taken when coding against this Application Programming Interface
(API). The following sections will
attempt to highlight important design patterns of GRAccess and outline the
major issues. Review the Known Issues
section of this document for detailed issues in this unsupported version.
GRAccess: a hierarchical object model.
The GRAccess API is hierarchical in design. At the root of the
object model is the GRAccessApp class which represents the Galaxy
Repository. This interface contains the
functionality to add, delete, and gain access to individual galaxies. At the next level of the object model is the
galaxy interface. Client code at this level can get version information, backup
and restore the GR database, and also gain access to the associated ArchestrA
objects contained within the galaxy. Client code MUST always login using
the IGalaxy.Login(“”,””) method before executing any methods on the IGalaxy
interface. This must be done regardless
of the security mode the galaxy is in. One level down on the GRAccess object
model are the object interfaces. There are three interfaces at this level: the
IgObject, ITemplate, and IInstance. The IgObject interface can be used to work
with either templates or instances of a galaxy application, and possesses
functionality common to both types of ArchestrA objects. At the lowest level of
the object model is the IAttribute interface. As indicated by its name this
interface provides access to the attributes in a galaxy via the associated
objects. The following client code examples walk through the various levels of
the GRAccess API. The root of the API is GRAccessApp where all client
applications start with code typical of the following:
Note: In order for
the following code samples to function properly do the following:
1.
In the
Solution Explorer of Visual Studio .NET right click references and select “Add Reference…”.
2.
Click on
the “COM” tab and select aaGRAccessApp 1.0 Type Library from the list. Click
the “Select” button and then “OK”.
3.
At the top
of the code add “Imports
aaGRAccessApp” for VB.NET or “using
aaGRAccessApp;” for C#.
VB.NET
Dim GRAccess As GRAccessApp
GRAccess = New GRAccessAppClass
Or
in C#
GRAccessApp GRAccess;
GRAccess = new GRAccessAppClass();
Note: It is possible to work with an instance of GRAccess rather than GRAccessApp but certain issues have to be dealt with. These issues are covered in the API help document.
The functionality at this GRAccessApp level
is similar to the IDE “Connect to Galaxy” dialog. You can connect to a galaxy
application in the following manner:
VB.NET
Dim Galaxies As IGalaxies = GRAccess.QueryGalaxies("")
Dim Galaxy As IGalaxy = GRAccess.QueryGalaxies.Item("App1")
Or
in C#
IGalaxies Galaxies =
GRAccess.QueryGalaxies("");
IGalaxy Galaxy =
Galaxies["App1"];
Where “App1” is the
name of the galaxy application the client code executes against. Once we have
an IGalaxy instance the client code MUST
login.
Galaxy.Login("","") or
Galaxy.Login("","");
Note: The
GetLocaleSettings, GetSecuritySettings, GetTimeMasterSettings method on the
Galaxy have an issue outlined below in the known
issues section under L00019535.
After the client code has logged into the
IGalaxy instance it can query for objects by name in the manner below and get a
.NET instance of IgObject that represents an instance in the galaxy with the
tagname “UserDefined_001” (be sure to have an instance named “$UserDefined_001”
in the “App1” galaxy when trying this sample).
VB.NET
Dim TagNames() As String =
{"UserDefined_001"}
Dim aaObject As IgObject = _
Galaxy.QueryObjectsByName(EgObjectIsTemplateOrInstance.gObjectIsInstance,
_
TagNames).Item(TagNames(0))
Or
in C#
String[] TagNames = new String[]{"UserDefined_001"};
Array TagnamName = TagNames;
IgObject aaObject =
Galaxy.QueryObjectsByName(EgObjectIsTemplateOrInstance.gObjectIsInstance,
ref TagnamName)[TagNames[0]];
This gives the client code an IgObject .NET
instance named aaObject. The following code sets the value of the ShortDesc
attribute to "My New ShortDesc":
VB.NET
‘Always check
out the IgObject instance before calling the
‘ConfigurableAttributes property. If the ConfigurableAttributes
‘is called before the CheckOut method the IgObject instance
‘will be opened in a read only mode.
aaObject.CheckOut()
Dim NewAttributeValue As String = "My
New ShortDesc"
Dim aaAttribute As IAttribute = _
aObject.ConfigurableAttributes.Item("ShortDesc")
‘MxValue can be
thought of as the ArchestrA variant data type. This type is used
‘by both the configuration as well as the runtime.
Dim MxVal As New MxValueClass
‘The following if else statement is
needed because MxValue is
‘designed to coerce most data types in the PutString method. One
‘exception is MxInternationalizedString. This MxDataType can only be
‘set by a PutInternationalString call of an MxValue instance.
If aaAttribute.DataType = MxDataType.MxInternationalizedString
Then
MxVal.PutInternationalString(1033, NewAttributeValue)
Else
MxVal.PutString(NewAttributeValue)
End If
aaAttribute.SetValue(MxVal)
aaObject.Save()
aaObject.CheckIn("")
Or
in C#
/* Always check
out the IgObject instance before calling the ConfigurableAttributes property.
If the ConfigurableAttributes is called before the CheckOut method the IgObject
instance will be opened in a read only mode.*/
aaObject.CheckOut();
string NewAttributeValue =
"My New ShortDesc";
IAttribute aaAttribute =
aaObject.ConfigurableAttributes["ShortDesc"];
/* MxValue can
be thought of as the ArchestrA variant data type. This type is used by both the
configuration as well as the runtime.*/
MxValue MxVal = new MxValueClass();
/* The following
if else statement is needed because MxValue is designed to coerce most data
types in the PutString method. One exception is MxInternationalizedString. This
MxDataType can only be set by a PutInternationalString call of an MxValue
instance.*/
if(aaAttribute.DataType ==
MxDataType.MxInternationalizedString)
MxVal.PutInternationalString(1033, NewAttributeValue);
else
MxVal.PutString(NewAttributeValue);
aaAttribute.SetValue(MxVal);
aaObject.Save();
aaObject.CheckIn("");
Notice at every level below the root of the
object model there is an associated collection object. The important ones are
as follows:
Discrete Entity Interface Collection Interface
IGalaxy IGalaxies
IgObject IGObjects
ITemplate IGObjects
IInstance IGObjects
IAttribute IAttributes
As
indicated by Known Issue L00019765, the CommandResult on many of the
GRAccess interfaces do not get initialized properly in this unsupported
release. The workaround for this is to use the following VB .NET code when
attempting to access a CommandResult property:
If Not
(aaGRAccessInterface.CommandResult Is Nothing) Then
'where
aaGRAccessInterface can be any interface with a CommandResult property
'Ok to access the CommandResult here
Debug.WriteLine(aaGRAccessInterface.CommandResult.Successful)
End If
The
If statement above tests the CommandResult property to see if it is
initialized. Any code within the If block can assume a properly initialized
CommandResult from the associated Interface.
|
L00019402 |
The QueryObjects method on the IGalaxy interface does
not return the proper instances when
EDeploymentStatus.deployedWithPendingChanges and
EDeploymentStatus.notDeployed are specified in the value parameter. |
|
L00019405 |
When calling the RtSethandler property on the
IAttribute interface an exception is thrown. |
|
L00019407 |
The properties ExecutionOrder ,
ExecutionRelatedObject, SecurityGroup, ShortDescription do not belong on the
IAttributes interface. |
|
L00019409 |
ICommandResult would be more lean and user
friendly with only two properties. |
|
L00019413 |
The CommandResult property of a .NET object of
type IConditions returns nothing after a method is called. |
|
L00019428 |
The Join method on a .NET object of type IConditions
does not function. |
|
L00019432 |
The GRAccessApp COM server should not throw an
exception when asked for information prior to a login. |
|
L00019447 |
The remove method on a .NET object of type
IConditions removes the incorrect item. |
|
L00019530 |
The properties Area and Host do not belong to the
IgObject interface. |
|
L00019535 |
The GetSecuritySettings, GetTimeMasterSettings,
and GetLocaleSettings return an IInstance .NET object representing the galaxy
instance. |
|
L00019542 |
The GRAccess Toolkit install needs to include a
Primary Interop Assembly for the GRAccess dll. |
|
L00019738 |
The VersionString method on a .NET object of type
IGalaxy returns internal slice information. |
|
L00019744 |
The UpgradeRequired method on a VB6 object of
type IGalaxy throws an exception when the galaxy object represents a galaxy
requiring an upgrade. |
|
L00019765 |
The CommandResult property on a .NET object of
type IgObject throws an exception if called after the Attributes property is called
on the same IObject. |
|
L00019771 |
The AddUDA method on a .NET object of type
IgObject does not function when leveraging optional parameters. |
|
L00019790 |
The AddExtensionPrimitive method with the
ExtensionType parameter equal to "inputoutputextension" on a .NET
object of type IgObject throws an exception when executed after previous
AddExtensionPrimitive calls. |
|
L00019791 |
The "ExtensionPrimitiveName" parameter
on the AddExtensionPrimitive method of the IgObject interface needs to be
renamed to "AttributeName". |
|
L00019794 |
The "ArrayElementCount" parameter on
the AddUDA method of the IgObject interface needs to have its data type
changed from Object to Integer. |
|
L00019809 |
The ExtensionType parameter on the AddExtensionPrimitive
method of IgObject should be an enumeration. |
|
L00019822 |
The ConfigurableAttributes and the Attributes
property on a .NET object of type IgObject return the same list of
attributes. |
|
L00019889 |
The EditStatus property on a
.NET instance of type IgObject returns a value of
"editedByThisSession" when the same user as the client GRAccess
code has the object checked out in the IDE. |
|
L00019890 |
The CommandResult property of
an instance of type IGalaxy has a value of true on its successful property
after an invalid login. |
|
L00019902 |
The GetObjectHelpURL on a
.NET instance of type IgObject is "Not implemented". |
|
L00019903 |
When executing the
DeleteExtensionPrimitive on a checked in .NET instance of type IgObject, the
CommandResult gives no indication clarifying the failure issue. |
|
L00019907 |
When executing the RenameUDA
method on a checked-in .NET instance of type IgObject, the CommandResult
gives no indication clarifying the failure issue. |
|
L00019915 |
Cannot modify the category of
a UDA to "Object writeable" using the UpdateUDA method on a .NET
instance of the IgObject interface |
