sp_cursorprepare (Transact-SQL)

Aplica-se: SQL Server

Compila a instrução ou lote do cursor em um plano de execução, mas não cria o cursor. A instrução compilada pode ser usada posteriormente pelo sp_cursorexecute. Este procedimento, juntamente com sp_cursorexecute, tem a mesma função que sp_cursoropen, mas é dividido em duas fases. sp_cursorprepare é invocado especificando ID = 3 em um pacote TDS (fluxo de dados tabulares).

Convenções de sintaxe de Transact-SQL

Sintaxe

sp_cursorprepare prepared_handle OUTPUT , params , stmt , options
    [ , scrollopt [ , ccopt ] ]
[ ; ]

Argumentos

prepared_handle

Um identificador preparado handle gerado pelo SQL Server que retorna um valor int .

prepared_handle é então fornecido a um sp_cursorexecute procedimento para abrir um cursor. Depois que um identificador é criado, ele existe até que você saia ou até que você o remova explicitamente por meio de um sp_cursorunprepare procedimento.

params

Identifica instruções parametrizadas. A definição de parâmetros de variáveis é substituída por marcadores de parâmetro na instrução. params é um parâmetro necessário que chama um valor de entrada ntext, nchar ou nvarchar . Insira um NULL valor se a instrução não estiver parametrizada.

Use uma cadeia de caracteres ntext como o valor de entrada quando stmt estiver parametrizado e o valor de PARAMETERIZED_STMT scrollopt estiver ON.

stmt

Define o conjunto de resultados do cursor. O parâmetro stmt é necessário e chama um valor de entrada ntext, **ncar ou nvarchar .

As regras para especificar o valor stmt são as mesmas sp_cursoropenque , com a exceção de que o tipo de dados de cadeia de caracteres stmt deve ser ntext.

options

Retorna uma descrição das colunas do conjunto de resultados do cursor. O parâmetro options é int, com um padrão de NULL. Quando definido como 0x0001, significa RETURN_METADATA.

scrollopt

Opção de rolagem. O parâmetro scrollopt é um parâmetro opcional que requer um dos seguintes valores de entrada int .

Valor Descrição
0x0001 KEYSET
0x0002 DYNAMIC
0x0004 FORWARD_ONLY
0x0008 STATIC
0x10 FAST_FORWARD
0x1000 PARAMETERIZED_STMT
0x2000 AUTO_FETCH
0x4000 AUTO_CLOSE
0x8000 CHECK_ACCEPTED_TYPES
0x10000 KEYSET_ACCEPTABLE
0x20000 DYNAMIC_ACCEPTABLE
0x40000 FORWARD_ONLY_ACCEPTABLE
0x80000 STATIC_ACCEPTABLE
0x100000 FAST_FORWARD_ACCEPTABLE

Como o valor solicitado pode não ser apropriado para o cursor definido por stmt, esse parâmetro serve como entrada e saída. Nesses casos, o SQL Server atribui um valor apropriado.

CCOPT

Opção de controle de simultaneidade. ccopt é um parâmetro opcional que requer um dos seguintes valores de entrada int .

Valor Descrição
0x0001 READ_ONLY
0x0002 SCROLL_LOCKS (anteriormente conhecido como LOCKCC)
0x0004 OPTIMISTIC (anteriormente conhecido como OPTCC)
0x0008 OPTIMISTIC (anteriormente conhecido como OPTCCVAL)
0x2000 ALLOW_DIRECT
0x4000 UPDT_IN_PLACE
0x8000 CHECK_ACCEPTED_OPTS
0x10000 READ_ONLY_ACCEPTABLE
0x20000 SCROLL_LOCKS_ACCEPTABLE
0x40000 OPTIMISTIC_ACCEPTABLE
0x80000 OPTIMISTIC_ACCEPTABLE

Assim como acontece com scrollpt, o SQL Server pode atribuir um valor diferente do solicitado.

Comentários

O parâmetro de status RPC é um dos seguintes valores:

Valor Descrição
0 Êxito
0x0001 Falha
1FF6 Não foi possível retornar metadados.

Observação: a razão para isso é que a instrução não produz um conjunto de resultados; por exemplo, é uma INSERT instrução ou DDL.

Exemplos

O código a seguir é um exemplo de uso sp_cursorprepare e sp_cursorexecute:

DECLARE @handle INT, @p5 INT, @p6 INT;

EXEC sp_cursorprepare @handle OUTPUT,
    N'@dbid int',
    N'select * from sys.databases where database_id < @dbid',
    1,
    @p5 OUTPUT,
    @p6 OUTPUT;

DECLARE @p1 INT
SET @P1 = @handle;

DECLARE @p2 INT;
DECLARE @p3 INT;
DECLARE @p4 INT;

SET @P6 = 4;

EXEC sp_cursorexecute @p1,
    @p2 OUTPUT,
    @p3 OUTPUT,
    @p4 OUTPUT,
    @p5 OUTPUT,
    @p6;

EXEC sp_cursorfetch @P2;
EXEC sp_cursorunprepare @handle;
EXEC sp_cursorclose @p2;

Quando stmt é parametrizado e o valor scrollopt PARAMETERIZED_STMT é ON, o formato da string está no seguinte formato:

<parameter_name> <data_type> [ ,... n ]