142 DBMS_PLSQL_CODE_COVERAGE
The DBMS_PLSQL_CODE_COVERAGE
package provides an interface for the collection of code coverage data of PL/SQL applications at the basic block level.
142.1 DBMS_PLSQL_CODE_COVERAGE Overview
The DBMS_PLSQL_CODE_COVERAGE
package provides an interface for collecting code coverage information at the basic block level of PL/SQL applications. A basic block refers to a single entry single exit block of PL/SQL code. PL/SQL developers want to know how well their test infrastructure exercised their code. The coverage tables are created using the CREATE_COVERAGE_TABLES
procedure.
A typical code coverage run in a session involves calls to :
-
START_COVERAGE
-
Run PL/SQL code
-
STOP_COVERAGE
The GET_BLOCK_MAP
function helps you calculate your total coverage.
See Also:
-
Oracle Database Development Guide for more information about using PL/SQL basic block coverage to maintain quality
-
Oracle Database PL/SQL Language Reference for the
COVERAGE PRAGMA
syntax and semantics -
Oracle Database PL/SQL Language Reference for more information about the PLSQL_OPTIMIZE_LEVEL compilation parameter
142.2 DBMS_PLSQL_CODE_COVERAGE Security Model
The user must have EXECUTE
privilege on the DBMS_PLSQL_CODE_COVERAGE package.
The user must have CREATE
privilege on the unit to collect coverage information about this unit.
PL/SQL basic block coverage data is collected when program units use
INTERPRETED
compilation ( parameter set PLSQL_CODE_TYPE
= INTERPRETED
). PL/SQL basic block coverage data is not
collected when program units use NATIVE
compilation. You can
disable the NATIVE
compiler by setting the parameter
PLSQL_OPTIMIZE_LEVEL
<= 1
. Regardless of
the compilation mode, coverage data for wrapped units is not collected.
142.3 DBMS_PLSQL_CODE_COVERAGE Constants
The DBMS_PLSQL_CODE_COVERAGE
package provides constants that are used with the namespace
parameter of the GET_BLOCK_MAP
function.
These constants are described in the following table.
Table 142-1 DBMS_PLSQL_CODE_COVERAGE Constants
Name | Type | Value | Description |
---|---|---|---|
|
|
|
Specifies the function namespace |
|
|
|
Specifies the package specification namespace |
|
|
|
Specifies the package definition (body) namespace |
|
|
|
Specifies the procedure namespace |
|
|
3 |
Specifies the trigger namespace |
|
|
|
Specifies the type specification namespace |
|
|
|
Specifies the type definition (body) namespace |
142.4 DBMS_PLSQL_CODE_COVERAGE Data Structures
Record Types
Table Types
142.4.1 MAP_REC Record Type
The MAP_REC record type defines the PL/SQL basic block location in the source code.
Syntax
TYPE map_rec IS RECORD ( procedure_name VARCHAR2(32767), block_num NUMBER, line NUMBER, col NUMBER, not_feasible NUMBER);
Fields
Table 142-2 MAP_REC Fields
Field | Description |
---|---|
|
The name of the procedure containing the basic block |
|
Identifies the basic block |
|
Starting line of the basic block |
col |
Starting column of the basic block |
|
Not_feasible marking of the basic block |
142.5 Summary of DBMS_PLSQL_CODE_COVERAGE Subprograms
This table lists the DBMS_PLSQL_CODE_COVERAGE
subprograms and briefly describes them.
Table 142-3 DBMS_PLSQL_CODE_COVERAGE Package Subprograms
Subprogram | Description | |
---|---|---|
Creates coverage tables |
||
GET_BLOCK_MAP Function | Gets the mapping of basic blocks to PL/SQL source | |
Starts the coverage data collection in the user’s session and returns the RUN_ID |
||
Ends the current coverage run |
142.5.1 CREATE_COVERAGE_TABLES Procedure
This procedure creates the tables used for coverage data collection.
Syntax
DBMS_PLSQL_CODE_COVERAGE.CREATE_COVERAGE_TABLES ( FORCE_IT IN BOOLEAN DEFAULT FALSE);
Parameters
Parameter | Description |
---|---|
|
The default is to raise an error if the coverage tables already exists. If set to TRUE, the tables are dropped silently if the tables already exist, and new tables are created. |
Exceptions
Table 142-4 CREATE_COVERAGE_TABLES Exceptions
Exception | Description |
---|---|
COVERAGE_ERROR |
The |
142.5.2 GET_BLOCK_MAP Function
This function gets the mapping of basic blocks to PL/SQL source.
Syntax
DBMS_PLSQL_CODE_COVERAGE.GET_BLOCK_MAP( unit_owner IN VARCHAR2, unit_name IN VARCHAR2, namespace IN POSITIVE) RETURN T_MAP_REC;
Table 142-5 Parameters
Parameter | Description |
---|---|
|
The owner of the unit. The unit owner is case insensitive. If the unit_owner is empty or NULL, then it defaults to the current schema. |
|
The unit whose mapping is to be gotten. The unit_name is case insensitive. |
|
Namespace to which this unit_name gets resolved. See DBMS_PLSQL_CODE_COVERAGE Constants for a list of valid namespace values. |
142.5.3 START_COVERAGE Function
This function starts the coverage data collection in the user’s session and returns a unique identifier RUN_ID
for the run.
Syntax
DBMS_PLSQL_CODE_COVERAGE.START_COVERAGE ( run_comment IN VARCHAR2) RETURN NUMBER;
Parameters
Parameter | Description |
---|---|
|
Allows the user to name a run and identify the test. |