Executar Tarefa SQL

Aplica-se a:SQL Server SSIS Integration Runtime em Azure Data Factory

A tarefa Executar SQL executa instruções SQL ou procedimentos armazenados a partir de um pacote. A tarefa pode conter uma única instrução SQL ou múltiplas instruções SQL que são executadas sequencialmente. Pode usar a tarefa Executar SQL para os seguintes fins:

• Truncar uma tabela ou vista para preparar a inserção de dados.

• Criar, alterar e eliminar objetos de base de dados, como tabelas e vistas.

• Recrie tabelas de factos e dimensões antes de carregar dados nelas.

• Executar procedimentos armazenados. Se a instrução SQL invocar um procedimento armazenado que devolve resultados de uma tabela temporária, use a opção WITH RESULT SETS para definir metadados para o conjunto de resultados.

• Guardar o conjunto de linhas devolvido de uma consulta numa variável.

A tarefa Executar SQL pode ser usada em combinação com os contentores Foreach Loop e For Loop para executar múltiplas instruções SQL. Estes contentores implementam fluxos de controlo repetidos num pacote e podem executar a tarefa Executar SQL repetidamente. Por exemplo, usando o contentor Foreach Loop, um pacote pode enumerar ficheiros numa pasta e executar uma tarefa Executar SQL repetidamente para executar a instrução SQL armazenada em cada ficheiro.

Ligar a uma origem de dados

A tarefa Executar SQL pode usar diferentes tipos de gestores de ligação para se ligar à fonte de dados onde executa a instrução SQL ou o procedimento armazenado. A tarefa pode usar os tipos de ligação listados na tabela seguinte.

Criar instruções SQL

A fonte das instruções SQL usadas por esta tarefa pode ser uma propriedade de tarefa que contém uma instrução, uma ligação a um ficheiro que contém uma ou várias instruções, ou o nome de uma variável que contém uma instrução. As instruções SQL devem ser escritas no dialeto do sistema de gestão de bases de dados de origem (SGBD). Para mais informações, consulte Consultas de Serviços de Integração (SSIS).

Se as instruções SQL estiverem armazenadas num ficheiro, a tarefa utiliza um gestor de ligação de ficheiros para se ligar ao ficheiro. Para obter mais informações, consulte Gestor de Conexões de Arquivo.

No SSIS Designer, pode usar a caixa de diálogo Executar Editor de Tarefas SQL para escrever instruções SQL, ou usar o Query Builder, uma interface gráfica para criar consultas SQL.

Enviar múltiplas instruções em lote

Se incluir múltiplas instruções numa tarefa Executar SQL, pode agrupá-las e executá-las em batch. Para sinalizar o fim de um lote, use o comando GO. Todas as instruções SQL entre dois comandos GO são enviadas em lote para o fornecedor OLE DB para serem executadas. O comando SQL pode incluir vários lotes separados por comandos GO.

Existem restrições sobre os tipos de instruções SQL que podes agrupar num lote. Para mais informações, consulte Lotes de Declarações.

Se a tarefa Executar SQL executar um lote de instruções SQL, as seguintes regras aplicam-se ao lote:

• Apenas uma instrução pode devolver um conjunto de resultados e deve ser a primeira instrução do lote.

• Se o conjunto de resultados usar ligações de resultados, as consultas devem devolver o mesmo número de colunas. Se as consultas devolverem um número diferente de colunas, a tarefa falha. No entanto, mesmo que a tarefa falhe, as consultas que executa, como as consultas DELETE ou INSERT, podem ter sucesso.

• Se as associações de resultados usarem nomes de colunas, a consulta deve devolver colunas com os mesmos nomes dos conjuntos de resultados usados na tarefa. Se as colunas estiverem em falta, a tarefa falha.

• Se a tarefa usar ligação por parâmetros, todas as consultas no lote devem ter o mesmo número e tipos de parâmetros.

Executar comandos SQL parametrizados

As instruções SQL e procedimentos armazenados usam frequentemente parâmetros de entrada, parâmetros de saída e códigos de retorno. A tarefa Executar SQL suporta os tipos de parâmetros Input, Output e ReturnValue . Usas o tipo Input para parâmetros de entrada, Output para parâmetros de saída e ReturnValue para códigos de retorno.

Especifique um tipo de conjunto de resultados

Dependendo do tipo de comando SQL, um conjunto de resultados pode ou não ser devolvido à tarefa Executar SQL. Por exemplo, uma instrução SELECT normalmente devolve um conjunto de resultados, mas uma instrução INSERT não. O conjunto de resultados de uma instrução SELECT pode conter zero linhas, uma linha ou muitas linhas. Os procedimentos armazenados também podem devolver um valor inteiro, chamado código de retorno, que indica o estado de execução do procedimento. Nesse caso, o conjunto de resultados consiste numa única linha.

Configurar a tarefa Executar SQL

Pode configurar a tarefa Executar SQL das seguintes formas:

• Especifique o tipo de gestor de ligação a usar para se ligar a uma base de dados.

• Especifique o tipo de conjunto de resultados que a instrução SQL devolve.

• Especifique um time-out para as instruções SQL.

• Especifique a origem da instrução SQL.

• Indique se a tarefa salta a fase de preparação para a instrução SQL.

• Se usar o tipo de ligação ADO, deve indicar se a instrução SQL é um procedimento armazenado. Para outros tipos de conexão, esta propriedade é apenas leitura e o seu valor é sempre falso.

Pode definir propriedades programaticamente ou através do SSIS Designer.

Página Geral - Executar Editor de Tarefas SQL

Use a página Geral da caixa de diálogo do Editor de Tarefas Executar SQL para configurar a tarefa de execução de SQL e fornecer a instrução SQL que a tarefa executa.

Para saber mais sobre a linguagem de consulta Transact-SQL, consulte Transact-SQL Referência (Motor de Base de Dados).

Opções estáticas

Nome
Forneça um nome único para a tarefa Executar SQL no fluxo de trabalho. O nome fornecido será apresentado no SSIS Designer.

Descrição
Descreva a tarefa de Executar SQL. Como boa prática, para tornar os pacotes auto-documentados e mais fáceis de manter, descreva a tarefa em termos do seu propósito.

TimeOut
Especifique o número máximo de segundos que a tarefa irá executar antes de expirar. Um valor de 0 indica um tempo infinito. O padrão é 0.

CodePage
Especifique a página de códigos a usar ao traduzir valores Unicode em variáveis. O valor padrão é a página de códigos do computador local.

TypeConversionMode
Quando definir esta propriedade como Permitido, a Tarefa Executar SQL tentará converter os resultados do parâmetro de saída e da consulta para o tipo de dado da variável a que os resultados foram atribuídos. Isto aplica-se ao tipo de conjunto de resultados de linha única .

Conjunto de Resultados
Especifique o tipo de resultado esperado pela instrução SQL que está a ser executada. Escolha entre linha única, conjunto completo de resultados, XML ou nenhum.

TipoDeConexão
Escolha o tipo de gestor de ligação a usar para se ligar à fonte de dados. Os tipos de ligação disponíveis incluem OLE DB,ODBC, ADO, ADO.NET e SQLMOBILE.

Tópicos Relacionados:OLE DB Connection Manager, ODBC Connection Manager, ADO Connection Manager, ADO.NET Connection Manager, SQL Server Compact Edition Connection Manager

Conexão
Escolha a ligação de uma lista de gestores de ligação definidos. Para criar uma nova ligação, selecione <Nova ligação...>.

SQLSourceType
Selecione o tipo de origem da instrução SQL que a tarefa executa.

Dependendo do tipo de gestor de ligação que a tarefa Executar SQL utiliza, deve usar marcadores de parâmetros específicos em instruções SQL parametrizadas.

Esta propriedade tem as opções listadas na tabela a seguir.

QueryIsStoredProcedure
Indica se a instrução SQL especificada a executar é um procedimento armazenado. Esta propriedade é apenas de leitura/escrita se a tarefa usar o gestor de ligação ADO. Caso contrário, a propriedade é apenas de leitura e o seu valor é falso.

BypassPrepare
Indique se a instrução SQL está preparada. true salta a preparação; false prepara a instrução SQL antes de a executar. Esta opção está disponível apenas com ligações OLE DB que apoiam a preparação.

Tópicos Relacionados:Execução Preparada

Navegar
Localize um ficheiro que contenha uma instrução SQL usando a caixa de diálogo Abrir . Selecione um ficheiro para copiar o conteúdo do ficheiro como uma instrução SQL para a propriedade SQLStatement .

Construir Consulta
Crie uma instrução SQL usando a caixa de diálogo Query Builder , uma ferramenta gráfica usada para criar consultas. Esta opção está disponível quando a opção SQLSourceType está definida como Entrada Direta.

Analisar consulta
Valide a sintaxe da instrução SQL.

SQLSourceType Opções Dinâmicas

SQLSourceType = Entrada direta

SQLStatement
Escreva a instrução SQL para executar na caixa de opções, ou clique no botão de navegar (...) para escrever a instrução SQL na caixa de diálogo Enter SQL Query , ou clique em Build Query para compor a instrução usando a caixa de diálogo Query Builder .

Tópicos Relacionados:Construtor de Consultas

SQLSourceType = Ligação ao ficheiro

FileConnection
Selecione um gestor de ligações de ficheiros existente, ou clique em <Nova ligação...> para criar um novo gestor de ligações.

Tópicos relacionados:Gerenciador de Conexão de Ficheiros, Editor de Gerenciador de Conexão de Ficheiros

SQLSourceType = Variável

SourceVariable
Seleciona uma variável existente, ou clica <em Nova variável...> para criar uma nova variável.

Tópicos relacionados:variáveis do Integration Services (SSIS)Adicionar variável

Página de Mapeamento de Parâmetros - Executar Editor de Tarefas SQL

Use a página de Mapeamento de Parâmetros da caixa de diálogo Executar Editor de Tarefas SQL para mapear variáveis para parâmetros na instrução SQL.

Opções

Nome da variável
Depois de adicionares um mapeamento de parâmetros clicando em Adicionar, seleciona uma variável definida pelo sistema ou pelo utilizador da lista ou clica <em Nova variável...> para adicionar uma nova variável usando a caixa de diálogo Adicionar Variável .

Tópicos Relacionados:Variáveis dos Serviços de Integração (SSIS)

Direção
Selecione a direção do parâmetro. Mapeie cada variável para um parâmetro de entrada, parâmetro de saída ou um código de retorno.

Tipo de Dados
Selecione o tipo de dado do parâmetro. A lista de tipos de dados disponíveis é específica para o fornecedor selecionado no gestor de ligação utilizado pela tarefa.

Nome do parâmetro
Forneça um nome de parâmetro.

Dependendo do tipo de gestor de ligação que a tarefa utiliza, deve usar números ou nomes de parâmetros. Alguns tipos de gestores de ligação exigem que o primeiro carácter do nome do parâmetro seja o sinal @, nomes específicos como @Param1, ou nomes de colunas como nomes de parâmetros.

Tamanho do parâmetro
Forneça o tamanho dos parâmetros com comprimento variável, como cadeias e campos binários.

Esta configuração garante que o fornecedor aloca espaço suficiente para valores de parâmetros de comprimento variável.

Add
Clique para adicionar um mapeamento de parâmetros.

Remove
Selecione um mapeamento de parâmetros na lista e depois clique em Remover.

Página de Conjunto de Resultados - Editor de Tarefas Executar SQL

Use a página de Conjunto de Resultados do diálogo Executar Editor de Tarefas SQL para mapear o resultado da instrução SQL para variáveis novas ou existentes. As opções nesta caixa de diálogo estão desativadas se o ResultSet na página Geral estiver definido como Nenhum.

Opções

Nome do Resultado
Depois de adicionar um conjunto de mapeamento de resultados clicando em Adicionar, dê um nome ao resultado. Dependendo do tipo de conjunto de resultados, deve usar nomes de resultados específicos.

Se o tipo de conjunto de resultados for Linha única, pode usar o nome de uma coluna devolvida pela consulta ou o número que representa a posição de uma coluna na lista de colunas de uma coluna devolvida pela consulta.

Se o tipo de conjunto de resultados for Full result set ou XML, deve usar 0 como nome do conjunto de resultados.

Nome da variável
Mapeie o conjunto de resultados para uma variável selecionando uma variável ou clique em <Nova variável...> para adicionar uma nova variável usando a caixa de diálogo Adicionar Variável .

Add
Clique para adicionar um mapeamento de conjunto de resultados.

Remove
Selecione um mapeamento de conjunto de resultados na lista e depois clique em Remover.

Parâmetros na tarefa Executar SQL

As instruções SQL e procedimentos armazenados usam frequentemente parâmetros de entrada , parâmetros de saída e códigos de retorno. Nos Serviços de Integração, a tarefa Executar SQL suporta os tipos de parâmetros Input, Output e ReturnValue . Usas o tipo Input para parâmetros de entrada, Output para parâmetros de saída e ReturnValue para códigos de retorno.

Os parâmetros nos comandos SQL, incluindo consultas e procedimentos armazenados, são mapeados para variáveis definidas pelo utilizador que são criadas dentro do âmbito da tarefa Executar SQL, de um contentor pai ou dentro do âmbito do pacote. Os valores das variáveis podem ser definidos em tempo de projeto ou preenchidos dinamicamente em tempo de execução. Também podes mapear parâmetros para variáveis do sistema. Para mais informações, consulte Variáveis de Serviços de Integração (SSIS ) e Variáveis do Sistema.

No entanto, trabalhar com parâmetros e códigos de retorno numa tarefa Executar SQL é mais do que apenas saber que tipos de parâmetros a tarefa suporta e como esses parâmetros serão mapeados. Existem requisitos e diretrizes adicionais de utilização para usar com sucesso parâmetros e códigos de retorno na tarefa Executar SQL. O restante deste tema aborda estes requisitos e diretrizes de utilização:

• Utilização de parâmetros, nomes e marcadores

• Utilização de parâmetros com tipos de dados de data e hora

• Utilização de parâmetros em cláusulas WHERE

• Utilização de parâmetros com procedimentos armazenados

• Obtenção dos valores dos códigos de retorno

Nomes de parâmetros e marcadores

Dependendo do tipo de ligação que a tarefa Executar SQL utiliza, a sintaxe do comando SQL utiliza diferentes marcadores de parâmetro. Por exemplo, o tipo de gestor de ligações ADO.NET exige que o comando SQL use um marcador de parâmetro no formato @varParameter, enquanto o tipo de ligação OLE DB requer o marcador de parâmetro com ponto de interrogação (?).

Os nomes que pode usar como nomes de parâmetros nas correspondências entre variáveis e parâmetros também variam consoante o tipo de gestor de conexões. Por exemplo, o tipo gestor de conexões ADO.NET usa um nome definido pelo utilizador com prefixo @, enquanto o tipo gestor de ligação OLE DB exige que use o valor numérico de um ordinal baseado em 0 como nome do parâmetro.

A tabela seguinte resume os requisitos para comandos SQL para os tipos de gestor de conexões que a tarefa Executar SQL pode utilizar.

Use parâmetros com ADO.NET e gestores de ligação ADO

Os gestores de ligação ADO.NET e ADO têm requisitos específicos para comandos SQL que utilizam parâmetros:

• ADO.NET gestores de conexões exigem que o comando SQL use nomes de parâmetros como marcadores de parâmetro. Isto significa que as variáveis podem ser mapeadas diretamente para os parâmetros. Por exemplo, a variável @varName é mapeada para o parâmetro nomeado @parName e fornece um valor ao parâmetro @parName.

• Os gestores de ligação ADO exigem que o comando SQL use pontos de interrogação (?) como marcadores de parâmetro. No entanto, pode usar qualquer nome definido pelo utilizador, exceto valores inteiros, como nomes de parâmetros.

Para fornecer valores aos parâmetros, as variáveis são mapeadas para nomes de parâmetros. Depois, a tarefa Executar SQL usa o valor ordinal do nome do parâmetro na lista de parâmetros para carregar valores de variáveis para parâmetros.

Use parâmetros com os gestores de conexões EXCEL, ODBC e OLE DB

Os gestores de ligação EXCEL, ODBC e OLE DB exigem que o comando SQL use pontos de interrogação (?) como marcadores de parâmetros e valores numéricos baseados em 0 ou 1 como nomes de parâmetros. Se a tarefa Executar SQL usar o gestor de ligações ODBC, o nome do parâmetro que corresponde ao primeiro parâmetro da consulta é chamado 1; caso contrário, o parâmetro é chamado 0. Para parâmetros subsequentes, o valor numérico do nome do parâmetro indica o parâmetro no comando SQL para o qual o nome do parâmetro corresponde. Por exemplo, o parâmetro chamado 3 corresponde ao terceiro parâmetro, que é representado pelo terceiro ponto de interrogação (?) no comando SQL.

Para fornecer valores aos parâmetros, as variáveis são mapeadas para nomes de parâmetros e a tarefa Executar SQL utiliza o valor ordinal do nome do parâmetro para carregar valores de variáveis para parâmetros.

Dependendo do fornecedor que o gestor de ligação utiliza, alguns tipos de dados OLE DB podem não ser suportados. Por exemplo, o driver Excel reconhece apenas um conjunto limitado de tipos de dados. Para mais informações sobre o comportamento do fornecedor Jet com o driver Excel, consulte Excel Source.

Utilizar parâmetros com os Gestores de Ligação OLE DB

Quando a tarefa Executar SQL utiliza o gestor de conexões OLE DB, a propriedade BypassPrepare da tarefa está disponível. Deves definir esta propriedade como verdadeira se a tarefa Executar SQL usar instruções SQL com parâmetros.

Quando usa um gestor de conexões OLE DB, não pode usar subconsultas parametrizadas porque a Tarefa Executar SQL não pode derivar informação de parâmetros através do fornecedor OLE DB. No entanto, pode usar uma expressão para concatenar os valores dos parâmetros na cadeia de consulta e para definir a propriedade SqlStatementSource da tarefa.

Use parâmetros com tipos de dados de data e hora

Use parâmetros de data e hora com os gestores de ligação ADO.NET e ADO

Ao ler dados dos tipos SQL Server, tempo e datetimeoffset, uma tarefa Executar SQL que utiliza um gestor de ligação ADO.NET ou ADO tem os seguintes requisitos adicionais:

• Para dados temporais , um gestor de ADO.NET de conexões exige que estes dados sejam armazenados num parâmetro cujo tipo de parâmetro seja Entrada ou Saída, e cujo tipo de dado seja string.

• Para dados de deslocamento de data-tempo, o gestor de ligações ADO.NET requer que estes dados sejam armazenados num dos seguintes parâmetros:

  • Um parâmetro cujo tipo de parâmetro é Input e cujo tipo de dado é string.

  • Um parâmetro cujo tipo de parâmetro é Output ou ReturnValue, e cujo tipo de dado é datetimeoffset, string ou datetime2. Se selecionar um parâmetro cujo tipo de dado seja string ou datetime2, o Integration Services converte os dados em string ou datetime2.

• Um gestor de ligação ADO requer que os dados time ou datetimeoffset sejam armazenados num parâmetro cujo tipo de parâmetro seja Entrada ou Saída, e cujo tipo de dado seja adVarWchar.

Para obter mais informações sobre tipos de dados do SQL Server e como eles são mapeados para tipos de dados do Integration Services, consulte Tipos de dados (Transact-SQL) e Tipos de dados do Integration Services.

Use parâmetros de data e hora com os Gestores de Ligação OLE DB

Ao usar um gestor de conexões OLE DB, uma tarefa Executar SQL tem requisitos específicos de armazenamento para dados dos tipos de dados do SQL Server: data, hora, data-hora, data-hora2 e datatimeoffset. Deve armazenar estes dados num dos seguintes tipos de parâmetros:

• Um parâmetro de entrada do tipo de dados NVARCHAR.

• Um parâmetro de saída com o tipo de dado apropriado, conforme listado na tabela seguinte.

  Tipo de parâmetro de saída	Tipo de dados de data
  DBDATE	date
  DBTIME2	time
  DBTIMESTAMP	data-hora, data-hora2
  DBTIMESTAMPOFFSET	datetimeoffset

Se os dados não forem armazenados no parâmetro de entrada ou saída apropriado, o pacote falha.

Utilizar parâmetros de data e hora com os gestores de ligação ODBC

Ao usar um gestor de conexões ODBC, uma tarefa Executar SQL tem requisitos específicos de armazenamento para dados com um dos tipos de dados do SQL Server: date, time, datetime, datetime2 ou datetimeoffset. Deve armazenar estes dados num dos seguintes tipos de parâmetros:

• Um parâmetro de entrada do tipo de dado SQL_WVARCHAR

• Um parâmetro de saída com o tipo de dado apropriado, conforme listado na tabela seguinte.

  Tipo de parâmetro de saída	Tipo de dados de data
  SQL_DATE	date
  SQL_SS_TIME2	time
  SQL_TYPE_TIMESTAMP -ou- SQL_TIMESTAMP	data-hora, data-hora2
  SQL_SS_TIMESTAMPOFFSET	datetimeoffset

Se os dados não forem armazenados no parâmetro de entrada ou saída apropriado, o pacote falha.

Utilizar parâmetros nas cláusulas WHERE

Os comandos SELECT, INSERT, UPDATE e DELETE incluem frequentemente cláusulas WHERE para especificar filtros que definem as condições que cada linha nas tabelas de origem deve cumprir para se qualificar para um comando SQL. Os parâmetros fornecem os valores do filtro nas cláusulas WHERE.

Pode usar marcadores de parâmetros para fornecer valores de parâmetros dinamicamente. As regras para quais marcadores de parâmetros e nomes de parâmetros podem ser usados na instrução SQL dependem do tipo de gestor de ligação que o Execute SQL utiliza.

A tabela seguinte lista exemplos do comando SELECT por tipo de gestor de ligações. As instruções INSERT, UPDATE e DELETE são semelhantes. Os exemplos usam SELECT para devolver produtos da tabela Product em AdventureWorks2025 que têm um ProductID maior e menor que os valores especificados por dois parâmetros.

Os exemplos exigiriam parâmetros com os seguintes nomes:

• Os gestores de ligações EXCEL e OLED DB utilizam os nomes dos parâmetros 0 e 1. O tipo de ligação ODBC usa 1 e 2.

• O tipo de ligação ADO pode usar quaisquer dois nomes de parâmetros, como Param1 e Param2, mas os parâmetros devem ser mapeados pela sua posição ordinal na lista de parâmetros.

• O tipo de ligação ADO.NET usa os nomes dos parâmetros @parmMinProductID e @parmMaxProductID.

Utilizar parâmetros com procedimentos armazenados

Comandos SQL que executam procedimentos armazenados também podem usar mapeamento de parâmetros. As regras para usar marcadores de parâmetros e nomes de parâmetros dependem do tipo de gestor de ligação que o Execute SQL utiliza, tal como as regras para consultas parametrizadas.

A tabela seguinte lista exemplos do comando EXEC por tipo de gestor de ligações. Os exemplos executam o procedimento armazenado uspGetBillOfMaterials em AdventureWorks2025. O procedimento armazenado utiliza os parâmetros @StartProductID e @CheckDatede entrada.

Para usar parâmetros de saída, a sintaxe exige que a palavra-chave OUTPUT siga cada marcador de parâmetro. Por exemplo, a seguinte sintaxe do parâmetro de saída está correta: EXEC myStoredProcedure ? OUTPUT.

Para mais informações sobre o uso de parâmetros de entrada e saída com Transact-SQL procedimentos armazenados, veja EXECUTE (Transact-SQL).

Mapear parâmetros de consulta para variáveis

Esta secção descreve como usar uma instrução SQL parametrizada na tarefa Executar SQL e criar mapeamentos entre variáveis e os parâmetros da instrução SQL.

1. No SSDT (SQL Server Data Tools), abra o pacote do Integration Services com o qual você deseja trabalhar.

2. No Gerenciador de Soluções, clique duas vezes no pacote para abri-lo.

3. Clique na guia Fluxo de controle .

4. Se o pacote ainda não incluir uma tarefa Executar SQL, adicione-a ao fluxo de controlo do pacote. Para obter mais informações, consulte Adicionar ou excluir uma tarefa ou um contêiner em um fluxo de controle.

5. Clique duas vezes na tarefa Executar SQL.

6. Forneça um comando SQL parametrizado de uma das seguintes formas:

   • Use entrada direta e escreva o comando SQL na propriedade SQLStatement.

   • Use entrada direta, clique em Construir Consulta, e depois crie um comando SQL usando as ferramentas gráficas fornecidas pelo Query Builder.

   • Use uma ligação de ficheiro e depois faça referência ao ficheiro que contém o comando SQL.

   • Use uma variável e depois faça referência à variável que contém o comando SQL.

   Os marcadores de parâmetros que usas nas instruções SQL parametrizadas dependem do tipo de ligação que a tarefa Executar SQL utiliza.

   Tipo de ligação	Marcador de parâmetros
   ADO	?
   ADO.NET e SQLMOBILE	@<nome do parâmetro>
   ODBC	?
   EXCEL e OLE DB	?

   A tabela seguinte lista exemplos do comando SELECT por tipo de gestor de ligações. Os parâmetros fornecem os valores do filtro nas cláusulas WHERE. Os exemplos usam SELECT para devolver produtos da tabela Product em AdventureWorks2025 que têm um ProductID maior e menor que os valores especificados por dois parâmetros.

   Tipo de ligação	Sintaxe SELECT
   EXCEL, ODBC e OLEDB	SELECT* FROM Production.Product WHERE ProductId > ? AND ProductID < ?
   ADO	SELECT* FROM Production.Product WHERE ProductId > ? AND ProductID < ?
   ADO.NET	SELECT* FROM Production.Product WHERE ProductId > @parmMinProductID AND ProductID < @parmMaxProductID

7. Clique em Mapeamento de Parâmetros.

8. Para adicionar um mapeamento de parâmetros, clique em Adicionar.

9. Forneça um nome na caixa de Nome do Parâmetro .

   Os nomes dos parâmetros que usas dependem do tipo de ligação que a tarefa Executar SQL utiliza.

   Tipo de ligação	Nome do parâmetro
   ADO	Parágrafo 1, Parágrafo 2, ...
   ADO.NET e SQLMOBILE	@<nome do parâmetro>
   ODBC	1, 2, 3, ...
   EXCEL e OLE DB	0, 1, 2, 3, ...

10. Da lista de Nomes das Variáveis , selecione uma variável. Para mais informações, consulte Adicionar, Eliminar, Alterar o Escopo da Variável Definida pelo Utilizador num Pacote.

11. Na lista de Direção, especifique se o parâmetro é uma entrada, uma saída ou um valor de retorno.

12. Na lista de Tipos de Dados , defina o tipo de dado do parâmetro.

    Importante

    O tipo de dados do parâmetro deve ser compatível com o tipo de dados da variável.

13. Repita os passos 8 a 11 para cada parâmetro na instrução SQL.

    Importante

    A ordem dos mapeamentos dos parâmetros deve ser a mesma que a ordem em que os parâmetros aparecem na instrução SQL.

14. Clique em OK.

Obtenha os valores dos códigos de retorno

Um procedimento armazenado pode devolver um valor inteiro, chamado código de retorno, para indicar o estado de execução de um procedimento. Para implementar códigos de retorno na tarefa Executar SQL, utiliza-se parâmetros do tipo ReturnValue .

A tabela seguinte lista, por tipo de ligação, alguns exemplos de comandos EXEC que implementam códigos de retorno. Todos os exemplos usam um parâmetro de entrada . As regras para usar marcadores e nomes de parâmetros são as mesmas para todos os tipos de parâmetros - Input, Output e ReturnValue.

Algumas sintaxes não suportam parâmetros literais. Nesse caso, deve fornecer o valor do parâmetro usando uma variável.

Na sintaxe mostrada na tabela anterior, a tarefa Executar SQL utiliza o tipo de fonte Direct Input para executar o procedimento armazenado. A tarefa Executar SQL pode também usar o tipo de fonte File Connection para executar um procedimento armazenado. Independentemente de a tarefa Executar SQL usar o tipo de origem Direct Input ou File Connection, use um parâmetro do tipo ReturnValue para implementar o código de retorno.

Para mais informações sobre o uso de códigos de retorno com Transact-SQL procedimentos armazenados, consulte RETURN (Transact-SQL).

Conjuntos de resultados na Tarefa Executar SQL

Num pacote de Serviços de Integração, se um conjunto de resultados é devolvido à tarefa Executar SQL depende do tipo de comando SQL que a tarefa utiliza. Por exemplo, uma instrução SELECT normalmente devolve um conjunto de resultados, mas uma instrução INSERT não.

O que o conjunto de resultados contém também varia consoante o comando SQL. Por exemplo, o conjunto de resultados de uma instrução SELECT pode conter zero linhas, uma linha ou muitas linhas. No entanto, o conjunto de resultados de uma instrução SELECT que devolve uma contagem ou soma contém apenas uma linha.

Trabalhar com conjuntos de resultados numa tarefa Executar SQL é mais do que apenas saber se o comando SQL devolve um conjunto de resultados e o que esse conjunto contém. Existem requisitos de utilização e diretrizes adicionais para utilizar com sucesso conjuntos de resultados na tarefa Executar SQL. O restante deste tema aborda estes requisitos e diretrizes de utilização:

• Especificação de um Tipo de Conjunto de Resultados

• Preencher uma variável com um conjunto de resultados

Especifique um tipo de conjunto de resultados

A tarefa Executar SQL suporta os seguintes tipos de conjuntos de resultados:

• O conjunto de resultados None é usado quando a consulta não retorna resultados. Por exemplo, este conjunto de resultados é usado para consultas que adicionam, alteram e eliminam registos numa tabela.

• O conjunto de resultados de linha única é usado quando a consulta retorna apenas uma linha. Por exemplo, este conjunto de resultados é usado para uma instrução SELECT que devolve uma contagem ou uma soma.

• O conjunto completo de resultados é usado quando a consulta devolve várias linhas. Por exemplo, este conjunto de resultados é usado para uma instrução SELECT que recupera todas as linhas de uma tabela.

• O conjunto de resultados XML é usado quando a consulta retorna um conjunto de resultados em formato XML. Por exemplo, este conjunto de resultados é usado para uma instrução SELECT que inclui uma cláusula FOR XML.

Se a tarefa Executar SQL usar o conjunto de resultados completo e a consulta devolver múltiplos conjuntos de linhas, a tarefa retorna apenas o primeiro conjunto. Se este conjunto de linhas gerar um erro, a tarefa reporta o erro. Se outros conjuntos de linhas gerarem erros, a tarefa não os reporta.

Preencha uma variável com um conjunto de resultados

Pode associar o conjunto de resultados que uma consulta devolve a uma variável definida pelo utilizador, se o tipo de conjunto de resultados for uma única linha, um conjunto de linhas ou XML.

Se o tipo de conjunto de resultados for Linha única, pode associar uma coluna no resultado de retorno a uma variável usando o nome da coluna como nome do conjunto de resultados, ou pode usar a posição ordinal da coluna na lista de colunas como nome do conjunto de resultados. Por exemplo, o nome do conjunto de resultados para a consulta SELECT Color FROM Production.Product WHERE ProductID = ? pode ser Color ou 0. Se a consulta devolver várias colunas e quiser aceder aos valores em todas as colunas, deve associar cada coluna a uma variável diferente. Se mapear colunas para variáveis usando números como nomes de conjuntos de resultados, os números refletem a ordem em que as colunas aparecem na lista de colunas da consulta. Por exemplo, na consulta SELECT Color, ListPrice, FROM Production.Product WHERE ProductID = ?, usa 0 para a coluna Color e 1 para a coluna ListPrice . A capacidade de usar o nome de uma coluna como nome de um conjunto de resultados depende do fornecedor para o qual a tarefa está configurada. Nem todos os fornecedores disponibilizam nomes de colunas.

Algumas consultas que retornam um único valor podem não incluir nomes de colunas. Por exemplo, a instrução SELECT COUNT (*) FROM Production.Product não devolve o nome da coluna. Pode aceder ao resultado de retorno usando a posição ordinal, 0, como nome do resultado. Para aceder ao resultado de retorno pelo nome da coluna, a consulta deve incluir uma cláusula AS<nome de alias> para fornecer um nome de coluna. A instrução SELECT COUNT (*)AS CountOfProduct FROM Production.Product, fornece a coluna CountOfProduct . Pode então aceder à coluna de retorno do resultado usando o nome da coluna CountOfProduct ou a posição ordinal, 0.

Se o tipo de conjunto de resultados for Full result set ou XML, deve usar 0 como nome do conjunto de resultados.

Quando mapear uma variável para um conjunto de resultados com o tipo de conjunto de resultados de linha única , a variável deve ter um tipo de dado compatível com o tipo de dados da coluna que o conjunto de resultados contém. Por exemplo, um conjunto de resultados que contém uma coluna com um tipo de dados String não pode mapear para uma variável com um tipo de dado numérico. Quando definir a propriedade TypeConversionMode para Permitido, a tarefa Executar SQL tentará converter os resultados do parâmetro de saída e da consulta para o tipo de dado da variável a que os resultados foram atribuídos.

Um conjunto de resultados XML só pode mapear para uma variável com o tipo de dados String ou Objeto. Se a variável tiver o tipo de dados String, a tarefa Executar SQL retorna dados do tipo string e a fonte XML pode consumir os dados XML. Se a variável tiver o tipo de dados Object, a tarefa Executar SQL devolve um objeto Document Object Model (DOM).

Um conjunto de resultados completo deve ser mapeado para uma variável do tipo de dados Objeto. O resultado de retorno é um objeto de conjunto de linhas. Pode usar um contentor Foreach Loop para extrair os valores das linhas da tabela que estão armazenados na variável Object em variáveis package, e depois usar uma tarefa Script para escrever os dados armazenados nas variáveis packages num ficheiro. Para uma demonstração de como fazer isto usando um container Foreach Loop e uma Script Task.

A tabela seguinte resume os tipos de dados das variáveis que podem ser mapeadas para conjuntos de resultados.

A variável pode ser definida no âmbito da tarefa Executar SQL ou do pacote. Se a variável tiver âmbito de pacote, o conjunto de resultados está disponível para outras tarefas e contentores dentro do pacote, e está disponível para quaisquer pacotes executados pelas tarefas Executar Pacote ou Executar Pacotes DTS 2000.

Quando se mapeia uma variável para um conjunto de resultados de linha única , valores não-string que a instrução SQL devolve são convertidos em strings quando as seguintes condições são cumpridas:

• A propriedade TypeConversionMode está definida como true. Define o valor da propriedade na janela de Propriedades ou usando o Editor de Tarefas Executar SQL.

• A conversão não resultará em truncamento de dados.

Mapear conjuntos de resultados para variáveis numa tarefa de Executar SQL

Esta secção descreve como criar um mapeamento entre um conjunto de resultados e uma variável numa tarefa Executar SQL. Mapear um conjunto de resultados para uma variável torna o conjunto disponível para outros elementos do pacote. Por exemplo, um script numa tarefa Script pode ler a variável e depois usar os valores do conjunto de resultados ou uma fonte XML pode consumir o conjunto de resultados armazenado numa variável. Se o conjunto de resultados for gerado por um pacote pai, o conjunto de resultados pode ser disponibilizado a um pacote filho chamado por uma tarefa "Executar Pacote", mapeando o conjunto de resultados para uma variável no pacote pai e depois criando uma configuração de variável de pacote pai no pacote filho para armazenar o valor da variável pai.

1. No SSDT (SQL Server Data Tools), abra o projeto Integration Services que contém o pacote desejado.

2. No Explorador de Soluções, clique duas vezes no pacote para o abrir.

3. Clique na guia Fluxo de controle .

4. Se o pacote ainda não incluir uma tarefa Executar SQL, adicione-a ao fluxo de controlo do pacote. Para obter mais informações, consulte Adicionar ou excluir uma tarefa ou um contêiner em um fluxo de controle.

5. Clique duas vezes na tarefa Executar SQL.

6. Na caixa de diálogo Executar Editor de Tarefas SQL, na página Geral, selecione o tipo Linha única, Conjunto de Resultados Completo ou Conjunto de Resultados XML.

7. Clique em Conjunto de Resultados.

8. Para adicionar um mapeamento de conjunto de resultados, clique em Adicionar.

9. Na lista de Nomes das Variáveis , selecione uma variável ou crie uma nova variável. Para mais informações, consulte Adicionar, Eliminar, Alterar o Escopo da Variável Definida pelo Utilizador num Pacote.

10. Na lista de Nomes de Resultados , opcionalmente, modifiquem o nome do conjunto de resultados.

    Em geral, pode usar o nome da coluna como nome do conjunto de resultados, ou pode usar a posição ordinal da coluna na lista de colunas como o conjunto de resultados. A capacidade de usar o nome de uma coluna como nome do conjunto de resultados depende do fornecedor para o qual a tarefa está configurada. Nem todos os fornecedores disponibilizam nomes de colunas.

11. Clique em OK.

Solucionar problemas da tarefa Executar SQL

Pode registar as chamadas que a tarefa Executar SQL faz para fornecedores de dados externos. Pode usar esta funcionalidade de registo para diagnosticar os comandos SQL que a tarefa Executar SQL executa. Para registar as chamadas que a tarefa Executar SQL faz a fornecedores de dados externos, ative o registo de pacotes e selecione o evento de diagnóstico ao nível do pacote. Para obter mais informações, consulte Ferramentas de solução de problemas para execução de pacotes.

Por vezes, um comando SQL ou procedimento armazenado devolve múltiplos conjuntos de resultados. Estes conjuntos de resultados incluem não só conjuntos de linhas resultantes de consultas SELECT , mas também valores únicos resultantes de erros de instruções RAISERROR ou PRINT . Se a tarefa ignora erros nos conjuntos de resultados que ocorrem após o primeiro conjunto de resultados depende do tipo de gestor de ligação utilizado:

• Quando usas gestores de ligações OLE DB e ADO, a tarefa ignora os conjuntos de resultados que ocorrem após o primeiro conjunto de resultados. Assim, com estes gestores de ligação, a tarefa ignora um erro devolvido por um comando SQL ou por um procedimento armazenado quando o erro não faz parte do primeiro conjunto de resultados.

• Quando usa os gestores de conexões ADO.NET e ODBC, esta tarefa não ignora conjuntos de resultados que aparecem após o primeiro conjunto. Com estes gestores de ligação, a tarefa falhará com um erro quando um conjunto de resultados, que não seja o primeiro, contiver um erro.

Entradas de Registo Personalizadas

A tabela seguinte descreve a entrada de registo personalizada para a tarefa Executar SQL. Para obter mais informações, consulte o Log de Serviços de Integração (SSIS) .