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.
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,-renameor-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
-projectand/or create a branch if-branchnameand-branchdirare 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
-fsuploadoption- -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
-branchnameis 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
-branchnameis 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 namerelease/2020_4asrelease\\/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
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.
TICSMaintenance -create -project ABC -branchname master -branchdir c:/archive/ABC/master
TICSMaintenance -project ABC -setmetrics CODINGSTANDARD:1,COMPILERWARNING:1
TICSMaintenance -project ABC -checkconfig
TICSMaintenance -project ABC -synccfgfiles
TICSMaintenance -project ABC -syncsrcfiles
TICSMaintenance -project ABC -genviewercache -branchname master
TICSMaintenance -project ABC -gensqareports
TICSMaintenance -project ABC -sendqsmail -branchname master
TICSMaintenance -project ABC -setbaseline MYBASELINE,plotline:1,delta:1 -branchname master -timestamp "2016-06-23 09:09:36"
Indicate that TICSQServer should not calculate the given branch. E.g., the branch has become inactive.
TICSMaintenance -project ABC -branchname master -calculate 0
Do not show the given branch in the TICS Dashboard and Explorer.
TICSMaintenance -project ABC -branchname master -visible 0
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. 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 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.
TICSMaintenance -project ABC -removerun -calc ALL -from "2019-10-02 10:12:26" -to "2019-10-02 10:21:53"
Remove all metrics measurements, except FANOUT.
TICSMaintenance -project ABC -removerun -calc ALL -from "2019-03-25 12:00:13" -nocalc FANOUT
TICSMaintenance -project ABC -removerun -calc FANOUT -from "2019-03-24 10:41:28"
TICSMaintenance -project ABC -removerun -calc COMPILERWARNING,FANOUT,AVGCYCLOMATICCOMPLEXITY -from "2019-01-04" -to "2019-03-04"
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.
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
TICSMaintenance -create -project ABC_featureX -clonedb ABC -branchname featureX -branchdir c:/archive/ABC_featureX/master -timestamp "2019-09-29"
TICSMaintenance -create -project ABC_featureX -clonedb ABC -branchdir c:/archive/ABC_featureX/master -branchname featureX -clonebranchname trunk
TICSMaintenance -create -project ABC_featureX -clonedb ABC -branchdir c:/archive/ABC_featureX/master -branchname featureX -getbaseline ClosedRelease
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.
TICS Maintenance needs to authenticate itself when communicating with the viewer. Please refer to configuring an authentication token.