From: drh <>
Date: Wed, 26 Nov 2025 22:58:26 +0000 (+0000)
Subject: Improvements to the QRF README.md file to help clarify how to use it.
X-Git-Tag: artiphishell~166
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9fa8f1d6e0c8f5b46733b7672b1cefbaac2cef90;p=thirdparty%2Fsqlite.git

Improvements to the QRF README.md file to help clarify how to use it.

FossilOrigin-Name: ff589e9e0da99e2248bc7a8bff37e1deb7cbdf8285c18467acd89b65c67401d3
---

diff --git a/ext/qrf/README.md b/ext/qrf/README.md
index 34b0409def..397c082076 100644
--- a/ext/qrf/README.md
+++ b/ext/qrf/README.md
@@ -19,10 +19,10 @@ that can be incorporated and reused by other applications.
 
 ## 1.0 Overview Of Operation
 
-Suppose `pStmt` is a pointer to an SQLite prepared statement
-(a pointer to an `sqlite3_stmt` object) that has been reset and
-bound and is ready to run.  Then to format the output from this
-prepared statement, use code similar to the following:
+Suppose variable `sqlite3_stmt *pStmt` is a pointer to an SQLite
+prepared statement that has been reset and bound and is ready to run.
+Then to format the output from this prepared statement, use code
+similar to the following:
 
 > ~~~
 sqlite3_qrf_spec spec;  /* Format specification */
@@ -41,14 +41,55 @@ if( rc ){
   sqlite3_free(zErrMsg);              /* Free the error message text */
 }else{
   printf("%s", zResult);              /* Report the results */
-  sqlite3_free(zResult);              /* Free memory used to hold results */
 }
+sqlite3_free(zResult);              /* Free memory used to hold results */
 ~~~
 
 The `sqlite3_qrf_spec` object describes the desired output format
 and where to send the generated output. Most of the work in using
 the QRF involves filling out the sqlite3_qrf_spec.
 
+### 1.1 Using QRF with SQL text
+
+If you start with SQL text instead of an sqlite3_stmt pointer, and
+especially if the SQL text might comprise two or more statements, then
+the SQL text needs to be converted into sqlite3_stmt objects separately.
+If the original SQL text is in a variable `const char *zSql` and the
+database connection is in variable `sqlite3 *db`, then code
+similar to the following should work:
+
+> ~~~
+sqlite3_qrf_spec spec;  /* Format specification */
+char *zErrMsg;          /* Text error message (optional) */
+char *zResult = 0;      /* Formatted output written here */
+sqlite3_stmt *pStmt;    /* Next prepared statement */
+int rc;                 /* Result code */
+
+memset(&spec, 0, sizeof(spec));       /* Initialize the spec */
+spec.iVersion = 1;                    /* Version number must be 1 */
+spec.pzOutput = &zResult;             /* Write results in variable zResult */
+/* Optionally fill in other settings in spec here, as needed */
+zErrMsg = 0;                          /* Not required; just being pedantic */
+while( zSql && zSql[0] ){
+  pStmt = 0;                          /* Not required; just being pedantic */
+  rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, &zSql);
+  if( rc!=SQLITE_OK ){
+    printf("Error: %s\n", sqlite3_errmsg(db));
+  }else{
+    rc = sqlite3_format_query_result(pStmt, &spec, &zErrMsg); /* Get results */
+    if( rc ){
+      printf("Error (%d): %s\n", rc, zErrMsg);  /* Report an error */
+      sqlite3_free(zErrMsg);              /* Free the error message text */
+    }else{
+      printf("%s", zResult);              /* Report the results */
+      sqlite3_free(zResult);              /* Free memory used to hold results */
+      zResult = 0;
+    }
+  }
+  sqlite3_finalize(pStmt);
+}
+~~~
+
 ## 2.0 The `sqlite3_qrf_spec` object
 
 The most recent definition of `sqlite3_qrf_spec` is shown below.
diff --git a/manifest b/manifest
index 0b9c4d5c88..9d3d8556e5 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Do\snot\somit\sthe\sbeginning\sand\sending\smargins\swhen\ssetting\sbBorder\sto\sQRF_Off,\nexcept\swhen\sthe\smargins\sneed\sto\sbe\ssqueezed\sto\sfit.\s\sThose\sextra\smargins\sgive\na\smore\spleasing\sappearance,\sand\salso\smake\sthe\soutput\sthe\ssame\sas\spsql.
-D 2025-11-26T21:56:55.233
+C Improvements\sto\sthe\sQRF\sREADME.md\sfile\sto\shelp\sclarify\show\sto\suse\sit.
+D 2025-11-26T22:58:26.158
 F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
@@ -416,7 +416,7 @@ F ext/misc/wholenumber.c 0fa0c082676b7868bf2fa918e911133f2b349bcdceabd1198bba5f6
 F ext/misc/windirent.h 02211ce51f3034c675f2dbf4d228194d51b3ee05734678bad5106fff6292e60c
 F ext/misc/zipfile.c 09e6e3a3ff40a99677de3c0bc6569bd5f4709b1844ac3d1c1452a456c5a62f1c
 F ext/misc/zorder.c bddff2e1b9661a90c95c2a9a9c7ecd8908afab5763256294dd12d609d4664eee
-F ext/qrf/README.md 07dcefad86c259c161d0ec2ee5f8430a88d1645ff9b23f535b7cf27a1c527d32
+F ext/qrf/README.md 86fc5c3c5e3eddbe54fc1235cbdc52b8c2c0732791d224345c3014cd45c4c0e7
 F ext/qrf/qrf.c f5dfef8bcd71144bc57023b875363101f89ab332f13593aed49361cdce8be19e
 F ext/qrf/qrf.h 322d48537a5aa39c206c2ec0764a7938ea7662a8c25be1c4e9d742789609ba1e
 F ext/rbu/rbu.c 801450b24eaf14440d8fd20385aacc751d5c9d6123398df41b1b5aa804bf4ce8
@@ -2180,8 +2180,8 @@ F tool/version-info.c 33d0390ef484b3b1cb685d59362be891ea162123cea181cb8e6d2cf6dd
 F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee87c1b31a7
 F tool/warnings.sh d924598cf2f55a4ecbc2aeb055c10bd5f48114793e7ba25f9585435da29e7e98
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P 5fdedc69b1ac05bcdc40ee30c1473be75d3afe89e031d750c8fc3dcfa9846d5b
-R 07acb13ffa0345c135c8758f8bc105e4
+P 2892aaeed9f55ad87791491068493c2e530eeff4194d156f16745d185760797c
+R 47643b76f3fa2e8ace4e989a9a6981ec
 U drh
-Z 658d4fe01ec54e040334567598ba30cd
+Z d304c4e1d952783653a628c674b5ed4e
 # Remove this line to create a well-formed Fossil manifest.
diff --git a/manifest.uuid b/manifest.uuid
index a5481c7034..52b3d84315 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-2892aaeed9f55ad87791491068493c2e530eeff4194d156f16745d185760797c
+ff589e9e0da99e2248bc7a8bff37e1deb7cbdf8285c18467acd89b65c67401d3