User-Defined Functions «Prev 

Functions returning a number, text, or date Value

Function Declaration

A function is a subprogram that can take parameters and return a single value. A function has two parts:
  1. the specification and
  2. the body.
The specification (spec for short) begins with the keyword FUNCTION and ends with the RETURN clause, which specifies the datatype of the return value. Parameter declarations are optional and functions that take no parameters are written without parentheses. The function body begins with the keyword IS (or AS) and ends with the keyword END followed by an optional function name.

PL/SQL Function Body

The function body has three parts:
  1. an optional declarative part,
  2. an executable part, and
  3. an optional exception-handling part.

The declarative part contains declarations of
  1. types,
  2. cursors,
  3. constants,
  4. variables,
  5. exceptions, and
  6. subprograms.
These items are local and cease to exist when you exit the function. The executable part contains statements that assign values, control execution, and manipulate data. The exception-handling part contains handlers that deal with exceptions raised during execution.
Note that the function declaration in a PL/SQL block or package is not the same as creating a function in SQL.


CREATE OR REPLACE FUNCTION FORMAT_ZIP
Use CREATE or (optionally) CREATE REPLACE to begin the definition of the function. In this example, the function name is FORMAT_ZIP.

CREATE OR REPLACE FUNCTION FORMAT_ZIP
(ZIPCODE IN VARCHAR2)
A function can only use incoming parameters. In this example, the parameter is name ZIPCODE and is of the VARCHAR2 datatype. Notice that the parameter has no length.

CREATE OR REPLACE FUNCTION FORMAT_ZIP
(ZIPCODE IN VARCHAR2)
RETURN VARCHAR2 AS
The RETURN clause is required. The clause defines the datatype of the field returned by the function. In this example, the function returns a field that is a VARCHAR2 datatype. Notice that there is no name or length identifying the returning value. The AS keyword marks the beginning of the body of the function's definition.

The BEGIN clause marks the beginning of the function's declaration section, if there is one.

The DECLARE section is optional. In this example, a single variable named FORMATTED_ZIP is declared.

The second BEGIN keyword marks the end of the DECLARE section and the beginning of the body of the function. If there had been no DECLARE section, this line would have been left out.

Here is the first portion of the logic. In this example, the length of the incoming parameter (ZIPCODE) is tested. If the length is five, the declared variable (FORMATTED_ZIP) assigned a value equal to ZIPCODE concatenated with a dash and four zeros.

Continuing with the logic, this next section tests ZIPCODE for a length of nine. If true, the FORMATTED_ZIP variable is assigned to a value which takes the first five characters of ZIPCODE, adds a dash, and then tacks on the last four characters of ZIPCODE.

The final portion of this IF statement simply assigns FORMATTED_ZIP the value of ZIPCODE without any changes in its format.

There must be at least one RETURN clause like this one inside the body of the function. In this example, the value stored in the FORMATTED_ZIP variable is returned.

The first END closes the body section. It is needed in this case because there is a DECLARE section and a second BEGIN. The second END completes the entire function syntax.

Type a slash on a separate line and press ENTER to execute the CREATE FUNCTION command. The line "Function created" is the response from SQL*Plus after executing the CREATE command listed here. It tells you that the function was successfully created.

To call the function within a query the function name follows the SELECT clause (in this case), and the one parameter is placed between parentheses. For simplicity, the example uses a literal value as the parameter. The parameter can also be a column or expression.

The results of the query show how the function has formatted the incoming parameter, '96753' into a ten-character string: '96753-0000'. This function can be reused because its definition is now stored in the database.