Distributed Tuning Interface Reference
The purpose of DTI is to provide an interface for configuring, monitoring, and diagnosing PSQL components. DTI provides the functionality of PSQL utilities from within your application.
This following topics cover the interface and its use:
Using the DTI Function Reference
For each function, the following information is provided:
•Brief description – provides a short description of the function.
•Syntax – shows the C prototype syntax for the function.
•Arguments – provides detailed descriptions of the function arguments, and indicates which values are modified by the function. Parameters marked “in” are input-only, not modified by the function. Parameters marked “out” contain values modified by the function. Parameters marked “in/out” contain values that are both used by the function as input and modified by the function.
•Return Values – lists the possible return values and their meanings.
•Remarks – provides additional explanation about a function’s parameters, effects, or usage.
•Example – provides a sample code segment showing the function’s use.
•See Also – lists related functions and topics.
DTI Functional Groups
The Distributed Tuning Interface is divided into functional groupings. For a summary of these groupings, please see the following table. The function descriptions begin in the following section in alphabetical order.
Table 2 DTI Function Groups
Function Group | Purpose | List of Functions |
Catalog catalog.h | Managing the database catalog information, such as creating, opening, copying, or closing named databases, and creating, modifying or deleting data source names (DSNs), | |
Configuration config.h | Controlling the configuration settings for the database engines, the communication managers, and the local requester components. | |
Connection connect.h | Starting and stopping a DTI session, connecting to a server, retrieving the name of the connected server, and disconnecting from a server. | |
Dictionary ddf.h | Creating and closing dictionaries (DDFs), and creating or deleting tables, indexes, users and groups. | |
License Administration dtilicense.h | Administering licensing such as authorizing or deauthorizing a key or retrieving information about keys. | |
Monitoring and Diagnostic monitor.h | Monitoring files, clients, and SQL connections, such as the following information for the MicroKernel Engine: Active Files—count and list open files, query if file is open, query user who opened/locked the file, obtain page size, read-only flag, record locks, transaction locks, number of handles, obtain handle information for each handle. Active Clients—count and list clients, query active handles, obtain client information, obtain handle information, disconnect a client and all client functionality. Resource Usage—retrieve current, peak, and maximum settings for data, including files, handles, clients, worker threads, licenses in use, transactions, locks. Communications Statistics—retrieve all communications statistics, total, delta, current, peak, maximum where appropriate, reset delta functionality. | |
Security dtisecurity.h | Enabling, disabling, or querying the status of security on databases. | |
DTI Error Messages
Refer to dticonst.h and ddfstrct.h for the defined status codes.
DTI Structures
The following describes the structures used in DTI. Each structure grouping details the type of structures included and any notable settings or arguments that may be required. Structures are stored in the following header files:
•CONFIG.H
•DDFSTRCT.H
•MONITOR.H
For detailed information specific to each structure, refer to the corresponding header file for that structure.
CONFIG.H Structures
The following lists the structures included in CONFIG.H. For detailed information about any of these structures, refer to the config header file.
•PVCATEGORYINFO
•PVSETTINGINFO
DDFSTRCT.H Structures
The following lists the structures included in DDFSTRCT.H. For detailed information about any of these structures, refer to the ddf header file.
•TABLEMAP
•TABLEINFO
•TABLEINFO Flags
B_FLAG_TRUE_NULLABLE = 64
Table is true nullable. When the table is created, a one byte null indicator is added before each column that is nullable.
•TABLESTAT
•TABLESTAT2
•COLUMNMAP
•COLUMNMAP Flags
B_FLAG_CASE_SENSITIVE = 1
Column values are case sensitive on comparisons and as part of index segments.
B_FLAG_NULLABLE = 4
If the table is created as true nullable, then a one byte null indicator column is added before the column value to indicate whether the column value is null.
B_FLAG_NTEXT = 2048
If a column is created as B_TYPE_BLOB, the data is treated as wide-character rather than character data.
B_FLAG_BINARY = 4096
If a column is created as B_TYPE_STRING or B_TYPE_BLOB, the data is treated as binary rather than character data.
•COLUMNMAP Data Types
COLUMNMAP DataType can take the following values:
B_TYPE_STRING = 0,
B_TYPE_INTEGER = 1,
B_TYPE_FLOAT = 2,
B_TYPE_DATE = 3,
B_TYPE_TIME = 4,
B_TYPE_DECIMAL = 5,
B_TYPE_MONEY = 6,
B_TYPE_LOGICAL = 7,
B_TYPE_NUMERIC = 8,
B_TYPE_BFLOAT = 9,
B_TYPE_LSTRING = 10,
B_TYPE_ZSTRING = 11,
B_TYPE_NOTE = 12,
B_TYPE_LVAR = 13,
B_TYPE_BINARY = 14,
B_TYPE_AUTOINC = 15,
B_TYPE_BIT = 16,
B_TYPE_NUMERSTS = 17,
B_TYPE_NUMERSA = 18,
B_TYPE_CURRENCY = 19,
B_TYPE_TIMESTAMP = 20,
B_TYPE_BLOB = 21,
B_TYPE_GDECIMAL = 22,
B_TYPE_WSTRING = 25,
B_TYPE_WZSTRING = 26,
B_TYPE_GUID = 27,
B_TYPE_DATETIME = 30
•INDEXMAP
•INDEXMAP Flags
B_FLAG_DUPLICATES = 1
Duplicates allowed in index.
B_FLAG_MODIFIABLE = 2
Index is modifiable.
B_FLAG_SORT_DESCENDING = 64
Sort index descending.
B_FLAG_PARTIAL = 512
Index is partial. Partial Index flags on segments that are not the last segment in the index, are ignored. Partial Indexes only apply to the last segment in an index.
Differences Between TABLESTAT2 and TABLESTAT
Note the following differences between the new TABLESTAT2 structure and the TABLESTAT structure:
•The fields for tableName and tableLocation allow more characters.
•The numberOfRecords field increased from 16 bits to 32 bits.
•File attribute fields were previously characters with values of “Y” or “N” to indicate whether the attribute is present or not. Attribute fields are now single byte integers with values of 1 or 0. A value of 1 means the attribute is present.
•The freespaceThreshold field is now an integer data type.
•The field fileVersion is no longer a float data type. It is now a single-byte integer that contains the same value that the Btrieve Stat (15) operation would return. For the 9.5 file format, the value returned is 0x95.
•A new field, pageCompression, indicates whether the physical file associated with the table has compressed pages or not.
•Previous fields dataCompression and systemDataKey have been renamed to recordCompression and systemData, respectively.
Backwards Compatibility
PSQL clients can still make PvGetTableStat calls to the database engine. The database engine converts the reply message to a TABLESTAT2 structure or to a TABLESTAT structure as required based on the version of the client.
A PSQL client determines the version of the database engine to which the client is connected. If the database engine version is prior to the current release, then PvGetTableStat2 returns a TABLESTAT structure and sets the value returned for pageCompression to 0.
MONITOR.H Structures
The following lists the structures included in MONITOR.H. For detailed information about any of these structures, refer to the monitor header file.
•PVDATETIME
•PVFILEINFO
•PVFILEHDLINFO
•PVCLIENTID
•PVMKDECLIENTINFO
•PVMKDECLIENTHDLINFO
•PVMKDEUSAGE
•PVMKDEUSAGEEX
•PVVERSION
•PVCOMMSTAT
•PVCOMMSTATEX
•PVCOMMPROTOCOLSTAT
•PVSQLCONNINFO
•PVSQLCONNID
DTI Calling Sequence
All Distributed Tuning Interface calls must initialize a DTI session by first calling PvStart().
status = PvStart(0);
status = PvStop(0);
The Remarks section of every function lists additional prerequisites and post requisites for that particular function.
DTI Function Definitions
This topic provides an alphabetical reference to the DTI functions.