Coverage Engine Object

Article
11/14/2006

Category	Reporting
Class	cov_engine
Class Library	coverage.vcx
Base Class	formset
Parent Class	scov_formset

This formset is not a subclass of _formset, therefore the Coverage Profiler runs in Visual FoxPro 5.0 and later.

Remarks

This class is subclassed from the Visual FoxPro formset class. Though it provides no visible components, it provides the datatsession of a formset class and includes provisions for feedback on coverage log processing through WAIT WINDOW NOWAIT, MESSAGEBOX( ), and subclasses of MSComDlg.CommonDialog. This formset has one member, a toolbar, that remains hidden while providing a container for custom objects, such as CusRegistry or Dialog subclasses. Cov_standard, a subclass of cov_engine, provides a sample user interface, the Coverage Profiler Application. You can subclass either cov_engine or cov_standard to fit your requirements.

aAddIns array Property

This one-dimensional array holds a list of registered add-in files.

Default .F. (the array will be dimensioned [1])

aFileTypes array Property

This two-dimensional array holds a list of the file types (extensions) the Coverage Profiler handles. The first column holds the extension listed in the coverage text log (such as .fxp or .vct). The second column holds the extension of the matching source code file (such as .prg or .vcx) that the Coverage Profiler must locate to analyze the code. This array is filled at startup by the FillFileTypeArray( ) method.

Default .F. (the array will be dimensioned [1, 2])

cAddIn Property

Specifies the add-in last run successfully. At startup this property can be set by an add-in passed to the Coverage Profiler application as a parameter and run in the Init. Otherwise, if add-in file names have been stored to the registry previously, this property is filled using the aAddIns array.

Default ""

cBaseFontName Property

Specifies a base font name for any interface elements. The default for this attribute when no preference has been saved to the registry is the #DEFINE constant COV_DEFAULT_BASE_FONTNAME in COV_TUNE.H.

Default MS Sans Serif

cBaseMonoFontName Property

Specifies a base font name for any interface elements that require a monospaced font.

The default for this attribute when no preference has been saved to the registry is, first, any Visual FoxPro resource file entry for MODIFY COMMAND window preferences. Otherwise, the coverage engine looks for a Visual FoxPro registry entry for the Trace window. If one of these is not found, the coverage engine uses the #DEFINE constant COV_DEFAULT_MONO_FONTNAME in COV_TUNE.H.

Default Courier New

cCovFilesAlias Property

Specifies the name of the cursor holding names of source files the Coverage Profiler should not locate and analyze. The engine fills this cursor with a set of file names using the CreateCoverageFileNameCursor( ) and FillCoverageFileNameCursor( ) methods. You can use the coverage engine abstract AdjustCoverageFileNameCursor( ) method to add file names to the set.

Default IgnoredFiles

cDefaultWritePath Property

Specifies the path to cSourceFile. Supplies the default path for any file output of the Coverage Profiler.

Default ""

cMarkExecuted Property

Specifies the character(s) that marks lines of code that executed according to the current coverage log. Although this property defaults to an empty string, the engine uses the SetMarks( ) procedure to adjust the length of cMarkExecuted and cMarkNotExecuted to equal lengths so the appearance of marked code is unspoiled. At startup, therefore, cMarkExecuted's value is SPACE(4), to match the default length of cMarkNotExecuted.

Default ""

cMarkNotExecuted Property

Specifies the character(s) that marks lines of code not run during the current coverage log.

Default |+SPACE(3)

cSavedSkipFiles Property

Specifies the name of the table (.dbf) file that contains the list of source files skipped during coverage analysis.

Default ""

cSavedTargetDBF Property

Specifies the name of the table (.dbf) file that contains the coverage results.

Default ""

cSkippedAlias Property

Specifies the name of the cursor which holds names of source files the Coverage Profiler could not locate or analyze. The engine fills this cursor using the CreateSkippedCursor( ) method and saves it to disk using the SaveSkippedCursor( ) method.

Default SkippedFiles

cSourceAlias Property

Specifies the name of the source which holds the appended and processed records stored by the coverage text log. The engine creates this cursor in the CreateSourceCursor( ) method and provides the abstract AdjustSourceCursor( ) method so you can add fields, index tags, and so on. Then the engine fills the cursor with records from the text log in the FillSourceCursor( ) method.

Default FromLog

cSourceFile Property

Specifies the name of the file to be analyzed. You can specify this value as the first parameter of the DO (_COVERAGE) WITH command.

Default ""

cSuspendedLog Property

Specifies the name of the current coverage log (SET(COVERAGE)) if the Coverage Profiler suspends coverage data logging. This property is set with the SuspendCoverage( ) method.

Default ""

cTargetAlias Property

Specifies the target cursor which holds the names of classes, source file names, coverage-marked procedure source code, and coverage statistics. The engine creates this cursor in the CreateTargetCursor( ) method and provides the abstract AdjustTargetCursor( ) method so you can add fields, tags, and so on. Then the coverage engine locates and analyses source code in the FillTargetCursor( ) method.

Default MarkedCode

iLenExecuting

Specifies the length of the field in the source work file that contains information about the object and method name that is running covered lines of code when the #DEFINE COV_TOPSPEED in COV_TUNE.H is false (.F.). You can decrease the default value, with care, if your fully-qualified object names and method names are short and if you want to conserve the disk space used by the Profiler work files. See COV_TUNE.H for more information about this value. See Conserving Disk Space During Coverage Runs for more information on using iLenExecuting.

Default 115

iLenDuration

Specifies the length, including decimal places, of the numeric field in the source file.

Default 8 (in Visual FoxPro versions 5.0 and 6.0. Defaults to 11 in later versions.)

iLenHostFile

Default 115

iLenObjClass

Specifies the length of a field in the source and target work files that holds information about the object executing Covered lines of code when the #DEFINE COV_TOPSPEED in COV_TUNE.H is false (.F.). To conserve the disk space used by the Profiler work files, you can decrease the default value, with care, if your object names are short. You can do this even when object names are fully-qualified by their container hierarchy. See COV_TUNE.H for more information about this value. See Conserving Disk Space During Coverage Runs for more information on using iLenObjClass.

Default 115

lBaseFontBold Property

Specifies a base font attribute (bold) for any displayed characters.

Default .F.

lBaseFontItalic Property

Specifies a base font attribute (italic) for any displayed characters.

Default .F.

lBaseMonoFontBold Property

Specifies a base font attribute (bold) for any displayed characters that require a monospaced font.

Default .F.

lBaseMonoFontItalic Property

Specifies a base font attribute (italic) for any displayed characters that require a monospaced font.

Default .F.

lError Property

A flag that specifies an error occurred; set by the Error method and checked by critical operations during processing.

Default .F.

lInCoverageFrame Property

Specifies whether the Coverage Profiler opens in the main Visual FoxPro window. The default displays Coverage Profiler elements in a separate window.

Default .F.

lInProfileMode Property

Specifies whether the Coverage Profiler analyzes the coverage log for profiling characteristics. In the default setting, the Coverage Profiler analyses for coverage characteristics.

Default .F.

lMarkAllOnLoad Property

Specifies whether all source code is marked when a target file is loaded. In the default setting, individual source code records are marked one at a time as required by the user.

Default .F.

lSaveFormPositions Property

Specifies whether all forms in the formset receive an instance of cov_SavePosition to handle form positions and size.

Default .F.

lSmartPath Property

Specifies whether the engine retains a reference to directories in which you have located files.

Default .T.

lStartInProfileMode Property

Specifies how the lInProfileMode property is set when each coverage log loads. This value is significant when the property lMarkAllOnLoad is set to true (.T.).

Default .F.

lTurnedOffTrace Property

Specifies whether the Coverage Profiler issued SET TRBETWEEN OFF during processing.

Default .F.

lUsingRegistry Property

Specifies whether user options are saved to and restored from the Microsoft Windows registry.

Default .T.

lUsingStatusBar Property

Determines whether feedback messages during processing are displayed in the status bar or as a WAIT WINDOW NOWAIT message. The status bar is used when the Coverage Profiler runs in the main Visual FoxPro window or in Unattended mode and STATUS BAR is ON.

Default .F.

lVFP5 Property

Specifies whether the Coverage Profiler is running in Visual FoxPro 5.0.

Default (ATC("FoxPro 05",VERSION( )) > 0)

nBasefontsize Property

Specifies a base font size for any displayed characters.

Default 11 (defaults to 8 in version 5.0 and 6.0)

oFrame Property

Specifies a reference to the Coverage Frame window when the Coverage Profiler exists in a separate window. The engine makes sure this window exists before displaying any related dialog boxes or other elements (including common dialog subclasses, SET TALK display, and so on).

Default .NULL.

AddFormPositionSaver( ) Method

Adds an instance of cov_SavePosition to a form to save and restore form size and position.

AddFormPositionSaver(toForm)

Return Values

None

Parameters

toForm
Specifies that the cov_SavePosition object is saved to a form.

AddPath( ) Method

Extracts directory information to concatenate to SET(PATH).

AddPath(tcFileName)

Return Values

None

Parameters

tcFileName
Specifies a file name.

Remarks

Extracts the directory information from the passed file name, tcFileName, to concatenate into the current SET(PATH).

AddRegisteredAddin( ) Method

Adds file name to the aAddIns array.

AddRegisteredAddin(tcFileToAdd)

Return Values

None

Parameters

tcFileToAdd
Specifies the file to add to the aAddIns array.

Remarks

Adds a file name, TcFileToAdd, to the aAddIns array when called by the RunAddIn( ) method after an add-in runs successfully.

AdjustCoverageFilenameCursor( ) Method

Enables adding files to cursor list of unanalyzed files.

AdjustCoverageFilenameCursor(tcTarget)

Return Values

NOT THIS*.lReturn*

Parameters

tcTarget
Specifies the name of the cursor you want to modify.

Remarks

Makes it possible for you to add files that you do not want analyzed to the cursor's file list when called by the CreateCoverageFilenameCursor( ) method. See the cCovFilesAlias property.

AdjustSourceCursor( ) Method

Abstract method that makes it possible for you to add index tags and custom fields to the source cursor when called by the CreateSourceCursor( ) method.

AdjustSourceCursor(tcSource)

Return Values Values

NOT THIS*.lReturn*

Parameters

tcSource
Specifies the name of the cursor containing the source records.

AdjustTargetCursor( ) Method

Abstract method called by the CreateTargetCursor( ) method makes it possible for you to add index tags and custom fields to the target cursor.

AdjustTargetCursor(tcTarget)

Return Values Values

NOT THIS*.lReturn*

Parameters

tcTarget
Specifies the name of the table being modified.

ClearStatus( ) Method

Removes a message from the status bar or performs a CLEAR WAIT WINDOW command. See lUsingStatusBar property.

ClearStatus( )

Return Values

None

Parameters

None

CreateCoverageFilenameCursor( ) Method

Creates a cursor to hold the names of source files that the Coverage Profiler should not locate and analyze. See the cCovFilesAlias property.

CreateCoverageFileNameCursor( )

Return Values

lReturn AND NOT THIS.lError

Parameters

None

CreateForms( ) Method

At startup, displays the Coverage Profiler window after workfiles have been set up if the coverage engine is not in Unattended mode. In the coverage engine base class, this method creates only the Coverage frame (if the engine is not running in the Visual FoxPro window). Subclasses can augment this method to add their own dialogs.

CreateForms( )

Return Values

None

Parameters

None

CreateSkippedCursor( ) Method

The engine creates this cursor by looking for deleted records in the Source table, because skipped records are deleted when the engine encounters file names that cannot be located or that are in the Ignored Files list during its load of the log file. See the CSkippedAlias property.

CreateSkippedCursor(tcSource, tcSkipped)

Return Values

NOT THIS.lError

Parameters

tcSource
Specifies the name of the table containing the source records.
TcSkipped
Specifies the alias of the cursor containing the skipped records.

CreateSourceCursor( ) Method

Creates a source cursor in the following format:

CREATE CURSOR(cSource) ;
(Duration n(COV_LEN_DURATION,N_COVLOG_PRECISION), ;ObjClass c(COV_LEN_OBJCLASS), ;Executing c(COV_LEN_EXECUTING), ;Procline i, ;Hostfile c(COV_LEN_HOSTFILE), ;Stacklevel I, ;FileType c(4) )

The Stacklevel field is excluded when the value of the lVFP5 property is true (.T.). See COV_TUNE.H for #DEFINE field lengths.

CreateSourceCursor(tcSource)

Return Values

lReturn AND NOT THIS.lError

Parameters

tcSource
Specifies the name of the cursor containing the source records.

CreateTargetCursor( ) Method

Creates a target cursor in the following format:

CREATE CURSOR (cTarget) ;
(Hostfile c(COV_LEN_HOSTFILE), ;ObjClass c(COV_LEN_OBJCLASS), ;FileType c(4), ;Marked   m, ;Profiled m, ;SourceCode m, ;Coverable i, ;Covered i, ;ObjTotal i, ;ObjHits i)

See COV_TUNE.H for #DEFINE field lengths.

CreateTargetCursor(tcSource, tcTarget)

Return Values

NOT THIS.lError

Parameters

tcSource
Specifies the name of the file to analyze.
TcTarget
Specifies the name of the file you want to modify.

Remarks

The target file contains one record for each of the following in the coverage log:

An ASCII source file.
A class contained in an ASCII source file.
A class contained in a .vcx or .scx file.
A stored procedure list in a .dbc file.
A Data Environment class or other Data Environment member class (such as a cursor) in a .frx or .lbx source file.

DeleteRegisteredAddin( ) Method

Removes a file name from the aAddIns array.

DeleteRegisteredAddin(tcFileToDelete)

Return Values

None

Parameters

tcFileToDelete
Specifies the add-in to remove from the registry.

Remarks

Called by the RunAddIn method after an add-in does not run successfully, whether the Registry is currently in use or not.

DisplayProjectStatistics( ) Method

Enables reporting after project statistics have been gathered in GetProjectStatistics( ).

DisplayProjectStatistics(tcSource, tcTarget, tcProject)

Return Values

NOT THIS.lError

Parameters

tcSource
Specifies the name of the table containing the source records.
tcTarget
Specifies the name of the table being modified.
tcProject
Specifies the alias of the project being analyzed.

DoMessage( ) Method

Displays tcMessage.

DoMessage(tcMessage [, tnMessageBoxOptions [, tcMessageBoxTitle]])

Return Values

liReturn

Parameters

tcMessage
Specifies the message that appears in the MESSAGEBOX.
TnMessageBoxOptions
Specifies the MESSAGEBOX nDialogBoxType setting.
TcMessageBoxTitle
Specifies the MESSAGEBOX cTitleBarText setting.
LiReturn
Specifies any return value from MESSAGEBOX( ), or 0 if a WAIT WINDOW executes.

Remarks

If the Coverage Profiler is running in Unattended mode, the message is displayed in a WAIT WINDOW TIMEOUT window so it does not prevent further processing. You can specify the timeout value using COV_TIMEOUT_SECS (a #DEFINE in COV_TUNE.H).

Error( ) Method

Sets the dialog error flag.

Error(nError, cMethod, nLine)

Return Values

None

Parameters

nError
Specifies the Visual FoxPro error number.
CMethod
Specifies the name of the method that caused the error.
NLine
Specifies the line number where the error occurred.

Remarks

Depending on the value of COV_DEBUG (a #DEFINE in COV_TUNE.H), this will display an error MESSAGEBOX and release the engine or display a WAIT WINDOW with error information and invoke the native Visual FoxPro error handler to make it possible for you to cancel, suspend, or ignore the current error.

FillCoverageFileNameCursor( ) Method

Adds files to the list of ignored files.

FillCoverageFileNameCursor( )

Return Values

NOT THIS.lError

Parameters

None

Remarks

CreateCoverageFileNameCursor( ) calls this method to add the names of the coverage engine file set to the group of files that should be ignored during processing. This method is a hard-coded set of INSERTs in the base coverage engine. You can override this set in a subclass designed to read in a set of file names from a text file generated from the Coverage.pjx file list.

FillFileTypeArray( ) Method

Initializes the aFileTypes array with known file extensions. See the aFileTypes property.

FillFileTypeArray( )

Return Values

NOT(EMPTY(THIS.aFileTypes[1,1]) OR THIS.lError)

Parameters

None

FillOneTargetRecord( ) Method

Adds unmarked source code to memo field.

FillOneTargetRecord(tcSource, tcTarget, tlFillingAll)

Return Values

lReturn AND(NOT THIS*.lError)*

Parameters

tcSource
Specifies the name of the table containing the source records.
TcTarget
Specifies the name of the table being modified.
TlFillingAll
Specifies whether all records are processed in a loop, which changes the user feedback and displayed character handling.

Remarks

Places the unmarked source code for a target record into the appropriate memo field for later marking using a different strategy to find the right code for each type of source code. When COV_TOPSPEED is not #DEFINEd true (.T.), this method also places certain initial statistics into the Target file.

FillSourceCursor( ) Method

APPENDs the coverage log contents to the coverage analysis source file.

FillSourceCursor(tcSource)

Return Values

lReturn

Parameters

tcSource
Specifies the name of the source file.

Remarks

This method calls the SourceAvailable( ) method to eliminate records that refer to source files unavailable for analysis. It marks these records deleted in the source cursor.

FillTargetCursor( ) Method

Calls the FillOneTargetRecord( ) method for all target records in a loop.

FillTargetCursor(tcTarget)

Return Values

(THIS*.iTargetReccount >* 0**AND NOT THIS*.lError*)

Parameters

tcTarget
Specifies the target file that receives the processed results.

Remarks

Replicates the ObjHits statistics from the CreateTargetCursor( ) method for additional records referring to the same source files with the target files. See the CreateTargetCursor( ) method.

FilterListByLocation( ) Method

Provides a placeholder for future enhancements.

FilterListByLocation( )

Return Values

NOT THIS.lError

Parameters

None

Remarks

FilterListByLocation( ) can be called either when a log loads or in response to a user action, with or without the Coverage Profiler application. This method is abstract in the engine.

GetAlias( ) Method

Returns the current or default alias of a Coverage Profiler workfile type.

GetAlias(tAlias, tcWhichProp)

Returns

cReturn

Parameters

tAlias
Specifies the alias of a file.
tcWhichProp
Specifies the workfile type (currently, either Source or Target) of the current default.

Remarks

GetAlias( ) returns either a currently used alias or the default alias of one of the Coverage Profiler workfile types. The valid workfile types include the following:

"SOURCE","TARGET","SKIPPED","COVFILES", and "PROJECT"

(The list of types is #DEFINEd in COV_SPEC.H as COV_KNOWN_ALIAS_PROPERTIES.) Each workfile type matches one c…Alias property to specify the default alias for this workfile.

The Coverage Profiler usually has a cursor open using each one of the workfile default aliases. However, the Coverage Profiler is capable of handling many sets of workfiles at the same time, within its data session, as long as you specify separate aliases for each one. The GetAlias( ) method and the system of defined work types, plus c…Alias, properties make it possible for you to have default alias names without the default aliases being hard-coded.

The engine methods that process the workfiles use aliases as parameters, so you can specify which source, target, or other file you are interested in at any time. Because you usually are interested only in one set of workfiles, however, these methods all use the GetAlias( ) methods to specify which alias and workfile default type to seek if you do not pass them a specific alias or aliases.

GetFontsFromUser( ) Method

Creates an instance of a common dialog subclass to ask the user to set font properties. If lUsingOCXs is False (.F.) or there has been an error creating an instance of the common dialog, the method uses the GETFONT( ) method. If the first parameter, tlBaseMonoFont, is True (.T.), the method shows only monospaced fonts and fills the monospaced font attribute properties of the engine. If this parameter is False (.F.), the second set of base font attribute properties is filled from a list of all available screen fonts.

See to the GetResourceLocation( ) method for more information on the lUsingOCXs property.

GetFontsFromUser(tlBaseMonoFont, toMemberHost )

Return Values

lFontChange AND NOT THIS.lError

Parameters

tlBaseMonoFont
Specifies the default monospace font style.
ToMemberHost
Specifies a reference to the current Coverage object.

GetProjectStatistics( ) Method

Creates a cursor containing project information.

GetStatistics(tcSource, tcTarget, tcProject)

Return Values

lReturn

Parameters

tcSource
Specifies the name of the alias containing the source records.
tcTarget
Specifies the name of the alias being modified.
tcProject
Specifies the project containing the source files.

Remarks

The information contained in the cursor is in the following format.

CREATE CURSOR(cProject) ;

(Hostfile c(COV_LEN_HOSTFILE), ;FileType c(4), ;Coverable n(8), ;Covered n(8), ;ObjTotal n(8), ;ObjHits n(8))

GetProjectStatistics( ) creates a header file in this cursor, indicating the project to which this cursor applies and fills this cursor with statistics drawn from the current coverage log that apply to each source file in the project. If necessary, GetProjectStatistics( ) calls MarkOneTargetRecord( ) for any project files that have not yet had their source code marked.

GetRegisteredAddins( ) Method

Fills the aAddIns array and the cAddIn property.

GetRegisteredAddins( )

Return Values

None

Parameters

None

GetRegistryKeyValue( ) Method

Retrieves registry value of user option

GetRegistryKeyValue(tcOption, tDefaultValue, tcPath)

Return Values

vReturn

Parameters

tcOption
Specifies the file type option.
tDefaultValue
Specifies the default registry value.
tcPath
Specifies RegKey.

Remarks

This method, typically used at startup, uses the registry-handling member of the toolbar in the engine formset to get a registry key value for a user option. It converts the registry value to other TYPE( )s as required and compares this TYPE( ) to the passed value, tDefaultValue. It returns the registry value or the default value if the registry value is not found or is of the wrong type.

GetResourceLocation( ) Method

Specifies whether GETFILE( )/ShowOpen( ) strategy or PUTFILE( )/ShowSave( ) strategy is followed.

GetResourceLocation(tcHost, tcTitle, tcCDLFilter, tcFileName, tcWhichDialog, [toMemberHost] )

Return Values

lcFileName

Parameters

tcHost
Specifies the name of the file the method is starting from, usually seeking the matching file name of the uncompiled version of the code. If it is passed, it provides information for the common file dialog .InitDir property.
tcTitle
Specifies the title to use in the dialog or, in the GETFILE( )/PUTFILE( ) version, to use as a WAIT WINDOW NOWAIT prompt. If tcHost also is passed and includes a file name, then this information is added to the dialog title or prompt.
tcCDLFilter
Specifies the file types allowed in the dialog. This parameter is expressed in the format required by the common dialog filter expression. If the GETFILE( )/PUTFILE( ) is called, the method parses the common dialog filter to put it into appropriate format for the two Visual FoxPro functions.
tcFileName
Specifies the default file name to display.
tcWhichDialog
Specifies the GETFILE or PUTFILE.
toMemberHost
Specifies an optional form reference that can be passed to indicate where the dialog is displayed. If toMemberHost is not passed, the file dialog will display relative to the Coverage frame (if the Coverage frame exists) or to the first form in the formset collection (if the Coverage Profiler is in the Visual FoxPro window).

Remarks

Adds a member of the appropriate common dialog subclass (depending on the value of tcWhichDialog) if this is the first call. The dialog subclasses differ in how they set various flags.

Note This method provides for additional dialog subclasses, showing a Help file or print dialog, to be instantiated and used in the future.

If a common dialog subclass or .ocx-related error occur in the Coverage Profiler, this method sets the lUsingOCXs property to false (.F.) and uses GETFILE( )/PUTFILE( ).

You can set the #DEFINE COV_USE_OCXS if you prefer to default to the native Visual FoxPro functions even if there are no OCX errors.

GetTableName( ) Method

Generates file names for unattended operation.

GetTableName(tcWhichSuffix)

Return Values

cLogfileStem+SUFFIX[+n]+.dbf

Parameters

tcWhichSuffix
Specifies which file extension to use.

Remarks

This method allows the coverage engine to generate file names with which to save its work to disk without overwriting existing files. Generally it just supplies file name defaults, but in Unattended mode, this method creates the file names without user intervention. Each method that saves a file to disk calls GetTableName( ) with a specific suffix; for example, in the SaveSkippedCursor:

cDBFName = ; THIS.GetTableName(COV_SKIPFILEDBF_SUFFIX)

GetTableName( ) uses the path and stem of the current log file name (THIS.cSourceFile) and attaches the appropriate suffix to this stem plus a digit, followed by the DBF extension. For example, Testlog.txt would produce TESTLOG_SKIP1.DBF in the previous example.

GetTableName( ) then increments the digit if the generated file name exists, until it finds a name that does not exist.

The default suffixes are #DEFINEs in COV_TUNE.H.

LockScreens( ) Method

Freezes or releases LockScreen properties and MousePointer properties for all members of _Screen during various long procedures.

LockScreens(tlOn)

Return Values

Logical. .T.

Parameters

tlOn
Specifies whether to lock the Lockscreen and MousePointer properties.

MarkAllTargetRecords( ) Method

Calls the MarkOneTargetRecord( ) method for all target records in a loop. Can be called because lMarkAllOnLoad is true (.T.) or because the coverage engine is in Unattended mode.

MarkAllTargetRecords(tcSource, tcTarget)

Return Values

NOT THIS*.lError*

Parameters

tcSource
Specifies the name of the table containing the source records.
tcTarget
Specifies the name of the table being modified.

MarkCodeLine( ) Method

Creates a marked-up version of a line of code, plus coverage statistics.

MarkCodeLine(tcLine, tiExecuted, tnFirst, tnAverage)

Return Values

CMarkedLine

Parameters

tcLine
Specifies the line of code.
tiExecuted
Specifies the number of times tcLine was run.
tnAverage
Specifies the average length of time to run.

Remarks

In Coverage mode, MarkCodeLine( ) marks code as "Executed" if tiExecuted is a positive number and "not Executed" if tiExecuted is 0. In Profile mode, MarkCodeLine( ) marks coverage statistics appropriately for the line. In either mode, MarkCodeLine( ) marks code as uncoverable (preceded by spaces) if tiExecuted is .NULL.

MarkOneTargetRecord( ) Method

Determines the marked status of the current line.

MarkOneTargetRecord(tcSource, tcTarget, tlFillingAll)

Return Values

lReturn AND (NOT THIS*.lError)*

Parameters

tcSource
Specifies the name of the table containing the source records.
tcTarget
Specifies the record being modified.
tlFillingAll
Specifies whether other target records are being processed. If all records are processed in a loop, then the user feedback and handling of displayed characters changes.

Remarks

Determines whether the current target record, tcTarget, is already marked in the current coverage mode and, if not, passes the relevant information to the MarkTargetCoverage( ) method for processing.

MarkTargetCoverage( ) Method

Marks up a copy of the source and REPLACEs a memo field in the target file.

MarkTargetCoverage(tcSource, tcTarget)

Return Values

NOT (EMPTY(cMemo) OR THIS.lError)

Parameters

tcSource
Specifies the name of the table containing the source records.
tcTarget
Specifies the name of the table being modified.

Remarks

MarkTargetCoverage( ) creates a marked-up version of tcSource and REPLACEs a memo field in the target file, tcTarget, (whether the code is for a class or a full procedure file).

To perform this action, the method starts with the sourcecode memo. The memo field REPLACEd depends on whether Coverage Profiler is marking Profiler or Coverage information, because the Target record retains both sets of marked-up code. This method parses the source code and evaluates its statistics line by line. By default, this method calls the MarkCodeLine( ) method to mark each line when it has the appropriate statistics. However, the way this method marks the code line is #DEFINEd as COV_MARK_CODE_LINE in COV_TUNE.H, not directly implemented as a call to the MarkCodeLine( ) method. This makes it possible for you to replace the call to the MarkCodeLine( ) method with a different marking system. A second #DEFINE, COV_TOPSPEED, in COV_TUNE.H also makes it possible for you to switch the MarkCodeLine( ) call to a simpler, in-line marking system for fastest response time.

MarkTargetCoverage( ) evaluates each line to find out whether it was executed, how many times it was executed, and its execution timings (first and average) when in Profile mode. However, many lines are considered uncoverable in Coverage Profiler. These lines, such as comments, DEFINE CLASS and ELSE/Otherwise statements, and lines within TEXT … ENDTEXT, do not appear in coverage logs, because they are not executable.

Note Other uncoverable code lines include #DEFINE statements, empty lines, continuations of executing lines, and parameter lines.

This method sets the number of times these lines run to .NULL. These lines are not considered when Coverage Profiler compiles statistics. In addition, lines broken by continuation symbols (semicolons) are considered as a single line of code and marked only on the last line.

OrderListByTime( ) Method

Provides a placeholder for future enhancements and subclasses.

OrderListByTime( )

Return Values

NOT THIS.lError

Parameters

None

Remarks

OrderListByTime( ) is abstract in the engine.

PassedProperParams( ) Method

PassedProperParams(tcFile, tlUnattended, tcAddIn)

Return Values

lReturn

Parameters

tcFile
Specifies the name of the log file.
tlUnattended
Specifies whether to run in Unattended mode.
tcAddIn
Specifies the add-in file name(s).

Remarks

Test at startup to determine whether passed parameters are appropriate to the class. If any passed parameters are not appropriate TYPE( ), provides a MESSAGEBOX showing what parameters may be passed and RETURNs false (.F.), preventing any further coverage processing, as well as the creation of an instance of the class.

This method uses a MESSAGEBOX for feedback and stops processing even if the Coverage Profiler is starting up in Unattended mode. If you are setting up the Coverage Profiler for automated testing, be sure your calling program sends correct parameters or the analysis will not proceed.

RestoreCoverage( ) Method

Resumes coverage logging from suspended operation.

RestoreCoverage( )

Return Values

None

Parameters

None

Remarks

If the Coverage Profiler previously suspended coverage logging, this method gives the user a chance to resume coverage logging when the Coverage Profiler releases. The user can choose to overwrite this previous log, append new log entries to it, or not resume coverage logging at that time.

RunAddin( ) Method

Runs an add-in file.

RunAddin(tcAddin)

Return Values

lReturn AND NOT THIS*.lError*

Parameters

tcAddin
Specifies the name of the file to run.

Remarks

RunAddin( ) runs a file (.scx, .fxp, .app, .prg, .qpx, .qpr, .mpx, or .mpr) that adds functionality to the Coverage object. If you do not pass a file name, RunAddin( ) runs the file specified by the cAddIn property.

The tcAddin file must accept an object reference, because the file is run by passing a reference to the coverage form, as in the following examples (depending on the file type):

DO (cFileName) WITH THIS
DO FORM (cFileName) WITH THIS

SaveFormsetAttributes( ) Method

Saves general frame and formset characteristivs to the registry as Profiler ends.

SaveFormsetAttributes( )

Return Values

None

Parameters

None

SaveOptionsToRegistry( ) Method

Saves current user values to the registry.

SaveOptionsToRegistry( )

Return Values

lSuccess

Parameters

None

Remarks

SaveOptionsToRegistry( ) can be called any time the user's current values should be saved to the registry. It saves the following user preferences:

Work options group
lStartInProfileModelSmartPathlMarkAllOnLoadcMarkExecutedcMarkNotExecutedlRegisterAddIn
UI options group
Font name, size, italic, bold for base monospace font

There are a few registry settings not saved by this method, because they have to be done at specific moments during the life of the engine. These are:

Coverage or the main Visual FoxPro frame (must be done when the user makes a choice and will be in effect next session but does not correspond to or affect any of the coverage property values for this session).

Registered add-ins (this array is manipulated over the life of the session, and the full set of file names it contains is saved to the registry at the end of the session).

SaveSkippedCursor( ) Method

Saves the skipped files cursor to disk.

SaveSkippedCursor(tcSkipped)

Return Values

RETURN NOT THIS.lError

Parameters

tcSkipped
Specifies the cursor containing skipped records.

Remarks

Saves the skipped files cursor to disk if it contains any records and places the name of the table on disk in the cSavedSkipFiles property. See the cSkippedAlias and cSavedSkipFiles properties.

SaveTargetToDisk( ) Method

Saves output file, including marked-up code and statistics, to disk.

SaveTargetToDisk(tcTarget)

Return Values

lReturn and NOT THIS*.lError*

Parameters

tcTarget
Specifies the name of the modified table saved to disk.

SetFontValues( ) Method

Sets up initial font attribute values using registry key values and other defaults.

SetFontValues( )

Return Values

NOT THIS*.lError*

Parameters

None

Remarks

See cBaseFontName and cBaseMonoFontName for information on how the coverage engine derives these defaults.

SetFormsetAttributes( ) Method

Reads and restores general frame and formset characteristics.

SetFormsetAttributes( )

Return Values

None

Parameters

None

Remarks

Reads and restores general frame and formset characteristics from the registry as Profiler starts.

SetLogFile( ) Method

Attempts to set up a file for analysis.

SetLogFile(tcFile)

Return Values

lReturn

Parameters

tcFile
Specifies the name of the file to analyze.

Remarks

If you pass no string value, the SET COVERAGE value is used. If there is no current log file, the method prompts for a file name. If a log file can be set successfully, the method returns .T. If the user designates no log file, the method returns. F. If no new log is specified, the Coverage Engine returns to the currently loaded log, if one is loaded, or releases, if no log is loaded.

SetMarks( ) Method

Synchronizes and returns the values of cMarkExecuted and cMarkNotExecuted.

SetMarks( )

Return Values

NOT THIS*.lError*

Parameters

None

Remarks

Synchronizes the lengths of cMarkExecuted and cMarkNotExecuted and returns the values of either or both properties to a default if they are not character-type or both properties are empty. If user options are not available from the registry, this method gets defaults from the #DEFINE values, COV_DEFAULT_MARKNOTEXECUTED and COV_DEFAULT_MARKEXECUTED, which you can set in COV_TUNE.H. A third #DEFINE, COV_DEFAULT_MARKSPACING, makes sure there is space between the marks and the line of code.

SetRegisteredAddins( ) Method

Saves the file names in the aAddIns array to registry values.

SetRegisteredAddins( )

Return Values

None

Parameters

None

SetRegistryKeyValue( ) Method

Sets a registry key value from a user option.

SetRegistryKeyValue(tcWhichOption, tValue)

Return Values

NOT THIS.lError

Parameters

tcWhichOption
Specifies the user option to be accessed.
tValue
Specifies the value of tcWhichOption.

Remarks

SetRegistryKeyValue( ) uses the registry-handling member of the toolbar in the engine formset to set a registry key value from a user option. It converts all values to string type before sending them to the registry-handler to apply to the registry.

SetUIFonts( ) Method

Provides font preferences.

SetUIFonts( )

Return Values

NOT THIS*.lError*

Parameters

None

Remarks

Abstract in the engine, called by SetUiOptions, SetUIFonts( ), makes it possible for the user font preferences saved in the various Base and BaseMont font properties to be applied to appropriate displayed characters .

SetUIOptions( ) Method

Sets UI options and defaults.

SetUIOptions( )

Return Values

lReturn and NOT THIS*.lError*

Parameters

None

Remarks

Sets up initial UI options according to user preferences or defaults after initial setup of workfiles. This group of options includes fonts and the array of registered add-ins. It is required for UI display and user interaction with the workfiles, after they have been processed.

SetUIToShowCode( ) Method

Enables display of current target record in new log.

SetUIToShowCode(tcTarget)

Return Values

NOT THIS*.lError*

Parameters

tcTarget
Specifies the name of the table being modified.

Remarks

Abstract in the engine, called at the end of SetupWorkFiles( ) to allow UI to show current Target record in the newly loaded log.

SetUIToShowFileStates( ) Method

Enables reporting of log loading status.

SetUIToShowFileStates(tcSource, tcTarget)

Return Values

NOT THIS*.lError*

Parameters

tcSource
Specifies the name of the table containing the source records.
tcTarget
Specifies the name of the table being modified.

Remarks

Abstract in the engine, called at the end of SetupWorkFiles( ) to allow UI to indicate success or failure or current attempt to load a log.

SetUpWorkFiles( ) Method

Sets and validates a coverage log.

SetupWorkFiles(tcLogFile, tcSource, tcTarget)

Return Values

lReturn AND NOT THIS.lError

Parameters

TcLogFile
Specifies the name of the text log to analyze.
tcSource
Specifies the name of the file to use as source.
tcTarget
Specifies the name of the cursor being modified.

Remarks

SetUpWorkFiles( ) sets and validates a coverage log and then creates and fills the source and target work files for this text log. If the user choice is the same as the log file currently loaded, the method asks the user whether the log should be reloaded and analyzed. It makes sure the log is not open in a text window before loading the log. If the user specifies lMarkAllOnLoad, it marks all records in the current mode (Coverage or Profile) after successfully filling the target file with source code entries. If Coverage Profiler is in Unattended mode, it marks all records in both Coverage and Profile mode after successfully filling the target file. If the load succeeds, this method also sets the cDefaultWritePath to mark the path of the text log and the cSourceFile property to hold the name of this text log.

SetWorkOptions( ) Method

Sets initial user defined options.

SetWorkOptions( )

Return Values

NOT THIS*.lError*

Parameters

None

Remarks

SetWorkOptions( ) sets up initial options according to user preferences or defaults before initial setup of workfiles. This group of options includes coverage marks and initial coverage mode and is required for processing the workfiles.

ShowProjectStatistics( ) Method

Runs coverage analysis figures against a Visual FoxPro project.

ShowStatistics(tcSource, tcTarget, tcProject)

Return Values

lReturn AND NOT THIS.lError

Parameters

tcSource
Specifies the name of the table containing the source records.
tcTarget
Specifies the name of the table being modified.
tcProject
Specifies the project containing tcSource.

Remarks

ShowProjectStatistics( ) calls GetProjectStatistics( ) and DisplayProjectStatistics( ) to run coverage analysis figures against a specific Visual FoxPro project set of files.

ShowStatistics( ) Method

Abstract in the base engine.

ShowStatistics( )

Return Values

NOT THIS.lError

Parameters

None

ShowStatus( ) Method

Places a message in the status bar or a WAIT WINDOW. See lUsingStatusBar property.

ShowStatus(cMessage)

Parameters

cMessage
Specifies the message to display in the status bar or WAIT WINDOW

SourceAvailable( ) Method

Replaces the current Source log compiled file name with the full path name of the file holding the uncompiled source code.

SourceAvailable( )

Return Values

lReturn

Parameters

None

Remarks

SourceAvailable( ) calls GetSourceLoc( ) if necessary to locate uncompiled source code. If the lSmarthPath property is true (.T.), it uses AddPath( ) to adjust SET (PATH) as the user specifies directories in which to find source files. RETURNs false (.F.) if the source file is on the Ignored Files list, if the file is of an unknown type, or if the uncompiled source code cannot be found.

SourceFileIsLog( ) Method

Checks the file name held in the cSourceFile property for valid coverage log format.

SourceFileIsLog( )

Return Values

lReturn

Parameters

None

SuspendCoverage( ) Method

Sets the cSuspendedLog property to the name of the current log.

SuspendCoverage( )

Return Values

None

Parameters

None

Remarks

Sets cSuspendedLog to the name of the current log and temporarily stops Visual FoxPro from writing this log, in one of the following cases:

The passed file name is the same as the current coverage log.
No file name is passed and the engine defaults to analyzing the current coverage log.

ToggleCoverageProfileMode( ) Method

Marks all target records in the new mode

ToggleCoverageProfileMode(tcSource, tcTarget)

Return Values

RETURN NOT THIS.lError

Parameters

tcSource
Specifies the name of the table containing the source records.
tcTarget
Specifies the name of the table being modified.

Remarks

If the lMarkAllOnLoad property is true (.T.), marks all target records in the new mode.

cSavedStackXML Property

Holds the name of the saved Coverage stacklevel analysis in XML form, after this file has been saved to disk. Set back to default ("") when you load a new log.

lStackXMLExtendedTree Property

If .T., then it generates more extensive StackXML, so profiling of each branch can assess effects of args and other factors for different invocations of a module. Defaults to .F. but if COV_LOAD_STACK_FROM_DBF is .T., then this more extensive XML is generated always.

ShowStackXML( )

ShowStackXML(tclog)

Returns

Logical. .T. if successful.

Parameters

tcLog
Specifies the name of the log file.

Remarks

ShowStackXML( ) calls GetStackXML(tcLog) and DisplayStackXML(tcXMLFile) to run coverage analysis figures against a specific Visual Foxpro project set of files. The tcLog argument is ignored if DEFINEd COV_LOAD_STACK_FROM_DBF is .T.

GetStackXML( ) Method

Generates Stack Analysis XML from tcLog.

GetStackXML(tclog)

Returns

Logical. .T. if successful.

Parameters

tcLog
Specifies the name of the log file.

Remarks

This function defaults to current Coverage source log. The tcLog argument is ignored if DEFINEd COV_LOAD_STACK_FROM_DBF is .T.

DisplayStackXML( ) Method

Displays XML file.

DisplayStackXML(tcXMLFile)

Returns

Logical. .T. if no error occurs.

Defaults to the current Stack Analysis filename indicated by the cSavedStackXML property.

Remarks

This method is similar to DisplayProjectStatistics, except that, instead of being abstract in the engine, cov_engine.DisplayStackXML performs a ShellExecuteA

ToggleStackXMLExtendedTree( ) Method

Toggles .lStackXMLExtendedTree.

ToggleStackXMLExtendedTree( )

Returns

Logical. .T. if no error occurs.

Parameters

None

Remarks

Designed to be augmented in subclasses to reflect this switch in the UI, change default XSLT on this basis, and so on. This method is similar to ToggleCoverageProfileMode.

*.cStackXSLT Property

Holds filename providing default XSL Transformation stylesheet to be applied by default to the generated Stack XML analysis document, when TransformStackXML is called.

*.TransformStackXML( ) Method

TransformStackXML(tcXSLT, tcXMLIn, tcXMLOut, tlNoShow)

Returns

Returns .T. if successful.

Parameters

tcXSLT
Specifies the name of the XSL file.
tcXMLIn
Specifies the name of the XML input file.
tcXMLOut
Specifies the name of the XML output file.
tlNoShow
Specifies whether to call DisplayStackXML.

Remarks

Applies tcXSLT (default to .cStackXSLT) to tcXMLIn (default .cSavedStackXML, GetStackXML( ) called if empty). Saves result to tcXMLOut (defaults to tcXMLIn-based generated name w/ HTM ext). If ! tlNoShow, calls DisplayStackXML( ).

Share via

Coverage Engine Object

Remarks

aAddIns array Property

aFileTypes array Property

cAddIn Property

cBaseFontName Property

cBaseMonoFontName Property

cCovFilesAlias Property

cDefaultWritePath Property

cMarkExecuted Property

cMarkNotExecuted Property

cSavedSkipFiles Property

cSavedTargetDBF Property

cSkippedAlias Property

cSourceAlias Property

cSourceFile Property

cSuspendedLog Property

cTargetAlias Property

iLenExecuting

iLenDuration

iLenHostFile

iLenObjClass

lBaseFontBold Property

lBaseFontItalic Property

lBaseMonoFontBold Property

lBaseMonoFontItalic Property

lError Property

lInCoverageFrame Property

lInProfileMode Property

lMarkAllOnLoad Property

lSaveFormPositions Property

lSmartPath Property

lStartInProfileMode Property

lTurnedOffTrace Property

lUsingRegistry Property

lUsingStatusBar Property

lVFP5 Property

nBasefontsize Property

oFrame Property

AddFormPositionSaver( ) Method

Return Values

Parameters

AddPath( ) Method

Return Values

Parameters

Remarks

AddRegisteredAddin( ) Method

Return Values

Parameters

Remarks

AdjustCoverageFilenameCursor( ) Method

Return Values

Parameters

Remarks

AdjustSourceCursor( ) Method

Return Values Values

Parameters

AdjustTargetCursor( ) Method

Return Values Values

Parameters

ClearStatus( ) Method

Return Values

Parameters

CreateCoverageFilenameCursor( ) Method

Return Values

Parameters

CreateForms( ) Method

Return Values

Parameters

CreateSkippedCursor( ) Method

Return Values

Parameters

CreateSourceCursor( ) Method

Return Values

Parameters

CreateTargetCursor( ) Method

Return Values

Parameters

Remarks