Skip to content

Command Status

Introduction

It is desirable to know whether each command has been successful for initialization, pre-run, and run. This is accomplished by tracking status of the command via command log messages, as described below.

CommandStatusProvider Interface

The CommandStatusProvider interface defines behavior needed by the TSTool UI to display command log messages and status.

CommandStatus Class Use

Every command that extends the AbstractCommand class, implements the CommandStatusProvider interface and includes an instance of the CommandStatus class, which maintains a log of messages generated by that command. Command log messages are set on the command via the command status and result in the command status being set to the most severe status (see CommandStatusType). This allows fine-grained feedback on commands and flexibility to generate reports after command workflows have run, as opposed to filtering and sorting log files for command output. The following illustrates use of the command status:

status.addToLog ( commandPhase,
   new CommandLogRecord(CommandStatusType.WARNING,
       message, "Verify that filename is correct and that the file exists - " +
           "may be OK if file is created during processing." ) );

There is a trade-off in that memory is consumed by maintaining in-memory command log. However, given that command status logging focuses on recording problems, the memory use is generally small for successful runs, and when there are issues the messages need to be reviewed to troubleshoot. Some commands limit the command logging output to a specific count to minimize memory use.

Using with For Command

The For command presents challenges for command logging because the same instance of a command can be executed multiple times during processing of the loop. There are at least three options for handling command status logging:

  1. Clear command logging each iteration.
  2. Accumulate logging for all iterations.
  3. Allow the logging approach to be specified, such as a parameter in the For command.
    1. Could implement global behavior across all iterations.
    2. Could implement granular control to log only some iterations.

A complication is that each command being executed in the loop needs to dynamically check whether or not to log.

The solution that has been implemented is to check a property from within each command. This is being phased in but has not been implemented for all commands. The default behavior if the check has not been implemented is to clear logging for each iteration.