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