Imagix 4D User Guide


Appendix B. Batch Mode Commands

In addition to operating as a gui-based application, Imagix 4D can be run as a command line batch process. This is most useful for major, repetitive tasks, such as regenerating project data or generating documentation, that you'd like to run as scheduled batch operations.

By invoking Imagix 4D as `imagix -cmmd cmmd_file_name', you can run Imagix 4D as a batch process. In this mode, Imagix 4D will start, execute the commands specified in the command file cmmd_file_name, and then terminate.

The following is a description of the available commands. For the most complete documentation, including a description of the associated report settings, see the file ../imagix/user/user_cmd.txt in your Imagix 4D installation.


There are several procedures available for use in a command file:

cmmdOpenProjectto open a project
cmmdUpdateProjectDatato update a project
cmmdRegenerateProjectDatato regenerate a project
cmmdCreateRevisionto create a delta revision
cmmdLoadDeltaRevisionto load an existing delta revision
cmmdLoadDeltaOtherProjectto load an existing delta project
cmmdDeleteArchitectureto delete an existing architecture
cmmdDefineArchitectureto define a new architecture
cmmdReportto output a report
cmmdReportFileto output a report about a specific file
cmmdReportClassto output a report about a specific class
cmmdReportMultipleto output multiple reports
cmmdReportExportto output a report for future import
cmmdReportFileExportto output a file report for future import
cmmdReportClassExportto output a class report for future import
cmmdReportExportMultipleto output multiple reports for future import
cmmdMetricsto output metrics
cmmdCalcMetricsto calculate but not output metrics
cmmdDocumentto output a document
cmmdDebugto create a debug trace

Projects and Updates

cmmdOpenProject project_name

This procedure opens project project_name. project_name must be an already existing project. This is equivalent to the Open Project function (File > Open Project).

cmmdUpdateProjectData

This procedure causes the currently open project to be updated. This is equivalent to the Update Project Data function (Project > Update Project Data).

cmmdRegenerateProjectData

This procedure causes the currently open project to be regenerated. This is equivalent to the Regenerate Project Data function (Project > Regenerate Project Data).

Delta Analysis Revisions

cmmdCreateRevision description [ revision_id ]

This procedure causes a delta analysis revision to be generated for the currently open project. This is equivalent to the Project > Create Revision menu item. If there are spaces in the description, the entire description should be enclosed in double quotes ("). The same is true for the revision_id.

cmmdLoadDeltaRevision revision

This procedure causes the specified revision to be loaded for the currently open project. This is equivalent to the Compare to Revision tab of the Project > Load Revision for Delta Analysis menu item.

revision can be specified as the Revision Created string in the Revision Information part of the gui dialog, for example "02 Aug 2015 (06:02)". Double quotes (") are required.

Alternatively, revision can be specified as the file name of the equivalent revision file residing in the ../project.4D/revisions directory, for example 1438520507.

A revision must be loaded before any delta analysis reports can be run.

cmmdLoadDeltaOtherProject project_name

This procedure causes the current status of project_name to be loaded for delta analysis with the currently open project. This is equivalent to the Compare to Other Project tab of the Project > Load Revision for Delta Analysis menu item.

project_name must be an already existing project, and must contain an externally available revision. This is equivalent to the Load Project button being enabled in the gui dialog. If it is not enabled, the Create Revision button should be run through the gui dialog.

A revision must be loaded before any delta analysis reports can be run.

Subsystem Architectures

cmmdDeleteArchitecture arch_name

This procedure deletes an existing architecture named arch_name. If no architecture is found with that name, issues a warning.

This can be used with the cmmdDefineArchitecture to insure that an architecture definition is synchronized with the source code, following a cmmdUpdateProjectData or cmmdRegenerateProjectData.

cmmdDefineArchitecture hierarchy type arch_name

This procedure causes a new architecture to be defined for the currently open project.

hierarchy specifies the container hierarchy to represent in the architecture. Valid settings are {Directory | Namespace | Package}.

type specifies the lowest level symbol types to include in the architecture. Valid settings are {Func | FuncVar}.

arch_name specifies a name to associate with the architecture. It must not be a name used for any of the existing architectures.

Reports

cmmdReport report_name [ file_name ]
cmmdReportExport report_name [ file_name ]

These procedures cause report report_name to be output to the file file_name. When cmmdReportExport is used instead of cmmdReport, the resulting file includes the special data section so that the file can later be imported back into Imagix 4D and appear with all of the symbol names fully tagged for browsing and navigation.

report_name is derived from the name of the report as it appears under the Reports menu. Spaces need to be converted to underscores, and format alternatives need to be separated by two periods. For example, Reports > Similar Functions becomes Similar_Functions, and Reports > Source Checks > Expressions > Conversion Issues becomes Source_Checks..Conversion_Issues.

file_name is the full path name of a file. If file_name is omitted, cmmdReport outputs to the file or pipe as was specified in the Print dialog, the last time Imagix 4D was invoked in interactive (normal) mode. In this case, in your command file, you may want to set the variables that control printing before you invoke cmmdReport. These variables correspond to the selections available in the Print dialog. Setting these variables will cause the settings from the previous interactive session to be overwritten.

VariableSettings
vtgPrint(Comment)string
vtgPrint(Output){ ToFile | PipeTo }
vtgPrint(PipeTo)string
vtgPrint(FileName)file_name

For Windows, setting vtgPrint(Output) to PipeTo is equivalent to selecting `To Default Printer' in the Print dialog.

Many of the reports have a number of optional settings. By default, cmmdReport uses the settings from the last time Imagix 4D was invoked in interactive (normal) mode. You can explicitly control these settings in the command file, using the variables listed in the file ../imagix/user/user_cmd.txt.

cmmdReportFile file report_name [ file_name ]
cmmdReportFileExport file report_name [ file_name ]
cmmdReportClass class report_name [ class_name ]
cmmdReportClassExport class report_name [ class_name ]

These procedures are variations on cmmdReport and cmmdReportExport, supporting reports that are available by right clicking on a file or class and bringing up the context sensitive menu.

file is the name of the file focus for the report. Specification of the full path name is optional, but will ensure the correct instance when multiple files have the same name.

class is the name of the class focus for the report.

report_name is the name of the report as it appears in the the context sensitive menu. Spaces need to be converted to underscores. For example, Open New > Reports > Delta Analysis becomes Delta_Analysis.

cmmdReportMultiple [ directory_name [ report_list [ skip_list ]]]
cmmdReportExportMultiple [ directory_name [ report_list [ skip_list ]]]

These procedures cause each specified report to be output to a file in the directory directory_name. When cmmdReportExportMultiple is used instead of cmmdReportMultiple, the resulting files include the special data section so that the files can later be imported back into Imagix 4D and appear with all of the symbol names fully tagged for browsing and navigation.

The name of the output file is generated automatically. If directory_name is omitted, the reports will be output to the reports subdirectory within the directory where the current project (the project opened via cmmdOpenProject) is located.

By default, cmmdReportMultiple runs all reports that appear under the Reports menu. You can limit which specific reports are run through report_list and skip_list. For each report, use the report_name format as specified for cmmdReport. Enclose each list is curly braces, for example {Similar_Functions Source_Checks..Conversion_Issues}. If you want to generate all reports except those specified in skip_list, use {} or all for the report_list argument.

Software Metrics

cmmdMetrics [ directory_name [ symbol_type_list ]]
cmmdCalcMetrics [ symbol_type_list ]

The cmmdMetrics procedure exports symbol metrics into files using a comma-separated values (csv) format. A separate file is created for each type of symbol having a metric.

The name of the output file is generated automatically. If directory_name is omitted, the reports will be output to the metrics subdirectory within the directory where the current project (the project opened via cmmdOpenProject) is located.

The cmmdCalcMetrics procedure calculates, but does not export, symbol metrics. It is an alternative to cmmdMetrics that is only useful when the project size setting for Imagix 4D is set to Very Large, so that the calculated metrics are stored in the database between sessions. (See the section on Project Resources in the User Guide for more info).

By default, both procedures generate metrics for all the metrics categories that appear under the Reports menu. You can limit which metrics files are generated through symbol_type_list. The default value of symbol_type_list, for all six symbol types, is {directory file namespace class function variable}.

Document Generation

cmmdDocument [ directory_name ]

This procedure causes documentation to be generated into the directory directory_name. If directory_name is omitted, output is directed to a directory ( ../project_name.4DD ) based on where the current project (the project opened via cmmdOpenProject) is located.

Document dialog settings are retained between sessions. By default, these are used when generating documentation. If you want to use different settings, you can specify the desired settings in a DocGen sheet, and apply that sheet for the document generation process. The following variables control document settings controlled outside of the DocGen sheets. Certain combinations of Format and File are incompatible, as indicated in the Document dialog.

VariableSettings
dcgOptions(Style){ UseOptionsSettings | ApplyDocGenSheet }
dcgOptions(DocGenSheet)file_name_of_.dgn_file
dcgOptions(Format) { ASCII | RTF | HTML }
dcgOptions(File) { SingleFile | FileperSection | FileperSymbol }

Support

cmmdDebug [ contents [ crashsppt [ tracefile ]]]

This procedure duplicates the debug trace support enabled through the File > Options > Behavior and Appearance > Technical Support dialog. The resulting trace file can be useful for refining command files, particularly when used in conjunction with dbgf commands.

contents must be one of the selections from the content selections from the dialog, or Off which is equivalent to disabling the debug trace; it defaults to Essentials. crashsppt must be 0 or 1; it defaults to 1. tracefile must be a file in a currently existing directory; it defaults to the location displayed in the Technical Support dialog.