Use Integrator from the Command Line

The method signatures for Build, Compare, Link and Unlink are shown below. These correspond to the interactive operations described in the Main Table Context Menu in Integrator Controls. The string arguments can be a name like /MyName or a reference like =123/45678. If duplicate names are used, it is best to always use reference numbers to avoid confusion. The array arguments are arrays of strings of the same format.

!!integrator.build(!Name is STRING)

!!integrator.build(!Names is ARRAY)

!!integrator.compare(!Name is STRING)

!!integrator.compare(!Names is ARRAY)

!!integrator.link(!Name1 is STRING, !Name2 is STRING)

!!integrator.unlink(!Name is STRING)

!!integrator.unlink(!Names is ARRAY)

The following methods get or set the current project configuration file, get the list of Configurations defined in the current file, and get or set the selected Configuration:

!!integrator.projectConfigurationFile()

!!integrator.projectConfigurationFile(!Filename is STRING)

!!integrator.getConfigurations()

!!integrator.configuration()

!!integrator.configuration(!Name is STRING)

The following methods return the Names of the Compare Colours, Comparison Category and rule set for the currently selected Configuration:

!!integrator.compareColours()

!!integrator.compareCategory()

!!integrator.compareRuleset()

By default the Compare Report is generated to the screen. Suppress the output to screen with this method (typically used in non-graphics mode):

!!integrator.setReportVisible(false)

Integrator will maintain the current compare report in a temporary file during the session. Use the following method to save a permanent report file.

!!integrator.setReportPath('c:\reports\rep.xml')

If the pathname of the report file has been specified as shown above, then the report can be viewed in the Compare form using the following command (note that this command cannot be used in non-graphics mode).

!!integrator.openReport()

The following method opens and colours all diagrams referenced by the last comparison. In non-graphics mode it does not display anything but holds the coloured views in memory pending save to pdf file.

!!integrator.openAllReferencedDiagrams()

The following method saves the side-by-side compare details from the last comparison to Excel. Default filetype is xlsx.

!!integrator.saveAsExcel(!filename is STRING)

The following method returns the array of diagram page names in the form <Diagram Name> Page- <Page Number>, for example A0-01-2012-0001 Page-1, for the last comparison.

!!integrator.diagramlist() is ARRAY

The results of the above method can be used in conjunction with the diagram viewer method (see below) to return a Diagram Page object and then save the coloured diagram page to a pdf file of the same name.

!list = !!integrator.diagramlist()

do !page values !list

!diagramPage = !!mmViewer.diagramPage(!page)

!diagramPage.saveAsPDF(!page)

enddo

The following methods have been provided to set flags to auto-link matched elements and auto-update attributes:

!!integrator.setCompareAutoLinkMatches(!Flag is BOOLEAN)

!!integrator.setCompareAutoUpdateAttributes(!Flag is BOOLEAN)

If these are set true then the next use of the compare method will perform these functions.

Integrator link information stored on CYMLNK elements includes references to the linked elements. It is possible during project execution for these references to become invalid when elements are deleted. A method is provided to clean up CYMLNK elements with invalid references.

!!Integrator.validateLinks()

Caution: This method should be used only when all of the databases holding elements that have been linked are current on the MDB.

The following method can be used to clear the Integrator 3D graphical view drawlist:

!!integratorSupportHandler.intdrawlist().removeall()

Comparison Summary Methods

The following method has been provided to return the Compare Summary statistics following a comparison run from the command line:

!subTotals       = ARRAY()

!typeCategory    = ARRAY()

!compareCategory = ARRAY() 

!!integrator.getCompareSummary(!subTotals is ARRAY, 
!typeCategory is ARRAY, !compareCategory is ARRAY)

The three arrays must be declared empty as shown before this method is called as the statistics are output to these arrays. The subtotal values are returned as a 2D array of [type category, compare category] aligned as per the Comparison Category form layout. The other two arrays return the type and compare category texts as per the same form. For valid combinations of type and category that have been switched off, the subtotal value returned is -1. For combinations that are not applicable (for example Sequence Mismatch on an Equipment) the subtotal value returned is -2.

A simplified interface to these statistics has also been provided. The following method handles the individual arrays internally and returns the summary text as an array of strings. It ignores any categories where none were found, the category was switched off, or was not applicable. The strings are returned as comma separated values for the category and the total:

!!integratorSupportHandler.compareSummary() is ARRAY

The following method runs the above method internally and prints the summary to the command line, formatted to match the summary as seen interactively:

!!integratorSupportHandler.printSummary()

Note:

The command line summary methods will return values only for the last comparison run from the command line, or for the last comparison run interactively whilst the report is still open.

Accept Differences Methods

A set of methods provide command line access to the functionality for accepting differences.

The following methods can be used to create an acceptance GPWL in a named database or in the first writable database, create an acceptance GPSET, and select an acceptance GPSET to be active.

!!integrator.createAcceptanceGPWLD(!GPWLDName is STRING, !Description is STRING, !OwnerDB is STRING)

!!integrator.CreateAcceptanceGPWLD(!GPWLDName is STRING, !Description is STRING)

!!integrator.CreateAcceptanceGPSET(!GPSETName is STRING, !Description is STRING, !OwnerGPWLD is STRING)

!!integrator.SelectAcceptanceGPSET(!GPSETName is STRING)

The following methods can be used to accept differences on an element or accept a missing element. The methods without the flag are equivalent to the corresponding methods with the flag set true. Setting the flag false has the effect of reversing any acceptance.

!!integrator.AcceptDifferences(!Name is STRING)

!!integrator.AcceptDifferences(!Name is STRING, !Flag is BOOLEAN)

!!integrator.AcceptMissingElement(!Name is STRING)

!!integrator.AcceptMissingElement(!Name is STRING, !Flag is BOOLEAN)

!!integrator.AcceptMissingElement(!Name is STRING, !Flag is BOOLEAN, !IncludeConnectedBranch is BOOLEAN)

The following methods can be used to disable or enable matching on an element. Setting the flag false has the effect of disabling matching.

!!integrator.DisableMatching(!Name is STRING)

!!integrator.EnableMatching(!Name is STRING)

!!integrator.EnableMatching(!Name is STRING, !Flag is BOOLEAN)

!!integrator.EnableMatching(!Name is STRING, !Flag is BOOLEAN, !IncludeConnectedBranch is BOOLEAN)

The following methods can be used to return a report of all accepted differences as an array of strings, or to print it out in the command window.

!arrayOfStrings = !!integratorSupportHandler.acceptedDifferences() 

!!integratorSupportHandler.printAllAccepted()

Diagram Viewer Methods

The MMViewer object provides diagram viewer methods. To use these methods the following initialisation is required at the top of each PML file (object, function or macro) where these methods are used.

import 'MMservices'

handle any

endhandle

The following initialisation is also required in each method or function where the diagram methods are to be called.

using namespace 'Aveva.PDMS.MMServices'

!mmViewer = object mmViewer()

The following methods can be used to clear colours and close the current or all diagrams.

!mmViewer.resetDiagramColours()

!mmViewer.resetAllDiagramColours()

!mmViewer.closeDiagram()

!mmViewer.closeAllDiagrams()

The findOnDrawing method opens the diagram for one or more schematic elements and highlights them.

Note:

That the argument is an array. If an object appears on more than one diagram, the user will be prompted to choose which diagram to open.

!mmViewer.findOnDrawing (!Name is STRing)

!mmViewer.findOnDrawing (!Name is ARRAY)

This example shows how to view the linked schematic object for the current element in 3D.

			!mmViewer.findOnDrawing (!!ce.schlnk.ref.string ())

Individual schematic elements can be coloured on the diagram view using the following methods.

Note:

These methods do not open a diagram or select an object.

The results will be visible only if the relevant diagram is already open in the viewer.

!mmViewer.setColour (!Name is STRING, !Colour is STRING)

!mmViewer.setColour (!Name is STRING, !Colour is REAL)

The following method returns a Diagram Page object for the diagram page name of the form <Diagram Name>Page-<Page Number>, for example A0-01-2012-0001 Page-1, such as would be returned by the Integrator diagramList method.

!!mmViewer.diagramPage(!page is STRING) is DIAGRAMPAGE

The following method saves the diagram page to pdf file:

!diagramPage.saveAsPDF(!filename is STRING)

Example Compare Macro

Below is a complete example macro that compares all schematic equipment and pipelines that appear on a particular diagram. It then saves the side-by-side details to Excel and the coloured diagrams to pdf files.

-- File: IntegratorUserGguide.pmlmac

-- Initialise Integrator

import 'MMServices'

handle any

endhandle

using namespace 'Aveva.Pdms.MMServices'

!!mmViewer = object mmViewer()

!!integratorInit()

-- Collect schematic equipment and pipelines that appear on this diagram

!diagram = |/A0-01-2012-0001|

var !items collect all SCEQUI

var !items append collect all SCPLIN

var !diaref evaluate diaref for all from !items

!comlist = ARRAY()

do !i index !items

if (match(!diaref[!i], !diagram) gt 0) then

!comlist.append(!items[!i])

endif

enddo

-- Set report direct to file and do compare

!!integrator.setreportvisible(false)

if (!comlist.size() gt 0) then

!!integrator.compare(!comlist)

handle any

write !!error.text

elsehandle none

    -- Write out the compare summary

    !!integratorSupportHandler.printSummary()

    -- View the report unless running in non graphics mode

    if (not istty) then

!file = object FILE('C:\Aveva\report.xml')

if (!file.exists()) then

!!integrator.openreport()

endif

    -- Generate compare Excel report and colour coded diagram pdf

    !!integrator.saveAsExcel('C:\Aveva\report.xlsx')

!!integrator.openAllReferencedDiagrams()

!list = !!integrator.diagramlist()

do !page values !list

!diagramPage = !!mmViewer.diagramPage(!page)

!diagramPage.saveAsPDF('C:\Aveva\' & !page)

enddo

endhandle

endif

Manage Links Methods

Note:

This method should be used only when all of the databases holding objects that have been linked are current on the MDB.

The MMManageLinks object provides a method to validate and clean uplinks. To use this method the following initialisation is required at the top of each PML file (object, function, or macro) where this method is to be used.

import 'MMservices'

handle any

endhandle

The following initialisation is also required in each method, function or macro where the method is to be called.

using namespace 'Aveva.Pdms.MMServices'

!!mmManageLinks = object mmManageLinks()

The validate method returns a BOOLEAN which will be TRUE if there are no links with invalid references, or FALSE if there are link objects with invalid references, such as may have occurred when objects have been deleted. It also outputs a list of links and any errors to the command line.

Note:

The validate method is not read only; it merges partially populated links, for example, 3D object "A" is linked to schematic object "A" by one link and schematic object "A" is linked to engineering object "A" by another link, as can occur when links are created in separate extract databases. This merging has to occur before it can check for invalid links.

!foundInvalidLinks = !!mmManageLinks.validate().not()

The removeInvalidLinks method deletes any link objects with invalid references.

!!mmManageLinks.removeInvalidLinks()

Note:

The MMManageLinks object is not available in 12.1.SP4, use the following integrator object instead:

•

Use the equivalent initialisation

!!integratorInit()

•

Use the equivalent method:

!!Integrator.validateLinks()