CLASEPublicado

FWExecStatement

FWExecStatement():New( <cQuery> ) --> oStatement

Ejecuta queries SQL parametrizadas con asociación de valores, resultados abiertos como alias y métodos heredados de FWPreparedStatement.

FrameworkSQLDBAccessQuery parametrizadaBindFWPreparedStatement

01 · DESCRIPCIÓN GENERAL

Descripción general

FWExecStatement deriva de FWPreparedStatement y encapsula conceptos de ejecución/caché de queries del Framework. Permite construir SQL con marcadores ?, asociar valores por tipo y ejecutar mediante OpenAlias() o ExecScalar(). La documentación oficial indica disponibilidad desde la LIB label 20211116 y que el bind sigue las reglas y limitaciones de TCGenQry2.

02 · SINTAXIS

Sintaxis

FWExecStatement():New( <cQuery> ) --> oStatement

Parámetros

cQuery

CarácterObligatorio

Query SQL con marcadores ? para los valores que se asociarán posteriormente.

Métodos

OpenAlias()Executa a consulta e retorna o alias aberto para navegação do result set.oStatement:OpenAlias( [cAlias], [cLifeTime], [cTimeout] ) --> cAlias

Parámetros

NombreFormatoObligatorioDescripciónObservación

cAliasCaractereOpcional

Alias que será criado para o resultado.

cLifeTimeCaractereOpcional

Configuração de tempo de vida da consulta no cache da DBAPI.

cTimeoutCaractereOpcional

Configuração de timeout relacionada ao cache da consulta.

Retorno

cAlias, caractere. Alias em que o resultado foi aberto.

ExecScalar()Executa uma consulta escalar e retorna diretamente o valor da coluna informada.oStatement:ExecScalar( <cColumn>, [cLifeTime], [cTimeout] ) --> xValue

Parámetros

NombreFormatoObligatorioDescripciónObservación

cColumnCaractereObligatorio

Nome da coluna que deve ser retornada.

cLifeTimeCaractereOpcional

Configuração de tempo de vida no cache da DBAPI.

cTimeoutCaractereOpcional

Configuração de timeout relacionada ao cache.

Retorno

xValue, variante. Valor obtido da coluna informada.

SetString()Método herdado de FWPreparedStatement para associar um valor caractere ao marcador indicado.oStatement:SetString( <nParam>, <cValue> )

SetDate()Método herdado para associar uma data AdvPL ao marcador indicado.oStatement:SetDate( <nParam>, <dDate> )

SetBoolean()Método herdado para associar um valor lógico ao marcador indicado.oStatement:SetBoolean( <nParam>, <lValue>, [lProtheus] )

SetIn()Método herdado para associar um array a um marcador utilizado em cláusula SQL IN.oStatement:SetIn( <nParam>, <aValues> )

SetUnsafe()Insere um valor sem o tratamento seguro normal. Use somente quando o valor for controlado e não vier de entrada externa.oStatement:SetUnsafe( <nParam>, <xValue> )

GetFixQuery()Retorna a consulta após o tratamento dos parâmetros, útil para diagnóstico.oStatement:GetFixQuery() --> cQuery

Destroy()Libera o objeto após o uso.oStatement:Destroy()

Retorno

El constructor devuelve un objeto FWExecStatement. La ejecución de la query ocurre posteriormente mediante OpenAlias() o ExecScalar().

03 · EJEMPLO PRÁCTICO

Query parametrizada con OpenAlias()

#Include "TOTVS.ch"

User Function ExFWExec()
    Local cQuery := ""
    Local cAlias := ""
    Local oStmt

    // A1_COD significa “Código”, A1_NOME significa “Nombre” y A1_FILIAL significa “Sucursal”.
    cQuery := "SELECT A1_COD, A1_NOME FROM " + RetSqlName("SA1")
    cQuery += " WHERE A1_FILIAL = ? AND A1_COD = ? AND D_E_L_E_T_ = ' '"
    cQuery := ChangeQuery(cQuery)

    oStmt := FWExecStatement():New(cQuery)
    // Los parámetros comienzan en 1 y siguen el orden de los marcadores ?.
    oStmt:SetString(1, xFilial("SA1"))
    oStmt:SetString(2, "000001")
    cAlias := oStmt:OpenAlias()

    While !(cAlias)->(Eof())
        ConOut((cAlias)->A1_COD + " - " + (cAlias)->A1_NOME)
        (cAlias)->(DbSkip())
    EndDo

    // Cierra primero el alias y después libera el objeto statement.
    (cAlias)->(DbCloseArea())
    oStmt:Destroy()
Return

Resultado esperado

La query asocia la sucursal y el código a los marcadores y abre el resultado en una WorkArea.

04 · EJEMPLO PRÁCTICO

Lista con SetIn()

User Function ExFWExecIn()
    Local cQuery := "SELECT A1_COD, A1_NOME FROM " + RetSqlName("SA1")
    Local cAlias := ""
    Local oStmt
    Local aCodigos := {"000001", "000003"}

    // A1_COD significa “Código”; A1_FILIAL significa “Sucursal”.
    cQuery += " WHERE A1_FILIAL = ? AND A1_COD IN (?) AND D_E_L_E_T_ = ' '"
    cQuery := ChangeQuery(cQuery)

    oStmt := FWExecStatement():New(cQuery)
    oStmt:SetString(1, xFilial("SA1"))
    // SetIn() se hereda de FWPreparedStatement y recibe un array.
    oStmt:SetIn(2, aCodigos)
    cAlias := oStmt:OpenAlias()

    // Se omite el procesamiento del alias para destacar la parametrización.
    (cAlias)->(DbCloseArea())
    oStmt:Destroy()
Return

Resultado esperado

SetIn() asocia la lista de códigos al segundo marcador de la query.

05 · EJEMPLO PRÁCTICO

Valor escalar con ExecScalar()

User Function ExFWScalar()
    Local cQuery := "SELECT COUNT(*) CANT FROM " + RetSqlName("SA1")
    Local oStmt
    Local nCant := 0

    // A1_FILIAL significa “Sucursal”.
    cQuery += " WHERE A1_FILIAL = ? AND D_E_L_E_T_ = ' '"
    cQuery := ChangeQuery(cQuery)

    oStmt := FWExecStatement():New(cQuery)
    oStmt:SetString(1, xFilial("SA1"))
    // ExecScalar() evita abrir un alias cuando solo necesitamos una columna/valor.
    nCant := oStmt:ExecScalar("CANT")
    oStmt:Destroy()

    ConOut("Cantidad: " + CValToChar(nCant))
Return

Resultado esperado

ExecScalar() devuelve directamente el valor de la columna agregada.

BUENAS PRÁCTICAS

Los parámetros son posicionales y comienzan en 1; las llamadas Set* deben seguir el orden de los marcadores ?.
Usa RetSqlName(), xFilial() y ChangeQuery() cuando correspondan al contexto de la query en Protheus.
Cierra el alias devuelto por OpenAlias() y ejecuta Destroy() al terminar.
SetIn() se hereda de FWPreparedStatement y soporta listas utilizadas en cláusulas SQL IN.
La clase está documentada por TOTVS como disponible desde la LIB label 20211116.

ERRORES COMUNES

No agregues comillas SQL alrededor de un marcador rellenado por SetString(); pasa el valor directamente al método.
No uses SetUnsafe() con valores de usuario, solicitudes HTTP u otra entrada no controlada; la documentación oficial alerta sobre SQL Injection.
No olvides cerrar la WorkArea abierta por OpenAlias() antes de destruir el objeto.
No asumas que FWExecStatement reemplaza automáticamente cualquier técnica de query; elige TCQUERY, Embedded SQL o statements parametrizados según el caso.

Contenido relacionado

REFERENCIAS

Estado: Publicado
Página creada el: 30/08/2026 às 00:20
Última revisión el: 30/08/2026 às 00:20
Idioma original: Portugués
Revisión: Usina.BR