Call (800) 766-1884 for Oracle support & training
Free Oracle Tips

Oracle Consulting Support
Oracle Upgrades
Use New Oracle Features
Oracle Replication Support
Oracle Training
Remote Oracle DBA
System Documentation
Oracle Tips
Oracle Performance

Free Oracle Tips



BC Oracle tuning

Oracle training

Oracle support

Remote Oracle




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 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,
-- *****************************************************************

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.


Oracle performance tuning software 

Oracle performance tuning book


Oracle performance Tuning 10g reference poster
Oracle training in Linux commands
Oracle training Excel
Oracle training & performance tuning books



Copyright © 1996 -  2014 by Burleson. All rights reserved.

Oracle® is the registered trademark of Oracle Corporation. 

Hit Counter