 |
|
Documenting Scripts
Oracle Tips by
Burleson
|
Scripts play a large role in most systems. If a script performs a
task within your system, the script should be documented. A script to
restore your database isn’t any good if no one has any idea how to run
it. The best place to document scripts is within the script’s header
(or prologue), as illustrated in Listing 3.7.
Listing 3.7 A documented header for a script.
-- *****************************************************************
-- This script performs an analysis report of trends in student
-- grades, broken down by professor. The report should help indicate
-- if specific professors are showing unusual trends in grades.
--
-- The script accepts the following parameters:
--
-- 1) The first parameter specifies a department for which the
-- script should be run.
-- 2) The second parameter specifies what level of students should
-- be examined. The values for this parameter are:
--
-- 1 -- calculate grades for all undergraduates
-- 2 -- calculate grades for all Masters candidates
-- 3 -- calculate grades for all doctoral candidates
--
-- The script is run from the Unix prompt by issuing the following
-- command:
--
-- sqlplus @grade_trends.report PSYCHOLOGY 2
--
--
-- The script uses these variables:
--
-- 1) &&MeanGrade -- indicates the mean grade for all students
-- in the program.
--
-- There are no expected errors that occur when running this script.
--
-- The script requires SELECT privileges on the STUDENTS,
-- DEPARTMENTS, and ENROLLED_COURSES tables.
-- *****************************************************************
The header shown in Listing 3.7 documents several important aspects
of the script:
- Purpose—A statement about the general
functionality of the script.
- Parameters—The parameters expected when
the script is called are documented. An explanation is given for the
use of each parameter within the script. An example of calling the
script from the command line is given.
- Variables—Any variables used within the
script are documented, and the use of the variables is discussed.
While this isn’t critical to the person who runs the script, it will
be critical to the person who has to update the script down the
road.
- Errors—Any errors that can occur while
running the script are documented. If possible, reasons are given
for these errors, and workarounds are documented.
- Account privileges—The privileges
required to run the script are specified.
- Leftovers—Any special information about
the script is documented.
Scripts for your system should be in version control with the rest
of the code; no one wants to have to re-create the backup script for
your database or the report that took a week to write and debug. It’s
especially critical that test scripts (and their results) be stored in
version control, because, at some point, the tests will need to be
executed again.
This is an excerpt from the book "High Performance Oracle
Database Automation" by Jonathan Ingram and Donald K.
Burleson, Series Editor. |
