Includes do Protheus
#Include "<arquivo>.ch"Entenda o papel dos arquivos .ch e escolha a include adequada para cada contexto.
Visão geral
Arquivos de include reúnem definições, constantes e comandos que o compilador precisa conhecer ao processar um fonte AdvPL. A diretiva #Include incorpora essas definições durante a compilação; ela não carrega uma biblioteca executável em tempo de execução. A pasta de includes deve corresponder ao ambiente e estar corretamente configurada na ferramenta de compilação.
Sintaxe
#Include "<arquivo>.ch"Base geral: TOTVS.ch
#Include "TOTVS.ch"
User Function ExInclude()
Local cMensagem := "Include geral configurada"
MsgInfo(cMensagem)
ReturnUse TOTVS.ch como include geral em novos fontes. PROTHEUS.ch permanece presente em muitos exemplos e códigos existentes; RWMAKE.ch deve ser tratada como legado.
MVC: FWMVCDef.ch
#Include "TOTVS.ch"
#Include "FWMVCDef.ch"
User Function ExMVC()
Local oModel := FWLoadModel("MATA020")
oModel:SetOperation(MODEL_OPERATION_INSERT)
ReturnFWMVCDef.ch fornece definições utilizadas pela arquitetura MVC, como as constantes de operação do modelo.
Consultas SQL: TopConn.ch
#Include "TOTVS.ch"
#Include "TopConn.ch"
User Function ExQuery()
Local cQuery := "SELECT A1_COD FROM " + RetSqlName("SA1")
TCQUERY (cQuery) ALIAS QRY NEW
QRY->(DbCloseArea())
ReturnTopConn.ch é necessária para comandos específicos de acesso relacional, como TCQUERY. A documentação oficial recomenda NEW para evitar o fechamento involuntário da área atual.
Preparação de ambiente: TBICONN.ch
#Include "TOTVS.ch"
#Include "TBICONN.ch"
User Function ExAmbiente()
PREPARE ENVIRONMENT EMPRESA "01" FILIAL "01" MODULO "FAT"
ConOut("Ambiente preparado")
RESET ENVIRONMENT
ReturnTBICONN.ch aparece em rotinas sem interface que utilizam os comandos PREPARE ENVIRONMENT e RESET ENVIRONMENT. Os valores de empresa, filial, módulo e tabelas dependem do processo executado.
Serviços REST: RestFul.ch
#Include "TOTVS.ch"
#Include "RestFul.ch"
// As declarações WSRESTFUL, WSDATA e WSMETHOD
// dependem das definições fornecidas por RestFul.ch.RestFul.ch é usada na declaração de serviços REST AdvPL baseados nos comandos e definições do framework REST.
- Use somente as includes necessárias ao recurso empregado pelo fonte.
- Mantenha o pacote de includes alinhado ao release e à atualização do ambiente Protheus.
- Segundo a orientação oficial da TOTVS, prefira TOTVS.ch como base geral; ela aponta para PROTHEUS.ch e pode receber definições futuras.
- Documente includes específicas quando sua ausência não produzir um erro de compilação intuitivo.
- RWMAKE.ch é uma include antiga e não é recomendada para novos desenvolvimentos; códigos legados ainda podem utilizá-la.
- Uma pasta de includes ausente, desatualizada ou pertencente a outro release pode causar comandos desconhecidos, identificadores não encontrados ou diferenças entre ambientes.
- Adicionar várias includes indiscriminadamente pode ocultar dependências reais e dificultar a manutenção.
- Nem toda função exige uma include específica; consulte a documentação do comando ou recurso utilizado.