Configuration Management Interface

The Configuration Management Interface (CMI) contains services to manage the component database and configurations. This section describes the CMI and contains a complete programming reference.


Overview

The Configuration Management Interface (CMI) contains services to manage the component database, database objects, configurations, and repositories. It also contains the code to build the run-time image (build process). The CMI provides the sole interface between the component database, configurations, and the user (i.e. the user interface tools such as Target Designer). The interface is exposed as a hierarchy of COM Automation objects that map onto the core features of the architecture (platforms, components, etc). Some of the core logic behind these objects is wired into the CMI, however many of the key functions associated with a component instance are implemented as script that is part of the configuration and the component. This provides inherent flexibility and extensibility without the need to rebuild or alter the CMI. The CMI is used both by tools (component authoring, target designer) as well as by configuration and component script code. The CMI does not display any UI of its own but it does fire events into its client application at times when UI services are needed.


Object Model

The picture below shows the CMI object model. Rounded boxes represent collections, which contain a set of individual objects that then reference the next object in the hierarchy. For example, the Platforms collection contains individual Platform objects, each of which contains a Groups collection.

Each of the objects depicted above is either a primary or a secondary object. Primary objects (shown in italic) are essentially stand-alone objects that are made available as a result of importing data into the database from a carrier file. All primary objects have either one or two unique GUIDs that identify them. Secondary objects generally specify data that is logically contained within a primary object. For example, a Component primary object can specify a list of resources that are to be processed during the building of a target system configuration (e.g. files, registry keys). Each resource is represented as a secondary Resource object.

In addition to the references between the objects shown in the hierarchy there also many back-pointers for the sake of convenience. Most objects have properties that return the top level CMI object as well as their containing Platform object (e.g. Resource.CMI and Resource.Platform).

All CMI objects have properties that describe the the object's state and some have methods to manipulate the object. Many objects also have a property called Properties that is a collection of Property objects. This collection allows CMI clients to extend the property set of an object both in the database and in a configuration.

Only the top level object CMI and Utilities are publicly creatable (using CoCreateInstance in C++, CreateObject in Visual Basic and VBScript, and ActiveXObject in JScript). All other objects are accessed from the CMI object. Component script never creates a CMI object as event handlers always receive the relevant object(s) as parameters. Access to the CMI object and the containing platform is always available using back-pointer properties.

After creating the the CMI object, the first call must be OpenDB. This connects the CMI to the component database and is a prerequisite for all CMI operations. The client can then use the CMI object to browse the database, import new objects into the database and manipulate configurations. When the client has completed its work with the database it must call CloseDB to close the connection.

The CMI object also fires events that a client application can sink in order to provide end-user services such as displaying component configuration UI, displaying messages from script, etc.


Collections

The object model makes extensive use of OLE automation collections to represent sets of objects. Collections of database objects (e.g. Platforms) are always returned from a method on the owning object (e.g. CMI.GetPlatforms). Collections of configuration objects (e.g. Instance.Properties) are always automatically populated.

Items within all collections can be referenced by ordinal index (one-based). Each object in a collection has an Index property (e.g. Platform.Index) that indicates its ordinal position in the collection. For database collections, this does not correspond to its position in the entire set of objects - only within the collection. An object that resides outside of a collection will always have an Index value of -1.

Many collections also allow referencing an item by a string key that is a uniquely identifying object property. For example the Platforms collection allows referencing elements in the collection by Platform.VSGUID). The following might be equivalent:

Set SomePlatform = Platforms(1)

Set SomePlatform = Platforms("{c694289a-67ba-4976-a90f-6312121ebe7b}")

All collections support the For...Each iteration syntax used in Visual Basic and VBScript. In JScript use the Enumerator object. In C++, all objects have a _NewEnum property that returns an IEnumVARIANT that will iterate IDispatch interfaces on the collection elements. The application can call IDispatch::QueryInterface to acquire the dual interface on the object. Alternatively, C++ applications can use the Visual C++ #import feature to generate an enumerator class.


Scripting

As part of the processing for various method calls, the CMI will invoke a method in configuration script. This is known as 'firing a script event'. The configuration's script is defined by its platform and comes from the Platform.DefaultConfigScript property. When a configuration is created or opened, the CMI loads its script using the specified scripting engine from Platform.DefaultScriptLanguage. The script remains loaded until the configuration is closed. This allows script code to maintain state in global variables between the invocation of event handlers.

The CMI adds a variable called cmiThis to the configuration scripting namespace that contains the Configuration object. If the event handler needs access to an Instance object then it is passed as a parameter. Note that all identifiers beginning with the prefix "cmi" are reserved and should not be used by configuration or component script.

The configuration's loaded script can be accessed externally from the Configuration.Script property. This property returns an object that can be used to directly call public functions in the script code. For example, to call a configuration script function called "Foo", the syntax is Configuration.Script.Foo.

Configuration script can call functions in resource type script. Resource type script is loaded when the ResourceType.Script property is first accessed. It can only be accessed from Resource.Type.Script when the Resource object is part of a configuration or an instance. Attempting to access ResourceType.Script when the owning Resource represents a database object will return an error.

Resource type script stays loaded until the ResourceType object is released so the script can maintain state in global variables as long as a reference is maintained on the object. When accessing a ResourceType object through the Resource.Type property, the same object is always returned, regardless of context and regardless of the owning Resource object. For example, if two instances both have a resource of the same type, then the Resource.Type property of both resources will return the same ResourceType object.

Configuration script can also call methods in component script. Component script is loaded when a component is added to a configuration and an Instance object is created or when a configuration containing the component is opened. Like configuration script, component script stays loaded until the configuration is closed so components can also maintain state in global variables. If the component has one or more prototypes then each one has its own private scripting context so there are no namespace collisions between global variables and private functions. The CMI itself does not call any methods in component script. Consult the documentation for the platform's script for information on how it calls component script.

The CMI also adds a variable called cmiThis to the component scripting namespace that contains the Instance object. If the component has a prototype then it also adds an object variable called cmiSuper that is the prototype's script. This allows the script code of a component to invoke a function in its prototype's code. If the component does not have a prototype then cmiSuper will be null.

In addition to cmiThis, the component scripting namespace also has a variable called cmiComponent that contains the Component object that owns the script.

The loaded script of all components in the prototype chain is available externally as Instance.Script. This object presents a combined view of the public functions in each of the components' script code. This mechanism allows the script code of one component to override a public function in the script code of one of its prototypes. This is similar to the way virtual functions work in C++. For example, calling Instance.Script.Foo will call the function "Foo" in the most derived component that defines it.

If component script simply makes a call to "Foo", (without using Instance.Script), then if the component itself does not implement "Foo", the CMI will attempt to find it in the component's prototype. If the prototype does not implement the function, then the CMI continues with the prototype's prototype and so on up to the base component.

If component script calls cmiSuper.Foo, then the CMI begins looking for the function with the prototype's script and continues from there up to the base component.

While this virtual function mechanism may not typically be used by most components, it allows a platform author to write default handlers for all component instance events in a base component that is specified in Platform.BaseComponentVIGUID. It is the platform that determines the events on the instance and the platform can also optionally define default handlers for them.

A complete list of events fired on configuration script can be found in the topic Configuration Script Events.


Debugging Script

The CMI uses Active Script debugging. Any script language supporting the Active Script debugging interfaces can be debugged using the Microsoft Script Debugger, Microsoft Visual Inter-Dev or any other Active Script debugger.

To specify that script code should be displayed in the debugger the application must set CMI.DebugScript before the script engine is loaded. The script engine is loaded when a Configuration or an Instance is created or loaded.

When the engine is loaded, the debugger will be started (if it is not already running) and a document will be added to it displaying the script code. At this point no code has run yet (including global code i.e. code outside any functions or procedures). Breakpoints can optionally be set and the debugger's run or single-step command must be executed.

It is also possible to invoke the debugger only when an error occurs in the script code. To use this option set CMI.DebugOnScriptError before the script engine is loaded.

The debugger will display a document for every Configuration and Instance created or loaded by the application. It is highly recommended that both configurations and components set the optional DisplayName property as it will be used to identify the script code in the debugger. For Instance objects, there will be a separate document window for each component in Instance.ComponentChain that has script code. Instance.Comment is used as a prefix to identify the Instance. If more than one Component in the chain has script then the additional document windows are identified using the same prefix followed by the display name of the Component.


Script Events

Configuration Script Events

The following is a list of the events fired on configuration script as part of the processing of method calls on CMI objects. The CMI does not define how a configuration should handle these events. They are fired in order to allow the configuration script to customize the behavior of the CMI method calls.

Event | Description
cmiOnNewConfig() | Fired by Platform.NewConfiguration. cmiThis references a completely initialized Configuration object.
cmiOnOpenConfig() | Fired by Platform.OpenConfiguration and CMI.OpenConfiguration. cmiThis references a completely loaded Configuration object. A typical handler will compare Configuration.Generation and CMI.Generation to determine if the database has changed since the Configuration was saved. If the generations are different then the handler should examine the configuration to determine if any objects are no longer in the database or have been revised and either adjust the configuration or notify the application.
cmiOnSaveConfig() | Fired by Configuration.Save.
cmiOnBuild(BuildPath) | Fired by Configuration.Build. The handler is responsible for building the target system image in the folder specified by BuildPath.
cmiOnResolveRegistryDependencies() | Fired by Configuration.ResolveRegistryDependencies. The handler can use this event to check for implied dependencies among the configuration's components due to their use of registry keys.
cmiOnCheckDependencies() | Fired by Configuration.CheckDependencies. The handler can use this event to check for conflicts among the configuration's dependencies.
cmiOnCloseConfig() | Fired by Configuration.Close.
Allow = cmiOnAddInstance(NewInstance) | Fired when a new Instance is added to a configuration by calling Instances.Add. NewInstance references a partially initialized Instance object. The CMI initializes Instance.InstanceID and Instance.ComponentChain before firing this event. The event handler is responsible for initialization of the remaining properties of NewInstance. It is highly recommended that the handler initialize Instance.Comment before accessing Instance.Script so that the CMI can use Instance.Comment as the name of the script when logging script errors and in the script debugger. This handler returns a boolean value that determines whether the add operation should be allowed to complete. If the event handler is not implemented then the operation will be completed
Allow = cmiOnLoadInstance(NewInstance) | Fired when a saved Instance is being loaded into an Instances collection. NewInstance references an Instance object that has been completely initialized from the properties of the saved Instance. This handler returns a boolean value that determines whether the load operation should be allowed to complete. If the event handler is not implemented then the operation will be completed
cmiOnConfigureInstance(Instance) | Fired by Instance.Configure.
cmiOnUpgradeInstance(NewInstance, OldInstance) | Fired by Instance.Upgrade. NewInstance is a newly initialized Instance object that has an upgraded Instance.ComponentChain and a new Instance.Script object. OldInstance is the original Instance object that is being upgraded.
Allow = cmiOnDeleteInstance(Instance) | Fired when an Instance is deleted from a configuration by calling Instances.Remove or Instances.Clear. Returns a boolean value that determines whether the delete operation should be allowed to complete. If the event handler is not implemented then the operation is completed.
Allow = cmiOnAddResource(Instance, NewResource) | Fired when a new Resource is added to a configuration or to an Instance by calling Resources.Add. Instance is null if the Resource is being added to a configuration. NewResource references a completely initialized Resource object. Returns a boolean value that determines whether the add operation should be allowed to complete. If the event handler is not implemented then the operation is completed.
Allow = cmiOnDeleteResource(Instance, Resource) | Fired when a Resource is deleted from a configuration or from an Instance by calling Resources.Remove or Resources.Clear. Instance is null if the Resource is being deleted from a configuration. Returns a boolean value that determines whether the delete operation should be allowed to complete. If the event handler is not implemented then the operation is completed.
Allow = cmiOnLoadResource(Instance, NewResource) | Fired when a saved Resource is being loaded into a Resources collection belonging to a Configuration or to an Instance. NewResource references a Resource object that has been completely initialized from the properties of the saved Resource. Instance is null if the Resource is being loaded into a configuration. This handler returns a boolean value that determines whether the load operation should be allowed to complete. If the event handler is not implemented then the operation will be completed.

Resource Type Script Events

The following is a list of the events fired on resource type script as part of the processing of method calls on CMI objects. The CMI does not define how a resource type should handle these events. They are fired in order to allow the resource type script to customize the behavior of the CMI method calls.

Event | Description
Name = cmiGetName(Resource) | Fired when an application gets the Resource.Name property. Allows the resource type script to synthesize the resource name based on its properties or any other criteria. Returns the name of the resource.

Returning Errors from Event Handlers

An event handler may encounter an error in its processing that must be returned to the CMI's client application. This can be done by throwing an exception. In VBScript call Err.Raise. In JScript use throw new Error. The following error number ranges are defined:

Range | Usage
0 - 8999 | Microsoft script errors.
9000 - 9999 | CMI object method errors
10000 and above | OEM script errors.


Threading Issues

The CMI is implemented as an apartment-model in-process COM object. All of its interfaces can be marshaled across threads and across processes and can be used simultaneously by more than one thread or process. Applications may also create more than one instance of the top-level CMI object and use them in a single thread or simultaneously in multiple threads.


Programming Language Support

The CMI consists of a set of language-neutral OLE automation (COM) objects. Any language that can be used as a COM client can be used. This includes (but is not limited to) VBScript, JScript, Visual Basic and C++. The reference section of this document displays language-neutral syntax that can be used for scripting languages. The underlying data types are explained using language-neutral descriptions such as integer and string. These data type descriptions can be used by script programmers to determine parameter and variable values. For other languages they serve as a general reference but you will also need the language-specific information contained in the following sections.


JScript

JScript can be used with the syntax shown in the object model reference including enumerated value names.

A JScript application that needs to create the top-level CMI object can do so using the ActiveXObject object:

var cmiTop;
cmiTop = new ActiveXObject("CMI.CMI");

To create the Utilities object use:

var cmiUtilities;
cmiUtilities = new ActiveXObject("CMI.Utilities");

Null Values

Some properties and return values are documented as potentially having a null value. These should be checked for null. For example, the Platform.Description property can potentially be null because it is optional and may not have been specified when the platform definition was imported into the component database. Its value should be checked before using it as follows:

if (objPlatform.Description != null)
{
... OK to use it ...
}

Arrays

Some properties and methods are documented as returning arrays. These will always be VBScript arrays and they can be used to create a VBArray object to access their contents. For more information on the VBArray object see the JScript language documentation on the Microsoft scripting web site.

When setting properties or calling methods that require an array, a standard JScript array can be used. If a JScript array has an uninitialzed element then it will be interpreted as an empty string ("") or zero depending on whether the property or method is expecting an array of strings or an array of integers.

Error Handling

All methods and properties can potentially throw an exception if an error occurrs. If you do not want default error handling or if you need to check for a specific error then use a try...catch block. The CMI always sets the error description and number. For example:

var ParseErr
var e
try
{
     objCMI.ImportCarrier("SomeCarrier.sld", ParseErr);
}
catch(e)
{
     alert("Error on import: number=" + e.number + "description=" + e.description);
}

CMI errors are documented in the section Trappable Errors. The JScript engine will return the complete error number that corresponds to a Win32 HRESULT value. To check for the specific CMI error number, mask off the lower 16 bits:

try
{
     ...
}
catch(e)
{
     var CMIError = e.number & 0xFFFF
     if (CMIError == cmiErrDBError)
     {
         alert("Database error occurred");
     }
}


VBScript

VBScript can be used with the syntax shown in the object model reference with the single exception of object assignments. VBScript must use the Set keyword when assigning an object to a variable. All enumerated value names can be used in script code.

A VBScript application that needs to create the top-level CMI object can do so using the CreateObject function:

Dim cmiTop
Set cmiTop = CreateObject("CMI.CMI")

To create the Utilities object use:

Dim cmiUtilities
Set cmiUtilities = CreateObject("CMI.Utilities")

Null Values

Some properties and out parameters are documented as potentially having a null value. These should be checked for the IsNull function. For example, the Platform.Description property can potentially be null because it is optional and may not have been specified when the platform definition was imported into the component database. Its value should be checked before using it as follows:

If Not IsNull(objPlatform.Description) Then
... OK to use it ...
End If

Error Handling

All methods and properties can potentially raise an error. If you do not want default error handling or if you need to check for a specific error then use On Error Resume. The CMI always sets the Err object properties. For example:

Dim ParseErr
On Error Resume Next
objCMI.ImportCarrier "SomeCarrier.sld", ParseErr

If Err.Number <> 0 Then
     MsgBox "Error on import: number=" & Err.Number & "description=" & Err.Description
End If

CMI errors are documented in the section Trappable Errors. The VBScript engine will return the complete error number that corresponds to a Win32 HRESULT value. To check for the specific CMI error number, mask off the lower 16 bits:

Dim CMIError
CMIError = Err.Number And 65535
If CMIError = cmiErrDBError Then
     MsgBox "Database error occurred"
End If


Visual Basic

In order to use the CMI within Visual Basic, the project must reference its library. On the Project menu click References and click the checkbox for "CMI Object Library v1.0".

Use the object browser in the Visual Basic IDE (press F2 to invoke it). This will show the Visual Basic syntax and also serve as a convenient quick reference within the IDE. In the combo box in the upper left corner, select "CMI" to display the contents of the library.

A Visual Basic application that needs to create the top-level CMI object can do so using the New keyword or by calling the CreateObject function. The following are equivalent:

Dim cmiTop As New CMI.CMI

Dim cmiTop As CMI.CMI
Set cmiTop = CreateObject("CMI.CMI")

To create the Utilities object use either of the following:

Dim cmiUtilities As New CMI.Utilities

Dim cmiUtilities As CMI.Utilities
Set cmiUtilities = CreateObject("CMI.Utilities")

Null Values

Some properties and out parameters are documented as potentially having a null value. These should be checked for the IsNull function. For example, the Platform.Description property can potentially be null because it is optional and may not have been specified when the platform definition was imported into the component database. Its value should be checked before using it as follows:

If Not IsNull(objPlatform.Description) Then
... OK to use it ...
End If

Error Handling

All methods and properties can potentially raise an error. If you do not want default error handling or if you need to check for a specific error then use On Error GoTo. The CMI always sets the Err object properties. For example:

Dim ParseErr
On Error Goto ImportFail
objCMI.ImportCarrier "SomeCarrier.sld", ParseErr
Exit Sub
ImportFail:
MsgBox "Error on import: number=" & Err.Number + "description=" & Err.Description
End If

CMI errors are documented in the section Trappable Errors. The CMI object library contains an Enum called CMIErrorConstants that can be used when checking for specific error codes. For example:

Dim CMIError
CMIError = Err.Number And 65535
If CMIError = cmiErrDBError Then
     MsgBox "Database error occurred"
End If


C++

To use the CMI in C++ there are several options.

  1. #include the header file cmi.h and use the raw interfaces
  2. In Visual C++ use #import to generate wrapper classes
  3. In Visual C++ with MFC, use the Class Wizard to generate wrapper classes
All of these techniques will work equally well and choosing one is only a matter of personal preference and programming style.

Using #import cmi.h

The #import directive is the easiest technique and it will generate very clear wrapper classes for each of the CMI objects. Source modules that require CMI access should use:

#import "cmi.dll"

Using MFC and the Class Wizard

To use the MFC, invoke the Class Wizard, click Add Class..., click From a type library..., and select cmi.dll. Select all of the interfaces and click OK. The class wizard will generate wrapper classes for all CMI object based upon its COleDispatchDriver class.

Using #include cmi.h

All objects in the documentation are named using their coclass names as defined in cmi.idl, the interface definition language file for the CMI. Each coclass has a default dual interface that should be used by C++ applications. The dual interface is always named after the coclass with the standard "I" prefix. For example, the Component object has a dual interface called IComponent.

A C++ application can create the top-level CMI object by using CoCreateInstance with CLSID_CMI and requesting IID_ICMI. To create the Utilities object use CLSID_Utilities and request IID_IUtilities. C++ applications must also use

#include <initguid.h>
#include cmi_i.c

in one (and only one) of the application source files in order to reference all of the IID and CLSID definitions from cmi.idl.

Any parameter to a CMI method that references an object uses a coclass pointer. While this is slightly inconvenient for the C++ programmer using the dual interfaces, it is done to conform to an automation convention used by Visual Basic. When passing a coclass pointer, cast the dual interface pointer to the coclass pointer. When receiving a coclass pointer, cast it to the dual interface pointer. For example:

IPlatforms *piPlatforms;
ICMI *piCMI;
HRESULT hr;

... code to call CoCreateInstance and get the ICMI pointer ...
hr = piCMI->get_Platforms(reinterpret_cast<Platforms **>(&piPlatforms));

Optional Parameters

Some methods have optional VARIANT parameters. If the application needs to omit an optional parameter then it should set VARIANT.vt to VT_ERROR and set VARIANT.scode to DISP_E_PARAMNOTFOUND.

Null Values

Some properties and out parameters are documented as potentially having a null value. These are all VARIANT types and should be checked for VT_VARIANT. For example, the Platform.Description property can potentially be null because it is optional and may not have been specified when the platform definition was imported into the component database. Its value should be checked before using it as follows:

IPlatforms *piPlatform;
VARIANT varDesc;
::VariantInit(&varDesc);

... some code to set piPlatform ...
hr = piPlatform->get_Description(&varDesc);
if (SUCCEEDED(hr) && (varDesc.vt != VT_NULL))
{
... OK to use it ...
}

Error Handling

All methods can potentially return errors. All returned HRESULT values should be checked. If using the dual interfaces then rich error information is available by using the OLE automation API function GetErrorInfo. If using IDispatch then the Invoke method will return DISP_E_EXCEPTION and the EXCEPINFO structure will be populated. CMI errors are documented in the section Trappable Errors. cmi.h contains an enum called CMIErrorConstants that can be used when checking for specific errors. These constants contain the SCODE portion of the HRESULT. To check for a specific error use the HRESULT_CODE macro from winerror.h:

if (HRESULT_CODE(hr) == cmiErrDBError)
{
... a database error occurred ...
}


Reference

The following sections describe each CMI object, its properties, and its methods in detail.


CMI

CMI is the top of the object hierarchy and it is a publicly creatable object. Configuration and component script never create a CMI object as event handlers always receive the relevant object(s) as parameters or global objects. Tools create the object using CoCreateInstance in C++, CreateObject in Visual Basic or VBScript, or ActiveXObject in JScript.

After creating the the CMI object, the next call must be OpenDB to open a component database. This connects the CMI to the component database and is a prerequisite for all CMI operations. The client can then use the CMI object to browse the database, import new objects into the database and manipulate configurations.

ImportCarrier imports the contents of a carrier file (.SLD) into the database.

CheckCarrier validates the contents of a carrier file (.SLD) but does not import it into the database.

GetPlatforms returns the collection of Platform objects representing the platforms present in the database.

DBServerName returns the name of the database server the CMI is currently connected to.

OpenConfiguration opens an existing configuration file. (New configurations can be created using Platform.NewConfiguration.

When the client has completed its work with the database it must call CloseDB to close the connection. Failure to call this method will result in resource leakage.

The CMI client application can also sink events from the CMI object. These events are fired by the CMI to request UI services from the the client application such as displaying a component's configuration HTML page, displaying messages from script code, etc.


CMI.AllowPlatformDeletes Property

AllowPlatformDeletes Property

The AllowPlatformDeletes property returns a boolean value that determines whether the application is allowed to delete a platform from the database. The default value is False to prevent inadvertent deletion of a platform as deleting a platform also deletes all of its dependent objects. For more information see Platforms.Remove.

Syntax

    fAllowPlatformDeletes = objCMI.AllowPlatformDeletes

Notes


CMI.CheckCarrier Method

CheckCarrier Method

The CheckCarrier method validates the contents of a carrier file (.SLD) without inserting it into the component database.

Syntax

    objCMI.CheckCarrier(SLDPaths)

    SLDPaths

      Either a string containing the fully qualified path to the .SLD file or an array of strings containing the fully qualified paths to multiple .SLD files.

Notes

The OpenDB method must be called before this method.

If an XML parsing error occurs then this method will return cmiErrXMLParsingError.

Note that unlike the ImportCarrier method, CheckCarrier does not do any repository file copy processing and does not fire OnImportObject or OnImportRepository events.


CMI.CloseDB Method

CloseDB Method

The CloseDB method is used to close a connection with a component database.

Syntax

    objCMI.CloseDB()

Notes

This method is used by tools to close a connection with a component database. It is not used in component script. When the tool is finished using the database or the CMI it must call CloseDB. After calling CloseDB, the tool may call OpenDB to establish a new connection.


CMI.DBServerName Property

DBServerName Property

The DBServerName property returns a string containing the name of the server on which the currently connected database resides.

Syntax

    strServerName = objCMI.DBServerName

Notes

If the CMI is not currently connected to a database then this property returns an empty string ("").


CMI.DebugOnScriptError Property

DebugOnScriptError Property

The DebugOnScriptError property returns a boolean value that determines whether the CMI invokes the script debugger when an error occurs in configuration or component script code. This property must be set before the script engine is loaded. The script engine is loaded when the Configuration or Instance containing the script is created or loaded.

Syntax

    fDebug = objCMI.DebugOnScriptError

Notes

If CMI.DebugScript is set to True then this property is ignored.

The initial setting of this property is taken from the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Embedded\CMI in a DWORD value called Flags. If the 0x2 bit is set then DebugOnScriptError will be set to True.

If the script code is encrypted then setting this property does not invoke the debugger when an error occurs in the script.


CMI.DebugScript Property

DebugScript Property

The DebugScript property returns a boolean value that determines whether the CMI invokes the script debugger when it runs script code. This property must be set before the script engine is loaded. The script engine is loaded when the Configuration or Instance containing the script is created or loaded.

Syntax

    fDebug = objCMI.DebugScript

Notes

UI tools should offer the user a way to set this property before calling any CMI method that might run script code.

If this property is set to True then CMI.DebugOnScriptError is ignored.

If the script code is encrypted then setting this property does not invoke the debugger when the script code is run.


CMI.DisplayHTML Method

DisplayHTML Method

The DisplayHTML method fires an OnDisplayHTML event to the CMI client application.

Syntax

    objCMI.DisplayHTML(Instance, HTMLTitles, HTMLTexts)

    Instance

      The Instance object for which the HTML should be displayed.

    HTMLTitles

      A VARIANT array containing the HTML titles for each component in Instance.ComponentChain that has HTML text. The length of the array must be the same as HTMLTexts.

    HTMLTexts

      A VARIANT array containing the HTML text for each component in Instance.ComponentChain that has HTML text. The length of the array must be the same as HTMLTitles.

    Notes

    The OpenDB method must be called before this method.

    Callers from VBScript and JScript can use their language-specific array. Visual Basic callers should use an array of Variant. Callers from C++ should use a SafeArray of VT_VARIANT where each VARIANT contains VT_BSTR.


CMI.Generation Property

Generation Property

The Generation property returns an integer containing the generation number of the currently open database. The generation number is an ordinal that is incremented each time any change is made to the database. Changes that affect this property are all import and delete operations as well as any modifications to CMI.Properties. This allows tools that cache database data to quickly check to see if the data might be stale. For an example of how this is used see Configuration.Generation.

Syntax

    nGeneration = objCMI.Generation


CMI.GetPlatform Method

GetPlatform Method

The GetPlatform method returns a Platform object from the component database identified by VIGUID or by VSGUID.

Syntax

    objPlatform = objCMI.GetPlatform(VXGUID)

VSGUID

    A string containing either the version-independent GUID (VIGUID) or the version-specific GUID (VSGUID) of the platform to retrieve.

Notes

This method always returns a new instance of the object.

The OpenDB method must be called before this method can be used.


CMI.GetPlatforms Method

GetPlatforms Method

The GetPlatforms method returns a collection of Platform objects from the component database.

Syntax

    objPlatforms = objCMI.GetPlatforms

Notes

This method always returns a new instance of the collection.

The OpenDB method must be called before this method can be used.


CMI.ImportCarrier Method

ImportCarrier Method

The ImportCarrier method imports the contents of a carrier file (.SLD) into the component database.

Syntax

    RetVal = objCMI.ImportCarrier(SLDPaths, [SrcRoot], [DstRoot])

    SLDPaths

      Either a string containing the fully qualified path to the .SLD file or an array of strings containing the fully qualified paths to multiple .SLD files.

    SrcRoot

      Optional. If the .SLD file contains REPOSITORY elements then this parameter must be specified using an absolute path. If a repository simply consists of a set of files then this parameter typically specifies the directory that contains the .SLD file and SRCPATH elements within REPOSITORY elements in the .SLD file specify a path that is relative to that directory. The application should have read access to the directory and to the files it contains. If the repository consists of a consolidated file manifest such as a cabinet (.CAB) or similar file then this parameter should specify the fully qualified path to that file. The application must have read access to the file and it must implement the OnImportRepository event. This event will be fired while ImportCarrier executes to handle the copying of repository files.

    DstRoot

      Optional. If specified, this parameter will be passed to the OnImportRepository event to be used as the destination for copying repository files. DstRoot must contain an absolute path and it is strongly recommended that it specify a UNC name to ensure that files can be located from any computer on the network.

    RetVal

      If the import is completed successfully then the return value can be ignored. If the OnImportRepository or OnImportObject event handlers cancel the import operation then RetVal will contain the return value from the event handler. The application can check the value of RetVal to determine whether its handler cancelled the operation.

Notes

The OpenDB method must be called before this method.

If an XML parsing error occurs then this method will return cmiErrXMLParsingError.

The processing of an .SLD file is transacted within the database. This means that either the entire .SLD file will be imported or none of it at all. If an error occurs during import processing, then all elements successfully imported prior to the error are removed.

During the processing of the .SLD file the application will receive the OnImportObject event for every element that represents a primary object in the database. Elements that cause OnImportObject events are:

  • PLATFORM
  • REPOSITORY
  • GROUP
  • RESTYPE
  • COMPONENT
If the application wants to continue the import operation then it should return cmiContinue (0) from the event handler. Returning any other value terminates the import operation and that value is returned from ImportCarrier.

If the .SLD file contains REPOSITORY elements then the application will receive an OnImportRepository event for each element found before the contents of the file are entered into the database. The event handler can be used to copy files, unpack files from a consolidated file manifest such as a .CAB file, and determine the value of Repository.SrcPath in the database. A typical file copy scheme creates a directory for each repository under DstRoot using the repository's VSGUID e.g. "c:\MyDstRoot\{CA809910-15A1-4684-8D54-B7F6D36523B9}". If the OnImportRepository event handler does not return a valid source path and does not return cmiDefaultFileCopy (see below) then the import operation is terminated and that value is returned from ImportCarrier.

If OnImportRepository is not implemented or returns the value cmiDefaultFileCopy (0) then the CMI sets Repository.SrcPath to the concatenation of the DstRoot parameter passed to ImportCarrier and the repository's VSGUID as described above. It then creates this directory if it is not there and copies the files from the directory formed by concatenating the SrcRoot parameter passed to ImportCarrier with the value of the SRCPATH element within the REPOSITORY element in the .SLD file. If the value of SRCPATH is an absolute path then it is used as is and the SrcRoot parameter is ignored. If one or more of the files already exists in the destination directory then the CMI will overwrite them. Note that this default handling cannot be used for consolidated file manifests such as .CAB files. To use default handling either SrcRoot must contain a directory path or the SRCPATH element must contain an absolute path.

If file copying succeeds (either by the application or the CMI) but the import process then fails (e.g. due to a database error), then the CMI does not delete the files. The application may choose to do this or simply inform the user that files were copied but they are not referenced in the database because of the error.

Repository Import Scenarios

The following paragraphs illustrate typical scenarios for repository import in order to clarify the various options available.

Default Handling: Copying Files from a CD to a Network Share

The CD is in the R: drive. A directory called "Components" on the CD contains a file called "Comp1.SLD". Another directory called "Repositories" contains a subdirectory called "Comp1Files". The destination for the repository files is a shared directory called "\\embedded\repos". "Comp1.SLD" contains the following REPOSITORY element:

    <REPOSITORY
            RepositoryVSGUID="{767632A5-4A2F-4FB9-B986-0836A682FB2E}"
            Revision="1"
            PlatformGUID="{59BD4C55-94FC-4D16-9E0E-7D37728272C0}"
            BuildType=0
    >
            <SRCPATH>Comp1Files</SRCPATH>
            <DISPLAYNAME>Component Repository</DISPLAYNAME>
    </REPOSITORY>

The call to ImportCarrier is:

    Status = ImportCarrier("R:\Components\Comp.SLD", "R:\Repositories", "\\embedded\repos")

The application does not implement OnImportRepository. The CMI creates a directory called "\\embedded\repos\{767632A5-4A2F-4FB9-B986-0836A682FB2E}". It copies the files from "R:\Repositories\Comp1Files" to that directory and uses its name for the value of Repository.SrcPath

Application Handling: Copying Files from a .CAB file to a Network Share

"C:\SomeDir\Comps.CAB" contains a file called "Embed.SLD" as well as repository files. The destination for the repository files is a shared directory called "\\embedded\repos". "Comp1.SLD" contains the following REPOSITORY element:

    <REPOSITORY
            RepositoryVSGUID="{767632A5-4A2F-4FB9-B986-0836A682FB2E}"
            Revision="1"
            PlatformGUID="{59BD4C55-94FC-4D16-9E0E-7D37728272C0}"
            BuildType=0
    >
            <SRCPATH>SomeSubDir</SRCPATH>
            <DISPLAYNAME>Component Repository</DISPLAYNAME>
    </REPOSITORY>

The application unpacks the .SLD file from the .CAB into "C:\SomeDir" and calls ImportCarrier as follows:

    Status = ImportCarrier("C:\SomeDir\Embed.SLD", "C:\SomeDir\Comps.CAB", "\\embedded\repos")

The application receives the OnImportRepository event as follows:

    OnImportRepository("C:\SomeDir\Comps.CAB", "\\embedded\repos", "SomeSubDir", "{767632A5-4A2F-4FB9-B986-0836A682FB2E}", "Component Repository")

The application creates a directory called "\\embedded\repos\{767632A5-4A2F-4FB9-B986-0836A682FB2E}". It unpacks the files from the .CAB and copies them to that directory. It returns the directory's name to be used as the value of Repository.SrcPath.

Reasons for "Invalid Parameter" Errors

Unlike most methods in the CMI object model, ImportCarrier can return an "Invalid Parameter" error (E_INVALIDARG in C++) for numerous reasons that may be difficult to diagnose. The following is a comprehensive list of possible invalid parameter errors.

  • SLDPath does not contain a fully qualified path.
  • The carrier file contains REPOSITORY elements but SrcRoot is either missing or does not contain a fully qualified path.
  • The OnImportRepository event handler returned a final source path string that does not contain a fully qualified path.
  • The carrier file contains REPOSITORY elements and the OnImportRepository event handler is either not implemented or indicated that default file copying is requested and DstRoot was either not passed or does not contain a fully qualified path.
  • SrcRoot or DstRoot were passed but do not contain strings.
  • One or more parameters were passed containing bad pointers (this is the same for any CMI method).


CMI.LogMessages Property

LogMessages Property

The LogMessages property returns a boolean value that determines whether the CMI writes messages to its log file when CMI.WriteMsg is called. Log file location is determined by CMI.LogFile.

Syntax

    fLogMessages = objCMI.LogMessages


CMI.LogFile Property

LogFile Property

The LogFile property returns a string containing the complete path of the file used to log messages when CMI.WriteMsg is called and CMI.LogMessages is True.

Syntax

    strLogFile = objCMI.LogFile


CMI.OnDisplayHTML Event

OnDisplayHTML Event

The OnDisplayHTML event is fired when an application calls DisplayHTML. This method would most likely be called by component script.

Syntax

    OnDisplayHTML(Instance)

    Instance

      The Instance object for which the HTML should be displayed.

    HTMLTitles

      A VARIANT array containing the HTML titles for each component in Instance.ComponentChain that has HTML text. The length of the array will be the same as HTMLTexts.

    HTMLTexts

      A VARIANT array containing the HTML text for each component in Instance.ComponentChain that has HTML text. The length of the array will be the same as HTMLTitles.

Notes

Implementers in JScript must use the VBArray object and assign VBArray.toArray() to a local variable.

Implementers in C++ will receive VARIANTs containing VT_ARRAY | VT_VARIANT. Each VARIANT in the arrays will contain VT_BSTR.

The CMI does not define how the client application should handle this event. A typical handler would display a dialog containing the Internet Explorer Web Browser control and load it with HTMLTexts(0). The dialog might also include an advanced button or use a tabbed property sheet to display the HTML of the prototype components as well (the subsequent elements in the HTMLTexts array). The corresponding HTMLTitles array elements can be used as dialog titles or as text for property page tabs.

The handler should not display HTML synchronously during the event. It should post itself a message, use a separate thread, or run Internet Explorer in a separate process.

If the handler uses the Internet Explorer Web Browser Control, then it can make the Instance object available to script code on the HTML page by implementing the IDocHostUIHandler interface. The implementation of IDocHostUIHandler::GetExternal can return the Instance object. This allows script code on the page to refer to the Instance as window.external. If the handler needs to expose more than one object, it can implement an IDispatch interface that exposes the Instance object as a property. In that case, script code on the page would use window.external.Instance. For more information see knowledge base article Q188015 "HOWTO: Access Methods/Properties of Container From Script" and see the documentation of IDocHostUIHandler in the Platform SDK.

If this event handler returns an error then that error is returned to the caller of DisplayHTML.


CMI.OnImportObject Event

OnImportObject Event

The OnImportObject event is fired when an application calls CMI.ImportCarrier to inform the application of the progress of the import process. If the application returns an error from the event handler then ImportCarrier is terminated and returns that error.

Syntax

    RetVal = OnImportObject(File, TotalObjects, ObjectsCompleted, ObjectType, ObjectDisplayName)

    File

      The name of the SLD file currently being imported into the database.

    TotalObjects

      The total number of objects being imported from that SLD file.

    ObjectsCompleted

      The number of objects imported so far from that SLD file. This allows the application to display import status such as "File c:\My.sld - Imported 2 out of 10 objects" or "File c:\My.sld import 20% complete".

    ObjectType

      The type of object currently being imported e.g. "Component".

    ObjectDisplayName

      If the object's XML element contains a DISPLAYNAME element with a non-empty value then this parameter will contain that value. If the value is empty or there is no DISPLAYNAME element then this parameter will contain the object's version-specific GUID (VSGUID).

    RetVal

      If the event handler returns cmiContinue (0) then the import operation continues. If the handler returns any other value then the import operation is terminated and that value is returned from CMI.ImportCarrier

Notes

This event handler is typically used by applications to display a progress bar or a similar feedback mechanism with a cancel button during the import process. As it is called while CMI.ImportCarrier is running and may be in the midst of a database transaction, event handlers should be very fast (e.g. simple UI updates). If more processing is needed the application should post itself a message or use a separate thread.


CMI.OnImportRepository Event

OnImportRepository Event

The OnImportRepository event is fired when an application calls CMI.ImportCarrier and the .SLD file contains REPOSITORY elements. The application can use this event to copy files, unpack files from a consolidated file manifest such as a .CAB file, and determine the value of Repository.SrcPath in the database. A typical file copy scheme creates a directory for each repository under DstRoot using the repository's VSGUID e.g. "c:\MyDstRoot\{CA809910-15A1-4684-8D54-B7F6D36523B9}".

Syntax

    RetVal = OnImportRepository(SrcRoot, DstRoot, SrcPath, VSGUID, DisplayName)

    SrcRoot

      The value of the SrcRoot parameter passed to CMI.ImportCarrier.

    DstRoot

      The value of the DstRoot parameter passed to CMI.ImportCarrier.

    SrcPath

      If the REPOSITORY element contains a SRCPATH element and its value is non-empty then this parameter contains that value otherwise it will contain "." to indicate that the repository files reside in the same directory as the SLD file.

    VSGUID

      The repository's version-specific GUID (VSGUID) from the RepositoryVSGUID attribute of the REPOSITORY element.

    DisplayName

      If the REPOSITORY element contains a DISPLAYNAME element and its value is non-empty then this parameter contains that value.

    RetVal

      The event handler typically returns a string containing the absolute path to be used for Repository.SrcPath in the database. If the value cmiDefaultFileCopy (0) is returned then the CMI will perform default handling. If the handler returns any other value then the import operation is terminated and that value is returned from CMI.ImportCarrier For more information see CMI.ImportCarrier.


CMI.OnMaybeUpgradeConfig Event

OnMaybeUpgradeConfig Event

The OnMaybeUpgradeConfig event can be fired when an application calls OpenConfiguration. The CMI checks the platform revision in the configuration file against the latest revision of platform in the component database. If the database is newer then the it fires this event.

Syntax

    OnMaybeUpgradeConfig(Configuration, Platform)

    Configuration

      The Configuration object that can be upgraded.

    Platform

      The newer Platform object that can be used for the upgrade.

    Notes

    The CMI does not define how the client application should handle this event. A typical handler would display a dialog explaining the potential upgrade and offer the user a choice.


CMI.OnReportStatus Event

OnReportStatus Event

The OnReportStatus event is fired when an application calls ReportStatus. This method would most likely be called by configuration or component script.

Syntax

    RetVal = OnReportStatus(Type, Context, Data)

Type

    A caller-defined integer used to indicate to the application the type of status being reported.

Context

    A caller-defined integer used to indicate the context from which the status is being reported

Data

    The caller-defined data containing the status report. This can be as simple as an integer or a string or, if more complex status reporting is needed, it be an object.

RetVal

    The return value from the event handler. This value is returned to the caller of ReportStatus.

Notes

The application should consult the documentation for the configuration and component script that can fire this event to determine the meaning of the parameters.

The CMI does not define how the client application should handle this event. A typical handler would display a message in a console-like window and possibly allow sorting them by type.

If this event handler returns an error then that error is returned to the caller of ReportStatus.


CMI.OnWriteMsg Event

OnWriteMsg Event

The OnWriteMsg event is fired when an application calls WriteMsg. This method would most likely be called by configuration or component script.

Syntax

    OnWriteMsg(Type, Text)

    Type

      An enumerated value that determines the nature of the message. For possible values see the WriteMsg method.

    Text

      The text of the message.

Notes

The CMI does not define how the client application should handle this event. A typical handler would display the messages in a console-like window and possibly allow sorting them by type.

If this event handler returns an error then that error is returned to the caller of WriteMsg.


CMI.OpenConfiguration Method

OpenConfiguration Method

The OpenConfiguration method opens a configuration file (.SLX) and returns a Configuration object that can be used to access it. It fires the cmiOnOpenConfig event in configuration script.

Syntax

    objConfiguration = objCMI.OpenConfiguration(Path)

    Path

      A string containing the fully qualified path to the .SLX file. When this method completes Configuration.Path will be set to this value.

    Notes

    The OpenDB method must be called before this method.

    The Configuration.Close method must be called when the application has finished using the Configuration object.

    The application can open multiple configurations simultaneously.

    The CMI checks that all the component GUIDs specified within the .SLX file are present in the component database and belong to the same platform as the configuration.

    The CMI also checks the platform revision in the configuration file against the latest revision of platform in the component database. If the database is newer then the it fires an OnMaybeUpgradeConfig event to the CMI client application.


CMI.OpenDB Method

OpenDB Method

The OpenDB method is used to establish a connection with a component database.

Syntax

    objCMI.OpenDB(ServerName, [DBName])

    ServerName

      A string containing the name of the server on which the database resides. If using the local machine then specify its name.

    THIS PARAMETER WILL NOT BE DOCUMENTED FOR EXTERNAL USE. REMOVE THIS EXPLANATION AND REMOVE THE PARAMETER FROM THE SYNTAX LINE ABOVE BEFORE RELEASE

    DBName

      Optional. A string indicating which database to open on the server. All CMI database servers are configured with a default database. If this parameter is not specified then the default database is opened. If it is specified then it must contain the name or path of a universal data locator (UDL) file that contains the database information. If a file name is specified without a path then it must reside on the CMI database server. If it is specified with a relative path then that path is resolved relative to the location of the CMI database server.

Notes

This method is used by tools to establish a connection with a component database. It is not used in component script. After creating a CMI object, tools must call this method before using any other CMI methods or properties. When the tool is finished using the database or the CMI it must call CloseDB. After calling CloseDB, the tool may call OpenDB again to establish a new connection.


CMI.Properties Property

Properties Property

The Properties property returns a read-write collection of ExtProperty objects from the database that are global within the database. Unlike all other database objects, this collection is not populated by calling CMI.ImportCarrier. The application uses ExtProperties.Add to add an ExtProperty object to the collection as well as to the database. ExtProperties.Remove can be used to delete properties from the collection as well as from the database.

Syntax

    objProperties = objCMI.Properties

Notes

This collection allows applications to store properties that are global to the database (i.e. not specific to a particular platform).

Applications running in a multi-user environment must be aware that changes to this collection could potentially affect other concurrently running applications. While individual changes to the collection are guaranteed to be atomic within the database, namespace collisions are the responsibility of the applications.


CMI.QueryObjectType Method

QueryObjectType Method

The QueryObjectType method returns the type name of an object. It is similar to the VBScript operator TypeName.

Syntax

    Type = objCMI.QueryObjectType(Object)

    Object

      The type name of this object is returned from this method.

Notes

This method performs exactly the same function as the VBScript TypeName operator. It can be used for languages that do not support a similar operator such as JScript. It is needed for properties such as Dependency.TargetObject that can return multiple different object types.

If the object does not supply the necessary type information the the string "Object" is returned.

If the object supports the IProvideClassInfo interface then IProvideClassInfo::GetClassInfo is called to get the object's type information. If the object does not support IProvideClassInfo then IDispatch::GetTypeInfo is called. In either case ITypeInfo::GetDocumentation(MEMBERID_NIL) is called to get the type name.


CMI.ReportStatus Method

ReportStatus Method

The ReportStatus method fires an OnReportStatus event to the CMI client application. It is typically used by script to make progress and error reports to UI tools during lengthy operations such as building a target system during Configuration.Build.

Syntax

    RetVal = objCMI.ReportStatus(Type, Context, Data)

Type

    A caller-defined integer used to indicate to the application the type of status being reported.

Context

    A caller-defined integer used to indicate the context from which the status is being reported

Data

    The caller-defined data containing the status report. This can be as simple as an integer or a string or, if more complex status reporting is needed, it can be an object.

RetVal

    The return value received from the OnReportStatus event handler.


CMI.Revision Property

Revision Property

The Revision property returns an integer containing the revision number of the CMI. This number is changed whenver there is a change in the CMI object model that would break application compatibility.

Syntax

    nRevision = objCMI.Revision


CMI.WriteMsg Method

WriteMsg Method

The WriteMsg method fires an OnWriteMsg event to the CMI client application. If CMI.LogMessages is True then the message will also be written to the file specified by CMI.LogFile.

Syntax

    objCMI.WriteMsg(Type, Text)

Type

    An enumerated value that determines whether the message is an error, a warning or only informational. Messages are logged with their type in order to allow searching the log. Type can have the following values:

    Type Values

    Constant | Description
cmiInfoMsg (1) | The message is informational only and requires no action.
cmiWarningMsg (2) | The message is a warning and may require corrective action.
cmiErrorMsg (3) | The message is an error and requires corrective action.
cmiDebugMsg (4) | The message contains debugging output. This is typically used during the development of Component, ResourceType, and Platform script code.

Text

    The text of the message


Components

The Components collection represents the component objects in the component database. It is accessed from the Platform.GetComponents method. Component objects can be referenced using an ordinal index or by VSGUID.

Count returns the number of Component objects in the collection.

Remove removes a Component object from the collection and also deletes it from the database.

Clear removes all Component objects from the collection and also deletes them from the database.

CMI returns the top-level CMI object that contains the collection.

Platform returns the Platform object that contains the collection.


Components.Clear Method

Clear Method

The Clear method removes all Component objects from the collection and also deletes them from the database. The components' dependent objects will also be removed from the database. These are dependencies, group membership, and resources and their properties.

Syntax

    objComponents.Clear()


Components.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the collection.

Syntax

    objCMI = objComponents.CMI


Components.Count Property

Count Property

The Count property returns the number of Component objects currently in the collection.

Syntax

    nComponents = objComponents.Count

Notes

The count does not necessarily reflect the number of component objects in the component database. It represents the number of objects retrieved from the database during the last call to Platform.GetComponents.


Components.GetGroups Method

GetGroups Method

The GetGroups method returns a collection of Group objects from the component database that represent the set of groups to which the components in the collection belong.

Syntax

    objGroups = objComponents.GetGroups

Notes

This method always returns a new instance of the collection.


Components.Item Property

Item Property

The Item property returns the specified Component object from the collection. It is the default property and does not require an explicit reference by name.

Syntax

    objComponent = objComponents(Index)

    objComponent = objComponents.Item(Index)

    Index

      Either an integer containing the one-based ordinal position of the Component object in the collection or a string containing the value of the object's VSGUID property.


Components.Platform Property

Platform Property

The Platform property returns the Platform object that contains the collection.

Syntax

    objPlatform = objComponents.Platform


Components.Remove Method

Remove Method

The Remove method removes the specified Component object from the collection and also deletes it from the database. The component's dependent objects will also be removed from the database. These are dependencies, group membership, and resources and their properties.

Syntax

    objComponents.Remove(Index)

    Index

      Either an integer containing the one-based ordinal position of the Component object in the collection or a string containing the value of the object's VSGUID property.


Component

The core of the system is the component. Many components describe operating system functionality, such as services and device drivers, but components are also used to describe 3rd party software. The features of a generated run-time image are controlled entirely by which components (or, more correctly, component instances) are included in the run-time configuration. Component objects are revisable and upgradable primary objects.

A component is comprised of the following items of information:

  • A normal set of component properties.
  • A list of groups to which the component belongs.
  • A list of resources (e.g. files, registry keyts) that will be processed when the run-time image is built.
  • A block of script that is used by the component instance.
  • A block of HTML that is used when configuring the component instance data.
  • A list of dependencies that specify inter-component relationships.
    •

    A component is built into a run-time image by being included as part of a configuration. Adding a component to a configuration creates a component instance (represented by an Instance object. An instance is an editable copy of the component state, and also contains a reference back to the component for additional non-editable information.


Component.Authors Property

Authors Property

The Authors property returns a string containing semi-colon separated list of email addresses of the authors of the component.

Syntax

    strAuthors = objComponent.Authors

Notes

This property is optional and may be null.


Component.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the component.

Syntax

    objCMI = objComponent.CMI


Component.Copyright Property

Copyright Property

The Copyright property returns a string containing the copyright text for the component.

Syntax

    strCopyright = objComponent.Copyright

Notes

This property is optional and may be null.


Component.DateCreated Property

DateCreated Property

The DateCreated property returns the date and time the component was created in UTC.

Syntax

    DateCreated = objComponent.DateCreated

Notes

This property is optional and may be null.


Component.DateImported Property

DateImported Property

The DateImported property returns the date and time the component definition was imported into the component database (in UTC).

Syntax

    DateImported = objComponent.DateImported


Component.DateRevised Property

DateRevised Property

The DateRevised property returns the date and time the component was last revised in UTC.

Syntax

    DateRevised = objComponent.DateRevised

Notes

This property is optional and may be null.


Component.Description Property

Description Property

The Description property returns a string containing the description of the component.

Syntax

    strDescription = objComponent.Description

Notes

This property is optional and may be null.


Component.DisplayName Property

DisplayName Property

The DisplayName property returns a string containing the display name of the component.

Syntax

    strDisplayName = objComponent.DisplayName

Notes

This property is optional and may be null.


Component.Editable Property

Editable Property

The Editable property returns a boolean value indicating whether the component is configurable by the user.

Syntax

    fEditable = objComponent.Editable


Component.GetDependencies Method

GetDependencies Method

The GetDependencies method returns a collection of Dependency objects from the database that belong to the component.

Syntax

    objDependencies = objComponent.Dependencies

Notes

This method always returns a new instance of the collection.


Component.GetGroups Method

GetGroups Method

The GetGroups method returns a collection of Group objects from the component database that represent the set of groups to which the component belongs.

Syntax

    objGroups = objComponent.GetGroups

Notes

This method always returns a new instance of the collection.


Component.GetRepositories Method

GetRepositories Method

The GetRepositories method returns a collection of Repository objects from the database that are used as sources of files for the component. If the component's repositories have not yet been imported into the database then this collection will be empty.

Syntax

    objRepositories = objComponent.GetRepositories


Component.GetResources Property

GetResources Method

The GetResources method returns a collection of all the Resource objects that belong to the component.

Syntax

    objResources = objComponent.GetResources()


Component.GroupVSGUIDs Method

GroupVSGUIDs Property

The GroupVSGUIDs property returns an array of GUIDs that specifies the groups to which the component belongs. This array does not necessarily correspond to the Groups collection returned by the Component.GetGroups method as some of the component's groups may not yet have been imported into the database.

Syntax

    objGroups = objComponent.GroupVSGUIDs


Component.HelpContext Property

HelpContext Property

The HelpContext property returns a string containing help text in HTML format that can be used by tools to display help for the component.

Syntax

    strHelpContext = objComponent.HelpContext

Notes

This property is optional and may be null.


Component.HTMLFinal Property

HTMLFinal Property

The HTMLFinal property returns a boolean indicating whether a UI tool should display configuration HTML (from Component.HTMLText) for the component's prototype and for any other components further up the prototype chain. If False then the UI can display HTML for the component but not for its prototypes.

Syntax

    fHTMLFinal = objComponent.HTMLFinal


Component.HTMLText Property

HTMLText Property

The HTMLText property returns a string containing the HTML displayed when the component is configured.

Syntax

    strHTMLText = objComponent.HTMLText

Notes

This property is optional and may be null.


Component.HTMLTitle Property

HTMLTitle Property

The HTMLTitle property returns a string containing the title that should be used when a UI tool displays Component.HTMLText to allow the user to configure the component.

Syntax

    strHTMLTitle = objComponent.HTMLTitle

Notes

This property is optional and may be null.


Component.Index Property

Index Property

The Index property returns an integer containing the ordinal position of the Component object in the Components collection.

Syntax

    nIndex = objComponent.Index

Notes

Index represents only the ordinal position in the collection. It does not necessarily represent the ordinal position in the database.


Component.IsMacro Property

IsMacro Property

The IsMacro property returns a boolean value indicating whether the component is a macro component. A macro component has no resources and derives from the default prototype component specified by Platform.DefaultProtoVIGUID.

Syntax

    fIsMacro = objComponent.IsMacro


Component.MultiInstance Property

MultiInstance Property

The MultiInstance property returns a boolean value indicating whether the component can be instantiated multiple times within the same configuration.

Syntax

    fMultiInstance = objComponent.MultiInstance

Notes

A component can only be instantiated multiple times within a configuration if all of the components in its prototype chain have MultiInstance set to True.


Component.Owners Property

Owners Property

The Owners property returns a string containing a semi-colon separated list of email addresses of the owners of the component.

Syntax

    strOwners = objComponent.Owners

Notes

This property is optional and may be null.


Component.Platform Property

Platform Property

The Platform property returns the Platform object that contains the component.

Syntax

    objPlatform = objComponent.Platform


Component.PlatformGUID Property

PlatformGUID Property

The PlatformGUID property returns a string containing the either the version-independent GUID (VIGUID) or version-specific GUID (VSGUID) that identifies the platform to which the component belongs.

Syntax

    strPlatformGUID = objComponent.PlatformGUID


Component.Properties Property

Properties Property

The Properties property returns a collection of ExtProperty objects from the database that belong to the component.

Syntax

    objProperties = objComponent.Properties

Notes

This property always returns the same instance of the collection.


Component.PrototypeVIGUID Property

PrototypeVIGUID Property

The PrototypeVIGUID property returns a string containing the version-independent GUID of the prototype component for this component.

Syntax

    strPrototypeVIGUID = objComponent.PrototypeVIGUID

Notes

If this property is null then the component uses the default prototype determined by the Platform.DefaultProtoVIGUID property.


Component.Released Property

Released Property

The Released property returns a boolean value indicating whether the component is fully authored or it is in pre-release.

Syntax

    fReleased = objComponent.Released

Notes

A component is only considered fully authored if all of the components in its prototype chain have Released set to True.


Component.RepositoryVSGUID Property

RepositoryVSGUID Property

The RepositoryVSGUID property returns a string containing the version-specific GUID (VSGUID) that identifies the repository or repository set for the component.

Syntax

    strRepositoryVSGUID = objComponent.RepositoryVSGUID


Component.Revision Property

Revision Property

The Revision property returns an integer containing the revision ordinal of the component. The revision is a simple ordinal value where a higher value represents a later version of an object. Revisions need not be sequential, but any changes that are made to an object must be accompanied by an increase in the value of the revision.

Syntax

    nRevision = objComponent.Revision


Component.ScriptEncoded Property

ScriptEncoded Property

The ScriptEncoded property returns a boolean value that indicates whether the script code returned by the ScriptText property is encrypted. Encrypted script code cannot be debugged by setting CMI.DebugScript or CMI.DebugOnScriptError.

Syntax

    fScriptEncoded = objComponent.ScriptEncoded

Notes

This property will be null if ScriptText is null.


Component.ScriptLanguage Property

ScriptLanguage Property

The ScriptLanguage property returns a string containing the language of the script code returned by the ScriptText property.

Syntax

    strScriptLanguage = objComponent.ScriptLanguage

Notes

This property may be null only if ScriptText is null.


Component.ScriptText Property

ScriptText Property

The ScriptText property returns a string containing the configuration script code used by the component. The language of the script code is specified by the ScriptLanguage property.

Syntax

    strScriptText = objComponent.ScriptText

Notes

This property is optional and may be null. If it is not null then ScriptLanguage must also be set.


Component.Vendor Property

Vendor Property

The Vendor property returns a string containing the vendor that created the component.

Syntax

    strVendor = objComponent.Vendor

Notes

This property is optional and may be null.


Component.Version Property

Version Property

The Version property returns a string containing the version of the component. The version string contains arbitrary text. It is never used to compare versions. The Revision property is used for this purpose.

Syntax

    strVersion = objComponent.Version

Notes

This property is optional and may be null.


Component.VIGUID Property

VIGUID Property

The VIGUID property returns a string containing the version-independent GUID that uniquely identifies the component.

Syntax

    strVIGUID = objComponent.VIGUID

Notes

The VIGUID property does not identify a specific revision of the component. That is specified by the VSGUID property.


Component.Visibility Property

Visibility Property

The Visibility property returns an integer value that controls the visibility of the component to the UI tools. This property defines a visibility "level" that defaults to 1000. Components may be filtered based upon their visibility level, with only those components that have a visibility greater than a specified threshold displayed. Components that should never be displayed to the user should have a visibility of 0. Components that should always be visible should have a visibility of 32767.

Syntax

    fVisibility = objComponent.Visibility


Component.VSGUID Property

VSGUID Property

The VSGUID property returns a string containing the version-specific GUID that uniquely identifies a specific revision of the component.

Syntax

    strVSGUID = objComponent.VSGUID


Configuration

The Configuration object represents a target system configuration. it consists of a set of component instances, Resources, and Properties that may be altered by component script.

A Configuration can define event handlers in script that are invoked by the CMI in response to client application method calls. See Script Events for a list of events handled by configuration script. The configuration's script code is taken from Platform.DefaultConfigScript.

A Configuration also has methods to check its dependencies, (CheckDependencies), build the target system image (Build) and save the configuration to a .SLX file (Save)

CMI client applications such as authoring and browsing tools can store some of their state with a configuration (e.g. display layout, current selections, etc.) can use the extended properties collection (Configuration.Properties).


Configuration.Authors Property

Authors Property

The Authors property returns a string containing semi-colon separated list of email addresses of the authors of the Configuration.

Syntax

    strAuthors = objConfiguration.Authors

Notes

This property is optional and may be null.


Configuration.Build Method

Build Method

The Build method fires the cmiOnBuild event in configuration script.

Syntax

    objConfiguration.Build(BuildPath)

    BuildPath

      A string containing the path of the folder in which the target system image should be built. This string is passed as the BuildPath parameter to the cmiOnBuild event.


Configuration.BuildType Property

BuildType Property

The BuildType property returns an integer that determines the build type of the target system (free, checked, etc). Possible values are determined by the build script code. The CMI does not interpret the value of this property.

Syntax

    nType = objConfiguration.BuildType


Configuration.CheckDependencies Method

CheckDependencies Method

The CheckDependencies method fires the cmiOnCheckDependencies event in configuration script.

Syntax

    objConfiguration.CheckDependencies()


Configuration.Close Method

Close Method

The Close method closes the configuration and must be called for all open Configuration objects. It allows the CMI to release internally allocated resources before the application releases the Configuration object. This method method fires the cmiOnCloseConfig event in configuration script.

Syntax

    objConfiguration.Close()

Notes

If the application does not call this method for an open Configuration object then it will leak memory.


Configuration.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the Configuration.

Syntax

    objCMI = objConfiguration.CMI


Configuration.Copyright Property

Copyright Property

The Copyright property returns a string containing the copyright text for the Configuration.

Syntax

    strCopyright = objConfiguration.Copyright

Notes

This property is optional and may be null.


Configuration.DateCreated Property

DateCreated Property

The DateCreated property returns the date and time the configuration was created in UTC. It is typically set by the platform script when the configuration is created. It must be set using a US English date format.

Syntax

    DateCreated = objConfiguration.DateCreated

Notes

This property is optional and may be null.


Configuration.DateRevised Property

DateRevised Property

The DateRevised property returns the date and time the Configuration was last revised in UTC. It must be set using a US English date format.

Syntax

    DateRevised = objConfiguration.DateRevised

Notes

This property is optional and may be null.


Configuration.Description Property

Description Property

The Description property returns a string containing the description of the configuration.

Syntax

    strDescription = objConfiguration.Description

Notes

This property is optional and may be null.


Configuration.Dirty Property

Dirty Property

The Dirty property returns a boolean value indicating whether the configuration has been changed since the last time it was saved. The application can use this property to determine whether to prompt the user to save the configuration.

Syntax

    fDirty = objConfiguration.Dirty


Configuration.DisplayName Property

DisplayName Property

The DisplayName property returns a string containing the display name of the configuration.

Syntax

    strDisplayName = objConfiguration.DisplayName

Notes

This property is optional and may be null.


Configuration.Generation Property

Generation Property

The Generation property returns an integer that is updated each time the configuration is saved, and is set to the corresponding value from CMI.Generation). When a configuration is opened, if CMI.Generation and Configuration.Generation are different, then it must be assumed that any cached data in the configuration is stale. The application should refresh the data from the database as necessary. This procedure is typically handled by the script event cmiOnOpenConfig.

Syntax

    nGeneration = objConfiguration.Generation


Configuration.Instances Property

Instances Property

The Instances property returns a collection of Instance objects that represents the set of component instances that comprise the target system. This collection can be altered by component script.

Syntax

    objInstances = objConfiguration.Instances

Notes

If this property is accessed repeatedly it always returns the same Configuration of the collection.


Configuration.Owners Property

Owners Property

The Owners property returns a string containing a semi-colon separated list of email addresses of the owners of the Configuration.

Syntax

    strOwners = objConfiguration.Owners

Notes

This property is optional and may be null.


Configuration.Path Property

Path Property

The Path property returns a string containing complete path (including the file name) to the configuration's .SLX file.

Syntax

    strPath = objConfiguration.Path


Configuration.Platform Property

Platform Property

The Platform property returns the Platform on which the configuration is based.

Syntax

    objPlatform = objConfiguration.Platform


Configuration.Properties Property

Properties Property

The Properties property returns a collection of ExtProperty objects that represents a set of extended properties for the Configuration. These properties are in addition to the extended properties defined by Instance.Properties for each Instance in the configuration. Configuration and component script may alter this collection.

Syntax

    objProperties = objConfiguration.Properties

Notes

If this property is accessed repeatedly it always returns the same Configuration of the collection.

CMI client applications such as authoring and browsing tools that need to store some of their state with a configuration (e.g. display layout, current selections, etc.) should use this collection.


Configuration.ResolveRegistryDependencies Method

ResolveRegistryDependencies Method

The ResolveRegistryDependencies method fires the cmiOnResolveRegistryDependencies event in configuration script.

Syntax

    objConfiguration.ResolveRegistryDependencies()


Configuration.Resources Property

Resources Property

The Resources property returns a collection of Resource objects that represents the set of resources that will be processed when building the target system for the Configuration. These resources are in addition to those defined by Instance.Resources for each Instance in the configuration. Configuration and component script may alter this collection.

Syntax

    objResources = objConfiguration.Resources


Configuration.Revision Property

Revision Property

The Revision property returns an integer that is incremented each time the configuration is edited or updated in any way. When a configuration is created this property is initially set to 1.

Syntax

    nRevision = objConfiguration.Revision


Configuration.Save Method

Save Method

The Save method saves the configuration to the .SLX file specified by the Path property. It fires the cmiOnSaveConfig event in configuration script.

Syntax

    objConfiguration.Save()

Notes

All directories specified in the Path property must exist. This method does not create new directories.


Configuration.Script Property

Script Property

The Script property returns an object that represents the loaded and running script code of the configuration. The object exposes the public methods of the code. The script code comes from the Platform on which the configuration is based (see Platform.ScriptText). The script engine is loaded when a new configuration is created or when an existing configuration is opened. For more information see Scripting.

Syntax

    objScript = objConfiguration.Script

Notes

If the Platform does not define any script code then this property will return null.


Configuration.Upgrade Method

Upgrade Method

The definition of this method is still under discussion.

TBD

Syntax

    objConfiguration.Upgrade()


Configuration.Vendor Property

Vendor Property

The Vendor property returns a string containing the vendor that created the Configuration.

Syntax

    strVendor = objConfiguration.Vendor

Notes

This property is optional and may be null.


Configuration.Version Property

Version Property

The Version property returns a string containing the version of the Configuration. The version string contains arbitrary text. It is never used to compare versions. The Revision property is used for this purpose.

Syntax

    strVersion = objConfiguration.Version

Notes

This property is optional and may be null.


Dependencies

The Dependencies collection can represent dependency objects in the component database (Component.GetDependencies), or in a component instance (Instance.Dependencies) within a configuration.

For components, Component.GetDependencies returned a collection that can be filtered to present a specific subset of the component's dependencies. Instance.Dependencies is always completely populated automatically by the CMI and can be altered by component script. Dependency objects in the collection can be referenced using an ordinal index.

The Add method can be used to add a Dependency object to the collection in a component instance.

Count returns the number of Dependency objects in the collection.

Remove removes a Dependency object from the collection. It can only be used for Instance.Dependencies.

Clear removes all Dependency objects from the collection. It can only be used for Instance.Dependencies.

CMI returns the top-level CMI object that contains the collection.

Platform returns the Platform object that contains the collection.

Owner returns the object that owns the collection.


Dependencies.Add Method

Add Method

The Add method adds a new Dependency object to the collection. This method can only be used in a Dependencies collection within a configuration (Instance.Dependencies). It cannot be used to add dependencies to a component definition in the database.

Syntax

    objNewDependency = objDependencies.Add(Class, Type, TargetGUID, MinRevision, [DisplayName], [Description])

    Class

      An enumerated value that determines whether the dependency is for build order, inclusion/exclusion, or registry keys. In all cases Type determines the exact relationship (e.g. dependent on one member of the group, the entire group, etc). See Dependency.Class for possible values.

    Type

      An enumerated value that determines the relationship between the Instance and the TargetObject. The nature of the relationship is determined by the combination of Class, Type, and whether TargetObject is an Instance or a Group. See Dependency.Type for possible values.

    TargetGUID

      The GUID of the object that is the target of the dependency. This can be the VIGUID of a Component or the VSGUID of a Group.

    MinRevision

      The minimim revision number of the object referenced by TargetGUID.

    DisplayName

      Optional. A string containing the display name for the dependency.

    Description

      Optional. A string containing the description the dependency.


Dependencies.Clear Method

Clear Method

The Clear method removes all Dependency objects from the collection. It can only be used for Instance.Dependencies. Component dependencies are only deleted when the owning components are deleted.

Syntax

    objDependencies.Clear()


Dependencies.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the collection.

Syntax

    objCMI = objDependencies.CMI


Dependencies.Count Property

Count Property

The Count property returns the number of Dependency objects currently in the collection.

Syntax

    nDependencies = objDependencies.Count

Notes

For components, the count does not necessarily reflect the number of dependency objects in the database. It represents the number of objects retrieved from the database during the last call to Component.GetDependencies.

For Instance.Dependencies it always represents the total number of Dependency objects for the instance within the configuration. That collection is initially populated from Component.Dependencies and can later be altered by component script.


Dependencies.Item Property

Item Property

The Item property returns the specified Dependency object from the collection. It is the default property and does not require an explicit reference by name.

Syntax

    objDependency = objDependencies(Index)

    objDependency = objDependencies.Item(Index)

    Index

      An integer containing the one-based ordinal position of the Dependency object in the collection.


Dependencies.Owner Property

Owner Property

The Owner property returns the object that owns the collection. This could be a Component or an Instance.

Syntax

    objOwner = objDependencies.Owner

Notes

To determine the type of object returned by this property the caller can use CMI.QueryObjectType.


Dependencies.Platform Property

Platform Property

The Platform property returns the Platform object that contains the collection.

Syntax

    objPlatform = objDependencies.Platform


Dependencies.Remove Method

Remove Method

The Remove method removes the specified Dependency object from the collection. It can only be used for Instance.Dependencies. Component dependencies are only deleted when the owning component is deleted.

Syntax

    objDependencies.Remove(Index)

    Index

      An integer containing the one-based ordinal position of the Dependency object in the collection.


Dependency

Components define target system functionality. They do not, however, exist in isolation. Most components require the services of other components to perform their tasks. This relationship is expressed as a dependency relationship between components.

The system architecture exposes a rich dependency model that allows complex inter-component relationships to be described. These relationships ensure that adequate support is available in a run-time image for the selected components and that the run-time image is constructed in the correct order.

Dependency objects are always contained in a Dependencies collection owned either by a Component or by an Instance. When an Instance is added to a configuration, the Platform script typically populates its dependencies collections from the collections in Instance.ComponentChain

The TargetObject property contains a reference to the object that is the target of the dependency. This can be an Component or a Group.

The MinRevision property specifies the minimum revision required of the object referenced by TargetObject.

The Class property returns an enumerated value that determines whether the dependency is for build order, inclusion/exclusion, or registry keys. Registry dependencies are not explicitly specified by components. Instead, these dependencies are derived by the CMI on the fly when a build process or dependency check is initiated. A registry dependency is deduced by the CMI when a component X performs a non-destructive edit of a registry key and a component Y performs a destructive write to the same registry key.

The Type property returns an enumerated value that determines the relationship between the Instance and TargetObject. The nature of the relationship is determined by the combination of Class, Type, and whether TargetObject is an Instance or a Group.


Dependency.Class Property

Class Property

The Class property returns an enumerated value that determines whether the dependency is for build order, inclusion/exclusion, or registry keys. In all cases Type determines the exact relationship (e.g. dependent on one member of a group, the entire group, etc).

Syntax

    eClass = objDependency.Class

    eClass can have the following values:

    eClass Values

    Constant | Description
cmiAfter (3) | Build-after dependency. The TargetObject must be built after the Instance.
cmiBefore (2) | Build-before dependency. The TargetObject must be built before the Instance.
cmiInclude (1) | Include dependency. The Instance requires the inclusion or exclusion of the TargetObject.
cmiRegistry (4) | Registry dependency. The Instance is dependent upon registry keys defined by the TargetObject and must be built after it.


Dependency.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the dependency.

Syntax

    objCMI = objDependency.CMI


Dependency.Description Property

Description Property

The Description property returns a string containing the description of the dependency.

Syntax

    strDescription = objDependency.Description

Notes

This property is optional and may be null.


Dependency.DisplayName Property

DisplayName Property

The DisplayName property returns a string containing the display name of the dependency.

Syntax

    strDisplayName = objDependency.DisplayName

Notes

This property is optional and may be null.


Dependency.Index Property

Index Property

The Index property returns an integer containing the ordinal position of the Dependency object in the Dependencies collection.

Syntax

    nIndex = objDependency.Index

Notes

Index represents only the ordinal position in the collection. It does not necessarily represent the ordinal position in the database.


Dependency.MinRevision Property

MinRevision Property

When the TargetGUID property specifies the VIGUID of a component then the MinRevision property returns an integer that specifies the minimum revision required of the component that will be returned by TargetObject.

Syntax

    nMinRevision = objDependency.MinRevision


Dependency.Owner Property

Owner Property

The Owner property returns the object that owns the Dependency. This can be a Component or an Instance.

Syntax

    objOwner = objDependency.Owner

Notes

To determine the type of object returned by this property the caller can use CMI.QueryObjectType.


Dependency.Platform Property

Platform Property

The Platform property returns the Platform object that contains the Dependency.

Syntax

    objPlatform = objDependency.Platform


Dependency.Properties Property

Properties Property

The Properties property returns a collection of ExtProperty objects that represent the set of extended properties for a dependency.

Syntax

    objExtProperties = objDependency.Properties

Notes

This property always returns the same instance of the collection.


Dependency.TargetGUID Property

TargetGUID Property

The TargetGUID property returns the GUID of the object on which the owner of the dependency is dependent. This can be the VIGUID of a Component or the VSGUID of a Group.

Syntax

    strTargetGUID = objDependency.TargetGUID


Dependency.TargetObject Property

TargetObject Property

The TargetObject property returns the object on which the owner of the dependency is dependent.

Syntax

    objTargetObject = objDependency.TargetObject

Notes

This method can return null if the target object has not yet been imported into the database.

To determine the type of object returned by this property the caller can use CMI.QueryObjectType.


Dependency.Type Property

Type Property

The Type property returns an enumerated value that determines the relationship between the Component and TargetObject. The nature of the relationship is determined by the combination of Class, Type, and whether TargetObject is an Component or a Group.

Syntax

    eType = objDependency.Type

    The meaning of Type values is dependent on the value of Class.

    Values for Type when Class=cmiAfter

    Constant | TargetObject is an Component | TargetObject is a Group
cmiAll (4) | The TargetObject component must be built after the Component that owns the dependency. | All members of the TargetObject group must be built after the Component that owns the dependency.
cmiAtLeastOne (2) | The TargetObject component must be built after the Component that owns the dependency. | Not Valid.
cmiExactlyOne (1) | Not valid. | Not valid.
cmiFromGroup (0) | Not valid. | The dependency type is take from the DefaultDependencyType property of the TargetObject group.
cmiNone (5) | Not valid. | Not valid.
cmiZeroOrOne (3) | Not valid. | Not valid.

    Values for Type when Class=cmiBefore

    Constant | TargetObject is an Component | TargetObject is a Group
cmiAll (4) | The TargetObject component must be built before the Component that owns the dependency. | All members of the TargetObject group must be built before the Component that owns the dependency.
cmiAtLeastOne (2) | The TargetObject component must be built before the Component that owns the dependency. | Not valid.
cmiExactlyOne (1) | Not valid. | Not valid.
cmiFromGroup (0) | Not valid. | The dependency type is take from the DefaultDependencyType property of TargetObject group.
cmiNone (5) | Not valid. | Not valid.
cmiZeroOrOne (3) | Not valid. | Not valid.

    Values for Type when Class=cmiInclude

    Constant | TargetObject is an Component | TargetObject is a Group
cmiAll (4) | The TargetObject component is included in the configuration. | All members of the TargetObject group are included in the configuration.
cmiAtLeastOne (2) | The TargetObject component is included in the configuration. | At least one member of TargetObject group is included in the configuration.
cmiExactlyOne (1) | The TargetObject component is included in the configuration. | Exactly one member of TargetObject group is included in the configuration.
cmiFromGroup (0) | Not valid. | The dependency type is take from the DefaultDependencyType property of TargetObject group.
cmiNone (5) | The TargetObject component is excluded from the configuration. | All members of the TargetObject group are excluded from the configuration.
cmiZeroOrOne (3) | Not valid. | At most, one member of the TargetObject group may be included in the configuration.


ExtProperties

The ExtProperties collection contains ExtProperty objects that represent the set of extended properties on an object. For database objects the properties are defined when the object is imported into the database and can only be changed if the object is re-imported. For configuration objects, the collection may be initially populated from the database where applicable (e.g. Instance.Properties is populated from Component.Properties), and it is always extensible by component script.

ExtProperty objects in the collection can be referenced using an ordinal index or by Name.

The Add method can be used to add a ExtProperty object to the collection within a configuration.

Count returns the number of ExtProperty objects in the collection.

Remove removes a ExtProperty object from the collection (within configurations only).

Clear removes all ExtProperty objects (within configurations only).

CMI returns the top-level CMI object that contains the collection.


ExtProperties.Add Method

Add Method

The Add method adds a new ExtProperty object to the collection. This method can only be used in a ExtProperties collection within a configuration. It cannot be used to add properties to a database object.

Syntax

    objNewExtProperty = objExtProperties.Add(Name, Format, Value)

    Name

      A string containing the name of the property.

    Format

      An enumerated value that determines the format of the data contained in the property's value. See ExtProperty.Format for the possible values.

    Value

      Data for the property's value. See ExtProperty.Format for information on the data format.


ExtProperties.Clear Method

Clear Method

The Clear method removes all ExtProperty objects from the collection. This method can only be used in a ExtProperties collection within a configuration. It cannot be used to remove properties from a database object.

Syntax

    objExtProperties.Clear()


ExtProperties.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the collection.

Syntax

    objCMI = objExtProperties.CMI


ExtProperties.Count Property

Count Property

The Count property returns the number of ExtProperty objects currently in the collection.

Syntax

    nExtProperties = objExtProperties.Count

Notes

For a database object the count does not necessarily reflect the number of property objects in the component database.


ExtProperties.Item Property

Item Property

The Item property returns the specified ExtProperty object from the collection. It is the default property and does not require an explicit reference by name.

Syntax

    objExtProperty = objExtProperties(Index)

    objExtProperty = objExtProperties.Item(Index)

    Index

      Either an integer containing the one-based ordinal position of the ExtProperty object in the collection or a string containing the value of the object's Name property (not case-sensitive).

    Notes

    If a name was specified and the item does not exist then this method succeeds and returns null. If an ordinal position was specified and the item does not exist then an error is returned.


ExtProperties.Remove Method

Remove Method

The Remove method removes the specified ExtProperty object from the collection. This method can only be used in a ExtProperties collection within a configuration. It cannot be used to remove properties from a database object.

Syntax

    objExtProperties.Remove(Index)

    Index

      Either an integer containing the one-based ordinal position of the ExtProperty object in the collection or a string containing the value of the object's Name property.


ExtProperty

The ExtProperty object represents an extended property on another object. It contains a name-value pair that is associated with the object and is always contained in a ExtProperties collection.

Name specifies the name of the property.

Format specifies the format of data contained in Value (if any). This serves as an indicator to the consumer of the data as to how it should be interpreted.

Value contains the data that is the property's value.


ExtProperty.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the ExtProperty.

Syntax

    objCMI = objExtProperty.CMI


ExtProperty.Format Property

Format Property

An enumerated value that determines specifies the format of data contained in ExtProperty.Value (if any). This serves as an indicator to the consumer (or producer) of the data as to how it should be interpreted.

Syntax

    eFormat = objExtProperty.Format

    The following table explains the possible values for eFormat and the corresponding data type of ExtProperty.Value. For all data formats ExtProperty.Value always contains data - it cannot contain null. A read-write property cannot be set to null by an application.

    eFormat Values

    Constant | Description
cmiBinary (1) | An array of unsigned 8 bit integers. The CMI stores the data as an array of VARIANTs where each VARIANT uses the VT_UI1 data type. It can be set to an empty array if the property is read-write or if it was imported from an empty PROPERTY element.
cmiString (2) | A string. The CMI stores the data as a UNICODE string. It can be set to an empty string ("") if the property is read-write or if it was imported from an empty PROPERTY element.
cmiInteger (3) | A 32 bit signed integer. The CMI stores the data as an integer (VT_I4).
cmiBoolean (4) | A boolean value. The CMI stores the data as a boolean (VT_BOOL).
cmiMultiString (5) | Multiple strings. The CMI stores the data as an array of VARIANTs where each VARIANT uses the VT_BSTR data type. It can be set to an empty array if the property is read-write or if it was imported from an empty PROPERTY element.
cmiExpression (6) | The data is stored as a UNICODE string containing an expression that must be evaluated by the script language of the component or configuration that owns the property. In VBScript use the Eval function. In JScript use the eval function. This format cannot be set to an empty string ("").
cmiScript (7) | The data is stored as a UNICODE string containing script code in the script language of the component or configuration that owns the property. The code must be run in order to determine the value of the property. In VBScript use the ExecuteGlobal function. In JScript use the eval function. This format cannot be set to an empty string ("").
cmiObject (8) | An object. The object must support persistence using IPersistStream or IPersistStreamInit. All CMI objects can be used for this type.
cmiGUID (9) | A GUID as a string in registry format e.g. "{00000000-0000-0000-0000-000000000000}". This format cannot be sent to an empty string.
cmiTimeDate (10) | A date and/or time in any OLE Automation VT_DATE compatible format.

Notes

Note that Format is always read-only. To change the format of a read-write property, remove it from the collection and add it back again with the new format.


ExtProperty.Index Property

Index Property

The Index property returns an integer containing the ordinal position of the ExtProperty object in the ExtProperties collection.

Syntax

    nIndex = objExtProperty.Index

Notes

Index represents only the ordinal position in the collection. It does not necessarily represent the ordinal position in the database.


ExtProperty.Name Property

Name Property

The Name property returns a string containing the Name of the property.

Syntax

    strName = objExtProperty.Name


Value.Value Property

Value Property

Value contains the data that is the property's value. For the format of the data see Format. This is the default property of the ExtProperty object.

Syntax

    Value = objExtProperty.Value

    Value = objExtProperty

Notes

A property's value cannot be set to null and it cannot have a null value from an empty PROPERTY element during import. For more information on how an empty PROPERTY element is interpreted see Format. If the application needs to keep track of whether a property has a valid data value it can use an additional property to store that information.

The Value property is read-only for database objects. It is read-write for Property objects that are members of the Configuration.Properties and Instance.Properties collections. It is also read-write for members of the Resource.Properties collection when the Resource object is a member of Configuration.Resources or Instance.Resources.

Note that ExtProperty.Format is always read-only. When setting the value of a read-write property, the data must be appropriate for the format. To change the format of a read-write property, remove it from the collection and add it back again with the new format.


Filter

The Filter object is used as an optional parameter to the Platform.GetComponents method to limit the returned collection to a subset of the Component objects that belong to the Platform.

A filter is defined using a Filter object and one or more Rule objects in Filter.Rule.

Filter.SortCols is used to sort the collection on one or more properties of a Component (e.g. sort by Vendor and Released).

Filter.SortOrders determines the sorting direction for each property in SortCols.

The Description and DisplayName properties are optional and supply a description and display name for use by UI tools.

The Save method saves the Filter object to a file. The Load method loads a saved filter. The Filter object also supports the IPersistStream and IPersistFile interfaces and can be used with the GetObject function in Visual Basic, VBScript, and JScript.

The Filter object is publicly createable and can be created using CoCreateInstance in C/C++, CreateObject("CMI.Filter") in VBScript, new ActiveXObject("CMI.Filter") in JScript, etc.

Sample Filter Creation Code

Getting All Components that Use a Certain Resource

Suppose that there is a resource type called "File", with a VSGUID of "{E66B49F6-4A35-4246-87E8-5C1A468315B5}", that has a property called "SrcName". This property indicates that a component uses a particular file. The following VBScript code shows how to retrieve a collection of components that use a file called "Foo.dll".

Dim o_CMI
Dim o_Plats
Dim o_Comps
Dim o_Filter
Dim o_Rule
Dim Args(2)

Set o_CMI = CreateObject("CMI.CMI")
o_CMI.OpenDB("MyDBServer")
Set o_Plats = o_CMI.GetPlatforms
Set o_Filter = CreateObject("CMI.Filter")
Set o_Rule = CreateObject("CMI.Rule")

o_Filter.DisplayName = "Components using Foo.dll"
o_Filter.Description = "Filter to retrieve all components that use the file Foo.dll"
Set o_Filter.Rule = o_Rule

o_Rule.Operator = cmiEquals
o_Rule.Qualifier = cmiResourceExtendedProperty

Args(0) = "SrcName"
Args(1) = "Foo.dll"
Args(2) = "{E66B49F6-4A35-4246-87E8-5C1A468315B5}"
o_Rule.Arguments = Args

Set o_Comps = o_Plats(1).GetComponents(o_Filter)

Getting Only the Latest Revision of All Components

Tools and scripts typically only need to access the latest revisions of components. The following JScript code shows to retrieve such a collection.

var o_CMI = new ActiveXObject("CMI.CMI");
var o_Filter = new ActiveXObject("CMI.Filter");
var o_Rule = new ActiveXObject("CMI.Rule");
var o_Plats = null;
var o_Comps = null;

o_CMI.OpenDB("MyDBServer");
o_Plats = o_CMI.GetPlatforms();

o_Filter.DisplayName = "Latest revisions of Components";
o_Filter.Description = "Filter to retrieve only the latest revision of all components.";
o_Filter.Rule = o_Rule;

o_Rule.Operator = cmiMax;
o_Rule.Qualifier = cmiComponentProperty;
o_Rule.Arguments = "Revision";

o_Comps = o_Plats(1).GetComponents(o_Filter);

Using Multiple Rules: Getting All Components from Two Vendors

A tree of Rule objects can be used to specify multiple rules in any combination of logical AND and logical OR operators with unlimited depth. The following example shows how to get all components from vendors "ABC" and "XYZ".

Dim o_CMI
Dim o_Plats
Dim o_Comps
Dim o_Filter
Dim o_RuleAnd
Dim o_RuleABC
Dim o_RuleXYZ
Dim Args(1)

Set o_CMI = CreateObject("CMI.CMI")
o_CMI.OpenDB("MyDBServer")
Set o_Plats = o_CMI.GetPlatforms
Set o_Filter = CreateObject("CMI.Filter")
Set o_RuleOr = CreateObject("CMI.Rule")
Set o_RuleABC = CreateObject("CMI.Rule")
Set o_RuleXYZ = CreateObject("CMI.Rule")

o_Filter.DisplayName = "Components from ABC and XYZ"
o_Filter.Description = "Filter to retrieve all components from companies ABC and XYZ"
Set o_Filter.Rule = o_RuleOr

o_RuleOr.Operator = cmiLogicalOr
Set Args(0) = o_RuleABC
Set Args(1) = o_RuleXYZ
o_RuleOr.Arguments = Args

o_RuleABC.Operator = cmiEquals
o_RuleABC.Qualifier = cmiComponentProperty
Args(0) = "Vendor"
Args(1) = "ABC"
o_RuleABC.Arguments = Args

o_RuleXYZ.Operator = cmiEquals
o_RuleXYZ.Qualifier = cmiComponentProperty
Args(0) = "Vendor"
Args(1) = "XYZ"
o_RuleXYZ.Arguments = Args

Set o_Comps = o_Plats(1).GetComponents(o_Filter)


Filter.Description Property

Description Property

The Description property returns a string containing a description of the Filter.

Syntax

    strDescription = objFilter.Description

Notes

This property is optional and may be null.


Filter.DisplayName Property

DisplayName Property

The DisplayName property returns a string containing the display name of the Filter.

Syntax

    strDisplayName = objFilter.DisplayName

Notes

This property is optional and may be null.


Load Method

The Load method is used to load the properties of a Filter object saved previously using the Save method.

Syntax

    objFilter.Load(Path)

    Path

      The fully qualified path and file name of the saved filter.

    Notes

    This method may be called mulitple times on the same Filter object. Each call completely replaces the filter's properties with the contents of the saved filter.


Filter.Rule Property

Rule Property

The Rule property returns a Rule object that determines how the collection will be filtered.

Syntax

    objRule = objFilter.Rule

Notes

This property is null when a Filter object is created and should be set before the Filter is used. A Filter can be used without a rule if sorting is needed on the returned collection without any selection criteria. If a Filter has no rule and no sorting defined then it has no effect on the returned collection.


Save Method

The Save method is used to save the properties of a Filter object to a file. The properties may be loaded into another Filter object using the Load method.

Syntax

    objFilter.Save(Path)

    Path

      The fully qualified path and file name for the saved filter.


Filter.SortCols Property

SortCols Property

The SortCols property returns the names of one or more component properties on which to sort the collection. If the sort is only on a single property then SortCols contains the name of that property. If the sort is on multiple properties then SortCols contains an array of the property names.

If SortCols is set then SortOrders must also be set to determine the sort order for each property.

Syntax

    strSortCols = objFilter.SortCols

    The following table lists the possible values for sort column names and their corresponding Component object properties:

    Sort Column Names

    Name | Property
"Authors" | Sort on Component.Authors
"Copyright" | Sort on Component.Copyright
"DateCreated" | Sort on Component.DateCreated
"DateImported" | Sort on Component.DateImported
"DateRevised" | Sort on Component.DateRevised
"Description" | Sort on Component.Description
"DisplayName" | Sort on Component.DisplayName
"Editable" | Sort on Component.Editable
"HTMLFinal" | Sort on Component.HTMLFinal
"HTMLTitle" | Sort on Component.HTMLTitle
"IsMacro" | Sort on Component.IsMacro
"MultiInstance" | Sort on Component.MultiInstance
"Owners" | Sort on Component.Owners
"PlatformGUID" | Sort on Component.PlatformGUID
"PrototypeVIGUID" | Sort on Component.PrototypeVIGUID
"Released" | Sort on Component.Released
"RepositoryVSGUID" | Sort on Component.RepositoryVSGUID
"Revision" | Sort on Component.Revision
"ScriptLanguage" | Sort on Component.ScriptLanguage
"Vendor" | Sort on Component.Vendor
"Version" | Sort on Component.Version
"VIGUID" | Sort on Component.VIGUID
"Visibility" | Sort on Component.Visibility
"VSGUID" | Sort on Component.VSGUID

Notes

This property is optional and may be null.

Note that the collection cannot be sorted on component extended properties, on resource properties, or on resource extended properties.

When passing an array in C++ use a VARIANT of type VT_ARRAY | VT_VARIANT. Each VARIANT in the SafeArray must be of type VT_BSTR where VARIANT.bstrVal contains the property name.


Filter.SortOrders Property

SortOrders Property

The SortOrders property returns one or more enumerated values that determine the sort order for each property in SortCols. If the sort is only on a single property then SortOrders contains a single value. If the sort is on multiple properties then SortOrders contains an array of values.

If SortOrders is not set then SortCols is ignored.

Syntax

    eSortOrders = objFilter.SortOrders

    Possible values for eSortOrder:

    eFormat Values

    Constant | Description
cmiAscending (1) | The sort is ascending on the corresponding property in SortCols
cmiDescending (2) | The sort is descending on the corresponding property in SortCols

Notes

This property is optional and may be null.

When passing an array in C++ use a VARIANT of type VT_ARRAY | VT_VARIANT. Each VARIANT in the SafeArray must be of type VT_I4 where VARIANT.lVal contains one of the enumerated values listed above.


Groups

The Groups collection represents the group objects in the component database. It is accessed from the Platform.GetGroups method. Group objects can be referenced using an ordinal index or by VSGUID.

Count returns the number of Group objects in the collection.

Remove removes a Group object from the collection and also deletes it from the database.

Clear removes all Group objects from the collection and also deletes them from the database.

CMI returns the top-level CMI object that contains the collection.

Platform returns the Platform object that contains the collection.


Groups.Clear Method

Clear Method

The Clear method removes all Group objects from the collection and also deletes them from the database along with all of their member objects. If the groups have any extended properties then they are also deleted from the database.

Syntax

    objGroups.Clear()


Groups.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the collection.

Syntax

    objCMI = objGroups.CMI


Groups.Count Property

Count Property

The Count property returns the number of Group objects currently in the collection.

Syntax

    nGroups = objGroups.Count

Notes

The count does not necessarily reflect the number of group objects in the component database. It represents the number of objects retrieved from the database during the last call to Platform.GetGroups.


Groups.Item Property

Item Property

The Item property returns the specified Group object from the collection. It is the default property and does not require an explicit reference by name.

Syntax

    objGroup = objGroups(Index)

    objGroup = objGroups.Item(Index)

    Index

      Either an integer containing the one-based ordinal position of the Group object in the collection or a string containing the value of the object's VSGUID property.


Groups.Platform Property

Platform Property

The Platform property returns the Platform object that contains the collection.

Syntax

    objPlatform = objGroups.Platform


Groups.Remove Method

Remove Method

The Remove method removes the specified Group object from the collection, deletes it from the database, and can optionally delete the group's member objects from the database. If the group has any extended properties then they are also deleted from the database.

Syntax

    objGroups.Remove(Index, [RemoveMembers])

    Index

      Either an integer containing the one-based ordinal position of the Group object in the collection or a string containing the value of the object's VSGUID property.

    RemoveMembers

      Optional. If specified, indicates whether to delete the objects that are members of the group from the database in addition to the group itself. If not specified, defaults to True.


Group

Groups are used to collect components into sets. Each Group object defines a group, and contains the usual properties for a primary object (VSGUID, Revision, etc). Each component then identifies the groups to which it belongs by listing group GUIDs. There is no limit to the number of groups, or the number of groups to which each component can belong. Group object are revisable objects.

Package Groups

Package groups are used to organize components into groups so that certain operations can be performed en masse. For example it is possible to delete a package group instead of deleting the individual components. In this case, the CMI will delete all components that are members of that group. An example of a package group might be a Windows NT Service Pack. All of the components that comprise the service pack can be marked as members of a Service Pack group. Package groups are also used to manage automatic configuration upgrades. When a component is added to a configuration, the component identity is stored in the configuration using a VSGUID, thus locking the configuration to a specific version of the component. As new versions of a component are added to the database it may become desirable to upgrade the configuration to use these components. This can be done on a component-by-component basis, but is more easily managed on a group basis. Thus it is possible to request a bulk upgrade of a configuration to (say) Service Pack 6. To do this, the CMI first correlates the VIGUID of each instance against the VIGUIDs of the SP6 components. For each match, the instance is upgraded to the SP6 version of the component.

Category Groups

Category groups are used to break the full set of components present in a platform into smaller sets for the purposes of UI display. There are actually no semantics within the CMI associated with category groups - they are available entirely for the use of UI tools. UI tools may display a list of components broken down by category, and thus a category group is analogous to a file folder on disk. However, unlike file folders, a component can belong to any number of category groups, and this allows the component to appear in more than one category (which is useful if a component straddles two category definitions). The categorization of components is beyond the scope of this specification. However, it is recommended that the DisplayName property of the category group be viewed as a simple "category path" that provides a main category and a series of sub-categories, each separated by colon characters. For example: Drivers : Networking : Network Adapters. If this convention is adopted, the UI tools may choose to display the category list as a flat list or a simple category tree. Notice that for readability spaces are placed on either side of the colon characters. UI tools that wish to display the category namespace as a tree should strip these spaces when processing the category names.

Dependency Groups

Dependency groups are used to indirectly specify inter-component dependencies. A "direct" dependency is used when one component specifies directly that it is dependent upon another (by GUID). An "indirect" dependency is used when one component specifies that it is dependent upon a dependency group. In this case the dependency is interpreted as meaning that the component is dependent upon all of the components that are members of that group. Components that specify group dependencies may specify a dependency type or they may instead take that type information from the group itself. If they choose the latter alternative, the type information comes from the DefaultDependencyType property of the group.


Group.Authors Property

Authors Property

The Authors property returns a string containing semi-colon separated list of email addresses of the authors of the group.

Syntax

    strAuthors = objGroup.Authors

Notes

This property is optional and may be null.


Group.Class Property

Class Property

The Class property returns an enumerated value that indicates whether the group defines a category, a package, or a dependency.

Syntax

    eClass = objGroup.Class

    eClass can have the following values:

    eClass Values

    Constant | Description
cmiPackage (1) | Package groups are used to collect components and repositories together for administrative purposes. A package group allows a set of components and/or repositories to be managed as a single unit. For example, all the components in a package group can be deleted in a single operation. In addition, package groups are used to manage bulk component instance upgrades (e.g. to upgrade all the component instances in a configuration to a new service pack).
cmiCategory (2) | Category groups are used to collect components together into functionally related categories. This is primarily used to assist in filtering and organizing components for display in the UI. For example, one category might be "Display Drivers" and contain all the components that define display adapter drivers. Categories are purely an organizational convenience.
cmiDependencyGroup (3) | The group defines a set of components that can be used by other components to express a dependency on the entire set.
cmiRepositorySet (4) | The group defines a set of repositories that can be used as the source of files for one or more components in the database.


Group.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the Group.

Syntax

    objCMI = objGroup.CMI


Group.Copyright Property

Copyright Property

The Copyright property returns a string containing the copyright text zfor the group.

Syntax

    strCopyright = objGroup.Copyright

Notes

This property is optional and may be null.


Group.DateCreated Property

DateCreated Property

The DateCreated property returns the date and time the group was created in UTC.

Syntax

    DateCreated = objGroup.DateCreated

Notes

This property is optional and may be null.


Group.DateImported Property

DateImported Property

The DateImported property returns the date and time the group definition was imported into the component database (in UTC).

Syntax

    DateImported = objGroup.DateImported


Group.DateRevised Property

DateRevised Property

The DateRevised property returns the date and time the group was last revised in UTC.

Syntax

    DateRevised = objGroup.DateRevised

Notes

This property is optional and may be null.


Group.DefaultDependencyType Property

DefaultDependencyType Property

Components that specify group dependencies may specify a dependency type or they may instead take that type information from the group itself. If they choose the latter alternative, the type information comes from the DefaultDependencyType property. This property returns an enumerated value that indicates the dependency type. This enumeration is the same one used by the Dependency.Type property.

Syntax

    eDefaultDependencyType = objGroup.DefaultDependencyType

See Dependency.Type for possible values of eDefaultDependencyType.

Notes

DefaultDependencyType cannot have the value cmiFromGroup.


Group.Description Property

Description Property

The Description property returns a string containing the description of the group.

Syntax

    strDescription = objGroup.Description

Notes

This property is optional and may be null.


Group.DisplayName Property

DisplayName Property

The DisplayName property returns a string containing the display name of the group.

Syntax

    strDisplayName = objGroup.DisplayName

Notes

This property is optional and may be null.


Group.GetMembers Method

GetMembers Method

The GetMembers method returns a polymorphic GroupMembers collection containing objects from the database that belong to the group. Each member of the collection can be a Component or a Repository.

Syntax

    objMembers = objGroup.GetMembers

Notes

This method always returns a new instance of the collection.

If there are multiple revisions of a Component or Repository in the database and they all are members of the group, then all of the revisions will be returned in this collection.


Group.Index Property

Index Property

The Index property returns an integer containing the ordinal position of the Group object in the Groups collection.

Syntax

    nIndex = objGroup.Index

Notes

Index represents only the ordinal position in the collection. It does not necessarily represent the ordinal position in the database.


Group.Owners Property

Owners Property

The Owners property returns a string containing a semi-colon separated list of email addresses of the owners of the group.

Syntax

    strOwners = objGroup.Owners

Notes

This property is optional and may be null.


Group.Platform Property

Platform Property

The Platform property returns the Platform object that contains the group.

Syntax

    objPlatform = objGroup.Platform


Group.PlatformGUID Property

PlatformGUID Property

The PlatformGUID property returns a string containing the either the version-independent GUID (VIGUID) or version-specific GUID (VSGUID) that identifies the platform to which the group belongs.

Syntax

    strPlatformGUID = objGroup.PlatformGUID


Group.Properties Property

Properties Property

The Properties property returns a collection of ExtProperty objects from the database that belong to the group.

Syntax

    objProperties = objGroup.Properties

Notes

This property always returns the same instance of the collection.


Group.Revision Property

Revision Property

The Revision property returns an integer containing the revision ordinal of the group. The revision is a simple ordinal value where a higher value represents a later version of an object. Revisions need not be sequential, but any changes that are made to an object must be accompanied by an increase in the value of the revision.

Syntax

    nRevision = objGroup.Revision


Group.Vendor Property

Vendor Property

The Vendor property returns a string containing the vendor that created the group.

Syntax

    strVendor = objGroup.Vendor

Notes

This property is optional and may be null.


Group.Version Property

Version Property

The Version property returns a string containing the version of the group. The version string contains arbitrary text. It is never used to compare versions. The Revision property is used for this purpose.

Syntax

    strVersion = objGroup.Version

Notes

This property is optional and may be null.


Group.VSGUID Property

VSGUID Property

The VSGUID property returns a string containing the version-specific GUID that uniquely identifies a specific revision of the group.

Syntax

    strVSGUID = objGroup.VSGUID


GroupMembers

The GroupMembers collection is accessed by calling Group.GetMembers. It is a polymorphic collection in which each each element can be either a Component or a Repository. To determine the type of object returned for a particular element in the collection the caller can use CMI.QueryObjectType.

Count returns the number of objects in the collection.

CMI returns the top-level CMI object that contains the collection.

Platform returns the Platform object that contains the collection.


GroupMembers.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the collection.

Syntax

    objCMI = objGroupMembers.CMI


GroupMembers.Count Property

Count Property

The Count property returns the number of objects in the collection.

Syntax

    nGroupMembers = objGroupMembers.Count


GroupMembers.Item Property

Item Property

The Item property returns the specified object from the collection. It is the default property and does not require an explicit reference by name.

Syntax

    objResourceType = objGroupMembers(Index)

    objResourceType = objGroupMembers.Item(Index)

    Index

      Either an integer containing the one-based ordinal position of the object in the collection or a string containing the value of the object's VSGUID property.


GroupMembers.Platform Property

Platform Property

The Platform property returns the Platform object that contains the collection.

Syntax

    objPlatform = objGroupMembers.Platform


ILoadInstanceStream

The ILoadInstanceStream interface is supported by the Instances collection. The Load method allows an application to load a previously saved Instance object into the collection. The QueryLoad method allows an application to query the collection as to whether the saved Instance can be loaded successfully. Saved Instance objects can be passed between threads as well as processes. They can also be saved in permanent storage (e.g. a file) and loaded at a later time.


Load

The Load method allows an application to load a previously saved Instance object into the collection. A new Instance object is created and initialzed from the properties of the saved Instance. This method fires the cmiOnLoadInstance event in configuration script.

Syntax

    HRESULT Load(IStream *piStream, IInstance **ppiInstance)

    IStream *piStream

      The stream containing the saved Instance object.

    IInstance **ppiInstance

      The newly loaded Instance object is returned here.

    Notes

    If the cmiOnLoadInstance event in configuration script disallows the loading of the Instance then this method will return the error cmiErrScriptDisallowed.


QueryLoad

The QueryLoad method allows an application to determine whether a previously saved Instance object can be loaded into the collection. A new Instance object is created and initialzed from the properties of the saved Instance. This method fires the cmiOnLoadInstance event in configuration script. If the cmiOnLoadInstance event disallows the loading of the Instance then this method will return the error cmiErrScriptDisallowed. If the Instance can be successfully created then this method returns S_OK.

Syntax

    HRESULT QueryLoad(IStream *piStream)

    IStream *piStream

      The stream containing the saved Instance object.


ILoadResourceStream

The ILoadResourceStream interface is supported by the Resources collection. The Load method allows an application to load a previously saved Resource object into the collection. The QueryLoad method allows an application to query the collection as to whether the saved Resource can be loaded successfully. Saved Resource objects can be passed between threads as well as processes. They can also be saved in permanent storage (e.g. a file) and loaded at a later time.


Load

The Load method allows an application to load a previously saved Resource object into the collection. A new Resource object is created and initialzed from the properties of the saved Resource. This method fires the cmiOnLoadResource event in configuration script.

Syntax

    HRESULT Load(IStream *piStream, IResource **ppiResource)

    IStream *piStream

      The stream containing the saved Resource object.

    IResource **ppiResource

      The newly loaded Resource object is returned here.

    Notes

    If the cmiOnLoadResource event in configuration script disallows the loading of the Resource then this method will return the error cmiErrScriptDisallowed.


QueryLoad

The QueryLoad method allows an application to determine whether a previously saved Resource object can be loaded into the collection. A new Resource object is created and initialzed from the properties of the saved Resource. This method fires the cmiOnLoadResource event in configuration script. If the cmiOnLoadResource event disallows the loading of the Resource then this method will return the error cmiErrScriptDisallowed. If the Resource can be successfully created then this method returns S_OK.

Syntax

    HRESULT QueryLoad(IStream *piStream)

    IStream *piStream

      The stream containing the saved Resource object.


Instances

The Instances collection represents the set of components that have been instantiated in a configuration and is referenced by Configuration.Instances. When a configuration is created the collection is initially empty. It is populated by the authoring tools as the user adds components to the configuration. Component script may also add Instance objects to the collection.

The Add method can be used to add an Instance object to the collection.

Count returns the number of Instance objects in the collection.

Remove removes an Instance object from the collection.

Clear removes all Instance objects from the collection.

CMI returns the top-level CMI object that contains the collection.

Platform returns the Platform on which the configuration is based.

The Instances collection supports the ILoadInstanceStream interface for the purpose of loading a previously saved Instance object. An Instance object can only be saved by using IPersistStream::Save on the Instance. It can only be loaded by using ILoadInstanceStream on the Instances collection.


Instances.Add Method

Add Method

The Add method adds a new Instance object to the collection. It fires the cmiOnAddInstance event in configuration script.

Syntax

    objNewInstance = objInstances.Add(Component)

    Component

      The Component object on which the new Instance object is based.

    Notes

    If the cmiOnAddInstance event in configuration script disallows the creation of the new Instance then this method will return the error cmiErrScriptDisallowed.


Instances.Clear Method

Clear Method

The Clear method deletes all Instance objects from the collection. It fires the OnDeleteInstance event in configuration script once for each Instance deleted.

Syntax

    objInstances.Clear()

Notes

If the OnDeleteInstance event in configuration script disallows the deletion of an Instance then this method will return the error cmiErrScriptDisallowed.


Instances.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the collection.

Syntax

    objCMI = objInstances.CMI


Instances.Configuration Property

Configuration Property

The Configuration property returns the Configuration object that contains the Instances collection.

Syntax

    objConfiguration = objInstances.Configuration


Instances.Count Property

Count Property

The Count property returns the number of Instance objects currently in the collection.

Syntax

    nInstances = objInstances.Count


Instances.Item Property

Item Property

The Item property returns the specified Instance object from the collection. It is the default property and does not require an explicit reference by name.

Syntax

    objInstance = objInstances(Index, [ID])

    objInstance = objInstances.Item(Index, [ID])

    Index

      Either an integer containing the one-based ordinal position of the Instance object in the collection or a string containing the Component.VSGUID property of the Component on which the Instance is based.

    ID

      Optional. The value of Instance.InstanceID. If Index is an integer then this parameter is ignored. If Index is a GUID and this parameter is not passed, then it is assumed to be zero (i.e. the default ID for single-instance components).


Instances.Platform Property

Platform Property

The Platform property returns the Platform on which the configuration containing the Instances collection is based.

Syntax

    objPlatform = objInstances.Platform


Instances.Remove Method

Remove Method

The Remove method removes the specified Instance object from the collection. It fires the cmiOnDeleteInstance event in configuration script.

Syntax

    objInstances.Remove(Index)

    Index

      Either an integer containing the one-based ordinal position of the Instance object in the collection or a string containing the component's VSGUID.

    Notes

    If the OnDeleteInstance event in configuration script disallows the deletion of the Instance then this method will return the error cmiErrScriptDisallowed.


Instance

The Instance object represents an instance of a Component that has been added to a configuration.

Like a component, an Instance has collections of Resources, Dependencies, and Properties. These collections are typically populated by script code in the OnAddInstance event by merging the contents of the corresponding collections from each component in the prototype chain. The prototype chain is available in the Instance.ComponentChain property. Unlike a Component, these collections can all be altered by component script.

An Instance also has methods to configure it (Configure) and upgrade all the components in the prototype chain to a newer version (Upgrade).

The Instance object supports the IPersistStream interface for saving only. To load a previously saved Instance from a stream use the ILoadInstanceStream interface on the Instances collection.

NOTE: when using IPersistStream::Save on an Instance the application should generally not pass fClearDirty=TRUE as that will render the Instance not dirty and this could incorrectly cause Configuration.Dirty to return False.


Instance.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the Instance.

Syntax

    objCMI = objInstance.CMI


Instance.Comment Property

Comment Property

The Comment property is used to describe or othwerwise distinguish the Instance within the configuration. The default value is null. This property is typically set by script code in the OnAddInstance event. It is highly recommended this property be initialized before accessing Instance.Script so that the CMI can use it as the name of the script when logging script errors and in the script debugger.

Syntax

    nID = objInstance.Comment


Instance.ComponentChain Property

ComponentChain Property

The ComponentChain property returns an ordered Components collection that contains the prototype chain from which the Instance is derived. ComponentChain(1) is the Component that was added to the configuration to create the instance. ComponentChain(2) is the prototype of that component and so on up to the default prototype component.

Syntax

    objComponentChain = objInstance.ComponentChain

Notes

This collection is read-only and cannot be used to delete component objects from the database.

If this property is accessed repeatedly it always returns the same instance of the collection.


Instance.Configuration Property

Configuration Property

The Configuration property returns the Configuration object that contains the Instance.

Syntax

    objConfiguration = objInstance.Configuration


Instance.Configure Method

Configure Method

The Configure method method fires the OnConfigureInstance event in configuration script.

Syntax

    objInstance.Configure()


Instance.Dependencies Property

Dependencies Property

The Dependencies property returns the collection of Dependency objects that represents the set of dependencies for the Instance. Component script may alter this collection.

Syntax

    objDependencies = objInstance.Dependencies

Notes

If this property is accessed repeatedly it always returns the same instance of the collection.


Instance.Editable Property

Editable Property

The Editable property returns a boolean value indicating whether the Instance is configurable by the user. The default value is False. This property is typically set by script code in the OnAddInstance event by examining the values of each component Instance.ComponentChain.

Syntax

    fEditable = objInstance.Editable


Instance.Index Property

Index Property

The Index property returns an integer containing the ordinal position of the Instance object in the Instances collection.

Syntax

    nIndex = objInstance.Index

Notes

Index represents only the ordinal position in the collection.


Instance.InstanceID Property

InstanceID Property

The InstanceID property is a zero-based index that is used to indicate the order in which multiple instances of a component have been added to a configuration. For single-instance components InstanceID is always zero.

Syntax

    nID = objInstance.InstanceID


Instance.IsBaseComponent Property

IsBaseComponent Property

The IsBaseComponent property returns a boolean value indicating whether the Instance represents the component referenced by Platform.BaseComponentVIGUID. The default value is False. This property is typically set by script code in the OnAddInstance event.

Syntax

    fIsBaseComponent = objInstance.IsBaseComponent


Instance.IsMacro Property

IsMacro Property

The IsMacro property returns a boolean value indicating whether the Instance is based on a macro component. A macro component has no resources and derives from the default prototype component specified by Platform.DefaultProtoVIGUID. This property is typically set by script code in the OnAddInstance event by examining the properties of each component in Instance.ComponentChain.

Syntax

    fIsMacro = objInstance.IsMacro


Instance.MultiInstance Property

MultiInstance Property

The MultiInstance property returns a boolean value indicating whether the Instance can be instantiated multiple times within the same configuration. The default value is False. This property is typically set by script code in the OnAddInstance event by examining the values of each component Instance.ComponentChain.

Syntax

    fMultiInstance = objInstance.MultiInstance


Instance.Platform Property

Platform Property

The Platform property returns the Platform on which the configuration containing the instance is based.

Syntax

    objPlatform = objInstance.Platform


Instance.Properties Property

Properties Property

The Properties property returns the collection of ExtProperty objects that represents the set of extended properties for the Instance. Configuration and component script may alter this collection.

Syntax

    objProperties = objInstance.Properties

Notes

If this property is accessed repeatedly it always returns the same instance of the collection.


Instance.Resources Property

Resources Property

The Resources property returns the collection of Resource objects that represents the set of resources that will be processed for the Instance when building the target system. Configuation and component script may alter this collection.

Syntax

    objResources = objInstance.Resources


Instance.Script Property

Script Property

The Script property returns an object that represents the combined loaded and running script code of all the components in Instance.ComponentChain. The object exposes the public functions of the script code. The script engine is loaded when a new Instance is created or when an existing configuration containing the Instance is opened. For more information see Scripting.

Syntax

    objScript = objInstance.Script


Instance.Upgrade Method

Upgrade Method

The Upgrade method creates a new Instance object and builds a new ComponentChain for it using the revised component. It also creates a new scripting context for each of the components in the revised prototype chain. When the new Instance has been completely initialized then this method fires the the OnUpgradeInstance event in configuration script.

Syntax

    objInstance.Upgrade(RevisedComponent)

    RevisedComponent

      A Component object that will become the new component on which the Instance is based.


Instance.Visibility Property

Visibility Property

The Visibility property returns an integer value that controls the visibility of the instance to the UI tools. This property defines a visibility "level" that defaults to 1000. Instances may be filtered based upon their visibility level, with only those instances that have a visibility greater than a specified threshold displayed. Instances that should never be displayed to the user should have a visibility of 0. Instances that should always be visible should have a visibility of 32767. This property is typically set by script code in the OnAddInstance event by examining the values of each component Instance.ComponentChain.

Syntax

    fVisibility = objInstance.Visibility


Platforms

The Platforms collection represents the platform objects in the component database. It is accessed from the CMI.GetPlatforms property. Platform objects can be referenced using an ordinal index or by VSGUID.

Count returns the number of Platform objects in the collection.

Remove removes a Platform object from the collection and also deletes it from the database.

Clear removes all Platform objects from the collection and also deletes them from the database.

CMI returns the top-level CMI object that contains the collection.


Platforms.Clear Method

Clear Method

The Clear method removes all Platform objects from the collection and also deletes them from the database. It also deletes all objects that are dependent on the platforms. These are:

    • repositories and their group membership
    • groups
    • components and their resources, dependencies, and group memership
    • resource types and their property types

If the platform and any of its dependent objects have extended properties then they are also deleted from the database.

WARNING: THIS METHOD COMPLETELY DELETES THE ENTIRE CONTENTS OF THE DATABASE.

As a safety measure, it cannot be called unless the application first sets CMI.AllowPlatformDeletes to True.

Syntax

    objPlatforms.Clear()


Platforms.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the collection.

Syntax

    objCMI = objPlatforms.CMI


Platforms.Count Property

Count Property

The Count property returns the number of Platform objects currently in the collection.

Syntax

    nPlatforms = objPlatforms.Count

Notes

The count does not necessarily reflect the number of platform objects in the component database. It represents the number of objects retrieved from the database during the last call to CMI.GetPlatforms.


Platforms.Item Property

Item Property

The Item property returns the specified Platform object from the collection. It is the default property and does not require an explicit reference by name.

Syntax

    objPlatform = objPlatforms(Index)

    objPlatform = objPlatforms.Item(Index)

    Index

      Either an integer containing the one-based ordinal position of the Platform object in the collection or a string containing the value of the object's VSGUID property.


Platforms.Remove Method

Remove Method

The Remove method removes the specified Platform object from the collection and also deletes it from the database. It also deletes all objects that are dependent on the platform. These are:

    • repositories and their group membership
    • groups
    • components and their resources, dependencies, and group memership
    • resource types and their property types

If the platform and any of its dependent objects have extended properties then they are also deleted from the database.

This method completely deletes a platform and all of its contents from the database. As a safety measure, it cannot be called unless the application first sets CMI.AllowPlatformDeletes to True.

Syntax

    objPlatforms.Remove(Index)

    Index

      Either an integer containing the one-based ordinal position of the Platform object in the collection or a string containing the value of the object's VSGUID property.

    Notes

    If another platform is in the database that has the same VIGUID as the platform being deleted, then only dependent objects that specified that the platform's VSGUID when they were imported will be deleted.


Platform

A platform defines the type of target run-time being constructed. All of the information in the component database belongs to one (and only one) platform. In addition, each configuration is bound to a specific platform when it is created. In effect, each platform represents a virtual, independent component database that exists independently of other platforms within the same physical database. Platforms are used to define the target operating system, CPU, locale and other variants that are handled at the global database level. For example, one platform might be "Windows 2000 Embedded (x86) - US English".


Platform.Authors Property

Authors Property

The Authors property returns a string containing semi-colon separated list of email addresses of the authors of the platform.

Syntax

    strAuthors = objPlatform.Authors

Notes

This property is optional and may be null.


Platform.BaseComponentVIGUID Property

BaseComponentVIGUID Property

The BaseComponentVIGUID property returns a string containing the version-independent GUID that identifies the base Component that is typically included in configurations based upon the platform.

Syntax

    strBaseComponentVIGUID = objPlatform.BaseComponentVIGUID

Notes

Inclusion of the base Component is a decision made by the configuration script when a configuration is created. The base Component can be used to guarantee the inclusion of platform-specific resources within all configurations based upon the platform.


Platform.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the platform.

Syntax

    objCMI = objPlatform.CMI


Platform.Copyright Property

Copyright Property

The Copyright property returns a string containing the copyright text for the platform.

Syntax

    strCopyright = objPlatform.Copyright

Notes

This property is optional and may be null.


Platform.DateCreated Property

DateCreated Property

The DateCreated property returns the date and time the platform was created in UTC.

Syntax

    DateCreated = objPlatform.DateCreated

Notes

This property is optional and may be null.


Platform.DateImported Property

DateImported Property

The DateImported property returns the date and time the platform definition was imported into the component database (in UTC).

Syntax

    DateImported = objPlatform.DateImported


Platform.DateRevised Property

DateRevised Property

The DateRevised property returns the date and time the platform was last revised in UTC.

Syntax

    DateRevised = objPlatform.DateRevised

Notes

This property is optional and may be null.


Platform.DefaultProtoVIGUID Property

DefaultProtoVIGUID Property

The DefaultProtoVIGUID property returns a string containing the version-independent GUID that identifies the default component to use for the prototype for components that do not explicitly define a prototype component.

Syntax

    strDefaultProtoVIGUID = objPlatform.DefaultProtoVIGUID


Platform.Description Property

Description Property

The Description property returns a string containing the description of the platform.

Syntax

    strDescription = objPlatform.Description

Notes

This property is optional and may be null.


Platform.DisplayName Property

DisplayName Property

The DisplayName property returns a string containing the display name of the platform.

Syntax

    strDisplayName = objPlatform.DisplayName

Notes

This property is optional and may be null.


Platform.GetComponent Method

GetComponent Method

The GetComponent method returns a Component object in the database that belongs to the platform identified by VIGUID or by VSGUID.

Syntax

    objGetComponent = objPlatform.GetComponent(VXGUID)

VXGUID

    A string containing either the version-independent GUID (VIGUID) or the version-specific GUID (VSGUID) of the component to retrieve.

Notes

This method always returns a new instance of the Component object.

If VIGUID is specified and there are multiple revisions of the Component in the database, then the latest revision is returned. To get a specific revision of a Component use Platform.GetComponents with a Filter object.


Platform.GetComponents Method

GetComponents Method

The GetComponents method returns a collection of Component objects in the database that belong to the platform. A component is considered to belong to a platform if it was imported with a PlatformGUID attribute that matches Platform.VIGUID or Platform.VSGUID.

The collection can optionally be filtered to return only a subset of the platform's components by passing a Filter object to this method.

Syntax

    objGetComponents = objPlatform.GetComponents([Filter])

    Filter

      Optional. A Filter object that restricts the collection to a specified subset of the components that belong to the platform. Note that the Filter object does not allow filtering on Component.Visibility. In order to control the minimum visibility required for a component to be returned by this method (with or without filtering) set Platform.MinVisibility

    Notes

    This method always returns a new instance of the collection.

    If there are multiple revisions of a Component in the database then all of the revisions will be returned in this collection if it is not filtered.


Platform.GetGroup Method

GetGroup Method

The GetGroup method returns a Group object from the database that belongs to the platform identified by VSGUID.

Syntax

    objGroup = objPlatform.GetGroup(VSGUID)

VSGUID

    A string containing the version-specific GUID (VSGUID) of the group to retrieve.

Notes

This method always returns a new instance of the Group object.


Platform.GetGroups Method

GetGroups Method

The GetGroups method returns a collection of Group objects from the database that belong to the platform. A group is considered to belong to a platform if it was imported with a PlatformGUID attribute that matches Platform.VIGUID or Platform.VSGUID.

Syntax

    objGroups = objPlatform.GetGroups

Notes

This method always returns a new instance of the collection.


Platform.GetRepository Method

GetRepository Method

The GetRepository method returns a Repository object from the database that belongs to the platform identified by VSGUID.

Syntax

    objRepository = objPlatform.GetRepository(VSGUID)

VSGUID

    A string containing the version-specific GUID (VSGUID) of the repository to retrieve.

Notes

This method always returns a new instance of the Repository object.


Platform.GetRepositories Method

GetRepositories Method

The GetRepositories method returns a collection of Repository objects from the database that belong to the platform. A repository is considered to belong to a platform if it was imported with a PlatformGUID attribute that matches Platform.VIGUID or Platform.VSGUID.

Syntax

    objRepositories = objPlatform.GetRepositories

Notes

This method always returns a new instance of the collection.


Platform.GetResourceTypes Method

GetResourceTypes Method

The GetResourceTypes property returns a collection of ResourceType objects from the database that belong to the platform. A resource type is considered to belong to a platform if it was imported with a PlatformGUID attribute that matches Platform.VIGUID or Platform.VSGUID.

Syntax

    objResourceTypes = objPlatform.GetResourceTypes

Notes

This method always returns a new instance of the collection.


Platform.Index Property

Index Property

The Index property returns an integer containing the ordinal position of the Platform object in the Platforms collection.

Syntax

    nIndex = objPlatform.Index

Notes

Index represents only the ordinal position in the collection. It does not necessarily represent the ordinal position in the database.


Platform.LCID Property

LCID Property

The LCID property returns an integer containing the platform locale. This is the locale ID of the platform, and by extension of all the components and files within the platform.

Syntax

    strLCID = objPlatform.LCID


Platform.MinVisibility Property

MinVisibility Property

The MinVisibility property returns an integer that determines the minimum value needed for Component.Visibility in order for a Component object to be returned from the GetComponents method.

Syntax

    nMinVisibility = objPlatform.MinVisibility

Notes

This value of MinVisibility defaults to 1000. This property is read/write and is not based on a value from the database.


Platform.NewConfiguration Method

NewConfiguration Method

The NewConfiguration method creates and returns a new Configuration object based on the platform. It fires the OnNewConfig event in configuration script.

Syntax

    objConfiguration = objPlatform.NewConfiguration()

Notes

The Configuration.Close method must be called when the application has finished using the Configuration object.

The application can open multiple configurations simultaneously.


Platform.OpenConfiguration Method

OpenConfiguration Method

The OpenConfiguration method opens a configuration file (.SLX) and returns a Configuration object that can be used to access it. It fires the cmiOnOpenConfig event in configuration script.

Syntax

    objConfiguration = objPlatform.OpenConfiguration(Path)

    Path

      A string containing the fully qualified path to the .SLX file. When this method completes Configuration.Path will be set to this value.

    Notes

    If the configuration is not based on the platform an error is returned. The CMI also checks that all the component GUIDs specified within the .SLX file are present in the component database and belong to the same platform as the configuration.

    The Configuration.Close method must be called when the application has finished using the Configuration object.

    The application can open multiple configurations simultaneously.


Platform.Owners Property

Owners Property

The Owners property returns a string containing a semi-colon separated list of email addresses of the owners of the platform.

Syntax

    strOwners = objPlatform.Owners

Notes

This property is optional and may be null.


Platform.Properties Property

Properties Property

The Properties property returns a collection of ExtProperty objects from the database that belong to the platform.

Syntax

    objProperties = objPlatform.Properties

Notes

This property always returns the same instance of the collection.


Platform.Revision Property

Revision Property

The Revision property returns an integer containing the revision ordinal of the platform. The revision is a simple ordinal value where a higher value represents a later version of an object. Revisions need not be sequential, but any changes that are made to an object must be accompanied by an increase in the value of the revision.

Syntax

    nRevision = objPlatform.Revision


Platform.ScriptEncoded Property

ScriptEncoded Property

The ScriptEncoded property returns a boolean value that indicates whether the script code returned by the ScriptText property is encrypted. Encrypted script code cannot be debugged by setting CMI.DebugScript or CMI.DebugOnScriptError.

Syntax

    fScriptEncoded = objPlatform.ScriptEncoded

Notes

This property is optional and may be null.


Platform.ScriptLanguage Property

ScriptLanguage Property

The ScriptLanguage property returns a string containing the language of the script code specified by Platform.ScriptText.

Syntax

    strScriptLanguage = objPlatform.ScriptLanguage

Notes

This property is optional and may be null.


Platform.ScriptText Property

ScriptText Property

The ScriptText property returns a string containing the script code used for configurations based on the Platform. When a configuration is created, the object returned by Configuration.Script is based on the script code specified by this property.

Syntax

    strScriptText = objPlatform.ScriptText

Notes

This property is optional and may be null.


Platform.Vendor Property

Vendor Property

The Vendor property returns a string containing the vendor that created the platform.

Syntax

    strVendor = objPlatform.Vendor

Notes

This property is optional and may be null.


Platform.Version Property

Version Property

The Version property returns a string containing the version of the platform. The version string contains arbitrary text. It is never used to compare versions. The Revision property is used for this purpose.

Syntax

    strVersion = objPlatform.Version

Notes

This property is optional and may be null.


Platform.VIGUID Property

VIGUID Property

The VIGUID property returns a string containing the version-independent GUID that uniquely identifies the platform.

Syntax

    strVIGUID = objPlatform.VIGUID

Notes

The VIGUID property does not identify a specific revision of the platform. That is specified by the VSGUID property.


Platform.VSGUID Property

VSGUID Property

The VSGUID property returns a string containing the version-specific GUID that uniquely identifies a specific revision of the platform.

Syntax

    strVSGUID = objPlatform.VSGUID


PropertyTypes

The PropertyTypes collection represents the property types defined for a ResourceType in the component database. It is accessed using the ResourceType.GetPropertyTypes method. PropertyType objects can be referenced using an ordinal index or by Name.

Count returns the number of PropertyType objects in the collection.

Remove removes a PropertyType object from the collection and also deletes it from the database.

Clear removes all PropertyType objects from the collection and also deletes them from the database.

CMI returns the top-level CMI object that contains the collection.


PropertyTypes.Clear Method

Clear Method

The Clear method removes all PropertyType objects from the collection and also deletes them from the database.

Syntax

    objPropertyTypes.Clear()


PropertyTypes.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the collection.

Syntax

    objCMI = objPropertyTypes.CMI


PropertyTypes.Count Property

Count Property

The Count property returns the number of PropertyType objects currently in the collection.

Syntax

    nPropertyTypes = objPropertyTypes.Count

Notes

The count does not necessarily reflect the number of PropertyType objects in the component database. It represents the number of objects retrieved from the database during the last call to ResourceType.GetPropertyTypes.


PropertyTypes.Item Property

Item Property

The Item property returns the specified PropertyType object from the collection. It is the default property and does not require an explicit reference by name.

Syntax

    objPropertyType = objPropertyTypes(Index)

    objPropertyType = objPropertyTypes.Item(Index)

    Index

      Either an integer containing the one-based ordinal position of the PropertyType object in the collection or a string containing the value of the object's Name property.


PropertyTypes.ResourceType Property

ResourceType Property

The ResourceType property returns the ResourceType object that contains the collection.

Syntax

    objResourceType = objPropertyTypes.ResourceType


PropertyType

The PropertyType object defines the type information for a property used by a ResourceType. It is always contained in a PropertyTypes collection that is accessible by calling ResourceType.GetPropertyTypes.

Name specifies the name of the property. The name must be unique among the property types for a resource type.

Format specifies the format of data contained in the property's value (if any).

DefaultValue contains the data that is used for the property's value when a resource is imported that does not specify the property.

ResourceType returns the ResourceType object that defines the property type.


PropertyType.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the PropertyType.

Syntax

    objCMI = objPropertyType.CMI


DefaultValue.DefaultValue Property

DefaultValue Property

DefaultValue contains the data that is used for the property's value when a resource is imported that does not specify the property. For the format of the data see Format.

Syntax

    DefaultValue = objPropertyType.DefaultValue


PropertyType.Format Property

Format Property

An enumerated value that determines specifies the format of data contained in ExtProperty.Value (if any). This serves as an indicator to the consumer of the data as to how it should be interpreted.

Syntax

    eFormat = objPropertyType.Format

    For the possible values of eFormat see ExtProperty.Format.


PropertyType.Index Property

Index Property

The Index property returns an integer containing the ordinal position of the PropertyType object in the PropertyTypes collection.

Syntax

    nIndex = objPropertyType.Index

Notes

Index represents only the ordinal position in the collection. It does not necessarily represent the ordinal position in the database.


PropertyType.Name Property

Name Property

The Name property returns a string containing the name of the property. The name must be unique within the PropertyTypes collection for a ResourceType.

Syntax

    strName = objPropertyType.Name


PropertyType.ResourceType Property

ResourceType Property

The ResourceType property returns the ResourceType object that contains the PropertyType.

Syntax

    objResourceType = objPropertyType.ResourceType


Resources

The Resources collection can represent resources defined by a component in the component database (Component.GetResources), in a Configuration (Configuration.Resources), or in an Instance (Instance.Resources) within a configuration.

The application must call Component.GetResources to get the collection for a component. Configuration.Resources and Instance.Resources are not populated automatically by the CMI. Resource objects in the collection can be referenced using an ordinal index.

The Add method can be used to add a Resource object to the collection in a configuration or in a component instance.

Count returns the number of Resource objects in the collection.

Remove removes a Resource object from the collection and for a Component also deletes it from the database.

Clear removes all Resource objects from the collection and for a Component also deletes them from the database.

CMI returns the top-level CMI object that contains the collection.

Platform returns the Platform object that contains the collection.

Owner returns the object that owns the collection.

A Resources collection within a Configuration supports the ILoadResourceStream interface for the purpose of loading a previously saved Resource object. A Resource object can only be saved by using IPersistStream::Save on the Resource. It can only be loaded by using ILoadResourceStream on the Resources collection.


Resources.Add Method

Add Method

The Add method adds a new Resource object to the collection. This method can only be used in a Resources collection within a configuration (Configuration.Resources or Instance.Resources). It cannot be used to add resources to a component definition in the database. It fires the OnAddResource event in configuration script.

Syntax

    objNewResource = objResources.Add(Type, BuildTypeMask, Localize, Disabled, [DisplayName], [Description])

    Type

      A ResourceType object that specifies the type of the resource.

    BuildTypeMask

      A bit mask that determines whether a resource can be used in a build. See Resource.BuildTypeMask for more information.

    Localize

      Indicates whether the resource must be localized for different platforms.

    Disabled

      Indicates whether the resource is disabled.

    DisplayName

      Optional. Display name of the resource.

    Description

      Optional. A string containing a description of the resource.

Notes

If the OnAddResource event in configuration script disallows the creation of the new Resource then this method will return the error cmiErrScriptDisallowed.

When the new Resource object is created, Resource.Properties is populated with the properties defined by ResourceType.GetPropertyTypes.


Resources.Clear Method

Clear Method

The Clear method deletes all Resource objects from the collection. It can only be used for a Resources that belong to a Configuration or to an Instance. It cannot be used to delete component resources from the database. Component resources are only deleted when the owning components are deleted. This method fires the cmiOnDeleteResource event in configuration script for each resource that is deleted.

Syntax

    objResources.Clear()

Notes

If the OnDeleteResource event in configuration script disallows the deletion of a Resource then this method will return the error cmiErrScriptDisallowed.


Resources.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the collection.

Syntax

    objCMI = objResources.CMI


Resources.Count Property

Count Property

The Count property returns the number of Resource objects currently in the collection.

Syntax

    nResources = objResources.Count

Notes

For Component resources the count does not necessarily reflect the number of Resource objects in the component database. It represents the number of objects retrieved from the database during the last call to Component.GetResources.

For Configuration.Resources and Instance.Resources it always represents the total number of Resource objects owned by the configuration or instance.


Resources.Item Property

Item Property

The Item property returns the specified Resource object from the collection. It is the default property and does not require an explicit reference by name.

Syntax

    objResource = objResources(Index)

    objResource = objResources.Item(Index)

    Index

      An integer containing the one-based ordinal position of the Resource object in the collection.


Resources.Owner Property

Owner Property

The Owner property returns the object that owns the collection. This could be a Component, a Configuration, or an Instance.

Syntax

    objOwner = objResources.Owner

Notes

To determine the type of object returned by this property the caller can use CMI.QueryObjectType.


Resources.Platform Property

Platform Property

The Platform property returns the Platform object that contains the collection.

Syntax

    objPlatform = objResources.Platform


Resources.Remove Method

Remove Method

The Remove method deletes the specified Resource object from the collection. It can only be used for a Resource that belongs to a Configuration or to an Instance. It cannot be used to delete component resources from the database. Component resources are only deleted when the owning component is deleted. This method fires the cmiOnDeleteResource event in configuration script.

Syntax

    objResources.Remove(Index)

    Index

      An integer containing the one-based ordinal position of the Resource object in the collection.

    Notes

    If the OnDeleteResource event in configuration script disallows the deletion of the Resource then this method will return the error cmiErrScriptDisallowed.


Resource

Each component specifies a list of resources that are are processed during the build of the component. A resource might be a file, a registry key, a block of ROM, or any other resource type defined for the component. Resource types are defined by ResourceType objects.

Each resource is represented as a secondary Resource object that has a set of properties. Component script may also add Resource objects to a configuration outside the scope of any component using Configuration.Resources. Component script may also add Resource objects to a component instance withing a configuration by using Instance.Resources

The BuildTypeMask property determines the type of build that the resource can be used for (free, checked, etc).

The Type property specifies a ResourceType object that defines the type of the resource.

The Description and DisplayName properties are optional and supply a description and display name for use by configuration tools.

Properties returns a collection of ExtProperty objects that represent the properties of the resource. These properties may include both those defined by the ResourceType and extended properties that were part of the component definition when it was imported into the database. For Configuration.Resources and Instance.Resources, extended properties may be added by script code.

A Resource object within a Configuration supports the IPersistStream interface for saving only. To load a previously saved Resource from a stream use the ILoadResourceStream interface on the Resources collection.

NOTE: when using IPersistStream::Save on a Resource the application should generally not pass fClearDirty=TRUE as that will render the Resource not dirty and this could incorrectly cause Configuration.Dirty to return False.


Resource.BuildTypeMask Property

BuildTypeMask Property

The BuildTypeMask property returns an integer containing a bit mask that determines the type of builds that the resource can be used for (free, checked, etc). A typical configuration build process compares these bits to the value of Configuration.BuildType in order to determine whether the resource can be used.

Syntax

    nBuildTypeMask = objResource.BuildTypeMask


Resource.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the Resource.

Syntax

    objCMI = objResource.CMI


Resource.Description Property

Description Property

The Description property returns a string containing the description of the Resource.

Syntax

    strDescription = objResource.Description

Notes

This property is optional. If a Resource is imported with an empty or missing DESCRIPTION element then it will contain an empty string (""). If a Resource is added to a dynamic collection and the Description parameter to Resources.Add is not specified, then this property will be null.


Resource.Disabled Property

Disabled Property

The Disabled property returns a boolean value indicating whether the Resource is disabled. A disabled Resource is not used as part of the runtime image when its owning component is added to a Configuration. The value of this property can be changed when a Resource is within a Configuration.

Syntax

    fDisabled = objResource.Disabled


Resource.DisplayName Property

DisplayName Property

The DisplayName property returns a string containing the display name of the Resource.

Syntax

    strDisplayName = objResource.DisplayName

Notes

This property is optional. If a Resource is imported with an empty or missing DISPLAYNAME element then it will contain an empty string (""). If a Resource is added to a dynamic collection and the DisplayName parameter to Resources.Add is not specified, then this property will be null.


Resource.Index Property

Index Property

The Index property returns an integer containing the ordinal position of the Resource object in the Resources collection.

Syntax

    nIndex = objResource.Index

Notes

Index represents only the ordinal position in the collection. It does not necessarily represent the ordinal position in the database if the collection was filtered.


Resource.Localize Property

Localize Property

The Localize property returns a boolean value indicating whether the resource must be localized for each platform.

Syntax

    fLocalize = objResource.Localize


Name.Name Property

Name Property

The Name property returns a string containing the name of the resource. The name is retrieved by invoking the script event cmiGetName on the resource type script. If the resource type script does not exist or it does not implement cmiGetName then null is returned. For more information see Script Events.

Syntax

    strName = objResource.Name


Resource.Owner Property

Owner Property

The Owner property returns the object that owns the Resource. This could be a Component, a Configuration, or an Instance.

Syntax

    objOwner = objResource.Owner

Notes

To determine the type of object returned by this property the caller can use CMI.QueryObjectType.


Resource.Platform Property

Platform Property

The Platform property returns the Platform object that contains the Resource.

Syntax

    objPlatform = objResource.Platform


Resource.Properties Property

Properties Property

The Properties property returns a collection of ExtProperty objects that represent the properties of the Resource. These properties may include both those defined by the ResourceType and extended properties that were part of the resource definition when it was imported into the database. For Configuration.Resources and Instance.Resources, extended properties may be added by script code.

Syntax

    objExtProperties = objResource.Properties()

Notes

This property always returns the same instance of the collection.

When the new Resource object is created, Resource.Properties is populated with the properties defined by ResourceType.GetPropertyTypes.


Resource.Type Property

Type Property

The Type property returns a ResourceType object that defines the type of the resource. The type determines the set of properties for the resource.

Syntax

    objResourceType = objResource.Type


ResourceTypes

The ResourceTypes collection represents the ResourceType objects in the component database for a particular platform. It is accessed by calling Platform.GetResourceTypes. ResourceType objects can be referenced using an ordinal index or by VSGUID.

Count returns the number of ResourceType objects in the collection.

Remove removes a ResourceType object from the collection and also deletes it from the database.

Clear removes all ResourceType objects from the collection and also deletes them from the database.

CMI returns the top-level CMI object that contains the collection.


ResourceTypes.Clear Method

Clear Method

The Clear method removes all ResourceType objects from the collection and also deletes them from the database. It also deletes all of the associated property types from the database.

Syntax

    objResourceTypes.Clear()


ResourceTypes.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the collection.

Syntax

    objCMI = objResourceTypes.CMI


ResourceTypes.Count Property

Count Property

The Count property returns the number of ResourceType objects currently in the collection.

Syntax

    nResourceTypes = objResourceTypes.Count

Notes

The count does not necessarily reflect the number of ResourceType objects in the component database. It represents the number of objects retrieved from the database during the last call to Platform.GetResourceTypes.


ResourceTypes.Item Property

Item Property

The Item property returns the specified ResourceType object from the collection. It is the default property and does not require an explicit reference by name.

Syntax

    objResourceType = objResourceTypes(Index)

    objResourceType = objResourceTypes.Item(Index)

    Index

      Either an integer containing the one-based ordinal position of the ResourceType object in the collection or a string containing the value of the object's VSGUID property.


ResourceTypes.Remove Method

Remove Method

The Remove method removes the specified ResourceType object from the collection and also deletes it from the database. It also deletes all of the associated property types from the database.

Syntax

    objResourceTypes.Remove(Index)

    Index

      Either an integer containing the one-based ordinal position of the ResourceType object in the collection or a string containing the value of the object's VSGUID property.


ResourceType

All Resource objects are instances of a particular resource type. The ResourceType object defines a resource type.

The Name property is a friendly name for the resource type that can be displayed to the user.

The VSGUID property is a version-specific GUID that uniquely identifies a resource type.

The Revision property is an ordinal that identifies the particular revision of the resource type.

The GetPropertyTypes method returns a collection of PropertyType objects that represent the property types defined for the resource type. Note that the resource's properties may also include extended properties that are not explicitly defined by the resource type.

The ScriptText property returns a string containing the script code for the resource type (if any). ScriptLanguage returns the language of the script code. Script returns the loaded and running script code.


ResourceType.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the ResourceType.

Syntax

    objCMI = objResourceType.CMI


ResourceType.Description Property

Description Property

The Description property returns a string containing the description of the ResourceType.

Syntax

    strDescription = objResourceType.Description

Notes

This property is optional and may be null.


ResourceType.DisplayName Property

DisplayName Property

The DisplayName property returns a string containing the display name of the ResourceType.

Syntax

    strDisplayName = objResourceType.DisplayName

Notes

This property is optional and may be null.


ResourceType.GetPropertyTypes Method

GetPropertyTypes Method

The GetPropertyTypes method returns a collection of PropertyType objects that represent the property types defined for the ResourceType.

Syntax

    objPropertyTypes = objResourceType.GetPropertyTypes()


ResourceType.Index Property

Index Property

The Index property returns an integer containing the ordinal position of the ResourceType object in the ResourceTypes collection.

Syntax

    nIndex = objResourceType.Index

Notes

Index represents only the ordinal position in the collection. It does not necessarily represent the ordinal position in the database if the collection was filtered.


Name.Name Property

Name Property

The Name property returns a string containing the name of the ResourceType.

Syntax

    strName = objResourceType.Name


ResourceType.PlatformGUID Property

PlatformGUID Property

The PlatformGUID property returns a string containing the either the version-independent GUID (VIGUID) or version-specific GUID (VSGUID) that identifies the platform to which the ResourceType belongs.

Syntax

    strPlatformGUID = objResourceType.PlatformGUID


ResourceType.Revision Property

Revision Property

The Revision property returns an integer containing the revision ordinal of the ResourceType. The revision is a simple ordinal value where a higher value represents a later revision of an object. Revisions need not be sequential, but any changes that are made to an object must be accompanied by an increase in the value of the revision.

Syntax

    nRevision = objResourceType.Revision


ResourceType.Script Property

Script Property

The Script property returns an object that represents the loaded and running script code of the ResourceType. The object exposes the public methods of the script code. ResourceType script code is specified by ResourceType.ScriptText. The script engine is loaded when this property is first accessed. For more information see Scripting.

Syntax

    objScript = objResourceType.Script

Notes

If the resource type does not define script then this property returns null.


ResourceType.ScriptEncoded Property

ScriptEncoded Property

The ScriptEncoded property returns a boolean value that indicates whether the script code returned by the ScriptText property is encrypted. Encrypted script code cannot be debugged by setting CMI.DebugScript or CMI.DebugOnScriptError.

Syntax

    fScriptEncoded = objResourceType.ScriptEncoded

Notes

This property will be null if ScriptText is null.


ResourceType.ScriptLanguage Property

ScriptLanguage Property

The ScriptLanguage property returns a string containing the language of the script code returned by the ScriptText property.

Syntax

    strScriptLanguage = objResourceType.ScriptLanguage

Notes

This property may be null only if ScriptText is null.


ResourceType.ScriptText Property

ScriptText Property

The ScriptText property returns a string containing the configuration script code used by the ResourceType. The language of the script code is specified by the ScriptLanguage property.

Syntax

    strScriptText = objResourceType.ScriptText

Notes

This property is optional and may be null. If it is not null then ScriptLanguage must also be set.


ResourceType.VSGUID Property

VSGUID Property

The VSGUID property returns a string containing the version-specific GUID that uniquely identifies a specific revision of the ResourceType.

Syntax

    strVSGUID = objResourceType.VSGUID


Repositories

The Repositories collection represents the Repository objects in the component database. It is accessed from the Platform.GetRepositories property. Repository objects can be referenced using an ordinal index or by VSGUID.

Count returns the number of Repository objects in the collection.

Remove removes a Repository object from the collection and also deletes it from the database.

Clear removes all Repository objects from the collection and also deletes them from the database.

CMI returns the top-level CMI object that contains the collection.

Platform returns the Platform object that contains the collection.


Repositories.Clear Method

Clear Method

The Clear method removes all Repository objects from the collection and also deletes them from the database. If the repositories have any extended properties then they are also deleted from the database.

Syntax

    objRepositories.Clear()


Repositories.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the collection.

Syntax

    objCMI = objRepositories.CMI


Repositories.Count Property

Count Property

The Count property returns the number of Repository objects currently in the collection.

Syntax

    nRepositories = objRepositories.Count

Notes

The count does not necessarily reflect the number of Repository objects in the component database. It represents the number of objects retrieved from the database during the last call to Platform.GetRepositories.


Repositories.Item Property

Item Property

The Item property returns the specified Repository object from the collection. It is the default property and does not require an explicit reference by name.

Syntax

    objRepository = objRepositories(Index)

    objRepository = objRepositories.Item(Index)

    Index

      Either an integer containing the one-based ordinal position of the Repository object in the collection or a string containing the value of the object's VSGUID property.


Repositories.Platform Property

Platform Property

The Platform property returns the Platform object that contains the collection.

Syntax

    objPlatform = objRepositories.Platform


Repositories.Remove Method

Remove Method

The Remove method removes the specified Repository object from the collection and also deletes it from the database. If the repository has any extended properties then they are also deleted from the database.

Syntax

    objRepositories.Remove(Index)

    Index

      Either an integer containing the one-based ordinal position of the Repository object in the collection or a string containing the value of the object's VSGUID property.


Repository

A repository is an archive that is used as a source of binary files during the construction of the run-time image. All the files that comprise the run-time, with the exception of the registry hives and any other files constructed on the fly, originate in one or more repositories.

Each repository is comprised of a single folder that contains the repository files. Note that each repository is a single folder, not a complete folder tree.

Repositories also play a special role in the selection of "free" and "checked" (debug) builds of the run-time image. Each repository is marked as either a "free" repository or a "checked" repository. When a configuration is built either the free or checked build can be constructed, and the appropriate files are automatically selected from the correct repository.

Repositories may be deleted from the component database.


Repository.Authors Property

Authors Property

The Authors property returns a string containing semi-colon separated list of email addresses of the authors of the Repository.

Syntax

    strAuthors = objRepository.Authors

Notes

This property is optional and may be null.


Repository.BuildType Property

BuildType Property

The BuildType property returns an integer that determines the type of build that the repository can be used for (free, checked, etc). A typical configuration build process compares this property to the value of Configuration.BuildType in order to determine whether the repository can be used.

Syntax

    nBuildType = objRepository.BuildType


Repository.CMI Property

CMI Property

The CMI property returns the top-level CMI object that contains the Repository.

Syntax

    objCMI = objRepository.CMI


Repository.Copyright Property

Copyright Property

The Copyright property returns a string containing the copyright text for the Repository.

Syntax

    strCopyright = objRepository.Copyright

Notes

This property is optional and may be null.


Repository.DateCreated Property

DateCreated Property

The DateCreated property returns the date and time the repository was created in UTC.

Syntax

    DateCreated = objRepository.DateCreated

Notes

This property is optional and may be null.


Repository.DateImported Property

DateImported Property

The DateImported property returns the date and time the repository definition was imported into the component database (in UTC).

Syntax

    DateImported = objRepository.DateImported


Repository.DateRevised Property

DateRevised Property

The DateRevised property returns the date and time the repository was last revised in UTC.

Syntax

    DateRevised = objRepository.DateRevised

Notes

This property is optional and may be null.


Repository.Description Property

Description Property

The Description property returns a string containing the description of the Repository.

Syntax

    strDescription = objRepository.Description

Notes

This property is optional and may be null.


Repository.DisplayName Property

DisplayName Property

The DisplayName property returns a string containing the display name of the Repository.

Syntax

    strDisplayName = objRepository.DisplayName

Notes

This property is optional and may be null.


Respository.GetGroups Method

GetGroups Method

The GetGroups method returns a collection of Group objects from the database that represent the set of groups to which the Respository belongs.

Syntax

    objGroups = objRespository.GetGroups

Notes

This method always returns a new instance of the collection.


Repository.GroupVSGUIDs Method

GroupVSGUIDs Property

The GroupVSGUIDs property returns an array of GUIDs that specifies the groups to which the repository belongs. This array does not necessarily correspond to the Groups collection returned by the Repository.GetGroups method as some of the repository's groups may not yet have been imported into the database.

Syntax

    objGroups = objRepository.GroupVSGUIDs


Repository.Index Property

Index Property

The Index property returns an integer containing the ordinal position of the Repository object in the Repositories collection.

Syntax

    nIndex = objRepository.Index

Notes

Index represents only the ordinal position in the collection. It does not necessarily represent the ordinal position in the database.


Repository.Owners Property

Owners Property

The Owners property returns a string containing a semi-colon separated list of email addresses of the owners of the Repository.

Syntax

    strOwners = objRepository.Owners

Notes

This property is optional and may be null.


Repository.Platform Property

Platform Property

The Platform property returns the Platform object that contains the repository.

Syntax

    objPlatform = objRepository.Platform


Repository.PlatformGUID Property

PlatformGUID Property

The PlatformGUID property returns a string containing the either the version-independent GUID (VIGUID) or version-specific GUID (VSGUID) that identifies the platform to which the repository belongs.

Syntax

    strPlatformGUID = objRepository.PlatformGUID


Repository.Properties Property

Properties Property

The Properties property returns a collection of ExtProperty objects from the database that belong to the Repository.

Syntax

    objProperties = objRepository.Properties

Notes

This property always returns the same instance of the collection.


Repository.Rebase Method

Rebase Method

The Rebase method changes the value of Repository.SrcPath in the database.

Syntax

    objRepository.Rebase(NewSrcPath)

    NewSrcPath

      A string containing the new fully qualified path for Repository.SrcPath

Notes

This method does not copy the repository files from the old location to the new one. It is the application's responsibility to copy the files.


Repository.Revision Property

Revision Property

The Revision property returns an integer containing the revision ordinal of the Repository. The revision is a simple ordinal value where a higher value represents a later version of an object. Revisions need not be sequential, but any changes that are made to an object must be accompanied by an increase in the value of the revision.

Syntax

    nRevision = objRepository.Revision


Repository.SrcPath Property

SrcPath Property

The SrcPath property returns a string containing the fully-qualified path of the folder containing the repository's source files.

Syntax

    strSrcPath = objRepository.SrcPath


Repository.Vendor Property

Vendor Property

The Vendor property returns a string containing the vendor that created the Repository.

Syntax

    strVendor = objRepository.Vendor

Notes

This property is optional and may be null.


Repository.Version Property

Version Property

The Version property returns a string containing the version of the Repository. The version string contains arbitrary text. It is never used to compare versions. The Revision property is used for this purpose.

Syntax

    strVersion = objRepository.Version

Notes

This property is optional and may be null.


Repository.VSGUID Property

VSGUID Property

The VSGUID property returns a string containing the version-specific GUID that uniquely identifies a specific revision of the Repository.

Syntax

    strVSGUID = objRepository.VSGUID


Rule

The Rule object is used as a property of the Filter object to determine how the filter restricts the contents of the collection. A rule consists of an operator, a qualifier, and one or more arguments.

The Operator contains an enumerated value that determines the type of comparison made between the rule's arguments (e.g. equals, not equals, etc).

The Qualifier contains an enumerated value that determines how arguments containing CMI object property names are interpreted e.g. component property, resource property, resource extended property, etc.

The Arguments contain one or more values that are needed by the combination of Operator and Qualifier in order to implement the rule. For example, when filtering for components from Microsoft, the Operator would be cmiEquals, the Qualifier would be cmiComponentProperty, and the arguments would be "Vendor", "Microsoft".


Rule.Arguments Property

Arguments Property

Arguments contains one or more values that are needed by the combination of Operator and Qualifier in order to implement the rule. For example, when filtering for components from Microsoft, the Operator would be cmiEquals, the Qualifier would be cmiComponentProperty, and the arguments would be "Vendor", "Microsoft". See Operator for complete information on the arguments needed for each combination of Operator and Qualifier.

Syntax

    Arguments = objRule.Arguments

Notes

Arguments containing property values must be of the same data type as the property. The following are some hints for ensuring correct data types in various languages.

  • When passing integer, boolean or date property values in scripting languages, make sure that the argument is of the correct data type (i.e. not a string). For integers, the parameter should contain a number. For booleans it should contain true or false. For literal dates in VBScript use the CDate function. For literal dates in JScript use Date.getVarDate().
  • When passing a GUID property value, use the GUID as a string in registry format e.g. "{00000000-0000-0000-0000-000000000000}".
  • For binary and object properties pass a binary array. When passing a binary array in scripting languages, make sure that all array elements are numbers (i.e. not strings). To check for an null binary or object property pass a zero length array. In VBScript use Dim EmptyBinary : EmptyBinary = Array(). In Visual Basic use Dim EmptyBinary() As Byte. In JScript use var EmptyBinary = new Array().
  • When passing a multi-string property value, use a single string or an array of strings. To check for an empty mutli-string property, use "".
  • When passing an array in Visual Basic use an array of Variant rather than the explicit data type.
  • When passing an array in C++ use a VARIANT of type VT_ARRAY | VT_VARIANT. Each VARIANT in the SafeArray must be of the type needed for the particular argument.


Rule.Operator Property

Operator Property

The Operator> property returns an enumerated value that determines the type of comparison made between the rule's arguments (e.g. equals, not equals, etc).

Syntax

    eOperator = objRule.Operator

    Possible values for eOperator:

    eOperator Values

    Constant | Description
cmiEquals (1) | First argument contains property name. The property's value must be equal to the second argument. If Qualifier is cmiResourceProperty or cmiResourceExtendedProperty then third argument contains VSGUID of resource type.
cmiNotEquals (2) | First argument contains property name. The property's value must not be equal to the second argument. If Qualifier is cmiResourceProperty or cmiResourceExtendedProperty then third argument contains VSGUID of resource type.
cmiLessThan (3) | First argument contains property name. The property's value must be less than the second argument. If Qualifier is cmiResourceProperty or cmiResourceExtendedProperty then third argument contains VSGUID of resource type.
cmiGreaterThan (4) | First argument contains property name. The property's value must be greater than the second argument. If Qualifier is cmiResourceProperty or cmiResourceExtendedProperty then third argument contains VSGUID of resource type.
cmiLessThanEquals (5) | First argument contains property name. The property's value must be less than or equal to the second argument. If Qualifier is cmiResourceProperty or cmiResourceExtendedProperty then third argument contains VSGUID of resource type.
cmiGreaterThanEquals (6) | First argument contains property name. The property's value must be greater than or equal to the second argument. If Qualifier is cmiResourceProperty or cmiResourceExtendedProperty then third argument contains VSGUID of resource type.
cmiContains (7) | First argument contains property name. The property's value must contain the second argument. The property's value and the second argument must both be strings. If Qualifier is cmiResourceProperty or cmiResourceExtendedProperty then third argument contains VSGUID of resource type.
cmiMemberOf (8) | Components in the collection must be a member of the Group whose VSGUID is specified by the one and only argument. Qualifier is ignored.
cmiMemberNone (9) | Components in the collection must not be a member of any Group. There are no arguments. Qualifier is ignored.
cmiExists (10) | First argument contains the name of an extended property. The extended property must exist. Qualifier must be cmiComponentExtendedProperty or cmiResourceExtendedProperty. If Qualifier is cmiResourceExtendedProperty then second argument contains VSGUID of resource type.
cmiDependsOn (11) | Components in the collection must depend on the Group or Component whose VIGUID or VSGUID is specified by the one and only argument. Qualifier is ignored.
cmiLogicalAnd (12) | Arguments are one or more Rule objects whose conditions are logically ANDed. Qualifier is ignored.
cmiLogicalOr (13) | Arguments are one or more Rule objects whose conditions are logically ORed. Qualifier is ignored.
cmiMax (14) | The collection will only include components that have the maximum value in the field specified by the first argument. This operator can only be used when Qualifier is cmiComponentProperty. Permitted fields are Component.Revision, Component.DateImported, Component.DateCreated, and Component.DateRevised. Typical use of this operator is to create a collection that only has the latest revision of all components. Only one cmiMax or cmiMin operator is allowed in a Filter.
cmiMin (15) | The collection will only include components that have the minimum value in the field specified by the first argument. This operator can only be used when Qualifier is cmiComponentProperty. Permitted fields are Component.Revision, Component.DateImported, Component.DateCreated, and Component.DateRevised. Only one cmiMax or cmiMin operator is allowed in a Filter.

Notes

All comparisons involving strings are not case-sensitive.


Rule.Qualifier Property

Qualifier Property

The Qualifier contains an enumerated value that determines how arguments containing CMI object property names are interpreted e.g. component property, resource property, resource extended property, etc.

Syntax

    eQualifier = objRule.Qualifier

    Possible values for eQualifier:

    eQualifier Values

    Constant | Description
    cmiComponentProperty (1) First argument contains the name of an implicit component property e.g. "Vendor". Permitted properties are:

    • Authors
    • Copyright
    • DateCreated
    • DateImported
    • DateRevised
    • Description
    • DisplayName
    • Editable
    • HTMLFinal
    • HTMLTitle
    • IsMacro
    • MultiInstance
    • Owners
    • PlatformGUID
    • PrototypeVIGUID
    • Released
    • RepositoryVSGUID
    • Revision
    • ScriptLanguage
    • Vendor
    • Version
    • VIGUID
    • VSGUID
    cmiComponentExtendedProperty (2) | First argument contains the name of a component extended property e.g. "MyComponentProp".
    cmiResourceProperty (3) First argument contains the name of an implicit Resource property e.g. "Localize". Permitted properties are:

    • BuildTypeMask
    • Description
    • Disabled
    • DisplayName
    • Localize
    cmiResourceExtendedProperty (4) | First argument contains the name of a Resource extended property e.g. "MyResourceProp".

Notes

See Operator for complete information on the arguments needed for each combination of Operator and Qualifier.


Utilities

The Utilities object is a publicly creatable object that provides methods for file copying and registration database access.

The LoadHive, TargetRegWrite, TargetRegRead, and UnloadHive methods allow the application to read and write a temporary hive in the local system registry as if it were a hive on the target system.

The RelativeKey property allows the application to use HKR or HKEY_RELATIVE as an alias for a particular key in the target system registry.

The LocalRegWrite and LocalRegRead methods give access to the local registry.

There are also file management utility methods that allow copying, renaming, and expanding files as well as copying files in and out of cabinet (.CAB) files.


Utilities.AddToCAB Method

AddToCAB Method

The AddToCAB method adds a file to a cabinet (.CAB) file and optionally renames it in the .CAB file.

Syntax

    objUtilities.AddToCAB(SrcPath, SrcFile, DstPath, DstCAB, [DstFile])

    SrcPath

      The complete path to the folder containing the source file.

    SrcFile

      The name of the source file.

    DstPath

      The complete path to the folder containing the .CAB file.

    DstCAB

      The name of the .CAB file.

    DstFile

      Optional. The name of the file within the .CAB file. If omitted then SrcFile is used.

Notes

If the destination .CAB file does not exist it is created.


Utilities.CABToCAB Method

CABToCAB Method

The CABToCAB method copies a file from one cabinet (.CAB) file to another and optionally renames it in the destination .CAB file.

Syntax

    objUtilities.CABToCAB(SrcPath, SrcCAB, SrcFile, DstPath, DstCAB, [DstFile])

    SrcPath

      The complete path to the folder containing the source .CAB file.

    SrcCAB

      The name of the source .CAB file.

    SrcFile

      The name of the source file in the source .CAB file.

    DstPath

      The complete path to the folder containing the destination .CAB file.

    DstCAB

      The name of the destination .CAB file.

    DstFile

      Optional. The name of the file within the destination .CAB file. If omitted then SrcFile is used.

Notes

If the destination .CAB file does not exist it is created.


Utilities.CopyFile Method

CopyFile Method

The CopyFile method copies a file to a destination folder and optionally renames it in that folder.

Syntax

    objUtilities.CopyFile(SrcPath, SrcFile, DstPath, [DstFile])

    SrcPath

      The complete path to the folder containing the source file.

    ScrFile

      The name of the source file.

    DstPath

      The folder to which the file is to be copied.

    DstFile

      Optional. The name of the file in the destination folder. If omitted then SrcFile is used.


Utilities.ExpandFile Method

ExpandFile Method

The ExpandFile method expands a compressed file, copies it to a destination folder, and optionally renames it in that folder.

Syntax

    objUtilities.ExpandFile(SrcPath, SrcFile, DstPath, [DstFile])

    SrcPath

      The complete path to the folder containing the source file.

    ScrFile

      The name of the source file.

    DstPath

      The folder to which the file is to be copied.

    DstFile

      Optional. The name of the file in the destination folder. If omitted then SrcFile is used.

Notes

Compressed files must be compressed using the Microsoft File Compression utility COMPRESS.EXE.


Utilities.ExtractFromCAB Method

ExtractFromCAB Method

The ExtractFromCAB method extracts a source file from a cabinet (.CAB) file, copies it to a destination folder, and optionally renames it in that folder.

Syntax

    objUtilities.ExtractFromCAB(CABPath, CABFile, SrcFile, DstPath, [DstFile])

    CABPath

      The complete path to the folder containing the .CAB file.

    CABFile

      The name of the .CAB file.

    SrcFile

      The name of the source file within the .CAB file.

    DstPath

      The folder to which the file is to be copied.

    DstFile

      Optional. The name of the file in the destination folder. If omitted then SrcFile is used.


Utilities.HexStringToArray Method

HexStringToArray Method

The HexStringToArray method converts a string of hexadecimal digits to an array of VARIANTs in which each VARIANT contains an 8-bit unsigned integer (VT_UI1).

Syntax

    Array = objUtilities.HexStringToArray(HexString)

    HexString

      A string containing pairs of hexadecimal digits (e.g. "0102030ABBCD"). For digits A to F both upper and lower case can be used.


Utilities.LoadHive Method

LoadHive Method

The LoadHive method loads a hive file into the local machine registry and then allows the application to view it as a particular key on the target system. The application can then make calls to TargetRegWrite and TargetRegRead specifying key paths on the target system. When the application has completed all of its work on the hive it must call UnloadHive or UnloadAllHives to save the contents of the hive to its file.

Syntax

    objUtilities.LoadHive(TargetKey, HiveFile)

    TargetKey

      A string containing the name of the key on the target system (e.g. HKEY_LOCAL_MACHINE\Software).

    HiveFile

      A string containing the complete path of the file containing the hive. The subsequent call to UnloadHive or UnloadAllHives will save the contents to the same file.

Notes

This method can be called multiple times to load multiple simultaneous hives.

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead


Utilities.LocalRegGetType Method

LocalRegGetType Method

The LocalRegGetType method returns the data type of the specified value from the local registry.

Syntax

    Type = objUtilities.LocalRegGetType(KeyName, ValueName)

    KeyName

      A string containing the name of the key on the local system (e.g. HKEY_LOCAL_MACHINE\Software\SomeCompany\SomeKey).

    ValueName

      A string containing the name of the value to read. For the default value pass null or an empty string.

    Type

      An integer is returned here that indicates the data type of the value. Constants are defined for known types. The type also determines how the data is returned from the LocalRegRead and TargetRegRead methods.

    Type Values

    Constant | Description
    cmiREG_NONE (0) | The data type is not specified. This is the same as free-form binary data. Data is returned as an array of VARIANTs in which each VARIANT contains a VT_UI1 (8 bit unsigned integer).
    cmiREG_SZ (1) | String. Data is returned as a string.
    cmiREG_EXPAND_SZ (2) | String with environment variable references (e.g. %PATH%). Data is returned as a string.
    cmiREG_BINARY (3) | Free-form binary data. Data is returned as an array of VARIANTs in which each VARIANT contains a VT_UI1 (8 bit unsigned integer).
    cmiREG_DWORD (4) | Typically a 32 bit number but there are cases where this type is used for binary data. If the data is a 32 bit number then it is returned as a number (VT_I4). If it is any larger then it is returned as as an array of VARIANTs in which each VARIANT contains a VT_UI1 (8 bit unsigned integer).
    cmiREG_DWORD_LITTLE_ENDIAN (4) 32 bit number in little endian format. This is the same as cmiREG_DWORD. See above for data format.

    In little-endian format, a multibyte value is stored in memory from the lowest byte (the "little end") to the highest byte. For example, the value 0x12345678 is stored as (0x78 0x56 0x34 0x12) in little-endian format.

    The Windows operating systems are designed to run on little-endian computer architectures. A user may connect to computers that have big-endian architectures, such as some UNIX systems.

    cmiREG_DWORD_BIG_ENDIAN (5) | 32 bit number in big endian format. Data is returned as for cmiREG_DWORD (see above).
    cmiREG_LINK (6) | Symbolic link. Data is returned as a string.
    cmiREG_MULTI_SZ (7) | Multiple strings. Data is returned as an array of VARIANTs in which each VARIANT contains a string.
    cmiREG_RESOURCE_LIST (8) | Device driver resource list in the resource map. Data is returned as an array of VARIANTs in which each VARIANT contains a VT_UI1 (8 bit unsigned integer).
    cmiREG_FULL_RESOURCE_DESCRIPTOR (9) | Resource list in the hardware description. Data is returned as an array of VARIANTs in which each VARIANT contains a VT_UI1 (8 bit unsigned integer).
    cmiREG_RESOURCE_REQUIREMENTS_LIST (10) | Resource requirements list. Data is returned as an array of VARIANTs in which each VARIANT contains a VT_UI1 (8 bit unsigned integer).
    cmiREG_QWORD (11) | 64-bit number. Data is returned as an array of VARIANTs in which each VARIANT contains a VT_UI1 (8 bit unsigned integer).
    cmiREG_QWORD_LITTLE_ENDIAN (11) | 64-bit number in little endian format (same as cmiREG_QWORD). Data is returned as an array of VARIANTs in which each VARIANT contains a VT_UI1 (8 bit unsigned integer).
    Other Custom Types | Data is returned as an array of VARIANTs in which each VARIANT contains a VT_UI1 (8 bit unsigned integer).

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead


Utilities.LocalRegKeyCreate Method

LocalRegKeyCreate Method

The LocalRegKeyCreate creates the specified key in the local registry.

Syntax

    Data = objUtilities.LocalRegKeyCreate(KeyName)

    KeyName

      A string containing the name of the key to be creeated on the local system (e.g. HKEY_LOCAL_MACHINE\Software\SomeCompany\SomeKey).

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead

If the key already exists then this method does nothing.


Utilities.LocalRegKeyDelete Method

LocalRegKeyDelete Method

The LocalRegKeyDelete method deletes the specified key and all of its subkeys from the local system registry.

Syntax

    objUtilities.LocalRegKeyDelete(KeyName)

    KeyName

      A string containing the name of the key on the local system.

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead

If the key does not exist then this method does not return an error.


Utilities.LocalRegKeyExists Method

LocalRegKeyExists Method

The LocalRegKeyExists method returns a boolean value that indicates whether the specified key exsists in the local system registry.

Syntax

    fExists = objUtilities.LocalRegKeyExists(KeyName)

    KeyName

      A string containing the name of the key on the local system.

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead


Utilities.LocalRegRead Method

LocalRegRead Method

The LocalRegRead method reads the specified value from the local registry and returns it.

Syntax

    Data = objUtilities.LocalRegRead(KeyName, ValueName)

    KeyName

      A string containing the name of the key on the local system (e.g. HKEY_LOCAL_MACHINE\Software\SomeCompany\SomeKey).

    ValueName

      A string containing the name of the value to read. For the default value pass null or an empty string.

Notes

If the data in the registry is zero-length then this method returns null.

For the KeyName parameter, root key names can be abbreviated as described in the following table. For example, instead of passing "HKEY_LOCAL_MACHINE\Software\SomeCompany\SomeKey" it is possible to use "HKLM\Software\SomeCompany\SomeKey".

Key | Abbreviation
HKEY_LOCAL_MACHINE | HKLM
HKEY_CURRENT_USER | HKCU
HKEY_CLASSES_ROOT | HKCR
HKEY_CURRENT_CONFIG | HKCC
HKEY_CURRENT_USER | HKCU
HKEY_USERS | HKU
HKEY_PERFORMANCE_DATA | HKPD
HKEY_DYN_DATA | HKDD


Utilities.LocalRegValueDelete Method

LocalRegValueDelete Method

The LocalRegValueDelete method deletes the specified value from the local system registry.

Syntax

    objUtilities.LocalRegValueDelete(KeyName, ValueName)

    KeyName

      A string containing the name of the key on the local system.

    ValueName

      A string containing the name of the value to delete. If this is null or an empty string then the default value will be deleted.

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead

If the value does not exist then this method does not return an error.


Utilities.LocalRegValueExists Method

LocalRegValueExists Method

The LocalRegValueExists method returns a boolean value that indicates whether the specified value exsists in the local system registry.

Syntax

    fExists = objUtilities.LocalRegValueExists(KeyName, ValueName)

    KeyName

      A string containing the name of the key on the local system.

    ValueName

      A string containing the name of the value on the local system. If this is null or an empty string then this method checks whether the default value exists.

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead


Utilities.LocalRegWrite Method

LocalRegWrite Method

The LocalRegWrite method writes the specified value to the local registry.

Syntax

    Data = objUtilities.LocalRegWrite(KeyName, ValueName, Type, Data)

    KeyName

      A string containing the name of the key on the local system (e.g. HKEY_LOCAL_MACHINE\Software\SomeCompany\SomeKey).

    ValueName

      A string containing the name of the value to write. For the default value pass null or an empty string.

    Type

      An integer that indicates the data type of the value. Constants are defined for known types. The type also determines the format of the Data parameter.

    Type Values

    Constant | Description
    cmiREG_NONE (0) | The data type is not specified. This is the same as free-form binary data. Data is an array in which the elements can be interpreted as 8 bit unsigned integers (bytes).
    cmiREG_SZ (1) | String. Data is a string. When writing an empty string ("") a single UNICODE null character will be written to the registry. When reading such a value, an empty string ("") is returned.
    cmiREG_EXPAND_SZ (2) | String with environment variable references (e.g. %PATH%). Data is a string. When writing an empty string ("") a single UNICODE null character will be written to the registry. When reading such a value, an empty string ("") is returned.
    cmiREG_BINARY (3) | Free-form binary data. Data is an array in which the elements can be interpreted as 8 bit unsigned integers (bytes).
    cmiREG_DWORD (4) | Typically a 32 bit number but there are cases where this type is used for binary data. Data can be an integer (VT_I4) or an array in which the elements can be interpreted as 8 bit unsigned integers (bytes).
    cmiREG_DWORD_LITTLE_ENDIAN (4) 32 bit number in little endian format. This is the same as cmiREG_DWORD. See above for data format.

    In little-endian format, a multibyte value is stored in memory from the lowest byte (the "little end") to the highest byte. For example, the value 0x12345678 is stored as (0x78 0x56 0x34 0x12) in little-endian format.

    The Windows operating systems are designed to run on little-endian computer architectures. A user may connect to computers that have big-endian architectures, such as some UNIX systems.

    cmiREG_DWORD_BIG_ENDIAN (5) | 32 bit number in big endian format. Data is an integer (VT_I4)
    cmiREG_LINK (6) | Symbolic link. Data is a string.
    cmiREG_MULTI_SZ (7) | Multiple strings. Data is an array in which each element can be interpreted as a string. When writing to the registry, passing an empty array will write a single UNICODE null character. When reading such a value, an empty array will be returned (VT_ARRAY | VT_VARIANT).
    cmiREG_RESOURCE_LIST (8) | Device driver resource list in the resource map. Data is an array in which the elements can be interpreted as 8 bit unsigned integers (bytes).
    cmiREG_FULL_RESOURCE_DESCRIPTOR (9) | Resource list in the hardware description. Data is an array in which the elements can be interpreted as 8 bit unsigned integers (bytes).
    cmiREG_RESOURCE_REQUIREMENTS_LIST (10) | Resource requirements list. Data is an array in which the elements can be interpreted as 8 bit unsigned integers (bytes).
    cmiREG_QWORD (11) | 64-bit number. Data is an array in which the elements can be interpreted as 8 bit unsigned integers (bytes).
    cmiREG_QWORD_LITTLE_ENDIAN (11) | 64-bit number in little endian format (same as cmiREG_QWORD). Data is an array in which the elements can be interpreted as 8 bit unsigned integers (bytes).
    Other Custom Types | Data is an array in which the elements can be interpreted as 8 bit unsigned integers (bytes).

    For all data types, it is possible to write zero bytes to the registry by specifying null or empty (VT_NULL or VT_EMPTY) for the data. When reading a zero byte value, null (VT_NULL) is always returned.

    For all binary data, the array may contain VARIANTs (VT_ARRAY | VT_VARIANT) in which each VARIANT is either VT_UI1, VT_I2, or VT_I4 where each value can be converted to VT_UI1. VARIANTs containing any other data types will cause an invalid parameter error. The array may also contain VT_UI1 (VT_ARRAY | VT_UI1).

    For all non-binary data types, (cmiREG_SZ, cmiREG_EXPAND_SZ, cmiREG_DWORD, cmiREG_DWORD_LITTLE_ENDIAN, cmiREG_DWORD_BIG_ENDIAN, cmiREG_LINK, cmiREG_MULTI_SZ), it is possible to specify binary data using an array as described above. This feature should only be used when the application needs to write non-standard data for backward compatibility reasons. When reading these types, if the data in the registry is not in standard format then binary data will be returned in an array (VT_ARRAY | VT_VARIANT where each VARIANT is VT_UI1). Standard format for the DWORD types is data the size of a DWORD. Standard format for the the string types is a number of bytes that is evenly divisble by the size of a UNICODE character. The string may or may not be null-terminated.

Data

    The data to be written. Format of the data is determined by the value of the Type parameter (see above).

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead


Utilities.RelativeKey Property

RelativeKey Property

Setting the RelativeKey property allows using the alias HKEY_RELATIVE or HKR for a particular key in the target system registry. For example, if RelativeKey is set to "HKEY_LOCAL_MACHINE\Software\Microsoft\Foo" then reading or writing the target key "HKR\Fred" or "HKEY_RELATIVE\Fred" will refer to the key "HKLM\Software\Microsoft\Foo\Fred" in the target system's registry.

To disable aliasing set this property to null or an empty string (""). The default is disabled.

Syntax

    sKey = objUtilities.RelativeKey

Notes

If RelativeKey has not been set, and HKEY_RELATIVE or HKR is used with a target registry access method, then an invalid parameter error will be returned.


Utilities.TargetRegGetType Method

TargetRegGetType Method

The TargetRegGetType method returns the data type of the specified value from the target system registry. LoadHive must be called before this method can be called.

Syntax

    Type = objUtilities.TargetRegGetType(KeyName, ValueName)

    KeyName

      A string containing the name of the key on the target system. This key must be located somewhere in the hive specified in the TargetKey parameter to LoadHive. For example, if HKEY_LOCAL_MACHINE\Software was specified in the LoadHive call then the value of this parameter could be HKEY_LOCAL_MACHINE\Software\SomeCompany\SomeKey.

    ValueName

      A string containing the name of the value to read. For the default value pass null or an empty string.

    Type

      An enumerated value that indicates the data type of the value. The type also determines how the data is returned from the TargetRegRead method. For a list of values and the corresponding data formats see the LocalRegGetType method.

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead


Utilities.TargetRegKeyCreate Method

TargetRegKeyCreate Method

The TargetRegKeyCreate creates the specified key in the target system registry. LoadHive must be called before this method can be called.

Syntax

    objUtilities.TargetRegKeyCreate(KeyName)

    KeyName

      A string containing the name of the key on the target system. This key must be located somewhere in the hive specified in the TargetKey parameter to LoadHive. For example, if HKEY_LOCAL_MACHINE\Software was specified in the LoadHive call then the value of this parameter could be HKEY_LOCAL_MACHINE\Software\SomeCompany\SomeKey.

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead

If the key already exists then this method does nothing.


Utilities.TargetRegKeyDelete Method

TargetRegKeyDelete Method

The TargetRegKeyDelete method deletes the specified key and all of its subkeys from the target system registry. LoadHive must be called before this method can be called.

Syntax

    objUtilities.TargetRegKeyDelete(KeyName)

    KeyName

      A string containing the name of the key on the target system. This key must be located somewhere in the hive specified in the TargetKey parameter to LoadHive. For example, if HKEY_LOCAL_MACHINE\Software was specified in the LoadHive call then the value of this parameter could be HKEY_LOCAL_MACHINE\Software\SomeCompany\SomeKey.

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead

If the key does not exist then this method does not return an error.


Utilities.TargetRegKeyExists Method

TargetRegKeyExists Method

The TargetRegKeyExists method returns a boolean value that indicates whether the specified key exsists in the target system registry. LoadHive must be called before this method can be called.

Syntax

    fExists = objUtilities.TargetRegKeyExists(KeyName)

    KeyName

      A string containing the name of the key on the target system. This key must be located somewhere in the hive specified in the TargetKey parameter to LoadHive. For example, if HKEY_LOCAL_MACHINE\Software was specified in the LoadHive call then the value of this parameter could be HKEY_LOCAL_MACHINE\Software\SomeCompany\SomeKey.

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead


Utilities.TargetRegRead Method

TargetRegRead Method

The TargetRegRead method reads the specified value from the target system registry and returns it. LoadHive must be called before this method can be called.

Syntax

    Data = objUtilities.TargetRegRead(KeyName, ValueName)

    KeyName

      A string containing the name of the key on the target system. This key must be located somewhere in the hive specified in the TargetKey parameter to LoadHive. For example, if HKEY_LOCAL_MACHINE\Software was specified in the LoadHive call then the value of this parameter could be HKEY_LOCAL_MACHINE\Software\SomeCompany\SomeKey.

    ValueName

      A string containing the name of the value to read. For the default value pass null or an empty string.

Notes

If the data in the registry is zero-length then this method returns null.

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead


Utilities.TargetRegValueDelete Method

TargetRegValueDelete Method

The TargetRegValueDelete method deletes the specified value from the target system registry. LoadHive must be called before this method can be called.

Syntax

    objUtilities.TargetRegValueDelete(KeyName, ValueName)

    KeyName

      A string containing the name of the key on the target system. This key must be located somewhere in the hive specified in the TargetKey parameter to LoadHive. For example, if HKEY_LOCAL_MACHINE\Software was specified in the LoadHive call then the value of this parameter could be HKEY_LOCAL_MACHINE\Software\SomeCompany\SomeKey.

    ValueName

      A string containing the name of the value to delete. If this is null or an empty string then the default value will be deleted.

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead

If the value does not exist then this method does not return an error.


Utilities.TargetRegValueExists Method

TargetRegValueExists Method

The TargetRegValueExists method returns a boolean value that indicates whether the specified value exsists in the target system registry. LoadHive must be called before this method can be called.

Syntax

    fExists = objUtilities.TargetRegValueExists(KeyName, ValueName)

    KeyName

      A string containing the name of the key on the target system. This key must be located somewhere in the hive specified in the TargetKey parameter to LoadHive. For example, if HKEY_LOCAL_MACHINE\Software was specified in the LoadHive call then the value of this parameter could be HKEY_LOCAL_MACHINE\Software\SomeCompany\SomeKey.

    ValueName

      A string containing the name of the value on the target system. If this is null or an empty string then this method checks whether the default value exists.

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead


Utilities.TargetRegWrite Method

TargetRegWrite Method

The TargetRegWrite method writes the specified value in the target system registry. LoadHive must be called before this method can be called.

Syntax

    objUtilities.TargetRegWrite(KeyName, ValueName, Type, Data)

    KeyName

      A string containing the name of the key on the target system. This key must be located somewhere in the hive specified in the TargetKey parameter to LoadHive. For example, if HKEY_LOCAL_MACHINE\Software was specified in the LoadHive call then the value of this parameter could be HKEY_LOCAL_MACHINE\Software\SomeCompany\SomeKey.

    ValueName

      A string containing the name of the value to write. For the default value pass null or an empty string.

    Type

      An enumerated value that indicates the data type of the value. The type also determines the format of the Data parameter. For a list of values and the corresponding data formats see the LocalRegWrite method.

    Data

      The data to be written. Format of the data is determined by the value of the Type parameter (see above).

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead


Utilities.UnloadAllHives Method

UnloadAllHives Method

The UnloadAllHives method unloads all hives from the local machine registry that were previously loaded with the LoadHive method and saves their contents to the same file specified in those calls.

Syntax

    objUtilities.UnloadAllHives()


Utilities.UnloadHive Method

UnloadHive Method

The UnloadHive method unloads a hive from the local machine registry that was previously loaded with the LoadHive method and saves its contents to the same file specified in that call.

Syntax

    objUtilities.UnloadHive(TargetKey)

    TargetKey

      A string containing the name of the key on the target system (e.g. HKEY_LOCAL_MACHINE\Software). This must be the same name that was passed to the previous call to Utilities.LoadHive

Notes

Root key names can be specified using shortcuts (e.g. HKLM for HKEY_LOCAL_MACHINE). For more information see Utilities.LocalRegRead


Trappable Errors

All CMI methods and properties can potentially return an error. If you do not want default error handling or if you need to check for a specific error the following pages describe the errors returned by the CMI.

The error symbols and numbers are diplayed as follows on each page:

cmiErrXMLParsingError (-2147212504, 0x80042328, 9000)

cmiErrXMLParsingError is the error symbol that can be used to check for a specific error. Its value will be the SCODE portion of the Win32 HRESULT that corresponds to the error. In this example that number is 9000 (i.e. cmiErrXMLParsingError = 9000).

-2147212504 is the Win32 HRESULT as a decimal number.

0x80042328 is the Win32 HRESULT as a hexdecimal number.

9000 is the SCODE portion of the Win32 HRESULT as a decimal number.

For more information on handling CMI errors in a specific programming language see Programming Language Support.


cmiErrAttributeDataTypeIncorrect

cmiErrAttributeDataTypeIncorrect (-2147212485, 0x8004233B, 9019)

A required attribute of an XML element does not have the correct data type.


cmiErrAttributeMissing

cmiErrAttributeMissing (-2147212497, 0x8004232F, 9007)

A required attribute is missing from an XML element.


cmiErrCantDowngradeObject

cmiErrCantDowngradeObject (-2147212451, 0x8004235D, 9053)

This error is returned from CMI.ImportCarrier and CMI.CheckCarrier when the carrier file contains an object with a revision value that is less than the revision value of an existing object in the database that has the same VSGUID and platform GUID.


cmiErrCantPersistObject

cmiErrCantPersistObject (-2147212460, 0x80042354, 9044)

The CMI is not able to get either the IPersistStream or the IPersistStreamInit interface on an object contained within ExtProperty.Value. The current operation requires either saving or loading the ExtProperties collection and it cannot complete because this object does not support persistence.


cmiErrCMIMIncompatible

cmiErrCMIMIncompatible (-2147212456, 0x80042358, 9048)

CMI.dll on the client machine and CMIM.dll on the database server are using incompatible versions. Reinstall either the client or the server so that the versions are compatible.


cmiErrCMIClosed

cmiErrCMIClosed (-2147212492, 0x80042334, 9012)

The methods and properties of any CMI object cannot be accessed after calling CMI.Close.


cmiErrCollectionEmpty

cmiErrCollectionEmpty (-2147212494, 0x80042332, 9010)

The operation cannot be completed because the collection is empty.


cmiErrCollectionReadOnly

cmiErrCollectionReadOnly (-2147212482, 0x8004233E, 9022)

Items cannot be added or removed from the collection because it is read-only for the attempted operation (Add, Remove, or Clear). Read-only collections usually contain database objects.


cmiErrCOMError

cmiErrCOMError (-2147212489, 0x80042337, 9015)

The CMI encountered an unexpected COM error. For more information see the application event log on the client machine and on the database server.


cmiErrConflictingVIGUIDs

cmiErrConflictingVIGUIDs (-2147212450, 0x8004235E, 9054)

This error is returned from CMI.ImportCarrier and CMI.CheckCarrier when the carrier file contains an object that has the same VSGUID and platfrom GUID as an existing object in the database but different VIGUIDs. This indicates that either the carrier file object has an incorrect VIGUID or that the database is corrupt. Contact Microsoft Product Support Services.


cmiErrDBError

cmiErrDBError (-2147212491, 0x80042335, 9013)

A database error occurred within the CMI. For more information see the application event log on the database server.


cmiErrDBIncompatible

cmiErrDBIncompatible (-2147212455, 0x80042359, 9049)

CMIM.dll on the server machine and the database are different versions and are incompatible. This indicates that the CMI server installation does not match the database. Contact Microsoft Product Support Services for assistance.


cmiErrDBNotOpen

cmiErrDBNotOpen (-2147212486, 0x8004233A, 9018)

A database has not been opened. CMI.OpenDB must be called before calling this method.


cmiErrDBOpen

cmiErrDBOpen (-2147212487, 0x80042339, 9017)

A database is already open. Call CMI.Close.DB before calling this method.


cmiErrDstDirNotEmpty

cmiErrDstDirNotEmpty (-2147212453, 0x8004235B, 9051)

The application called CMI.ImportCarrier for a carrier file that contains REPOSITORY elements and chose to use default file copying. The CMI cannot copy the files because the default destination directory exists and is not empty. See the event log on the client machine for the name of the directory.


cmiErrDuplicateElement

cmiErrDuplicateElement (-2147212467, 0x8004234D, 9037)

The application attempted to add an element to a collection and a duplicate element already exists within the collection. For example, if Instances.Add is called twice passing the same component, and that component does not support multi-instance, then this error is returned.


cmiErrElementDataTypeIncorrect

cmiErrElementDataTypeIncorrect (-2147212484, 0x8004233C, 9020)

The value of an XML element does not have the correct data type.


cmiErrExceptionInEventHandler

cmiErrExceptionInEventHandler (-2147212454, 0x8004235A, 9050)

An event was fired from the CMI object into the application and the application's event handler caused an exception (e.g. access violation). Check the event log to determine the name of the event handler that caused the exception.


cmiErrHiveAlreadyLoaded

cmiErrHiveAlreadyLoaded (-2147212479, 0x80042341, 9025)

The Utilities.LoadHive method was called twice for the same target key without calling Utilities.UnloadHive or Utilities.UnloadAllHives. The application must unload the hive before it can load a new hive using the same target key.


cmiErrHiveNotLoaded

cmiErrHiveNotLoaded (-2147212478, 0x80042342, 9026)

A Utilities method that references a target hive registry key was called but Utilities.LoadHive has not been called for the target key. The application must load a hive before it can access target system registry keys.


cmiErrIncompleteComponentChain

cmiErrIncompleteComponentChain (-2147212464, 0x80042350, 9040)

An Instance was added to a Configuration or a Configuration was loaded containing an Instance and one of the components in Instance.ComponentChain is either missing from the database or is present in the database but does not belong to the same configuration as the platform.


cmiErrIncorrectPropertyFormat

cmiErrIncorrectPropertyFormat (-2147212480, 0x80042340, 9024)

A PROPERTY element has been specified within a RESOURCE element and its Name attribute indicates that it has a defined property type. The PROPERTY element's Format attribute does not match the Format attribute of the PROPTYPE element that defines the property's type. Check the PROPTYPE definition for the correct format and change the PROPERTY element to use that format.


cmiErrInternalError

cmiErrInternalError (-2147212501, 0x8004232B, 9003)

An internal CMI error occurred.


cmiErrInvalidCarrierRevision

cmiErrInvalidCarrierRevision (-2147212498, 0x8004232E, 9006)

The Revision attribute of the DCARRIER element does not contain a valid value. Check the .SLD file's DTD for the correct value.


cmiErrInvalidCollectionIndex

cmiErrInvalidCollectionIndex (-2147212493, 0x80042333, 9011)

The index specified does not reference an existing item in the collection.


cmiErrInvalidComponentChain

cmiErrInvalidComponentChain (-2147212458, 0x80042356, 9046)

A saved configuration cannot be loaded because the component chain of an Instance has been corrupted in the file. When a configuration is loaded, the CMI populates Instance.ComponentChain based on the contents of the file. It then traverses the chain and checks that each component is the prototype of the preceding component and that the last one in the chain is the default prototype component for the platform. It also checks that all of the components in the chain in the configuration file are still present in the database. If any of these integrity checks fail then this error is returned. If possible, the error description will include the VSGUID of the component at the head of the chain. The most typical cause of this error is deleting a component from the database that is used in an existing configuration.

The following is a complete list of the integrity checks that can cause this error.

  • The component chain in the configuration file is empty. This is likely due to configuration file corruption.
  • None of the components in the configuration file's component chain are in the database. This could be caused by deleting all of the components from the database, database corruption, or configuration file corruption.
  • A component in the configuration file's component chain cannot be found in the database. This is the most typical cause of this error and is usually due to deleting the component from the database. It can also be caused by database corruption or configuration file corruption.
  • A VSGUID in the configuration file's component chain does not match a VSGUID in the database component chain. This can be due to configuration file corruption, database corruption or changes in the chain's components in the database such as altering the prototype VIGUID.
  • The protoype VIGUID of a component in the database does not match the VIGUID of the next component in the chain. This can be due to configuration file corruption, database corruption or changes in the chain's components in the database such as altering the prototype VIGUID.
  • The last component in the chain is not the default protoype for the platform. This can be due to configuration file corruption, database corruption, changes in the chain's components in the database such as altering the prototype VIGUID, or altering the platform's prototype VIGUID in the database.


cmiInvalidDependencyClass

cmiInvalidDependencyClass (-2147212472, 0x80042348, 9032)

A DEPENDENCY element specified a Class attribute that is not a recognized dependency class. For valid dependency class values consult the document type definition (DTD).


cmiErrInvalidDependencyType

cmiErrInvalidDependencyType (-2147212473, 0x80042347, 9031)

A DEPENDENCY element specified a Type attribute that is not a recognized dependency type. For valid dependency type values consult the document type definition (DTD).


cmiErrInvalidFilterParameter

cmiErrInvalidFilterParameter (-2147212459, 0x80042355, 9045)

A Filter object or one of its Rule objects contains an invalid property. See the event log on the client machine for details of the error.


cmiErrInvalidGroupClass

cmiErrInvalidGroupClass (-2147212475, 0x80042345, 9029)

A GROUP element specified a GroupClass attribute that is not a recognized class value. For valid values consult the document type definition (DTD).


cmiErrInvalidGroupDefaultDependency

cmiErrInvalidGroupDefaultDependency (-2147212474, 0x80042346, 9030)

A GROUP element specified a DefaultDependencyType attribute that is not a recognized dependency type or not permitted for groups. For valid dependency type values consult the document type definition (DTD). Note that groups cannot specify FromGroup as the default dependency type.


cmiErrInvalidGUID

cmiErrInvalidGUID (-2147212496, 0x80042330, 9008)

The specified GUID is not in a valid format. Use {1996a3f5-04c2-48b3-9d3f-7c10e62f54e1}.


cmiErrInvalidPropertyValueDataType

cmiErrInvalidPropertyValueDataType (-2147212495, 0x80042331, 9009)

The value of a PROPERTY or PROPTYPE element cannot be converted to its specified data type. Possible reasons for this error are:

  • The data does not match the specified format e.g. the element contains a string but the format was specified as TimeDate.
  • The element is empty when its format is Integer, Boolean, Expression, Script, Object, GUID, or TimeDate. The reason for this is that there is no obvious default value when the element is empty with one of these formats.
  • The format is Multi but the element does contain zero or more groups of four hex digits representing UNICODE character values in little endian form.
  • The data is too large. In particular, string formats cannot hold more than 3850 characters and binary formats cannot hold more than 7700 bytes.


cmiErrInvalidResourceType

cmiErrInvalidResourceType (-2147212476, 0x80042344, 9028)

A RESOURCE element specified a ResTypeVSGUID attribute that does not correspond to an existing resource type in the database. A RESOURCE element cannot be imported into the database before the RESTYPE element that defines its type.


cmiErrInvalidTopElement

cmiErrInvalidTopElement (-2147212499, 0x8004232D, 9005)

The top level XML element must be CARRIER.


cmiErrMultipleObjectRevisions

cmiErrMultipleObjectRevisions (-2147212452, 0x8004235C, 9052)

This error is returned from CMI.ImportCarrier and CMI.CheckCarrier when the database contains multiple objects that have the same VSGUID and platform GUID. This is a sign that the database is corrupt. Contact Microsoft Product Support Services.


cmiErrNeedTransaction

cmiErrNeedTransaction (-2147212502, 0x8004232A, 9002)

The CMIM.MantisDB object was incorrectly configured in COM+. This object requires a transaction.


cmiErrNoConfigurationPath

cmiErrNoConfigurationPath (-2147212465, 0x8004234F, 9039)

Configuration.Save was called but Configuration.Path has not been set. Configuration.Path must be set before the configuration can be saved.


cmiErrNoDBConnection

cmiErrNoDBConnection (-2147212503, 0x80042329, 9001)

The CMI must have a database connection before this method can be invoked. Call CMI.OpenDB to establish a connection.


cmiErrNoDefaultDBConfigured

cmiErrNoDefaultDBConfigured (-2147212483, 0x8004233D, 9021)

CMI.OpenDB was called without specifying a database name but no default database was configured in COM+ on the database server for CMIM.MantisDB. The COM+ configuration should include a constructor string that contains the database connection string.


cmiErrNoResourceTypeScript

cmiErrNoResourceTypeScript (-2147212457, 0x80042357, 9047)

Resource.Name could not be retrieved because the ResourceType object either does not have any script code or its script does not implement cmiGetName.

The Resource.Name property is retrieved by calling the method cmiGetName in the ResourceType script code. If the ResourceType object was imported into the database without script code or its script code does not implement cmiGetName then this error will be returned when trying to access Resource.Name.

For more information see Configuration Script Events.


cmiNotDynamic

cmiErrNotDynamic (-2147212469, 0x8004234B, 9035)

Some objects can represent both database and dynamic objects within a Configuration or an Instance. Some properties and methods can only be used if the object is dynamic.


cmiErrNotXCarrier

cmiErrNotXCarrier (-2147212463, 0x80042351, 9041)

The application attempted to open a file that contains a Configuration but that file contains import definitions (i.e. is it actually an .SLD file).


cmiPlatformDeletesProhibited

cmiPlatformDeletesProhibited (-2147212468, 0x8004234C, 9036)

The application has attempted to delete a platform from the database but CMI.AllowPlatformDeletes is False. The application must be set this property to True before it can delete a platform.


cmiErrPlatformMismatch

cmiErrPlatformMismatch (-2147212462, 0x80042352, 9042)

The application called Platform.OpenConfiguration but the .SLX file contains a Configuration that is not based on the Platform. Open the Configuration from its own Platform or use CMI.OpenConfiguration instead.


cmiErrPlatformNotInDB

cmiErrPlatformNotInDB (-2147212461, 0x80042353, 9043)

The application called Platform.OpenConfiguration or CMI.OpenConfiguration and the .SLX file references a Platform that is not in the database.


cmiErrRegKeyNotFound

cmiErrRegKeyNotFound (-2147212477, 0x80042343, 9027)

A Utilities method referenced a non-existent registry key or value. Check that both the key path and the value name exist. Attempting to read a default value that has not been set will also return this error.


cmiErrRepositorySrcPathTooLong

cmiErrRepositorySrcPathTooLong (-2147212481, 0x8004233F, 9023)

The combination of the carrier file path and the SRCPATH element within a REPOSITORY element is too long for the file system. Maximum path is 260 characters.


cmiErrScriptDisallowed

cmiErrScriptDisallowed (-2147212466, 0x8004234E, 9038)

The method cannot complete because a configuration script event has disallowed it. For example, if the application calls Instances.Add and the configuration script event OnAddInstance returns False, then this error is returned.


cmiScriptingError

cmiScriptingError (-2147212470, 0x8004234A, 9034)

An error occured in either platform, component, or resource type script code. See the application event log for more information. The CMI returns this error when the scripting engine reports to the CMI that an error has occurred in script code. The error could be due to a programming problem in the script code (e.g. divide-by-zero) or due to an error caused by a call to an external object. The CMI attempts to return the script error directly to the caller (the CMI application or other script code) but that is not always possible due to limitations of some scripting engines. The error will always be written to the application event log. Note that the line and column numbers specified in the event log are one-based i.e. the first line of the script code is line 1.


cmiUnknownScriptingLanguage

cmiUnknownScriptingLanguage (-2147212471, 0x80042349, 9033)

An unsupported scripting language was specified for platform, component, or resource type script. The CMI uses the scripting language name as the ProgID of the engine. It calls the Win32 API function CLSIDFromProgID using that name. If the function returns the error CO_E_CLASSSTRING then the CMI assumes that the language is not supported on the system and returns this error.


cmiErrWin32Error

cmiErrWin32Error (-2147212488, 0x80042338, 9016)

The CMI encountered an unexpected error from the Win32 subsystem. For more information see the application event log on the client machine and on the database server.


cmiErrXMLError

cmiErrXMLError (-2147212490, 0x80042336, 9014)

The CMI encountered an unexpected error from MSXML. For more information see the application event log on the database server.


cmiErrXMLParsingError

cmiErrXMLParsingError (-2147212504, 0x80042328, 9000)

The XML parser found an error in the XML source. The error description contains details of the problem and it can also be found in the event log.


cmiErrXMLTooLarge

cmiErrXMLTooLarge (-2147212500, 0x8004232C, 9004)

The XML source is too large. Divide it into smaller files and retry the import operation.


Platform.DefaultConfigScript Property

DefaultConfigScript Property

The DefaultConfigScript property returns a string containing the default configuration script. This script code is used for configurations based on the platform.

Syntax

    strDefaultConfigScript = objPlatform.DefaultConfigScript

Notes

This property is optional and may be null.


Platform.DefaultScriptLanguage Property

DefaultScriptLanguage Property

The DefaultScriptLanguage property returns a string containing the language of the default configuration script specified by Platform.DefaultConfigScript.

Syntax

    strDefaultScriptLanguage = objPlatform.DefaultScriptLanguage

Notes

This property is optional and may be null.


PropertyTypes.Remove Method

Remove Method

The Remove method removes the specified PropertyType object from the collection and also deletes it from the database.

Syntax

    objPropertyTypes.Remove(Index)

    Index

      Either an integer containing the one-based ordinal position of the PropertyType object in the collection or a string containing the value of the object's Name property.