%table:ALIAS%SubstituiçãoOpcional
Resolve o nome físico da tabela Protheus correspondente ao alias informado.
FUNDAMENTOPublicado
Embedded SQL em AdvPL
BeginSql Alias <cAlias> ... EndSqlEscreva consultas SQL legíveis diretamente no fonte AdvPL, usando substituições do pré-compilador, filtros de filial e exclusão lógica e conversão declarativa de tipos.
Visão geral
Embedded SQL permite escrever o SELECT diretamente entre BeginSql e EndSql. Durante a compilação e a execução, expressões especiais delimitadas por % são transformadas para integrar a consulta ao Protheus e ao DBAccess. Entre os recursos documentados estão %table, %xfilial, %exp, %notDel, %Order, column ... as Date/Logic/Numeric e %noparser%. Por padrão, a consulta passa por ChangeQuery(); o alias aberto deve ser fechado ao final do processamento.
Sintaxe
BeginSql Alias <cAlias> ... EndSqlParâmetros
%xfilial:ALIAS%SubstituiçãoOpcional
Resolve a filial corrente adequada à tabela informada.
%exp:expressão%ExpressãoOpcional
Insere na consulta o valor de uma variável ou expressão AdvPL compatível.
%notDel%SubstituiçãoOpcional
Gera a condição de exclusão lógica baseada em D_E_L_E_T_.
%Order:ALIAS%SubstituiçãoOpcional
Converte a expressão de índice AdvPL para uma cláusula SQL de ordenação.
column <campo> as <tipo>ConversãoOpcional
Declara a conversão de campos Date, Logic ou Numeric do result set para tipos AdvPL.
%noparser%ControleOpcional
Impede que a consulta passe por ChangeQuery() antes de ser enviada ao banco. Use apenas quando houver motivo técnico claro.
Retorno
Abre o cursor da consulta no alias indicado em BeginSql. O result set deve ser percorrido como uma WorkArea de consulta e fechado com DbCloseArea() quando não for mais necessário.
Consulta básica com tabela, filial e exclusão lógica
#Include "TOTVS.ch"
User Function ExEmbedded()
Local cAlias := GetNextAlias()
Local cCodigo := "000001"
// Embedded SQL evita concatenar trechos de texto para formar o SELECT.
BeginSql Alias cAlias
SELECT A1_COD, A1_NOME
FROM %table:SA1% SA1
WHERE A1_FILIAL = %xfilial:SA1%
AND A1_COD = %exp:cCodigo%
AND SA1.%notDel%
EndSql
While !(cAlias)->(Eof())
ConOut((cAlias)->A1_COD + " - " + (cAlias)->A1_NOME)
(cAlias)->(DbSkip())
EndDo
// O cursor aberto pelo BeginSql deve ser fechado ao final.
(cAlias)->(DbCloseArea())
ReturnResultado esperado
A consulta resolve a tabela física, filial, valor de código e exclusão lógica sem montar manualmente uma string SQL.
Conversão declarativa de campo de data
#Include "TOTVS.ch"
User Function ExEmbeddedData()
Local cAlias := GetNextAlias()
Local cPrefixo := "NF"
BeginSql Alias cAlias
column E2_EMISSAO as Date
SELECT E2_PREFIXO, E2_NUM, E2_EMISSAO
FROM %table:SE2% SE2
WHERE E2_FILIAL = %xfilial:SE2%
AND E2_PREFIXO = %exp:cPrefixo%
AND SE2.%notDel%
EndSql
While !(cAlias)->(Eof())
// E2_EMISSAO já é disponibilizado como data AdvPL.
ConOut((cAlias)->E2_PREFIXO + " - " + DToC((cAlias)->E2_EMISSAO))
(cAlias)->(DbSkip())
EndDo
(cAlias)->(DbCloseArea())
ReturnResultado esperado
A declaração column substitui o tratamento manual posterior do tipo do campo retornado.
Inspecionando a query executada com GetLastQuery()
#Include "TOTVS.ch"
User Function ExLastQuery()
Local cAlias := GetNextAlias()
Local aInfo := {}
BeginSql Alias cAlias
SELECT A1_COD, A1_NOME
FROM %table:SA1% SA1
WHERE A1_FILIAL = %xfilial:SA1%
AND SA1.%notDel%
EndSql
// GetLastQuery() permite inspecionar a consulta efetivamente aberta.
aInfo := GetLastQuery()
ConOut(aInfo[2]) // SQL executado
(cAlias)->(DbCloseArea())
ReturnResultado esperado
GetLastQuery()[2] permite observar a string SQL executada; o retorno completo também contém alias, conversões, indicação de parser e tempo de abertura do cursor.
- Use %table:ALIAS% em vez de fixar o nome físico da tabela no SQL.
- Use %xfilial:ALIAS% e %notDel% quando a regra da consulta exigir filial corrente e exclusão lógica.
- Use %exp:variável% para inserir valores AdvPL no Embedded SQL e evite montar a consulta por concatenação quando a sintaxe embedded já atende ao caso.
- Declare com column os campos que precisem ser convertidos para Date, Logic ou Numeric no result set.
- Feche sempre o alias aberto pelo BeginSql ao terminar o processamento.
- Use GetLastQuery() após a abertura do cursor quando precisar inspecionar a consulta efetivamente executada e o tempo gasto para abri-la.
- Quando a consulta ou os valores precisarem conter o caractere ?, avalie FWPreparedStatement/FWExecStatement conforme a recomendação oficial.
- Não coloque funções diretamente no meio do bloco Embedded SQL quando a sintaxe exigir uma expressão pré-calculada; armazene o valor em uma variável antes do BeginSql.
- O caractere ? é reservado no processamento do Embedded SQL e pode causar não conformidades quando aparece na query ou nos valores substituídos.
- Não use %noparser% por conveniência: ele desativa o tratamento padrão por ChangeQuery().
- Breakpoints dentro do bloco BeginSql/EndSql não funcionam como em código AdvPL comum; coloque pontos de parada antes ou depois do bloco.
- Se a compilação apontar erro em EndSql, verifique também alinhamento, espaços e tabulações anteriores à instrução conforme a documentação da versão utilizada.
- Um alias já aberto pode provocar erro ao executar a consulta com o mesmo nome.
Comentários
Ainda não há comentários aprovados.
Entre com Google ou Microsoft para comentar.