SQL DESCRIBE QUERY Statement

< > Status Inquiry Statements Query Statements Example Flow Chart Table of Contents

The SQL DESCRIBE QUERY statement returns a group that describes an InstantSQL query.

QueryHandle (input). This argument must specify a numeric integer value with at least six digits of precision. The value identifies the query to be described. This value must have been returned from a successful SQL PREPARE QUERY statement or any of the browse statements.

QueryDescGroup (output). This argument must refer to a group data item that has the same data description as sql-Query-Description defined in the copy file lisqldef.cpy. The description of the query is stored in this group data item.

The data description entries for the elementary items of an sql-Query-Description group are provided in the copy file lisqldqy.cpy.

The meanings of the values returned in an sql-Query-Description group are as follows:

20 sql-QryType         PIC S9(04) LEADING.
88 sql-IsQTypeDataSources VALUE sql-QryDataSources.
88 sql-IsQTypeTables      VALUE sql-QryTables.
88 sql-IsQTypeColumns     VALUE sql-QryColumns.
88 sql-IsQTypeIndexes     VALUE sql-QryIndexes.
88 sql-IsQTypeTypes       VALUE sql-QryTypes.
88 sql-IsQTypeProcs       VALUE sql-QryProcs.
88 sql-IsQTypeProcColumns VALUE sql-QryProcColumns.
88 sql-IsQTypePrepared    VALUE sql-QryPrepared.

The value of sql-QryType indicates the type of the query. It identifies the statement that created the query.

20 sql-QryStatus       PIC S9(04) LEADING.
88 sql-IsQStatPrepared    VALUE sql-StatPrepared.
88 sql-IsQStatExecuting   VALUE sql-StatExecuting.
88 sql-IsQStatFetching    VALUE sql-StatFetching.
88 sql-IsQStatEndOfQuery VALUE sql-StatEndOfQuery.

The value of sql-QryStatus indicates the current status of the query. It identifies the last successfully executed statement on the query or, with the value sql-StatEndOfQuery, that all rows in the result set have been fetched.

20 sql-QryHstmt PIC S9(18) LEADING.

The value of sql-QryHstmt is the ODBC statement handle of the query. For a data-sources query, the statement handle is a NULL value (SQL_NULL_HSTMT = 0) and is not a valid statement handle for use in direct ODBC calls. For all other query types, the statement handle is not a NULL value and may be used in direct ODBC calls.

20 sql-QryDSHandle USAGE ISqlHandle.

The value of sql-QryDSHandle is the InstantSQL data source connection handle for the connection with which the query is associated. For a data-sources query, which is not associated with any connection, the value -1 is returned.

20 sql-QryNoCols PIC S9(04) LEADING.

The value of sql-QryNoCols is the number of columns in a row of the result set of the query. This is normally a fixed value for a query. For some drivers (for example, the Access 97 driver), the number of columns for a procedure invocation is zero after the query is prepared with the SQL PREPARE QUERY statement. When the query is executed for the first time with the SQL START QUERY statement, such drivers then report the number of columns in a row of the result set for the procedure, if any.

20 sql-QryNoParams PIC S9(04) LEADING.

The value of sql-QryNoParams is the number of parameter markers in the query.

20 sql-QryRowNo PIC S9(18) LEADING.

The value of sql-QryRowNo is the current row number of the query, that is, the number of rows fetched with SQL FETCH ROW statements since the last SQL START QUERY statement was executed for this query.

20 sql-QryRowCount PIC S9(18) LEADING.

The value of sql-QryRowCount indicates the number of rows affected by a DELETE, INSERT or UPDATE query. The value is set to -1 for other queries.

20 sql-QrySQLGroup.
24 sql-QrySQLLength PIC S9(04) LEADING.
24 sql-QrySQL PIC X(sql-StatementSize).

The value of sql-QrySQLGroup is a counted string that contains the SQL statement text string provided to the SQL PREPARE QUERY statement. If the query string is longer than sql-StatementSize (4096), the first 4096 characters of the SQL text string are returned and a data truncation error occurs. If truncation occurs, the value in sql-QrySQLLength will be the total length of the SQL statement text string before truncation.

For queries started with any of the browse statements, InstantSQL provides a text string that describes the query as follows:

Browse Query Statement	Query Description String
SQL QUERY COLUMNS	SQLColumns: TableName; CatalogName; SchemaName; ColumnName
SQL QUERY DATASOURCES	SQLDataSources
SQL QUERY INDEXES	SQLStatistics: TableName; CatalogName; SchemaName
SQL QUERY PROCEDURES	SQLProcedures: DataSourceName; CatalogName; SchemaName; ProcedureName
SQL QUERY PROCEDURE-COLUMNS	SQLProcedureColumns: ProcedureName; CatalogName; SchemaName; ColumnName
SQL QUERY TABLES	SQLTables: DataSourceName; CatalogName; SchemaName; TableName; TableType
SQL QUERY TYPES	SQLGetTypeInfo: DataSourceName; DataType

In those cases where the optional CatalogName, ColumnName, ProcedureName, SchemaName or TableName arguments are omitted or specified as OMITTED in the InstantSQL statement, the corresponding value in the above table is replaced by "~" with no leading space.

SQL DESCRIBE QUERY Statement Example:

           SQL DESCRIBE QUERY
               sql-QueryHandle,
               sql-Query-Description.