SaldoTit

SaldoTit retorna o saldo financeiro de um titulo (SE1/SE2), considerando baixas, abatimentos, juros, descontos. Util pra relatorios e validacoes. Anti-padrao classico: chamar dentro de loop sobre SE1/SE2 porque cada chamada gera nova query no banco.

Sintaxe

nSaldo := SaldoTit( ;
    SE1->E1_PREFIXO, ;
    SE1->E1_NUM,     ;
    SE1->E1_PARCELA, ;
    SE1->E1_TIPO,    ;
    SE1->E1_CLIENTE, ;
    SE1->E1_LOJA     )

Anti-padrao classico

// ERRADO — query por iteracao = 5000 titulos = 5000 queries
SE1->(DBSetOrder(1))
SE1->(DBSeek(xFilial("SE1") + cCliente))
While !SE1->(Eof()) .And. SE1->E1_CLIENTE == cCliente
    nSaldo := SaldoTit(SE1->E1_PREFIXO, SE1->E1_NUM, ;
                       SE1->E1_PARCELA, SE1->E1_TIPO, ;
                       SE1->E1_CLIENTE, SE1->E1_LOJA)
    nTotal += nSaldo
    SE1->(DBSkip())
EndDo

Padrao correto — TCQuery agregada

// CERTO — 1 query so, agregando tudo
cQry := "SELECT E1_PREFIXO, E1_NUM, E1_PARCELA, E1_TIPO, ;
              (E1_VALOR - E1_VALLIQ - E1_VALPAR) AS SALDO  ;
           FROM " + RetSqlName("SE1") + " ;
          WHERE E1_FILIAL  = '" + xFilial("SE1") + "'    ;
            AND E1_CLIENTE = '" + cCliente + "'           ;
            AND E1_BAIXA   = '        '                   ;
            AND D_E_L_E_T_ = ' '"

TCQuery cQry New Alias "QRYSAL"
While !QRYSAL->(Eof())
    nTotal += QRYSAL->SALDO
    QRYSAL->(DBSkip())
EndDo
QRYSAL->(DBCloseArea())

Quando usar SaldoTit

• Validacao pontual de 1 titulo (UI, PE)
• Calculo individual antes de baixar
• Quando voce precisa do calculo "oficial" do framework (com juros/multa/abatimento)

Quando NAO usar

• Em loop sobre muitos titulos — use TCQuery agregada
• Em rotinas batch de fechamento de mes
• Em relatorio com 1000+ linhas — degrada absurdamente

Pegadinhas

• Performance — chamada custosa, cada call abre cursor.
• Data de referencia opcional — se omitida, usa dDataBase.
• Detecta automaticamente: a skill /advpl-find-issues tem regra (em desenvolvimento) pra detectar SaldoTit em loop.