Intro to Embedded
SQL Programming for
ILE RPG Developers
Dan Cruikshank
DB2 for i Center of Excellence
Event Title
1
Agenda
f
Reasons for using Embedded SQL
f
Getting started with Embedded SQL
f
Using Host Variables
f
Using Indicator Variables
f
Using a cursor
f
Reading/writing more than 1 row at a time
f
Updating and deleting multiple rows
f
Best practices
Event Title
2
Reasons for Using Embedded SQL
f
Leverage SQL set processing when processing large
amounts of data
f
f
f
Event Title
3
Automatic input/output blocking, searched updates,
etc.
Take advantage of HLL programming constructs not
available to DB2 SQL Procedure Language (PSM)
f
Blocked INSERT support via externally described data
structures
f
Built-in functions not available in DB2
To take advantage of the full range of performance
optimizations from the Query Optimizer
Getting Started with Embedded SQL
f
Licensed program
IBM® DB2 Query
Manager and SQL
Development Kit for
i5/OS.
f
Compilers for the
host languages you
want to use.
Event Title
4
Rules for Embedding SQL in HLL
programs
f
Each SQL statement must begin with EXEC SQL
and end with a semicolon (;)
f
The EXEC SQL keywords must be on the same line
f The SQL statement can be on the same line or
multiple lines
f
Only 1 SQL statement for each EXEC SQL group
f
Refer to the Embedded SQL Programming
manual for other language specific
restrictions/conventions
Event Title
5
Types of SQL
f
f
f
Event Title
6
Embedded SQL is a general term for SQL in an
application program and can be either Static or
Dynamic
f
Static SQL validated during compilation
f
Dynamic SQL validated during preparation
f
Both produce plans that can be shared and reused
Both Static and Dynamic can be used in the
same program
f
SQL EXEC SELECT COUNT(*) INTO…
f
SQL EXEC EXECUTE IMMEDIATE ‘DELETE…’
SQL implemented in PSM is generally Static but
can also be Dynamic
Advantages of Dynamic SQL
f
Offers a high degree of application flexibility
f
Can create/build SQL statement based on
parameters received from:
f
Event Title
7
f
Interactive user interface
f
List selection techniques
f
Application control file
f
RPG Open Access
Two types:
f
Fixed list (does not require a descriptor)
f
Varying List (requires a descriptor)
Using Host Variables
f
Host Variable
f
f
8
specify a value in the predicate of a search condition
f
replace a literal value in an expression
f
Provide a target to receive a value from an INTO clause
A group of host variables commonly used to:
f
Specify values for VALUES clause (INSERT), SET clause (UPDATE)
f
Provide a target to receive multiple values from a FETCH or
SELECT INTO
Host Structure Array
f
Event Title
f
Host Structure
f
f
Single field commonly used to:
A multiple occurrence data structure or array
f
Commonly used for blocked FETCH and INSERT statements
f
Currently not supported in SQL PL
Assigning Host Variables
f
SQL values are assigned
f
to host variables during the running of
f
f
from host variables during the running of
f
f
9
INSERT, UPDATE, and CALL statements.
Use soft-coding techniques to avoid data
conversion or data mapping errors
f
Event Title
FETCH, SELECT INTO, SET, and VALUES INTO statements.
For instance:
f
SQL Descriptors or SQLDA
f
Externally described data structures
f
RPG Template support
Host Structure Array Soft-Coding
Techniques
f
RPG Example
FSQLVIEW IF E
DISK
F RENAME(SQLVIEWR:INPRECORD3)
F
TEMPLATE
TEMPLATE added in 6.1
DR3
DS
D result_set...
D
DS
D CITY D STATE D ZIPCODE Event Title
10
LIKEREC(INPRECORD3)
OCCURS(10000)
LIKE(R3.CITY)
LIKE(R3.STATE)
LIKE(R3.ZIPCODE)
SQL Descriptor Areas
What are they?
f
An SQL descriptor area is used
to contain information about a
dynamic SQL statement
f
A set of variables are used to
communicate this information
between SQL and your
program
f
f
The meaning of the information
in the descriptor area depends
on the type of statement
f
Event Title
11
Think externally described data
structure with a variable file
name
SELECT or non-SELECT (UPDATE,
INSERT, etc.)
Where could they be used?
f
Eliminate DDS Select/Omit
Logical Files or SQL Sparse
Indexes
f
Replace OPNQRYF or
embedded RUNQRY
commands
f
Create Generic SQL Open
Access Handlers
f
Provide single stored procedure
for all data access to/from a
view
f
Minimize SQL coding
Static Vs Dynamic Host Structures
Static SQL Host Array
Dynamic SQL Descriptors
One SQL Service PGM per format
One SQL Service PGM
Event Title
12
Variable WHERE Clause
CALL PROC1 (‘ABC’, ‘X127B89’);
Construct WHERE clause
ALLOCATE DESCRIPTOR
• SELECT * FROM VIEW WHERE Company = ? And Store =?
• Size of descriptor based on number of parameter markers (?)
Descriptor
Size
Max Nbr of Vars
Actual nbr of vars
96 bytes
2
2
Type
Length
Name
Data
CHAR
3
Company
‘ABC’
VARCHAR
15
Store
‘X127B89’
Event Title
13
PREPARE and SET DESCRIPTOR
DECLARE and OPEN CURSOR
• Load descriptor with column attributes and variables
• Result set based on parameter values
Company
Store
…
…
ABC
X127B89
1
A
ABC
X127B89
2
B
ABC
X127B89
3
C
Using Indicator Variables for Input Operations
f
Indicator Variable
Further defines the contents
of a host variable
f Half word (2 byte) integer
type
f Indicator value used to
denote nulls, data mapping
errors or string truncation
f
f
Always test the indicator
variable first
f
Example of testing for NULL
EXEC SQL
SELECT COUNT(*),
AVG(SALARY)
INTO :vCount,
:vSalary:INDVAR
FROM EMPLOYEE_VIEW
WHERE EDLEVEL < 18;
Event Title
14
HLL
Indicator Variable
Definition
C
short
COBOL
PIC S9(4) COMP-4 or
PIC S9(4) BINARY
RPG
5i 0 or 4b 0
If INDVAR < 0 then
vSalary is
not usable
Input Indicator Array
ƒ An array of indicator variables
ƒ Used to support host structures
ƒ The number of indicators must equal the number of
columns in the host structure
– For host arrays there needs to be an equivalent
number of indicator arrays
RPG Host Array Example
DSAL_REC
D MIN_SAL
D AVG_SAL
D MAX_SAL
DS
OCCURS(10)
6P 2
6P 2
6P 2
DSAL_IND_ARY DS
D SAL_IND
Equal to number
of structures
OCCURS(10)
4B 0 DIM(3)
Equal to number of columns
Event Title
15
Indicator Values for INSERT and
UPDATE
Normal indicators
f
f
If zero then use host variable value
f
If negative 1 then set to NULL
Example of setting a column to NULL
f
PHONEIND = -1;
EXEC SQL
UPDATE EMPLOYEE_VIEW
SET
PHONENO=:NEWPHONE:PHONEIND
WHERE EMPNO = :EMPID;
Event Title
16
After completion of
UPDATE PHONENO will
be NULL
Extended Indicator Values for INSERT and UPDATE
f
Extended indicators
f
Provides more flexibility
f
Single SQL statement can be used for multiple INSERT and UPDATE
scenarios
f
f
Besides nulls, columns can be set to defaults or ignored completely
The following table describes the possible indicator values along with
their intended purpose
Indicator Value
Purpose
0
Use host variable value
-1, -2, -3, -4 or -6
Set column to NULL
-5
Use default value for column
-7
For UPDATE ignore, for INSERT use default
Event Title
17
Extended Indicators UPDATE Scenarios
f
Multiple users execute a common table maintenance program
f
f
Each user updates different columns within the table
The maintenance program calls a common service program
Each instance of the maintenance program passes a record structure
containing the column update values and an indicator array
f The service program issues a single update to the SQL view
f
f
The following is a diagram depicting the above scenario:
ADDRLINE3 = p_ADDRLINE3;
Ind_Ary(3) = 0;
Call Srv_Pgm(Upd_View:Ind_Ary);
T
H
R
E
A
D
S
ADDRLINE2 = p_ADDRLINE2;
Ind_Ary(2) = 0;
Call Srv_Pgm(Upd_View:Ind_Ary);
D
D
Upd_View LIKEDS(Upd_Record)
Ind_Ary 5i 0 DIM(3) INZ(-7)
ADDRLINE1 = p_ADDRLINE1;
Ind_Ary(1) = 0;
Call Srv_Pgm(Upd_View:Ind_Ary);
Reset Ind_Ary;
Event Title
18
CALL
Service Pgm
D Srv_pgm
D HV
D Ind_Ary
D Ind_Ary_Ptr
D Ind_Ary_DS
D
Ind_Ary_1
D
Ind_Ary_2
D
Ind_Ary_3
PI
N
LIKEDS(Upd_Record)
5i 0 DIM(3)
S
*
BASED(Ind_Ary_Ptr)
DS
5i 0
5i 0
5i 0
EXEC SQL
UPDATE EMPLOYEE_ADDRESS_VIEW
SET ADDRLINE1 = :HV.ADDRLINE1:Ind_Ary_1,
ADDRLINE2 = :HV.ADDRLINE2:Ind_Ary_2,
ADDRLINE3 = :HV.ADDRLINE3:Ind_Ary_3,
WHERE EMPNO = :HV.EMPNO;
S
R
V
P
R
O
G
R
A
M
Using an SQL Cursor
f
SQL Statements used with a Cursor
f
DECLARE an SQL cursor
f
OPEN a declared SQL cursor
f
FETCH from an open SQL cursor
f
CLOSE an open SQL cursor
Event Title
19
DECLARE CURSOR – Input only or Update
f
By default, all columns may be updated or deleted
f
FOR UPDATE OF - lists the columns that are to be updated
f
f
f
f
only columns NOT included in ORDER BY are eligible
FOR READ ONLY - specifies no updating/deleting allowed
Considerations:
f
FOR READ ONLY – better concurrency and documentation
f
FOR UPDATE OF - security; better throughput and documentation
f
With Hold clause useful with commitment control
f
Default – cursors are closed with commit/rollback commands
f
With Hold – keeps cursor open
Example:
/FREE
EXEC SQL
DECLARE empcsr CURSOR WITH HOLD FOR
SELECT empno, lastname, SALARY
FROM EMPLOYEE_VIEW
WHERE workdept = :dept
FOR UPDATE OF SALARY;
Event Title
20
DECLARE CURSOR – Returning the result set
f
WITH RETURN allows the result set to be accessed by a
calling program
f
f
f
Default is return to program
f
f
Very useful in client/server or web applications
Available to RPG in release 7.1
WITH RETURN TO CLIENT allows nested programs to return
result sets to client program
Example
/FREE
EXEC SQL
DECLARE empcsr CURSOR WITH RETURN TO CLIENT
SELECT empno, lastname, SALARY
FROM EMPLOYEE_VIEW
WHERE workdept = :dept
FOR READ ONLY;
/END-FREE
Event Title
21
DECLARE CURSOR – using extended indicators
f
Allows extended indicators to be used with
positioned updates
f
Overrides SQL pre-compiler option
f Best practice is to tell DB2 everything you
know
f
Example
/FREE
EXEC SQL
DECLARE empcsr CURSOR
WITH HOLD WITH EXTENDED INDICATORS FOR
SELECT empno, lastname, SALARY
FROM EMPLOYEE
WHERE workdept = :dept
FOR UPDATE OF SALARY;
Event Title
22
OPEN a Declared SQL Cursor
f
Executes the SELECT Statement For a Declared Cursor
f
Validates SQL and allocates required resources
f
Successful Open places the file cursor before the first
row of the result table
f
Cursor must be closed before it can be opened
f
Example
/Free
EXEC SQL OPEN empcsr;
Event Title
23
FETCH From an Open SQL Cursor
f Two
f
Functions
Position the cursor at the start of the result set
EXEC SQL
FETCH FIRST FROM empcsr;
f
INTO Bring rows/records into the program
EXEC SQL
FETCH NEXT FROM empcsr
INTO :number, :name, :pay;
f
Event Title
24
Note: FETCH NEXT after OPEN is same as
FETCH FIRST
Multiple Row FETCH
f
f
RPG Multiple Occurrence Data Structure or Array
Clause on FETCH
f
FOR n ROWS (n = max number of rows to be returned)
f
f
f
Can be host variable
Specify number of rows to be retrieved to fill the structure
Example
D
D
D
D
Result_set
empnbr
firstname
dpt
D v_row_count
DS
S
OCCURS(10)
LIKE(empno)
LIKE(firstnme)
LIKE(workdept)
31P 0
/FREE
EXEC SQL
FETCH FROM Employee_Cursor
FOR 10 ROWS INTO Result_set;
EXEC SQL
GET DIAGNOSTICS :v_Row_Count = ROW_COUNT;
/END-FREE
Event Title
25
Number of rows can be 1 to
maximum occurrence of data
structure
GET DIAGNOSTIC returns actual
number of rows fetched
CLOSE an Open SQL Cursor
f
Closes the cursor
f
DB2 for i will attempt to perform a “soft” close
f
Open Data Path (ODP) is reused
f
Cursor must be opened in order to be closed
f
DB2 for i “hard” closes cursors for the following reasons:
f job end
f activation group ends
f Precompiler option CLOSQLCSR is not properly set
f commit or rollback without a 'with hold' clause
f error handling......
f
Best practice - close the cursor when finished with it
Example
f
/EXEC SQL CLOSE
Event Title
26
empcsr;
Accessing Result Sets
f
ASSOCIATE LOCATORS and ALLOCATE CURSOR (7.1)
f
Allows a result set created within a stored procedure to be
returned to the calling program
f
Example
D RS_LOC1 S SQLTYPE(RESULT_SET_LOCATOR)
EXEC SQL ASSOCIATE LOCATORS (:RS_loc1) WITH PROCEDURE P1;
EXEC SQL ALLOCATE C1 CURSOR FOR RESULT SET :RS_loc1;
f
Pointers
f
The data structure used for passing row data is based on a
pointer
f
The procedure populates the data structure and the results
are available upon return to the calling program
f
Example
D ViewHostArray...
D
DS
D
D
Event Title
27
OCCURS(29000)
LIKEREC(SQLRESULT)
BASED(HostArrayPtr)
ASSOCIATE LOCATORS and ALLOCATE CURSOR
(7.1)
Stored Procedure Example
CREATE PROCEDURE RS1_PROC (
IN P_WDEPT CHAR(3))
RESULT SETS 1
DECLARE RS1_PROC_C1 CURSORFOR
SELECT * FROM VEMPDPT3
WHERE WORKDEPT = p_WDEPT;
OPEN RS1_PROC_C1;
Event Title
28
HLL Program Example
EXEC SQL CALL RS1_PROC (E11);
EXEC SQL ASSOCIATE RESULT SET
LOCATORS (:RS_Loc1)WITH PROCEDURE
RS1_PROC;
EXEC SQL ALLOCATE C1 CURSOR FOR
RESULT SET :RS_Loc1;
EXEC SQL FETCH NEXT FROM C1 FOR n
ROWS INTO:RS_Array;
EXEC SQL SET RESULT SETS ARRAY
:RS_Array FOR n ROWS;
Consuming Result Set Program Flow
f
Simplifies coding effort
f
f
Results
Event Title
29
Single procedure can be used
by multiple applications
Allows exploitation of what SQL
does best
f
Reusable cursors
f
Blocked FETCH
f
Advanced join technology
f
1 cursor versus multiple open
files
f
1 IO versus multiple file reads
Blocked INSERT
Multiple elements from a host structure are
inserted into a table
f Program variable may be used to set the number
of records to be inserted
f Executes as if n INSERT statements had been
issued
f but with improved performance
f
f
Example
OCCURS(10)
D empnbr
LIKE(empno)
D firstname
D dpt
LIKE(firstnme)
LIKE(workdept)
EXEC SQL
INSERT INTO Employee_view
10 ROWS VALUES :Result_set
Event Title
30
Updating and/or Deleting Multiple
Rows
f
f
Searched UPDATE/DELETE
f
All rows selected are updated in a single SQL
statement
f
Eliminates need for cursor and For loop
f
Can be used with extended indicators
Examples:
EXEC SQL DELETE EMPLOYEE_VIEW
WHERE SALARY + BONUS + COMM = 0;
EXEC SQL UPDATE EMPLOYEE_VIEW SET BONUS = 1000
WHERE WORKDEPT = 'D11';
Event Title
31
Best Practices
f Use
f
SQL Views -
easier to soft code, mask complexity
f Use
data access modules
f
HLL - ILE service programs
f
SQL - PROGRAM TYPE SUB
f Use
NULL indicator support
f Use
dynamic SQL
f
Parameter Markers, Descriptors
f Use
pre-compiler opiton
CLOSQLCSR(*ENDACTGRP)
Event Title
32
IBM Education Roadmap for DB2 & SQL
f
DB2 for i Advanced Programming
f Data Modeling Best Practices
f DB2 for i Architecture and Types of SQL
f Data Cenric Development DDL and DML basics
f Embedded SQL within an HLL program – use of
host variables and indicator variables
f Thinking in Sets and Processing Data Sets
f Error Detection Dynamic SQL
f Debugging Tools – using the debugger, running
SQL Scripts
f Advanced Table and Index Definition
f Sequence and Variable Objects
f Joins, views, subqueries, common table
expressions
f Instead of Triggers, Online Analytical Processing
(OLAP)
f SQL Procedures, User Defined Functions, and
Triggers
f And more…
f Labs
f
SQL only via System I Navigator
f
SQL and Embedded SQL via iNav and RDP and IBM
Data Studio
Event Title
33
Event Title
34