## 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 http://www.wonderware.com 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. --- --- ## 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#] ```csharp ICommandResult CommandResult { get; }; ``` [Visual C++] ```cpp HRESULT CommandResult( [out, retval] ICommandResult** CommandResult ); ``` **Parameters** *CommandResult* Returns the CommandResult. **RtSethandler Property** Returns the RtSethandler property of the attribute. **Class** IAttribute **Syntax** [C#] ```csharp bool RtSethandler { get; }; ``` [Visual C++] ```cpp 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#]** ```csharp bool CfgSethandler { get; }; ``` **[Visual C++]** ```cpp 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#]** ```csharp MxSecurityClassification SecurityClassification { get; }; ``` **[Visual C++]** ```cpp 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#] ```csharp string Name { get; }; ``` [Visual C++] ```cpp 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#] ```csharp MxDataType DataType { get; }; ``` [Visual C++] ```cpp 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#]** ```csharp void SetLocked( MxPropertyLockedEnum NewMxPropertyLockedEnum ); ``` **[Visual C++]** ```cpp 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#]** ```csharp short UpperBoundDim1 { get; }; ``` **[Visual C++]** ```cpp 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#]** ```csharp void SetSecurityClassification( MxSecurityClassification NewMxSecurityClassification ); ``` **[Visual C++]** ```cpp 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#]** ```csharp MxPropertyLockedEnum Locked { get; }; ``` **[Visual C++]** ```cpp 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#]** ```csharp void SetValue( MxValue NewValue ); ``` **[Visual C++]** ```cpp 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#]** ```csharp MxValue value { get; }; ``` **[Visual C++]** ```cpp 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#] ```csharp MxAttributeCategory AttributeCategory { get; }; ``` [Visual C++] ```cpp 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#] ```csharp bool HasBuffer { get; }; ``` [Visual C++] ```cpp 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#]** ```csharp void SetHasBuffer(bool hasBuffer); ``` **[Visual C++]** ```cpp 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#] ```csharp IAttribute this[object attributeIdentifier] { get; }; ``` [Visual C++] ```cpp 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#] ```csharp int count { get; }; ``` [Visual C++] ```cpp 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#]** ```csharp string ShortDescription { set; get; } ``` **[Visual C++]** ```cpp [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#]** ```csharp EExecutionOrder ExecutionOrder { set; get; } ``` **[Visual C++]** ```cpp [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++] ```cpp [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#] ```csharp string ExecutionRelatedObject { set; get; } ``` [Visual C++] ```cpp [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#] ```csharp bool Successful { get; }; ``` [Visual C++] ```cpp HRESULT Successful( [out, retval] VARIANT_BOOL* ); ``` ### Text Property Textual description corresponding to the result code. **Class** ICommandResult **Syntax** [C#] ```csharp string Text { get; } ``` [Visual C++] ```cpp 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++] ```cpp HRESULT ID( [out, retval] EGRCommandResult* ); ``` # CustomMessage Property Custom message associated with the result. **Class** ICommandResult **Syntax** [C#] ```csharp string CustomMessage { get; }; ``` [Visual C++] ```cpp 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#] ```csharp int count { get; }; ``` [Visual C++] ```cpp HRESULT Count( [out, retval] LONG* ); ``` # Item Method Returns the CommandResult object by index. **Class** ICommandResults **Syntax** [C#] ```csharp ICommandResult get_Item( int index ); ``` [Visual C++] ```cpp 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#] ```csharp bool CompletelySuccessful { get; }; ``` [Visual C++] ```cpp 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. --- ## Page 29 Interfaces <page_number>29</page_number> # Kind Property Indicates the type of condition to be used by the query. **Class** ICondition **Syntax** [C#] ```csharp EConditionType Kind { get; }; ``` [Visual C++] ```cpp 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#] ```csharp object value { get; }; ``` [Visual C++] ```cpp HRESULT Value( [out, retval] VARIANT* Value ); ``` # Negation Property Negation. Specify False to “NOT” the expression. **Class** ICondition **Syntax** [C#] ```csharp EConditionType Negation { get; }; ``` [Visual C++] ```cpp 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#] ```csharp ICommandResult CommandResult { get; }; ``` [Visual C++] ```cpp HRESULT CommandResult( [out, retval] ICommandResult** CommandResult ); ``` ### Parameters **CommandResult** Returns the CommandResult object. --- ## Page 31 Interfaces <page_number>31</page_number> # Remove Method Remove a condition object from the collection. **Class** IConditions **Syntax** **[C#]** ```csharp void Remove( int index ); ``` **[Visual C++]** ```cpp 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#]** ```csharp void Add( EConditionType Kind, object value, bool Negation ); ``` **[Visual C++]** ```cpp 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#] ```csharp int count { get; }; ``` [Visual C++] ```cpp HRESULT Count( [out, retval] LONG* ); ``` ## Item Property Returns the condition object by index. ### Class IConditions ### Syntax [C#] ```csharp ICondition this[int index] { get; }; ``` [Visual C++] ```cpp 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++] ```cpp 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#] ```csharp IGalaxy this[object galaxyIdentifier] { get; }; ``` [Visual C++] ```cpp 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#] ```csharp int count { get; }; ``` [Visual C++] ```cpp 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. --- ## Page 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. --- ## Page 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#]** ```csharp ICommandResult CommandResult { get; }; ``` **[Visual C++]** ```cpp 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#]** ```csharp IgObjects QueryObjectsMultiCondition( EgObjectIsTemplateOrInstance templateOrInstance, IConditions conditions ); ``` **[Visual C++]** ```cpp HRESULT QueryObjectsMultiCondition( [in] EgObjectIsTemplateOrInstance templateOrInstance, [in] IConditions* Conditions, [out, retval] IgObjects** ); ``` **Parameters** *templateOrInstance* Indicates whether a gObject is a template or an instance. --- ## Page 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#] ```csharp IScriptLibraries QueryScriptLibraries(); ``` [Visual C++] ```cpp 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#] ```csharp string Name { get; }; ``` [Visual C++] ```cpp 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#] ```csharp void Backup( int lProcessId, string backupFilename, string GRNodeName, string Galaxy ); ``` [Visual C++] ```cpp 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). --- ## Page 40 <page_number>40</page_number> Chapter 2 API Reference # VersionString Property Retrieves the version string of the Galaxy. **Class** IGalaxy **Syntax** [C#] ```csharp string VersionString { get; } ``` [Visual C++] ```cpp 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#] ```csharp void Login( string UserName, string Password ); ``` [Visual C++] ```cpp 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#]** ```csharp void LoginEx( string UserName, string Password, bool bForceSynchronization ); ``` **[Visual C++]** ```cpp 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#] ```csharp void SynchronizeClient() ``` [Visual C++] ```cpp HRESULT SynchronizeClient(); ``` **Remarks** User should be logged in. # GetTimeMasterSettings Method Retrieves TimeMaster settings. **Class** IGalaxy **Syntax** [C#] ```csharp ISettings GetTimeMasterSettings(); ``` [Visual C++] ```cpp 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#] ```csharp IgObjects CreategObjectCollection(); ``` [Visual C++] ```cpp HRESULT CreategObjectCollection( [out, retval] IgObjects** gObjects ); ``` **Parameters** *gObjects* The newly created gObjects object. # ImportObjects Method Imports objects into the Galaxy. **Class** IGalaxy **Syntax** [C#] ```csharp void ImportObjects( string inputFile, bool OverwritesAllowed ); ``` [Visual C++] ```cpp 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#]** ```csharp IToolsets QueryToolsets(); ``` **[Visual C++]** ```cpp 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#]** ```csharp IgObjects QueryObjectsByName( EgObjectIsTemplateOrInstance templateOrInstance, ref string[] tagnames ); ``` --- ## Page 45 Interfaces <page_number>45</page_number> [Visual C++] ```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#]** ```csharp string GetUserDefaults( EUserDefault userDefault ); ``` **[Visual C++]** ```c++ HRESULT GetUserDefaults ( [in] EUserDefault userDefault, [out, retval] BSTR* defaultValue ); ``` ### Parameters **userDefault** The default. **defaultValue** The value of the default. --- ## Page 46 <page_number>46</page_number> Chapter 2 API Reference # VersionNumber Property Retrieves the version number of the Galaxy. **Class** IGalaxy **Syntax** [C#] ```csharp int VersionNumber { get; }; ``` [Visual C++] ```cpp 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#] ```csharp void SetUserDefaults( EUserDefault userDefault, string defaultValue ); ``` [Visual C++] ```cpp 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#] ```csharp void Restore( int lProcessId, string backupFilename, string GRNodeName, string Galaxy, bool bRestoreOlderVersion ); ``` [Visual C++] ```cpp 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. --- ## Page 48 <page_number>48</page_number> Chapter 2 API Reference # Logout Method Logs out from an ArchestrA Galaxy. **Class** IGalaxy **Syntax** [C#] ```csharp void Logout(); ``` [Visual C++] ```cpp 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#] ```csharp bool UpgradeRequired { get; }; ``` [Visual C++] ```cpp 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#]** ```csharp void MigrateGalaxy( string galaxyName, string grNodeName ); ``` **[Visual C++]** ```cpp 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#]** ```csharp string CdiVersionString { get; } ``` **[Visual C++]** ```cpp 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#] ```csharp ISettings GetSecuritySettings(); ``` [Visual C++] ```cpp 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#] ```csharp IConditions CreateConditionsObject(); ``` [Visual C++] ```cpp 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#] ```csharp IgObjects QueryObjects( EgObjectIsTemplateOrInstance templateOrInstance, EConditionType Kind, object value, EMatch MatchCondition ); ``` [Visual C++] ```cpp 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#] ```csharp void ImportScriptLib( string path ); ``` [Visual C++] ```cpp HRESULT ImportScriptLib( [in] BSTR path ); ``` **Parameters** path Path to the .aaslib file. # GetLocaleSettings Method Retrieves locale settings. **Class** IGalaxy **Syntax** [C#] ```csharp ISettings GetLocaleSettings( ); ``` [Visual C++] ```cpp 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#]** ```csharp void ExportAll( EExportType exportType, string outputFile ); ``` **[Visual C++]** ```cpp 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#]** ```csharp IGalaxySecurity GetReadOnlySecurity( ); ``` **[Visual C++]** ```cpp 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#] ```csharp ICommandResults CommandResults { get; }; ``` [Visual C++] ```cpp HRESULT CommandResults( [out, retval] ICommandResults** CommandResults ); ``` # GRLoad Method ## Class IGalaxy ## Syntax [C#] ```csharp void GRLoad( string CSVFileNameWithPath, GRLoadMode GRLoadMode ); ``` [Visual C++] ```cpp 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#] ```csharp void ImportObjectsEx( string inputFile, E_RESOLVE_VERSION_CONFLICT_ACTION versionMismatchPreference, E_RESOLVE_NAME_CONFLICT_ACTION nameConflictPreference, string appendToObjectName ); ``` [Visual C++] ```cpp 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#] ```csharp IToolsets QueryToolsetsEx( FolderType eFolderType ); ``` [Visual C++] ```cpp 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#] ```csharp string RoleName { get; } ``` [Visual C++] ```cpp HRESULT RoleName( [out, retval] BSTR *roleName ); ``` # AccessLevel Property Returns the access level of the Galaxy role. ## Class IGalaxyRole ## Syntax [C#] ```csharp int AccessLevel { get; } ``` [Visual C++] ```cpp 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++] ```cpp HRESULT Permissions( [out, retval] IPermissions **generalPermissions ); ``` # OperationalPermissions Property Returns the operational permissions of the Galaxy role. **Class** IGalaxyRole **Syntax** [C#] ```csharp IPermissions OperationalPermissions { get; }; ``` [Visual C++] ```cpp 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#] ```csharp IGalaxyRole this[object galaxyIdentifier] { get; }; ``` [Visual C++] ```cpp 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#] ```csharp int count { get; }; ``` [Visual C++] ```cpp HRESULT Count ( [out, retval] LONG* count ); ``` ## Parameters count Returns the number of roles in the collection. --- ## Page 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#] ```csharp EAUTHMODE AuthenticationMode { get; }; ``` [Visual C++] ```cpp HRESULT AuthenticationMode( [out, retval] EAUTHMODE *authMode ); ``` ### Parameters **AuthenticationMode** Indicates whether Galaxy security mode is none, Galaxy, OS User, or OS Group. --- ## Page 60 <page_number>60</page_number> Chapter 2 API Reference # SecurityGroupsAvailable Property Retrieves the available security groups of the Galaxy. **Class** IGalaxySecurity **Syntax** [C#] ```csharp ISecurityGroups SecurityGroupsAvailable { get; }; ``` [Visual C++] ```cpp 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#] ```csharp IGalaxyRoles RolesAvailable { get; }; ``` [Visual C++] ```cpp 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#] ```csharp IGalaxyUsers UsersAvailable { get; }; ``` [Visual C++] ```cpp 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#] ```csharp string LoginTime { get; }; ``` [Visual C++] ```cpp 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#] ```csharp string RoleUpdateInterval { get; }; ``` [Visual C++] ```cpp 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 `\`. ### FullName Property Returns the full name of the user retrieved from the domain controller in the form ` `. ### AssociatedRoles Property Returns collection of roles associated with this user. ## UserName Property Returns the user name along with the domain name in the form `\`. ### Class IGalaxyUser ### Syntax **[C#]** ```csharp string UserName { get; } ``` **[Visual C++]** ```cpp HRESULT UserName( [out, retval] BSTR* *userName ); ``` ## FullName Property Returns the full name of the user retrieved from the domain controller in the form ` `. ### Class IGalaxyUser ### Syntax **[C#]** ```csharp string FullName { get; } ``` **[Visual C++]** ```cpp 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#] ```csharp IGalaxyRoles AssociatedRoles { get; }; ``` [Visual C++] ```cpp 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#] ```csharp IGalaxyUser this[object galaxyIdentifier] { get; }; ``` [Visual C++] ```cpp 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#] ```csharp int count { get; }; ``` [Visual C++] ```cpp 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 Guide
--- ## Page 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#] ```csharp 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#]** ```csharp string HierarchicalName { get; }; ``` **[Visual C++]** ```cpp 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#]** ```csharp IAttributes Attributes { get; }; ``` **[Visual C++]** ```cpp 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#] ```csharp IAttributes ConfigurableAttributes { get; }; ``` [Visual C++] ```cpp 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#] ```csharp EPACKAGESTATUS ValidationStatus { get; }; ``` [Visual C++] ```cpp 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#]** ```csharp string[] Errors { get; }; ``` **[Visual C++]** ```cpp 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#]** ```csharp string[] Warnings { get; }; ``` **[Visual C++]** ```cpp 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#] ```csharp string checkedOutBy { get; }; ``` [Visual C++] ```cpp 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#] ```csharp ECheckoutStatus CheckoutStatus { get; }; ``` [Visual C++] ```cpp 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#]** ```csharp int ConfigVersion { get; }; ``` **[Visual C++]** ```cpp HRESULT ConfigVersion( [out, retval] LONG* theConfigVersion ); ``` **Parameters** **theConfigVersion** The configuration version. # Category Property The category of the object. **Class** IgObject **Syntax** **[C#]** ```csharp ECATEGORY category { get; }; ``` **[Visual C++]** ```cpp 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#] ```csharp string DerivedFrom { get; }; ``` [Visual C++] ```cpp 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#] ```csharp string basedOn { get; }; ``` [Visual C++] ```cpp 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#] ```csharp string Host { set; get; } ``` [Visual C++] [propget] ```csharp HRESULT Host ( [out, retval] BSTR* theHost ); ``` [propput] ```csharp HRESULT Host ( [in] BSTR NewHost ); ```
GRAccess Toolkit API User's Guide
--- ## 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#] ```csharp string GetObjectHelpURL( ); ``` [Visual C++] ```cpp HRESULT GetObjectHelpURL( [out, retval] BSTR* ); ``` # Save Method Saves the object after it is configured. Object must be checked out. ## Class IgObject ## Syntax [C#] ```csharp void Save( ); ``` [Visual C++] ```cpp 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++] ```cpp HRESULT CheckIn( [in, optional] BSTR CheckInComment ); ``` ## Parameters CheckInComment Check in an object. # CheckOut Method Checks out an object. ## Class IgObject ## Syntax [C#] ```csharp void CheckOut( ); ``` [Visual C++] ```cpp 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++] ```cpp 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#] ```csharp void Unload(); ``` [Visual C++] ```cpp HRESULT Unload(); ``` # EditStatus Property The edit status of the object. **Class** IgObject **Syntax** [C#] ```csharp EEditStatus EditStatus { get; }; ``` [Visual C++] ```cpp 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++] ```cpp 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#]** ```csharp void DeleteExtensionPrimitive( string ExtensionType, string ExtensionPrimitiveName ); ``` **[Visual C++]** ```cpp 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#]** ```csharp void RenameExtensionPrimitive( string OldPrimitiveName, string NewPrimitiveName ); ``` **[Visual C++]** ```cpp 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#]** ```csharp void AddUDA( string UDAName, MxDataType DataType, MxAttributeCategory category, MxSecurityClassification Security, bool IsArray, object ArrayElementCount ); ``` **[Visual C++]** ```cpp 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#]** ```csharp void DeleteUDA( string UDAName ); ``` **[Visual C++]** ```cpp HRESULT DeleteUDA( [in] BSTR UDAName ); ``` **Parameters** UDAName Delete a UDA by its name. # RenameUDA Method Renames a UDA. **Class** IgObject **Syntax** **[C#]** ```csharp 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++] ```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#]** ```csharp void UpdateUDA( string wszUDAInfo, MxDataType DataType, MxAttributeCategory category, MxSecurityClassification Security, bool IsArray, object ArrayElementCount ); ``` **[Visual C++]** ```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#] ```csharp ICommandResult CommandResult { get; }; ``` [Visual C++] ```cpp 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#] ```csharp ICommandResults CommandResults { get; }; ``` [Visual C++] ```cpp 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#] ```csharp string Area { set; }; ``` [Visual C++] ```cpp 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#] ```csharp string Host { set; }; ``` [Visual C++] ```cpp 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#] ```csharp void AddFromCollection( IgObjects gObjects ); ``` [Visual C++] ```cpp 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#] ```csharp void Upload( EAutomaticallyUndocheckout automaticallyUndocheckout, ESkipOtherUsersCheckedOutObjects skipOtherUsersCheckedOutObjects, ESkipObjectsWithPendingUpdates skipObjectsWithPendingUpdates ); ``` GRAccess Toolkit API User's Guide --- ## Page 91 Interfaces <page_number>91</page_number> [Visual C++] ```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#]** ```csharp void CheckIn( string CheckInComment ); ``` **[Visual C++]** ```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#] ```csharp void Add( IgObject gObject ); ``` [Visual C++] ```cpp 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#] ```csharp string Container { set; }; ``` [Visual C++] ```cpp 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#]** ```csharp void ExportObjects( EExportType exportType, string outputFile ); ``` **[Visual C++]** ```cpp 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#]** ```csharp void ExportObjectsAsProtected( string outputFile ); ``` **[Visual C++]** ```cpp 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#] ```csharp void DeleteAllObjects(); ``` [Visual C++] ```cpp HRESULT DeleteAllObjects(); ``` ## CheckOut Method Checks out the gObjects in the collection. ### Class IgObjects ### Syntax [C#] ```csharp void CheckOut(); ``` [Visual C++] ```cpp 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#] ```csharp string SecurityGroup { set; }; ``` [Visual C++] ```cpp 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#] ```csharp void Undeploy( EForceOffScan UndeployRule, bool markAsUndeployedOnFailure ); ``` [Visual C++] ```cpp 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#] ```csharp void Deploy( EActionForCurrentlyDeployedObjects actionForDeployedObjects, ESkipIfCurrentlyUndeployed skipIfCurrentlyUndeployed, EDeployOnScan deployOnScan, EForceOffScan forceOffScan, bool markAsDeployedOnStatusMismatch ); ``` [Visual C++] ```cpp 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#] ```csharp IgObject this[gObjectIdentifier] { get; } ``` [Visual C++] ```cpp 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 Guide
--- ## Page 98 <page_number>98</page_number> Chapter 2 API Reference # Count Property Returns the number of gObjects in the collection. ## Class IgObjects ## Syntax [C#] ```csharp int count { get; }; ``` [Visual C++] ```cpp HRESULT Count( [out, retval] LONG* ); ``` # UndoCheckOut Method Undo check-out on the gObjects in the collection. ## Class IgObjects ## Syntax [C#] ```csharp void UndoCheckOut(); ``` [Visual C++] ```cpp HRESULT UndoCheckOut(); ``` # DeployEx Method Deploy the instances in the given collection of objects. ## Class IgObjects ## Syntax [C#] ```csharp 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++] ```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#] ```csharp void UndeployEx ( EForceOffScan UndeployRule, bool markAsUndeployedOnFailure, string strCustomData ); ``` ### [Visual C++] ```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#] ```csharp void UploadEx( EAutomaticallyUndocheckout automaticallyUndocheckout, ESkipOtherUsersCheckedOutObjects skipOtherUsersCheckedOutObjects, ESkipObjectsWithPendingUpdates skipObjectsWithPendingUpdates, string strCustomData ); ``` ### [Visual C++] ```csharp 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#] ```csharp ICommandResult CommandResult { get; } ``` [Visual C++] ```cpp HRESULT CommandResult( [out, retval] ICommandResult** CommandResult ); ``` **Parameters** *CommandResult* Returns the *CommandResult* object.
GRAccess Toolkit API User's Guide
--- ## Page 102 <page_number>102</page_number> Chapter 2 API Reference # CreateGalaxy Method Create a new Galaxy on the GR node. ## Class IGRAccess ## Syntax [C#] ```csharp void CreateGalaxy( string galaxyName, string GRNodeName, bool enableSecurity, EAuthenticationMode AuthenticationMode, string osUserName ); ``` [Visual C++] ```cpp 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 Guide
--- ## Page 103 Interfaces <page_number>103</page_number> # DeleteGalaxy Method Delete a Galaxy. **Class** IGRAccess **Syntax** **[C#]** ```csharp void DeleteGalaxy( string galaxyName, string grNodeName ); ``` **[Visual C++]** ```cpp 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#]** ```csharp IGalaxies QueryGalaxies ( string grNodeName ); ``` **[Visual C++]** ```cpp 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#] ```csharp void CreateGalaxyFromTemplate( string createGalaxyTemplateName, string galaxyName, string grNodeName ); ``` [Visual C++] ```cpp 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 Guide
--- ## Page 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 Guide
--- ## Page 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#] ```csharp 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#] ```csharp void AddUDA( string UDAName, MxDataType DataType, MxAttributeCategory category, MxSecurityClassification Security, bool IsArray, object ArrayElementCount ); ``` ### [Visual C++] ```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> ```csharp 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#] ```csharp string Area { set; get; }; ``` [Visual C++] ```csharp // 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#] ```csharp IAttributes Attributes { get; }; ``` [Visual C++] ```cpp // 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#] ```csharp string basedOn { get; }; ``` [Visual C++] ```cpp // 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++] ```cpp // 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#] ```csharp VBGUID CategoryGUID { get; }; ``` [Visual C++] ```cpp // 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++] ```cpp // 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#] ```csharp void CheckIn( string CheckInComment ); ``` [Visual C++] ```cpp // 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++] ```cpp // Checks out an object. HRESULT CheckOut(); ``` # CheckoutStatus Property Returns the check out status of the object. **Class** IInstance **Syntax** [C#] ```csharp ECheckoutStatus CheckoutStatus { get; }; ``` [Visual C++] ```cpp // 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#] ```csharp 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#] ```csharp IAttributes ConfigurableAttributes { get; }; ``` [Visual C++] ```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#] ```csharp 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#] ```csharp string ContainedName { set; get; } ``` ### [Visual C++] ```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#] ```csharp string Container { set; get; }; ``` [Visual C++] ```cpp // 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#] ```csharp void DeleteExtensionPrimitive( string ExtensionType, string ExtensionPrimitiveName ); ``` GAccess Toolkit API User's Guide --- ## Page 117 Interfaces <page_number>117</page_number> [Visual C++] ```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#]** ```csharp void DeleteInstance ( EForceDeleteInstanceOption ForceDeleteOption ); ``` **[Visual C++]** ```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 Guide
--- ## Page 118 <page_number>118</page_number> Chapter 2 API Reference # DeleteUDA Method Delete a UDA. **Class** IInstance **Syntax** [C#] ```csharp void DeleteUDA( string UDAName ); ``` [Visual C++] ```cpp // 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#] ```csharp 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++] ```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#] ```csharp int DeployedVersion { get; }; ``` #### [Visual C++] ```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++] ```cpp // 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> ```csharp // 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#] ```csharp EDeploymentStatus DeploymentStatus { get; }; ``` [Visual C++] ```csharp 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#] ```csharp string DerivedFrom { get; }; ``` [Visual C++] ```csharp // 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++] ```cpp // 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#] ```csharp string[] Errors { get; }; ``` [Visual C++] ```cpp // 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++]** ```cpp //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#] ```csharp string GetObjectHelpURL(); ``` [Visual C++] ```cpp // 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#] ```csharp string HierarchicalName { get; }; ``` [Visual C++] ```cpp // 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++] ```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#] ```csharp void RenameExtensionPrimitive( string OldPrimitiveName, string NewPrimitiveName ); ``` [Visual C++] ```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#] ```csharp void RenameUDA( string OldUDAName, string NewUDAName ); ``` [Visual C++] ```cpp // 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#] ```csharp void Save(); ``` [Visual C++] ```cpp // 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#]** ```csharp string Tagname { set; get; } ``` **[Visual C++]** ```cpp // Returns the Tagname of this object. [propget] HRESULT Tagname( // The Tagname of this object. [out, retval] BSTR* theTagname ); ``` ```cpp // 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#]** ```csharp 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++] ```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#]** ```csharp void Undeploy( EForceOffScan UndeployRule, ECascade cascade, bool markAsUndeployedOnFailure ); ``` **[Visual C++]** ```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#]** ```csharp void UndoCheckOut(); ``` **[Visual C++]** ```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#]** ```csharp void Unload(); ``` **[Visual C++]** ```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++] ```cpp // 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#] ```csharp void Upload( EAutomaticallyUndocheckout automaticallyUndocheckout, ESkipOtherUsersCheckedOutObjects skipOtherUsersCheckedOutObjects, ESkipObjectsWithPendingUpdates skipObjectsWithPendingUpdates ); ``` [Visual C++] ```cpp 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#] ```csharp void UploadEx( EAutomaticallyUndocheckout automaticallyUndocheckout, ESkipOtherUsersCheckedOutObjects skipOtherUsersCheckedOutObjects, ESkipObjectsWithPendingUpdates skipObjectsWithPendingUpdates, string strCustomData ); ``` [Visual C++] ```cpp // 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#] ```csharp EPACKAGESTATUS ValidationStatus { get; }; ``` [Visual C++] ```cpp // 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#] ```csharp string[] Warnings { get; }; ``` [Visual C++] ```cpp // 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.
GRAccess Toolkit API User’s Guide
--- ## 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++]** ```cpp 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#] ```csharp void Empty(); ``` [Visual C++] ```cpp 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#] ```csharp void PutBoolean( bool newVal ); ``` [Visual C++] ```cpp 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#] ```csharp void PutInteger( int newVal ); ``` [Visual C++]> ```cpp 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#] ```csharp void PutFloat( float newVal ); ``` [Visual C++] ```cpp 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#] ```csharp void PutDouble( double newVal ); ``` [Visual C++] ```cpp 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#] ```csharp void PutString( string newVal ); ``` [Visual C++] ```cpp 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 Guide
--- ## Page 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#] ```csharp void PutTime( ref VBFILETIME pNewVal ); ``` [Visual C++] ```cpp 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#] ```csharp void PutElapsedTime ( ref VB_LARGE_INTEGER pNewVal ); ``` [Visual C++] ```cpp 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#] ```csharp void PutMxReference( IMxReference newVal ); ``` [Visual C++] ```cpp 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#] ```csharp void PutMxStatus ( ref MxStatus newVal ); ``` GRAccess Toolkit API User's Guide --- ## Page 143 Interfaces <page_number>143</page_number> [Visual C++] ```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#] ```csharp void PutMxDataType ( MxDataType newVal ); ``` [Visual C++] ```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#] ```csharp void PutMxSecurityClassification( MxSecurityClassification newVal ); ``` [Visual C++] ```cpp 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#] ```csharp void PutMxDataQuality( ref short newVal ); ``` [Visual C++] ```cpp 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#] ```csharp void PutCustomStruct ( int guid, int structSize, ref byte pStruct ); ``` [Visual C++] ```cpp 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#] ```csharp void PutCustomEnum( string value, short ordinal, short primitiveId, short attributeId ); ``` [Visual C++] ```cpp 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 Guide
--- ## Page 147 Interfaces <page_number>147</page_number> # GetDataType Method Returns the data type of the value stored in the MxValue. **Class** IMxValue **Syntax** [C#] ```csharp MxDataType GetDataType(); ``` [Visual C++] ```cpp 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#] ```csharp bool GetBoolean(); ``` [Visual C++] ```cpp 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#] ```csharp int GetInteger(); ``` [Visual C++] ```cpp 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#] ```csharp float GetFloat(); ``` [Visual C++] ```cpp 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#] ```csharp double GetDouble(); ``` [Visual C++] ```cpp 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#] ```csharp string GetString(); ``` [Visual C++] ```cpp 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 Guide
--- ## Page 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#] ```csharp void GetTime( out VBFILETIME pVal ); ``` [Visual C++] ```cpp 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#] ```csharp VB_LARGE_INTEGER GetElapsedTime(); ``` [Visual C++] ```cpp 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#] ```csharp IMxReference GetMxReference(); ``` [Visual C++] ```cpp 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#] ```csharp MxStatus GetMxStatus(); ``` [Visual C++] ```cpp 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#] ```csharp MxDataType GetMxDataType(); ``` [Visual C++] ```cpp 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#] ```csharp MxSecurityClassification GetMxSecurityClassification(); ``` [Visual C++] ```cpp 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#] ```csharp short GetMxDataQuality(); ``` [Visual C++] ```cpp 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#] ```csharp 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++] ```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#] ```csharp void GetCustomEnum( out string pValue, out short pOrdinal, out short pPrimitiveId, out short pAttributeId ); ``` ### [Visual C++] ```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#] ```csharp void GetDimensionCount ( out short nDimensions ); ``` [Visual C++] ```cpp 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 Guide
--- ## Page 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#] ```csharp void PutElement ( int index, MxValue pMxValue ); ``` [Visual C++] ```cpp 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#]** ```csharp void GetElement ( int index1, MxValue pMxValue ); ``` **[Visual C++]** ```cpp 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#]** ```csharp void GetDimensionSize ( out int pSize ); ``` GRAccess Toolkit API User's Guide --- ## Page 161 Interfaces <page_number>161</page_number> [Visual C++] ```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#] ```csharp void PutCustomStructVB ( int guid, ref byte[] pStruct ); ``` [Visual C++] ```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#] ```csharp 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#]** ```csharp void PutInternationalStrings( int count, ref InternationalizedString strings ); ``` **[Visual C++]** ```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#]** ```csharp void PutInternationalStringsVB( ref InternationalizedString[] ppsa ); ``` **[Visual C++]** ```cpp 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#]** ```csharp void GetInternationalStrings ( out int count, System.IntPtr locals ); ``` **[Visual C++]** ```cpp 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#] ```csharp void GetInternationalStringsVB( ref InternationalizedString[] ppsa ); ``` [Visual C++] ```cpp 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#] ```csharp string GetInternationalString( int locale ); ``` [Visual C++] ```cpp 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#] ```csharp void PutInternationalString( int locale, string InternationalizedString ); ``` [Visual C++] ```cpp 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 Guide
--- ## Page 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.
GRAccess Toolkit API User's Guide
--- ## 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#] ```csharp string PermissionName { get; }; ``` [Visual C++] ```cpp 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#] ```csharp string PermissionParentName { get; }; ``` [Visual C++] ```cpp 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#] ```csharp 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#] ```csharp bool HasChildren { get; }; ``` [Visual C++] ```c++ HRESULT HasChildren( [out, retval] VARIANT_BOOL *hasChildren ); ``` # ChildPermissions Property Returns the collection of child permissions. **Class** IPermission **Syntax** [C#] ```csharp IPermissions ChildPermissions { get; }; ``` [Visual C++] ```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++] ```cpp HRESULT IsASecurityGroup( [out, retval] VARIANT_BOOL *isSecurityGroup ); ``` # SecurityGroup Property Retrieves the security group object. **Class** IPermission **Syntax** [C#] ```csharp ISecurityGroup SecurityGroup { get; }; ``` [Visual C++] ```cpp 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#] ```csharp IPermission this[object galaxyIdentifier] { get; }; ``` [Visual C++] ```cpp 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#] ```csharp int count { get; }; ``` [Visual C++] ```cpp HRESULT Count( [out, retval] LONG* ); ```
GRAccess Toolkit API User's Guide
--- ## 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#] ```csharp ICommandResult CommandResult { get; }; ``` [Visual C++] ```cpp HRESULT CommandResult( [out, retval] ICommandResult** CommandResult ); ``` ### Parameters **CommandResult** Returns the CommandResult object.
GRAccess Toolkit API User's Guide
--- ## Page 174 <page_number>174</page_number> Chapter 2 API Reference # Item Property Return a script library. ## Class IScriptLibraries ## Syntax [C#] ```csharp IScriptLibrary this[object scriptLibraryIdentifier] { get; }; ``` [Visual C++] ```cpp 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#] ```csharp int count { get; }; ``` [Visual C++] ```cpp 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#] ```csharp void Add( string scriptLibraryPath ); ``` [Visual C++] ```cpp 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 Guide
--- ## Page 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#] ```csharp ICommandResult CommandResult { get; }; ``` [Visual C++] ```cpp HRESULT CommandResult( [out, retval] ICommandResult** CommandResult ); ``` ## Parameters CommandResult Returns the CommandResult object. # Export Method Export this script library. ## Class IScriptLibrary ## Syntax [C#] ```csharp void Export( string path ); ``` [Visual C++] ```cpp 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#] ```csharp string Name { get; }; ``` [Visual C++] ```cpp 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#] ```csharp string GroupName { get; }; ``` GRAccess Toolkit API User's Guide --- ## Page 178 <page_number>178</page_number> Chapter 2 API Reference [Visual C++] ```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#] ```csharp IgObjects gObjects { get; }; ``` [Visual C++] ```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#] ```csharp ISecurityGroup this[object galaxyIdentifier] { get; }; ``` [Visual C++] ```cpp 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#] ```csharp int count { get; }; ``` [Visual C++] ```cpp HRESULT Count ( [out, retval] LONG* count ); ``` ## Parameters count Returns the number of security groups in the collection.
GRAccess Toolkit API User's Guide
--- ## Page 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#] ```csharp ICommandResult CommandResult { get; }; ``` [Visual C++] ```cpp 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#] ```csharp void Cancel(); ``` [Visual C++] ```cpp HRESULT Cancel(); ``` # Instance Property Get the instance for configuring this object. **Class** ISettings **Syntax** [C#] ```csharp IInstance Instance { get; }; ``` [Visual C++] ```cpp 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#] ```csharp void Close(); ``` [Visual C++] ```cpp 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 Guide
--- ## Page 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 Guide
--- ## Page 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#]** ```csharp void AddExtensionPrimitive( string ExtensionType, string ExtensionPrimitiveName, bool IsObjectExtension ); ``` **[Visual C++]** ```cpp 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#] ```csharp void AddUDA( string UDAName, MxDataType DataType, MxAttributeCategory category, MxSecurityClassification Security, bool IsArray, object ArrayElementCount ); ``` [Visual C++] ```cpp // 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#] ```csharp 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#] ```csharp IAttributes Attributes { get; }; ``` [Visual C++] ```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#] ```csharp string basedOn { get; }; ``` [Visual C++] ```cpp // 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#] ```csharp ECATEGORY category { get; }; ``` [Visual C++] ```cpp // 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++] ```cpp // 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#] ```csharp void CheckOut(); ``` [Visual C++] ```cpp // Checks out an object. HRESULT CheckOut(); ``` # CheckoutStatus Property Returns the check out status of the object. **Class** ITemplate **Syntax** [C#] ```csharp 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#] ```csharp ICommandResult CommandResult { get; }; ``` [Visual C++] ```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#] ```csharp ICommandResults CommandResults { get; }; ``` [Visual C++] ```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#]** ```csharp IAttributes ConfigurableAttributes { get; }; ``` **[Visual C++]** ```cpp // 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#]** ```csharp int ConfigVersion { get; }; ``` **[Visual C++]** ```cpp // 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#] ```csharp 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#] ```csharp 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#] ```csharp IInstance CreateInstance( string Name, bool createContainedObjects ); ``` ### [Visual C++] ```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#]** ```csharp IgObjects CreateInstances( ref string[] tagnames, bool createContainedObjects ); ``` **[Visual C++]** ```cpp 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 Guide
--- ## Page 195 Interfaces <page_number>195</page_number> # CreateTemplate Method Derive an a new template from this template. ## Class ITemplate ## Syntax [C#] ```csharp ITemplate CreateTemplate( string Name, bool createContainedObjects ); ``` [Visual C++] ```cpp 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#] ```csharp 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++] ```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#] ```csharp void DeleteTemplate( EForceDeleteTemplateOption ForceDeleteTemplateOption ); ``` [Visual C++] ```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#]** ```csharp void DeleteUDA( string UDAName ); ``` **[Visual C++]** ```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#]** ```csharp string DerivedFrom { get; }; ``` **[Visual C++]** ```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++] ```cpp // 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#] ```csharp string[] Errors { get; }; ``` [Visual C++] ```cpp // 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++]** ```cpp //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++] ```cpp // 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#] ```csharp string HierarchicalName { get; }; ``` [Visual C++] ```cpp // 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#] ```csharp string Host { set; get; } ``` [Visual C++] ```cpp // 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#] ```csharp 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#] ```csharp 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#] ```csharp void Save(); ``` [Visual C++] ```cpp // 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#] ```csharp string Tagname { set; get; } ``` [Visual C++] ```cpp // 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#] ```csharp string Toolset { set; get; } ``` [Visual C++] ```cpp [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#] ```csharp void UndoCheckOut(); ``` [Visual C++] ```cpp // 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#] ```csharp void Unload(); ``` [Visual C++] ```cpp // 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#] ```csharp void UpdateUDA( string wszUDAInfo, MxDataType DataType, MxAttributeCategory category, MxSecurityClassification Security, bool IsArray, object ArrayElementCount ); ``` [Visual C++] ```cpp // 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#] ```csharp EPACKAGESTATUS ValidationStatus { get; }; ``` ### [Visual C++] ```csharp // 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#] ```csharp 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#]** ```csharp ICommandResult CommandResult { get; }; ``` **[Visual C++]** ```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#]** ```csharp IToolsets GetChildToolsets( int depth ); ``` **[Visual C++]** ```cpp // 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#]** ```csharp void MoveToToolset( string parentToolset ); ``` **[Visual C++]** ```cpp // 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#] ```csharp string Name { get; }; ``` [Visual C++] ```cpp HRESULT Name( [out, retval] BSTR* theToolset ); ``` **Parameters** theToolset The toolset name. # Rename Method Renames this toolset. **Syntax** [C#] ```csharp void Rename( string newName ); ``` [Visual C++] ```cpp 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#]** ```csharp void Add( string newToolst ); ``` **[Visual C++]** ```cpp HRESULT Add( [in] BSTR newToolst ); ``` ### Parameters **newToolset** The name of the new toolset.
GRAccess Toolkit API User's Guide
--- ## Page 211 Interfaces <page_number>211</page_number> # AddToolSet Method Add the toolset to the Galaxy. **Class** IToolsets **Syntax** **[C#]** ```csharp void AddToolSet( string parentToolset, string newToolset ); ``` **[Visual C++]** ```cpp // 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#]** ```csharp void DeleteToolSet( string toolsetToDelete ); ``` **[Visual C++]** ```cpp // 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++] ```cpp 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#] ```csharp int count { get; }; ``` [Visual C++] ```cpp 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
GRAccess Toolkit API User's Guide
--- ## Page 214 <page_number>214</page_number> Chapter 2 API Reference * EUserDefaults * EgObjectIsTemplateOrInstance * MxAttributeCategory * MxPropertyLockedEnum # EATTRIBUTEPROPERTY Lists property IDs of all attributes. **enum EATTRIBUTEPROPERTY** ```c { 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, ```
GRAccess Toolkit API User's Guide
--- ## Page 215 Type Definitions <page_number>215</page_number> ```c 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. ```csharp 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. ```csharp enum EAuthenticationMode { osAuthenticationMode = 0, galaxyAuthenticationMode = 1, } ``` ## Members galaxyAuthenticationMode Galaxy Authentication Mode osAuthenticationMode OS Authentication Mode # EAutomaticallyUndocheckout Automatically undoes checkout. ```csharp 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. ```csharp enum EBASERUNTIMEOBJECT { idxBROAttributeUndefined = -1, idxBROPriimitiveList = 100, idxBRODeployComplete = 101, } ```
GRAccess Toolkit API User's Guide
--- ## Page 219 Type Definitions <page_number>219</page_number> ```c 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 ```c 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 ```c 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. ```c 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. ```c 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. ```csharp 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. ```c 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. ```csharp 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. ```c++ 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. ```c++ 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 Guide
--- ## Page 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. ```csharp 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. ```csharp 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. ```csharp enum EForceDeleteTemplateOption { dontForceTemplateDelete = 0, cascadeDeleteDontUndeploy = 1, cascadeDeleteUndeployDescendentsIfRunningOffScan = 2, cascadeDeleteUndeployDescendentsIfRunning = 3 } ```
GRAccess Toolkit API User's Guide
--- ## 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. ```csharp 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. ```csharp enum EGRCommandResult { cmdUnknownError = -1, cmdSuccess = 0, cmdInsufficientPermissions = 101, cmdNoSuchGRNode = 102, cmdNoSuchUser = 103, cmdPasswordIncorrect = 104, cmdLicenseUnavailable = 105, } ```
GRAccess Toolkit API User's Guide
--- ## Page 234 <page_number>234</page_number> Chapter 2 API Reference ```c 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 Guide
--- ## Page 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 Guide
--- ## Page 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. ```c 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. ```c 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. ```csharp 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. ```csharp 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 Guide
--- ## Page 240 <page_number>240</page_number> Chapter 2 API Reference # EUserDefault The user default. ```csharp enum EUserDefault { defaultPlatform = 1, defaultAppEngine = 2, defaultHistorianNode = 3, defaultArea = 4, defaultSecurityGroup = 5 } ``` ## Members
defaultSecurityGroupThe name of the default security group of the user.
defaultHistorianNodeThe name of the historian node name of the user.
defaultAppEngineThe name of the default AppEngine of the user.
defaultAreaThe name of the default Area of the user.
defaultPlatformThe name of the default Platform of the user.
# EgObjectIsTemplateOrInstance Indicates whether a gObject is a template or an instance. ```csharp enum EgObjectIsTemplateOrInstance { gObjectIsTemplate = 0, gObjectIsInstance = 1, } ``` ## Members
gObjectIsTemplateGObject is a Template.
gObjectIsInstanceGObject is a Instance.
GRAccess Toolkit API User's Guide
--- ## Page 241 Type Definitions <page_number>241</page_number> # MxAttributeCategory Indicates the category of an attribute. ```csharp 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. ```csharp 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: ```c #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: ```c #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. ```c++ // 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 #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 ```c if (SUCCEEDED(comInit)) { CoUninitialize(); } } private: HRESULT comInit; }; ``` ```c int _tmain(int argc, _TCHAR* argv[]) { COMINIT SmartComInitialize; CComPtr spGRApp; HRESULT hr = spGRApp.CoCreateInstance ( __uuidof(GRAccessApp) ); if (spGRApp == NULL) return -1; CComPtr 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 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> ```c++ CComPtr 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 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 spGObjects; _variant_t vtTemplateName = L"$UserDefined"; spGObjects = spGalaxy->QueryObjects (gObjectIsTemplate,NameEquals,&vtTemplateName,MatchCondition ); CComPtr spGObject; spGObjects->get_Item (vtTemplateName,&spGObject); CComPtr spInstance; CComQIPtr spTemplate = spGObject; time_t ltime; ``` GRAccess Toolkit API User's Guide --- ## Page 248 <page_number>248</page_number> Chapter 2 API Reference ```c++ 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 spAttributes; spInstance->get_ConfigurableAttributes (&spAttributes); CComPtr 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 spAttrib1 = spAttributes->GetItem(i); wprintf(L"%s\n",spAttrib1->GetName ().GetBSTR ()); } CComPtr spNamesValue; spNamesValue.CoCreateInstance (__uuidof(MxValue)); ``` GRAccess Toolkit API User's Guide --- ## Page 249 GRAccess Code Examples <page_number>249</page_number> ```c for(int i=1;i<=5;i++) { CComPtr 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. 1. Using Visual Studio, create a new C# console application "CreateGalaxyExample". 2. 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. ``` 3. 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> ```csharp 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 Guide
--- ## Page 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 ---