[Zope-Checkins] CVS: Products/DCOracle2/DCOracle2 - DCOracle2.py:1.84

[Matthew T. Kromer]

Update of /cvs-repository/Products/DCOracle2/DCOracle2
In directory cvs.zope.org:/tmp/cvs-serv12870/DCOracle2

Modified Files:
	DCOracle2.py 
Log Message:
Add a wee bit of narration about how stored procedures work in the comments


=== Products/DCOracle2/DCOracle2/DCOracle2.py 1.83 => 1.84 ===
 # $Id$
 
+#
+# Stored Procedure Narrative Documenation
+#
+# Stored procedures are some of most difficult thing to get working right.
+# Normal statements will undergo type conversion by Oracle for input parameters
+# and offer a description of the resultant output columns after the execute
+# takes place for conversion back to Python.
+#
+# Stored procedures, on the other hand, modify variables defined by the
+# calling environment.  Thus, those variables must be set up in advance,
+# and must align with what the procedure is defined for.  It is possible
+# to still have Oracle do type conversion on the variables (dco2 does
+# use strings for numbers at the time of this note) but a lot more must
+# be set up in advance for the process to work (e.g. binding arrays of
+# a structure, returning cursors, etc.)
+#
+# The original DCOracle left behind a notion of the "procedure" object
+# on a cursor.  This procedure object had as children all procedures
+# available to the cursor it was invoked on.  Thus, you can use
+# a notion of cursor.procedures.SCHEMA.PACKAGE.PROCEDURE(params) to invoke
+# a particular stored procedure.
+#
+# DCOracle2 continues this, although it leads to some convoluted looking
+# code (particularly the getattr on a procedure).
+#
+# The database connection can do a schema describe of any object in Oracle.
+# This describe() function returns back a dictionary (of lists and more)
+# which represent the results of the OCIDescribeAny call.  The mapproc
+# method on the connection uses describe and the method collapsedesc to
+# "collapse" the description down into a more terse form.
+#
+# The utility functions decodedesc and decodecdesc will decode the
+# uncollapsed and collapsed descriptions, for diagnostic purposes.
+#
+# When mapproc() on a database object is called, it will save the description
+# of the mapped object into the _procdesc attribute on the connection. This
+# avoids calling OCIDescribeAny again for any schema object.
+#
+# When a cursor object is asked for its procedure or procedures attribute,
+# the cursor __getattr__ code will create a new top-level procedure object,
+# if it does not exist, and then save this object into the cursor's dictionary
+# so that the __getattr__ code is not called again.
+#
+# The procedure object's __getattr__ does most of the heavy permutation,
+# creating new procedure objects representing each segment of the schema
+# name being traversed, and associating the invoking cursor with that object.
+# Each time the procedure's __getattr__ makes a new attribute (for dynamic
+# discovery) it is added to the procedure's dict so the getattr hook does
+# not get invoked again.  
+#
+# The description of the object being traversed is saved in the procedure
+# object so it does not have to be fetched again.  The decoded description
+# is saved in the procedure's __doc__ string as human-readable text.
+#
+# The cursor's callproc method (the API 2.0 compliant way of invoking a
+# stored procedure) calls the cursor findproc() method, which firsts checks
+# to see if a known procedure is found by looking in the cursor's _mapproc
+# attribute.  If not, it breaks the name up by splitting on periods, and
+# tries to getattr() each successive element from the procedure object,
+# starting with the base procedure object.  Once it finds a procedure object
+# it saves it in its _mapproc attribute so it does not have to do the
+# traversal again.
+#
+
+
 import dco2
 import sys
 import types