PL/SQL can help you reduce overhead, improve performance, and increase productivity. For example, without PL/SQL, Oracle must process SQL statements one at a time. Each SQL statement results in another call to the Server and higher overhead. However, with PL/SQL, you can send an entire block of SQL statements to the Server. This minimizes communication between your application and Oracle.

PL/SQL is tightly integrated with the Oracle Server. For example, most PL/SQL datatypes are native to the Oracle data dictionary. Furthermore, you can use the %TYPE attribute to base variable declarations on column definitions stored in the data dictionary, as the following example shows:

job_title  emp.job%TYPE; 

That way, you need not know the exact datatype of the column. Furthermore, if a column definition changes, the variable declaration changes accordingly and automatically. This provides data independence, reduces maintenance costs, and allows programs to adapt as the database changes.

With PL/SQL, you need not use the DECLARE, OPEN, FETCH, and CLOSE statements to define and manipulate a cursor. Instead, you can use a cursor FOR loop, which implicitly declares its loop index as a record, opens the cursor associated with a given query, repeatedly fetches data from the cursor into the record, then closes the cursor. An example follows:

DECLARE 
... 
BEGIN 
   FOR emprec IN (SELECT empno, sal, comm FROM emp) LOOP 
   IF emprec.comm / emprec.sal > 0.25 THEN ... 
   ... 
END LOOP; 
END; 

Notice that you use dot notation to reference components in the record.

PL/SQL has two types of subprograms called procedures and functions, which aid application development by letting you isolate operations. Generally, you use a procedure to perform an action and a function to compute a value.

Procedures and functions provide extensibility. That is, they let you tailor the PL/SQL language to suit your needs. For example, if you need a procedure that creates a new department, just write your own as follows:

PROCEDURE create_dept 
  (new_dname  IN CHAR(14), 
   new_loc    IN CHAR(13), 
   new_deptno OUT NUMBER(2)) IS 
BEGIN 
   SELECT deptno_seq.NEXTVAL INTO new_deptno FROM dual; 
   INSERT INTO dept VALUES (new_deptno, new_dname, new_loc); 
END create_dept; 

When called, this procedure accepts a new department name and location, selects the next value in a department-number database sequence, inserts the new number, name, and location into the dept table, then returns the new number to the caller.

You use parameter modes to define the behavior of formal parameters. There are three parameter modes: IN (the default), OUT, and IN OUT. An IN parameter lets you pass values to the subprogram being called. An OUT parameter lets you return values to the caller of a subprogram. An IN OUT parameter lets you pass initial values to the subprogram being called and return updated values to the caller.

The datatype of each actual parameter must be convertible to the datatype of its corresponding formal parameter. Table 7-1 shows the legal conversions between datatypes.

PL/SQL lets you bundle logically related types, program objects, and subprograms into a package. With the Procedural Database Extension, packages can be compiled and stored in an Oracle database, where their contents can be shared by many applications.

Packages usually have two parts: a specification and a body. The specification is the interface to your applications; it declares the types, constants, variables, exceptions, cursors, and subprograms available for use. The body defines cursors and subprograms; it implements the specification. In the following example, you "package" two employment procedures:

PACKAGE emp_actions IS  -- package specification 
  PROCEDURE hire_employee (empno NUMBER, ename CHAR, ...); 
 
  PROCEDURE fire_employee (emp_id NUMBER); 
END emp_actions; 
 
PACKAGE BODY emp_actions IS  -- package body 
  PROCEDURE hire_employee (empno NUMBER, ename CHAR, ...) IS 
  BEGIN 
    INSERT INTO emp VALUES (empno, ename, ...); 
  END hire_employee; 
 
  PROCEDURE fire_employee (emp_id NUMBER) IS 
  BEGIN 
    DELETE FROM emp WHERE empno = emp_id; 
  END fire_employee; 
END emp_actions; 

Only the declarations in the package specification are visible and accessible to applications. Implementation details in the package body are hidden and inaccessible.

PL/SQL provides a composite datatype named TABLE. Objects of type TABLE are called PL/SQL tables, which are modeled as (but not the same as) database tables. PL/SQL tables have only one column and use a primary key to give you array-like access to rows. The column can belong to any scalar type (such as CHAR, DATE, or NUMBER), but the primary key must belong to type BINARY_INTEGER, PLS_INTEGER or VARCHAR2.

You can declare PL/SQL table types in the declarative part of any block, procedure, function, or package. In the following example, you declare a TABLE type called NumTabTyp:

... 
DECLARE 
   TYPE NumTabTyp IS TABLE OF NUMBER 
      INDEX BY BINARY_INTEGER; 
... 
BEGIN 
   ... 
END; 
... 

Once you define type NumTabTyp, you can declare PL/SQL tables of that type, as the next example shows:

num_tab  NumTabTyp; 

The identifier num_tab represents an entire PL/SQL table.

You reference rows in a PL/SQL table using array-like syntax to specify the primary key value. For example, you reference the ninth row in the PL/SQL table named num_tab as follows:

num_tab(9) ... 

You can use the %ROWTYPE attribute to declare a record that represents a row in a table or a row fetched by a cursor. However, you cannot specify the datatypes of components in the record or define components of your own. The composite datatype RECORD lifts those restrictions.

Objects of type RECORD are called records. Unlike PL/SQL tables, records have uniquely named components, which can belong to different datatypes. For example, suppose you have different kinds of data about an employee such as name, salary, hire date, and so on. This data is dissimilar in type but logically related. A record that contains such components as the name, salary, and hire date of an employee would let you treat the data as a logical unit.

You can declare record types and objects in the declarative part of any block, procedure, function, or package. In the following example, you declare a RECORD type called DeptRecTyp:

DECLARE 
TYPE DeptRecTyp IS RECORD 
    (deptno  NUMBER(4) NOT NULL, -- default is NULL allowed 
    dname   CHAR(9), 
    loc     CHAR(14)); 

Notice that the component declarations are like variable declarations. Each component has a unique name and specific datatype. You can add the NOT NULL option to any component declaration and so prevent the assigning of NULLs to that component.

Once you define type DeptRecTyp, you can declare records of that type, as the next example shows:

dept_rec  DeptRecTyp; 

The identifier dept_rec represents an entire record.

You use dot notation to reference individual components in a record. For example, you reference the dname component in the dept_rec record as follows:

dept_rec.dname ... 

You can use the VARCHAR datatype to declare variable-length character strings. If the VARCHAR is an input host variable, you must tell Oracle what length to expect. Therefore, set the length component to the actual length of the value stored in the string component.

If the VARCHAR is an output host variable, Oracle automatically sets the length component. However, to use a VARCHAR (as well as CHARZ and STRING) output host variable in your PL/SQL block, you must initialize the length component before entering the block. So, set the length component to the declared (maximum) length of the VARCHAR, as shown here:

int     emp_number; 
varchar emp_name[10]; 
float   salary; 
... 
emp_name.len = 10;   /* initialize length component */ 
 
EXEC SQL EXECUTE 
  BEGIN 
    SELECT ename, sal INTO :emp_name, :salary 
        FROM emp 
        WHERE empno = :emp_number; 
    ... 
  END; 
END-EXEC; 
... 

Do not use C pointer or array syntax in PL/SQL blocks. The PL/SQL compiler does not understand C host-variable expressions and is, therefore, unable to parse them. For example, the following is invalid:

EXEC SQL EXECUTE
    BEGIN
        :x[5].name := 'SCOTT';
        ...
    END;
END-EXEC;

To avoid syntax errors, use a place-holder (a temporary variable), to hold the address of the structure field to populate structures as shown in the following valid example:

name = x[5].name ;
EXEC SQL EXECUTE
    BEGIN
        :name := ...;
        ...
    END;
END-EXEC;

When entering a block, if an indicator variable has a value of -1, PL/SQL automatically assigns a NULL to the host variable. When exiting the block, if a host variable is NULL, PL/SQL automatically assigns a value of -1 to the indicator variable. In the next example, if ind_sal had a value of -1 before the PL/SQL block was entered, the salary_missing exception is raised. An exception is a named error condition.

... 
EXEC SQL EXECUTE 
BEGIN 
    IF :salary :ind_sal IS NULL THEN 
    RAISE salary_missing; 
END IF; 
... 
END; 
END-EXEC; 
...

PL/SQL does not raise an exception when a truncated string value is assigned to a host variable. However, if you use an indicator variable, PL/SQL sets it to the original length of the string. In the following example, the host program will be able to tell, by checking the value of ind_name, if a truncated value was assigned to emp_name:

... 
EXEC SQL EXECUTE 
DECLARE 
... 
new_name  CHAR(10); 
BEGIN 
    ... 
    :emp_name:ind_name := new_name; 
    ... 
END; 
END-EXEC; 

Suppose you must pass an input host array to a PL/SQL block for processing. By default, when binding such a host array, the Pro*C/C++ Precompiler uses its declared dimension. However, you might not want to process the entire array. In that case, you can use the ARRAYLEN statement to specify a smaller array dimension. ARRAYLEN associates the host array with a host variable, which stores the smaller dimension. The statement syntax is

EXEC SQL ARRAYLEN host_array (dimension) [EXECUTE]; 

where dimension is a 4-byte integer host variable, not a literal or expression.

EXECUTE is an optional keyword.

The ARRAYLEN statement must appear along with, but somewhere after, the declarations of host_array and dimension. You cannot specify an offset into the host array. However, you might be able to use C features for that purpose. The following example uses ARRAYLEN to override the default dimension of a C host array named bonus:

float bonus[100]; 
int dimension; 
EXEC SQL ARRAYLEN bonus (dimension); 
/* populate the host array */ 
... 
dimension = 25;  /* set smaller array dimension */ 
EXEC SQL EXECUTE 
DECLARE 
    TYPE NumTabTyp IS TABLE OF REAL 
    INDEX BY BINARY_INTEGER; 
    median_bonus  REAL; 
    FUNCTION median (num_tab NumTabTyp, n INTEGER) 
        RETURN REAL IS 
  BEGIN 
    -- compute median 
  END; 
  BEGIN 
    median_bonus := median(:bonus, :dimension); 
    ... 
  END; 
END-EXEC; 

Only 25 array elements are passed to the PL/SQL block because ARRAYLEN reduces the array from 100 to 25 elements. As a result, when the PL/SQL block is sent to Oracle for execution, a much smaller host array is sent along. This saves time and, in a networked environment, reduces network traffic.

Host arrays used in a dynamic SQL method 2 EXEC SQL EXECUTE statement may have two different interpretations based on the presence or absence of the optional keyword EXECUTE.

By default (if the EXECUTE keyword is absent on an ARRAYLEN statement):

• The host array is considered when determining the number of times a PL/SQL block will be executed. (The minimum array dimension is used.)

• The host array must not be bound to a PL/SQL index table.

If the keyword EXECUTE is present:

• The host array must be bound to an index table.

• The PL/SQL block will be executed one time.

• All host variables specified in the EXEC SQL EXECUTE statement must either

  • Be specified in an ARRAYLEN ... EXECUTE statement

  • Be scalar.

For example, given the following PL/SQL procedure:

   CREATE OR REPLACE PACKAGE pkg AS 
          TYPE tab IS TABLE OF NUMBER(5) INDEX BY BINARY_INTEGER; 
          PROCEDURE proc1 (parm1 tab, parm2 NUMBER, parm3 tab); 
   END; 
 

The following Pro*C/C++ function demonstrates how host arrays can be used to determine how many times a given PL/SQL block is executed. In this case, the PL/SQL block will be executed 3 times resulting in 3 new rows in the emp table.

func1() 
{ 
  int empno_arr[5] = {1111, 2222, 3333, 4444, 5555}; 
  char *ename_arr[3] = {"MICKEY", "MINNIE", "GOOFY"}; 
  char *stmt1 = "BEGIN INSERT INTO emp(empno, ename) VALUES :b1, :b2; END;"; 
  
  EXEC SQL PREPARE s1 FROM :stmt1; 
  EXEC SQL EXECUTE s1 USING :empno_arr, :ename_arr; 
}  
 

The following Pro*C/C++ function demonstrates how to bind a host array to a PL/SQL index table through dynamic method 2. Note the presence of the ARRAYLEN...EXECUTE statement for all host arrays specified in the EXEC SQL EXECUTE statement.

func2() 
{ 
  int ii = 2; 
  int int_tab[3] = {1,2,3}; 
  int dim = 3; 
  EXEC SQL ARRAYLEN int_tab (dim) EXECUTE;  
 
  char *stmt2 = "begin pkg.proc1(:v1, :v2, :v3); end; "; 
 
  EXEC SQL PREPARE s2 FROM :stmt2; 
  EXEC SQL EXECUTE s2 USING :int_tab, :ii, :int_tab;  
} 
 

However the following Pro*C/C++ function will result in a precompile-time warning because there is no ARRAYLEN...EXECUTE statement for int_arr.

func3() 
{ 
  int int_arr[3]; 
  int int_tab[3] = {1,2,3}; 
  int dim = 3; 
  EXEC SQL ARRAYLEN int_tab (dim) EXECUTE;  
 
  char *stmt3 = "begin pkg.proc1(:v1, :v2, :v3); end; "; 
 
  EXEC SQL PREPARE s3 FROM :stmt3; 
  EXEC SQL EXECUTE s3 USING :int_tab, :int_arr, :int_tab;  
} 

You can embed the SQL statements CREATE FUNCTION, CREATE PROCEDURE, and CREATE PACKAGE in a host program, as the following example shows:

EXEC SQL CREATE 
FUNCTION sal_ok (salary REAL, title CHAR) 
RETURN BOOLEAN AS 
min_sal  REAL; 
max_sal  REAL; 
  BEGIN 
    SELECT losal, hisal INTO min_sal, max_sal 
        FROM sals 
        WHERE job = title; 
    RETURN (salary >= min_sal) AND 
           (salary <= max_sal); 
  END sal_ok; 
END-EXEC; 

Notice that the embedded CREATE {FUNCTION | PROCEDURE | PACKAGE} statement is a hybrid. Like all other embedded CREATE statements, it begins with the keywords EXEC SQL (not EXEC SQL EXECUTE). But, unlike other embedded CREATE statements, it ends with the PL/SQL terminator END-EXEC.

In the example later, you create a package that contains a procedure named get_employees, which fetches a batch of rows from the EMP table. The batch size is determined by the caller of the procedure, which might be another stored subprogram or a client application.

The procedure declares three PL/SQL tables as OUT formal parameters, then fetches a batch of employee data into the PL/SQL tables. The matching actual parameters are host arrays. When the procedure finishes, it automatically assigns all row values in the PL/SQL tables to corresponding elements in the host arrays.

EXEC SQL CREATE OR REPLACE PACKAGE emp_actions AS 
    TYPE CharArrayTyp IS TABLE OF VARCHAR2(10) 
        INDEX BY BINARY_INTEGER; 
    TYPE NumArrayTyp IS TABLE OF FLOAT 
        INDEX BY BINARY_INTEGER; 
  PROCEDURE get_employees( 
    dept_number IN     INTEGER, 
    batch_size  IN     INTEGER, 
    found       IN OUT INTEGER, 
    done_fetch  OUT    INTEGER, 
    emp_name    OUT    CharArrayTyp, 
    job_title   OUT    CharArrayTyp, 
    salary      OUT    NumArrayTyp); 
  END emp_actions; 
END-EXEC;
EXEC SQL CREATE OR REPLACE PACKAGE BODY emp_actions AS 
 
    CURSOR get_emp (dept_number IN INTEGER) IS 
        SELECT ename, job, sal FROM emp 
            WHERE deptno = dept_number; 
 
  PROCEDURE get_employees( 
    dept_number IN     INTEGER, 
    batch_size  IN     INTEGER, 
    found       IN OUT INTEGER, 
    done_fetch  OUT    INTEGER, 
    emp_name    OUT    CharArrayTyp, 
    job_title   OUT    CharArrayTyp, 
    salary      OUT    NumArrayTyp) IS 
 
  BEGIN 
    IF NOT get_emp%ISOPEN THEN 
        OPEN get_emp(dept_number); 
    END IF; 
    done_fetch := 0; 
    found := 0; 
    FOR i IN 1..batch_size LOOP 
        FETCH get_emp INTO emp_name(i), 
        job_title(i), salary(i); 
        IF get_emp%NOTFOUND THEN 
            CLOSE get_emp; 
            done_fetch := 1; 
            EXIT; 
        ELSE 
            found := found + 1; 
        END IF; 
    END LOOP; 
  END get_employees; 
END emp_actions; 
END-EXEC; 

You specify the REPLACE clause in the CREATE statement to redefine an existing package without having to drop the package, re-create it, and re-grant privileges on it. For the full syntax of the CREATE statement see SQL Statements: COMMIT to CREATE JAVA.

If an embedded CREATE {FUNCTION | PROCEDURE | PACKAGE} statement fails, Oracle generates a warning, not an error.

Datatypes and Host Variables described how to embed OCI calls in your host program. After calling the library routine SQLLDA to set up the LDA, use the OCI call odessp to get useful information about a stored subprogram. When you call odessp, you must pass it a valid LDA and the name of the subprogram. For packaged subprograms, you must also pass the name of the package. odessp returns information about each subprogram parameter such as its datatype, size, position, and so on.

You can also use the DESCRIBE_PROCEDURE stored procedure, in the DBMS_DESCRIBE package.

Follow these rules for external procedures:

• External procedures can only be in C. C++ external procedures are not supported.

• When you are connected to the external procedure context, any additional connection is not permitted and results in a runtime error.

• Multithreaded external procedures are not supported. Executing an EXEC SQL ENABLE THREADS statement is not permitted and will return a runtime error. Pro*C/C++ does support multithreading in an application not using the external procedure method we are describing.

• You cannot use DDL statements. They result in runtime errors.

• You cannot use transaction control statements, such as EXEC SQL COMMIT, and EXEC SQL ROLLBACK.

• You cannot use object navigation statements such as EXEC SQL OBJECT ... .

• You cannot use polling EXEC SQL LOB statements.

• You cannot use EXEC TOOLS statements. They will result in runtime errors.

Here is a simple example to create the external procedure extp1.

To store an external C procedure, compile and link the code to a library such as a DLL.

Reference to NT removed user comment 9561

Then use the following SQL command once to register the external procedure extp1:

CREATE OR REPLACE PROCEDURE extp1
AS EXTERNAL NAME "extp1"
LIBRARY mylib
WITH CONTEXT
PARAMETERS(CONTEXT) ;

Where mylib is the name of the library storing procedure extp1. WITH CONTEXT means to implicitly call this procedure with argument of type OCIExtProcContext*. The context is omitted in your call, but is passed to the procedure anyway. The keyword CONTEXT appears in the CREATE statement, however, as a place marker.

This context parameter is the one referenced in the EXEC SQL REGISTER CONNECT statement inside extp1.

The external procedure is called from SQL*Plus this way:

SQL>
BEGIN
  INSERT INTO emp VALUES(9999,'JOHNSON','SALESMAN',7782, sysdate, 1200,150,10);
  extp1;
END;

Here is the listing of extp1.pc:

void extp1 (epctx)
OCIExtProcContext *epctx;
{
char name[15];
        EXEC SQL REGISTER CONNECT USING :epctx;
        EXEC SQL WHENEVER SQLERROR goto err;
        EXEC SQL SELECT ename INTO :name FROM emp WHERE empno = 9999;
        return;
err: SQLExtProcError(SQL_SINGLE_RCTX,sqlca.sqlerrm.sqlerrmc,sqlca.sqlerrm.sqlerrml);
        return;
}

The SQLLIB function SQLExtProcError() provides the ability to return control to PL/SQL when an error occurs in an external C procedure. The function and its arguments are:

SQLExtProcError (ctx, msg, msglen)

where:

ctx (IN) sql_context *

This is the target SQLLIB runtime context of the REGISTER CONNECT statement, which has to be executed before this function is invoked. Only the global runtime context is supported now.

msg (OUT) char *

The text of the error message.

msglen (OUT) size_t

The length in bytes of the message.

SQLLIB calls the OCI service function OCIExtProcRaiseExcpWithMsg when this function is executed.

The message is from the structure sqlerrm in the SQLCA.

Here is an example showing use of SQLExtProcError():

void extp1 (epctx)
OCIExtProcContext *epctx;
{
   char name[15];
   EXEC SQL REGISTER CONNECT USING :epctx;
   EXEC SQL WHENEVER SQLERROR goto err;
   EXEC SQL SELECT ename INTO :name FROM emp WHERE smpno = 9999;
   return;
 err:
   SQLExtProcError (SQL_SINGLE_RCTX, sqlca.sqlerrm.sqlerrmc,
      sqlca.sqlerrm.sqlerrml);
   printf("\n%*s\n", sqlca.sqlerrm.sqlerrml, sqlca.sqlerrm.sqlerrmc);
   return;
}