FUNCTIONPublished

TCSqlExec

TCSqlExec( <cComandoSQL> ) --> nRet

Executes an SQL command directly through TopConn/DBAccess.

SQLTopConnDBAccessDatabaseEssential functions

01 · OVERVIEW

Overview

TCSqlExec() runs SQL commands that do not return a query cursor, such as controlled update or maintenance statements. It should be used carefully because it bypasses part of the usual Protheus business-routine safeguards.

02 · SYNTAX

Syntax

TCSqlExec( <cComandoSQL> ) --> nRet

Parameters

cComandoSQL

CaracterRequired

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

Return value

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

03 · PRACTICAL EXAMPLE

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 nReturn := TCSqlExec(cSql)

    MsgInfo("SQL return: " + CValToChar(nReturn))
Return

Expected result

Runs an UPDATE restricted by key and shows the return code. Use only as a didactic example and validate in a test environment.

BEST PRACTICES

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.

COMMON PITFALLS

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.