CoverageSnapshot

(Engine-Level Function)

Description:	Captures the areas in a VTScada source file which have not executed along with summary statistic for each module in the file to extract code coverage information.
Warning	This function should be used only by advanced programmers.
Returns:	Structure
Usage:	Script Only.
Function Groups:	Advanced Module
Related to:
Format:	CoverageSnapshot(Module, [ Reset ])
Parameters:

Module

Required. A VTScada module. The data returned will be for the source file which contains that module. Information for all of the modules in the same source file will be included in the returned value. The module need not be the root module of the source file.

Reset

Optional Tells the function to reset all of the code coverage counters to 0 immediately after the statistics are collected.
A true value indicates that the reset should be done and a false (0) indicates that it should not be done. The default value is 1.

Comments:

This function exists for purposes of internal testing by Trihedral. It is unlikely to be useful elsewhere.

The VTScada interpreter engine keeps counters for every module, variable, state, statement and function parameter. All of these counters start at 0 whenever VTScada starts. Every time one of these internal structures is executed, its corresponding counter is incremented.
The CoverageSnapshot function searches through the code for a given VTScada script source file and locates all of the counters which are still 0. These represent the areas of the code that have not executed since VTScada started or at least since the last reset.
CoverageSnapshot returns a list of all these areas of the code that haven’t executed. The list is in the form of starting and ending byte offsets in the source file. The list excludes constants the declaration of TEST modules and FIXTURES.
The structure returned is

FileCoverage Struct [
  Children  { Dictionary of child module names. The values are
              either a pointer to Child Struct or a file name. 
              File name is used if not in the same source file. 
             File names are relative to VTScada installation directory.}; 
  List      { Pointer to an UncoveredList Struct       };
  FileSize { Number of bytes in the file. Will be invalid if the
             first parameter of the  function refers to a module
             which is not the root module in the file and the
             parent of the module is invalid. };
  TimeStamp { File time for the file       };
  Class     { Variable class defined for the root module
              In the file. };
];

The referenced structures are:

Child Struct [
  Begin    { Byte offset from the beginning of the source file for 
              module definition };
  End      { Last byte offset for the module definition      }; 
  Children { Dictionary as defined in FileCoverage Struct    };
  Class    { Variable class defined for the module           };
];

UncoveredList Struct [
  Begin     { Offset to start of uncovered code in source file  }; 
  End       { Offset to last byte of uncovered code in range    };
  Mode      { 0 for code, 1 for variables                       };
  Next      { Pointer to next UncoveredList for the file        };
]

The UncoverList is ordered in increasing Begin offsets with none of the Begin/End areas overlapping in the list.