COMANDOPublicado

TCQUERY

TCQUERY <cSqlExpr> ALIAS <cAlias> [NEW]

Ejecuta una consulta SELECT mediante la RDD TOPCONN y abre el resultado en una WorkArea AdvPL.

Base de datosSQLTOPCONNQueryAliasWorkAreaDQL

01 · DESCRIPCIÓN GENERAL

Descripción general

TCQUERY abre el resultado de una consulta SQL de lectura en un alias AdvPL mediante la RDD TOPCONN. Durante la compilación, el comando se traduce en operaciones basadas en DbUseArea() y TCGenQry(). Se debe preferir NEW para crear una nueva WorkArea y evitar cerrar involuntariamente el área actual. El cursor resultante está orientado a lectura secuencial y no debe tratarse como una tabla ISAM editable.

02 · SINTAXIS

Sintaxis

TCQUERY <cSqlExpr> ALIAS <cAlias> [NEW]

Parámetros

cSqlExpr

CarácterObligatorio

Expresión, constante o variable de caracteres que contiene una consulta SELECT que será ejecutada por TOPCONN.

ALIAS cAlias

CarácterObligatorio

Nombre del alias donde se abrirá el result set. Puede ser un literal o una expresión.

NEW

CláusulaOpcional

Abre la consulta en una nueva WorkArea. La documentación oficial recomienda su uso para evitar cerrar el área actual.

Retorno

No devuelve directamente un valor. El resultado de la consulta queda disponible en el alias informado como cursor de lectura.

03 · EJEMPLO PRÁCTICO

Query portable con alias dinámico

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

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

    // A1_COD significa “Código”, A1_NOME significa “Nombre” y A1_FILIAL significa “Sucursal”.
    // D_E_L_E_T_ es el campo técnico utilizado para controlar la eliminación 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 la instrucción a las bases homologadas cuando sea necesario.
    cQuery := ChangeQuery(cQuery)

    // NEW preserva la WorkArea que estaba activa antes de esta consulta.
    TCQUERY (cQuery) ALIAS (cAlias) NEW

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

    // El alias de la query ocupa una WorkArea y debe cerrarse al finalizar.
    (cAlias)->(DbCloseArea())
Return

Resultado esperado

La query usa el nombre físico de SA1, filtra sucursal y eliminación lógica, abre un alias dinámico en una nueva WorkArea y libera el cursor al finalizar.

04 · EJEMPLO PRÁCTICO

Qué abstrae el comando

#Include "TopConn.ch"

// Forma más legible para abrir la query:
TCQUERY (cQuery) ALIAS QRY NEW
QRY->(DbCloseArea())

// Conceptualmente, TCQUERY combina la apertura TOPCONN con TCGenQry().
// La implementación interna puede evolucionar; utiliza la sintaxis documentada.

Resultado esperado

TCQUERY expresa directamente la intención de abrir una query como WorkArea sin hacer que el código de aplicación dependa de los detalles de apertura.

BUENAS PRÁCTICAS

Incluye TopConn.ch para disponer del comando; TOTVS.ch puede permanecer como include general del fuente.
Usa NEW salvo que exista una razón técnica específica y controlada para reutilizar la WorkArea actual.
Prefiere GetNextAlias() cuando la rutina pueda coexistir con otros aliases o ejecutarse más de una vez.
Usa RetSqlName() para nombres físicos de tablas Protheus, xFilial() cuando corresponda y filtra D_E_L_E_T_ en tablas con eliminación lógica.
Usa ChangeQuery() cuando la instrucción necesite adaptación a las bases homologadas.
Selecciona solo los campos necesarios y cierra explícitamente el alias al finalizar.
Cuando valores externos necesiten parametrización, considera FWPreparedStatement/FWExecStatement en lugar de concatenarlos directamente en SQL.

ERRORES COMUNES

Sin NEW, la apertura puede reutilizar la WorkArea actual y cerrar una tabla que ya estaba abierta allí.
TCQUERY está destinado a consultas de lectura que comienzan con SELECT. Para DML/DDL, utiliza el mecanismo apropiado, como TCSqlExec(), según la documentación oficial.
Un cursor de query no es una tabla ISAM común: no cuentes con edición, DbSkip(-1), DbGoBottom() o LastRec() para representar la cantidad de filas.
DbGoTop() en un cursor de query puede cerrar y volver a abrir el cursor, enviando nuevamente la consulta a la base.
Los aliases fijos pueden colisionar con áreas abiertas por otras rutinas.
El SQL específico de una sola base reduce la portabilidad.
No concatenes directamente entradas no confiables en SQL cuando exista parametrización.

Contenido relacionado

REFERENCIAS

Estado: Publicado
Página creada el: 02/08/2026 a las 15:18
Última revisión el: 29/08/2026 a las 23:27
Idioma original: Portugués
Revisión: Usina.BR