PCA$HELP.HLB  —  SET  COVERAGE
    Collector Command

    Establishes the collection of test coverage data at specified
    program locations.

    Format

      SET COVERAGE  [nodespec [,nodespec...]]

1  –  Parameters 

 nodespec

    Specifies a set of program locations at which to measure test
    coverage.

    See HELP Nodespec for information about node specifications.

2  –  Description 

    The SET COVERAGE command establishes the collection of test
    coverage data for all program locations specified by node
    specifications. The Collector places a breakpoint at each
    specified program location to measure test coverage. After
    you enter the GO command, the Collector determines whether
    each specified program location is reached during program
    execution. When a test coverage breakpoint is reached during
    program execution, the Collector records that program location
    in the performance data file. The Collector then removes the
    breakpoint so that the overhead of measuring coverage is not
    incurred in subsequent executions of the same program location.
    If you specify the /UNTIL:n qualifier, the Collector removes
    the breakpoint after the nth execution instead of the first
    execution.

    You must collect stack PC information if you want to use a /MAIN_
    IMAGE, /CUMULATIVE or /STACK_DEPTH qualifier with the PLOT or TAB
    command in the Analyzer.

    If you enter the SET COVERAGE command before entering a SET
    DATAFILE command, the Collector establishes a default data file.
    The default data file has the same file name as your program's
    executable image file and a file type of PCA.

3  –  Qualifiers

3.1    /PREVIOUS 

    Causes the Collector to use the breakpoint table left by the
    previous collection run when it is appending test coverage data
    to an existing performance data file. If such a breakpoint table
    exists, the node specifications are ignored. Also causes the
    Collector to write a table of test coverage breakpoint locations
    not yet covered (or not yet covered n times if /UNTIL:n is
    specified) to the data file at the end of the current collection
    run.

    This qualifier causes test coverage to be measured only once
    (or only n times for /UNTIL:n) for an entire set of collection
    runs. If a program location has been found to be covered in
    one collection run, the Collector makes no attempt to measure
    coverage of that location in any subsequent collection run. Use
    of the /PREVIOUS qualifier makes data collection more efficient,
    but you lose the ability to determine what individual collection
    runs covered which program locations. If you use the /PREVIOUS
    qualifier, you should use the /APPEND qualifier on the SET
    DATAFILE command.

3.2    /UNTIL 

       /UNTIL:n

    Causes each test coverage breakpoint to be removed the nth time
    it is reached during program execution. By using the /UNTIL:n
    qualifier, you can determine whether a program location is
    executed at least n times. If you omit the /UNTIL:n qualifier,
    each breakpoint is removed the first time it is reached.

3.3    /STACK_PCS 

    Specifies that stack PC values are collected for coverage data.
    Further SET COVERAGE requests will assume a default of /STACK_
    PCS.

3.4    /NOSTACK_PCS 

    Specifies that no stack PC values are collected for coverage
    data. This is the default upon entry into the collector.

3.5    /ANC 

    Saves codepath information in the performance data file for every
    module containing coverage-set points. This information is used
    by the Analyzer MERGE/ANC command to validate the ANC information
    being merged.

4  –  Examples 

  PCAC> SET COVERAGE/STACK_PCS PROGRAM BY CODEPATH

      This command specifies that test coverage be measured for every
      codepath in the user program, and enables the collection of
      stack PC values.

  PCAC> SET DATAFILE/APPEND COV_TEST.PCA
  PCAC> SET COVERAGE/PREVIOUS PROGRAM BY CODEPATH

      The SET DATAFILE command specifies that the coverage data from
      this collection run be appended to an existing performance
      data file if such a file exists. The SET COVERAGE command
      specifies that test coverage be measured for every codepath in
      the user program. The /PREVIOUS qualifier specifies that if an
      existing data file is found, then the Collector will ignore the
      nodespec, and will use the breakpoint table from the previous
      collection run recorded in that data file. Hence, test coverage
      is measured only once for each codepath in the program over all
      collection runs recorded in the performance data file.

  PCAC> SET COVERAGE/UNTIL:4 MODULE NICK BY CODEPATH

      This command specifies that test coverage be measured for every
      codepath in module NICK. Up to four executions of each codepath
      is recorded in the performance data file before the coverage
      breakpoint is removed.

  PCAC> SET COVERAGE PROGRAM BY ROUTINE

      This command specifies that test coverage be measured for every
      routine in the user program. Each routine that is called at
      least once is recorded as being covered.
Close Help