FUNCIóNPublicado

TCSqlExec

TCSqlExec( <cComandoSQL> ) --> nRet

Ejecuta un comando SQL directamente mediante TopConn/DBAccess.

SQLTopConnDBAccessBase de datosFunciones esenciales

01 · DESCRIPCIÓN GENERAL

Descripción general

TCSqlExec() ejecuta comandos SQL que no devuelven cursor de consulta, como actualizaciones o mantenimiento controlado. Debe usarse con criterio porque evita parte de las protecciones habituales de las rutinas de negocio de Protheus.

02 · SINTAXIS

Sintaxis

TCSqlExec( <cComandoSQL> ) --> nRet

Parámetros

cComandoSQL

CaracterObligatorio

Comando SQL enviado ao banco de dados por meio do DBAccess/TopConn.

Retorno

Numérico. Retorna o código de execução informado pela camada TopConn/DBAccess; valide o comportamento no ambiente e versão utilizados.

03 · EJEMPLO PRÁCTICO

Executar comando SQL controlado

#Include "TOTVS.ch"

User Function ExTCSqlExec()
    Local cSql := "UPDATE " + RetSqlName("SA1") + " SET A1_XOBS = 'OK' WHERE D_E_L_E_T_ = ' ' AND A1_COD = '000001'"
    Local nRetorno := TCSqlExec(cSql)

    MsgInfo("Retorno SQL: " + CValToChar(nRetorno))
Return

Resultado esperado

Ejecuta un UPDATE restringido por clave y muestra el código de retorno. Úsalo solo como ejemplo didáctico y valida en homologación.

BUENAS PRÁCTICAS

Use TCSqlExec() para comandos SQL sem cursor de retorno.
Para leitura de dados, prefira TCQUERY quando a intenção for percorrer um resultado.
Em tabelas Protheus, respeite filial, D_E_L_E_T_ e regras de negócio antes de escrever diretamente.

ERRORES COMUNES

Evite montar SQL com concatenação de dados de usuário sem tratamento.
Não use para atualizar tabelas de negócio quando existir API, rotina ou mecanismo oficial mais seguro.
Teste em homologação: um comando SQL direto pode afetar muitos registros rapidamente.

Contenido relacionado

REFERENCIAS

RXM Tecnologia. 20 funciones AdvPL esenciales que todo desarrollador Protheus usa. Mayo de 2026.

Estado: Publicado
Página creada el: 03/09/2026 a las 10:15
Última revisión el: 03/09/2026 a las 10:15
Idioma original: Portugués
Revisión: Usina.BR