advpl-advanced — Tópicos avançados ADVPL

advpl-advanced — Tópicos avançados ADVPL

ADVPL avançado cobre o que vai além do CRUD MVC básico: transações ACID, relatórios estruturados (TReport), manipulação de arquivos em massa (SPED, EDI), captura de informações multi-linha (grids dinâmicas fora de MVC), threads paralelas, OOP clássico, e técnicas de programação eficiente.

Quando usar

• Usuário pede "relatório", "TReport", "impressão", "PDF", "Excel".
• Necessidade de Begin Transaction / BeginTran (gravações atômicas multi-tabela).
• Manipulação de arquivos texto (.csv, .txt, layouts SPED/EDI/SEFAZ) com FCreate/FOpen/FRead/FWrite ou FT_FUse/FT_FReadLn (família 2).
• Telas com grids dinâmicas (MsNewGetDados, TCBrowse) fora do contexto MVC.
• Performance de loops, arredondamento financeiro (NoRound), I/O bulk.
• Threads paralelas com MsRunInThread (cuidado com WorkArea por thread).
• OOP em ADVPL clássico (Class ... Method ... EndClass).
• Migrações de código Modelo1/Modelo2/Modelo3/AxCadastro (legacy) → MVC moderno.

Transações — Begin Transaction × BeginTran

Begin Transaction
    RecLock("SC5", .T.)
    SC5->C5_NUM     := cNumPed
    SC5->C5_FILIAL  := xFilial("SC5")
    SC5->C5_CLIENTE := cCli
    SC5->(MsUnlock())

    RecLock("SC6", .T.)
    SC6->C6_FILIAL := xFilial("SC6")
    SC6->C6_NUM    := cNumPed
    SC6->C6_ITEM   := "01"
    SC6->(MsUnlock())

    If lErroNaValidacao
        DisarmTransaction()   // forca rollback explicito
        Break                  // sai do bloco
    EndIf
End Transaction

• Begin Transaction é multi-tabela ACID — garante atomicidade.
• BeginTran/EndTran é forma alternativa (mais rara).
• DisarmTransaction() antes do Break força rollback explícito.
• NUNCA abra UI (MsgInfo, Pergunte, MsgBox) dentro de transação — trava o banco com lock segurando.

Veja [[advpl-code-review]] regra BP-002 (impl: BEGIN TRANSACTION sem END) e [[advpl-refactoring]] padrão 6.

TReport — relatórios estruturados (substitui SetPrint/RptStatus legacy)

#include "TOTVS.CH"
#include "TBICONN.CH"
#include "TOPCONN.CH"
#include "RPTDEF.CH"

User Function ZRel01()
    Local oReport := Nil

    oReport := TReport():New( ;
        "ZREL01",;                                 // ID
        "Relatorio de Clientes",;                  // titulo
        "ZREL01",;                                 // pergunta SX1 (opcional)
        {|oReport| ReportPrint(oReport)},;         // callback
        "Lista clientes por grupo")                 // descricao

    DefineSecoes(oReport)
    oReport:PrintDialog()                          // abre dialog de impressao
Return Nil

Static Function DefineSecoes(oReport)
    Local oSec1 := TRSection():New(oReport, "Clientes", {"SA1"})
    TRCell():New(oSec1, "A1_COD",    "SA1", "Codigo", "@!", 6)
    TRCell():New(oSec1, "A1_NOME",   "SA1", "Nome",   "@!", 30)
    TRCell():New(oSec1, "A1_GRUPO",  "SA1", "Grupo",  "@!", 6)
Return Nil

Static Function ReportPrint(oReport)
    Local oSec1 := oReport:Section(1)
    oSec1:Init()
    DbSelectArea("SA1")
    DbGoTop()
    While !Eof()
        oSec1:PrintLine()
        SA1->(DbSkip())
    EndDo
    oSec1:Finish()
Return Nil

Saída: PDF / Excel / CSV / TXT / HTML nativo (usuário escolhe no dialog).

TReport (singular) é a API canônica. TReports (plural) era uma classe anterior, hoje em desuso. Veja diferença TReports vs TReport.

FWTemporaryTable — tabelas temporárias

Para queries complexas que precisam de tabela intermediária sem poluir SQL nativo (e sem CREATE TABLE direto que viola padrão):

Local oTmp := FWTemporaryTable():New("TMP")
oTmp:SetFields({ ;
    {"COD",  "C", 6,  0}, ;
    {"DESC", "C", 30, 0}, ;
    {"VLR",  "N", 14, 2}, ;
    {"DT",   "D", 8,  0} ;
})
oTmp:AddIndex("01", {"COD"})
oTmp:Create()

// usa "TMP" como alias normal
DbSelectArea("TMP")
RecLock("TMP", .T.)
TMP->COD  := "001"
TMP->VLR  := 100.50
TMP->(MsUnlock())

// no fim, sempre limpar
oTmp:Delete()

Tabela existe só durante a sessão. Garbage collection automático no :Delete().

Manipulação de arquivos texto

Duas famílias:

Família 1 — FCreate/FOpen/FRead/FWrite/FClose (baixo nível)

Local nHnd := FCreate("\system\out.txt")
If nHnd < 0
    ConOut("Erro FCreate: " + cValToChar(FError()))
    Return
EndIf
FWrite(nHnd, "Linha 1" + Chr(13) + Chr(10))
FWrite(nHnd, "Linha 2" + Chr(13) + Chr(10))
FClose(nHnd)

Use Família 1 para arquivos binários ou pequenos. Sempre cheque retorno < 0 (erro).

Família 2 — FT_FUse/FT_FReadLn/FT_FGoTop/FT_FEof (eficiente, GB-scale)

Local nHnd := FT_FUse("\system\sped.txt")
If nHnd < 0
    ConOut("Erro abrir arquivo")
    Return
EndIf

FT_FGoTop()
While !FT_FEof()
    cLinha := FT_FReadLn()
    ProcessaLinha(cLinha)
    FT_FSkip()
EndDo

FT_FUse()    // libera handle (FT_FUse sem args = close)

Use Família 2 para SPED, EDI, layouts SEFAZ, arquivos > 100MB — buffered, não carrega tudo em memória. Família 1 carrega o arquivo inteiro pra RAM.

MemoWrite / MemoRead — atalho pra escrita rápida

// Grava string em arquivo (sobrescreve)
MemoWrite("\system\debug.txt", cStr)

// Grava com append
MemoWrite("\system\debug.txt", cStr, .T.)

// Le inteiro
cContent := MemoRead("\system\debug.txt")

Útil para debug em JOB ou serialização rápida. Não use pra arquivos > 10MB (carrega tudo em memória).

MsNewGetDados — grid dinâmica fora de MVC

Local aHeader := {}
Local aCols   := {}
Local oGrid   := Nil

// aHeader: {titulo, campo, picture, tamanho, decimal, valid, usado, tipo, F3, when}
aAdd(aHeader, {"Codigo", "COD",  "@!",          6,  0, "", "", "C", "",       ""})
aAdd(aHeader, {"Nome",   "NOME", "@!",          30, 0, "", "", "C", "",       ""})
aAdd(aHeader, {"Valor",  "VLR",  "@E 999.999.999,99", 14, 2, "", "", "N", "", ""})

// aCols: array de arrays — cada linha é um array com 1 valor por coluna + flag deletado
aAdd(aCols, {"001", "Cliente A", 100.50, .F.})
aAdd(aCols, {"002", "Cliente B", 200.00, .F.})

oGrid := MsNewGetDados():New( ;
    0, 0, 200, 400,;                           // nTop, nLeft, nBottom, nRight
    GD_INSERT + GD_UPDATE + GD_DELETE,;        // operacoes permitidas
    "AllwaysTrue",;                            // bLineValid
    "AllwaysTrue",;                            // bTudoOk
    "",;                                       // cIniCpos
    ,;
    999,;                                      // max linhas
    , , ,;
    oDlg,;
    aHeader,;
    aCols)

Padrão para dialogs ad-hoc onde MVC seria over-engineering (ex: rotina de importação custom, popup de selecionar registros).

OOP em ADVPL clássico

#include "TOTVS.CH"

Class TCliente
    Data cCodigo
    Data cNome
    Data nLimite
    Data lAtivo

    Method New(cCodigo) Constructor
    Method GetNome()           // public
    Method SetLimite(nValor)   // public
    Method Save()              // public
EndClass

Method New(cCodigo) Class TCliente
    ::cCodigo := cCodigo
    ::cNome   := ""
    ::nLimite := 0
    ::lAtivo  := .T.
    If !Empty(cCodigo) .And. DbSelectArea("SA1") .And. DbSeek(xFilial("SA1") + cCodigo)
        ::cNome   := AllTrim(SA1->A1_NOME)
        ::nLimite := SA1->A1_LC
    EndIf
Return Self

Method GetNome() Class TCliente
Return ::cNome

Method SetLimite(nValor) Class TCliente
    If nValor < 0
        Return .F.
    EndIf
    ::nLimite := nValor
Return .T.

Method Save() Class TCliente
    DbSelectArea("SA1")
    DbSetOrder(1)
    If DbSeek(xFilial("SA1") + ::cCodigo)
        RecLock("SA1", .F.)
    Else
        RecLock("SA1", .T.)
        SA1->A1_FILIAL := xFilial("SA1")
        SA1->A1_COD    := ::cCodigo
    EndIf
    SA1->A1_NOME := ::cNome
    SA1->A1_LC   := ::nLimite
    SA1->(MsUnlock())
Return .T.

Uso:

Local oCli := TCliente():New("000001")
oCli:SetLimite(5000)
oCli:Save()
ConOut(oCli:GetNome())

ADVPL clássico não tem private/protected — todos os Data/Method são essencialmente públicos. TLPP corrige isso (veja [[advpl-tlpp]]).

Threads — MsRunInThread

// Dispara funcao XYZProcParalelo numa nova thread Protheus
Local lOk := MsRunInThread(0, "XYZProcParalelo", aDados)
// nSlot = 0 (qualquer); 2o param = nome da funcao; 3o em diante = args

Static Function XYZProcParalelo(aDados)
    Local aArea := GetArea()     // sempre saveArea por thread!
    Local nI

    For nI := 1 To Len(aDados)
        // processa item aDados[nI]
    Next nI

    RestArea(aArea)               // sempre restArea no fim
Return Nil

Crítico em thread:

• Cada thread herda o ambiente do pai (cFilAnt, cEmpAnt, RpcSetEnv state).
• Cada thread DEVE fazer seu próprio GetArea/RestArea — sem isso, threads disputam o ponteiro do alias e geram bug "qual registro tô vendo?".
• Cada thread DEVE ter seu próprio DbSelectArea/DbSetOrder — não confie no estado do pai.
• Limite prático: pool default do AppServer aceita ~10-50 threads simultâneas. Acima disso, lentidão.

Veja [[advpl-jobs-rpc]] para mais detalhes em contexto JOB.

Reflection — Type, ValType, Eval

// Type retorna tipo de uma EXPRESSAO como string
cTipo := Type("nValor")              // "N", "C", "D", "L", "A", "O", "U" (undefined)

// ValType retorna tipo de um VALOR
cTipo := ValType(uValor)             // mesmo retorno

// Eval avalia codeblock em runtime
bBloco := {|x| x * 2}
nRet   := Eval(bBloco, 10)            // 20

// __ClassName retorna nome da classe (ADVPL OO)
cClasse := __ClassName(oObj)         // "TCliente"

// __ClassMethArr lista métodos da classe
aMtds := __ClassMethArr(oObj)

Em TLPP, use FwReflection que é mais estruturado (veja [[advpl-tlpp]]).

Boas práticas de eficiência

• NoRound(nValor, nCasas) para arredondamento financeiro determinístico (evita banker's rounding implícito).
• For Each em vez de For/Next com índice quando possível (mais legível).
• Evite + em loop para construir strings — use array + FwArrayJoin (em TOTVS R26+) ou Array2String (legacy).
• Capitulação: Local, If, EndIf em PascalCase (convenção TOTVS).
• Static no fonte ou Local na função em vez de Public global — escopo limpo.
• AScan em vez de loop manual para busca em array.
• aSize(arr, n) para redimensionar em vez de criar novo.
• FwTimeStamp() em vez de concat Date() + Time() (mais rápido + formato ISO).

Anti-padrões legados (referenciados pelo lint)

• AxCadastro/Modelo2/Modelo3 em código novo → catalogado MOD-004 (não detectado pelo lint atual, mas é warning conceitual). Veja [[advpl-refactoring]] padrão 4.
• MsgInfo/Alert em JOB → bloqueia execução. Veja [[advpl-jobs-rpc]].
• Begin Transaction com UI dentro → deadlock garantido. BP-002 (impl).
• Concatenar string em loop com + em vez de array + FwArrayJoin (PERF-004 catalog).
• Não tratar erros de FOpen/FRead/FT_FUse (retornam -1 ou < 0) → exception silenciosa.
• Thread sem GetArea/RestArea → corrompe contexto do pai.
• MemoRead em arquivo > 10MB → carrega tudo em RAM, pode estourar memória.
• TReport sem :Finish() na seção → última linha não imprime.
• OOP clássico assumindo encapsulamento — ADVPL não tem private/protected, tudo é público.

Cross-references com outras skills

• [[advpl-tlpp]] — OOP moderno com private/protected/static + namespaces.
• [[advpl-refactoring]] — AxCadastro → MVC, concat em loop → array.
• [[advpl-fundamentals]] — Static/Local/Private/Public scopes; reservadas.
• [[advpl-code-review]] — BP-002 (Transaction), BP-005 (>6 params), PERF-001/002/003.
• [[advpl-embedded-sql]] — SQL em transação, MPSysOpenQuery.
• [[advpl-mvc]] — quando preferir MVC vs MsNewGetDados ad-hoc.
• [[advpl-jobs-rpc]] — threads e RpcSetEnv em background.
• [[advpl-encoding]] — arquivos cp1252 vs UTF-8 quando ler/escrever texto.
• [[advpl-debugging]] — debug de transação travada, lock órfão.
• [[plugadvpl-index-usage]] — /plugadvpl:find function TReport, etc.

Comandos plugadvpl relacionados

• /plugadvpl:find function TReport — relatórios indexados no projeto.
• /plugadvpl:grep "Begin Transaction\|BeginTran" — transações.
• /plugadvpl:grep "MsRunInThread\|StartJob" — threading.
• /plugadvpl:grep "FT_FUse\|FCreate" — manipulação de arquivos.
• /plugadvpl:grep "Class.*Method\|EndClass" — OOP clássico.
• /plugadvpl:lint <arq> — checa BP-001 (RecLock+MsUnlock), BP-002 (Transaction), BP-005 (>6 params), BP-006 (RecLock raw mix), MOD-001/002 (ConOut, Public).
• Tabela operacoes_escrita cataloga todos os RecLock+MsUnlock patterns do projeto.

Referência profunda

Para detalhes completos (~2.3k linhas), consulte reference.md ao lado deste arquivo:

• Apostila ADVPL II completa (TOTVS) com programação de atualização, browses, transações.
• Catálogo de relatórios TReport com TRSection, TRCell, TRPosition, TRFunction, fórmulas, agrupamentos.
• Família completa de manipulação de arquivos (Famílias 1 e 2, FWTemporary*, FWFileReader/Writer).
• Componentes de interface visual (TDialog, TGet, TButton, TFolder, TPanel, TBitmap, TScrollBox).
• Boas práticas: arredondamento, identação, capitulação, técnicas de programação eficiente.
• Padrões de OOP em ADVPL clássico — singleton, factory, observer (com workarounds para falta de private).

Sources

• Criação de relatórios em 10 minutos AdvPL - Terminal de Informação
• TReport TRFunction TRSection TRCell - Maratona AdvPL TL++ 505
• Diferença entre TReports e TReport - Terminal de Informação
• Criando arquivos com MemoWrite - Maratona AdvPL 345
• Boas Práticas em Transações ADVPL (PDF)
• Controle de transações - TDN
• Classes em AdvPL - Tudo em AdvPL
• Acelerando o AdvPL - Importação de tabelas