Skip to content

StateDMI / Command / Comment #

Overview

Single-line comments start with #. Spaces and tabs before the comment character are currently not allowed. Comments cannot be added after commands - comments must exist on their own command line. Commands can be converted to and from # comments by right-clicking on a command in StateDMI and selecting Convert selected commands to # comments and Convert selected commands from # comments from the popup menu. See also the /* and */ comment block commands, which are used to comment multiple commands.

Special Comments

The following table lists annotation tags that can be placed in comments to provide additional information to software that processes the commands, using notation similar to the following:

#@expectedStatus Failure

The Commands / General - Comments menu provides menu items to insert special comments.

# Comment Annotation Tags

Annotation Tag                                              Command That Uses                                                        Description          
@enabled False RunCommands Used to disable a command file. For example, use this annotation in a test command file when the test is not ready for use in the software release process.
@expectedStatus Failure
@expectedStatus Warning		 RunCommands Used to help the test framework know if an error or warning is expected, in which case a passing test can occur even if the command status is not “success”.
@os Windows
@os UNIX		 CreateRegressionTestCommandFile Used to filter out test command files that are not appropriate for the operating system. Linux is included in UNIX.
@readOnly StateDMI main interface and command editors Indicates that the command file should not be edited. StateDMI will update old command syntax to current syntax when a command file is loaded. However, this tag will cause the software to warn the user when saving the command file, so that they can cancel. This tag is often used with templates to protect the template from mistakenly being edited and saved in StateDMI (StateDMI does not currently allow editing templates within the interface).
@require application StateDMI >= Version

Available since StateDMI 5.00.06		 StateDMI main interface and RunCommands. Check that the software application version meets requirements for the command file. This can be used to prevent running the command file with incompatible software. The version should match the format shown in Help / About StateDMI (e.g., 5.00.05). Only the first three parts of the version are compared. The comparison operator can be:
  • < (less than)
  • <= (less than or equal)
  • = or == (equal)
  • != (not equal)
  • > (greater than)
  • >= (greater than or equal)
@require datastore HydroBase >= Version

Available since StateDMI 5.00.06		 StateDMI main interface and RunCommands. Check that the datastore version meets requirements for the command file. This can be used to prevent running the command file with incompatible database. The version should match the format used in the HydroBase database name shown in View / Datastores (e.g., 20200720). See above for available comparison operators and behavior when conditions are not met.
@template StateDMI main interface Similar to @readOnly and indicates a template command file. Currently, a text file editor needs to be used to edit template files because StateDMI checks commands for final syntax.
@testSuite ABC CreateRegressionTestCommandFile Used to filter out test command files that are not appropriate for the operating system.

Command Editor

The following dialog is used to edit the command and illustrates the command syntax.

Comment Command Editor

# Command Editor (see also the full-size image)

Command Syntax

The command syntax is as follows. See also the Special Comments section above.

# A comment
# Another comment

Examples

See the automated tests.

Checking StateDMI Version Requirements

Special comments can be used to check the StateDMI application version. Using these comments ensures that command files are only run with appropriate software versions. These comments are particularly useful for implementing automated tests that need to be run with different combinations of software and databases as versions change over time. Command log messages are added to indicate whether a requirement is met, as shown in the following examples.

The following checks that StateDMI version 5.00.05 software is being used with the command file, using the following comment. This type of check ensures that a command file is not used with an incompatible software version. In this case, the requirement is met, as shown in the following image.

#@require application StateDMI >= 5.00.05

require success message

@require Command Success Message (see also the full-size image)

The following checks that StateDMI version 5.00.07 software is being used with the command file, using the following comment. In this case, the requirement is not met, as shown in the following image, and the comment is also marked as a failure when the command file is run.

#@require application StateDMI >= 5.00.07

require failure message

@require Command Failure Message (see also the full-size image)

Checking HydroBase Version Requirements

Special comments can be used to check HydroBase versions when datastores are used (HydroBase datastores are enabled by default for StateDMI 5.00.06 and later). Using these comments ensures that command files are only run with appropriate database version. These comments are particularly useful for implementing automated tests that need to be run with different combinations of software and databases as versions change over time. Command log messages are added to indicate whether a requirement is met, similar to the examples in the previous section.

The following checks that HydroBase version 20200720 is being used with the command file, using the following comment. This type of check ensures that a command file is not used with an incompatible database version.

#@require datastore HydroBase >= 20200720

Troubleshooting

See the main troubleshooting documentation

See Also