Re: [INTERFACES] ExecCommandOk() return code always zero?

So, the apparent problem is not with the code so much as my
interpretation of what the functions are for, and what the meaning of
the return value is.

I guess I find these two functions a little esoteric; I don't believe
they should be meddling in what the command/query is as that is for the
backend server to deal with. I would have thought that ExecCommandOk()
would return PGRES_COMMAND_OK if execution was successful, or
PGRES_NONFATAL_ERROR or PGRES_FATAL_ERROR if execution failed.
ExecTuplesOk() would return PGRES_TUPLES_OK if successful and tuples
were available, PGRES_QUERY_EMPTY if successful but no tuples were
returned, and PGRES_NONFATAL_ERROR or PGRES_FATAL_ERROR if execution
failed. However, I know that if for no other reason than backward
compatibility, this ain't gonna happen. (I see where I'm going to have
to whip together some new Exec() wrappers! ;)

Anyways, I'd be happy to suggest a doc revision. First of all, I like
to suggest a bit of a nomenclature change. That is this; SQL is a
language of statements. Every statement is either a command (does not
return data), or a query (returns data). That is, a "command" tells the
backend server to do something (INSERT, UPDATE, ALTER) and expects
nothing in return other than information about how the command execution
went.

All that ranting and whining aside, how about something like the
following:

ExecCommandOk(): Sends a command to the backend server. The command
should not be a query that can return tuples (e.g. SELECT).

PgConnection::ExecCommandOk(const char *command)

Returns TRUE if execution was successful.
Returns FALSE if execution failed or a query was sent.

ExecTuplesOk(): Sends a query to the backend server. The query should
not be a command that can not return tuples (e.g UPDATE, INSERT, etc.).

PgConnectin::ExecTuplesOk(const char *query)

Returns TRUE if command executed successfully.
Returns FALSE if execution failed or a command was sent.

(I know that in light of my previous rantings about
statement/command/query that saying "The command should not be a query
[...]" and "The query should not be a command [...]" are somewhat odd
statements. If the documentation DID distinguish between a statement,
command and query, the descriptions could be reduced to "Sends a command
to the backend server" and "Sends a query to the backend server"
respectively).

Also, it might not hurt to put a note in the Caveats section indicating
that ExecCommandOk() will properly execute a query and ExecTuplesOk()
will properly execute a command. However in both cases a return code of
FALSE will result.

Thank-you very much for explaining these two functions, Tom. I'd have
dicked around with this for quite a while before I discovered what was
going on here.

Cheers,
Richard

Tom Lane wrote:
>
> Richard <blackw(at)sfu(dot)ca> writes:
> Those docs are certainly wrong about ExecTuplesOk. ExecTuplesOk
> should return TRUE if your query was valid, regardless of whether
> any tuples were found. Otherwise, you cannot tell the difference
> between a bogus query (a syntax error, for example) and a correct
> query that returned zero tuples.
>
> ExecCommandOk is supposed to be used for query types that are incapable
> of ever returning tuples (INSERT or UPDATE for example).