TICSMaintenance

TICSMaintenance is the TICS maintenance application. It is used for a great variety of maintenance tasks such as new project creation, setting configuration properties, and, database maintenance.

TICSMaintenance runs for the project specified on the command line via the -project option, or for all projects specified in the PROJECTS.yaml configuration file in case of -allprojects.

Synopsis

TICSMaintenance [option...] -project project|-allprojects

The following TICSMaintenance options are allowed.

-allprojects
execute the specified maintenance actions for all projects in the SERVER.yaml/PROJECTS.yaml
-archivefile archivefilename
the 'ARCHIVE'-file used for the archive extraction. (Only used in combination with -listarchiveresult)
-backup
make a backup of the project database
-branchdir dir
specify the root directory of the source files for the branch
-branchname branch name
specify the name of the branch to set one of the following properties: -branchdir, -calculate, -rename or -visible
-calc metric
one or more (comma separated) metric type(s)
-calculate [0|1]
specify whether the branch should be analyzed
-checkchk
check the TICS checkers for faults
-checkconfig
check the TICS configuration
-cleanupdatabase
shrink the database by removing unused meta data from the database (only available for Firebird databases)
-clonebranchname name
specify the branch name in the original database when cloning to a different branch name
-clonedb name
specify the name of the database to clone
-create
create project specified with -project and/or create a branch if -branchname and -branchdir are given
-custom custom module name
executes custom module TICSCustomname.pm in the cfg directory
-dbhealthcheck
check project db consistency
-detach
forcefully disconnect other processes from the project database
-dirlisting inputfile
a file containing a list of directories which should be used to generate the archive expression. (Only used in combination with option -genarchiveexpression)
-err file
write error messages to the specified file
-finalize
create finalization (viewer) tables for the project specified by -project
-from yyyy-mm-dd[ hh:mm:ss]
date/time in ISO format
-fsdest dir
optional destination for artifacts created by the -fsupload option
-genarchiveexpression
generate a 'DIR'-expression for the 'ARCHIVE'-file based on a file containing the directories which TICS has to process. (Specified with -dirlisting)
-gendbinfo
generate the dbinfo for the project
-gensqareports
generate and mail SQA reports for all branches of the project
-genviewercache
generate the viewer cache for the project
-getbaseline name
get baseline name for the given project and branch
-getscmidcontents revisionid
get contents of a given SCM ID for a given file. Used together with option -srcfile.
-help
show this help info
-info
show configuration and project details
-list
list project name and database version
-listarchiveresult
list all directories that will be processed by TICS based on the 'DIR'-expression in the 'ARCHIVE'-file. (Optionally the 'ARCHIVE'-file can be specified with -archivefile)
-listruns
list the last 20 runs for a branch of a project
-log int
show diagnostic messages upto the specified log level
-logdir dir
use the specified directory for server log files
-lowpriority
run TICS with low priority
-machineid
obtain a unique machine ID
-nobackup
do not make a backup before maintaining the database (not recommended)
-nocalc metric
one or more (comma separated) metric type(s)
-nocheckconfig
do not check the TICS configuration
-noconfirm
do not interactively ask the user to confirm when using -fsupload
-noclobber
do not overwrite the global log file (but append to it instead)
-nologo
suppress TICS logo output
-nowarn
suppress all warnings
-project name
specify the name of the database to maintain
-recalclangforfilename
recalculate the language for all filenames in the database
-remove
delete a project or, if -branchname is specified, delete a branch from the database (use with care)
-removebaseline name
removes a baseline from the database
-removerun
remove a specific run from the database
-removeunreferencedfilenames
remove entries from FileName that have no corresponding entry in FileLifeCycle
-rename new project name|branch name
rename a project or, if -branchname is specified, rename a branch to the given name
-renamebranchdirs [+-]subpath
rename branch directories in the database; remove(-) or add(+) the given subpath from/to each branch directory. E.g., -renamebranchdirs +/system/ appends /system/ to all branch directories
-renamefilenames frompath-topath
rename filenames that match the frompath pattern with the topath replacement value in the database. E.g., -renamefilenames "^A/B/C/-A/B/D/" renames all files under directory "A/B/C" to "A/B/D"
-saveqsmail dir
save a QServer status mail for the project in specified directory
-senderrormail
send a QServer error mail for the project
-sendqsmail
send a QServer status mail for the project
-setbaseline name[,delta:(0|1)][,plotline:(0|1)]
set baseline name for a branch. Defaults: delta:1,plotline:1. You also need to specify option -timestamp.
-setfilefilters [filter:value,]+
set (one or more) file filters
-setmetrics [metricname:value,]+
configure (one or more) metrics for a project
-setproppath [proppath=value;]+
set a property in the configuration; proppath is a '/' element separated root path in the configuration and value a valid value (empty to remove an existing property). Furthermore, branch names that contain / should be escaped; this escaping can be done by prefixing the slash with a double backslash \\. For instance, you would write the branch name release/2020_4 as release\\/2020_4.
-srcfile filename
the path (excluding branchdir) of the source file of which a given SCM ID is to be fetched. Used together with option -getscmidcontents.
-st
dump stack trace in case of errors
-synccfgfiles
synchronize the file server configuration with the webserver
-syncsrcfiles
synchronize all active source files between the build server and the webserver
-timestamp yyyy-mm-dd hh:mm:ss
date/time in ISO format
-tmpdir dir
use the specified directory for intermediate files
-to yyyy-mm-dd[ hh:mm:ss]
date/time in ISO format
-updatescmid
update SCM IDs in the database for all active files
-updatescmidclonedflc
update SCM IDs in the database for all cloned file instances (for buildability)
-version
show version info and exit
-visible [0|1]
specify whether the branch should be visible in the viewer
-weburl
show the tiobeweb URL from the configuration
-zipchk
compress the TICS checkers to improve caching performance

Common Tasks

A number of common tasks is described below. For all tasks mentioned (except the -syncfgfiles example) the -project switch is required.

For most tasks it is possible to limit the action to a single, named branch (useful in case the project has multiple active branches). In the example of -setbaseline, the -branchname is mandatory since baselines are branch-specific.

Create a new project

TICSMaintenance -create -project ABC -branchname master -branchdir c:/archive/ABC/master

Enable metrics

TICSMaintenance -project ABC -setmetrics CODINGSTANDARD:1,COMPILERWARNING:1

Check a project configuration

TICSMaintenance -project ABC -checkconfig

Synchronize the file server configuration with the web server

TICSMaintenance -project ABC -synccfgfiles

Upload source files for annotated source

TICSMaintenance -project ABC -syncsrcfiles

Generate viewer caches

TICSMaintenance -project ABC -genviewercache -branchname master

Send SQA report

TICSMaintenance -project ABC -gensqareports

Send status mail

TICS periodically sends out an email to TIOBE with aggregated metric data, analysis errors and other diagnostics ("phone-home" functionality). These emails are used internally by TIOBE to compile benchmark data, and by our service engineers to remotely monitor the health of your analyses. An email is sent after a run, but you can trigger this also using the following command: 

TICSMaintenance -project ABC -sendqsmail -branchname master
Note: An email will only be sent when the OWNER is properly configured.

Set a baseline

TICSMaintenance -project ABC -setbaseline MYBASELINE,plotline:1,delta:1 -branchname master -timestamp "2016-06-23 09:09:36"

Disable calculation of a branch

Indicate that TICSQServer should not calculate the given branch. E.g., the branch has become inactive. 

TICSMaintenance -project ABC -branchname master -calculate 0

Hide a branch in the viewer

Do not show the given branch in the TICS Dashboard and Explorer. 

TICSMaintenance -project ABC -branchname master -visible 0

Remove a branch from the database

Remove all data related to the given branch from the quality database. All related measurements including the complete branch history will be lost! Use with care. Be sure to backup your database first. 

TICSMaintenance -project ABC -branchname master -remove

Remove a project from the TICS configuration

Remove a project from the TICS configuration. This will remove the project from the TICS Dashboard/Explorer. TICSQServer will no longer calculate the project. The corresponding database is not removed! So no data is lost and the complete project history can be restored as long as a copy of the database is kept. This is relevant in case one wants to create a new project with the same name as a removed project (TICS will complain that the corresponding database cannot be created -- since it already exists). 

TICSMaintenance -project ABC -remove

To remove the project database; go to the database server and remove the project's .fdb file.

Remove a run from the database

Remove measurement data from the project database. This can be used to clean-up the project trend by removing trial runs.

The following options play an important role for removing metric measurement points from the project database.

-removerun
indicate that measurements are to be removed from the database
-calc metric
one or more (comma separated) metric type(s); can be ALL
-from yyyy-mm-dd[ hh:mm:ss]
start date/time in ISO format
-to yyyy-mm-dd[ hh:mm:ss]
end date/time in ISO format

Use -from to specify the start of a date range in combination with -to, or, use -from without -to to specify a specific run date. The -to date is exclusive; the -from date is inclusive.

Example; a run consists of the measurement points XYZ: 

TICSMaintenance -project ABC -removerun -calc ALL -from X -to Z

Then the result will consists only of Z.

Remove all metric measurements for a date range

TICSMaintenance -project ABC -removerun -calc ALL -from "2019-10-02 10:12:26" -to "2019-10-02 10:21:53"

Remove all metric measurements for a single run

Remove all metrics measurements, except FANOUT. 

TICSMaintenance -project ABC -removerun -calc ALL -from "2019-03-25 12:00:13" -nocalc FANOUT

Remove FANOUT metric measurements for a single run

TICSMaintenance -project ABC -removerun -calc FANOUT -from "2019-03-24 10:41:28"

Remove certain metric measurements for a date range

TICSMaintenance -project ABC -removerun -calc COMPILERWARNING,FANOUT,AVGCYCLOMATICCOMPLEXITY -from "2019-01-04" -to "2019-03-04"

Clone a database

Create a new project database based on a measurement in an existing project database. Cloning a database starts a new database that only contains a single run. No further history is copied from the original database.

This can be used to start a new project based on a given starting point. This can be useful when basing a development stream on a parent stream.

The following options play an important role for cloning a project database.

-create
indicate that a new database is created
-project name
the name of the new database to clone to
-clonedb name
the name of the existing database to clone from
-branchdir dir
the branch directory in the clone
-branchname name
the new branch name in the clone
-clonebranchname name
the branch name in the original database to clone from
-timestamp yyyy-mm-dd[ hh:mm:ss]
date to start the clone from
-getbaseline name
baseline to start the clone from

In case no -timestamp or -getbaseline is specified, the latest measurement in the original database is used to clone from. If -timestamp is specified, the nearest run to the given date is used to clone from (in case a matching run is found). If -getbaseline is specified, a run with the given baseline name is used to clone from (if such a run exists).

The -branchname is mandatory. Use -branchname to specify the branch name in the new database. Use -clonebranchname to specify the original branch to clone from.

Minimal clone database example

The minimal invocation for cloning a database consists of -create, a source database, a target database, a target branch name and a branch directory where the source code lives. 

TICSMaintenance -create -project ABC_featureX -clonedb ABC -branchname featureX -branchdir c:/archive/ABC_featureX/master

Clone database from date

TICSMaintenance -create -project ABC_featureX -clonedb ABC -branchname featureX -branchdir c:/archive/ABC_featureX/master -timestamp "2019-09-29"

Clone a specific branch

TICSMaintenance -create -project ABC_featureX -clonedb ABC -branchdir c:/archive/ABC_featureX/master -branchname featureX -clonebranchname trunk

Clone database from baseline

TICSMaintenance -create -project ABC_featureX -clonedb ABC -branchdir c:/archive/ABC_featureX/master -branchname featureX -getbaseline ClosedRelease

Disconnect processes from the project database

Sometimes a TICSQServer process is stuck and remains connected to the project database. This prevents other TICSQServers to act on the same project. In such a case error 5333 is given. See the example below: 

[ERROR 5333] Project database 'mbedtls' already is connected to a running TICSQServer process. To avoid data corruption, analysis is aborted. Details of the other connection: 78,16820,/home/user42/databases/mbedtls.fdb,SYSDBA,TCPv4,127.0.0.1,16759,2020-07-09 15:44:51.0610,/tmp/par-7374617070657273/cache-6ee536fa589e9e06eef4c9c1d93952edd4658f34/TICSQServer.bin.

This means that the second TICSQServer refuses to continue to protect the project data integrity.

There are two ways around this. The first is that it is the intention to run multiple metrics in parallel. In that case, add the -parallel flag to TICSQServer. However, this is advanced usage.

The second way is what this section is about. You mean to abort any previous TICSQServer attempts and start over. In that case, use TICSMaintenance with -detach as follows: 

TICSMaintenance -project mbedtls -detach

Replace the example project name "mbedtls" by the appropriate project name.

Authentication

TICS Maintenance needs to authenticate itself when communicating with the viewer. Please refer to configuring an authentication token.