Compare Tool API (to compare and align)
CompareTool is a MEGA object enabling management of object comparison between the current private workspace and a target repository in VBScript. Comparison enables creation of an update file designed to align the target repository. This functionality is available with the "HOPEX Power Supervisor" module.
NOTE: The comparison wizard provided as standard is a comprehensive and well maintained example of API use.
Implementation to VbScript
MegaObject can be installed using the following methods:
• Function OpenCompareToolEx(ByVal oParameterSource As Object, ByVal oParameterTarget As Object, ByVal strOption As String) As Object
This method enables instancing of the CompareTool object. Comparison is between a source and a target repository. You can either open the repository you wish to compare or provides the required parameter to let the compare tool opening the repository for you.
The two first parameter can be either a MEGARoot or a String. In case of a MEGARoot it'll be used by the CompareTool. If it is a String, it should describe the repository to be used:
strParameter
This is a string option of the form:
<optionName1>=<optionValue1>,<optionName2>=<optionValue2>,…
DbTarget = it can be either a base name, a base id or “TRANSACTION” or “FILE”. If you select “TRANSACTION” the current private workspace will be used. If you select “FILE”, a temporary repository will be created and your data file imported into it.
FileTarget = When specifying “FILE” as DbTarget, here is the path of the data file to import.
DbSource = Like DbTarget but for the source
FileSource = Like FileTarget but for the source
BaselineSource = When selecting a base name or a base id as DbSource you can open the repository according to an archived state.
BaselineTarget = Like BaselineSource for the target. Of course when a repository is opened according to an archived state, it is read only. You will not be able to align comparison result.
The last parameter is for option. You can leave it empty or use the previous syntax: <optionName>=<optionValue>
Compatibility = 0 or 1 lets you select the old comparison algorithm for compatibility purpose.
• Sub Close()
Frees the target repository private workspace and frees the MegaObject variables.
Frees the target repository private workspace and frees the MegaObject variables.
Attributes
• ContinueOnConfidential:
Enables specification of whether comparison processing should be aborted if a confidential object is present in the collection of objects to be compared (in source or target repository).
TRUE: comparison processing is not aborted.
FALSE: processing is aborted; this is the default value.
Enables specification of whether comparison processing should be aborted if a confidential object is present in the collection of objects to be compared (in source or target repository).
TRUE: comparison processing is not aborted.
FALSE: processing is aborted; this is the default value.
• Perimeter:
Enables modification of the perimeter of extraction of sets of objects and links to be compared in repositories. This attribute is not used when the "CompareAll" method is used.
Enables modification of the perimeter of extraction of sets of objects and links to be compared in repositories. This attribute is not used when the "CompareAll" method is used.
• FoundConfidential:
This attribute is specified by comparison processing to indicate presence of a confidential object in one of the two object collections to be compared.
This attribute is specified by comparison processing to indicate presence of a confidential object in one of the two object collections to be compared.
Methods
Comparison between complete repository or object sets is necessary to enable generation of an alignment file.
• Sub CompareAll()
Compares all objects and links of the source repository related to the target repository.
Compares all objects and links of the source repository related to the target repository.
• Sub CompareObjects(mgobjcolFromSource as MegaCollection, mgobjcolFromTarget as MegaCollection)
Compares the a set of objects and links from repository source and/or target.
Parameter:
mgobjcolFromSource: Object set of the source repository enabling, with assistance of the perimeter, constitution of a set of objects and links for the two repositories to be compared (source and target).
Compares the a set of objects and links from repository source and/or target.
Parameter:
mgobjcolFromSource: Object set of the source repository enabling, with assistance of the perimeter, constitution of a set of objects and links for the two repositories to be compared (source and target).
mgobjcolFromTarget: Object set of the target repository enabling, with assistance of the perimeter, constitution of a set of objects and links for the two repositories to be compared (source and target).
• Sub SetGenerateOutputOption(strOptionName As String, varOptionValue As Variant)
Enables specification of variables used at alignment file generation.
Parameter:
strOptionName: Name of variable identifying the Option. The following three options are available: "UpdateExtract", "DeleteFile", "IgnoreAttributes" and “TransferredObjects”.
varOptionValue: Option value. The value depends on Option:
* "DisconnectExtract": This option enables specification of whether the alignment file generates "disconnect" commands rather than "delete" commands; default value of this option is FALSE.
* "DeleteFile: A second file name can be configured using this option in order to manage "delete" commands. The alignment file takes into account all actions, and if a file name is defined for this option, all "delete" commands are sent to this file.
* "IgnoreAttributes": Processing compares all object MetaAttributes, but with this option it is possible to ignore certain MetaAttribute types. Each element is separated by " ; ". MetaAttribute types are as follows: "Date" ("Date" MetaAttributes are not taken into account at generation of alignment files, for example: Modification Date),"Creator" (MetaAttributes linked to object creation are ignored), "Authorization" (MetaAttributes linked to authorization are not managed), "Comment" (Comment MetaAttributes are ignored), "Order" (Order MetaAttribute is not taken into account). A MetaAttribute can be specifically ignored by adding it to the list. This MetaAttribute will be ignored for all objects and links,
for example: oCompareTool.SetGenerateOutputOption “IgnoreAttributes”, “Date; ~610000000P00[Date de modification];~b10000000L20[Modificateur];Order"
Enables specification of variables used at alignment file generation.
Parameter:
strOptionName: Name of variable identifying the Option. The following three options are available: "UpdateExtract", "DeleteFile", "IgnoreAttributes" and “TransferredObjects”.
varOptionValue: Option value. The value depends on Option:
* "DisconnectExtract": This option enables specification of whether the alignment file generates "disconnect" commands rather than "delete" commands; default value of this option is FALSE.
* "DeleteFile: A second file name can be configured using this option in order to manage "delete" commands. The alignment file takes into account all actions, and if a file name is defined for this option, all "delete" commands are sent to this file.
* "IgnoreAttributes": Processing compares all object MetaAttributes, but with this option it is possible to ignore certain MetaAttribute types. Each element is separated by " ; ". MetaAttribute types are as follows: "Date" ("Date" MetaAttributes are not taken into account at generation of alignment files, for example: Modification Date),"Creator" (MetaAttributes linked to object creation are ignored), "Authorization" (MetaAttributes linked to authorization are not managed), "Comment" (Comment MetaAttributes are ignored), "Order" (Order MetaAttribute is not taken into account). A MetaAttribute can be specifically ignored by adding it to the list. This MetaAttribute will be ignored for all objects and links,
for example: oCompareTool.SetGenerateOutputOption “IgnoreAttributes”, “Date; ~610000000P00[Date de modification];~b10000000L20[Modificateur];Order"
* " TransferredObjects": This option lets the user choose to include or not objects of merging (_TransferedObject). By default this option is true. This value is a Boolean.
• Sub ResetGenerateOutputOptions()
This method enables reinitialization of options that were specified using the previous method: "SetGenerateOutputOption".
This method enables reinitialization of options that were specified using the previous method: "SetGenerateOutputOption".
• Sub GenerateOutput(strOutputFileName As String, strOutputType As String)
This method generates the alignment file named "strOutPutFileName". If the "DeleteFile" option was specified a file with "delete" commands is created.
Parameters:
strOutputFileName: Alignment file name.
strOutputType: enables modification of alignment file format. Default format is "MGR".
This method generates the alignment file named "strOutPutFileName". If the "DeleteFile" option was specified a file with "delete" commands is created.
Parameters:
strOutputFileName: Alignment file name.
strOutputType: enables modification of alignment file format. Default format is "MGR".
• GetRootSource
Returns the MEGA Root used for comparison as Source Repository. This is convenient especially if you opened is through the call to OpenCompareTool
• GetRootTarget
Just like GetRootSource, returns the MEGA Root of the target repository.
• Align
This function will align the differences with the target repository. If an error occurs it returns a path (string) to the rejected commande file. If there are no rejected command an empty string is returned. You can only align if the target repository is writable. As an instance, you cannot use align if the target repository is an archived state based on a dispatch.
• Commit
This method must be called after the align function and before closing the target repository. Commit will save every update on the target repository after the alignment.
• Rollback
This method can be called instead of “Commit” to cancel every update processed in the target repository with the “align” function.
• SetMatchingObjectMacro(strMacroId)
You can call this method specifying a macro Id.
When comparing two repositories, the standard behavior to find the matching object in the other base is to look for an object with the same idabs.
The macro must implement this function:
Function GetMatchingObject(oContext, oReference)
oReference is the MEGAObject that is searched in the other repository
oContext is an object with the following available methods:
o GetDirection: returns a String with two possible values:
“ST”: oReference is from the Source repository and the macro should look for the matching object in the Target repository.
“TS”: oReference is from the Target repository and the macro should look for the matching object in the Source repository.
o GetMatchingObjectRoot: returns the MEGARoot of the repository where the matching object is searched.
This macro must always return a MEGAObject (even if no matching object have been found).
Here is a sample function with quite the same behavior as the standar.
Function GetMatchingObject(oContext, oReference)
Dim oMatchingObjectRoot
set oMatchingObjectRoot = oContext.GetMatchingObjectRoot()
Dim szDirection
szDirection = oContext.GetDirection()
Dim oMatchingObject
Set oMatchingObject = oMatchingObjectRoot.GetCollection(oReference.GetClassId).Item(oReference.GetId())
Set GetMatchingObject = oMatchingObject
End Function
Here, “.item” on a MEGACollection always returns a mega object even if the item is not found.
• GetDiffResultCollection
After a CompareAll or CompareObjects this methods returns a MEGACollection containing all differences.
This MEGA Collection contains object with attributes described with the following Informal Query: “~CcRkodhCELgI[Compare.DiffResult.Collection]”
“~410000000H00[Order]” Number: This is the order of the current difference.
“~310000000D00[Absolute Identifier]” Idabs: This is the identifier of the current difference.
“~snk(al)kEboV[MetaPicture]” Idabs: this is the picture's idabs of the current difference (according to its type: create, delete, link, …).
“~K3Rv(lEmEvlI[DiffTypeMetaPicture]” MegaIdentifier: this metapicture depends if it is a update, a connect, a delete…
“~3SqlLqFEEPoF[Kind]” Enumeration: this is the kind of the difference, a link or an object. Many attributes are available only link or object kind.
”~)TqlXLHEEn3G[SourceAvailable]” Boolean: true if the element is available in the source repository.
”~PUqliLHEEj4G[TargetAvailable]” Boolean: true if the element is availbale in the target repository.
”~ZApdg(vjEX67[Difference]” Enumeration: It is the difference type: Connect, create, delete,…
0: Aucune différence
1: Créé
2: Modifié
3: Supprimé
4: Relié
5 : Délié
”~CVJie9xjEzg5[Target]” String : The metaclass name of the object or the metaassociation name of the link.
”~ASJi1AxjEHj5[Object 1]” String: the object name if the difference kind is an object. The object next to the link if the difference is a link.
”~BTJiGAxjELm5[Object 2]” String: if the difference is a link the other object name next to the link.
”~ITqlPgcDEb8F[ObjectSourceIdabs]” Mega Idabs: if the difference is about an object, this property is the idabs of the object in the source database when it exists.
“~jSqlClcDEzIF[ObjectSourceMetaclassIdabs]” Mega Idabs: if the difference is about an object, this property is the idabs of the metaclass of the object in the source database when it exists.
“~sTqlmgcDEP9F[ObjectTargetIdabs]” Mega Idabs: if the difference is about an object, this property is the idabs of the object in the target database when it exists.
“~ETqlBtcDEzKF[ObjectTargetMetaclassIdabs] ]” Mega Idabs: if the difference is about an object, this property is the idabs of the metaclass of the object in the target database when it exists.
“~LSqlvKfDE1OF[LinkSourceIdabs]” Mega Idabs: if the link exists in the source database, this property is the metaassociation idabs.
“~9TqlULfDEzOF[LinkSourceMajorIdabs]” Mega Idabs: If the link exists in the source database, this property is the major metaassociationend idabs.
“~5Vql)qGEErwF[LinkSourceMajorMetaclassIdabs]” Mega Idabs: if the link exists in the source database, this property is the metacalss idabs on the major side of the link.
“~jTqlpLfDEvPF[LinkSourceMinorIdabs]” Mega Idabs: If the link exists in the source database, this property is the minor metaassociationend idabs.
“~FSqlhrGEEjyF[LinkSourceMinorMetaclassIdabs]” Mega Idabs: if the link exists in the source database, this property is the metacalss idabs on the minor side of the link.
“~OVqliuKEE59G[LinkTargetIdabs]” Mega Idabs: if the link exists in the target database, this property is the metaassociation idabs.
“~LUqlCMfDErQF[LinkTargetMajorIdabs]” Mega Idabs: If the link exists in the target database, this property is the major metaassociationend idabs.
“~uSql5sGEEfzF[LinkTargetMajorMetaclassIdabs]” Mega Idabs: if the link exists in the target database, this property is the metacalss idabs on the major side of the link.
“~1UqlwOfDEfUF[LinkTargetMinorIdabs]” Mega Idabs: If the link exists in the target database, this property is the minor metaassociationend idabs.
“~OTqlMsGEEb(F[LinkTargetMinorMetaclassIdabs]” Mega Idabs: if the link exists in the target database, this property is the metacalss idabs on the minor side of the link.
Sample (VBScript)
Option Explicit
Const cszDbSourceName = "Dev"
Const cszDbTargetName = "Prod"
Function DifferenceTypeName(strDiffValue)
DifferenceTypeName = ""
dim mgDiffTypeCurrent
For Each mgDiffTypeCurrent In GetObjectFromId("~ZApdg(vjEX67[Difference]").GetCOllection("~uGZC89p5ua00[_ParameterValue]")
If strDiffValue = mgDiffTypeCurrent.GetProp("~L20000000L50[Valeur interne]") Then
DifferenceTypeName = mgDiffTypeCurrent.Name
Exit For
End If
Next
End Function
Dim mgCmpTool
Set mgCmpTool = GetRoot.OpenCompareToolEx("DbSource=" & cszDbSourceName, "DbTarget=" & cszDbTargetName, “”)
If Not mgCmpTool Is Nothing Then
print "Repository " & mgCmpTool.GetRootSource.Name & " opened as source"
print "Repository " & mgCmpTool.GetRootTarget.Name & " opened as target"
mgCmpTool.CompareAll
Dim mgcolDiff
Set mgcolDiff = mgCmpTool.GetDiffResultCollection
Dim mgDiff
For Each mgDiff In mgcolDiff
Dim strDiff
strDiff = mgDiff.GetProp("~ZApdg(vjEX67[Difference]")
Dim strtarget
strTarget = mgDiff.GetProp("~CVJie9xjEzg5[Cible]")
Dim strObject1
strObject1 = mgDiff.GetProp("~ASJi1AxjEHj5[Objet 1]")
Dim strObject2
strObject2 = mgDiff.GetProp("~BTJiGAxjELm5[Objet 2]")
print DifferenceTypeName(strDiff) & ": [" & strtarget & "] " & strObject1 & "/" & strObject2
Next
mgCmpTool.Close
End If
Sample (Java)
final MegaRoot mgRoot = mgobjSource.getRoot();
final MegaCurrentEnvironment mgEnvironment = mgRoot.currentEnvironment();
final MegaToolkit mgToolkit = mgEnvironment.toolkit();
final MegaCollection mgcolOrgProcess = mgRoot.getCollection("~gsUiU9B5iiR0[Organizational Process]");
final MegaObject mgNewOrgProcess = mgcolOrgProcess.create();
final MegaObject mgobjPerimeter = mgRoot.getObjectFromID("~cj6s5ij3q400[Standard for comparison]");
if ((null != mgobjPerimeter) && mgobjPerimeter.exists()) {
final MegaCollection mgcolObjectToCompare = mgRoot.getSelection("");
mgcolObjectToCompare.add(mgNewOrgProcess);
final MegaCompareTool oCompareTool = new MegaCompareTool(mgRoot, "DbSource=TRANSACTION", "DbTarget=" + mgRoot.getProp("~Z20000000D60[Short Name]"), "");
oCompareTool.perimeter(mgToolkit.getString64FromID(mgobjPerimeter.getID()));
oCompareTool.compareObjects(mgcolObjectToCompare);
final String strRejects = oCompareTool.align();
if (0 == strRejects.length()) {
oCompareTool.commit();
} else {
oCompareTool.rollback();
}
oCompareTool.close();
mgcolObjectToCompare.release();
mgobjPerimeter.release();
}
mgNewOrgProcess.release();
mgToolkit.release();
mgEnvironment.release();
mgcolOrgProcess.release();
mgRoot.release();