Klocwork Architect scripting commands

From Insight-9.2

Contents

You can use the scripting interface commands described in this section to write scripts that work with Architect models.

The commands are written in standard tool command language (TCL) version 8.0 (a Sun Microsystems scripting language), with some Klocwork enhancements. The enhancements are described in detail in the remainder of this section.

Scripts can be useful in automating repetitive tasks or performing a repeatable set of actions on a number of projects. You may also wish to use these commands to modify scripts created from actual Architect editing sessions.

For details on how to run Architect scripts, see Using Architect scripts.

Note: If you set the value of the variable INTERRUPT_MODE to "YES" (set INTERRUPT_MODE YES), the script will be interrupted if some command cannot be completed or returns an exceptional value.

The following scripting commands use parameters such as eid (entity identifier) and kid (kind identifier). A number of the scripting commands return these identifiers, for example:

  • <eid> To get an entity identifier (eid) parameter used in many of the commands that follow, use the command 24. getBlocks, 25. getBlocksEids <name-kind-list>, or 18. getBlockEid <name> <kind>.
  • <ident> An identifier is a code entity such as a variable, type or method. You can find specific identifiers in a Flowchart view or by searching in Architect.

addBlock <name> <kind>

Parameters: <name> - String, <kind> - String

Action: Adds to the current diagram the block with the given name <name> and the given kind <kind>.

Return value: none

Examples: addBlock bbb ARCHITECTURE-BLOCK

attachScript <file-name> <menu-item-name>

Parameters: <file-name> - String, <menu-item-name> - String

Action: Attaches script specified by <file-name> to the Scripts menu item represented by <menu-item-name>.

Return value: none

Examples: attachScript myScript3 Script3

changeBlockName <eid> <name>

Parameters: <eid> - Integer, <name> - String

Action: In the current diagram, changes the name of the block with the given entity identifier <eid> to the name <name>.

Return value: none

Examples: changeBlockName [getBlockEid INCLUDES DIRECTORY] ccc

contractBlock <eid>

Parameters: <eid> - Integer

Action: Performs a contract operation for the block with the given entity identifier <eid> in the current diagram.

Return value: none

Examples: contractBlock 7

copyBlocks <blocks-paths-list>

Parameters: <blocks-paths-list> - List of elements <block-path>, <block-path> - List of pairs {<name> <kind>}, <name> - String, <kind> -String

Action: Copies blocks represented by <blocks-paths-list> from the System Model to the current diagram of the current view.

Return value: none

Examples: copyBlocks {{{"System Model" ARCHITECTURE-BLOCK} {"GCC-INCLUDES" DIRECTORY}} {{"System Model" ARCHITECTURE-BLOCK} {"INCLUDES" DIRECTORY}}}

createRelationshipProfile <name> <relations-list>

Parameters: <name> - String, <relations-list> - List of elements <relation>, <relation> - String

Action: Creates the relationship profile with the given name <name> and consisting of the given list of relationship types <relations-list>.

Return value: none

Examples: createRelationshipProfile "My profile" {INCLUDES CLASS-METHOD_CALLS_CLASS-METHOD DECLARED-BY CLASS-METHOD_WRITES_CLASS-DATA-MEMBER}

createCustomDiagram <name>

Parameters: <name> - String

Action: Creates a custom diagram with the given name <name>.

Return value: none

Examples: createCustomDiagram my_view

cutBlocks <eid-list>

Parameters: <eid-list> - List of elements <eid>, <eid> - Integer

Action: Cuts (removes and copies to the clipboard) the entities with the given entity identifiers <eid> in the current diagram.

Return value: none

Examples:

cutBlocks {24 7}

cutBlocks [getBlocksEids {{INCLUDES DIRECTORY} {SOURCES DIRECTORY}}]

dehighlightBlock <eid>

Parameters: <eid> - Integer

Action: Removes the highlight from the block with the corresponding entity identifier <eid> in the current diagram.

Return value: none

Examples: dehighlightBlock 3

dehighlightBlocks

Parameters: none

Action: Removes the highlight from all blocks in the current diagram.

Return value: none

Examples: dehighlightBlocks

dehighlightEdges

Parameters: none

Action: Removes the highlight from all edges in the current diagram.

Return value: none

Examples: dehighlightEdges

deleteBlocks <eid-list>

Parameters: <eid-list> - List of elements <eid>, <eid> - Integer

Action: Permanently deletes the entities with the given entity identifiers <eid> in the current diagram.

Return value: none

Examples: deleteBlocks {24 7}

enterBlock <eid>

Parameters: <eid> - Integer

Action: Enters the block with the given entity identifier <eid> in the current diagram.

Return value: none

Examples:

enterBlock 3

enterBlock [findBlockParent 6]

enterParent

Parameters: none

Action: Opens the parent diagram of the current diagram.

Return value: none

Examples: enterParent

expandBlock <eid>

Parameters: <eid> - Integer

Action: Performs an expand operation on the block with the given entity identifier <eid> in the current diagram.

Return value: none

Examples: expandBlock 7

explodeBlocks <eid-list>

Parameters: <eid-list> - List of elements <eid>, <eid> - Integer

Action: Performs an explode operation on the entities with the given entity identifiers <eid> in the current diagram.

Return value: none

Examples: explodeBlocks [getBlocksEids {{INCLUDES DIRECTORY} {usr DIRECTORY}}]

findBlockParent <eid>

Parameters: <eid> - Integer

Action: Returns the entity identifier <eid> of the block in the current diagram and which is the transitive parent of the block with the given <eid>.

Return value: Integer

Examples: findBlockParent 6

getBlockEid <name> <kind>

Parameters: <name> - String, <kind> - String

Action: Returns the entity identifier of the block named <name> and the given kind <kind> in the current diagram

Return value: Integer

Examples: puts stdout [getBlockEid INCLUDES DIRECTORY]

getBlockName <eid>

Parameters: <eid> - Integer

Action: Returns the name of the block with the given entity identifier <eid>.

Return value: String

Examples: puts stdout [getBlockName 24]

getBlockFullName <eid>

Parameters: <eid> - Integer

Action: Returns the name of the block with the given <eid>. For a block which is not a file, return its name. For a file, return its path, if this path is present in the map file.

Return value: String

Examples: puts stdout [getBlockFullName 24]

getBlockKind <eid>

Parameters: <eid> - Integer

Action: Returns the kind of the block with the given entity identifier <eid>.

Return value: String

Examples:

puts stdout [getBlockKind 24]

puts stdout [getBlockKind [lindex [getBlocks] 0]]

getBlockLocation <eid>

Parameters: <eid> - Integer

Action: Returns the coordinates of the block with the corresponding entity identifier <eid> in the current diagram.

Return value: List of pairs {<x> <y>}, <x> - Integer, <y> - Integer

Examples: puts stdout [getBlockLocation [getBlockEid SOURCES DIRECTORY]]

getBlockSize <eid>

Parameters: <eid> - Integer

Action: Returns the size of the block with the corresponding entity identifier <eid> in the current diagram.

Return value: List of pairs {<width> <height>}, <width> - Integer, <height> - Integer

Examples: puts stdout [getBlockSize [getBlockEid SOURCES DIRECTORY]]

getBlocks

Parameters: none

Action: Returns the list of entity identifiers of the entities in the current diagram.

Return value: List of Integers

Examples: puts stdout [getBlocks]

getBlocksEids <name-kind-list>

Parameters: <name-kid-list> - List of pairs {<name> <kind>}, <name> - String, <kind> - String

Action: Using the list of pairs {<name> <kind>} (in which <name> and <kind> are strings representing the name and the kind of the block) returns the list of entity identifiers of the entities with the given names and kinds in the current diagram.

Return value: List of Integers

Examples: puts stdout [getBlocksEids {{INCLUDES DIRECTORY} {SOURCES DIRECTORY}}]

getCurrentBlock

Parameters: none

Action: Returns the entity identifier <eid> of the currently selected block. If no block is currently selected, getCurrentBlock returns -1 (not an <eid>).

Return value: Integer

Examples: puts stdout [getCurrentBlock]

getEdgeDetail <from-eid> <to-eid> <mode>

Parameters: <from-eid> - Integer, <to-eid> - Integer, <mode> - 0 or 1

Action: Returns the list from the Relationship Viewer for the edge that goes from the block with the given <from-eid> to the block with the given <to-eid>. If <mode> equals 1, the Relationship Viewer opens in the "Relationships" mode. If <mode> equals 0, the Relationship Viewer opens in the "Interfaces" mode.

Return value:

If mode is 1 - List of elements: {<relationship-type-kid> <identifier-eid> <in-file1-eid> <uses-identifier-eid> <in-file2-eid>}, <relationship-type-kid> - Integer, <identifier-eid> - Integer, <in-file1-eid> - Integer, <uses-identifier-eid> - Integer, <in-file2-eid> - Integer;

If mode is 0 - List of elements: {<uses-identifier-eid> <in-file-eid> <density>}, <uses-identifier-eid> - Integer, <in-file-eid> - Integer, <density> - Integer

Examples: puts stdout [getEdgeDetail 3 4 1]

getEdges

Parameters: none

Action: Returns the list of edges that are visible at this moment in the current diagram (edge is the list: {<from-eid> <to-eid> <from-density> <to-density>})

Return value: List of elements:

{<from-eid> <to-eid> <from-density> <to-density>}, <from-eid> - Integer, <to-eid> - Integer, <from-density> - Integer, <to-density> - Integer

Examples: puts stdout [getEdges]

getEnvironmentVariableValue

Parameters: environment variable name

Action: provides access to USER and SYSTEM environment variables from TCL interpreter. Variables may be needed for some scripts on Windows machines.

Return value: environment variable value

Example: puts stdout [getEnvironmentVariableValue "TEMP"]

Example: executing a script:

set INTERRUPT_MODE YES

openModel "System Model"

puts stdout [getEnvironmentVariableValue "PATH"]

puts stdout ----"The_End"

getHighlightedBlocks

Parameters: none

Action: Returns the list of entity identifiers <eid> of the highlighted blocks in the current diagram.

Return value: List of Integers

Examples: puts stdout [getHighlightedBlocks]

getHighlightedEdges

Parameters: none

Action: Returns the list of highlighted edges in the current diagram. (An edge is the list: {<from-density> <to-eid> <from-density> <to-density>}.)

Return value: List of elements: {<from-eid> <to-eid> <from-density> <to-density>}, <from-eid> - Integer, <to-eid> - Integer, <from-density> - Integer, <to-density> - Integer

Examples: puts stdout [getHighlightedEdges]

getRelationshipKindName <kid>

Parameters: <kid> - Integer

Action: Returns the description of the kind with the given <kid>.

Return value: String

Examples: getRelationshipKindName 8

getRelationshipProfile

Parameters: none

Action: Returns the name of the current relationship profile.

Return value: String

Examples: puts stdout [getRelationshipProfile]

getRelationshipProfileKinds <name>

Parameters: <name> - String

Action: Returns the list of relationship types with respect to the relationship profile with the given name <name>.

Return value: List of Strings

Examples: puts stdout [getRelationshipProfileKinds "Call graphs"]

groupBlocks <eid-list> <name>

Parameters: <eid-list> - List of elements <eid>, <eid> - Integer

Action: Groups the entities with the given entity identifiers <eid> in the current diagram to the architecture block with the name <name>.

Return value: none

Examples: groupBlocks [getBlocksEids {{local DIRECTORY} {Develop DIRECTORY}}] aaa

highlightBlock <eid>

Parameters: <eid> - Integer

Action: Highlights the block in the current diagram with the given entity identifier <eid>.

Return value: none

Examples:

highlightBlock 3

highlightBlock [findBlockParent 6]

highlightEdge <from_eid> <to_eid>

Parameters: <from_eid> - Integer, <to_eid> - integer

Action: In the current diagram, highlights the edge between the block with the given <from_eid> and the block with the given <to_eid>.

Return value: none

Examples: highlightEdge 3 7

layoutDiagram <eid-x-y-width-height-list>

Parameters: <eid-x-y-width-height-list> - List of elements: {<eid> <x> <y> <width> <height>}, <eid> - Integer, <x> - Integer, <y> - Integer, width> - Integer, <height> - Integer

Action: Sets coordinates and sizes of the blocks which have the corresponding eids and are placed in the current diagram to the corresponding <x>, <y>, <width> and <height> in the current diagram.

Return value: none

Examples: layoutDiagram [list [list [getBlockEid usr DIRECTORY] 138 132 200 100] [list [getBlockEid SOURCES DIRECTORY] 152 40 150 50]]

moveBlocks <blocks-paths-list> <new-parent-path>

Parameters: <blocks-paths-list> - List of elements <block-path>, <block-path> - List of pairs {<name> <kind>}, <name> - String, <kind> -String; <new-parent-path> - List of pairs {<name> <kind>}, <name> - String, <kind> -String

Action: Moves blocks represented by <blocks-paths-list> to the new parent diagram, represented by <new-parent-path>.

Return value: none

Examples: moveBlocks {{{"System Model" ARCHITECTURE-BLOCK} {"GCC-INCLUDES" DIRECTORY}} {{"System Model" ARCHITECTURE-BLOCK} {"INCLUDES" DIRECTORY}}} {{"System Model" ARCHITECTURE-BLOCK} {"SOURCES" DIRECTORY}}

openDiagram <eid>

Parameters: <eid> - Integer

Action: Opens the diagram with the given value <eid>.

Return value: none

Examples: openDiagram 5

openDiagramByPath <name-kid-list>

Parameters: <name-kid-list> - List of pairs {<name> <kind>}, <name> - String, <kind> - String

Action: Opens the diagram which is the tail of the given path.

The path is the list of pairs {<name> <kind>} (in which <name> and <kind> are strings representing the name and the type of the block) and is the path from the root diagram.

Return value: none

Examples:

openDiagramByPath {{System_view ARCHITECTURE-BLOCK}

{INCLUDES DIRECTORY} {Develop DIRECTORY} {REP-5.0 DIRECTORY} {sources DIRECTORY}}

openModel <name>

Parameters: <name> - String

Action: Opens the model with the given name <name>.

Return value: none

Examples: openModel System_view

pasteBlocks

Parameters: none

Action: Pastes entities on the clipboard (previously cut from a diagram) into the current diagram.

Return value: none

Examples: pasteBlocks

redo

Parameters: none

Action: Redoes the last undone edit operation.

Return value: none

Examples: redo

saveModel <name>

Parameters: <name> - String

Action: Saves the model with the name <name>.

Note: A model with the given name must not already exist.

Return value: none

Examples: saveModel my3

setBlockLocation <eid> <x> <y>

Parameters: <eid> - Integer, <x> - Integer, <y> - Integer

Action: Sets the coordinates of the block with the given entity identifier <eid> in the current diagram to (<x>, <y>).

Note: If you attempt to set coordinates that are invalid, for example, negative coordinates; Architect sets the coordinates to zero.

Return value: none

Examples: setBlockLocation [getBlockEid SOURCES DIRECTORY] 138 132

setBlockSize <eid> <width> <height>

Parameters: <eid> - Integer, <width> - Integer, <height> - Integer

Action: In the current diagram, sets the size of the block with the given eid to (<width>, <height>).

Note: If this is impossible, sets size to the nearest valid size.

Return value: none

Examples: setBlockSize [getBlockEid SOURCES DIRECTORY] 200 100

setBlocksLocations <eid-x-y-list>

Parameters: <eid-x-y-list> - List of elements: {<eid> <x> <y>}, <eid> - Integer, <x> - Integer, <y> - Integer

Action: Sets the coordinates of the entities with the corresponding entity identifiers to the corresponding <x> and <y> coordinates in the current diagram.

Return value: none

Examples: setBlocksLocations [list [list [getBlockEid usr DIRECTORY] 138 132] [list [getBlockEid SOURCES DIRECTORY] 152 40]]

setBlocksSizes <eid-width-height-list>

Parameters: <eid-width-height-list> - List of elements: {<eid> <width> <height>}, <eid> - Integer, <width> - Integer, <height> - Integer

Action: Sets the sizes of the blocks with the corresponding eids to the corresponding <width> and <height> in the current diagram.

Return value: none

Examples: setBlocksSizes [list [list [getBlockEid usr DIRECTORY] 200 100] [list [getBlockEid SOURCES DIRECTORY] 150 50]]

setRelationshipProfile <name>

Parameters: <name> - String

Action: Sets the profile with the given name <name> as the current relationship profile.

Return value: none

Examples: setRelationshipProfile "Call graphs"

showEdgeDetail <from-eid> <to-eid> <mode>

Parameters: <from-eid> - Integer, <to-eid> - Integer, <mode> - 0 or 1

Action: Shows the Relationship Viewer for the edge that goes from the block with the given <from-eid> to the block with the given <to-eid>. If <mode> equals 1, the Relationship Viewer opens in the "Relationships" mode. If <mode> equals 0, the Relationship Viewer opens in the "Interfaces" mode.

Return value: none

Examples: showEdgeDetail 3 4 1

trackBlock <eid>

Parameters: <eid> - Integer

Action: Finds the block with the given <eid> and highlights this block in the parent diagram.

Return value: none

Examples:

trackBlock 7

trackBlock [findBlockParent 6]

trackBlock <file> <ident> <line>

Parameters: <file> - String, <ident> - String, <line> - Integer

Action: Finds and highlights (on the parent diagram) the block which presents the identifier with name <ident> which is present in the file <section> on line number <line>.

Return value: none

Examples: trackBlock tk.h TK_RELEASE_LEVEL 42

undo

Parameters: none

Action: Undoes the last edit operation.

Return value: none

Examples: undo

See also