Joseph Doherty
32f26272ae
Five tools under one repo, all docs organized per DOCS-GUIDE.md: - aalogcli: .NET 4.8 / x86 CliFx CLI for reading System Platform binary logs (*.aaLGX) for LLM debugging, built on aaOpenSource/aaLog. Commands: last, tail, range, unread, fields. Stable JSON envelope under --llm-json. Build template under lib/build/ for rebuilding aaLogReader.dll. - aot: ArchestrA Object Toolkit 2014 v4.0 reference material. Dev guide (Markdown converted from CHM), API reference for the ArchestrA.Toolkit namespace, and the Monitor / Watchdog VS sample solutions. - graccesscli: .NET 4.8 / x86 CliFx CLI that automates Galaxy configuration via the ArchestrA GRAccess COM interop. Includes session daemon, IPC protocol, and llm-json envelope contract. - grdb: SQL/DDL exploration of the Galaxy Repository database. DDL captures, reusable queries, hierarchy / contained-name <-> tag-name translation notes. - histdb: LLM-oriented reference for AVEVA Historian retrieval. INSQL linked-server, extension tables, every wwXxx time-domain extension, every retrieval mode, alarm/event SQL recipes, REST API. Distilled from the 243-page Historian Retrieval Guide. Root contains: - CLAUDE.md: thin index pointing into each tool's README. - DOCS-GUIDE.md: doctrine for organizing docs for LLM consumption. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
278 KiB
Page 1
<img>invenys Wonderware®</img>
ArchestrA GRAccess Toolkit API User's Guide
5/6/14
Page 2
All rights reserved. No part of this documentation shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Invensys Systems, Inc. No copyright or patent liability is assumed with respect to the use of the information contained herein. Although every precaution has been taken in the preparation of this documentation, the publisher and the author assume no responsibility for errors or omissions. Neither is any liability assumed for damages resulting from the use of the information contained herein.
The information in this documentation is subject to change without notice and does not represent a commitment on the part of Invensys Systems, Inc. The software described in this documentation is furnished under a license or nondisclosure agreement. This software may be used or copied only in accordance with the terms of these agreements.
© 2002-2010, 2014 by Invensys Systems, Inc. All rights reserved.
Invensys Systems, Inc. 26561 Rancho Parkway South Lake Forest, CA 92630 U.S.A. (949) 727-3200
For comments or suggestions about the product documentation, send an e-mail message to ProductDocumentationComments@invensys.com.
All terms mentioned in this documentation that are known to be trademarks or service marks have been appropriately capitalized. Invensys Systems, Inc. cannot attest to the accuracy of this information. Use of a term in this documentation should not be regarded as affecting the validity of any trademark or service mark.
Alarm Logger, ActiveFactory, ArchestrA, Avantis, DBDump, DBLoad, DT Analyst, Factelligence, FactoryFocus, FactoryOffice, FactorySuite, FactorySuite A², InBatch, InControl, IndustrialRAD, IndustrialSQL Server, InTouch, MaintenanceSuite, MuniSuite, QI Analyst, SCADALarm, SCADASuite, SuiteLink, SuiteVoyager, WindowMaker, WindowViewer, Wonderware, Wonderware Factelligence, and Wonderware Logger are trademarks of Invensys plc, its subsidiaries and affiliates. All other brands may be trademarks of their respective owners.
Page 3
<page_number>3</page_number>
Contents
Welcome .................................................................................................................... 7 Documentation Conventions ........................................................................................ 7 Technical Support ....................................................................................................... 8
Chapter 1 About GRAccess Toolkit ................................................................................. 9 Target Clients .................................................................................................................. 9 GRAccess Object Model ................................................................................................... 10
Chapter 2 API Reference................................................................................................... 11 COM Classes ................................................................................................................... 11 GRAccess ........................................................................................................................ 11 GRAccessApp ................................................................................................................... 12 MxValue .......................................................................................................................... 12 Interfaces ...................................................................................................................... 12 IAssociatedFileAccess ................................................................................................... 13 IAttribute ....................................................................................................................... 13 IAttributes ..................................................................................................................... 21 ICommandResult ............................................................................................................. 25 ICommandResults ........................................................................................................... 26 ICondition ..................................................................................................................... 28 IConditions .................................................................................................................... 30 IGalaxies ...................................................................................................................... 33
GRAccess Toolkit API User's Guide
Page 4
<page_number>4</page_number> Contents
IGalaxy .................................................. 35 IGalaxyRole ............................................ 55 IGalaxyRoles .......................................... 57 IGalaxySecurity ...................................... 59 IGalaxyUser .......................................... 62 IGalaxyUsers ......................................... 64 IgObject ............................................... 65 IgObjects ............................................. 87 IGRAccess ............................................ 101 IInstance ............................................ 104 IMxValue ............................................. 134 IPermission .......................................... 167 IPermissions ........................................ 171 IScriptLibraries ................................... 173 IScriptLibrary ...................................... 175 ISecurityGroup ...................................... 177 ISecurityGroups .................................... 178 ISettings ............................................ 180 ITemplate ............................................ 182 IToolset ............................................. 207 IToolsets ........................................... 210 Type Definitions ................................... 213 EATTRIBUTEPROPERTY ................................ 214 EActionForCurrentlyDeployedObjects ............ 217 EAuthenticationMode ................................ 218 EAutomaticallyUndocheckout ....................... 218 EBASERUNTIMEOBJECT ................................. 218 ECATEGORY ........................................... 219 ECOMMONATTRIBUTES ................................ 221 ECOMMONPRIMITIVE .................................. 221 ECascade ............................................ 224 ECheckoutStatus .................................... 224 EConditionType ..................................... 225 EDeployOnScan ...................................... 227 EDeploymentStatus .................................. 227 EEXECUTIONGROUP ................................... 228 EEditStatus ........................................ 229 EExecutionOrder .................................... 230 EExportType ........................................ 230 EFileType ........................................... 231 EForceDeleteInstanceOption ...................... 232 EForceDeleteTemplateOption ...................... 232 EForceOffScan ...................................... 233
GRAccess Toolkit API User's Guide
Page 5
<page_number>5</page_number>
EGRCommandResult 233 EMatch 236 EPACKAGESTATUS 237 ERESERVEDPRIMITIVEIDS 237 ESkipIfCurrentlyUndeployed 238 ESkipObjectsWithPendingUpdates 238 ESkipOtherUsersCheckedOutObjects 239 ETestOnly 239 EUserDefault 240 EgObjectIsTemplateOrInstance 240 MxAttributeCategory 241 MxPropertyLockedEnum 243 GRAccess Code Examples 244 Programming Tips 244 Example for Defining the Entry Point for a Console Application 245 Example for Creating and Populating a Galaxy 250
Index 255
GRAccess Toolkit API User's Guide
Page 6
<page_number>6</page_number> Contents
GRAccess Toolkit API User's Guide
Page 7
<page_number>7</page_number>
Welcome
Archestra Galaxy configuration is exposed to .NET and COM clients through a programmable object model called GRAccess. You can use the GRAccess object model to write programs that automate configuration of local and remote Galaxies.
This documentation assumes you know how to use Microsoft Windows, including navigating menus, moving from application to application, and moving objects on the screen. If you need help with these tasks, see the Microsoft Help.
You can view this document online or you can print it, in part or whole, by using the print feature in Adobe Reader.
Documentation Conventions
This documentation uses the following conventions:
| Convention | Used for |
|---|---|
| Initial Capitals | Paths and file names. |
| Bold | Menus, commands, dialog box names, and dialog box options. |
| Monospace | Code samples and display text. |
GRAccess Toolkit API User's Guide
Page 8
<page_number>8</page_number>
Technical Support
Wonderware Technical Support offers a variety of support options to answer any questions on Wonderware products and their implementation.
Before you contact Technical Support, refer to the relevant section(s) in this documentation for a possible solution to the problem. If you need to contact technical support for help, have the following information ready:
- The type and version of the operating system you are using.
- Details of how to recreate the problem.
- The exact wording of the error messages you saw.
- Any relevant output listing from the Log Viewer or any other diagnostic applications.
- Details of what you did to try to solve the problem(s) and your results.
- If known, the Wonderware Technical Support case number assigned to your problem, if this is an ongoing problem.
Note: If you are installing the GAccess Toolkit on a 64-bit operating system, please see "Programming Tips" on page 244.
GAccess Toolkit API User's Guide
Page 9
<page_number>9</page_number>
Chapter 1
About GRAccess Toolkit
You can use the Wonderware® GRAccess object model to write programs that automate configuration of local and remote Galaxies.
GRAccess requires a license. Contact your local Wonderware Distributor for purchase information.
Target Clients
C# is the recommended programming language for GRAccess. GRAccess also works with other COM or .NET programming languages such as VB6, C++, and VB.NET.
GRAccess provides a .NET primary interop assembly for use in Microsoft .NET languages, and a COM type library that can be used in VB6 or other COM clients.
GRAccess Toolkit API User's Guide
Page 10
<page_number>10</page_number> Chapter 1 About GRAccess Toolkit
GRAccess Object Model
GRAccess provides a hierarchical object model. At the root of this object model is the GRAccessAppClass. The GRAccessAppClass provides access to other Archestra objects including Galaxies, gObject Templates and Instances.
Typically, only the GRAccessAppClass and the MxValue objects are created directly. Other objects are obtained by navigating the GRAccessAppClass object object model.
graph TD A[GRAccessApp] --> B[Galaxy Collection] A --> C[Command Results Collection] B --> D[Galaxy] B --> E[GalaxySecurity] C --> F[Command Result]E --> G[SecurityGroup Collection]
G --> H[SecurityGroup]
G --> I[gObject Collection]
D --> J[GalaxyRole Collection]
J --> K[GalaxyRole]
J --> L[Permission Collection]
L --> M[Permission]
M --> N[Permission Collection]
M --> O[SecurityGroup]
K --> P[GalaxyUser Collection]
P --> Q[GalaxyUser]
Q --> R[GalaxyRole Collection]
A --> S[Toolset Collection]
A --> T[ScriptLibrary Collection]
A --> U[gObject Collection]
U --> V[gObject (Template or Instance)]
V --> W[Attribute Collection]
W --> X[Attribute]
Page 11
<page_number>11</page_number>
Chapter 2
API Reference
You can use the GRAccess API to write programs that manipulate the configurations of local and remote Galaxies.
COM Classes
This section describes the COM classes that are defined and exposed through GRAccess. These include:
- GRAccess
- GRAccessApp
- MxValue
GRAccess
GRAccess is similar to GRAccessApp but is cocreated in-process to the client. Restrictions include:
- EXE program hosting the component must reside in the AppServer Bin folder.
- Single-stepping over GRAccess method calls with the Visual Basic 6.0 debugger may cause execution to run-away and not stop at the next line.
GRAccess Toolkit API User's Guide
Page 12
<page_number>12</page_number> Chapter 2 API Reference
Interfaces Implemented
IgObject
GRAccessApp
Clients use the GRAccess Component to gain access to the Galaxy Repository.
Interfaces Implemented
IgObject
MxValue
The MxValue provides storage and retrieval of ArchestrA data types. MxValues are passed as parameters in the AutomationObject Get and Set methods.
Interfaces Implemented
IMxValue
Interfaces
This section describes the COM interfaces that are defined and exposed through GRAccess. These interfaces include:
Objects
- IAssociatedFileAccess
- IAttribute
- ICommandResult
- ICondition
- IGalaxy
- IGalaxyRole
- IGalaxySecurity
- IGalaxyUser
- IGraphicAccess
- IInstance
- IMxValue
- IgObject
- IPermission
- IScriptLibrary
Collections of
- IAttributes
- ICommandResults
- IConditions
- IGalaxies
- IGalaxyRoles
- IGalaxyUsers
- IgObjects
- IPermissions
- IScriptLibraries
Page 13
Interfaces <page_number>13</page_number>
-
ISecurityGroup
-
ISettings
-
ITemplate
-
IToolset
-
ISecurityGroups
-
IToolsets
IAssociatedFileAccess
Internal use only.
IAttribute
Represents a single attribute of an object.
IAttribute Class Members
This class has the following members.
Operations
CommandResult Property Returns the CommandResult Object, which has the last method call's result.
RtSethandler Property Returns the RtSethandler property of the Attribute.
CfgSethandler Property Returns the CfgSethandler property of the Attribute.
SecurityClassification Property Returns the SecurityClassification property of the Attribute.
Name Property Returns the Name property of the Attribute.
DataType Property Returns the Type property of the Attribute.
SetLocked Method Sets the Locked property of the Attribute.
UpperBoundDim1 Property Returns the UpperBoundDim1 property of the Attribute.
SetSecurityClassification Method Sets the SecurityClassification property of the Attribute.
Locked Property Returns the Locked property of the Attribute.
SetValue Method Sets the Value of the Attribute.
Value Property Returns the Value of the Attribute.
GRAccess Toolkit API User's Guide
Page 14
<page_number>14</page_number> Chapter 2 API Reference
AttributeCategory Property Returns the Category of the Attribute.
HasBuffer Property Returns the HasBuffer property of the Attribute.
SetHasBuffer Method Sets the HasBuffer property of the Attribute.
CommandResult Property Returns the CommandResult object, which has the last method call's result.
Class IAttribute
Syntax
[C#]
ICommandResult CommandResult { get; };
[Visual C++]
HRESULT CommandResult(
[out, retval] ICommandResult** CommandResult
);
Parameters
CommandResult Returns the CommandResult.
RtSethandler Property Returns the RtSethandler property of the attribute.
Class IAttribute
Syntax
[C#]
bool RtSethandler { get; };
[Visual C++]
HRESULT RtSethandler(
[out, retval] VARIANT_BOOL* hasRtSethandler
);
Parameters
hasRtSethandler Returns the RtSethandler property of the attribute.
GAccess Toolkit API User's Guide
Page 15
Interfaces <page_number>15</page_number>
CfgSethandler Property
Returns the CfgSethandler property of the attribute.
Class IAttribute
Syntax
[C#]
bool CfgSethandler { get; };
[Visual C++]
HRESULT CfgSethandler(
[out, retval] VARIANT_BOOL* hasCfgSethandler
);
Parameters
hasCfgSethandler
Returns the CfgSethandler property of the attribute.
SecurityClassification Property
Returns the SecurityClassification property of the attribute.
Class IAttribute
Syntax
[C#]
MxSecurityClassification SecurityClassification { get; };
[Visual C++]
HRESULT SecurityClassification(
[out, retval] MxSecurityClassification* securityClassification
);
Parameters
securityClassification
Returns the SecurityClassification property of the attribute.
GRAccess Toolkit API User's Guide
Page 16
<page_number>16</page_number> Chapter 2 API Reference
Name Property
Returns the name property of the attribute.
Class IAttribute
Syntax
[C#]
string Name { get; };
[Visual C++]
HRESULT Name(
[out, retval] BSTR* name
);
Parameters
name Returns the name property of the attribute.
DataType Property
Returns the type property of the attribute.
Class IAttribute
Syntax
[C#]
MxDataType DataType { get; };
[Visual C++]
HRESULT DataType(
[out, retval] MxDataType* dataType
);
Parameters
dataType Returns the type property of the attribute.
GRAccess Toolkit API User's Guide
Page 17
Interfaces <page_number>17</page_number>
SetLocked Method
Sets the locked property of the attribute.
Class IAttribute
Syntax
[C#]
void SetLocked(
MxPropertyLockedEnum NewMxPropertyLockedEnum
);
[Visual C++]
HRESULT SetLocked(
[in] MxPropertyLockedEnum
);
Parameters
- MxPropertyLockedEnum The new locked property of the attribute.
UpperBoundDim1 Property
Returns the UpperBoundDim1 property of the attribute.
Class IAttribute
Syntax
[C#]
short UpperBoundDim1 { get; };
[Visual C++]
HRESULT UpperBoundDim1 (
[out, retval] short* upperBoundDim1
);
Parameters
- upperBoundDim1 Returns the UpperBoundDim1 property of the attribute.
GRAccess Toolkit API User's Guide
Page 18
<page_number>18</page_number> Chapter 2 API Reference
SetSecurityClassification Method
Sets the SecurityClassification property of the attribute.
Class IAttribute
Syntax
[C#]
void SetSecurityClassification(
MxSecurityClassification NewMxSecurityClassification
);
[Visual C++]
HRESULT SetSecurityClassification(
[in] MxSecurityClassification
);
Parameters
- MxSecurityClassification The new SecurityClassification property of the attribute.
Locked Property
Returns the Locked property of the attribute.
Class IAttribute
Syntax
[C#]
MxPropertyLockedEnum Locked { get; };
[Visual C++]
HRESULT Locked(
[out, retval] MxPropertyLockedEnum*
);
Parameters
- MxPropertyLockedEnum Returns the Locked property of the attribute.
GRAccess Toolkit API User's Guide
Page 19
Interfaces <page_number>19</page_number>
SetValue Method
Sets the value of the attribute.
Class IAttribute
Syntax
[C#]
void SetValue(
MxValue NewValue
);
[Visual C++]
HRESULT SetValue(
[in] IMxValue* NewValue
);
Parameters
NewValue The new value of the attribute.
Value Property
Returns the value of the attribute.
Class IAttribute
Syntax
[C#]
MxValue value { get; };
[Visual C++]
HRESULT Value(
[out, retval] IMxValue** value
);
Parameters
value Returns the value of the attribute.
GRAccess Toolkit API User's Guide
Page 20
<page_number>20</page_number> Chapter 2 API Reference
AttributeCategory Property
Returns the category of the attribute.
Class
IAttribute
Syntax
[C#]
MxAttributeCategory AttributeCategory { get; };
[Visual C++]
HRESULT AttributeCategory(
[out, retval] MxAttributeCategory* attributeCategory
);
Parameters
attributeCategory Returns the category of the attribute.
HasBuffer Property
Returns the HasBuffer property of the attribute.
Class
IAttribute
Syntax
[C#]
bool HasBuffer { get; };
[Visual C++]
HRESULT HasBuffer(
[out, retval] VARIANT_BOOL* hasBuffer
);
Parameters
hasBuffer Returns the HasBuffer property of the attribute.
GRAccess Toolkit API User's Guide
Page 21
Interfaces <page_number>21</page_number>
SetHasBuffer Method
Sets the HasBuffer property of the attribute.
Class IAttribute
Syntax
[C#]
void SetHasBuffer(bool hasBuffer);
[Visual C++]
HRESULT SetHasBuffer(
[in] VARIANT_BOOL hasBuffer
);
Parameters
- hasBuffer The new value of the attribute.
IAttributes
Represents a collection of attribute objects.
IAttributes Class Members
This class has the following members.
Operations
- Item Property Returns the Attribute object by name or index.
- Count Property Returns the number of attributes in the collection.
- ShortDescription Property Returns the short description for this object.
- ExecutionOrder Property Returns the name of the execution order of this object.
- SecurityGroup Property Returns the securitygroup for this object.
- ExecutionRelatedObject Property Returns the name of the execution related object of this object.
GRAccess Toolkit API User's Guide
Page 22
<page_number>22</page_number> Chapter 2 API Reference
Item Property
Returns the attribute object by name or index.
Class
IAttributes
Syntax
[C#]
IAttribute this[object attributeIdentifier] { get; };
[Visual C++]
HRESULT Item(
[in] VARIANT attributeIdentifier,
[out, retval] IAttribute**
);
Parameters
attributeIdentifier The name of the attribute object to return if a string is specified. If a number is specified, it is interpreted as the index into this collection and is in the range from 1 to count. IAttribute The returned attribute object or nothing if attribute doesn't exist.
Count Property
Returns the number of attributes in the collection.
Class
IAttributes
Syntax
[C#]
int count { get; };
[Visual C++]
HRESULT Count (
[out, retval] LONG* count
);
Parameters
count The number of attributes in the collection.
GRAccess Toolkit API User's Guide
Page 23
Interfaces <page_number>23</page_number>
ShortDescription Property
Returns the short description of this object.
Class IAttributes
Syntax
[C#]
string ShortDescription { set; get; }
[Visual C++]
[propget]
HRESULT ShortDescription(
[out, retval] BSTR*
);
[propput]
HRESULT ShortDescription(
[in] BSTR
);
ExecutionOrder Property
Returns the name of the execution order of this object.
Class IAttributes
Syntax
[C#]
EExecutionOrder ExecutionOrder { set; get; }
[Visual C++]
[propget]
HRESULT ExecutionOrder(
[out, retval] EExecutionOrder*
);
[propput]
HRESULT ExecutionOrder(
[in] EExecutionOrder
);
---
## Page 24
<page_number>24</page_number> Chapter 2 API Reference
# SecurityGroup Property
Returns the security group for this object.
## Class
IAttributes
## Syntax
[C#]
```csharp
string SecurityGroup { set; get; }
[Visual C++]
[propget]
HRESULT SecurityGroup(
[out, retval] BSTR*
);
[propput]
HRESULT SecurityGroup(
[in] BSTR
);
ExecutionRelatedObject Property
Returns the name of the execution related object of this object.
Class
IAttributes
Syntax
[C#]
string ExecutionRelatedObject { set; get; }
[Visual C++]
[propget]
HRESULT ExecutionRelatedObject(
[out, retval] BSTR*
);
[propput]
HRESULT ExecutionRelatedObject(
[in] BSTR newExecutionRelatedObject
);
Parameters
newExecutionRelatedObject The name of the execution related object.
GRAccess Toolkit API User's Guide
Page 25
Interfaces <page_number>25</page_number>
ICommandResult
Indicates the result of a given operation (for instance, success, fail and why).
ICommandResult Class Members
This class has the following members.
Operations
Successful Property Indicates whether the operation was successful.
Text Property Textual description corresponding to the result code.
ID Property Reason code for the result.
CustomMessage Property Custom message associated with the result.
Successful Property
Indicates whether the operation was successful.
Class
ICommandResult
Syntax
[C#]
bool Successful { get; };
[Visual C++]
HRESULT Successful( [out, retval] VARIANT_BOOL* );
Text Property
Textual description corresponding to the result code.
Class
ICommandResult
Syntax
[C#]
string Text { get; }
[Visual C++]
HRESULT Text( [out, retval] BSTR* );
---
## Page 26
<page_number>26</page_number> Chapter 2 API Reference
# ID Property
Reason code for the result.
**Class**
ICommandResult
**Syntax**
[C#]
```csharp
EGRCommandResult ID { get; };
[Visual C++]
HRESULT ID( [out, retval] EGRCommandResult* );
CustomMessage Property
Custom message associated with the result.
Class ICommandResult
Syntax
[C#]
string CustomMessage { get; };
[Visual C++]
HRESULT CustomMessage( [out, retval] BSTR* );
ICommandResults
Represents a collection of CommandResult objects.
ICommandResults Class Members
This class has the following members.
Operations
Count Property Returns the number of CommandResults in the collection.
Item Method Returns the CommandResult object by index.
CompletelySuccessful Property Indicates that all CommandResult objects in the collection are successful.
GRAccess Toolkit API User's Guide
Page 27
Interfaces <page_number>27</page_number>
Count Property
Returns the number of CommandResult objects in the collection.
Class ICommandResults
Syntax
[C#]
int count { get; };
[Visual C++]
HRESULT Count(
[out, retval] LONG*
);
Item Method
Returns the CommandResult object by index.
Class ICommandResults
Syntax
[C#]
ICommandResult get_Item(
int index
);
[Visual C++]
HRESULT Item(
[in] LONG index,
[out, retval] ICommandResult** customResult
);
Parameters
index The Index of the CommandObject. This is a numeric value from 1 to count.
customResult The returned CommandResult object.
GRAccess Toolkit API User's Guide
Page 28
<page_number>28</page_number> Chapter 2 API Reference
CompletelySuccessful Property
Indicates that all CommandResult objects in the collection are successful.
Class
ICommandResults
Syntax
[C#]
bool CompletelySuccessful { get; };
[Visual C++]
HRESULT CompletelySuccessful(
[out, retval] VARIANT_BOOL* completelySuccessful
);
Parameters
completelySuccessful
Indicates that all CommandResult objects in the collection are successful.
ICondition
Indicates a condition used when querying for a list of objects.
ICondition Class Members
This class has the following members.
Operations
Kind Property Indicates the type of condition to be used by the query.
Value Property The value to be searched for. Meaning is based on the Kind parameter.
Negation Property Negation. Specify False to “NOT” the expression.
GRAccess Toolkit API User’s GuidePage 29
Interfaces <page_number>29</page_number>
Kind Property
Indicates the type of condition to be used by the query.
Class
ICondition
Syntax
[C#]
EConditionType Kind { get; };
[Visual C++]
HRESULT Kind( [out, retval] EConditionType* Kind );
Value Property
The value to be searched for. Meaning is based on the Kind parameter.
Class
ICondition
Syntax
[C#]
object value { get; };
[Visual C++]
HRESULT Value( [out, retval] VARIANT* Value );
Negation Property
Negation. Specify False to “NOT” the expression.
Class
ICondition
Syntax
[C#]
EConditionType Negation { get; };
[Visual C++]
HRESULT Negation([out, retval] VARIANT_BOOL* Value );
GRAccess Toolkit API User's Guide
Page 30
<page_number>30</page_number> Chapter 2 API Reference
IConditions
Represents a collection of condition objects.
IConditions Class Members
This class has the following members.
Operations
CommandResult Property Returns the CommandResult Object, which has the last method call's result.
Remove Method Remove a condition object from the collection.
Add Method Add a condition object to the collection.
Count Property Returns the number of condition objects in the collection.
Item Property Returns the condition object by index.
Join Method Join two condition objects.
CommandResult Property
Returns the CommandResult object, which has the last method call's result.
Class
IConditions
Syntax
[C#]
ICommandResult CommandResult { get; };
[Visual C++]
HRESULT CommandResult(
[out, retval] ICommandResult** CommandResult
);
Parameters
CommandResult Returns the CommandResult object.
GRAccess Toolkit API User's GuidePage 31
Interfaces <page_number>31</page_number>
Remove Method
Remove a condition object from the collection.
Class IConditions
Syntax
[C#]
void Remove(
int index
);
[Visual C++]
HRESULT Remove(
[in] LONG index
);
Parameters
index The index of the condition object. This is a numeric value from 1 to count.
Add Method
Add a condition object to the collection.
Class IConditions
Syntax
[C#]
void Add(
EConditionType Kind,
object value,
bool Negation
);
[Visual C++]
HRESULT Add(
[in] EConditionType Kind,
[in] VARIANT Value,
[in, optional, defaultvalue( -1 )] VARIANT_BOOL negation
);
GRAccess Toolkit API User's Guide
Page 32
<page_number>32</page_number> Chapter 2 API Reference
Parameters
Kind Indicates the type of condition to be used by the query.
Value The value to be searched for. Meaning is based on the Kind parameter.
negation Negation. To NOT the expression, pass False for negation.
Count Property
Returns the number of condition objects in the collection.
Class
IConditions
Syntax
[C#]
int count { get; };
[Visual C++]
HRESULT Count(
[out, retval] LONG*
);
Item Property
Returns the condition object by index.
Class
IConditions
Syntax
[C#]
ICondition this[int index] { get; };
[Visual C++]
HRESULT Item(
[in] LONG index,
[out, retval] ICondition**
);
---
## Page 33
Interfaces <page_number>33</page_number>
## Parameters
**index**
The index of the condition object. This is a numeric value from 1 to count.
**ICondition**
The returned condition object.
## Join Method
Join two conditions.
### Class
IConditions
### Syntax
[C#]
```csharp
void Join(
IConditions conditions
);
[Visual C++]
HRESULT Join(
[in] IConditions* conditions
);
Parameters
conditions The returned condition object.
IGalaxies
Represents a collection of Galaxies.
IGalaxies Class Members
This class has the following members.
Operations
Item Property Return a Galaxy
Count Property Returns the number of Galaxy objects in the collection.
GRAccess Toolkit API User's Guide
Page 34
<page_number>34</page_number> Chapter 2 API Reference
Item Property
Return a Galaxy
Class
IGalaxies
Syntax
[C#]
IGalaxy this[object galaxyIdentifier] { get; };
[Visual C++]
HRESULT Item(
[in] VARIANT galaxyIdentifier,
[out, retval] IGalaxy**
);
Parameters
galaxyIdentifier The index of a Galaxy. This is a numeric value from 1 to count, or the name of the Galaxy.
IGalaxy The returned Galaxy object.
Count Property
Returns the number of Galaxy objects in the collection.
Class
IGalaxies
Syntax
[C#]
int count { get; };
[Visual C++]
HRESULT Count(
[out, retval] LONG*
);
Page 35
Interfaces <page_number>35</page_number>
IGalaxy
Represents a Galaxy.
IGalaxy Class Members
This class has the following members.
Operations
CommandResult Property Returns the CommandResult object, which has the last method call's result.
QueryObjectsMultiCondition Method Retrieves a gObjects collection using multiple conditions.
QueryScriptLibraries Method Query Script Libraries.
Name Property Retrieves the name of the Galaxy.
Backup Method Backs-up the given Galaxy to a backup file.
VersionString Property Retrieves the version string of the Galaxy.
Login Method Logs in to an ArchestrA Galaxy and performs a forced synchronization of the client with the Galaxy Repository. This method must be called before any other Galaxy method.
LoginEx Method Logs in to an ArchestrA Galaxy and offers the option to perform synchronization at a later point in time and cancel synchronization. This method must be called before any other Galaxy method.
SynchronizeClient Method Synchronizes the client with the server.
GetTimeMasterSettings Method Retrieves TimeMaster settings.
CreategObjectCollection Method Creates an empty gObjects collection object
ImportObjects Method Imports objects into the Galaxy.
QueryToolsets Method Retrieves the list of available Toolsets.
QueryObjectsByName Method Retrieves a gObjects collection based on a set of tagnames.
GRAccess Toolkit API User's GuidePage 36
<page_number>36</page_number> Chapter 2 API Reference
GetUserDefaults Method Get the logged in user's defaults from the Galaxy repository.
VersionNumber Property Retrieves the version number of the Galaxy.
SetUserDefaults Method Set the logged in user's defaults.
Restore Method Restores a Galaxy from a backup file.
Logout Method Logs out from an ArchestrA Galaxy.
UpgradeRequired Property Retrieves the Boolean indicated if the Galaxy needs to be upgraded.
MigrateGalaxy Method Upgrade a Galaxy.
CdiVersionString Property Retrieves the version string of the Cdi.
GetSecuritySettings Method Retrieves the Galaxy's security settings.
CreateConditionsObject Method Creates a condition object used with QueryObjectsMultiCondition.
QueryObjects Method Retrieves a gObjects collection based on the given criteria.
ImportScriptLib Method Imports this script library.
GetLocaleSettings Method Retrieves the Galaxy's local settings.
ExportAll Method Exports all objects in the Galaxy.
GetReadOnlySecurity Method Accesses the Galaxy security in read-only mode.
CommandResults Property Returns a collection of CommandResult objects.
GRLoad Method Loads the Galaxy from a CSV file.
ImportObjectsEx Method Imports objects into the Galaxy.
IGalaxyQueryToolsetsEx Method Retrieves the list of available Toolsets.
GRAccess Toolkit API User's GuidePage 37
Interfaces <page_number>37</page_number>
CommandResult Property
Returns the CommandResult object, which has the last method call's result.
Class IGalaxy
Syntax
[C#]
ICommandResult CommandResult { get; };
[Visual C++]
HRESULT CommandResult(
[out, retval] ICommandResult** CommandResult
);
Parameters
CommandResult Returns a CommandResult object.
QueryObjectsMultiCondition Method
Retrieves a gObjects collection using multiple conditions.
Class IGalaxy
Syntax
[C#]
IgObjects QueryObjectsMultiCondition(
EgObjectIsTemplateOrInstance templateOrInstance,
IConditions conditions
);
[Visual C++]
HRESULT QueryObjectsMultiCondition(
[in] EgObjectIsTemplateOrInstance templateOrInstance,
[in] IConditions* Conditions,
[out, retval] IgObjects**
);
Parameters
templateOrInstance Indicates whether a gObject is a template or an instance.
GRAccess Toolkit API User's GuidePage 38
<page_number>38</page_number> Chapter 2 API Reference
Conditions A condition collection object containing a list of conditions to be ANDed together.
IgObjects Returns a gObjects collection.
QueryScriptLibraries Method
Query Script Libraries.
Class
IGalaxy
Syntax
[C#]
IScriptLibraries QueryScriptLibraries();
[Visual C++]
HRESULT QueryScriptLibraries(
[out, retval] IScriptLibraries** scriptLibraries
);
Parameters
scriptLibraries The list of script libraries.
Name Property
Retrieves the name of the Galaxy.
Class
IGalaxy
Syntax
[C#]
string Name { get; };
[Visual C++]
HRESULT Name(
[out, retval] BSTR* Galaxy
);
Parameters
Galaxy Returns the name of Galaxy.
GRAccess Toolkit API User's Guide
Page 39
Interfaces <page_number>39</page_number>
Backup Method
Backs up the given the Galaxy to a backup file.
Class
IGalaxy
Syntax
[C#]
void Backup(
int lProcessId,
string backupFilename,
string GRNodeName,
string Galaxy
);
[Visual C++]
HRESULT Backup
(
[in] LONG lProcessId,
[in] BSTR backupFilename,
[in, optional] BSTR GRNodeName,
[in, optional] BSTR Galaxy
);
Parameters
lProcessId Process ID of the calling process.
backupFilename Name of the backup file. File extension .cab is appended if not specified. If a folder name is specified, the contents of the folder is deleted and the backup files are placed directly in the folder.
GRNodeName The name of the GR node (computer name). Blank or omitted means the current computer is the GR.
Galaxy The name of the Galaxy (application database).
GRAccess Toolkit API User's GuidePage 40
<page_number>40</page_number> Chapter 2 API Reference
VersionString Property
Retrieves the version string of the Galaxy.
Class
IGalaxy
Syntax
[C#]
string VersionString { get; }
[Visual C++]
HRESULT VersionString(
[out, retval] BSTR* VersionString
);
Parameters
VersionString Returns the version string of the Galaxy.
Login Method
Logs in to an Archestra Galaxy and performs a forced synchronization of the client with the Galaxy Repository. This method must be called before any other Galaxy method.
Class
IGalaxy
Syntax
[C#]
void Login(
string UserName, string Password
);
[Visual C++]
HRESULT Login(
[in, optional] BSTR UserName,
[in, optional] BSTR Password
);
Parameters
UserName The name of the user. Blank or omitted means log in as “admin”.
Password The user's password. Blank or omitted means use a blank password.
GRAccess Toolkit API User’s Guide
Page 41
Interfaces <page_number>41</page_number>
Remarks
If GRAccess is already logged into a Galaxy, the session is logged off and re-established with the specified Galaxy.
LoginEx Method
Logs in to an ArchestrA Galaxy and offers the option to perform synchronization at a later point in time and cancel synchronization. This method must be called before any other Galaxy method.
Class
IGalaxy
Syntax
[C#]
void LoginEx(
string UserName, string Password, bool bForceSynchronization
);
[Visual C++]
HRESULT LoginEx (
[in, optional] BSTR UserName,
[in, optional] BSTR Password,
[in, optional] VARIANT_BOOL bForceSynchronization
);
Parameters
UserName The name of the user. Blank or omitted means log in as “admin”.
Password The user's password. Blank or omitted means use a blank password.
bForceSynchronization Set to true to synchronize the client with the server if out of sync is detected.
Remarks
If GRAccess is already logged into a Galaxy, the session is logged off and re-established with the specified Galaxy.
GRAccess Toolkit API User’s Guide
Page 42
<page_number>42</page_number> Chapter 2 API Reference
SynchronizeClient Method
Synchronizes the client with the server.
Class IGalaxy
Syntax
[C#]
void SynchronizeClient()
[Visual C++]
HRESULT SynchronizeClient();
Remarks User should be logged in.
GetTimeMasterSettings Method
Retrieves TimeMaster settings.
Class IGalaxy
Syntax
[C#]
ISettings GetTimeMasterSettings();
[Visual C++]
HRESULT GetTimeMasterSettings(
[out, retval] ISettings**
);
Parameters
- ISettings Returns a gObjects collection object.
Remarks Automatically check-out the instance for the settings object. While the instance is checked out, no other object may be checked out. User should be logged in.
GRAccess Toolkit API User's Guide
Page 43
Interfaces <page_number>43</page_number>
CreategObjectCollection Method
Creates an empty gObjects collection object.
Class IGalaxy
Syntax
[C#]
IgObjects CreategObjectCollection();
[Visual C++]
HRESULT CreategObjectCollection(
[out, retval] IgObjects** gObjects
);
Parameters
gObjects
The newly created gObjects object.
ImportObjects Method
Imports objects into the Galaxy.
Class IGalaxy
Syntax
[C#]
void ImportObjects(
string inputFile,
bool OverwritesAllowed
);
[Visual C++]
HRESULT ImportObjects(
[in] BSTR inputFile,
[in, optional, defaultvalue( 0 )]
VARIANT_BOOL OverwritesAllowed
);
GRAccess Toolkit API User's Guide
Page 44
<page_number>44</page_number> Chapter 2 API Reference
Parameters
inputFile The name of the input file -- can be aaPDF or aaPKG file. aaPDF is base Template and aaPKG is exported objects file format.
OverwritesAllowed Indicates whether existing objects can be overwritten.
Remarks
User should be logged in.
QueryToolsets Method
Retrieves a collection object containing the available Toolsets.
Class
IGalaxy
Syntax
[C#]
IToolsets QueryToolsets();
[Visual C++]
HRESULT QueryToolsets(
[out, retval] IToolsets** toolsets
);
Parameters
toolsets The Toolsets collection object.
Remarks
User should be logged in.
QueryObjectsByName Method
Retrieves a gObjects collection based on a set of tagnames.
Class
IGalaxy
Syntax
[C#]
IgObjects QueryObjectsByName(
EgObjectIsTemplateOrInstance templateOrInstance, ref
string[] tagnames
);
Page 45
Interfaces <page_number>45</page_number>
[Visual C++]
HRESULT QueryObjectsByName (
[in] EgObjectIsTemplateOrInstance templateOrInstance,
[in, out] SAFEARRAY(BSTR) * Tagnames,
[out, retval] IgObjects**
);
Parameters
templateOrInstance Indicates whether a gObject is a template or an instance.
Tagnames An array of tagnames. Any tagname found in the Galaxy will be included in the returned collection.
IgObjects Returns a gObjects collection object.
Remarks
User should be logged in.
Note: If a tagname is not found, it is simply not included in the returned collection object.
GetUserDefaults Method
Get the logged in user's defaults from the Galaxy repository.
Class
IGalaxy
Syntax
[C#]
string GetUserDefaults(
EUserDefault userDefault
);
[Visual C++]
HRESULT GetUserDefaults (
[in] EUserDefault userDefault,
[out, retval] BSTR* defaultValue
);
Parameters
userDefault The default.
defaultValue The value of the default.
GRAccess Toolkit API User's GuidePage 46
<page_number>46</page_number> Chapter 2 API Reference
VersionNumber Property
Retrieves the version number of the Galaxy.
Class
IGalaxy
Syntax
[C#]
int VersionNumber { get; };
[Visual C++]
HRESULT VersionNumber(
[out, retval] LONG* VersionNumber
);
Parameters
VersionNumber
Returns the version number of Galaxy.
SetUserDefaults Method
Set the logged in user's defaults.
Class
IGalaxy
Syntax
[C#]
void SetUserDefaults(
EUserDefault userDefault,
string defaultValue
);
[Visual C++]
HRESULT SetUserDefaults(
[in] EUserDefault userDefault,
[in] BSTR defaultValue
);
Parameters
userDefault The default.
defaultValue The value of the default.
GRAccess Toolkit API User's Guide
Page 47
Interfaces <page_number>47</page_number>
Restore Method
Restores a Galaxy from a backup file.
Class
IGalaxy
Syntax
[C#]
void Restore(
int lProcessId,
string backupFilename,
string GRNodeName,
string Galaxy,
bool bRestoreOlderVersion
);
[Visual C++]
HRESULT Restore (
[in] LONG lProcessId,
[in] BSTR backupFilename,
[in, optional] BSTR GRNodeName,
[in, optional] BSTR Galaxy,
[in, optional] VARIANT_BOOL bRestoreOlderVersion
);
Parameters
lProcessId Process ID of the calling process.
backupFilename Name of the backup file. File extension cab is appended if not specified. If a folder name is specified, the Galaxy is restored from the contents of the folder.
GRNodeName The name of the GR node (computer name). Blank or omitted means the current computer is the GR.
Galaxy The name of an exiting Galaxy (application database) into which the backed up Galaxy is to be restored into.
bRestoreOlderVersion Indicates whether to restore the database even if backup is an older version. If omitted, this field is set to false indicating an older database that should not be restored.
Remarks
User should not be logged in.
GRAccess Toolkit API User's GuidePage 48
<page_number>48</page_number> Chapter 2 API Reference
Logout Method
Logs out from an ArchestrA Galaxy.
Class IGalaxy
Syntax
[C#]
void Logout();
[Visual C++]
HRESULT Logout();
Remarks Logs out from an ArchestrA Galaxy.
UpgradeRequired Property
Retrieves a Boolean that indicates whether the Galaxy needs to be upgraded.
Class IGalaxy
Syntax
[C#]
bool UpgradeRequired { get; };
[Visual C++]
HRESULT UpgradeRequired(
[out, retval] VARIANT_BOOL* vtUpgradeRequired
);
Parameters
vtUpgradeRequired Returns a Boolean indicating whether the Galaxy needs to be upgraded.
GRAccess Toolkit API User's Guide
Page 49
Interfaces <page_number>49</page_number>
MigrateGalaxy Method
Upgrade a Galaxy.
Class IGalaxy
Syntax
[C#]
void MigrateGalaxy(
string galaxyName,
string grNodeName
);
[Visual C++]
HRESULT MigrateGalaxy(
[in] BSTR galaxyName,
[in, optional] BSTR grNodeName
);
Parameters
galaxyName The name of the Galaxy.
grNodeName The name of the GR node (computer name). Blank or omitted means the current computer is the GR.
CdiVersionString Property
Retrieves the version string of the Cdi.
Class IGalaxy
Syntax
[C#]
string CdiVersionString { get; }
[Visual C++]
HRESULT CdiVersionString(
[out, retval] BSTR* VersionString
);
Parameters
VersionString Returns the version string of Cdi.
GRAccess Toolkit API User's Guide
Page 50
<page_number>50</page_number> Chapter 2 API Reference
GetSecuritySettings Method
Retrieves the security settings.
Class IGalaxy
Syntax
[C#]
ISettings GetSecuritySettings();
[Visual C++]
HRESULT GetSecuritySettings(
[out, retval] ISettings** settings
);
Parameters
settings Returns a gObjects collection.
Remarks
Automatically checks-out the instance of the settings object. While the instance is checked out, no other object may be checked out. User should be logged in.
CreateConditionsObject Method
Creates a conditions object used with QueryObjectsMultiCondition.
Class IGalaxy
Syntax
[C#]
IConditions CreateConditionsObject();
[Visual C++]
HRESULT CreateConditionsObject(
[out, retval] IConditions** conditions
);
Parameters
conditions The newly created conditions object.
GRAccess Toolkit API User's Guide
Page 51
Interfaces <page_number>51</page_number>
QueryObjects Method
Retrieves gObjects collection based on the given criteria.
Class
IGalaxy
Syntax
[C#]
IgObjects QueryObjects(
EgObjectIsTemplateOrInstance templateOrInstance,
EConditionType Kind,
object value,
EMatch MatchCondition
);
[Visual C++]
HRESULT QueryObjects(
[in] EgObjectIsTemplateOrInstance templateOrInstance,
[in] EConditionType Kind,
[in] VARIANT Value,
[in, optional, defaultvalue( MatchCondition )] EMatch MatchCondition,
[out, retval] IgObjects**
);
Parameters
templateOrInstance Indicates whether a gObject is a template or an instance.
Kind Indicates the type of condition used by the query.
Value The value to be searched for. Meaning is based on the Kind parameter.
MatchCondition To negate the condition, pass False.
IgObjects Returns a gObjects collection.
Remarks
User should be logged in.
GRAccess Toolkit API User's Guide
Page 52
<page_number>52</page_number> Chapter 2 API Reference
ImportScriptLib Method
Import a script library.
Class IGalaxy
Syntax
[C#]
void ImportScriptLib(
string path
);
[Visual C++]
HRESULT ImportScriptLib(
[in] BSTR path
);
Parameters
path Path to the .aaslib file.
GetLocaleSettings Method
Retrieves locale settings.
Class IGalaxy
Syntax
[C#]
ISettings GetLocaleSettings( );
[Visual C++]
HRESULT GetLocaleSettings(
[out, retval] ISettings**
);
Parameters
ISettings Returns a gObjects collection.
Remarks
Automatically check-out the instance for the settings object. While the instance is checked out, no other object may be checked out. User should be logged in.
GRAccess Toolkit API User's Guide
Page 53
Interfaces <page_number>53</page_number>
ExportAll Method
Exports all objects in the Galaxy.
Class IGalaxy
Syntax
[C#]
void ExportAll(
EExportType exportType,
string outputFile
);
[Visual C++]
HRESULT ExportAll (
[in] EExportType exportType,
[in] BSTR outputFile
);
Parameters
- exportType Indicates whether to export to aaPKG file.
- outputFile The name of the output file. Appends extension if one is not specified.
Remarks
User should be logged in.
GetReadOnlySecurity Method
Accesses the Galaxy security in read-only mode. The user can not modify the Galaxy security.
Class IGalaxy
Syntax
[C#]
IGalaxySecurity GetReadOnlySecurity( );
[Visual C++]
HRESULT GetReadOnlySecurity (
[in] IGalaxySecurity** galaxySecurity
);
GRAccess Toolkit API User's Guide
Page 54
<page_number>54</page_number> Chapter 2 API Reference
Parameters
galaxySecurity IGalaxySecurity provides an API interface to read the Galaxy security information configured using the security dialog box in aaIDE.
CommandResults Property
Returns the CommandResult.
Class
IGalaxy
Syntax
[C#]
ICommandResults CommandResults { get; };
[Visual C++]
HRESULT CommandResults(
[out, retval] ICommandResults** CommandResults
);
GRLoad Method
Class
IGalaxy
Syntax
[C#]
void GRLoad(
string CSVFileNameWithPath,
GRLoadMode GRLoadMode
);
[Visual C++]
HRESULT GRLoad(
[in, string] LPCOLESTR CSVFileNameWithPath,
[in] GRLoadMode grLoadMode
);
ImportObjectsEx Method
Class
IGalaxy
GRAccess Toolkit API User's Guide
Page 55
Interfaces <page_number>55</page_number>
Syntax
[C#]
void ImportObjectsEx(
string inputFile,
E_RESOLVE_VERSION_CONFLICT_ACTION versionMismatchPreference,
E_RESOLVE_NAME_CONFLICT_ACTION nameConflictPreference,
string appendToObjectName
);
[Visual C++]
HRESULT ImportObjectsEx(
// The name of the input file -- can be a PDF or //.csv file.
[in] BSTR inputFile,
[in] E_RESOLVE_VERSION_CONFLICT_ACTION versionMismatchPreference,
[in] E_RESOLVE_NAME_CONFLICT_ACTION nameConflictPreference,
[in] BSTR appendToObjectName
);
IGalaxyQueryToolsetsEx Method
Class
IGalaxy
Syntax
[C#]
IToolsets QueryToolsetsEx(
FolderType eFolderType
);
[Visual C++]
HRESULT QueryToolsetsEx
(
// The list of toolsets.
[in] enum FolderType eFolderType,
[out, retval] IToolsets** toolsets
);
IGalaxyRole
Accesses the role object and its properties, including role name, access level, list of general permissions, and operational permissions.
IGalaxyRole Class Members
This class has the following members.
GRAccess Toolkit API User's Guide
Page 56
<page_number>56</page_number> Chapter 2 API Reference
Operations
RoleName Property
Returns the name of the Galaxy role.
AccessLevel Property
Returns the access level of the Galaxy role.
Permissions Property
Returns the general permissions of the Galaxy role.
OperationalPermissions Property
Returns the operational permissions of the Galaxy role.
RoleName Property
Returns the name of the Galaxy role.
Class
IGalaxyRole
Syntax
[C#]
string RoleName { get; }
[Visual C++]
HRESULT RoleName(
[out, retval] BSTR *roleName
);
AccessLevel Property
Returns the access level of the Galaxy role.
Class
IGalaxyRole
Syntax
[C#]
int AccessLevel { get; }
[Visual C++]
HRESULT AccessLevel(
[out, retval] LONG *accessLevel
);
---
## Page 57
Interfaces <page_number>57</page_number>
# Permissions Property
Returns the general permissions of the Galaxy role.
**Class**
IGalaxyRole
**Syntax**
[C#]
```csharp
IPermissions Permissions { get; };
[Visual C++]
HRESULT Permissions(
[out, retval] IPermissions **generalPermissions
);
OperationalPermissions Property
Returns the operational permissions of the Galaxy role.
Class IGalaxyRole
Syntax
[C#]
IPermissions OperationalPermissions { get; };
[Visual C++]
HRESULT OperationalPermissions(
[out, retval] IPermissions **operationalPermissions
);
IGalaxyRoles
Returns information about the roles in the Galaxy.
IGalaxyRoles Class Members
This class has the following members.
Operations
Item Property Returns a Galaxy role.
Count Property Returns the number of roles in the collection.
GRAccess Toolkit API User's Guide
Page 58
<page_number>58</page_number> Chapter 2 API Reference
Item Property
Returns a Galaxy role.
Class
IGalaxyRoles
Syntax
[C#]
IGalaxyRole this[object galaxyIdentifier] { get; };
[Visual C++]
HRESULT Item(
[in] VARIANT galaxyIdentifier,
[out, retval] IGalaxyRole** galaxyRole
);
Parameters
galaxyIdentifier The index of a role. This is a numeric value from 1 to count, or the name of the role. galaxyRole The returned Galaxy role object.
Count Property
Returns the number of roles in the collection.
Class
IGalaxyRoles
Syntax
[C#]
int count { get; };
[Visual C++]
HRESULT Count (
[out, retval] LONG* count
);
Parameters
count Returns the number of roles in the collection.
GRAccess Toolkit API User's GuidePage 59
Interfaces <page_number>59</page_number>
IGalaxySecurity
Accesses top-level security information and Galaxy security objects, including security groups, roles, and users configured for the Galaxy.
IGalaxySecurity Class Members
This class has the following members.
Operations
AuthenticationMode Property Retrieves the authentication mode of the Galaxy.
SecurityGroupsAvailable Property Retrieves the available security groups of the Galaxy.
RolesAvailable Property Retrieves the collection of roles configured for this Galaxy.
UsersAvailable Property Retrieves the collection of users configured for this Galaxy.
LoginTime Property Retrieves the configured login time.
RoleUpdateInterval Property Retrieves role update interval time.
AuthenticationMode Property
Retrieves the authentication mode of the Galaxy.
Class
IGalaxySecurity
Syntax
[C#]
EAUTHMODE AuthenticationMode { get; };
[Visual C++]
HRESULT AuthenticationMode(
[out, retval] EAUTHMODE *authMode
);
Parameters
AuthenticationMode Indicates whether Galaxy security mode is none, Galaxy, OS User, or OS Group.
GRAccess Toolkit API User's GuidePage 60
<page_number>60</page_number> Chapter 2 API Reference
SecurityGroupsAvailable Property
Retrieves the available security groups of the Galaxy.
Class IGalaxySecurity
Syntax
[C#]
ISecurityGroups SecurityGroupsAvailable { get; };
[Visual C++]
HRESULT SecurityGroupsAvailable(
[out, retval] ISecurityGroups** securityGroups
);
Parameters
SecurityGroupsAvailable The collection of security groups configured for this Galaxy.
RolesAvailable Property
Retrieves the collection of roles configured for this Galaxy.
Class IGalaxySecurity
Syntax
[C#]
IGalaxyRoles RolesAvailable { get; };
[Visual C++]
HRESULT RolesAvailable(
[out, retval] IGalaxyRoles** roles
);
Parameters
roles The collection of roles configured for this Galaxy.
GRAccess Toolkit API User's Guide
Page 61
Interfaces <page_number>61</page_number>
UsersAvailable Property
Retrieves the collection of users configured for this Galaxy.
Class IGalaxySecurity
Syntax
[C#]
IGalaxyUsers UsersAvailable { get; };
[Visual C++]
HRESULT UsersAvailable(
[out, retval] IGalaxyUsers** users
);
Parameters
users The collection of users configured for this Galaxy.
LoginTime Property
Retrieves the configured login time.
Class IGalaxySecurity
Syntax
[C#]
string LoginTime { get; };
[Visual C++]
HRESULT LoginTime(
[out, retval] BSTR* loginTime
);
Parameters
LoginTime The timeout period during which the system validates the user's membership against the OS groups selected as ArchestrA roles. Minimum value is 0 (zero), maximum is 9,999,999. Default value is 0 (zero), which turns off this feature so the operation does not time out. Specify a value based on the speed of your network and the number of groups configured in ArchestrA roles. The slower the network or the larger the number of groups, the greater the value.
GRAccess Toolkit API User's Guide
Page 62
<page_number>62</page_number> Chapter 2 API Reference
RoleUpdateInterval Property
Retrieves role update interval time.
Class
IGalaxySecurity
Syntax
[C#]
string RoleUpdateInterval { get; };
[Visual C++]
HRESULT RoleUpdateInterval(
[out, retval] BSTR* roleUpdateInterval
);
Parameters
RoleUpdateInterval The time between each validation attempt per OS group for the user's membership when a logon is attempted. The user membership update is done one role per Role Update interval to minimize network usage. The minimum allowed value is 0 (zero) and the maximum is 9,999,999. The default value is 0 (zero), which turns off this feature so the operation does not pause between validating user membership and groups. This option operates independently of the Login Time option. Even if Login Time times out, the role update operation continues in the background and eventually updates user-to-role relationships for this user in the local cache.
IGalaxyUser
Provides user information: user name, full name, and associated role list.
If you are using OS group authentication mode, you can not configure Galaxy users. During login from client utilities, user information is updated in the Galaxy, which can then be obtained using the IGalaxyUser interface.
The FullName property is only valid when a user is an OS (domain or local) user.
GRAccess Toolkit API User's Guide
Page 63
Interfaces <page_number>63</page_number>
IGalaxyUser Class Members
This class has the following members.
Operations
UserName Property
Returns the user name along with the domain name in the form <domain_name>\<user_name>.
FullName Property
Returns the full name of the user retrieved from the domain controller in the form <first_name> <last_name>.
AssociatedRoles Property
Returns collection of roles associated with this user.
UserName Property
Returns the user name along with the domain name in the form <domain_name>\<user_name>.
Class
IGalaxyUser
Syntax
[C#]
string UserName { get; }
[Visual C++]
HRESULT UserName(
[out, retval] BSTR* *userName
);
FullName Property
Returns the full name of the user retrieved from the domain controller in the form <first_name> <last_name>.
Class
IGalaxyUser
Syntax
[C#]
string FullName { get; }
[Visual C++]
HRESULT FullName(
[out, retval] BSTR* *fullName
);
GRAccess Toolkit API User's Guide
Page 64
<page_number>64</page_number> Chapter 2 API Reference
AssociatedRoles Property
Returns collection of roles associated with this user.
Class
IGalaxyUser
Syntax
[C#]
IGalaxyRoles AssociatedRoles { get; };
[Visual C++]
HRESULT AssociatedRoles(
[out, retval] IGalaxyRoles **associatedRoles
);
IGalaxyUsers
Represents a collection of Galaxy users.
IGalaxyUsers Class Members
This class has the following members.
Operations
Item Property Returns a Galaxy user.
Count Property Returns the number of roles in the collection.
Item Property
Returns a Galaxy user.
Class
IGalaxyUsers
Syntax
[C#]
IGalaxyUser this[object galaxyIdentifier] { get; };
[Visual C++]
HRESULT Item(
[in] VARIANT galaxyIdentifier,
[out, retval] IGalaxyUser** galaxyUser
);
GRAccess Toolkit API User's Guide
Page 65
Interfaces <page_number>65</page_number>
Parameters
galaxyIdentifier The index of a user. This is a numeric value from 1 to count, or the name of the user.
galaxyUser The returned Galaxy user.
Count Property
Returns the number of users in the collection.
Class
IGalaxyUsers
Syntax
[C#]
int count { get; };
[Visual C++]
HRESULT Count (
[out, retval] LONG* UserCount
);
Parameters
UserCount Returns the number of users in the collection.
IgObject
Represents a gObject that could be either a template or an instance.
IgObject Class Members
This class has the following members.
Operations
Tagname Property Returns or sets the tagname of this object.
ContainedName Property Returns or sets the contained name of this object (for instance, Inlet).
HierarchicalName Property Returns the hierarchical name of this object (e.g. Reactor.Tank.Inlet).
Attributes Property The collection of attributes of this object.
GRAccess Toolkit API User's Guide
Page 66
<page_number>66</page_number> Chapter 2 API Reference
ConfigurableAttributes Property The collection of attributes of this object that can be configured.
ValidationStatus Property The validation status of this object based on the last time the object was validated and saved.
Errors Property The list of errors that was generated the last time the object was validated and saved.
Warnings Property The list of warnings that was generated the last time the object was validated and saved.
CheckedOutBy Property The name of the user that this object is checked out by.
CheckoutStatus Property The check-out status of the object.
ConfigVersion Property The configuration version of the object.
Category Property The category of the object.
DerivedFrom Property Returns the name of the template that this object was created from.
BasedOn Property The name of the base template (root ancestor) of this object.
Container Property Returns or sets the name of the container object, or blank if object is not contained.
Area Property Returns or sets name of the area object, or blank if the object does not have an area.
Host Property Returns or sets the name of the host for this object, or blank if unassigned.
GetObjectHelpURL Method Returns the URL where the object’s help is stored in the Galaxy Repository.
Save Method Saves the object after it is configured.
CheckIn Method Checks in an object.
CheckOut Method Checks out an object.
GRAccess Toolkit API User’s GuidePage 67
Interfaces <page_number>67</page_number>
UndoCheckOut Method Undoes check-out of this object.
Unload Method Unloads the gObject cache.
EditStatus Property The edit status of the object.
AddExtensionPrimitive Method Add an extension primitive.
DeleteExtensionPrimitive Method Delete an extension primitive.
RenameExtensionPrimitive Method Rename an object extension primitive.
AddUDA Method Add a UDA.
DeleteUDA Method Delete a UDA by its name.
RenameUDA Method Renames a UDA.
UpdateUDA Method Update a UDA.
CommandResult Property Returns the CommandResult object, which has the last method call's result.
CategoryGUID Property Returns the Category GUID of the object.
GetExtendedAttributes Method Returns the Extended Attributes in the hierarchy.
Tagname Property Returns or sets the tagname of this object.
Class IgObject
Syntax [C#]
string Tagname { set; get; }
GRAccess Toolkit API User's Guide
Page 68
<page_number>68</page_number> Chapter 2 API Reference
[Visual C++]
[propget]
HRESULT Tagname ( [out, retval] BSTR* theTagname );
[propput]
HRESULT Tagname ( [in] BSTR newTagName );
Parameters
theTagname The current tagname of this object.
newTagName The new tagname of this object. The object does not need to be checked out. The operation is immediate.
ContainedName Property
Returns or sets the contained name of this object (for instance, Inlet).
Class
IgObject
Syntax
[C#]
string ContainedName { set; get; };
[Visual C++]
[propget]
HRESULT ContainedName ( [out, retval] BSTR* theContainedName );
[propput]
HRESULT ContainedName ( [in] BSTR newContainedName );
Parameters
theContainedName The current contained name of this object.
newContainedName The new contained name of this object.
GRAccess Toolkit API User's Guide
Page 69
Interfaces <page_number>69</page_number>
HierarchicalName Property
The hierarchical name of this object (for instance, Reactor.Tank.Inlet).
Class
IgObject
Syntax
[C#]
string HierarchicalName { get; };
[Visual C++]
HRESULT HierarchicalName(
[out, retval] BSTR* theHierarchicalName
);
Parameters
theHierarchicalName
The current hierarchical name of this object.
Attributes Property
The collection of attributes of this object.
Class
IgObject
Syntax
[C#]
IAttributes Attributes { get; };
[Visual C++]
HRESULT Attributes(
[out, retval] IAttributes** theAttributes
);
Parameters
theAttributes
The collection of attributes of this object.
GRAccess Toolkit API User's Guide
Page 70
<page_number>70</page_number> Chapter 2 API Reference
ConfigurableAttributes Property
The collection of this object's attributes that can be configured. Configuring attributes requires that the object be checked out.
Class
IgObject
Syntax
[C#]
IAttributes ConfigurableAttributes { get; };
[Visual C++]
HRESULT ConfigurableAttributes(
[out, retval] IAttributes** theConfigurableAttributes
);
Parameters
theConfigurableAttributes The collection of attributes that can be configured.
ValidationStatus Property
The validation status of this object based on the last time the object was validated and saved.
Class
IgObject
Syntax
[C#]
EPACKAGESTATUS ValidationStatus { get; };
[Visual C++]
HRESULT ValidationStatus(
[out, retval] EPACKAGESTATUS* theValidationStatus
);
Parameters
theValidationStatus The validation status of the object.
GRAccess Toolkit API User's Guide
Page 71
Interfaces <page_number>71</page_number>
Errors Property
The list of errors generated the last time the object was validated and saved.
Class
IgObject
Syntax
[C#]
string[] Errors { get; };
[Visual C++]
HRESULT Errors(
[out, retval] SAFEARRAY(BSTR) * theErrors
);
Parameters
theErrors The list of errors.
Warnings Property
The list of warnings generated the last time the object was validated and saved.
Class
IgObject
Syntax
[C#]
string[] Warnings { get; };
[Visual C++]
HRESULT Warnings(
[out, retval] SAFEARRAY(BSTR) * theWarnings
);
Parameters
theWarnings The list of warnings.
GRAccess Toolkit API User's Guide
Page 72
<page_number>72</page_number> Chapter 2 API Reference
CheckedOutBy Property
The name of the user that this object is checked out by.
Class
IgObject
Syntax
[C#]
string checkedOutBy { get; };
[Visual C++]
HRESULT CheckedOutBy(
[out, retval] BSTR* CheckedOutByUserName
);
Parameters
CheckedOutByUserName The user's name.
CheckoutStatus Property
The check-out status of the object.
Class
IgObject
Syntax
[C#]
ECheckoutStatus CheckoutStatus { get; };
[Visual C++]
HRESULT CheckoutStatus (
[out, retval] ECheckoutStatus* theCheckoutStatus
);
Parameters
theCheckoutStatus The check-out status.
GRAccess Toolkit API User's Guide
Page 73
Interfaces <page_number>73</page_number>
ConfigVersion Property
The configuration version of the object.
Class IgObject
Syntax
[C#]
int ConfigVersion { get; };
[Visual C++]
HRESULT ConfigVersion(
[out, retval] LONG* theConfigVersion
);
Parameters
theConfigVersion The configuration version.
Category Property
The category of the object.
Class IgObject
Syntax
[C#]
ECATEGORY category { get; };
[Visual C++]
HRESULT Category(
[out, retval] ECATEGORY* theCategory
);
Parameters
theCategory The category.
GRAccess Toolkit API User's Guide
Page 74
<page_number>74</page_number> Chapter 2 API Reference
DerivedFrom Property
Returns the name of the template that this object was created from.
Class
IgObject
Syntax
[C#]
string DerivedFrom { get; };
[Visual C++]
HRESULT DerivedFrom(
[out, retval] BSTR* theParentTemplate
);
Parameters
theParentTemplate The name of the object's parent template.
BasedOn Property
The name of the base template (root ancestor) of this object.
Class
IgObject
Syntax
[C#]
string basedOn { get; };
[Visual C++]
HRESULT BasedOn(
[out, retval] BSTR* theBaseTemplate
);
Parameters
theBaseTemplate The name of the object's base template.
GRAccess Toolkit API User's Guide
Page 75
Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Page 76
<page_number>76</page_number> Chapter 2 API Reference
[Visual C++]
[propget]
HRESULT Area ( [out, retval] BSTR* theArea );
[propput]
HRESULT Area ( [in] BSTR NewArea );
Parameters
theArea The name of the current Area object, or blank if the object doesn't have an area.
NewArea The new name of the area, or blank to unassign the object from its existing area.
Host Property
Returns or sets the name of the host for this object, or blank if unassigned.
Class
IgObject
Syntax
[C#]
string Host { set; get; }
[Visual C++]
[propget]
HRESULT Host (
[out, retval] BSTR* theHost
);
[propput]
HRESULT Host (
[in] BSTR NewHost
);
Page 77
Interfaces <page_number>77</page_number>
Parameters
theHost The current name of the host for this object.
NewHost The new name of the host, or blank to unassign the object from its existing host.
GetObjectHelpURL Method
Returns the URL where the object's help is stored on the Galaxy Repository. The client can display the URL in Internet Explorer or use web publishing to change the data.
Class
IgObject
Syntax
[C#]
string GetObjectHelpURL( );
[Visual C++]
HRESULT GetObjectHelpURL(
[out, retval] BSTR*
);
Save Method
Saves the object after it is configured. Object must be checked out.
Class
IgObject
Syntax
[C#]
void Save( );
[Visual C++]
HRESULT Save( );
---
## Page 78
<page_number>78</page_number> Chapter 2 API Reference
# CheckIn Method
Checks in an object. Called on a checked-out object after it is configured and saved.
## Class
IgObject
## Syntax
[C#]
```csharp
void CheckIn(
string CheckInComment
);
[Visual C++]
HRESULT CheckIn(
[in, optional] BSTR CheckInComment
);
Parameters
CheckInComment Check in an object.
CheckOut Method
Checks out an object.
Class
IgObject
Syntax
[C#]
void CheckOut( );
[Visual C++]
HRESULT CheckOut( );
---
## Page 79
Interfaces <page_number>79</page_number>
# UndoCheckOut Method
Undoes check-out of this object.
**Class**
IgObject
**Syntax**
[C#]
```csharp
void UndoCheckOut();
[Visual C++]
HRESULT UndoCheckOut();
Unload Method
Unloads the gObject cache. This method does not affect functionality. It is used to release internal resources obtained by the object during operations. Unload() can be called to free those resources. After this method is called, the object is still usable and will reload the internal resources as needed.
Class
IgObject
Syntax
[C#]
void Unload();
[Visual C++]
HRESULT Unload();
EditStatus Property
The edit status of the object.
Class
IgObject
Syntax
[C#]
EEditStatus EditStatus { get; };
[Visual C++]
HRESULT EditStatus(
[out, retval] EEditStatus* theEditStatus
);
---
## Page 80
<page_number>80</page_number> Chapter 2 API Reference
# Parameters
theEditStatus
The edit status of the object.
# AddExtensionPrimitive Method
Adds an extension primitive.
## Class
IgObject
## Syntax
[C#]
```csharp
void AddExtensionPrimitive(
string ExtensionType,
string ExtensionPrimitiveName,
bool IsObjectExtension
);
[Visual C++]
HRESULT AddExtensionPrimitive(
[in] BSTR ExtensionType,
[in] BSTR ExtensionPrimitiveName,
[in, optional, defaultvalue( -1 )] VARIANT_BOOL IsObjectExtension
);
Parameters
ExtensionType Type of extension.
ExtensionPrimitiveName Name of extension primitive to be added. For an attribute extension primitive, this parameter is the fully qualified name of the attribute being extended. For an object extension primitive, it is the new name specified by user for object extension primitive.
IsObjectExtension If ExtensionPrimitiveName is the new name specified by the user, this field is set to true (for example, when add script pass is true).
GRAccess Toolkit API User's Guide
Page 81
Interfaces <page_number>81</page_number>
DeleteExtensionPrimitive Method
Deletes an extension primitive.
Class
IgObject
Syntax
[C#]
void DeleteExtensionPrimitive(
string ExtensionType,
string ExtensionPrimitiveName
);
[Visual C++]
HRESULT DeleteExtensionPrimitive(
[in] BSTR ExtensionType,
[in] BSTR ExtensionPrimitiveName
);
Parameters
- ExtensionType Type of extension.
- ExtensionPrimitiveName Name of extension primitive to be deleted.
RenameExtensionPrimitive Method
Renames an object extension primitive.
Class
IgObject
Syntax
[C#]
void RenameExtensionPrimitive(
string OldPrimitiveName,
string NewPrimitiveName
);
[Visual C++]
HRESULT RenameExtensionPrimitive(
[in] BSTR OldPrimitiveName,
[in] BSTR NewPrimitiveName
);
GRAccess Toolkit API User's Guide
Page 82
<page_number>82</page_number> Chapter 2 API Reference
Parameters
- OldPrimitiveName Old name of primitive extension.
- NewPrimitiveName New name specified by user.
AddUDA Method
Adds a UDA.
Class
IgObject
Syntax
[C#]
void AddUDA(
string UDAName,
MxDataType DataType,
MxAttributeCategory category,
MxSecurityClassification Security,
bool IsArray,
object ArrayElementCount
);
[Visual C++]
HRESULT AddUDA
(
[in] BSTR UDAName,
[in, optional, defaultvalue( MxBoolean )] MxDataType Datatype,
[in, optional, defaultvalue( MxCategroyWriteable_UC_Lockable )] MxAttributeCategory Category,
[in, optional, defaultvalue( MxSecurityOperate )] MxSecurityClassification Security,
[in, optional, defaultvalue( 0 )] VARIANT_BOOL IsArray,
[in, optional] VARIANT ArrayElementCount
);
Parameters
- UDAName The new UDA's name.
- Datatype The new UDA's datatype.
- Category The new UDA's category.
GRAccess Toolkit API User's Guide
Page 83
Interfaces <page_number>83</page_number>
Security The new UDA's security classification.
IsArray The new UDA is an array.
ArrayElementCount The new UDA's array element count.
DeleteUDA Method
Deletes a UDA by its name.
Class IgObject
Syntax
[C#]
void DeleteUDA(
string UDAName
);
[Visual C++]
HRESULT DeleteUDA(
[in] BSTR UDAName
);
Parameters
UDAName Delete a UDA by its name.
RenameUDA Method
Renames a UDA.
Class IgObject
Syntax
[C#]
void RenameUDA(
string OldUDAName,
string NewUDAName
);
GRAccess Toolkit API User's Guide
Page 84
<page_number>84</page_number> Chapter 2 API Reference
[Visual C++]
HRESULT RenameUDA(
[in] BSTR OldUDAName,
[in] BSTR NewUDAName
);
Parameters
- OldUDAName The old external name of the primitive to be renamed.
- NewUDAName The new external name of the primitive.
UpdateUDA Method
Updates a UDA. The new data overwrites the old data.
Class
IgObject
Syntax
[C#]
void UpdateUDA(
string wszUDAInfo,
MxDataType DataType,
MxAttributeCategory category,
MxSecurityClassification Security,
bool IsArray,
object ArrayElementCount
);
[Visual C++]
HRESULT UpdateUDA
(
[in] BSTR wszUDAInfo,
[in, optional, defaultvalue( MxBoolean )] MxDataType Datatype,
[in, optional, defaultvalue( MxCategotyWriteable_UC_Lockable )] MxAttributeCategory Category,
[in, optional, defaultvalue( MxSecurityOperate )] MxSecurityClassification Security,
[in, optional, defaultvalue( 0 )] VARIANT_BOOL IsArray,
[in, optional] VARIANT ArrayElementCount
);
GRAccess Toolkit API User's Guide
Page 85
Interfaces <page_number>85</page_number>
Parameters
- wszUDAInfo The updated UDA data.
- Datatype The updated UDA's datatype.
- Category The updated UDA's category.
- Security The updated UDA's security classification.
- IsArray The updated UDA is an array.
- ArrayElementCount The updated UDA's array element count.
CommandResult Property
Returns the CommandResult object, which has the last method call's result.
Class
IgObject
Syntax
[C#]
ICommandResult CommandResult { get; };
[Visual C++]
HRESULT CommandResult(
[out, retval] ICommandResult** CommandResult
);
Parameters
- CommandResult Returns the CommandResult object.
Page 86
<page_number>86</page_number> Chapter 2 API Reference
CategoryGUID Property
Returns the Category GUID of the object.
Class
IgObject
Syntax
[C#] VBGUID CategoryGUID { get; };
[Visual C++] HRESULT CategoryGUID ( // The Category GUID of the object. [out, retval] VBGUID *categoryGUID );
GetExtendedAttributes Method
Returns the extended attributes in the hierarchy.
Class
IgObject
Syntax
[C#] IAttributes GetExtendedAttributes ( string AttributeName, int upto_level, MxAttributeCategory[] ReturnOnlyTheseCategories ); [Visual C++] HRESULT GetExtendedAttributes ( [in] BSTR AttributeName, [in] int upto_level, [in] SAFEARRAY(MxAttributeCategory) ReturnOnlyTheseCategories, [out, retval] IAttributes** theAttributes );
Page 87
Interfaces <page_number>87</page_number>
Parameters
- AttributeName Attribute full name which is extended
- upto_level Up to how many level user needs extended primitives -1 will return all levels
- ReturnOnlyTheseCategories Return attributes which are only in these categories. If safe array is empty, method will return all attributes.
- theAttributes Returns the attributes
IgObjects
Represents a collection of gObject objects.
IgObjects Class Members
This class has the following members.
Operations
- CommandResults Property Returns the CommandResults Object, which has the last method call's result.
- Area Property Sets the area for the given set of gObjects.
- Host Property Sets the host for the given set of gObjects.
- AddFromCollection Method Adds objects to the list from another list.
- Upload Method Uploads AutomationObject configuration changes made in the runtime.
- CheckIn Method Checks in the gObjects in the collection.
- Add Method Adds an object to the list.
- Container Property Sets the container for the given set of gObjects.
- ExportObjects Method Exports object from the Galaxy.
- ExportObjectsAsProtected Method Exports objects from the Galaxy as protected.
GRAccess Toolkit API User's Guide
Page 88
<page_number>88</page_number> Chapter 2 API Reference
DeleteAllObjects Method Deletes all objects in the collection.
CheckOut Method Checks out the gObjects in the collection.
SecurityGroup Property Sets the security group for the given set of gObjects.
Undeploy Method Undeploys the instances in the given collection of objects.
Deploy Method Deploys the instances in the given collection of objects.
Item Property Returns the gObject object by index.
Count Property Returns the number of gObjects in the collection.
UndoCheckOut Method Undoes check-out on the gObjects in the collection.
DeployEx Method Deploy the instances in the given collection of objects.
UndeployEx Method Undeploy the instances in the given collection of objects.
UploadEx Method Uploads AutomationObject configuration changes made in the runtime.
CommandResults Property Returns the CommandResults object, which has the last method call's result.
Class IgObjects
Syntax
[C#]
ICommandResults CommandResults { get; };
[Visual C++]
HRESULT CommandResults(
[out, retval] ICommandResults** CommandResults
);
Parameters
- CommandResults Returns the CommandResult object.
GAccess Toolkit API User's Guide
Page 89
Interfaces <page_number>89</page_number>
Area Property
Set the area for the given set of gObjects.
Class
IgObjects
Syntax
[C#]
string Area { set; };
[Visual C++]
HRESULT Area(
[in] BSTR NewArea
);
Parameters
NewArea
The name of the Area object, or blank or unspecified to unassign from existing area.
Remarks
The area of an AppObject gObject cannot be set directly. Set the container or host. The gObjects do not need to be checked out; the operation is immediate.
Host Property
Set the host for the given set of gObjects.
Class
IgObjects
Syntax
[C#]
string Host { set; };
[Visual C++]
HRESULT Host (
[in] BSTR NewHost
);
GRAccess Toolkit API User's Guide
Page 90
<page_number>90</page_number> Chapter 2 API Reference
Parameters
NewHost The name of the host object, or blank or unspecified to unassign from existing area.
Remarks
If the gObject is an ApplicationObject, its area and container are also updated. The gObjects do not need to be checked out; the operation is immediate.
AddFromCollection Method
Add objects to the list from another list.
Class
IgObjects
Syntax
[C#]
void AddFromCollection(
IgObjects gObjects
);
[Visual C++]
HRESULT AddFromCollection(
[in] IgObjects* gObjects
);
Parameters
gObjects Collection representing templates or instances.
Upload Method
Uploads AutomationObject configuration changes made at run time.
Class
IgObjects
Syntax
[C#]
void Upload(
EAutomaticallyUndocheckout automaticallyUndocheckout,
ESkipOtherUsersCheckedOutObjects skipOtherUsersCheckedOutObjects,
ESkipObjectsWithPendingUpdates skipObjectsWithPendingUpdates
);
GRAccess Toolkit API User's Guide
Page 91
Interfaces <page_number>91</page_number>
[Visual C++]
HRESULT Upload(
[in, optional, defaultvalue( doAutomaticallyUndocheckout )]
EAutomaticallyUndocheckout automaticallyUndocheckout,
[in, optional, defaultvalue( doSkipOtherUsersCheckedOutObjects )]
ESkipOtherUsersCheckedOutObjects skipOtherUsersCheckedOutObjects,
[in, optional, defaultvalue( doSkipObjectsWithPendingUpdates )]
ESkipObjectsWithPendingUpdates skipObjectsWithPendingUpdates
);
Parameters
- automaticallyUndocheckout Automatically undo check out.
- skipOtherUsersCheckedOutObjects Skip objects other users' have checked out.
- skipObjectsWithPendingUpdates Skip objects with pending updates.
CheckIn Method
Checks in the gObjects in the collection.
Class
IgObjects
Syntax
[C#]
void CheckIn(
string CheckInComment
);
[Visual C++]
HRESULT CheckIn(
[in, optional] BSTR CheckInComment
);
Parameters
- CheckInComment The check-in comment.
GRAccess Toolkit API User's Guide
Page 92
<page_number>92</page_number> Chapter 2 API Reference
Add Method
Add an object to the list.
Class
IgObjects
Syntax
[C#]
void Add(
IgObject gObject
);
[Visual C++]
HRESULT Add(
[in] IgObject* gObject
);
Parameters
gObject
A gObject to be added to the list.
Container Property
Set the container for the given set of gObjects.
Class
IgObjects
Syntax
[C#]
string Container { set; };
[Visual C++]
HRESULT Container(
[in] BSTR NewContainer
);
Parameters
NewContainer
The name of the container, or blank to uncontain.
Remarks
If the gObject is an ApplicationObject, its area and host are also updated. The gObjects do not need to be checked out; the operation is immediate.
GRAccess Toolkit API User's Guide
Page 93
Interfaces <page_number>93</page_number>
ExportObjects Method
Exports an object from the Galaxy.
Class IgObjects
Syntax
[C#]
void ExportObjects(
EExportType exportType, string outputFile
);
[Visual C++]
HRESULT ExportObjects(
[in] EExportType exportType,
[in] BSTR outputFile
);
Parameters
- exportType Indicates whether to export to aaPKG file.
- outputFile The name of the output file. Appends extension if one is not specified.
ExportObjectsAsProtected Method
Exports object templates and symbols from the Galaxy as protected.
Class IgObjects
Syntax
[C#]
void ExportObjectsAsProtected(
string outputFile
);
[Visual C++]
HRESULT ExportObjectsAsProtected(
[in] BSTR outputFile
);
GRAccess Toolkit API User's Guide
Page 94
<page_number>94</page_number> Chapter 2 API Reference
Parameters
outputFile The name of the output file. Appends extension if one is not specified.
Remarks
There is no exportType parameter as only objects and templates, not instances, can be exported as protected. The default exportType is "exportAsPDF".
DeleteAllObjects Method
Delete all objects in the collection.
Class
IgObjects
Syntax
[C#]
void DeleteAllObjects();
[Visual C++]
HRESULT DeleteAllObjects();
CheckOut Method
Checks out the gObjects in the collection.
Class
IgObjects
Syntax
[C#]
void CheckOut();
[Visual C++]
HRESULT CheckOut();
SecurityGroup Property
Set the security group for the given set of gObjects.
Class
IgObjects
GRAccess Toolkit API User's Guide
Page 95
Interfaces <page_number>95</page_number>
Syntax
[C#]
string SecurityGroup { set; };
[Visual C++]
HRESULT SecurityGroup(
[in] BSTR rhs
);
Parameters
rhs
The name of the security group.
Undeploy Method
Undeploy the instances in the given collection of objects.
Class
IgObjects
Syntax
[C#]
void Undeploy(
EForceOffScan UndeployRule,
bool markAsUndeployedOnFailure
);
[Visual C++]
HRESULT Undeploy(
[in, optional, defaultvalue( dontForceOffScan )] EForceOffScan UndeployRule,
[in, optional, defaultvalue( 0 )] VARIANT_BOOL markAsUndeployedOnFailure
);
Parameters
UndeployRule
Indicates whether to force an object off-scan if it is running on-scan prior to undeployment.
markAsUndeployedOnFailure
On failure, set deploy status as undeployed.
Deploy Method
Deploy the instances in the given collection of objects.
GRAccess Toolkit API User's Guide
Page 96
<page_number>96</page_number> Chapter 2 API Reference
Class
IgObjects
Syntax
[C#]
void Deploy(
EActionForCurrentlyDeployedObjects actionForDeployedObjects,
ESkipIfCurrentlyUndeployed skipIfCurrentlyUndeployed,
EDeployOnScan deployOnScan,
EForceOffScan forceOffScan,
bool markAsDeployedOnStatusMismatch
);
[Visual C++]
HRESULT Deploy
(
[in, optional, defaultvalue( skipDeploy )]
EActionForCurrentlyDeployedObjects actionForDeployedObjects,
[in, optional, defaultvalue( dontSkipIfCurrentlyUndeployed )]
ESkipIfCurrentlyUndeployed skipIfCurrentlyUndeployed,
[in, optional, defaultvalue( doDeployOnScan )] EDeployOnScan deployOnScan,
[in, optional, defaultvalue( doForceOffScan )] EForceOffScan forceOffScan,
[in, optional, defaultvalue( 1 )] VARIANT_BOOL markAsDeployedOnStatusMismatch
);
Parameters
- actionForDeployedObjects Action for currently deployed objects.
- skipIfCurrentlyUndeployed Action for currently undeployed objects.
- deployOnScan Deploy on scan.
- forceOffScan Force off scan.
- markAsDeployedOnStatusMismatch Deploy status mismatch.
Item Property
Returns the gObject object by Index.
Class
IgObjects
GRAccess Toolkit API User's Guide
Page 97
Interfaces <page_number>97</page_number>
Syntax
[C#]
IgObject this[gObjectIdentifier] { get; }
[Visual C++]
HRESULT Item(
[in] VARIANT gObjectIdentifier,
[out, retval] IgObject**
);
Parameters
gObjectIdentifier
The index of the gObject. This is a numeric value from 1 to count. Or it is the name of the gObject.
IgObject
The returned gObject object.
GRAccess Toolkit API User's GuidePage 98
<page_number>98</page_number> Chapter 2 API Reference
Count Property
Returns the number of gObjects in the collection.
Class
IgObjects
Syntax
[C#]
int count { get; };
[Visual C++]
HRESULT Count(
[out, retval] LONG*
);
UndoCheckOut Method
Undo check-out on the gObjects in the collection.
Class
IgObjects
Syntax
[C#]
void UndoCheckOut();
[Visual C++]
HRESULT UndoCheckOut();
DeployEx Method
Deploy the instances in the given collection of objects.
Class
IgObjects
Syntax
[C#]
void DeployEx(
EActionForCurrentlyDeployedObjects actionForDeployedObjects,
ESkipIfCurrentlyUndeployed skipIfCurrentlyUndeployed,
EDeployOnScan deployOnScan,
EForceOffScan forceOffScan,
bool markAsDeployedOnStatusMismatch,
string strCustomData
);
GRAccess Toolkit API User's Guide
Page 99
Interfaces <page_number>99</page_number>
[Visual C++]
HRESULT DeployEx
(
// Action for currently deployed objects
[in, optional, defaultvalue( skipDeploy )] EActionForCurrentlyDeployedObjects actionForDeployedObjects,
// Action for currently undeployed objects
[in, optional, defaultvalue( dontSkipIfCurrentlyUndeployed )] ESkipIfCurrentlyUndeployed skipIfCurrentlyUndeployed,
// Deploy on scan
[in, optional, defaultvalue( doDeployOnScan )] EDeployOnScan deployOnScan,
// Force off scan
[in, optional, defaultvalue( doForceOffScan )] EForceOffScan forceOffScan,
// Deploy status mismatch
[in, optional, defaultvalue( 1 )] VARIANT_BOOL markAsDeployedOnStatusMismatch,
// Data used by custom category package
[in, optional, defaultvalue( "" )] BSTR strCustomData
);
UndeployEx Method
Undeploy the instances in the given collection of objects.
Class
IgObjects
Syntax
[C#]
void UndeployEx (
EForceOffScan UndeployRule,
bool markAsUndeployedOnFailure,
string strCustomData
);
[Visual C++]
HRESULT UndeployEx(
// Indicates whether to force an object off-scan //if it's running on-scan prior to undeployment.
[in, optional, defaultvalue( dontForceOffScan )] EForceOffScan UndeployRule,
---
## Page 100
<page_number>100</page_number> Chapter 2 API Reference
```csharp
// On Failure, set deploy status as undeployed
[in, optional, defaultvalue( 0 )] VARIANT_BOOL markAsUndeployedOnFailure,
// Data used by custom category package
[in, optional, defaultvalue("") ] BSTR strCustomData
);
UploadEx Method
Uploads AutomationObject configuration changes made at run time.
Class
IgObjects
Syntax
[C#]
void UploadEx(
EAutomaticallyUndocheckout automaticallyUndocheckout,
ESkipOtherUsersCheckedOutObjects skipOtherUsersCheckedOutObjects,
ESkipObjectsWithPendingUpdates skipObjectsWithPendingUpdates,
string strCustomData
);
[Visual C++]
HRESULT UploadEx(
// Automatically Undocheckout
[in, optional, defaultvalue( doAutomaticallyUndocheckout )] EAutomaticallyUndocheckout automaticallyUndocheckout,
// Skip other users CheckedOuts
[in, optional, defaultvalue( doSkipOtherUsersCheckedOutObjects )] ESkipOtherUsersCheckedOutObjects skipOtherUsersCheckedOutObjects,
// Skip objects with pending updates
[in, optional, defaultvalue( doSkipObjectsWithPendingUpdates )] ESkipObjectsWithPendingUpdates skipObjectsWithPendingUpdates,
// Data used by custom category package
[in, optional, defaultvalue("") ] BSTR strCustomData
);
GAccess Toolkit API User's Guide
Page 101
Interfaces <page_number>101</page_number>
IGRAccess
Main interface implemented by GRAccess used by clients to gain access to Galaxy Repository.
IGRAccess Class Members
This class has the following members.
Operations
CommandResult Property Returns the CommandResult Object, which has the last method call's result.
CreateGalaxy Method Create a new Galaxy on the GR node.
DeleteGalaxy Method Delete a Galaxy.
QueryGalaxies Method Query available Galaxies on a given GR node.
CreateGalaxyFromTemplate Method Creates a new Galaxy from the template.
CommandResult Property
Returns the CommandResult object, which has the last method call's result.
Class
IGRAccess
Syntax
[C#]
ICommandResult CommandResult { get; }
[Visual C++]
HRESULT CommandResult(
[out, retval] ICommandResult** CommandResult
);
Parameters
CommandResult Returns the CommandResult object.
GRAccess Toolkit API User's GuidePage 102
<page_number>102</page_number> Chapter 2 API Reference
CreateGalaxy Method
Create a new Galaxy on the GR node.
Class
IGRAccess
Syntax
[C#]
void CreateGalaxy(
string galaxyName,
string GRNodeName,
bool enableSecurity,
EAuthenticationMode AuthenticationMode,
string osUserName
);
[Visual C++]
HRESULT CreateGalaxy(
[in] BSTR galaxyName,
[in, optional] BSTR grNodeName,
[in, optional, defaultvalue( -1 )] VARIANT_BOOL enableSecurity,
[in, optional, defaultvalue ( osAuthenticationMode )] EAuthenticationMode authenticationMode,
[in, optional] BSTR osUserName
);
Parameters
galaxyName The name to give the new Galaxy.
grNodeName The name of the GR node (computer name). Blank or omitted means the current computer is the Galaxy repository.
enableSecurity Indicates whether security should be enabled.(valid only for Galaxy authentication).
authenticationMode Indicates whether OS or Galaxy authentication should be used.
osUserName The name of the OS user if osAuthenticationMode is specified. Ignored otherwise. If not specified in OS authentication mode, the user currently logged in to the OS is used.
GRAccess Toolkit API User's GuidePage 103
Interfaces <page_number>103</page_number>
DeleteGalaxy Method
Delete a Galaxy.
Class IGRAccess
Syntax
[C#]
void DeleteGalaxy(
string galaxyName,
string grNodeName
);
[Visual C++]
HRESULT DeleteGalaxy (
[in] BSTR galaxyName,
[in, optional] BSTR grNodeName
);
Parameters
- galaxyName The name of the Galaxy to be deleted.
- grNodeName The name of the GR node (computer name). Blank or omitted means the current computer is the Galaxy Repository.
QueryGalaxies Method
Query available Galaxies on a given GR node.
Class IGRAccess
Syntax
[C#]
IGalaxies QueryGalaxies (
string grNodeName
);
[Visual C++]
HRESULT QueryGalaxies (
[in, optional] BSTR grNodeName,
[out, retval] IGalaxies** galaxies
);
GRAccess Toolkit API User's Guide
Page 104
<page_number>104</page_number> Chapter 2 API Reference
Parameters
- grNodeName The name of the GR node (computer name). Blank or omitted means the current computer is the Galaxy Repository.
- galaxies The list of galaxies.
CreateGalaxyFromTemplate Method
Creates a new Galaxy from the template.
Class
IGRAccess
Syntax
[C#]
void CreateGalaxyFromTemplate(
string createGalaxyTemplateName,
string galaxyName,
string grNodeName
);
[Visual C++]
HRESULT CreateGalaxyFromTemplate(
[in] BSTR CreateGalaxyTemplateName,
[in] BSTR galaxyName,
[in, optional] BSTR grNodeName,
[out, retval] IGalaxies** galaxies
);
Parameters
- createGalaxyTemplateName The template name to create the Galaxy.
- galaxyName The name to give the new Galaxy.
- grNodeName The name of the GR node (computer name). Blank or omitted means the current computer is the Galaxy Repository.
IInstance
Represents an instance object.
IInstance Class Members
This class has the following members.
GRAccess Toolkit API User's Guide
Page 105
Interfaces <page_number>105</page_number>
Operations
AddExtensionPrimitive Method Add an extension primitive.
AddUDA Method Add a UDA.
Area Property Get or set the area of an object.
Attributes Property Gets the collection of attributes for this object.
BasedOn Property Returns the name of the base template for this object.
Category Property Returns the category of this object.
CategoryGUID Property Returns the category GUID for this object.
CheckedOutBy Property Returns the name of the user who has checked out this object.
CheckIn Method Checks in an object.
CheckOut Method Checks out an object.
CheckoutStatus Property Returns the check out status of the object.
CommandResult Property Returns the CommandResult object, which has the results from the object's last method call.
ConfigurableAttributes Property Returns a collection of this object's attributes that can be modified.
ConfigVersion Property Returns the this object's configuration version number.
ContainedName Property Sets or returns the object's contained name.
Container Property Sets or returns the object's container.
DeleteExtensionPrimitive Method Delete an extension primitive.
DeleteInstance Method Delete this instance.
DeleteUDA Method Delete a UDA.
Deploy Method Deploy this instance.
GRAccess Toolkit API User's GuidePage 106
<page_number>106</page_number> Chapter 2 API Reference
DeployedVersion Property The configuration version of this instance at the time it was last deployed.
DeployEx Method Deploy this instance.
DeploymentStatus Property Indicates whether the instance is currently deployed and if so, if it has pending changes.
DerivedFrom Property Returns the name of the object’s template.
EditStatus Property Edit the status of this object.
Errors Property Retrieves the list of errors generated when the object was last validated and saved.
GetExtendedAttributes Method Get the extended attributes in the hierarchy.
GetObjectHelpURL Method Returns the URL to where the object help is stored on the Galaxy repository.
HierarchicalName Property Returns the hierarchical name of this object.
Host Property Returns the name of this object’s host.
RenameExtensionPrimitive Method Rename the object extension primitive.
RenameUDA Method Change the name of the UDA.
Save Method Save the object.
Tagname Property Returns or sets the object’s tagname.
Undeploy Method Undeploy this instance.
UndeployEx Method Undeploy this instance.
UndoCheckOut Method Reverse the check out operation without saving changes.
Unload Method Unload the object cache.
UpdateUDA Method Save the UDA information.
GRAccess Toolkit API User’s GuidePage 107
Interfaces <page_number>107</page_number>
Upload Method Uploads AutomationObject configuration changes made in the runtime.
UploadEx Method Uploads the AutomationObject configuration changes.
ValidationStatus Property Returns this object's validation status.
Warnings Property Returns the list of warnings generated the last time the object was validated and saved.
AddExtensionPrimitive Method Adds an extension primitive.
Class IInstance
Syntax [C#]
void AddExtensionPrimitive(
string ExtensionType,
string ExtensionPrimitiveName,
bool IsObjectExtension
);
---
## Page 108
<page_number>108</page_number> Chapter 2 API Reference
[Visual C++]
```c++
HRESULT AddExtensionPrimitive(
// Type of extension
[in] BSTR ExtensionType,
// Name of extension primitive to be added -
// For attribute extension primitive - Fully
// qualified name of attribute being extended
// For object extension primitive - New name
// specified by user for object extension
// primitive
[in] BSTR ExtensionPrimitiveName,
// If wszName is the new name specified by user, // this
// field will be set to true. for example
// when add script pass true
[in, optional, defaultvalue( -1 )] VARIANT_BOOL
IsObjectExtension
);
AddUDA Method
Adds a UDA.
Class
IInstance
Syntax
[C#]
void AddUDA(
string UDAName,
MxDataType DataType,
MxAttributeCategory category,
MxSecurityClassification Security,
bool IsArray,
object ArrayElementCount
);
[Visual C++]
// Add a UDA
//
// Returns:
// S_OK - Successfully add a UDA
GRAccess Toolkit API User's Guide
Page 109
Interfaces <page_number>109</page_number>
HRESULT AddUDA(
// Same XML format. But only one is allowed.
[in] BSTR UDAName,
[in] enum MxDataType Datatype,
[in] enum MxAttributeCategory Category,
[in] enum MxSecurityClassification Security,
[in] VARIANT_BOOL IsArray,
[in] VARIANT ArrayElementCount
);
Area Property
Get or set the area of this object. An AppObject area must be set using the SetContainer or SetHost methods. The object does not need to be checked out, and the operation is immediate.
Class
IInstance
Syntax
[C#]
string Area { set; get; };
[Visual C++]
// Returns name of the Area object, or blank if the
// object doesn't have an Area.
[propget]
HRESULT Area(
[out, retval] BSTR* theArea
);
// Set the Area of this object.
[propput]
HRESULT Area(
// The name of the Area, or blank to unassign
// from existing Area.
[in] BSTR NewArea
);
GRAccess Toolkit API User's Guide
Page 110
<page_number>110</page_number> Chapter 2 API Reference
Attributes Property
Returns the collection of attributes of this object.
Class
IInstance
Syntax
[C#]
IAttributes Attributes { get; };
[Visual C++]
// The collection of Attributes of this object.
// Configuring attributes requires that the object
// be checked out.
HRESULT Attributes(
// The collection of Attributes of this object.
[out, retval] IAttributes** theAttributes
);
BasedOn Property
Returns the name of the base template for this object.
Class
IInstance
Syntax
[C#]
string basedOn { get; };
[Visual C++]
// The name of the base template (root ancestor) of // this
// object.
HRESULT BasedOn (
// The name of the base template (root ancestor)
// of this object.
[out, retval] BSTR* theBaseTemplate
);
---
## Page 111
Interfaces <page_number>111</page_number>
# Category Property
Returns the category of this object.
## Class
IInstance
## Syntax
[C#]
```csharp
ECATEGORY category { get; };
[Visual C++]
// The Category of the object.
HRESULT Category(
// The Category of the object.
[out, retval] enum ECATEGORY* theCategory
);
CategoryGUID Property
Gets the category GUID of this object.
Class
IInstance
Syntax
[C#]
VBGUID CategoryGUID { get; };
[Visual C++]
// The Category GUID of the object.
HRESULT CategoryGUID(
// The Category of the object.
[out, retval] VBGUID *categoryGUID
);
---
## Page 112
<page_number>112</page_number> Chapter 2 API Reference
# CheckedOutBy Property
Returns the name of the user who has checked out this object.
**Class**
IInstance
**Syntax**
[C#]
```csharp
string checkedOutBy { get; };
[Visual C++]
// The name of the user that this object is checked // out by.
HRESULT CheckedOutBy(
// The name of the user that this object is checked out by.
[out, retval] BSTR* CheckedOutByUserName
);
CheckIn Method
Check in this object.
Class
IInstance
Syntax
[C#]
void CheckIn(
string CheckInComment
);
[Visual C++]
// Checks in an object.
// Called on a checked-out object after it is
// configured and saved.
HRESULT CheckIn(
// Check in an object.
[in, optional] BSTR CheckInComment
);
---
## Page 113
Interfaces <page_number>113</page_number>
# CheckOut Method
Check out this object.
**Class**
IInstance
**Syntax**
[C#]
```csharp
void CheckOut();
[Visual C++]
// Checks out an object.
HRESULT CheckOut();
CheckoutStatus Property
Returns the check out status of the object.
Class IInstance
Syntax
[C#]
ECheckoutStatus CheckoutStatus { get; };
[Visual C++]
// The check-out status of the object.
HRESULT CheckoutStatus(
// The check-out status of the object.
[out, retval] enum ECheckoutStatus* theCheckoutStatus
);
CommandResult Property
Returns the CommandResult object, which has the results from the last method call.
Class IInstance
Syntax
[C#]
ICommandResult CommandResult { get; };
---
## Page 114
<page_number>114</page_number> Chapter 2 API Reference
[Visual C++]
```c++
// Returns the CommandResult Object, which has last
// method call result
HRESULT CommandResult(
// Returns the CommandResult
[out, retval] ICommandResult** CommandResult
);
ConfigurableAttributes Property
Returns a collection of this object's attributes that can be configured.
Class
IInstance
Syntax
[C#]
IAttributes ConfigurableAttributes { get; };
[Visual C++]
// The collection of Attributes of this object that
// can be configured.
// Configuring attributes requires that the object
// be checked out.
HRESULT ConfigurableAttributes(
// The collection of Attributes of this object
// that can be configured.
[out, retval] IAttributes** theConfigurableAttributes
);
ConfigVersion Property
Returns this object's configuration version number. The configuration version is incremented each time the object is checked in.
Class
IInstance
Syntax
[C#]
int ConfigVersion { get; };
---
## Page 115
Interfaces <page_number>115</page_number>
[Visual C++]
```c++
// The configuration version of the object.
HRESULT ConfigVersion(
// The configuration version of the object.
[out, retval] LONG* theConfigVersion
);
ContainedName Property
Sets or returns this object's contained name. When setting the contained name, the object does not need to be checked out, and the operation is immediate.
Class
IInstance
Syntax
[C#]
string ContainedName { set; get; }
[Visual C++]
//
// Returns Contained name of this object (eg. Inlet)
[propget]
HRESULT ContainedName (
// The contained name of this object (eg. Inlet)
[out, retval] BSTR* theContainedName
);
//
// Sets the contained name of this object (eg.
// Inlet)
//
// The object does not need to be checked out; the
// operation is immediate.
[propput]
HRESULT ContainedName (
// The contained name of this object (eg. Inlet)
[in] BSTR newContainedName
);
GRAccess Toolkit API User's Guide
Page 116
<page_number>116</page_number> Chapter 2 API Reference
Container Property
Returns or sets the container for this object. When setting the container the object does not need to be checked out, and the change is immediate. For an ApplicationObject, the ApplicationObject's area and host area are also updated.
Class
IInstance
Syntax
[C#]
string Container { set; get; };
[Visual C++]
// Returns name of the Container object, or blank if
// object is not contained.
[propget]
HRESULT Container(
// The name of the Container object, or blank if
// the object is not contained.
[out, retval] BSTR* theContainer
);
// Set the Container for this object.
[propput]
HRESULT Container(
// The name of the container, or blank to
// uncontain.
[in] BSTR NewContainer
);
DeleteExtensionPrimitive Method
Delete an extension primitive.
Class
IInstance
Syntax
[C#]
void DeleteExtensionPrimitive(
string ExtensionType,
string ExtensionPrimitiveName
);
GAccess Toolkit API User's Guide
Page 117
Interfaces <page_number>117</page_number>
[Visual C++]
// Delete an extension primitive
// Returns S_OK
HRESULT DeleteExtensionPrimitive(
// Type of extension
[in] BSTR ExtensionType,
// Name of Extension primitive to be deleted.
[in] BSTR ExtensionPrimitiveName
);
DeleteInstance Method
Delete an instance.
Class
IInstance
Syntax
[C#]
void DeleteInstance (
EForceDeleteInstanceOption ForceDeleteOption
);
[Visual C++]
HRESULT DeleteInstance (
[in, optional, defaultvalue( dontForceInstanceDelete )]
EForceDeleteInstanceOption ForceDeleteOption
);
Parameters
ForceDeleteOption Various options to indicate whether deletion of the object should be forced.
GRAccess Toolkit API User's GuidePage 118
<page_number>118</page_number> Chapter 2 API Reference
DeleteUDA Method
Delete a UDA.
Class IInstance
Syntax
[C#]
void DeleteUDA(
string UDAName
);
[Visual C++]
// Delete a UDA
//
// Returns:
// S_OK - Successfully delete a UDA
HRESULT DeleteUDA(
// Delete an UDA by UDA name.
[in] BSTR UDAName
);
Deploy Method
Deploy this instance.
Class IInstance
Syntax
[C#]
void Deploy(
EActionForCurrentlyDeployedObjects actionForDeployedObjects,
ESkipIfCurrentlyUndeployed skipIfCurrentlyUndeployed,
EDeployOnScan deployOnScan,
EForceOffScan forceOffScan,
ECascade cascade,
bool markAsDeployedOnStatusMismatch
);
GRAccess Toolkit API User's Guide
Page 119
Interfaces <page_number>119</page_number>
[Visual C++]
HRESULT Deploy(
[in, optional, defaultvalue( skipDeploy )] EActionForCurrentlyDeployedObjects actionForDeployedObjects,
[in, optional, defaultvalue( dontSkipIfCurrentlyUndeployed )] ESkipIfCurrentlyUndeployed skipIfCurrentlyUndeployed,
[in, optional, defaultvalue( doDeployOnScan )] EDeployOnScan deployOnScan,
[in, optional, defaultvalue( doForceOffScan )] EForceOffScan forceOffScan,
[in, optional, defaultvalue( doCascade )] ECascade cascade,
[in, optional, defaultvalue( 1 )] VARIANT_BOOL markAsDeployedOnStatusMismatch
);
Parameters
- actionForDeployedObjects
- Action for currently deployed object.
- skipIfCurrentlyUndeployed
- Action for currently undeployed object.
- deployOnScan
- Deploy on scan.
- forceOffScan
- Force off scan.
- cascade
- Cascade.
- markAsDeployedOnStatusMismatch
- Deploy status mismatch.
DeployedVersion Property
The configuration version of this instance at the time it was last deployed.
Class
IInstance
Syntax
[C#]
int DeployedVersion { get; };
[Visual C++]
HRESULT DeployedVersion(
[out, retval] LONG*
);
---
## Page 120
<page_number>120</page_number> Chapter 2 API Reference
# DeployEx Method
Deploy this instance.
## Class
IInstance
## Syntax
[C#]
```csharp
void DeployEx(
EActionForCurrentlyDeployedObjects actionForDeployedObjects,
ESkipIfCurrentlyUndeployed skipIfCurrentlyUndeployed,
EDeployOnScan deployOnScan,
EForceOffScan forceOffScan,
ECascade cascade,
bool markAsDeployedOnStatusMismatch,
string strCustomData
);
[Visual C++]
// Deploy this Instance.
HRESULT DeployEx(
// Action for currently deployed object
[in, optional, defaultvalue( skipDeploy )]
EActionForCurrentlyDeployedObjects actionForDeployedObjects,
// Action for currently undeployed object
[in, optional, defaultvalue( dontSkipIfCurrentlyUndeployed )]
ESkipIfCurrentlyUndeployed skipIfCurrentlyUndeployed,
// Deploy on scan
[in, optional, defaultvalue( doDeployOnScan )] EDeployOnScan deployOnScan,
// Force off scan
[in, optional, defaultvalue( doForceOffScan )] EForceOffScan forceOffScan,
// Cascade
[in, optional, defaultvalue( doCascade )] ECascade cascade,
// Deploy status mismatch
[in, optional, defaultvalue( 1 )] VARIANT_BOOL markAsDeployedOnStatusMismatch,
GAccess Toolkit API User's Guide
Page 121
Interfaces <page_number>121</page_number>
// Data used by custom category package
[in, optional, defaultvalue("")] BSTR strCustomData
);
DeploymentStatus Property
Indicates whether the instance is currently deployed and if so, if it has pending changes.
Class
IInstance
Syntax
[C#]
EDeploymentStatus DeploymentStatus { get; };
[Visual C++]
HRESULT DeploymentStatus(
[out, retval] EDeploymentStatus* theDeploymentStatus
);
Parameters
theDeploymentStatus Indicates whether the instance is currently deployed and if so, if it has pending changes.
DerivedFrom Property
Returns the name of the object's template.
Class
IInstance
Syntax
[C#]
string DerivedFrom { get; };
[Visual C++]
// Returns the name of the template that this object // was created from.
HRESULT DerivedFrom(
// The name of the template that this object was // created from.
[out, retval] BSTR* theParentTemplate
);
---
## Page 122
<page_number>122</page_number> Chapter 2 API Reference
# EditStatus Property
Edit the status of the object.
## Class
IInstance
## Syntax
[C#]
```csharp
EEditStatus EditStatus { get; };
[Visual C++]
// The edit status of the object.
HRESULT EditStatus(
// The edit status of the object.
[out, retval] enum EEditStatus* theEditStatus
);
Errors Property
Retrieves the list of errors generated when the object was last validated and saved.
Class
IInstance
Syntax
[C#]
string[] Errors { get; };
[Visual C++]
// The list of errors that got generated the last
// time the object was validated and saved.
[propget]
HRESULT Errors(
// The list of errors that got generated the last // time the
object was validated and saved.
[out, retval] SAFEARRAY(BSTR) * theErrors
);
---
## Page 123
Interfaces <page_number>123</page_number>
# GetExtendedAttributes Method
Get the extended attributes in the hierarchy.
**Class**
IInstance
**Syntax**
**[C#]**
```csharp
IAttributes GetExtendedAttributes(
string AttributeName,
int upto_level,
MxAttributeCategory[] ReturnOnlyTheseCategories
);
[Visual C++]
//Get Extended Attributes in Hierarchy
HRESULT GetExtendedAttributes (
//Attribute full name which is extended
[in] BSTR AttributeName,
//Up to how many level user needs extended
//primitives
//-1 will return all levels
[in] int upto_level,
//Return attributes which are only these
//categories. If safearray is empty returns all
//attributes.
[in] SAFEARRAY(MxAttributeCategory) ReturnOnlyTheseCategories,
//Return attributes
[out, retval] IAttributes** theAttributes
);
GetObjectHelpURL Method
Returns the URL where the object help is stored on the Galaxy repository.
Class IInstance
GRAccess Toolkit API User's Guide
Page 124
<page_number>124</page_number> Chapter 2 API Reference
Syntax
[C#]
string GetObjectHelpURL();
[Visual C++]
// Returns the URL to where the Object Help is
// stored on the Galaxy Repository.
// The client can display the URL in
// InternetExplorer or use web publishing
// to change the data.
HRESULT GetObjectHelpURL(
// Returns the URL to where the Object Help is
// stored on the GR.
[out, retval] BSTR*
);
HierarchicalName Property
Returns the hierarchical name of this object.
Class
IInstance
Syntax
[C#]
string HierarchicalName { get; };
[Visual C++]
// The Hierarchical name of this object. (eg.
//Reactor.Tank.Inlet)
HRESULT HierarchicalName
(
// The hierarchical name of this object. (eg.
Reactor.Tank.Inlet)
[out, retval] BSTR* theHierarchicalName
);
---
## Page 125
Interfaces <page_number>125</page_number>
# Host Property
Returns the name of this object's host.
**Class**
IInstance
**Syntax**
[C#]
```csharp
string Host { set; get; }
[Visual C++]
// The name of the Host for this object, or blank if // unassigned.
HRESULT Host(
// The name of the Host for this object.
[out, retval] BSTR* theHost
);
RenameExtensionPrimitive Method
Rename the object extension primitive.
Class IInstance
Syntax
[C#]
void RenameExtensionPrimitive(
string OldPrimitiveName,
string NewPrimitiveName
);
[Visual C++]
// Rename an object extension primitive
//
// Returns S_OK
HRESULT RenameExtensionPrimitive(
// Old name of primitive extension
[in] BSTR OldPrimitiveName,
// New name specified by user
[in] BSTR NewPrimitiveName
);
GRAccess Toolkit API User's Guide
Page 126
<page_number>126</page_number> Chapter 2 API Reference
RenameUDA Method
Change the name of a UDA.
Class
IInstance
Syntax
[C#]
void RenameUDA(
string OldUDAName,
string NewUDAName
);
[Visual C++]
// Rename a UDA
//
// Returns:
//
// S_OK - Successfully rename a UDA
HRESULT RenameUDA (
// The old external name of the primitive
[in] BSTR OldUDAName,
// The new external name of the primitive
[in] BSTR NewUDAName
);
Save Method
Save the object.
Class
IInstance
Syntax
[C#]
void Save();
[Visual C++]
// Saves the object after it's configured.
// Object must be checked out.
HRESULT Save();
GRAccess Toolkit API User's Guide
Page 127
Interfaces <page_number>127</page_number>
Tagname Property
Returns or sets this object's tagname.
Class IInstance
Syntax
[C#]
string Tagname { set; get; }
[Visual C++]
// Returns the Tagname of this object.
[propget]
HRESULT Tagname(
// The Tagname of this object.
[out, retval] BSTR* theTagname
);
// Sets the Tagname of this object.
// The object does not need to be checked out; the
// operation is immediate.
[propput]
HRESULT Tagname(
// The Tagname of this object.
[in] BSTR newTagName
);
Undeploy Method
Undeploy this instance.
Class IInstance
Syntax
[C#]
void Undeploy(
EForceOffScan UndeployRule,
ECascade cascade,
bool markAsUndeployedOnFailure
);
GRAccess Toolkit API User's Guide
Page 128
<page_number>128</page_number> Chapter 2 API Reference
[Visual C++]
HRESULT Undeploy(
[in, optional, defaultvalue( dontForceOffScan )] EForceOffScan UndeployRule,
[in, optional, defaultvalue( doCascade )] ECascade cascade,
[in, optional, defaultvalue( 0 )] VARIANT_BOOL markAsUndeployedOnFailure
);
Parameters
UndeployRule Indicates whether to force an object off-scan if it is running on-scan prior to undeployment.
cascade Cascade.
markAsUndeployedOnFailure On failure, set deploy status as undeployed.
UndeployEx Method
Undeploy this instance.
Class
IInstance
Syntax
[C#]
void Undeploy(
EForceOffScan UndeployRule,
ECascade cascade,
bool markAsUndeployedOnFailure
);
[Visual C++]
// Undeploy this Instance.
HRESULT UndeployEx(
// Indicates whether to force an object off-scan //if it's running on-scan prior to undeployment.
[in, optional, defaultvalue( dontForceOffScan )] EForceOffScan UndeployRule,
// Cascade
[in, optional, defaultvalue( doCascade )] ECascade cascade,
---
## Page 129
Interfaces <page_number>129</page_number>
```csharp
// On Failure, set deploy status as undeployed
[in, optional, defaultvalue( 0 )] VARIANT_BOOL
markAsUndeployedOnFailure,
// Data used by custom category package
[in, optional, defaultvalue("") ] BSTR strCustomData
);
UndoCheckOut Method
Reverses the check out operation without making changes.
Class IInstance
Syntax
[C#]
void UndoCheckOut();
[Visual C++]
// Undo check-out this object.
HRESULT UndoCheckOut();
Unload Method
Unload the object cache, releasing internal resources obtained by the object during operations. After executing this method, the object is still available. Internal resources will be reloaded as necessary.
Class IInstance
Syntax
[C#]
void Unload();
[Visual C++]
// Unloads the gObject cache. This method doesn't
// affect functionality.
HRESULT Unload();
---
## Page 130
<page_number>130</page_number> Chapter 2 API Reference
# UpdateUDA Method
Save the UDA information.
## Class
IInstance
## Syntax
[C#]
```csharp
void UpdateUDA(
string wszUDAIInfo,
MxDataType DataType,
MxAttributeCategory category,
MxSecurityClassification Security,
bool IsArray,
object ArrayElementCount
);
[Visual C++]
// Update a UDA
// Returns:
// S_OK - Successfully update a UDA
HRESULT UpdateUDA (
// Same XML format. But only one is allowed. The // new info
// will overwrite the old info.
[in] BSTR wszUDAIInfo,
[in] enum MxDataType Datatype,
[in] enum MxAttributeCategory Category,
[in] enum MxSecurityClassification Security,
[in] VARIANT_BOOL IsArray,
[in] VARIANT ArrayElementCount
);
GRAccess Toolkit API User's Guide
Page 131
Interfaces <page_number>131</page_number>
Upload Method
Uploads AutomationObject configuration changes made at run time.
Class
IInstance
Syntax
[C#]
void Upload(
EAutomaticallyUndocheckout automaticallyUndocheckout,
ESkipOtherUsersCheckedOutObjects skipOtherUsersCheckedOutObjects,
ESkipObjectsWithPendingUpdates skipObjectsWithPendingUpdates
);
[Visual C++]
HRESULT Upload(
[in, optional, defaultvalue( doAutomaticallyUndocheckout )] EAutomaticallyUndocheckout automaticallyUndocheckout,
[in, optional, defaultvalue( doSkipOtherUsersCheckedOutObjects )] ESkipOtherUsersCheckedOutObjects skipOtherUsersCheckedOutObjects,
[in, optional, defaultvalue( doSkipObjectsWithPendingUpdates )] ESkipObjectsWithPendingUpdates skipObjectsWithPendingUpdates
);
Parameters
- automaticallyUndocheckout
- Automatically undo the check out.
- skipOtherUsersCheckedOutObjects
- Skip other users' checked out objects.
- skipObjectsWithPendingUpdates
- Skip objects with pending updates.
GRAccess Toolkit API User's Guide
Page 132
<page_number>132</page_number> Chapter 2 API Reference
UploadEx Method
Saves the AutomationObject configuration changes.
Class
IInstance
Syntax
[C#]
void UploadEx(
EAutomaticallyUndocheckout automaticallyUndocheckout,
ESkipOtherUsersCheckedOutObjects skipOtherUsersCheckedOutObjects,
ESkipObjectsWithPendingUpdates skipObjectsWithPendingUpdates,
string strCustomData
);
[Visual C++]
// Uploads AutomationObject configuration changes
// made in the runtime.
HRESULT UploadEx(
// Automatically Undocheckout
[in, optional, defaultvalue(doAutomaticallyUndocheckout)] EAutomaticallyUndocheckout automaticallyUndocheckout,
// Skip other users CheckedOuts
[in, optional, defaultvalue( doSkipOtherUsersCheckedOutObjects )] ESkipOtherUsersCheckedOutObjects skipOtherUsersCheckedOutObjects,
// Skip objects with pending updates
[in, optional, defaultvalue( doSkipObjectsWithPendingUpdates )] ESkipObjectsWithPendingUpdates skipObjectsWithPendingUpdates,
// Data used by custom category package
[in, optional, defaultvalue("") ] BSTR strCustomData
);
GRAccess Toolkit API User's Guide
Page 133
Interfaces <page_number>133</page_number>
ValidationStatus Property
Returns this object's validation status.
Class IInstance
Syntax
[C#]
EPACKAGESTATUS ValidationStatus { get; };
[Visual C++]
// The ValidationStatus of this object based on the // last time
// the object was validated and saved.
[propget]
HRESULT ValidationStatus(
// The validation status of the object.
[out, retval] enum EPACKAGESTATUS* theValidationStatus
);
Warnings Property
Returns the list of warnings generated the last time the object was validated and saved.
Class IInstance
Syntax
[C#]
string[] Warnings { get; };
[Visual C++]
// The list of warnings that got generated the last time the
// object was validated and saved.
HRESULT Warnings(
// The list of warnings that got generated the
// last time the object was validated and saved.
[out, retval] SAFEARRAY(BSTR) * theWarnings
);
---
## Page 134
<page_number>134</page_number> Chapter 2 API Reference
# IMxValue
Represents the fundamental variant object that contains a single data value or single array of data values of like type. The IMxValue is used to get and set data within the ArchestrA framework.
## IMxValue Class Members
This class has the following members.
### Operations
**Clone Method**
Creates a duplicate MxValue object with a state identical to the current MxValue.
**Empty Method**
Changes the MxValue's data type to MxNoData.
**PutBoolean Method**
Stores a Boolean value in the MxValue.
**PutInteger Method**
Stores a long value in the MxValue.
**PutFloat Method**
Stores a float value in the MxValue.
**PutDouble Method**
Stores a double value in the MxValue.
**PutString Method**
Stores a Unicode string value in the MxValue.
**PutTime Method**
Stores a VBFILETIME value in the MxValue.
**PutElapsedTime Method**
Stores a VB_LARGE_INTEGER value in the MxValue.
**PutMxReference Method**
Stores an MxReference in the MxValue.
**PutMxStatus Method**
Stores an MxStatus in the MxValue.
**PutMxDataType Method**
Stores an MxDataType in the MxValue.
**PutMxSecurityClassification Method**
Stores an MxSecurityClassification in the MxValue.
**PutMxDataQuality Method**
Stores an MxDataQuality in the MxValue.
**PutCustomStruct Method**
Stores a struct in the MxValue.
**PutCustomEnum Method**
Stores an MxCustomEnum in the MxValue.
<footer>GRAccess Toolkit API User’s Guide</footer>
---
## Page 135
Interfaces <page_number>135</page_number>
**GetDataType Method**
Returns the data type of the value stored in the MxValue.
**GetBoolean Method**
Returns the value stored in the MxValue as a VARIANT_BOOL.
**GetInteger Method**
Returns the value stored in the MxValue as a long.
**GetFloat Method**
Returns the value stored in the MxValue as a float.
**GetDouble Method**
Returns the value stored in the MxValue as a double.
**GetString Method**
Returns the value stored in the MxValue as a string.
**GetTime Method**
Returns the value stored in the MxValue as a VBFILETIME.
**GetElapsedTime Method**
Returns the value stored in the MxValue as a VB_LARGE_INTEGER.
**GetMxReference Method**
Returns the value stored in the MxValue as an IMxReference *.
**GetMxStatus Method**
Returns the MxStatus stored in the MxValue.
**GetMxDataType Method**
Returns the value stored in the MxValue as an MxDataType.
**GetMxSecurityClassification Method**
Returns the value stored in the MxValue as an MxSecurityClassification.
**GetMxDataQuality Method**
Returns the value stored in the MxValue as an MxDataQuality.
**GetCustomStruct Method**
Returns the qualified struct stored in the MxValue.
**GetCustomEnum Method**
Returns the value stored in the MxValue as a qualified enum.
**GetDimensionCount Method**
Indicates whether the MxValue holds an array.
**PutElement Method**
Puts an element into an array held by an MxValue.
**GetElement Method**
Gets an element from an array held in an MxValue.
**GetDimensionSize Method**
Gets the size of the array held by the MxValue.
**PutCustomStructVB Method**
Stores a qualified struct in the MxValue for a VB client.
GRAccess Toolkit API User's Guide
---
## Page 136
<page_number>136</page_number> Chapter 2 API Reference
**GetCustomStructVB Method**
Returns the qualified struct stored in the MxValue for a VB client.
**PutInternationalStrings Method**
Initializes an MxValue with a set of internationalized strings.
**PutInternationalStringsVB Method**
Initializes an MxValue with a set of internationalized strings for a VB client.
**GetInternationalStrings Method**
Returns the internationalized strings stored by the MxValue.
**GetInternationalStringsVB Method**
Returns the internationalized strings stored by the MxValue for a VB client.
**GetInternationalString Method**
Returns the internationalized string associated with a particular local.
**PutInternationalString Method**
Adds the internationalized string of a specific locale to the existing internationalized strings.
**Clone Method**
Creates a duplicate MxValue object with a state identical to the current MxValue.
**Class**
IMxValue
**Syntax**
**[C#]**
```csharp
void Clone(
out MxValue ppMxValue
);
[Visual C++]
HRESULT Clone(
[out] IMxValue **ppMxValue
);
Parameters
- ppMxValue Receives the IMxValue interface pointer of the newly cloned object.
GRAccess Toolkit API User's Guide
Page 137
Interfaces <page_number>137</page_number>
Returns
S_OK - Success
E_POINTER - An invalid pointer was passed in.
E_OUTOFMEMORY - Unable to allocate memory for the new MxValue object.
Empty Method
Changes the MxValue's data type to MxNoData.
Class
IMxValue
Syntax
[C#]
void Empty();
[Visual C++]
HRESULT Empty();
Returns
S_OK - Success
PutBoolean Method
Stores a Boolean value in the MxValue. The MxValue's data type will be MxBoolean.
Class
IMxValue
Syntax
[C#]
void PutBoolean(
bool newVal
);
[Visual C++]
HRESULT PutBoolean(
[in] VARIANT_BOOL newVal
);
GRAccess Toolkit API User's Guide
Page 138
<page_number>138</page_number> Chapter 2 API Reference
Parameters
newVal
The value that will be stored in the MxValue object.
Returns
S_OK - Success
PutInteger Method
Stores a long value in the MxValue. The MxValue's data type will be MxInteger.
Class
IMxValue
Syntax
[C#]
void PutInteger(
int newVal
);
[Visual C++]>
HRESULT PutInteger(
[in] long newVal
);
Parameters
newVal
The value that will be stored in the MxValue object.
Returns
S_OK - Success
GRAccess Toolkit API User's Guide
Page 139
Interfaces <page_number>139</page_number>
PutFloat Method
Stores a float value in the MxValue. The MxValue's data type will be MxFloat.
Class
IMxValue
Syntax
[C#]
void PutFloat(
float newVal
);
[Visual C++]
HRESULT PutFloat(
[in] float newVal
);
Parameters
newVal The value that will be stored in the MxValue object. A value that is NaN (not a number) is permitted.
Returns
S_OK - Success
PutDouble Method
Stores a double value in the MxValue. The MxValue's data type will be MxDouble.
Class
IMxValue
Syntax
[C#]
void PutDouble(
double newVal
);
[Visual C++]
HRESULT PutDouble(
[in] double newVal
);
GRAccess Toolkit API User's Guide
Page 140
<page_number>140</page_number> Chapter 2 API Reference
Parameters
newVal The value that will be stored in the MxValue object. A value that is NaN (not a number) is permitted.
Returns
S_OK - Success
PutString Method
Stores a Unicode string value in the MxValue. The MxValue's data type will be MxString.
Class
IMxValue
Syntax
[C#]
void PutString(
string newVal
);
[Visual C++]
HRESULT PutString(
[in, string] LPCWSTR newVal
);
Parameters
newVal The value that will be stored in the MxValue object.
Returns
S_OK - Success E_OUTOFMEMORY - Unable to allocate memory for the string.
GRAccess Toolkit API User's GuidePage 141
Interfaces <page_number>141</page_number>
PutTime Method
Stores a VBFILETIME value in the MxValue. The MxValue's data type will be MxTime.
Class
IMxValue
Syntax
[C#]
void PutTime(
ref VBFILETIME pNewVal
);
[Visual C++]
HRESULT PutTime (
[in] VBFILETIME *pNewVal
);
Parameters
pNewVal The value that will be stored in the MxValue object.
Returns
S_OK - Success
PutElapsedTime Method
Stores a VB_LARGE_INTEGER value in the MxValue. The MxValue's data type will be MxElapsedTime.
Class
IMxValue
Syntax
[C#]
void PutElapsedTime (
ref VB_LARGE_INTEGER pNewVal
);
[Visual C++]
HRESULT PutElapsedTime (
[in] VB_LARGE_INTEGER *pNewVal
);
GRAccess Toolkit API User's Guide
Page 142
<page_number>142</page_number> Chapter 2 API Reference
Parameters
pNewVal The value that will be stored in the MxValue object.
Returns
S_OK - Success
PutMxReference Method
Stores an MxReference in the MxValue. The MxValue's data type will be MxReferenceType.
Class
IMxValue
Syntax
[C#]
void PutMxReference(
IMxReference newVal
);
[Visual C++]
HRESULT PutMxReference (
[in] IMxReference *newVal
);
Parameters
newVal The MxReference that will be stored in the MxValue object.
Returns
S_OK - Success
PutMxStatus Method
Stores an MxStatus in the MxValue. The MxValue's data type will be MxStatusType.
Class
IMxValue
Syntax
[C#]
void PutMxStatus (
ref MxStatus newVal
);
GRAccess Toolkit API User's Guide
Page 143
Interfaces <page_number>143</page_number>
[Visual C++]
HRESULT PutMxStatus (
[in] const MxStatus *newVal
);
Parameters
newVal The MxStatus that will be stored in the MxValue object.
Returns
S_OK - Success
PutMxDataType Method
Stores an MxDataType in the MxValue. The MxValue's data type will be MxDataTypeEnum.
Class
IMxValue
Syntax
[C#]
void PutMxDataType (
MxDataType newVal
);
[Visual C++]
HRESULT PutMxDataType (
[in] MxDataType newVal
);
Parameters
newVal The MxDataType that will be stored in the MxValue object.
Returns
S_OK - Success
GRAccess Toolkit API User's Guide
Page 144
<page_number>144</page_number> Chapter 2 API Reference
PutMxSecurityClassification Method
Stores an MxSecurityClassification in the MxValue. The MxValue's data type will be MxSecurityClassificationEnum.
Class
IMxValue
Syntax
[C#]
void PutMxSecurityClassification(
MxSecurityClassification newVal
);
[Visual C++]
HRESULT PutMxSecurityClassification(
[in] MxSecurityClassification newVal
);
Parameters
newVal The MxSecurityClassification that will be stored in the MxValue object.
Returns
S_OK - Success
PutMxDataQuality Method
Stores an MxDataQuality in the MxValue. The MxValue's data type will be MxDataQualityEnum.
Class
IMxValue
Syntax
[C#]
void PutMxDataQuality(
ref short newVal
);
[Visual C++]
HRESULT PutMxDataQuality(
[in] const MxDataQuality *newVal
);
GAccess Toolkit API User's Guide
Page 145
Interfaces <page_number>145</page_number>
Parameters
newVal The MxDataQuality that will be stored in the MxValue object.
Returns
S_OK - Success
PutCustomStruct Method
Stores a struct in the MxValue. The MxValue's data type will be MxCustomeStruct.
Class
IMxValue
Syntax
[C#]
void PutCustomStruct (
int guid,
int structSize,
ref byte pStruct
);
[Visual C++]
HRESULT PutCustomStruct (
[in] long guid,
[in] long structSize,
[in, size_is(structSize)] const unsigned char *pStruct
);
Parameters
guid A quasi-GUID that uniquely identifies this struct. The BRO does not validate the GUID.
structSize Size of the struct.
pStruct Pointer to the struct. MxValue will create its own copy of the struct.
Returns
S_OK - Success
GRAccess Toolkit API User's Guide
Page 146
<page_number>146</page_number> Chapter 2 API Reference
PutCustomEnum Method
Stores an MxCustomEnum in the MxValue. The MxValue's data type will be MxCustomEnum.
Class
IMxValue
Syntax
[C#]
void PutCustomEnum(
string value,
short ordinal,
short primitiveId,
short attributeId
);
[Visual C++]
HRESULT PutCustomEnum (
[in] LPCWSTR value,
[in] short ordinal,
[in] MxPrimitiveId primitiveId,
[in] MxAttributeId attributeId
);
Parameters
value, The enumeration's string value. This parameter is used by Message Exchange clients. BRO can pass in 0 for internal clients.
ordinal, The enumeration's ordinal value. This parameter is used by primitives. Other clients can pass in 0.
primitiveId, The primitive corresponding to the attribute which holds an array of all the possible enumeration string values, or just pass in 0. This parameter is ignored by the BRO on external sets. This parameter is used by the BRO to initialize an MxValue.
attributeId The attribute holding an array of all the possible enumeration string values, or just pass in 0. This parameter is ignored by the BRO on external sets. This parameter is used by the BRO to initialize an MxValue.
Returns
S_OK - Success
GRAccess Toolkit API User's GuidePage 147
Interfaces <page_number>147</page_number>
GetDataType Method
Returns the data type of the value stored in the MxValue.
Class
IMxValue
Syntax
[C#]
MxDataType GetDataType();
[Visual C++]
HRESULT GetDataType(
[out, retval] MxDataType *pVal
);
Parameters
pVal Receives the data type.
Returns
S_OK - Success
E_POINTER - An invalid pointer was passed in.
GetBoolean Method
Returns the value stored in the MxValue as a VARIANT_BOOL.
Class
IMxValue
Syntax
[C#]
bool GetBoolean();
[Visual C++]
HRESULT GetBoolean(
[out, retval] VARIANT_BOOL *pVal
);
Parameters
pVal Receives the value.
Returns
S_OK - Success
GRAccess Toolkit API User's Guide
Page 148
<page_number>148</page_number> Chapter 2 API Reference
MX_E_ConversionNotSupported - The stored value is a type that cannot be converted to VARIANT_BOOL. MX_E_UnableToConvertString - The string held in the MxValue is not "true" or "false". E_POINTER - An invalid pointer was passed in.
GetInteger Method
Returns the value stored in the MxValue as a long.
Class
IMxValue
Syntax
[C#]
int GetInteger();
[Visual C++]
HRESULT GetInteger(
[out, retval] long *pVal
);
Parameters
pVal Receives the value.
Returns
S_OK - Success MX_E_ConversionNotSupported - The stored value is a type that cannot be converted to long. MX_E_UnableToConvertString - The string held in the MxValue cannot be converted to a long. MX_E_Overflow - Conversion of the stored value results in overflow. E_POINTER - An invalid pointer was passed in.
GRAccess Toolkit API User's Guide
Page 149
Interfaces <page_number>149</page_number>
GetFloat Method
Returns the value stored in the MxValue as a float.
Class
IMxValue
Syntax
[C#]
float GetFloat();
[Visual C++]
HRESULT GetFloat(
[out, retval] float *pVal
);
Parameters
pVal Receives the value.
Returns
S_OK - Success MX_E_ConversionNotSupportedException - The stored value is a type that cannot be converted to float. MX_E_UnableToConvertString - The string held in the MxValue cannot be converted to a float. MX_E_Overflow - Conversion of the stored value results in overflow. E_POINTER - An invalid pointer was passed in.
GetDouble Method
Returns the value stored in the MxValue as a double.
Class
IMxValue
Syntax
[C#]
double GetDouble();
[Visual C++]
HRESULT GetDouble(
[out, retval] double *pVal
);
GRAccess Toolkit API User's Guide
Page 150
<page_number>150</page_number> Chapter 2 API Reference
Parameters
pVal Receives the value.
Returns
S_OK - Success
MX_E_ConversionNotSupportedException - The stored value is a type that cannot be converted to double.
MX_E_UnableToConvertString - The string held in the MxValue cannot be converted to a double.
E_POINTER - An invalid pointer was passed in.
GetString Method
Returns the value stored in the MxValue as a string.
Class
IMxValue
Syntax
[C#]
string GetString();
[Visual C++]
HRESULT GetString(
[out, retval] BSTR *pVal
);
GRAccess Toolkit API User's Guide
Page 151
Interfaces <page_number>151</page_number>
Parameters
pVal Receives the value. Use SysFreeString to free the BSTR when finished with it.
If the value stored in the MxValue is not of type MxString, a string representation of the value is returned as follows:
MxNoData - "No Data" MxBoolean - "true" or "false" MxInteger - "1234" MxFLOAT - "3.5" MxDouble - "3.5" MxString - "Hello World" MxTime - "Sun May 01 20:27:01 1994" MxElapsedTime - "89384" (elapsed time in 100 nanosecond increments.) MxReferenceType - "Valve1.pv" MxStatusType - "Error detected by Requesting NMX: Request timed out." MxDATATypeEnum - "MxInteger" MxSecurityClassificationEnum - "MxSecurityFreeAccess" MxDATAQualityType - "Uncertain" MxCUSTOMEnum - "Open" MxCUSTOMStruct - "478602" (guid for the struct)
Returns
S_OK - Success E_OUTOFMEMORY - Unable to allocate memory for the string. E_POINTER - An invalid pointer was passed in.
GRAccess Toolkit API User's GuidePage 152
<page_number>152</page_number> Chapter 2 API Reference
GetTime Method
Returns the value stored in the MxValue as a VBFILETIME.
Class
IMxValue
Syntax
[C#]
void GetTime(
out VBFILETIME pVal
);
[Visual C++]
HRESULT GetTime (
[out] VBFILETIME *pVal
);
Parameters
pVal Receives the value.
Returns
S_OK - Success
MX_E_ConversionNotSupported - The stored value is a type that cannot be converted to VBFILETIME.
MX_E_UnableToConvertString - The string held in the MxValue cannot be converted to a VBFILETIME.
E_POINTER - An invalid pointer was passed in.
GetElapsedTime Method
Returns the value stored in the MxValue as a VB_LARGE_INTEGER.
Class
IMxValue
Syntax
[C#]
VB_LARGE_INTEGER GetElapsedTime();
[Visual C++]
HRESULT GetElapsedTime (
[out, retval] VB_LARGE_INTEGER *pVal
);
GAccess Toolkit API User's Guide
Page 153
Interfaces <page_number>153</page_number>
Parameters
pVal Receives the value.
Returns
S_OK - Success. MX_E_ConversionNotSupported - The stored value is not of type MxElapsedTime. E_POINTER - An invalid pointer was passed in.
GetMxReference Method
Returns the value stored in the MxValue as an IMxReference *.
Class
IMxValue
Syntax
[C#]
IMxReference GetMxReference();
[Visual C++]
HRESULT GetMxReference(
[out, retval] IMxReference **pVal
);
Parameters
pVal Receives the value.
Returns
S_OK - Success. MX_E_ConversionNotSupported - The stored value is not an MxReference or MxString. E_POINTER - An invalid pointer was passed in.
GRAccess Toolkit API User's Guide
Page 154
<page_number>154</page_number> Chapter 2 API Reference
GetMxStatus Method
Returns the MxStatus stored in the MxValue.
Class
IMxValue
Syntax
[C#]
MxStatus GetMxStatus();
[Visual C++]
HRESULT GetMxStatus(
[out, retval] MxStatus *pVal
);
Parameters
pVal Receives the value.
Returns
S_OK - Success. MX_E_ConversionNotSupported - The stored value is not an MxStatus. E_POINTER - An invalid pointer was passed in.
GetMxDataType Method
Returns the value stored in the MxValue as an MxDataType.
Class
IMxValue
Syntax
[C#]
MxDataType GetMxDataType();
[Visual C++]
HRESULT GetMxDataType(
[out, retval] MxDataType *pVal
);
Parameters
pVal Receives the value.
GRAccess Toolkit API User's Guide
Page 155
Interfaces <page_number>155</page_number>
Returns
S_OK - Success
MX_E_ConversionNotSupportedException - The stored value is a type that cannot be converted to MxDataType.
MX_E_UnableToConvertString - The string held in the MxValue cannot be converted to an MxDataType.
MX_E_Overflow - Conversion of the stored value results in overflow.
E_POINTER - An invalid pointer was passed in.
GetMxSecurityClassification Method
Returns the value stored in the MxValue as an MxSecurityClassification.
Class
IMxValue
Syntax
[C#]
MxSecurityClassification GetMxSecurityClassification();
[Visual C++]
HRESULT GetMxSecurityClassification(
[out, retval] MxSecurityClassification *pVal
);
Parameters
pVal Receives the value.
Returns
S_OK - Success
MX_E_ConversionNotSupportedException - The stored value is a type that cannot be converted to MxSecurityClassification.
MX_E_UnableToConvertString - The string held in the MxValue cannot be converted to an MxSecurityClassification.
MX_E_Overflow - Conversion of the stored value results in overflow.
E_POINTER - An invalid pointer was passed in.
GRAccess Toolkit API User's Guide
Page 156
<page_number>156</page_number> Chapter 2 API Reference
GetMxDataQuality Method
Returns the value stored in the MxValue as an MxDataQuality.
Class
IMxValue
Syntax
[C#]
short GetMxDataQuality();
[Visual C++]
HRESULT GetMxDataQuality(
[out, retval] MxDataQuality *pVal
);
Parameters
pVal Receives the value.
Returns
S_OK - Success. MX_E_ConversionNotSupported - The stored value is a type that cannot be converted to MxMxDataQualityataType. MX_E_UnableToConvertString - The string held in the MxValue cannot be converted to an MxDataQuality. MX_E_Overflow - Conversion of the stored value results in overflow. E_POINTER - An invalid pointer was passed in.
GetCustomStruct Method
Returns the qualified struct stored in the MxValue.
Class
IMxValue
Syntax
[C#]
void GetCustomStruct (
out int pGuid,
out int pStructSize,
System.IntPtr pStruct
);
GRAccess Toolkit API User's Guide
Page 157
Interfaces <page_number>157</page_number>
[Visual C++]
HRESULT GetCustomStruct (
[out] long *pGuid,
[out] long *pStructSize,
[out, size_is(*pStructSize)] unsigned char **pStruct
);
Parameters
pGuid, Receives the quasi-GUID that uniquely identifies this struct. The BRO does not validate the GUID.
pStructSize, Receives the size of the struct held by the MxValue.
pStruct Address of the pointer which will receive the struct. The caller must call CoTaskMemFree on pStruct when it is finished using it.
Returns
S_OK - Success.
MX_E_ConversionNotSupported - The stored value is not a qualified struct.
E_POINTER - An invalid pointer was passed in.
GetCustomEnum Method
Returns the value stored in the MxValue as a qualified enum.
Class
IMxValue
Syntax
[C#]
void GetCustomEnum(
out string pValue,
out short pOrdinal,
out short pPrimitiveId,
out short pAttributeId
);
[Visual C++]
HRESULT GetCustomEnum (
[out] BSTR *pValue,
[out] short *pOrdinal,
[out] MxPrimitiveId *pPrimitiveId,
[out] MxAttributeId *pAttributeId
);
GRAccess Toolkit API User's Guide
Page 158
<page_number>158</page_number> Chapter 2 API Reference
Parameters
- pValue,
Receives the enumeration's string value. - pOrdinal,
Receives the enumeration's ordinal value. - pPrimitiveId,
Receives primitive ID of the primitive that contains the attribute holding an array of all the possible enumeration string values. - pAttributeId
Receives attribute ID of the attribute holding an array of all the possible enumeration string values.
Returns
- S_OK - Success.
- MX_E_ConversionNotSupportedException - The stored value is a type that cannot be converted to a qualified enum.
- E_POINTER - An invalid pointer was passed in.
GetDimensionCount Method
Indicates whether the MxValue holds an array. MxValue holds an array if PutElement has been called on it and there have been no subsequent calls to Empty or PutXxx (where Xxx is an Integer, Boolean or any of the other data type).
Class
IMxValue
Syntax
[C#]
void GetDimensionCount (
out short nDimensions
);
[Visual C++]
HRESULT GetDimensionCount (
[out] short *nDimensions
);
Parameters
nDimensions Returns 1 if the MxValue is an array or 0 if MxValue does not hold an array.
GRAccess Toolkit API User’s GuidePage 159
Interfaces <page_number>159</page_number>
PutElement Method
Puts an element into an array held by an MxValue. Call this method consecutively to populate an MxValue with an array of one dimension. The first call on this method will establish the MxDataType for the array. Subsequent calls to this method must supply MxValues of the same MxDataType.
Note: A array's dimension cannot be reduced. Therefore it is not a good idea to cache an MxValue. The array should be destroyed and recreated if its dimension needs to be reduced. Array elements must be written sequentially when initializing array values.
Syntax
[C#]
void PutElement (
int index,
MxValue pMxValue
);
[Visual C++]
HRESULT PutElement (
[in] long index,
[in] IMxValue *pMxValue
);
Parameters
- index Index into the array. Must be between 1 and 2147483647 inclusive.
- pMxValue The value to be put as an array element.
Returns
- MX_E_InvalidIndex - Index is out of range.
- MX_E_IndexOutOfOrder - Index is not sequential.
- MX_E_WrongDataType - A prior call to PutElement supplied an MxValue of a different data type.
GRAccess Toolkit API User's Guide
Page 160
<page_number>160</page_number> Chapter 2 API Reference
GetElement Method
Gets an element from an array held in an MxValue.
Class
IMxValue
Syntax
[C#]
void GetElement (
int index1,
MxValue pMxValue
);
[Visual C++]
HRESULT GetElement (
[in] long index1,
[in] IMxValue *pMxValue
);
Parameters
- index1 Index into the one-dimensional array.
- pMxValue Receives the specified element's value.
Returns
MX_E_InvalidIndex - Index is out of range.
MX_E_WrongNumberOfDimensions - This is not a one-dimensional array.
GetDimensionSize Method
Gets the size of the array held by the MxValue. MxValue determines the size of the array based on the max index value of prior calls to PutElement.
Class
IMxValue
Syntax
[C#]
void GetDimensionSize (
out int pSize
);
GRAccess Toolkit API User's Guide
Page 161
Interfaces <page_number>161</page_number>
[Visual C++]
HRESULT GetDimensionSize(
[out] long *pSize
);
Parameters
pSize Receives the specified dimension's size.
PutCustomStructVB Method
Stores a qualified struct in the MxValue for a VB client.
Class IMxValue
Syntax
[C#]
void PutCustomStructVB (
int guid,
ref byte[] pStruct
);
[Visual C++]
HRESULT PutCustomStructVB (
[in] long guid,
[in, out] SAFEARRAY(BYTE) *pStruct
);
GetCustomStructVB Method
Returns the qualified struct stored in the MxValue for a VB client.
Class IMxValue
Syntax
[C#]
void GetCustomStructVB (
out int pGuid,
ref byte[] pStruct
);
---
## Page 162
<page_number>162</page_number> Chapter 2 API Reference
[Visual C++]
```c++
HRESULT GetCustomStructVB(
[out] long *pGuid,
[in, out] SAFEARRAY(BYTE) *pStruct
);
PutInternationalStrings Method
Initializes an MxValue with a set of internationalized strings.
Class
IMxValue
Syntax
[C#]
void PutInternationalStrings(
int count,
ref InternationalizedString strings
);
[Visual C++]
HRESULT PutInternationalStrings(
[in] long count,
[in, size_is(count)] struct InternationalizedString strings[]
);
Parameters
count, The number of internationalized strings the MxValue is being initialized with.
strings[] The internationalized strings the MxValue is being initialized with.
Returns
S_OK - operation succeeded. E_FAIL - operation failed.
GRAccess Toolkit API User's Guide
Page 163
Interfaces <page_number>163</page_number>
PutInternationalStringsVB Method
Initializes an MxValue with a set of internationalized strings for a VB client.
Class IMxValue
Syntax
[C#]
void PutInternationalStringsVB(
ref InternationalizedString[] ppsa
);
[Visual C++]
HRESULT PutInternationalStringsVB (
[in] SAFEARRAY(struct InternationalizedString) *ppsa
);
Returns
S_OK - operation succeeded. E_FAIL - operation failed.
GetInternationalStrings Method
Returns the internationalized strings stored by the MxValue.
Class IMxValue
Syntax
[C#]
void GetInternationalStrings (
out int count,
System.IntPtr locals
);
[Visual C++]
HRESULT GetInternationalStrings (
[out] long *count,
[out, size_is(*count)] struct InternationalizedString **locals
);
GRAccess Toolkit API User's Guide
Page 164
<page_number>164</page_number> Chapter 2 API Reference
Parameters
count The number of internationalized strings that are stored in the MxValue.
locals The internationalized strings that are stored in the MxValue.
Returns
S_OK - operation succeeded. E_FAIL - operation failed. MX_E_WrongDataType - the stored value isn't an internationalized string.
GetInternationalStringsVB Method
Returns the internationalized strings stored by the MxValue for a VB client.
Class
IMxValue
Syntax
[C#]
void GetInternationalStringsVB(
ref InternationalizedString[] ppsa
);
[Visual C++]
HRESULT GetInternationalStringsVB(
[in, out] SAFEARRAY(struct InternationalizedString) *ppsa
//M1
);
Returns
S_OK - operation succeeded. E_FAIL - operation failed. MX_E_WrongDataType- the stored value isn't an internationalized string.
GRAccess Toolkit API User's Guide
Page 165
Interfaces <page_number>165</page_number>
GetInternationalString Method
Returns the internationalized string associated with a particular locale. The internationalized string for the locale passed in must have been added to the MxValue via calls to PutInternationalString, PutInternationalStringsVB, or PutInternationalStrings prior to calling this method.
Class
IMxValue
Syntax
[C#]
string GetInternationalString(
int locale
);
[Visual C++]
HRESULT GetInternationalString(
[in] long locale,
[out, retval] BSTR *internationalizedString
);
Parameters
locale, The locale of the internationalized string that is to be retrieved from the MxValue.
internationalizedString The internationalized string that corresponds to the locale passed in.
Returns
S_OK - operation succeeded. E_FAIL - operation failed. MX_E_WrongDataType - the stored value isn't an internationalized string. MX_E_LocaleNotSupported - the internationalized text doesn't exist for the locale passed in.
GRAccess Toolkit API User's Guide
Page 166
<page_number>166</page_number> Chapter 2 API Reference
PutInternationalString Method
Adds the internationalized string of a specific locale to the existing internationalized strings. Held by the MxValue. If the locale is already supported by the internationalized string then the string passed in overwrites the existing string for that locale.
Class
IMxValue
Syntax
[C#]
void PutInternationalString(
int locale,
string InternationalizedString
);
[Visual C++]
HRESULT PutInternationalString(
[in] long locale,
[in] BSTR internationalizedString
);
Parameters
locale, The locale of the internationalized string that is being set into the MxValue.
internationalizedString, The internationalized string that is to be set into the MxValue.
Returns
S_OK - operation succeeded. E_FAIL - operation failed.
GRAccess Toolkit API User's GuidePage 167
Interfaces <page_number>167</page_number>
IPermission
Provides read-only access to the properties of a single permission, including name, parent name, whether the permission is configured, if it has any children permissions, collection children permissions, whether it is a security group (root nodes in operation permission are). If the permission is a security group, IPermission can access the security group object.
Each role has two collections of permissions, a collection of general permissions and a collection of operational permissions, from which the client program can drill down to each sub-permission.
For example, for a role configured with the options shown in the sample Options dialog box, IPermission returns the following:
| Operation | What it returns |
|---|---|
| PermissionName | General Permission |
| PermissionParentName | Empty string |
| IsConfigured | Returns VARIANT_TRUE, or VARIANT_FALSE if any of its permission in the tree is configured |
| HasChildren | Returns VARIANT_TRUE |
| ChildPermissions | Returns the collection of IPermissions, which in this case is IDE Permissions and SMC Permissions |
| IsASecurityGroup | Returns VARIANT_FALSE. For "Operational Permissions" children, this property is VARIANT_TRUE. |
| SecurityGroup | Returns the ISecurityGroup object interface through which the user can access security group related properties. This property is valid for Operational Permission children. In other cases, this returns a NULL pointer. |
Page 168
<page_number>168</page_number> Chapter 2 API Reference
<img>Screenshot showing a tree-like structure titled "General permissions:" with two main categories expanded:
- IDE permissions
- ☑ Can start the IDE
- ☑ Importing and exporting
- ☑ General configuration
- ☑ System configuration
- ☑ DeviceIntegration objects
- ☑ Application configuration
- ☑ Framework configuration
- ☑ User configuration
- ☑ Deployment permissions
- ☑ Graphic management permissions
- SMC permissions
- ☑ Can start the SMC
- ☑ Can start/stop engine/platform
- ☑ Can write to gObject attributes using Obje </img>
<img>Screenshot showing a section titled "Operational permissions:" with one item:
- ☑ Default </img>
IPermission Class Members
This class has the following members.
Operations
PermissionName Property Returns the permission name.
PermissionParentName Property Returns the name of the permission's parent permission.
IsConfigured Property Returns whether the permission is configured; that is, whether the permission is active.
HasChildren Property Returns true if the permission has child permissions.
ChildPermissions Property Returns the collection of child permissions.
IsSecurityGroup Property Returns true if the permission is a security group.
SecurityGroup Property Retrieves the security group object.
GAccess Toolkit API User’s Guide
Page 169
Interfaces <page_number>169</page_number>
PermissionName Property
Returns the name of the permission.
Class
IPermission
Syntax
[C#]
string PermissionName { get; };
[Visual C++]
HRESULT PermissionName(
[out, retval] BSTR *permissionName
);
PermissionParentName Property
Returns the name of the permission's parent, if any. (For top-level permissions, this is an empty string.)
Class
IPermission
Syntax
[C#]
string PermissionParentName { get; };
[Visual C++]
HRESULT PermissionParentName(
[out, retval] BSTR *permissionParentName
);
IsConfigured Property
Returns true if the permission is configured; that is, if the permission is active.
Class
IPermission
Syntax
[C#]
bool IsConfigured { get; };
---
## Page 170
<page_number>170</page_number> Chapter 2 API Reference
[Visual C++]
```c++
HRESULT IsConfigured(
[out, retval] VARIANT_BOOL *isConfigured
);
HasChildren Property
Returns true if the permission has child permissions.
Class
IPermission
Syntax
[C#]
bool HasChildren { get; };
[Visual C++]
HRESULT HasChildren(
[out, retval] VARIANT_BOOL *hasChildren
);
ChildPermissions Property
Returns the collection of child permissions.
Class
IPermission
Syntax
[C#]
IPermissions ChildPermissions { get; };
[Visual C++]
HRESULT ChildPermissions(
[out, retval] IPermissions **childPermissions
);
---
## Page 171
Interfaces <page_number>171</page_number>
# IsSecurityGroup Property
Returns true if the permission is a security group.
**Class**
IPermission
**Syntax**
[C#]
```csharp
bool IsASecurityGroup { get; };
[Visual C++]
HRESULT IsASecurityGroup(
[out, retval] VARIANT_BOOL *isSecurityGroup
);
SecurityGroup Property
Retrieves the security group object.
Class
IPermission
Syntax
[C#]
ISecurityGroup SecurityGroup { get; };
[Visual C++]
HRESULT SecurityGroup(
[out, retval] ISecurityGroup **secGroup
);
IPermissions
Represents a collection of security permissions.
IPermissions Class Members
This class has the following members.
Operations
Item Property Returns a permission.
Count Property Returns the number of permissions in the collection.
GRAccess Toolkit API User's Guide
Page 172
<page_number>172</page_number> Chapter 2 API Reference
Item Property
Returns a permission.
Class
IPermissions
Syntax
[C#]
IPermission this[object galaxyIdentifier] { get; };
[Visual C++]
HRESULT Item(
[in] VARIANT galaxyIdentifier,
[out, retval] IPermission**
);
Parameters
- galaxyIdentifier The index of a permission. This is a numeric value from 1 to count, or the name of the permission.
- IPermission The returned permission.
Count Property
Returns the number of permissions in the collection.
Class
IPermissions
Syntax
[C#]
int count { get; };
[Visual C++]
HRESULT Count(
[out, retval] LONG*
);
Page 173
Interfaces <page_number>173</page_number>
IScriptLibraries
Represents a collection of script libraries.
IScriptLibraries Class Members
This class has the following members.
Operations
CommandResult Property Returns the CommandResult object, which has the last method call's result.
Item Property Return a script library.
Count Property Returns the number of script libraries in the collection.
Add Method Add a script library to the Galaxy.
CommandResult Property
Returns the CommandResult object, which has the last method call's result.
Class
IScriptLibraries
Syntax
[C#]
ICommandResult CommandResult { get; };
[Visual C++]
HRESULT CommandResult(
[out, retval] ICommandResult** CommandResult
);
Parameters
CommandResult Returns the CommandResult object.
GRAccess Toolkit API User's GuidePage 174
<page_number>174</page_number> Chapter 2 API Reference
Item Property
Return a script library.
Class
IScriptLibraries
Syntax
[C#]
IScriptLibrary this[object scriptLibraryIdentifier] { get; };
[Visual C++]
HRESULT Item(
[in] VARIANT scriptLibraryIdentifier,
[out, retval] IScriptLibrary**
);
Parameters
- scriptLibraryIdentifier The index of a script library. This is a numeric value from 1 to Count, or the name of the script library.
- IScriptLibrary The returned script library object.
Count Property
Returns the number of script library objects in the collection.
Class
IScriptLibraries
Syntax
[C#]
int count { get; };
[Visual C++]
HRESULT Count (
[out, retval] LONG*
);
GRAccess Toolkit API User's Guide
Page 175
Interfaces <page_number>175</page_number>
Add Method
Add a script library to the Galaxy.
Class
IScriptLibraries
Syntax
[C#]
void Add(
string scriptLibraryPath
);
[Visual C++]
HRESULT Add(
[in] BSTR scriptLibraryPath
);
Parameters
scriptLibraryPath Path to the .aaslib file containing the script library.
IScriptLibrary
Represents a script library.
IScriptLibrary Class Members
This class has the following members.
Operations
CommandResult Property Returns the CommandResult object, which has the last method call's result.
Export Method Export this script library.
Name Property Returns the name of the script library.
GRAccess Toolkit API User's GuidePage 176
<page_number>176</page_number> Chapter 2 API Reference
CommandResult Property
Returns the CommandResult object, which has the last method call's result.
Class
IScriptLibrary
Syntax
[C#]
ICommandResult CommandResult { get; };
[Visual C++]
HRESULT CommandResult(
[out, retval] ICommandResult** CommandResult
);
Parameters
CommandResult Returns the CommandResult object.
Export Method
Export this script library.
Class
IScriptLibrary
Syntax
[C#]
void Export(
string path
);
[Visual C++]
HRESULT Export(
[in] BSTR path
);
Parameters
path Path to copy the .aaslib file.
GRAccess Toolkit API User's Guide
Page 177
Interfaces <page_number>177</page_number>
Name Property
Returns the name of the script library.
Class
IScriptLibrary
Syntax
[C#]
string Name { get; };
[Visual C++]
HRESULT Name(
[out, retval] BSTR* theScriptLibrary
);
Parameters
theScriptLibrary The script library name.
ISecurityGroup
Accesses a security group object and its properties, including the security group name and the list of gObjects.
ISecurityGroup Class Members
This class has the following members.
Operations
GroupName Property Returns a security group name.
gObjects Property Returns the list of gObjects in this security group.
GroupName Property
Returns the security group name.
Class
ISecurityGroup
Syntax
[C#]
string GroupName { get; };
GRAccess Toolkit API User's Guide
Page 178
<page_number>178</page_number> Chapter 2 API Reference
[Visual C++]
HRESULT GroupName (
[out, retval] BSTR *groupName
);
Parameters
groupName The returned security group name.
gObjects Property
Returns the list of gObjects in this security group.
Class
ISecurityGroup
Syntax
[C#]
IgObjects gObjects { get; };
[Visual C++]
HRESULT gObjects (
[out, retval] IgObjects** *gObjects
);
Parameters
gObjects The list of gObjects in this security group.
ISecurityGroups
Represents a collection of security groups.
ISecurityGroups Class Members
This class has the following members.
Operations
Item Property Returns a security group.
Count Property Returns the number of security groups in the collection.
GRAccess Toolkit API User's Guide
Page 179
Interfaces <page_number>179</page_number>
Item Property
Returns a security group.
Class
ISecurityGroups
Syntax
[C#]
ISecurityGroup this[object galaxyIdentifier] { get; };
[Visual C++]
HRESULT Item(
[in] VARIANT galaxyIdentifier,
[out, retval] ISecurityGroup** securityGroup
);
Parameters
galaxyIdentifier The index of a Galaxy. This is a numeric value from 1 to Count, or the name of the security group.
securityGroup The returned security group.
Count Property
Returns the number of security groups in the collection.
Class
ISecurityGroups
Syntax
[C#]
int count { get; };
[Visual C++]
HRESULT Count (
[out, retval] LONG* count
);
Parameters
count Returns the number of security groups in the collection.
GRAccess Toolkit API User's GuidePage 180
<page_number>180</page_number> Chapter 2 API Reference
ISettings
Represents a settings object. Client configures the data for this settings object using the attributes of the instance property. After completed, the client calls Close to save and check-in the changes, or Cancel to undo the changes. While the settings object is being configured, no other object in the GR may be checked-out.
ISettings Class Members
This class has the following members.
Operations
CommandResult Property Returns the CommandResult object, which has the last method call's result.
Cancel Method Cancels the configuration of this object.
Instance Property Gets the instance for configuring this object.
Close Method Saves and checks in the settings object.
CommandResult Property
Returns the CommandResult object, which has the last method call's result.
Class
ISettings
Syntax
[C#]
ICommandResult CommandResult { get; };
[Visual C++]
HRESULT CommandResult(
[out, retval] ICommandResult** CommandResult
);
Parameters
CommandResult Returns the CommandResult object.
GRAccess Toolkit API User's Guide
Page 181
Interfaces <page_number>181</page_number>
Cancel Method
Cancels the configuration of this object.
Class ISettings
Syntax
[C#]
void Cancel();
[Visual C++]
HRESULT Cancel();
Instance Property
Get the instance for configuring this object.
Class ISettings
Syntax
[C#]
IInstance Instance { get; };
[Visual C++]
HRESULT Instance(
[out, retval] IInstance** anInstance
);
Parameters
- anInstance The instance to be used to configure the object.
Close Method
Saves and checks in the settings object.
Class ISettings
Syntax
[C#]
void Close();
[Visual C++]
HRESULT Close();
GRAccess Toolkit API User's Guide
Page 182
<page_number>182</page_number> Chapter 2 API Reference
ITemplate
Represents a Template object.
ITemplate Class Members
This class has the following members.
Operations
AddExtensionPrimitive Method Adds an extension primitive.
AddUDA Method Adds a UDA.
Area Property Returns or sets the area for this object.
Attributes Property Returns the collection of the object's attributes.
BasedOn Property Returns the name of the object's base template.
Category Property Returns the category of this object.
CategoryGUID Property Returns the category GUID for this object.
CheckIn Method Checks in the object.
CheckedOutBy Property Returns the user who has checked out this object.
CheckOut Method Checks out the object.
CheckoutStatus Property Returns the checkout status of this object.
CommandResult Property Returns the CommandResult object, which has the last method call results.
CommandResults Property Returns the CommandResults object, which has the last method call's result. Used for CreateInstances.
ConfigurableAttributes Property Returns a collection of the configurable attributes for this object.
ConfigVersion Property Returns the configuration version number.
ContainedName Property Returns or sets the contained name for this object.
GRAccess Toolkit API User's GuidePage 183
Interfaces <page_number>183</page_number>
Container Property Returns or sets the container for this object.
CreateInstance Method Create a new instance from this template.
CreateInstances Method Creates a collection of new instances from a template.
CreateTemplate Method Derive a new template from this template.
DeleteExtensionPrimitive Method Delete the extension primitive.
DeleteTemplate Method Deletes the template.
DeleteUDA Method Deletes a user defined attribute.
DerivedFrom Property Returns the name of the template this object was derived from.
EditStatus Property Returns the status of this object.
Errors Property Returns a list of errors generated the last time this object was validated and saved.
GetExtendedAttributes Method Returns a list of attributes for this object.
GetObjectHelpURL Method Returns the URL where the object's help is stored in the Galaxy repository.
HierarchicalName Property Returns the hierarchical name of this object.
Host Property Returns the name of this object's host.
RenameExtensionPrimitive Method Change the name of an extension primitive..
RenameUDA Method Changes the name of a user defined attribute.
Save Method Saves an object.
Tagname Property Returns the tagname of this object.
Toolset Property Returns the Toolset that this template belongs to.
UndoCheckOut Method Changes the object's checked out status without saving changes.
GRAccess Toolkit API User's GuidePage 184
<page_number>184</page_number> Chapter 2 API Reference
Unload Method Unloads the object's cache. The object remains usable.
UpdateUDA Method Change a user defined attribute.
ValidationStatus Property Returns the validation status information from the last time the object was validated and saved.
Warnings Property Returns a list of warnings from the last time the object was validated and saved.
AddExtensionPrimitive Method Adds an extension primitive to this object.
Class ITemplate
Syntax
[C#]
void AddExtensionPrimitive(
string ExtensionType,
string ExtensionPrimitiveName,
bool IsObjectExtension
);
[Visual C++]
HRESULT AddExtensionPrimitive(
// Type of extension
[in] BSTR ExtensionType,
// Name of extension primitive to be added -
// For attribute extension primitive - Fully
// qualified name of attribute being extended
// For object extension primitive - New name
// specified by user for object extension
// primitive
[in] BSTR ExtensionPrimitiveName,
// If wszName is the new name specified by user, // this
// field will be set to true. for example
// when add script pass true
[in, optional, defaultvalue( -1 )] VARIANT_BOOL
IsObjectExtension
);
GAccess Toolkit API User's Guide
Page 185
Interfaces <page_number>185</page_number>
AddUDA Method
Adds a UDA.
Class
ITemplate
Syntax
[C#]
void AddUDA(
string UDAName,
MxDataType DataType,
MxAttributeCategory category, MxSecurityClassification Security,
bool IsArray,
object ArrayElementCount
);
[Visual C++]
// Add a UDA
//
// Returns:
// S_OK - Successfully add a UDA
HRESULT AddUDA(
//Same XML format. But only one is allowed.
[in] BSTR UDAName,
[in] enum MxDataType Datatype,
[in] enum MxAttributeCategory Category,
[in] enum MxSecurityClassification Security,
[in] VARIANT_BOOL IsArray,
[in] VARIANT ArrayElementCount
);
Area Property
Get or set the area of this object. An AppObject area must be set using the SetContainer or SetHost methods. The object does not need to be checked out, and the operation is immediate.
Class
ITemplate
Syntax
[C#]
string Area { set; get; };
---
## Page 186
<page_number>186</page_number> Chapter 2 API Reference
[Visual C++]
```c++
// Returns name of the Area object, or blank if the // object doesn't have an Area.
[propget]
HRESULT Area(
[out, retval] BSTR* theArea
);
// Set the Area of this object.
[propput]
HRESULT Area(
// The name of the Area, or blank to unassign //from existing Area.
[in] BSTR NewArea
);
Attributes Property
Returns the collection of attributes of this object.
Class
ITemplate
Syntax
[C#]
IAttributes Attributes { get; };
[Visual C++]
// The collection of Attributes of this object.
// Configuring attributes requires that the object
// be checked out.
HRESULT Attributes(
// The collection of Attributes of this object.
[out, retval] IAttributes** theAttributes
);
GRAccess Toolkit API User's Guide
Page 187
Interfaces <page_number>187</page_number>
BasedOn Property
Returns the name of the base template for this object.
Class
ITemplate
Syntax
[C#]
string basedOn { get; };
[Visual C++]
// The name of the base template (root ancestor) of // this object.
HRESULT BasedOn(
// The name of the base template (root ancestor)
// of this object.
[out, retval] BSTR* theBaseTemplate
);
Category Property
Returns the category of this object.
Class
ITemplate
Syntax
[C#]
ECATEGORY category { get; };
[Visual C++]
// The Category of the object.
HRESULT Category(
// The Category of the object.
[out, retval] enum ECATEGORY* theCategory
);
---
## Page 188
<page_number>188</page_number> Chapter 2 API Reference
# CategoryGUID Property
Gets the category GUID of this object.
**Class**
ITemplate
**Syntax**
[C#]
VBGUID CategoryGUID { get; };
[Visual C++]
// The Category GUID of the object.
HRESULT CategoryGUID(
// The Category of the object.
[out, retval] VBGUID *categoryGUID
);
# CheckIn Method
Check in this object.
**Class**
ITemplate
**Syntax**
[C#]
void CheckIn(
string CheckInComment
);
[Visual C++]
// Checks in an object.
// Called on a checked-out object after it is
// configured and saved.
HRESULT CheckIn(
// Check in an object.
[in, optional] BSTR CheckInComment
);
GRAccess Toolkit API User's Guide
---
## Page 189
Interfaces <page_number>189</page_number>
# CheckedOutBy Property
Returns the name of the user who has checked out this object.
**Class**
ITemplate
**Syntax**
[C#]
```csharp
string checkedOutBy { get; };
[Visual C++]
// The name of the user that this object is checked // out by.
HRESULT CheckedOutBy(
// The name of the user that this object is
// checked out by.
[out, retval] BSTR* CheckedOutByUserName
);
CheckOut Method
Check out this object.
Class ITemplate
Syntax
[C#]
void CheckOut();
[Visual C++]
// Checks out an object.
HRESULT CheckOut();
CheckoutStatus Property
Returns the check out status of the object.
Class ITemplate
Syntax
[C#]
ECheckoutStatus CheckoutStatus { get; };
---
## Page 190
<page_number>190</page_number> Chapter 2 API Reference
[Visual C++]
```c++
// The check-out status of the object.
HRESULT CheckoutStatus(
// The check-out status of the object.
[out, retval] enum ECheckoutStatus* theCheckoutStatus
);
CommandResult Property
Returns the CommandResult object, which has the results from the last method call.
Class
ITemplate
Syntax
[C#]
ICommandResult CommandResult { get; };
[Visual C++]
// Returns the CommandResult Object, which has last // method call result
HRESULT CommandResult(
// Returns the CommandResult
[out, retval] ICommandResult** CommandResult
);
CommandResults Property
Returns the CommandResults object, which has the last method call's result. Used for CreateInstances
Class
ITemplate
Syntax
[C#]
ICommandResults CommandResults { get; };
[Visual C++]
HRESULT CommandResults(
[out, retval] ICommandResults** CommandResults
);
GAccess Toolkit API User's Guide
Page 191
Interfaces <page_number>191</page_number>
Parameters
CommandResults Returns the CommandResults object.
ConfigurableAttributes Property
Returns a collection of this object's attributes that can be configured.
Class
ITemplate
Syntax
[C#]
IAttributes ConfigurableAttributes { get; };
[Visual C++]
// The collection of Attributes of this object that // can be configured.
// Configuring attributes requires that the object // be checked out.
HRESULT ConfigurableAttributes(
// The collection of Attributes of this object
// that can be configured.
[out, retval] IAttributes** theConfigurableAttributes
);
ConfigVersion Property
Returns this object's configuration version number. The configuration version is incremented each time the object is checked in.
Class
ITemplate
Syntax
[C#]
int ConfigVersion { get; };
[Visual C++]
// The configuration version of the object.
HRESULT ConfigVersion(
// The configuration version of the object.
[out, retval] LONG* theConfigVersion
);
GRAccess Toolkit API User's Guide
Page 192
<page_number>192</page_number> Chapter 2 API Reference
ContainedName Property
Sets or returns this object's contained name. When setting the contained name, the object does not need to be checked out, and the operation is immediate.
Class
ITemplate
Syntax
[C#]
string ContainedName { set; get; };
[Visual C++]
// Returns Contained name of this object (eg. Inlet)
[propget]
HRESULT ContainedName(
// The contained name of this object (eg. Inlet)
[out, retval] BSTR* theContainedName
);
// Sets the contained name of this object (eg.
// Inlet)
// The object does not need to be checked out; the
// operation is immediate.
[propput]
HRESULT ContainedName(
// The contained name of this object (eg. Inlet)
[in] BSTR newContainedName
);
Container Property
Returns or sets the container for this object. When setting the container the object does not need to be checked out, and the change is immediate. For an ApplicationObject, the ApplicationObject's Area and Host area are also updated.
Class
ITemplate
Syntax
[C#]
string Container { set; get; };
---
## Page 193
Interfaces <page_number>193</page_number>
[Visual C++]
```c++
// Returns name of the Container object, or blank if //object is
// not contained.
[propget]
HRESULT Container(
// The name of the Container object, or blank if // the
// object is not contained.
[out, retval] BSTR* theContainer
);
// Set the Container for this object.
[propput]
HRESULT Container(
// The name of the container, or blank to
// uncontain.
[in] BSTR NewContainer
);
CreateInstance Method
Create a new Instance from this template.
Class
ITemplate
Syntax
[C#]
IInstance CreateInstance(
string Name,
bool createContainedObjects
);
[Visual C++]
HRESULT CreateInstance(
[in] BSTR Name,
[in, optional, defaultvalue( 1 )] VARIANT_BOOL createContainedObjects,
[out, retval] IInstance**
);
GRAccess Toolkit API User's Guide
Page 194
<page_number>194</page_number> Chapter 2 API Reference
Parameters
Name The name of the newly created instance.
createContainedObjects Set to True to create contained objects.
IInstance The instance that was created.
CreateInstances Method
Creates a collection of new instances from a template.
Class
ITemplate
Syntax
[C#]
IgObjects CreateInstances(
ref string[] tagnames,
bool createContainedObjects
);
[Visual C++]
HRESULT CreateInstances(
[in, out] SAFEARRAY(BSTR)* tagnames,
[in, optional, defaultvalue( 1 )] VARIANT_BOOL createContainedObjects,
[out, retval] IgObjects**
);
Parameters
tagnames An array of unique tagnames for the newly created instances.
createContainedObjects Set to true to create contained objects.
IgObjects The instances that were created.
GRAccess Toolkit API User's GuidePage 195
Interfaces <page_number>195</page_number>
CreateTemplate Method
Derive an a new template from this template.
Class
ITemplate
Syntax
[C#]
ITemplate CreateTemplate(
string Name,
bool createContainedObjects
);
[Visual C++]
HRESULT CreateTemplate(
[in] BSTR Name,
[in, optional, defaultvalue( 1 )] VARIANT_BOOL createContainedObjects,
[out, retval] ITemplate**
);
Parameters
- Name
- The name of the newly created template.
- createContainedObjects
- Set to true to create contained objects.
- ITemplate
- The template that was created.
DeleteExtensionPrimitive Method
Deletes an extension.
Class
ITemplate
Syntax
[C#]
void DeleteExtensionPrimitive(
string ExtensionType,
string ExtensionPrimitiveName
);
GRAccess Toolkit API User's Guide
Page 196
<page_number>196</page_number> Chapter 2 API Reference
[Visual C++]
// Delete an extension primitive
//
// Returns S_OK
HRESULT DeleteExtensionPrimitive(
// Type of extension
[in] BSTR ExtensionType,
// Name of Extension primitive to be deleted.
[in] BSTR ExtensionPrimitiveName
);
DeleteTemplate Method
Deletes the template.
Class
ITemplate
Syntax
[C#]
void DeleteTemplate(
EForceDeleteTemplateOption ForceDeleteTemplateOption
);
[Visual C++]
HRESULT DeleteTemplate(
[in, optional, defaultvalue( dontForceTemplateDelete ) ]
EForceDeleteTemplateOption ForceDeleteTemplateOption
);
Parameters
ForceDeleteTemplateOption Indicates whether descendent instances should be undeployed prior to deletion.
GRAccess Toolkit API User's Guide
Page 197
Interfaces <page_number>197</page_number>
DeleteUDA Method
Deletes a UDA.
Class ITemplate
Syntax
[C#]
void DeleteUDA(
string UDAName
);
[Visual C++]
// Delete a UDA
//
// Returns:
// S_OK - Successfully delete a UDA
HRESULT DeleteUDA (
// Delete an UDA by UDA name.
[in] BSTR UDAName
);
DerivedFrom Property
Returns the name of the object's template.
Class ITemplate
Syntax
[C#]
string DerivedFrom { get; };
[Visual C++]
// Returns the name of the template that this object // was created from.
[propget]
HRESULT DerivedFrom (
// The name of the template that this object was // created from.
[out, retval] BSTR* theParentTemplate
);
---
## Page 198
<page_number>198</page_number> Chapter 2 API Reference
# EditStatus Property
Edit the status of the object.
## Class
ITemplate
## Syntax
[C#]
```csharp
EEditStatus EditStatus { get; };
[Visual C++]
// The edit status of the object.
HRESULT EditStatus(
// The edit status of the object.
[out, retval] enum EEditStatus* theEditStatus
);
Errors Property
Retrieves the list of errors generated when the object was last validated and saved.
Class
ITemplate
Syntax
[C#]
string[] Errors { get; };
[Visual C++]
// The list of errors that got generated the last
// time the object was validated and saved.
HRESULT Errors(
// The list of errors that got generated the last // time the
// object was validated and saved.
[out, retval] SAFEARRAY(BSTR) * theErrors
);
---
## Page 199
Interfaces <page_number>199</page_number>
# GetExtendedAttributes Method
Get the extended attributes in the hierarchy.
**Class**
ITemplate
**Syntax**
**[C#]**
```csharp
IAttributes GetExtendedAttributes(
string AttributeName,
int upto_level,
MxAttributeCategory[] ReturnOnlyTheseCategories
);
[Visual C++]
//Get Extended Attributes in Hierarchy
HRESULT GetExtendedAttributes (
//Attribute full name which is extended
[in] BSTR AttributeName,
//Up to how many level user needs extended
//primitives
//-1 will return all levels
[in] int upto_level,
//Return attributes which are only these
//categories. If safearray is empty returns all
//attributes.
[in] SAFEARRAY(MxAttributeCategory) ReturnOnlyTheseCategories,
//Return attributes
[out, retval] IAttributes** theAttributes
);
---
## Page 200
<page_number>200</page_number> Chapter 2 API Reference
# GetObjectHelpURL Method
Returns the URL where the object help is stored on the Galaxy repository.
**Class**
ITemplate
**Syntax**
[C#]
```csharp
string GetObjectHelpURL();
[Visual C++]
// Returns the URL to where the Object Help is
// stored on the Galaxy Repository.
// The client can display the URL in
// InternetExplorer or use web publishing
// to change the data.
HRESULT GetObjectHelpURL(
// Returns the URL to where the Object Help is
//stored on the GR.
[out, retval] BSTR*
);
HierarchicalName Property
Returns the hierarchical name of this object.
Class
ITemplate
Syntax
[C#]
string HierarchicalName { get; };
[Visual C++]
// The Hierarchical name of this object. (eg.
//Reactor.Tank.Inlet)
HRESULT HierarchicalName(
// The hierarchical name of this object. (eg.
//Reactor.Tank.Inlet)
[out, retval] BSTR* theHierarchicalName
);
GRAccess Toolkit API User's Guide
Page 201
Interfaces <page_number>201</page_number>
Host Property
Returns or sets the name of this object's host.
Class
ITemplate
Syntax
[C#]
string Host { set; get; }
[Visual C++]
// Retrieve the name of the Host for this object, or // blank if unassigned.
[propget]
HRESULT Host (
// The name of the Host for this object.
[out, retval] BSTR* theHost
);
// Set the Host for this object.
// If this object is an ApplicationObject, its Area
// And container area also updated.
// The object does not need to be checked out; the
// operation is immediate.
[propput]
HRESULT Host (
// The name of the Host, or blank to unassign
//from existing Host.
[in] BSTR NewHost
);
RenameExtensionPrimitive Method
Rename the object extension primitive.
Class
ITemplate
Syntax
[C#]
void RenameExtensionPrimitive(
string OldPrimitiveName,
string NewPrimitiveName
);
GRAccess Toolkit API User's Guide
Page 202
<page_number>202</page_number> Chapter 2 API Reference
[Visual C++]
// Rename an object extension primitive
//
// Returns S_OK
HRESULT RenameExtensionPrimitive(
// Old name of primitive extension
[in] BSTR OldPrimitiveName,
// New name specified by user
[in] BSTR NewPrimitiveName
);
RenameUDA Method
Change the name of a UDA.
Class
ITemplate
Syntax
[C#]
void RenameUDA(
string OldUDAName,
string NewUDAName
);
[Visual C++]
// Rename a UDA
//
// Returns:
//
// S_OK - Successfully rename a UDA
HRESULT RenameUDA(
// The old external name of the primitive
[in] BSTR OldUDAName,
// The new external name of the primitive
[in] BSTR NewUDAName
);
GAccess Toolkit API User's Guide
Page 203
Interfaces <page_number>203</page_number>
Save Method
Save the object.
Class ITemplate
Syntax
[C#]
void Save();
[Visual C++]
// Saves the object after it's configured.
// Object must be checked out.
HRESULT Save();
Tagname Property
Returns or sets this object's tagname.
Class ITemplate
Syntax
[C#]
string Tagname { set; get; }
[Visual C++]
// Returns the Tagname of this object.
[propget]
HRESULT Tagname(
// The Tagname of this object.
[out, retval] BSTR* theTagname
);
// Sets the Tagname of this object.
// The object does not need to be checked out; the
// operation is immediate.
[propput]
HRESULT Tagname(
// The Tagname of this object.
[in] BSTR newTagName
);
GRAccess Toolkit API User's Guide
Page 204
<page_number>204</page_number> Chapter 2 API Reference
Toolset Property
Returns the Toolset that this template belongs to.
Class
ITemplate
Syntax
[C#]
string Toolset { set; get; }
[Visual C++]
[propget]
HRESULT Toolset(
[out, retval] BSTR* theToolset
);
[propput]
HRESULT Toolset(
[in] BSTR theToolset
);
Parameters
theToolset The Toolset that this template belongs to.
UndoCheckOut Method
Reverses the check out operation without making changes.
Class
ITemplate
Syntax
[C#]
void UndoCheckOut();
[Visual C++]
// Undo check-out this object.
HRESULT UndoCheckOut();
GRAccess Toolkit API User's Guide
Page 205
Interfaces <page_number>205</page_number>
Unload Method
Unload the object cache, releasing internal resources obtained by the object during operations. After executing this method, the object is still available. Internal resources will be reloaded as necessary.
Class
ITemplate
Syntax
[C#]
void Unload();
[Visual C++]
// Unloads the gObject cache. This method doesn't
// affect functionality. It's used to release
// internal resources obtained by the object during
// operations.
//
// After this method is called, the object is still // usable
// and will reload the internal resources as // needed.
HRESULT Unload();
UpdateUDA Method
Save the UDA information.
Class
ITemplate
Syntax
[C#]
void UpdateUDA(
string wszUDAInfo,
MxDataType DataType,
MxAttributeCategory category,
MxSecurityClassification Security,
bool IsArray,
object ArrayElementCount
);
[Visual C++]
// Update a UDA
//
// Returns:
//
// S_OK - Successfully update a UDA
---
## Page 206
<page_number>206</page_number> Chapter 2 API Reference
```csharp
HRESULT UpdateUDA(
// Same XML format. But only one is allowed. The // new info
// will overwrite the old info.
[in] BSTR wszUDAInfo,
[in] enum MxDataType Datatype,
[in] enum MxAttributeCategory Category,
[in] enum MxSecurityClassification Security,
[in] VARIANT_BOOL IsArray,
[in] VARIANT ArrayElementCount
);
ValidationStatus Property
Returns this object's validation status.
Class
ITemplate
Syntax
[C#]
EPACKAGESTATUS ValidationStatus { get; };
[Visual C++]
// The ValidationStatus of this object based on the // last time
// the object was validated and saved.
HRESULT ValidationStatus(
// The validation status of the object.
[out, retval] enum EPACKAGESTATUS* theValidationStatus
);
Warnings Property
Returns the list of warnings generated the last time the object was validated and saved.
Class
ITemplate
Syntax
[C#]
string[] Warnings { get; };
---
## Page 207
Interfaces <page_number>207</page_number>
[Visual C++]
```c++
// The list of warnings that got generated the last // time the object was validated and saved.
HRESULT Warnings(
// The list of warnings that got generated the //last time the object was validated and saved.
[out, retval] SAFEARRAY(BSTR)* theWarnings
);
IToolset
Represents a toolset.
IToolset Class Members
This class has the following members.
Operations
CommandResult Property Returns the CommandResult object, which has the last method call's result.
GetChildToolsets Method Retrieves the list of child toolsets.
MoveToToolset Method Moves the toolset to a new parent toolset.
Name Property Returns the name of the toolset.
Rename Method Renames this toolset.
CommandResult Property
Returns the CommandResult object, which has the last method call's result.
Class
IToolset
Syntax
[C#]
ICommandResult CommandResult { get; };
[Visual C++]
HRESULT CommandResult(
[out, retval] ICommandResult** CommandResult
);
GRAccess Toolkit API User's Guide
Page 208
<page_number>208</page_number> Chapter 2 API Reference
Parameters
CommandResult Returns the CommandResult object.
GetChildToolsets Method
Retrieves the list of child toolsets.
Class IToolset
Syntax
[C#]
IToolsets GetChildToolsets(
int depth
);
[Visual C++]
// Retrieves the list of child Toolsets.
HRESULT GetChildToolsets(
// the level of children to retrieve: pass -1 for N.
[in] int depth,
[out, retval] IToolsets** toolsets
);
MoveToToolset Method
Moves the toolset to a new parent toolset.
Class IToolset
Syntax
[C#]
void MoveToToolset(
string parentToolset
);
[Visual C++]
// Moves toolset to a new parent toolset
HRESULT MoveToToolset(
[in] BSTR parentToolset
);
GRAccess Toolkit API User's Guide
Page 209
Interfaces <page_number>209</page_number>
Name Property
Returns the name of the toolset.
Class IToolset
Syntax
[C#]
string Name { get; };
[Visual C++]
HRESULT Name(
[out, retval] BSTR* theToolset
);
Parameters
theToolset The toolset name.
Rename Method
Renames this toolset.
Syntax
[C#]
void Rename(
string newName
);
[Visual C++]
HRESULT Rename (
[in] BSTR newName
);
Parameters
newName The new name of the toolset.
GRAccess Toolkit API User's Guide
Page 210
<page_number>210</page_number> Chapter 2 API Reference
IToolsets
Represents a collection of toolsets.
IToolsets Class Members
This class has the following members.
Operations
Add Method Add a new toolset to the Galaxy.
AddToolSet Method Add a new toolset to the Galaxy.
DeleteToolSet Method Delete the toolset from the Galaxy.
Item Property Returns a toolset.
Count Property Returns the number of toolsets in the collection.
Add Method
Add a new toolset to the Galaxy.
Class
IToolsets
Syntax
[C#]
void Add(
string newToolst
);
[Visual C++]
HRESULT Add(
[in] BSTR newToolst
);
Parameters
newToolset The name of the new toolset.
GRAccess Toolkit API User's GuidePage 211
Interfaces <page_number>211</page_number>
AddToolSet Method
Add the toolset to the Galaxy.
Class IToolsets
Syntax
[C#]
void AddToolSet(
string parentToolset,
string newToolset
);
[Visual C++]
// Add a new toolset to the Galaxy.
HRESULT AddToolSet(
[in] BSTR parentToolset,
[in] BSTR newToolset
);
DeleteToolSet Method
Delete the toolset from the Galaxy.
Class IToolsets
Syntax
[C#]
void DeleteToolSet(
string toolsetToDelete
);
[Visual C++]
// Delete an existing toolset from the Galaxy.
HRESULT DeleteToolSet(
[in] BSTR toolsetToDelete
);
---
## Page 212
<page_number>212</page_number> Chapter 2 API Reference
# Item Property
Return a toolset.
## Class
IToolsets
## Syntax
[C#]
```csharp
IToolset this[object toolsetIdentifier] { get; };
[Visual C++]
HRESULT Item(
[in] VARIANT toolsetIdentifier,
[out, retval] IToolset**
);
Parameters
- toolsetIdentifier The index of a toolset. This is a numeric value from 1 to Count. Or it is the name of the toolset.
- IToolset The returned toolset.
Count Property
Returns the number of toolsets in the collection.
Class
IToolsets
Syntax
[C#]
int count { get; };
[Visual C++]
HRESULT Count (
[out, retval] LONG*
);
GRAccess Toolkit API User's Guide
Page 213
Type Definitions <page_number>213</page_number>
Type Definitions
This section describes the enumerations defined and exposed through GRAccess. These include:
- EATTRIBUTEPROPERTY
- EActionForCurrentlyDeployedObjects
- EAuthenticationMode
- EAutomaticallyUndocheckout
- EBASERUNTIMEOBJECT
- ECATEGORY
- ECOMMONATTRIBUTES
- ECOMMONPRIMITIVE
- ECascade
- ECheckoutStatus
- EConditionType
- EDeployOnScan
- EDeploymentStatus
- EEXECUTIONGROUP
- EEditStatus
- EExecutionOrder
- EExportType
- EFileType
- EForceDeleteInstanceOption
- EForceDeleteTemplateOption
- EForceOffScan
- EGRCommandResult
- EMatch
- EPACKAGESTATUS
- ERESERVEDPRIMITIVEIDS
- ESkipIfCurrentlyUndeployed
- ESkipObjectsWithPendingUpdates
- ESkipOtherUsersCheckedOutObjects
- ETestOnly
Page 214
<page_number>214</page_number> Chapter 2 API Reference
- EUserDefaults
- EgObjectIsTemplateOrInstance
- MxAttributeCategory
- MxPropertyLockedEnum
EATTRIBUTEPROPERTY
Lists property IDs of all attributes.
enum EATTRIBUTEPROPERTY
{ idxAttribPropUndefined = -1
idxAttribPropName = 0,
idxAttribPropAttributeCategory = 1,
idxAttribPropCfgSethandler = 2,
idxAttribPropRtSethandler = 3,
idxAttribPropType = 4,
idxAttribPropUpperBoundDim1 = 5,
idxAttribPropValue = 10,
idxAttribPropSecurityClassification = 11,
idxAttribPropLocked = 12,
idxAttribPropQuality = 13,
idxAttribPropBit00 = 14,
idxAttribPropBit01 = 15,
idxAttribPropBit02 = 16,
idxAttribPropBit03 = 17,
idxAttribPropBit04 = 18,
idxAttribPropBit05 = 19,
idxAttribPropBit06 = 20,
idxAttribPropBit07 = 21,
idxAttribPropBit08 = 22,
idxAttribPropBit09 = 23,
idxAttribPropBit10 = 24,
idxAttribPropBit11 = 25,
idxAttribPropBit12 = 26,
idxAttribPropBit13 = 27,
idxAttribPropBit14 = 28,
Page 215
Type Definitions <page_number>215</page_number>
idxAttribPropBit15 = 29,
idxAttribPropBit16 = 30,
idxAttribPropBit17 = 31,
idxAttribPropBit18 = 32,
idxAttribPropBit19 = 33,
idxAttribPropBit20 = 34,
idxAttribPropBit21 = 35,
idxAttribPropBit22 = 36,
idxAttribPropBit23 = 37,
idxAttribPropBit24 = 38,
idxAttribPropBit25 = 39,
idxAttribPropBit26 = 40,
idxAttribPropBit27 = 41,
idxAttribPropBit28 = 42,
idxAttribPropBit29 = 43,
idxAttribPropBit30 = 44,
idxAttribPropBit31 = 45,
idxAttribPropValueReadOnly = 46,
idxAttribPropSecurityClassificationReadOnly = 47,
idxAttribPropLockedReadOnly = 48,
idxAttribPropTime = 49,
idxAttribPropBuffer = 50,
idxAttribPropHasBuffer = 51,
idxAttribPropEND = 46
}
Members
idxAttribPropType MxDataTypeEnum
idxAttribPropUndefined
idxAttribPropUpperBoundDim1 MxInteger
idxAttribPropQuality MxDataQualityEnum
idxAttribPropAttributeCategory MxInteger
GRAccess Toolkit API User's Guide
Page 216
<page_number>216</page_number> Chapter 2 API Reference
idxAttribPropLocked MxInteger idxAttribPropBit05 idxAttribPropBit02 idxAttribPropBit00 idxAttribPropBit01 idxAttribPropBit03 idxAttribPropBit04 idxAttribPropBit06 idxAttribPropBit07 idxAttribPropBit08 idxAttribPropBit09 idxAttribPropBit10 idxAttribPropBit11 idxAttribPropBit12 idxAttribPropBit13 idxAttribPropBit14 idxAttribPropBit15 idxAttribPropBit16 idxAttribPropBit17 idxAttribPropBit18 idxAttribPropBit19 idxAttribPropBit20 idxAttribPropBit21 idxAttribPropBit22 idxAttribPropBit23 idxAttribPropSecurityClassification MxSecurityClassificationEnum idxAttribPropBit24 idxAttribPropBit25 idxAttribPropBit26 idxAttribPropBit27 idxAttribPropBit28 idxAttribPropBit29 idxAttribPropBit30
GRAccess Toolkit API User's Guide
Page 217
Type Definitions <page_number>217</page_number>
idxAttribPropRtSethandler MxBoolean
idxAttribPropBit31
idxAttribPropValueReadOnly MxBoolean
idxAttribPropSecurityClassificationReadOnly MxBoolean
idxAttribPropLockedReadOnly MxBoolean
idxAttribPropTime MxDouble
idxAttribPropBuffer MxBoolean
idxAttribPropHasBuffer MxCustomStruct
idxAttribPropEND
idxAttribPropValue Depends on datatype
idxAttribPropName MxString
idxAttribPropCfgSethandler MxBoolean
EActionForCurrentlyDeployedObjects
Action for currently deployed objects.
enum EActionForCurrentlyDeployedObjects
{
skipDeploy = 0,
redeployOriginal = 1,
deployChanges = 2
}
Members
deployChanges Deploy updated versions.
skipDeploy Skip if currently deployed.
redeployOriginal redeploy original version.
GRAccess Toolkit API User's Guide
Page 218
<page_number>218</page_number> Chapter 2 API Reference
EAuthenticationMode
Indicates whether operating system or Galaxy authentication should be used.
enum EAuthenticationMode
{
osAuthenticationMode = 0,
galaxyAuthenticationMode = 1,
}
Members
galaxyAuthenticationMode Galaxy Authentication Mode
osAuthenticationMode OS Authentication Mode
EAutomaticallyUndocheckout
Automatically undoes checkout.
enum EAutomaticallyUndocheckout
{
dontAutomaticallyUndocheckout = 0,
doAutomaticallyUndocheckout = 1
}
Members
dontAutomaticallyUndocheckout Fail if any object is checked out to the current user.
doAutomaticallyUndocheckout Automatically undoes checkout of any check-outs to the current user before processing.
EBASERUNTIMEOBJECT
Specifies the IDs of the attributes of the base run time object to be used for deployment.
enum EBASERUNTIMEOBJECT
{
idxBROAttributeUndefined = -1,
idxBROPriimitiveList = 100,
idxBRODeployComplete = 101,
}
Page 219
Type Definitions <page_number>219</page_number>
idxBROCreateDynamicAttributes = 102,
idxBRODumpState = 103
}
Members
idxBROAttributeUndefined idxBROPrimitiveList Array of MxQualifiedStruct - primitiveId, parentId, primitiveGUID. idxBRODeployComplete MxBoolean idxBROCreateDynamicAttributes idxBRODumpState
ECATEGORY
Lists categories of attributes.
enum ECATEGORY { idxCategoryUndefined = 0, idxCategoryPlatformEngine = 1, idxCategoryClusterEngine = 2, idxCategoryApplicationEngine = 3, idxCategoryViewEngine = 4, idxCategoryProductEngine = 5, idxCategoryHistoryEngine = 6, idxCategoryPrintEngine = 7, idxCategoryOutpost = 8, idxCategoryQueryEngine = 9, idxCategoryApplicationObject = 10, idxCategoryIONetwork = 11, idxCategoryIODEVice = 12, idxCategoryArea = 13, idxCategoryUserProfile = 14, idxCategoryDisplay = 15, idxCategorySymbol = 16, idxCategoryViewApp = 17, }
GRAccess Toolkit API User's Guide
Page 220
<page_number>220</page_number> Chapter 2 API Reference
idxCategoryProductionObject = 18,
idxCategoryReport = 19,
idxCategorySharedProcedure = 20,
idxCategoryInsertablePrimitive = 21,
idxCategoryIDEMacro = 22,
idxCategoryGalaxy = 23
}
Members
idxCategoryViewApp idxCategoryViewEngine idxCategoryOutpost idxCategoryApplicationObject idxCategoryUserProfile idxCategoryReport idxCategoryGalaxy idxCategoryPlatformEngine idxCategoryIDEMacro idxCategoryUndefined idxCategoryHistoryEngine idxCategoryPrintEngine idxCategoryClusterEngine idxCategoryDisplay idxCategoryProductEngine idxCategoryApplicationEngine idxCategorySymbol idxCategoryProductionObject idxCategoryInsertablePrimitive idxCategoryQueryEngine idxCategoryIODevice idxCategoryArea idxCategorySharedProcedure idxCategoryIONetwork
GRAccess Toolkit API User's Guide
Page 221
Type Definitions <page_number>221</page_number>
ECOMMONATTRIBUTES
Lists the attributes common to all primitives.
enum ECOMMONATTRIBUTES { idxComAttUnknown = -1, idxComAttExternalName = 1, idxComAttInternalName = 2 }
Members
idxComAttExternalName idxComAttInternalName idxComAttUnknown
ECOMMONPRIMITIVE
Specifies the IDs of the attributes of the common primitive.
enum ECOMMONPRIMITIVE { idxCommonUndefined = -1, idxCommonExternalName = 1, idxCommonInternalName = 2, idxCommonTagname = 100, idxCommonShortDescription = 101, idxCommonCategoryIDEnum = 102, idxCommonAttributes = 103, idxCommonCmdScanState = 104, idxCommonScanState = 105, idxCommonSecurityGroup = 106, idxCommonError = 107, idxCommonRelativeOrderEnum = 108, idxCommonArea = 109, idxCommonContainer = 110, idxCommonHost = 111, idxCommonAlarmModeEnum = 112, idxCommonAlarmMode = 113, }
GRAccess Toolkit API User's Guide
Page 222
<page_number>222</page_number> Chapter 2 API Reference
idxCommonAlarmModeCmd = 114,
idxCommonAlarmInhibit = 115,
idxCommonInAlarm = 116,
idxCommonBasedOn = 117,
idxCommonIsTemplate = 118,
idxCommonCodeBase = 119,
idxCommonUDAs = 120,
idxCommon_InheritedUDAs = 121,
idxCommonExtensions = 122,
idxCommon_InheritedExtensions = 123,
idxCommon_Category = 124,
idxCommon_ConfigVersion = 125,
idxCommon_Warnings = 126,
idxCommonContainedName = 127,
idxCommonExecutionRelatedObject = 128,
idxCommonExecutionRelativeOrder = 129,
idxCommonHierachicalName = 130,
idxCommonMinorVersion = 131
}
Members
idxCommonAlarmMode idxCommonBasedOn idxCommonExecutionRelatedObject idxCommonContainedName idxCommonInAlarm idxCommonCategoryIDEnum idxCommonCategoryEnum idxCommonExecutionRelativeOrder idxCommonUndefined idxCommonSecurityGroup idxCommon_Warnings idxCommonAlarmModeEnum idxCommonInternalName idxCommon_InheritedUDAs
GRAccess Toolkit API User's Guide
Page 223
Type Definitions <page_number>223</page_number>
idxCommon_InheritedExtensions idxCommonShortDescription idxCommonExtensions idxCommonHierachicalName idxCommonExternalName idxCommonCodeBase idxCommonRelativeOrderEnum idxCommonExecutionRelativeOrderEnum idxCommonUDAs idxCommonContainer idxCommonAlarmInhibit idxCommonArea idxCommonHost idxCommonTagname idxCommonError idxCommonErrors idxCommonAttributes idxCommon_Category idxCommonCmdScanState idxCommonScanStateCmd idxCommon_ConfigVersion this is for ConfigVersion idxCommonScanState idxCommonScanStateActual idxCommonMinorVersion idxCommonAlarmModeCmd idxCommonIsTemplate
GRAccess Toolkit API User's Guide
Page 224
<page_number>224</page_number> Chapter 2 API Reference
ECascade
Cascade operation.
enum ECascade
{
dontCascade = 0,
doCascade = 1,
}
Members
dontCascade Don't cascade
doCascade Do force off scan
ECheckoutStatus
Indicates the check-out status of an object.
enum ECheckoutStatus
{
notCheckedOut = 0,
checkedOutToMe = 1,
checkedOutToSomeoneElse = 2
}
Members
notCheckedOut The object is not checked-out.
checkedOutToSomeoneElse The object is checked out to someone else.
checkedOutToMe The object is checked out the currently logged-in user.
GRAccess Toolkit API User's Guide
Page 225
Type Definitions <page_number>225</page_number>
EConditionType
Used by the querying methods to get a list of objects from the GR. Indicates the type of condition used by the query.
enum EConditionType
{
derivedOrInstantiatedFrom = 1,
basedOn = 2,
containedBy = 3,
hostEngineIs = 4,
belongsToArea = 5,
assignedTo = 6,
withinSecurityGroup = 7,
createdBy = 8,
lastModifiedBy = 9,
checkedOutBy = 10,
namedLike = 11,
validationStatusIs = 12,
deploymentStatusIs = 13,
checkoutStatusIs = 14,
objectCategoryIs = 15,
hierarchicalNameLike = 16,
NameEquals = 17
NameSpaceddls = 18
}
Members
derivedOrInstantiatedFrom Search for objects that are derived or instantiated from the given template (first level children only.)
objectCategoryIs Search for objects with the check-out status. Value parameter should be the numeric value represented by ECATEGORY.
deploymentStatusIs Search for objects with the given deployment status. Value parameter should be the numeric value represented by EDeploymentStatus.
GRAccess Toolkit API User's Guide
Page 226
<page_number>226</page_number> Chapter 2 API Reference
hierarchicalNameLike Search for objects whose hierarchical name is like the given text.
belongsToArea Search for objects whose Area is the given object.
withinSecurityGroup Search for objects that match the given security group.
lastModifiedBy Search for objects that were modified by the given user.
checkedOutBy Search for objects that are checked out by the given user.
validationStatusIs Search for objects with the given validation status. Value parameter should be the numeric value represented by EPACKAGESTATUS.
hostEngineIs Search for objects hosted by the given engine (Domain objects of an AppEngine or Engines of a Platform.)
namedLike Search for objects whose name is like the given text.
NameEquals Search for objects whose name is equal to the given text.
NameSpaceIdIs Search for NameSpaceId equal to the value of AutomationObject = 1, BackupObject = 2 or VisualElement = 3
containedBy Search for objects contained by the given object.
checkoutStatusIs Search for objects with the check-out status. Value parameter should be the numeric value represented by ECheckoutStatus.
createdBy Search for objects that were created by the given user.
assignedTo Search for objects hosted by the given object (ApplicationObjects or IONetworks of an Area, IODevices of an IONetwork, Domain objects of an AppEngine, or Engines of a Platform)
basedOn Search for objects that are based on or instantiated from the given base template (all descendents).
ShowInArchestraBrowser Search for Objects that "show_in_archestra_browser" == given value
GAccess Toolkit API User's Guide
Page 227
Type Definitions <page_number>227</page_number>
objectCategoryGUIDIs Search Objects with “object category guid” = = given value.
HasExtensionType Search automation objects for extension type. Possible values are: “ScriptExtension”, “SymbolExtension”, “DisplayExtension”, “inputoutputextension”, “inputextension”, “outputextension”, “alarmextension”, and “historyextension”.
EDeployOnScan
Deploy on scan.
enum EDeployOnScan { dontDeployOnScan = 0, doDeployOnScan = 1, }
Members
doDeployOnScan Do deploy on scan.
dontDeployOnScan Don't deploy on scan.
EDeploymentStatus
Indicates the whether the object is deployed.
enum EDeploymentStatus { notDeployed = 0, deployed = 1, deployedWithPendingChanges = 2 }
Members
notDeployed The object is not deployed.
deployed The object is deployed.
deployedWithPendingChanges The object is deployed and it has pending changes.
GRAccess Toolkit API User's Guide
Page 228
<page_number>228</page_number> Chapter 2 API Reference
EEXECUTIONGROUP
Lists ExecutionGroup options.
enum EEXECUTIONGROUP
{
idxExeGroupUnknown = -1,
idxExeGroupCommon = 0,
idxExeGroupInput = 1,
idxExeGroupPreScript = 2,
idxExeGroupCustom = 3,
idxExeGroupCustom1 = 4,
idxExeGroupCustom2 = 5,
idxExeGroupCustom3 = 6,
idxExeGroupCustom4 = 7,
idxExeGroupCustom5 = 8,
idxExeGroupCustom6 = 9,
idxExeGroupCustom7 = 10,
idxExeGroupCustom8 = 11,
idxExeGroupCustom9 = 12,
idxExeGroupCustom10 = 13,
idxExeGroupExpression = 14,
idxExeGroupScript = 15,
idxExeGroupPostScript = 16,
idxExeGroupOutput = 17,
idxExeGroupHistory = 18,
idxExeGroupAlarm = 19,
}
Members
idxExeGroupCustom6 idxExeGroupCustom4 idxExeGroupCustom5 idxExeGroupCustom2 idxExeGroupCustom3 idxExeGroupCustom1 New Default
GRAccess Toolkit API User's Guide
Page 229
Type Definitions <page_number>229</page_number>
idxExeGroupCommon idxExeGroupCustom7 idxExeGroupCustom8 idxExeGroupCustom9 idxExeGroupScript idxExeGroupOutput idxExeGroupExpression idxExeGroupInput idxExeGroupPostScript idxExeGroupCustom10 idxExeGroupCustom idxExeGroupAlarm idxExeGroupPreScript idxExeGroupHistory idxExeGroupUnknown
EEditStatus
Indicates the edit status of an object.
enum EEditStatus
{
notBeingEdited = 0,
editedByThisSession = 1,
editedByYouInOtherSession = 2,
editedByAnotherUser = 3,
}
Members
editedByThisSession The object is being edited by this session.
editedByYouInOtherSession The object is being edited by you in another session.
notBeingEdited The object is not being edited.
editedByAnotherUser The object is being edited by another user.
GRAccess Toolkit API User's Guide
Page 230
<page_number>230</page_number> Chapter 2 API Reference
EExecutionOrder
Indicates the execution order of an object as related to the object specified by ExecutionRelatedObject.
enum EExecutionOrder
{
The execution order doesn't matter and is determined by the Engine hosting the object.
NONE = 1,
The object should run before the object referenced by ExecutionRelatedObject.
BEFORE,
The object should run after the object referenced by ExecutionRelatedObject.
AFTER
}
Members
NONE BEFORE AFTER
EExportType
Indicates the type of export: aaPKG.
enum EExportType
{
exportAsPDF = 0,
exportAsCSV = 1,
}
Members
exportAsPDF Export to a .PDF file. The resulting cab file contains a list of all templates and instances (along with required templates) plus any code modules.
exportAsCSV Export instances to a text .CSV which can be opened in Excel.
GRAccess Toolkit API User's GuidePage 231
Type Definitions <page_number>231</page_number>
EFileType
Describes the type of file that is in the PIM file repository. PIM uses this to determine how to install the file.
enum EFileType
{
eUndefinedFileType = 0,
eNormal = 1,
eComDLL = 2,
eComEXE = 3,
eNTService = 4,
eMergeRegistryScript = 5,
eForHTMLEditor = 6,
eDictionary = 7,
eMsiMergeModule = 8,
eNETFrameworkAssembly
}
Members
eForHTMLEditor File is an HTML editor code module file. Store in Vendorname\Primitive GUID subdirectory instead of Vendorname subdirectory.
eNormal Normal file. Do nothing extra except install file.
eMsiMergeModule File is an MSI merge module, which will be merged into an installable MSI file.
eComEXE File is a COM local server .EXE. Run " /RegServer".
eUndefinedFileType
eComDLL File is a COM in-proc server .DLL. Run regsvr32 on the file.
eNETFrameworkAssembly File is a .NET Framework assembly.
eDictionary File is an ArchestrA Dictionary file.
GRAccess Toolkit API User's Guide
Page 232
<page_number>232</page_number> Chapter 2 API Reference
eNTService File is an NT Service .EXE. Run " -Service".
eMergeRegistryScript File is a .REG registry script. Merge it into system registry.
EForceDeleteInstanceOption
Indicates whether a deployed instance should be undeployed prior to deletion.
enum EForceDeleteInstanceOption
{
dontForceInstanceDelete = 0,
undeployIfNotRunningOnScan = 1,
undeployIfDeployed = 2
}
Members
undeployIfDeployed If object is deployed, set it off-scan if needed, and undeploy prior to deletion.
dontForceInstanceDelete Don't force the deletion of the instance.
undeployIfNotRunningOnScan If object is deployed, undeploy it prior to deletion. Object must be off-scan.
EForceDeleteTemplateOption
Indicates how to handle descendents prior to deletion.
enum EForceDeleteTemplateOption
{
dontForceTemplateDelete = 0,
cascadeDeleteDontUndeploy = 1,
cascadeDeleteUndeployDescendentsIfRunningOffScan = 2,
cascadeDeleteUndeployDescendentsIfRunning = 3
}
Page 233
Type Definitions <page_number>233</page_number>
Members
cascadeDeleteUndeployDescendentsIfRunning Prior to deletion, decendent instances are first undeployed (and forced off-scan if needed) and then deleted.
cascadeDeleteUndeployDescendentsIfRunningOffScan Prior to deletion, decendent instances are first undeployed and then deleted. Undeployed objects must be off-scan.
cascadeDeleteDontUndeploy Do delete decendent objects first, but only if they're not deployed.
dontForceTemplateDelete Don't force the deletion of the template. The template cannot have any derived descendents.
EForceOffScan
Force off-scan.
enum EForceOffScan
{
dontForceOffScan = 0,
doForceOffScan = 1,
}
Members
dontForceOffScan Don't force off-scan.
doForceOffScan Do force off-scan.
EGRCommandResult
Indicates the result of a command issued to the GR.
enum EGRCommandResult
{
cmdUnknownError = -1,
cmdSuccess = 0,
cmdInsufficientPermissions = 101,
cmdNoSuchGRNode = 102,
cmdNoSuchUser = 103,
cmdPasswordIncorrect = 104,
cmdLicenseUnavailable = 105,
}
Page 234
<page_number>234</page_number> Chapter 2 API Reference
cmdNoSuchFile = 201,
cmdCouldntCreateFile = 202,
cmdObjectIsCheckedOut = 301,
cmdObjectIsCheckedOutToSomeoneElse = 302,
cmdObjectNotCheckedOutToMe = 303,
cmdObjectCannotBeOverwritten = 401,
cmdTemplateInUse = 402,
cmdObjectIsAContainer = 403,
cmdObjectHostNotFound = 404,
cmdInstanceIsHost = 405,
cmdObjectIsRequired = 406,
cmdObjectNotAnAutomationObject = 407,
cmdObjectInBadState = 408,
cmdCustomConfigurationError = 409,
cmdObjectInReadOnlyMode = 410,
cmdObjectHostNotDeployed = 501,
cmdInstanceIsDeployed = 502,
cmdInvalidGRLoadMode = 503,
cmdOEMVersionIncompatible = 504,
cmdRetryClientSync = 505,
cmdSyncSemaphore = 506,
cmdOutOfSync = 507
}
Members
cmdLicenseUnavailable Operation failed because a license problem occurred.
cmdCustomConfigurationError The operation failed because of configuration error.
cmdObjectHostNotFound The operation failed because the given instance does not have a host.
cmdInsufficientPermissions Operation failed because the user has insufficient permission.
cmdNoSuchGRNode Operation failed because the given GR Node is invalid.
GRAccess Toolkit API User's Guide
Page 235
Type Definitions <page_number>235</page_number>
cmdObjectIsAContainer The operation failed because the object is a container of other objects.
cmdObjectHostNotDeployed The operation failed because the host of the given instance is not deployed.
cmdNoSuchFile The specified file was not found.
cmdObjectNotAnAutomationObject The operation failed because the object is not an AutomationObject.
cmdObjectIsRequired The object could not be deleted because it is a required object.
cmdSuccess Success code.
cmdUnknownError Unknown error.
cmdObjectInBadState The operation failed because the object is in a bad state.
cmdObjectCannotBeOverwritten The specified object already exists and cannot be overwritten.
cmdObjectIsCheckedOutToSomeoneElse The operation failed because the object is currently checked out to someone else.
cmdObjectInReadOnlyMode The operation failed because the object is in read-only mode.
cmdTemplateInUse The operation failed because the template has one or more objects derived from it.
cmdInstanceIsHost The operation failed because the instance is a host of other objects.
cmdCouldntCreateFile The operation failed because the file could not be created.
cmdInstanceIsDeployed The operation failed because the instance is currently deployed.
cmdObjectNotCheckedOutToMe The operation failed because the object is not checked out to the current user.
cmdObjectIsCheckedOut The operation failed because the object is currently checked out.
cmdNoSuchUser Operation failed because the given user name is invalid.
GRAccess Toolkit API User's GuidePage 236
<page_number>236</page_number> Chapter 2 API Reference
cmdPasswordIncorrect Operation failed because the given password is invalid.
cmdInvalidGRLoadMode The operation failed because enum GRLoad mode is invalid.
cmdOEMVersionIncompatible The operation failed because client and galaxy OEMVersions are incompatible.
cmdRetryClientSync The operation failed because enum cmdRetryClientSync mode is invalid.
cmdSyncSemaphore The operation failed because enum cmdForceSynchronize mode is invalid.
cmdOutOfSync The operation failed because enum cmdOutOfSync mode is invalid.
EMatch
Indicates which results should be returned: condition match or negate result.
enum EMatch { NotMatchCondition = 0, MatchCondition = 1 }
Members
MatchCondition Condition match results.
NotMatchCondition Condition match negate results.
GRAccess Toolkit API User's GuidePage 237
Type Definitions <page_number>237</page_number>
EPACKAGESTATUS
Indicates the status of an object after it is validated.
enum EPACKAGESTATUS { Package configured properly. ePackageUnknownStatus = -1, The object is properly configured and can be deployed. ePackageGood = 0, The object is not properly configured, but it can be deployed. ePackageBad = 1, The object is not properly configured, and cannot be deployed. ePackageWarning = 2 }
Members
ePackageBad ePackageGood ePackageWarning ePackageUnknownStatus
ERESERVEDPRIMITIVEIDS
Specifies the primitive IDs of the common primitives and the topmost custom primitive.
enum ERESERVEDPRIMITIVEIDS { eReservedPrimitiveIdUndefined = -1, eBaseRuntimeObjectId = 1, eCommonPrimitiveId = 2, eTopLevelCustomPrimitiveId = 100 }
Page 238
<page_number>238</page_number> Chapter 2 API Reference
Members
eCommonPrimitiveId eTopLevelCustomPrimitiveId eReservedPrimitiveIdUndefined eBaseRuntimeObjectId Primitive ID reserved for BRO use during deployment.
ESkipIfCurrentlyUndeployed
Skip if currently undeployed.
enum ESkipIfCurrentlyUndeployed
{
dontSkipIfCurrentlyUndeployed = 0,
doSkipIfCurrentlyUndeployed = 1,
}
Members
doSkipIfCurrentlyUndeployed Do skip if currently undeployed. dontSkipIfCurrentlyUndeployed Don't skip if currently undeployed.
ESkipObjectsWithPendingUpdates
Skip objects with pending updates.
enum ESkipObjectsWithPendingUpdates
{
dontSkipObjectsWithPendingUpdates = 0,
doSkipObjectsWithPendingUpdates = 1
}
Members
dontSkipObjectsWithPendingUpdates Upload will fail if any object has pending updates. doSkipObjectsWithPendingUpdates Automatically skip objects that have pending updates.
GRAccess Toolkit API User's Guide
Page 239
Type Definitions <page_number>239</page_number>
ESkipOtherUsersCheckedOutObjects
Skip other users' CheckedOuts.
enum ESkipOtherUsersCheckedOutObjects
{
dontSkipOtherUsersCheckedOutObjects = 0,
doSkipOtherUsersCheckedOutObjects = 1
}
Members
doSkipOtherUsersCheckedOutObjects Automatically skip objects that are checked out to another user.
dontSkipOtherUsersCheckedOutObjects Upload will fail if any objects are checked out to other users.
ETestOnly
Indicates whether the operation is to be performed or just tested to determine if it can be performed.
enum ETestOnly
{
performOperation = 0,
testOnly = 1,
}
Members
performOperation Perform the operation.
testOnly Only test to determine if the operation can be performed.
GRAccess Toolkit API User's GuidePage 240
<page_number>240</page_number> Chapter 2 API Reference
EUserDefault
The user default.
enum EUserDefault
{
defaultPlatform = 1,
defaultAppEngine = 2,
defaultHistorianNode = 3,
defaultArea = 4,
defaultSecurityGroup = 5
}
Members
| defaultSecurityGroup | The name of the default security group of the user. |
| defaultHistorianNode | The name of the historian node name of the user. |
| defaultAppEngine | The name of the default AppEngine of the user. |
| defaultArea | The name of the default Area of the user. |
| defaultPlatform | The name of the default Platform of the user. |
EgObjectIsTemplateOrInstance
Indicates whether a gObject is a template or an instance.
enum EgObjectIsTemplateOrInstance
{
gObjectIsTemplate = 0,
gObjectIsInstance = 1,
}
Members
| gObjectIsTemplate | GObject is a Template. |
| gObjectIsInstance | GObject is a Instance. |
Page 241
Type Definitions <page_number>241</page_number>
MxAttributeCategory
Indicates the category of an attribute.
enum MxAttributeCategory
{
MxCategoryUndefined = -1,
Can only be configured at IDE time and not Lockable. Attribute doesn't exist at Runtime.
MxCategoryPackageOnly = 0,
Can only be configured at IDE time and is Lockable. Attribute doesn't exist at Runtime. (eg. CmdDisagreeAlarm.Available)
MxCategoryPackageOnly_Lockable = 1,
Not configurable at IDE time. Calculated and readable at runtime, and not Checkpointed. (eg. Valve1.PVAuto)
MxCategoryCalculated = 2,
Not configurable at IDE time. Calculated and readable at runtime and Checkpointed. (eg. Timer or Counter Accumulator)
MxCategoryCalculatedRetentive = 3,
Only the Security Classification is configurable at IDE time. User writable but not Supervisory writable. Checkpointed. (eg. Valve1.CmdTImeoutAlarm.Acknowledged)
MxCategoryWriteable_U = 4,
Not configurable at IDE time. Supervisory writable but not User writable. Checkpointed.
MxCategoryWriteable_S = 5,
Only the Security Classification is configurable at IDE time. User and Supervisory writable and Checkpointed. (eg. Valve1.CMD, PID1.SP)
MxCategoryWriteable_US = 6,
Can be configured at IDE time but not lockable. User writable but not Supervisory writable. Checkpointed. (eg. Valve1.PVOverrideEnabled)
MxCategoryWriteable_UC = 7,
Can be configured at IDE time but not lockable. User and Supervisory writable and Checkpointed. (eg. Valve1.PVMode)
MxCategoryWriteable_USC = 8,
Can be configured at IDE time and is Lockable. User writable but not Supervisory writable. Checkpointed. (eg. Valve1.FieldInputToPVMap)
}
GRAccess Toolkit API User's Guide
Page 242
<page_number>242</page_number> Chapter 2 API Reference
MxCategoryWriteable_UC_Lockable = 9, Can be configured at IDE time and is Lockable. User and Supervisory writable and Checkpointed. (eg. Valve1.CmdTImeoutAlarm.Limit)
MxCategoryWriteable_USC_Lockable = 10, Can be configured at IDE time and is Lockable. Not writable at runtime or checkpointed. (eg. Valve1.NumInputs)
MxCategoryWriteable_C_Lockable = 11, Not configurable or Lockable at IDE time. User or Supervisory writable, but System writable. Not checkpointed. (eg. GEngine._BindReference)
MxCategory_SystemSetsOnly = 12, Not configurable or Lockable at IDE time. User or Supervisory writable, but System writable. Not readable at Runtime. Not checkpointed. (eg. _InternalName, _ExternalName)
MxCategory_SystemInternal = 13, Not configurable or Lockable, but readable at IDE time. Not writable but readable at Runtime. Not checkpointed. (eg. Tagname)
MxCategory_SystemWriteable = 14, Defined at SDK time and not modified after that.
MxCategory_Constant = 15, Defined at Config time. This attribute does not exist at runtime
MxCategory_SystemInternal_Browsable = 16, Defined at SDK time. This attribute does not exist at runtime
MxCategory_CalculatedPackage = 17, Defined at SDK time. This attribute is used to send data to runtime.
MxCategory_DeleteAfterStartup = 18,
MxAttributeCategoryEND = 19 }
Members
MxCategoryCalculated MxCategoryWriteable_USC MxCategoryWriteable_UC_Lockable MxCategoryWriteable_USC_Lockable MxCategoryWriteable_C_Lockable
GRAccess Toolkit API User's Guide
Page 243
Type Definitions <page_number>243</page_number>
MxCategoryCalculatedRetentive MxCategoryUndefined MxCategory_SystemWriteable MxCategory_Constant MxCategory_SystemInternal_Browsable MxCategoryWriteable_US MxCategoryWriteable_UC MxCategory_SystemSetsOnly MxCategory_CalculatedPackage MxCategory_DeleteAfterStartup MxAttributeCategoryEND MxCategoryPackageOnly_Lockable MxCategory_SystemInternal MxCategoryPackageOnly MxCategoryWriteable_U MxCategoryWriteable_S
MxPropertyLockedEnum
Indicates the lock status of an attribute.
enum MxPropertyLockedEnum
{
MxUndefinedLockedStatus = -1,
The Attribute is Unlocked. Data can be modified.
MxUnLocked = 0,
The Attribute is Locked in this object and propagated to all descendents. Data can be modified.
MxLockedInMe = 1,
The Attribute is LockedByMe in an ancestor object. Data cannot be modified.
MxLockedInParent = 2,
MxPropertyLockedEnumEND = 3
}
GRAccess Toolkit API User's Guide
Page 244
<page_number>244</page_number> Chapter 2 API Reference
Members
MxUndefinedLockedStatus MxLockedInParent MxPropertyLockedEnumEND MxLockedInMe MxUnLocked
GRAccess Code Examples
This section provides examples related to performance and other best practices.
Programming Tips
Follow these programming tips:
- GRAccessApp m_gr = new GRAccessApp(). m_gr object must be active when you want to use any of GRAccess Objects. This means that it should not go out of scope from your code path.
- CommandResult and CommandResults are error checking methods like GetLastError in C++ and The Err Object in VB. After each GRAccess object API call, you can check that the API succeeded or not. APIs that deal with multiple objects return CommandResults.
- If you are using GRAccess from a remote machine, make sure you have run the OSConfigUtility.
- If you are running GRAccess on a 64-bit system, you must modify the import statement in stdafx.h to include (x86) in the file path, as shown in the following example:
#import "C:\Program Files
(x86)\ArchestrA\Framework\Bin\ArchestrA.GRAccess.dll"
no_namespace, raw_interfaces_only
The import path may vary depending on variables such as the InTouch installation directory. Modify the import statement in stdafx.h to import from the correct library path, as shown in the following example:
#import "C:\Program
Files\Wonderware\InTouch\AppServerSecurity.dll"
no_namespace, raw_interfaces_only
GRAccess Toolkit API User's Guide
Page 245
GRAccess Code Examples <page_number>245</page_number>
Example for Defining the Entry Point for a Console Application
The following example shows the entry point for the console application with ATL support:
Note: This code can be found in \Samples\CreateGalaxyCPP.
// Copyright (C) 2014 Invensys Systems Inc. All rights reserved.
//
// THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
// KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// CreateGalaxyCPP.cpp : Defines the entry point for the console application with ATL
// support.
#include "stdafx.h"
#include <time.h>
#import "GRAccess111.tlb" no_namespace
class COMINIT
{
public:
COMINIT()
{
// Initialize COM.
comInit = CoInitializeEx(
0,
//COINIT_APARTMENTTHREADED
COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE
);
}
~COMINIT()
{
// Uninitialize COM.
GRAccess Toolkit API User's Guide
Page 246
<page_number>246</page_number> Chapter 2 API Reference
if (SUCCEEDED(comInit))
{
CoUninitialize();
}
}
private:
HRESULT comInit;
};
int _tmain(int argc, _TCHAR* argv[])
{
COMINIT SmartComInitialize;
CComPtr<IGRAccess> spGRApp;
HRESULT hr = spGRApp.CoCreateInstance ( __uuidof(GRAccessApp) );
if (spGRApp == NULL)
return -1;
CComPtr<IGalaxies> spGalaxies;
DWORD dwsize = MAX_COMPUTERNAME_LENGTH + 1;
TCHAR szGRNodeComputerName[MAX_COMPUTERNAME_LENGTH + 1];
::GetComputerName(szGRNodeComputerName, &dwsize);
CComBSTR bstrGRNodeComputerName = szGRNodeComputerName;
spGalaxies = spGRApp->QueryGalaxies (bstrGRNodeComputerName.m_str);
CComPtr<ICommandResult> spCommandResult;
spGRApp->get_CommandResult (&spCommandResult);
if (spCommandResult->Successful == VARIANT_FALSE || spGalaxies == NULL)
{
wprintf(L"%s : %s \n", spCommandResult->CustomMessage.GetBSTR(), spCommandResult->Text.GetBSTR());
return 1;
}
}
GRAccess Toolkit API User's Guide
Page 247
GRAccess Code Examples <page_number>247</page_number>
CComPtr<IGalaxy> spGalaxy;
_variant_t vtGalName = L"Example1";
// OR you can use index if you have only one galaxy use 1. All collections are 1 base
// _variant_t vtGalName = L"1";
spGalaxies->get_Item (vtGalName,&spGalaxy);
if (spGalaxy == NULL)
{
spGRApp->CreateGalaxy (vtGalName.bstrVal
,bstrGRNodeComputerName.m_str,FALSE,galaxyAuthenticationMode,L"");
CComPtr<ICommandResult> spCommandResult;
spGRApp->get_CommandResult (&spCommandResult);
if (spCommandResult->Successful == VARIANT_FALSE || spGalaxies == NULL)
{
wprintf(L"Create Galaxy Named Example1 Failed: %s : %s \n",spCommandResult->CustomMessage.GetBSTR (), spCommandResult->Text.GetBSTR ());
return 1;
}
}
spGalaxies = spGRApp->QueryGalaxies (bstrGRNodeComputerName.m_str);
spGalaxies->get_Item (vtGalName,&spGalaxy);
}
spGalaxy->Login (L"",L"");
CComPtr<IgObjects> spGObjects;
_variant_t vtTemplateName = L"$UserDefined";
spGObjects = spGalaxy->QueryObjects
(gObjectIsTemplate,NameEquals,&vtTemplateName,MatchCondition );
CComPtr<IgObject> spGObject;
spGObjects->get_Item (vtTemplateName,&spGObject);
CComPtr<IInstance> spInstance;
CComQIPtr<ITemplate> spTemplate = spGObject;
time_t ltime;
GRAccess Toolkit API User's Guide
Page 248
<page_number>248</page_number> Chapter 2 API Reference
time( <ime );
WCHAR UTCStr [32];
wsprintf(UTCStr,L"%ld",ltime);
_bstr_t instanceName(L"UD_");
instanceName += UTCStr;
spInstance = spTemplate->CreateInstance (instanceName,VARIANT_FALSE);
spInstance->CheckOut ();
_variant_t vtCount = 5;
spInstance->AddUDA
(L"Names",MxString,MxCategoryWriteable_USC_Lockable,MxSecurityOperate,VARIANT_TRUE,v
tCount);
CComPtr<IAttributes> spAttributes;
spInstance->get_ConfigurableAttributes (&spAttributes);
CComPtr<IAttribute> spAttrib;
_variant_t vtAttrName = L"Names";
spAttributes->get_Item (vtAttrName,&spAttrib);
//Display first 5 attribute names from collection
for (int i = 1; i <= 5; i++)
{
CComPtr<IAttribute> spAttrib1 = spAttributes->GetItem(i);
wprintf(L"%s\n",spAttrib1->GetName ().GetBSTR ());
}
CComPtr<IMxValue> spNamesValue;
spNamesValue.CoCreateInstance (__uuidof(MxValue));
GRAccess Toolkit API User's Guide
Page 249
GRAccess Code Examples <page_number>249</page_number>
for(int i=1;i<=5;i++)
{
CComPtr<IMxValue> mxv;
mxv.CoCreateInstance (__uuidof(MxValue));
mxv->PutInteger (i);
// Attribute Data type is string Why Integer ??
// The reason is MxValue (Just Like Variant) is smart which contains logic
// to convert from one type to another.
spNamesValue->PutElement (i,mxv);
}
spAttrib->SetValue (spNamesValue);
spInstance->Save ();
spInstance->CheckIn (L"");
spGalaxy->Logout ();
WCHAR dummy [81];
wprintf (L"\nPress ENTER to quit: ");
_getws_s (dummy, 80);
//char ch = getchar();
return 0;
}
GRAccess Toolkit API User's Guide
Page 250
<page_number>250</page_number> Chapter 2 API Reference
Example for Creating and Populating a Galaxy
The steps below demonstrate how to use GRAccess through C# and Visual Studio.
This procedure creates an Archestra Galaxy and populates it with a single instance.
Build and execute the program below. It creates a Galaxy called "Example1" and a single instance of a $UserDefined template with a name based on the current date and time.
Note: The C# console application should work with ATL support.
- Using Visual Studio, create a new C# console application "CreateGalaxyExample".
- On the Main menu, click Project / Add Reference and add a reference to the GRAccess primary interop assembly. By default, this is in
C:\Windows\assembly\GAC\Archestra.GRAccess\1.7.0.0_23106a86e706d0ae\Archestra.GRAccess.dll. - Replace the contents of the generated C# source file with the following text:
Note: This code can be found in \Samples\CreateGalaxyCSharp.
// Copyright (C) 2014 Invensys Systems Inc. All rights reserved.
// THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
// KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
using System;
using Archestra.GRAccess;
class CreateGalaxyExample
{
[STAThread]
static void Main()
{
// Your code here
}
}
GRAccess Toolkit API User's Guide
Page 251
GRAccess Code Examples <page_number>251</page_number>
string nodeName = Environment.MachineName;
string galaxyName = "Example1";
// create GRAccessAppClass object
GRAccessApp grAccess = new GRAccessAppClass();
// try to get galaxy
IGalaxies gals = grAccess.QueryGalaxies(nodeName);
if (gals == null || grAccess.CommandResult.Successful == false)
{
Console.WriteLine(grAccess.CommandResult.CustomMessage +
grAccess.CommandResult.Text);
return;
}
IGalaxy galaxy = gals[galaxyName];
ICommandResult cmd;
// create galaxy if it doesn't already exist
if( galaxy == null )
{
grAccess.CreateGalaxy(
galaxyName,
nodeName,
false, // no security
EAuthenticationMode.galaxyAuthenticationMode,
"" );
cmd = grAccess.CommandResult;
if (!cmd.Successful)
{
Console.WriteLine("Create Galaxy Named Example1 Failed: " +
cmd.Text + " : " +
cmd.CustomMessage);
---
## Page 252
<page_number>252</page_number> Chapter 2 API Reference
```csharp
return;
}
galaxy = grAccess.QueryGalaxies( nodeName ) [ galaxyName ];
}
// log in
galaxy.Login( "", "" );
cmd = galaxy.CommandResult;
if ( !cmd.Successful )
{
Console.WriteLine("Login to galaxy Example1 Failed : " +
cmd.Text + " : " +
cmd.CustomMessage);
return;
}
// get the $UserDefined template
string [] tagnames = { "$UserDefined" };
IgObjects queryResult = galaxy.QueryObjectsByName(
EgObjectIsTemplateOrInstance.gObjectIsTemplate,
ref tagnames );
cmd = galaxy.CommandResult;
if ( !cmd.Successful )
{
Console.WriteLine("QueryObjectsByName Failed for $UserDefined Template : " +
cmd.Text + " : " +
cmd.CustomMessage);
return;
}
GRAccess Toolkit API User's Guide
Page 253
GRAccess Code Examples <page_number>253</page_number>
ITemplate userDefinedTemplate = (ITemplate) queryResult[1];
// create an instance of $UserDefined, named with current time
DateTime now = DateTime.Now;
string instanceName = String.Format( "sample_object_{0}{1}{2}" , now.Hour.ToString( "00" ) , now.Minute.ToString( "00" ) , now.Second.ToString( "00" ) );
IInstance sampleinst = userDefinedTemplate.CreateInstance(instanceName, true);
//How to edit the object ?
sampleinst.CheckOut();
sampleinst.AddUDA( "Names", MxDataType.MxString, MxAttributeCategory.MxCategotyWriteable_USC_Lockable, MxSecurityClassification.MxSecurityOperate, true, 5);
IAttributes attrs = sampleinst.ConfigurableAttributes;
//Diplay first 5 attribute names from collection
for (int i = 1; i <= 5; i++)
{
IAttribute attrb = attrs[i];
Console.WriteLine(attrb.Name);
}
IAttribute attr1 = attrs["Names"];
MxValue mxv = new MxValueClass ();
// we don't need to check that attribute is array type or not
GRAccess Toolkit API User's Guide
Page 254
<page_number>254</page_number> Chapter 2 API Reference
// because we set it as array type when we addUDA.
// I am just showing example, you can do like this.
if (attr1.UpperBoundDim1 > 0)
{
for (int i = 1; i <= attr1.UpperBoundDim1; i++)
{
MxValue mxvelement = new MxValueClass();
mxvelement.PutString("string element number " + i.ToString());
mxv.PutElement(i, mxvelement);
}
attr1.SetValue(mxv);
}
sampleinst.Save();
sampleinst.CheckIn("Check in after addUDA");
galaxy.Logout();
Console.WriteLine();
Console.Write("Press ENTER to quit: ");
string dummy;
dummy = Console.ReadLine();
}
}
GRAccess Toolkit API User's Guide
Page 255
<page_number>255</page_number>
Index
A
access level, Galaxy role 56 accessing, Galaxy Repository 12 AccessLevel property 56 Add method 31, 92, 175, 210 AddExtensionPrimitive method 80, 107, 184 AddFromCollection method 90 adding extension to a template 184 extension to an instance 107 library to the Galaxy 175 object 92 object to a condition collection 31 objects to an object collection 90 toolset collection 210, 211 UDA to a template 185 UDA to an instance 108 UDA to an object 82 AddToolSet method 211 AddUDA method 82, 108, 185 area instance 109 objects 89 template 185 Area object 75 Area property 75, 89, 109, 185 array 134 array, MxValue object 158, 159, 160 AssociatedFileAccess 13 AssociatedRoles property 64 attribute category 20 data type 16 locked 17, 18 name 16 object 13 security classification 15, 18 set handler 14, 15 upper bound 17 value 19 attribute collection description 21, 23 execution order 23 execution related object 24 number in collection 22 returning name or index 22 security group 24 attribute ID enumeration 218 AttributeCategory Property 20 attributes
GRAccess Toolkit API User's Guide
Page 256
<page_number>256</page_number> Index
category enumeration 219 common enumeration 221 instance 110 property ID enumeration 214 template 186 Attributes property 69, 110, 186 authentication mode enumeration 218 Galaxy security 59 AuthenticationMode property 59
B backup file, Galaxy 39, 47 Backup method 39 base template instance 110 object 74 template 187 BasedOn property 74, 110, 187
C cache instance 129 object 79 template 205 Cancel method 181 cascade enumeration 224 category attribute 20 instance 111 object 73 template 187 category enumeration 219, 241 Category property 73, 111, 187 CategoryGUID property 86, 111, 188 Cdi, version string 49 CdiVersionString property 49 CfgSethandler Property 15 check in instance 112 object 78 objects 91 settings object 181 template 188 check out enumeration 218, 224, 239 instance 112, 113, 129 object 72, 78, 79 objects 94 template 189, 204 CheckedOutBy property 72, 112, 189 CheckIn method 78, 91, 112, 188 CheckOut method 78, 94, 113, 189 CheckoutStatus Property 72 CheckoutStatus property 113, 189 child permissions, permission 170 child toolsets 208 ChildPermissions property 170 Clone method 136 Close method 181 code examples 244, 245, 250 collection of attributes 69 collection of roles 60 collection of users 61 COM Classes 11 command result enumeration 233 CommandResult collection description 26 index 27 number in collection 27 status 28 CommandResult Property 14 CommandResult property 30, 37, 85, 101, 113, 173, 176, 180, 190, 207 CommandResults property 54, 88, 190 common enumeration, attributes 221 CompletelySuccessful property 28 condition negation 29 type 29 value 29 condition collection adding an object 31 description 30 index 32 joining conditions 33 number of objects in 32 removing an object 31 result 30 condition enumeration 225 conditions object 50 configurable attributes instance 114 object 70 template 191 ConfigurableAttributes property 70, 114, 191
GAccess Toolkit API User's Guide
Page 257
Index <page_number>257</page_number>
configuration changes instance 131, 132 objects 90, 100
configuration version instance 119 object 73
configuration, settings object 181 ConfigVersion property 73, 114, 191
contained name instance 115 object 68 template 192
ContainedName property 68, 115, 192
container instance 116 objects 92 template 192
container object 75 Container property 75, 92, 116, 192
Count property 22, 27, 32, 34, 58, 65, 98, 172, 174, 179, 212
CreateConditionsObject method 50 CreateGalaxy method 102 CreategObjectCollection method 43 CreateInstance method 193 CreateInstances method 194 CreateTemplate method 195
creating empty gObjects collection object 43 new Galaxy 102 new instance 193, 194 new template 195
custom enumeration, MxValue object 146
CustomMessage property 26
D
data type attribute 16 changing for MxValue object 137 MxValue object 143, 147 retrieving 12 data value 134
DataType Property 16 debugger 11
DeleteAllObjects method 94 DeleteExtensionPrimitive method 81, 116, 195 DeleteGalaxy method 103
DeleteInstance method 117 DeleteTemplate method 196 DeleteToolSet method 211 DeleteUDA method 83, 118, 197
deleting all objects 94 an extension from a template 195 an extension from an object 81 an extensionfrom an instance 116 Galaxy Repository 103 instance 117 template 196 toolset collection 211 UDA from a template 197 UDA from an instance 118 UDA from an object 83
deploy instance 118, 120 instances 98 objects 95
Deploy method 95, 118 DeployedVersion property 119 DeployEx method 98, 120
deployment enumeration 227 deployment status, instance 121 DeploymentStatus property 121
derived name object 74 template 197
DerivedFrom property 74, 121, 197 domain name, Galaxy users 63 duplicate, MxValue object 136
E
EActionForCurrentlyDeployedObjects 217 EATTRIBUTEPROPERTY 214 EAuthenticationMode 218 EAutomaticallyUndochekout 218 EBASERUNTIMEOBJECT 218 ECascade 224 ECATEGORY 219 ECheckoutStatus 224 ECOMMONATTRIBUTES 221 ECOMMONPRIMITIVE 221 EConditionType 225 EDeploymentStatus 227 EDeployOnScan 227 edit status, object 79
GRAccess Toolkit API User's Guide
Page 258
<page_number>258</page_number> Index
EditStatus property 79, 122, 198 EEditStatus 229 EEXECUTIONGROUP 228 EExecutionOrder 230 EExportType 230 EFileType 231 EForceDeleteInstanceOption 232 EForceDeleteTemplateOption 232 EForceOffScan 233 EgObjectIsTemplateOrInstance 240 EGRCommandResult 233 EMatch 236 Empty method 137 enumeration authentication mode 218 check out 218 objects 217 EPACKAGESTATUS 237 ERESERVEDPRIMITIVEIDS 237 errors instance 122 object 71 template 198 Errors property 71, 122, 198 ESkipIfCurrentlyUndeployed 238 ESkipObjectsWithPendingUpdates 238 ESkipOtherUsersCheckedOutObjects 239 ETestOnly 239 EUserDefault 240 example 245, 250 execution enumeration 228 execution order 23 execution order enumeration 230 execution related object 24 ExecutionOrder property 23 ExecutionRelatedObject property 24 Export method 176 export type enumeration 230 ExportAll method 53 exporting all objects in a Galaxy 53 an object in a collection 93 script library 176 ExportObjects method 93 extended attributes instance 123 object 86 template 199 extending an object 80 extension, instance 125
F file type enumeration 231 FullName property 63
G Galaxies collection 33 Galaxies collection, number of objects in 34 Galaxy 35 backup file 39, 47 conditions object 50 creating an empty gObjects collection object 43 exporting all objects 53 gObjects collection 51 importing objects 43 locale settings 52 log out 48 logged in user's defaults 45, 46 login 40 name 38 querying script libraries 38 result 37 retrieving a gObjects collection 37 script library 52 security 50, 53 tagnames 44 time settings 42 toolsets 44 upgrade 49 upgrade status 48 version number 46 version string 40 Galaxy Repository accessing 12 creating a new Galaxy 102 deleting 103 description 101 querying 103 result 101 Galaxy role, access level 56 GetBoolean method 147 GetChildToolsets method 208 GetCustomEnum method 157 GetCustomStruct method 156 GetCustomStructVB method 161
GRAccess Toolkit API User's Guide
Page 259
Index <page_number>259</page_number>
GetDataType method 147 GetDimensionCount method 158 GetDimensionSize method 160 GetDouble method 149 GetElapsedTime method 152 GetElement method 160 GetExtendedAttributes method 86, 123, 199 GetFloat method 149 GetInteget method 148 GetInternationalString method 165 GetInternationalStrings method 163 GetInternationalStringsVB method 164 GetLocaleSettings method 52 GetMxDataQuality method 156 GetMxDataType method 154 GetMxReference method 153 GetMxSecurityClassification method 155 GetMxStatus method 154 GetObjectHelpURL method 77, 123, 200 GetReadOnlySecurity method 53 GetSecuritySettings method 50 GetString method 150 GetTime method 152 GetTimeMasterSettings method 42 GetUserDefaults method 45 gObjects collection 51 gObjects property 178 gObjects, security group 178 GRAccess 11 GRAccess object model 10 GRAccessApp 12 GRLoad method 54 GroupName property 177 GUID instance 111 object 86 template 188
H HasChildren property 170 Help instance 123 object 77 template 200 hierarchical name instance 124 object 69 template 200 HierarchicalName property 69, 124, 200 host instance 125 object 76 objects 89 template 201 Host property 76, 89, 125, 201
I IAssociatedFileAccess 13 IAttribute 13 IAttribute class members 13 IAttributes 21 IAttributes class members 21 ICommandResult 25 ICommandResult class members 25 ICommandResults 26 ICommandResults class members 26 ICondition 28 ICondition class members 28 IConditions 30 IConditions class members 30 ID property 26 IGalaxies 33 IGalaxies class members 33 IGalaxy 35 IGalaxy class members 35 IGalaxyQueryToolsetsEx method 55 IGalaxyRole 55 IGalaxyRole class members 55 IGalaxyRoles 57 IGalaxyRoles class members 57 IGalaxySecurity 59 IGalaxySecurity class members 59 IGalaxyUser 62 IGalaxyUser class members 63 IGalaxyUsers 64 IGalaxyUsers class members 64 IgObject 65 IgObject class members 65 IgObjects 87 IgObjects class members 87 IGRAccess 55, 101 IGRAccess class members 101 IInstance 104 IInstance class members 104 importing objects, Galaxy 43 ImportObjects method 43
GRAccess Toolkit API User's GuidePage 260
<page_number>260</page_number> Index
ImportObjectsEx method 54 ImportScriptLib method 52 IMxValue 134 IMxValue class members 134 index CommandResult collection 27 condition collection 32 instance adding a UDA 108 adding an extension 107 area 109 attributes 110 base template 110 cache 129 category 111 check in 112 check out 112, 113, 129 configurable attributes 114 configuration changes 131, 132 configuration version 119 contained name 115 container 116 deleting 117 deleting a UDA 118 deleting an extension 116 deploy 118, 120 deployment status 121 description 104 errors 122 extended attributes 123 extension 125 GUID 111 Help 123 hierarchical name 124 host 125 results 113 saving 126 settings object 181 status 122 template name 121 UDA 126, 130 undeploy 127, 128 validation status 133 version number 114 warnings 133 instance deletion enumeration 232 instance enumeration 240 Instance property 181 Interfaces 12 Interfaces Implemented 12 internationalized strings, MxValue object 162, 163, 164, 165, 166 IPermission 167 IPermission class members 168 IPermissions 171 IPermissions class members 171 IsConfigured property 169 IScriptLibraries 173 IScriptLibraries class members 173 IScriptLibrary 175 IScriptLibrary class members 175 ISecurityGroup 177 ISecurityGroup class members 177 ISecurityGroups 178 ISecurityGroups class members 178 ISettings 180 ISettings class members 180 IsSecurityGroup property 171 Item method 27 Item property 22, 32, 34, 58, 64, 96, 172, 174, 179, 212 ITemplate 182 ITemplate class members 182 IToolset 207 IToolset class members 207 IToolset 207 IToolsets 210 IToolsets class members 210 J Join method 33 joining conditions 33 K Kind property 29 L locale settings, Galaxy 52 locale, MxValue object 165, 166 lock status enumeration 243 Locked Property 18 locked, attribute 17, 18 log in 40 log in time 61 log out 48 logged in user's defaults 45, 46
GAccess Toolkit API User's Guide
Page 261
Index <page_number>261</page_number>
Login method 40 LoginTime property 61 Logout method 48
M MigrateGalaxy method 49 MoveToToolset method 208 MxAttributeCategory 241 MxPropertyLockedEnum 243 MxValue 12 MxValue object array 158, 159, 160 changing data type 137 custom enumeration 146 data type 143, 147 description 134 duplicate 136 internationalized strings 162, 163, 164, 165, 166 locale 165, 166 quality 144 returning a qualified struct 156, 161 returning as qualified enum 157 returning value as Boolean 147 returning value as double 149 returning value as float 149 returning value as IMxReference 153 returning value as long 148 returning value as MxDataQuality 156 returning value as MxDataType 154 returning value as MxSecurityClassification 155 returning value as MxValue 154 returning value as string 150 returning value as VB_LARGE_INTEGER 152 returning value as VBFILETIME 152 security classification 144 status 142 storing a Boolean value in 137 storing a double value in 139 storing a float value in 139 storing a long value in 138 storing a MxCustomEnum in 146 storing a MxDataQuality in 144 storing a MxDataType in 143 storing a MxReference in 142 storing a MxSecurityClassification in 144 storing a MxStatus in 142 storing a qualified struct 161 storing a string value in 140 storing a struct in 145 storing a VB_LARGE_INTEGER value in 141 storing a VBFILETIME value in 141 struct 145
N name attribute 16 Galaxy 38 permission 169 role 56 script library 177 security group 177 toolset 209 Name property 16, 38, 177, 209 Negation property 29 negation, condition 29 number in attribute collection 22 CommandResult collection 27 condition collection 32 Galaxies collection 34 Galaxy roles 58 Galaxy users 65 object collection 98 permissions collection 172 script library collection 174 security group collection 179 toolset collection 212
O object adding a UDA 82 Area object 75 attribute 13 attribute ID enumeration 218 base template 74 cache 79 category 73 check out 72, 78, 79, 224 checking in 78 collection of attributes 69 configurable attributes 70 configuration version 73
GRAccess Toolkit API User's Guide
Page 262
<page_number>262</page_number> Index
| contained name | 68 | result code | 26 |
| container object | 75 | result description | 25 |
| deleting a UDA | 83 | result message | 26 |
| deleting an extension | 81 | status | 25 |
| derived name | 74 | success indicator | 25 |
| description | 65 | OperationalPermissions property | 57 |
| edit status | 79 | overview | 9 |
| errors | 71 | ||
| extended attributes | 86 | P | |
| extending | 80 | parent name | 169 |
| GUID | 86 | parent toolset | 208 |
| Help | 77 | permission | |
| hierarchical name | 69 | child permissions | 170 |
| host | 76 | description | 167 |
| renaming a UDA | 83 | name | 169 |
| renaming an extension | 81 | parent name | 169 |
| result | 85 | security group | 171 |
| saving | 77 | status | 169 |
| tagname | 67 | PermissionName property | 169 |
| updating a UDA | 84 | PermissionParentName property | 169 |
| validation status | 70 | permissions collection | |
| warnings | 71 | description | 171 |
| object model | 9, 10 | number in the collection | 172 |
| object status enumeration | 237 | returning a permission | 172 |
| objects | Permissions property | 57 | |
| adding an object | 92 | permissions, Galaxy role | 57 |
| adding to the collection | 90 | primitive enumeration | 237 |
| area | 89 | programming tips | 244 |
| check in | 91 | property ID enumeration, attributes | 214 |
| check out | 94 | PutBoolean method | 137 |
| configuration changes | 90, 100 | PutCustomEnum method | 146 |
| container | 92 | PutCustomStruct method | 145 |
| deleting all objects | 94 | PutCustomStructVB method | 161 |
| deploy | 95 | PutDouble method | 139 |
| deploying instances | 98 | PutElapsedTime method | 141 |
| description | 87 | PutElement method | 159 |
| enumeration | 217 | PutFloat method | 139 |
| exporting an object | 93 | PutInteger method | 138 |
| host | 89 | PutInternationalString method | 166 |
| number of objects in collection | 98 | PutInternationalStrings method | 162 |
| result | 88 | PutInternationalStringsVB method | 163 |
| returning an object | 96 | PutMxDataQuality method | 144 |
| security group | 94 | PutMxDataType method | 143 |
| undeploy | 95 | PutMxReference method | 142 |
| undeploying instances | 99 | PutMxSecurityClassification method | 144 |
| off-scan enumeration | 233 | PutMxStatus method | 142 |
| operation | PutString method | 140 | |
| cascade enumeration | 224 | PutTime method | 141 |
GRAccess Toolkit API User's Guide
Page 263
Index <page_number>263</page_number>
Q quality, MxValue object 144 QueryGalaxies method 103 querying script libraries, Galaxy 38 querying, Galaxy Repository 103 QueryObjects method 51 QueryObjectsByName method 44 QueryObjectsMultiCondition method 37 QueryScriptLibraries method 38 QueryToolsets method 44
R Remove method 31 removing an object 31 Rename method 209 RenameExtensionPrimitive method 81, 125, 201 RenameUDA method 83, 126, 202 renaming extension in a template 201 extension in an object 81 toolset 209 UDA in a template 202 UDA in an object 83 Restore method 47 result 14 condition collection 30 Galaxy 37 Galaxy Repository 101 object 85 objects 88 script library 176 script library collection 173 settings object 180 template 190 toolset 207 result code, operation 26 result description, operation 25 result message, operation 26 results instance 113 template 190 results enumeration 236 retrieving data types 12 gObjects collection 37 returning as qualified enum 157 name or index 22 object 96 permission 172 qualified struct 156, 161 role 58 script library 174 security group 179 toolset collection 212 user 64 value as Boolean 147 value as double 149 value as float 149 value as IMxReference 153 value as long 148 value as MxDataQuality 156 value as MxDataType 154 value as MxSecurityClassification 155 value as MxValue 154 value as string 150 value as VB_LARGE_INTEGER 152 value as VBFILETIME 152 role description 55 name 56 permissions 57 role update interval, Galaxy security 62 RoleName property 56 roles description 57 number of roles 58 returning a role 58 RolesAvailable property 60 RoleUpdateInterval property 62 RtSethandler Property 14
S Save method 77, 126, 203 saving instance 126 object 77 settings object 181 template 203 script library description 175 exporting 176 Galaxy 52 name 177 result 176
GRAccess Toolkit API User's Guide
Page 264
<page_number>264</page_number> Index
script library collection adding a library to the Galaxy 175 description 173 number in the collection 174 result 173 returning a script library 174
security authentication mode 59 collection of roles 60 collection of users 61 description 59 Galaxy 53 login time 61 role update interval 62 security groups 60 security classification attribute 15, 18 MxValue object 144 security group attribute collection 24 description 177 gObjects in the group 178 name 177 objects 94 permission 171 security group collection description 178 number of groups in the collection 179 returning security group 179 security groups, Galaxy security 60 security settings, Galaxy 50 SecurityClassification Property 15 SecurityGroup property 24, 94, 171 SecurityGroupsAvailable property 60 set handler, attribute 14, 15 SetLocked Method 17 SetSecurityClassification Method 18 settings object check in 181 configuration 181 description 180 instance 181 result 180 saving 181 SetUserDefaults method 46 SetValue Method 19 ShortDescription property 23 status CommandResult collection 28 instance 122 MxValue object 142 operation 25 permission 169 template 198 status enumeration 229 storing Boolean value 137 double value 139 float value 139 long value 138 MxCustomEnum 146 MxDataQuality 144 MxDataType 143 MxReference 142 MxSecurityClassification 144 MxStatus 142 qualified struct 161 string value 140 struct 145 VB_LARGE_INTEGER value 141 VBFILETIME value 141 struct, MxValue object 145 success indicator, operation 25 Successful property 25
T tagname object 67 template 203 Tagname property 67, 127, 203 tagnames, Galaxy 44 target clients 9 template adding a UDA 185 adding an extension 184 area 185 attributes 186 base template 187 cache 205 category 187 check in 188 check out 189, 204 configurable attributes 191 contained name 192 container 192 creating a new instance from 193, 194
GAccess Toolkit API User's Guide
Page 265
Index <page_number>265</page_number>
creating a new template from 195 deleting 196 deleting a UDA 197 deleting an extension 195 derived name 197 description 182 errors 198 extended attributes 199 GUID 188 Help 200 hierarchical name 200 host 201 renaming a UDA 202 renaming an extension 201 result 190 results 190 saving 203 status 198 tagname 203 toolset 204 UDA 205 validation status 206 version number 191 warnings 206
template deletion enumeration 232 template enumeration 240 template name, instance 121 test enumeration 239 Text property 25 time settings, Galaxy 42 toolset child toolsets 208 description 207 Galaxy 44 name 209 parent toolset 208 renaming 209 result 207 template 204 toolset collection adding 210, 211 deleting 211 description 210 number of toolsets 212 returning 212 Toolset property 204 type definitions 213 type, condition 29
U UDA instance 126, 130 template 205 undeploy instance 99, 127, 128 objects 95 undeploy enumeration 238 Undeploy method 95, 127 UndeployEx method 99, 128 UndoCheckOut method 79, 98, 129, 204 Unload method 79, 129, 205 update enumeration 238 UpdateUDA method 84, 130, 205 updating a UDA 84 upgrade status, Galaxy 48 upgrade, Galaxy 49 UpgradeRequired property 48 Upload method 90, 131 UploadEx method 100, 132 upper bound 17 UpperBoundDim1 Property 17 user default enumeration 240 user full name 63 user name 63 UserName property 63 users description 62, 64 domain name 63 number of users in collection 65 returning a user 64 user full name 63 user name 63 UsersAvailable property 61
V validation status instance 133 object 70 template 206 ValidationStatus property 70, 133, 206 value attribute 19 condition 29 Value property 19, 29 variant object 134 version number
GRAccess Toolkit API User's Guide
Page 266
<page_number>266</page_number> Index
Galaxy 46 instance 114 template 191 version string Cdi 49 Galaxy 40 VersionNumber property 46 VersionString property 40
W warnings instance 133 object 71 template 206 Warnings property 71, 133, 206
GRAccess Toolkit API User's Guide