cSqlExprCaractereObligatorio
Expresión SQL constante o variable ejecutada mediante TOPCONN.
COMANDOPublicado
TCQUERY
TCQUERY <cSqlExpr> ALIAS <cAlias> [NEW]Ejecuta una consulta SQL mediante la RDD TOPCONN y expone el resultado en un área de trabajo AdvPL.
Descripción general
TCQUERY ejecuta una expresión SQL en una base relacional mediante la RDD TOPCONN y abre el resultado con el alias informado. Durante la compilación se traduce en llamadas a DbUseArea() y TCGenQry(). Debe utilizarse NEW para abrir una nueva área de trabajo y evitar cerrar el área actual y cualquier tabla que ya esté abierta en ella.
Sintaxis
TCQUERY <cSqlExpr> ALIAS <cAlias> [NEW]Parámetros
ALIAS cAliasCaractereObligatorio
Nombre del área de trabajo donde se abre el resultado. Puede ser literal o expresión.
NEWCláusulaOpcional
Abre la consulta en una nueva WorkArea. La documentación oficial recomienda usarlo siempre para no cerrar el área actual.
Consulta con 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
La consulta usa el nombre físico de SA1, recibe ajustes de compatibilidad, abre una nueva WorkArea y cierra el alias al terminar.
Equivalencia conceptual del 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 la apertura con DbUseArea() y TCGenQry() y mantiene clara la intención del fuente.
- Incluye TopConn.ch para el comando; TOTVS.ch puede mantenerse como include general del fuente.
- Utiliza NEW en cada consulta nueva, salvo una razón técnica cuidadosamente controlada.
- Utiliza GetNextAlias() cuando la rutina pueda coexistir con otros alias o ejecutarse más de una vez.
- Utiliza RetSqlName() para obtener nombres físicos de tablas Protheus y filtra registros eliminados cuando corresponda.
- Pasa la instrucción por ChangeQuery() cuando necesites compatibilidad con los bancos homologados.
- Cierra explícitamente el alias al terminar, preferentemente en un flujo que también trate errores.
- Los campos de fecha o numéricos pueden requerir ajuste de tipo; consulta TCSetField() según el resultado y el banco.
- Sin NEW, TCQUERY utiliza la WorkArea actual y puede cerrar una tabla que ya estaba abierta.
- Los alias fijos pueden colisionar con otras rutinas; genera uno cuando sea necesario.
- No concatenes directamente entradas de usuarios, solicitudes o integraciones en SQL; valida los datos y usa mecanismos seguros disponibles.
- El SQL específico de un banco reduce la portabilidad; revisa funciones, concatenación, límites y conversiones.
- SELECT * aumenta el tráfico y el acoplamiento; solicita solo los campos necesarios.
- Olvidar DbCloseArea() mantiene recursos y un área de trabajo ocupados.
- Una consulta TOPCONN normalmente es de solo lectura; no supongas que puede editarse como una tabla común.