A instrução SELECT INTO produz uma tabela de resultados que contém apenas uma linha.
A instrução atribui os valores nessa linha para hospedar variáveis.
Se a tabela estiver vazia, a instrução não atribui valores às variáveis do host.

Invocação

Esta declaração pode ser incorporada apenas em um programa aplicativo.
É uma instrução executável que não pode ser preparada dinamicamente.

Autorização

Os privilégios mantidos pelo ID de autorização do proprietário do plano ou pacote devem incluir pelo menos um dos seguintes itens para cada tabela e exibição identificada na instrução:

• O privilégio SELECT na tabela ou exibição (view)
• Propriedade da tabela ou exibição (view)
• Autoridade DBADM para o banco de dados (apenas tabelas)
• Autoridade DATAACCESS
• Autoridade SYSADM
• Autoridade SYSCTRL (apenas tabelas de catálogo)

Se a instrução SELECT INTO incluir uma instrução de alteração de dados SQL, o conjunto de privilégios também deverá incluir pelo menos os privilégios (INSERT, UPDATE ou DELETE) associados a essa instrução de alteração de dados SQL na tabela ou exibição (view).

Syntax

Notas:

• ¹ A cláusula select não pode fazer referência a uma tabela temporal de período do sistema e uma tabela habilitada para arquivamento.
• ² A mesma cláusula não deve ser especificada mais de uma vez.

Descrição

A tabela de resultados é derivada avaliando-se logicamente as isolation-clause, cláusula from, cláusula where, group-by-clause, having-clause, order-by-clause e a select-clause nessa ordem.
Consulte Queries para obter uma descrição dessas cláusulas.

As tabelas ou visualizações (views) identificadas na instrução podem existir no servidor atual ou em qualquer subsistema DB2 com o qual o servidor atual possa estabelecer uma conexão.

WITH common-table-expression

Consulte common-table-expression para obter informações sobre como especificar uma expressão da tabela comum.

INTO host-variable,...

Cada variável de host deve identificar uma estrutura ou variável descrita no programa de acordo com as regras para declarar estruturas e variáveis de host.
Na forma operacional da cláusula INTO, uma referência a uma estrutura é substituída por uma referência a cada uma de suas variáveis de host.

O primeiro valor na linha de resultado é atribuído à primeira variável na lista, o segundo valor à segunda variável e assim por diante.
Se o número de variáveis ??do host for menor que o número de valores da coluna, o valor W será designado ao campo SQLWARN3 do SQLCA.
(Consulte Área de comunicação SQL (SQLCA) .)

O tipo de dados de uma variável deve ser compatível com o valor atribuído a ela.
Se o valor for numérico, a variável deve ter a capacidade de representar a parte integrante do valor.
Para um valor de data ou hora, a variável deve ser uma variável de cadeia de caracteres de tamanho mínimo, conforme definido nas atribuições Datetime assignments.
Se o valor for nulo, uma variável indicadora deve ser especificada.

Cada atribuição a uma variável é feita de acordo com as regras descritas em Language elements.
As atribuições são feitas em sequência através da lista.

e ocorrer um erro como resultado de uma expressão aritmética na lista SELECT de uma instrução SELECT INTO (divisão por zero ou excedente) ou ocorrer um erro de conversão numérica, o resultado será o valor nulo.
Como em qualquer outro caso de valor nulo, uma variável indicadora deve ser fornecida e a variável principal permanece inalterada.
Nesse caso, no entanto, a variável indicadora está configurada para -2.
O processamento da instrução continua como se o erro não tivesse ocorrido.
(No entanto, esse erro causa um SQLCODE positivo.)
Se você não fornecer uma variável de indicador, um valor negativo será retornado no campo SQLCODE do SQLCA.
O processamento da instrução termina quando o erro é encontrado.

Se ocorrer um erro, nenhum valor será atribuído à variável do host ou a variáveis posteriores, embora quaisquer valores que já tenham sido atribuídos às variáveis permaneçam atribuídos.

Se ocorrer um erro porque a tabela de resultados possui mais de uma linha, os valores podem ou não ser atribuídos às variáveis do host.
Se valores são atribuídos às variáveis do host, a linha que é a origem dos valores é indefinida e não previsível.

isolation-clause

Especifica o nível de isolamento no qual a instrução é executada e, opcionalmente, o tipo de bloqueios adquiridos.

SKIP LOCKED DATA

Especifica que as linhas são ignoradas quando bloqueios incompatíveis são mantidos na linha por outras transações.
Essas linhas podem pertencer a qualquer tabela acessada especificada na instrução.
SKIP LOCKED DATA pode ser usado apenas quando o isolamento CS ou RS está em vigor e se aplica apenas aos bloqueios no nível da linha ou no nível da página.

SKIP LOCKED DATA será ignorado se for especificado quando o nível de isolamento em vigor for leitura repetível (WITH RR) ou leitura não confirmada (WITH UR).

QUERYNO integer

Especifica o número a ser usado para esta instrução SQL nos registros de saída e rastreio EXPLAIN.
O número é usado para as colunas QUERYNO das tabelas de plano para as linhas que contêm informações sobre esta instrução SQL.
Esse número também é usado na coluna QUERYNO das tabelas de catálogo SYSIBM.SYSSTMT e SYSIBM.SYSPACKSTMT.

Se a cláusula for omitida, o número associado à instrução SQL será o número da instrução designado durante a pré-compilação.
Portanto, se o programa aplicativo for alterado e pré-compilado, esse número da instrução poderá ser alterado.

É útil usar a cláusula QUERYNO para atribuir números exclusivos às instruções SQL em um programa:

• Para simplificar o uso de dicas de otimização para a seleção do caminho de acesso
• Para correlacionar o texto da instrução SQL com a saída EXPLAIN na tabela de plano

Para obter informações sobre o uso de dicas de otimização, como ativar o sistema para dicas de otimização e definir valores válidos de dicas e para obter informações sobre como acessar a tabela de planos, consulte Managing DB2 Performance.

FETCH FIRST ROW ONLY integer

A cláusula FETCH FIRST ROW ONLY pode ser usada na instrução SELECT INTO quando a consulta pode resultar em mais de uma única linha.
A cláusula indica que apenas uma linha deve ser recuperada, independentemente de quantas linhas possam estar na tabela de resultados.
Quando um número é especificado explicitamente, ele deve ser 1.

O uso da cláusula FETCH FIRST ROW ONLY para limitar explicitamente a tabela de resultados a uma única linha fornece uma maneira de a instrução SELECT INTO ser usada com uma consulta que retorna mais de uma linha.
O uso da cláusula ajuda a evitar o uso de um cursor quando você sabe que deseja recuperar apenas uma linha.

Para influenciar qual linha é retornada, você pode usar a order-by-clause. Quando você especifica a order-by-clause, as linhas do resultado são ordenadas e a primeira linha é retornada. Se a cláusula FETCH FIRST ROW ONLY não for especificada e a tabela de resultados contiver mais de uma única linha, ocorrerá um erro.

Notas

Esquema de codificação padrão:

O esquema de codificação padrão para os dados é o valor na opção de ligação ENCODING, que é a opção para codificação de aplicativo.
Se essa instrução for usada com funções como LENGTH ou SUBSTRING que estão operando em localizadores LOB, e os dados LOB especificados pelo localizador estão em um esquema de codificação diferente da opção de ligação ENCODING, ocorre a materialização LOB e a conversão de caracteres.
Para evitar a materialização do LOB e a conversão de caracteres, selecione os dados do LOB na tabela de amostra SYSIBM.SYSDUMMYA, SYSIBM.SYSDUMMYE ou SYSIBM.SYSDUMMYU.

Se a tabela de resultados estiver vazia:

Se a tabela estiver vazia, a instrução atribui +100 a SQLCODE, '02000' a SQLSTATE e não atribui valores às variáveis do host.

Número de linhas inseridas:

Se a instrução SELECT INTO do cursor contiver uma instrução de alteração de dados SQL, a operação SELECT INTO configurará SQLERRD (3) para o número de linhas inseridas.

Usando localizadores:

Normalmente, você usa localizadores LOB para atribuir e recuperar dados de colunas LOB.
No entanto, devido às regras de compatibilidade, você também pode usar localizadores LOB para atribuir dados para hospedar variáveis com os tipos de dados CHAR, VARCHAR, GRAPHIC ou VARGRAPHIC.

Exemplos:

1. Coloque o salário máximo em DSN8A10.EMP na variável do host MAXSALRY.

   EXEC SQL 
        SELECT MAX(SALARY)
        INTO  :MAXSALRY
        FROM   DSN8A10.EMP;
   END-EXEC.

2. Coloque a linha do funcionário 528671, de DSN8A10.EMP, na estrutura do host EMPREC.

   EXEC SQL 
        SELECT *
        INTO  :EMPREC
        FROM   DSN8A10.EMP
        WHERE  EMPNO = '528671'
   END-EXEC.

3. Coloque a linha do funcionário 528671, de DSN8A10.EMP, na estrutura do host EMPREC.
Suponha que a linha será atualizada posteriormente e deve ser bloqueada quando a consulta for executada.

   EXEC SQL 
        SELECT *
        INTO  :EMPREC
        FROM   DSN8A10.EMP
        WHERE  EMPNO = '528671'
        WITH RS USE AND KEEP EXCLUSIVE LOCKS
   END-EXEC.

4. Usando uma instrução SELECT INTO, recupere o valor de INTCOL1 da tabela T1 em um elemento na matriz MYINTARRAY1, que é indexado pelo valor da expressão
INTCOL2 + MYINTVAR + 1.

   EXEC SQL 
   SELECT INTCOL1 INTO MYINTARRAY1[INTCOL2+MYINTVAR+1]
     FROM T1
    WHERE INTCOL1 = MYINTARRAY1[INTCOL2]
   END-EXEC.