# sum-cp -- summary of PRE-SQL
# $Id$
# Carlos Duarte <cgd@teleweb.pt>, 990702

Overview
--------
	. a pre-sql statement is: 

		EXEC SQL ... ; 

	  where `...' is an, SQL like, expression

	. the pre-sql statement itself is case insensitive

	. it may appear wherever a C statement can

	. interface with C host vars, is done by prefix them with colons ":"

		exec sql select Name into :name; 

	  here, "name" is a C variable.

	. SQL statements (queries), might extended by several lines, 
	  ending on a semicolon ";"

Host variables
--------------

exec sql begin declare section;
/* normal C declarations... */
exec sql end declare section;

	. variables declared this way, might appear on SQL queries, prefixed
	  by ":"

	. the enclosed begin/end declare sections should appear anywhere
	  where a normal C var can also

Connecting
----------

exec sql connect :user [identified by :pass] [at :conn_name] [using :server] ; 

	. opens a new connection 
	. multiple connections might be done, using different connection
	  names, which form, therefor, the connection with

exec sql disconnect { conn_name | current | default | all } ; 

	. disconnects a previous opened session

exec sql [at connection :conn_name] .... ;

	. execute SQL query explicitly at a given connection

exec sql set connection :conn_name;
	
	. sets the default connection to be the one indicated by CONN_NAME

exec sql use DATABASE ; 
	
	. set database for use

Catching errors
---------------

exec sql whenever 
	{ sqlwarning | sqlerror | not found }
	{ continue | goto label | call function ([arg [,arg2]..]) | stop }
	; 

	. specify behavior when warn/err/not_found happens

NULLS
-----

exec sql .... into :host_var indicator :ind_var ; 
exec sql .... from :host_var indicator :ind_var ; 

	. indicator (IND_VAR above), are of type SMALLINT
	. if HOST_VAR _receives_ data from query, then IND_VAR is: 
		-1	NULL data received
		0 	ok
		>0	data truncated

	. if HOST_VAR _sends_ data to query, then IND_VAR is: 

		-1 	send a NULL, no matter what HOST_VAR contains
		0	send content of HOST_VAR

Procedures
----------

exec sql exec :retcode = stored_proc :arg1 out, :arg2 ; 

	. executes STORED_PROC
	. passes ARG2 as an input argument
	. passes ARG1 as an output argument
	. result of procedure, is returned in RETCODE, which is a SMALLINT