DECLARE CURSOR (Transact-SQL)DECLARE CURSOR (Transact-SQL)

APLICA-SE A: simSQL Server simBanco de Dados SQL do Azure nãoAzure Synapse Analytics (SQL DW) nãoParallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database noAzure Synapse Analytics (SQL DW) noParallel Data Warehouse

Define os atributos de um cursor de servidor Transact-SQLTransact-SQL, como seu comportamento de rolagem e a consulta usada para construir o conjunto de resultados no qual o cursor funciona.Defines the attributes of a Transact-SQLTransact-SQL server cursor, such as its scrolling behavior and the query used to build the result set on which the cursor operates. DECLARE CURSOR aceita uma sintaxe fundada no padrão ISO e uma sintaxe que usa um conjunto de extensões Transact-SQLTransact-SQL.DECLARE CURSOR accepts both a syntax based on the ISO standard and a syntax using a set of Transact-SQLTransact-SQL extensions.

Ícone de link do tópico Convenções de sintaxe de Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxeSyntax

ISO Syntax  
DECLARE cursor_name [ INSENSITIVE ] [ SCROLL ] CURSOR   
     FOR select_statement   
     [ FOR { READ ONLY | UPDATE [ OF column_name [ ,...n ] ] } ]  
[;]  
Transact-SQL Extended Syntax  
DECLARE cursor_name CURSOR [ LOCAL | GLOBAL ]   
     [ FORWARD_ONLY | SCROLL ]   
     [ STATIC | KEYSET | DYNAMIC | FAST_FORWARD ]   
     [ READ_ONLY | SCROLL_LOCKS | OPTIMISTIC ]   
     [ TYPE_WARNING ]   
     FOR select_statement   
     [ FOR UPDATE [ OF column_name [ ,...n ] ] ]  
[;]  

ArgumentosArguments

cursor_namecursor_name
É o nome do cursor de servidor do Transact-SQLTransact-SQL definido.Is the name of the Transact-SQLTransact-SQL server cursor defined. cursor_name deve estar em conformidade com as regras de identificadores.cursor_name must conform to the rules for identifiers.

INSENSITIVEINSENSITIVE
Define um cursor que faz uma cópia temporária dos dados a serem usados por ele.Defines a cursor that makes a temporary copy of the data to be used by the cursor. Todas as solicitações para o cursor são respondidas nessa tabela temporária em tempdb; portanto, as modificações feitas na tabelas base não são refletidas nos dados retornados pelas buscas feitas nesse cursor, que não permite modificações.All requests to the cursor are answered from this temporary table in tempdb; therefore, modifications made to base tables are not reflected in the data returned by fetches made to this cursor, and this cursor does not allow modifications. Quando a sintaxe de ISO é usada, se INSENSITIVE for omitido, exclusões e atualizações confirmadas nestas tabelas subjacentes (por qualquer usuário) serão refletidas em buscas subsequentes.When ISO syntax is used, if INSENSITIVE is omitted, committed deletes and updates made to the underlying tables (by any user) are reflected in subsequent fetches.

SCROLLSCROLL
Especifica que todas as opções de busca (FIRST, LAST, PRIOR, NEXT, RELATIVE, ABSOLUTE) estão disponíveis.Specifies that all fetch options (FIRST, LAST, PRIOR, NEXT, RELATIVE, ABSOLUTE) are available. Se SCROLL não for especificado em um ISO DECLARE CURSOR, NEXT será a única opção de busca compatível.If SCROLL is not specified in an ISO DECLARE CURSOR, NEXT is the only fetch option supported. Não será possível especificar SCROLL se FAST_FORWARD também estiver especificado.SCROLL cannot be specified if FAST_FORWARD is also specified. Se SCROLL não for especificado, apenas a opção de busca NEXT estará disponível e o cursor passará a ser FORWARD_ONLY.If SCROLL is not specified then only the fetch option NEXT is available and the cursor becomes FORWARD_ONLY.

select_statementselect_statement
É uma instrução SELECT padrão que define o conjunto de resultados de um cursor.Is a standard SELECT statement that defines the result set of the cursor. As palavras-chave FOR BROWSE e INTO não são permitidas na select_statement de uma declaração de cursor.The keywords FOR BROWSE, and INTO are not allowed within select_statement of a cursor declaration.

O SQL ServerSQL Server converte o cursor implicitamente em outro tipo se as cláusulas em select_statement entram em conflito com a funcionalidade do tipo de cursor solicitado.SQL ServerSQL Server implicitly converts the cursor to another type if clauses in select_statement conflict with the functionality of the requested cursor type.

READ ONLYREAD ONLY
Previne atualizações feitas por este cursor.Prevents updates made through this cursor. O cursor não pode ser referenciado em uma cláusula WHERE CURRENT OF em um instrução UPDATE ou DELETE.The cursor cannot be referenced in a WHERE CURRENT OF clause in an UPDATE or DELETE statement. Essa opção anula a funcionalidade padrão de um cursor para ser atualizado.This option overrides the default capability of a cursor to be updated.

UPDATE [OF column_name [ , ...n]]UPDATE [OF column_name [,...n]]
Define colunas atualizáveis em um cursor.Defines updatable columns within the cursor. Se OF <column_name> [, <... n>] for especificada, somente as colunas listadas permitirão modificações.If OF <column_name> [, <... n>] is specified, only the columns listed allow modifications. Se UPDATE for especificada sem uma lista de colunas, todas as colunas poderão ser atualizadas.If UPDATE is specified without a column list, all columns can be updated.

cursor_namecursor_name
É o nome do cursor de servidor do Transact-SQLTransact-SQL definido.Is the name of the Transact-SQLTransact-SQL server cursor defined. cursor_name deve estar em conformidade com as regras de identificadores.cursor_name must conform to the rules for identifiers.

LOCALLOCAL
Especifica que o escopo do cursor é local para o lote, procedimento armazenado ou gatilho no qual o cursor foi criado.Specifies that the scope of the cursor is local to the batch, stored procedure, or trigger in which the cursor was created. O nome de cursor só é válido dentro desse escopo.The cursor name is only valid within this scope. O cursor pode ser referenciado por meio de variáveis de cursor local no lote, no procedimento armazenado ou no gatilho ou em um parâmetro OUTPUT do procedimento armazenado.The cursor can be referenced by local cursor variables in the batch, stored procedure, or trigger, or a stored procedure OUTPUT parameter. Um parâmetro OUTPUT é usado para repassar o cursor local para o lote de chamada, o procedimento armazenado ou o gatilho, que pode atribuir o parâmetro a uma variável do cursor para fazer referência ao cursor após o procedimento armazenado terminar.An OUTPUT parameter is used to pass the local cursor back to the calling batch, stored procedure, or trigger, which can assign the parameter to a cursor variable to reference the cursor after the stored procedure terminates. O cursor é implicitamente desalocado quando o lote, o procedimento armazenado ou o gatilho é encerrado, a menos que o cursor tenha sido repassado como um parâmetro OUTPUT.The cursor is implicitly deallocated when the batch, stored procedure, or trigger terminates, unless the cursor was passed back in an OUTPUT parameter. Se for repassado em um parâmetro OUTPUT, o cursor será desalocado quando a última variável que faz referência a ele for desalocada ou extrapolar o escopo.If it is passed back in an OUTPUT parameter, the cursor is deallocated when the last variable referencing it is deallocated or goes out of scope.

GLOBALGLOBAL
Especifica que o escopo do cursor é global para a conexão.Specifies that the scope of the cursor is global to the connection. O nome do cursor pode ser referenciado em qualquer procedimento armazenado ou lote executado pela conexão.The cursor name can be referenced in any stored procedure or batch executed by the connection. O cursor só é desalocado implicitamente na desconexão.The cursor is only implicitly deallocated at disconnect.

Observação

Se nem GLOBAL nem LOCAL forem especificados, o padrão será controlado pela definição da opção padronizar para cursor local do banco de dados.If neither GLOBAL or LOCAL is specified, the default is controlled by the setting of the default to local cursor database option.

FORWARD_ONLYFORWARD_ONLY
Especifica se o cursor só pode se mover para frente e ser rolado da primeira à última linha.Specifies that the cursor can only move forward and be scrolled from the first to the last row. FETCH NEXT é a única opção de busca compatível.FETCH NEXT is the only supported fetch option. Todas as instruções insert, update e delete feitas pelo usuário atual ou confirmadas por outros usuários que afetam as linhas no conjunto de resultados são visíveis como as linhas buscadas.All insert, update, and delete statements made by the current user (or committed by other users) that affect rows in the result set are visible as the rows are fetched. Porém, como o cursor não podem ser revertido, as alterações feitas nas linhas no banco de dados depois que a linha foi buscada não são visíveis pelo cursor.Because the cursor cannot be scrolled backward, however, changes made to rows in the database after the row was fetched are not visible through the cursor. Cursores somente de avanço são dinâmicos por padrão, o que significa que todas as alterações são detectadas conforme a linha atual é processada.Forward-only cursors are dynamic by default, meaning that all changes are detected as the current row is processed. Isso permite uma abertura do cursor mais rápida e que o conjunto de resultados exiba as atualizações feitas nas tabelas subjacentes.This provides faster cursor opening and enables the result set to display updates made to the underlying tables. Embora os cursores somente de avanço não sejam compatíveis com rolagem para trás, os aplicativos podem retornar ao início do conjunto de resultados fechando e reabrindo o cursor.While forward-only cursors do not support backward scrolling, applications can return to the beginning of the result set by closing and reopening the cursor. Se FORWARD_ONLY for especificado sem as palavras-chave STATIC, KEYSET ou DYNAMIC, o cursor operará como um cursor dinâmico.If FORWARD_ONLY is specified without the STATIC, KEYSET, or DYNAMIC keywords, the cursor operates as a dynamic cursor. Quando nem FORWARD_ONLY nem SCROLL é especificado, FORWARD_ONLY é o padrão, a menos que as palavras-chave STATIC, KEYSET ou DYNAMIC sejam especificadas.When neither FORWARD_ONLY nor SCROLL is specified, FORWARD_ONLY is the default, unless the keywords STATIC, KEYSET, or DYNAMIC are specified. Os cursores STATIC, KEYSET e DYNAMIC utilizam SCROLL como padrão.STATIC, KEYSET, and DYNAMIC cursors default to SCROLL. Ao contrário de APIs de banco de dados, como ODBC e ADO, FORWARD_ONLY dá suporte aos cursores STATIC, KEYSET e DYNAMIC Transact-SQLTransact-SQL.Unlike database APIs such as ODBC and ADO, FORWARD_ONLY is supported with STATIC, KEYSET, and DYNAMIC Transact-SQLTransact-SQL cursors.

STATICSTATIC
Especifica que o cursor sempre exibe o conjunto de resultados como ele era quando o cursor foi aberto pela primeira vez e faz uma cópia temporária dos dados a serem usados pelo cursor.Specifies that the cursor always displays the result set as it was when the cursor was first opened, and makes a temporary copy of the data to be used by the cursor. Todas as solicitações para o cursor são respondidas dessa tabela temporária em tempdb.All requests to the cursor are answered from this temporary table in tempdb. Portanto, inserções, atualizações e exclusões feitas na tabelas base não são refletidas nos dados retornados pelas buscas feitas nesse cursor e esse cursor não detecta as alterações feitas à associação, à ordem ou aos valores do conjunto de resultados depois que o cursor é aberto.Therefore inserts, updates, and deletes made to base tables are not reflected in the data returned by fetches made to this cursor, and this cursor does not detect changes made to the membership, order, or values of the result set after the cursor is opened. Cursores estáticos podem detectar as próprias atualizações, exclusões e inserções, embora não precisem fazer isso.Static cursors may detect their own updates, deletes, and inserts, although they are not required to do so. Por exemplo, suponha que um cursor estático busque uma linha e outro aplicativo então atualize a linha.For example, suppose a static cursor fetches a row, and another application then updates that row. Se o aplicativo buscar novamente a linha do cursor estático, os valores que ele verá estarão inalterados, apesar das alterações feitas por outro aplicativo.If the application refetches the row from the static cursor, the values it sees are unchanged, despite the changes made by the other application. Há suporte para todos os tipos de rolagem.All types of scrolling are supported.

KEYSETKEYSET
Especifica que a associação e a ordem de linhas no cursor são fixas, quando o cursor é aberto.Specifies that the membership and order of rows in the cursor are fixed when the cursor is opened. O conjunto de chaves que identificam exclusivamente as linhas é construído em uma tabela no tempdb, conhecido como keyset.The set of keys that uniquely identify the rows is built into a table in tempdb known as the keyset. Esse cursor fornece funcionalidades entre um cursor dinâmico e um cursor estático em sua capacidade de detectar alterações.This cursor provides functionality between a static and a dynamic cursor in its ability to detect changes. Como um cursor estático, ele nem sempre detecta alterações à associação e à ordem do conjunto de resultados.Like a static cursor, it does not always detect changes to the membership and order of the result set. Como um cursor dinâmico, ele detecta alterações aos valores de linhas no conjunto de resultados.Like a dynamic cursor, it does detect changes to the values of rows in the result set. Os cursores controlados por conjuntos de chaves são controlados por um conjunto exclusivo de identificadores (chaves) conhecido como conjunto de chaves.Keyset-driven cursors are controlled by a set of unique identifiers (keys) known as the keyset. As chaves são criadas a partir de um conjunto de colunas, que identificam exclusivamente as linhas no conjunto de resultados.The keys are built from a set of columns that uniquely identify the rows in the result set. O conjunto de chaves é o conjunto de valores de chave de todas as linhas retornadas pela instrução de consulta.The keyset is the set of key values from all the rows returned by the query statement. Com cursores controlados por conjunto de chaves, uma chave é criada e salva para cada linha do cursor e armazenada na estação de trabalho cliente ou no servidor.With keyset-driven cursors, a key is built and saved for each row in the cursor and stored either on the client workstation or on the server. Quando você acessa cada linha, a chave armazenada é usada para buscar os valores de dados atual da fonte de dados.When you access each row, the stored key is used to fetch the current data values from the data source. Em um cursor controlado por conjunto de chaves, a associação do conjunto de resultados é congelada quando o conjunto de chaves está completamente preenchido.In a keyset-driven cursor, result set membership is frozen when the keyset is fully populated. Depois disso, adições ou atualizações que afetem a associação não farão parte do resultado definido até que ele seja reaberto.Thereafter, additions or updates that affect membership are not a part of the result set until it is reopened. Alterações nos valores de dados (feitas por outros processos ou pelo proprietário do conjunto de chaves) são visíveis conforme o usuário rola pelo conjunto de resultados:Changes to data values (made either by the keyset owner or other processes) are visible as the user scrolls through the result set:

  • Se uma linha for excluída, uma tentativa de buscar a linha retornará um @@FETCH_STATUS de -2 porque a linha excluída aparecerá como uma lacuna no conjunto de resultados.If a row is deleted, an attempt to fetch the row returns an @@FETCH_STATUS of -2 because the deleted row appears as a gap in the result set. A chave para a linha existe no conjunto de chaves, mas a linha não existe mais no conjunto de resultados.The key for the row exists in the keyset, but the row no longer exists in the result set.
  • Inserções feitas fora do cursor (por outros processos) serão visíveis apenas se o cursor for fechado e reaberto.Inserts made outside the cursor (by other processes) are visible only if the cursor is closed and reopened. Inserções feitas de dentro do cursor são visíveis no final do conjunto de resultados.Inserts made from inside the cursor are visible at the end of the result set.
  • Atualização de valores de chave externos ao cursor lembram a exclusão de uma linha antiga, seguida de uma inserção de uma nova linha.Updates of key values from outside the cursor resemble a delete of the old row followed by an insert of the new row. A linha com os novos valores não é visível e as tentativas de buscar a linha com os valores antigos retornam um @@FETCH_STATUS igual a -2.The row with the new values is not visible, and attempts to fetch the row with the old values return an @@FETCH_STATUS of -2. Os novos valores ficarão visíveis se a atualização for feita por meio do cursor especificando a cláusula WHERE CURRENT OF.The new values are visible if the update is done through the cursor by specifying the WHERE CURRENT OF clause.

Observação

Se a consulta referencia ao menos uma tabela sem um índice exclusivo, o cursor controlado por conjunto de chaves é convertido a um cursor estático.If the query references at least one table without a unique index, the keyset cursor is converted to a static cursor.

DYNAMICDYNAMIC
Define um cursor que reflete todas as alterações de dados feitas às linhas em seu conjunto de resultados conforme você rola o cursor e busque um novo registro, não importa se as alterações ocorrem de dentro do cursor ou são feitas por outros usuários fora do cursor.Defines a cursor that reflects all data changes made to the rows in its result set as you scroll around the cursor and fetch a new record, regardless of whether the changes occur from inside the cursor or by other users outside the cursor. Portanto, todas as instruções insert, update e delete feitas por todos os usuários são visíveis por meio do cursor.Therefore all insert, update, and delete statements made by all users are visible through the cursor. Os valores de dados, a ordem e a associação das linhas podem ser alterados em cada busca.The data values, order, and membership of the rows can change on each fetch. Não há suporte para a opção de buscar ABSOLUTE com cursores dinâmicos.The ABSOLUTE fetch option is not supported with dynamic cursors. As atualizações feitas fora do cursor não são visíveis até serem confirmadas (a menos que o nível de isolamento da transação do cursor esteja definido como UNCOMMITTED).Updates made outside the cursor are not visible until they are committed (unless the cursor transaction isolation level is set to UNCOMMITTED). Por exemplo, suponha que um cursor dinâmico busque duas linhas e outro aplicativo então atualize uma dessas linhas e exclua a outra.For example, suppose a dynamic cursor fetches two rows and another application then updates one of those rows and deletes the other. Se o cursor dinâmico então buscar essas linhas, ele não localizará a linha excluída, mas exibirá os novos valores para a linha atualizada.If the dynamic cursor then fetches those rows, it will not find the deleted row, but it will display the new values for the updated row.

FAST_FORWARDFAST_FORWARD
Especifica um cursor FORWARD_ONLY, READ_ONLY com otimizações de desempenho habilitadas.Specifies a FORWARD_ONLY, READ_ONLY cursor with performance optimizations enabled. Não será possível especificar FAST_FORWARD se SCROLL ou FOR_UPDATE também estiver especificado.FAST_FORWARD cannot be specified if SCROLL or FOR_UPDATE is also specified. Esse tipo de cursor não permite modificações de dados de dentro do cursor.This type of cursor does not allow data modifications from inside the cursor.

Observação

FAST_FORWARD e FORWARD_ONLY podem ser usados na mesma instrução DECLARE CURSOR.Both FAST_FORWARD and FORWARD_ONLY can be used in the same DECLARE CURSOR statement.

READ_ONLYREAD_ONLY
Previne atualizações feitas por este cursor.Prevents updates made through this cursor. O cursor não pode ser referenciado em uma cláusula WHERE CURRENT OF em um instrução UPDATE ou DELETE.The cursor cannot be referenced in a WHERE CURRENT OF clause in an UPDATE or DELETE statement. Essa opção anula a funcionalidade padrão de um cursor para ser atualizado.This option overrides the default capability of a cursor to be updated.

SCROLL_LOCKSSCROLL_LOCKS
Especifica se atualizações posicionadas ou exclusões feitas pelo cursor têm garantia de êxito.Specifies that positioned updates or deletes made through the cursor are guaranteed to succeed. O SQL ServerSQL Server bloqueia as linhas à medida que são lidas no cursor para assegurar a disponibilidade para modificações posteriores.SQL ServerSQL Server locks the rows as they are read into the cursor to ensure their availability for later modifications. Não será possível especificar SCROLL_LOCKS se FAST_FORWARD ou STATIC também estiver especificado.SCROLL_LOCKS cannot be specified if FAST_FORWARD or STATIC is also specified.

OPTIMISTICOPTIMISTIC
Especifica que as atualizações posicionadas e exclusões realizadas pelo cursor não terão êxito se a linha tiver sido atualizada desde que foi lida no cursor.Specifies that positioned updates or deletes made through the cursor do not succeed if the row has been updated since it was read into the cursor. SQL ServerSQL Server não bloqueia linhas à medida que são lidas no cursor.does not lock rows as they are read into the cursor. Em vez disso, ele usa comparações de valores de coluna timestamp ou um valor de soma de verificação se a tabela não tem nenhuma coluna timestamp, para determinar se a linha foi modificada depois de ser lida no cursor.It instead uses comparisons of timestamp column values, or a checksum value if the table has no timestamp column, to determine whether the row was modified after it was read into the cursor. Se a linha tiver sido modificada, a tentativa de atualização ou exclusão posicionada falhará.If the row was modified, the attempted positioned update or delete fails. Não será possível especificar OPTIMISTIC se FAST_FORWARD também estiver especificado.OPTIMISTIC cannot be specified if FAST_FORWARD is also specified.

TYPE_WARNINGTYPE_WARNING
Especifica que uma mensagem de aviso é enviada ao cliente quando o cursor é convertido implicitamente em outro a partir do tipo solicitado.Specifies that a warning message is sent to the client when the cursor is implicitly converted from the requested type to another.

select_statementselect_statement
É uma instrução SELECT padrão que define o conjunto de resultados de um cursor.Is a standard SELECT statement that defines the result set of the cursor. As palavras-chave COMPUTE, COMPUTE BY, FOR BROWSE e INTO não são permitidas na select_statement de uma declaração de cursor.The keywords COMPUTE, COMPUTE BY, FOR BROWSE, and INTO are not allowed within select_statement of a cursor declaration.

Observação

Você pode usar uma dica de consulta dentro de uma declaração de cursor, porém, se você também usar a cláusula FOR UPDATE OF, especifique OPTION (<query_hint>) após de FOR UPDATE OF.You can use a query hint within a cursor declaration; however, if you also use the FOR UPDATE OF clause, specify OPTION (<query_hint>) after FOR UPDATE OF.

O SQL ServerSQL Server converte o cursor implicitamente em outro tipo se as cláusulas em select_statement entram em conflito com a funcionalidade do tipo de cursor solicitado.SQL ServerSQL Server implicitly converts the cursor to another type if clauses in select_statement conflict with the functionality of the requested cursor type. Para obter mais informações, consulte Conversões implícitas de cursorFor more information, see Implicit Cursor Conversions.

FOR UPDATE [OF column_name [ , ...n]]FOR UPDATE [OF column_name [,...n]]
Define colunas atualizáveis em um cursor.Defines updatable columns within the cursor. Se OF <column_name> [, <... n>] for fornecido, somente as colunas listadas permitirão modificações.If OF <column_name> [, <... n>] is supplied, only the columns listed allow modifications. Se UPDATE for especificado sem uma lista de colunas, todas as colunas poderão ser atualizadas, a não ser que a opção de simultaneidade READ_ONLY seja especificada.If UPDATE is specified without a column list, all columns can be updated, unless the READ_ONLY concurrency option was specified.

RemarksRemarks

DECLARE CURSOR define os atributos de um cursor de servidor Transact-SQLTransact-SQL, como seu comportamento de rolagem e a consulta usada para criar o conjunto de resultados no qual o cursor funciona.DECLARE CURSOR defines the attributes of a Transact-SQLTransact-SQL server cursor, such as its scrolling behavior and the query used to build the result set on which the cursor operates. A instrução OPEN popula o conjunto de resultados e FETCH retorna uma linha do conjunto de resultados.The OPEN statement populates the result set, and FETCH returns a row from the result set. A instrução CLOSE libera o conjunto de resultados atual associado ao cursor.The CLOSE statement releases the current result set associated with the cursor. A instrução DEALLOCATE libera os recursos usados pelo cursor.The DEALLOCATE statement releases the resources used by the cursor.

O primeiro formulário da instrução DECLARE CURSOR usa a sintaxe ISO para declarar comportamentos do cursor.The first form of the DECLARE CURSOR statement uses the ISO syntax for declaring cursor behaviors. O segundo formulário do DECLARE CURSOR usa extensões Transact-SQLTransact-SQL que lhe permitem definir cursores com os mesmos tipos de cursor usados nas funções do cursor de API do banco de dados de ODBC ou ADO.The second form of DECLARE CURSOR uses Transact-SQLTransact-SQL extensions that allow you to define cursors using the same cursor types used in the database API cursor functions of ODBC or ADO.

Você não pode misturar os dois formulários.You cannot mix the two forms. Se você especificar as palavras-chave SCROLL ou INSENSITIVE antes da palavra-chave CURSOR, não poderá usar nenhuma palavra-chave entre as palavras-chave CURSOR e FOR <select_statement>.If you specify the SCROLL or INSENSITIVE keywords before the CURSOR keyword, you cannot use any keywords between the CURSOR and FOR <select_statement> keywords. Se você especificar quaisquer palavras-chave entre CURSOR e FOR <select_statement>, não poderá especificar SCROLL ou INSENSITIVE antes da palavra-chave CURSOR.If you specify any keywords between the CURSOR and FOR <select_statement> keywords, you cannot specify SCROLL or INSENSITIVE before the CURSOR keyword.

Se um DECLARE CURSOR usando a sintaxe Transact-SQLTransact-SQL não especifica READ_ONLY, OPTIMISTIC ou SCROLL_LOCKS, o padrão é o seguinte:If a DECLARE CURSOR using Transact-SQLTransact-SQL syntax does not specify READ_ONLY, OPTIMISTIC, or SCROLL_LOCKS, the default is as follows:

  • Se a instrução SELECT não der suporte para atualizações (permissões insuficientes, acesso a tabelas remotas que não dão suporte a atualizações e assim por diante), o cursor será READ_ONLY.If the SELECT statement does not support updates (insufficient permissions, accessing remote tables that do not support updates, and so on), the cursor is READ_ONLY.

  • Os cursores STATIC e FAST_FORWARD utilizam READ_ONLY como padrão.STATIC and FAST_FORWARD cursors default to READ_ONLY.

  • Os cursores DYNAMIC e KEYSET utilizam OPTIMISTIC como padrão.DYNAMIC and KEYSET cursors default to OPTIMISTIC.

Nomes de cursor só podem ser referenciados através de outras instruções Transact-SQLTransact-SQL.Cursor names can be referenced only by other Transact-SQLTransact-SQL statements. Eles não podem ser referenciados através de funções da API do banco de dados.They cannot be referenced by database API functions. Por exemplo, depois de declarar um cursor, o nome de cursor não pode ser referenciado das funções ou métodos OLE DB, ODBC ou ADO.For example, after declaring a cursor, the cursor name cannot be referenced from OLE DB, ODBC or ADO functions or methods. As linhas de cursor não podem ser pesquisadas com as funções ou métodos de busca das APIs; as linhas só podem ser buscadas através de instruções FETCH Transact-SQLTransact-SQL.The cursor rows cannot be fetched using the fetch functions or methods of the APIs; the rows can be fetched only by Transact-SQLTransact-SQL FETCH statements.

Depois que um cursor ter sido declarado, esses procedimentos armazenados do sistema podem ser usados para determinar as características do cursor.After a cursor has been declared, these system stored procedures can be used to determine the characteristics of the cursor.

Procedimentos armazenados do sistemaSystem stored procedures DescriçãoDescription
sp_cursor_listsp_cursor_list Retorna uma lista de cursores atualmente visíveis na conexão e seus atributos.Returns a list of cursors currently visible on the connection and their attributes.
sp_describe_cursorsp_describe_cursor Descreve os atributos de um cursor, por exemplo, se ele é de somente avanço ou de rolagem.Describes the attributes of a cursor, such as whether it is a forward-only or scrolling cursor.
sp_describe_cursor_columnssp_describe_cursor_columns Descreve os atributos das colunas no conjunto de resultados do cursor.Describes the attributes of the columns in the cursor result set.
sp_describe_cursor_tablessp_describe_cursor_tables Descreve as tabelas base acessadas pelo cursor.Describes the base tables accessed by the cursor.

Variáveis podem ser usadas como parte da select_statement que declara um cursor.Variables may be used as part of the select_statement that declares a cursor. Valores de variáveis de cursor não se alteram depois que um cursor é declarado.Cursor variable values do not change after a cursor is declared.

PermissõesPermissions

Permissões de DECLARE CURSOR seguem o padrão para todo usuário que tem permissões SELECT para exibições, tabelas e colunas usadas no cursor.Permissions of DECLARE CURSOR default to any user that has SELECT permissions on the views, tables, and columns used in the cursor.

Limitações e RestriçõesLimitations and Restrictions

Não é possível usar cursores nem gatilhos em uma tabela com um índice columnstore clusterizado.You cannot use cursors or triggers on a table with a clustered columnstore index. Essa restrição não se aplica a índices columnstore não clusterizados. É possível usar cursores e gatilhos em uma tabela com um índice columnstore não clusterizado.This restriction does not apply to nonclustered columnstore indexes; you can use cursors and triggers on a table with a nonclustered columnstore index.

ExemplosExamples

A.A. Usando a sintaxe e o cursor simplesUsing simple cursor and syntax

O conjunto de resultados gerado na abertura deste cursor inclui todas as linhas e todas as colunas na tabela.The result set generated at the opening of this cursor includes all rows and all columns in the table. Este cursor pode ser atualizado e todas as atualizações e exclusões são representadas em buscas feitas no cursor.This cursor can be updated, and all updates and deletes are represented in fetches made against this cursor. FETCH NEXT é a única busca disponível porque a opção SCROLL não foi especificada.FETCH NEXT is the only fetch available because the SCROLL option has not been specified.

DECLARE vend_cursor CURSOR  
    FOR SELECT * FROM Purchasing.Vendor  
OPEN vend_cursor  
FETCH NEXT FROM vend_cursor;  

B.B. Usando cursores aninhados para produzir saída de relatórioUsing nested cursors to produce report output

O exemplo a seguir mostra como cursores podem ser aninhados para produzir relatórios complexos.The following example shows how cursors can be nested to produce complex reports. O cursor interno é declarado para cada vendedor.The inner cursor is declared for each vendor.

SET NOCOUNT ON;  
  
DECLARE @vendor_id int, @vendor_name nvarchar(50),  
    @message varchar(80), @product nvarchar(50);  
  
PRINT '-------- Vendor Products Report --------';  
  
DECLARE vendor_cursor CURSOR FOR   
SELECT VendorID, Name  
FROM Purchasing.Vendor  
WHERE PreferredVendorStatus = 1  
ORDER BY VendorID;  
  
OPEN vendor_cursor  
  
FETCH NEXT FROM vendor_cursor   
INTO @vendor_id, @vendor_name  
  
WHILE @@FETCH_STATUS = 0  
BEGIN  
    PRINT ' '  
    SELECT @message = '----- Products From Vendor: ' +   
        @vendor_name  
  
    PRINT @message  
  
    -- Declare an inner cursor based     
    -- on vendor_id from the outer cursor.  
  
    DECLARE product_cursor CURSOR FOR   
    SELECT v.Name  
    FROM Purchasing.ProductVendor pv, Production.Product v  
    WHERE pv.ProductID = v.ProductID AND  
    pv.VendorID = @vendor_id  -- Variable value from the outer cursor  
  
    OPEN product_cursor  
    FETCH NEXT FROM product_cursor INTO @product  
  
    IF @@FETCH_STATUS <> 0   
        PRINT '         <<None>>'       
  
    WHILE @@FETCH_STATUS = 0  
    BEGIN  
  
        SELECT @message = '         ' + @product  
        PRINT @message  
        FETCH NEXT FROM product_cursor INTO @product  
        END  
  
    CLOSE product_cursor  
    DEALLOCATE product_cursor  
        -- Get the next vendor.  
    FETCH NEXT FROM vendor_cursor   
    INTO @vendor_id, @vendor_name  
END   
CLOSE vendor_cursor;  
DEALLOCATE vendor_cursor;  

Consulte TambémSee Also

@@FETCH_STATUS (Transact-SQL) @@FETCH_STATUS (Transact-SQL)
CLOSE (Transact-SQL) CLOSE (Transact-SQL)
Cursores (Transact-SQL) Cursors (Transact-SQL)
DEALLOCATE (Transact-SQL) DEALLOCATE (Transact-SQL)
FETCH (Transact-SQL) FETCH (Transact-SQL)
SELECT (Transact-SQL) SELECT (Transact-SQL)
sp_configure (Transact-SQL)sp_configure (Transact-SQL)