sp_cursorfetch (Transact-SQL)
Aplica-se a:
SQL Server
Busca um buffer de uma ou mais linhas do banco de dados. O grupo de linhas nesse buffer é chamado de buffer de busca de do cursor.
sp_cursorfetch é invocado especificando ID = 7 em um pacote de fluxo de dados tabular (TDS).
Transact-SQL convenções de sintaxe
Sintaxe
sp_cursorfetch cursor
[ , fetchtype [ , rownum [ , nrows ] ] ]
[ ; ]
Argumentos
Importante
Os argumentos para procedimentos armazenados estendidos devem ser inseridos na ordem específica, conforme descrito na seção de sintaxe. Se os parâmetros forem inseridos fora de ordem, ocorrerá uma mensagem de erro.
cursor
Um identificador valor gerado pelo SQL Server e retornado por sp_cursoropen.
cursor é um parâmetro obrigatório que exige um int valor de entrada. Para obter mais informações, consulte a seção Observações.
fetchtype
Especifica qual buffer de cursor buscar. fetchtype é um parâmetro opcional que requer um dos seguintes valores de entrada inteiros.
| Valor | Designação | Descrição |
|---|---|---|
0x0001 |
FIRST |
Busca o primeiro buffer de nrows linhas. 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 nrows linhas. |
0x0004 |
PREV |
Busca o buffer anterior de nrows linhas. Nota: Usar PREV para um cursor FORWARD_ONLY retorna uma mensagem de erro porque FORWARD_ONLY suporta apenas a rolagem em uma direção. |
0x0008 |
LAST |
Busca o último buffer de nrows linhas. Se nrows for igual a 0, o cursor será posicionado após o conjunto de resultados e nenhuma linha será retornada. Nota: Usar LAST para um cursor FORWARD_ONLY retorna uma mensagem de erro porque FORWARD_ONLY suporta apenas a rolagem em uma direção. |
0x10 |
ABSOLUTE |
Busca um buffer de nrows linhas começando com a linha rownum. Nota: Usar ABSOLUTE para um cursor DYNAMIC ou um cursor FORWARD_ONLY retorna uma mensagem de erro porque FORWARD_ONLY só suporta rolagem em uma direção. |
0x20 |
RELATIVE |
Busca o buffer de nrows linhas começando com a linha especificada como sendo o valor de de linhas da primeira linha no bloco atual. Neste caso, de linha pode ser um número negativo. Nota: Usar RELATIVE para um cursor FORWARD_ONLY retorna uma mensagem de erro porque FORWARD_ONLY suporta apenas a rolagem em uma direção. |
0x80 |
REFRESH |
Recarrega o buffer das tabelas subjacentes. |
0x100 |
INFO |
Recupera informações sobre o cursor. Essas informações são retornadas usando o rownum e nrows parâmetros. Portanto, quando INFO é especificado, de soma de linha e nrows se tornam parâmetros de saída. |
0x200 |
PREV_NOADJUST |
É usado como PREV. No entanto, se o topo do conjunto de resultados for encontrado prematuramente, os resultados podem 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 Observações.
rownum
Um parâmetro opcional que é usado para especificar a posição da linha para os valores ABSOLUTE e INFOfetchtype usando apenas valores inteiros para entrada ou saída, ou ambos.
rownum serve como o deslocamento de linha para o valor de bit fetchtypeRELATIVE.
rownum é ignorado para todos os outros valores. Para obter mais informações, consulte a seção Observações.
nrows
Um parâmetro opcional que é 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 de 0. Quando nrows é aplicado à consulta INFO fetchtype, ela retorna o número total de linhas nessa consulta.
nrows é ignorado pelo valor REFRESHfetchtype bit. Para obter mais informações, consulte a seção Observações.
Valores de código de retorno
Quando você especifica o valor de bit INFO, os valores que podem ser retornados são mostrados nas tabelas a seguir.
Se nenhuma linha for retornada, o conteúdo do buffer permanecerá como estava.
| <rownum> | Definir como |
|---|---|
| Se não estiver aberto | 0 |
| Se posicionado antes do conjunto de resultados | 0 |
| Se posicionado após o conjunto de resultados | -1 |
Para KEYSET e STATIC cursores |
O número absoluto da linha da posição atual no conjunto de resultados |
Para DYNAMIC cursores |
1 |
Para ABSOLUTE |
-1 retorna a última linha de um conjunto. -2 retorna a penúltima linha de um conjunto, e assim por diante. Nota: Se mais de uma linha for solicitada para busca, neste caso, as duas últimas linhas do conjunto de resultados serão retornadas. |
<nrows> |
Definir como |
|---|---|
| Se não estiver aberto | 0 |
Para KEYSET e STATIC cursores |
Normalmente, o tamanho atual do conjunto de chaves.-m se o cursor estiver em criação assíncrona com m linhas encontradas até este ponto. |
Para DYNAMIC cursores |
-1 |
Comentários
O cursor parâmetro
Antes de qualquer operação de busca, a posição padrão de um cursor é antes da primeira linha do conjunto de resultados.
O parâmetro fetchtype
Com exceção 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 do conjunto de chaves quando uma linha é buscada ou atualizada. Se a linha do conjunto de chaves estiver sendo atualizada, os valores das colunas de carimbo de data/hora permanecerão como o valor anterior. Se a linha do conjunto de chaves estiver sendo inserida, os valores das colunas de carimbo de data/hora serão indefinidos.
Para KEYSET cursores, isso significa que a tabela do conjunto de chaves tem os valores definidos durante o último FETCHnão ignorado, se um foi executado. Se não, são os valores definidos durante a população.
Para DYNAMIC cursores, isso significa que, se o pulo for executado com uma atualização, ele produzirá os mesmos resultados que KEYSET. Para qualquer outro tipo de busca, a tabela do conjunto de chaves é truncada. Isso significa que as linhas estão sendo inseridas e os valores para as colunas de carimbo de data/hora estão indefinidos. Portanto, quando você executar sp_cursorfetch para DYNAMIC cursores, evite usá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 solicitada está além do conjunto de resultados, a posição do cursor será definida logo após a última linha. Se uma operação de busca falhar porque a posição do cursor solicitada está posicionada antes do conjunto de resultados, a posição do cursor é definida antes da primeira linha.
O parâmetro rownum
Quando você usa de número de linha, o buffer é preenchido começando com a linha especificada.
O valor fetchtypeABSOLUTE refere-se à posição de de número de linha 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 fetchtypeRELATIVE refere-se à posição de de número de linha em relação à posição do cursor no início do buffer atual. Um número negativo com RELATIVE especifica que o cursor retroceda da posição atual do cursor.
O parâmetro nrows
O fetchtype valores REFRESH e INFO ignorar esse parâmetro.
Quando você especifica um valor de fetchtype de FIRST que é um valor de 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 de fetchtype de LAST que é um nrow valor de 0, o cursor é posicionado após o conjunto de resultados que não tem linhas no buffer de busca atual.
Para o fetchtype valores de NEXT, PREV, ABSOLUTE, RELATIVEe PREV_NOADJUST, um valor de de nrow de 0 não é válido.
Considerações sobre RPC
O status de retorno RPC indica se o parâmetro de tamanho do conjunto de chaves é final ou não; ou seja, se o conjunto de chaves ou a tabela temporária estiver sendo preenchida 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 para o início do conjunto de resultados, quando a busca teria sido logicamente antes dos resultados. |
0x10 |
Um cursor de avanço rápido foi fechado automaticamente. |
As linhas são retornadas como um conjunto de resultados típico: formato de coluna (0x2a), linhas (0xd1), seguido de DONE (0xfd). Os tokens de metadados são enviados no mesmo formato especificado para sp_cursoropen: 0x81, 0xa5 e 0xa4 para usuários do SQL Server e assim por diante. Os indicadores de status da linha são enviados como colunas ocultas, semelhantes ao modo BROWSE, no final de cada linha com o nome da coluna rowstat e o tipo de dados int. Esta 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 fornece nenhuma maneira de enviar a coluna de status à direita sem enviar as colunas anteriores, os dados fictícios são enviados para linhas ausentes. Os campos anuláveis são definidos como nulos e os campos de comprimento fixo são definidos como 0, em branco ou o padrão para essa coluna, conforme apropriado.
A contagem de linhas DONE é sempre 0. A mensagem DONE contém a contagem de linhas do conjunto de resultados real e mensagens de erro ou informativas podem 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
Um. Utilizar o PREV para alterar a posição do cursor
Suponha que um cursor h2 produziria um conjunto de resultados com o seguinte conteúdo 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_cursorfetchPREV onde nrows é 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 solicitadas. Isso frequentemente significa que ele retorna linhas que estavam no buffer de busca PRIOR.
Observação
Este é o caso exato em que o parâmetro de status RPC é definido como 2.
B. Use PREV_NOADJUST para retornar menos linhas do que PREV
PREV_NOADJUST nunca inclui nenhuma das linhas na ou após a posição atual do cursor 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 anteriormente, quando PREV é aplicado, sp_cursorfetch (h2, 4, 1, 5) busca as seguintes linhas:
row1 contents
row2 contents
row3 contents
row4 contents
row5 contents
No entanto, quando PREV_NOADJUST é aplicado, sp_cursorfetch (h2, 512, 6, 5) obtém apenas as seguintes linhas:
row1 contents
row2 contents
row3 contents