sp_cursorfetch (Transact-SQL)

Aplica-se a:SQL Server

Busca um buffer de uma ou mais linhas no banco de dados. O grupo de linhas nesse buffer é chamado de buffer de busca do cursor. sp_cursorfetch é invocado especificando ID = 7 em um pacote TDS (fluxo de dados tabular).

Convenções de sintaxe de Transact-SQL

Sintaxe

  
sp_cursorfetch cursor  
    [ , fetchtype[ , rownum [ , nrows] ]]   

Argumentos

cursor
É um valor de identificador gerado por SQL Server e retornado por sp_cursoropen. cursor é um parâmetro obrigatório que exige um valor de entrada int . Para obter mais informações, consulte a seção Comentários, mais adiante neste tópico.

Fetchtype
Especifica o buffer de cursor a ser buscado. fetchtype é um parâmetro opcional que requer um dos seguintes valores de entrada inteiro.

Valor	Nome	Descrição
0x0001	FIRST	Busca o primeiro buffer de linhas nrows . Se nrows for igual a 0, o cursor será posicionado antes do conjunto de resultados e nenhuma linha será retornada.
0x0002	NEXT	Busca o próximo buffer de linhas nrows .
0x0004	PREV	Busca o buffer anterior de linhas nrows . Observação: o uso de PREV para um cursor FORWARD_ONLY retorna uma mensagem de erro porque FORWARD_ONLY só dá suporte à rolagem em uma direção.
0x0008	LAST	Busca o último buffer de linhas nrows . Se nrows for igual a 0, o cursor será posicionado após o conjunto de resultados e nenhuma linha será retornada. Observação: usar LAST para um cursor FORWARD_ONLY retorna uma mensagem de erro porque FORWARD_ONLY só dá suporte à rolagem em uma direção.
0x10	ABSOLUTE	Busca um buffer de linhas nrows começando com a linha rownum . Observação: usar ABSOLUTE para um cursor DYNAMIC ou um cursor FORWARD_ONLY retorna uma mensagem de erro porque FORWARD_ONLY só dá suporte à rolagem em uma direção.
0x20	RELATIVE	Busca o buffer de linhas nrows começando com a linha especificada como sendo o valor de número de linhas da primeira linha no bloco atual. Nesse caso , rownum pode ser um número negativo. Observação: o uso de RELATIVE para um cursor FORWARD_ONLY retorna uma mensagem de erro porque FORWARD_ONLY só dá suporte à rolagem em uma direção.
0x80	REFRESH	Torna a encher o buffer a partir de tabelas subjacentes.
0x100	INFO	Recupera informações sobre o cursor. Essas informações são retornadas usando os parâmetros rownum e nrows . Portanto, quando INFO é especificado, rownum e nrows se tornam parâmetros de saída.
0x200	PREV_NOADJUST	É usado como PREV. Porém, se a parte superior do conjunto de resultados for encontrada prematuramente, os resultados poderão variar.
0x400	SKIP_UPDT_CNCY	Deve ser usado com um dos outros valores fetchtype , exceto para INFO.

Observação

Não há suporte para o valor 0x40.

Para obter mais informações, consulte a seção Comentários, mais adiante neste tópico.

Rownum
É um parâmetro opcional que é usado para especificar a posição da linha para os valores de fetchtype ABSOLUTE e INFO usando apenas valores inteiros para entrada ou saída, ou ambos. rownum serve como o deslocamento de linha para o valor de bit fetchtype RELATIVE. rownum é ignorado para todos os outros valores. Para obter mais informações, consulte a seção Comentários, mais adiante neste tópico.

Nrows
É um parâmetro opcional usado para especificar o número de linhas a serem buscadas. Se nrows não for especificado, o valor padrão será 20 linhas. Para definir a posição sem retornar dados, especifique um valor igual a 0. Quando nrows é aplicado à consulta fetchtype INFO, ele retorna o número total de linhas nessa consulta.

Observação

nrows é ignorado pelo valor de bit fetchtype REFRESH.

Para obter mais informações, consulte a seção Comentários, mais adiante neste tópico.

Valores do código de retorno

Quando você especificar o valor de bit INFO, os valores que podem ser retornados são mostrados nas tabelas a seguir.

Observação

: se nenhuma linha for retornada, o conteúdo do buffer permanecerá como estavam.

<Rownum>	Definir como
Se não abrir	0
Se posicionado antes do conjunto de resultados	0
Se posicionado após o conjunto de resultados	-1
Para cursores KEYSET e STATIC	O número de linha absoluto da posição atual no conjunto de resultados
Para cursores DYNAMIC	1
Para ABSOLUTE	-1 retorna a última linha de um conjunto. -2 retorna da segunda à última linha de um conjunto, e assim por diante. Observação: se mais de uma linha for solicitada para ser buscada nesse caso, as duas últimas linhas do conjunto de resultados serão retornadas.

<Nrows>	Definir como
Se não abrir	0
Para cursores KEYSET e STATIC	Normalmente, o tamanho do conjunto de chaves atual. -m se o cursor estiver em criação assíncrona com linhas m encontradas até este ponto.
Para cursores DYNAMIC	-1

Comentários

Parâmetro cursor

Antes de haver qualquer operação de busca, a posição padrão de um cursor é antes da primeira linha do conjunto de resultados.

Parâmetro fetchtype

Exceto por SKIP_UPD_CNCY, os valores fetchtype são mutuamente exclusivos.

Quando SKIP_UPDT_CNCY é especificado, os valores da coluna de carimbo de data/hora não são gravados na tabela de conjuntos de chaves quando uma linha é buscada ou atualizada. Se a linha de conjunto de chaves estiver sendo atualizada, os valores das colunas de carimbo de data/hora permanecerão como o valor anterior. Se a linha de conjunto de linhas estiver sendo inserida, os valores das colunas de carimbo de data/hora serão indefinidos.

Para cursores KEYSET, isso significa que a tabela de conjuntos de chaves tem os valores definidos durante o último FETCH sem salto, caso um seja realizado. Caso contrário, terá os valores definidos durante a população.

Para cursores DYNAMIC, isso significa que se o salto for executado com uma atualização, gerará os mesmos resultados que KEYSET. Para qualquer outro tipo de busca, uma tabela de conjuntos de chaves truncada. Isso significa que as linhas estão sendo inseridas e os valores da(s) colunas de carimbo de data/hora são indefinidos. Portanto, quando você executar sp_cursorfetch para cursores DYNAMIC, evite usar SKIP_UPDT_CNCY para qualquer operação que não seja REFRESH.

Se uma operação de busca falhar porque a posição do cursor solicitado está além do conjunto de resultados, a posição do cursor será definida para logo após a última linha. Se uma operação de busca falhar porque a posição do cursor solicitado está antes do conjunto de resultados, a posição do cursor será definida para antes da primeira linha.

Parâmetro rownum

Quando você usa rownum, o buffer é preenchido começando com a linha especificada.

O valor fetchtype ABSOLUTE refere-se à posição de rownum dentro de todo o conjunto de resultados. Um número negativo com ABSOLUTE especifica que a operação conta linhas a partir do final do conjunto de resultados.

O valor fetchtype RELATIVE refere-se à posição de rownum em relação à posição do cursor no início do buffer atual. Um número negativo com RELATIVE especifica que o cursor retroceda a partir da posição atual.

Parâmetro nrows

Os valores fetchtype REFRESH e INFO ignoram esse parâmetro.

Quando você especifica um valor fetchtype de FIRST que tem um valor nrow de 0, o cursor é posicionado antes do conjunto de resultados que não tem linhas no buffer de busca.

Quando você especifica um valor fetchtype de LAST que tem um valor nrow de 0, o cursor é posicionado após o conjunto de resultados que não tem linhas no buffer de busca atual.

Para os valores fetchtype de NEXT, PREV, ABSOLUTE, RELATIVE e PREV_NOADJUST, um valor nrow de 0 não é válido.

Considerações sobre RPC:

O status de retorno RPC indica se o parâmetro de tamanho de conjunto de chaves é final ou não, ou seja, se a tabela de conjuntos de chaves ou temporária está sendo populada de forma assíncrona.

O parâmetro de status RPC é definido como um dos valores mostrados na tabela a seguir.

Valor	Descrição
0	Procedimento executado com êxito.
0x0001	Falha no procedimento.
0x0002	Uma busca em uma direção negativa fez com que a posição do cursor fosse definida no início do conjunto de resultados, quando a busca logicamente teria sido antes dos resultados.
0x10	Um cursor de avanço rápido foi fechado automaticamente.

As linhas são retornadas como um conjunto de resultados comum, ou seja, formato de coluna (0x2a), linhas (0xd1), seguidas de Done (0xfd). Tokens de metadados são enviados no mesmo formato que o especificado para sp_cursoropen, ou seja, 0x81, 0xa5 e 0xa4 para usuários do SQL Server 7.0, e assim por diante. Os indicadores de status de linha são enviados como colunas ocultas, semelhante ao modo BROWSE, ao final de cada linha com o nome de coluna rowstat e o tipo de dados INT4. Essa coluna rowstat tem um dos valores mostrados na tabela a seguir.

Valor	Descrição
0x0001	FETCH_SUCCEEDED
0x0002	FETCH_MISSING

Como o protocolo TDS não oferece nenhuma forma de enviar a coluna de status à direita sem enviar as colunas anteriores, são enviados dados fictícios para linhas ausentes (campos que permitem valor nulo definidos como nulos, campos de comprimento fixo definidos como 0, em branco ou o padrão para aquela coluna, conforme apropriado).

A contagem de linhas DONE sempre será zero. A mensagem DONE contém a contagem de linhas do conjunto de resultados real, e mensagens de erro ou informativas poderão aparecer entre quaisquer mensagens TDS.

Para solicitar que os metadados sobre a lista de seleção do cursor sejam retornados no fluxo TDS, defina o sinalizador de entrada RPC RETURN_METADATA como 1.

Exemplos

a. Usando PREV para alterar uma posição de cursor

Suponha que um cursor h2 gerasse um conjunto de resultados com o conteúdo a seguir com uma posição atual conforme é mostrado:

row 1 contents      
row 2 contents  
row 3 contents  
row 4 contents  <-- current position  
row 5 contents   
row 6 contents  

Em seguida, um sp_cursorfetch PREV que tem um valor nrows de 5 posicionaria logicamente o cursor duas linhas antes da primeira linha do conjunto de resultados. Nesses casos, o cursor é ajustado para iniciar na primeira linha e retornar o número de linhas solicitado. Em geral, isso significa que ele retornará linhas que estavam no buffer de busca PRIOR.

Observação

Esse é o caso exato em que o parâmetro de status RPC é definido como 2.

B. Usando PREV_NOADJUST para retornar menos linhas que PREV

PREV_NOADJUST nunca inclui nenhuma das linhas na posição do cursor atual, ou após, no bloco de linhas que retorna. Nos casos em que PREV retorna linhas após a posição atual, PREV_NOADJUST retorna menos linhas do que o solicitado em nrows. Dada a posição atual no Exemplo A anterior, quando PREV é aplicado, sp_cursorfetch (h2, 4, 1, 5) busca as seguintes linhas:

row1 contents   
row2 contents  
row3 contents  
row4 contents  
row5 contents  

Porém, quando PREV_NOADJUST é aplicado, sp_cursorfetch (h2, 512, 6, 5) busca somente as seguintes linhas:

row1 contents   
row2 contents  
row3 contents   

Consulte Também

sp_cursoropen (Transact-SQL)
Procedimentos armazenados do sistema (Transact-SQL)