Kernel Memory Space Analyzer — Known Issues Database (Phase 3)

 

Last  Updated: 1/28/00

 

1.     Introduction. 6

2.     Signature Id Files. 6

3.     Database Design and Schema. 8

3.1       Fixed Data Tables. 9

3.1.1        CrashClass. 9

3.1.2        CrashInstance. 10

3.1.3        KernelModule. 11

3.1.4        KernelModuleData. 12

3.1.5        HWProfile. 12

3.1.6        OSProfile. 12

3.1.7        KanalyzeModule. 13

3.1.8        KanalyzeModuleData. 13

3.2       Variable Data and Attachment Tables. 13

3.2.1        AttachmentData. 14

3.2.2        VariableCrashData. 14

3.3       Fixed Administrative Data Tables. 14

3.3.1        History. 15

3.3.2        Analysis. 15

3.3.3        ProgressText 15

3.3.4        Solution. 16

3.3.5        HintData. 16

3.3.6        AssociatedDB.. 16

3.3.7        StopCodeDescription. 17

3.3.8        ExternalRecordLocator 17

3.3.9        ProcessorType. 17

3.3.10      ProcessorVendor 17

3.4       Enforcing Table Integrity Using Primary and Foreign Keys. 18

4.     Theory of Operation. 19

4.1       General 19

4.1.1        Database Connections. 19

4.1.2        Transaction. 19

4.1.3        Querying. 19

4.1.3.1     Query Callback Function. 20

4.1.4        Updating. 21

4.1.5        Error Handling. 21

4.2       Querying For CrashClass. 22

4.3       Inserting Crash Instance Data. 22

4.4       Adding Solutions and Hint Data. 24

4.5       Querying for a Solution. 24

4.6       Adding Analysis Data. 24

5.     Database Access DLL. 24

5.1       Provider Interface. 24

5.1.1        KaDbInitialize. 26

5.1.2        KaDbCleanup. 27

5.1.3        KaDbOpenConnection. 27

5.1.4        KaDbCloseConnection. 28

5.1.5        KaDbStartTransaction. 28

5.1.6        KaDbRollbackTransaction. 29

5.1.7        KaDbCommitTransaction. 29

5.1.8        KaDbGetCrashClass. 30

5.1.9        KaDbAddCrashClass. 31

5.1.10      KaDbUpdateCrashClass. 32

5.1.11      KaDbGetHWProfile. 33

5.1.12      KaDbGetOSProfile. 34

5.1.13      KaDbAddHWProfile. 35

5.1.14      KaDbAddOSProfile. 36

5.1.15      KaDbUpdateHWProfileOccurrenceCount 37

5.1.16      KaDbUpdateOSProfileOccurrenceCount 37

5.1.17      KaDbGetCrashInstance. 38

5.1.18      KaDbAddCrashInstance. 39

5.1.19      KaDbGetKernelModuleData. 40

5.1.20      KaDbGetKanalyzeModuleData. 42

5.1.21      KaDbAddKernelModuleData. 43

5.1.22      KaDbAddKanalyzeModuleData. 44

5.1.23      KaDbGetKernelModule. 44

5.1.24      KaDbAddKernelModule. 46

5.1.25      KaDbGetKanalyzeModule. 46

5.1.26      KaDbAddKanalyzeModule. 48

5.1.27      KaDbGetAttachmentData. 48

5.1.28      KaDbAddAttachmentData. 50

5.1.29      KaDbGetVariableCrashData. 50

5.1.30      KaDbAddVariableCrashData. 52

5.1.31      KaDbGetSolution. 53

5.1.32      KaDbAddSolution. 54

5.1.33      KaDbUpdateSolution. 54

5.1.34      KaDbGetHintData. 55

5.1.35      KaDbGetAnalysis. 57

5.1.36      KaDbAddAnalysis. 58

5.1.37      KaDbUpdateAnalysis. 59

5.1.38      KaDbAddProgressText 60

5.1.39      KaDbGetProgressText 61

5.1.40      KaDbGetProcessorTypeProcessorVendor 62

5.1.41      KaDbGetLastError 63

5.2       Database Low-Level Access Interface. 64

6.     Kanalyze Plug-ins. 64

6.1       Role of the Master Analysis Plug-In. 64

6.2       Database Plug-In. 64

6.2.1        Hint processing. 65

6.2.1.1     Match Level to Report 65

6.2.1.2     Hint data syntax. 65

6.2.2        Method Interfaces. 67

6.2.2.1     M_QUERY_GET_PREQUERY_MATCH_RESULT. 67

6.2.2.2     M_QUERY_GET_MATCH_RESULT. 68

6.2.3        Public helper/callback routines. 68

6.2.3.1     DbInitialize. 68

6.2.3.2     DbCleanup. 68

6.2.3.3     DbOpenConnection. 69

6.2.3.4     DbCloseConnection. 69

6.2.3.5     DbStartTransaction. 69

6.2.3.6     DbRollBackTransaction. 70

6.2.3.7     DbCommitTransaction. 70

6.2.3.8     DbGetCrashClass. 70

6.2.3.9     DbAddCrashClass. 71

6.2.3.10       DbUpdateCrashClass. 71

6.2.3.11       DbGetHWProfile. 71

6.2.3.12       DbGetOSProfile. 72

6.2.3.13       DbAddHWProfile. 72

6.2.3.14       DbAddOSProfile. 72

6.2.3.15       DbUpdateHWProfileOccuranceCount 73

6.2.3.16       DbUpdateOSProfileOccuranceCount 73

6.2.3.17       DbGetCrashInstance. 74

6.2.3.18       DbAddCrashInstance. 74

6.2.3.19       DbGetKernelModuleData. 74

6.2.3.20       DbGetKanalyzeModuleData. 75

6.2.3.21       DbAddKernelModuleData. 75

6.2.3.22       DbAddKanalyzeModuleData. 75

6.2.3.23       DbGetKernelModule. 76

6.2.3.24       DbAddKernelModule. 76

6.2.3.25       DbGetKanalyzeModule. 77

6.2.3.26       DbAddKanalyzeModule. 77

6.2.3.27       DbGetAttachmentmentData. 77

6.2.3.28       DbAddAttachmentData. 78

6.2.3.29       DbGetVariableCrashData. 78

6.2.3.30       DbAddVariableCrashData. 79

6.2.3.31       DbGetSolution. 79

6.2.3.32       DbAddSolution. 79

6.2.3.33       DbUpdateSolution. 80

6.2.3.34       DbGetHintData. 80

6.2.3.35       DbGetAnalysisBy. 80

6.2.3.36       DbAddAnalysis. 81

6.2.3.37       DbUpdateAnalysis. 81

6.2.3.38       DbAddProgressText 82

6.2.3.39       DbGetProgressText 82

6.2.3.40       DbGetCrashClassCrashInstance. 82

6.2.3.41       DbGetProcessorTypeProcessorVendor 83

6.2.3.42       DbBuildHWProfileMatchString. 83

6.2.3.43       DbBuildOSProfileMatchStr 83

6.2.3.44       DbBuildKernelModuleDataMatchStr 84

6.2.3.45       DbBuildKanalyzeModuleDataMatchStr 84

6.2.3.46       DbGetLastError 84

6.2.4        Useful macros. 85

6.2.4.1     KADB_GET_PLATFORM_A.. 85

6.2.4.2     KADB_GET_PLATFORM_W... 85

6.2.4.3     KADB_SET_PLATFORM_A.. 85

6.2.4.4     KADB_SET_PLATFORM_W... 86

6.2.4.5     KADB_GET_OS_TYPE_A.. 86

6.2.4.6     KADB_GET_OS_TYPE_W... 87

6.2.4.7     KADB_SET_OS_TYPE_A.. 87

6.2.4.8     KADB_SET_OS_TYPE_W... 87

6.2.4.9     KADB_GET_KANALYZE_TYPE_A.. 88

6.2.4.10       KADB_GET_KANALYZE_TYPE_W... 88

6.2.4.11       KADB_SET_KANALYZE_TYPE_A.. 89

6.2.4.12       KADB_SET_KANALYZE_TYPE_W... 89

6.2.4.13       KADB_SET_PROCESSOR_TYPE_A.. 89

6.2.4.14       KADB_SET_PROCESSOR_TYPE_W... 90

6.2.4.15       KADB_GET_PROCESSOR_TYPE_A.. 90

6.2.4.16       KADB_GET_PROCESSOR_TYPE_W... 91

6.2.4.17       KADB_SET_PROCESSOR_VENDOR_A.. 91

6.2.4.18       KADB_SET_PROCESSOR_VENDOR_W... 92

6.2.4.19       KADB_GET_PROCESSOR_VENDOR_A.. 92

6.2.4.20       KADB_GET_PROCESSOR_VENDOR_W... 93

Appendix A: Interpreting The Database Design Diagram.. 93

 


1.      Introduction

A known issues database tracks crash cases and their resolutions. Kanalyze can perform matching against a database to determine whether a crash represents a problem whose symptoms and resolution is known. Kanalyze can also create new crash cases in a database and update existing records with newly discovered information.

 

There are two general scenarios for using kanalyze with a known issues database. In the first scenario, kanalyze gathers information felt to be relevant to diagnosing a crash and places it in a signature id file, which is saved for later use. At any point in the future, the saved information in a signature id file can be used with kanalyze again to look up the crash in the database and/or update the database.

 

An example of this scenario is the field technician case: a support person goes into the field with his laptop to service several clients in a day. At each site, he runs kanalyze, which performs its analysis and may provide some indication of the problem symptoms and cause, and perhaps a preliminary suggested course of action (i.e., kanalyze does what it normally does independently of the presence of the known issues database functionality). The technician’s laptop also gets loaded up with signature id files over the course of the day. When the technician returns from the field to the support center, the signature id files are run through kanalyze, which does matching against the support center’s known issues database to provide final resolution for the customers’ problems. The support center’s known issues database is also updated with new crash cases.

 

The second scenario is real-time usage of the database. In this scenario, the computer where kanalyze is being run has access to a known issues database while it is running. The connection to the database could be on a LAN, or on a WAN (such as via a persistent or point-to-point dial-up link). This is essentially an optimization of the first scenario. Note that it is still possible in this scenario to generate and save signature id files.

 

Table of Contents Ý

2.      Signature Id Files

These diagrams illustrate the signature id file infrastructure.

 

The first diagram represents an analysis and signature id file generation phase. Kanalyze is run on a crash dump, and, in conjunction with plug-ins, creates a signature id file containing all the data that kanalyze thinks is necessary to characterize this crash and match it against other crashes. This phase is run wherever it is convenient to run kanalyze, for example at a support center after a crash dump has been received, or automatically on the machine itself if a third-party product providing such a feature has been installed.

 

 

 

The second diagram represents a database usage phase. Kanalyze connects to a known issues database and uses the signature id file to determine whether this crash has been seen before. If the crash has been seen before, any resolution information is output to the user. If the crash has not been seen before, case information is added to the database.

 

 

 

 

Note that the two phases are logically separate and need not be run at the same time. If a known issues database is not available at the time when kanalyze is initially run, the signature id file can be saved and run through the database matching phase at a later time. If a database is available, then the two phases are chained together to produce an immediate result.

 

The contents of a signature id file correspond very closely to records in the known issues database. In fact, a signature id file *is* the external manifestation of a record in the known issues database.

 

A crash case is represented in a known issues database, and therefore the signature id file contains,

 

·        A set of fixed crash data fields, containing information such as the bugcheck (stop) code and 4 parameters, OS version, loaded module list, etc.

·        A set of fixed administrative fields, containing information such as customer ids, case history, annotations, etc.

·        A set of fixed kanalyze data fields, containing information such as the version of kanalyze that produced the signature id file, the plug-ins that were loaded and participated in the analysis, etc.

·        A set of pointers to any attachments and tracking data for them. An attachment is a link to external data that is useful to custom “value-add” plug-ins and is felt by the plug-in to be inappropriate for storage in the database itself. For example the crash dump file itself could be an attachment. Or a custom plug-in might tie the event log into the analysis in some way; the actual event log can be attached by the plug-in to the signature id file.

·        Variable data. Variable data contains anything the plug-ins felt was relevant, such as anomaly data, or particular data pulled out from the crash dump. Variable data is a set of tagged blobs; the only entity that understands a variable datum is the plug-in that generated it and requested that it be written to the signature id file.

 

The knowledge of the internal format of a signature id file is contained in one single place: sigidlib.lib. This static library has interfaces to create signature id files and to read and write the data in them, and to deal with attachments.

 

3.      Database Design and Schema

The design of the known issues database is shown below.  The following sections outline each of the tables and relationships that comprise the knowledge database.

 

The database logically groups records into one of three areas:

 

·        Tables pertaining to the fixed crash data and fixed kanalyze data portions of the signature id file (blue/lightly shaded)

·        Tables pertaining to the variable data and attachments portions of the signature id file (white/no shading)

·        Tables pertaining to the fixed administrative data portion of the database (cyan/dark shading).

 

The known issues database will be implemented using SQL Server 7.0 and will be designed to achieve maximal ANSI SQL-92 compatibility. The Database Access DLL routines will also be built upon OleDB technologies. 

 

Data integrity for the database will be declarative as opposed to procedural and will be enforced by defining constrains and defaults directly on the tables and columns. The exception is that triggers will be written to handle the more complicated integrity logic such as having cascading deletes.

 

Additionally, the database must be capable of maintaining and displaying unsigned 64-bit wide addresses.  Since the current version of SQL Server only supports up to a 4-byte (32 bit) signed integers, a fixed length character strings representing a 16 bit hex character string will be used to map all 64-bit unsigned entities.

 

 

Notes about interpreting this diagram are in Appendix A.

 

3.1      Fixed Data Tables

This section deals with those tables that correspond to the fixed crash data and fixed kanalyze data portions of the kanalyze signature id file.

 

3.1.1    CrashClass

The CrashClass table has been denormalized to include:

·        OS and HW profile information

·        Instance counters and TimeStamps.


The OS and HW profile data was added to the CrashClass table to facilitate plugins querying the Known Issues database for an initial set of matches (e.g., plugins only have to query a single table as opposed to having to join/query three tables.

Instance counters and Timestamps have been added to CrashClass because in time, it is believed that CrashInstance data will be deleted from the database. As such, separate counter and timestamps must be maintained.

 

Field Name

Key Attributes

Null

Data Type

Description

ClassID

Primary Key

Not Null

Int (Identity)

Primary key assigned to each unique instance.

AnalysisID

Foreign

Key

Not Null

Int

 

SolutionID

Foreign Key

Not Null

Int

 

StopCode

Index

Not Null

Char(8)

 

StopCodeParameter1 StopCodeParameter2 StopCodeParameter3
StopCodeParameter4

Index Index Index Index

Not Null
Not Null
Not Null
Not Null

Varchar(256)
Varchar(256)
Varchar(256)
Varchar(256)

 

 

NTBuild

 

Not Null

SmallInt

Denormalized for faster lookup.

Platform

 

Not Null

Char(10)

Denormalized for faster lookup.

Canonical

 

Null

Int

Indicates canonicalization level of the StopCodeParameterX parameter.

Keyword1
Keyword2
Keyword3
Keyword4

 

Null
Null
Null
Null

Varchar(256)
Varchar(256)
Varchar(256)
Varchar(256)

 

InstanceCount

 

Null

Int

 

FirstOccurrence
LastOccurrence

 

Null
Null

SmallDateTime
SmallDateTime

 

 

 

3.1.2      CrashInstance

The CrashInstance table maintains associations with the following tables:

·                    KernelModule

·                    KanalyzeModule

·                    AttachementData

·                    VaraiableCrashData.

New AttachementData and VariableCrashData records are added for each new CrashInstance record. KernelModule and KanalyzeModule tables represent the set of loaded kernel modules and the set of analysis plugins respectively.

To conserve space and avoid duplicating module data, the database plugin must first search in the KernelModuleData (for kernel modules) or KanalyzeModuleData table  (for kanalyze modules) to obtain a ModuleID that matches the module characteristics (i.e., name, size, checksum etc). If module data is not found, the database plugin must add a new ModuleData record.
 
In other words, a CrashInstance record maintains associations with a set of KernelModule and KanalyzeModule records.  These records represent the set of loaded modules on the machine. To access the details of these modules one must perform a look-up operation using either the KernelModuleData or KanalyzeModuleData tables and the ModuleID key found in KernelModule or KanlayzeModule records.

 

Field Name

Key Attributes

Null

Data Type

Description

ClassID

Foreign Key

Not Null

Int

Used as composite primary key with InstanceID.

InstanceID

Primary Key

Not Null

Int (Identity)

 

HWProfileRecID

Foreign Key

Not Null

Int

 

OSProfileRecID

Foreign Key

Not Null

Int

 

StopCodeParameter1 StopCodeParameter2 StopCodeParameter3
StopCodeParameter4

 

Not Null
Not Null
Not Null
Not Null

Varchar(16)
Varchar(16)
Varchar(16)
Varchar(16)

 

 

KanalyzeMajorVersion
KanalyzeMinorVersion

 

Not Null
Not Null

SmallInt
SmallInt

 

CrashTimeDate

 

Null

DateTime

 

 

 

3.1.3    KernelModule

 

Field Name

Key Attributes

Null

Data Type

Description

ClassID

Foreign Key

Not Null

Int

 

InstanceID

 

Foreign
Key

Not Null

Int

 

KernelModuleID

Foreign Key

Not Null

Int

 

LoadAddress

 

Not Null

VarChar(16)

 

 

 

3.1.4    KernelModuleData

 

Field Name

Key Attributes

Null

Data Type

Description

KernelModuleID

Primary Key

Not Null

Int (identity)

 

BaseName

 

Not Null

NVarChar(256)

 

Size

 

Not Null

Int

The size of the module.

CheckSum

 

Not Null

Char(8)

 

The checksum associated with an image, from the image header.

DateTime

 

Null

DateTime

The link date/time stamp, from the module image header.

SubSystemMajorVersion SubSystemMinorVersion

 

Null
Null

SmallInt
SmallInt

Target OS subsystem version, from the module image header.

 

 

3.1.5    HWProfile

 

Field Name

Key Attributes

Null

Data Type

Description

HWProfileRecID

Primary Key

Not Null

Int

(Identity)

Surrogate key (See Appendix A) that represents a particular hardware configuration.

Architecture

 

Not Null

Char(8)

Identifies the processor architecture. Legal values: x86, Alpha, ia64 or axp64.

ProcessorType

 

Not Null

Char(8)

 

Indicates the processor level (i.e., Pentium, Pentium II or Pentium III).

ProcessorSpec

 

Null

Char(8)

 

Represents the process stepping revision.

ProcessorVendor

 

Null

VarChar(13)

Contains a CPU identification string used to identify the CPU manufacture, i.e., Intel, AMD, Cyrix, etc.

ProcessorCount

 

Not Null

SmallInt

Indicates the number of processors.

OccurrenceCount

 

 

Not Null

Int

Indicates the count of crashes that have occurred with this type of hardware platform.

 

 

3.1.6    OSProfile

 

Field Name

Key Attributes

Null

Data Type

Description

OSProfileRecID

Primary Key

Not Null

Int

(Identity)

Surrogate key (See Appendix A) that represents a particular operating system configuration.

OSCheckedBuild

 

Null

Bit

If set indicates that kernel is a checked build

OSSMPKernel

 

Null

Bit

If set indicates that kernel is a MP based

OSPAEKernel

 

Null

Bit

If set indicates kernel is PAE version

OSBuild

 

Not Null

SmallInt

Indicates the NT build number that equates to specific version of the OS.

OSServicePackLevel

 

Null

SmallInt

 

Indicates the Service Pack revision.

ProductType

 

Null

 VarChar(12)

Represents product type, i.e., Workstation, Server, Advanced Server, etc.

QfeData

 

Null

NVarChar(256)

Annotated string field that represents one or more hot fixes.

OccurrenceCount

 

Not Null

Int

Represents the number of crashes that have occurred on this type of operating system profile.

 

 

3.1.7    KanalyzeModule

 

Field Name

Key Attributes

Null

Data Type

Description

ClassID
InstanceID

Foreign Key
Foreign Key

Not Null
Not Null

Int
Int

Migrating keys used to associate kanlayze with a specific crash class and instance

KanalyzeModuleID

Foreign Key

Not Null

Int

 

 

 

3.1.8    KanalyzeModuleData

 

Field Name

Key Attributes

Null

Data Type

Description

KanalyzeModuleID

Primary Key

Not Null

Int (Identity)

 

BaseName

Index

Not Null

NvarChar(256)

 

Type

 

Not Null

Char(8)

 

AlternateName

Index

Not Null

NVarChar(50)

 

MajorVersion
MinorVersion

 

Not Null
Not Null

SmallInt
SmallInt

Indicates the version of the kanalyze module.

Description

 

Null

NVarChar(256)

Optional human-readable description.

 

 

3.2      Variable Data and Attachment Tables

This section deals with those tables that correspond to the attachments and variable data portions of the kanalyze signature id file. 

 

3.2.1    AttachmentData

Associated with a signature file may be zero, one or more attachments.  Attachments represent separate data that is to be associated with a particular CrashClass and AssociateCustomer record. Types of attachment data include:

 

·        Dump File (micro dump)

·        Kanalyze Signature Id File

·        Support Engineering Notes (i.e., kd or kanlayze debug output).

·        Anything else that a plugin or support engineer feels is relevant.

 

Field Name

Key Attributes

Null

Data Type

Description

ClassID
InstanceID

Foreign Key
Foreign Key

Not Null
Not Null

Int
Int

Used as composite primary key with ItemID.

ItemID

Primary Key

Not Null

Int (Identity)

Uniquely identifies item.

Location

 

Not Null

NVarChar(256)

Indicates the location of the data item.

Size

 

Not Null

Int

Indicates the size of the attached data.

Description

 

Null

NVarChar(256)

A free formed text field that provides a description of attachment item.

DateTime

 

Not Null

SmallDateTime

A time stamp when attachment was created.

 

 

3.2.2    VariableCrashData

The VariableCrashData table represents plug-in data that is to be associated with a CrashClass table. Plug-in data is anything that is viewed as relevant by the plug-in at the time of analysis. Data stored is in binary form (i.e., blob).

 

Field Name

Key Attributes

Null

Data Type

Description

ClassID
InstanceID

Foreign Key
Foreign Key

Not Null
Not Null

Int
Int

Used as composite primary key with BlobName.

BlobName
BlobWriterID

Primary Key

Not Null
Not Null

NVarChar(256)
NVarChar(50)

 Uniquely identifies blob data item.

Data

 

Not Null

Image

Binary data written by the kanalyze module.

DataLength

 

Not Null

Int

Indicates the size of the data plugin.  We may be able to delete this field and calcuate the size of the Data item.

 

 

3.3      Fixed Administrative Data Tables

This section deals with the administrative tables of the known issues database. These tables are not derived from the signature file.

 

3.3.1    History

The History table acts as an audit log for tracking changes made to the database. The table is populated via database insert, update and deletion triggers. It will be implemented after the database has matured and is known to be in a stable state.

 

Field Name

Key Attributes

Null

Data Type

Description

HistoryID

Primary Key

Not Null

Identity(1,1).

 

DatabaseName

 

Null

NvarChar(128)

The name of the database.

User

 

Not Null

NvarChar(50)

Who is making the changes (most of the time will be SA).

TableName

 

Not Null

NvarChar(60)

Identifies the table that is operated upon.

Operation

 

Not Null

NvarChar(20)

Identifies the operation as an INSERT, UPDATE, DELETE, BEGINTRANS, ENDTRANS or ROLLBACK.

TimeStamp

 

Not Null

DateTime

Defines when the operation occurred.

 

Additionally, there is a set of stored procedures (ie, sp_KaDBEnableHistory, sp_KADBDisableHistory) that the database administrator can invoke to enable or disable logging. These stored associate or disassociate the update, delete, and insert triggers from the database, i.e., Disable logging, implies that all update, delete and insert triggers are removed from the database and enabling logging implies that all update, delete and insert triggers are added to the database and associated with the various tables.  In essence, when the triggers are in place we are logging history records.

 

3.3.2    Analysis

 

Field Name

Key Attributes

Null

Data Type

Description

AnalysisID

Primary Key

Not Null

Int(Identity)

 

Abstract

 

Null

NVarChar(350)

 

ProblemDescription

 

Null

NVarChar(3250)

 

Keywords

 

Null

NVarChar(400)

 

Status

 

Null

Char(8)

 

 

 

3.3.3    ProgressText

 

Field Name

Key Attributes

Null

Data Type

Description

AnalysisID

Foreign Key

Not Null

Int

Used as composite primary key with ProgressTextID.

ProgressTextID

Primary Key

Not Null

Int (Identity)

 

DateTime

 

Not Null

SmallDateTime

 

Annotation

 

Not Null

NVarChar(3800)

 

Author

 

Null

NVarChar(75)

 

 

 

3.3.4    Solution

 

Field Name

Key Attributes

Null

Data Type

Description

SolutionID

Primary Key

Not Null

Int (Identity)

Unique Key assigned to Solution.

Abstract

 

Not Null

NVarChar(350)

 

SolutionDescription

 

Not Null

NVarChar(3250)

 

Keywords

 

Null

NVarChar(400)

 

LastUpdated

 

Not Null

SmallDateTime

Timestamp when this solution was last updated.

 

                                                                               

3.3.5    HintData

Field Name

Key Attributes

Null

Data Type

Description

DataID

Primary Key

Not Null

Int (Identity)

 

SolutionID

Foreign Key

Not Null

Int

Used as composite primary key with DataID.

Data

 

Not Null

NVarChar(2500)

 

                                                                               

 

3.3.6    AssociatedDB

In addition to being a relational database, the known issues database maintains a hierarchical relationship with other known issue databases. The AssociatedDB table maintains this hierarchical relationship.

 

This strategy provides the ability to partition databases. For example, an OEM may have a public database and private database, where the public database maybe limited in its knowledge and is open to everyone. The private database is reserved for paying contracts and is much more extensive. This strategy will also allow vendors to sell/purchase knowledge data.

 

The AssociatedDB table will not be implemented in the first release of the known issues database.

 

Field Name

Key Attributes

Null

Data Type

Description

DatabaseID

Primary Key

Not Null

Int Identity

Identifies the database.  An ID of zero identifies this database

DatabaseName

 

Not Null

NVarChar(128)

The database name

Parent

 

Null

Bit

If set, then database is the parent of the databases listed. There can only be one parent per table.

ConnectionData1
ConnectionData2

 

Not Null
Null

varchar(256)
varchar(256)

TBD. Contains connection data.

 

 

 

3.3.7    StopCodeDescription

Given a StopCode, the StopCodeDescription table provides lookup information for a StopCode name and description.

 

Field Name

Key Attributes

Null

Data Type

Description

StopCode

Primary Key

Not Null

Char(8)

StopCode

Name

 

Not Null

VarChar(80)

Provides a human-readable name to associate with the Stop Code.

 

3.3.8    ExternalRecordLocator

Field Name

Key Attributes

Null

Data Type

Description

ClassID
InstanceID

Foreign Key
Foreign Key

Not Null
Not Null

Int
Int

 

Customer
ServiceRec

 

Null
Null

NVarChar(100)
varchar(100)

 

 

3.3.9    ProcessorType

This table is a static lookup table used to acquire processor information. This table is used in conjunction with the ProcessorVendor table below. This table can be manually updated, as required, to reflect the latest available processors.

 

Field Name

Key Attributes

Null

Data Type

Description

ProcessorTypeID

Primary Key

Not Null

Int (Identity)

Identifies the processor type

VendorID

Foreign Key

Not Null

Int

Used as composite primary key with ProcessorTypeID.

Type

 

Null

Char(8)

Processor type, e.g. PII, PIII,K6-2, etc.

Family

 

Null

SmallInt

Processor Family, e.g. 4,5,6, etc.

Model

 

Null

SmallInt

Processor Model, e.g. 1,2,3, etc.

Step

 

Null

SmallInt

Processsor Step

 

3.3.10                       ProcessorVendor

This table provides a vendor name to associate with a vendorID.

 

Field Name

Key Attributes

Null

Data Type

Description

VendorID

Primary Key

Not Null

Int (Identity)

Identifies the processor vendor

VendorName

 

Not Null

VarChar(13)

Processor vendor name

 

 

3.4      Enforcing Table Integrity Using Primary and Foreign Keys

A Primary Key is the column or combination of columns that uniquely identifies one row from any other row in a table. A primary key (PK) must be not null and must have a unique index.

 

A Composite Primary Key is made up of two or more columns. For example, the AttachmentData table has a composite primary key made up of three columns.  The combination of ClassID, InstanceID and ItemID uniquely identifies each row in the AttachmentData table. 

 

A Foreign Key is the column or combination of columns used to establish and enforce a link between the data in two tables. A link is created between two tables by adding the column or columns that hold one table’s primary key values to the second table. The column then becomes a foreign key in the second table.

 

The Foreign Key Reference Table is the table in which the foreign key is defined as a primary key.

 

Tables in the Known Issues Database use primary, composite primary, and foreign keys to enforce table integrity as follows:

 

 

Table Name

Primary Key

Foreign Key

Foreign Key Reference

Table Name

Analysis

AnalysisID

 

 

AssociateDB

DatabaseID

 

 

AttachmentData

ClassID

InstanceID

ItemID

ClassID

InstanceID

CrashInstance

CrashInstance

CrashClass

ClassID

AnalysisID

SolutionID

Analysis

Solution

CrashInstance

ClassID

InstanceID

ClassID

HWProfileRecID

OSProfileRecID

CrashClass

HWProfile

OSProfile

HintData

DataID

SolutionID

 

SolutionID

 

Solution

History

HistoryID

 

 

HWProfile

HWProfileRecID

 

 

KanalyzeModuleData

KanalyzeModuleID

 

 

KernelModuleData

KernelModuleID

 

 

OSProfile

OSProfileRecID

 

 

ProgressText

AnalysisID

ProgressTextID

AnalysisID

Analysis

Solution

SolutionID

 

 

StopCodeDescription

StopCode

 

 

VariableCrashData

ClassID

InstanceID

BlobName

ClassID

InstanceID

CrashInstance

CrashInstance

ExternalRecordLocator

 

ClassID

InstanceID

CrashInstance

CrashInstance

KanalyzeModule

 

ClassID

InstanceID

KanalyzeModuleID

CrashInstance

CrashInstance

KanalyzeModuleData

KernelModule

 

ClassID

InstanceID

KernelModuleID

CrashInstance

CrashInstnace

KernelModuleData

ProcessorType

ProcessorTypeID

VendorID

ProcessorVendor

ProcessorVendor

VendorID

 

 

 

4.      Theory of Operation

This section articulates the rules for inserting, updating and deleting records within the known issue database. It also describes the general architectural considerations.

 

4.1      General

This section covers architectural topics such as establishing a database connection, performing a transaction and discusses some of the general mechanics used to query and update the database.

 

4.1.1    Database Connections

Prior to invoking any of the functions that query, add or update a record within the database a connection to the database must first be established. This is accomplished by invoking KaDbOpenConnection. If successful, this function returns a connection handle. The connection handle is used as a formal parameter to all subsequent KaDbxxxx functions.

The function KaDBCloseConnection is used to close a database connection.

 

4.1.2    Transaction

A transaction is a series of processing steps that results in a specific activity being completed, ensuring that a set of actions is treated as a whole. The function KaDbStartTransaction is used to initiate a SQL transaction.  Transactions are associated with a connection handle. Once a transaction is initiated, any number of KaDBGetxxxx or KaDbAddxxxx functions can be invoked.   If for some reason while adding/updating a set of records an error occurs, calling DbRollBackTransaction function will back out the entire set of database actions performed under the transaction.  If no errors have occurred, the set of actions performed under the transaction can be committed by invoking KaDbCommitTransaction.

 

4.1.3    Querying

The general mechanism for querying the database consists of invoking a single function, KaDbGetxxxx where xxxx is one or more table names. For example, KaDbGetCrashClass queries the CrashClass table while the KaDbGetCrashClassSolution performs a query on the join of the CrashClass and Solution tables.

 

Associated with each of the KaDbGetxxxx function is a MatchStr (or derivative there of), a callback function and a structure definition.

 

The MatchStr is used to specify the set of SQL predicates used to build the Where clause (less any join statements).  A set of helper functions is also provided to help build specific query strings, i.e., to find out if a specific HW Profile record exists.

 

The callback function must be specified when invoking the KADbGetxxxx function. The KaDbGetxxxx function builds and executes the query string and a rowset object is returned. KaDbGetxxxx extracts a record from the data and copies it into a provided structure definition and then invokes the callback function.

 

Within the callback, the user can determine the number matching records, the ID of the returned record as well as the data from the returned data record. To acquire the next record within the rowset the callback routine must return TRUE.  In essence, the single function/callback mechanism builds a simple forward only block cursor.

 

Additionally, each KaDbGetxxxx function allows its caller to specify a callback parameter. This callback parameter is used by the callback routine.

NOTE

 

If a more elaborate cursor mechanism is desired, a Flags parameter can be added to the callback function. The flags parameter would indicate the direction (Forward, Back) and a directive (GetNext or GetByIndex).  Through the use of the RecordID parameter (functions now as an IN/OUT) the user can set the Flags and RecordID as follows:

Direction

Directive

RecordID

Results

Forward

GetNext

N/A

Retrieves the next record in record-set

Backward

GetNext

N/A

Retrieves the previous record in the record-set.

N/A

GetByIndex

Used as an Index

Retrieves the nth record within the rowset.

 

In addition, a Flags parameter should be added to KaDBGetxxxx function. The Flags parameter would indicate the initial direction and directive. By default, these values are set to mimic a standard block cursor (Forward and GetNext flags are set).

4.1.3.1       Query Callback Function

All KaDbGetxxxx functions use the same callback function prototype.  For brevity, it is documented here only.

 

typedef

BOOL

(CALLBACK *PKADB_ENUM_DATA_CALLBACK)(

IN ULONG32 RecordCount,

IN DWORD RecordID,

IN PVOID Data,

IN ULONG32 Flags,

IN PVOID CallBackParm );

 

Parameters:

 

RecordCount—Indicates the number of records that matched the query.

 

RecordID—Contains the RecordID  (key) for the matching record.

 

Data—Points to a structure that receives record data for a specified table.

Flags—Reserved for future use. Must be zero.

 

CallBackParmKaDbGetxxxx sets this value to its CallBackParm. Allowing callers to the KaDbGetxxxx function to pass parameters to their respective callback routines.

Return Value:

 

When TRUE is returned KaDbGetxxxx function will attempt to retrieve the next record found within the rowset. If FALSE is returned, KaDbGetxxxx aborts enumerating records.  The KaDbGetxxxx function will perform cleanup, sets LastError to indicate a cancel operation and returns FALSE.

 

4.1.4    Updating

Updating of database tables is performed by a single function, KaDbUpdatexxxx where xxxx is the table name. Each update function requires a recordID, a flags parameter and a structure definition.

 

The recordID identifies what record within the table to update, while the flags parameter defines what fields within the database table to update. Data is passed to the update function via a structure definition. The same structure definition is used in KaDbAddxxxx and KaDbGetxxxx (query) database functions.

 

4.1.5    Error Handling

All KaDb functions return TRUE or FALSE. Calling GetLastError can retrieve extended error information. Because we may also be dealing with underlying SQL error messages we should expose an additional function, KaDBGetLastError. This function should be used in place of GetLastError.

 

KaDbGetLastError determines if the error is a SQL error or a WIN32 error, returns a message string and an indication of the error. 

4.2      Querying For CrashClass

The database plugin exposes a function to query the CrashClass table. KaDbGetCrashClass is used to perform this query. The caller is responsible for proving a SQL Where clause statement which is restricted to a set of predicates less join statements.

 

A callback function is provided to return CrashClass data to the caller. The callback function is invoked for each record returned in the rowset. The caller can abort processing of records (i.e., found a match) by returning FALSE from the callback function.


If a matching CrashClass record was found the CrashClass record must be updated to reflect:

·       An InstanceCount increment.

·       FirstOccurrence is set equal to the crash datetime if the crash datetime is older than FirstOccurrence.

·       LastOccurrence is set queal to the crash datetime if the crash datetime is earlier than LastOccurrence.

 

The above operation is performed with the KaDbUpdateCrashClass function.

 

4.3      Inserting Crash Instance Data

Regardless of whether CrashClass record was found or added, a CrashInstance record must be added to the database. However, prior to adding a new CrashInstance record, the HW and OS profile tables must be enumerated to locate a profile record that matches what is specified in the signature ID file. Matching for the HW profile consists of matching on the following fields:

·        Architecture

·        ProcessorType

·        ProcessorCount[1].

Whereas matching for the OS profile consists of matching on the following fields:

·                    OSCheckedBuild

·                    OSSMPKernel

·                    OSPAEKernel

·                    OSBuild

·                    OSServicePackLevel

·                    ProductType[2].

If any of the above fields do not match, then a new HW or OS profile record must be added to the database.

Given the above, the following functions are provided:

·        KaDbAddCrashInstance. Adds a new CrashInstance record.

·        KaDbGetHWProfile and KaDbGetOSProfile. Get HW and OS Profile records respectively.

·        KaDbAddHWProfile andKa DbAddOSProfile. Add HW and OS Profile records respectively.

·        KaDbUpdateHWProfile and KaDbUpdateOSProfile. Increment and update counters associated with the HW and OS Profile records respectively.

 

Once the database plugin has obtained the HW and OS profile ID keys a new CrashInstance record can be added by invoking KaDbAddCrashInstance function.

 

After the CrashInstance record has been added, the database’s kernel and kanalyze module lists (i.e., KernelModuleData and KanalyzeModuleData tables) must be enumerated to see if a match exists with the set of modules specified in the signature ID file.  Matches on these tables are based off the module characteristics. For example, if a module in KernelModuleData table and a module from the Signature ID file have the same name, checksum and timestamp but have different version numbers then no match is found and the a new module record should be added to the database.  For each kernel module found or added in KernelModuleData, the database plugin must add a new KernelModule record to the database. Likewise, the database plugin must enumerate the set of kanalyze modules as well.

 

The functions to do the above are as follows:

·        KaDbGetKernelModule and KaDbGetKanalyzeModule. These functions are used to query module data that is associated with a specific crash instance. The caller can use a match string to query for a specific module or if the match string is set to NULL, the above functions will return a list of kernel or kanalyze modules respectively that are associated with a specific crash.

·        KaDbGetKernelModuleData and KaDbGetKanalyzeModuleData are used to determine if a specific module configuration (i.e., build number and checksum information) is defined in the database. The helper functions KaDbBuildKernelModuleMatchString and KaBuildKanalyzeMatchString are used to build match strings that can be used to build the query to look for an exact match, e.g., KaDbBuildKernelModuleMatchString would build a query string to match a kernel module based upon: BaseName, Size, CheckSum, DateTime, SubSystemMajorVersion and SubSystemMinorVersion.

·        KaDbAddKernelModuleData. Adds a new KernelModule record to the database.

·        KaDbAddKanalyzeModuleData.  Adds a new KanalyzeModule record to the database.

·        KaDbAddKernelModule and KaDbAddKanalyzeModule. These functions are used to add Kernel and Kanlayze module records to the database. These functions are called as part of adding a new crash instance.

 

Finally, as part of adding a CrashIntstance record, attachment and variable crash data must be added.  There can be zero, one or more attachment and/or VariableCrashData records per CrashInstance record.  The database functions to add these records are:

·        KaDbAddAttachementData

·        KaDbAddVariableCrashData.

 

Due to the number of table interactions involved when adding a new crash instance, it is strongly recommended that the operations per performed under a SQL transaction.

4.4      Adding Solutions and Hint Data

Solutions and hint data are added to the known issues database either manually or through some other external application.

 

4.5      Querying for a Solution

Once a CrashClass has been identified, a query can be performed to retrieve the solution that is assocated with the CrashClass.  The function KaDbGetSolution is called to return a solution record associated with the CrashClass.

 

Associated with a solution is zero, one or more hint data records. HintData is used to determine the goodness of fit for a solution. The function KaDbGetHintData is used to retrieve and enumerate the DataHint record associated with a solution.  Invoking KaDbAddHintData is used to retrieve additional HintData records within the result-set.

 

4.6      Adding Analysis Data

Associated with a CrashClass record is an Analysis record.  The Analysis record maintains information regarding the nature/analysis of the crash. The following functions are defined to manage Analysis data records:

·        KaDbAddAnalysisData is used to add an analysis record to the database.

·        KaDbUpdateAnalysisData is used to update an analysis record.

 

In addition to the Analysis record are ProgressText records. These records are free form text record are use to capture analysis progress. The function KaDbAddProgressText is used to add a ProgressText record while KaDbGetProgressText fuction allows the user to fetch a set of ProgessText records associated with a specific analysis record.

 

5.      Database Access DLL

All access to a known issues database is performed by the database provider DLL. This DLL is used by the database plug-in and can also be used by other tools that are not part of kanalyze but which manipulate the database. KaDbProv.dll uses SQLOLEDB and exports interfaces for establishing connections to a local or remote database; for performing and refining queries; and for setting data in the database.

5.1      Provider Interface

The following table outlines the various functions that act upon the database tables.  Also provided in the Provider Interface are a number of helper functions (i.e., establish connection and transaction management).

 

Table Name

Provider Interface Function

Notes

CrashClass

KaDbGetCrashClass

Queries the CrashClass table.

KaDbUpdateCrashClass

Updates a CrashClass record.

KaDbAddCrashClass

 

Adds a new CrashClass record.

Solution

KaDbGetSolution

Queries the Solution table.

KaDbUpDateSolution

Updates a Solution record.

KaDbAddSolution

 

Adds a solution to the database

HintData

KaDbGetHintData

Queries Hint data

KaDbUpdateHintData

Future release.

KaDbAddHintData

Future release.

Analysis

KaDbGetAnalysis

Queries the Analysis table.

KaDbUpdateAnalysis

Updates an Analysis record.

KaDbAddAnalysis

Adds a new Analysis record.

ProgressText

KaDbGetProgressText

Queries the ProgressText table.

KaDbAddProgressText

Adds a new ProgressText record.

 

Note: There is no update function, as one never updates a ProgressText record.

CrashInstance

KaDbGetCrashInstance

Queries the CrashInstance table.

KaDbAddCrashInstance

Adds a new CrashInstance.

 

Note: There is no update function, as one never updates a CrashInstance record.

KernelModule

KaDbGetKernelModule

Queries the KernelModule table

KaDbAddKernelModule

Adds a new KernelModule record.

 

Note: There is no update function, as one never updates a KernelModule record.

KernelModuleData

KaDbGetKernelModuleData

Queries the KernelModuleData table.

KaDbAddKernelModuleData

Adds a new KerneloduleData record.

 

Note: There is no update function, as one never updates a KernelModuleData record.

AttachmentData

KaDbGetAttachmentData

Queries the AttachmentData table.

KaDbAddAttachmentData

Adds an attachment record.

KaDbUpdateAttachmentData

Future release.

KaDbDeleteAttachmentData

Future release.

VariableCrashData

KaDbGetVariableCrashData

Queries the VariableCrashData table.

KaDbAddVariableCrashData

Adds a new VariableCrashData record.

 

Note: There is no update function, as one never updates a VariableCrashData record.

KanalyzeModule

KaDbGetKanalyzeModule

Queries the KanalyzeModule table

KaDbAddKanalyzeModule

Adds a new KanalyzeModule record.

 

Note: There is no update function, as one never updates a KanalyzeModule record.

KanalyzeModuleData

KaDbGetKanalyzeModuleData

Queries the KanalyzeModule Data table.

KaDbAddKanalyzeModuleData.

Adds a new KanalyzeModuleData record.

 

Note: There is no update function, as one never updates a KanalyzeModuleData record.

HWProfile

KaDbGetHWProfile

Queries the HWProfile table.

KaDbAddHWProfile

Adds a new HWProfile record.

KaDbUpdateHWProfileOccurrenceCount

Updates the occurrence count associated with a HWProfile record. (Only field that can de updated in HWProfile).

OSProfile

KaDbGetOSProfile

Queries the OSProfile table.

KaDbAddOSProfile

Adds a new OSProfile record.

KaDbUpdateOSProfileOccurrenceCount

Updates the occurrence count associated with a OSProfile record. (Only field that can de updated in OSProfile).

AssociateDB

???

Future release

StopCodeDescription

KaDbGetStopCodeDesc

Future release.

ExternalRecordLocator

???

Future release.

ProcessorType

KaDbGetProcessorType

Queries the ProcessorType Table

ProcessorVendor

KaDbGetProcessorType

Acesses ProcessorVendor Table through joined query with ProcessorType Table.

 

5.1.1    KaDbInitialize

This function is called to initialize the kanalyze database. It will be used to initialize OLE DB and COM libraries.

 

BOOL

KaDbInitialize(

            VOID 

            );

 

Parameters:

 

None.

 

Return Value:

If the function succeeds, the return value is TRUE.  If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

5.1.2    KaDbCleanup

This function is called when no additional database calls are required. The function  closes all connection, closes OLE DB and COM libraries and frees system resources.

 

BOOL

KaDbCleanup(

            IN VOID

            );

 

Parameters:

 

None.

 

Return Value:

If the function succeeds, the return value is TRUE.  If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

5.1.3    KaDbOpenConnection

This function is used to establish a database connection with a named data source. A connection handle is required for all subsequent KaDBxxxx functions.

 

The connection handle is defines as:

 

#define KADB_CONNECTION_TRANACTION_ACTIVE             0x0001

 

typedef struct _KADB_CONNECTION_HANDLE {

   SHORT  Size;

   ULONG32   Flags; // Reserved at this point in time.

   IDBInitialize *pIDBInitialize;

   IUnknown* pUnkSession;

   IUnknown* pUnkPrivateSession; // Private session

}KADB_CONNECTION_HANDLE, *PKADB_CONNECTION_HANDLE;

 

The Size field is used to verify the structure.

 

HANDLE

KaDbOpenConnection(

      IN LPCWSTR FileDSN,

                IN LPCWSTR UID,

            IN LPCWSTR Password

            );

 

Parameters:

 

FileDSN—Specify the full path name of the DSN.

 

UID—User ID to use when connecting to the specified database.

 

Password—The password used to establish a connection.

 

Return Value:

If the function succeeds, the return value is an opaque connection handle.  If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Comment:

The handle returned is a pointer to a structure that contains the interface to the data source and session object. This structure may also contain some state data, i.e., whether a transaction is in progress.

5.1.4    KaDbCloseConnection

This function is used to close a database connection that was previous established by invoking KaDbOpenConnection.

 

BOOL

KaDbCloseConnection(

IN HANDLE DbConnection

);

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

Return Value:

 

If the function succeeds, the return value is TRUE.  If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

 

5.1.5    KaDbStartTransaction

This function is used to start a database transaction and requires a database connection handle.

 

BOOL

KaDbStartTransaction(

            IN HANDLE DbConnection

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

Return Value:

 

If the function succeeds, the return value is TRUE.  If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

 

5.1.6    KaDbRollbackTransaction

This function is used to “un-do” or rollback a set of operations that have been performed under a database transaction. The caller must of called KaDbStartTransaction prior to invoking this function.

 

BOOL

KaDbRollBackTransaction(

            IN HANDLE DbConnection

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

Return Value:

 

If the function succeeds, the return value is TRUE.  If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

 

5.1.7    KaDbCommitTransaction

This function is used to complete a set of operations that have been performed under a database transaction. The caller must of called KaDbStartTransaction prior to invoking this function.

 

BOOL

KaDbCommitTransaction(

            IN HANDLE DbConnection

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

Return Value:

 

If the function succeeds, the return value is TRUE.  If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

 

5.1.8    KaDbGetCrashClass

This function is used to query the CrashClass table for a matching crash. A callback routine is provided to enumerate CrashClass records found within the rowset.  The invoked callback must return TRUE to obtain the next subsequent record within the rowset.

 

CrashClass data is returned within the following structure:

 

typedef struct _KADB_CRASH_CLASS {

    LONG32 SolutionID;

    LONG32 AnalysisID;

    LPSTR StopCode;

    LPSTR StopCodeParameters[4];

    USHORT NTBuild;

    LPSTR Platform;

    LONG32 CanonicalizationLevel;

    LPSTR KeyWords[4];

    LONG32 InstanceCount;

    SYSTEMTIME FirstOccurrence;

    SYSTEMTIME LastOccurrence;

} KADB_CRASH_CLASS, *PKADB_CRASH_CLASS;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDbGetCrashClass(

            IN HANDLE DbConnection,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK CallBack,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

MatchString—Specifies the match string which consists of a SQL Where clause. For example,  “NTBuild = 1381 AND StopCode = ‘A’ AND StopCodeParameter1 = ‘srv!srvXXX+044’ ”. If NULL is passed then a wildcard searched is performed for all CrashClasses records. 

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to its respective callback routine.

 

Reserved—Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and RecordID set to zero and the pointer to the CrashClass data structure is set to NULL.

 

Comment:

This function executes a SQL query and retrieves a rowset object. The callback function is invoked for each record within the rowset. If zero is returned or there are no more records found within the rowset, system resources are returned and the function completes.

5.1.9    KaDbAddCrashClass

This function is used to add a CrashClass record to the database.

 

BOOL

KaDbAddCrashClass(

IN HANDLE DbConnection,

IN PKADB_CRASH_CLASS CrashClass,

            OUT PLONG32 ClassID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

);

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

CrashClassPoints to CrashClass structure that contains the data to be added. The caller is responsible for populating this structure.

 

ClassID—Receives the ID (Key) assigned by the database. This ID is used to uniquely identify this record.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function succeeds, the return value is TRUE. If the function fails, the return value is zero. To get extended error information, call GetLastError. 

 

Comments:

 

The fields FirstOccurrence, LastOccurrence and InstanceCount found within the KANALYZE_CRASH_CLASS_DATA structure are not applicable and are ignored by this function.

 

5.1.10                        KaDbUpdateCrashClass

This function is used to update a CrashClass record. A matching CrashClass record must have been previous located prior to invoking this function (See KaDBGetCrashClass ).

 

#define KADB_UP_CRASH_CLASS_SOLUTION_ID                     0x00001

#define KADB_UP_CRASH_CLASS_ANALYSIS_ID                      0x00002

#define KADB_UP_CRASH_CLASS_INSTANCE_COUNT            0x04000

#define KADB_UP_CRASH_CLASS_FIRST_OCCURRENCE        0x08000

#define KADB_UP_CRASH_CLASS_LAST_OCCURRENCE         0x10000

BOOL

KaDbUpdateCrashClass(

IN HANDLE DbConnection,

IN UINT64 UpdateFlags,

IN LONG32 ClassID,

IN PKADB_CRASH_CLASS CrashClass,

IN PVOID Reserved,

IN UINT_PTR Reserved2

);

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

UpdateFlags—Contains a set of flags that identify which fields to update. Flag values defined as a set of manifested constants can be ORed together.

 

ClassIDIdentifies the CrashClass record to be updated.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function succeeds, the return value is TRUE. If the function fails, the return value is zero. To get extended error information, call GetLastError. 

 

Comments:

 

The CrashClass record identified by the ClassID is currently updated to reflect:

·       Updating the field FirstOccurrence if the CrashTime is older than FirstOccrurance or updating the field LastOccurrence if the CrashTime is earlier than LastOccurrence.

 

5.1.11                        KaDbGetHWProfile

This function is used to query the HWProfile table to determine if a set of matching records exist. A callback routine is provided to enumerate HWProfile records found within the rowset.  The invoked callback routine must return TRUE to obtain the next subsequent record within the rowset.

 

typedef struct _KADB_HW_PROFILE {

   LPSTR Architecture;

   LPSTR ProcessorType;

   LPSTR ProcessorSpec;                     // Not used for now.

   LPSTR ProcessorVendor;                 // Not used for now.

   BYTE ProcessorCount;

   ULONG3222 OccurrenceCount;

} KADB_HW_PROFILE, *PKADB_HW_PROFILE;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDBGetHWProfile(

            IN HANDLE DbConnection,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

MatchString—Specifies the match string which consists of a SQL Where clause. For example,  “Architecture = ‘x86’ AND ProcessorType = ‘Pentium II’ AND ProcessorSpec= ‘Stepping 2’”.  See Comments below.

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

CallBackParm—General purpose parameter passed to callback routine.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function succeeds the return value is TRUE. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and RecordID set to zero and the pointer to the HWProfile data structure is set to NULL.

 

Comments:

The callback function is invoked for each record within the rowset. If FALSE is returned or there are no more records found within the rowset, system resources are returned and the function completes.

5.1.12                        KaDbGetOSProfile

This function is used to query the OSProfile table to determine if a set of matching records exist. A callback routine is provided to enumerate OSProfile records found within the rowset.  The invoked callback routine must return TRUE to obtain the next subsequent record within the rowset. 

 

OSProfile data is returned within the following structure:

 

#define  KADB_OSP_FLAG_CHECKED_BUILD                 0x00000001

#define  KADB_OSP_FLAG_SMP_KERNEL                     0x00000002

#define  KADB_OSP_FLAG_PAE_KERNEL                     0x00000004

 

typedef struct _KADB_OS_PROFILE {

    ULONG32  Flags; 

    USHORT Build;

    SHORT ServicePackLevel;

    LPSTR ProductType;

    LPWSTR QfeData;                          // Not used for now.

    ULONG32 OcurranceCount;

} KADB_OS_PROFILE, *PKADB_OS_PROFILE;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDBGetOSProfile(

            IN HANDLE   DbConnection,

            IN LONG32    OSProfileRecID,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

BOOL

KaDBGetOSProfile(

            IN HANDLE   DbConnection,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

MatchString—Specifies the match string which consists of a SQL Where clause. For example,  “OSCheckedBuild = 0 AND OSBuild= 1381 AND OSServicePack=3”.  See Comments below.

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to the its respective callback routine.

 

Reserved—Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and RecordID set to zero and the pointer to OsProfile data structure is set to NULL.

 

Comments:

The callback function is invoked for each record within the rowset. If FALSE is returned or there are no more records found within the rowset, system resources are returned and the function completes.

5.1.13                        KaDbAddHWProfile

This function is used to add a new HW Profile record to the database and is invoked when an exact HW match could not be found.

 

BOOL

KaDbAddHWProfile(

            IN HANDLE   DbConnection,

            IN PKADB_HW_PROFILE HWProfile,

            OUT PULONG32 HWProfileRecID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

 Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

HWProfile—Points to a data structure that contains HW Profile data that is to be added to the database. The OccurrenceCount field is ignored for this call.

 

HWProfileRecID—Receives the ID (key) assigned by the database. This ID is used to uniquely identify this record.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function successfully adds the record, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

5.1.14                        KaDbAddOSProfile

This function is used to add a new OS Profile record to the database and is invoked when an exact HW match could not be found.

 

BOOL

KaDbAddOSProfile(

            IN HANDLE   DbConnection,

            IN PKADB_OS_PROFILE OSProfile

            OUT PULONG32 OSProfileRecID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

 Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

OSProfile—Points to a data structure that contain OS Profile data that is to be added to the database. The OccurrenceCount field is ignored for this call.

 

OSProfileRecID—Receives the ID (key) assigned by the database. This ID is used to uniquely identify this record.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function successfully adds the record, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

5.1.15                        KaDbUpdateHWProfileOccurrenceCount

This function is used to update the HW Profile record occurrence count.

 

BOOL

KaDbUpdateHWProfileOccurrenceCount(

            IN HANDLE   DbConnection,

            IN LONG32  HWProfileRecID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

HWProfileRecID—Specifies the ID (key) of the HWProfile record to update.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function successfully updates the record, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

5.1.16                        KaDbUpdateOSProfileOccurrenceCount

This function is used to update the occurrence count OS Profile record..

 

BOOL

KaDbUpdateOSProfileOccurrenceCount(

            IN HANDLE   DbConnection,

            IN LONG32 OSProfileRecID,

IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

OSProfileRecID—Specifies the ID (key) of the OSProfile record to update.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function successfully updates the record, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError

 

5.1.17                       KaDbGetCrashInstance

This function is used to query the CrashInstance table for a matching instance. A callback routine is provided to enumerate CrashInstance records found within the rowset.  The invoked callback must return TRUE to obtain the next subsequent record within the rowset.

 

CrashInstance data is returned within the following structure:

 

typedef struct _KADB_CRASH_INSTANCE {

    ULONG32 HWProfileRecID;

    ULONG32 OSProfileRecID;

    LPSTR     StopCodeParameters[4];

    USHORT KanalyzeMajorVersion;

    USHORT KanalyzeMinorVersion;

    SYSTEMTIME DateTime;

} KADB_CRASH_INSTANCE, *PKADB_CRASH_INSTANCE;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDbGetCrashInstance(

            IN HANDLE DbConnection,

            IN LONG32 CrashID,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK CallBack,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

CrashID—Specifies the CrashClass record ID and is used to query the set of crash instances that are associated with a particular CrashClass. If  NULL is specified, then a wild card search is performed on all CrashClass records. Using NULL for the CrashClassID allows the caller to perform quick searches for specific crash instances without the need to first identify a CrashClass.

 

MatchString—Specifies the match string which consists of a SQL Where clause. For example,  “KanalyzeMajorVersion = 3 AND StopCodeParameter1 = ‘c0000005’ AND StopCodeParameter4 = ‘f2152260’ ”. Additionally, the MatchString can be set to NULL. In this case, the function will enumerate a list of crash instances that are associated with a specific crash class.

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to the respective callback routine.

 

Reserved— Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and RecordID set to zero and the pointer to the CrashInstance data structure is set to NULL.

 

Comment:

This function executes a SQL query and retrieves a rowset object. The callback function is invoked for each record within the rowset. If zero is returned or there are no more records found within the rowset, system resources are returned and the function completes.

When a ClassID is specified in the call, the SQL select statement is modified as shown in bold:

            Select * from CrashInstance where ClassID = parm1 AND
            StopCodeParmeter1 = parm2 AND StopCodeParmeter2 = parm3….

5.1.18                        KaDbAddCrashInstance

This function is used to add a CrashInstance record to the database.

 

BOOL

KaDbAddCrashInstance(

IN HANDLE DbConnection,

IN PKADB_CRASH_INSTANCE CrashInstance,

            OUT PLONG32 InstanceID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

);

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

CrashInstancePoints to CrashInstance structure that contains the data to be added. The caller is responsible for populating this structure.

 

InstanceID—Receives the ID (Key) assigned by the database. This ID is used to uniquely identify this record.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function succeeds, the return value is TRUE. If the function fails, the return value is zero. To get extended error information, call GetLastError. 

 

Comments:

 

Prior to adding a new CrashInstance record, the HW profile table must be enumerated for matches on the following fields specified in the signature ID file: Architecture, ProcessorType,  and ProcessorCount.

 

The OS profile tables must also be enumerated for matches on the following fields specified in the signature ID file: OSCheckedBuild, OSSMPKernel, OSPAEKernel,OSServicePackLevel, and ProductType. 

 

If any of the fields do not match, then a new HW or OS profile record must be added to the database.

 

5.1.19                        KaDbGetKernelModuleData

This function is used to query the KernelModuleData table for matching records. A callback routine is provided to enumerate KernelModuleData records found within the returned rowset.  The invoked callback routine must return TRUE to obtain the next subsequent record within the rowset. 

 

The KernelModuleData record is returned within the following structure:

 

typedef struct _KADB_KERNEL_MODULE_DATA {

    LPWSTR BaseName;

    LONG32 Size;

    LPSTR Checksum;

    SYSTEMTIME DateTime;

    SHORT SubsystemMajorVersion;

    SHORT SubsystemMinorVersion;

} KADB_KERNEL_MODULE_DATA, *PKADB_KERNEL_MODULE_DATA;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDBGetKernelModuleData(

            IN HANDLE   DbConnection,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackRt,

            IN UINT_PTR Reserved

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

MatchString—Specifies the match string which consists of a SQL Where clause. For example,  “BaseName= ‘srv’ AND Size=4500 AND Checksum=’0234AE28’”.  See Comments below.

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to the respective callback routine.

 

Reserved—Reserved for future use.

 

Return Value:

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and RecordID set to zero and the pointer to the KernelModuleData data structure is set to NULL.

 

Comments:

The callback function is invoked for each record within the rowset. If FALSE is returned or there are no more records found within the rowset, system resources are returned and the function completes.

 

To obtain the required data, this function must perform a join between KernelModuleData and KernelModule tables (KernelModule is required as to obtain the LoadAddress field).

 

5.1.20                        KaDbGetKanalyzeModuleData

This function is used to query the KanalyzeModuleData table for a matching crash. A callback routine is provided to enumerate KanalyzeModuleData records found within the returned rowset.  The invoked callback routine must return TRUE to obtain the next subsequent record within the rowset. 

 

The KanalyzeModuleData record is returned within the following structure:

 

typedef struct _KADB_KANALYZE_MODULE_DATA {

    LPWSTR BaseName;

    LPSTR Type;

    LPWSTR AlternateName;  

    USHORT MajorVersion;

    USHORT MinorVersion;

    LPWSTR Description; 

} KADB_KANALYZE_MODULE_DATA, *PKADB_KANALYZE_MODULE_DATA;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDBGetKanalyzeModuleData(

            IN HANDLE   DbConnection,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

MatchString—Specifies the match string which consists of a SQL Where clause. For example,  “BaseName= ‘Ebojects’ Type= ‘Base’”.  See Comments below.

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to the respective callback routine.

 

Reserved—Reserved for future use.

 

Return Value:

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and RecordID set to zero and the pointer to KanalyzeModuleData data structure is set to NULL.

 

Comments:

The callback function is invoked for each record within the rowset. If FALSE is returned or there are no more records found within the rowset, system resources are returned and the function completes.

 

5.1.21                        KaDbAddKernelModuleData

This function is used to add a new KernelModuleData record to the database and is invoked when an exact KernelModuleData match could not be found.

 

 

BOOL

KaDbAddKernelModuleData(

            IN HANDLE   DbConnection,

                IN PKADB_KERNEL_MODULE_DATA KernelModuleData,

            OUT PLONG32 KernelModuleID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

 Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

KernelModuleData—Points to a data structure that contain the KernelModuleData data that is to be added to the database. The LoadAddress field is ignored for this call.

 

KernelModuleID—Receives the ID (key) assigned by the database. This ID is used to uniquely identify this record.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

                             

If the function successfully adds the record, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

5.1.22                        KaDbAddKanalyzeModuleData

This function is used to add a new KanalyzeModuleData record to the database and is invoked when an exact KanalyzeModuleData match could not be found.

 

BOOL

KaDbAddKanalyzeModuleData(

            IN HANDLE   DbConnection,

            PKADB_KANALYZE_MODULE_DATA KanalyzeModuleData

            OUT PLONG32 KanalyzeModuleID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

 Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

KanalyzeModuleData—Points to a data structure that contains KanalyzeModuleData data that is to be added to the database. 

 

KanalyzeModuleID—Receives the ID (key) assigned by the database. This ID is used to uniquely identify this record.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function successfully adds the record, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

5.1.23                        KaDbGetKernelModule

This function is used to query the KernelModule and KernelModuleData tables to obtain a list of kernel modules that are associated with a specific crash instance and/or to acquire specific information regarding a kernel module that is associated with a crash instance. Internally the function performs a join on the KernelModule and KernelModuleData tables. A callback routine is provided to enumerate KernelModule records found within the rowset.  The invoked callback must return TRUE to obtain the next subsequent record within the rowset.

 

KernelModule and KernelModuleData data is returned within the following structure:

 

typedef struct _KADB_KERNEL_MODULE {

    LPWSTR LoadAddress;

    PKADB_KERNEL_MODULE_DATA KernelModuleData;

} KADB_KERNEL_MODULE, *PKADB_KERNEL_MODULE;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDbGetKernelModule(

IN HANDLE DbConnection,

IN LONG32 ClassID,

IN LONG32 InstanceID,

IN LPCWSTR MatchString,

IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

);

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

ClassID—Specifies the ClassID of the CrashClass.

 

InstanceID—Specifies the instance of the crash that is associated with the ClassID.

 

MatchString—Specifies the match string which consists of a SQL Where clause. For example,  “BaseName= ‘ntoskrnl.exe’AND Checksum=0x84534573”. Setting the MatchString to NULL will cause the function to generate a list of all kernel modules that were associated with a crash.

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to the its respective callback routine.

 

Reserved—Reserved for future use.

 

Return Value:

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and RecordID set to zero and the pointer to Data data structure is set to NULL.

 

5.1.24                        KaDbAddKernelModule

This function is used to create a new KernelModule record within the database. It requires that a KernelModuleData record be first identified (or added) as well as the identification of a crash instance and CrashClass record.

 

BOOL

KaDbAddKernelModule(

            IN HANDLE   DbConnection,

            IN PKADB_KERNEL_MODULE KernelModule,     

            IN LONG32 ClassID,

            IN LONG32 InstanceID,

IN LONG32 KernelModuleID,

IN PVOID Reserved,

IN UINT_PTR Reserved2

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

KernelModule— ID Specifies a pointer that points to KernelModule. For the insert operation only interested in the LoadAddress field of the structure.

 

ClassID— ID (key) assigned by the database to uniquely identify a CrashClass record.

 

InstanceID—ID (key) assigned by the database to uniquely identify a unique instance of a specific crash.

 

KernelModuleID-ID (key) assigned by the database to uniquely identifies a KernelModule (obtained by querying KernelModule table or adding a new KernelModule record.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

                             

If the function successfully adds the record, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError. 

 

5.1.25                        KaDbGetKanalyzeModule

This function is used to query the KanalyzeModule and KanalyzeModuleData tables to obtain a list of kanalyze modules that are associated with a specific crash instance and/or to acquire specific information regarding a kanalyze module that is associated with a crash instance. Internally the function performs a join on the KanalyzeModule and KanalyzeModuleData tables. A callback routine is provided to enumerate KanalyzeModule records found within the rowset.  The invoked callback must return TRUE to obtain the next subsequent record within the rowset.

 

KanalyzeModuleData data is returned within the KADB_KANALYZE_MODULE_DATA structure. No KanalyzeModule data is retuned. This is because KanalyzeModule table does not provide any additional data (the two tables are required to obtain the join relationship that will enable the SQL to associate the set of kanalyze modules that are associated with a specific crash instance).

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDbGetKanalyzeModule(

IN HANDLE DbConnection,

IN LONG32 ClassID,

IN LONG32 InstanceID,

IN LPCWSTR MatchString,

IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

);

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

ClassID—Specifies the ClassID of the CrashClass.

 

InstanceID—Specifies the instance of the crash that is associated with the ClassID.

 

MatchString—Specifies the match string which consists of a SQL Where clause. For example,  “BaseName= ‘Eobjects.dll’”. Setting the MatchString to NULL will cause the function to generate a list of all kanalyze modules that were associated with a crash.

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to the its respective callback routine.

 

Reserved—Reserved for future use.

 

Return Value:

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and RecordID set to zero and the pointer to Data data structure is set to NULL.

 

5.1.26                        KaDbAddKanalyzeModule

This function is used to add a new KanalyzeModule record to the database.

 

BOOL

KaDbAddKanalyzeModule(

            IN HANDLE   DbConnection,

            IN LONG32 KanalyzeModuleID,

            IN LONG32 ClassID,

IN LONG32 InstanceID,

IN PVOID Reserved,

IN UINT_PTR Reserved2

            );

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

KanalyzeModuleID - ID (key) assigned by the database to uniquely identify KanalyzeModuleData.

 

ClassID - ID (key) assigned by the database to uniquely identify a CrashClass record.

 

InstanceID - ID (key) assigned by the database to uniquely identify a CrashInstance record.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

                             

If the function successfully adds the record, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

5.1.27                        KaDbGetAttachmentData

This function is used to query the AttachmentData table for a matching crash. A callback routine is provided to enumerate AttachmentData records found within the rowset.  The invoked callback must return TRUE to obtain the next subsequent record within the rowset.

 

Attachment data is returned within the following structure:

 

typedef struct _KADB_ATTACHMENT_DATA {

    LPWSTR Location;

    ULONG32 Size;

    LPWSTR Description;         

    SYSTEMTIME DateTime;

} KADB_ATTACHMENT_DATA, *PKADB_ATTACHMENT_DATA;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDbGetAttachmentData(

            IN HANDLE DbConnection,

            IN LONG32 ClassID,

            IN LONG32 InstanceID,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK CallBack,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

ClassID—Specifies the ClassID to associate Attachment data record. With.

 

InstanceID—Specifies the instanceID to associate Attachment data record with.

 

MatchString—Specifies the match string which consists of a SQL Where clause. For example,  “DateTime = 8/27/99 6:33:00 AM AND ClassID = ‘25’ AND InstanceID = ‘14’ ”

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to the respective callback routine.

 

Reserved—Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and RecordID set to zero and the pointer to the AttachmentData structure is set to NULL.

 

Comment:

This function executes a SQL query and retrieves a rowset object. The callback function is invoked for each record within the rowset. If zero is returned or there are no more records found within the rowset, system resources are returned and the function completes.

5.1.28                        KaDbAddAttachmentData

This function is called as part of adding a crash instance and is used to add Attachment records. Prior to invoking this call, the caller must have identified a CrashClass and CrashInstance record.

 

BOOL

KaDbAddAttachmentData(
            IN HANDLE  DbConnection,

            IN LONG32  ClassID,

            IN LONG32  InstanceID,

            OUT PLONG32  ItemID,

            IN PKADB_ATTACHMENT_DATA AttachmentData,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

ClassID— ID (key) assigned by the database to uniquely identify a CrashClass record.

 

InstanceID—ID (key) assigned by the database to uniquely identify a unique instance of a specific crash.

 

ItemID—Receives a uniquely identifies for the item being added.

 

AttachementData—Points to a data structure that contains attachment data.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

                             

If the function successfully adds the record, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

5.1.29                       KaDbGetVariableCrashData

This function is used to query the VariableCrashData table for a matching crash. A callback routine is provided to enumerate VariableCrashData records found within the rowset.  The invoked callback must return TRUE to obtain the next subsequent record within the rowset.

 

Variable Crash data is returned within the following structure:

 

typedef struct _KADB_VARIABLE_CRASH_DATA {

   LPWSTR BlobName;

   LPWSTR BlobWriterID;

   ULONG32 DataLength;        // Size of blob in bytes

   PUCHAR Data;                               

} KADB_ VARIABLE_CRASH _DATA, *PKADB_ VARIABLE_CRASH_DATA;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDbGetVariableCrashData(

            IN HANDLE DbConnection,

            IN LONG32 ClassID,

            IN LONG32 InstanceID,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK CallBack,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

ClassID—Specifies the CrashClass to associate the variable crash data with.

 

InstanceID—Specifies the Crash Instance to associate the variable crash data with.

 

MatchString—Specifies the match string which consists of a SQL Where clause. For example,  “ClassID = 381 AND InstanceID = ‘121’ AND BlobName = ‘Netbt Blob’ ”

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to the respective callback routine.

 

Reserved—Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and RecordID set to zero and the pointer to the VariableCrashData structure is set to NULL.

 

Comment:

This function executes a SQL query and retrieves a rowset object. The callback function is invoked for each record within the rowset. If zero is returned or there are no more records found within the rowset, system resources are returned and the function completes.

 

5.1.30                        KaDbAddVariableCrashData

This function is used to add variable crash data to a crash instance record.  Prior to invoking this call, the caller must have identified a CrashClass and CrashInstance record.

 

BOOL

KaDbAddVariableCrashData(
            IN HANDLE DbConnection,

            IN LONG32  ClassID,

            IN LONG32  InstanceID,

            IN PKADB_VARIABLE_CRASH_DATA VariableCrashData,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

ClassID— ID (key) assigned by the database to uniquely identify a CrashClass record.

 

InstanceID—ID (key) assigned by the database to uniquely identify a unique instance of a specific crash.

 

VariableCrashData—Points to a data structure that contains variable crash data.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

                             

If the function successfully adds the record, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

5.1.31                        KaDbGetSolution

This function is used to query the Solution table for a matching crash. A callback routine is provided to enumerate Solution records found within the rowset.  The invoked called back must return TRUE to obtain the next subsequent record within the rowset. Solution Data is returned in the data structure KADB_SOLUTION which is defined in the function.

 

Solution Data is returned in the data structure KADB_SOLUTION which is defined as:

 

typedef struct KADB_SOLUTION {

   LPWSTR Abstract;

   LPWSTR SolutionDescription;

   LPWSTR KeyWords;

   SYSTEMTIME LastUpdated;

} KADB_SOLUTION, *PKADB_SOLUTION;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDBGetSolution(

            IN HANDLE   DbConnection,

            IN LONG32 SolutionID,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

      IN UINT_PTR Reserved

      );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

SolutionID— Specifies the SolutionID for quick record lookups. Parameter is mutually exclusive with the MatchString parameter. Should be NULL when specifying a MatchString.

 

MatchString—Specifies the match string which consists of a SQL Where clause.

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to the respective callback routine.

Reserved—Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and RecordID set to zero and the pointer to Solution data structure is set to NULL.

 

5.1.32                        KaDbAddSolution

This function is used to add a Solution record to the database.

 

BOOL

KaDbAddSolution(

IN HANDLE DbConnection,

IN PKADB_SOLUTION Solution,

OUT PLONG32 SolutionID,

IN PVOID Reserved,

IN UINT_PTR Reserved2

);

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

SolutionPoints to Solution structure that contains the data to be added. The caller is responsible for populating this structure.

 

SolutionID—Receives the ID (Key) assigned by the database. This ID is used to uniquely identify this record.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function succeeds, the return value is TRUE. If the function fails, the return value is zero. To get extended error information, call GetLastError. 

 

Comments:

 

None.

 

5.1.33                        KaDbUpdateSolution

This function is used to update a Solution record. A matching Solution record must have been previous located prior to invoking this function (See KaDBGetSolution ).

 

#define KADB_UP_SOLUTION_ABSTRACT                                  0x0001

#define KADB_UP_SOLUTION_SOLUTION_DESCRIPTION       0x0002

#define KADB_UP_KEYWORDS                                                      0x0004

 

BOOL

KaDbUpdateSolution(

    IN HANDLE DbConnection,

    IN UINT64 UpdateFlags

    IN LONG32 SolutionID,

    IN PKADB_SOLUTION Solution

    IN PVOID Reserved,

    IN UINT_PTR Reserved2

    );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

UpdateFlags—Contains a set of flags that identify which fields to update. Flag values defined as a set of manifested constants can be ORed together.

 

SolutionID—Specifies the ID (key) of the solution record to update.

 

pSolution— Points to KADB_SOLUTION structure that contains the data to be updated. The caller is responsible for populating this structure.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

Comments:

 

None.

 

5.1.34                        KaDbGetHintData

This function is used to query the HintData table for a matching crash. A callback routine is provided to enumerate HintData records found within the rowset.  The invoked called back must return TRUE to obtain the next subsequent record within the rowset.

 

Hint Data is returned in the following structure.

 

typedef struct _KADB_HINT {

     LPWSTR Data;                   // Keep in structure as we may add to this structure.

} KADB_HINT, *PKADB_HINT;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

The invoked callback routine must return TRUE to obtain the next subsequent record within the rowset.

 

BOOL

KaDBGetHintData(

            IN HANDLE   DbConnection,

            IN LONG32  SolutionID,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

SolutionID—Specifies the match data which consists of a SQL Where clause.

 

MatchString— Specifies the match string which consists of a SQL where clause. Setting the MatchString to NULL will cause the function to generate a list of all hint data that is associated with a SolutionID.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to the respective callback routine.

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

Reserved—Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount, DataID and DataSize are set to zero and Data is set to NULL.

 

Comments:


The callback function is invoked for each record within the rowset. If FALSE is returned or there are no more records found within the rowset, system resources are returned and the function completes.

5.1.35                        KaDbGetAnalysis

This function is used to query the Analysis table for a matching crash. A callback routine is provided to enumerate Analysis records found within the rowset.  The invoked called back must return TRUE to obtain the next subsequent record within the rowset. Analysis Data is returned in the data structure KADB_ANALYSIS which is defined in the function.

 

Analysis Data is returned in the data structure KADB_ANALAYSIS, which is defined as:

 

typedef struct _KADB_ANALYSIS {

   LPWSTR Abstract;

   LPWSTR ProblemDescription;

   LPWSTR KeyWords;

   LPSTR Status;

} KADB_ANALYSIS, *PKADB_ANALYSIS;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDBGetAnalysis(

            IN HANDLE   DbConnection,

            IN LONG32    AnalysisID,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

      );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

AnalysisID-- Specifies an AnalysisID for quick record lookups. Parameter is mutually exclusive with the MatchString parameter. Should be NULL when specifying a MatchString.

 

MatchString—Specifies the match string which consists of a SQL Where clause.

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to the its respective callback routine.

 

Reserved—Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and RecordID set to zero and the pointer to Analysis  data structure is set to NULL.

 

 

5.1.36                        KaDbAddAnalysis

This function is used to create an analysis record and to associate the analysis record with a CrashClass record. This function requires that the caller has identified a CrashClass record.

 

BOOL

KaDBAddAnalysis(

            IN HANDLE  DbConnection,

            IN LONG32   CrashClassID,

            IN PKADB_ANALYSIS AnalysisData

            OUT PLONG AnalysisID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

CrashClassID—Specifies the ID (key) of the CrashClass to associate the new created analysis record.

 

AnalysisData—Points to a structure that receives the Analysis data.

 

AnalysisID—Receives the ID (key) of the newly created analysis record.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

Comments:

 

None.

 

KaDbAddAnalysis first retrieves the CrashClass record identified by ClassID parameter. If no analysis record is found, this function creates the analysis record and then updates the CrashClass record to include the AnalysisID (key).

 

5.1.37                        KaDbUpdateAnalysis

This function is the generalize update function used to update an analysis record. It requires the user to have previously identified an Analysis record.

 

#define KADB_UP_ANALYSIS_ABSTRACT                       0x0001 // Updates abstract field

#define KADB_UP_ANALYSIS_PROBLEM_DESC 0x0002 // Updates problem desc

                                                                                                            //  field

#define KADB_UP_ANALYSIS_KEYWORDS                     0x0004 // Updates keyword field

#define KADB_UP_ANALYSIS_STATUS                            0x0008 // Updates status field

 

BOOL

KaDbUpdateAnalysis(

            IN HANDLE  DbConnection,

            IN UINT64 UpdateFlags

            IN LONG32   AnalysisID,

            IN PKADB_ANALYSIS AnalysisData,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

UpdateFlags—Contains a set of flags that identify which fields to update. Flag values defined as a set of manifested constants can be ORed together.

 

AnalysisID—Specifies the ID (key) of the analysis record to update.

 

AnalysisData—Points to a structure that contains analysis data.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

Comments:

 

None.

 

5.1.38                        KaDbAddProgressText

This function is used to create a ProgressText record and to associate that ProgressText with an analysis record.

 

BOOL

KaDBAddProgressText(

            IN HANDLE  DbConnection,

            IN LONG  AnalysisID,

            IN PKADB_PROGRESS_TEXT ProgressText,

           OUT PLONG32 ProgressTextID,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

AnalysisID—Specifies the analysisID to associate with new progress text record.

 

ProgressText—Points to ProgressText structure that contains the data to be added. The caller is responsible for populating this structure.

 

ProgressTextID—Received the ID (key) for the newly create progress text record.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to the respective callback routine.

 

Reserved—Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. Otherwise FALSE is returned. To get extended error information, call GetLastError.

 

Comments:

 

Function validates whether the analysis record exist and creates an analysis record with the specified data.

 

5.1.39                        KaDbGetProgressText

This function is used to query for ProgressText records given an AnalysisID.  A callback routine is provided to enumerate ProgressData records found within the rowset in either ascending or descending order.  The query is limited to ProgressData records that are associated with a specific Analysis record.

 

The following structure is used to receive ProgressText record data:

 

typedef struct _KADB_PROGRESS_TEXT {

   SYSTEMTIME DateTime;

   LPWSTR Author;

   LPWSTR Annotation;

} KADB_PROGRESS_TEXT, *PKAD_PROGRESS_TEXT;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDbGetProgressText(

            IN HANDLE  DbConnection,

            IN LONG32 AnalysisID,                    

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

AnalysisID Specifies the Solution record, which will limit the search of only the set of ProgressText records that is associated with the same AnalysisID.

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

Reserved—Reserved for future use.

 

Reserved2—Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. Otherwise FALSE is returned. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and ProgressTextID set to zero and the pointer to ProgressText data structure is set to NULL.

 

Comments:

 

The callback function is invoked for each record within the rowset. If FALSE is returned or there are no more records found within the rowset, system resources are returned and the function completes.

5.1.40                        KaDbGetProcessorTypeProcessorVendor

This function allows the caller to query  the ProcessorType and ProcessorVendor tables (they are joined).  A callback routine is provided to enumerate the records found within the rowset.  The invoked called back must return TRUE to obtain the next subsequent record within the rowset. ProcessorType and ProcessorVendor data which is returned in the data structure KADB_PROCESSOR_TYPE_PROCESSOR_VENDOR defined below.

typedef struct _KADB_PROCESSOR_TYPE {

   LONG32      VendorID;

   LPSTR         Type;

   USHORT      Family;

   USHORT      Model;

   USHORT      Step;

} KADB_PROCESSOR_TYPE, *PKADB_PROCESSOR_TYPE;

 

typedef struct _KADB_PROCESSOR_VENDOR {

   LONG32   VendorID;

   LPSTR     VendorName;

} KADB_PROCESSOR_VENDOR, *PKADB_PROCESSOR_VENDOR;

 

typedef struct _KADB_PROCESSOR_TYPE_PROCESSOR_VENDOR {

    struct _KADB_PROCESSOR_TYPE    ProcessorType;

    struct _KADB_PROCESSOR_VENDOR  ProcessorVendor;  

} KADB_PROCESSOR_TYPE_PROCESSOR_VENDOR, *PKADB_PROCESSOR_TYPE_PROCESSOR_VENDOR;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDbGetProcessorTypeProcessorVendor(

    IN  HANDLE      DbConnection,

    IN  LPCWSTR     MatchString,

    IN  PKADB_ENUM_DATA_CALLBACK Callback,

    IN  PVOID       CallBackParm,

    IN  UINT_PTR    Reserved

    );

 

Parameters:

 

DbConnection—A database connection that was established by KaDbOpenConnection.

 

MatchString—Specifies the match string which consists of a SQL Where clause.

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for each matching record found within the returned rowset.

 

CallBackParm—Specifies a callback parameter. Allows caller to pass a parameter to the respective callback routine.

Reserved—Reserved for future use.

 

Return Value:

 

If the function succeeds, TRUE is returned. If the function fails, the return value is zero. To get extended error information, call GetLastError.

 

In the case where no matching records are found, the callback function is invoked with the RecordCount and RecordID set to zero and the pointer to ProcessorTypeProcessorVendor data structure is set to NULL.

 

5.1.41                        KaDbGetLastError

All KaDb functions return TRUE or FALSE. Calling GetLastError can retrieve extended error information. Because we may also be dealing with underlying SQL error messages we should expose an additional function, KaDBGetLastError. This function should be used in place of GetLastError.

 

KaDbGetLastError determines if the error is a SQL error or a WIN32 error, returns a message string and an indication of the error.

 

The following structure is used to receive error context:

 

typedef struct _KADB_ERROR {

    ULONG32 HResult; // HRESULT error code

    LPCWSTR Description; // Error description for Hresult, if any. Otherwise, NULL.

    LPCWSTR SQLInfo; // SQL error context, if any. Otherwise, NULL.

    LPCWSTR Source; // Name of the component that generated the error, if any. Otherwise, NULL.

} KADB_ERROR, *PKADB_ERROR;

 

PKADB_ENUM_DATA_CALLBACK defined in section 4.1.3.1.

 

BOOL

KaDbGetLastError(

            IN PKADB_ENUM_DATA_CALLBACK Callback

            );

 

Parameters:

 

CallBack—Provides the address of an enumerator callback function. This function is invoked for the error context.

 

Return Value:

 

If the function succeeds, TRUE is returned. Otherwise FALSE is returned. To get extended error information, call GetLastError.

 

Comments:

 

GetLastError should be called earlier than KaDbGetLastError, when the both functions need to be called.

 

5.2      Database Low-Level Access Interface

This set of interfaces defines the low-level functions that wrap OLE DB. TBD.

 

6.      Kanalyze Plug-ins

6.1      Role of the Master Analysis Plug-In

TBD.

6.2      Database Plug-In

On the kanalyze environment, all access to the known issues database provides by database plug-in (database.dll). And the database plug-in also process the hint data.

This section deal with the functions that the database plug-in provides, and the hint data syntax.

 

The database plug-in provides the following routines.

            Functions to get the detail information of known issues database matched items.

            Functions to access the known issues database. (This is wrapped the kadbprov.dll functions)

 

6.2.1    Hint processing

The database plug-in process the hint data.

This section is deal with hint processing.

 

6.2.1.1       Match Level to Report

The database plug-in will reports a match level depending on the matching result. The results can be classified into the following three cases.

 

Case 1 : No hint data was found in DB or

Hint data was found, but no related data was found in sigid file.

The database plug-in will not reports match level (i.e. does not call ReportMatchCallback).

 

Case 2 : Hint data was found, but not matched with sigid file.

The database plug-in will reports MatchNot.

 

Case 3 : Hint data found, and matched with sigid file.

The database plug-in will reports MatchAbsolute.

 

When multiple hint data were found, database plug-in processes each hint data and combine match results with “AND”. This means, database plug-in will reports MatchAbsolute only in the case that all conditions described in hint data are match.

 

 

6.2.1.2       Hint data syntax

The hint data syntax is the following.

The hint data will be maintained by human work, so the hint data should be written in plain text.

The clauses can combine with AND/OR and/or round brackets. This is like a WHERE clause format of SQL search condition.

 

Hint data format:

<Condition> [ <AND or OR > <Condition> [...] ]

 

<Condition>

<Table_name>.<Keyword><Operator><Value>

Notes:

- Each condition is separated by one space character (“ “).

- No space caracter (“ “) is needed between each Operator except CONTAINS, AND and OR Operator.

- You can enclose a string type value contains any spaces with single quotation (‘). If the value does not contain any spaces, you can specify the value without single quotation.

- This plug-in will evaluates operator in left to right order. You can change the evaluation order by using a pair of round brackets (“(...)”).

 

<Table_name>

Specify a table name. Valid table names are...

CrashClass, CrashInstance, KernelModule, KernelModuleData, KanalyzeModuleData, ExternalRecordLocator, HWProfile, OSProfile

All other tables are not supported.

 

<Keyword>

Specify a keyword. Valid keywords are...

CrashClass:

StopCode, StopCodeParameter1, StopCodeParameter2, StopCodeParameter3, StopCodeParameter4, NTBuild, Platform, KeyWord1, KeyWord2, KeyWord3, KeyWord4

CrashInstance:

StopCodeParameter1, StopCodeParameter2, StopCodeParameter3, StopCodeParameter4, KanalyzeMajorVersion, KanalyzeMinorVersion

KernelModule:

LoadAddress

KernelModuleData:

BaseName, Size, CheckSum, TimeDate, SubSystemMajorVersion, SubsystemMinorVersion

KanalyzeModuleData:

BaseName, Type, AlternateName, MajorVersion, MinorVersion, Description

ExternalRecordLocator:

Customer, ServiceRec

HWProfile:

Architecture, ProcessorType, ProcessorStep, ProcessorVendor, ProcessorCount

OSProfile:

OSCheckedBuild, OSMPKernel, OSPAEKernel, OSBuild, OSServicePackLevel, ProductType, QfeData

 

<Operator>

Specify an operator. Valid operators are...

=                          Means equal.

!=                         Means not equal.

<                          Means less than.

<=                        Means less than or equal.

>                          Means greater than.

>=                        Means greater than or equal.

CONTAINS        Means contains, valid for only strings.

 

<Value>

Specify a value.

When specify a numeric value, you must specify in the following syntax.

    decimal value    123456

    hex value          0x123456

 

When table name is one of the following, you must specify the BaseName first.

    KernelModuleData, KernelModule, KanalyzeModuleData

 

When the keyword has TimeDate type, you must specify the <Value> in following syntax.

    yyyy/mm/dd[,hh:mm:ss]

                yyyy:year, mm:month, dd:day

                hh:hour, mm:minute, ss:second

                you can use ‘*’ for wildcard at the end of <Value>.

e.g.

KernelModuleData.BaseName=foo.sys AND (KernelModuleData.MajorVersion<2 OR OSProfile.OSBuild<=2032) AND ExternalRecordLocator.Customer=’ABC Company’

 

KernelModuleData.BaseName contains foo AND KernelModuleData.DateTime<1999/12/*

 

 

6.2.2    Method Interfaces

The database plug-in provides two method interfaces, which are used to get detailed information about the items located in Analysis\DbPreMatching and Analysis\DbMatching namespaces.

 

6.2.2.1       M_QUERY_GET_PREQUERY_MATCH_RESULT

This function returns the detailed information of the specified pre-query match result item.

The following structure is used to receive the detailed information.

 

typedef struct _QUERY_MATCH_RESULT {

    HKAPLUGIN ReportedPluginHandle;

    MatchConfidenceLevel MatchLevel;

    KANALYZE_CRASH_CLASS_DATA CrashData;

    KADB_SOLUTION SolutionData;

    LPWSTR SolutionTextOverride;

    KADB_ANALYSIS AnalysisData;

} QUERY_MATCH_RESULT, *PQUERY_MATCH_RESULT;

 

UINT_32

(KANALYZE_CALL_METHOD_ROUTINE)(

IN HKAPLUGIN hPlugIn

IN KA_ITEM_ID ItemID

IN ULONG32 M_QUERY_GET_PREQUERY_MATCH_RESULT

OUT PQUERY_MATCH_RESULT QueryMatchResult

)

 

 

6.2.2.2       M_QUERY_GET_MATCH_RESULT

This function returns the detailed information of the specified full-query match result item.

The following structure is used to receive the detailed information.

 

typedef struct _QUERY_MATCH_RESULT {

    HKAPLUGIN ReportedPluginHandle;

    MatchConfidenceLevel MatchLevel;

    KANALYZE_CRASH_CLASS_DATA CrashData;

    KADB_SOLUTION SolutionData;

    LPWSTR SolutionTextOverride;

    KADB_ANALYSIS AnalysisData;

} QUERY_MATCH_RESULT, *PQUERY_MATCH_RESULT;

 

UINT_32

(KANALYZE_CALL_METHOD_ROUTINE)(

IN HKAPLUGIN hPlugIn

IN KA_ITEM_ID ItemID

IN ULONG32 M_QUERY_GET_MATCH_RESULT

OUT PQUERY_MATCH_RESULT QueryMatchResult

)

 

6.2.3    Public helper/callback routines

Database plug-in provides the wrapper functions of kadbprov.dll.

The plug-ins can use these functions to access the known issues database.

Public helper routine name is L"Database". To use these private helper routine, you should invoke KxGetHelperTable function. See ka3arch.doc for more details.

 

6.2.3.1       DbInitialize

BOOL

DbInitialize(

            VOID

);

 

Parameters:

None.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.2       DbCleanup

BOOL

DbCleanup(

            VOID

            );

 

Parameters:

None.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.3       DbOpenConnection

BOOL

DbOpenConnection(

            IN LPCWSTR Connect,

            IN LPCWSTR UID,

            IN LPCWSTR Password

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.4       DbCloseConnection

BOOL

DbCloseConnection(

            VOID

            );

 

Parameters:

None.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.5         DbStartTransaction

BOOL

DbStartTransaction(

            VOID

            );

 

Parameters:

None.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.6         DbRollBackTransaction

BOOL

DbRollBackTransaction(

            VOID

            );

 

Parameters:

None.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.7         DbCommitTransaction

BOOL

DbCommitTransaction(

            VOID

            );

 

Parameters:

None.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.8         DbGetCrashClass

BOOL

DbGetCrashClass(

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK CallBack,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.9         DbAddCrashClass

BOOL

DbAddCrashClass(

IN PKANALYZE_CRASH_CLASS_DATA CrashClass,

            OUT PLONG32 ClassID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

);

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.10      DbUpdateCrashClass

BOOL

DbUpdateCrashClass(

IN UINT64 UpdateFlags,

IN LONG32 ClassID,

IN PKADB_CRASH_CLASS CrashClass,

IN PVOID Reserved,

IN UINT_PTR Reserved2

);

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.11      DbGetHWProfile

BOOL

DbGetHWProfile(

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.12      DbGetOSProfile

BOOL

DbGetOSProfile(

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.13      DbAddHWProfile

BOOL

DbAddHWProfile(

            IN PKADB_HW_PROFILE HWProfile,

            OUT PLONG32 HWProfileRecID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.14      DbAddOSProfile

BOOL

DbAddOSProfile(

            IN PKADB_OS_PROFILE OSProfile

            OUT PLONG32 OSProfileRecID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.15      DbUpdateHWProfileOccuranceCount

BOOL

DbUpdateHWProfileOccuranceCount(

            IN LONG32 HWProfileRecID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.16      DbUpdateOSProfileOccuranceCount

BOOL

DbUpdateOSProfileOccuranceCount(

            IN LONG32 OSProfileRecID,

IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.17   DbGetCrashInstance

BOOL

DbGetCrashInstance(

        IN LONG32 CrashID,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK CallBack,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.18   DbAddCrashInstance

BOOL

DbAddCrashInstance(

IN PKANALYZE_CRASH_INSTANCE_DATA CrashInstance,

IN PKADB_CRASH_INSTANCE CrashInstance,

            OUT PLONG32 InstanceID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

);

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.19      DbGetKernelModuleData

BOOL

DbGetKernelModuleData(

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParam,

            IN UINT_PTR Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.20      DbGetKanalyzeModuleData

BOOL

DbGetKanalyzeModuleData(

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.21      DbAddKernelModuleData

BOOL

DbAddKernelModuleData(

            IN PKADB_KERNEL_MODULE_DATA KernelModuleData,

            OUT PLONG32 KernelModuleID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.22      DbAddKanalyzeModuleData

BOOL

DbAddKanalyzeModuleData(

            IN PKADB_KANALYZE_MODULE_DATA KanalyzeModuleData

            OUT PLONG32 KanalyzeModuleID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.23   DbGetKernelModule

BOOL

DbGetKernelModule(

IN LONG32 ClassID,

IN LONG32 InstanceID,

IN LPCWSTR MatchString,

IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

);

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.24      DbAddKernelModule

BOOL

DbAddKernelModule(

            IN LONG32 ClassID,

            IN LONG32 InstanceID,

IN LONG32 KernelModuleID,

            IN PKADB_KERNEL_MODULE KernelModule,     

IN PVOID Reserved,

IN UINT_PTR Reserved2

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.25   DbGetKanalyzeModule

BOOL

DbGetKanalyzeModule(

IN LONG32 ClassID,

IN LONG32 InstanceID,

IN LPCWSTR MatchString,

IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

);

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.26      DbAddKanalyzeModule

BOOL

DbAddKanalyzeModule(

            IN LONG32 KanalyzeModuleID,

            IN LONG32 ClassID,

IN LONG32 InstanceID,

IN PVOID Reserved,

IN UINT_PTR Reserved2

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.27   DbGetAttachmentmentData

BOOL

DbGetAttachmentData(

            IN LONG32 ClassID,

            IN LONG32 InstanceID,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK CallBack,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.28      DbAddAttachmentData

BOOL

DbAddAttachementData(

            IN LONG32  ClassID,

            IN LONG32  InstanceID,

            IN PKADB_ATTACHMENT_DATA AttachmentData,

            OUT PLONG32  ItemID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.29   DbGetVariableCrashData

BOOL

DbGetVariableCrashData(

            IN LONG32 ClassID,

            IN LONG32 InstanceID,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK CallBack,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.30      DbAddVariableCrashData

BOOL

DbAddVariableCrashData(

            IN LONG32  ClassID,

            IN LONG32  InstanceID,

            IN PKADB_VARIABLE_CRASH_DATA VariableCrashData,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.31      DbGetSolution

BOOL

DbGetSolution(

            IN LONG32 SolutionID,

            IN LPCWSTR MatchString,

        IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.32   DbAddSolution

BOOL

DbAddSolution(

IN PKADB_SOLUTION Solution,

OUT PLONG32 SolutionID,

IN PVOID Reserved,

IN UINT_PTR Reserved2

);

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.33   DbUpdateSolution

BOOL

DbUpdateSolution(

IN UINT64 UpdateFlags

IN LONG32 SolutionID,

IN PKADB_SOLUTION Solution

IN PVOID Reserved,

IN UINT_PTR Reserved2

);

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.34      DbGetHintData

BOOL

DbGetHintData(

            IN LONG32  SolutionID,

            IN LPCWSTR MatchString,

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.35      DbGetAnalysisBy

BOOL

DbGetAnalysis(

            IN LONG32    AnalysisID,

            IN LPCWSTR MatchString,

        IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.36   DbAddAnalysis

BOOL

DbAddAnalysis(

            IN PKADB_ANALYSIS AnalysisData

            OUT PLONG32 AnalysisID,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.37      DbUpdateAnalysis

BOOL

DbUpdateAnalysis(

            IN UINT64 UpdateFlags

            IN LONG32   AnalysisID,

            IN PKADB_ANALYSIS AnalysisData,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.38      DbAddProgressText

BOOL

DbAddProgressText(

            IN LONG32  AnalysisID,

            IN PKADB_PROGRESS_TEXT ProgressText,

        OUT PLONG32 ProgressTextID,

            IN PVOID CallBackParm,

            IN UINT_PTR Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.39      DbGetProgressText

BOOL

DbGetProgressText(

            IN LONG32 AnalysisID,                    

            IN PKADB_ENUM_DATA_CALLBACK Callback,

            IN PVOID Reserved,

            IN UINT_PTR Reserved2

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.40      DbGetCrashClassCrashInstance

BOOL

DbGetCrashClassCrashInstance(

IN  LPCWSTR     MatchString,

IN  PKADB_ENUM_DATA_CALLBACK Callback,

IN  PVOID       CallBackParm,

IN  UINT_PTR    Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

 

6.2.3.41      DbGetProcessorTypeProcessorVendor

BOOL

DbGetProcessorTypeProcessorVendor(

IN  LPCWSTR     MatchString,

IN  PKADB_ENUM_DATA_CALLBACK Callback,

IN  PVOID       CallBackParm,

IN  UINT_PTR    Reserved

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

To get extended error function, call GetLastError() before DbGetLastError().

 

6.2.3.42      DbBuildHWProfileMatchString

LPWSTR

DbBuildHWProfileMatchString(

            IN PKADB_HWPROFILE HWProfile

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

KaDbBuildHWProfileMatchString is not implemented in kadbprov.dll, so this function will always return with FALSE.

 

6.2.3.43      DbBuildOSProfileMatchStr

LPWSTR

DbBuildOSProfileMatchStr(

            IN PKADB_OSPROFILE OSProfile

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

KaDbBuildOSProfileMatchString is not implemented in kadbprov.dll, so this function will always return with FALSE.

 

6.2.3.44      DbBuildKernelModuleDataMatchStr

LPWSTR

DbBuildKernelModuleDataMatchStr(

            PKADB_KERNEL_MODULE_DATA KernelModuleData

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

KaDbBuildKernelModuleDataMatchString is not implemented in kadbprov.dll, so this function will always return with FALSE.

 

6.2.3.45      DbBuildKanalyzeModuleDataMatchStr

LPWSTR

DbBuildKanalyzeModuleDataMatchStr(

            PKADB_KANALYZE_MODULE_DATA KanayzeModuleData

            );

 

Parameters:

See ka3db.doc.

 

Return Value:

KaDbBuildKanalyzeModuleDataMatchString is not implemented in kadbprov.dll, so this function will always return with FALSE.

 

6.2.3.46   DbGetLastError

BOOL

DbGetLastError(

            IN PKADB_ENUM_DATA_CALLBACK Callback

            );

 

Parameters:

Callback – specify the callback routine. If this is NULL, database plug-in will use internal callback routine. The internal callback routine will log an error message.

 

Return Value:

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

 

 

6.2.4    Useful macros

The database plug-in provides some useful macros to convert the value between the sigid file known issues database.

Note that in all functions, the buffer allocation is callers role.

 

6.2.4.1       KADB_GET_PLATFORM_A

VOID

KADB_GET_PLATFORM_A(

    IN LPCSTR _name,

    OUT DWORD _type

    );

 

Routine Description:

    This routine is used to convert platform name to platform type.

 

Arguments:

    _name - specify the platform name in LPCSTR.

    _type - return the platform type in DWORD.

 

Return Value:

    None.

 

6.2.4.2       KADB_GET_PLATFORM_W

VOID

KADB_GET_PLATFORM_W(

    IN LPCWSTR _name,

    OUT DWORD _type

    );

 

Routine Description:

    This routine is used to convert platform name to platform type.

 

Arguments:

    _name - specify the platform name in LPCWSTR.

    _type - return the platform type in DWORD.

 

Return Value:

    None.

 

6.2.4.3       KADB_SET_PLATFORM_A

VOID

KADB_SET_PLATFORM_A(

    IN DWORD _type,

    OUT LPSTR _name

    );

 

Routine Description:

    This routine is used to convert platform type to platform name.

 

Arguments:

    _type - specify the platform type in DWORD.

    _name - return the platform name in LPSTR.

 

Return Value:

    None.

 

6.2.4.4       KADB_SET_PLATFORM_W

VOID

KADB_SET_PLATFORM_W(

    IN DWORD _type,

    OUT LPWSTR _name

    );

 

Routine Description:

    This routine is used to convert platform type to platform name.

 

Arguments:

    _type - specify the platform type in DWORD.

    _name - return the platform name in LPWSTR.

 

Return Value:

    None.

 

6.2.4.5       KADB_GET_OS_TYPE_A

VOID

KADB_GET_OS_TYPE_A(

    IN LPCSTR _name,

    OUT DWORD _type

    );

 

Routine Description:

    This routine is used to convert os product name to os product type.

 

Arguments:

    _name - specify the os product name in LPCSTR.

    _type - return the os product type in DWORD.

 

Return Value:

    None.

 

6.2.4.6       KADB_GET_OS_TYPE_W

VOID

KADB_GET_OS_TYPE_W(

    IN LPCWSTR _name,

    OUT DWORD _type

    );

 

Routine Description:

    This routine is used to convert os product name to os product type.

 

Arguments:

    _name - specify the os product name in LPCWSTR.

    _type - return the os product type in DWORD.

 

Return Value:

    None.

 

6.2.4.7       KADB_SET_OS_TYPE_A

VOID

KADB_SET_OS_TYPE_A(

    IN DWORD _type,

    OUT LPSTR _name

    );

 

Routine Description:

    This routine is used to convert os product type to os product name.

 

Arguments:

    _type - specify the os product type in DWORD.

    _name - return the os product name in LPSTR.

 

Return Value:

    None.

 

6.2.4.8       KADB_SET_OS_TYPE_W

VOID

KADB_SET_OS_TYPE_W(

    IN DWORD _type,

    OUT LPWSTR _name

    );

 

Routine Description:

    This routine is used to convert os product type to os product name.

 

Arguments:

    _type - specify the os product type in DWORD.

    _name - return the os product name in LPWSTR.

 

Return Value:

    None.

 

6.2.4.9       KADB_GET_KANALYZE_TYPE_A

VOID

KADB_GET_KANALYZE_TYPE_A(

    IN LPCSTR _name,

    OUT DWORD _type

    );

 

Routine Description:

    This routine is used to convert kanalyze type name to kanalyze type.

 

Arguments:

    _name - specify the kanalyze type name in LPCSTR.

    _type - return the kanalyze type in DWORD.

 

Return Value:

    None.

 

6.2.4.10   KADB_GET_KANALYZE_TYPE_W

VOID

KADB_GET_KANALYZE_TYPE_W(

    IN LPCWSTR _name,

    OUT DWORD _type

    );

 

Routine Description:

    This routine is used to convert kanalyze type name to kanalyze type.

 

Arguments:

    _name - specify the kanalyze type name in LPCWSTR.

    _type - return the platform type in DWORD.

 

Return Value:

    None.

 

6.2.4.11   KADB_SET_KANALYZE_TYPE_A

VOID

KADB_SET_KANALYZE_TYPE_A(

    IN DWORD _type,

    OUT LPSTR _name

    );

 

Routine Description:

    This routine is used to convert kanalyze type to kanalyze type name.

 

Arguments:

    _type - specify the kanalyze type in DWORD.

    _name - return the kanalyze type name in LPSTR.

 

Return Value:

    None.

 

6.2.4.12   KADB_SET_KANALYZE_TYPE_W

VOID

KADB_SET_KANALYZE_TYPE_W(

    IN DWORD _type,

    OUT LPWSTR _name

    );

 

Routine Description:

    This routine is used to convert kanalyze type to kanalyze type name.

 

Arguments:

    _type - specify the kanalyze type in DWORD.

    _name - return the kanalyze type name in LPWSTR.

 

Return Value:

    None.

 

6.2.4.13   KADB_SET_PROCESSOR_TYPE_A

VOID

KADB_SET_PROCESSOR_TYPE_A(

    IN HKAPLUGIN _hp,

    IN USHORT _vendor,

    IN USHORT _family,

    IN USHORT _model,

    IN USHORT _step,

    OUT LPSTR _type

    );

 

Routine Description:

    This routine is used to convert processor vendor/family/model/step to processor name.

 

Arguments:

    _hp - specify the caller's plug-in handle.

    _vendor - specify the processor vendor

    _family - specify the processor type

    _model - specify the processor model

    _step - specify the processor spec, if this is -1, then ignored.

    _type - return the processor type in LPSTR. Caller should alloc/free this buffer.

 

Return Value:

    None.

 

6.2.4.14   KADB_SET_PROCESSOR_TYPE_W

VOID

KADB_SET_PROCESSOR_TYPE_W(

    IN HKAPLUGIN _hp,

    IN USHORT _vendor,

    IN USHORT _family,

    IN USHORT _model,

    IN USHORT _step,

    OUT LPWSTR _type

    );

 

Routine Description:

    This routine is used to convert processor vendor/family/model/step to processor name.

 

Arguments:

    _hp - specify the caller's plug-in handle.

    _vendor - specify the processor vendor

    _family - specify the processor type

    _model - specify the processor model

    _step - specify the processor spec, if this is -1, then ignored.

    _type - return the processor type in LPWSTR. Caller should alloc/free this buffer.

 

Return Value:

    None.

 

6.2.4.15   KADB_GET_PROCESSOR_TYPE_A

VOID

KADB_GET_PROCESSOR_TYPE_A(

    IN HKAPLUGIN _hp,

    IN LPCSTR _type,

    OUT USHORT _family

    );

 

Routine Description:

    This routine is used to convert processor name to processor family.

 

Arguments:

    _hp - specify the caller's plug-in handle.

    _type - specify the processor name in LPCSTR.

    _family - return the processor family in DWORD.

 

Return Value:

    None.

 

6.2.4.16   KADB_GET_PROCESSOR_TYPE_W

VOID

KADB_GET_PROCESSOR_TYPE_A(

    IN HKAPLUGIN _hp,

    IN LPCWSTR _type,

    OUT DWORD _family

    );

 

Routine Description:

    This routine is used to convert processor name to processor family.

 

Arguments:

    _hp - specify the caller's plug-in handle.

    _type - specify the processor name in LPCWSTR.

    _family - return the processor family in DWORD.

 

Return Value:

    None.

 

6.2.4.17   KADB_SET_PROCESSOR_VENDOR_A

VOID

KADB_SET_PROCESSOR_VENDOR_A(

    IN HKAPLUGIN _hp,

    IN DWORD _id,

    OUT LPSTR _name

    );

 

Routine Description:

    This routine is used to convert processor vendor type to processor vendor name.

 

Arguments:

    _hp - specify the caller's plug-in handle.

    _id - specify the processor vendor type in DWORD.

    _name - return the processor vendor name in LPSTR. Caller should alloc/free this buffer.

 

Return Value:

    None.

 

6.2.4.18   KADB_SET_PROCESSOR_VENDOR_W

VOID

KADB_SET_PROCESSOR_VENDOR_A(

    IN HKAPLUGIN _hp,

    IN DWORD _id,

    OUT LPWSTR _name

    );

 

Routine Description:

    This routine is used to convert processor vendor type to processor vendor name.

 

Arguments:

    _hp - specify the caller's plug-in handle.

    _id - specify the processor vendor type in DWORD.

    _name - return the processor vendor name in LPWSTR. Caller should alloc/free this buffer.

 

Return Value:

    None.

 

6.2.4.19   KADB_GET_PROCESSOR_VENDOR_A

VOID

KADB_GET_PROCESSOR_VENDOR_A(

    IN HKAPLUGIN _hp,

    IN LPCSTR _name,

    OUT DWORD _id

    );

 

Routine Description:

    This routine is used to convert processor vendor name to processor vendor type.

 

Arguments:

    _hp - specify the caller's plug-in handle.

    _name - specify the processor vendor name in LPCSTR.

    _id - return the processor vendor id in DWORD.

 

Return Value:

    None.

 

6.2.4.20   KADB_GET_PROCESSOR_VENDOR_W

VOID

KADB_GET_PROCESSOR_VENDOR_W(

    IN HKAPLUGIN _hp,

    IN LPCWSTR _name,

    OUT DWORD _id

    );

 

Routine Description:

    This routine is used to convert processor vendor name to processor vendor type.

 

Arguments:

    _hp - specify the caller's plug-in handle.

    _name - specify the processor vendor name in LPCWSTR.

    _id - return the processor vendor id in DWORD.

 

Return Value:

    None.

 

 

Appendix A: Interpreting The Database Design Diagram

The database is designed with ERwin version 3.5.  This appendix is intended for people who are not familiar with database design or IDEF1X notation.

 

Key Selection


When choosing the primary key for an entity, a surrogate key which is an arbitrary number is assigned to an instance to uniquely identify it within an entity. “Employee-number” is an example of a surrogate key. A surrogate key is often the best choice for a primary key because it is short, can be accessed the fastest, and ensures unique identification of each instance. Further, a surrogate key can be automatically generated by the system so that numbering is sequential and does not include gaps.

 

Candidate keys not selected as primary keys can be designated as alternate keys, and recorded as such in the model. Alternate keys are often used to show different indexes the application will use to access the data. Sometimes attributes that are not unique, but are routinely used to look up information for the entity also need to be tracked. These attributes are called inversion entries.

 

Relationships

 

Whenever entities in a ERwin diagram are connected by a relationship (a solid or dotted line), the relationship contributes a key (or set of key attributes) to the child entity. These attributes are called the foreign keys (FK). The contributed keys are said to migrate from parent to child.

 

In relational terms, a child entity that depends on the foreign key attribute for uniqueness is called a dependent entity.

 

If you want the foreign key to migrate to the key area of the child entity (and create a dependent

entity as a result), you can create an identifying relationship between the parent and child entities. Identifying relationships are indicated by a solid line connecting the entities. The line includes a solid dot on the end nearest to the child entity.

 

Non-identifying relationship are used to show a different migration of the foreign key attribute(s), that is, migration to the data area of the child entity (below the line). Non-identifying relationships are indicated by a dashed line connecting the entities.

 

Because the migrated keys in a non-identifying relationship are not part of the primary key of the child, non-identifying relationships do not result in any identification dependency.

 

When a relationship is optional, the diagram includes a diamond opposite that of the dot.

Cardinality

 

Cardinality is the relational property that defines exactly how many instances appear in a child table for each corresponding instance in the parent table. Symbols associated with the relationship lines (discussed above) are used to denote one or more, zero or more, zero or one, or exactly N, as explained in the following table.

 

One to zero, one, or more

No symbol used. Straight solid dot on Child entity.

One, zero, or more

The symbol P is found next to the solid dot.

Zero or one to zero or one

The symbol Z is found next to the solid dot.

 



[1] For now match only on Architecture, ProcessorType and ProcessorCount. In future we can add ProcessorVendor and Processor Spec.

[2] I am not sure we need to worry about QFE data at this point in time. Let’s leave it in the database for now but not match on it.