Protheus include files
#Include "<arquivo>.ch"Understand the role of .ch files and choose the appropriate include for each context.
Overview
Include files gather definitions, constants and commands that the compiler must know when processing AdvPL source code. The #Include directive incorporates these definitions during compilation; it does not load an executable library at runtime. The include folder must match the environment and be correctly configured in the compilation tool.
Syntax
#Include "<arquivo>.ch"General base: TOTVS.ch
#Include "TOTVS.ch"
User Function ExInclude()
Local cMensagem := "General include configured"
MsgInfo(cMensagem)
ReturnUse TOTVS.ch as the general include in new source files. PROTHEUS.ch remains present in many examples and existing code; RWMAKE.ch should be treated as legacy.
MVC: FWMVCDef.ch
#Include "TOTVS.ch"
#Include "FWMVCDef.ch"
User Function ExMVC()
Local oModel := FWLoadModel("MATA020")
oModel:SetOperation(MODEL_OPERATION_INSERT)
ReturnFWMVCDef.ch provides definitions used by the MVC architecture, including model operation constants.
SQL queries: 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 is required for specific relational access commands such as TCQUERY. The official documentation recommends NEW to avoid unintentionally closing the current work area.
Environment preparation: TBICONN.ch
#Include "TOTVS.ch"
#Include "TBICONN.ch"
User Function ExAmbiente()
PREPARE ENVIRONMENT EMPRESA "01" FILIAL "01" MODULO "FAT"
ConOut("Environment prepared")
RESET ENVIRONMENT
ReturnTBICONN.ch appears in non-interface routines that use PREPARE ENVIRONMENT and RESET ENVIRONMENT. Company, branch, module and table values depend on the process being run.
REST services: RestFul.ch
#Include "TOTVS.ch"
#Include "RestFul.ch"
// WSRESTFUL, WSDATA and WSMETHOD declarations
// depend on definitions provided by RestFul.ch.RestFul.ch is used to declare AdvPL REST services based on commands and definitions from the REST framework.
- Use only the includes required by the feature used in the source code.
- Keep the include package aligned with the Protheus release and update level.
- According to official TOTVS guidance, prefer TOTVS.ch as the general base; it points to PROTHEUS.ch and may receive future definitions.
- Document specific includes when their absence does not produce an intuitive compilation error.
- RWMAKE.ch is an old include and is not recommended for new development; legacy code may still use it.
- A missing, outdated or mismatched include folder can cause unknown commands, missing identifiers or differences between environments.
- Adding many includes indiscriminately can hide actual dependencies and make maintenance harder.
- Not every function requires a specific include; consult the documentation for the command or feature being used.