sp_cursorfetch (Transact-SQL)
Aplica-se:
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 tabulares).
Convenções de sintaxe de Transact-SQL
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 sintaxe. Se os parâmetros forem inseridos fora de ordem, ocorrerá uma mensagem de erro.
cursor
Um valor de identificador gerado pelo SQL Server e retornado por sp_cursoropen.
cursor é um parâmetro necessário que chama um valor de entrada int . Para obter mais informações, consulte a seção Comentários.
tipo de busca
Especifica o buffer de cursor a ser buscado. fetchType é um parâmetro opcional que requer um dos seguintes valores de entrada inteiros.
| 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: Usar PREV para um FORWARD_ONLY cursor retorna uma mensagem de erro porque FORWARD_ONLY suporta apenas a 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 FORWARD_ONLY cursor retorna uma mensagem de erro porque FORWARD_ONLY suporta apenas a rolagem em uma direção. |
0x10 |
ABSOLUTE |
Busca um buffer de nrows rows começando com rownum row. Observação: Usar ABSOLUTE para um DYNAMIC cursor ou um FORWARD_ONLY cursor retorna uma mensagem de erro porque FORWARD_ONLY suporta apenas a rolagem em uma direção. |
0x20 |
RELATIVE |
Busca o buffer de linhas nrows começando com a linha especificada como sendo o valor rownum das linhas da primeira linha no bloco atual. Nesse caso, rownum pode ser um número negativo. Observação: Usar RELATIVE para um FORWARD_ONLY cursor retorna uma mensagem de erro porque FORWARD_ONLY suporta apenas a 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.
rownum
Um parâmetro opcional usado para especificar a posição da linha para os ABSOLUTE valores 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 fetchtype RELATIVE .
rownum é ignorado para todos os outros valores. Para obter mais informações, consulte a seção Comentários.
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 fetchtypeINFO, ele retorna o número total de linhas nessa consulta.
nrows é ignorado pelo valor de bit fetchtypeREFRESH. Para obter mais informações, consulte a seção Comentários.
Valores do código de retorno
Quando você especifica o valor INFOdo bit , 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 abrir | 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 de linha absoluto da posição atual no conjunto de resultados |
Para DYNAMIC cursores |
1 |
Para ABSOLUTE |
-1 retorna a última linha de um conjunto. -2 retorna da segunda à ú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 abrir | 0 |
Para KEYSET e STATIC cursores |
Normalmente, o tamanho do conjunto de chaves atual.-m se o cursor estiver em criação assíncrona com m linhas encontradas até este ponto. |
Para DYNAMIC cursores |
-1 |
Comentários
O parâmetro cursor
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
Exceto por SKIP_UPD_CNCY, os valores fetchtypesã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 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 KEYSET cursores, isso significa que a tabela de conjunto de chaves tem os valores definidos durante o último nonskip FETCH, se um foi executado. Caso contrário, são os valores definidos durante a população.
Para DYNAMIC cursores, isso significa que, se o salto for executado com uma atualização, ele produzirá 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 das colunas de carimbo de data/hora são indefinidos. Portanto, ao executar sp_cursorfetchDYNAMIC cursores, evite usar SKIP_UPDT_CNCY para qualquer operação diferente de 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.
O parâmetro rownum
Quando você usa rownum, o buffer é preenchido começando com a linha especificada.
O 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 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 retrocede a partir da posição atual do cursor.
O parâmetro nrows
Os REFRESH e INFO ignorar esse parâmetro.
Quando você especifica um valor fetchtype de FIRST que é um valor nrow de 0, o cursor é posicionado antes do conjunto de resultados que não há linhas no buffer de busca.
Quando você especifica um valor fetchtype de que é um LAST de 0, o cursor é posicionado após o conjunto de resultados que não há linhas no buffer de busca atual.
Para os valores fetchtype de NEXT, PREV, ABSOLUTE, RELATIVEe 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 do conjunto de chaves é final ou não; ou seja, se o conjunto de chaves ou a tabela temporária estiver sendo preenchido 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 típico: formato de coluna (0x2a), linhas (0xd1), seguidas por 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 BROWSE modo, no final de cada linha com o nome da coluna rowstat e o tipo de dados int. 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 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 DONE contagem de linhas é sempre 0. A DONE mensagem contém a contagem de linhas do conjunto de resultados real e mensagens de erro ou informativas podem aparecer entre qualquer mensagem 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
R. Use PREV para alterar a posição do 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_cursorfetchPREV where nrows is 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. Isso frequentemente significa que ele retorna linhas que estavam no PRIOR buffer de busca.
Observação
Esse é 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 posição atual do cursor ou após ela no bloco de linhas que ele 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) busca apenas as seguintes linhas:
row1 contents
row2 contents
row3 contents