Documentation Style Issue - semi-colon at the end of SQL statement examples

[Laura Stewart-2]

Hi -
Should there be a semi-colon at the end of the SQL statement examples
in the Derby documentation.  In other documentation work that I have
done, this was the standard. I just wanted to check with the Derby
community to see what is appropriate for the Derby docs.

--
Laura Stewart

[Army-4]

Laura Stewart wrote:
> Hi -
> Should there be a semi-colon at the end of the SQL statement examples
> in the Derby documentation.  In other documentation work that I have
> done, this was the standard. I just wanted to check with the Derby
> community to see what is appropriate for the Derby docs.

I don't know if there's a "rule" for this in Derby docs, but it seems to me that
at some point someone somewhere pointed out that, technically, the semi-colon is
NOT part of the SQL statement.  For example, I think if you include the
semi-colon at the end of a SQL statement in a JDBC call like:

   ResultSet rs = st.executeQuery("SELECT * FROM T1;");

the result will be a syntax error caused by the presence of the semi-colon:

ERROR 42X01: Syntax error: Encountered ";" at line 1 ...

I think the semi-colon is a popular statement terminator for a lot of
command-line interfaces to databases, including Derby's own ij.  But in the case
of ij the semi-colon is stripped off before the statement is actually passed to
the Derby engine, so it (the semi-colon) is really an ij requirement, not a SQL
statement requirement.

My personal answer to your question, then, would be that the semi-colon should
only be included if the doc is showing the example statement as it would be
executed in ij.  So if the doc looked like:

ij> connect 'mydb';
ij> select * from t1;

I'd say include the semi-colon.  But if the example is just an example of how to
select all the rows from t1 or an example of how to use the syntax for a Derby
SQL statement, I'd say leave the semicolon off:

   select * from t1

FWIW,
Army

[Knut Anders Hatlen]

Laura Stewart <scotsmatrix@...> writes:

> Hi -
> Should there be a semi-colon at the end of the SQL statement examples
> in the Derby documentation.  In other documentation work that I have
> done, this was the standard. I just wanted to check with the Derby
> community to see what is appropriate for the Derby docs.

If the example is shown in ij, it should be there. If it is just an
example SQL statement, I think it should be written without a
semicolon.

--
Knut Anders

[Bernt M. Johnsen]

Details from the standard (maybe I'm just nit-picking.... ;-)

Semicolon in SQL is used
1) After statements in trigger and procedure bodies (we don't support this)
2) In various embedded SQL variants (Statements are terminated with
semicolon when SQL is embedded in Ada, C, Pascal, PL/I. Declarations is
terminated with semicolon when SQL is embedded in C and MUMPS... etc)
3) A "direct SQL statement" is terminated by semicolon (as in ij)

I think semicolon should *only* be used in examples when the standard
requires a semicolon. And that is basically exactly what Army and Knut
Anders points out.

Knut Anders Hatlen wrote:

> Laura Stewart <scotsmatrix@...> writes:
>
>> Hi -
>> Should there be a semi-colon at the end of the SQL statement examples
>> in the Derby documentation.  In other documentation work that I have
>> done, this was the standard. I just wanted to check with the Derby
>> community to see what is appropriate for the Derby docs.
>
> If the example is shown in ij, it should be there. If it is just an
> example SQL statement, I think it should be written without a
> semicolon.
>

--
Bernt Marius Johnsen, Database Technology Group,
Staff Engineer, Technical Lead Derby/Java DB
Sun Microsystems, Trondheim, Norway