Passing Parameters to PL/SQL Subprograms

NULL;

END;

/

Passing Parameters to PL/SQL Subprograms

This section explains how to pass information in and out of PL/SQL subprograms using parameters:

■Actual Versus Formal Subprogram Parameters on page 8-6

■Using Positional, Named, or Mixed Notation for Subprogram Parameters on page 8-7

■Specifying Subprogram Parameter Modes on page 8-7

■Using Default Values for Subprogram Parameters on page 8-9

Actual Versus Formal Subprogram Parameters

Subprograms pass information using parameters:

■The variables declared in a subprogram spec and referenced in the subprogram body are formal parameters.

■The variables or expressions passed from the calling subprogram are actual parameters.

A good programming practice is to use different names for actual and formal parameters.

When you call a procedure, the actual parameters are evaluated and the results are assigned to the corresponding formal parameters. If necessary, before assigning the value of an actual parameter to a formal parameter, PL/SQL converts the datatype of the value. For example, if you pass a number when the procedure expects a string, PL/SQL converts the parameter so that the procedure receives a string.

The actual parameter and its corresponding formal parameter must have compatible datatypes. For instance, PL/SQL cannot convert between the DATE and REAL datatypes, or convert a string to a number if the string contains extra characters such as dollar signs.

Example 8–4 Formal Parameters and Actual Parameters

The following procedure declares two formal parameters named emp_id and amount:

PROCEDURE raise_salary (emp_id INTEGER, amount REAL) IS BEGIN

UPDATE emp SET sal = sal + amount WHERE empno = emp_id; END raise_salary;

/

This procedure call specifies the actual parameters emp_num and amount:

raise_salary(emp_num, amount);

Expressions can be used as actual parameters:

raise_salary(emp_num, merit + cola);

8-6 PL/SQL User's Guide and Reference

Passing Parameters to PL/SQL Subprograms

Using Positional, Named, or Mixed Notation for Subprogram Parameters

When calling a subprogram, you can write the actual parameters using either:

■Positional notation. You specify the same parameters in the same order as they are declared in the procedure.

This notation is compact, but if you specify the parameters (especially literals) in the wrong order, the bug can be hard to detect. You must change your code if the procedure's parameter list changes.

■Named notation. You specify the name of each parameter along with its value. An arrow (=>) serves as the association operator. The order of the parameters is not significant.

This notation is more verbose, but makes your code easier to read and maintain. You can sometimes avoid changing your code if the procedure's parameter list changes, for example if the parameters are reordered or a new optional parameter is added. Named notation is a good practice to use for any code that calls someone else's API, or defines an API for someone else to use.

■Mixed notation. You specify the first parameters with positional notation, then switch to named notation for the last parameters.

You can use this notation to call procedures that have some required parameters, followed by some optional parameters.

Example 8–5 Subprogram Calls Using Positional, Named, and Mixed Notation

DECLARE

acct INTEGER := 12345; amt REAL := 500.00;

PROCEDURE credit_acct (acct_no INTEGER, amount REAL) IS

Specifying Subprogram Parameter Modes

You use parameter modes to define the behavior of formal parameters. The three parameter modes are IN (the default), OUT, and IN OUT.

Any parameter mode can be used with any subprogram. Avoid using the OUT and IN OUT modes with functions. To have a function return multiple values is a poor programming practice. Also, functions should be free from side effects, which change the values of variables not local to the subprogram.

Using the IN Mode

An IN parameter lets you pass values to the subprogram being called. Inside the subprogram, an IN parameter acts like a constant. It cannot be assigned a value.

You can pass a constant, literal, initialized variable, or expression as an IN parameter.

Using PL/SQL Subprograms 8-7

Passing Parameters to PL/SQL Subprograms

IN parameters can be initialized to default values, which are used if those parameters are omitted from the subprogram call. For more information, see "Using Default Values for Subprogram Parameters" on page 8-9.

Using the OUT Mode

An OUT parameter returns a value to the caller of a subprogram. Inside the subprogram, an OUT parameter acts like a variable. You can change its value, and reference the value after assigning it:

PROCEDURE split_name

(

phrase IN VARCHAR2, first OUT VARCHAR2, last OUT VARCHAR2

)

IS

first := SUBSTR(phrase, 1, INSTR(phrase, ' ')-1); last := SUBSTR(phrase, INSTR(phrase, ' ')+1);

IF first = 'John' THEN

DBMS_OUTPUT.PUT_LINE('That is a common first name.'); END IF;

END;

/

You must pass a variable, not a constant or an expression, to an OUT parameter. Its previous value is lost unless you specify the NOCOPY keyword (see "Using Default Values for Subprogram Parameters" on page 8-9) or the subprogram exits with an unhandled exception.

Like variables, OUT formal parameters are initialized to NULL. The datatype of an OUT formal parameter cannot be a subtype defined as NOT NULL, such as the built-in subtypes NATURALN and POSITIVEN. Otherwise, when you call the subprogram, PL/SQL raises VALUE_ERROR.

Before exiting a subprogram, assign values to all OUT formal parameters. Otherwise, the corresponding actual parameters will be null. If you exit successfully, PL/SQL assigns values to the actual parameters. If you exit with an unhandled exception, PL/SQL does not assign values to the actual parameters.

Using the IN OUT Mode

An IN OUT parameter passes initial values to a subprogram and returns updated values to the caller. It can be assigned a value and its value can be read. Typically, an IN OUT parameter is a string buffer or numeric accumulator, that is read inside the subprogram and then updated.

The actual parameter that corresponds to an IN OUT formal parameter must be a variable; it cannot be a constant or an expression.

If you exit a subprogram successfully, PL/SQL assigns values to the actual parameters. If you exit with an unhandled exception, PL/SQL does not assign values to the actual parameters.

Summary of Subprogram Parameter Modes

Table 8–1 summarizes all you need to know about the parameter modes.

8-8 PL/SQL User's Guide and Reference