Acessar consultas pela AL
As consultas podem ser uma substituição efetiva para acesso iterativo a dados no Business Central, especialmente quando você usa várias iterações de dados aninhadas no código AL. Um objeto Consulta inclui um conjunto de funções AL que você pode usar para acessar dados, filtrar o conjunto de dado resultante de uma consulta ou exportar o conjunto de dados resultante para o formato CSV ou XML usando fluxos.
Você pode executar uma consulta AL para iterar através do conjunto de dados resultante por meio de programação. Embora os princípios de acesso a uma consulta se assemelhem ao acesso a tabelas, um conjunto diferente de funções existe em um objeto de consulta.
Função Abrir
A função Abrir executa um objeto de consulta e gera um conjunto de dados que pode ser lido. Ele também coloca a consulta no estado de leitura.
A função Abrir retorna um valor booliano, que indica se a consulta foi aberta com êxito ou não. Se você omitir esse valor de retorno opcional e se a consulta não abrir com êxito, ocorrerá um erro em tempo de execução. Se você incluir um valor de retorno, nenhum erro em tempo de execução ocorrerá quando a função for chamada e você tratará os erros.
Se a função Abrir falhar, não será possível chamar outras funções nem acessar os dados na consulta. Se você tentar concluir esta ação, ocorrerá um erro em tempo de execução. A função Abrir somente executa o objeto de consulta e gera um conjunto de dados; ele não retorna a primeira linha do conjunto de resultados. Para acessar qualquer linha, você deve chamar a função Ler.
Função Ler
A função Ler lê uma única linha do conjunto de resultados de uma consulta. A função retorna um valor booliano que indica se uma linha foi recuperada. Quando você chama a função Ler, a próxima linha na consulta de conjunto de dados é recuperada.
Quando a consulta está no estado de leitura, você pode acessar os valores das colunas na linha da mesma maneira que acessa os campos em uma variável de registro.
Você pode chamar a função Ler várias vezes após a função Abrir para ler linhas consecutivas no conjunto de dados. A primeira chamada da função Ler recupera a primeira linha do conjunto de dados resultante. Cada chamada sucessiva da função Ler recupera a próxima linha do conjunto de dados resultante.
Função Fechar
A função Fechar fecha um conjunto de dados de uma consulta e retorna a consulta ao estado inicializado. Ele permite que o Business Central Server saiba que você terminou de usar este objeto.
Chamar a função Fechar explicitamente é opcional. Esta função é chamada implicitamente em qualquer uma das seguintes situações:
Quando a variável da consulta sai do escopo
Se você chamar a função Abrir em uma variável de consulta que está aberta no momento
Se você chamar a função SetFilter ou SetRange em uma variável de consulta que está aberta no momento
A função Fechar não limpa nenhum filtro definido por você na consulta programaticamente. Se você quiser limpar esses filtros, chame a função Limpar.
begin
if SimpleItemQuery.Open() then begin
while SimpleItemQuery.Read() do begin
// Enter some logic
end;
SimpleItemQuery.Close();
end;
end;
Acesso à coluna
Em uma variável de consulta, você pode acessar as colunas de uma consulta de uma maneira semelhante a acessar os campos de uma tabela em uma variável de registro. Quando você lê valores de colunas em AL, pode fazer referência a colunas exatamente como faria para fazer referência a campos de registro.
O exemplo a seguir mostra como ler um valor da coluna preço da consulta de item simples (acessando uma coluna de uma consulta da AL).
begin
if SimpleItemQuery.Open() then begin
while SimpleItemQuery.Read() do begin
ItemPrice := SimpleItemQuery.Price;
// Do some logic
end;
SimpleItemQuery.Close();
end;
end;
Programaticamente, você só pode acessar essas colunas que foram definidas na consulta, mas não os outros campos que existem nas tabelas das quais a consulta é construída.
Consultas de Filtro
Você pode filtrar os dados em consultas para restringir os conjuntos de valores resultantes. Você só pode filtrar uma consulta em um campo incluído como uma coluna ou um filtro na consulta. Você pode usar as funções SetRange e SetFilter para definir filtros em uma variável de consulta.
Ao usar as funções SetFilter e SetRange para definir um filtro no mesmo campo que já está filtrado por meio da propriedade ColumnFilter no criador de consultas, o filtro definido na propriedade ColumnFilter é substituído pelo filtro definido no código AL.
Se você usa as funções SetFilter ou SetRange no mesmo campo que está incluído na propriedade DataItemTableFilter de um item de dados, o filtro da função e o filtro da propriedade DataItemTableFilter serão combinados.
O exemplo a seguir mostra como usar as funções SetFilter e SetRange para filtrar o conjunto de resultados de uma consulta.
PendingProdOrders.SetRange(Status, 1, 3);
PendingProdOrders.SetFilter("Due_Date", '>0D|<%1', WorkDate());
if PendingProdOrders.Open() then
while PendingProdOrders.Read() do begin
Item.Get(PendingProdOrders."Item_No");
Item.TestField(Blocked, false);
end;
PendingProdOrders.Close();
Como nenhum dado é recuperado antes de a consulta ser aberta, a referência a colunas de qualquer forma, incluindo a especificação de valores de funções de filtragem, não é permitida. Portanto, neste exemplo, a função SetRange é chamada na coluna status, fornecendo o inteiro em vez de valores de opção. Se você especificar o intervalo usando valores de opção antes de a consulta ser aberta, ocorrerá um erro em tempo de execução.
Chamar SetRange ou SetFilter em uma consulta que já está aberta fechará automaticamente a consulta. Para acessar dados de tal consulta, você deve verificar se está usando uma chamada Abrir antes de Ler. A prática recomendada é definir filtros antes de a primeira chamada Abrir e fechar a consulta chamando Fechar imediatamente depois que todas as linhas forem lidas.
Você pode ter várias chamadas para a função SetFilter. Se SetFilter chamar definir filtros em colunas diferentes, os filtros serão combinados e aplicados ao conjunto de dados. Se chamadas de função SetFilter consecutivas definirem filtros na mesma coluna, a última SetFilter será aplicada à coluna.
Função TopNumberOfRows
Ao criar uma consulta, você pode definir o limite para o número de linhas que a consulta retorna especificando sua propriedade TopNumberOfRows na janela designer de consulta. Em tempo de execução, você pode verificar ou alterar o valor dessa propriedade usando a função TopNumberOfRows. Se você limitar o número de linhas definindo a propriedade TopNumberOfRows, a função TopNumberOfRows sobrescreverá a propriedade TopNumberOfRows.
Se o valor da propriedade TopNumberOfRows for indefinido, a função TopNumberOfRows retornará zero (0). Se você definir TopNumberOfRows como zero (0), todas as linhas serão retornadas.
O código a seguir mostra como limitar programaticamente o número de linhas que são retornadas de uma consulta para 10 linhas.
SimpleItemQuery.TopNumberOfRows := 10;
Você pode chamar a filtragem e as funções TopNumberOfRows na variável CurrQuery do gatilho OnBeforeOpen no objeto de consulta. A variável CurrQuery é implícita no código AL do objeto da consulta; você não precisa referenciá-la diretamente.
Funções SaveAsXml e SaveAsCsv
Você pode salvar o conjunto de resultados da consulta em um arquivo externo da AL. Você pode usar a função SaveAsCsv para salvar os resultados em um arquivo de valores separados por vírgula (CSV) e usar SaveAsXml para salvar os resultados em um arquivo XML.
Você sempre pode chamar SaveAsCsv e SaveAsXml diretamente sem antes chamar AbrirLer ou Fechar. Quando SaveAsCsv ou SaveAsXml são chamadas, a consulta é aberta, lida e fechada implicitamente. Se você chamar SaveAsCsv ou SaveAsXml em uma consulta que já está aberta, o conjunto de dados será recuperado primeiro do banco de dados do Business Central. Depois que o conjunto de dados é salvo no arquivo, a consulta é deixada no estado fechado, o que faz qualquer chamada posterior à Ler inválida. Você deve reabrir a consulta para continuar a leitura dos dados.
Uma prática recomendada a ser seguida é sempre chamar as funções SaveAsCsv ou SaveAsXml em variáveis separadas. Nunca as chamam em variáveis usadas para iterar por meio do conjunto de resultados.
As funções SaveAsCsv e SaveAsXml retornam um valor booliano que indica se a consulta foi salva ou não com êxito. Se você omitir esse valor de retorno opcional e se a consulta não salvar com êxito, ocorrerá um erro em tempo de execução.
O exemplo a seguir mostra como exportar um número superior de linhas no conjunto de registros resultante de uma consulta para um arquivo XML. É necessário usar fluxos para salvar o arquivo porque, em um ambiente SaaS, você não tem acesso ao sistema de arquivos.
procedure GetTop10ProdOrdersXml()
var
Top10ProdOrders: Query "Top-10 Prod. Orders - by Cost";
TempBlob: Codeunit "Temp Blob";
FileNotSavedMsg: Label 'The file was not saved. The problem was %1';
OutStr: OutStream;
InStr: InStream;
FileName: Text;
begin
TempBlob.CreateOutStream(OutStr);
Top10ProdOrders.TopNumberOfRows(5);
if not Top10ProdOrders.SaveAsXml(OutStr) then
Error(FileNotSavedMsg, GetLastErrorText());
TempBlob.CreateInStream(InStr);
FileName := 'top_10_prod_orders.xml';
File.DownloadFromStream(InStr, 'Top 10 Prod. Orders XML', '', '', FileName);
end;
Diferentemente dos arquivos XML que são exportados dos XMLports, a estrutura dos arquivos XML criados pela função SaveAsXml sempre segue a mesma estrutura fixa. Os dados no documento XML resultante não pertencem a um namespace, o elemento raiz é sempre <DataSet>, e cada linha é representada como um elemento <Result>. As colunas são representadas como elementos filho do elemento <Result>. O nome de cada elemento que representa uma coluna é igual ao nome da coluna, conforme especificado na propriedade Nome. O esquema XSD que descreve o formato do arquivo XML resultante é incorporado ao arquivo.
Um arquivo CSV armazena os dados em um formato de texto simples. Os arquivos criados por meio da função SaveAsCsv parecem com os arquivos de formato de texto variável que são exportados de um XMLport. Cada linha de dados em um arquivo CSV reside em uma linha separada. A primeira linha de um arquivo CSV criado por meio da SaveAsCsv sempre contém os nomes de coluna da consulta. Os nomes de coluna são especificados na propriedade Nome de cada coluna na definição da consulta.
Os arquivos CSV seguem um conjunto fixo de regras que simplificam a sua capacidade de importá-los em outros aplicativos, como o Microsoft Excel.