cSqlExprCaractereObrigatório
Expressão SQL, constante ou variável, que será executada pelo TOPCONN.
COMANDOPublicado
TCQUERY
TCQUERY <cSqlExpr> ALIAS <cAlias> [NEW]Executa uma consulta SQL pela RDD TOPCONN e disponibiliza o resultado em uma área de trabalho AdvPL.
Visão geral
O comando TCQUERY executa uma expressão SQL em um banco relacional por meio da RDD TOPCONN e abre o resultado no alias informado. Durante a compilação, ele é traduzido para chamadas de DbUseArea() e TCGenQry(). A cláusula NEW deve ser usada para abrir uma nova área de trabalho e evitar que a área atual — e uma tabela eventualmente aberta nela — seja fechada.
Sintaxe
TCQUERY <cSqlExpr> ALIAS <cAlias> [NEW]Parâmetros
ALIAS cAliasCaractereObrigatório
Nome da área de trabalho em que o resultado da consulta será aberto. Pode ser literal ou expressão.
NEWCláusulaOpcional
Abre a consulta em uma nova WorkArea. A documentação oficial recomenda utilizá-la sempre para evitar o fechamento involuntário da área corrente.
Consulta com alias dinâmico
#Include "TOTVS.ch"
#Include "TopConn.ch"
User Function ExTCQuery()
Local cAlias := GetNextAlias()
Local cQuery := ""
cQuery := "SELECT A1_COD, A1_NOME "
cQuery += "FROM " + RetSqlName("SA1") + " "
cQuery += "WHERE D_E_L_E_T_ = ' ' "
cQuery += "ORDER BY A1_COD"
cQuery := ChangeQuery(cQuery)
TCQUERY (cQuery) ALIAS (cAlias) NEW
While !(cAlias)->(Eof())
ConOut((cAlias)->A1_COD + " - " + ;
(cAlias)->A1_NOME)
(cAlias)->(DbSkip())
EndDo
(cAlias)->(DbCloseArea())
ReturnResultado esperado
A consulta usa o nome físico da SA1, recebe ajustes de compatibilidade, abre uma nova WorkArea e fecha o alias ao terminar.
Equivalência conceitual do comando
#Include "TopConn.ch"
// Forma recomendada pela legibilidade:
TCQUERY (cQuery) ALIAS QRY NEW
QRY->(DbCloseArea())
// Internamente, o comando combina operações equivalentes a:
// DbUseArea(.T., "TOPCONN", ;
// TCGenQry(,, cQuery), "QRY", .T., .T.)Resultado esperado
TCQUERY simplifica a abertura realizada com DbUseArea() e TCGenQry(), mantendo clara a intenção do fonte.
- Inclua TopConn.ch para disponibilizar o comando; TOTVS.ch pode ser mantido como include geral do fonte.
- Use NEW em todas as novas consultas, salvo uma razão técnica cuidadosamente controlada.
- Use GetNextAlias() quando a rotina puder coexistir com outros aliases ou ser chamada mais de uma vez.
- Use RetSqlName() para obter o nome físico de tabelas do Protheus e filtre registros excluídos quando aplicável.
- Passe a instrução por ChangeQuery() quando precisar adequá-la aos bancos homologados pelo Protheus.
- Feche o alias explicitamente ao terminar, preferencialmente em um fluxo que também trate erros.
- Campos de data ou numéricos podem exigir ajuste de tipo após a abertura; consulte TCSetField() conforme o resultado e o banco.
- Sem NEW, TCQUERY usa a WorkArea atual e pode fechar uma tabela que já estava aberta.
- Aliases fixos podem colidir com áreas abertas por outra rotina; prefira um alias gerado quando necessário.
- Não concatene diretamente textos recebidos de usuário, requisição ou integração na instrução SQL; valide a entrada e utilize mecanismos seguros disponíveis no contexto.
- SQL específico de um único banco reduz a portabilidade; revise funções, concatenação, limites e conversões.
- SELECT * aumenta tráfego e acoplamento; liste apenas os campos necessários.
- Esquecer DbCloseArea() mantém recursos e a área de trabalho ocupados.
- Uma consulta aberta pelo TOPCONN é normalmente usada para leitura; não presuma que o resultado possa ser editado como uma tabela comum.