Add documentation and tests for quote marks in ECPG literal queries.

ECPG's PREPARE ... FROM and EXECUTE IMMEDIATE can optionally take
the target query as a simple literal, rather than the more usual
string-variable reference.  This was previously documented as
being a C string literal, but that's a lie in one critical respect:
you can't write a data double quote as \" in such literals.  That's
because the lexer is in SQL mode at this point, so it'll parse
double-quoted strings as SQL identifiers, within which backslash
is not special, so \" ends the literal.

I looked into making this work as documented, but getting the lexer
to switch behaviors at just the right point is somewhere between
very difficult and impossible.  It's not really worth the trouble,
because these cases are next to useless: if you have a fixed SQL
statement to execute or prepare, you might as well write it as
a direct EXEC SQL, saving the messiness of converting it into
a string literal and gaining the opportunity for compile-time
SQL syntax checking.

Instead, let's just document (and test) the workaround of writing
a double quote as an octal escape (\042) in such cases.

There's no code behavioral change here, so in principle this could
be back-patched, but it's such a niche case I doubt it's worth
the trouble.

Per report from 1250kv.

Discussion: https://postgr.es/m/673825.1603223178@sss.pgh.pa.us

src/interfaces/ecpg/preproc/pgc.l

@@ -715,7 +715,14 @@ cppline			{space}*#([^i][A-Za-z]*|{if}|{ifdef}|{ifndef}|{import})((\/\*[^*/]*\*+
 					BEGIN(state_before_str_start);
 					if (literallen == 0)
 						mmerror(PARSE_ERROR, ET_ERROR, "zero-length delimited identifier");
-					/* The backend will truncate the identifier here. We do not as it does not change the result. */
+					/*
+					 * The server will truncate the identifier here.  We do
+					 * not, as (1) it does not change the result; (2) we don't
+					 * know what NAMEDATALEN the server might use; (3) this
+					 * code path is also taken for literal query strings in
+					 * PREPARE and EXECUTE IMMEDIATE, which can certainly be
+					 * longer than NAMEDATALEN.
+					 */
 					base_yylval.str = mm_strdup(literalbuf);
 					return CSTRING;
 				}

src/interfaces/ecpg/test/expected/sql-execute.c

@@ -77,8 +77,8 @@ if (sqlca.sqlcode < 0) sqlprint();}
 #line 26 "execute.pgc"
 
 
-	sprintf(command, "insert into test (name, amount, letter) values ('db: ''r1''', 1, 'f')");
-	{ ECPGdo(__LINE__, 0, 1, NULL, 0, ECPGst_exec_immediate, command, ECPGt_EOIT, ECPGt_EORT);
+	/* test handling of embedded quotes in EXECUTE IMMEDIATE "literal" */
+	{ ECPGdo(__LINE__, 0, 1, NULL, 0, ECPGst_exec_immediate, "insert into test (name, \042amount\042, letter) values ('db: ''r1''', 1, 'f')", ECPGt_EOIT, ECPGt_EORT);
 #line 29 "execute.pgc"
 
 if (sqlca.sqlcode < 0) sqlprint();}

src/interfaces/ecpg/test/expected/sql-execute.stderr

@@ -10,7 +10,7 @@
 [NO_PID]: sqlca: code: 0, state: 00000
 [NO_PID]: ECPGtrans on line 26: action "commit"; connection "main"
 [NO_PID]: sqlca: code: 0, state: 00000
-[NO_PID]: ecpg_execute on line 29: query: insert into test (name, amount, letter) values ('db: ''r1''', 1, 'f'); with 0 parameter(s) on connection main
+[NO_PID]: ecpg_execute on line 29: query: insert into test (name, "amount", letter) values ('db: ''r1''', 1, 'f'); with 0 parameter(s) on connection main
 [NO_PID]: sqlca: code: 0, state: 00000
 [NO_PID]: ecpg_execute on line 29: using PQexec
 [NO_PID]: sqlca: code: 0, state: 00000

src/interfaces/ecpg/test/sql/execute.pgc

@@ -25,8 +25,8 @@ exec sql end declare section;
 	exec sql create table test (name char(8), amount int, letter char(1));
 	exec sql commit;
 
-	sprintf(command, "insert into test (name, amount, letter) values ('db: ''r1''', 1, 'f')");
-	exec sql execute immediate :command;
+	/* test handling of embedded quotes in EXECUTE IMMEDIATE "literal" */
+	exec sql execute immediate "insert into test (name, \042amount\042, letter) values ('db: ''r1''', 1, 'f')";
 
 	sprintf(command, "insert into test (name, amount, letter) values ('db: ''r1''', 2, 't')");
 	exec sql execute immediate :command;