Pular para conteúdo

Fundamentos de AdvPL

Status: parcial — afirmações verificadas, com lacunas declaradas. [n · F] remete à fonte n da lista de fontes; a letra marca a procedência: F fato em fonte oficial TOTVS/TDN · S fonte secundária (blog, fórum) · unverified sem fonte que sustente.

Escopo desta seção

Linguagem AdvPL: escopo de variáveis, as formas de declarar função, controle de fluxo e tratamento de erro clássico, a camada de workareas DBF e as convenções de código que a própria TOTVS impõe a código customizado.

Escopo de variáveis

  • AdvPL tem quatro identificadores de escopo: LOCAL, STATIC, PRIVATE e PUBLIC.[11 · F]
  • Variável LOCAL pertence só à função onde foi declarada e precisa ser declarada explicitamente.[10 · F]
  • A declaração de locais precisa vir antes de qualquer comando ou de declarações PRIVATE/PUBLIC; fora dessa ordem é erro de compilação.[10 · F]
  • Atribuir valor a uma variável não declarada cria a variável como PRIVATE — o escopo é dinâmico.[11 · F]
  • Consequência prática: erro de digitação no nome de uma variável não gera erro de compilação nem de execução.[11 · F]

A armadilha que mais custa tempo

Como PRIVATE nasce por atribuição, um nomeErrado := 1 no lugar de nomeCerto := 1 compila limpo e roda. O bug aparece longe da causa — na leitura que devolve vazio.[11]

Funções: FUNCTION, STATIC FUNCTION, USER FUNCTION

  • Duas visibilidades: funções públicas, declaradas por FUNCTION, visíveis em qualquer parte da aplicação; e funções estáticas, visíveis apenas por outras funções do mesmo arquivo .PRW.[18 · F]
  • USER FUNCTION declara função de usuário que não pertence ao padrão do Protheus e pode ser invocada por qualquer outra função do Protheus.[18 · F]
  • Armadilha de nome: o nome pode ter qualquer tamanho, mas só os 10 primeiros caracteres identificam a função.[18 · F]
  • Parâmetro não recebido vira NIL automaticamente; o parâmetro pode ser enviado por valor ou por referência.[18 · F]

Controle de fluxo e tratamento de erro

  • O tratamento de erro clássico é BEGIN SEQUENCE ... RECOVER ... END SEQUENCE, com desvio explícito por BREAK.[19 · F]
  • Dentro do bloco é permitido RETURN, mas não LOOP nem EXIT de um WHILE/ENDDO ou FOR/NEXT externo; entre RECOVER e END SEQUENCE são permitidos LOOP, EXIT ou BREAK.[19 · F]

AdvPL x TLPP aqui

Aqui o desvio só acontece com BREAK explícito. O TLPP muda isso: lá a exceção desvia para o CATCH automaticamente — veja TLPP.

Workareas DBF

  • A camada "Controle de Arquivos" reúne as funções de workarea: DBSelectArea, DBSeek, DBSkip, DBSetOrder, DBSetFilter, RecLock, DBRLock, MsUnlock, DbUseArea, DbStruct, Posicione e xFilial.[37, 70 · F]
  • O padrão de leitura documentado pela própria TOTVS é salvar a área, selecionar o alias, posicionar por xFilial() + chave, iterar com DbSkip e restaurar a área.[54 · F]
  • Boa prática obrigatória: salvar as workareas com GetArea() e restaurar com RestArea().[31 · F]
  • Ao atualizar campos é obrigatório travar o registro e liberar depois; esquecer MsUnLock() deixa o registro travado para os processos padrão.[31 · F]
  • RecLock(<alias>, .T.) cria registro em branco com lock exclusivo; com (.F.) trava o registro posicionado para update.[29 · F]

Convenções de código

  • Não reutilizar nomes de rotinas nem de funções do padrão em código customizado — nem rotinas como MATA010, MATA460 ou FINA040, nem funções como A460Dupl ou A460Process.[31 · F]
  • Não reaproveitar variáveis públicas padrão para outra finalidade dentro de função específica; nOpc e dDataBase são os exemplos citados pela TOTVS.[31 · F]

Lacunas declaradas

Lacuna: exemplos completos de BEGIN SEQUENCE aninhado e o comportamento do error block em thread não foram coletados nesta passada.

Lacuna: tipos primitivos (Character, Numeric, Date, Logical, Array, Codeblock, Object) não têm página oficial coletada — a evidência desta passada cobre escopo e funções, não a tabela de tipos.

Fontes

[10] · [11] · [18] · [19] · [29] · [31] · [37] · [54] · [70] — ver lista completa.