SQL Appli ation DevelopmentFrank TompaDavid R. Cheriton S hool of Computer S ien eUniversity of WaterlooCS 348Introdu tion to Database ManagementWinter 2010CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 1 / 34

SQL APIs� Intera tive SQL ommand interpreters (e.g., DB2's ommand linepro essor) are simply domain-independent lient programs thatintera t with an SQL database server� In general, it is ne essary to write other lient programs forspe i� appli ations� SQL has �bindings� for various programming languages thatdes ribe how appli ations written in those languages an be madeto intera t with a database serverNoteThe main problem is the �impedan e mismat h� betweenset-oriented SQL and the appli ation programming language. Howshould data be passed ba k and forth between the two?CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 2 / 34

Outline1 Embedded SQLStati Embedded SQLDynami Embedded SQLSQLJ2 Call Level Interfa es3 Stored Pro eduresCS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 3 / 34

Development Pro ess for Embedded SQL Appli ationsSOURCE CODE

EMBEDDED SQL

EMBEDDED SQL

PREPROCESSOR

SOURCE CODEGeneral stru tureEMBEDDED SQL

C

C

OBJECT

LINKER

EXECUTABLE

EMBEDDED SQL / C

C

CODEOBJECT

CODE

SOURCE

COMPILER

LIBRARIES

SOURCE

PREPROCESSOR

CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 4 / 34

A Simple Example#include <stdio.h>EXEC SQL INCLUDE SQLCA;main() {

EXEC SQL WHENEVER SQLERROR GOTO error;EXEC SQL CONNECT TO sample;EXEC SQL UPDATE Employee

SET salary = 1.1*salaryWHERE empno = ’000370’;

EXEC SQL COMMIT WORK;EXEC SQL CONNECT RESET;return(0);

error:printf("update failed, sqlcode = %ldnn",SQLCODE );EXEC SQL ROLLBACK WORKreturn(-1);

}CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 5 / 34

Stati Embedded SQL� SQL DML and DDL an be embedded in a C program bypre�xing with �EXEC SQL� and su�xing with �;�.� host variables are used to send and re eive values from thedatabase system� values an be sent by using host variables in pla e of onstants.� values an be re eived by using host variables in an INTO lause.NoteThe SELECT statement is (potentially) di�erent in embeddedSQL.CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 6 / 34

De laring Host VariablesEXEC SQL BEGIN DECLARE SECTION;char deptno[4];char deptname[30];char mgrno[7];char admrdept[4];char location[17];EXEC SQL END DECLARE SECTION;

/* program assigns values to variables */

EXEC SQL INSERT INTODepartment(deptno,deptname,mgrno,admrdept,location)

VALUES(:deptno,:deptname,:mgrno,:admrdept,:location);CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 7 / 34

Domain and Type Corresponden eDomain C TypeINTEGER long int v;SMALLINT short int v;REAL �oat v;DOUBLE double v;CHAR(n) har v[n+1℄;VARCHAR(n) har v[n+1℄; orstru t tag { short int len; har v[n℄; }DATE har v[11℄;NoteEa h SQL domain (type) orresponds to a type in the hostlanguage. See, e.g., the DB2 Appli ation Development Guide for omplete list.CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 8 / 34

Queries Using INTOint PrintEmployeeName( char employeenum[] ) {EXEC SQL BEGIN DECLARE SECTION;

char empno[7];char fname[16];char lname[16];

EXEC SQL END DECLARE SECTION;strcpy(empno,employeenum);EXEC SQL

SELECT firstname, lastname INTO :fname, :lnameFROM employeeWHERE empno = :empno;

if( SQLCODE < 0 ) { return( -1 ); } /* error */else if(SQLCODE==100){printf("no such employeenn");}else { printf("%snn",lastname); }return( 0 );

}CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 9 / 34

Indi ator Variables� What if a returned value is NULL?� NULLs are handled using spe ial �ags alled indi ator variables.� Any host variable that might re eive a NULL should have a orresponding indi ator variable.� In C/C++, indi ator variables are short intsCS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 10 / 34

Indi ator Variables: An Exampleint PrintEmployeePhone( char employeenum[] ) {EXEC SQL BEGIN DECLARE SECTION;char empno[7];char phonenum[5];short int phoneind;

EXEC SQL END DECLARE SECTION;strcpy(empno,employeenum);EXEC SQL

SELECT phoneno INTO :phonenum :phoneindFROM employee WHERE empno = :empno;

if( SQLCODE < 0) { return( -1 ); } /* error */else if(SQLCODE==100){printf("no such employeenn");}else if (phoneind<0){printf("phone unknownnn");}else { printf("%snn",phonenum); }return( 0 );

}CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 11 / 34

Cursors� If a query may return more than one row, then a ursor must beuse to retrieve values from the result.� A ursor is like a pointer that refers to some row of the result. Atany time, a ursor may be in one of three pla es:� before �rst tuple� on a tuple� after last tupleBEFORE FIRST TUPLE0

1

2

−n − 1

−n

−n + 1

n − 1

n

n + 1

−2

−1

AFTER LAST TUPLECS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 12 / 34

Using Cursors1 De lare the ursor� De laring a ursor asso iates a ursor identi�er with a query.2 Open the ursor� Opening a ursor ( on eptually) auses the query to be evaluated,generating a result.3 Fet h one or more tuples using the ursor� Ea h all to the FETCH ommand returns values from one tuple ofthe generated result.4 Close the ursorCS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 13 / 34

The FETCH Command Syntaxfetch [<location>] <cursor-name>

[ INTO <host-var1>, <host-var2> : : : ]� Possible lo ations:� NEXT (this is the default)� PRIOR� FIRST� LAST� ABSOLUTE n� RELATIVE nUnfortunately, lo ations annot be spe i�ed in DB2CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 14 / 34

Using Cursors: An Exampleint PrintEmpNames() {

int rval; /* -1 for error, 0 for success */EXEC SQL BEGIN DECLARE SECTION;char fullname[30];EXEC SQL END DECLARE SECTION;EXEC SQL DECLARE C1 CURSOR FORSELECT firstname || ’ ’ || lastname FROM Employee;EXEC SQL OPEN C1;for( ;; ) {

EXEC SQL FETCH NEXT C1 INTO :fullname;if (SQLCODE == 100) { rval = 0; break; }else if (SQLCODE < 0) { rval = -1; break;}printf("%snn", fullname );

}EXEC SQL CLOSE C1;return(rval); }CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 15 / 34

Dynami Embedded SQL� Must be used when tables, olumns or predi ates are not known atthe time the appli ation is written.� Basi idea:1 prepare the statement for exe ution: PREPARE� in stati embedded SQL programs, statement preparation ishandled at ompile time by the prepro essor2 exe ute the prepared statement: EXECUTE� On e prepared, a statement may be exe uted multiple times, ifdesiredCS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 16 / 34

Dynami Embedded SQL: A Simple ExampleEXEC SQL BEGIN DECLARE SECTION;char s[100] ="INSERT INTO department VALUES (’000456’,’Legal’,..)";EXEC SQL END DECLARE SECTION;EXEC SQL EXECUTE IMMEDIATE :s;or, to fa tor ost of �preparing�EXEC SQL BEGIN DECLARE SECTION;char s[100] ="INSERT INTO department VALUES (’000456’,’Legal’,..)";EXEC SQL END DECLARE SECTION;EXEC SQL PREPARE S1 FROM :s;EXEC SQL EXECUTE S1;EXEC SQL EXECUTE S1;CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 17 / 34

Dynami Embedded SQL: Using Host Variables forInputEXEC SQL BEGIN DECLARE SECTION;char s[100] = "INSERT INTO employee VALUES (?, ?, ...char empno[7];char firstname[13];...EXEC SQL END DECLARE SECTION;

EXEC SQL PREPARE S1 FROM :s;strcpy(empno,"000111");strcpy(firstname,"Ken");...EXEC SQL EXECUTE S1 USING :empno, :firstname, ... ;CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 18 / 34

Pla eholders� In the query string"INSERT INTO employee VALUES (?, ?, ... )";the ? are alled pla eholders� pla eholders an appear where literals an appear - not in pla e ofrelation names, olumn names, et .� host variable values repla e the pla eholders when the preparedstatement is exe uted� the USING lause is used to spe ify whi h host variables shouldrepla e the pla eholders:EXEC SQL EXECUTE S1 USING :empno, :firsname, ... ;� USING an only use used with previously-prepared statements,not with EXECUTE IMMEDIATECS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 19 / 34

Dynami Single-Row QueriesEXEC SQL BEGIN DECLARE SECTION;char s[100] ="select lastname,salary from employee where empno = ?"char empno[7];char lastname[16];double salary;short int salaryind;EXEC SQL END DECLARE SECTION;EXEC SQL PREPARE S1 FROM :s;EXEC SQL EXECUTE S1

INTO :lastname, :salary :salaryind USING :empno� INTO (with EXECUTE) in dynami SQL is like INTO (withSELECT) in stati � Note: our DB2 version does not allow the use of INTO withEXECUTE. A dynami ursor must be used to retrieve values.CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 20 / 34

Dynami CursorsEXEC SQL BEGIN DECLARE SECTION;char s[100] ="select lastname,salary from employee where edlevel =short int edlevel;char lastname[16];double salary;short int salaryind;EXEC SQL END DECLARE SECTION;EXEC SQL PREPARE S1 FROM :s;EXEC SQL DECLARE C1 CURSOR FOR S1;edlevel = 18;EXEC SQL OPEN C1 USING :edlevel;while( ... ) {

EXEC SQL FETCH FROM C1INTO :lastname, :salary:salaryind;

}CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 21 / 34

Des riptors and the SQLDA� if the numbers and types of input and output values are notknown in advan e, SQL des riptors an be used determine themat run-time� an SQLDA (des riptor area) is used to hold a des ription of thestru ture (number of attributes and their types) of a query result.� the DESCRIBE ommand an be used to populate a des riptorarea, that is, to �nd out the stru ture of a query resultCS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 22 / 34

SQLJ� SQLJ allows embedding of SQL into Java� Not part of SQL standard, but supported by most DBMSs� Like Embedded SQL, utilizes prepro essing step� stati type he king against database s hema� DBMS an optimize stati queries at ompile time� Unlike Embedded SQL, runtime onne tion established via JDBC onne tion� for es omplian e to SQL standard syntaxCS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 23 / 34

JDBC, ODBC and CLI� CLI (Call-Level Interfa e) is a vendor-neutral ISO standardprogramming interfa e for SQL database systems. It is similar toODBC.� ODBC (Open Database Conne tivity), popularized by Mi rosoft,is a programming interfa e for SQL database systems.� JDBC (Java Database Conne tivity) is a olle tion of Java lassesthat provide an ODBC/CLI-like programming interfa e.� Why?� An embedded SQL program used to a ess one DBMS must bere ompiled before it an be used to a ess a di�erent DBMS.� A CLI/ODBC/JDBC program need not be re ompiled - a singleappli ation may even a ess multiple DBMS at the same time.CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 24 / 34

CLI Overview� Main ideas for both dynami SQL and CLI/ODBC/JDBC1 Queries are represented as strings in the appli ation2 Queries are prepared and then exe uted3 In general, app will not know number and type of input parametersand number and type of output parameters - des riptor areas areused to hold type info (meta data) and a tual data.� �des ribing� a query auses DBMS to analyze query and pla e typeinfo into des riptor area� app an read type info� app an pla e data into des riptor (or into vars to whi h des riptorpoints) before exe uting the query, and an pla e result data intothe des riptor through a ursor afterwards.CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 25 / 34

A CLI ExampleSQLHANDLE henv; /* an environment handle*/SQLHANDLE hdbc; /* a connection handle */SQLHANDLE hstmt; /* a statement handle */SQLCHAR numteamsquery[] = "select count(*) from teams";SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);DBconnect(henv,&hdbc,server,uid,pwd);SQLAllocHandle( SQL_HANDLE_STMT, hdbc, &hstmt );SQLExecDirect(hstmt,numteamsquery,SQL_NTS ); /* executeSQLFetch(hstmt); /* get one row of the result */SQLGetData(hstmt,1,SQL_C_LONG,&numteams,

sizeof(numteams),&bytesremaining);SQLFreeStmt(hstmt,SQL_CLOSE); /* close the statementNoteCLI/ODBC interfa e is similar to dynami embedded SQL, butsyntax is entirely valid host language.CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 26 / 34

Stored Pro eduresIdeaA stored pro edure exe utes appli ation logi dire tly inside theDBMS pro ess.� Possible implementations� invoke externally- ompiled appli ation� SQL/PSM (or vendor-spe i� language)� Possible advantages of stored pro edures:1 minimize data transfer osts2 entralize appli ation ode3 logi al independen eCS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 27 / 34

A Stored Pro edure Example: Atomi -Valued Fun tionCREATE FUNCTION sumSalaries(dept CHAR(3))

RETURNS DECIMAL(9,2)LANGUAGE SQLRETURN

SELECT sum(salary)FROM employeeWHERE workdept = deptCS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 28 / 34

A Stored Pro edure Example: Atomi -Valued Fun tiondb2 => SELECT deptno, sumSalaries(deptno) AS sal \

=> FROM department

DEPTNO SAL------ -----------A00 128500.00B01 41250.00C01 90470.00D01 -D11 222100.00D21 150920.00E01 40175.00E11 104990.00E21 95310.00

9 record(s) selected.CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 29 / 34

A Stored Pro edure Example: Table-Valued Fun tionCREATE FUNCTION deptSalariesF(dept CHAR(3))

RETURNS TABLE(salary DECIMAL(9,2))LANGUAGE SQL

RETURNSELECT salaryFROM employeeWHERE workdept = deptCS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 30 / 34

A Stored Pro edure Example: Table-Valued Fun tiondb2 => SELECT * FROM TABLE \

=> (deptSalariesF(CAST(’A00’ AS CHAR(3)))) AS s

SALARY-----------

52750.0046500.0029250.00

3 record(s) selected.CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 31 / 34

A Stored Pro edure Example: Multiple ResultsCREATE PROCEDURE deptSalariesP(IN dept CHAR(3))

RESULT SETS 2LANGUAGE SQL

BEGINDECLARE emp_curs CURSOR WITH RETURN FOR

SELECT salaryFROM employeeWHERE workdept = dept;

DECLARE dept_curs CURSOR WITH RETURN FORSELECT deptno, sumSalaries(deptno) as sumsalFROM department;

OPEN emp_curs;OPEN dept_curs;

ENDCS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 32 / 34

A Stored Pro edure Example: Multiple Resultsdb2 => call deptSalariesP(’A00’)

SALARY52750.0046500.0029250.00

DEPTNO SUMSALA00 128500.00B01 41250.00C01 90470.00D01 NULLD11 222100.00D21 150920.00E01 40175.00E11 104990.00E21 95310.00

"DEPTSALARIESP" RETURN_STATUS: "0"CS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 33 / 34

A Stored Pro edure Example: Bran hingCREATE PROCEDURE UPDATE_SALARY_IF

(IN employee_number CHAR(6), INOUT rating SMALLINT)LANGUAGE SQL

BEGINDECLARE not_found CONDITION FOR SQLSTATE ’02000’;DECLARE EXIT HANDLER FOR not_found

SET rating = -1;IF rating = 1 THEN

UPDATE employeeSET salary = salary * 1.10, bonus = 1000WHERE empno = employee_number;

ELSEIF rating = 2 THENUPDATE employeeSET salary = salary * 1.05, bonus = 500WHERE empno = employee_number;

ELSEUPDATE employeeSET salary = salary * 1.03, bonus = 0WHERE empno = employee_number;

END IF;ENDCS 348 (Intro to DB Mgmt) SQL APIs Winter 2010 34 / 34