Operations - server commands
Genesis has numerous built-in commands that have their own individual functions. This page goes through them and details the function, parameters and use cases of those commands.
Once an application has been built and zipped, you can install it in any another system that contains the Genesis low-code platform.
To ensure a correct installation, you must follow the product installation procedure.
CountRecords
This counts the number of records in the database, grouped by table; the results are printed to screen.
By default, a count is given for every table in the database.
If you only want the record count for specific tables, you can specify the table name or names.
Syntax
Argument | Argument long name | Mandatory | Description | Restricted values | Default |
---|---|---|---|---|---|
[TABLES] | no | the name of the table whose rows are to be counted; for more than one table, this must be a space-separated list | none | a record count is provided for all tables in the database |
This example gives a record count for all tables:
CountRecords
The example below gives a record count for two specific tables:
CountRecords CHF_ORDERS CHF_TRADES
DbMon
DbMon is the Genesis database client, which provides its own command line. From here, you can navigate through the database tables in your application.
DbMon
itself has a help
command, which shows all the available commands. To get help on a specific command, run help _command_
.
DbMon --quietMode
performs database changes without triggering real-time updates in the update queue layer.
For full details, see our page on DbMon.
DropTable
The DropTable
command removes all rows from the specified tables.
If you do not specify any tables, then all rows will be removed from all tables in the database.
Use with care!
Syntax
Argument | Argument long name | Mandatory | Description | Restricted values | Default |
---|---|---|---|---|---|
-t | [TABLES] | no | the name of the table to have its rows removed; for more than one table, this must be a space-separated list | none | all records are removed from all tables |
The example below removes all the rows from three separate tables:
DropTable -t EQUITY_ORDERS_GB EQUITY_ORDERS_DE EQUITY_ORDERS_IT
The command will ask you to confirm the removal of the content from each table.
DumpIt
To copy data from a Genesis database, use the DumpIt
command.
Syntax
The DumpIt
command can take the following arguments:
Argument | Argument long name | Mandatory | Description | Restricted values | Default |
---|---|---|---|---|---|
-a | --all | no | exports all tables to csv | none | none |
-f | --file (arg) | no | name of the csv file where table is exported | none | none |
-fields (arg) | no | space separated field list e.g. "FIRST_NAME LAST_NAME" | none | none | |
-h | --help | no | show help on how to use the command | none | none |
-s | --sql (arg) | no | name of the sql file to export the table to | none | none |
-t | --table (arg) | no | specify the name of the table you want to export to CSV. If there are multiple tables to include, provide a list separated by spaces. | none | none |
-cem | --criteriaEvaluatorMode (arg) | no | the type of criteria evaluator to be used | TYPE_AWARE or LEGACY | LEGACY |
-fm | --formatMode (arg) | no | indicates whether field formats should be taken into account | FORMATTED (takes field formats into account) or LEGACY (does not take field formats into account) | none |
-qi | --quoteIdentifiers | no | if present, all sql identifiers (e.g. column names) will be quoted | none | none |
-where (arg) | no | match criteria e.g. "USER_NAME=='John'" | none | none |
Here are some examples:
DumpIt -t GBP_TRADES -f gbp-trades
This copies all records in the GBP_TRADES table to the file gbp-trades.csv.
DumpIt -t USER -where "USER_NAME=='John'" -fields "USER_NAME"
This copies the USER_NAME of every record in the USER table where the USER_NAME is John. This useful if you want to know if the user name John is in the database.
DumpIt -t FUND -f FUND -fields "FUND_ID NAME" -where "NAME == 'FUND_FUND' && YEARS_IN_SERVICE >= 10"
This copies the FUND_ID and NAME fields of every record that has "FUND_FUND" for a name, and ten or more years in service.
DumpIt --all
This copies all the tables in the system, creating one .csv file for each table in the database. The files are saved in the current directory. It is useful for taking a back-up of the current system database.
Interactive mode
You can run DumpIt
without any arguments to enter interactive mode.
FixEnumValues
Converts non-matching enum values in the database to SNAKE_CASE. This command is intended for use after a dictionary change that adds new enum values. It will only update the data if the converted value matches the list of enum values in the dictionary.
Changes will only be applied to the database if the command is run with the --commit flag.
Stop all processes before using this command.
Syntax
The FixEnumValues
command can take the following arguments:
Argument | Argument long name | Mandatory | Description | Restricted values | Default |
---|---|---|---|---|---|
-c | --commit | no | applies dictionary changes to the database | none | none |
[TABLES] | no | a space-separated list of specific tables to be changed; if no list is supplied, all tables are changed | none | none | |
-h | --help | no | shows help on how to use the command | none | none |
In the example below, the changes are applied to the database for two tables: TRADE and POSITION.
FixEnumValues --commit TRADE POSITION
Using an installHook
To automate this process, you can use an installHook to call the script before remap
is performed - be aware that it will only run successfully once.
The following example finds all String to Enum changes in all tables and commits any valid updates to the database before remap
is performed.
#!/bin/bash
source "$HOME"/.bashrc
shopt -s expand_aliases
FixEnumValues --commit
exit $?
To implement this:
-
Navigate to the appName\server\jvm\appName-config\src\main\resources\scripts\installHooks folder
-
Create a file called nextInstallHookNumber_ConvertData.sh or similar and add the bash script above.
The installHook will run before remap
on your next deploy.
genesisInstall
This command validates all system and product configuration, checking for things such as field duplication.
genesisInstall
looks at all the folders (apart from runtime and generated), all the modules, and all files in the cfg directory. It copies the config files from the cfg directory into the generated folder.
In the files collected, the command examines the installation environment and looks for system definition tokens (file names with suffix .tmplt.xml). The generated cfg file names have their token placeholders replaced with the environment's system definition value for the token, and the suffix will be changed to .auto.xml.
The command also checks the system-specific definitions and uses these to replace any definitions that have the same name in any of the modules. Where a file in site-specific/cfg has the same name as a file in a module's cfg, the version in site-specific/cfg will always be used.
Following this, when you start any process, the startProcess
command reads from the cfg directory in the generated folder.
genesisInstall
also completes config checking, looking out for mistakes in the configured code and providing warnings and error messages. If an error is encountered, the configuration will not be propagated to the run/generated/cfg area.
Syntax
The genesisInstall
command can take the following arguments:
Argument | Argument long name | Mandatory | Description | Restricted values | Default |
---|---|---|---|---|---|
--ignore | no | If supplied, will ignore errors in the configuration files | none | none | |
--ignoreHooks | no | If supplied, will ignore any install hooks found | none | none | |
--compactProcesses | no | When set to true , combines compatible services into a single process, which reduces the number of services running in the container | none | none | |
--repeatedHooks | no | If supplied, will repeat the specified install hooks | none | none | |
--hostDiff | no | If supplied, will compare all the files in every Genesis server in the cluster to make sure that the files are in sync | none | none |
Once complete, all configuration files will be copied and, where necessary, merged into the ~/run/generated/cfg file, which we alias as $GC.
If any problems are found in the generated configuration files, they will be deleted. This forces you to correct the errors in the original configuration files.
To ignore errors in the configuration files, use the --ignore
argument. This leaves the configuration files undeleted, even if errors are found.
All process configuration is stored within $GC.
The example below ignores errors and leaves the configuration files undeleted, even if errors are found.
genesisInstall --ignore
The example combines all compatible processes into a single process.
genesisInstall --compactProcesses
Install hooks
Install hooks run as part of genesisInstall
. You can specify the relevant scripts as part of genesisInstall
then add those scripts to the file applicationName_config/resources/scripts/installHooks, where applicationName is the name of application you are developing.
The scripts (hooks) you add will only run once, unless their execution fails. If you run genesisInstall
again, previously successful executions of installHook scripts will not be run as part of the install.
The scripts must be implemented to work in an idempotent way, and the end result of executing a script means the system is (or already was) in the expected target state, whether you run it on a pre-existing environment (e.g. upgrading a server) or you run it in a completely new environment.
On the server, it is located in the GENESIS_HOME/applicationName/scripts/installHooks directory. Logs are located in GENESIS_HOME/runtime/installHooks
Install hook file-name conventions:
- We only use shell script for install hooks and inside the shell script you can call a Python script, a Kotlin script or whatever is necessary.
- The install hook name must be unique.
- It must contain a priority number at the beginning of the file name. This number should be unique. For example: 1_migrateLogFiles.sh, 2_migrateDictionary.sh.
- If you need to create a new install hook that has to execute before priority number 1 or number 2, you must increase the numbers for all the other scripts (e.g. rename 1_migrateLogFiles.sh to 9_migrateLogFiles.sh).
Practical examples
You can create a new script and add it to the folder mentioned above to perform any particular functionality as part of genesisInstall
.
Any script exiting with value "0" is considered successful by the installHooks system, and any script exiting with a non-zero value is considered to have failed execution.
In a Java or Kotlin world, a simple implementation could look like this:
@JvmStatic
fun main(args: Array<String>) {
ScriptUtils.initRootLogLevel(Level.WARN)
val genesisHome = System.getenv("GENESIS_HOME")
if (genesisHome == null || "" == genesisHome) {
val message = "System environment variable GENESIS_HOME is not set. Aborting migration process..."
// installHooks FAILURE
System.err.println(message)
exitProcess(1)
}
try {
run(args)
// installHooks SUCCESS
exitProcess(0)
} catch (e: Exception) {
// installHooks FAILURE
System.err.println(e.message)
exitProcess(1)
}
}
Consider another example; we have a migration script called migrateDictionary.sh as an install hook; this internally executes MigrateDictionary as shown below:
#!/bin/bash
MigrateDictionary -dst DB
exit $?
GenesisRun
This is a Python script wrapper for Genesis scripts.
'GenesisRun` will attempt to find a script to execute within the Genesis folder structure (site-specific or scripts).
There are two environment variables that can be used to configure how much RAM the scripts will use:
- SCRIPT_MAX_HEAP
- REMAP_MAX_HEAP
GenesisRun
can execute code in two different modes: Groovy script and GPAL Kotlin script. GenesisRun builds the necessary classpath, so you don't need to build it in each script.
- Groovy script: GenesisRun SetLogLevelScript.groovy
- GPAL Kotlin script: GenesisRun customPurger-script.kts
There is a separate wrapper, JvmRun
for Java main class scripts.
GetAutoIncrementCount
This gets the current auto increment INT values defined in dictionaries for all the sequences in the system. By default, the values are printed on screen (to the terminal), but they can be written to a file so they can be reused by the SetAutoIncrement
script (see below).
Stop all your application's processes before using this command.
Syntax
The GetAutoIncrementCount
command can take the following arguments:
Argument | Argument long name | Mandatory | Description | Restricted values | Default |
---|---|---|---|---|---|
-f | --file (arg) | no | name of file to receive the values | none | AutoIncrementValues |
-h | --help | no | displays help on the command | none | none |
-p | no | if sending to a file, then use this if you also want to print to screen | none | true (unless -f is supplied) |
The behaviour of this command depends on which database implementation your application uses.
-
If you are using a NOSQL database, such as Foundation DB, auto-incremented values are assigned in blocks of 100 in order to improve performance. This command retrieves the value of the counter stored on disk. If the system is currently active, this value might not correspond to the value of the next record inserted that references the value.
-
Similarly, if you are using Oracle, auto-incremented values are cached in memory in configurable block sizes. This command only retrieves the current value of the counter stored on disk.
-
If you are using an SQL implementation, this command returns the last value assigned by the sequence, not the next to be assigned.
For example, this command puts all the auto increment values in a file called AutoIncVals. The values are not displayed on screen.
GetAutoIncrementCount -f=AutoIncVals
And remember: only use this command when all the application's processes have been stopped.
GetSequenceCount
This gets the current sequence number for all the sequences in the system. The values can be printed on screen or written to a file so they can be reused by the SetSequence
script (see below). For example, if you have 120 rows in the table DE_ORDERS, the sequence count is for that table is 120.
Syntax
The GetSequenceCount
command can take the following arguments:
Argument | Argument long name | Mandatory | Description | Restricted values | Default |
---|---|---|---|---|---|
-f | --file (arg) | no | name of the file to contain the sequence numbers | none | SEQUENCE.csv |
-h | --help | no | show help on how to use thus command | none | none |
-p | no | none | true (unless -f is supplied) |
The example below puts the numbers for all sequences in the database in the file /home/user/run/sequenceCount.
GetSequenceCount --file=/home/user/run/sequenceCount