Configuración

* MisTools.prg

DEFINE CLASS SaldoClienteTool AS FoxAgentTool

  * Nombre con el que el modelo la invoca. En snake_case.
  ToolName        = "saldo_cliente"

  * El modelo lee esta descripción para decidir cuándo usarla.
  * Cuanto más concreta, mejor la elige.
  ToolDescription = "Devuelve el saldo de un cliente a partir de su " + ;
                    "código. Úsala cuando pregunten por el saldo o la " + ;
                    "deuda de un cliente concreto."

  FUNCTION DefineParameters()
    * Nombre, tipo, descripción para el modelo y si es obligatorio.
    THIS.AddParam("codigoCliente", "number", "Código del cliente", .T.)
  ENDFUNC

  FUNCTION Execute(toContext)
    LOCAL lnCodigo, lcSalida, lcError

    * Los parámetros llegan en el CONTEXTO, no en THIS.
    lnCodigo = toContext.Parameters.codigoCliente

    * Valida antes de tocar datos: es barato y deja el bloque protegido
    * para lo que de verdad puede fallar.
    IF VARTYPE(lnCodigo) != "N" OR lnCodigo <= 0
      RETURN THIS.Err("codigoCliente es obligatorio y mayor que cero")
    ENDIF

    lcSalida = ""
    lcError  = ""

    * Tu herramienta nace en una SESIÓN DE DATOS PRIVADA: las tablas que
    * tiene abiertas tu aplicación NO están abiertas aquí. Se entra en la
    * sesión de la aplicación, se trabaja allí y se vuelve por una sola
    * salida.
    THIS.UseAppSession()
    TRY
      IF !USED("CLIENTES")
        lcError = "La tabla CLIENTES no está abierta en la aplicación"
      ELSE
        * Deja el puntero donde estaba: el agente leyendo datos no puede
        * mover la pantalla por debajo del usuario.
        LOCAL lnRec
        lnRec = RECNO("CLIENTES")

        SELECT CLIENTES
        LOCATE FOR CLI_COD = lnCodigo
        IF !FOUND()
          lcError = "No existe el cliente " + TRANSFORM(lnCodigo)
        ELSE
          lcSalida = ALLTRIM(CLIENTES.CLI_NOM) + ", saldo: " + ;
                     TRANSFORM(CLIENTES.CLI_SALDO, "999,999.99")
        ENDIF

        IF lnRec > 0 AND lnRec <= RECCOUNT("CLIENTES")
          GO lnRec IN CLIENTES
        ENDIF
      ENDIF
    CATCH TO loErr
      lcError = "Error leyendo CLIENTES: " + loErr.Message
    FINALLY
      * Siempre, por cualquier camino. Por eso hay una sola salida y no
      * un RETURN dentro del bloque.
      THIS.RestoreSession()
    ENDTRY

    IF !EMPTY(lcError)
      RETURN THIS.Err(lcError)
    ENDIF
    RETURN THIS.Ok(lcSalida)
  ENDFUNC

ENDDEFINE

DEFINE CLASS BuscarClientesTool AS FoxAgentTool

  ToolName        = "buscar_clientes"
  ToolDescription = "Busca clientes por nombre, código postal o saldo mínimo."

  FUNCTION DefineParameters()
    THIS.AddParam("texto",        "string",  "Texto en el nombre",      .T.)
    THIS.AddParam("codigoPostal", "string",  "Filtrar por CP",          .F.)
    THIS.AddParam("saldoMinimo",  "number",  "Saldo mínimo",            .F.)
    THIS.AddParam("soloActivos",  "boolean", "Solo clientes activos",   .F.)
  ENDFUNC

  FUNCTION Execute(toContext)
    LOCAL lcTexto, lcPostal, lnSaldo, llActivos, lcSalida, lcError

    lcTexto   = toContext.Parameters.texto
    lcPostal  = toContext.Parameters.codigoPostal
    lnSaldo   = toContext.Parameters.saldoMinimo
    llActivos = toContext.Parameters.soloActivos

    lcSalida = ""
    lcError  = ""

    THIS.UseAppSession()
    TRY
      * El texto lo escribe el modelo. Una consulta montada con & y
      * comillas es una inyección de SQL esperando a ocurrir: aquí las
      * variables van tal cual y las resuelve VFP.
      SELECT * FROM CLIENTES ;
        WHERE UPPER(CLI_NOM) LIKE "%" + UPPER(ALLTRIM(lcTexto)) + "%" ;
          AND (EMPTY(lcPostal) OR CLI_CP = lcPostal) ;
          AND (lnSaldo = 0 OR CLI_SALDO >= lnSaldo) ;
          AND (NOT llActivos OR CLI_ACTIVO) ;
        INTO CURSOR curBusca NOFILTER

      * RECCOUNT() sobre el cursor, no ALEN() sobre un array: con cero
      * filas el array no llega a existir y ALEN() da error 12.
      lcSalida = TRANSFORM(RECCOUNT("curBusca")) + " clientes encontrados"

      * Cierra tus cursores AQUÍ, todavía en la sesión de la aplicación:
      * desde la tuya ya no se ven.
      USE IN SELECT("curBusca")
    CATCH TO loErr
      lcError = "Error buscando clientes: " + loErr.Message
    FINALLY
      THIS.RestoreSession()
    ENDTRY

    IF !EMPTY(lcError)
      RETURN THIS.Err(lcError)
    ENDIF
    RETURN THIS.Ok(lcSalida)
  ENDFUNC

ENDDEFINE

SET PROCEDURE TO "C:\Program Files\FoxAgent\SDK\FoxTool.prg"      ADDITIVE
SET PROCEDURE TO "C:\Program Files\FoxAgent\SDK\FoxAgentTool.prg" ADDITIVE
SET PROCEDURE TO "MisTools.prg" ADDITIVE

* Una llamada por herramienta, justo después de un Connect correcto.
goBridge.RegisterTool(CREATEOBJECT("SaldoClienteTool"))
goBridge.RegisterTool(CREATEOBJECT("BuscarClientesTool"))

* Cuando cambia el usuario que ha iniciado sesión, rehaz la lista:
* qué herramientas existen lo decide tu aplicación, por usuario.
goBridge.ClearTools()
goBridge.UnregisterTool("buscar_clientes")