sp_cursorfetch (Transact-SQL)

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-se ID = 7 em um pacote TDS.

Convenções da sintaxe Transact-SQL

Sintaxe

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

Argumentos

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

• fetchtype
  Especifica o buffer de cursor a ser buscado. fetchtype é um parâmetro opcional que exige um dos valores de entrada de inteiro a seguir.

  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, pois FORWARD_ONLY oferece suporte à rolagem em uma única 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    O uso de LAST para um cursor FORWARD_ONLY retorna uma mensagem de erro, pois FORWARD_ONLY oferece suporte à rolagem em uma única direção.
  0x10	ABSOLUTE	Busca um buffer de linhas nrows que iniciam com a linha rownum. Observação    O uso de ABSOLUTE para um cursor DYNAMIC ou FORWARD_ONLY retorna uma mensagem de erro, pois FORWARD_ONLY oferece suporte à rolagem em uma única direção.
  0x20	RELATIVE	Busca o buffer de linhas nrows que iniciam com a linha que é especificada como sendo o valor rownum de linhas a partir da primeira linha no bloco atual. Neste caso, rownum pode ser um número negativo. Observação    O uso de RELATIVE para um cursor FORWARD_ONLY retorna uma mensagem de erro, pois FORWARD_ONLY oferece suporte à rolagem em uma única 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 com 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, com exceção de INFO.

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

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

• rownum
  É um parâmetro opcional usado para especificar a posição da linha para os valores ABSOLUTE e INFO de fetchtype usando valores inteiros para entrada ou saída, ou ambos. rownum serve como o deslocamento da linha para o valor de bit de fetchtype RELATIVE. rownum é ignorado para todos os outros valores. Para obter mais informações, consulte a seção Comentários, posteriormente 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 0. Quando nrows é aplicado à consulta INFO de fetchtype, retorna o número total de linhas nessa consulta.

  Observação
  nrows é ignorado pelo valor de bit de fetchtype REFRESH. Para obter mais informações, consulte a seção Comentários, posteriormente neste tópico.

Valores de 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, os conteúdo do buffer permanecerá como era.

<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 a ser buscada neste 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 m linhas encontradas para 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

Com exceção de SKIP_UPD_CNCY, os valores fetchtype são mutuamente exclusivo.

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ê usar rownum, o buffer será preenchido a partir da 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 FIRST com um valor nrow 0, o cursor é posicionado antes do conjunto de resultados que não tem nenhuma linha no buffer de busca.

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

Para os valores fetchtype NEXT, PREV, ABSOLUTE, RELATIVE e PREV_NOADJUST, um valor nrow 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 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 com um valor nrows 5 posicionaria o cursor logicamente 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 as solicitadas 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

Referência

sp_cursoropen (Transact-SQL)

Procedimentos armazenados do sistema (Transact-SQL)