Share via

sp_describe_cursor_columns (Transact-SQL)

  • Article

Reports the attributes of the columns in the result set of a server cursor.

Topic link iconTransact-SQL Syntax Conventions

Syntax

sp_describe_cursor_columns 
   [ @cursor_return = ] output_cursor_variable OUTPUT 
    { [ , [ @cursor_source = ] N'local', 
          [ @cursor_identity = ] N'local_cursor_name' ] 
    | [ , [ @cursor_source = ] N'global', 
          [ @cursor_identity = ] N'global_cursor_name' ] 
    | [ , [ @cursor_source = ] N'variable', 
          [ @cursor_identity = ] N'input_cursor_variable' ] 
   }

Arguments

  • [ @cursor_return = ] output_cursor_variableOUTPUT
    Is the name of a declared cursor variable to receive the cursor output. output_cursor_variable is cursor, with no default, and must not be associated with any cursors at the time sp_describe_cursor_columns is called. The cursor returned is a scrollable, dynamic, read-only cursor.
  • [ @cursor_source = ] { N'local' | N'global' | N'variable' }
    Specifies whether the cursor being reported on is specified by using the name of a local cursor, a global cursor, or a cursor variable. The parameter is nvarchar(30).
  • [ @cursor_identity = ] N'local_cursor_name'
    Is the name of a cursor created by a DECLARE CURSOR statement that either has the LOCAL keyword or that defaulted to LOCAL. local_cursor_name is nvarchar(128).

  • [ @cursor_identity = ] N'global_cursor_name'
    Is the name of a cursor created by a DECLARE CURSOR statement that either has the GLOBAL keyword or that defaulted to GLOBAL. global_cursor_name is nvarchar(128).

    global_cursor_name can also be the name of an API server cursor that is opened by an ODBC application and then named by calling SQLSetCursorName.

  • [ @cursor_identity = ] N'input_cursor_variable'
    Is the name of a cursor variable associated with an open cursor. input_cursor_variable is nvarchar(128).

Return Code Values

None

Remarks

sp_describe_cursor_columns describes the attributes of the columns in the result set of a server cursor, such as the name and data type of each cursor. Use sp_describe_cursor for a description of the global attributes of the server cursor. Use sp_describe_cursor_tables for a report of the base tables referenced by the cursor. To obtain a report of the Transact-SQL server cursors visible on the connection, use sp_cursor_list.

Permissions

Requires membership in the public role.

Cursors Returned

sp_describe_cursor_columns encapsulates its report as a Transact-SQL cursor output parameter. This enables Transact-SQL batches, stored procedures, and triggers to work with the output one row at a time. This also means that the procedure cannot be called directly from database API functions. The cursor output parameter must be bound to a program variable, but the database APIs do not support binding cursor parameters or variables.

The following table shows the format of the cursor returned by using sp_describe_cursor_columns.

Column name Data type Description

column_name

sysname (nullable)

Name assigned to the result set column. The column is NULL if the column was specified without an accompanying AS clause.

ordinal_position

int

Relative position of the column from the leftmost column in the result set. The first column is in position 0.

column_characteristics_flags

int

A bitmask that indicates the information stored in DBCOLUMNFLAGS in OLE DB. Can be one or a combination of the following:

1 = Bookmark

2 = Fixed length

4 = Nullable

8 = Row versioning

16 = Updatable column (set for projected columns of a cursor that has no FOR UPDATE clause and, if there is such a column, can be only one per cursor).

When bit values are combined, the characteristics of the combined bit values apply. For example, if the bit value is 6, the column is a fixed-length (2), nullable (4) column.

column_size

int

Maximum possible size for a value in this column.

data_type_sql

smallint

Number that indicates the SQL Server data type of the column.

column_precision

tinyint

Maximum precision of the column as per the bPrecision value in OLE DB.

column_scale

tinyint

Number of digits to the right of the decimal point for the numeric or decimal data types as per the bScale value in OLE DB.

order_position

int

If the column participates in the ordering of the result set, the position of the column in the order key relative to the leftmost column.

order_direction

varchar(1)(nullable)

A = The column is in the order key and the ordering is ascending.

D = The column is in the order key and the ordering is descending.

NULL = The column does not participate in ordering.

hidden_column

smallint

0 = this column appears in the select list.

1 = Reserved for future use.

columnid

int

Column ID of the base column. If the result set column was built from an expression, columnid is -1.

objectid

int

Object ID of the object or base table that is supplying the column. If the result set column was built from an expression, objectid is -1.

dbid

int

ID of the database that contains the base table that is supplying the column. If the result set column was built from an expression, dbid is -1.

dbname

sysname

(nullable)

Name of the database that contains the base table that is supplying the column. If the result set column was built from an expression, dbname is NULL.

Examples

The following example opens a global cursor and uses sp_describe_cursor_columns to report on the columns used in the cursor.

USE AdventureWorks;
GO
-- Declare and open a global cursor.
DECLARE abc CURSOR KEYSET FOR
SELECT LastName
FROM Person.Contact
GO
OPEN abc

-- Declare a cursor variable to hold the cursor output variable
-- from sp_describe_cursor_columns.
DECLARE @Report CURSOR

-- Execute sp_describe_cursor_columns into the cursor variable.
EXEC master.dbo.sp_describe_cursor_columns
      @cursor_return = @Report OUTPUT,
      @cursor_source = N'global', @cursor_identity = N'abc'

-- Fetch all the rows from the sp_describe_cursor_columns output cursor.
FETCH NEXT from @Report
WHILE (@@FETCH_STATUS <> -1)
BEGIN
   FETCH NEXT from @Report
END

-- Close and deallocate the cursor from sp_describe_cursor_columns.
CLOSE @Report
DEALLOCATE @Report
GO
-- Close and deallocate the original cursor.
CLOSE abc
DEALLOCATE abc
GO

See Also

Reference

CURSOR_STATUS (Transact-SQL)
DECLARE CURSOR (Transact-SQL)
sp_describe_cursor (Transact-SQL)
sp_cursor_list (Transact-SQL)
sp_describe_cursor_tables (Transact-SQL)
System Stored Procedures (Transact-SQL)

Other Resources

Cursors (Database Engine)

Help and Information

Getting SQL Server 2005 Assistance