Level 1 subroutine
Retrieve statistics about a table and its indexes.
call EDSStatistics(HSTMT_IV, TABLE_STRUCT, UNIQUE_IV, ACCURACY_IV, MAXROWS_IV, NUMROWS_IV, ARRAY_STRUCT)
•HSTMT_IV An input integer value that indicates the statement handle for retrieving results.
•TABLE_STRUCT An input EDSTABLE_STRUCT structure containing table information.
•UNIQUE_IV An input integer value indicating the type of index: EDS_INDEX_UNIQUE or EDS_INDEX_ALL.
•ACCURACY_IV An input integer value indicating the importance of the CARDINALITY and PAGES columns in the result set:
•EDS_ENSURE requests that the driver unconditionally retrieve the statistics. EDS_QUICK requests that the driver retrieve results only if they are readily available from the server. In this case, the driver does not ensure that the values are current.
•MAXROWS_IV An input integer value indicating the maximum number of rows in the result array.
•NUMROWS_IV An output integer value indicating the actual number of rows in the result array.
•ARRAY_STRUCT An output array of EDSSPCOLS_STRUCT structures that contain the indexes and statistics associated with the specified table.
Description
EDSStatistics returns a list of the indexes associated with a single table. Results are returned as an array of EDSSTAT_STRUCT structures ordered by NONUNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME, AND SEQ_IN_INDEX. The result array combines statistics information for the table with information about each index.
If MAXROWS_IV = NUMROWS_IV, then there were more rows of data to fetch than there were structures in the array. To retrieve the full set of results, the user must RESIZE the array and call the function again.
If the row in the result set corresponds to a table, the driver sets TYPE to 0 and sets NON_UNIQUE, INDEX_QUALIFIER, INDEX_NAME, SEQ_IN_INDEX, COLUMN_NAME, and COLLATION to NULL. If CARDINALITY or PAGES are not available from the data source, the driver sets them to NULL.
The following table lists the elements returned in each structure.
Column Name |
Data Type |
Comments |
TABLE_QUALIFIER |
string |
Table qualifier identifier of the table to which the statistic or index applies; NULL if not applicable to the data source. |
TABLE_OWNER |
string |
Table owner identifier of the table to which the statistic or index applies; NULL if not applicable to the data source. |
TABLE_NAME |
string |
Table identifier of the table to which the statistic or index applies. |
NON_UNIQUE |
integer not NULL |
Indicates whether the index prohibits duplicate values: EDS_TRUE if the index values can be non--unique. EDS_FALSE if the index values must be unique. NULL is returned if TYPE is EDS_TABLE_STAT. |
INDEX_QUALIFIER |
string |
The identifier that is used to qualify the index name doing a DROP INDEX; NULL is returned if an index qualifier is not supported by the data source or if TYPE is EDS_TABLE_STAT. If a non-null value is returned in this column, it must be used to qualify the index name on a DROP INDEX statement; otherwise the TABLE_OWNER name should be used to qualify the index name. |
INDEX_NAME |
string |
Index identifier; NULL is returned if TYPE is EDS_TABLE_STAT. |
TYPE |
integer not NULL |
Type of information being returned: EDS_TABLE_STAT indicates a statistic for the table. EDS_INDEX_CLUSTERED indicates a clustered index. EDS_INDEX_HASHED indicates a hashed index. EDS_INDEX_OTHER indicates another type of index. |
SEQ_IN_INDEX |
integer |
Column sequence number in index (starting with 1); NULL is returned if TYPE is EDS_TABLE_STAT. |
COLUMN_NAME |
string |
Column identifier. NULL is returned if TYPE is EDS_TABLE_STAT. |
COLLATION |
string |
Sort sequence for the column: “A” for ascending, “D” for descending. NULL is returned if column sort sequence is not supported by the data source or if TYPE is EDS_TABLE_STAT. |
CARDINALITY |
string |
Cardinality of table or index: number of rows in table if TYPE is EDS_TABLE_STAT, number of unique values in the index if TYPE is not EDS_TABLE_STAT. NULL is returned if the value is not available from the data source. |
PAGES |
integer |
Number of pages used to store the index or table: number of pages for the table if TYPE is EDS_TABLE_STAT, number of pages for the index if TYPE is not EDS_TABLE_STAT. NULL is returned if the value is not available from the data source, or if not applicable to the data source. If MAXROWS_IV=NUMROWS_IV, then there were more rows of data to fetch than there were structures in the array. To retrieve the full set of results, the user must RESIZE the array and call the function again. |
Return Value
EDSStatistics returns EDS_SUCCESS, EDS_ERROR, or EDS_INVALID_HANDLE.
When EDSStatistics returns EDS_ERROR, you can obtain an associated SQLSTATE value with more specific information by calling EDSError. The following table lists each typical SQLSTATE value and explains each one in the context of the command EDSStatistics.
The following table lists possible SQLSTATE values:
SQL STATE |
Error |
Description |
08S01 |
Communication link failure |
The communication link between the driver and the data source to which the driver was connected failed before the function completed processing |
24000 |
Invalid cursor state |
Results were pending on the statement handle from a previous SELECT statement or a cursor associated with the statement handle had not been closed. |
IM001 |
Driver does not support this function |
The driver associated with the statement handle does not support the function. |
S1000 |
General error |
An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by EDSError in the argument ERRORTEXT describes the error and its cause. |
S1001 |
Memory allocation failure |
The driver was unable to allocate the memory required to support execution or completion of the function. |
S1008 |
Operation cancelled |
Asynchronous processing was enabled for the statement handle. The function was called and before it completed execution, EDSCancel was called on the statement handle. Then the function was called again on the statement handle. |
S1010 |
Function sequence error |
An asynchronously executing function (not this one) was called for the statement handle and was still executing when this function was called. |
S1100 |
Uniqueness option type out of range |
An invalid UNIQUE_IV value was specified. |
S1101 |
Accuracy option type |
An invalid ACCURACY_IV value was out of range specified. |
S1C00 |
Driver not capable |
A table qualifier or a table owner was specified and the driver or data source does not support one or both of the qualifiers. |
S1T00 |
Timeout expired |
The timeout period expired before the data source returned the requested result set. The timeout period is set through EDSSetStmtOption, EDS_QUERY_TIMEOUT. |
See Also
EDSPrimaryKeys returns the list of columns that make up a primary key.
EDSForeignKeys returns the list of columns that make up a foreign key.
