| 6 | | |
| 7 | | T3Q uses an XML-based configuration format. Starting with version v0.4.2, the location of the configuration file must be supplied as a command line option during execution (the location was previously based in the default user's data location - depending on the system, a file {{{t3q.xml}}} was stored in {{{%APPDATA%\T3Q}}} (Windows) or in {{{~/.t3q/}}} (Unix)). The location of the {{{%APPDATA%}}} directory depended on the username, the Windows version and possibly the localization. For example, for a user 'foobar' on a German Windows XP machine, the resulting configuration path would be {{{C:\Documents and Settings\foobar\Application Data\T3Q}}}. In version v0.4.2 and onwards, the location of the configuration file has to be supplied every time T3Q is called. Additionally, starting with version v1.0.1, if there is no existing configuration file in the selected location, the tool will prompt the user to use the appropriate option to generate a new configuration with the default settings. Thus, the tool has to be started with the appropriate parameter to generate a new configuration prior to actual usage. This way, it will be possible to modify the configuration file to accommodate the particular needs of the user prior to performing any analysis. By location here the path, filename, and extension of the configuration file are meant, which implies that any filename and any extension can be used. It is probably best to retain certain norms in naming the configuration files, at least in preserving the file extensions ({{{.xml}}}) to avoid confusion. |
| | 5 | T3Q uses an XML-based configuration format. Starting with version v0.4.2, the location of the configuration file must be supplied as a command line option during execution (the location was previously based in the default user's data location - depending on the system, a file `t3q.xml` was stored in `%APPDATA%\T3Q` (Windows) or in `~/.t3q/` (Unix)). The location of the `%APPDATA%` directory depended on the username, the Windows version and possibly the localization. For example, for a user 'foobar' on a German Windows XP machine, the resulting configuration path would be `C:\Documents and Settings\foobar\Application Data\T3Q`. In version v0.4.2 and onwards, the location of the configuration file has to be supplied every time T3Q is called. Additionally, starting with version v1.0.1, if there is no existing configuration file in the selected location, the tool will prompt the user to use the appropriate option to generate a new configuration with the default settings. Thus, the tool has to be started with the appropriate parameter to generate a new configuration prior to actual usage. This way, it will be possible to modify the configuration file to accommodate the particular needs of the user prior to performing any analysis. By location here the path, filename, and extension of the configuration file are meant, which implies that any filename and any extension can be used. It is probably best to retain certain norms in naming the configuration files, at least in preserving the file extensions (`.xml`) to avoid confusion. |
| 32 | | This means that apart from any required options (see below), there always has to be at very least one parameter that needs to be specified. This parameter is the input parameter, which can be either a path that contains the TTCN-3 files that should be analyzed, the name of an individual file, or any combination of these (a mixed list), including wildcards. |
| 33 | | |
| 34 | | - If a path provided as input (and recursive processing is enabled in the configuration, which is the default setting), T3Q will recursively parse and analyze all files in this directory that match the provided file extensions (which are specified in the configuration file). For the current path a simple '.' is sufficient. If no files match these extensions, T3Q will output a corresponding message and quit. |
| 35 | | - If an individual file is provided as input, then only that file will be processed. |
| 36 | | - If the path or filename contains spaces, you need to put the path into quotation marks or use the auto-completion feature of the environment (provided there is one), which should take care of escaping spaces or enclosing the complete path in quotation marks. |
| 37 | | - If a list of individual files and/or paths are provided as input, these will be combined and processed together. |
| 38 | | - If wildcards are used, these will be expanded by the command-line environment into a list and subsequently analyzed as such. |
| | 32 | * If a path provided as input (and recursive processing is enabled in the configuration, which is the default setting), T3Q will recursively parse and analyze all files in this directory that match the provided file extensions (which are specified in the configuration file). For the current path a simple '.' is sufficient. If no files match these extensions, T3Q will output a corresponding message and quit. |
| | 33 | * If an individual file is provided as input, then only that file will be processed. |
| | 34 | * If the path or filename contains spaces, you need to put the path into quotation marks or use the auto-completion feature of the environment (provided there is one), which should take care of escaping spaces or enclosing the complete path in quotation marks. |
| | 35 | * If a list of individual files and/or paths are provided as input, these will be combined and processed together. |
| | 36 | * If wildcards are used, these will be expanded by the command-line environment into a list and subsequently analyzed as such. |
| 58 | | |
| 59 | | * {{{--help}}} will provide brief usage information listing the expected syntax and the available options. T3Q will stop and analyze no files when the help screen is called. |
| 60 | | * The {{{--generate-config}}} option (new as of v1.0.1) allows the generation of new default configuration files at the location specified. T3Q will then quit. |
| 61 | | * The {{{--config}}} option (new as of v0.4.2) is mandatory and has to be specified every time T3Q is run (except when {{{--help}}} or {{{--generate-config}}} are used). It specifies the location of the configuration file. Starting with v1.0.1, if no configuration file is found at the specified location, the user will be prompted to use the appropriate option ({{{--generate-config}}}) to produce a new default configuration. To use the default location from previous versions one will have to specify it manually, e.g. [[BR]] |
| | 56 | * `--help` will provide brief usage information listing the expected syntax and the available options. T3Q will stop and analyze no files when the help screen is called. |
| | 57 | * The `--generate-config` option (new as of v1.0.1) allows the generation of new default configuration files at the location specified. T3Q will then quit. |
| | 58 | * The `--config` option (new as of v0.4.2) is mandatory and has to be specified every time T3Q is run (except when `--help` or `--generate-config` are used). It specifies the location of the configuration file. Starting with v1.0.1, if no configuration file is found at the specified location, the user will be prompted to use the appropriate option (`--generate-config`) to produce a new default configuration. To use the default location from previous versions one will have to specify it manually, e.g. [[BR]] |
| 71 | | * The {{{--profile}}} option overrides the '''defaultConfigurationProfile''' in the XML configuration. This means that you can specify multiple profiles in the XML configuration and run T3Q using another existing profile without the need to change the XML configuration. If the profile specified on the command-line does not exist, T3Q will automatically fall back to the default profile provided in the main section of XML configuration. In turn, if this default profile does not exist as well, T3Q will fall back to the implicit ''all'' profile. If the configuration profile name contains any empty spaces, they need to be escaped or the profile name needs to be enclosed in quotation marks, depending on the environment. |
| | 68 | * The `--profile` option overrides the '''defaultConfigurationProfile''' in the XML configuration. This means that you can specify multiple profiles in the XML configuration and run T3Q using another existing profile without the need to change the XML configuration. If the profile specified on the command-line does not exist, T3Q will automatically fall back to the default profile provided in the main section of XML configuration. In turn, if this default profile does not exist as well, T3Q will fall back to the implicit ''all'' profile. If the configuration profile name contains any empty spaces, they need to be escaped or the profile name needs to be enclosed in quotation marks, depending on the environment. |
| 79 | | The native binary executable for Windows supplied with v1.0.1 is discarded again as of v1.0.2, due to the fact that it does not grant the desired advantages. Thus, the basic usage is reverted to the batch scripts. Starting with v1.0.2, the batch scripts include a "hidden" {{{--echo}}} option, which simply outputs the deployment specific call to the Java virtual machine, '''without''' any command line arguments, meaning that it makes no sense to provide any further command line parameters besides the {{{--echo}}} option. The sole purpose of this option is to output the full command line necessary for starting the tool, which may be necessary for embedding into third party tools. This is why this option is considered hidden (it also does not show in the standard help screen). It should not affect the general usage of the tool. If, for whatever reason, other command line arguments are supplied together with the {{{--echo}}} option, then the {{{--echo}}} option needs to be the first command line argument. |
| | 76 | The native binary executable for Windows supplied with v1.0.1 is discarded again as of v1.0.2, due to the fact that it does not grant the desired advantages. Thus, the basic usage is reverted to the batch scripts. Starting with v1.0.2, the batch scripts include a "hidden" `--echo` option, which simply outputs the deployment specific call to the Java virtual machine, '''without''' any command line arguments, meaning that it makes no sense to provide any further command line parameters besides the `--echo` option. The sole purpose of this option is to output the full command line necessary for starting the tool, which may be necessary for embedding into third party tools. This is why this option is considered hidden (it also does not show in the standard help screen). It should not affect the general usage of the tool. If, for whatever reason, other command line arguments are supplied together with the `--echo` option, then the `--echo` option needs to be the first command line argument. |
| | 111 | === Performance and Memory Usage === |
| | 112 | Large TTCN-3 test suites tend to take quite a while to process (both for parsing and for analysis). Therefore, it is generally a good idea to set larger memory limits (as far as the system allows) in order to improve processing time and avoid possible memory problems. The default setting is to set the '''upper''' memory limit to 512MB, which by today's standards is rather conservative, however, it should be sufficient for smaller to medium-sized TTCN-3 test suites. The optimal memory limits are not easy to determine, and ways to automatically calculate and set these depending on the available system resources, the size of the input TTCN-3 test suite, and the configuration in use are currently being investigated. In the meantime, should processing take too long or memory errors occur, it is advisable to set a higher upper memory limit, depending on the available system resources. This can be done by manually editing the parameters in the start scripts (`t3q.bat` and `t3q` for Windows and Unix respectively). These files should be edited very carefully, as mistakes may prevent T3Q from starting. Under Windows, in `t3q.bat`, set the `-Xmx` parameter in following line: |
| 117 | | === Performance and Memory Usage === |
| 118 | | |
| 119 | | Large TTCN-3 test suites tend to take quite a while to process (both for parsing and for analysis). Therefore, it is generally a good idea to set larger memory limits (as far as the system allows) in order to improve processing time and avoid possible memory problems. The default setting is to set the '''upper''' memory limit to 512MB, which by today's standards is rather conservative, however, it should be sufficient for smaller to medium-sized TTCN-3 test suites. The optimal memory limits are not easy to determine, and ways to automatically calculate and set these depending on the available system resources, the size of the input TTCN-3 test suite, and the configuration in use are currently being investigated. In the meantime, should processing take too long or memory errors occur, it is advisable to set a higher upper memory limit, depending on the available system resources. This can be done by manually editing the parameters in the start scripts ({{{t3q.bat}}} and {{{t3q}}} for Windows and Unix respectively). These files should be edited very carefully, as mistakes may prevent T3Q from starting. Under Windows, in {{{t3q.bat}}}, set the {{{-Xmx}}} parameter in following line: |
| 133 | | This is a temporary solution for an emerging problem, until either a way to automatically configure the memory settings is implemented or a more convenient way to manually change the memory settings is implemented. |
| | 128 | As of v1.0.3, a tool to guesstimate the optimal memory settings is included with T3Q. This tool is launched prior to the actual tool execution and attempts to detect the maximum memory settings with which T3Q can be started at that particular moment, aiming to both reduce processing time and avoid potential out of memory errors. It should be noted that this tool can be considered in beta status, as in some edge cases it may cause T3Q/T3D to crash or to fail at start. Such cases should be reported so that the memory detection tool can be further adjusted to avoid such issues in the future. It is still possible to select preferred memory settings manually by adjusting the start-up scripts as described above, where the particular line has been changed to: |
| | 129 | |
| | 130 | {{{ |
| | 131 | set JAVA_CMD=%JAVA% -Xmx%HEAP%m -Xss128m -cp "%CLASSPATH%" org.etsi.t3q.T3Q |
| | 132 | }}} |
| | 133 | under Windows and to |
| | 134 | |
| | 135 | {{{ |
| | 136 | JAVA_CMD="$JAVA -Xmx`$MT_CMD`m -Xss128m -cp $CLASSPATH org.etsi.t3q.T3Q" |
| | 137 | }}} |
| | 138 | under Unix, and the `%HEAP%` and {{{`$MT_CMD`}}} parts of the line should be substituted with the desired settings. |
