COMANDOPublicado

TCQUERY

TCQUERY <cSqlExpr> ALIAS <cAlias> [NEW]

Executa uma consulta SELECT pela RDD TOPCONN e abre o resultado em uma WorkArea AdvPL.

Banco de dadosSQLTOPCONNQueryAliasWorkAreaDQL

01 · VISÃO GERAL

Visão geral

TCQUERY abre o resultado de uma consulta SQL de leitura em um alias AdvPL usando a RDD TOPCONN. O comando é traduzido em compilação para operações baseadas em DbUseArea() e TCGenQry(). A cláusula NEW deve ser preferida para criar uma nova WorkArea e evitar o fechamento involuntário da área corrente. O cursor resultante é voltado à leitura sequencial e não deve ser tratado como uma tabela ISAM editável.

02 · SINTAXE

Sintaxe

TCQUERY <cSqlExpr> ALIAS <cAlias> [NEW]

Parâmetros

cSqlExpr

CaractereObrigatório

Expressão, constante ou variável caractere contendo uma consulta SELECT a ser executada pelo TOPCONN.

ALIAS cAlias

CaractereObrigatório

Nome do alias em que o result set será aberto. Pode ser literal ou expressão.

NEW

CláusulaOpcional

Abre a consulta em uma nova WorkArea. A documentação oficial recomenda seu uso para evitar o fechamento da área corrente.

Retorno

Não retorna um valor diretamente. O resultado da consulta fica disponível no alias informado como um cursor de leitura.

03 · EXEMPLO PRÁTICO

Consulta portável com alias dinâmico

#Include "TOTVS.ch"
#Include "TopConn.ch"

User Function ExTCQuery()
    Local cAlias := GetNextAlias()
    Local cQuery := ""

    // A1_COD = código, A1_NOME = nome e A1_FILIAL = filial.
    // D_E_L_E_T_ é o campo técnico de controle de exclusão lógica.
    cQuery := "SELECT A1_COD, A1_NOME "
    cQuery += "FROM " + RetSqlName("SA1") + " "
    cQuery += "WHERE A1_FILIAL = '" + xFilial("SA1") + "' "
    cQuery += "AND D_E_L_E_T_ = ' ' "
    cQuery += "ORDER BY A1_COD"

    // ChangeQuery() adapta a instrução aos bancos homologados quando necessário.
    cQuery := ChangeQuery(cQuery)

    // NEW preserva a WorkArea que estava corrente antes desta consulta.
    TCQUERY (cQuery) ALIAS (cAlias) NEW

    While !(cAlias)->(Eof())
        ConOut((cAlias)->A1_COD + " - " + (cAlias)->A1_NOME)
        (cAlias)->(DbSkip())
    EndDo

    // O alias da query ocupa uma WorkArea e deve ser fechado ao terminar.
    (cAlias)->(DbCloseArea())
Return

Resultado esperado

A consulta usa o nome físico da SA1, filtra filial e exclusão lógica, abre um alias dinâmico em nova WorkArea e libera o cursor ao final.

04 · EXEMPLO PRÁTICO

O que o comando abstrai

#Include "TopConn.ch"

// Forma mais legível para abrir a consulta:
TCQUERY (cQuery) ALIAS QRY NEW
QRY->(DbCloseArea())

// Conceitualmente, TCQUERY combina a abertura TOPCONN com TCGenQry().
// A implementação interna pode evoluir; use a sintaxe documentada do comando.

Resultado esperado

TCQUERY expressa de forma direta a intenção de abrir uma consulta como WorkArea, evitando que o código de aplicação dependa dos detalhes da abertura.

BOAS PRÁTICAS

Inclua TopConn.ch para disponibilizar o comando; TOTVS.ch pode permanecer como include geral do fonte.
Use NEW salvo quando houver uma razão técnica específica e controlada para reutilizar a WorkArea corrente.
Prefira GetNextAlias() quando a rotina puder coexistir com outros aliases ou executar mais de uma vez.
Use RetSqlName() para nomes físicos de tabelas Protheus, xFilial() quando aplicável e filtre D_E_L_E_T_ em tabelas com exclusão lógica.
Use ChangeQuery() quando a instrução precisar ser adequada aos bancos homologados.
Selecione apenas os campos necessários e feche o alias explicitamente ao concluir o processamento.
Quando valores externos precisarem ser parametrizados, avalie FWPreparedStatement/FWExecStatement em vez de concatená-los diretamente no SQL.

ARMADILHAS COMUNS

Sem NEW, a abertura pode reutilizar a WorkArea corrente e fechar uma tabela que já estava aberta nela.
TCQUERY é destinado a consultas de leitura iniciadas por SELECT. Para DML/DDL, use o mecanismo apropriado, como TCSqlExec(), conforme a documentação oficial.
O cursor de query não deve ser tratado como uma tabela ISAM comum: não conte com edição, DbSkip(-1), DbGoBottom() ou LastRec() para representar a quantidade de linhas.
DbGoTop() em um cursor de query pode fechar e reabrir o cursor, submetendo novamente a consulta ao banco.
Aliases fixos podem colidir com áreas já abertas por outras rotinas.
SQL específico de um único banco reduz portabilidade.
Não concatene diretamente entrada não confiável no SQL quando houver alternativa de parametrização.

Conteúdos relacionados

REFERÊNCIAS

Situação: Publicado
Página criada em: 02/08/2026 às 15:18
Última revisão em: 29/08/2026 às 23:27
Idioma original: Português
Revisão: Usina.BR