Test Execution and Test Scalers

In a typical analyzer, as each event is analyzed, all the defined tests will be evaluated. The results of these tests are then available to be used as conditions on histogram incrementing. CTP calls are also available to accumulate scalers of the number of times each test was evaluated as true (not zero.)

All CTP calls return an integer*4 error code. Zero is returned for successful execute. No specific failure codes are defined except that a failure will be indicated by a non-zero return code.

The following calls are available for test evaluation and for incrementing test result scalers:

  character *(*) blockname
  integer*4 ierr

  ierr=thtstexe()           ! Execute all tests
  ierr=thtstexeb(blockname) ! Execute a single block of tests

  ierr=thtstins()           ! Increment all test scalers
  ierr=thtstinsb(blockname) ! Increment scalers for on block

The calls without arguments will cause all the blocks (in alphabetical order) to be processed. For the routines that end with b, only a single block is executed.

The test scalers must be cleared initially before any calls to increment the scalers are made or before a new run is analyzed. As with test execution and scaler incrementing, all test scalers or just those associated with a specific test block may be cleared.

  character *(*) blockname
  integer*4 ierr

  ierr=thtstcls()           ! Clear all test scalers
  ierr=thtstclsb(blockname) ! Clear test scalers for
                            ! a single block of tests

Test test results may be cleared before tests are executed with the following routines.

  character *(*) blockname
  integer*4 ierr

  ierr=thtstclr()           ! Clear all test flags
  ierr=thtstclrb(blockname) ! Clear test flags a single block

Clearing the test results is not required as the execution of each test will result in a definite value. However, there can be situations where clearing the test results is important. Two of the situations are:

• If a particular block of tests is not executed for every event, but if its test results are used in other test blocks or as conditions on histogram execution, the test results should be cleared so that they do not reflect test results from previous events.
• If some of the test results in a block are arrays, the test results flags for that block should be cleared. Otherwise, array elements that were not accessed for a particular event may have values from previous events.

In writing the tests that go into CTP test blocks, a given test result name should generally only be used in one block. In particular particular care must be taken if arrays are used for test results. If mutually exclusive array elements (of a given array) are used in more than one test block, the use of test scalers and the clearing of test flags can have undesired results. This is because, the ins, cls, and clr routines will operate on an entire array even if only one element of that array is used as a test result in a given block. Since the indices of arrays can be variable as well as fixed, CTP has no easy way of determining which elements of these arrays to operate on (increment or clear.)