Moving from Oracle web toolkit to Apex 4.2 - oracle

Question

Suppose I have a procedure like this
CREATE OR REPLACE PROCEDURE my_proc IS
var_empno emp.empno%type;
var_ename emp.ename%type;
var_bonus emp.bonus%type;
var_budget number;
var_budget := 100000;
CURSOR EMP_CURSOR IS
select empno, ename, bonus from emp order by empno;
BEGIN
htp.print('EMPLOYEE NUMBER EMPLOYEE NAME BONUS');
open EMP_CURSOR;
LOOP
fetch EMP_CURSOR into var_empno, var_ename, var_bonus;
//------Give employee a extra $1,000 bonus if budget allows-----------.
EXIT when EMP_CURSOR%NOTFOUND;
IF (var_budget >= 1000) then
var_budget := var_budget - 1000;
var_bonus := var_bonus + 1000;
END IF;
//----DBMS_OUTPUT.put_line(var_empno || ' ' || var_ename || ' ' || var_bonus);
htp.print(var_empno || ' ' || var_ename || ' ' || var_bonus);
END LOOP;
close EMP_CURSOR;
END;
The procedure selects empno, name, and bonus from the emp table ordered by lowest empno. The cursor loops through and adds $1,000 to the bonus variable if var_budget has the funds for it. The report uses htp.print.
Of course this is just a simple example and my report html would be formatted better. We have over 100 procedures like this. What is the best way to handle logic like this in APEX where a cursor is used and the output is unique for each row. APEX seems to be good with simple select statements. But I am unclear how to convert procedures like this for APEX 4.2

Answer 1

Adapting Oracle REF CURSOR Data for APEX Report Regions
The following solution was developed on a demo hosted instance of Oracle Apex at apex.oracle.com; At the time this was done, the hosted Apex release version was: 4.2.5
Depending on which version of Oracle you are looking at, the implementation of REF CURSOR logic has changed in small ways. I found a good discussion here from Oracle-Base. The notable changes include:
Creation of a SYS_REFCURSOR type, which eliminates the need for developers to declare their own custom types independently to have a REF CURSOR type to reference in their code.
Programming languages/platforms such as Microsoft ADO or Java have syntax and structures that are equipped to open and iterate over the records stored in a REF CURSOR. This is probably why there are many shops like yours with procedural code in REF CURSOR data structures; they're simple and compatible with other programming languages.
APEX report region definitions work best with a data input defined by a SQL SELECT query.
Adapting Existing REF CURSOR Based PL/SQL Code from Oracle Web Toolkit
Here is the sample procedure from the OP with comments on initial changes to adapt it for use with an APEX Report Output region.
CREATE OR REPLACE PROCEDURE my_proc (bonus_increase IN number,
result_data OUT sys_refcursor) IS
-- (1) Replace Procedure Declaration to include output REF CURSOR
-- CREATE OR REPLACE PROCEDURE my_proc IS
-- (2) Remove variable references/placeholders used by procedure
-- for data output display reasons.
-- var_empno emp.empno%type;
-- var_ename emp.ename%type;
-- var_bonus emp.bonus%type;
-- var_budget number;
-- var_budget := 100000;
-- (3) A suggested practice to put a tolerance level within a
-- constant variable.
--
-- Removing literals from the SQL code segments improves
-- performance, because it allows the PL/SQL interpreter to
-- reuse the execution plans for multiple consecutive runs of
-- the cursor query.
c_var_budget_limit constant number:= 100000;
l_var_budget number;
CURSOR EMP_CURSOR IS
select empno, ename, bonus from emp order by empno;
BEGIN
-- (4) This task is reserved for APEX to handle in a REPORT REGION
-- definition.
-- htp.print('EMPLOYEE NUMBER EMPLOYEE NAME BONUS');
-- (5) I rewrote the cursor using the IMPLICIT cursor method.
l_var_budget:= c_var_budget_limit;
for result_data in EMP_CURSOR
LOOP
IF (l_var_budget >= bonus_increase) then
l_var_budget := l_var_budget - bonus_increase;
result_data.bonus:= result_data.bonus + bonus_increase;
END IF;
END LOOP;
-- (6) The web toolkit output is no longer necessary.
//----DBMS_OUTPUT.put_line(var_empno || ' ' || var_ename || ' '
-- || var_bonus);
-- htp.print(var_empno || ' ' || var_ename || ' ' || var_bonus);
END;
The commented sections show how much of the burden for display and output and formatting conventions have been removed. I found a good reference on how to use REF CURSORS as encapsulated queries of business logic in an article: Using Ref Cursors Reference posted in a reference on "oracle-base.com".
The cleaned up procedure, modeled after this reference looks like:
CREATE OR REPLACE PROCEDURE my_proc_data (result_data OUT sys_refcursor)
IS
BEGIN
OPEN result_data FOR
SELECT empno, ename, 0 as bonus
FROM emp
ORDER BY empno ASC;
END;
The calling procedure that opens and loops through the cursor contents looks similar to the OP procedure, in the form of an anonymous PL/SQL block:
DECLARE
l_cursor SYS_REFCURSOR;
l_empno emp.empno%TYPE;
l_ename emp.ename%TYPE;
l_bonus number;
c_var_budget_limit constant number:= 100000;
c_bonus_increase constant number:= 1000;
l_var_budget number;
BEGIN
my_proc_data (result_data => l_cursor);
l_var_budget := c_var_budget_limit;
LOOP
FETCH l_cursor
INTO l_empno, l_ename, l_bonus;
IF (l_var_budget >= c_bonus_increase) then
l_var_budget := l_var_budget - c_bonus_increase;
l_bonus:= l_bonus + c_bonus_increase;
DBMS_OUTPUT.PUT_LINE(to_char(l_empno) || ' | ' || l_ename ||
' | ' || to_char(l_bonus));
END IF;
EXIT WHEN l_cursor%NOTFOUND;
END LOOP;
CLOSE l_cursor;
END;
The result output:
7369 | SMITH | 1000
7499 | ALLEN | 1000
7521 | WARD | 1000
7566 | JONES | 1000
7654 | MARTIN | 1000
7698 | BLAKE | 1000
7782 | CLARK | 1000
7788 | SCOTT | 1000
7839 | KING | 1000
7844 | TURNER | 1000
7876 | ADAMS | 1000
7900 | JAMES | 1000
7902 | FORD | 1000
7934 | MILLER | 1000
7934 | MILLER | 2000
Statement processed.
This isn't the ending solution, remember, the data needs to be fed to APEX in the form of a SELECT statement.
Using Oracle PL/SQL Collections to Deliver REF CURSOR Data Through Apex Report Regions
Some additional changes to further prepare the original sample procedure for use with an Apex page region report:
Added two new SQL object types: EMPLOYEE_RECORD_TYPE and EMP_OUTPUT_TABLE_TYPE.
Changed to PL/SQL FUNCTION object type instead of PROCEDURE object type.
Changed output data type to NESTED TABLE collection type. (This allows us to QUERY the output data stored in this collection using direct SQL).
The separated code for the REF CURSOR and the report-output query were combined.
Converted the Anonymous PL/SQL block used in testing the first part into a FUNCTION object.
Changed (reduced) the MAX BUDGET value from OP so that we can see the looping logic at work (i.e., running out of budget money to award bonuses to employees)
Here's the revised code:
SQL Collection and Object Type Definitions (DDL)
CREATE OR REPLACE TYPE employee_record_type AS object (
empno number,
ename varchar2(10),
bonus number
);
CREATE OR REPLACE TYPE emp_output_table_type IS TABLE OF
employee_record_type;
New PL/SQL Function Definition (Containing REF CURSOR)
create or replace FUNCTION my_bonuses RETURN
emp_output_table_type IS
-- table collection type declared and initialized here:
l_output emp_output_table_type:= emp_output_table_type();
l_row_index pls_integer:= 0;
c_var_budget_limit constant number:= 100000;
c_bonus_increase constant number:= 1000;
l_var_budget number;
cursor l_cursor is
select empno, ename, 0 as bonus
from emp
order by empno ASC;
BEGIN
l_var_budget := c_var_budget_limit;
FOR i in l_cursor
LOOP
l_row_index := l_row_index + 1;
l_output.extend;
l_output(l_row_index):= employee_record_type(i.empno,
i.ename, i.bonus);
IF (l_var_budget >= c_bonus_increase) then
l_var_budget := l_var_budget - c_bonus_increase;
l_output(l_row_index).bonus:= l_output(l_row_index).bonus
+ c_bonus_increase;
END IF;
END LOOP;
RETURN l_output;
END;
Function MY_BONUSES When Queried from SQL Client
This is the SQL that will be referenced in the Apex page report definition as in the "Region Source" section of the Region Definition configuration page.
Comparison: Source Table Data vs. REF CURSOR query results
Some Closing Comments and Discussion
This example leaves room for lots of optimizations given the leaps in the product versions of the RDBMS between Oracle 9i, up to and including 11g and 12c. Some side-thoughts for consideration:
Use of bulk-binding operations and methods when loading data from ref-cursors to Oracle collection types.
Additional modularization. You can see the components of the OP procedure my_proc moved around a little during the development of this solution. Your conversion effort may benefit from better organization using packages and separation of processes (where it makes sense).
Read up on the documentation on Oracle PL/SQL collections. You will learn a few important distinctions:
a. Some collection types can be queried directly with SQL.
b. Composite data types defined in PL/SQL vs at the schema level each have their own limitations...
In general, choose wisely, or just stick with this example as it should get you most of the way towards converting an existing library of PL/SQL code with REF CURSOR driven parameters/outputs.
Onward!