11.4.2 Collections as Program Parameters

Collections can also serve as module parameters. In this case, you cannot return a user-defined type that is declared in the module itself. You will instead use types that you have built outside the scope of the module, either via CREATE TYPE or via public declaration in a package. The following function provides a pseudo "UNION ALL" operation on two input parameters of type Color_tab_t. That is, it creates an OUT parameter that is the superset of the colors of the two input parameters. The full implementation of this function may be found in the make_colors_superset.sp file on the O'Reilly site.

CREATE PROCEDURE make_colors_superset (first_colors IN Color_tab_t,

second_colors IN Color_tab_t, superset OUT Color_tab_t)

And here is an example of how you would call such a program:

DECLARE

my_colors Color_tab_t;

your_colors Color_tab_t;

our_colors Color_tab_t;

BEGIN

make_colors_superset (

my_colors,

your_colors,

our_colors

);

END;

Check out the later section Section 11.6.6 for details.

11.4.3 Collections as Datatypes of a Function's Return Value

In the next example, we have defined Color_tab_t as the type of a function return value, and also used it as the datatype of a local variable. The same restriction about scope applies to this usage—types must be declared outside the module's scope.

CREATE FUNCTION true_colors (whose_id IN NUMBER) RETURN Color_tab_t

AS

l_colors Color_tab_t;

BEGIN

SELECT favorite_colors INTO l_colors

FROM personality_inventory

WHERE person_id = whose_id;

RETURN l_colors;

EXCEPTION

WHEN NO_DATA_FOUND

THEN

RETURN NULL;

END;

This example also illustrates a long-awaited feature: the retrieval of a complex data item in a single fetch. This is so cool that it bears repeating, so we'll talk more about it later in this chapter.

How would you use this function in a PL/SQL program? Because it acts in the place of a variable of type Color_tab_t, you can do one of two things with the returned data:

1. Assign the entire result to a collection variable

2. Assign a single element of the result to a variable (as long as the variable is of a type compatible with the collection's elements)

Option one is easy. Notice, by the way, that this is another circumstance where you don't have to initialize the collection variable explicitly:

DECLARE

color_array Color_tab_t;

BEGIN

color_array := true_colors (8041);

END;

With option two, we actually give the function call a subscript. The general form is:

variable_of_element_type := function ( ) (subscript);

Or, in the case of the true_colors function:

DECLARE

one_of_my_favorite_colors VARCHAR2(30);

BEGIN

one_of_my_favorite_colors := true_colors (whose_id=>8041) (1);

END;

Note that this code has a small problem: if there is no record in the database table where person_id is 8041, the attempt to read its first element will raise a COLLECTION_IS_NULL exception. We should trap and deal with this exception in a way that makes sense to the application.

In the previous example, I've used named parameter notation (whose_id=>) for readability, although it is not strictly required. (See Chapter 16 for more details.)