@netoalmanca/advpl-sensei 1.1.0

package/skills/advpl-code-generation/patterns-jobs.md

@@ -0,0 +1,519 @@
+# Protheus Jobs and Background Processing Patterns
+
+Complete reference for implementing background jobs, multi-threading, and scheduled tasks in TOTVS Protheus.
+
+---
+
+## 1. Overview
+
+Protheus supports background processing through Jobs configured in `appserver.ini` and programmatic thread creation via `StartJob`. Jobs run without a user interface and are used for batch processing, integrations, scheduled tasks, and parallel operations.
+
+Key functions:
+- **StartJob()**: Executes a function in a secondary thread without interface.
+- **RpcSetEnv()**: Opens/prepares the Protheus environment (company, branch, tables) in a new thread.
+- **RpcClearEnv()**: Closes/releases the environment and connections opened by `RpcSetEnv`.
+- **LockByName()**: Creates a named semaphore on the license server for concurrency control.
+- **UnlockByName()**: Releases a named semaphore created by `LockByName`.
+- **ConOut()**: Writes messages to the AppServer console log.
+- **FWLogMsg()**: Standardized logging API (recommended replacement for `ConOut` in newer versions).
+
+Required includes:
+```advpl
+#Include "TOTVS.CH"
+```
+
+---
+
+## 2. OnStart - AppServer.ini Configuration
+
+### 2.1 Basic Job Configuration
+
+Jobs are configured in the `appserver.ini` file to run automatically when the Application Server starts.
+
+```ini
+[OnStart]
+JOBS=MYJOB
+REFRESHRATE=120
+
+[MYJOB]
+MAIN=U_zJobMain
+ENVIRONMENT=PRODUCAO
+```
+
+| Key | Description |
+|-----|-------------|
+| `JOBS` | Comma-separated list of job section names to execute |
+| `REFRESHRATE` | Interval in seconds to re-execute jobs if not running (default: 60) |
+
+### 2.2 Job Section Keys
+
+| Key | Description |
+|-----|-------------|
+| `MAIN` | Function name to execute (e.g., `U_zJobMain`) |
+| `ENVIRONMENT` | Server environment name |
+
+### 2.3 Multiple Jobs
+
+```ini
+[OnStart]
+JOBS=JOB_INTEG,JOB_LOTE,JOB_HTTP
+REFRESHRATE=300
+
+[JOB_INTEG]
+MAIN=U_zIntegJob
+ENVIRONMENT=PRODUCAO
+
+[JOB_LOTE]
+MAIN=U_zLoteJob
+ENVIRONMENT=PRODUCAO
+
+[JOB_HTTP]
+MAIN=HTTP_START
+ENVIRONMENT=PRODUCAO
+```
+
+---
+
+## 3. StartJob - Thread Creation
+
+### 3.1 Syntax
+
+```advpl
+StartJob(cFuncName, cEnvironment, lWait, parm1, parm2, ..., parm25)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `cFuncName` | Character | Function name to execute in the new thread |
+| `cEnvironment` | Character | Server environment (use `GetEnvServer()` for current) |
+| `lWait` | Logical | `.T.` waits for thread to finish, `.F.` runs in background |
+| `parm1..parm25` | Any | Up to 25 optional parameters passed to the function |
+
+### 3.2 Basic Usage
+
+```advpl
+// Executa em background sem esperar
+StartJob("U_zProcessa", GetEnvServer(), .F.)
+
+// Executa e aguarda conclusao
+StartJob("U_zProcessa", GetEnvServer(), .T.)
+
+// Passa parametros
+StartJob("U_zProcessa", GetEnvServer(), .F., "99", "01", "PARAM3")
+```
+
+---
+
+## 4. RpcSetEnv - Environment Setup
+
+### 4.1 Syntax
+
+```advpl
+lRet := RpcSetEnv(cCodEmp, cCodFil, cUsuario, cSenha, cModulo, cFunName, aTables)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `cCodEmp` | Character | Company code (e.g., `"99"`) |
+| `cCodFil` | Character | Branch code (e.g., `"01"`) |
+
+> **IMPORTANT:** Never use `cFilial`, `cFilAnt` or `cEmpAnt` as variable names — these are **reserved Private variables** maintained by the Protheus framework to track company/branch context. Using them as Local variables will shadow the system variables and cause unpredictable behavior. Use `cCodFil`, `cCodEmp` or similar names instead.
+| `cUsuario` | Character | User login (optional) |
+| `cSenha` | Character | User password (optional) |
+| `cModulo` | Character | Module code, e.g., `"FAT"`, `"CTB"` (default: `"FAT"`) |
+| `cFunName` | Character | Function name for `FunName()` (default: `"RPC"`) |
+| `aTables` | Array | Array of table aliases to open (optional) |
+| **Return** | Logical | `.T.` if environment was prepared successfully |
+
+### 4.2 Basic Usage
+
+```advpl
+If RpcSetEnv("99", "01", "admin", " ", "FAT")
+    // Ambiente preparado, executar logica de negocio
+    // ...
+    RpcClearEnv()
+EndIf
+```
+
+---
+
+## 5. RpcClearEnv - Environment Cleanup
+
+### 5.1 Syntax
+
+```advpl
+RpcClearEnv()
+```
+
+Closes the environment opened by `RpcSetEnv`, releasing connections and resources. Must always be called after processing is complete.
+
+**Important**: Do not call `RpcSetEnv` or `RpcClearEnv` in routines executed from the Protheus menu, as the environment is already open and managed by the system.
+
+---
+
+## 6. LockByName / UnlockByName - Semaphores
+
+### 6.1 LockByName Syntax
+
+```advpl
+lLocked := LockByName(cName, lByCompany, lByBranch)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `cName` | Character | Semaphore name |
+| `lByCompany` | Logical | `.T.` considers company code in the lock |
+| `lByBranch` | Logical | `.T.` considers branch code in the lock |
+| **Return** | Logical | `.T.` if lock was acquired successfully |
+
+### 6.2 UnlockByName Syntax
+
+```advpl
+UnlockByName(cName, lByCompany, lByBranch)
+```
+
+Parameters are the same as `LockByName`. Releases the named semaphore.
+
+### 6.3 Usage Pattern
+
+```advpl
+// Tenta adquirir o semaforo
+If LockByName("PROC_LOTE_001", .F., .F.)
+    // Executa processamento exclusivo
+    ProcessaLote()
+
+    // Libera o semaforo
+    UnlockByName("PROC_LOTE_001", .F., .F.)
+Else
+    ConOut("Processamento ja em execucao por outra thread.")
+EndIf
+```
+
+---
+
+## 7. Logging
+
+### 7.1 ConOut
+
+Writes a message to the Application Server console log:
+
+```advpl
+ConOut("Inicio do processamento: " + DToC(Date()) + " " + Time())
+ConOut("Registro processado: " + cCodigo)
+ConOut("Erro: " + cMsgErro)
+```
+
+### 7.2 FWLogMsg (Recommended)
+
+Standardized logging API that replaces `ConOut` in newer Protheus versions:
+
+```advpl
+FWLogMsg("INFO",  /*cTransactionId*/, "MYJOB", /*cCategory*/, /*cStep*/, "001", "Inicio do processamento", /*aMessage*/, /*nLogLevel*/)
+FWLogMsg("ERROR", /*cTransactionId*/, "MYJOB", /*cCategory*/, /*cStep*/, "002", "Erro no processamento: " + cMsgErro, /*aMessage*/, /*nLogLevel*/)
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| 1st | Severity: `"INFO"`, `"ERROR"`, `"WARNING"` |
+| 2nd | Transaction ID (optional) |
+| 3rd | Message grouper/module ID |
+| 4th | Category (optional) |
+| 5th | Step (optional) |
+| 6th | Message code |
+| 7th | Message text |
+| 8th | Array of additional messages (optional) |
+| 9th | Log level (optional) |
+
+---
+
+## 8. Complete Example - Batch Processing Job
+
+This example implements a job that processes pending records in batches, with environment setup, semaphore control, and logging.
+
+```advpl
+#Include "TOTVS.CH"
+
+/*/{Protheus.doc} zJobLote
+Job de processamento em lote
+@type User Function
+@author Autor
+@since 01/01/2026
+@version 1.0
+/*/
+User Function zJobLote()
+    Local cCodEmp := "99"
+    Local cCodFil := "01"
+
+    ConOut("[zJobLote] Iniciando job: " + DToC(Date()) + " " + Time())
+
+    // Prepara o ambiente
+    If !RpcSetEnv(cCodEmp, cCodFil, "admin", " ", "FAT", "zJobLote")
+        ConOut("[zJobLote] ERRO: Falha ao preparar ambiente.")
+        Return Nil
+    EndIf
+
+    // Controle de concorrencia via semaforo
+    If !LockByName("JOB_PROC_LOTE", .F., .F.)
+        ConOut("[zJobLote] Job ja em execucao por outra thread. Saindo.")
+        RpcClearEnv()
+        Return Nil
+    EndIf
+
+    // Executa o processamento
+    Begin Sequence
+        fProcessaLote()
+    Recover
+        ConOut("[zJobLote] ERRO: Excecao durante processamento.")
+    End Sequence
+
+    // Libera semaforo e ambiente
+    UnlockByName("JOB_PROC_LOTE", .F., .F.)
+    RpcClearEnv()
+
+    ConOut("[zJobLote] Job finalizado: " + DToC(Date()) + " " + Time())
+
+Return Nil
+
+// =============================================================
+// Processamento em lote
+// =============================================================
+Static Function fProcessaLote()
+    Local cAlias  := "ZA9"
+    Local aArea   := GetArea()
+    Local nCount  := 0
+    Local nErrors := 0
+
+    DbSelectArea(cAlias)
+    DbSetOrder(1)
+    DbGoTop()
+
+    While !Eof()
+        If xFilial(cAlias) == ZA9->ZA9_FILIAL .And. ZA9->ZA9_STATUS == "1" // Pendente
+
+            Begin Transaction
+                RecLock(cAlias, .F.)
+                    ZA9->ZA9_STATUS := "2" // Em processamento
+                MsUnlock()
+
+                // Executa logica de negocio
+                If fProcessaRegistro(ZA9->ZA9_CODIGO)
+                    RecLock(cAlias, .F.)
+                        ZA9->ZA9_STATUS  := "3" // Processado
+                        ZA9->ZA9_DTPROC  := Date()
+                        ZA9->ZA9_HRPROC  := Time()
+                    MsUnlock()
+                    nCount++
+                Else
+                    RecLock(cAlias, .F.)
+                        ZA9->ZA9_STATUS := "9" // Erro
+                    MsUnlock()
+                    nErrors++
+                EndIf
+            End Transaction
+
+        EndIf
+
+        DbSkip()
+    EndWh
+
+    ConOut("[zJobLote] Processados: " + cValToChar(nCount) + " | Erros: " + cValToChar(nErrors))
+
+    RestArea(aArea)
+
+Return Nil
+
+// =============================================================
+// Processa um registro individual
+// =============================================================
+Static Function fProcessaRegistro(cCodigo)
+    Local lRet := .T.
+
+    // Logica de negocio especifica
+    ConOut("[zJobLote] Processando registro: " + cCodigo)
+
+    // ... implementar logica aqui ...
+
+Return lRet
+```
+
+---
+
+## 9. Multi-Thread Processing with StartJob
+
+### 9.1 Dispatcher Pattern
+
+A common pattern is to have a dispatcher function that creates multiple worker threads:
+
+```advpl
+#Include "TOTVS.CH"
+
+/*/{Protheus.doc} zDispatcher
+Dispatcher que cria multiplas threads de processamento
+@type User Function
+@author Autor
+@since 01/01/2026
+@version 1.0
+/*/
+User Function zDispatcher()
+    Local nThreads := 5
+    Local nI       := 0
+
+    ConOut("[zDispatcher] Iniciando " + cValToChar(nThreads) + " threads")
+
+    // Prepara ambiente para o dispatcher
+    If !RpcSetEnv("99", "01", "admin", " ", "FAT", "zDispatcher")
+        ConOut("[zDispatcher] ERRO: Falha ao preparar ambiente.")
+        Return Nil
+    EndIf
+
+    // Inicia threads de processamento
+    For nI := 1 To nThreads
+        StartJob("U_zWorker", GetEnvServer(), .F., cValToChar(nI))
+        ConOut("[zDispatcher] Thread " + cValToChar(nI) + " iniciada.")
+    Next nI
+
+    RpcClearEnv()
+
+Return Nil
+
+/*/{Protheus.doc} zWorker
+Worker thread para processamento paralelo
+@type User Function
+@author Autor
+@since 01/01/2026
+@version 1.0
+/*/
+User Function zWorker(cThreadId)
+    Default cThreadId := "0"
+
+    ConOut("[zWorker-" + cThreadId + "] Inicio: " + Time())
+
+    // Cada thread prepara seu proprio ambiente
+    If !RpcSetEnv("99", "01", "admin", " ", "FAT", "zWorker")
+        ConOut("[zWorker-" + cThreadId + "] ERRO: Falha ao preparar ambiente.")
+        Return Nil
+    EndIf
+
+    // Processamento da thread
+    fWorkerProcess(cThreadId)
+
+    RpcClearEnv()
+
+    ConOut("[zWorker-" + cThreadId + "] Fim: " + Time())
+
+Return Nil
+
+Static Function fWorkerProcess(cThreadId)
+    Local nI := 0
+
+    // Exemplo: cada thread processa um lote de registros
+    For nI := 1 To 100
+        // Processamento individual
+        ConOut("[zWorker-" + cThreadId + "] Processando item " + cValToChar(nI))
+    Next nI
+
+Return Nil
+```
+
+---
+
+## 10. Job with Interval Processing
+
+Pattern for a job that runs periodically and processes data in intervals:
+
+```advpl
+#Include "TOTVS.CH"
+
+/*/{Protheus.doc} zJobLoop
+Job com processamento em intervalo (controlado por OnStart/RefreshRate)
+@type User Function
+@author Autor
+@since 01/01/2026
+@version 1.0
+/*/
+User Function zJobLoop()
+
+    ConOut("[zJobLoop] Executando ciclo: " + DToC(Date()) + " " + Time())
+
+    If !RpcSetEnv("99", "01", "admin", " ", "FAT", "zJobLoop")
+        ConOut("[zJobLoop] ERRO: Falha ao preparar ambiente.")
+        Return Nil
+    EndIf
+
+    // Controle de concorrencia
+    If !LockByName("JOB_LOOP", .F., .F.)
+        ConOut("[zJobLoop] Outra instancia em execucao.")
+        RpcClearEnv()
+        Return Nil
+    EndIf
+
+    // Processa pendencias
+    fProcessaPendencias()
+
+    UnlockByName("JOB_LOOP", .F., .F.)
+    RpcClearEnv()
+
+    ConOut("[zJobLoop] Ciclo finalizado: " + DToC(Date()) + " " + Time())
+    // O RefreshRate do appserver.ini controlara a proxima execucao
+
+Return Nil
+
+Static Function fProcessaPendencias()
+    Local cQuery  := ""
+    Local cAlias  := GetNextAlias()
+    Local nCount  := 0
+
+    cQuery := "SELECT ZA9_CODIGO, ZA9_DESCRI "
+    cQuery += "FROM " + RetSqlName("ZA9") + " ZA9 "
+    cQuery += "WHERE ZA9.D_E_L_E_T_ = ' ' "
+    cQuery += "AND ZA9_FILIAL = '" + xFilial("ZA9") + "' "
+    cQuery += "AND ZA9_STATUS = '1' "
+    cQuery += "ORDER BY ZA9_CODIGO "
+
+    TCQuery cQuery New Alias (cAlias)
+
+    While !(cAlias)->(Eof())
+        ConOut("[zJobLoop] Processando: " + AllTrim((cAlias)->ZA9_CODIGO))
+        // ... logica de processamento ...
+        nCount++
+        (cAlias)->(DbSkip())
+    EndWh
+
+    (cAlias)->(DbCloseArea())
+
+    ConOut("[zJobLoop] Total processado: " + cValToChar(nCount))
+
+Return Nil
+```
+
+---
+
+## 11. Best Practices
+
+### 11.1 Environment Management
+
+- **Always** call `RpcClearEnv()` after `RpcSetEnv()`, even if an error occurs (use `Begin Sequence` / `Recover`).
+- **Never** call `RpcSetEnv()` or `RpcClearEnv()` in routines executed from the Protheus menu (the environment is already managed by the system).
+- Each thread started by `StartJob` must call its own `RpcSetEnv()` to prepare its environment.
+
+### 11.2 Concurrency Control
+
+- Use `LockByName()` / `UnlockByName()` to prevent multiple instances of the same job from running simultaneously.
+- Always release the lock in a `Recover` block or ensure it is released even on errors.
+
+### 11.3 Logging
+
+- Use `ConOut()` for basic console logging.
+- Prefer `FWLogMsg()` for standardized, structured logging in production environments.
+- Include timestamps and identifiers in log messages for easier debugging.
+
+### 11.4 Error Handling
+
+```advpl
+Begin Sequence
+    // Logica de negocio
+    fProcessa()
+Recover
+    ConOut("[JOB] Erro critico durante processamento: " + DToC(Date()) + " " + Time())
+End Sequence
+```