Kernel Memory Space
Analyzer — Known Issues Database (Phase 3)
Last Updated: 1/28/00
3.2 Variable Data and Attachment
Tables
3.3 Fixed Administrative Data Tables
3.4 Enforcing Table Integrity Using
Primary and Foreign Keys
4.1.3.1 Query Callback Function
4.3 Inserting Crash Instance Data
4.4 Adding Solutions and Hint Data
5.1.15 KaDbUpdateHWProfileOccurrenceCount
5.1.16 KaDbUpdateOSProfileOccurrenceCount
5.1.19 KaDbGetKernelModuleData
5.1.20 KaDbGetKanalyzeModuleData
5.1.21 KaDbAddKernelModuleData
5.1.22 KaDbAddKanalyzeModuleData
5.1.29 KaDbGetVariableCrashData
5.1.30 KaDbAddVariableCrashData
5.1.40 KaDbGetProcessorTypeProcessorVendor
5.2 Database Low-Level Access
Interface
6.1 Role of the Master Analysis
Plug-In
6.2.2.1 M_QUERY_GET_PREQUERY_MATCH_RESULT
6.2.2.2 M_QUERY_GET_MATCH_RESULT
6.2.3 Public helper/callback routines
6.2.3.15 DbUpdateHWProfileOccuranceCount
6.2.3.16 DbUpdateOSProfileOccuranceCount
6.2.3.19 DbGetKernelModuleData
6.2.3.20 DbGetKanalyzeModuleData
6.2.3.21 DbAddKernelModuleData
6.2.3.22 DbAddKanalyzeModuleData
6.2.3.27 DbGetAttachmentmentData
6.2.3.29 DbGetVariableCrashData
6.2.3.30 DbAddVariableCrashData
6.2.3.40 DbGetCrashClassCrashInstance
6.2.3.41 DbGetProcessorTypeProcessorVendor
6.2.3.42 DbBuildHWProfileMatchString
6.2.3.43 DbBuildOSProfileMatchStr
6.2.3.44 DbBuildKernelModuleDataMatchStr
6.2.3.45 DbBuildKanalyzeModuleDataMatchStr
6.2.4.9 KADB_GET_KANALYZE_TYPE_A
6.2.4.10 KADB_GET_KANALYZE_TYPE_W
6.2.4.11 KADB_SET_KANALYZE_TYPE_A
6.2.4.12 KADB_SET_KANALYZE_TYPE_W
6.2.4.13 KADB_SET_PROCESSOR_TYPE_A
6.2.4.14 KADB_SET_PROCESSOR_TYPE_W
6.2.4.15 KADB_GET_PROCESSOR_TYPE_A
6.2.4.16 KADB_GET_PROCESSOR_TYPE_W
6.2.4.17 KADB_SET_PROCESSOR_VENDOR_A
6.2.4.18 KADB_SET_PROCESSOR_VENDOR_W
6.2.4.19 KADB_GET_PROCESSOR_VENDOR_A
6.2.4.20 KADB_GET_PROCESSOR_VENDOR_W
Appendix A: Interpreting The
Database Design Diagram
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 Ý
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.
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.
This section deals with those tables that correspond to the fixed crash data and fixed kanalyze data portions of the kanalyze signature id file.
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 |
Index Index Index Index |
Not Null |
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 |
|
Null |
Varchar(256) |
|
InstanceCount |
|
Null |
Int |
|
FirstOccurrence |
|
Null |
SmallDateTime |
|
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 |
|
Not Null |
Varchar(16) |
|
KanalyzeMajorVersion |
|
Not Null |
SmallInt |
|
CrashTimeDate |
|
Null |
DateTime |
|
Field
Name |
Key
Attributes |
Null |
Data
Type |
Description |
ClassID |
Foreign Key |
Not Null |
Int |
|
InstanceID |
Foreign |
Not Null |
Int |
|
KernelModuleID |
Foreign Key |
Not Null |
Int |
|
LoadAddress |
|
Not Null |
VarChar(16) |
|
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 |
SmallInt |
Target OS
subsystem version, from the module image header. |
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. |
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. |
Field
Name |
Key
Attributes |
Null |
Data
Type |
Description |
ClassID |
Foreign Key |
Not Null |
Int |
Migrating
keys used to associate kanlayze with a specific crash class and instance |
KanalyzeModuleID |
Foreign Key |
Not Null |
Int |
|
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 |
|
Not Null |
SmallInt |
Indicates the version of the kanalyze module. |
Description |
|
Null |
NVarChar(256) |
Optional human-readable
description. |
This section deals with those tables that correspond to the attachments and variable data portions of the kanalyze signature id file.
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 |
Foreign Key |
Not Null |
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. |
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 |
Foreign Key |
Not Null |
Int |
Used as composite primary key with BlobName. |
BlobName |
Primary Key |
Not Null |
NVarChar(256) |
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. |
This section deals with the administrative tables of the known issues database. These tables are not derived from the signature file.
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.
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) |
|
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) |
|
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. |
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) |
|
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 |
|
Not Null |
varchar(256) |
TBD.
Contains connection data. |
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. |
Field
Name |
Key
Attributes |
Null |
Data
Type |
Description |
ClassID |
Foreign Key |
Not Null |
Int |
|
Customer |
|
Null |
NVarChar(100) |
|
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 |
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 |
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 |
|
|
This section articulates the rules for
inserting, updating and deleting records within the known issue database. It
also describes the general architectural considerations.
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.
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.
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.
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).
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.
CallBackParm—KaDbGetxxxx 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.
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.
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 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.
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.
Solutions and hint data are added to the known issues database either manually or through some other external application.
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.
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.
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.
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 |
|
Queries the
CrashClass table. |
|||
Updates a
CrashClass record. |
|||
|
Adds a new
CrashClass record. |
||
Queries the
Solution table. |
|||
Updates a
Solution record. |
|||
|
Adds a
solution to the database |
||
Queries Hint
data |
|||
KaDbUpdateHintData |
Future
release. |
||
KaDbAddHintData |
Future
release. |
||
Queries the
Analysis table. |
|||
Updates an
Analysis record. |
|||
Adds a new
Analysis record. |
|||
Queries the
ProgressText table. |
|||
Adds a new
ProgressText record. |
|||
|
Note: There
is no update function, as one never updates a ProgressText record. |
||
Queries the
CrashInstance table. |
|||
Adds a new
CrashInstance. |
|||
|
Note: There
is no update function, as one never updates a CrashInstance record. |
||
Queries
the KernelModule table |
|||
Adds a new
KernelModule record. |
|||
|
Note: There
is no update function, as one never updates a KernelModule record. |
||
Queries the
KernelModuleData table. |
|||
Adds a new
KerneloduleData record. |
|||
|
Note: There
is no update function, as one never updates a KernelModuleData record. |
||
Queries the
AttachmentData table. |
|||
Adds an
attachment record. |
|||
KaDbUpdateAttachmentData |
Future release. |
||
KaDbDeleteAttachmentData |
Future
release. |
||
Queries the
VariableCrashData table. |
|||
Adds a new
VariableCrashData record. |
|||
|
Note: There
is no update function, as one never updates a VariableCrashData record. |
||
Queries
the KanalyzeModule table |
|||
Adds a new
KanalyzeModule record. |
|||
|
Note: There
is no update function, as one never updates a KanalyzeModule record. |
||
Queries the
KanalyzeModule Data table. |
|||
Adds a new
KanalyzeModuleData record. |
|||
|
Note: There
is no update function, as one never updates a KanalyzeModuleData record. |
||
Queries the
HWProfile table. |
|||
Adds a new
HWProfile record. |
|||
Updates the
occurrence count associated with a HWProfile record. (Only field that can de
updated in HWProfile). |
|||
Queries the
OSProfile table. |
|||
Adds a new
OSProfile record. |
|||
Updates the
occurrence count associated with a OSProfile record. (Only field that can de
updated in OSProfile). |
|||
??? |
Future
release |
||
KaDbGetStopCodeDesc |
Future
release. |
||
??? |
Future
release. |
||
Queries the
ProcessorType Table |
|||
Acesses
ProcessorVendor Table through joined query with ProcessorType Table. |
|||
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
CrashClass—Points 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.
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.
ClassID—Identifies the CrashClass record to
be updated.
Reserved—Reserved for future use.
Reserved2—Reserved for future use.
Return
Value:
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.
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.
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
UINT_PTR Reserved
);
BOOL
KaDBGetOSProfile(
IN HANDLE DbConnection,
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.
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.
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,
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.
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.
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
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 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….
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.
CrashInstance—Points 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.
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).
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.
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.
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.
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 {
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.
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.
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.
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.
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;
} 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.
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.
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.
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.
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.
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.
Solution—Points 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.
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 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.
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.
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.
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).
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.
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.
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.
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,
);
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.
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.
This set of interfaces defines the low-level functions that wrap OLE DB. TBD.
TBD.
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)
The database plug-in process the hint data.
This section is deal with hint processing.
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.
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/*
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.
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
)
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
)
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.
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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().
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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. |