cQueryCaractereObrigatório
Consulta SQL com marcadores ? para os valores que serão associados posteriormente.
CLASSEPublicado
FWExecStatement
FWExecStatement():New( <cQuery> ) --> oStatementExecuta consultas SQL parametrizadas com bind de valores, abertura do resultado em alias e suporte aos recursos herdados de FWPreparedStatement.
Visão geral
FWExecStatement é derivada de FWPreparedStatement e encapsula os conceitos de execução/cache de consultas utilizados pelo Framework. A classe permite construir uma instrução com marcadores ?, associar valores por tipo e executar a consulta por OpenAlias() ou ExecScalar(). A documentação oficial informa disponibilidade a partir da LIB label 20211116 e orienta respeitar as regras e limitações da TCGenQry2 utilizadas no bind.
Sintaxe
FWExecStatement():New( <cQuery> ) --> oStatementParâmetros
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
NomeFormatoObrigatórioDescriçãoObservação
cAliasCaractereOpcionalAlias que será criado para o resultado.
cLifeTimeCaractereOpcionalConfiguração de tempo de vida da consulta no cache da DBAPI.
cTimeoutCaractereOpcionalConfiguraçã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
NomeFormatoObrigatórioDescriçãoObservação
cColumnCaractereObrigatórioNome da coluna que deve ser retornada.
cLifeTimeCaractereOpcionalConfiguração de tempo de vida no cache da DBAPI.
cTimeoutCaractereOpcionalConfiguraçã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
O construtor retorna o objeto FWExecStatement. A execução ocorre posteriormente por OpenAlias() ou ExecScalar().
Consulta parametrizada com OpenAlias()
#Include "TOTVS.ch"
User Function ExFWExec()
Local cQuery := ""
Local cAlias := ""
Local oStmt
// A1_COD é o código, A1_NOME o nome e A1_FILIAL a filial do cliente.
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)
// Os parâmetros começam em 1 e seguem a ordem dos 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
// Libere primeiro o alias e depois o objeto statement.
(cAlias)->(DbCloseArea())
oStmt:Destroy()
ReturnResultado esperado
A consulta associa filial e código aos marcadores e abre o resultado em uma WorkArea.
Lista com SetIn()
User Function ExFWExecIn()
Local cQuery := "SELECT A1_COD, A1_NOME FROM " + RetSqlName("SA1")
Local cAlias := ""
Local oStmt
Local aCodigos := {"000001", "000003"}
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() é herdado de FWPreparedStatement e recebe um array.
oStmt:SetIn(2, aCodigos)
cAlias := oStmt:OpenAlias()
// Processamento do alias omitido para destacar a parametrização.
(cAlias)->(DbCloseArea())
oStmt:Destroy()
ReturnResultado esperado
SetIn() associa a lista de códigos ao segundo marcador da consulta.
Valor escalar com ExecScalar()
User Function ExFWScalar()
Local cQuery := "SELECT COUNT(*) QTD FROM " + RetSqlName("SA1")
Local oStmt
Local nQtd := 0
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 alias quando precisamos somente de uma coluna/valor.
nQtd := oStmt:ExecScalar("QTD")
oStmt:Destroy()
ConOut("Quantidade: " + CValToChar(nQtd))
ReturnResultado esperado
ExecScalar() retorna diretamente o valor da coluna agregada.
- Os parâmetros são posicionais e começam em 1; a ordem dos Set* deve corresponder à ordem dos marcadores ? da consulta.
- Use RetSqlName(), xFilial() e ChangeQuery() quando aplicáveis ao contexto da consulta Protheus.
- Feche o alias retornado por OpenAlias() e execute Destroy() ao final do processamento.
- SetIn() é herdado de FWPreparedStatement e atende listas usadas em cláusulas IN.
- A classe está documentada pela TOTVS como disponível a partir da LIB label 20211116.
- Não coloque aspas SQL ao redor de um marcador que será preenchido por SetString(); passe o valor normalmente ao método.
- Não use SetUnsafe() com valores recebidos de usuário, requisição HTTP ou outra origem não controlada; a documentação alerta para risco de SQL Injection.
- Não esqueça de fechar a WorkArea aberta por OpenAlias() antes de destruir o objeto.
- Não presuma que FWExecStatement substitui toda técnica de consulta; escolha entre TCQUERY, Embedded SQL e statements parametrizados conforme o caso.
Comentários
Ainda não há comentários aprovados.
Entre com Google ou Microsoft para comentar.