iotk-explain-oracle-error.php is a facility that helps to provide substantive documentation for common Oracle errors that you might encounter while using IOTK. It was added to the framework because of the often abstract or unrelated messages given by Oracle’s error reporting facility oerr.
For example, if you receive an ORA-04068 error you can execute the following Oracle command:
oerr ora 4068
oerr will produce the following documentation:
04068, 00000, "existing state of packages%s%s%s has been discarded" // *Cause: One of errors 4060 - 4067 when attempt to execute a stored // procedure. // *Action: Try again after proper re-initialization of any application's // state.
For someone new to IOTK, Oracle, or this error it might take some time to figure out exactly what to do. But after using IOTK for awhile, the solution is quite simple: restart Apache.
Instead of executing oerr to get a description of the issue, you can execute IOTK’s ioerr using the same command line parameters passed to oerr:
ioerr ora 4068
Will produce the following documentation:
ORA-4068
--------
Oracle's (oerr ora 4068) official description:
existing state of packages%s%s%s has been discarded
PROBLEM DESCRIPTION
-------------------
This issue occurs when interacting with stored procedures through a Web
browser. You will receive this error after hitting submit on a form. Prior
to receiving this error you either rebuilt your application or a part of it
that included reloading PL/SQL.
This error is occurring because Oracle has determined that the cached version
of your stored procedure code no longer matches changes to the database. In
essence the application is out of sync with the database.
Here is what Oracle will report:
exception 'ut_Oracle_Error' with message '
==================================================
Array
(
=> 4068
[message] => ORA-04068: existing state of packages has been discarded
ORA-04061: existing state of package "IOTK.CO_PKG" has been invalidated
ORA-04065: not executed, altered or dropped package "IOTK.CO_PKG"
ORA-06508: PL/SQL: could not find program unit being called: "IOTK.CO_PKG"
ORA-06512: at line 3
[offset] => 0
[sqltext] => [Full text of query that was being executed]
[p_id] => inout
[p_local_time] => 1241799814
[p_name] => IOTK
)
==================================================
RESOLUTION
----------
Restart your Web server and than go back to your browser and hit the reload
button.
Restarting your Web server will cause Oracle to re-cache the stored procedure
code. Reloading the page in your browser will cause your browser to re-post
the form.
NOTES
-----
It is common to get this error after rebuilding your application or performing
a push to production. To ensure this issue does not occur, always restart your
Web server after either of these occurrences.
In total, documentation is provided for 18 errors ranging from issues with straightforward solutions (like this one) to more complex issues with solutions requiring code changes or upgrades of Oracle.
I will document all of the errors that I’ve tracked and documented while building and using IOTK. I suspect a few of my solutions will be helpful to people. Here are the specific errors that I have documented:
ORA-01000
An issue caused by a memory leak in specific versions of older PHP OCI 8 drivers. Proud to say I helped provide reproducible test cases for this one for Oracle.
ORA-01001
ORA-01031
ORA-01036
ORA-12154
ORA-12528
ORA-12541
ORA-01745
ORA-01861
ORA-02429
ORA-28002
ORA-03114
If accompanied by an ORA-07445 and core dump you might need to upgrade Oracle to 11g. This was a nasty one.
ORA-00054
ORA-06550
ORA-06553
ORA-00904
OCI-22303
An issue that used to arise when calling oci_new_collection() to bind user defined types to stored procedures. This is essentially another memory leak in the PHP OCI 8 driver, one for which I also provided reproducible test cases to Oracle.
