/*
 * FiveSqlCls.prg — Public API wrapper: five_SQL() function
 *
 * FiveSql2 — SQL Engine for Harbour DBF/NTX
 *
 * Copyright (c) 2025-2026 Charles KWON (Charles KWON OhJun)
 * Email: charleskwonohjun@gmail.com
 *
 * All rights reserved.
 */

#include "FiveSqlDef.ch"

/*
 * five_SQL( cSQL [, aParams ] [, bBlock ] [, oSession ] ) --> aResult | NIL
 *
 * Execute a SQL statement against the current DBF workareas.
 *
 * Two return modes:
 *   1. Without bBlock: returns { aFieldNames, aRows } on success,
 *                      or { {"__error__"}, {{nCode, cMsg, cSQL}} } on failure.
 *   2. With bBlock:    streams matching rows into the block, spreading
 *                      the SELECT list as positional params. Returns NIL.
 *                      Block mode is the high-performance path — no
 *                      intermediate row array is built.
 *
 * Block mode only fires for simple SELECT queries that the fast path
 * already supports (single table, no JOIN, no GROUP BY, no aggregates,
 * all projections are plain column refs). Complex queries fall back to
 * array mode even when a block is supplied, and the block is invoked
 * once per row after the fact as a compatibility layer.
 *
 * Session parameter:
 *   When oSession is NIL (the common embedded case), the engine uses
 *   a lazy process-default session via SqlDefaultSession() so existing
 *   callers keep working unchanged. The pgserver frontend passes a
 *   fresh TSqlSession instance per connection so concurrent clients
 *   don't share transaction logs or plan caches.
 *
 * Accepts both parameter positions so existing callers still work:
 *   five_SQL( cSQL )
 *   five_SQL( cSQL, aParams )
 *   five_SQL( cSQL, aParams, bBlock )
 *   five_SQL( cSQL, NIL, bBlock )
 *   five_SQL( cSQL, NIL, NIL, oSession )
 */
FUNCTION five_SQL( cSQL, aParams, bBlock, oSession )

   LOCAL oSql := TFiveSQL():New( aParams, oSession )

RETURN oSql:Execute( cSQL, bBlock )