 |
|
Documenting Functions
Oracle Tips by
Burleson
|
The essential elements of documentation are the same for both
functions and procedures. Your documentation must cover the following
four basic aspects of the function:
- Purpose
- Parameters
- Return value
- Error conditions
Headers, pseudocode, comments, and identifier names all contribute
to creating a well-documented piece of code.
The Header
Listing 5.20 contains a header for the Parse_String()
function that we’ve been discussing.
Listing 5.20 The Parse_String() function with a
header.
FUNCTION Parse_String (vStringToParse IN varchar2)
RETURN Global_Types.VARCHAR2_TABTYPE
-- *****************************************************************
-- Description: The Parse_String function accepts a single parameter
-- of type varchar2. This parameter is expected to be a series of
-- varchar2 strings delimited by a caret (^) symbol. If any section
-- of the parameter is longer than 10 characters, a VALUE_ERROR
-- exception will be raised when the section is stored in the
-- PL/SQL table.
--
-- The function returns a PL/SQL table, with each element of the
-- table containing a single section of the string.
--
-- REVISON HISTORY
-- Date Author Reason For Change
-- ----------------------------------------------------------------
-- 19 FEB 1997 J. Schmoe Function created.
-- *****************************************************************
IS
iStringPos integer;
biIndex binary_integer := 0;
DELIMITER CONSTANT char (1) := '^';
vString varchar2 (2000);
Return_tab VARCHAR2_TABTYPE;
BEGIN
vString := vStringToParse;
LOOP
--
-- Get the position of the next delimiter.
--
iStringPos := instr (vString, DELIMITER);
--
-- If there are no more elements in the string, return
-- the table.
--
IF (iStringPos = 0) THEN
RETURN Return_tab;
END IF;
Return_tab (biIndex) := substr (vString, 1, (iStringPos - 1));
biIndex := biIndex + 1;
--
-- Chop off the first portion of the string so that the
-- next iteration of the loop will get the next section.
--
vString := substr (vString, (iStringPos + 1));
END LOOP;
EXCEPTION
WHEN VALUE_ERROR THEN
Log_System_Error (vErrorLocation => 'Parse_String',
vErrorText => SQLERRM);
END;
This is an excerpt from the book "High Performance Oracle
Database Automation" by Jonathan Ingram and Donald K.
Burleson, Series Editor. |
