If you have defined multiple database connections and want to specify a particular connection context instance for an executable statement, then use the following syntax:

#sql [conn_context_instance] { SQL operation };

If you have defined one or more execution context instances of the sqlj.runtime.ExecutionContext class and want to specify one of them for use with an executable statement, then use the following syntax:

#sql [exec_context_instance] { SQL operation };

You can use an execution context instance to provide status or control of the SQL operation of a SQLJ executable statement. For example, you can use execution context instances in multithreading situations where multiple operations are occurring on the same connection.

You can also specify both a connection context instance and an execution context instance:

#sql [conn_context_instance, exec_context_instance] { SQL operation };

Elementary INSERT

The following example demonstrates a basic INSERT. The statement clause does not require any syntax specific to SQLJ.

Consider an employee table EMP with the following rows:

CREATE TABLE EMP (
   ENAME VARCHAR2(10),
   SAL NUMBER(7,2) );

Use the following SQLJ executable statement, which uses only standard SQL syntax, to insert Joe as a new employee into the EMP table, specifying his name and salary:

#sql { INSERT INTO emp (ename, sal) VALUES ('Joe', 43000) };

Elementary INSERT with Connection Context or Execution Context Instances

The following examples use ctx as a connection context instance, which is an instance of either the default sqlj.runtime.ref.DefaultContext or a class that you have previously declared in a connection context declaration, and execctx as an execution context instance:

#sql [ctx] { INSERT INTO emp (ename, sal) VALUES ('Joe', 43000) };

#sql [execctx] { INSERT INTO emp (ename, sal) VALUES ('Joe', 43000) };

#sql [ctx, execctx] { INSERT INTO emp (ename, sal) VALUES ('Joe', 43000) };

A Simple SQLJ Method

This example demonstrates a simple method using SQLJ code, demonstrating how SQLJ statements interrelate with and are interspersed with Java statements. The SQLJ statement uses standard INSERT INTO table VALUES syntax supported by the Oracle SQL implementation. The statement also uses Java host expressions, marked by colons (:), to define the values. Host expressions are used to pass data between the Java code and SQL instructions.

public static void writeSalesData (int[] itemNums, String[] itemNames)
       throws SQLException
{
  for (int i =0; i < itemNums.length; i++)
    #sql { INSERT INTO sales VALUES(:(itemNums[i]), :(itemNames[i]), SYSDATE) };
}

Syntax Notes

Keep the following in mind regarding the host expression syntax:

• White space is always allowed after the colon as well as after the mode specifier. Wherever white space is allowed, you can also have a comment.

  You can have any of the following in the SQL namespace:

  • SQL comments after the colon and before the mode specifier

  • SQL comments after the colon and before the host expression if there is no mode specifier

  • SQL comments after the mode specifier and before the host expression

  You can have the following in the Java namespace:

  • Java comments within the host expression (inside the parentheses)

• The IN, OUT, and INOUT syntax used for host variables and expressions are not case-sensitive. These tokens can be in uppercase, lowercase, or mixed.

• Do not confuse the IN, OUT, and INOUT syntax of SQLJ host expressions with similar IN, OUT, and IN OUT syntax used in PL/SQL declarations to specify the mode of parameters passed to PL/SQL stored functions and procedures.

Usage Notes

Keep the following in mind regarding the usage of host expressions:

• A simple host variable can appear multiple times in the same SQLJ statement, as follows:

  • If the host variable appears only as an input variable, then there are no restrictions or complications.

  • If at least one appearance of the host variable is as an output variable in a PL/SQL block, then you will receive a portability warning if the translator -warn=portability flag is set. SQLJ run-time behavior in this situation is vendor-specific. Oracle SQLJ run time uses value semantics, as opposed to reference semantics, for all occurrences of the host variable.

  • If at least one appearance of the host variable is as an output variable in a stored procedure call, stored function call, SET statement, or INTO-list, then you will not receive any warning. SQLJ run-time behavior in this situation is standardized, using value semantics.

  Note:

  The term output refers to OUT or INOUT variables, as applicable.

• If a host expression that is a simple host variable appears multiple times in a SQLJ statement, then by default each appearance is treated completely independently of the other appearances, using value semantics. However, if you use the SQLJ translator -bind-by-identifier=true setting, then this is not the case. With a true setting, multiple appearances of the same host variable in a given SQLJ statement or PL/SQL block are treated as a single bind occurrence.

• When binding a string host expression into a WHERE clause for comparison against CHAR data, be aware that there is a SQLJ option, -fixedchar, that accounts for blank padding in the CHAR column when the comparison is made.

The following examples will help clarify the preceding syntax discussion.

Example 1

In this example, two input host variables are used, one as a test value for a WHERE clause and one to contain new data to be sent to the database.

Presume you have a database employee table emp with an ename column for employee names and a sal column for employee salaries. The relevant Java code that defines the host variables is as follows:

String empname = "SMITH";
double salary = 25000.0;
...
#sql { UPDATE emp SET sal = :salary WHERE ename = :empname };

IN is the default, but you can state it explicitly as well:

#sql { UPDATE emp SET sal = :IN salary WHERE ename = :IN empname };

As you can see, the colon (:) can immediately precede the variable when not using the IN token, but :IN must be followed by white space before the host variable.

Example 2

This example uses an output host variable in a SELECT INTO statement, where you want to find out the name of the employee whose employee number 28959.

String empname;
...
#sql { SELECT ename INTO :empname FROM emp WHERE empno = 28959 };

OUT is the default for an INTO-list, but you can state it explicitly as well:

#sql { SELECT ename INTO :OUT empname FROM emp WHERE empno = 28959 };

This statement looks in the empno column of the emp table for employee number 28959, selects the name in the ename column of that row, and outputs it to the empname output host variable, which is a Java String.

Example 3

This example uses an arithmetic expression as an input host expression. The Java variables balance and minPmtRatio are multiplied, and the result is used to update the minPayment column of the creditacct table for account number 537845.

float balance = 12500.0;
float minPmtRatio = 0.05;
...
#sql { UPDATE creditacct SET minPayment = :(balance * minPmtRatio) 
       WHERE acctnum = 537845 };

Alternatively, to use the IN token:

#sql { UPDATE creditacct SET minPayment = :IN (balance * minPmtRatio) 
       WHERE acctnum = 537845 };

Example 4

This example shows the use of the output of a method call as an input host expression and also uses an input host variable. This statement uses the value returned by getNewSal() to update the sal column in the emp table for the employee who is specified by the Java empname variable. Java code initializing the host variables is also shown.

String empname = "SMITH";
double raise = 0.1;
...
#sql {UPDATE emp SET sal = :(getNewSal(raise, empname)) 
      WHERE ename = :empname};

This section discusses, for ISO code generation, how Java expressions are evaluated when your application executes.

Evaluation of Prefix and Postfix Operators

When a Java expression contains a Java postfix increment or decrement operator, the incrementing or decrementing occurs after the expression has been evaluated. Similarly, when a Java expression contains a Java prefix increment or decrement operator, the incrementing or decrementing occurs before the expression is evaluated. This is equivalent to how these operators are handled in standard Java code.

The following is an example of postfix operator:

int indx = 1;
...
#sql { ... :OUT (array[indx]) ... :IN (indx++) ... };

This example is evaluated as follows:

#sql { ... :OUT (array[1]) ... :IN (1) ... };

The indx variable is incremented to 2 and will have that value the next time it is encountered, but not until after :IN (indx++) has been evaluated.

The following is the example of postfix operator:

int indx = 1;
...
#sql { ... :OUT (array[indx++]) ... :IN (indx++) ... };

This example is evaluated as follows:

#sql { ... :OUT (array[1]) ... :IN (2) ... };

The variable indx is incremented to 2 after the first expression is evaluated, but before the second expression is evaluated. It is incremented to 3 after the second expression is evaluated and will have that value the next time it is encountered.

The following example consists of both prefix and postfix operators:

int indx = 1;
...
#sql { ... :OUT (array[++indx]) ... :IN (indx++) ... };

This example is evaluated as follows:

#sql { ... :OUT (array[2]) ... :IN (2) ... };

The variable indx is incremented to 2 before the first expression is evaluated. It is incremented to 3 after the second expression is evaluated and will have that value the next time it is encountered.

Evaluation Order of IN, INOUT, and OUT Host Expressions

Host expressions are evaluated from left to right. Whether an expression is IN, INOUT, or OUT makes no difference when it is evaluated. All that matters is its position in the left-to-right order.

Consider the following example:

int[5] arry;
int n = 0;
...
#sql { SET :OUT (arry[n]) = :(++n) };

This example is evaluated as follows:

#sql { SET :OUT (arry[0]) = 1 };

One might expect input expressions to be evaluated before output expressions, but that is not the case. The expression :OUT (arry[n]) is evaluated first because it is the left-most expression. Then n is incremented prior to evaluation of ++n, because it is being operated on by a prefix operator. Then ++n is evaluated as 1. The result will be assigned to arry[0], not arry[1], because 0 was the value of n when it was originally encountered.

Expressions in PL/SQL Blocks Are Evaluated Before Statements Are Executed

Host expressions in a PL/SQL block are all evaluated in one sequence, before any have been executed. Consider the following example:

int x=3;
int z=5;
...
#sql { BEGIN :OUT x := 10; :OUT z := :x; END };
System.out.println("x=" + x + ", z=" + z);

This example is evaluated as follows:

#sql { BEGIN :OUT x := 10; :OUT z := 3; END };

Therefore, it would print x=10, z=3.

All expressions in a PL/SQL block are evaluated before any are executed. In this example, the host expressions in the second statement, :OUT z and :x, are evaluated before the first statement is executed. In particular, the second statement is evaluated while x still has its original value of 3, before it has been assigned the value 10.

Consider another example of how expressions are evaluated within a PL/SQL block:

int x=1, y=4, z=3;
...
#sql { BEGIN
         :OUT x := :(y++) + 1;
         :OUT z := :x;
       END };

This example is evaluated as follows:

#sql { BEGIN
          :OUT x := 4 + 1;
          :OUT z := 1;
       END };

The postfix increment operator is executed after :(y++) is evaluated, so the expression is evaluated as 4, which is the initial value of y. The second statement, :OUT z := :x, is evaluated before the first statement is executed. Therefore, x still has its initialized value of 1. After execution of this block, x will have the value 5 and z will have the value 1.

The following example demonstrates the difference between two statements appearing in a PL/SQL block in one SQLJ executable statement, and the same statements appearing in separate (consecutive) SQLJ executable statements.

First, consider the following, where two statements are in a PL/SQL block.

int y=1;
...
#sql { BEGIN :OUT y := :y + 1; :OUT x := :y + 1; END };

This example is evaluated as follows:

#sql { BEGIN :OUT y := 1 + 1; :OUT x := 1 + 1; END };

The :y in the second statement is evaluated before either statement is executed. Therefore, y has not yet received its output from the first statement. After execution of this block, both x and y have the value 2.

Now, consider the situation where the same two statements are in PL/SQL blocks in separate SQLJ executable statements.

int y=1;
#sql { BEGIN :OUT y := :y + 1; END };
#sql { BEGIN :OUT x := :y + 1; END };

The first statement is evaluated as follows:

#sql { BEGIN :OUT y := 1 + 1; END };

Then, it is executed and y is assigned the value 2.

After execution of the first statement, the second statement is evaluated as follows:

#sql { BEGIN :OUT x := 2 + 1; END };

This time, as opposed to the previous PL/SQL block example, y has already received the value 2 from execution of the previous statement. Therefore, x is assigned the value 3 after execution of the second statement.

Expressions in PL/SQL Blocks Are Always Evaluated Once Only

Each host expression is evaluated once, and only once, regardless of program flow and logic.

Consider the following example of evaluation of host expression in a loop:

int count = 0;
...
#sql {
   DECLARE
      n NUMBER
   BEGIN
      n := 1;
      WHILE n <= 100 LOOP
         :IN (count++);
         n := n + 1;
      END LOOP;
   END
};

The Java count variable will have the value 0 when it is passed to SQL, because it is operated on by a postfix operator, as opposed to a prefix operator. It will then be incremented to 1 and will hold that value throughout execution of this PL/SQL block. It is evaluated only once as the SQLJ executable statement is parsed and then is replaced by the value 1 prior to SQL execution.

Consider the following example that illustrates the evaluation of host expressions in conditional blocks. This example demonstrates how each expression is always evaluated, regardless of the program flow. As the block is executed, only one branch of the IF...THEN...ELSE construct can be executed. However, before the block is executed, all expressions in the block are evaluated in the order that the statements appear.

int x;
...
(operations on x)
...
#sql {
   DECLARE
      n NUMBER
   BEGIN
      n := :x;
      IF n < 10 THEN
         n := :(x++);
      ELSE
         n := :x * :x;
      END LOOP;
   END
};

Say the operations performed on x resulted in x having a value of 15. When the PL/SQL block is executed, the ELSE branch will be executed and the IF branch will not. However, all expressions in the PL/SQL block are evaluated before execution, regardless of program logic or flow. Therefore, x++ is evaluated, then x is incremented, and then each x is evaluated in the (x * x) expression. The IF...THEN...ELSE block is evaluated as follows:

IF n < 10 THEN
   n := 15;
ELSE
   n := :16 * :16;
END LOOP;

After execution of this block, given an initial value of 15 for x, n will have the value 256.

Output Host Expressions Are Assigned Left to Right, Before Result Expression

Remember that OUT and INOUT host expressions are assigned in order from left to right, and then the result expression, if any, is assigned last. If the same variable is assigned more than once, then it will be overwritten according to this order, with the last assignment taking precedence.

The following example contains multiple output host expressions referencing the same variable:

#sql { CALL foo(:OUT x, :OUT x) };

If foo() outputs the values 2 and 3, respectively, then x will have the value 3 after the SQLJ executable statement has finished executing. The right-hand assignment will be performed last, thereby taking precedence.

The following example contains multiple output host expressions referencing the same object:

MyClass x = new MyClass();
MyClass y = x;
...
#sql { ... :OUT (x.field):=1 ... :OUT (y.field):=2 ... };

After execution of the SQLJ executable statement, x.field will have a value of 2, and not 1, because x is the same object as y, and field was assigned the value of 2 after it was assigned the value of 1.

The following example demonstrates the difference between having the output results of a function assigned to a result expression and having the results assigned to an OUT host expression. Consider the following function, with the invar input parameter, the outvar output parameter, and a return value:

CREATE FUNCTION fn(invar NUMBER, outvar OUT NUMBER)
   RETURN NUMBER AS BEGIN
      outvar := invar + invar;
      return (invar * invar);
   END fn;

Now consider an example where the output of the function is assigned to a result expression:

int x = 3;
#sql x = { VALUES(fn(:x, :OUT x)) };

The function will take 3 as the input, will calculate 6 as the output, and will return 9. After execution, the :OUT x will be assigned first, giving x a value of 6. But finally the result expression is assigned, giving x the return value of 9 and overwriting the value of 6 previously assigned to x. So x will have the value 9 the next time it is encountered.

Now consider an example where the output of the function is assigned to an OUT host variable instead of a result expression:

int x = 3;
#sql { BEGIN :OUT x := fn(:x, :OUT x); END };

In this case, there is no result expression and the OUT variables are simply assigned left to right. After execution, the first :OUT x, on the left side of the equation, is assigned first, giving x the function return value of 9. However, proceeding left to right, the second :OUT x, on the right side of the equation, is assigned last, giving x the output value of 6 and overwriting the value of 9 previously assigned to x. Therefore, x will have the value 6 the next time it is encountered.

The examples in this section use an employee table EMP with the following rows:

CREATE TABLE EMP (
   EMPNO NUMBER(4),
   ENAME VARCHAR2(10),
   HIREDATE DATE );

The following is an example of a SELECT INTO statement with a single host expression in the INTO-list:

String empname;
#sql { SELECT ename INTO :enpname FROM emp WHERE empno=28959 };

The following is an example of a SELECT INTO statement with multiple host expressions in the INTO-list:

String empname;
Date hdate;
#sql { SELECT ename, hiredate INTO :empname, :hdate FROM emp 
       WHERE empno=28959 };

Comparative Iterator Notes

Be aware of the following notes regarding SQLJ iterators:

• In populating a positional iterator, the number of columns you select from the database must equal the number of columns in the iterator. In populating a named iterator, the number of columns you select from the database can never be less than the number of columns in the iterator, but can be greater than the number of columns in the iterator if you have the translator -warn=nostrict flag set. Unmatched columns are ignored in this case.

• Although the term "fetching" often refers to fetching data from a database, remember that a FETCH INTO statement for a positional iterator does not necessarily involve a round trip to the server. This depends on the row-prefetch value. This is because you are fetching data from the iterator, and not the database. However, if the row-prefetch value is 1, then each fetch does involve a separate trip to the database. The row-prefetch value determines how many rows are retrieved with each trip to the database.

• Result set iterators use the same FETCH INTO syntax that is used with positional iterators and are subject to the same restriction at run time. That is, the number of data items in the SELECT-list must match the number of variables that are assigned data in the FETCH statement.

When you declare a named iterator class, you declare the name as well as the data type of each column of the iterator. When you select data into a named iterator, the columns in the SELECT statement must match the iterator columns in two ways:

• The name of each data item in the SELECT statement, either a table column name or an alias, must match an iterator column name. However, this is not case-sensitive. That is, ename or Ename would match ENAME).

• The data type of each iterator column must be compatible with the data type of the corresponding data item in the SELECT statement according to standard JDBC type mappings.

The order in which attributes are declared in the named iterator class declaration is irrelevant. Data is selected into the iterator based on name alone.

A named iterator has a next() method to retrieve data row by row and an accessor method for each column to retrieve the individual data items. The accessor method names are identical to the column names. Unlike most accessor method names in Java, accessor method names in named iterator classes do not start with get. For example, a named iterator object with a column sal would have a sal() accessor method.

Declaring Named Iterator Classes

Use the following syntax to declare a named iterator class:

#sql <modifiers> iterator classname <implements clause> <with clause> 
     ( type-name-list );

In this syntax, modifiers is an optional sequence of legal Java class modifiers, classname is the desired class name for the iterator, and type-name-list is a list of the Java types and names equivalent to or compatible with the column types and column names in a database table.

The implements clause and with clause are optional, specifying interfaces to implement and variables to define and initialize, respectively.

Consider the following table:

CREATE TABLE PROJECTS (
   ID NUMBER(4),
   PROJNAME VARCHAR(30),
   START_DATE DATE,
   DURATION NUMBER(3) );

You can declare the following named iterator to use with this table:

#sql public iterator ProjIter (String projname, int id, Date deadline);

This will result in an iterator class with columns of data accessible, using the following provided accessor methods: projname(), id(), and deadline().

Instantiating and Populating Named Iterators

Continuing to use the PROJECTS table and ProjIter iterator defined in the preceding section, note that there are columns in the table whose names and data types match the id and projname columns of the iterator. However, you must use an alias and perform an operation to populate the deadline column of the iterator. Following is an example:

ProjIter projsIter;

#sql projsIter = { SELECT start_date + duration AS deadline, projname, id 
                   FROM projects WHERE start_date + duration >= sysdate };

This calculates a deadline for each project by adding its duration to its start date, then aliases the results as deadline to match the deadline iterator column. It also uses a WHERE clause so that only future deadlines are processed, that is, deadlines beyond the current system date in the database.

Similarly, you must create an alias if you want to use a function call. Suppose you have a MAXIMUM() function that takes a DURATION entry and an integer as input and returns the maximum of the two. For example, you could input the value 3 to ensure that each project has at least a three-month duration in your application.

Now, presume you are declaring your iterator as follows:

#sql public iterator ProjIter2 (String projname, int id, float duration);

You could use the MAXIMUM() function in your query, with an alias for the result, as follows:

ProjIter2 projsIter2;

#sql projsIter2 = { SELECT id, projname, maximum(duration, 3) AS duration 
                    FROM projects };

Generally, you must use an alias in your query for any data item in the SELECT statement whose name is not a legal Java identifier or does not match a column name in the iterator.

Remember that in populating a named iterator, the number of columns you select from the database can never be less than the number of columns in the iterator. The number of columns you select can be greater than the number of columns in the iterator, because unmatched columns are ignored. However, this will generate a warning, unless you have the SQLJ -warn=nostrict option set.

Accessing Named Iterators

Use the next() method of the named iterator object to step through the data that was selected into it. To access each column of each row, use the accessor methods generated by SQLJ, typically inside a while loop.

Whenever next() is called:

• If there is another row to retrieve from the iterator, then next() retrieves the row and returns true.

• If there are no more rows to retrieve, next() returns false.

The following is an example of how to access the data of a named iterator, repeating the declaration, instantiation, and population code illustrated in the preceding section.

Presume the following iterator class declaration:

#sql public iterator ProjIter (String projname, int id, Date deadline);

Populate and then access an instance of this iterator class as follows:

// Declare the iterator variable
ProjIter projsIter;

// Instantiate and populate iterator; order of SELECT doesn't matter
#sql projsIter = { SELECT start_date + duration AS deadline, projname, id 
                   FROM projects WHERE start_date + duration >= sysdate };

// Process the results
while (projsIter.next()) {
   System.out.println("Project name is " + projsIter.projname());
   System.out.println("Project ID is " + projsIter.id());
   System.out.println("Project deadline is " + projsIter.deadline());
}  

// Close the iterator
projsIter.close();
...

Note the convenient use of the projname(), id(), and deadline() accessor methods to retrieve the data. Note also that the order of the SELECT items does not matter, nor does the order in which the accessor methods are used.

However, remember that accessor method names are created with the case exactly as in your declaration of the iterator class. The following will generate compilation errors.

Consider the following declaration of the iterator:

#sql iterator Cursor1 (String NAME);

The code for using the iterator is as follows:

...
Cursor1 c1;
#sql c1 = { SELECT NAME FROM TABLE };
while (c1.next()) {
   System.out.println("The name is " + c1.name());
}
...

The Cursor1 class has a method called NAME(), and not name(). You will have to use c1.NAME() in the System.out.println statement.

When you declare a positional iterator class, you declare the data type of each column but not the column name. The Java types into which the columns of the SQL query results are selected must be compatible with the data types of the SQL data. The names of the database columns or data items in the SELECT statement are irrelevant. Because names are not used, the order in which you declare your positional iterator Java types must exactly match the order in which the data is selected.

To retrieve data from a positional iterator once data has been selected into it, use a FETCH INTO statement followed by an endFetch() method call to determine if you have reached the end of the data.

Declaring Positional Iterator Classes

Use the following syntax to declare a positional iterator class:

#sql <modifiers> iterator classname <implements clause> <with clause> 
     ( position-list );

In this syntax, modifiers is an optional sequence of legal Java class modifiers and the position-list is a list of Java types compatible with the column types in a database table.

The implements clause and with clause are optional, specifying interfaces to implement and variables to define and initialize, respectively.

Now consider an employee table EMP with the following rows:

CREATE TABLE EMP (
   EMPNO NUMBER(4),
   ENAME VARCHAR2(10), 
   SAL NUMBER(7,2) );

And consider the following positional iterator declaration:

#sql public iterator EmpIter (String, int, float);

This example defines the EmpIter Java class with unnamed String, int, and float columns. Note that the table columns and iterator columns are in a different order, with the String corresponding to ENAME and the int corresponding to EMPNO. The order of the iterator columns determines the order in which you must select the data.

Instantiating and Populating Positional Iterators

Instantiating and populating a positional iterator is no different than doing so for a named iterator, except that you must be certain that the data items in the SELECT statement are in the proper order.

The three data types in the EmpIter iterator class are compatible with the types of the EMP table, but be careful how you select the data, because the order is different. The following will work, because the data items in the SELECT statement are in the same order as the iterator columns:

EmpIter empsIter;

#sql empsIter = { SELECT ename, empno, sal FROM emp };

Remember that in populating a positional iterator, the number of columns you select from the database must equal the number of columns in the iterator.

Accessing Positional Iterators

Access the columns defined by a positional iterator using SQL FETCH INTO syntax. The INTO part of the command specifies Java host variables that receive the results columns. The host variables must be in the same order as the corresponding iterator columns. Use the endFetch() method provided with all positional iterator classes to determine whether the last fetch reached the end of the data.

The following is an example, repeating the declaration, instantiation, and population code illustrated in the preceding section. Note that the Java host variables in the SELECT statement are in the same order as the columns of the positional iterator, which is mandatory.

First, presume the following iterator class declaration:

#sql public iterator EmpIter (String, int, float);

Populate and then access an instance of this iterator class as follows:

// Declare and initialize host variables
int empnum=0;
String empname=null;
float salary=0.0f;

// Declare an iterator instance
EmpIter empsIter;

#sql empsIter = { SELECT first_name, employee_id, salary FROM employees };

while (true) {
   #sql { FETCH :empsIter INTO :empnum, :empname, :salary };
   if (empsIter.endFetch()) break;  // This test must be AFTER fetch,
                                    // but before results are processed.
   System.out.println("Name is " + empname);
   System.out.println("Employee number is " + empnum);
   System.out.println("Salary is " + salary);
}

// Close the iterator
empsIter.close();
...

The empname, empnum, and salary variables are Java host variables whose types must match the types of the iterator columns.

Do not use the next() method for a positional iterator. A FETCH operation calls it implicitly to move to the next row.

Positional Iterator Navigation with the next() Method

The positional iterator FETCH clause discussed in the preceding section performs a movement, an implicit next() call, before it populates the host variables, if any. As an alternative, the Oracle SQLJ implementation supports a special FETCH syntax in conjunction with explicit next() calls in order to use the same movement logic as with JDBC result sets and SQLJ named iterators. Using this special FETCH syntax, the semantics differ. There is no implicit next() call before the INTO-list is populated.

SQLJ supports SQLJ iterators and JDBC result sets as host variables. Using iterators and result sets is fundamentally the same, with differences in declarations and in accessor methods to retrieve the data.

For the examples in this section, consider the following department and employee tables:

CREATE TABLE DEPT (
   DEPTNO NUMBER(2),
   DNAME VARCHAR2(14) );

CREATE TABLE EMP (
   EMPNO NUMBER(4),
   ENAME VARCHAR2(10), 
   SAL NUMBER(7,2), 
   DEPTNO NUMBER(2) );

Example: Use of Result Set as OUT Host Variable

This example uses a JDBC result set as an output host variable.

...
ResultSet rs;
...
#sql { BEGIN
          OPEN :OUT rs FOR SELECT ename, empno FROM emp;
       END };

while (rs.next())
{
   String empname = rs.getString(1);
   int empnum = rs.getInt(2);
}
rs.close();
...

This example opens the result set rs in a PL/SQL block to receive data from a SELECT statement, selects data from the ENAME and EMPNO columns of the EMP table, and then loops through the result set to retrieve data into local variables.

Example: Use of Iterator as OUT Host Variable

This example uses a named iterator as an output host variable.

The iterator can be declared as follows:

#sql public <static> iterator EmpIter (String ename, int empno);

The public modifier is required, and the static modifier may be advisable if your declaration is at class level or nested-class level.

This iterator can be used as follows:

...
EmpIter iter;
...
#sql { BEGIN
          OPEN :OUT iter FOR SELECT ename, empno FROM emp;
       END };

while (iter.next())
{
   String empname = iter.ename();
   int empnum = iter.empno();
   
   ...process/output empname and empnum...
}
iter.close();
...

This example opens the iterator iter in a PL/SQL block to receive data from a SELECT statement, selects data from the ENAME and EMPNO columns of the EMP table, and then loops through the iterator to retrieve data into local variables.

Example: Use of Iterator as OUT Host Variable for SELECT INTO

This example uses a named iterator as an output host variable, taking data through a SELECT INTO statement. OUT is the default for host variables in an INTO-list.

The iterator can be declared as follows:

#sql public <static> iterator ENameIter (String ename);

The public modifier is required, and the static modifier may be advisable if your declaration is at class level or nested-class level.

This iterator can be used as follows:

...
ENameIter enamesIter;
String deptname;
...

#sql { SELECT dname, cursor 
      (SELECT ename FROM emp WHERE deptno = dept.deptno)
       INTO :deptname, :enamesIter FROM dept WHERE deptno = 20 };

System.out.println(deptname);
while (enamesIter.next())
{
   System.out.println(enamesIter.ename());
}
enamesIter.close();
... 

This example uses nested SELECT statements to accomplish the following:

• Select the name of department number 20 from the DEPT table, selecting it into the deptname output host variable.

• Query the EMP table to select all employees whose department number is 20, selecting the resulting cursor into the enamesIter output host variable, which is a named iterator.

• Print the department name.

• Loop through the named iterator printing employee names. This prints the names of all employees in the department.

In most cases, using SELECT INTO is more convenient than using nested iterators if you are retrieving a single row in the outer SELECT, although that option is also available. Also, with nested iterators, you would have to process the data to determine how many rows there are in the outer SELECT. With SELECT INTO you are assured of just one row.

The Oracle SQLJ implementation includes extensions that allow iterator declarations to specify columns of ResultSet type or columns of other iterator types declared within the current scope. In other words, iterators and result sets can exist within iterators. These column types are used to retrieve a column in the form of a cursor. This is useful for nested SELECT statements that return nested table information.

The following examples are functionally identical. Each uses a nested result set or iterator, that is, result sets or iterators in a column within an iterator, to print all the employees in each department in the DEPT table. The first example uses result sets within a named iterator, the second example uses named iterators within a named iterator, and the third example uses named iterators within a positional iterator.

Following are the steps:

Stored procedures do not have a return value but can take a list with input, output, and input-output parameters. Stored procedure calls use the CALL token. The CALL token is followed by white space and then the procedure name. There must be a space after the CALL token to differentiate it from the procedure name. There cannot be a set of outer parentheses around the procedure call. This differs from the syntax for function calls. The syntax for the CALL token is as follows:

#sql { CALL PROC(<PARAM_LIST>) };

PROC is the name of the stored procedure, which can optionally take a list of input, output, and input-output parameters. PROC can include a schema or package name as well, such as HR.MYPROC().

Presume that you have defined the following PL/SQL stored procedure:

CREATE OR REPLACE PROCEDURE MAX_DEADLINE (deadline OUT DATE) IS
   BEGIN
      SELECT MAX(start_date + duration) INTO deadline FROM projects;
   END;

This reads the PROJECTS table, looks at the START_DATE and DURATION columns, calculates start_date + duration in each row, then takes the maximum START_DATE + DURATION total, and assigns it to DEADLINE, which is an output parameter of type DATE.

In SQLJ, you can call this MAX_DEADLINE procedure as follows:

java.sql.Date maxDeadline;
...
#sql { CALL MAX_DEADLINE(:out maxDeadline) };

For any parameters, you must use the host expression tokens IN, OUT, and INOUT appropriately, to match the input, output, and input-output designations of the stored procedure. Additionally, the types of the host variables you use in the parameter list must be compatible with the parameter types of the stored procedure.

#sql { CALL MAX_DEADLINE };

#sql { CALL MAX_DEADLINE() };

Stored functions have a return value and can also take a list of input, output, and input-output parameters. Stored function calls use the VALUES token. The VALUES token is followed by the function call. In standard SQLJ, the function call must be enclosed in a set of outer parentheses. In the Oracle SQLJ implementation, the outer parentheses are optional. When using the outer parentheses, it does not matter if there is white space between the VALUES token and the begin-parenthesis. The syntax for the VALUES token is as follows:

#sql result = { VALUES(FUNC(PARAM_LIST)) };

In this syntax, result is the result expression, which takes the function return value. FUNC is the name of the stored function, which can optionally take a list of input, output, and input-output parameters. FUNC can include a schema or package name, such as HR.MYFUNC().

Referring back to the example in "Calling Stored Procedures", consider defining the stored procedure as a stored function instead, as follows:

CREATE OR REPLACE FUNCTION GET_MAX_DEADLINE RETURN DATE IS
   deadline DATE;
   BEGIN
      SELECT MAX(start_date + duration) INTO deadline FROM projects;
      RETURN deadline;
   END;

In SQLJ, you can call this GET_MAX_DEADLINE function as follows:

java.sql.Date maxDeadline;
...
#sql maxDeadline = { VALUES(GET_MAX_DEADLINE) };

The result expression must have a type compatible with the return type of the function.

In the Oracle SQLJ implementation, the following syntax is also allowed:

#sql maxDeadline = { VALUES GET_MAX_DEADLINE };

Note that the outer parentheses is omitted.

For stored function calls, as with stored procedures, you must use the host expression tokens IN, OUT, and INOUT appropriately, to match the input, output, and input-output parameters of the stored function. Additionally, the types of the host variables you use in the parameter list must be compatible with the parameter types of the stored function.

SQLJ supports assigning the return value of a stored function to an iterator or result set variable, if the function returns a REF CURSOR type.

The following example uses an iterator to take a stored function return. Using a result set is similar.

Example: Iterator as Stored Function Return

This example uses an iterator as a return type for a stored function, using a REF CURSOR type in the process.

Presume the following function definition:

CREATE OR REPLACE PACKAGE sqlj_refcursor AS
   TYPE EMP_CURTYPE IS REF CURSOR;
   FUNCTION job_listing (j varchar2) RETURN EMP_CURTYPE;
END sqlj_refcursor;

CREATE OR REPLACE PACKAGE BODY sqlj_refcursor AS 
   FUNCTION job_listing (j varchar) RETURN EMP_CURTYPE IS 
   DECLARE
      rc EMP_CURTYPE;
   BEGIN
      OPEN rc FOR SELECT ename, empno FROM emp WHERE job = j;
      RETURN rc;
   END;
END sqlj_refcursor;

Declare the iterator as follows:

#sql public <static> iterator EmpIter (String ename, int empno);

The public modifier is required, and the static modifier may be advisable if your declaration is at class level or nested-class level.

The code that uses the iterator and the function is as follows:

EmpIter iter;
...
#sql iter = { VALUES(sqlj_refcursor.job_listing('SALES')) };

while (iter.next())
{
   String empname = iter.ename();
   int empnum = iter.empno();

   ... process empname and empnum ...
}
iter.close();
...

This example calls the job_listing() function to return an iterator that contains the name and employee number of each employee whose job title is SALES. It then retrieves this data from the iterator.